Psion Link Protocol

Version 1.15, 02-Mar-02
by Alexander Thoukydides (alex@thouky.co.uk)

Copyright © Alexander Thoukydides.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

Introduction

The SIBO and EPOC operating systems use a proprietary serial protocol, called the Psion Link Protocol (PLP), to allow remote access to their filesystems and to permit synchronization. This document attempts to provide sufficient information to allow the implementation of clients that communicate with SIBO or EPOC devices via the PLP.

The latest version of this document will normally be available from http://www.thouky.co.uk/software/psifs/plp.html.

History

Revision	Date	Author	Description
1.15	02-Mar-02	Alexander Thoukydides	Added some details of the `WPRT` print data format.
1.14	05-Feb-02	Alexander Thoukydides	Added information on the `WPRT` server.
1.13	30-Jun-01	Alexander Thoukydides	Replaced CRC table with algorithm to generate it. Improved the `GENCSERV` server description.
1.12	27-Jun-01	Alexander Thoukydides	Added more details of Ericsson R380 variant.
1.11	17-Jun-01	Alexander Thoukydides	Added some details of Ericsson R380 variant. Improved clipboard and CRC descriptions.
1.10	10-Jun-01	Alexander Thoukydides	Modified clipboard description to fit the rest of the document better.
1.09	10-Jun-01	Fritz Elfert	Added description of Clipboard server and clipboard data.
1.08	08-Jun-01	Alexander Thoukydides	Corrected sense parameter for `RFSV16_FSEEK` and `RFSV32_SEEK_FILE`.
1.07	30-Jan-01	Alexander Thoukydides	Corrected parameters for `RFSV32_READ_WRITE_FILE` and added description of missing `RFSV16_FDIRREAD` parameter.
1.06	09-Oct-00	Alexander Thoukydides	Added note that the EPOC variant of the data link layer is multi-windowed.
1.05	28-Jul-00	Alexander Thoukydides	Added command line length parameter to `NCP_GET_CMD_LINE` response.
1.04	02-Jun-00	Alexander Thoukydides	Released under version 1.1 of the GNU Free Documentation License.
1.03	21-Apr-00	Alexander Thoukydides	Corrected HTML Updated email address. Added URL for latest version of this document.
1.02	23-Jan-00	Alexander Thoukydides	Added details for `NCP_SET_TIME` and `NCP_GET_MACHINE_INFO`.
1.01	22-Dec-99	Alexander Thoukydides	Added descriptions for most `RFSV` server commands.
1.00	09-Dec-99	Alexander Thoukydides	First draft. No descriptions for `RFSV` server commands.

Disclaimer

This document is supplied "as is"; no warranty, express or implied, of the merchantability of this document or its fitness for any particular purpose is given. In no circumstances shall the author, or any provider or distributor of this document, be liable for any damage, loss of profits, or any indirect or consequential loss arising out of the use or misuse of any information or particular in this document.

All trademarks are acknowledged.

Acknowledgements

The information contained within this document was collated from many different sources, including (but not restricted to):

Olaf Flebbe's document providing a partial description of the PLP.
Phil Proudman's PLP implementation for UNIX.
Frodo Looijaard's file format description.
Psion documents describing the proposed differences between the SIBO and EPOC implementations.
EPOC C++ SDK, Evaluation Edition.
Excerpts from the EPOC source code.
Analysis of the serial data exchanged between a Psion Series 5 and a PC running PsiWin.
Trial and error while developing PsiFS for RISC OS computers.
Corrections supplied by Fritz Elfert, Johan Persson, Andy Porro, David Bingham and Pauli Heikkinen.

Due to the diverse and incomplete nature of these sources, the description here probably contains both errors and omissions. Please send any corrections or additions to the author for inclusion in future revisions.

Layers

The PLP consists of a stack of layers that can be mapped onto the layers of the Open Systems Interconnection model:

OSI layer EPOC name Description

7 Application n/a

6 Presentation LINK, RPCS, RFSV etc Multiple servers, each providing a related set of services

5 Session NCP Multiplexing of multiple client-server communications channels with flow control

4 Transport n/a

3 Network n/a

2 Data link Link Synchronization, error detection and recovery

1 Physical RS-232

OSI layer	EPOC name	Description
7	Application	n/a
6	Presentation	`LINK`, `RPCS`, `RFSV` etc	Multiple servers, each providing a related set of services
5	Session	NCP	Multiplexing of multiple client-server communications channels with flow control
4	Transport	n/a
3	Network	n/a
2	Data link	Link	Synchronization, error detection and recovery
1	Physical	RS-232

Conventions

Unless otherwise specified the following conventions apply:

Numeric values larger than a byte are stored with the least significant byte first.
Strings are terminated by a single NUL (0x00) byte unless otherwise described.

Physical Layer

At the lowest level, the PLP uses standard RS-232 for the physical layer. Depending on the exact devices being used, a special cable or converter may be required.

The DTR and RTS handshaking lines are both raised when the PLP is enabled and dropped when it is subsequently disabled. However, only the DSR line should be monitored to detect activity.

Any baud rate supported by both devices may be used. The data format is 8 data bits, 1 stop bit, and no parity checking.

Data Link Layer

The data link layer provides a simple byte orientated protocol to allow reliable communication between two devices. It is a connection orientated protocol with clear phases of link establishment, information transfer, and link termination. An acknowledgement and retry strategy is used to guarantee error free exchange of data.

This layer is sometimes referred to as LINK, but that leads to confusion with one of the higher level servers having the same name.

Frame Format

All data is transmitted within frames of the following format:

Bytes 1 1 1 1 n 1 1 2

Data SYN DLE STX Cont Seq Data DLE ETX CRC

Bytes	1	1	1	1	n	1	1	2
Data	`SYN`	`DLE`	`STX`	Cont	Seq	Data	`DLE`	`ETX`	CRC

The Cont and Seq fields are combined into a single byte, with the Cont in the high nibble, and Seq in the low nibble. If the Seq value is greater than 7 then the most significant bit of the Seq nibble is set and an additional byte is inserted into the frame (EPOC variant only):

Bytes 1 1 1 1 1 n 1 1 2

Data SYN DLE STX Cont (Seq & 7) | 8 Seq >> 3 Data DLE ETX CRC

Bytes	1	1	1	1	1	n	1	1	2
Data	`SYN`	`DLE`	`STX`	Cont	`(`Seq `& 7) \| 8`	Seq `>> 3`	Data	`DLE`	`ETX`	CRC

The length of the Data field (n) can vary from 0 to 300 bytes before byte stuffing. The session layer (NCP) is responsible for splitting and recombining longer messages to fit within this limit.

The 16 bit Cyclic Redundancy Check (CRC) is transmitted with the most significant byte followed by the least significant byte.

Note that the Ericsson R380 implementation uses ETB instead of SYN for the start of frame character. It also has a larger maximum frame size, with the length of the Data field (n) varying up to 2048 bytes before byte stuffing.

Special Characters

The following special characters are used within the protocol:

Name Value Description

STX 0x02 Start of frame

ETX 0x03 End of frame

EOT 0x04 A stuffed ETX character

DLE 0x10 Field delimiter within a frame

DC1 0x11 Not protocol characters, but stuffed (Ericsson R380)

DC3 0x13

SYN 0x16 Synchronize start of frame

ETB 0x17 Synchronize start of frame (Ericsson R380)

Name	Value	Description
`STX`	`0x02`	Start of frame
`ETX`	`0x03`	End of frame
`EOT`	`0x04`	A stuffed `ETX` character
`DLE`	`0x10`	Field delimiter within a frame
`DC1`	`0x11`	Not protocol characters, but stuffed (Ericsson R380)
`DC3`	`0x13`
`SYN`	`0x16`	Synchronize start of frame
`ETB`	`0x17`	Synchronize start of frame (Ericsson R380)

To prevent control characters within the frame body from being misinterpreted, a system of byte stuffing is employed. This replaces characters within the Cont/Seq and Data fields as follows:

Raw character Stuffed character sequence Variants

Name Value Names Values

DLE 0x10 DLE DLE 0x10 0x10 SIBO and EPOC

ETX 0x03 DLE EOT 0x10 0x04 EPOC

DC1 0x11 DLE Space 0x10 0x20 Ericsson R380 only

DC3 0x13 DLE ! 0x10 0x21

Raw character	Stuffed character sequence	Variants
Name	Value	Names	Values
`DLE`	`0x10`	`DLE DLE`	`0x10 0x10`	SIBO and EPOC
`ETX`	`0x03`	`DLE EOT`	`0x10 0x04`	EPOC
`DC1`	`0x11`	`DLE Space`	`0x10 0x20`	Ericsson R380 only
`DC3`	`0x13`	`DLE !`	`0x10 0x21`

The reverse process is performed by the receiver.

Cyclic Redundancy Check

The standard x¹⁶ + x¹² + x⁵ + 1 polynomial is used to generate a 16 bit CRC. This is the same CRC as used for the XMODEM protocol. It is calculated over the Cont/Seq and Data bytes prior to any stuffing.

The following C code calculates a lookup table to allow efficient calculation of this CRC:

