In its simplest form data is sent over the link using the 'link layer', an error correcting protocol which uses data packets. Each packet has the following format (in hex):

16 10 02 <CHAN> <TYPE> <DATA> 10 03 <CRC>

The first three bytes are always 16 10 02.

The next byte, <CHAN>, is the channel number. It is not used and must always equal 1. It is compared to the value stored at $2173, which is set to 1 when the comms link is loaded and not changed afterwards. It may be that some other communications devices use a different channel number.

The next byte, <TYPE>, contains the type of packet in the top 5 bits, and also a sequence number in the bottom 3 bits. The sequence number is a number that each data packet has to make sure that they are not mixed up. Since the sequence number increases with each new data packet, missing packets can be detected.

There are 4 types of packet:

<TYPE>=0	ACKNOWLEDGE	Signals proper reception of a data packet. The sequence number of the acknowledge is the same as that of the data packet received. If a packet is received with the wrong sequence number, an Acknowledge is sent of the last correct data packet, so this is also used as a request for the next packet. Contains no data.
<TYPE>=1	DISCONNECT	Signal that communication is to end. When sent to the Psion, the data should contain the error number. If the Psion sends one then it has no data. The sequence number is 0.
<TYPE>=2	LINK REQUEST	Requests a connection. Used at the start of a session to test two-way communication. Sequence number is 0 and it contains no data.
<TYPE>=3	DATA	A data packet. The sequence number is one more than that of the previous data packet (modulo 8) or 1 if it is the first data packet of the session.

The bytes 10 03 follow the data to signal the end of the packet.

The <CRC> is a 16-bit checksum for all the bytes between the header 16 10 02 and the footer 10 03. See below.

To make sure that sending the bytes 10 03 in the data will not prematurely end the packet, an escape mechanism is used. Every 10 byte in the data (or chan/type bytes) will be sent twice over the link. The receiving end then replaces each 10 10 by a single 10, and will not end the packet if it is followed by a 03. The extra 10 is not used in generating the CRC however.

The maximum length of a packet is 260 bytes.

CRC

Explaining CRC theory is beyond this manual. However CRCs can be computed by knowing the following values:

      CRC(01)=C1C0      CRC(10)=01CC
      CRC(02)=81C1      CRC(20)=01D8
      CRC(04)=01C3      CRC(40)=01F0
      CRC(08)=01C6      CRC(80)=01A0

The CRC of any single byte can be computed by EOR-ing the values above together for each set bit in the byte. If ChCl is the CRC for a sequence of one or more bytes, then the CRC of that sequence followed by a byte B will be CRC(B eor Ch) eor (Cl*0100).

For example, let's calculate CRC(01 10):

      CRC(01) = C1C0.
      CRC(01 10) = CRC(10 eor C1) eor C000
                 = CRC(D1) eor C000
                 = CRC(80) eor CRC(40) eor CRC(10) eor CRC(01) eor C000
                 = 01A0 eor 01F0 eor 01CC eor C1C0 eor C000
                 = 005C

The Link Protocol

Connecting

When CL is running on the PC, it continuously sends out Link Request packets. When the Psion is ready to start communicating it first starts up a link session in the following manner:

Waits to receive a Link Request. Times out if none received.
Sends a Link Request.
Waits to receive an Acknowledgment (seq.nr. 0). Times out if none.

After that the link is considered to be active and working, and the sequence numbers are reset.

Specifically, the packets involved are:

     Link Request: 16 10 02 01 10 10 10 03 00 5C
      Acknowledge: 16 10 02 01 00 10 03 01 90

If in step 3 a disconnect request is received, it should contain an error byte as data. Receiving a data packet will cause the Psion to return a data acknowledgement, and then it also considers the link to be active.

The start-up sequence above is performed before every data transfer. It can also be called specifically by using the XLCON: command, or calling rs$licon in machine code.

Sending

When sending a sequence of data packets, each packet is numbered 1,2,..,6,7,0,1,... etc. After each packet is sent, a reply is expected. What happens next depends on the type of reply:

An acknowledgement with the correct sequence number: The packet has been successfully sent, so now further packets can be sent if necessary.
An acknowledgement with the wrong sequence number, or
A packet with an incorrect CRC, or
A data packet: The same data packet will be re-sent.
If this happens too often, a 'Device Read' error occurs.
A link request: A 'Device read' error occurs.
A disconnect packet: The error in the packet is raised.

A single packet can be sent using the XLPUT:(a$) command, or RS$liput in machine code.

Receiving

When receiving a sequence of data packets, each packet should numbered 1,2,..,6,7,0,1,... etc. After each packet is received, a reply is expected. When the Psion is waiting for a data packet, what happens depends on the type of packet it receives:

A data packet with the correct sequence number: An acknowledgement is sent for this packet. The data is stored.
A data packet with the wrong sequence number, or
A packet with an incorrect CRC, or too long: An acknowledgement is sent with the previous sequence number, i.e. the sequence number of the last received packet.
A link request, or
A disconnect packet: The error in the packet is raised.
An acknowledgement: It is simply ignored.

