  Linux and Psion HOWTO
  Hans Kugler, der.hans@LuftHans.com
  v0.0.9, 2000-11-17

  This document describes how to use Psion palmtops with Linux, but does
  not cover running Linux on a Psion palmtop. See the Linux on Psion
  Project <http://SourceForge.net/projects/linux-7110/> for that.
  ______________________________________________________________________

  Table of Contents



  1. About this HOWTO

     1.1 Introduction
     1.2 This Document
     1.3 Mailing List
     1.4 Copyright notice and disclaimer

  2. General Information

     2.1 What is a Psion
     2.2 Psion models
     2.3 Psion Availability

  3. Sharing data between the Psion and Linux

     3.1 Hardware connectivity options
        3.1.1 Serial cable
        3.1.2 IrDA
        3.1.3 Builtin programs
     3.2 Programs for connectivity
        3.2.1 plptools
        3.2.2 p3nfs/p5nfs
        3.2.3 ncp
     3.3 Linux utilities
        3.3.1 Psiconv
        3.3.2 psiontobbdb
        3.3.3 psiontognomecard
        3.3.4 kab2psion
        3.3.5 PsiLin
        3.3.6 Psion SDK
        3.3.7 Xmakesys
     3.4 Psion utilities
        3.4.1 hermes
        3.4.2 perl
        3.4.3 python
        3.4.4 python
        3.4.5 BProlog
        3.4.6 Shell5
        3.4.7 E_Shell
        3.4.8 c2f

  4. Hardware Info

     4.1 Hardware Troubleshooting
     4.2 Pictures of internals
     4.3 Disassembly

  5. Further Information

     5.1 Psion Specs
        5.1.1 Psion File Formats
        5.1.2 PLP and NCP
        5.1.3 SIS and PLP

  6. Series 3

     6.1 Further Information
     6.2 Programs for connectivity
        6.2.1 p3nfs/p5nfs
     6.3 Psion utilities
        6.3.1 nfsc
        6.3.2 Shell3a
        6.3.3 PsiLin
        6.3.4 arb's Psion Software
     6.4 Informational Web Pages
        6.4.1 Hardware Info
        6.4.2 Psion Link Protocol (for Psion 3)
        6.4.3 Generic FAQs

  7. Revo

     7.1 Informational Web Pages
        7.1.1 Hardware Info


  ______________________________________________________________________

  1.  About this HOWTO



  1.1.  Introduction


  Psion <http://www.Psion.com/> has been making PDA's for years. This
  document will concentrate on the Series 5* models, e.g. Series 5,
  Series 5mx <http://www.series5mx.com/> and Series 5mx PRO and the 32
  bit EPOC operating system they come with, but there will be some
  crossover to older models such as the Series 3* and newer models such
  as the Series 7. There is also a little information about other
  ``series'' at the end of this document.


  1.2.  This Document


  The latest version of this document can be found at
  <http://home.pages.de/~lufthans/unix/docs/HOWTO/psion-HOWTO.html>, but
  the main repository is the Linux Documentation Project (LDP
  <http://www.LinuxDoc.org/>).

  Please send updates, corrections or suggestions to psion@LuftHans.com.


  1.3.  Mailing List


  There is a mailing list dedicated to using Psions with Linux and
  developing tools to enhance communication between them.

  To subscribe, send a message to plptools-developers-
  request@lists.SourceForge.net. John Schrader has put up a searchable
  list <http://rz-home.de/~jschrade/linux-psion.html> of messages from
  Oct 1998 through Feb 1999.

  There is also a mailing list dedicated to porting Linux to the Psion
  5* models at linux-7110-request@lists.SourceForge.net. An archive
  beginning 04Dec1999 is available at
  <http://web.gnu.walfield.org/mail-archive/linux-7110/>.

  Both mailing lists can be searched through the SourceForge interface.


  1.4.  Copyright notice and disclaimer


  (c) 1999-2000 Hans Kugler

  This document may be distributed under the terms set forth in the LDP
  license at http://www.linuxdoc.org/COPYRIGHT.html
  <http://www.linuxdoc.org/COPYRIGHT.html>. The author reserves the
  right to release the document and all submissions under a different
  license in addition to the LDP license.

  This document is provided ``AS IS'', with no express or implied
  warranties. Use the information in this document at your own risk.


  2.  General Information



  2.1.  What is a Psion


  Psion is a powerful Personal Digital Assistant (PDA) with pen-based
  touch screen as well as keyboard. There are several models. This HOWTO
  currently only covers the Series 5* models, e.g. Series 5, Series 5mx
  and Series 5mxPro.



  2.2.  Psion models


  There are several models of Psion PDAs. All have a foldout case where
  the screen is in the cover and opening the Psion causes the keyboard
  to jut out to a more usable position. They also feature the instant on
  and instant off capabilities of the EPOC operating system.

  Psion 3* are older PDAs that still have a lot of functionality and
  still get sold new due to their meeting needs and being lower cost.
  This HOWTO doesn't currently cover the Psion 3* series.

  Psion 5* has two main product lines with each having two models. The
  Psion series 5 has a green limited edition counterpart with no
  functional difference between itself and the standard Series 5. The
  series 5mxPro, however, has some fundamental differences from the
  Series 5mx.

  All four of the Series 5* products have: compact flash, serial port,
  keyboard and stylus (for the touchscreen). They all operate on 2 AA
  batteries and have a backup battery to maintain state when changing
  out the main batteries. Check out Akaev's site
  <http://psion.by.ru/psioninside/s5inside/index.htm> to take a tour of
  a dissected Series 5 classic.

  Both of the Series 5 models as well as the Series 5mx have system ROMs
  where the EPOC operating system is stored. After boot they operate out
  of the RAM (8MB for the Series 5 models and 16MB for the Series 5mx).
  The Series 5mxPro, however, has no ROM and operates entirely out of
  its 24MB of RAM. This enables software upgrades to the Series 5mxPro,
  whereas the other 3 models must exchange hardware to update EPOC.

  Psion has also released the Series 7, which is set to compete against
  the subnotebook class of PC, but running EPOC. They also have a Revo,
  which is smaller than the Series 5*.


  2.3.  Psion Availability


  Psion products are no longer available at retail stores in the US.
  They are available from retail shops in Europe as well as through mail
  order. Psion maintains a list of mail order
  <http://www.psion.com/resellers/index.html> firms by country on their
  web site.

  3.  Sharing data between the Psion and Linux



  3.1.  Hardware connectivity options


  The Psions have both serial and infra red ports. Either can be used
  for connectivity, but most connectivity programs currently only have
  features for the serial port connection.


  3.1.1.  Serial cable


  Armin Podtschaske x-rayed the "honda" connector.


  Pin 1 is on the top and pin 15 is on the bottom. Only pins 2 through 8
  and 15 are connected.


  ˇ  Pin 2: RTS

  ˇ  Pin 3: DTR

  ˇ  Pin 4: TXD

  ˇ  Pin 5: DSR

  ˇ  Pin 6: DCD

  ˇ  Pin 7: CTS

  ˇ  Pin 8: RXD

  ˇ  Pin 15: GND - Signal and Power ground

  ˇ  Frame: GND - Shield frame ground


  3.1.2.  IrDA


  See Werner Heuser's Infrared HOWTO
  <http://www.LinuxDoc.org/HOWTO/Infrared-HOWTO/> for information about
  using the Linux IrDA driver with a Psion. It is possible to beam files
  from Psion 5 (mx) via Linux-IrDA to a Linux System. The irda-utils
  include a special client psion5.c which can beam files between them.


  3.1.3.  Builtin programs


  There are two builtin software methods to use the communications
  ports. The first is the remote link, <ctrl>-l from the main file menu,
  which can be set to serial, infrared or off.

  EPOC also provides the program comms. The remote link must be set to
  off for the comms program to have access to the serial port.


  3.2.  Programs for connectivity



  3.2.1.  plptools



     Description
        plptools <http://SourceForge.net/projects/plptools> was
        originally developed by Fritz Elfert, who had merged plp and
        ``p3nfs/p5nfs''. plptools is currently being worked on by
        members of the PLP Tools project.

        plptools comprises of 3 different programs. ncpd provides a
        socket connection to the Psion. plpnfsd provides mounted
        filesystem access to the Psion and plpftp provides ftp access to
        the Psion.



     Usage
        ncpd [-V] [-v logclass] [-d] [-p <port>] [-s <device>] [-b
        <baudrate>]

        plpnfsd [-v] [-V] [-p port] [-d mountdir] [-u user]

        First start ncpd get it to listen on a port (7501 by default)
        for connection requests. Then, start either plpnfsd or plpftp.
        plpnfsd defaults to mount the Psion under /mnt/psion.



  3.2.2.  p3nfs/p5nfs



     Description

        p3nfs <http://www.koeniglich.de/> mounts the psion drives over
        the serial cable at /psion.stand/mnt, by default.



  3.2.3.  ncp



     Description
        Matt Gumbley originally started ncp
        <http://www.gumbley.demon.co.uk/ncp.html> for use with his Psion
        Series 3. Now that he's working on ``plptools'', you should use
        that :). However, ncp might still be of interest to users of a
        Psion Series 3, which this HOWTO doesn't cover :). Matt's ncp
        page also has information about the plp protocol.



  3.3.  Linux utilities



  3.3.1.  Psiconv



     Description
        Psiconv <http://huizen.dds.nl/~frodol/psiconv/> translates Psion
        Word documents or TextEd files (as used by the OPL editor, for
        example) to HTML (3.2 or 4.0) or plain text. It can also
        translate Sketch files and MBM files to almost any graphics
        format. A description of the Psion files formats is also
        included.



  3.3.2.  psiontobbdb



     Description
        psiontobbdb <http://www.ramin.uklinux.net/psiontobbdb> converts
        Psion vcard format from from the EPOC Contacts application to
        emacs BBDB format.



  3.3.3.  psiontognomecard



     Description
        psiontognomecard <http://www.ramin.uklinux.net/psiontognomecard>
        converts Psion vcard format from from the EPOC Contacts
        application GnomeCard vcard format.



  3.3.4.  kab2psion



     Description
        kab2psion <http://web.wanadoo.be/rc.s/kab2psion/> is a small
        utility written in perl to create a CSV file from the KDE
        addressbook.



  3.3.5.  PsiLin



     Description
        PsiLin
        <http://www.medsyn.fr/perso/g.delafond/psilin/psiolinu.htm> (in
        French, short english version
        <http://www.medsyn.fr/perso/g.delafond/psilin/psilingb.html>) is
        a GTK-based graphical frontend for many programs which connect
        Linux to Psion. It also works for Series 3*.



  3.3.6.  Psion SDK



     Description
        The EPOC SDK works on Linux via WINE, see Olaf Flebbe's web page
        <http://members.linuxstart.com/~oflebbe/sdk/> for instructions
        on how to get it working.



  3.3.7.  Xmakesys



     Description
        xmakesys <http://www.tardis.ed.ac.uk/~adq/projects/epoc32/> is a
        perl utilility that parses Psion's .pkg files and outputs .sis
        files.



  3.4.  Psion utilities



  3.4.1.  hermes



     Description
        hermes <http://www.iota.demon.co.uk/psion/hermes/hermes.html> is
        a fully featured vt100 emulator.



  3.4.2.  perl



     Description
        Olaf Flebbe has perl
        <http://members.linuxstart.com/~oflebbe/perl/perl5.html> running
        under EPOC.



  3.4.3.  python



     Description
        Duncan Booth has python <http://dales.rmplc.co.uk/Duncan/>
        running under EPOC. (link currently down)



  3.4.4.  python



     Description
        Otfried Cheong also has a port of python
        <http://www.cs.uu.nl/~otfried/Python/> for EPOC.



  3.4.5.  BProlog



     Description
        Tim Wentford has gotten Bprolog
        <http://www.probp.com/download/Epoc.html> working on the Psion
        5*.


  3.4.6.  Shell5



     Description
        Nick Murray has created Shell5
        <http://www.geocities.com/SiliconValley/Pines/1439/shell.html>,
        which is a command line interpreter which allows basic file
        operations as well as some sophisticated functions such as
        command history, filename expansion, batch file support, input
        and output redirection, pipe like feature :), aliases and shell
        variables, keyboard remapping and macros and UNIX or DOS syntax
        for pathnames.



  3.4.7.  E_Shell



     Description
        E-shell comes with the SDK and is a DOS-like shell environment
        from the EPOC SDK. It provides ways to launch programs from a
        command line; to check for file system corruption; to create,
        edit and display plain text files; to check on currently active
        processes and threads. The former link to download the shell
        itself has been removed.



  3.4.8.  c2f



     Description
        c2f <http://home.pages.de/~lufthans/unix/packages/> converts the
        Psion contact file to a comma delimited format.



  4.  Hardware Info



  4.1.  Hardware Troubleshooting


  Hardware troubleshooting
  <http://psion.by.ru/psioninside/trouble/index.htm>



  4.2.  Pictures of internals


  Akaev has disassembled several handhelds and made lots of pictures
  available as tours.


  Series 5 inside <http://psion.by.ru/psioninside/s5inside/index.htm>


  Series 5mx x-ray 1 <http://psion.by.ru/psioninside/xray/s5mx_1.htm>



  Series 5mx x-ray 2 <http://psion.by.ru/psioninside/xray/s5mx_2.htm>



  4.3.  Disassembly


  Series 5 disassembly
  <http://psion.by.ru/psioninside/s5dismantle/index.htm>


  Series 5 monitor disassembly
  <http://psion.by.ru/psioninside/s5inside/mon01.htm>



  5.  Further Information



  5.1.  Psion Specs



  5.1.1.  Psion File Formats


  Frodo Looijaard has released information about the information
  <http://huizen.dds.nl/~frodol/psiconv/html/Index.html> he's garnered
  from reverse engineering various Psion file formats.


  5.1.2.  PLP and NCP


  Matt Gumbley has released some information
  <http://www.gumbley.demon.co.uk/ncp.html> about the PLP
  <http://www.gumbley.demon.co.uk/ncp.html#9>, Psion Link Protocol, and
  NCP <http://www.gumbley.demon.co.uk/ncp.html#12>.


  5.1.3.  SIS and PLP


  Alexander Thoukydides has released some information about sis
  <http://www.btinternet.com/~thouky/software/psifs/sis.html> files as
  well as the PLP
  <http://www.btinternet.com/~thouky/software/psifs/plp.html>, Psion
  Link Protocol.


  6.  Series 3



  6.1.  Further Information


  As I said earlier, this HOWTO doesn't cover the Series 3 ( e.g.
  3/3a/3c/3mx/Sienna ), however, as I run into information, I will try
  to place it here anyway. This section will probably never be organized
  (unless someone else keeps it uptodate), but it still might contain
  useful information.


  6.2.  Programs for connectivity



  6.2.1.  p3nfs/p5nfs



     Description
        p3nfs <http://www.koeniglich.de/>, referenced ``above'' mounts
        the psion drives over the serial cable at /psion.stand/mnt, by
        default.



  6.3.  Psion utilities



  6.3.1.  nfsc



     Description
        nfsc <http://www.koeniglich.de/> is a VT100 emulator from Rudolf
        König.



  6.3.2.  Shell3a



     Description
        Nick Murray has created Shell3a
        <http://www.geocities.com/SiliconValley/Pines/1439/shell.html>,
        which is a command line interpreter which allows basic file
        operations as well as some sophisticated functions such as
        command history, filename expansion, batch file support, input
        and output redirection, pipe like feature :), aliases and shell
        variables, keyboard remapping and macros and UNIX or DOS syntax
        for pathnames.



  6.3.3.  PsiLin



     Description
        ``PsiLin'', mentioned in the Series 5* sections, also supports
        Series 3*



  6.3.4.  arb's Psion Software



     Description
        Various utilities <http://www.sat.dundee.ac.uk/~arb/psion/> for
        Series 3* from arb.



  6.4.  Informational Web Pages



  6.4.1.  Hardware Info


  Zerlegeanleitung Psion Serie 3a <http://www.home.unix-
  ag.org/fionn/d/Psion/Inside.html>, e.g. Disassembling a Series 3a (in
  German only)


  A naked Series 3 <http://psion.by.ru/psioninside/s3inside/index.htm>


  Series 3 x-ray <http://psion.by.ru/psioninside/xray/s3.htm>



  6.4.2.  Psion Link Protocol (for Psion 3)


  PLP documentation <http://ns1.filetron.com/~oflebbe/psion/>


  6.4.3.  Generic FAQs


  Series 3 FAQ: part 1 <http://www.widget.com.au/widget/faq1.htm>, part
  2 <http://www.widget.com.au/widget/faq2.htm>, part 3
  <http://www.widget.com.au/widget/faq3.htm>, part 4
  <http://www.widget.com.au/widget/faq4.htm>



  7.  Revo



  7.1.  Informational Web Pages



  7.1.1.  Hardware Info


  Revo Inside <http://psion.by.ru/psioninside/revoinside/index.htm>



