• intro
• news
• security
• contribute
• development
• history
• hardware
• faq

KPilot FAQ

This is the FAQ page for KPilot. It also has the troubleshooting guide and some tips for configuring your system to support your PalmOS handheld device. The pilot-link site also has similar troubleshooting guides. If you can't find what you're looking for there either, mail us for help at kdepim-users or join the IRC channel #kpilot on irc.kde.org.

About KPilot

1. Who produces KPilot?

   KPilot is produced by an international distributed team; the composition of the team varies per season. Right now it's mainly Adriaan ([ade]), Jason (vanRijn), and Bertjan (bbroeksema).

2. Where can I get more help?

   There's the mailing list for KPilot (and other KDE PIM applications) at kdepim-users@kde.org ; it's generally best to send mail to the list since there's the greatest number of eyeballs to see your question. You can send messages to kdepim-users without being subscribed, but any answers to your questions may only be sent to the list. It's a good idea to subscribe. See the KDE lists page for more details, Alternatively, there is the IRC channel #kpilot on irc.kde.org ; someone from the KPilot team is generally idle on the channel, but it can take quite some time to get a response (jobs and babies are prime sources of distraction). A third source of information, but not help, about KPilot is the KPilot section of [ade]'s blog.

Device Issues

1. KPilot doesn't find my device. Now what?

   Getting a device working with KPilot is a three-stage process. These steps are:

   1. Get the kernel to recognize the device
   2. Get the pilot-link tools to recognize the device (optional)
   3. Get KPilot to recognize the device

   Step 2 is optional because you may not have the pilot-link tools -- KPilot includes its own copy, and has its own little test tools.

   Getting the kernel to recognize the device is very OS (and perhaps distro-) specific. For FreeBSD, you need to load the uvisor kernel module.

2. How do I get /dev/pilot to point to the right device?

   With USB devices, the device name assigned to the handheld during a HotSync may vary -- for instance, it might be /dev/ttyUSB0 one time, and /dev/ttyUSB2 the next. This is very inconvenient, since you can only configure KPilot to watch one device at a time. The solution is to use your OS to automatically create a correct link to the device. How you do this depends on your OS.

   • FreeBSD: In /etc/rc.conf, make sure that usbd(8) is enabled with a line usbd_enable="YES", and then add the following section to /etc/usbd.conf (near the bottom, just above the fallthrough entry; lines wrapped for clarity.):

     device "PalmOS"
     devname "ucom[0-9]+"
     attach "chmod 666 /dev/${DEVNAME} ; 
             rm -f /dev/pilot ; 
             ln -s /dev/${DEVNAME} /dev/pilot"
     detach "rm -f /dev/pilot"
     

     In previous versions of FreeBSD, the handheld got device names like ucom0 but this has changed to ttyU0 in recent releases.
   • SuSE 10.0 (perhaps other Linuxes): Create a file /etc/udev/rules.d/10-custom.rules and include the line (wrapped for clarity -- it should be a single line):

     KERNEL="ttyUSB*", 
       NAME="%k", 
       SYMLINK="pilot", 
       GROUP="uucp", 
       MODE="0666"
     	 

3. What Linux kernel should I use?

   Some versions of the Linux kernel do better with USB devices -- PalmOS devices in particular -- than others. 2.6.15 has been reported to cause difficulties in Kubuntu, while 2.6.17 is just fine.

4. What FreeBSD kernel should I use?

   KPilot is developed on FreeBSD 6-STABLE on an amd64, most of the time. So use 6-STABLE, that is easiest. You will need the following settings:

   1. device uvisor (for instance, add uvisor_load="YES" to the file /boot/loader.conf)
   2. devfs rules to allow you to read and write to the device for the handheld. The following works for me in /etc/devfs.rules:

      [localrules=10]
      add path 'ttyU*' mode 0660 group operator

   3. usbd rules to set up the link from /dev/pilot to the device created when the HotSync starts (optional). See the FAQ entry above for details.

Technical

1. Where does KPilot store its data?

   All of the data KPilot saves from your Pilot goes into directories underneath the KDE configuration directory. This is often .kde/ in your home directory, but may be some different value. Check the value of the environment variable $KDEHOME for a hint.

   Underneath $KDEHOME, you will find share/apps/kpilot. In there, there should be two directories: pending_install which stores the files you want to store on your Pilot at next HotSync, and a directory DBBackup. Under DBBackup you will find a directory named after your user name on the Pilot, and in there you'll find the database files from your Pilot.

   I recommend making backups of the DBBackup directory regularly. You never know.

