Version 1

Librarian Protocol

Overview

Each controller will have a single librarian which is responsible for storing all sequences. All other programs will request the sequences that it needs from the Librarian, using the sequence's title.

This arrangement will minimize disk usage and maximize reliability and flexibility.

The Librarian

The Librarian will maintain 3 separate libraries: one for sequences, one for messages, and one for animated graphics. Animated graphics are stored as sequences, but they are stored separately so that they can be conveniently used to build up sequences to display.

It is the Librarian's responsibility to ensure that it stores its libraries in a robust manner.

The Protocol

The Librarian Protocol is a variable-length packet based protocol which is initiated by a challenge-response authentication phase, followed by a versioning handshake.

The Librarian will listen for connections using this protocol on port 40101.

Note: unless otherwise specified, all multi-byte integral types are in network-order (i.e. big-endian).

Challenge-Response Authentication

The protocol begins with a challenge-response exchange using the "network password" of the controller (the network password is described in the Data Sources specificaiton).

The Librarian issues a unique 20 byte challenge. The correct response is the 20 byte SHA1 hash of the concatenation of the challenge and the secret password. (i.e. SHA1(challenge + password).) The initiator of the connection only gets one chance; if it does not return the correct response, the connection is terminated. Also, the connection is terminated if the complete response is not recieved within 90 seconds.

Handshake

The purpose of the handshake is to determine the version of the protocol to be used. The handshake packets do not contain a packet type because their required order make it redundant.

The handshake packets are, in order:

Librarian -> Client Handshake Packet
Byte Count Data Type Value Description
1 unsigned byte 0 The maximum version of the protocol which is supported.
Client -> Librarian Handshake Packet
Byte Count Data Type Value Description
1 unsigned byte 0 The version of the protocol to be used. This must be <= the maximum supported version sent by the Librarian. If the Librarian cannot support a version great enough, the client should simply drop the connection and report an error.

Normal Operation

This is normally a synchronous protocol, where the librarian only sends packets in response to packets from the client.

Inserting

In order to insert, the client sends one of:

If a sequence/message/graphic with the same title exists in the library, it is replaced with the one sent. (It is up to the client to ensure that the user really wants to do this.) Once the insertion is complete, the Librarian sends an Insertion Acknowledgement Packet. If the insertion fails, the Librarian instead sends a Insertion Failure Packet

Deleting

In order to delete, the client sends one of:

Once the deletion is complete, the Librarian sends an Deletion Acknowledgement Packet.

Fetching

In order to fetch, the client sends one of:

The Librarian responds with one of:

as appropriate. (while it is not necessary to reuse these packets, the metaphore of the Librarian inserting the requested sequence/message/graphic into the client works, and is about an efficient transport mechanism as any.)

Retrieving Library Information

To request information about a library, the client sends one of:

The Librarian then responds with one of:

as appropriate.


Appendix A. Packet Definitions

Sequence Insertion Packet
Byte Count Data Type Value Description
1 unsigned byte 0 Packet Type
variable Sequence This packet embeds the sequence which is to be inserted into the sequence library.
Message Insertion Packet
Byte Count Data Type Value Description
1 unsigned byte 1 Packet Type
variable Message This packet embeds the message which is to be deleted from the message library.
Graphics Insertion Packet
Byte Count Data Type Value Description
1 unsigned byte 2 Packet Type
variable Sequence This packet embeds the sequence which is to be inserted into the graphics library. (Animated graphics are nothing but sequences of images.)
Sequence Request Packet
Byte Count Data Type Value Description
1 unsigned byte 3 Packet Type
2 unsigned short The length of the sequence title
0-65,535 bytes The sequence title to be fetched, encoded in UTF-8.
Message Request Packet
Byte Count Data Type Value Description
1 unsigned byte 4 Packet Type
2 unsigned short The length of the message title
0-65,535 bytes The message title to be fetched, encoded in UTF-8.
Graphics Request Packet
Byte Count Data Type Value Description
1 unsigned byte 5 Packet Type
2 unsigned short The length of the graphic's title
0-65,535 bytes The title of the graphic to be fetched, encoded in UTF-8.
Sequence List Request Packet
Byte Count Data Type Value Description
1 unsigned byte 6 Packet Type
Message List Request Packet
Byte Count Data Type Value Description
1 unsigned byte 10 Packet Type
Graphics List Request Packet
Byte Count Data Type Value Description
1 unsigned byte 11 Packet Type
Sequence List Packet
Byte Count Data Type Value Description
1 unsigned byte 7 Packet Type
4 unsigned integer The number of sequences in the library
variable Strings The rest of this packet contains a list of the titles of the sequences in the library, one after the other. The String format is the standard Java string serialization: an unsigned short indicating the number of bytes in the string, followed by the string encoded in UTF-8.
Message List Packet
Byte Count Data Type Value Description
1 unsigned byte 8 Packet Type
4 unsigned integer The number of messages in the library
variable Strings The rest of this packet contains a list of the titles of the messages in the library, one after the other. The String format is the standard Java string serialization: an unsigned short indicating the number of bytes in the string, followed by the string encoded in UTF-8.
Graphics List Packet
Byte Count Data Type Value Description
1 unsigned byte 9 Packet Type
4 unsigned integer The number of graphics in the library
variable Strings The rest of this packet contains a list of the titles of the graphics in the library, one after the other. The String format is the standard Java string serialization: an unsigned short indicating the number of bytes in the string, followed by the string encoded in UTF-8.
Insertion Acknowledgement Packet
Byte Count Data Type Value Description
12 unsigned byte Packet Type
Insertion Failure Packet
Byte Count Data Type Value Description
17 unsigned byte Packet Type
1 unsigned byte Error code
2 unsigned short the length of the error message
0-65,535 bytes The error message, encoded in UTF-8.
Deletion Acknowledgement Packet
Byte Count Data Type Value Description
16 unsigned byte Packet Type
Sequence Deletion Packet
Byte Count Data Type Value Description
1 unsigned byte 13 Packet Type
2 unsigned short The length of the sequence title
0-65,535 bytes The title of the sequence to be deleted, encoded in UTF-8.
Message Deletion Packet
Byte Count Data Type Value Description
1 unsigned byte 14 Packet Type
2 unsigned short The length of the message title
0-65,535 bytes The title of the message to be deleted, encoded in UTF-8.
Graphics Deletion Packet
Byte Count Data Type Value Description
1 unsigned byte 15 Packet Type
2 unsigned short The length of the graphic's title
0-65,535 bytes The title of the graphic to be deleted, encoded in UTF-8.

Appendix B. Packet types

Packet Type # Packet Type
0 Sequence Insertion Packet
1 Message Insertion Packet
2 Graphics Insertion Packet
3 Sequence Request Packet
4 Message Request Packet
5 Grpahics Request Packet
6 Sequence List Request Packet
7 Sequence List Packet
8 Message List Packet
9 Graphics List Packet
10 Message List Request Packet
11 Graphics List Request Packet
12 Insertion Acknowledgement Packet
13 Sequence Deletion Packet
14 Message Deletion Packet
15 Graphics Deletion Packet
16 Deletion Acknowledgement Packet
17 Insertion Failure Packet

Last modified: Fri Sep 17 09:30:11 Eastern Daylight Time 2004