Penguin carries Palm under arm

1. Introduction.

2. Standard disclaimer.

3. Hotsyncing Palm with Linux host.

4. Palm networking using Linux host as router.

5. References and thanks.

6. Author.

1. Introduction.

Shortly speaking: This page is for people wishing to link USB-equipped handhelds with/through Linux host using USB cradle.

2. Standard disclaimer.

2.1 Author does not take any responsibility for possible software crashes, hardware destructions and brain damages, that may follows using tips/tricks/patches mentioned in this document. Use it for You own risk.

2.2 Patches mentioned here is the quick and dirty hacks for long-existing Open Source software. Altough these software packages are well known and well tested tools, using my patches for tweaking these packages may cause some strange/incorrect behavior. Authors/communities supporting these packages does not have any guilties is these. Author of these patches have no guilty too, because [You are warned in 2.1]. All abuse must be directed to /dev/null.

2.3 Author does not provide any form of support or advisory for patches/examples supplied on this page, nor software mentioned here. You must have basic skills in Unix/Linux and know how to configure/compile kernel, how to compile software under Linux, how to apply patches etc.

2.4 All patches/tricks/exapmles may be freely used, modified and improved by anyone. If You found things are useful and wish to reference or quote this page in any sort of information sources, notify me about this.

2.5 Author yields apologies for it's poor English.

3. Hotsyncing Palm with Linux host.

3.1 Kernel configuration

# Core USB support
CONFIG_USB=m
CONFIG_USB_DEBUG=y
CONFIG_USB_DEVICEFS=y
# Host hardware (USB hub support); really, You need only one of
# these items, depending of Your chipset type. First two is for Intel chipsets,
# last - for ALi, VIA and so on.
CONFIG_USB_UHCI=m
CONFIG_USB_UHCI_ALT=m
CONFIG_USB_OHCI=m
# USB Serial Converter support; These modules needed for convert
# USB-connected device into serial-tty-like Linux device. First two modules
# is USB/serial redirector modules, third is "recognizer" of particular USB-connected
# device (if You look at drivers/usb/serial/ options, You will see many options,
# not only Palm handhelds)
CONFIG_USB_SERIAL=m
CONFIG_USB_SERIAL_GENERIC=y
CONFIG_USB_SERIAL_VISOR=m

3.2 Kernel patching

make dep && make clean

make modules && su -c 'make modules_install'

3.3 Loading drivers

insmod usbcore.o
insmod usbserial.o
# one of these, depending of Your USB-hub hardware
insmod usb-uhci.o | uhci.o | usb-ohci.o
insmod visor.o

# USB handhelds support
alias char-major-188 visor
# one of these, depending of Your USB-hub hardware
post-install usbserial modprobe usb-uhci | uhci.o | usb-ohci.o

3.4 Configuring coldsync.

# Sample of ~/.coldsyncrc
listen serial {
        protocol: simple;
        device: "/dev/ttyUSB1";
}

pda "mypalm" {
        directory: "/home/jsmith/palm/coldsync";
        username: "jsmith";
        userid: 501;
        default;
}

• About protocol simple in listen section. It must present if You have handheld with Palm OS 4.0 and above. Remove this statement if Your handheld have Palm OS 3.5.
• About using /dev/ttyUSB1, not /dev/ttyUSB0. When handheld connects to host (sync button pressed or icon in HotSync application tapped), serial redirector attaches two ttys: /dev/ttyUSB0 (used for control purposes, unknown for me), and /dev/ttyUSB1 (used for data transmission). We supply second of these ttys to coldsync.
• About username/userid. If Your handheld already initialized via Palm's HotSync software (initializing means assigning some username and userid from desktop to handheld; remember HotSync question about username at first syncing?), You can supply existing username/userid to coldsync in pda section. Procedure for discovering username/userid at handheld via special shortcut described in coldsync documentation. Optionally, You may discover username/userid from binary file users.dat placed in Windows Palm Desktop directory. Open this file in some hex viewer, find Your username, then step back one-byte username length, then two-byte zero (may be this is most significant word of userid) and see two-byte userid. Here is (euristically discovered) partial users.dat record format:

  struct users_dat {
      u16 userid;
      u16 zero_word; /* may be, this is MSW of userid, */
                     /* then userid has u32; Palm Desktop can
                     /* support up to 2^32 users? Cool! :) */
  
      char name_len;
      char name[];
      char dir_name_len;
      char dir_name[];    /* subdirectory where HotSync stores data */
                          /* for this user; at most 6 bytes length */
  };
  

  Do not forget about little-endianess of Intel architecture: swap bytes for construct userid for ~/.coldsyncrc.
  If Your handheld has not yet initialized (I use my old Palm V about two years without without Palm Desktop software and, accordingly, without "initialization"; I used pilot-link for backing up data and installing applications/databases), You may:
  select username/userid as You wish, write they in "pda" section and issue

  coldsync -mI

  for initialization;
  or, simply issue coldsync -mI for initialization handheld with Your current Unix username and userid (not root, I hope)... Yea, coldsync must be named COOLsync. :)
  WARNING: Do not use userids with zero MSB (<=255), if You plan to use Windows Palm Desktop software too; Palm Desktop treats these ids as "profiles", not as users.
  WARNING: Never use zero userid; see coldsync documentation about this.

