3.1. Requirements

Some obvious things are required, such as a computer, USB ports, Handspring Visor (with USB cradle). You should also know how to compile and install programs and the kernel. If you do not, you have a few options: learn, get your resident expert to help you, or get a distro with everything prepared for you.

If you don't have a USB controller for your computer, then you need to either buy the serial cradle for the Visor (but you wont need this document), or buy a USB-capable device for your computer (ie. add-on card or a new motherboard).

3.2. Kernel Version

The linux kernel version v2.4 was the first to have USB support. You can get the latest v2.4 kernel from: ftp://ftp.kernel.org/pub/linux/kernel/v2.4/.

The USB code has been backported to the v2.2 kernel, starting at version v2.2.18. If you must, you should probably be able to follow the same instructions with the latest v2.2 kernel

Now would be a good time to download the latest kernel, and configure things to your desire. The following has the instructions you need to configure USB.

If you have already have compiled and installed the kernel, you should not need to reboot! All we need to do is to compile and install the appropriate modules, and we will be all set.

3.3. USB Controller Type

The first thing to do is o determine which type of USB host controller you have. The USB host controller is the hardware in your computer which handles USB input/output.

Motherboards based on Intel chipsets, are typically UHCI controllers. Most addon cards are OHCI controllers. You can determine the type of USB hardware available by using, as root, the following command:

lspci -v

If you see an entry like:

USB Controller: ......
Flags: .....
I/O ports at ....

Then you have a UHCI based controller. If you see an entry like:

USB Controller: .....
Flags: ....
Memory at .....

Then you have a OHCI based controller. You could refer to http://www.linux-usb.org for further details. The kernel documentation /usr/src/linux/Documentation/usb/usb.txt may also be helpful in determining which type of controller you have.

3.4. Configure/Build Kernel

Now we need to configure, and make your kernel. During configuration, make sure you enable the following entries. You may either compile them directly into your kernel, or as modules. It is highly recommended that you compile them as modules. If you compile them directly in, you will need to reboot.

• USB support (CONFIG_USB)

• The preliminary USB Device Filesystem (CONFIG_USB_DEVICEFS)

• The appropriate controller - UHCI, or OHCI (CONFIG_USB_UHCI, or CONFIG_USB_OHCI)

• USB Serial Converter support (CONFIG_USB_SERIAL)

• USB Handspring Visor Driver (CONFIG_USB_SERIAL_VISOR) (serial converter's sub-option)

There are two UHCI drivers. You do not want the "UHCI Alternate (JE)" driver. This driver does not yet support all the USB features which the Visor uses. Thus, you will be unable to sync using this driver. If you are unable to see the original driver, ensure that the UHCI-JE driver is NOT selected, you should then see the option for both drivers.

Here, you should decide if you would like to include Hotplug support. With Hotplug support, you are able to auto-magically sync your visor by only pressing the Hotsync button. Please see the hotplug section, and especially the Hotplug Kernel Config, before choosing this route.

Compile and install as required. Don't forget to run lilo. If you are installing a new kernel image, do not reboot yet.

3.5. usbdevfs

usbdevfs puts information about your USB bus into the /proc directory tree. Its a good thing, and can be especially useful for debugging. You can enable it by adding the following line into your /etc/fstab.

none  /proc/bus/usb  usbdevfs  defaults  0  0

If you installed a new kernel image, you could reboot from this point on. Remember, if you are just adding the USB info as modules, you do not need to reboot.

3.6. Making /dev Entries

If your linux distro does not come with USB Visor support, or if you are NOT using devfs (not the same thing as usbdevfs), you will need to make the USB tty devices.

If you are using devfs, these devices are automagically created under /dev/usb/tts/{0,1,...}; so you can skip ahead to using the modules

If you are not using devfs, you can create the devices by executing these commands, as root:

            mknod /dev/ttyUSB0 c 188 0
            mknod /dev/ttyUSB1 c 188 1
            mknod /dev/ttyUSB2 c 188 2
            mknod /dev/ttyUSB3 c 188 3
            etc...
            chmod 666 /dev/ttyUSB*
            

You are able to have up to 255 connections/ports/devices, but unless you have more than one USB serial device, you'll probably only need the first few. The chmod is to allow users to be able to access the Visor device. It is the opinion of the author of this document that this should be safe for a personal computer. Multiuser computers may want to look into the security for this (please let me know).

When a Visor connects, there are two "ports" opened. (For most people, this will be /dev/ttyUSB0, and /dev/ttyUSB1). The first port (zero), is a generic connection. The second port is the hotsync port. This feature allows for future developments; for example, to export a filesystem from the Visor. A useful thing to do is to create a link to the hotsync port so that synchronization software will use the appropriate device be default. You can do this by:

            cd /dev
            ln -s /dev/ttyUSB1 pilot
            ln -s /dev/ttyUSB1 palm
            

The software package pilot-xfer uses /dev/pilot by default. coldsync defaults to /dev/palm. Create devices and links as appropriate. Just for fun, you might also want to create a link from /dev/visor to /dev/ttyUSB1, just, well, because we have a visor, not a pilot (or Palm(tm)). The actual device number may change, depending on how many (active?) USB-serial devices you have on your system. A message containing the device actually used is entered into syslog. Eventually, the idea is to make an entry in the /proc filesystem which contains the needed information.

3.7. Using the Modules

For people who compiled the USB code as modules, you will also need to insert the modules into the running kernel. When you want to use the visor, you will need to runt the following commands as root:

            /sbin/modprobe usb-uhci
            /sbin/modprobe usb-ohci
            /sbin/modprobe visor
            

One important note is that the actually driver/device connection for /dev/ttyUSB* are not created in the kernel memory until the hotsync button is pressed. Therefore, if you try to use any software before pressing the hotsync button, it won't work.