$Id: README.usb,v 1.14 2007/02/16 18:26:41 desrod Exp $
======================================================================
README.usb
Author: David A. Desrosiers
Updated: Sun Feb  4 16:10:15 EST 2007
----------------------------------------------------------------------
TODO: 
	- Create README.porting as referenced in this HOWTO

======================================================================
This README will describe in detail, the process and programs required
to get pilot-link 0.12.0 and later working with standard usb
connectivity on Linux and Mac OS X machines.

Since the release of version 0.10.99 of pilot-link, USB-based Palm
handheld devices are fully supported by the entire suite of pilot-link
tools, conduits and bindings.

To get this working may require a few things to be configured on your
desktop or server machine first, and you should verify a few items to
make sure that it is working properly.
	
Currently (as of 2/4/2007), USB connections are supported on Mac OS X,
Linux and BSD-based operating systems on several hardware different
architectures.

Porting it to work with Win32 or and any other POSIX-compliant
environment (such as OS/2 or BeOS) should not be much harder. Please
see README.porting in the pilot-link docs subdirectory for more details
on how to help with these efforts.


Mac OS X USB Configuration
--------------------------
	There is nothing specific to do at all. No really, its just
	that easy.

	When you compile pilot-link on Mac OS X, the darwinusb driver
	code under ./libpisock/ is detected and built and supports USB
	handhelds as well as the PalmConnect USB serial adapter.
	
	All pilot-link command line tools take a special port "name" as
	their sole port argument. This is different from Linux where
	there is a very specific entry in /dev to manage, depending on
	your particular handheld (more on this point later).

	In OS X, there is no /dev filesystem, so we use a magic port
	designation which talks to the bus directly.

	On OS X, use the port designation of "-p usb:" if your Palm
	handheld is connected through a USB cradle, cable or a
	PalmConnect serial-to-USB adapter. That's it.
	
	Note that USB support on OS X requires Mac OS X 10.2 or later,
	and will not work on MacOS 9 or earlier versions.

	If you are running Mac OS X, you can ignore all the rest of
	this document, your job is done here; It Should "Just
	Work(tm)".