const unsigned int polynomial = 0x1021; unsigned int table[256], index; table[0] = 0; for (index = 0; index < 128; index++) { unsigned int carry = table[index] & 0x8000; unsigned temp = (table[index] << 1) & 0xffff; table[index * 2 + (carry ? 0 : 1)] = temp ^ polynomial; table[index * 2 + (carry ? 1 : 0)] = temp; }

The following line can then be used to add a byte (value) to a 16 bit CRC (old_crc) to give the new 16 bit CRC (new_crc):

new_crc = (old_crc << 8) ^ table[((old_crc >> 8) ^ value) & 0xff];

The CRC value should be initialised to 0 before any bytes are processed. It may be necessary to use unsigned values to prevent implementation dependant problems on systems with 16 bit integers.

Timers

Two timer events are used to implement timeouts:

Timer Period

Re-transmission Baud rate dependant

Inactivity Application dependant

Timer	Period
Re-transmission	Baud rate dependant
Inactivity	Application dependant

The re-transmission timeout is used to trigger the re-transmission of unacknowledged frames. To optimise the timeout for the operating conditions, it is calculated by summing the following three components:

Component Description

Baud Rate Bits Factor The estimated time required to transmit the number of bits in a frame at the current baud rate. A suitable timeout is given by (13200 / baud) seconds.

Round Trip Time Factor A running estimate of the additional time to receive an acknowledgement from the remote device. A constant offset of 0.2 seconds is probably adequate for simpler implementations.

Backoff Factor An additional timeout dependant on the number of re-transmissions that have taken place. This factor may be omitted in a simple implementation.

Component	Description
Baud Rate Bits Factor	The estimated time required to transmit the number of bits in a frame at the current baud rate. A suitable timeout is given by (13200 / baud) seconds.
Round Trip Time Factor	A running estimate of the additional time to receive an acknowledgement from the remote device. A constant offset of 0.2 seconds is probably adequate for simpler implementations.
Backoff Factor	An additional timeout dependant on the number of re-transmissions that have taken place. This factor may be omitted in a simple implementation.

The Baud Rate Bits Factor is most significant at low baud rates, but the Round Trip Time Factor is more significant at higher baud rates.

The inactivity timer period may be adjusted to suit the application. If no detection of an idle connection is required then it can be completely disabled, otherwise a timeout of 60 seconds is recommended.

Although two different timer events are required, they may both be implemented using a single timer since only one timer can be active at any time.

Protocol Data Units

There are four major types of frame or Protocol Data Unit (PDU):

Cont Seq Name Description

0 Sequence number of last valid Data_Pdu received Ack_Pdu Used to complete handshaking during connection phase, and to acknowledge Data_Pdu frames.

1 0 Disc_Pdu Used to terminate a connection.

1 Disc_Req_Pdu First disconnect in a handshaked disconnection. Not currently used.

2 0 Req_Pdu Used during connection phase to request a connection.

1 ... 3 (use 1) Req_Req_Pdu First request in connection establishment. EPOC variant of protocol only.

4 ... 6 (use 4) Req_Con_Pdu Responding request in connection establishment. EPOC variant of protocol only.

3 Next sequence number Data_Pdu Data frame.

Cont	Seq	Name	Description
`0`	Sequence number of last valid `Data_Pdu` received	`Ack_Pdu`	Used to complete handshaking during connection phase, and to acknowledge `Data_Pdu` frames.
1	`0`	`Disc_Pdu`	Used to terminate a connection.
`1`	`Disc_Req_Pdu`	First disconnect in a handshaked disconnection. Not currently used.
`2`	`0`	`Req_Pdu`	Used during connection phase to request a connection.
`1` ... `3` (use `1`)	`Req_Req_Pdu`	First request in connection establishment. EPOC variant of protocol only.
`4` ... `6` (use `4`)	`Req_Con_Pdu`	Responding request in connection establishment. EPOC variant of protocol only.
`3`	Next sequence number	`Data_Pdu`	Data frame.

Only the Data_Pdu and Req_Con_Pdu frames contain Data fields.

The Data_Pdu and Ack_Pdu both contain a sequence number. This is used to allow acknowledgements to be matched to the corresponding data frame. Each device maintains its own sequence number that is incremented for each Data_Pdu, modulo either 8 for the SIBO variant or 2048 for the EPOC variant. More details are given in the following sections.

Connection Sequence

The connection sequence is slightly different with the SIBO and EPOC variants of the protocol. The original SIBO implementation suffers from a modem echo problem, whereby the data link layer can establish a connection with itself if serial data is echoed back; this was corrected in the EPOC implementation.

Both client-server and peer to peer connections are supported. The peer to peer connection sequence is a symmetrical version of the client-server sequence, with both devices processing all of the PDUs.

SIBO Connection

The client-server connection sequence is initiated by the client:

From client From server Description

Req_Pdu Connection requested by client

Req_Pdu Connection accepted by server

Ack_Pdu Connection established

From client	From server	Description
`Req_Pdu`		Connection requested by client
	`Req_Pdu`	Connection accepted by server
`Ack_Pdu`		Connection established

The peer to peer connection sequence is very similar:

From device 1 From device 2 Description

Req_Pdu Req_Pdu Both devices request a connection

Ack_Pdu Ack_Pdu Both devices accept the connection

From device 1	From device 2	Description
`Req_Pdu`	`Req_Pdu`	Both devices request a connection
`Ack_Pdu`	`Ack_Pdu`	Both devices accept the connection

In both cases the sequence numbers should be initialised to 0, and the Ack_Pdu sent with a Seq field of 0. However, if the received Ack_Pdu contains a non-zero Seq field then the sequence number should be seeded from the supplied value.

EPOC Connection

The client-server connection sequence is initiated by the client:

From client From server Description

Req_Req_Pdu Connection requested by client

Req_Con_Pdu Connection request confirmed by server

Ack_Pdu Connection established

From client	From server	Description
`Req_Req_Pdu`		Connection requested by client
	`Req_Con_Pdu`	Connection request confirmed by server
`Ack_Pdu`		Connection established

The peer to peer connection sequence is very similar:

From device 1 From device 2 Description

Req_Req_Pdu Req_Req_Pdu Both devices request a connection

Req_Con_Pdu Req_Con_Pdu Both devices confirm the connection request

Ack_Pdu Ack_Pdu Both devices accept the connection

From device 1	From device 2	Description
`Req_Req_Pdu`	`Req_Req_Pdu`	Both devices request a connection
`Req_Con_Pdu`	`Req_Con_Pdu`	Both devices confirm the connection request
`Ack_Pdu`	`Ack_Pdu`	Both devices accept the connection

The Data field of the Req_Con_Pdu frames contain a 4 byte magic number. This is a pseudo-random value generated independently by each device. If the magic numbers match then a peer to peer connection is rejected because it indicates that the device is attempting to connect to itself. To avoid the risk of the same pseudo-random number sequence being generated by both devices, it is advisable to include an additional unique element, such as the value of a clock.

In both cases the sequence numbers should be initialised to 0, and the Ack_Pdu sent with a Seq field of 0. However, if the received Ack_Pdu contains a non-zero Seq field then the sequence number should be seeded from the supplied value.

If the Ack_Pdu is not received within the re-transmission timeout, then the Req_Req_Pdu may be re-transmitted up to 4 times before aborting the connection attempt.

Universal Connection

With a little care it is possible to support both variants of the protocol within a single state machine. The modulo value for sequence numbers can then be selected once the protocol variant has been identified.

A Req_Req_Pdu frame can always be used to initiate a connection; a device that supports the EPOC variant of the protocol will then reply with a Req_Con_Pdu frame, but if the other device only supports the SIBO variant then it will treat it as a Req_Pdu and reply with an Ack_Pdu. Hence, the protocol variant is indicated by whether a Req_Con_Pdu is received prior to the Ack_Pdu.

Similarly, if the other device initiates the connection, then the protocol variant can be detected from whether a Req_Pdu or Req_Req_Pdu is received.

Data Transfer Sequence

The SIBO variant of the data link layer is single windowed, i.e. only a single acknowledgement can be outstanding at any time. This guarantees that only a single transmit buffer and a single receive buffer is required. Beware though, that due to the asynchronous nature of data transfer, the data transmission and acknowledgement in each direction may be interleaved.

The EPOC variant of the data link layer is multi windowed, i.e. more than one acknowledgement can be outstanding at any time. The default configuration will send up to 8 Data_Pdu frames before waiting for an acknowledgement.

The data transfer sequence is the same for both the SIBO and EPOC variants. Either device may initiate a data transfer, providing that there are not too many outstanding acknowledgements for the previous transfers.

From device 1 From device 2 Description

Data_Pdu Data sent

Ack_Pdu Data acknowledged

From device 1	From device 2	Description
`Data_Pdu`		Data sent
	`Ack_Pdu`	Data acknowledged

The only other difference between the SIBO and EPOC variants, as described earlier, is the range of sequence numbers used; the value is modulo 8 for the SIBO variant and modulo 2048 for the EPOC variant. The sequence number is incremented prior to sending the Data_Pdu.

An Ack_Pdu should always be sent in response to a received Data_Pdu, even if the sequence number does not match the expected value. However, the Seq field of the Ack_Pdu should be set to the value from the last valid Data_Pdu received, not necessarily that of the Data_Pdu being responded to.

