J-Pilot User Manual


J-Pilot is a palm pilot desktop for Linux/Unix written by:
Judd Montgomery, judd@engineer.com, http://jpilot.linuxbox.com
J-Pilot has been reported to work on:

J-Pilot should work with Palm Pilot models 1000, 5000, Personal, Professional, III, IIIx, IIIe, V, and VII.

Purpose of this document

Many things in this document are pretty much self explanatory, like a lot of the text on how to use J-Pilot.  I have written this document for a user as well as someone who is thinking about being a user and wants to know the capabilities of J-Pilot before much time is wasted downloading and compiling it, etc.  In the using J-Pilot section, I have marked some things with "*Hint*" that I think may not be right away obvious to a new user.  If you are in a hurry, just read these.

Installation

Prerequisites

  • GTK+, and glib (installed by default on most Linux distributions)
  • pilot-link (comes with many distributions)

    •  

     

    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.

    David Silber has some pretty good documentation for using Palm Pilots with Linux at http://www.orbits.com/Palm/.

    The pilot-link code can be found at ftp://ryeham.ee.ryerson.ca/pub/PalmOS/

    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
    make
    make install
    jpilot

    For Japanese support, use ./configure --with-japanese.
    ./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.96.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.

    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 HOME environment variable

    Normally, you can just leave HOME alone.

    J-Pilot uses the HOME environment variable to make it easy to allow multiple pilots to be synced under the same user.  Just set HOME to the directory you want J-Pilot to use.  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
    HOME=/home/judd/palm2
    jpilot

    This is also handy for syncing xcopilot 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".  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 "Add" 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.  There are 4 arrows on top of the calendar.  The inner arrows will go backwards 1 month at a time, or forward one month at a time.  The outside arrows will scroll the calendar by a year at a time.

    *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.

    Deleting a Record

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

    Adding a New Record

    To add a new record, first press the "clear" 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 It" 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.  If you want change this, you must change it on the Palm Pilot under the menu in the address program and then sync and switch to another application and back.

    *Hint* You may also browse through the records in a more detailed view.  To do this press the "Add or Modify Record" button and then choose the records from the left side of the window.

    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 left side of the screen.

    Adding a New Record

    To add a new record, first press the "Add or Modify Record" button on the upper right hand side of the screen.  Press "Clear".  Then fill in all of the details of the address and then press "Add It".  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, first press the "Add or Modify Record" button on the upper right hand side of the screen.  Then 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 left side of the screen.

    Adding a New Record

    To add a new record, Press the "Clear" 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 It".  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 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 memo program and then sync and switch to another application and back.

    Deleting a Record

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

    Adding a New Record

    To add a new record, Press the "Clear" 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 It".  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.

    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


     
  • Choose the localization for the abbreviated dates feild.
  • Choose the localization for the long dates field.
  • Choose the localization of the time field.
  • *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.
  • Choose the first day of the week.  The next time the calendar is re-drawn it will use the this day of the week to start the week on.
  • 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.

    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 .pc 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.

    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]/share/jpilot/plugins/  directory, where BASEDIR is the directory that J-Pilot was installed under (default is /usr/local/).  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

    FAQ
    (Frequently Asked Questions)

    Q:  Why is it called J-Pilot?  Its 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.