                         Zaurus framebuffer VNC server
                         -----------------------------
                                      v0.2
                                    --------

                   SDG Systems, LLC <support@sdgsystems.com>
                                  16 NOV 2002

                            Formerly maintained by:
                   Pierre-Philippe Coupard <pierre@lineo.com>
                                    20/02/02
                       (This address is no longer valid.)



  The Zaurus framebuffer VNC server is a specialized VNC server for the Sharp
Zaurus and for the Compaq iPAQ PDAs. It can be used to take control of a PDA
remotely, and specifically features:

- Remote display of the Zaurus or iPAQ display, independently of the
  environment in use (Qtopia, X11, console ...)

- Emulation of the status of the "battery" and "email" LEDs on the remote
  display, including blinking (Zaurus only)

- Low-level remote touchscreen control with working drag-and-drop

- Low-level remote keyboard control, specialized for the Zaurus, with working
  dual-function keys.

- Optional simulated Zaurus or iPAQ panel, viewable in full-size or
  split-screen modes (split-screen mode on Zaurus only), complete with a
  working soft-keyboard.

- Integrated HTTP server with Java VNC client.

- Usable with any standard VNC client



  1 - Installing and configuring the fbvncserver package on the Zaurus

  Before installing the fbvncserver package, make sure you install the zlib
package first, as most recent ROMs don't have it by default. fbvncserver also
requires the jpeg library, but if you use a recent ROM, you won't have to
install it since it's already present.

  Install the fbvncserver package using the Qtopia package installer, or
from the command line with the ipkg utility. Then soft-reboot the PDA, either
by choosing "Settings" -> "Shutdown" in the Qtopia menu and selecting "reboot",
or by typing "reboot" from the command line.

  Once the PDA has rebooted, you need to calibrate the touchscreen emulation
daemon. To do that, tap as precisely as you can the top-left corner, then the
bottom-right corner of the display. Don't worry if Qtopia reacts to your
tappings, it doesn't understand that you're doing a calibration because the
daemon runs silently underneath it.



  2 - Installing and configuring the fbvncserver package on the iPAQ

  Before installing the fbvncserver package, make sure you install the zlib and
the libjpeg packages first.

  Install the fbvncserver package using the Qtopia package installer, or
from the command line with the ipkg utility. Then soft-reboot the PDA, either
by choosing "Settings" -> "Shutdown" in the Qtopia menu and selecting "reboot",
or by typing "reboot" from the command line.

  Once the PDA has rebooted, to use the server under X or with a framebuffer
application, simply run the VNC server manually in the background from the
command line (see below for options), then start your X environment or your
application. The order your start things up doesn't matter, you can run the VNC
server after the environment or the framebuffer application has started as well.

  If your environment is Qtopia or Opie, you need to calibrate the touchscreen
emulation daemon. To do that, when the PDA has rebooted, tap as precisely as
you can the top-left corner, then the bottom-right corner of the display. Don't
worry if Qtopia reacts to your tappings, it doesn't understand that you're
doing a calibration because the daemon runs silently underneath it.



  3 - Using the VNC server

  The VNC server knows 3 display modes (2 display modes for the iPAQ) :

- Minimal : only the Zaurus or iPAQ display is exported. This is good if you
  don't want all the bells and whistles and you want to save space on your PC's
  desktop.

- Fancy (full-size panel) : a life-like Zaurus or iPAQ front panel is exported,
  with the display embedded inside it, and the LEDs' status reflected (Zaurus
  only). In this, mode, the fake keyboard is functional as well.

- Split panel (Zaurus only) : Like the fancy mode, but the top half of the
  panel (the display) is displayed on the left and the bottom half (the
  keyboard) is displayed on the right. This is good if your PC's vertical
  resolution doesn't allow the full-size panel to be displayed entirely, or if
  you want the VNC client's window be landscape instead of portrait.

  To start the server from Qtopia, choose the icon corresponding to the mode
you want. To start the server from the command line, invoke "fbvncserver" for
the minimal mode, "fbvncserver -fancy" for the fancy mode, or "fbvncserver
-fancy -split" for the split panel mode (Zaurus only).

  Once the server is running, you can connect to it using with a standalone VNC