If the Ack_Pdu is not received within the re-transmission timeout, or if an Ack_Pdu is received with a different sequence number from that sent in the Data_Pdu, then the Data_Pdu may be re-transmitted up to 8 times before the link is disconnected. The sequence number must not be incremented when re-transmitting a Data_Pdu.

Disconnection Sequence

No handshaking occurs during the PLP disconnection sequence, so there is a risk of one device disconnecting without the other noticing. A fix was planned for the EPOC variant of the protocol, but does not appear to have been implemented.

A disconnection may also occur if the serial cable is physically disconnected, so the DSR handshaking line should also be monitored as described earlier. Additionally, if the inactivity timeout is exceeded without any frames being received then a disconnection should be assumed.

SIBO Disconnection

Either device may initiate the disconnection:

From device 1 From device 2 Description

Disc_Pdu Initiator requests a disconnection

From device 1	From device 2	Description
`Disc_Pdu`		Initiator requests a disconnection

Note that there is no reply to the Disc_Pdu, so the disconnection must be assumed to have succeeded.

EPOC Disconnection

The following disconnection sequence was proposed to fix the problem described above, but does not appear to be implemented. Either device may initiate the disconnection:

From device 1 From device 2 Description

Disc_Req_Pdu Initiator requests a disconnection

Disc_Pdu Disconnection confirmed

From device 1	From device 2	Description
`Disc_Req_Pdu`		Initiator requests a disconnection
	`Disc_Pdu`	Disconnection confirmed

Even if this enhanced disconnection sequence is supported, the original SIBO disconnection sequence must still be supported. In particular, if the Disc_Pdu is not received within the re-transmission timeout then a Disc_Pdu frame should be sent and the disconnection assumed to have succeeded.

State Machine

This section describes a sample state machine that implements both the SIBO and EPOC variants of the data link layer. A peer to peer connection is attempted, but client-server connections should also be supported.

This is not intended to be the definitive implementation, but should help to clarify the operation of the protocol. In particular, only single windowed behaviour is supported, but this does not present interoperability with systems that do support multi-windowed operation; it just reduces that maximum achievable transfer rate.

States

Five states are used:

State Description

Idle_State Disconnected

Idle_Req_State Req_Req_Pdu sent, awaiting Req_Con_Pdu response

Idle_Ack_State Req_Con_Pdu sent, awaiting Ack_Pdu response

Data_State Connected, no acknowledgement pending

Data_Ack_State Data_Pdu sent, awaiting Ack_Pdu acknowledgement

State	Description
`Idle_State`	Disconnected
`Idle_Req_State`	`Req_Req_Pdu` sent, awaiting `Req_Con_Pdu` response
`Idle_Ack_State`	`Req_Con_Pdu` sent, awaiting `Ack_Pdu` response
`Data_State`	Connected, no acknowledgement pending
`Data_Ack_State`	`Data_Pdu` sent, awaiting `Ack_Pdu` acknowledgement

Events

The following events are processed by the state machine:

Event Source Description

Ack_Rx Received frame Ack_Pdu (acknowledge) received

Disc_Rx Disc_Pdu or Disc_Req_Pdu (disconnect) received

Req_Rx Req_Pdu (connection request) received

Req_Req_Rx Req_Req_Pdu (handshaked connection request) received

Req_Con_Rx Req_Con_Pdu (handshaked connection accepted) received

Data_Rx Data_Pdu (data) received

Connect Local client Connection requested

Disconnect Disconnection requested

Write Data to transmit

Timeout Timer Re-transmission timer or inactivity timer expired

Event	Source	Description
`Ack_Rx`	Received frame	`Ack_Pdu` (acknowledge) received
`Disc_Rx`	`Disc_Pdu` or `Disc_Req_Pdu` (disconnect) received
`Req_Rx`	`Req_Pdu` (connection request) received
`Req_Req_Rx`	`Req_Req_Pdu` (handshaked connection request) received
`Req_Con_Rx`	`Req_Con_Pdu` (handshaked connection accepted) received
`Data_Rx`	`Data_Pdu` (data) received
`Connect`	Local client	Connection requested
`Disconnect`	Disconnection requested
`Write`	Data to transmit
`Timeout`	Timer	Re-transmission timer or inactivity timer expired

Note that only a single timer event is used; both the re-transmission and inactivity timeouts are implemented using a single timer.

Only the SIBO disconnection sequence is implemented, so Disc_Pdu and Disc_Req_Pdu are treated identically.

Variables

The following variables are required to store additional state:

Variable Description Default

Enabled Is the link enabled FALSE

Variant The protocol variant: SIBO or EPOC SIBO

Retries Number of retries remaining 0

Seq_Tx Last sequence number for transmitted data frames 0

Seq_Rx Last sequence number for received data frames 0

Magic Magic number for this device Pseudo-random

Variable	Description	Default
`Enabled`	Is the link enabled	`FALSE`
`Variant`	The protocol variant: `SIBO` or `EPOC`	`SIBO`
`Retries`	Number of retries remaining	`0`
`Seq_Tx`	Last sequence number for transmitted data frames	`0`
`Seq_Rx`	Last sequence number for received data frames	`0`
`Magic`	Magic number for this device	Pseudo-random

State Tables

The following tables detail the actions taken for each event, with a separate table for each state.

The function Inc(x) is defined to return the next sequence number after x, modulo the appropriate value.

The Reset() function sets all of the variables, except for Enabled, back to the defaults given in the above table. This should select a different pseudo-random number for Magic. It also starts the re-transmission timer.

Idle_State

Event	Condition	Action	Next state
`Ack_Rx`	Always	No action	`Idle_State`
`Disc_Rx`	Always	No action	`Idle_State`
`Req_Rx`	`Enabled`	`Variant = SIBO` Send `Req_Con` with `Magic` as data Start re-transmission timer `Retries = 4`	`Idle_Ack_State`
`Req_Rx`	else	No action	`Idle_State`
`Req_Req_Rx`	`Enabled`	`Variant = EPOC` Send `Req_Con` with `Magic` as data Start re-transmission timer `Retries = 4`	`Idle_Ack_State`
`Req_Req_Rx`	else	No action	`Idle_State`
`Req_Con_Rx`	Always	No action	`Idle_State`
`Data_Rx`	Always	No action	`Idle_State`
`Connect`	Always	`Enabled = TRUE`	`Idle_State`
`Disconnect`	Always	`Enabled = FALSE`	`Idle_State`
`Write`	Always	Error - not connected	`Idle_State`
`Timeout`	`Enabled`	Send `Req_Req_Pdu` Start re-transmission timer	`Idle_Req_State`
`Timeout`	else	No action	`Idle_State`

Idle_Req_State

Event	Condition	Action	Next state
`Ack_Rx`	`Enabled`	`Seq_Tx =` sequence number `Seq_Rx = 0` Start inactivity timer Connection established	`Data_State`
`Ack_Rx`	else	No action	`Idle_Req_State`
`Disc_Rx`	Always	`Reset()`	`Idle_State`
`Req_Rx`	`Enabled`	`Variant = SIBO` `SeqTx = 0` `Seq_Rx = 0` Send `Ack_Pdu` with sequence number `Seq_Rx` Start inactivity timer Connection established	`Data_State`
`Req_Rx`	else	No action	`Idle_Req_State`
`Req_Req_Rx`	`Enabled`	`Variant = EPOC` Send `Req_Con` with `Magic` as data Start re-transmission timer `Retries = 4`	`Idle_Ack_State`
`Req_Req_Rx`	else	No action	`Idle_Req_State`
`Req_Con_Rx`	Always	No action	`Idle_Req_State`
`Data_Rx`	Always	No action	`Idle_Req_State`
`Connect`	Always	Error - already enabled	`Idle_Req_State`
`Disconnect`	Always	`Enabled = FALSE` Send `Disc_Pdu` `Reset()`	`Idle_State`
`Write`	Always	Error - not connected	`Idle_Req_State`
`Timeout`	`Enabled`	Try next baud rate if attempting auto-baud rate identification Send `Req_Req_Pdu` Start re-transmission timer	`Idle_Req_State`
`Timeout`	else	`Reset()`	`Idle_State`

Idle_Ack_State

Event	Condition	Action	Next state
`Ack_Rx`	`Enabled`	`Seq_Tx =` sequence number `Seq_Rx = 0` Start inactivity timer Connection established	`Data_State`
`Ack_Rx`	else	No action	`Idle_Ack_State`
`Disc_Rx`	Always	`Reset()`	`Idle_State`
`Req_Rx`	`Enabled`	`Variant = SIBO` `SeqTx = 0` `Seq_Rx = 0` Send `Ack_Pdu` with sequence number `Seq_Rx` Start inactivity timer Connection established	`Data_State`
`Req_Rx`	else	No action	`Idle_Ack_State`
`Req_Req_Rx`	`Enabled`	`Variant = EPOC` Send `Req_Con` with `Magic` as data Start re-transmission timer `Retries = 4`	`Idle_Ack_State`
`Req_Req_Rx`	else	No action	`Idle_Ack_State`
`Req_Con_Rx`	`Enabled` and `(`magic number `!= Magic)`	`Variant = EPOC` `Seq_Tx = 0` `Seq_Rx = 0` Send `Ack_Pdu` with sequence number `Seq_Rx` Start inactivity timer Connection established	`Data_State`
`Req_Con_Rx`	else	No action	`Idle_Ack_State`
`Data_Rx`	Always	No action	`Idle_Ack_State`
`Connect`	Always	Error - already enabled	`Idle_Ack_State`
`Disconnect`	Always	`Enabled = FALSE` Send `Disc_Pdu` `Reset()`	`Idle_State`
`Write`	Always	Error - not connected	`Idle_Ack_State`
`Timeout`	`Enabled` and `(0 < Retries)`	`Retries = Retries - 1` Send `Req_Con` with `Magic` as data	`Idle_Ack_State`
`Timeout`	else	Reset	`Idle_State`

