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 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 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).
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.
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:
Byte Count | Data Type | Value | Description |
1 | unsigned byte | 0 | The maximum version of the protocol which is supported. |
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. |
This is normally a synchronous protocol, where the librarian only sends packets in response to packets from the client.
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
In order to delete, the client sends one of:
Once the deletion is complete, the Librarian sends an Deletion Acknowledgement Packet.
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.)To request information about a library, the client sends one of:
The Librarian then responds with one of:
as appropriate.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. |
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. |
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.) |
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. |
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. |
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. |
Byte Count | Data Type | Value | Description |
1 | unsigned byte | 6 | Packet Type |
Byte Count | Data Type | Value | Description |
1 | unsigned byte | 10 | Packet Type |
Byte Count | Data Type | Value | Description |
1 | unsigned byte | 11 | Packet Type |
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. |
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. |
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. |
Byte Count | Data Type | Value | Description |
12 | unsigned byte | Packet Type |
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. |
Byte Count | Data Type | Value | Description |
16 | unsigned byte | Packet Type |
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. |
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. |
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. |