J-Pilot User Manual
J-Pilot is a palm pilot desktop for Linux/Unix written by:
Judd Montgomery, judd@engineer.com, http://jpilot.org
J-Pilot has been reported to work on:
-
Linux
-
Solaris
-
HP-UX
-
Irix
-
FreeBSD
-
PowerPC
HP-UX
J-Pilot should work with Palm Pilot models 1000, 5000, Personal, Professional,
all III models, IIIc, V, VII, All Visors, Sonys, pretty much any Palm OS
device.
01 Feb 2002:
Palm OS versions greater than 4.0 cannot have the password set on the
handheld. This will be fixed in a later version.
USB Palms (m series) and Sony Clies will work, but require
pilot-link 0.10.1 or greater, which is still unreleased at the time of this
writing. J-Pilot will autodetect the newer version of pilot-link and
build appropriately.
Updates
This document was last updated 03 Feb 2002, for J-Pilot-0.99.2.
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)
pilot-link > 0.10.1 for Palm OS 4.x USB and Sony USB handhelds.
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.;nbsp
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
~/.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
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.