%ents; ]> Dan Pilone

pilone@slac.com

Adriaan de Groot

adridg@cs.kun.nl

1999 2000 Adriaan de Groot &FDLNotice; 9/12/2000 4.0.0 &kpilot; 4.0.0 is the KDE version of the Desktop HotSync software for the &ThreeCom; &PalmPilot; and similar products. KDE KPilot kdepim palm pilot synchronisation &kpilot; 4.0.0 is the latest version of the Desktop HotSync software for &UNIX;. After several releases and many contributions from users &kpilot;, along with &korganizer;, has evolved into a rather complete replacement for the &Windows; Desktop provided by &ThreeCom;. &kpilot; offers a few internal tools for viewing and manipulating data, and a convenient API for developing ways of sharing data with other applications. &kpilot; supports the &ThreeCom; &PalmPilot; and similar devices, like the Handspring Visor. There is a web page for &kpilot;: the Official &kpilot; Home Page . There is also a mailing list. Send mail to majordomo@slac.com with the following subject: subscribe kpilot-list. (To unsubscribe from the list again, send mail to majordomo@slac.com with the following subject: unsubscribe kpilot-list. Do not send subscribe or unsubscribe requests to the list itself.) You may also wish to use kde-pim@kde.org for more general questions about the integration between your &PalmPilot; and KDE. A word about version numbers: &kpilot; 3.x versions are for KDE 1. With the release of KDE 2 &kpilot; 3.x is obsolete and &kpilot; 4.x has become current. 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. The most important visible new features are: There is a new &knotes; conduit that synchronizes the memo pad with &knotes;. More intuitive conduit installation and setup. The documentation has been brought mostly up-to-date. 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. The documentation for &kpilot; -- in english only -- has been vastly expanded. 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;. The &GUI; has been improved and some issues with various OS distributions have been dealt with. See the buglist for more information. 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 new features are: Now supports debugging output, just start &kpilot; by hand from the command line with kpilot --debug 1023 and you will get loads of debugging output. Useful for reporting bugs. See the FAQ for information on the parameter to --debug. Addresses can be sorted by company, name or by lastname, firstname. A new (demonstration) conduit has been added that does nothing. For programmers, mostly. The &GUI; has been cleaned up. The most important bugs that have been fixed are: SMTP support Daemon startup Note that the debugging code hasn't spread to the whole of &kpilot; yet. The daemon and conduits do have some debugging output, which may also be useful if &kpilot; doesn't work perfectly on your system. 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. 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 synchronise your &PalmPilot; with your KDE desktop or view data from your &PalmPilot; with the builtin applications. Once &kpilot; is installed it is rather easy to set up. Run &kpilot; from either the panel menu or from the command prompt and it will prompt you with a dialog box asking you to configure it for the first time. This configuration dialog can be requested later from the File Settings menu or by starting &kpilot; from the shell as follows: $ kpilot --setup In addition, if you upgrade &kpilot; and some new configuration options require your attention, this setup dialog will reappear. A full description of the setup dialog can be found below. Once &kpilot; is properly set up, pressing OK will bring up the main &kpilot; window. The first thing you should do is make a full backup of the &PalmPilot;. Do this by selecting File Backup or the toolbar icon Full Backup . When you do, the status bar will ask you to press the HotSync button on the cradle. Assuming everything is set up properly you should see the &PalmPilot; begin to sync and a message box telling you what databases are being backed up. This will back up your entire &PalmPilot; into your local directory. Note that this may take a little while, however a normal HotSync is significantly faster. 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. General page The General setup page The General setup page Pilot Device This is the serial port that the cradle is connected to. By default it is set to /dev/pilot which should be a symbolic link to the proper serial port. Make sure the serial 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 serial port. See also the FAQ for more information about setting up the &PalmPilot; device. Speed This indicates the speed of the serial connection to the &PalmPilot;. 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. Pilot User This is the user name of the &PalmPilot;. By default this name is the same as your log on name. When you first 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. This is also used to store the information synced from the &PalmPilot;. For example, if I were to HotSync my &PalmPilot; on your machine, it would store the data into a subdirectory named pilone. Start HotSync Daemon at login 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. Start KPilot at HotSync When the HotSync button is pressed on the cradle (assuming the daemon is running) &kpilot; can sync without actually starting up the &GUI;. However, by enabling this option the daemon will start up the &kpilot; &GUI; when the HotSync begins. Show Daemon in KPanel This option lets the daemon place a little HotSync icon in the KPanel. This icon has a menu that can be brought up with the right mouse button, for performing a HotSync and the like. Without this option, the daemon is not visible to the user at all. Stop Daemon on exit Setting this option will cause the daemon to exit when you quit &kpilot;, leaving the serial port free for other &PalmPilot;-syncing tools such as malsync For a fully visible &kpilot; installation, enable Start KPilot at HotSync and Show Daemon in KPanel while disabling Stop Daemon on exit. To make &kpilot; all but invisible, disable all the options except Stop Daemon on exit. The address page contains settings specific to the built in address book. Note that this address book has nothing directly to do with the KDE address book, your email address book, or anything else. Connections with those address books could be provided by conduits. (Right now there is no conduit for the address book, though.) Address page The Address setup page The Address setup page Import Format Export Format &kpilot; can import and export the address database to or from a text file. These two fields determine the format the file is written in (for export) or must have (for import). Address display This set of radio buttons determines how addresses are displayed and sorted in the address book. This is similar to the setting in the &PalmPilot; itself where addresses can be sorted based on company or on last name. Both the import and the export format are lists of field specifiers separated by some delimiter (usually a comma). Note that all fields must be separated by the same delimiter. For import formats: Field specifiers are three-character strings that begin with a %. Field specifiers %CC are used to indicate that in the imported data the data for the corresponding field is to be found there (as a string that does not contain the delimiter character). The following field specifiers are supported: SpecifierField%LNLast name %FNFirst name %COCompany %P1,%P2,%P3,%P4,%P5Phone numbers 1 through 5 %ADAddress %CICity %STState %ZIZip (Postal code) %CTCountry %TITitle %C1,%C2,%C3,%C4Custom fields This page contains settings specific to the &PalmPilot; databases &kpilot; works with. DB Specials page The DB Setup page The DB Setup page Show secrets 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. Backup only 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). Skip This text field lists databases that should not be backed up nor synced, in the same format as the backup only field. The sync page contains preferences relevant to the HotSync operation on your &PalmPilot;. Sync page The Sync page The Sync page Sync Files 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. Local overrides Pilot 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. Force first-time sync every time 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. Do full backup when changing PCs If you have more than one PC and synchronise 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. Prefer FastSync to HotSync While a HotSync is faster than a full backup, a FastSync is faster still than a HotSync and synchronises only those databases that have conduits. This means that any database without a conduit is not backed up and not synchronised. 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. The main window in &kpilot; just contains the &kpilot; logo. You can switch to one of the builtin applications by using the drop-down list on the toolbar. &kpilot; Main Window The Main Window The Main Window The main window contains the application menu, which we will deal with here. File Settings Brings up the configuration dialog for &kpilot;. File HotSync Starts a HotSync. You should press the HotSync button on your &PalmPilot;'s cradle. Note: it is not possible to cancel a HotSync once the request has been made. File FastSync (not available with all installations) Starts a FastSync in the same way that a HotSync is started. File Backup Performs a full backup of your &PalmPilot;. This is like a HotSync, but can take several minutes. File Restore 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! File Quit Quits &kpilot;, closing the main window and stopping the daemon if that configuration option is enabled. Conduits External Configures the external conduits. This is explained below. Conduits : The remainder of the Conduits menu lists the builtin applications, just like the drop-down box in the toolbar does. Select one of these applications to switch to it. The builtin applications can be selected in two ways: either by selecting the application from the Conduits menu, for example Conduits Memo , or by selecting the application from the drop-down list in &kpilot;'s toolbar. &kpilot; Toolbar The &kpilot; Toolbar The &kpilot; Toolbar 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. Memo Application The Memo Application 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 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 &URL;s from &konqueror;! Also, if you are using the HotSync Daemon you may drag and drop files or &URL;s 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 The File Installer The File Installer Conduits can be external programs, written by third parties, to interface your &PalmPilot; to any application imaginable. Conduits can be set up by selecting Conduits External . 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 The Conduit Setup Dialog The Conduit Setup Dialog You can drag-and-drop conduits between the two branches of the tree (from Available to Active and back again). Only those conduits listed under Active will actually run during a HotSync. This conduit allows you to send and receive email. The configuration of the Mail Conduit is fairly complex. Setting up the Mail Conduit The Mail Conduit Setup Dialog The Mail Conduit Conduit Setup Dialog There are two tabs in the setup dialog for the Mail Conduit, one for Sending mail and one for Receiving mail. Setting up the Mail Conduit Choosing the Send Method Choosing the Send Method Setting up the Mail Conduit Choosing the Receive Method Choosing the Receive Method 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 directory) and whether or not to ask before changing data in that calendar file. The Calendar Conduit Setup Dialog Calendar Conduit Setup 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 &knotes; Conduit Setup &knotes; Conduit Setup The NULL conduit is included as a programming example and has no practical function whatsoever. 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: ValueMeaning1List the name of *every* function called. Very tedious. 2Major &GUI; operations (e.g. Creating windows). 4Minor &GUI; operations (e.g. Adding visual elements). 8All &GUI; operations (e.g. Filling list boxes -- this is very tedious). 16Major database operations. 32Minor database operations. 64All database operations. 128Major sync actions. 256Minor sync actions. 512All sync actions. Just add up the numbers of the kind of messages you want. &kpilot; says Can't connect to pilot This can have various causes. Check that: The pilot device (usually /dev/pilot) exists and points to the serial port the &PalmPilot; is actually connected to. To link the &PalmPilot; device to the correct serial port, you can either fill in /dev/ttySn in the Pilot Device field in the setup dialog or (preferably) link /dev/pilot to /dev/ttySn with the following command (as root): ln -s /dev/ttySn /dev/pilot Here /dev/ttySn is the name of the serial port; replace n with the correct number (usually 0 or 1). Check that you have permission to read and write to the serial port. The permissions for the serial port should be such that you can write to it. This is most easily done by running the following (as root): chmod 666 /dev/ttySn Try starting the daemon by hand before starting &kpilot;. (For Mandrake 7 systems) Check the system security level: settings higher than 3 prevent some forms of inter-process communication which are necessary for &kpilot; to operate correctly. (Mandrake security information courtesy of Jay Summett) To set your MSEC (Mandrake SECurity) settings to not block the &kpilot; socket (for connections to localhost) you can login as root and type /etc/security/msec/init.sh 3 Which will set your MSEC level to 3 (regular security). For more information about the various security levels, etc, see: the Mandrake reference guide. This section answers questions commonly asked about particular databases and how they interact with &kpilot;. 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: DatabaseCreator IDAction Launcher (the &PalmPilot;'s main menu) lnch Backup Only Arranger Arng Backup Only (unknown) PmDB Backup Only AvantGo avgo Skip (Mostly because there's no point in backing up the news articles that AvantGo gives you) 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. This section lists questions about HotSync methods that differ from the usual direct serial link method. 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: PalmOS 3.3 and higher include support for it; there is an IR enhancements package for older PalmOS 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 RedHat systems, the following command should setup IR support (as root): # modprobe ircomm Other 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/ircomm0 Next we need to start some daemons for IR services: # irattach /dev/ttySn # irmanager -d 0 Here /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! 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. Is there any support for remote HotSyncs? No, not yet. Maybe later. &kpilot; Program copyright 1998-2000 by Dan Pilone pilone@slac.com Contributors: Adriaan de Groot adridg@cs.kun.nl Preston Brown pbrown@redhat.com Conduits by: Herwin Jan Steehouwer, Kenneth Albanowski, Michael Kropfberger Patches by: Robert Ambrose, Scott Presnell, Dag Nygren, Chuck Robey, Jay Summet, Heiko Purnhagen, Jörg Habenicht Documentation copyright 2000 Adriaan de Groot adridg@cs.kun.nl &underFDL; &underGPL;