Data_State

Event	Condition	Action	Next state
`Ack_Rx`	Always	No action	`Data_State`
`Disc_Rx`	Always	`Reset()` Connection terminated	`Idle_State`
`Req_Rx`	Always	`Reset()` Connection terminated	`Idle_State`
`Req_Req_Rx`	Always	`Reset()` Connection terminated	`Idle_State`
`Req_Con_Rx`	Always	`Reset()` Connection terminated	`Idle_State`
`Data_Rx`	sequence number `== Inc(Seq_Rx)`	`Seq_Rx = Inc(Seq_Rx)` Send `Ack_Pdu` with sequence number `Seq_Rx` Start inactivity timer	`Data_State`
`Data_Rx`	else	Send `Ack_Pdu` with sequence number `Seq_Rx`	`Data_State`
`Connect`	Always	Error - already enabled	`Data_State`
`Disconnect`	Always	`Enabled = FALSE` Send `Disc_Pdu` `Reset()` Connection terminated	`Idle_State`
`Write`	Always	`Seq_Tx = Inc(Seq_Tx)` Send `Data_Pdu` with sequence number `Seq_Tx` Start re-transmission timer `Retries = 8`	`Data_Ack_State`
`Timeout`	Always	Send `Disc_Pdu` `Reset()` Connection terminated	`Idle_State`

Data_Ack_State

Event	Condition	Action	Next state
`Ack_Rx`	sequence number `== Seq_Tx`	Start inactivity timer	`Data_State`
`Ack_Rx`	else	No action	`Data_Ack_State`
`Disc_Rx`	Always	`Reset()` Connection terminated	`Idle_State`
`Req_Rx`	Always	`Reset()` Connection terminated	`Idle_State`
`Req_Req_Rx`	Always	`Reset()` Connection terminated	`Idle_State`
`Req_Con_Rx`	Always	`Reset()` Connection terminated	`Idle_State`
`Data_Rx`	sequence number `== Inc(Seq_Rx)`	`Seq_Rx = Inc(Seq_Rx)` Send `Ack_Pdu` with sequence number `Seq_Rx` Start re-transmission timer	`Data_Ack_State`
`Data_Rx`	else	Send `Ack_Pdu` with sequence number `Seq_Rx`	`Data_Ack_State`
`Connect`	Always	Error - already enabled	`Data_Ack_State`
`Disconnect`	Always	`Enabled = FALSE` Send `Disc_Pdu` `Reset()` Connection terminated	`Idle_State`
`Write`	Always	Error - connection busy	`Data_Ack_State`
`Timeout`	`0 < Retries`	`Retries = Retries - 1` Send `Data_Pdu` with sequence number `Seq_Tx` Start re-transmission timer	`Data_Ack_State`
`Timeout`	else	Send `Disc_Pdu` `Reset()` Connection terminated	`Idle_State`

PLP Mode on Erisson R380

The Ericsson R380 incorporates a modem, so it is necessary to reconfigure the serial port for PLP use.

Starting PLP

An "AT" command is used to start the PLP connection:

From host From R380 Description

0x41 0x54 0x2a 0x45 0x53 0x59 0x4e 0x3d 0x31 0x0d Request PLP mode: AT*ESYN=1

0x41 0x54 0x2a 0x45 0x53 0x59 0x4e 0x3d 0x31 0x0d Echo command: AT*ESYN=1

0x0d 0x0a 0x4f 0x4b 0x0d 0x0a Acknowledge command: OK

0x11 0x11 Start PLP operation

From host	From R380	Description
`0x41 0x54 0x2a 0x45 0x53 0x59 0x4e 0x3d 0x31 0x0d`		Request PLP mode: `AT*ESYN=1`
	`0x41 0x54 0x2a 0x45 0x53 0x59 0x4e 0x3d 0x31 0x0d`	Echo command: `AT*ESYN=1`
	`0x0d 0x0a 0x4f 0x4b 0x0d 0x0a`	Acknowledge command: `OK`
	`0x11 0x11`	Start PLP operation

A peer to peer PLP connection is then established as described above.

Ending PLP

Following the Req_Req_Pdu the Erisson R380 sends a single DC1 character and returns to "AT" mode.

Session Layer

The Network Control Protocol (NCP) provides multiplexed communication channels between multiple clients and servers. It also supports fragmentation and recombination to allow arbitrary sized messages to be transmitted via data link layer frames that have a maximum permitted data field size.

Channels

Numbered channels are used to address frames to the appropriate process. The SIBO variant supports 8 simultaneous channels, but the EPOC variant increases this to 256. Channel 0 is always used for the NCP control channel, and channel 1 is always used for the special LINK channel used to register additional servers. Other channels are dynamically allocated as required.

Frame Formats

The general format for an NCP frame is:

Bytes 1 1 1 n

Data Destination channel Source channel Frame type Data

The channel pair (Source channel and Destination channel) specifies a connection between two processes. PDUs for channel 0 are expedited; they must be delivered and processed before any PDUs for other channels.

Command Frames

Command frames are always send to channel 0. The interpretation of the source channel is defined below for each command.

XOFF Frame

Bytes	1	1	1
Data	`0x00`	Channel	`0x01`

Block transmission of frames to the specified Channel until an XON frame is received. All channels default to being unblocked.

XON Frame

Bytes	1	1	1
Data	`0x00`	Channel	`0x02`

Unblock transmission of frames to the specified Channel. This reverses the effect on an XOFF frame.

Connect Frame

Bytes	1	1	1	n
Data	`0x00`	Client channel	`0x03`	Server name

A client is requesting connection to the server called Server name. A Connect Response frame is always sent in reply.

The maximum length of the server name field is 16 characters, including the NUL terminator.

Connect Response Frame

Bytes	1	1	1	1	1
Data	`0x00`	Server channel	`0x04`	Client channel	Status code

This is the reply sent in response to a Connect frame. The source channel is set to the server's channel if the connection was successful, or 0 for the control channel otherwise. The Status code is zero (E_SIBO_NONE) for a successful connection, or non-zero (E_SIBO_FILE_NXIST) if the server cannot be found.

Connection Termination Frame

Bytes	1	1	1
Data	`0x00`	Server channel	`0x05`

A client has disconnected from the specified server.

NCP Information Frame

Bytes	1	1	1	1	4
Data	`0x00`	`0x00`	`0x06`	Version	ID

This is the first frame that is sent by an invocation of NCP when a connection has been established. It enables the NCP and servers to adapt to the capabilities of the other device.

The following Version numbers are currently used:

Version Description

0x02 SIBO (old)

0x03 SIBO (new)

0x06 EPOC (ER3)

0x10 EPOC (ER5)

Version	Description
`0x02`	SIBO (old)
`0x03`	SIBO (new)
`0x06`	EPOC (ER3)
`0x10`	EPOC (ER5)

For maximum compatibility it is recommended that 6 be used if the data link layer has identified the EPOC variant of the protocol, and 2 be used otherwise. The behaviour of servers should be controlled by the received version number.

The ID is a unique identifier for the current NCP process. It does not appear to be used for anything, so it is probably sufficient to generate a pseudo-random number.

Disconnection Frame

Bytes	1	1	1	1
Data	`0x00`	Server channel	`0x07`	Client channel

The specified server has disconnected the specified client.

NCP Termination Frame

Bytes	1	1	1
Data	`0x00`	Channel	`0x08`

The NCP has shut down.

Data Frames

As described above, the NCP fragments and recombines messages to fit within the data link layer's maximum data field size. Zero or more Partial frames are sent followed by a Complete frame to transmit the full message.

Complete Frame

Bytes	1	1	1	n
Data	Destination channel	Source channel	`0x01`	Data

A Complete frame serves as either the final frame in a series of Partial frames which make a single large frame, or as a single frame which fits into the data link layer's frame size.

Partial Frame

Bytes	1	1	1	n
Data	Destination channel	Source channel	`0x02`	Data

A Partial frame is sent as one of a series that should be re-assembled to form a larger frame.

Connection Sequence

The following general sequence of frames are exchanged after a connection has been established:

From device 1 From device 2

NCP Information frame NCP Information frame

Connect frame for LINK.* Connect frame for LINK.*

Connect frame for other servers Connect frame for other servers

Connect Response frames Connect Response frames

From device 1	From device 2
NCP Information frame	NCP Information frame
Connect frame for `LINK.*`	Connect frame for `LINK.*`
Connect frame for other servers	Connect frame for other servers
Connect Response frames	Connect Response frames

Due to the asynchronous nature of the protocol, the Connect Response frames may occur at any time after the corresponding Connect frame has been sent. Also, with the exception of the LINK.* connection, the Connect frames may be sent at any time to connect to additional servers.