A single packet can be received using the XLGET$: command, or RS$liput in machine code.

Note that the sequence numbers used when receiving packets are independent from those used when sending packets.

Disconnecting

When the link session is finished, the link should be deactivated. This is done by calling the XLDIS: command, or RS$lidis in machine code. This will send a disconnect packet, and close the link session. The disconnect packet has no data when sent from the Psion, but those sent by CL will contain a single byte which is the error number.

Higher layers

The link layer is simply an error correcting protocol for sending small snippets of data. Built on top of this is a protocol for sending and receiving files, file access commands etc.

The Psion Series 3 and 5 first have an NCP protocol layer above the link layer. NCP is a method of sending data over different channels. This is not implemented on the series II, though there seems to be a simple channel byte in every packet which is not used at all.

The file protocol layer generally works like this:

The startup sequence is performed first.
The Psion sends a word like 'FTRAN' in a data packet (which is acknowledged in the link layer as usual).
The CL program loads the FTRAN overlay, the program in S_FTRAN.EXE
The PC sends back an empty data packet as reply (which is again acknowledged in the link layer as usual).
The Psion sends a command to the FTRAN program in a data packet (+ack).
The PC sends data packet back in reply (+ack).
Repeat 5 and 6 till everything accomplished.
The Psion sends a disconnect packet.

It now remains to be explained what overlays there are, what commands they accept and what data they return.

FILE overlay

This overlay handles all remote file access (i.e. XFOPEN, XFCLOSE etc). There are five types of data packet that the Psion sends to CL/FILE. The data packet starts with a byte between 00 and 04 to indicate the call type and is followed by the parameters.

CALL TYPE		PARAMETERS	DESCRIPTION
XFOPEN	00	mode type name	Opens a remote file where mode/type are bytes and name is a string, exactly like the XFOPEN: command.
XFCLOSE	01		Closes current remote file, and exits the FILE overlay.
XFPUT	02	datastring	Puts the data at the current file position.
XFGET$	03	length	Gets (at most) length bytes from the current file position which are returned in the reply data packet from CL/FILE.
XFPOS	04	mode position	Sets the current file position. Mode is a byte but position is a string representation of the new file position. The reply data packet contains a string representation of the old file position.

For example, suppose we run the following short program:

      TEST:
      XFOPEN:("HOMER.TXT",1,1)
      XFPUT$:("Doh"+CHR$(33))
      XFCLOSE:

then the following list is the complete exchange between the Psion and the PC, assuming no errors occur:

   Start link layer session:
         PC:  Link Request:  16 10 02 01 10(10)10 03 00 5C
         Ps:  Link Request:  16 10 02 01 10(10)10 03 00 5C
         PC:  Acknowledge:   16 10 02 01 00 10 03 01 90
   Then the FILE overlay is loaded:
         Ps:  FILE overlay:  16 10 02 01 19 46 49 4C 45 10 03 2D BE
         PC:  Acknowledge:   16 10 02 01 01 10 03 C0 50
   Reply:
         PC:  No Data:       16 10 02 01 19 10 03 C0 5A
         Ps:  Acknowledge:   16 10 02 01 01 10 03 C0 50
   File is opened:
         Ps:  Open command:  16 10 02 01 1A 00 01 01 48 4F 4D 45 52 2E 54 58 54
                             10 03 39 8B              H  O  M  E  R  .  T  X  T
         PC:  Acknowledge:   16 10 02 01 02 10 03 80 51
   Reply:
         PC:  No Data:       16 10 02 01 1A 10 03 80 5B
         Ps:  Acknowledge:   16 10 02 01 02 10 03 80 51
   Send data:
         Ps:  Data Doh!:     16 10 02 01 1B 02 44 6F 68 21 10 03 A1 DE
                                                D  o  h  !
         PC:  Acknowledge:   16 10 02 01 03 10 03 41 91
   Reply:
         PC:  No Data:       16 10 02 01 1B 10 03 41 9B
         Ps:  Acknowledge:   16 10 02 01 03 10 03 41 91
   End signal:
         Ps:  End packet:    16 10 02 01 1C 01 10 03 98 C0
         PC:  Acknowledge:   16 10 02 01 04 10 03 00 53
   Reply:
         PC:  No Data:       16 10 02 01 1C 10 03 00 59
         Ps:  Acknowledge:   16 10 02 01 04 10 03 00 53
   End link layer session:
         Ps:  disconnect:    16 10 02 01 08 10 03 00 56

FTRAN overlay

This is the most commonly used one. It handles all standard file transfer. There are four types of data packet that the Psion sends to FTRAN. The data packet starts with a byte between 00 and 03 to indicate the call type and is followed by the parameters.