2. What information do you need to report a problem?

   You should collect the following items. If an item has a red asterisk ("*") in front of it, it's strictly necessary. Items that start with something in square brackets ("[]") have a default assumption. For example, I'm going to assume people are using x86 hardware until the world becomes a better place.

   • [x86] Your hardware platform (x86, PPC, SPARC, etc.). If you aren't sure, it's a safe bet that it's x86.
   • * Your operating system (AIX, FreeBSD, Linux, Solaris, etc.)
   • The distribution of the operating system, if relevant (for example, there's only one Solaris, but Linux could be Red Hat, Mandriva, Ubuntu, etc.)
   • The version of your operating system and kernel (especially relevant for a this-week's-kernel type OS). The output of the command uname -a will provide this information for AIX, FreeBSD, Linux, Solaris and other POSIX-compliant systems.
   • * The model of Palm OS device you're using.
   • [USB] What kind of connection you're using to the KDE machine (IrDA [infrared], USB, serial, network, Bluetooth).
   • [Qt 3.2.4] The version of Qt installed on your system.
   • [KDE 3.4.2] The version of KDE installed on your system.
   • [0.11.8] The version of pilot-link installed on your system.
   • * The top of the HotSync log from KPilot, where it says what it thinks are the answers to the previous three questions and what its own version is. It should look something like this:

     Version: KPilot 4.5.4 (dreumes)
     Version: pilot-link 0.11.8
     Version: KDE 3.4.2
     Version: Qt 3.3.4

   It's been said lots of times, but it can be said again: more information is usually a good thing. Provide all the details you can. In particular, if the sync is hanging somewhere, you might send in a debug log as well.

3. Where do I get the KPilot source?

   See the development pages.

4. How do I compile KPilot?

   See the development pages.

5. How do I create a "debug log"?

   OK, first of all you're going to need a KPilot that is compiled with debugging support.

   Most of the packaged binaries do not have debugging compiled in. When KPilot is compiled with debugging, it will print gobs of debugging information to stderr or the KDE debug stream.

   Now, with KPilot ready for debugging, start a konsole window and run KPilot and the daemon in it:

   $ kpilotDaemon > /tmp/daemon.log 2>&1
   $ kpilot > /tmp/kpilot.log 2>&1

   There! You now have a (probably large) debug log, showing all the function calls in KPilot and lots of other information. You should check that there's nothing particularly sensitive in the log if you're going to send it off. It contains the names of your address contacts and the titles of your memos -- you may not want those to leak out. Don't send debug logs to the list. Send them to me privately, possibly.

HotSync Issues

1. I have a problem with HotSync.

   Please make sure you have a debugging-enabled version of KPilot; keep a debug log. Read the FAQ. Post a question to the kdepim-users@kde.org mailing list. Or file a bug with bugs.kde.org.

2. Kontact conduits -- addressbook, datebook, todo -- keep failing.

   Check that there are no stale lockfiles lying around for the default resource. You can check this inside Kontact by trying to add an entry -- address, appointment or todo -- to the\ default resource.

3. /dev/ttyUSB* is there but kpilot doesn't seem to be able to connect to it.

   Are you affected?

   Firstly, make sure kpilot is configured to connect to the odd numbered device (ie: ttyUSB1 and not ttyUSB0). If that is not the issue, you might have one of these Palm Pilots that creates a device even if the hotsync button is not pressed on the hand held device. Here is how you can identify if you have such a device (follow these steps precisely in this order):

   1. Start kpilot
   2. In a terminal window, type in the following command:

       $ watch 'dmesg | grep ttyUSB tail'

      NOTE: if the watch command isn't recognized, here is an alternative syntax (a little messier)
      

      $ while : ; do dmesg | grep ttyUSB | tail;sleep 1; clear; done

   3. Plug in the Hand held device, you should now see something like this in the terminal window:
      

      usb 4-1: Handspring Visor / Palm OS converter now attached to ttyUSB0
      usb 4-1: Handspring Visor / Palm OS converter now attached to ttyUSB1

   4. Press the hotsync button on the Hand held device. If you see ttyUSB2 and ttyUSB3 appear in the terminal window, this FAQ entry applies to you. The output looks like this:

      usb 4-1: Handspring Visor / Palm OS converter now attached to ttyUSB0
      usb 4-1: Handspring Visor / Palm OS converter now attached to ttyUSB1
      *usb 4-1: Handspring Visor / Palm OS converter now attached to ttyUSB2
      usb 4-1: Handspring Visor / Palm OS converter now attached to ttyUSB3*

   5. Close kpilotDaemon (the taskbar icon usually at the lower right of your screen). If you look in the console window, you should notice that the kernel now thinks the "first" device has been unplugged:

      usb 4-1: Handspring Visor / Palm OS converter now attached to ttyUSB0
      usb 4-1: Handspring Visor / Palm OS converter now attached to ttyUSB1
      usb 4-1: Handspring Visor / Palm OS converter now attached to ttyUSB2
      usb 4-1: Handspring Visor / Palm OS converter now attached to ttyUSB3
      visor ttyUSB0: Handspring Visor / Palm OS converter now disconnected from ttyUSB0
      visor ttyUSB1: Handspring Visor / Palm OS converter now disconnected from ttyUSB1

   6. You can now cancel the terminal program by pressing CTRL-C.
   The workaround:

   The following sequence is the only way to get kpilot to sync with your palm:

   1. Plug in the Hand held device,
   2. Press the Hand held device's HotSync button,
   3. Start kpilot, it will automatically start the sync with the handheld so make sure the default startup sync action is the one you desire,
   4. Once the sync is done, close kpilot entirely (don't foget kiplotDaemon in the taskbar if your kpilot is not configured to close it on quit).

   We thank Eric Thibodeau for writing this faq item!

The KPilot site is valid XHTML most of the time. The CSS for the site is tested with recent versions of Konqueror. I know that IE has a lot of trouble doing the right thing with this site - provide patches if you feel it is important.

The content of this website is copyright by Adriaan de Groot, 2004-2006. Redistribution in whole or in part is prohibited except for fair-use; license is granted to KDE e.V. to distribute this content provided this notice remains.