coldsync -mb ~/palm/coldsync

3.5 Coldsyncing more comfortably (coldsync daemon mode).

# Sample of /etc/palms
123456789|jsmith|11000|501|mypalm

• 123456789 - serial number of Your Palm (see info in App Launcher);
• jsmith - username of Your Palm;
• 11000 - userid of Your Palm; It may be same as Unix userid, 11000 given here for example only; See note in previous chapter about discovering/setting up of userid;
• 501 - Your Unix userid (coldsync performs setuid() and uses Your ~/.coldsyncrc);
• mypalm - name of pda section for this Palm in Your ~/.coldsyncrc.

cs:235:respawn:/usr/local/bin/coldsync -v -t serial -P simple -l /syslog/coldsync.log -md ttyUSB1

init q

#!/bin/bash
#
# Give USB stack enough time to destroy old /dev/ttyUSB
sleep 20
/usr/local/bin/coldsync -v -t serial -P simple -l /syslog/coldsync.log -md ttyUSB1

In inittab:

cs:235:respawn:/usr/local/bin/coldsync-sleep.sh

Or, You may apply this patch to coldsync source tree and recompile coldsync. Patch uses asyncronous read with select(). If nothing to read from device for 15 seconds, we terminates with ETIMEDOUT status. Then init process respawns coldsync and everything is ok. Moreover, this patch fixes unreliable read of of packet header in netsync_read_method()@netsync.c Netsync protocol uses in local exchange with Palm OS 4.0 devices and in network syncing with all Palms. Original code does read of all header in one read() and fails if not all bytes arrived at this moment.

Addtional information about daemon mode (21-Feb-2002) for people using a post-sync (dump) conduits.
Dump conduits is directed to exporting data from syncronized backup copies of Palm databases to various desktop formats. A comprehensive info about conduits with examples and documentation You may found here.
You are in trouble with both standard and patched version of coldsync. Coldsync runs dump conduits after main syncing is complete, device is disconnected from host and device filedescriptor is closed by coldsync. When disconnect event occurs at tty line, device driver send SIGHUP to process, which uses a tty line. Original coldsync does not install a handler of SIGHUP. When coldsync runs from shell, SIGHUP caught and handled by shell (at least BASH does such), but init reset all signal handlers to defaults before forking any process. Default action for SIGHUP is to terminate the process, then coldsync terminates and does not runs all things after close() call.

Theoretically, coldsync will demonstrate this behavior with any Palms, including serial-equipped, not only with USB. Unfortunately, I have no possibility for testing this assumption.
Two workarounds of this issue, without and with more hacking of coldsync:

• Without hacking. Start codsync under nohup program, which blocks/ignores SIGHUP. Create file /etc/initscript as follows:

  #
  # Sample of /etc/initscript file
  #
  PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin
  export PATH
  
  # Execute the program.
  nohup $4
  

  When init detects this file, it will execute it for each process with following command line:

  /bin/sh /etc/initscript id level action process
  

• With hacking. Apply modified patch (it includes previous corrections about asyncronous read()) to clean coldsync sources and recompile coldsync. Coldsync will caught SIGHUP (only in daemon mode) and stays alive after closing tty line.

