Whole document tree
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
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
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.
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
Settings Tab
Alarms Tab
Conduits Tab
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.