| KPilot User's Guide |
| Next |
Copyright © 1999, 2000, 2001, 2002, 2003 Adriaan de Groot
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".
KPilot 4.4.0 is the KDE version of the Desktop HotSync® software for the 3Com® PalmPilot™ and similar products.
Table of Contents
| Introduction |
| Prev | Next |
KPilot 4.4.0 is an application that synchronizes your PalmPilot™ or similar device (like the Handspring™ Visor™ or the Sony® Clie™) with your KDE desktop, much like the Palm Desktop HotSync® software does for Windows®. KPilot can back-up, restore, and HotSync® your PalmPilot™. It can synchronize the built-in applications with their KDE counterparts. It also features additional conduits for third-party software.
There is a web page for KPilot: the Official KPilot Home Page . The KDE-PIM website also offers useful information on the subject of PIM in general. KPilot shares the kde-pim mailing list, <kde-pim@kde.org>. See the mailing lists page for more information on subscribing and unsubscribing from the list.
A word about version numbers: KPilot 4.4.0 is current and unstable as of July 2003. It works with both KDE 3.0 and KDE 3.1, though its functionality may be limited with KDE 3.0. Some conduits have been updated to required KDE 3.2, and these conduits will not be installed under older KDE versions.
This document still reflects KPilot version 4.2.2. The descriptions may be inaccurate and the screenshots misleading. Updated documentation will be released after the KDE 3.0 release.
New in 4.4.0 - The configuration dialogs for both conduits and KPilot's general settings have been rearranged again. Conduits have been renamed. The popmail and expenses conduits have been removed, since they just weren't working. For users of KPilot 4.3.x versions, both Kroupware syncing and file installation have been moved into the conduit configuration. A dialog will open up warning you of the transition.
New in 4.3.0 - a new architecture, USB support, and possibly a VCal (KOrganizer) conduit that isn't dead slow.
New in 4.2.2 - Many compilation and portability fixes were applied. Those changes do not affect the visible appearance of KPilot. What has changed is the GUI. We now use the KDE 2 XML GUI. This means that menu names have changed again but we feel it should be obvious where things have ended up. This has the advantage that you can now easily customize the toolbar and that the KPilot user interface behaves more like the rest of KDE 2. Tool tips (also called balloon help) have finally been added.
New in 4.0.0 - KPilot is now a KDE 2 application. A lot of work has gone into making the main KPilot application compatible with the new KDE 2 standards. The stability of the program as a whole has improved as well, with lots of bugfixes under the hood.
New in 3.2.1 - more bugfixes. KPilot 3.2.1 is also the last version of KPilot for KDE 1. Development on the 3.x series has stopped.
New in 3.2.0 - KPilot has been polished sufficiently for a new public release. The infamous application-category bug has been squashed along with other bugs.
New in 3.1.14 - New configuration options Backup Only: and Skip have been added to avoid database corruption for some Handbase databases — and possibly other products as well.
New in 3.1.13 - You can now HotSync - experimentally - with UNIX® style mailboxes. The popmail conduit will read a standard mailbox and copy it to the PalmPilot™.
New in 3.1.12 - This release of KPilot has only been tested with KDE 1.0, 1.1 and 1.1.1. Previous versions of KDE are no longer supported. KPilot 3.1.12 has a number of new features compared to 3.1b9. It also includes a large number of bug fixes. The most important feature is that KPilot now supports debugging output.
New in 3.1.9 - This is the fourth release of KPilot. The major change in this release is conduit support. There are currently two included conduits, a KOrganizer conduit (vcal syncing) and a PopMail conduit (this fixes the email bug with KPilot 2.1). Also fixed in this release is the Address/Memo “off by one” bug. This release requires KDE Beta 4 or better.
| Trademarks |
| Prev | Introduction | Next |
KPilot describes synchronization operations with Palm OS® devices, and it uses the word HotSync® to name those synchronization operations, while recognizing that HotSync® is a trademark of Palm, Inc. Holders of other trademarks, such as Handspring™ Visor™, Sony® Clie™, and the Palm, Inc. trademarks PalmPilot™ and Zire™ are recognized as well.
| Prev | Home | Next |
| Introduction | Up | Using KPilot |
| Prev | Home | Next |
| KPilot User's Guide | Up | Trademarks |
| Using KPilot |
| Prev | Next |
Once KPilot is installed it needs to be configured to match your hardware. The conduits need to be configured as well. After that you can use KPilot to synchronize your PalmPilot™ with your KDE desktop or view data from your PalmPilot™ with the builtin applications.
When you run KPilot from either the panel menu or from the command prompt for the first time it will prompt you with a dialog box to configure it. This configuration dialog can be requested later from the Settings->Configure KPilot menu or by starting KPilot from the shell as follows:
$ kpilot --setupIn addition, if you upgrade KPilot and some new configuration options require your attention, this setup dialog will reappear.
In KPilot 4.4.0, the way conduits are programmed changed, and you will need to use newly compiled conduits. If there are old conduits on your system, KPilot will prompt you to remove them.
The way file installation and Kroupware are enabled has changed. They have been moved to conduits; your settings will be preserved, and KPilot will warn you.
The names of encodings have changed as well. If you enabled encodings for KPilot by editing the configuration file, you will need to re-select your encoding from the configuration dialog. KPilot will not warn you about this.
Please take the time to review all of the configuration settings.
The configuration tabs
The general configuration dialog for KPilot has five tabs, as shown above. Each is described in detail below. The General tab sets device options. The Sync tab sets HotSync® specific options. The Viewers tab sets display options for the builtin viewers. Backup sets special treatment for certain databases. Finally, the About tab describes the KPilot application and its authors. Every configuration dialog in KPilot has an About tab listing the authors of that particular part.
This is a setup page that contains options describing the PalmPilot™ hardware, you, the user and how you want the various parts of KPilot to be started.
The General setup page
This is the port that the cradle is connected to. By default it is set to /dev/pilot which should be a symbolic link to the real port. The port might be a serial port, in which case /dev/pilot should point to something like /dev/cuaa0 (in FreeBSD) or /dev/ttyS0 (in Linux®). For USB devices, it can be more difficult to determine where /dev/pilot should point. It may be possible to configure your USB daemon to set up the link automatically, so that /dev/pilot points to the right port no matter where you plug in your Palm OS® device.
Make sure the port has the correct permissions. It must be read/write by all if KPilot is intended to be used by a normal user! This is done by doing a chmod 666 device where device is the correct port. KPilot will complain if the permissions are wrong, but you will need to fix the permissions by hand.
This indicates the speed of the serial connection to the PalmPilot™. It has no meaning for USB devices. For an older model PalmPilot™, choose 9600. Newer models may be able to handle speeds up to the maximum listed, 115200. You can experiment with the connection speed: the PalmPilot™ manual suggests starting at a speed of 19200 and trying faster speeds to see if they work.
Palm OS® devices are available in many different languages. If your device uses a different encoding than ISO-latin1, you will need to select the correct encoding from the list in order to have KPilot display national characters correctly. If you can enter Russian in your PalmPilot™, select CP1251, for instance.
This is the user name of the PalmPilot™. By default this name is the same as your log on name. When you sync with the PalmPilot™ KPilot will check to see if this name matches the one on the PalmPilot™. If they do not, you are asked to pick which you will use. If you pick the local name, the PalmPilot™ will be changed to match. The Pilot User entry is also used to store the information synced from the PalmPilot™, in a folder named DBBackup/Pilot User.
By enabling this a link to the daemon is placed in your autostart folder and will be started automatically. Note that this is not normally needed if the daemon is docked in the panel.
This option instructs the daemon to place a HotSync® icon
HotSync icon
.
in
the Kicker system tray.
This icon has a menu that can be brought up with
the right mouse button.
Without this option, the daemon is not visible to the user at all.
Setting this option will cause the daemon to exit when you quit KPilot, leaving the device port free for other PalmPilot™-syncing tools such as malsync
When this option is enabled, both KPilot and the KPilot daemon will exit after the HotSync® operation has completed, leaving the device port free for other tools. This may be needed on systems where the USB daemon starts KPilot automatically.
This page contains settings specific to the PalmPilot™ databases KPilot works with.
The DB Setup page
In your PalmPilot™ you can mark some records as “private”. By default, KPilot does not display these records on the screen. If you want to see them, turn this option on.
This text field can be used to list databases that should not be synced, only backed up. Note that you have to fill in the database creator, not the name of the product, so for Handbase databases you fill in PmDB. Multiple databases should be separated by commas. See the FAQ for a list of databases that should be listed here (the default should be OK though).
This text field lists databases that should not be backed up nor synced, in the same format as the backup only field.
Changing the contents of the Backup Only: or Skip fields, in particular removing the databases already listed there, can damage those databases when you perform a HotSync®.
The sync page contains preferences relevant to the HotSync® operation on your PalmPilot™.
The Sync page
When this is enabled any files dropped into the file install (either the icon docked on the panel or into the file installer in KPilot) will be installed on the PalmPilot™ during the next HotSync.
When a record has been modified on both the PalmPilot™ and the local side, only one can be kept. By default KPilot assumes the PalmPilot™ has the most recent information and will keep that. By enabling this option KPilot assumes it has the most recent information and will overwrite the PalmPilot™'s copy.
Under some circumstances — you have many PCs and many PalmPilot™s — you may want to perform a "cleaner" HotSync every time instead of the "quick-and-dirty" HotSync that KPilot does if you just have one PalmPilot™ and one PC. Just when you want to enable this option is a matter of personal preference.
If you have more than one PC and synchronize your PalmPilot™ with each of them you may want to disable this option. When you change PCs it is a good idea to perform a full backup, since otherwise your KDE desktop will not reflect the state of your PalmPilot™ accurately. (This is a limitation of the PalmPilot™ itself.) On the other hand, performing a full backup can be time-consuming and annoying, which is why you can disable such a backup here.
While a HotSync is faster than a full backup, a FastSync is faster still than a HotSync and synchronizes only those databases that have conduits. This means that any database without a conduit is not backed up and not synchronized. This also means that if something goes wrong with your PalmPilot™, you may not be able to recover databases with no conduit. This is a classic trade-off between speed and safety.
| Main Window |
| Prev | Using KPilot | Next |
The main window in KPilot just contains the KPilot logo. You can switch to one of the builtin applications by using the View menu.
The Main Window
The main window contains the application menu, which we will deal with here.
Starts a HotSync®. You should press the HotSync button on your PalmPilot™'s cradle.
It is not possible to cancel a HotSync® once the request has been made.
(not available with all installations) Starts a FastSync in the same way that a HotSync® is started.
Performs a full backup of your PalmPilot™. This is like a HotSync®, but can take several minutes.
The first thing you should do after starting KPilot for the first time is make a full backup.
This copies all the data on your PC to your PalmPilot™, replacing whatever data was there. Use this if your PalmPilot™ suffers some catastrophe (or is replaced by a new one).
Doing a restore will erase all data on the PalmPilot™ before restoring the information from your PC!
Quits KPilot, closing the main window and stopping the daemon if that configuration option is enabled.
The View menu allows you to choose a database viewer or KPilot's main page.
Displays the KPilot logo page. This puts KPilot in the state shown in the picture above.
Displays the internal memo viewer. See below for more information on the memo viewer.
Displays the internal address book viewer. You can view and edit addresses with the address book viewer. See below for more information.
Displays the file installer. You can drag files onto the file installer to install them on your PalmPilot™. See below for more information.
| Prev | Home | Next |
| Using KPilot | Up | Builtin Applications |
| Builtin Applications |
| Prev | Using KPilot | Next |
The builtin applications can be selected : by selecting the application from the Conduits menu, for example Conduits->Memo.
Selecting one of the builtin applications will cause that application to appear in KPilot's main window. Any changes you make to the PalmPilot™ databases with the builtin applications (such as deleting a memo) do not take effect on the PalmPilot™ until the next HotSync.
The memo application allows you to view the memos on your PalmPilot™, export them to text files, import new ones to be installed the next time you HotSync®, or edit existing ones.
The Memo Application
The memo application has a drop-down box for the memo categories defined in the PalmPilot™. Here category "All" is selected. Underneath the drop-down box is a list of memo titles. These are the first lines of the memos, just like in the PalmPilot™ memo application. Clicking on one of the memo titles in the list box will display it in the text box labelled Memo Text: to the right.
When a memo is selected you can use the buttons Export Memo and Delete Memo to export the selected memo to a file or to delete the selected memo. Exporting a memo requires you to give a filename; the memo is written to that file. Take care not to overwrite existing files with this action. Deleting a memo does not affect the PalmPilot™ until the next HotSync®.
The Import Memo button allows you to read a text file and add it — as a memo — to the PalmPilot™. Importing a memo does not take effect until the next HotSync®. Note that if you import a memo and decide that you do not want to have it on the PalmPilot™ you must perform a HotSync® (copying the memo to the PalmPilot™) and then delete the memo from the PalmPilot™. It is not possible to delete newly-added memos from the builtin memo application.
The address viewer lets you view, import, export and edit addresses to and from the PalmPilot™. The import and export format is configurable via the settings dialog. Note that the first field in the import format is used as the Key Field. That is, if Use Key Field is turned on in the settings dialog, when importing if KPilot sees another record with a matching Key Field the existing record is updated to reflect the new data being read in. If no such record exists, a new record is created. The default is not to use the Key Field, so every record read in from the import file is created and added to the database.
The Address Application
The address application resembles the memo application; the drop-down box, list and text area function exactly the same, allowing you to select and view an address as on the PalmPilot™.
You can use the buttons to enter new records into the address book, delete addresses or changes addresses. The button Import List lets you read a text file containing records in comma-separated-value format (with the fields in the particular order described by the Address Import setting) and add those records to the address book. The Export List writes all the addresses in the address book to a file in the format given by the Address Export setting.
The file installer supports dragging and dropping of files into the file list area or just hit the Add File button to add a file if you are not. These files will be installed on your PalmPilot™ during the next HotSync® if Sync Files is checked in the settings dialog. If you choose not to install the files on the PalmPilot™, just hit Clear List to remove any pending files.
An internal copy of the file is kept, so you can even drag and drop URLs from Konqueror!
Also, if you are using the HotSync® Daemon you may drag and drop files or URLs onto the docked icon on the tool bar. Provided Sync Files is checked in the settings dialog they will be installed the next time you HotSync.
The File Installer
| Prev | Home | Next |
| Main Window | Up | Conduits |
| Conduits |
| Prev | Using KPilot | Next |
Conduits can be external programs, written by third parties, to interface your PalmPilot™ to any application imaginable.
Conduits can be set up by selecting Settings->Configure Conduits. This allows you to select which conduits to run during a HotSync® and to configure those conduits. A window similar to the following will be displayed:
The Conduit Setup Dialog
This conduit allows you to send and receive email. The configuration of the Mail Conduit is fairly complex.
The Mail Conduit Conduit Setup Dialog
Choosing the Send Method
Depending on which send method you choose, different fields will be activated in the remainder of the tab, allowing you to enter the necessary information.
General mail configuration: who are you?
Your email address can be entered in the Email Address field. This is the email address that goes in the “From:” line in outgoing mail. If you enter a file name in the Signature File field then that file will be appended to each outgoing mail as a signature.
sendmail® configuration
The configuration of the sendmail® method of sending is fairly straightforward. Check the path to your installation of sendmail®, for example by typing which sendmail in a Konsole window. The options to sendmail® should not need to be changed, but you can if you like.
sendmail® is not provided with destination addresses on the command line, so you must specify the -t. If you are using a non-sendmail® MTA like Postfix then the equivalent “extract recipients from message headers” option must be given.
SMTP setup
To use SMTP sending you need to specify the name of the machine which runs your SMTP server, and the port number to connect to. The default port number of 25 is almost always correct.
KPilot does not use the SMTP configuration of the SMTP IOSlave. This may change in a future version of KPilot.
KMail sending
When sending mail through KMail, KPilot automatically places it in your KMail outbox. KMail saves mail in the outbox until you request that those pieces of mail are really sent. Check the Send mail through KMail immediately to let the Mail Conduit tell KMail to send all mail from the outbox as soon as it it done HotSyncing. This has the side effect of also sending any other pieces of mail that may be in your outbox.
This conduit will synchronize your PalmPilot™ with KOrganizer. The conduit needs two pieces of information: the filename of the calendar file (this will usually be a file that ends in .vcs under .kde/share/apps/korganizer/ under your home folder) and whether or not to ask before changing data in that calendar file.
Calendar Conduit Setup
You can usually leave Prompt before changing data off.
This conduit synchronizes with KOrganizer's todo list. The configuration dialog looks exactly the same as the configuration dialog for the Calendar Conduit.
The KNotes Conduit is a partial replacement for the builtin memo application. It keeps the notes you write with KNotes synchronized with the memos you write on your PalmPilot™.
Setting up the KNotes conduit is very simple, since there is only one configuration option.
KNotes Conduit Setup
The KAddressBook conduit allows you to synchronize the PalmPilot™ address book with your KDE address book.
| Prev | Home | Next |
| Builtin Applications | Up | FAQ |
| Prev | Home | Next |
| Trademarks | Up | Main Window |
| FAQ |
| Prev | Next |
| 1. | What do I put after --debug? | ||||||||||||||||||||||
The number after --debug indicates what kind of messages you want to see; 1023 indicates all messages. The exact numbers you can use are as follows:
Just add up the numbers of the kind of messages you want. | |||||||||||||||||||||||
| 2. | KPilot says Can't connect to pilot | ||||||||||||||||||||||
This can have various causes. Check that:
|
| Database Questions |
| Prev | FAQ | Next |
This section answers questions commonly asked about particular databases and how they interact with KPilot.
| 1. | Databases become corrupted after a sync, what should I do? |
Certain databases (from third-party software manufacturers) appear not to follow the standard database layout. If you can find out what the creator id of the database is, you can add it to either the Backup Only: list or the Skip list in the settings dialog. The following table shows which databases should be skipped or backed-up only: | |
| 2. | Is there a conduit for Netscape® Calendar? |
No, there isn't. Neither are there plans to include support or write a conduit for Netscape® Calendar. |
| Prev | Home | Next |
| FAQ | Up | Special HotSync Questions |
| Special HotSync Questions |
| Prev | FAQ | Next |
This section lists questions about HotSync methods that differ from the “usual” direct serial link method.
| 1. | How do I do an infrared (IR) HotSync? |
First of all your PalmPilot™ has to actually support IR HotSyncs. This can be achieved through various means: Palm OS® 3.3 and higher include support for it; there is an IR enhancements package for older Palm OS® versions; IrLink from IsComplete apparently has the same capabilities. Check out the Palm web pages for more information. Assuming your PalmPilot™ now has PC HotSync support and it is setup to do IR HotSyncs (in the HotSync preferences on the PalmPilot™), we can turn our attention to the PC you will be syncing with. It needs an IR port. For laptops, this is trivial, desktop PCs may require some extra hardware. Your Linux® kernel will need to support IR and the IRCOMM protocol. For stock Red Hat® systems, the following command should setup IR support (as root): # modprobe ircommOther distributions should follow the IR-HOWTO. Once IR support in the kernel has been activated, you need to make devices for the IR ports. The IR-HOWTO suggests (as root): # mknod /dev/ircomm0 60 64 # chmod 666 /dev/ircomm0Next we need to start some daemons for IR services: # irattach /dev/ttySn # irmanager -d 0Here /dev/ttySn is the serial port the IR port is using. n could be 0, 1, or some other number depending on your hardware setup. Follow the instructions in the IR-HOWTO for assistance (for desktop machines, it's usually a setting in the BIOS). Once you've gotten this far, just make /dev/pilot point to /dev/ircomm0 and you're ready! The IR-HOWTO and other useful information on using IR may be found at http://mobilix.org/howtos.html and http://mobilix.org/software/irda/. | |
| 2. | Can I do a HotSync® with my (USB) Handspring™ Visor™? |
Yes, you can. I don't have definitive information, but postings on the KPilot mailing-list have stated that you can point /dev/pilot to the USB device and everything will work fine. | |
| 3. | Is there any support for remote HotSyncs? |
No, not yet. Maybe later. |
| Prev | Home | Next |
| Database Questions | Up | Credits and License |
| Prev | Home | Next |
| Conduits | Up | Database Questions |
| Credits and License |
| Prev |
KPilot Program copyright 1998-2000 by Dan Pilone <pilone@slac.com>
Contributors:
Adriaan de Groot <adridg@cs.kun.nl>
Preston Brown <pbrown@redhat.com>
VCal and Todo Conduits by: Herwin Jan Steehouwer, Kenneth Albanowski, Michael Kropfberger
Popmail Conduit overhaul: Marko Grönroos
KAddressBook Conduit: Greg Stern
Patches by: Robert Ambrose, Jörg Habenicht, Philipp Hullmann, Dag Nygren, Scott Presnell, Heiko Purnhagen, Chuck Robey and Jay Summet
Documentation copyright 2000,2001 Adriaan de Groot <adridg@cs.kun.nl>
This documentation is licensed under the terms of the GNU Free Documentation License.
This program is licensed under the terms of the GNU General Public License.
| Prev | Home | |
| Special HotSync Questions | Up |
| Next | ||
| Introduction |
