home *** CD-ROM | disk | FTP | other *** search
/ Freelog Special Edition 1: Linux / CD1.iso / doc / HOWTO / Pilot-HOWTO < prev    next >
Text File  |  1998-10-14  |  15KB  |  405 lines
  1.   Pilot HOWTO
  2.   by David H. Silber pilot@orbits.com
  3.   v0.5, 17 August 1997
  4.  
  5.   This HOWTO document explains how to use your Pilot with a linux sys¡
  6.   tem.  Although HOWTO documents are targeted towards use with the linux
  7.   operating system, this one is not dependent on the version of unix
  8.   used.
  9.  
  10.   1.  Introduction
  11.  
  12.   The Pilot comes with software to synchronize its memory with data on a
  13.   Microsoft Windows system.  There is optional software you can buy to
  14.   synchronize with an Apple Macintosh.  The linux/unix community has
  15.   been ignored by the manufacturers of the Pilot.  Fortunately, a suite
  16.   of free software has been developed to fill this need.  This document
  17.   describes this software, where to get it, and how to install and use
  18.   it.
  19.  
  20.   1.1.  This Document
  21.  
  22.   The latest version of this document can be read at
  23.   http://www.orbits.com/Pilot/Pilot-HOWTO.html, and is part of the Linux
  24.   Documentation Project (LDP).  See http://sunsite.unc.edu/LDP/ for
  25.   further information about the LDP and other HOWTO documents.
  26.  
  27.   Future versions will cover more unix tools for writing application
  28.   programs to run on the Pilot and conduits to transfer data between the
  29.   unix system and the Pilot.
  30.  
  31.   If you find anything in this document which needs to be corrected or
  32.   better explained, please send me e-mail at the address above and
  33.   specify which version of this document you are referring to.
  34.  
  35.   This document is Copyright ⌐ 1997 by David H. Silber.  It is released
  36.   under the copyright terms in the LDP HOWTO-INDEX document.
  37.  
  38.   1.2.  Mailing List
  39.  
  40.   The pilot-unix mailing list is maintained by Matthew Cravit
  41.   <mailto:pilot-unix-owner@lists.best.com>.  Its mandate is:
  42.  
  43.        The pilot-unix mailing list is for discussion and idea-sharing for those
  44.        interested in using the US Robotics Pilot PDAs with UNIX systems. This
  45.        includes people who are interested in helping to develop tools to allow the
  46.        Pilot to operate with UNIX, and possibly to develop an SDK for the Pilot
  47.        for Unix.
  48.  
  49.   For more information, including how to subscribe to the list, send
  50.   mail containing the word ``INFO'' to pilot-unix-
  51.   request@lists.best.com.  The subject line does not matter.
  52.  
  53.   1.3.  Mailing List Archives
  54.  
  55.   An archive of the pilot-unix mailing list can be found at
  56.   http:///www.acm.rpi.edu/~albert/pilot/.  It is maintained by Chris
  57.   Stevens <mailto:albert@acm.rpi.edu>.
  58.  
  59.   1.4.  FTP Site
  60.  
  61.   An FTP site containing an archive of Pilot tools for use on unix
  62.   systems is located at ftp://ryeham.ee.ryerson.ca/pub/PalmOS/.  It is
  63.   maintained by Jeff Dionne <mailto:jeff@ryeham.ee.ryerson.ca>.
  64.  
  65.   2.  General Information
  66.  
  67.   2.1.  What is a Pilot?
  68.  
  69.   The Pilot is a small pen-based Personal Digital Assistant (PDA).  It
  70.   is made by U. S. Robotics, now part of 3Com.
  71.  
  72.   For those of you unfamiliar with the term, a Personal Digital
  73.   Assistant is one of those small electronic devices which typically
  74.   contain various types of personal information, such as addresses and
  75.   telephone numbers, a calendar, checkbook registry, lists of reminders
  76.   and/or memos and is designed to be conveniently carried so as to be
  77.   handy when the information is needed.
  78.  
  79.   The more adaptable PDAs, such as the Pilot, allow for the data stored
  80.   on the PDA to be backed up to another computer and for data and new
  81.   programs to be loaded onto the PDA from another computer.
  82.  
  83.   2.2.  Different types of Pilots
  84.  
  85.   There are four versions of the Pilot.  The earlier two, the 1000 and
  86.   the 5000 have 128k and 512k of RAM, respectively.
  87.  
  88.   The more recent two, the PalmPilot Personal and the PalmPilot
  89.   Professional have 512k and 1 Meg of RAM, respectively.  They also have
  90.   a backlighting feature for the LCD panel and version 2.0 of the
  91.   operating system.  The Professional also comes with a TCP/IP stack and
  92.   a few extra programs built-in.
  93.  
  94.   It is possible to upgrade any Pilot by swapping out the memory card,
  95.   which includes both RAM & ROM.  Of course, this doesn't get you
  96.   backlighting for the older pilots.
  97.  
  98.   2.3.  Hardware Installation
  99.  
  100.   Pilots come with a ``cradle'' for exchanging data with the desktop
  101.   computer.  This device is actually a serial cable with a custom holder
  102.   for the Pilot end and a `HotSync' button.  Plug your cradle into a
  103.   spare serial port on your computer.  When you run each of the stand-
  104.   alone programs, you will need to place your Pilot in the cradle and
  105.   push the `HotSync' button so the Pilot knows that it has to
  106.   communicate.  If the Pilot happens to be off when the button is
  107.   pushed, it will turn itself on.
  108.  
  109.   For convenience, create a device, /dev/pilot which will be an
  110.   alternate name for the serial port to which your Pilot cradle is
  111.   connected.  As the root user, enter the following at the shell prompt:
  112.  
  113.        ln /dev/cua0 /dev/pilot
  114.  
  115.   Replace cua0 with the name of the port to which you connected your
  116.   Pilot's cradle.
  117.  
  118.   3.  Sharing Pilot Data with your Linux System
  119.  
  120.   3.1.  The pilot-link software
  121.  
  122.   The pilot-link suite of software tools allows you to download programs
  123.   onto your Pilot, and transfer data for the Pilot's various built-in
  124.   programs between the linux system and the Pilot.  While these programs
  125.   are not quite as seamless as the desktop software that comes with the
  126.   Pilot, they do allow you to copy your data in both directions.  In
  127.   general, each separate program in the pilot-link suite manages one
  128.   type of data.  The PilotManager software is built on top of pilot-link
  129.   and provides a more integrated solution, which typically includes full
  130.   synchronization of the various types of data.
  131.  
  132.   3.1.1.  Installing the pilot-link software
  133.  
  134.   The prepackaged versions will inevitably lag slightly behind the
  135.   master distribution, but will be easier to install and not require
  136.   configuration.  The master distribution might be a better choice in
  137.   those rare occasions when you have been waiting for a particular
  138.   feature or bug fix.
  139.  
  140.   You can get the Debian Linux port of pilot-link version 0.7.2 from
  141.   ftp://ftp.debian.org/pub/debian/hamm/hamm/binary-i386/otherosfs/pilot-
  142.   link_0.7.2-1.deb.  Install this file in the normal manner and skip to
  143.   Using the pilot-link software.
  144.  
  145.   You can get the RedHat Linux port of pilot-link version 0.7.6 from
  146.   ftp://ftp.redhat.com/pub/contrib/i386/pilot-link-0.7.6-2.i386.rpm.
  147.   Install this file in the normal manner and skip to Using the pilot-
  148.   link software.
  149.  
  150.   For other versions of linux or unix, download the version 0.8.2 of
  151.   pilot-link from ftp://ryeham.ee.ryerson.ca/pub/PalmOS/pilot-
  152.   link.0.8.2.tar.gz.  The version number is likely to change, but new
  153.   versions should end up in the same location with a similar name.
  154.  
  155.   Once you have the software distribution, unpack it with:
  156.  
  157.        tar -xvzf pilot-link.0.8.2.tar.gz
  158.  
  159.   This will create a directory (pilot-link.0.8.2) containing the source.
  160.  
  161.   Run ./configure.  This will search through your system for information
  162.   needed to compile the software.  configure will set things up to be
  163.   installed in /usr/local by default.  If you want to change it, run
  164.   ./configure --prefix=DIR, where DIR is replaced with the name of the
  165.   directory to which the software will be installed.
  166.  
  167.   Run make.  This will compile the software.  The software will not be
  168.   installed until later, so that you have a chance to try it out first.
  169.   (If you are replacing an older version with a newer release, you may
  170.   wish to check and make sure that no functionality that you need has
  171.   been broken.  Generally, this is not a problem.)
  172.  
  173.   As the root user, run make install.  This will copy the software into
  174.   directories under /usr/local (or wherever you specified with the
  175.   --prefix option).  If you can not log in as root, you can install the
  176.   software to some directory where you have write access.
  177.  
  178.   Don't forget to add any new directories of executables to your search
  179.   path.
  180.  
  181.   3.1.2.  Using the pilot-link software
  182.  
  183.   Most of the programs in the pilot-link suite are conduits, that is
  184.   they transfer data into or out of your Pilot.
  185.  
  186.   Each time you use of one of these programs, press the HotSync button
  187.   on your Pilot's cradle.  This will initiate the Pilot side of the data
  188.   transfer.  Note that not all of these programs prompt you to press the
  189.   `HotSync' button, so you may have to remember to do it yourself.
  190.  
  191.   For more details, and other options to these programs, view the
  192.   corresponding manual page.  For the pilot-xfer program, for example,
  193.   type man pilot-xfer at your unix shell prompt.
  194.  
  195.   If you are going to use PilotManager, you may not need to bother
  196.   learning to use these (more primitive) tools.
  197.  
  198.   3.1.2.1.  pilot-xfer
  199.  
  200.   Possibly the most useful program in the pilot-link suite, pilot-xfer
  201.   allows you to install programs on your Pilot, make a backup, and
  202.   restore that backup.
  203.  
  204.   To install a program:
  205.  
  206.        pilot-xfer /dev/pilot -i program.prc
  207.  
  208.   To backup your Pilot:
  209.  
  210.        pilot-xfer /dev/pilot -b backup-directory
  211.  
  212.   This will copy all of the databases on your Pilot, (including pro¡
  213.   grams?)  to a directory called ``backup-directory'', creating it if it
  214.   does not already exist.
  215.  
  216.   To restore data to Pilot:
  217.  
  218.        pilot-xfer /dev/pilot -r backup-directory
  219.  
  220.   Generally, you will only need to do this if your Pilot loses power or
  221.   if you have to do a hard reset.
  222.  
  223.   To list the programs on your Pilot:
  224.  
  225.        pilot-xfer /dev/pilot -l
  226.  
  227.   3.1.2.2.  install-memo
  228.  
  229.   Install a linux file onto the Pilot as a memo.
  230.  
  231.   To install a memo into your (already existing) project category:
  232.  
  233.        install-memo /dev/pilot -c project project.memo
  234.  
  235.   The name of the file will be inserted into the memo as its first line
  236.   and will appear in the directory of memos on your Pilot.
  237.  
  238.   3.1.2.3.  memos
  239.  
  240.   This program grabs each memo from the Pilot and prints it out in
  241.   standard mailbox format.
  242.  
  243.   To view your memos:
  244.  
  245.        memos /dev/pilot
  246.  
  247.   3.1.2.4.  pilot-addresses
  248.  
  249.   pilot-addresses Transfer the address database to or from the Pilot.
  250.  
  251.   To write your address data to a linux file from your Pilot:
  252.  
  253.        pilot-addresses /dev/pilot -w storage.file
  254.  
  255.   To read your address data from a linux file onto your Pilot:
  256.  
  257.   pilot-addresses /dev/pilot -r storage.file
  258.  
  259.   3.2.  MakeDoc
  260.  
  261.   One short-coming of the Pilot's built-in memo program is that it does
  262.   not deal well with large documents.  To compensate for this, Rick Bram
  263.   <mailto:rbram@concentric.net> wrote Doc, a document reader for the
  264.   Pilot.  (See http://www.concentric.net/~rbram/doc.shtml).  Documents
  265.   can be converted to the Doc format with MakeDoc, by Pat Beirne
  266.   <mailto:pat.beirne@sympatico.ca>.
  267.  
  268.   3.2.1.  Installing MakeDoc
  269.  
  270.   MakeDoc can be downloaded from
  271.   http://www.concentric.net/~rbram/makedoc7.cpp.  Compile it with your
  272.   C++ compiler and install the resulting executable as ``makedoc'' in a
  273.   directory in your search path.  There seems to be a small bug in
  274.   makedoc (version 0.7a) in that it does not output a newline as the
  275.   last character displayed to the user.  This does not seem to affect
  276.   the resulting document file, but it is annoying.
  277.  
  278.   There is a new version out, but it requires Java.  Take a look at Pat
  279.   Beirne's MakeDoc web page at
  280.   http://cpu563.adsl.sympatico.ca/MakeDocJ.htm.
  281.  
  282.   3.2.2.  Using MakeDoc
  283.  
  284.   Use MakeDoc as follows:
  285.  
  286.        makedoc data.txt data.prc "Data to display with Doc"
  287.  
  288.   This will create a file data.prc, which can be installed on your Pilot
  289.   with pilot-xfer.  The text "Data to display with Doc" will be dis¡
  290.   played in the directory of documents that Doc manages.
  291.  
  292.   The syntax for MakeDoc is as follows:
  293.  
  294.        makedoc [-n] [-b] <text-file> <prc-file> <story-name>
  295.        or
  296.        makedoc -d [-b] <prc-file> <text-file>
  297.  
  298.      <text-file>
  299.         The file that you wish to convert.
  300.  
  301.      <prc-file>
  302.         The name of the resulting file.  (End the name with ``.prc''.)
  303.  
  304.      <story-name>
  305.         The name you want displayed in the Doc or Jdoc directory of
  306.         documents.
  307.  
  308.   There are also options to decode the resulting .prc file and manage
  309.   various compression options.
  310.  
  311.   3.3.  PilotManager
  312.  
  313.   PilotManager is a generalized tool which allows multiple databases to
  314.   be synchronized in a single HotSync session.
  315.  
  316.   I have not been able to build and install PilotManager in time to
  317.   write about it for this version of the Pilot-HOWTO.
  318.  
  319.   A few links that might be helpful:
  320.  
  321.   ╖  The PilotManager package:
  322.      http://playground.sun.com/~bharat/pilotmgr.html
  323.      <http://playground.sun.com/~bharat/pilotmgr.html>
  324.  
  325.   ╖  A patch:
  326.      ftp://ftp.orbits.com/pub/Pilot/pilotmgr,v1.009-BETA-3.patch
  327.      <ftp://ftp.orbits.com/pub/Pilot/pilotmgr,v1.009-BETA-3.patch>
  328.  
  329.      This patch for PilotManager is only intended for use with
  330.      PilotManager version 1.009 Beta 3 when used with pilot-link version
  331.      0.8.0.  Install the PilotManager source and apply the patch with
  332.      the commands:
  333.  
  334.        tar -xvzf pilotmgr,v1.009-BETA-3.dev.tar.gz
  335.        cd pilotmgr,v1.009-BETA-3
  336.        patch -p1 < ../pilotmgr,v1.009-BETA-3.patch
  337.  
  338.   I hope to be able to install this software soon and report about it in
  339.   a future version of this document.
  340.  
  341.   4.  Tools for Developing Pilot Software
  342.  
  343.   4.1.  prc-tools
  344.  
  345.   The prc-tools package is a complete development environment built from
  346.   the FSF GNU utilities, compiler and debugger with the addition of a
  347.   few special tools.
  348.  
  349.   There is not much in the way of documentation, but you might want to
  350.   look at the Pilot Software Development web page at
  351.   http://www.massena.com/darrin/pilot/.
  352.  
  353.   4.1.1.  Installing prc-tools
  354.  
  355.   Download the most recent version of prc-tools from
  356.   ftp://ryeham.ee.ryerson.ca/pub/PalmOS.  The GNU tools can be retrieved
  357.   from ftp://prep.ai.mit.edu/pub/gnu.  Get binutils-2.7.tar.gz,
  358.   gcc-2.7.2.2.tar.gz and gdb-4.16.tar.gz.  The version numbers specified
  359.   for the GNU tools are correct as of prc-tools release 0.5.0.  Later
  360.   releases of prc-tools may require newer versions of the GNU tools.
  361.  
  362.   Put all of the distribution packages in one directory.  Unpack only
  363.   the prc-tools distribution.  The prc-tools Makefile will take care of
  364.   the other packages.  By default, prc-tools will be installed in
  365.   /usr/local/gnu.  If you want them installed somewhere else, you need
  366.   to change the value of INSTALLDIR in Makefile.  The steps are:
  367.  
  368.        tar -xvzf prc-tools.0.5.0.tar.gz
  369.        cd prc-tools-0.5.0
  370.        (Edit Makefile, if necessary.)
  371.        make doeverything
  372.  
  373.   4.1.2.  Using prc-tools
  374.  
  375.   One good reference for general use of prc-tools is the example
  376.   directory, particularly the Makefile.  Documentation for PilRC is
  377.   provided in the file pilrc1.5/doc/pilrc.htm included as part of prc-
  378.   tool version 0.5.0.
  379.  
  380.   E.  People
  381.  
  382.   Kenneth Albanowski <mailto:kjahds@kjahds.com> Maintains the pilot-link
  383.   suite of tools.
  384.  
  385.   Donnie Barnes <mailto:djb@redhat.com> Packaged pilot-link suite as Red
  386.   Hat RPM files.
  387.  
  388.   Rick Bram <mailto:rbram@concentric.net> Author of Doc.
  389.  
  390.   Matthew Cravit <mailto:pilot-unix-owner@lists.best.com> List owner for
  391.   the pilot-unix mailing list.
  392.  
  393.   Jeff Dionne <mailto:jeff@ryeham.ee.ryerson.ca> Original author of the
  394.   pilot-link suite of tools.  Manages the FTP area for the UNIX
  395.   PalmOS/Pilot development project.
  396.  
  397.   Mark W. Eichin <mailto:eichen@kitten.gen.ma.us> Ported pilot-link
  398.   suite to Debian Linux.
  399.  
  400.   David H. Silber <mailto:pilot@orbits.com> Author of this document.
  401.  
  402.   Chris Stevens <mailto:albert@acm.rpi.edu> Maintains the pilot-unix
  403.   mailing list archives.
  404.  
  405.