You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
392 lines
14 KiB
392 lines
14 KiB
$Id: README.libusb,v 1.4 2007/02/16 18:26:41 desrod Exp $
|
|
======================================================================
|
|
README.libusb
|
|
Author: David A. Desrosiers
|
|
Updated: Sun Feb 4 15:49:15 EST 2007
|
|
======================================================================
|
|
This README will describe in detail, the process and programs necessary
|
|
to get pilot-link 0.12.0 and later working with libusb on Linux and Mac
|
|
OS X machines.
|
|
|
|
Why do I want to use libusb?
|
|
--------------------------------------------------------------------------
|
|
libusb is an alternative way of communicating with USB devices
|
|
on Linux, Unix, Mac OS X and Windows machines.
|
|
|
|
In the Linux world, Palm devices using USB would require the
|
|
Linux kernel's "visor" module, written and maintained by Greg
|
|
Kroah-Hartman.
|
|
|
|
A lot of work and testing has been put into the visor module
|
|
over the years and it is very solid, but making sure that it
|
|
remains current with released Palm devices can be problematic,
|
|
because the devices coming out are always different and some
|
|
can require special handling.
|
|
|
|
The current version of the visor module allows you to insert it
|
|
into the kernel namespace with the proper Palm product and
|
|
vendor values at runtime (described in README.usb), so
|
|
modifying the module's source code and rebuilding it is no
|
|
longer necessary as it was with earlier versions of the visor
|
|
module.
|
|
|
|
Using libusb, you no longer have to use the visor module, and
|
|
you can talk "directly" to the device. In short, libusb
|
|
requires less maintenance overhead, and is MUCH faster to use
|
|
with current Palm devices (roughly 200% to 600% faster,
|
|
depending on your Palm's processor speed and the type of
|
|
records you are syncronizing across. YMMV, of course.).
|
|
|
|
|
|
Why is visor so slow? Why is libusb so much faster?
|
|
--------------------------------------------------------------------------
|
|
In testing, syncronizing a Palm device with libusb has been
|
|
shown to be anywhere from 200% to 600% faster vs. using the
|
|
kernel visor module.
|
|
|
|
The kernel visor module itself is not "slow", there are just
|
|
more kernel interfaces to pass through, which slows down the
|
|
communication between kernel and Palm.
|
|
|
|
It has never been optimized for speed, and certainly could be,
|
|
if someone was interested in doing so. The primary maintainer
|
|
is not.
|
|
|
|
|
|
Does it work with every device?
|
|
--------------------------------------------------------------------------
|
|
It works with every device I've personally tested it with,
|
|
which isn't saying much. This includes an m505, T2, T3, Treo650
|
|
and Treo680 device. They all work over libusb without too much
|
|
trouble at all.
|
|
|
|
Some devices behave very differently with respect to the
|
|
"timing" between the point where you hit HotSync and the time
|
|
libusb recognizes it on the bus, but everything I've used with
|
|
it seems to work once I get a feel for the right timing.
|
|
|
|
Does that mean it will work with every device? No. We need
|
|
testers to make sure it works reliably.
|
|
|
|
If you have a device that doesn't work with libusb, we want to
|
|
know about it.
|
|
|
|
|
|
How do I use libusb, assuming I have all the pieces?
|
|
--------------------------------------------------------------------------
|
|
Simply pass the port of 'usb:' (without the quotes) as the port
|
|
designation when using any pilot-link or GUI conduits or tools.
|
|
Some examples of that are:
|
|
|
|
pilot-xfer -p usb: -b $HOME/Palm/backups
|
|
|
|
pilot-dlpsh -p usb:
|
|
|
|
pilot-nredir -e -p usb:
|
|
|
|
The same syntax applies when running pilot-link on Mac OS X
|
|
machines.
|
|
|
|
When you configure J-Pilot, gnome-pilot or KPilot, the port
|
|
designation of 'usb:' is still the same.
|
|
|
|
|
|
What are these "pieces" I need?
|
|
--------------------------------------------------------------------------
|
|
Now things get really interesting.
|
|
|
|
Below are the necessary programs and versions you'll need.
|
|
|
|
These are the MINIMUM versions you can use. Anything earlier
|
|
than these versions WILL NOT work, and will likely cause other
|
|
problems.
|
|
|
|
- pilot-link....: 0.12.0
|
|
- libusb........: 0.1
|
|
- libusb-dev....: 0.1 headers
|
|
- udev..........: 0.70
|
|
- Linux kernel..: 2.4.21 or 2.6.10
|
|
|
|
You'll also need the 60-libpisock.rules file included in the
|
|
latest pilot-link release. A copy of the current file can be
|
|
found at the following URL, and will always be updated to
|
|
reflect the latest changes or additions:
|
|
|
|
http://cvs.pilot-link.org/index.cgi/doc/60-libpisock.rules
|
|
|
|
Let's go through each item above and see what we need here:
|
|
|
|
pilot-link
|
|
---------------------------------------------------
|
|
First, you'll need to grab a copy of the latest release
|
|
of pilot-link 0.12.0 or later. libusb does NOT work
|
|
with pilot-link v0.11.8 or previous versions. There is
|
|
no code in pilot-link 0.11.8 to use libusb, so you
|
|
can't use that version or anything earlier than that.
|
|
|
|
You MUST use 0.12.0 or later to use libusb. Stick with
|
|
the latest public release (and not CVS versions) and
|
|
you'll be fine.
|
|
|
|
CVS versions tend to include some unstable code being
|
|
put there for other developers to test, and may
|
|
sometimes break, so its best to stick with a public,
|
|
released version.
|
|
|
|
libusb
|
|
---------------------------------------------------
|
|
libusb should be a part of your current Linux or
|
|
FreeBSD distribution. If it isn't, you can install it
|
|
with the standard Linux package management tools for
|
|
your distribution (apt-get, yast2, yum, etc.)
|
|
|
|
On Debian, this is as simple as:
|
|
|
|
apt-get update && apt-get install libusb libusb-dev
|
|
|
|
This should get you the pieces you'll need.
|
|
|
|
On Fedora/Red Hat, you can use yum or urpmi or similar
|
|
tools, as in:
|
|
|
|
yum update
|
|
yum install libusb libusb libusb-devel
|
|
|
|
Other distributions may vary, but the package names
|
|
should be similar.
|
|
|
|
Remember, you'll want version 0.1 or later, and make
|
|
sure you use the one supplied with your distribution.
|
|
Don't try to build and install your own version from
|
|
source, unless your distribution uses that method
|
|
(FreeBSD, Gentoo, LFS)
|
|
|
|
udev
|
|
---------------------------------------------------
|
|
Your distribution should have this already, there is no
|
|
need to install it, but you may need to update it to
|
|
the latest, current version if you are behind in
|
|
updates.
|
|
|
|
The important thing is that you have a version of AT
|
|
LEAST 0.70 or later. Anything earlier will cause
|
|
problems, and we cannot support it.
|
|
|
|
BIG FAT WARNING: Do not... I repeat, do NOT try to
|
|
build and install udev from source. The documentation
|
|
that comes with it warns against it, and it WILL break
|
|
things. Don't do it. Use your distributions package for
|
|
it and you'll be fine.
|
|
|
|
|
|
How do I configure these pieces on Linux?
|
|
--------------------------------------------------------------------------
|
|
Easy!
|
|
|
|
Assuming you have all of the prerequisites above, and have
|
|
compiled (but NOT installed!) pilot-link 0.12.0 against libusb
|
|
(described below, don't worry), and that it reported a
|
|
successful libusb implementation at configure time, you can
|
|
proceed.
|
|
|
|
setting up the rules file for udev
|
|
---------------------------------------------------
|
|
We need to configure and restart udev first, and since
|
|
its the easiest of the pieces, we'll start there.
|
|
|
|
Put the 60-libpisock.rules file that came with your
|
|
pilot-link release in '/etc/udev/rules.d/' and restart
|
|
udev.
|
|
|
|
Check that the file was read and parsed by udev by
|
|
looking at the udev logs in /var/log (if you log, if
|
|
not, enable logging in /etc/udev/udev.conf and restart
|
|
udev to verify), or use the following to enable logging
|
|
at runtime:
|
|
|
|
udevcontrol log_priority="debug"
|
|
|
|
Check that it saw the new file and has correctly parsed
|
|
it.
|
|
|
|
mount the kernel's usbfs
|
|
---------------------------------------------------
|
|
Make sure you have usbfs mounted, which can be found in
|
|
fstab, by adding the following line:
|
|
|
|
# <file system> <mount point> <type> <options>
|
|
none /proc/bus/usb usbfs defaults
|
|
|
|
Then 'mount -a' to make sure its mounted. You should
|
|
now have a /proc/bus/usb directory heirarchy. The "new"
|
|
udev and libusb will be using /dev/bus/usb, but many
|
|
applications still use /proc/bus/usb, so we'll mount it
|
|
until that gets deprecated.
|
|
|
|
blacklist the kernel visor module
|
|
---------------------------------
|
|
In order to use libusb, you'll want to make sure the
|
|
kernel "visor" module does not automatically load when
|
|
it sees a Palm device connecting to the USB root hub on
|
|
your system.
|
|
|
|
udev method (for newer udev versions, no hotplug)
|
|
-------------------------------------------------
|
|
If your udev is new enough and you no longer use
|
|
hotplug, you can use the following process to blacklist
|
|
the visor module:
|
|
|
|
Simply add the two words 'blacklist visor' (without
|
|
quotes) to a new file called:
|
|
|
|
/etc/modprobe.d/blacklist-palm
|
|
|
|
If that file doesn't exist, create it and put the
|
|
one-line entry into it.
|
|
|
|
older method (for systems still using hotplug)
|
|
-------------------------------------------------
|
|
You can blacklist list by adding 'visor' to the
|
|
/etc/hotplug/blacklist file to stop hotplug from
|
|
loading it at connect time.
|
|
|
|
Don't forget to restart hotplug to re-read the
|
|
blacklist file.
|
|
|
|
pilot-link
|
|
---------------------------------------------------
|
|
You'll need to compile pilot-link by passing the
|
|
--enable-libusb option at configure time. When you
|
|
configure it with libusb support, you should see the
|
|
following output in the summary page:
|
|
|
|
Direct USB support...... : yes, libusb
|
|
|
|
If you do not see that, you are missing some critical
|
|
build dependency (such as the libusb development
|
|
package, which includes the necessary header files to
|
|
provide this support).
|
|
|
|
Check config.log, search for libusb and see what went
|
|
wrong. Remember, you'll need the libusb headers to
|
|
build the support into pilot-link for it, not the
|
|
runtime. This will be a libusb-dev or libusb-devel
|
|
package on most distributions.
|
|
|
|
|
|
How do I configure these pieces on OS X?
|
|
--------------------------------------------------------------------------
|
|
OSX is even easier, you don't have to do anything. Just
|
|
configure pilot-link *WITHOUT* passing the --enable-libusb
|
|
option, and use the same port designation ('usb:' without
|
|
quotes), and it will "Just Work(tm)". Many thanks go to Florent
|
|
Pillet for debugging this and making it work as quickly as it
|
|
does.
|
|
|
|
Florent's SyncBuddy product is based on libpisock, the core
|
|
library behind pilot-link. If you want a VERY fast
|
|
syncronization application for OSX which can read Photos,
|
|
external storage, backup, and do many other things, check it
|
|
out and support his efforts and contributions:
|
|
|
|
http://www.florentpillet.com/syncbuddy.html
|
|
|
|
|
|
Ok, I have all the pieces, I've configured them, now what?
|
|
--------------------------------------------------------------------------
|
|
If you're sure you've done everything above, and all services
|
|
and pieces are configured and restarted properly, you're almost
|
|
done.
|
|
|
|
The last step is to try it. To do that, just launch any of the
|
|
pilot-link conduits using the following syntax:
|
|
|
|
pilot-link -p usb: -l
|
|
|
|
pilot-dlpsh -p usb:
|
|
|
|
You should see something like this:
|
|
|
|
$ pilot-xfer -p usb: -l
|
|
|
|
Listening for incoming connection on usb:...
|
|
|
|
The port designation for libusb is simply 'usb:' (minus the
|
|
quotes). You can launch it at the desktop side first, and it
|
|
will wait for an incoming connection for as long as it takes to
|
|
receive one.
|
|
|
|
That's it. If you get any sort of error or other problem, make
|
|
sure the visor module is truly unloaded (rmmod visor, as root),
|
|
make sure udev and hotplug are restarted, make sure your
|
|
pilot-link is the right version (built with libusb support),
|
|
and make sure your .rules file is in the right place for your
|
|
Palm device.
|
|
|
|
|
|
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.
|
|
|