CALL TYPE		PARAMETERS	DESCRIPTION
Command	00	command filetype filename	Tells FTRAN to perform a command on the remote file. The filetype is 00 for ODB files, 01 for OPL files, 02-0F for block files. It is 00 if the type is irrelevant. The available commands are listed below.
End	01		Exits the FTRAN overlay.
PutData	02	datastring	Passes data to FTRAN for saving on disk.
GetData	03	length	Gets (at most) length bytes from the current file position which are returned in the reply data packet from CL/FILE. The length requested is usually FE.

The commands available are:

Recv	00	Warns CL/FTRAN that the Psion is about to request data from the file of the given name. This returns the length and type of the PC file. Further details below.
Send	01	Warns CL/FTRAN that the Psion is about to send data to the file of the given name. Any existing file of that name will be overwritten without warning.
Exists	04	Gives an error if the file does not exist.

When sending/receiving ODB files, each record is sent in a separate packet. No data is returned after the recv command.

When sending/receiving block files, the data is split in a separate packets, generally about FE bytes long. The data returned after the recv command is the length of the block in the file, followed by the Psion file type (between 82 and 8F).

When sending/receiving OPL files, the data is split in a separate packets just like block files. The line ends are indicated by zero bytes, and it is FTRAN that translates it to/from CR/LF when writing to disk. The data returned after the recv command is the length of the block in the file, the Psion file type (81 - although the file is stuctured like an OB3), followed by 0000 and the length of the OPL part of the procedure block file. Note that using file type 83 works fine if used with the COMMS menu, but produces pack corruption when used with the OPL XTRECV: command.

BOOT overlay

This overlay handles the loading of BOOT code, and the XMLOAD: command. After the BOOT overlay is loaded, it expects to be sent a data packet containing the name of the boot file to load. The reply packet contains the length of the code.

The Psion then sends a packet containing the address to load the code. In reply the first data packet contains the first part of the code, ready to be stored in memory. When the Psion next sends a packet containing just a zero byte, the next code packet is sent. This is repeated as often as necessary.

When the end of the code has been reached, a disconnect packet with a zero error is returned by CL/BOOT.

Note that fixing up the relocatable addresses in the code is done by CL/BOOT.

Instead of using the BOOT option in the menu, the XMLOAD: command can be used. XMLOAD:(addr%,len%,name$) loads the boot code from remote file name$ to address addr%, but rejects it if the code exceeds length Len%.

EXIT overlay

This overlay exits the CL program completely (by stuffing q and y in the keyboard buffer of the PC). It has no other functions. It can therefore be used by using the following sequence of commands:

   XLCON:
   XLPUT:("EXIT")
   XLDIS:

PLAN and PLANM overlays

These overlays are used by the spreadsheet program. When you choose the FILE/IMPORT or FILE/EXPORT menu options, the Psion requests the PLANM overlay which returns the file type menu, and the Psion disconnects again. The file type menu returned is 19h bytes long and is as follows:

   03 "WKS" 0001
   03 "WK1" 0002
   03 "WR1" 0003
   03 "DIF" 0004
   00

It is in the correct format for the MN$DISP (SWI 50h) system service.

The PLAN overlay handles the transfer and conversion of the spreadsheet files. To export a file, the Psion first sends it a packet of which the first byte is between 81h and 84h depending on the file type chosen, and the rest contains the file name. The spreadsheet data follows; first a packet containing the dimensions of the sheet, then a packet for each non-empty cell, and finally a packet containing just FE. The reply that PLAN gives each time is a packet containing 00, except that the FE is answered with FE 00.

A cell is encoded in this format:

Column	Byte containing column of cell (0 is column A)
Row	Byte containing row of cell (0 is row 1)
Type	Contains 22h (=") if cell contains text. Contains 87h if cell contains a number or formula
Contents	')"; onMouseout="hideddrivetip()"> ASCII string with contents of cell.

If a cell contains a formula and its result then one packet contains the formula, and the cell is resent in the next packet but this time containing just the value.

For example, here are the packets sent to PLAN to export a simple sheet:

    84 54 45 53 54                  Export TEST in DIF format.
    02 04                           Columns A-B, Rows 1-4 used.
    01 00 22 43 4F 4C 31            B1, contains "COL1"
    00 01 22 52 4F 57 31            A2, contains "ROW1"
    01 01 87 31                     B2, contains 1
    00 02 22 52 4F 57 32            A4, contains "ROW2"
    01 02 87 35                     B3, contains 5
    01 03 87 3D 42 32 2B 42 33      B4, contains =B2+B3 (formula)
    01 03 87 36                     B4, contains 6 (value)
    FE                              End of sheet

Import is very similar. First the Psion sends CL/PLAN a packet of which the first byte is between 01 and 04 depending on the file type chosen, and the rest contains the file name. It just returns 00. Then the Psion sends a 00 and PLAN returns the first non-empty cell, in the same format as before. This is repeated until PLAN sends FE00, signifying the end of the sheet.