J-Pilot User Manual

To compile J-Pilot you need to have GTK+1.2 or later installed.  You can find out what version you have by running "gtk-config --version".  GTK+ requires glib.  The glib version probably should match the gtk version.  You can also do a "glib-config --version".  You can get these at http://www.gtk.org

Pilot link must be installed and working.  What I mean by working is that you can use pilot-xfer, memos, or some other pilot-link program.

Here is a visor USB howto I found: Handspring Visor and J-Pilot guide
The HOWTO is also relevant for the clie devices.

The pilot-link code and other helpful info can be found at http://www.pilot-link.org/

If you are installing pilot-link from RPMs make sure that you also have the pilot-link-dev rpm installed for the header files so that J-Pilot can compile.

Compiling

To compile and install do the following:
./configure --prefix=/usr
make
make install
jpilot
./configure --help will list all the options available.

make uninstall is also an option, however I do not recommend using this ;)

I have included a spec file so if you want to create your own RPM all you have to do is "rpm -tb jpilot-0.99.2.tar.gz"

J-Pilot was written in such a way that it should be very safe to sync.  There is always the possibility of something going wrong though.  As with anything else, backup your data if you cannot afford to lose it.  Just make sure your backup software doesn't destroy it first.

Serial Port Setup

When syncing, J-Pilot uses the port and speed settings out of the J-Pilot preferences screen.  If the port is blank then J-Pilot will use the PILOTPORT environment variables, as does pilot-link.  If these are blank also then J-Pilot will default to /dev/pilot.

It is recommended, but not necessary to make a link from /dev/pilot to the correct serial port.  So, if your cradle is on COM1, this is /dev/ttyS0 under Linux.  You could execute the command

ln -s /dev/ttyS0 /dev/pilot

COM2 is /dev/ttyS1, and so on.  The Linux serial ports cua[n] are going away.  You should use the ttyS[n] ports instead.  USB ports are usually /dev/ttyUSB1, or /dev/usb/tts/1 (for devfs), but some devices use /dev/ttyUSB0, or /dev/usb/tts/0. 

You must also give non-root users permissions to access the serial port.  The command to do this is (as root)

chmod 666 /dev/ttyS0

for the first serial port, ttyS1, for the second, and so on.

Color Files

Make install will copy a few default color files to /usr/local/share/jpilot/ (unless you told configure to use another prefix).  These will be selectable from the preferences menu.  Also J-Pilot will look in $HOME/.jpilot/ for colors files.  They must start with "jpilotrc".  If you want to add new ones, or modify the current ones, just put the files in one of these directories and they will show up in the preferences menu.

If you create your own cool jpilotrc files feel free to send them back to me and if I like it, I'll include it in the release.

Use of the JPILOT_HOME environment variable

J-Pilot uses the JPILOT_HOME environment variable to make it easy to allow multiple pilots to be synced under the same user.  Just set JPILOT_HOME to the directory you want J-Pilot to use.  Be sure to export it also. For example, I have 2 palm pilots.  I can sync the one I use all the time into /home/judd.  The other one I can sync into /home/judd/palm2 by using this script:

#!/bin/bash
export JPILOT_HOME=/home/judd/palm2
jpilot

This is also handy for syncing xcopilot or pose into its own directory.

Oops, Reverting

You can always make the databases revert back to the last time that the pilot was synced.  All you have to do is