Disconnection Sequence

There may not be an opportunity to perform a controlled disconnection sequence, for example if the cable is physically disconnected, but the ideal sequence would be:

From disconnecting device

Disconnection frames and Connection Termination frames for each connection

NCP Termination frame

From disconnecting device
Disconnection frames and Connection Termination frames for each connection
NCP Termination frame

Note that no confirmations are received; it is the responsibility of the data link layer to ensure that the frames are communicated without errors. Connect frames received during this sequence should be ignored; the remote device may attempt to re-establish terminated connections.

Presentation Layer

Named servers provide a set of related services, such as remote file system access. All operations consist of a command sent by the client and a reply from the server.

LINK Server

The LINK server is closely associated with the NCP; it is always connected before any other servers, always uses channel 1, and allows allows additional servers to be registered. The name "LINK.*" is used in the Connect frame to start the LINK server.

Command Frames

LINK only supports a single command.

Link Register Command

Command:

Bytes 1 2 n

Data 0x00 Operation ID Server name

Bytes	1	2	n
Data	`0x00`	Operation ID	Server name

or:

Bytes 1 2 n 1 1 4

Data 0x00 Operation ID Server name Major version Minor version Build

Bytes	1	2	n	1	1	4
Data	`0x00`	Operation ID	Server name	Major version	Minor version	Build

Reply:

Bytes 1 2 2 2 n

Data 0x01 Operation ID Status code ??? Server name

Bytes	1	2	2	2	n
Data	`0x01`	Operation ID	Status code	???	Server name

This command is used to register a server for connection using a Connect frame. It should normally be tried after a connection has been unsuccessfully attempted.

The Operation ID is a unique identifier used to verify that commands and replies match. A different value within the range 0 to 65535 should be generated for each command, and the reply checked to confirm that it contains the same value.

The Server name in the command is the name of the required server, but without any extension specified. If the reply contains a valid Server name (at least 4 characters long and not containing any control characters) then that should be used as the name within the Connect frame, otherwise ".*" should be appended to the name specified in the command.

The second form of the command allows a minimum version of the server to be specified. The two forms behave identically if the Version and Build are both set to 0.

A typical sequence of operations would be:

From client From server

Connect frame for SYS$RPCS.*

Connect Response frame indicating failure

Link Register command for SYS$RPCS

Link Register response specifying SYS$RPCS.*

Connect frame for SYS$RPCS.*

Connect Response frame indicating success

From client	From server
Connect frame for `SYS$RPCS.*`
	Connect Response frame indicating failure
Link Register command for `SYS$RPCS`
	Link Register response specifying `SYS$RPCS.*`
Connect frame for `SYS$RPCS.*`
	Connect Response frame indicating success

RPCS Server

The RPCS server provides Remote Command Services. This supports general operations, such as launching and terminating processes. The name "SYS$RPCS.*" is used in the Connect frame to start the RPCS server. However, as mentioned above, it may be necessary to use the Link Register command to register the server first. On some SIBO devices, the RPCS server is not present by default, and is normally downloaded as M:\SYS$RPCS.IMG by either RCOM or PsiWin.

Note that the Ericsson R380 uses the name "SYS$RPCSU.*" instead, where the additional "U" in the name indicates that Unicode strings are used.

Command Frames

All RPCS command frames generate a response frame. The first byte of the response is a result code; this is always a SIBO status code, even with the EPOC variant of the protocol. However, the SIBO variant uses the SIBO character set for any text strings, and the EPOC variant uses the EPOC character set.

NCP_QUERY_SUPPORT

Command:

Bytes 1 1 1

Data 0x00 Major version Minor version

Reply:

Bytes 1 1 1

Data Status code Major version Minor version

Exchange NCP version numbers.

All existing implementations use a Major version of 1, with the Minor version varying between 1 and 30.

NCP_EXEC_PROGRAM

Command:

Bytes 1 128 1 n

Data 0x01 Program name Arguments length Arguments

Bytes	1	128	1	n
Data	`0x01`	Program name	Arguments length	Arguments

Reply:

Bytes 1

Data Status code

Bytes	1
Data	Status code

Start a copy of Program name with the specified Arguments.

If the Program name is shorter than 128 characters then it is padded to 128 characters with 0 bytes, otherwise the field is extended as required. The Arguments length field specifies the length of the Arguments string, excluding the terminator character.

NCP_QUERY_DRIVE

Command:

Bytes 1 1

Data 0x02 Drive letter

Bytes	1	1
Data	`0x02`	Drive letter

Reply:

Bytes 1 Repeated fields:

n_i m_i

Data Status code Program name Arguments

List the programs with open files on the specified drive.

The EPOC variant lists all applications, regardless of which drive they are using. The result is a list of Program name and Argument pairs; one for each open program.

NCP_STOP_PROGRAM

Command:

Bytes 1 n

Data 0x03 Program name

Reply:

Bytes 1

Data Status code

Attempt to terminate the specified process.

This may result in the application opening a dialogue box to allow any modifications to be saved. NCP_PROG_RUNNING can be used to detect when the process has been stopped.

NCP_PROG_RUNNING

Command:

Bytes 1 n

Data 0x04 Program name

Reply:

Bytes 1

Data Status code

Check whether the specified process is running.

This returns E_SIBO_NONE if the process is running, or E_SIBO_FILE_NXIST otherwise.

NCP_FORMAT_OPEN

Command:

Bytes 1 n

Data 0x05 Device name

Reply:

Bytes 1 2 2

Data Status code Handle Count

Initiate formatting a drive.

This is a slow process, so NCP_FORMAT_READ should be called Count times with the returned Handle to progress the format.

NCP_FORMAT_READ

Command:

Bytes 1 2

Data 0x06 Handle

Reply:

Bytes 1

Data Status code

Continue formatting a drive.

The Handle returned by NCP_FORMAT_OPEN must be passed to specify the operation to progress.

NCP_GET_UNIQUE_ID

Command:

Bytes 1 n

Data 0x07 Device name

Reply:

Bytes 1 4

Data Status code Unique ID

Read the Unique ID for the specified removable device.

NCP_GET_OWNER_INFO

Command:

Bytes 1

Data 0x08

Reply:

Bytes 1 n

Data Status code Owner information (not NUL terminated)

Read the user information.

The returned Owner information is plain text; any formatting is stripped.

NCP_GET_MACHINE_TYPE

Command:

Bytes 1

Data 0x09

Reply:

Bytes 1 2

Data Status code Machine type

Read the type of the remote machine.

The following Machine type numbers are currently used:

Machine type Description

0x00 Unknown

0x01 PC

0x02 MC

0x03 HC

0x04 Series 3

0x05 Series 3a, 3c, or 3mx

0x06 Workabout

0x07 Sienna

0x08 Series 3c

0x20 Series 5

0x21 WinC

Be careful; some of these values are untested.

NCP_GET_CMD_LINE

Command:

Bytes 1 n

Data 0x0a Process name

Reply:

Bytes 1 n

Data Status code Program name

or:

Bytes 1 n 1 m

Data Status code Program name m Command line (not NUL terminated)

or:

Bytes 1 n 256 - n m 40 - m

Data Status code Program name m Command line ???

Read the Command line for Process name.

The first form of the reply is used if there is no open file. The other two forms are used by the EPOC and SIBO variants respectively.

NCP_STOP_FILE

Command:

Bytes 1 n

Data 0x0b File name

Reply:

Bytes 1 n

Data Status code Process name

Find the Process name of the program using the named file.

NCP_GET_MACHINE_INFO

Command:

Bytes 1

Data 0x64

Reply:

Bytes 1 4 1 1 2 8 16 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 88

Data Status code Machine type Major ROM version Minor ROM version ROM build Reserved Machine name Display width Display height Machine UID low Machine UID high Time low Time high Country code UTC offset DST DST zone Main battery inserted low Main battery inserted high Main battery status Main battery used low Main battery used high Main battery current Main battery used power Main battery voltage Main battery max voltage Backup battery status Backup battery voltage Backup battery maximum voltage External power Backup battery used low Backup battery used high ??? RAM size ROM size RAM maximum free RAM free RAM disk size Registry size ROM reprogrammable Language Reserved

This command is only supported by the EPOC variant of the protocol.

See NCP_GET_MACHINE_TYPE for a description of the possible Machine type values.

The Major ROM version, Minor ROM version, and ROM build fields combine to give the version number of the operating system. This is typically displayed with the Major ROM version followed by a decimal point, Minor ROM version using two digits, and finally the ROM build in brackets. All values are displayed in decimal.

The Machine name is a string giving a textual description of the machine type and revision.

The Display width and Display height indicate the size of the LCD in pixels.

The Machine UID low and Machine UID high fields combine to form a 64 bit unique identifier for this machine.

See NCP_SET_TIME for a description of the Time low, Time high, Country code, UTC offset, DST and DST zone values.

The Main battery inserted low and Main battery inserted high fields combine to form a 64 bit date specifying when the main batteries were inserted, specified as the number of micro-seconds since 00:00 on 1st January 1.

Main battery status gives the condition of the main batteries. See RFSV32_VOLUME for a description of the possible values.

