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 for
that.
-------------------------------------------------------------------------------

1. About this HOWTO


 1.1 Introduction

Psion has been making PDA's for years. This document will concentrate on the
Series 5* models, e.g. Series 5, Series_5mx 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).
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 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. 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 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 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.

 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


 IrDA

See Werner Heuser's 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.

 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


 plptools



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


 p3nfs/p5nfs



  Description
      p3nfs mounts the psion drives over the serial cable at /psion.stand/mnt,
      by default.


 ncp



  Description
      Matt Gumbley originally started ncp 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


 Psiconv



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


 psiontobbdb



  Description
      psiontobbdb converts Psion vcard format from the EPOC Contacts
      application to emacs BBDB format.


 psiontognomecard



  Description
      psiontognomecard converts Psion vcard format from the EPOC Contacts
      application GnomeCard vcard format.


 kab2psion



  Description
      kab2psion is a small utility written in perl to create a CSV file from
      the KDE addressbook.


 PsiLin



  Description
      PsiLin (in French, short_english_version) is a GTK-based graphical
      frontend for many programs which connect Linux to Psion. It also works
      for Series 3*.


 Psion SDK



  Description
      The EPOC SDK works on Linux via WINE, see Olaf Flebbe's web_page for
      instructions on how to get it working.


 Xmakesys



  Description
      xmakesys is a perl utilility that parses Psion's .pkg files and outputs
      .sis files.


 3.4 Psion utilities


 hermes



  Description
      hermes is a fully featured vt100 emulator.


 perl



  Description
      Olaf Flebbe has perl running under EPOC.


 python



  Description
      Duncan Booth has python running under EPOC. (link currently down)


 python



  Description
      Otfried Cheong also has a port of python for EPOC.


 BProlog



  Description
      Tim Wentford has gotten Bprolog working on the Psion 5*.


 Shell5



  Description
      Nick Murray has created Shell5, 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.


 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.


 c2f



  Description
      c2f converts the Psion contact file to a comma delimited format.


 4. Hardware Info


4.1 Hardware Troubleshooting

Hardware_troubleshooting

4.2 Pictures of internals

Akaev has disassembled several handhelds and made lots of pictures available as
tours.
Series_5_inside
Series_5mx_x-ray_1
Series_5mx_x-ray_2

4.3 Disassembly

Series_5_disassembly
Series_5_monitor_disassembly

 5. Further Information


5.1 Psion Specs


Psion File Formats

Frodo Looijaard has released information about the information he's garnered
from reverse engineering various Psion file formats.

PLP and NCP

Matt Gumbley has released some information about the PLP, Psion Link Protocol,
and NCP.

SIS and PLP

Alexander Thoukydides has released some information about sis files as well as
the PLP, 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


 p3nfs/p5nfs



  Description
      p3nfs, referenced above mounts the psion drives over the serial cable at
      /psion.stand/mnt, by default.


 6.3 Psion utilities


 nfsc



  Description
      nfsc is a VT100 emulator from Rudolf König.


 Shell3a



  Description
      Nick Murray has created Shell3a, 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.


PsiLin



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


arb's Psion Software



  Description
      Various utilities for Series 3* from arb.


6.4 Informational Web Pages


Hardware Info

Zerlegeanleitung_Psion_Serie_3a, e.g. Disassembling a Series 3a (in German
only)
A_naked_Series_3
Series_3_x-ray

Psion Link Protocol (for Psion 3)

PLP_documentation

Generic FAQs

Series 3 FAQ: part_1, part_2, part_3, part_4

 7. Revo


7.1 Informational Web Pages


Hardware Info

Revo_Inside