4. Palm networking using Linux host as router.

4.1 Setting up PPP connection between Palm and Linux host.

Software prerequisites:

• USB/serial redirector support in kernel (You already have it, see Chapter 3),
• PPP support in kernel (CONFIG_PPP=m),
• PPP daemon,
• mgetty
.

Standard mgetty will not work over not existing tty device, bacuse USB/redirected ttys exists only when Palm is active and destroyed when Palm disconnects.Therefore You need another patch. This patch introduces new mgetty option nodevsleep; default is no, if set to yes, mgetty will continuously trying to open() tty when ENODEV || ENOENT || ENXIO is returned.

Think about IP address assingnment for You Palm. If You have only one routable IP address and it's occupied with Linux host, then masquerading is Your friend (CONFIG_IP_MASQUERADE=y). Compile and install all mentioned software components and kernel modules. Mgetty must be compiled with -DAUTO_PPP in CFLAGS.

Turn on IP forwarding:

echo 1 > /proc/sys/net/ipv4/ip_forward.

#/etc/mgetty+sendfax/mgetty.config
port ttyUSB1
        debug 3
        direct yes
        nodevsleep yes
        modem-type data
        toggle-dtr no
        blocking yes
        ignore-carrier yes

#/etc/mgetty+sendfax/login.config
/AutoPPP/   -   -   /usr/sbin/pppd auth login +pap -chap
*   -   -   /bin/login @

for pppd
/etc/ppp/options.ttyUSB1
local
lock
crtscts
nodetach
asyncmap 00000000
:192.168.10.20
ms-dns 192.168.10.1
ms-dns 192.168.10.2
proxyarp

Add inittab entry:

us1:235:respawn:/sbin/mgetty ttyUSB1

Configure network connection in Your Palm:

• run Prefs application;
• select Network in upper right combobox;
• enter something descriptive in Service: item;
• fill User Name: and Password: with values suitable for authorization of PPP link; You can use self username or create separate account especially for Your Palm;
• select Cable/Cradle in Connection: combo.
• tap Details;
• select PPP in Connection type: combo;
• check Query DNS and IP Address Automatic boxes;
• tap Script: button and make empty script, containing only End line.

Tap Connect. If all things is correct then after sequential flashing Initializing -> Signing on -> Established, Connect button will be replaced with Disconnect.

Ping Palm from host. RTT must be around 10ms (as for HomePNA) for USB connection.

If something are wrong, add debug to pppd options file and raise debug level for mgetty (for example debug 8) and see logfiles.
Now You can browse WCA, refresh AvantGo channels and send/receive e-mail via MultiMail, or even syncing with Windows Palm Desktop somewhere in network (or, for example, inside VMWare box at same Linux host).

4.2. Seamless switching between coldsyncing and networking without tweaking /etc/inittab.

init q

Tweak login.config:

#/etc/mgetty/login.config
/AutoPPP/   -   -   /usr/sbin/pppd auth login +pap -chap
/HotSync/   -   -   /usr/local/bin/coldsync -l/syslog/coldsync.log -tserial -Psimple -md -
*   -   -   /bin/login @

Now mgetty will "automagically" detect type of Palm connection and execute appropriate daemon: coldsync or pppd. For pppd it exec'ed new process as usually, for coldsync, it stays alive, forks itself and feed datastream to/from child (coldsync really) via anonymous duplex pipe (socketpair).

Addtional information about daemon mode (21-Feb-2002) for people using a post-sync (dump) conduits.
Dump conduits will not work under coldsync running over socketpair pipe as STDIN, unless You apply modified patch mentioned above. After coldsync closes device (STDIN in this case), pipe() call founds a least numbered filedescriptor 0 and uses it for one of handles in pipe pair. This [by some strange reason] clashes with socketpair, which used to feed data stream from mgetty to coldsync and still alive at this time.

5. References and Thanks.

• To all Linux kernel community for Linux - one of most features-rich and reliable Unix-like OSes.
• To Andrew Arensburger and coldsync people for cool Coldsync package.
• To Gert Doering and all Mgetty people for Mgetty+Sendfax package.
• To Palm Computing for my favorite PDA Palm m505.

6. Author.