The Main battery used low and Main battery used high fields combine to form a 64 bit value giving the number of micro-seconds that the main battery has been used.

Main battery current is the main battery current in milli-amps.

Main battery used power is the integrated main battery usage in mA-seconds.

Main battery voltage and Main battery max voltage give the current and maximum main battery voltages in milli-volts.

Backup battery status gives the condition of the backup batteries. See RFSV32_VOLUME for a description of the possible values.

Backup battery voltage and Backup battery maximum voltage give the current and maximum backup battery voltages in milli-volts.

The External power field indicates whether the machine is operating on external power.

The Backup battery used low and Backup battery used high fields combine to form a 64 bit value giving the number of micro-seconds that the backup battery has been used.

RAM size and ROM size give the total size of ROM and RAM fitted.

RAM maximum free and RAM free give the maximum and current free RAM in bytes.

RAM disk sizeis the current size of the internal RAM disk in bytes.

Registry size is the current size of the registry in bytes.

The ROM reprogrammable field indicates whether the ROM can be modified.

The Language may be one of the following:

Language Description

0x00 Test

0x01 UK English

0x02 French

0x03 German

0x04 Spanish

0x05 Italian

0x06 Swedish

0x07 Danish

0x08 Norwegian

0x09 Finnish

0x0A American English

0x0B Swiss French

0x0C Swiss German

0x0D Portuguese

0x0E Turkish

0x0F Icelandic

0x10 Russian

0x11 Hungarian

0x12 Dutch

0x13 Belgian Flemish

0x14 Australian English

0x15 Belgian French

0x16 Austrian German

0x17 New Zealand English

0x18 International French

0x19 Czech

0x1A Slovak

0x1B Polish

0x1C Slovenian

0x1D Taiwan Chinese

0x1E Hong Kong Chinese

0x1F RPC Chinese

0x20 Japanese

0x21 Thai

NCP_CLOSE_HANDLE

Command:

Bytes 1 2

Data 0x65 Handle

Reply:

Bytes 1

Data Status code

Close a previously opened resource Handle. This command is only supported by the EPOC variant of the protocol.

NCP_REG_OPEN_ITER

Command:

Bytes 1 ???

Data 0x66 ???

Reply:

Bytes 1 ???

Data Status code ???

This command is only supported by the EPOC variant of the protocol.

NCP_REG_READ_ITER

Command:

Bytes 1 ???

Data 0x67 ???

Reply:

Bytes 1 ???

Data Status code ???

This command is only supported by the EPOC variant of the protocol.

NCP_REG_WRITE

Command:

Bytes 1 ???

Data 0x68 ???

Reply:

Bytes 1 ???

Data Status code ???

This command is only supported by the EPOC variant of the protocol.

NCP_REG_READ

Command:

Bytes 1 ???

Data 0x69 ???

Reply:

Bytes 1 ???

Data Status code ???

This command is only supported by the EPOC variant of the protocol.

NCP_REG_DELETE

Command:

Bytes 1 ???

Data 0x6a ???

Reply:

Bytes 1 ???

Data Status code ???

This command is only supported by the EPOC variant of the protocol.

NCP_SET_TIME

Command:

Bytes 1 4 4 4 4 4 4

Data 0x6b Time low Time high Country code UTC offset DST DST zone

Reply:

Bytes 1

Data Status code

Set the clock. This command is only supported by the EPOC variant of the protocol.

The Time low and Time high fields combine to form a 64 bit date, specified as the number of micro-seconds since 00:00 on 1st January 1 in the home time zone.

The Country code indicates the country of the home time zone. This is 0 for most countries, but should probably be the international dial code.

The UTC offset is the number of seconds offset of the home time zone from UTC.

The DST consists of a combination of the following flags, specifying which zones daylight saving time is active:

DST zone Description

0x00000000 None

0x00000001 European

0x00000002 Northern

0x00000004 Southern

0x40000000 Home

The DST zone is a single flag, from those listed above, specifying which DST zone the home time zone is part of.

The easiest way to use this command is to read the various time zone and DST fields using NCP_GET_MACHINE_INFO and just change the Time low and Time high fields to the new time.

NCP_CONFIG_OPEN

Command:

Bytes 1 ???

Data 0x6c ???

Reply:

Bytes 1 ???

Data Status code ???

This command is only supported by the EPOC variant of the protocol.

NCP_CONFIG_READ

Command:

Bytes 1 ???

Data 0x6d ???

Reply:

Bytes 1 ???

Data Status code ???

This command is only supported by the EPOC variant of the protocol.

NCP_CONFIG_WRITE

Command:

Bytes 1 ???

Data 0x6e ???

Reply:

Bytes 1 ???

Data Status code ???

This command is only supported by the EPOC variant of the protocol.

NCP_QUERY_OPEN

Command:

Bytes 1 1

Data 0x6f Drive letter

Reply:

Bytes 1 2

Data Status code Handle

Start a query to read the files open on the specified drive. This command is only supported by the EPOC variant of the protocol.

NCP_QUERY_READ should be called repeatedly with the returned Handle to read the details, and NCP_CLOSE_HANDLE should be called to close the Handle when finished.

NCP_QUERY_READ

Command:

Bytes 1 2

Data 0x70 Handle

Reply:

Bytes 1 Repeated fields:

n_i m_i

Data Status code Program name Arguments

List the programs with open files on the specified drive. This command is only supported by the EPOC variant of the protocol.

NCP_QUERY_OPEN should be used to obtain the Handle. The result is a list of Program name and Argument pairs; one for each open program. This should be called repeatedly until no further details are returned.

NCP_QUIT_SERVER

Command:

Bytes 1

Data 0xff

Reply:

Bytes 1

Data Status code

Quit the RPCS server.

It is not necessary to use this command; use of the Connection Termination frame is adequate.

RFSV Server

The RFSV server provides Remote File Services. This provides a remote interface that behaves similarly to local file accesses; files must be opened before they can be read or written, and a sequential file pointer is maintained for each open file. A current directory is also maintained, allowing use of relative file names.

The name "SYS$RFSV.*" is used in the Connect frame to start the RFSV server. The Ericsson R380 uses the name "SYS$RFSVU.*" instead, where the additional "U" in the name indicates that Unicode strings are used.

The version number specified in the NCP Information frame selects the RFSV version; a value of 6 or higher is required to use the EPOC variant, otherwise the SIBO variant is used.

SIBO Command Frames

All RFSV command frames have the following general format:

Bytes 2 2 n

Data Reason code n Request data

The maximum length of Request data is 852 bytes, leading to a maximum command frame size of 856 bytes.

All RFSV reply frames have the following general format:

Bytes 2 2 2 n

Data 0x2a n + 2 Status code Reply data

The Status code is a SIBO status code.

The maximum length of Reply data is 852 bytes, leading to a maximum reply frame size of 858 bytes. To make allowance for possibly buggy implementations, it is recommended that at most 640 bytes of data are read or written to a file in a single operation, but all received frames up to the maximum size of 858 bytes should be accepted.

The SIBO character set is used for any text strings.

RFSV16_FOPEN

Command:

Bytes 2 2 2 n

Data 0x00 Frame length Mode File name

Reply:

Bytes 2 2 2 2

Data 0x2a Frame length Status code Handle

Open File name for reading or writing via the returned Handle.

The Mode consists of one of the following operations:

Mode Description

0x0000 Open an existing file

0x0001 Create a new file

0x0002 Create a new file, or truncate an existing file to zero length

0x0003 Append to an existing file

0x0004 Create a new file with a unique name

combined with one of these stream types:

Mode Description

0x0000 Open as a binary stream

0x0010 Open as a text stream

0x0020 Open as a binary record

0x0030 Open as a directory record

0x0040 Open as a format

0x0050 Open as a device list

0x0060 Open as a node list

and any of the following flags:

Mode Description

0x0100 Open for read and write access

0x0200 Open for random access

0x0400 Open for sharing

RFSV16_FCLOSE must be used to close the Handle when it is no longer required.

RFSV16_FCLOSE

Command:

Bytes 2 2 2

Data 0x02 Frame length Handle

Reply:

Bytes 2 2 2

Data 0x2a Frame length Status code

Close the Handle previously opened using RFSV16_FOPEN or RFSV16_OPENUNIQUE.

RFSV16_FREAD

Command:

Bytes 2 2 2 2

Data 0x04 Frame length Handle Length

Reply:

Bytes 2 2 2 n

Data 0x2a Frame length Status code Data

Read Length bytes from the file identified by Handle.

The reply contains the Length bytes of data read.

RFSV16_FDIRREAD

Command:

Bytes 2 2 2

Data 0x06 Frame length Handle

Reply:

Bytes 2 2 2 2 Repeated fields:

2 2 4 4 4 n_i

Data 0x2a Frame length Status code Buffer length Version Attributes Size Modified Reserved File name

Read entries from the directory specified by Handle.

The reply contains details of entries from the specified directory. To read all of the directory entries this operation should be repeated until the returned Status code is E_SIBO_FILE_EOF.

The Buffer length is the length of the repeated fields, i.e. Frame length - 4.

The Attrubutes consists of a combination of the following flags:

Attribute Description

0x0001 Writeable

0x0002 Hidden

0x0004 System

0x0008 Volume label

0x0010 Directory

0x0020 Modified

0x0100 Readable

