How to synchronize the GPE PIM applications with a Linux desktop computer

This page describes how to use OpenSync to synchronize PIM data (contact, calendar, etc) between the Archos 5/7 running OpenAOS Angstrom and a Linux desktop PIM, over a WiFi connection. It describes KDEPim in particular, but any desktop PIM supported by OpenSync should work. I believe there is support in OpenSync even for remote calendars such as Google's, but I haven't tried this. I'm also describing the desktop side of things for Fedora, but it shouldn't be much different for other Linux distributions.

Note:
Until it's set up properly, this process is incredibly flakey. It seems OK when it's settled down, but there are particular problems when copying large amounts of data from the desktop to the device. In the end I found it necessary to create a new KDEPim database and copy the old data over a few entries at a time, synchronizing periodically. This was a bit of a drag, to put it mildly. I am using OpenSync version 0.36, and it's just possible that some of these quirks are fixed in a later version.

There are additional problems caused by the fact that WiFi almost certainly uses dynamic IP configuration (e.g., DHCP). OpenSync will need an IP number, and there doesn't seem to be an easy way to change it when the Archos unit's IP changes -- you'll need to edit the OpenSync config file. If your desktop uses DHCP as well, then you've got a double problem, because the A5 needs to be configured to allow sync access by IP number. OpenSync should be able to connect to the A5/7 using ssh to start up the A5 end of the sync process, but this did not work at all for me. Fortunately there is a panel applet to start the GPE sync server, so at least you won't need to do it from the prompt :)

Initial setup

1. Install your desktop PIM if you haven't already

For example

# yum install kdepim

2. Install the OpenSync framework and command-line tool

# yum install msynctool

There are graphical interfaces for OpenSync, but I've found that the command line is uncomplicated enough.

3. Install OpenSync plugins for GPE and for whatever desktop PIM you have

yum install libopensync-plugin-gpe
yum install libopensync-plugin-kdepim

4. Install OpenSync plugins for the data exchange formats you need

For KDEPim and GPE that amounts to vcard, vcalendar, etc

# yum install libopensync-plugin-vformat

5. Create sync pair and configure

You don't need to do this as root. In fact, in most cases you'll need to do it as the user that will be running the desktop app. Otherwise the OpenSync plugin won't be able to find the data.

% msynctool --addgroup gpe-kdepim

gpe-kdepim is an arbitrary name, used to refer to the config later. Add the GPE end of the pair:

% msynctool --add member gpe-kdepim gpe-sync

Add the desktop end of the pair:

% msynctool --add member gpe-kdepim kdepim-sync

Configure the GPE end. This is where it gets a bit tricky.

% msynctool --configure gpe-kdepim 1

This will bring up our old friend vi for you to edit the configuration file. There are a lot of comments to start with, which makes it look more ugly than it needs to be. After editing, my config file looks like this:

<?xml version="1.0"?>
<config>
  <remote>
    <handheld_ip>192.168.1.101</handheld_ip>
    <handheld_port>6446</handheld_port>
  </remote>
</config>

Note the IP number and port in this file :/ If this is the first sync pair you've created, this file will end up at

%HOME/.opensync/group1/1/gpe-sync.conf

That's what you'll have to edit when your A5's WiFi interface gets a new IP number. To configure the desktop end:

% msynctool --configure gpe-kdepim 2

In fact, the KDEPim sync plugin does not require any configuration.

6. Configure GPE to allow sync access from your desktop

From the GPE user account, edit the file

$HOME/.gpe/gpesyncd.allow

and add the IP number of the desktop. You could add the whole DHCP range here if your desktop uses DHCP, and save reconfiguration later. If you skip this step, you'll just get 'Connection refused' in the next step.

7. Discover object types

The sync server needs to be running on the A5 to do this step, and there needs to be a network connection, probably WiFi. For information on setting up WiFi [wiki:ImprovedAngstromWifi click here]. To start the sync server from the GUI, tap-and-hold the bottom panel on the screen, select 'Add' then add 'Sync Applet'. Pop up the sync applet and check the box that says 'Enable sync access'. When it's running, do this:

% msynctool --discover gpe-kdepim 1

In fact, because the GPE sync plugin was written in the days before glibc was fussy about memory allocation bugs in our code, you might find that the plugin generates a segfault. In practice I had to do this, to make glibc less fussy:

% MALLOC_CHECK_=0 msynctool --discover gpe-kdepim 1

Sigh. Happily this is, or should be, a one-time operation. You'll also need to do the discover operation on the desktop end of the sync pair. For KDEPim nothing specific needs to be running.

% MALLOC_CHECK_=0 msynctool --discover gpe-kdepim 2

And you should be ready to go.

How to sync

If the previous steps were successful, then sync should be straightforward. 1. Check the IP numbers are still correct, if you're using DHCP. If they're not, you'll need to edit the OpenSync config file on the desktop side, and/or the gpesync.allow file on the A5/7. 2. Run the sync

% msynctool --sync gpe-kdepim

Gotchas

The Sync Applet panel applet does not really indicate whether the sync server is running. It just display a tick in the box if it thinks it started it. When everything is running properly the tick in the box is a reasonable indication that the server is running, but when setting up it may be better to run

% gpesync -d

From the terminal. Note that this server needs to run as the GPE user, not as root.

I had better results syncing with KDEPim shut down on the desktop
The sync process can fail if the data in KDEPim cannot be converted into valid vcard/vcalendar entries. A particular problem is missing name fields in KDEPim
Synchronization of contact and calendar information seems to work properly in both directions. To-do entries only seem to travel from the desktop to the A5, and not the other way around. I don't know if there is a good reason for that, or if it's just a bug