TDE
/
extra-dependencies
mirror of https://mirror.git.trinitydesktop.org/gitea/TDE/extra-dependencies.git
0
0
Fork 0
Code Issues Releases Wiki Activity
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.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'e6ba08c3b2'
${ noResults }
extra-dependencies/debian/pilot-link/pilot-link-0.12.5-dfsg/doc/README.usb

520 lines
19 KiB
Raw Blame History Escape

$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<6C> 4.x
kernel: usbserial.c: USB Serial support registered for Sony Cli<6C> 3.5
kernel: visor.c: USB HandSpring Visor, Palm m50x, Treo, Sony Cli<6C> 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<6C> 4.x converter detected
kernel: visor.c: Handspring Visor / Palm 4.0 / Cli<6C> 4.x: Number of ports: 2
kernel: visor.c: Handspring Visor / Palm 4.0 / Cli<6C> 4.x: port 1, is for Generic use and is bound to ttyUSB0
kernel: visor.c: Handspring Visor / Palm 4.0 / Cli<6C> 4.x: port 2, is for HotSync use and is bound to ttyUSB1
kernel: usbserial.c: Handspring Visor / Palm 4.0 / Cli<6C> 4.x converter now attached to ttyUSB0 (or usb/tts/0 for devfs)
kernel: usbserial.c: Handspring Visor / Palm 4.0 / Cli<6C> 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.
View Git Blame Copy Permalink