0x0200 Executable

0x0400 Stream

0x0800 Text

The Size is simply the length of the file in bytes.

The Modified date is specified as the number of seconds since 13:00 on 1st January 1970. This is always a multiple of two.

RFSV16_FDEVICEREAD

Command:

Bytes 2 2 2

Data 0x08 Frame length Handle

Reply:

Bytes 2 2 2 2 2 2 4 4 n 2 16

Data 0x2a Frame length Status code Version Media type Removable Size Free Volume label Battery status Reserved

Read information about the device specified by Handle.

The Media type consists of a type:

Media type Description

0x0000 Not a known type

0x0001 Floppy disk

0x0002 Hard disk

0x0003 Flash disk

0x0004 RAM

0x0005 ROM

0x0006 Write protected

combined with any of the following flags:

Media type Description

0x0800 Formattable

0x1000 Dual density

0x2000 Internal

0x4000 Dynamic

0x8000 Compressible

The Removable flag is non-zero for a removable device, or zero otherwise.

Size and Free give the total size and the remaining free space on the device.

The Battery status may be one of the following:

Media type Description

0 Dead

1 Very low

2 Low

3 Good

RFSV16_FWRITE

Command:

Bytes 2 2 2 n

Data 0x0a Frame length Handle Data

Reply:

Bytes 2 2 2

Data 0x2a Frame length Status code

Write Data to the file identified by Handle.

The number of bytes is not explicitly specified; this is inferred from the size of the frame.

RFSV16_FSEEK

Command:

Bytes 2 2 2 4 2

Data 0x0c Frame length Handle Seek offset Sense

Reply:

Bytes 2 2 2 4

Data 0x2a Frame length Status code New offset

Reposition the sequential file pointer for the file specified by Handle.

The interpretation of the signed New offset value depends on the Sense specified:

Sense Description

0x0001 Absolute position from the start of the file

0x0002 Offset from the current position

0x0003 Offset from the end of the file

0x0004 Read the current position without changing it

0x0005 Set

0x0006 Rewind

The value of the sequential file pointer after the seek is returned as New offset.

RFSV16_FFLUSH

Command:

Bytes 2 2 2

Data 0x0e Frame length Handle

Reply:

Bytes 2 2 2

Data 0x2a Frame length Status code

Flush to disk any cached data for the file specified by Handle.

RFSV16_FSETEOF

Command:

Bytes 2 2 2 4

Data 0x10 Frame length Handle Size

Reply:

Bytes 2 2 2

Data 0x2a Frame length Status code

Set the length of the file specified by Handle to Size bytes.

RFSV16_RENAME

Command:

Bytes 2 2 n m

Data 0x12 Frame length Source name Destination name

Reply:

Bytes 2 2 2

Data 0x2a Frame length Status code

Rename Source name to Destination name.

RFSV16_DELETE

Command:

Bytes 2 2 n

Data 0x14 Frame length File name

Reply:

Bytes 2 2 2

Data 0x2a Frame length Status code

Delete File name.

RFSV16_FINFO

Command:

Bytes 2 2 n

Data 0x16 Frame length File name

Reply:

Bytes 2 2 2 2 2 4 4 4

Data 0x2a Frame length Status code Version Attributes Size Modified Reserved

Read details about File name.

See RFSV16_FDIRREAD for a description of the returned values.

RFSV16_SFSTAT

Command:

Bytes 2 2 2 2 n

Data 0x18 Frame length Set Mask File name

Reply:

Bytes 2 2 2

Data 0x2a Frame length Status code

Set the Mask attributes of File name to the state specified by Set.

See RFSV16_FDIRREAD for a description of the possible attribute values.

If both the Set and Mask values are both specified as 0x0008, indicating a volume label, then this changes the volume label. As an example, if File name is C:\FOOBAR then it will set the volume label for drive C: to FOOBAR.

RFSV16_PARSE

Command:

Bytes 2 2 n

Data 0x1a Frame length File name

Reply:

Bytes 2 2 2 n

Data 0x2a Frame length Status code Parsed name

Parse File name to give Parsed name.

This can be used to remove wildcards from a file name.

RFSV16_MKDIR

Command:

Bytes 2 2 n

Data 0x1c Frame length Directory name

Reply:

Bytes 2 2 2

Data 0x2a Frame length Status code

Create a new directory called Directory name.

RFSV16_OPENUNIQUE

Command:

Bytes 2 2 2 n

Data 0x1e Frame length Mode File name

Reply:

Bytes 2 2 2 2 n

Data 0x2a Frame length Status code Handle Opened name

Open File name for reading or writing via the returned Handle.

See RFSV16_FOPEN for a description of the possible Mode values.

The actual name of the file opened is returned as Opened name. This is useful when requesting a unique file to be opened.

RFSV16_STATUSDEVICE

Command:

Bytes 2 2 n

Data 0x20 Frame length Device name

Reply:

Bytes 2 2 2 2 2 2 4 4 n 2 16

Data 0x2a Frame length Status code Version Media type Removable Size Free Volume label Battery status Reserved

Read the status of the device specified by Device name.

See RFSV16_FDEVICEREAD for details of the returned values.

RFSV16_PATHTEST

Command:

Bytes 2 2 n

Data 0x22 Frame length File name

Reply:

Bytes 2 2 2

Data 0x2a Frame length Status code

Check if File name specifies a valid path.

RFSV16_STATUSSYSTEM

Command:

Bytes 2 2 n

Data 0x24 Frame length File system

Reply:

Bytes 2 2 2 2 2 2

Data 0x2a Frame length Status code Version Type Formattable

Read the status of the specified File system.

RFSV16_CHANGEDIR

Command:

Bytes 2 2 n

Data 0x26 Frame length Directory name

Reply:

Bytes 2 2 2

Data 0x2a Frame length Status code

Change the current directory to Directory name.

RFSV16_SFDATE

Command:

Bytes 2 2 4 n

Data 0x28 Frame length Modified File name

Reply:

Bytes 2 2 2

Data 0x2a Frame length Status code

Set the Modified date of File name.

The date is specified as number of seconds since 13:00 on 1st January 1970.

EPOC Command Frames

All RFSV command frames have the following general format:

Bytes 2 2 n

Data Reason code Operation ID Request data

All RFSV reply frames have the following general format:

Bytes 2 2 4 n

Data 0x11 Operation ID Status code Reply data

The Status code is an EPOC status code.

The maximum frame size is not well defined, but to avoid potential incompatibilities it is recommended that at most 2048 bytes of data are read or written to a file in a single operation, but all received frames up to a maximum size of 2079 bytes should be accepted.

Strings are usually passed as a 2 byte length followed by the data using the EPOC character set. Strings are not NUL terminated. The most significant bit of the length field may be set to indicate Unicode strings.

RFSV32_CLOSE_HANDLE

Command:

Bytes 2 2 4

Data 0x01 Operation ID Handle

Reply:

Bytes 2 2 4

Data 0x11 Operation ID Status code

Close the Handle previously opened using RFSV32_OPEN_DIR, RFSV32_OPEN_FILE, RFSV32_TEMP_FILE, RFSV32_CREATE_FILE, RFSV32_REPLACE_FILE or RFSV32_OPEN_DIR_UID.

RFSV32_OPEN_DIR

Command:

Bytes 2 2 4 2 + n

Data 0x10 Operation ID Attributes File name

Reply:

Bytes 2 2 4 4

Data 0x11 Operation ID Status code Handle

Open a Handle to read files that match the wildcarded File name.

RFSV32_READ_DIR should be used to read the list of matching files. The description for that command also details the possible Attributes that may be specified.

RFSV32_READ_DIR

Command:

Bytes 2 2 4

Data 0x12 Operation ID Handle

Reply:

Bytes 2 2 4 Repeated fields:

0 to 3 4 4 4 4 4 4 4 4 4 n_i 0 to 3 m_i

Data 0x11 Operation ID Status code Alignment Short name length Attributes Size Modified low Modified high UID 1 UID 2 UID 3 Long name length Long name Alignment Short name

Read directory entries specified by the Handle previously opened using RFSV32_OPEN_DIR.

The reply contains details of entries from the specified directory. To read all of the directory entries this operation should be repeated until the returned Status code is E_EPOC_EOF.

Two names are returned for each file. The Long name is the actual name of the file, and the Short name is the SIBO compatible version. Unlike the other commands, the lengths of these strings are specified by 4 byte values. If the Short name length is 0 then the Short name field is omitted, and both names should be treated as being identical.

The Attributes consist of a combination of the following flags:

Attribute Description

0x0001 Read only

0x0002 Hidden

0x0004 System

0x0010 Directory

0x0020 Archive

0x0040 Volume label

0x0080 Normal

0x0100 Temporary

0x0800 Compressed

The Size is simply the length of the file in bytes.

The Modified low and Modified high fields combine to form a 64 bit modification date, specified as the number of micro-seconds since 00:00 on 1st January 1.

The UID 1, UID 2 and UID 3 fields are the first three words of the file, and indicate the type of data it contains. These fields are only valid if bit 28 (0x10000000) of the Attributes was passed to RFSV32_OPEN_DIR. The UIDs for some of the standard applications are:

Application UID 1 UID 2 UID 3

Word 0x10000037 0x1000006D 0x1000007F

