By Thomas DeWeese; Currently maintained by Aaron Kaplan

SourceForge Logo

    This is a synchronization conduit between Palm Inc.'s Palm Pilot Address application and The Insidious Big Brother Data Base (BBDB), an address manager for Emacs (and XEmacs).  It is easiest to use with PilotManager (see reasons) however it can be used in a standalone manner.


    For the impatient: SyncBBDB-2.6.tgz

What you need:

  1. Palm Pilot (I'm guessing you have this already or this 'free software' is about to get expensive :)
  2. BBDB version 2.2 (see BBDB versions)
  3. PilotManager (I am currently using version 1.108)
  4. Perl 5 (I'm not a Perl version weenie, but I think anything greater than 5.004 will work)

Development Information

Development has moved to SourceForge. This means you can access the code at

Example command lines (empty password for anonymous access):
cvs login
cvs -z3 checkout dev

What you get:
PilotManager conduit for syncing with your palm.
A no frills Perl script for syncing BBDB with Address book (doesn't require PilotManager).  More a proof of concept than a finished entity.
SyncBBDB (Perl package)
The package that does all the work for bootstrap and  This is where most of the code lives.
BBDB (Perl package)
A set of Perl objects for reading and manipulating your BBDB database (supports BBDB version 2.00.06, 2.1 & 2.2).
This is a generally useful thing for people who know Perl but don't have a clue about e-lisp.
It can also be useful for cleaning up a corrupted BBDB (you may lose a few records but the uncorrupted records should come through fine).
SyncUtil (Perl package)
A set of Perl objects that offer a framework for writing Pilot Conduits.
This offers two major advantages over 'rolling your own'.  First it knows how to deal with both fast and full synch.  Second it makes it fairly easy to build your conduit so it runs under PilotManager or standalone (actually it should be possible to write a small front end for virtually any synch manager).

Reasons to use a Synchronization Manager

    As someone who virtually lives in Emacs I felt I should give some comment to the decision to write the Palm Pilot synchronization tool for an Emacs package in something other than e-lisp. 

First you should understand that synchronization generally takes two forms, first is a slow (or more the more 'PC' term 'full') synch.  During a slow synch the entire contents of a database are transferred to the host computer and the contents are compared with the contents as of the last sync any records that are different are considered modified on the palm.  In many instances this is the only form of synchronization implemented by conduit writers (at least in the Unix domain).  The second type of synch is called a 'fast sync'  A fast synch is done when the conduit can determine that the last synch was with this host.  In this case the host can request that the Palm Pilot send it just the new/modified/deleted records. 

This is usually the difference between a synch that takes a few seconds at most and a synch that can take a minute or more.  If you have several different syncing systems (one for calendar, one for address, one for mail etc.) you will always be doing slow synchs, which is a real bummer.  If you unify them all under one manager then you can usually do fast synchs (This was one of the major motivators behind my build the SyncUtil Package, to help encourage people to support both slow and fast synch).

Second it was clear to me that synchronizing with your Pilot should be a one stop shopping experience, otherwise you are likely to forget certain conduits or the whole process becomes such a pain that you don't do it regularly.  Both of which are a disaster waiting to happen.

The big downside is that complex customization that is normally done with e-lisp in Emacs packages needs to be done by users in Perl (not very likely), or provided through a user interface or configuration files. Which is generally significantly more work and less flexible.

More information about pilot-link

Many people have missed the way that you build the Perl binding for pilot-link. After you have built and installed the pilot-link package normally (configure; make; make install). You need to build the Perl binding. This is done by going to the bindings/Perl subdirectory, and building the Perl package as one normally builds a Perl package (perl Makefile.PL; make; make install).

BBDB Version info

BBDB Version Description
Works, not recommended
Doesn't support 'duplicate records'.  Duplicate records can happen two ways, first if you happen to know two people with the same name (say John Smith).  Second if you happen to modify the same record on the Pilot and in BBDB it will duplicate the record so that both sets of modifications are preserved.  It is then an excercise for the owner to merge the changes intelligently (in other words delete one of them :).
2.1 Supported This introduces BBDB file format 4 (adds country to Address record, implies possible existence of duplicate records).
2.2 Supported
(formats 5 & 6)
Depending on when you got BBDB 2.2 it may be using file format 5 or file format 6 (The switch happened on 11/27/2000). Versions of SyncBBDB starting at 2.3 should support both. SyncBBDB 1.2 through 2.2 will not support file format 6.

History of SyncBBDB versions:

Version 2.6

    Fix bug: when a bbdb record was split into multiple pilot records, changes to the notes field on the pilot weren't being propagated correctly. Bug reported by Alex Lancaster.

    Update installation instructions and contact info in README.

    Change the way we reference constants exported from libpisock, for compatibility with pilot-link 0.12.0. Backwards compatibility is maintained.

    In log, display company name if first and last names are empty.

    Patch from David Goldberg: for empty name or company, use nil instead of "". With "", it becomes an "unfield" which bbdb won't let you edit.

Version 2.5

    Aaron Kaplan takes over maintenance of SyncBBDB.

    Fixed major bug: if connection is dropped during sync, entries can be erroneously deleted. You could lose your whole address book this way!

    Bring "bootstrap" up to date so that it works again.

    More fixes for non-ASCII characters, although you may still have problems depending on the combination of encodings used on your Palm and your desktop.

Version 2.4

    It once again deletes records in BBDB when deleted on Pilot.

    Only sets first name, last name and company on pilot if a value was given on the pilot (minor issue really).

Version 2.3

    Added support for bbdb file format version 6

    Incorperated a fix for bbdb files containing Non-ASCII chars. Contributed by Aaron Kaplan, thanks!.

    Now updates timestamp, and creates creation-date as appropriate.

Version 2.2

    This adds support for a 'pilot-ignore' note in BBDB. When present on a record, SyncBBDB will ignore the record for purposes of synching (it will remove it from the Palm if it had previously been synched to the Palm).

    Will now properly create a 'net' field in bbdb when the first e-mail is entered on the palm.

    Fixed category handling so records won't go back to 'Unfiled' after being modified on the Palm.

    Now properly parses the SyncBBDB 'control' file when the pre/post sync scripts are empty.

    Now works with an empty or non-existent BBDB file (nice for first time users who are building the bbdb file from the palm).

    (see the ChangeLog in distribution for a few more details).

Version 2.1

    This fixes an apparent problem with fast/slow sync detection. While I haven't seen an issue here, I did receive a bug report. Even if what I was doing wasn't wrong it was different from all the other conduits so I decided to switch methods to be more consistent.

Version 2.0

    This has a few mostly cosmetic improvements over 2.0b3. The startup code is more automatic for first time users. Now provides better feedback while loading the bbdb file. Does a better job of protecting against time-outs while running startup/shutdown scripts.
    If you have used 1.x versions of SyncBBDB please read the README it has directions on the "best" way to upgrade. If you do nothing special things should still work ok, but you won't obtain the full benefits of 2.0.

Version 2.0b3 (BETA for 2.0)

    In the process of investigating the 1.3 inherited address bug I tried the same sequence on 2.0b2.
    This turned up two major problems:

  1. New Pilot records with an address weren't properly created in BBDB.
  2. Pilot field labels can be invalid BBDB note labels. The conduit now fixes these labels.
    From #2 also became clear that it was important to quote the fields in the Pilot<->BBDB mapping (BBDB phone and address locations can both include spaces for example). So I modified the Pilot<->BBDB mapping code to quote these items (for now it will also accept the unquoted versions for read, see the README for details).

Version 2.0b2 (BETA for 2.0)

    As of today (8/2/00) I have been using versions closely related to this as my main conduit for a few days. But this is not for the faint of heart. Please use caution if you decide to use this version.
    The details of the changes can be found in the README.
    Brief overview:
      1) Manages a Pilot record for each Address in a BBDB record.
      2) Customizable mapping between BBDB and Pilot fields.
    If you use this version please let me know how it goes.

Version 1.5

Bug fix for Version 1.4.

This includes the 'bbdb' package from the 2.0 branch instead of the 1.3 branch version. This fixes a number of minor problems with the rewriting of the bbdb file (see the README for more details).

This is likely to be the last release in the 1.X branch as it demonstrates that at least parts of the 2.0 branch are more capable.

Version 1.4

Bug fix for Version 1.3.

New records on the Pilot that did not have an address would inherit the address from the next new Pilot record that did have an address. This was apparently due to the code not properly detecting empty address records. How this would lead to the address inheritance I don't know. But this also avoids the creation of 'empty' addresses in BBDB so I guess it's still 'a good thing'.

Version 1.3

Bug fix for Version 1.2. Due to changes made to support International zip codes, a US zip+4 entered on the palm would lead to an invalid zip code entry in BBDB (it wouldn't split at the dash, but would still write it like it was a number).

Version 1.2

First version that had acceptable support for International Zips and Phones.
   This version also added support for BBDB file format 5 (which supports BBDB 2.2).

Version 1.1

Short lived version that tended to generate illegal zips for all US zip codes.

Version 1.0

Initial public release.


I would like to thank John Straw who has sent several very useful bug reports. In particular he took the time to put together a very nice and concise demonstration of the bug in version 1.2. He clearly uses SyncBBDB differently than I do :).

I wanted to thank Kevin Davidson. He provided a steady stream of patches for international phone and zip support as well as example BBDB version 5 parsing code, all of which formed the majority of the changes between 1.0 and 1.2.

Contact Info

For questions or comments regarding SyncBBDB, use the PilotManager contact information.
If you are using BBDB you might also subscribe to the bbdb-info mailing list.