rm ~/.jpilot/*.pc

or

rm ~/.jpilot/*.pc3

for version 0.99 and above. 
Deleted records will come back, modified records will be un-modified, etc.  Nothing is permanent until the sync/backup.  You can do this if you make a mistake, or just to play around with J-Pilot and then delete the changed records without syncing them.  For example if you want to restore the addresses to their last sync state you can remove ~/.jpilot/AddressDB.pc.

Also, from the preferences menu, you can choose to show deleted records and then click on the deleted record and use "Copy" to get a copy of it back.

Using J-Pilot

Datebook Application

Viewing Records

You can browse through days on the calendar for the current month by pressing the days. 

*Hint*To go back to today's date, just hit the datebook application button again.  The application buttons are the 4 large buttons with pictures on them on the left hand side of the screen.

*Hint* Page up and Page down keys also work for scrolling through the days. 
The Home key takes you back to "today". 

Deleting a Record

To delete a record, just highlight the record and hit the delete button on the right side of the screen.

Adding a New Record

To add a new record, first press the "New Record" button on the upper right hand side of the screen.  Then fill in all of the details of the appointment and then press the "Add Record" button.  New records will show up in a different color.  Once they are synced they will be the same color as existing appointments.

Modifying a Record

To modify a record click on the record in the daily schedule, change the details of the record, and then press the "Apply Changes" button.

Address Application

Viewing Records

On the left side of the screen there is a list of addresses.  These can be viewed by category from the menu above them.  They will appear in the same order as on the Palm Pilot.  You can resort them by clicking the "Name/Company" heading.nbsp;

Quick Find

Just type in the quickfind box the first few letters of the record that you are looking for and the display will incrementally jump to the first matching record.

Deleting a Record

To delete a record, just highlight the record and hit the delete button on the right side of the screen.

Adding a New Record

To add a new record, first press the "New Record" button on the upper right hand side of the screen.  Then fill in all of the details of the address and then press "Add Record".  New records will show up in a different color.  Once they are synced they will be the same color as existing appointments.

Modifying a Record

To modify a record, change the details of the address and then press the "Apply Changes" button.

ToDo Application

Viewing Records

On the left side of the screen there is a list of todos.  These can be viewed by category from the menu above them.  They will appear in the same order as on the Palm Pilot.  If you want change this, you must change it on the Palm Pilot under the menu in the todo program and then sync and switch to another application and back.  You may also check the "Hide Completed ToDos" button if you don't want to see completed todos.

Deleting a Record

To delete a record, just highlight the record and hit the delete button on the right side of the screen.

Adding a New Record

To add a new record, Press the "New Record" button in the upper right hand corner of the window.  Then fill in all of the details of the todo record and then press "Add Record".  New records will show up in a different color.  Once they are synced they will be the same color as existing records.

Modifying a Record

To modify a record select the record, change the details of the todo and then press the "Apply Changes" button.

Also, todo items can be checked, or unchecked by clicking in the checkmark box.

Memo Application

Viewing Records

On the left side of the screen there is a list of memos.  These can be viewed by category from the menu above them.  They are sorted alphabetically. 

Deleting a Record

To delete a record, just highlight the record and hit the delete button on the right side of the screen.

Adding a New Record

To add a new record, Press the "New Record" button in the upper right hand corner of the window.  Then fill in all of the details of the memo record and then press "Add Record".  New records will show up in a different color.  Once they are synced they will be the same color as existing records.

Modifying a Record

To modify a record select the record, change the details of the memo and then press the "Apply Changes" button.

Expense Application Plugin

This is an example plugin application

I've written the expense application mostly for an example of a plugin and a proof of concept.  The User Interface is pretty much the same as the other applications so I am not going to waste time being any more repetitive. 

SyncTime Plugin

This is another plugin that comes with J-Pilot

It is a GUI-less plugin.  It will do something during the sync process, however, it does not have a GUI interface. 

During the sync process it will set the time on the Palm to the same time as on the desktop host computer.  It should be accurate plus or minus 1 second.  Palm OS 3.3 is broken and this plugin will crash a Palm running OS 3.3 during the sync.  It auto detects the OS and should not do anything during a sync to Palm OS 3.3, so it should not hurt anything to have it enabled. 

Searching

Search allows you to search for strings that may appear in records.  Just type the search string into the "Search for" entry and hit enter.  The "Case Sensitive" checkbox can be clicked for a case sensitive search.  A list of found strings will be listed in the window.  Just click on these records and the J-Pilot main window will go to the application and the record that matches the one that was selected.

Installing files to the Palm Pilot

The files entered here will be installed during the next sync.  J-Pilot just keeps a pointer to the file, not a copy, so you shouldn't move the file, or delete it until after a sync.  Just browse through the directory structure and select the files you are wishing to install.  You can either double-click on them, or press the "Add" button after they are selected.  They will show up in the "Files to be installed" window.  You can always remove them from the "Files to be installed" window by selecting them and pressing the "Remove" button.  When you are done press the "Done" button.

Preferences screen

Locale Tab

• Choose the character set for internationalization.
• Choose the localization for the short dates field.
• Choose the localization for the long dates field.
• Choose the localization of the time field.
• Choose the first day of the week.
• Hint Some displays will flicker with every change of the clock, so you may not want the clock updating every second.  In this case, choose one of the time settings without seconds.  Then the time will update every minute.

Settings Tab

• Select a GTK colors file.  J-Pilot must be restarted for this change to take effect.
• Set the serial port.  If this is empty, then the environment variable PILOTPORT will be used.  If PILOTPORT is not set then the default of /dev/pilot is used.
• Set the serial rate.  Some computers will not sync reliably above 9600.  I am not sure why this is.
• Set the number of backup copies to keep.  Everytime a backup is made it will go into a new backup directory of ~/.jpilot/backupMMDDhhmm where MM is the month, DD is the day and hhmm is the time.  Backups over the number to be kept will be deleted.
• Set "show deleted records".  Having this box checked means that deleted records will still be displayed as a different color.  This can be confusing at times.
• Set "show modified deleted records".  Having this box checked means that when a record is modified the original record will still be displayed as a different color.  This can be very confusing at times.
• Set "Highlight calendar days with appointments".  Having this box checked will make the datebook application highlight the calendar days that have appointments occurring on that day.  This option will slow down the application noticeably on slower computers depending on the number of records in the datebook.
• Set "Use DateBk3/4 note tags".  DateBk3 and DateBk4 is a rewrite of the Palm Datebook with added features.  Some of them are implemented in J-Pilot and will be used if this button is checked. 

Alarms Tab

• Check "Open alarm windows for appointment reminders" to have J-Pilot open a window when an alarm occurs. 
• Check "Execute this command" to have J-Pilot open a window when an alarm occurs.  Enter in the command to be executed when an alarm occurs.  This has the potential to be dangerous if an unwanted command is executed.

Conduits Tab

• Check which conduits you want to be executed during the sync process. 

Quit

To quit the program, use the quit button, or quit from the menu.  You should not quit the program by killing its window.  This causes a harsh death and the cleanup routines will not be executed.

Sync

The sync button will sync four the main applications and any plugins that are installed.

If you get warnings about the palm having a different userID or a different username than the pilot that was last synced:

Every palm has a username and userid.  These can be set by using install-user from the pilot-link set of tools.  If you changed the name or ID and it is the same palm then you can go ahead and safely sync.  If it is truly a different palm then you can still sync, just beware that any records pending modify/delete, etc. will try to be modified in the new palm.  You can always remove the .pc3 files to prevent these.  You can have multiple palms under the same user by using the JPILOT_HOME envirenment variable.

If you get warnings about the palm having a NULL userID:

J-Pilot cannot sync with this palm because it looks as though it has been hard-reset.  If it has been hard-reset (cleared) DO NOT sync it unless you want to lose data.  You should use pilot-xfer to restore the palm and then once the data is restored use install-user to create a username/ID on the palm and then sync. 

If your palm has not been reset, but maybe just has always had a NULL userID because you never used the Windows or Mac desktop, then good for you!  Just use install-user to add a username/ID and sync away.  i.e.: install-user bob 1234
You can type install-user on the command line for instructions. 

J-Pilot Sync Daemon

I've included an additional sync program called jpilot-sync.  It does not need j-pilot running in order to sync from the command line, or a script, so it can be handy for network syncs, or logging into a machine remotely.

Backup

This will sync the main applications and any plugins that are installed and then do a backup of all databases and programs.  It will only backup changed files, so the first time it will take a while.  Subsequent backups will be a lot quicker.

Restoring a Palm Pilot

This is not part of J-Pilot.  J-Pilot stores its files in $HOME/.jpilot/ and $HOME/.jpilot/backupMMDDhhmm.  A symbolic link of backup will be made to the most recent backup for convenience.  To restore a palm pilot that has lost its data you can use the pilot-xfer program that comes with pilot-link.  The easiest way to do this is to put every file that you want installed (or restored) back on the palm pilot in one directory.  For this example, a directory called backup.  Then you can execute "pilot-xfer -r backup".  Do not install applications that are already in ROM on the palm pilot, such as the Address.prc, etc. You probably shouldn't install "Saved Preferences.prc" to a palm pilot that it didn't come from since this can throw off the screen calibration and make it very hard to re-calibrate.

Do not try to use j-pilot to sync data back into a reset palm pilot.  It will overwrite the data on the desktop with the empty palm pilot files.  This may change in a later release.

Plugins

Plugins are shared libraries.  They should end with a ".so" suffix.  They should be placed in the ~/.jpilot/plugins/ directory, or [BASEDIR]/lib/jpilot/plugins/  directory, where BASEDIR is the directory that J-Pilot was installed under.  The source compiled default is /usr/local/ and the RPM default is /usr/.  The BASEDIR can be changed during the build by "configure --prefix=/this_dir/", etc.  Once the plugin is there it will automatically appear in the J-Pilot menu.  If it doesn't, then that probably means that J-Pilot was installed incorrectly, or the plugin isn't compatible.

Feedback/Contributions

I always like to here feedback from users.  Sometimes I get a little busy with email and my paying job, but I should always respond.
If you want to contribute some code just email me and tell me what you want to do, or have already done, etc.  I may like it, and I may not.  You are always free to do what you want to with the source code.
If you really want to give me something for my effort in putting together this program.  You can send me a little donation.  I collect coins from anywhere, anytime also.

Judd Montgomery
P.O. Box 665
Sunbury, OH 43074

Q:  Why is it called J-Pilot?  It is not written in Java.

A:  Originally I wrote this program for myself and my wife to use.  The J was for Judd or Jacki.  Not much thought was put into this.  Then, out of the goodness of my heart (ughh), I wanted to release it under the GPL.  I asked around for some better names, but I didn't come up with one.  gtkpilot would be more appropriate, but I hate typing gtk.

Q:  Why do you give it away for free?

A:  1. Because I can.  2. World Domination.
I would like to see Linux, become the dominate desktop both in the workplace and at home.  This is one of my contributions to help make it happen.  The more people that use Linux at home, the more I benefit from the hardware support and commercial software that will become available.  The more Linux/Unix is used in the office, the more pleasant my job becomes.  If I drove cars for a living, I'd rather be driving Ferraris and Corvettes around than Chevettes and Yugos.

Q:  Are you going to Gnome-ify it, or KDE-ify it?

A:  I don't run KDE, or Gnome, and at this point I don't even know what it would take to do this.  If someone else wants to do this, that is ok.  My only requirement is that KDE, or Gnome isn't required to run J-Pilot.  I take pride in the fact that Linux/Unix has many window managers available to use.

Q:  How do I cut-and-paste?

A:  Cut is ctrl-x, copy is ctrl-c and paste is ctrl-v.