Sheet 0x10000037 0x1000006D 0x10000088

Record 0x10000037 0x1000006D 0x1000007E

OPL 0x10000037 0x1000006D 0x10000085

Data 0x10000050 0x1000006D 0x10000086

Agenda 0x10000050 0x1000006D 0x10000084

Sketch 0x10000037 0x1000006D 0x1000007D

The two Alignment fields ensure that the offset for the start of the following field is a multiple of 4 bytes.

RFSV32_GET_DRIVE_LIST

Command:

Bytes 2 2

Data 0x13 Operation ID

Reply:

Bytes 2 2 4 26

Data 0x11 Operation ID Status code Drive list

Read the status of all drives.

A single byte is returned for each drive letter A: to Z:.

RFSV32_VOLUME

Command:

Bytes 2 2 4

Data 0x14 Operation ID Drive

Reply:

Bytes 2 2 4 4 4 4 4 4 4 4 4 4 4 n

Data 0x11 Operation ID Status code Media type Battery status Drive attributes Media attributes UID Size low Size high Free low Free high Volume label length Volume label

Read information about a single device.

The Drive is the number of the device, from 0 for A: to 25 for Z:.

The Media type may be one of the following:

Media type Description

0 Not present

1 Not a known type

2 Floppy disk

3 Hard disk

4 CD-ROM

5 RAM

6 Flash disk

7 ROM

8 Remote

The Battery status may be one of the following:

Battery status Description

0 Dead

1 Very low

2 Low

3 Good

The Drive attributes consists of the following flags:

Drive attribute Description

0x01 Local

0x02 ROM

0x04 Redirected

0x08 Substituted

0x10 Internal

0x20 Removable

The Media attributes consists of the following flags:

Media attribute Description

0x01 Variable size

0x02 Dual density

0x04 Formattable

0x08 Write protected

The Size low and Size high fields combine to give the 64 bit total size, and the Free low and Free high fields combine to give the 64 bit remaining free space on the device.

Unlike the other commands, the length of the Volume label string is specified by the 4 byte Volume label length.

RFSV32_SET_VOLUME_LABEL

Command:

Bytes 2 2 4 2 + n

Data 0x15 Operation ID Drive Volume label

Reply:

Bytes 2 2 4

Data 0x11 Operation ID Status code

Set the Volume label of a device.

The Drive is the number of the device, from 0 for A: to 25 for Z:.

RFSV32_OPEN_FILE

Command:

Bytes 2 2 4 2 + n

Data 0x16 Operation ID Mode File name

Reply:

Bytes 2 2 4 4

Data 0x11 Operation ID Status code Handle

Open File name for reading or writing via the returned Handle.

The Mode consists of one of the following sharing types:

Mode Description

0x0000 Exclusive access

0x0001 Share for read access

0x0002 Share for any access

combined with one of these stream types:

Mode Description

0x0000 Open as a binary stream

0x0020 Open as a text stream

and any of the following flags:

0X0200 Open for read and write access

RFSV32_TEMP_FILE

Command:

Bytes 2 2 4 2 + n

Data 0x17 Operation ID Mode File name

Reply:

Bytes 2 2 4 4 2 + n

Data 0x11 Operation ID Status code Handle Opened name

Create a new file with a unique file name for reading or writing via the returned Handle.

See RFSV32_OPEN_FILE for a description of the possible Mode values.

The actual name of the file opened is returned as Opened name.

RFSV32_READ_FILE

Command:

Bytes 2 2 4 4

Data 0x18 Operation ID Handle Length

Reply:

Bytes 2 2 4 n

Data 0x11 Operation ID Status code Data

Read Length bytes from the file identified by Handle.

The reply contains the Length bytes of data read.

RFSV32_WRITE_FILE

Command:

Bytes 2 2 4 n

Data 0x19 Operation ID Handle Data

Reply:

Bytes 2 2 4

Data 0x11 Operation ID Status code

Write Data to the file identified by Handle.

The number of bytes is not explicitly specified; this is inferred from the size of the frame.

RFSV32_SEEK_FILE

Command:

Bytes 2 2 4 4 4

Data 0x1a Operation ID Seek offset

Bytes	1	Repeated fields:
Bytes	1	n_i	m_i
Data	Status code	Program name	Arguments

Machine type	Description
`0x00`	Unknown
`0x01`	PC
`0x02`	MC
`0x03`	HC
`0x04`	Series 3
`0x05`	Series 3a, 3c, or 3mx
`0x06`	Workabout
`0x07`	Sienna
`0x08`	Series 3c
`0x20`	Series 5
`0x21`	WinC

Bytes	1	n	256 - n	m	40 - m
Data	Status code	Program name	m	Command line	???

Language	Description
`0x00`	Test
`0x01`	UK English
`0x02`	French
`0x03`	German
`0x04`	Spanish
`0x05`	Italian
`0x06`	Swedish
`0x07`	Danish
`0x08`	Norwegian
`0x09`	Finnish
`0x0A`	American English
`0x0B`	Swiss French
`0x0C`	Swiss German
`0x0D`	Portuguese
`0x0E`	Turkish
`0x0F`	Icelandic
`0x10`	Russian
`0x11`	Hungarian
`0x12`	Dutch
`0x13`	Belgian Flemish
`0x14`	Australian English
`0x15`	Belgian French
`0x16`	Austrian German
`0x17`	New Zealand English
`0x18`	International French
`0x19`	Czech
`0x1A`	Slovak
`0x1B`	Polish
`0x1C`	Slovenian
`0x1D`	Taiwan Chinese
`0x1E`	Hong Kong Chinese
`0x1F`	RPC Chinese
`0x20`	Japanese
`0x21`	Thai

Bytes	1	4	4	4	4	4	4
Data	`0x6b`	Time low	Time high	Country code	UTC offset	DST	DST zone

DST zone	Description
`0x00000000`	None
`0x00000001`	European
`0x00000002`	Northern
`0x00000004`	Southern
`0x40000000`	Home

Mode	Description
`0x0000`	Open an existing file
`0x0001`	Create a new file
`0x0002`	Create a new file, or truncate an existing file to zero length
`0x0003`	Append to an existing file
`0x0004`	Create a new file with a unique name

Mode	Description
`0x0000`	Open as a binary stream
`0x0010`	Open as a text stream
`0x0020`	Open as a binary record
`0x0030`	Open as a directory record
`0x0040`	Open as a format
`0x0050`	Open as a device list
`0x0060`	Open as a node list

Mode	Description
`0x0100`	Open for read and write access
`0x0200`	Open for random access
`0x0400`	Open for sharing

Attribute	Description
`0x0001`	Writeable
`0x0002`	Hidden
`0x0004`	System
`0x0008`	Volume label
`0x0010`	Directory
`0x0020`	Modified
`0x0100`	Readable
`0x0200`	Executable
`0x0400`	Stream
`0x0800`	Text

Bytes	2	2	2	2	2	2	4	4	n	2	16
Data	`0x2a`	Frame length	Status code	Version	Media type	Removable	Size	Free	Volume label	Battery status	Reserved

Media type	Description
`0x0000`	Not a known type
`0x0001`	Floppy disk
`0x0002`	Hard disk
`0x0003`	Flash disk
`0x0004`	RAM
`0x0005`	ROM
`0x0006`	Write protected

Media type	Description
`0x0800`	Formattable
`0x1000`	Dual density
`0x2000`	Internal
`0x4000`	Dynamic
`0x8000`	Compressible

Sense	Description
`0x0001`	Absolute position from the start of the file
`0x0002`	Offset from the current position
`0x0003`	Offset from the end of the file
`0x0004`	Read the current position without changing it
`0x0005`	Set
`0x0006`	Rewind

Bytes	2	2	4	2 + n
Data	`0x10`	Operation ID	Attributes	File name

Attribute	Description
`0x0001`	Read only
`0x0002`	Hidden
`0x0004`	System
`0x0010`	Directory
`0x0020`	Archive
`0x0040`	Volume label
`0x0080`	Normal
`0x0100`	Temporary
`0x0800`	Compressed

Application	UID 1	UID 2	UID 3
Word	`0x10000037`	`0x1000006D`	`0x1000007F`
Sheet	`0x10000037`	`0x1000006D`	`0x10000088`
Record	`0x10000037`	`0x1000006D`	`0x1000007E`
OPL	`0x10000037`	`0x1000006D`	`0x10000085`
Data	`0x10000050`	`0x1000006D`	`0x10000086`
Agenda	`0x10000050`	`0x1000006D`	`0x10000084`
Sketch	`0x10000037`	`0x1000006D`	`0x1000007D`

Media type	Description
`0`	Not present
`1`	Not a known type
`2`	Floppy disk
`3`	Hard disk
`4`	CD-ROM
`5`	RAM
`6`	Flash disk
`7`	ROM
`8`	Remote

Drive attribute	Description
`0x01`	Local
`0x02`	ROM
`0x04`	Redirected
`0x08`	Substituted
`0x10`	Internal
`0x20`	Removable

Media attribute	Description
`0x01`	Variable size
`0x02`	Dual density
`0x04`	Formattable
`0x08`	Write protected

Mode	Description
`0x0000`	Exclusive access
`0x0001`	Share for read access
`0x0002`	Share for any access