Linux USB Configuration
-----------------------
	Roll up your sleeves, this could get a bit confusing... but
	don't fret, I'm thorough and I'll walk you through every single
	step.

	First, in order to get USB working with your Palm device, your
	desktop machine must support the USB subsystem. Depending on
	your machine's configuration, this may require enabling USB in
	the machine's BIOS, or in your Linux kernel configuration, or
	perhaps just as simple as loading the required modules for your
	USB subsystem. Many of these are supported by current Linux
	kernels and recent Linux distributions (as of 2/2007).

	If you should find that your kernel is older than 2.4.21 (as of
	the date of this README), you will need to do a kernel upgrade
	to something more recent.

	Using kernels older than 2.4.21 are not recommended and may not
	work for newer Palm devices, as the kernel-level visor module
	that is required may not have support for your newer Palm
	device. In short, the kernel was released before your Palm
	device was released, so it doesn't know how to speak to it.

	With each new Palm device that is released, the vendor and
	product identifiers in the hardware have to be added to the
	visor module to allow it to recognize the device at connect
	time. See the "Loading visor" section below for more detail.

	First, verify that you have USB functioning properly on your
	system. If you're using a USB-based keyboard or a USB mouse and
	it works properly, you already have functioning USB support in
	your linux kernel, which was probably provided through your
	Linux distribution by default.

	If you are not using a USB device already, you can try to probe
	for the USB host controller that your system supports (you do
	have a system with USB ports on it, right? =) with the
	following syntax, as the 'root' user (only root can load and
	unload kernel modules in Linux):


	For 2.4.xx kernels
	-----------------------
		# /sbin/modprobe usb-ohci

		or..

		# /sbin/modprobe usb-uhci

		or..

		# /sbin/modprobe usb

	For 2.6.xx kernels
	-----------------------

		# /sbin/modprobe uhci_hcd
	
		or..

		# /sbin/modprobe ehci_hcd

	Each motherboard will have a specific chipset that one of these
	modules should support. You will only need one, so please don't
	be alarmed if you try to modprobe one of the above, and receive
	errors.  If you do, it simply means that the host controller
	isn't what the module expects; try one of the others.

	Once you have that working (verified to be loaded with
	lsmod(1), you can then try loading the USB serial support
	layer, using:

		# /sbin/modprobe usbserial

	If this is successful, you should see the following in the
	system logs (usually /var/log/messages):

		kernel: usb.c: registered new driver serial
		kernel: usbserial.c: USB Serial support registered for Generic
		kernel: usbserial.c: USB Serial Driver core v1.4

	Then on top of that, load the visor module. 

	The name of the module is called "visor" for historical
	reasons, here's why: The very first Palm device to support USB
	was a Handspring Visor. 

	Since then, many vendors such as Sony, Palm, and others have
	provided Palm handhelds with USB support, and this "visor"
	module should contain the proper code to sync and communicate
	with them as well; the code is still inside the module but it
	retains its legacy name.

		# /sbin/modprobe visor

	If successful, you should see the following entries in the
	logs:

		kernel: usbserial.c: USB Serial support registered for Handspring Visor / Treo / Palm 4.0 / Cli 4.x
		kernel: usbserial.c: USB Serial support registered for Sony Cli 3.5
		kernel: visor.c: USB HandSpring Visor, Palm m50x, Treo, Sony Cli driver v1.7

	Don't be alarmed if your version does not show these exact
	strings.  As long as you see the usbserial and visor module
	load successfully, without reporting any errors or unresolved
	symbols, the system is ready for the next step.

	Now if you do an '/sbin/lsmod' you should see something similar to this:

		Module                  Size  Used by    Tainted: PF 
		visor                   9036   0  (unused)
		usbserial              19904   0  [visor]
		usb-ohci               18080   0  (unused)
		usb-uhci               23012   0  (unused)


	Loading visor dynamically with custom device ids
	------------------------------------------------
	   If you're running Linux kernel 2.4.22 or higher, you can add
	   your vendor_id and product_id at module load time by passing
	   the values to modprobe(1) as follows:

		modprobe visor product=0x70 vendor=0x80

	   If you do not know the values that your device requires, you
	   can check your system logs in /var/log/messages after you
	   hit HotSync on your Palm device. It should show something
	   like this:

		usb.c: USB device 11 (vend/prod 0x830/0x61) 
			is not claimed by any active driver.

	   In that case, you know you want to pass the following values
	   to modprobe:

		modprobe visor product=0x61 vendor=0x830

	   Or you can put it in your /etc/modules.conf file as well,
	   using a similar syntax as follows:

		options visor vendor=0x54c product=0x144

	   Simple, right? Yes.


	Verifying device inode creation (non-udev)
	------------------------------------------
	   Next we must verify that the actual USB devices are created
	   and registered in /dev for you.

	   In your kernel source directory, under the kernel source
	   directory Documentation/usb/usb-serial.txt, is an overview
	   of how to create the proper USB devices on your system.

	   For Palm devices, you will need no more than two of these
	   devices, dev/ttyUSB0 and /dev/ttyUSB1, depending on your
	   Palm device manufacturer (as of the time of this README, two
	   Sony models use dev/ttyUSB0, and the rest of the Sony and
	   Palm models seem to be using /dev/ttyUSB1)

		# /bin/mknod /dev/ttyUSB0 c 188 0
		# /bin/mknod /dev/ttyUSB1 c 188 1

	   If you are using devfs (currently not recommended for
    	   security reasons), the devices supported will show up as
    	   /dev/usb/tts/0 and /dev/usb/tts/1 respectively. More on
    	   devfs issues will be covered later in this README.

	   Also, make sure your user has read and write permissions to
	   those device nodes:

		# the '?' used below is a wildcard and will chmod all
		# ttyUSB* devices with a single digit (USB1, USB2,
		# USB3, and so on).

		# /bin/chmod 0666 /dev/ttyUSB?
	   ..or

		# /bin/chmod a+rw /dev/ttyUSB?

	Configuring udev to create inodes dynamically for you
	-----------------------------------------------------
	   With the newer Linux distributions, you can take advantage
	   of udev(1), which will create and name devices for you
	   dynamically. Using udev, you don't have to create the
	   devices in /dev manually, nor do you have to create symlinks
	   to /dev/pilot if you want to use that interface.

	   Configuring udev is fairly straightforward: 

		1. Install the latest udev package for your Linux distribution

		2. Create a file in /etc/udev/rules.d called
		   pilot.rules, with the following information in it
		   (all on one line, and do not make a typo or it will
		   not work properly):

			BUS=="usb", SYSFS{product}=="Palm Handheld*|Handspring *", KERNEL=="ttyUSB*", NAME="ttyUSB%n", SYMLINK="pilot", GROUP="usb", MODE="0666"

		   Yep, that's it. 

		3. Restart udev using whatever service restart tools
		   your distribution provides. You do not have to
		   reboot for this to take effect.


Linux Kernel Configuration
---------------------------
	If your distrubution-supplied Linux kernel does not have native
	USB support, you will have to build it into your kernel first.
	Building a Linux kernel is not as hard or as daunting as it
	seems, and is in fact, quite rewarding. Not only do custom
	kernels perform better, but they tend to be faster, because
	they only include support for hardware _on_ your system, and
	not hardware you don't. You wouldn't build a kernel for SCSI
	support, if you didn't have SCSI drives in your system, would
	you?

	There is a very comprehensive and concise kernel-building-HOWTO
	which will walk you through the entire process, in
	non-confusing language, found here:

		http://howto.gnu-designs.com/kernel-HOWTO

	Once you have built a kernel, and tested it, you can easily add
	the necessary support for USB devices and USB host controller
	support into it afterwards.
	
	After configuring your Linux kernel, you will find in your
	kernel source directory, is a file called .config ("dot
	config"). In this file, are several parameters you will need to
	add/change to enable proper USB support.

		CONFIG_USB=y
		CONFIG_USB_DEBUG=y
		CONFIG_USB_DEVICEFS=y
		CONFIG_USB_UHCI=m
		CONFIG_USB_UHCI_ALT=m
		CONFIG_USB_OHCI=m

		CONFIG_USB_SERIAL=m
		CONFIG_USB_SERIAL_GENERIC=y
		CONFIG_USB_SERIAL_VISOR=m   

	If you would like to support for other USB devices (such as a
	USB-based digital camera, or scanner) you can add it here as
	well.

	Rebuild your kernel as specified in your favorite kernel HOWTO,
	and then proceed to the previous section to verify that all
	required USB bits are functioning.


Talking to your Palm over USB
-----------------------------
	To now "speak" to these devices you've created, using the
	drivers you loaded, you must hit the HotSync button on your
	cradle first, before launching any of pilot-link's various
	utilities, if your version of pilot-link is earlier than
	0.11.8.

	When you hit the HotSync button on the cradle or by tapping on
	your HotSync icon on the Palm itself, you should see something
	similar to the following in the system logs (/var/log):

		kernel: Manufacturer: Palm, Inc.
		kernel: Product: Palm Handheld
		kernel: SerialNumber: L0JH14R12345
		kernel: usbserial.c: Handspring Visor / Palm 4.0 / Cli 4.x converter detected
		kernel: visor.c: Handspring Visor / Palm 4.0 / Cli 4.x: Number of ports: 2
		kernel: visor.c: Handspring Visor / Palm 4.0 / Cli 4.x: port 1, is for Generic use and is bound to ttyUSB0
		kernel: visor.c: Handspring Visor / Palm 4.0 / Cli 4.x: port 2, is for HotSync use and is bound to ttyUSB1
		kernel: usbserial.c: Handspring Visor / Palm 4.0 / Cli 4.x converter now attached to ttyUSB0 (or usb/tts/0 for devfs)
		kernel: usbserial.c: Handspring Visor / Palm 4.0 / Cli 4.x converter now attached to ttyUSB1 (or usb/tts/1 for devfs)
		kernel: usb.c: serial driver claimed interface c76aa160

	If you received errors or see a message similar to the following:

		kernel: usb.c: USB device 28 (vend/prod 0x54c/0x95) is not claimed by any active driver

	...see the "Loading visor dynamically with custom ids" section
	above.

	Once your module is loaded, and you see the successful message
	when you hit HotSync, you can now launch any of pilot-link's
	various conduits such as:

		$ pilot-dlpsh -p /dev/ttyUSB1

		..or 

		$ pilot-dlpsh -p /dev/pilot

		export PILOTPORT=/dev/ttyUSB1
		$ pilot-xfer -l

	It should connect and allow you to talk to your Palm device.
	The PILOTPORT environment variable will be read if the '-p'
	option is not specified. If you do not specify either,
	/dev/pilot will be used if it exists. Substitute ttyUSB1 for
	your port, based on the DeviceMatrix above.


FreeBSD USB Configuration 
-------------------------
	This information copyright 2002 Anish Mistry & David A.
	Desrosiers.  All rights reserved. Written by Anish Mistry of AM
	Productions (http://am-productions.yi.org)

	Configuring FreeBSD to speak to your Palm device over USB is a
	bit different from Linux and OSX. Here are the quick steps:

	1. Create a small shell script to be executed from your
	usbd.conf.

		#!/bin/sh

		# export the following enviornmental variables to enable full
		# logging of a connection
		#
		# export PILOT_LOGFILE=$HOME/.pilot/pilot-link.log
		# export PILOT_LOG=1		# set to 0 to disable logging
		# export PILOT_DEBUG="DEV SLP CMP PADP NET SOCK"
		# export PILOT_DEBUG_LEVEL="DEBUG"
		/usr/local/bin/pilot-xfer -p usb:/dev/$1 --sync $HOME/.pilot/

	2. You will need to su to root and add the following to your
 	   /etc/usbd.conf before the passthrough entry. Your entry may
 	   vary depending on your handheld.

	   In order to find out what your particular Palm handheld
	   requires for 'vendor' and 'product' below, make sure your
	   kernel has support for 'ucom' and 'uvisor', and run 'usbdevs
	   -v' AFTER hitting HotSync on your Palm device. The fields
	   will be displayed, simply copy them into the appropriate
	   places as shown below.

		##########################
		## Handspring visor (PDA)
		device "Handspring Visor"
		   devname "ugen0"
		   vendor 0x082d
		   product 0x0100
		   release 0x0100
		   # pilot-link
		   # attach "/home/dir/.pliot/pilot-sync.sh ${DEVNAME}"

	3. Kill and restart the usbd daemon with the following (as
	root)

		# killall usbd && usbd

		Verify that usbd properly restarted with: 

		# ps ax | grep usbd

	4. Press the HotSync button again on your cradle.

	5. Launch the application of your choice to syncronize with
	   your Palm handheld. 'pilot-xfer' and 'dlpsh' are two common
	   ones to try. The correct syntax is:

		$ /usr/local/bin/pilot-xfer -p /dev/ucom0 -b $HOME/.pilot/

		$ /usr/local/bin/dlpsh -p /dev/ucom0

		The first sync can take a while, so please be patient.

		Alternately, you can uncomment the 'attach' line in
		/etc/usbd.conf above and restart usbd as explained in
		step 3 above.

	6. You're done. Enjoy! (This is the most important item.)


USB Palm Handheld Device Kernel Matrix
--------------------------------------
	Many thanks go to Greg Kroah for his tireless work supporting
	these new devices as they come out. The matrix of which kernels
	support which Palm handheld device can be found at the
	pilot-link wiki, at the following URL:

		http://www.pilot-link.org/DeviceMatrix

	If you see your Palm in this list, you must be running the
	corresponding kernel version to be able to use it with
	pilot-link or ColdSync using the USB interface.

	If you don't see your Palm device there, feel free to add your
	entry so others can benefit from the vendor and product
	information you've added.


None of this is working! Where do I go for help now?
--------------------------------------------------------------------------
        There are mailing lists and an irc channel that can help. You
        can find those at the following places:

        General discussion, problems, configuration issues
        ------------------------------------------------------
        http://www.pilot-link.org/mailman/listinfo/pilot-link-general

        Development-related issues and discussion, i.e. "code"
        ------------------------------------------------------
        http://www.pilot-link.org/mailman/listinfo/pilot-link-devel

        pilot-link irc channel
        ------------------------------------------------------
        We can also be found on irc, at irc.pilot-link.org in the
        channel #pilot-link

        If your irc client supports SSL, you can point to port 994 on
        irc.pilot-link.org and have a secured session (no cleartext).

        If you cannot use SSL, use port 6667 for "normal" irc.

        Lastly, I can be reached directly at desrod@gnu-designs.com if
        nothing else works for you. Try the mailing lists and irc first
        though, as I might be hard to reach at times.


Donating to pilot-link
--------------------------------------------------------------------------
        Do you like our work? Do you rely on the code we release for
        your daily work or for your own commercial or OSS project?

        Please consider donating to keep the project going. We're 100%
        self-funded, and we see a LOT of traffic from users and
        downloads. Every contribution helps, whether to pay for
        bandwidth or to buy devices for testing.

        You can help support us by visiting the pilot-link.org site and
        clicking on the "Donate" button on the left side of the page.  

        We thank you for your contributions, whatever you can offer.


Thanks go to...
--------------------------------------------------------------------------
        Justin Paulsen, "Petaris" on irc, for his tireless testing
        efforts, mirroring pilot-link releases, helping out users on
        irc, and keeping things lively in general.

        Florent Pillet, "fpillet" on irc, for helping fix up libpisock
        to work on OSX and doing testing on newer devices to work out
        the various Heisenbergs found in there. His work has been
        invaluable over the last year or two with usb, devices and OS X
        support.

        Zephania Hull, "Mercury" on irc for spending the time and
        effort to get libusb worked out on the Linux side. Without his
        effort, libusb wouldn't be where it is today.

        Other thanks go to Knghtbird, Nicholas Piper, Adriaan de Groot,
        John Marshall, Kenneth Albanowski and many others through the
        years for helping bring this to where it is today. If I've
        forgotten to mention you, just let me know.