client by pointing the client to the PDA's IP address, followed by the display
number ":0". If you have a Zaurus in the cradle and the USB link between the
PDA and the PC up, you would normally point the VNC client to "192.168.1.201:0"
for example (sometimes it's "192.168.129.201:0". If you use a network card or
a wireless network card, you'll have to determine the IP assigned to the
card.

  You can also connect to the VNC server with your web browser, using the
Java VNC client provided in the package. To use your browser, make sure the
Java support is enabled, then point it to "http://<your PDA's IP>:5800"
(for example, over USB, point it to "http://192.168.1.201:5800") : you browser
should then download the Java VNC client and start it. Once you see the main
screen appear, simply click on "OK" as there is no password. Note that the
Java VNC client only displays in 8 bits per pixel, therefore the colors will
be a little off and strange-looking. Only native VNC clients can display all
the colors correctly. Note that Netscape can do away with the leading "http://"
in the address, but not Internet Explorer.

  You can change the display mode while a client is connected : if you click
on one of the "start VNC" icons in Qtopia, the server will restart in the new
mode you've chosen. Because a VNC client can't be resized on the fly however,
it will be disconnected and you will have to reconnect it to the PDA manually.

  Note that it is possible to have several VNC clients connected to the same
PDA : all the clients will share the same display, keyboard and touchscreen.

  In fancy mode or split-panel mode, you can use the soft keyboard to type
things. However, be aware that, with the Zaurus, the dual-function keys, such
as the "ON/OFF" button and the "Light" button will behave differently if you
click on them and maintain the click for about a second, just like if you
pressed the buttons accordingly on the real Zaurus keyboard. Therefore, if you
"long-click" on the "Light" button, you can turn the backlighting on and off,
which is good, but if you "long-click" on the "ON/OFF" button, the Zaurus will
suspend itself and you will loose your VNC connection to it . If you resume
the Zaurus by pressing back on the real "ON/OFF" button, the VNC connection
should resume as well, but you can't resume the Zaurus remotely of course.



  4 - Technical note

  fbvncserver is a framebuffer VNC server, which means that it simply grabs
the raw content of the PDA's framebuffer periodically, looks for things that
have changed on the screen and sends the updated regions over to the VNC
client(s).

  The advantage of this method is that the VNC server is totally
environment-independant: you can use Qtopia, X, or the console equally, which
is very convenient to do development or testing. The disadvantage is that
some CPU is used all the time to actively look for changes in the framebuffer.
However, the most speed-critical sections of the server, the ones that deal
with the framebuffer, are coded in tight optimized assembler, so the server
will only minimally impact performances on the PDA.

  To inject synthetic touchscreen events, a multiplexer daemon is "wedged"
between the GUI and the kernel, which is partly the reason why the PDA has to
be restarted after installing the package. When the daemon is running, the GUI
actually talks to it instead of talking to the kernel, and the daemon takes
care of forwarding kernel touchscreen events as well as synthetic VNC events
to the GUI. If you stop the daemon, even when the VNC server is not running,
the GUI will be unable to receive any touchscreen event. If the VNC server
can't send synthetic events to the daemon (because it is stopped for example),
it will not terminate.

  To inject synthetic keyboard events, a small kernel driver is insmod-ed in
the kernel. The driver takes raw keyboard scancodes from its device file and
sends them down the kernel like if they came from the actually keyboard. The
kernel then processes those scancodes and the resulting keystrokes eventually
find their way up to the console, or the GUI. If you remove the module from the
kernel, the VNC server will not be able to send scancode events but will not
terminate either.

  Note that you can change the permissions on /dev/tssim and /dev/kbdsim, which
are the nodes used by the VNC server to send synthetic events, to 0, in which
case the VNC server will not be able to send any event back to the console or
the GUI, effectively turning it into a view-only server.

  The default VNC encoding is "tight" if you client supports it, or "hextile"
if it doesn't. You can try different encodings with the VNC client, but over
a LAN or USB connection, you won't see much of a difference (apart in "raw"
mode of course). With a fast connection, the advantage of sending less data
is pretty much equally lost due to the extra load of doing the compression.
However, with a slower connection, high compression encodings such as "tight"
win hands down of course.

  5 - Compiling the Source

You will need the libvncserver package available on sourceforge
(http://www.sf.net/) and the libjpeg package (I'm not sure where I got that.
Try a Google search.).  You will need to change the variable at the top of the
Makefile to point to the correct directories.  The Makefile compiles using -O6
because theoretically, it should be faster and there is very little difference
in size between this and -Os.


  6 - Known bugs/limitations

- Because the keyboard simulation happens at the lowest level in the kernel,
  it can't simulate quite all the keyboard inputs you'd normally find on a
  full-size keyboard.

As far as I'm aware, the server is bug-free.



  7 - License

  This software and its components are released under the terms of the General
Public License, version 2. See the "COPYING" file for details.



  8 - Legalese

  This software and its components are provided "as is". Although this software
has been subjected to extensive testing and has been found to work
satisfactorily on my PDAs, the developers and maintainers cannot be held
responsible for any damage it may cause to yours, whether it causes you to
hard-reset your PDA and lose that address you had to write to to win a new
Bentley, makes your PDA burn in flames, your PC explode, or your CompactFlash
slot to start eating your dog's food, etc ... If you have any doubt about this
software, or you don't want to take any risk with your PDA or your PC, DO NOT
INSTALL OR USE IT!



  9 - Shameless plug

  This software is sponsored by my employer, Lineo, Inc. (http://www.lineo.com/)
Lineo is kind enough to let me work on free software, so if you like the
framebuffer VNC server, please let them know.

Update: Pierre-Philippe Coupard no longer works at Lineo, so we at SDG Systems
(http://www.sdgsystems.com/) are currently maintaining it.
