The display driver is the software which sits atop the serial port(s) and displays the current sequence on the display modules. This standard describes a simple protocol for directly communicating with the Display Driver to query it for information and to set the current sequence.
(While the Scheduler might be integrated with the Display Driver for performance reasons, it might yield better performance not to, so that the Display Driver can be scheduled at a higher priority than every other process running on the system. Thus the protocol having the ability to set the current sequence will give us flexibility, even if we don't initially go that route. Also, it will make unit testing simpler if the scheduler and the display driver can be divorced.)
The Display Driver Protocol is a variable-length packet based protocol which is initiated by a challenge-response authentication phase, followed by a versioning handshake.
Each Display Driver will find an available port to listen on and publish this information with the Information Daemon in the category "display". For convenience, however, the first display driver is on port 50401, and subsequence display drivers are on consecutive ports.
Note: unless otherwise specified, all multi-byte integral types are in network-order (i.e. big-endian).
New packets and different packet behaviors are indicated in the notes for those packets. (Note: in the packets, versions are zero-centered, so version 1 is indicated with a 0.)
The initial implementation of this protocol.
There are no new packets in version 2 of the protocol, but the behavior of the Sequence Query Packet has changed. In protocol version 2, it now registers the client as desiring to be notified when the displaying sequence changes. After every change, the display driver will notify the client of the new sequence. There is no way to terminate this interest, other than severing the connection and re-establishing it, but it's difficult to imagine why one would want to terminate the interest.
Version 3 adds Set Test Mode Packet and Test Module Packet to allow module testing remotely.
The protocol handshake works according to the Solartech Protocol Handshake & Authentication specification. The current protocol version is 3.
After the version handshake, the protocol is asynchronous, though some packets require a response.
Unless otherwise noted, all multi-byte integral types are big-endian.
Byte Count | Data Type | Value | Description |
1 | unsigned byte | 0 | Packet Type |
variable | Sequence | A sequence. See notes. | |
Notes: When sent to the Display Driver, this is the sequence to display. When sent by the Display Driver, this is the sequence currently playing. |
Byte Count | Data Type | Value | Description |
1 | unsigned byte | 1 | Packet Type |
Notes: This causes the Display Driver to send a Sequence Packet. In version 2 and later of this protocol, it also causes the display driver to send a Sequence Packet after every change in the currently displaying sequence. There is no way to de-register from the change notifications. |
Byte Count | Data Type | Value | Description |
1 | unsigned byte | 2 | Packet Type |
Notes: This causes the Display Driver to send a Capabilities Packet. |
Byte Count | Data Type | Value | Description |
1 | unsigned byte | 3 | Packet Type |
2 | unsigned short | width (in pixels) | |
2 | unsigned short | height (in pixels) | |
2 | unsigned short | minimum time between frames, specified in milliseconds. (e.g. 100 corresponds to 10fps) | |
1 | unsigned byte | bits per pixel | |
1 | unsigned byte | bits per color | |
Notes: |
Byte Count | Data Type | Value | Description |
1 | unsigned byte | 4 | Packet Type |
1 | unsigned byte | Intensity | |
Notes: When this packet is sent to the Display Driver, it sets the intensity of the sign. When it is sent by the Display Driver, it indicates what the current insensity is. |
Byte Count | Data Type | Value | Description |
1 | unsigned byte | 5 | Packet Type |
Notes: Requests that the server send a Display Intensity Packet |
Byte Count | Data Type | Value | Description |
1 | unsigned byte | 6 | Packet Type |
1 | unsigned byte | On/off. 1==on, 0==off. | |
Notes: When this packet is sent to the Display Driver, it turns the sign on or off. When it is sent by the Display Driver, it indicates what the current on/off status is. |
Byte Count | Data Type | Value | Description |
1 | unsigned byte | 7 | Packet Type |
Notes: This packet causes the display driver to emit a Sign Status Packet. |
Byte Count | Data Type | Value | Description | ||||||||
1 | unsigned byte | 8 | Packet Type | ||||||||
1 | unsigned byte | Status Code:
|
|||||||||
Notes: This packet indicates whether the sign is working or malfunctioning. The fields form a bitfield indicating their problems. |
Byte Count | Data Type | Value | Description |
1 | unsigned byte | 9 | Packet Type |
1 | unsigned byte | Mode. 1 == on, 0 == off. | |
Notes: The Display Driver will respond by sending the packet back as a confirmation. |
Byte Count | Data Type | Value | Description | ||||||||||
1 | unsigned byte | 10 | Packet Type | ||||||||||
1 | unsigned byte | row | |||||||||||
1 | unsigned byte | column | |||||||||||
1 | unsigned byte | pattern
|
|||||||||||
Notes: The module specific patterns are all different, and are meant for sign debugging (switching modules around while the sign is displaying). The display Driver will respond by sending the packet back as confirmation. |
Byte Count | Data Type | Value | Description |
1 | unsigned byte | 11 | Packet Type |
1 | unsigned byte | Initiate test before reporting (0 == use current data, 1 == initiate new test) | |
Notes: The test is time-consuming as it requires powering down the sign panel and starting it back up to get back a full immediate report. Once a pixel failure report is requested, if the pixel failure list changes, a new pixel failure report will be spontaneously sent. |
Byte Count | Data Type | Value | Description | ||||||||||||||||||||||||||||
1 | unsigned byte | 12 | Packet Type | ||||||||||||||||||||||||||||
1 | unsigned byte | Full test results flag (0 == result of normal collection, 1 == result of commanded full test) | |||||||||||||||||||||||||||||
2 | unsigned short | count | The # of records of failed pixels which follow | ||||||||||||||||||||||||||||
5*count | records:
|
||||||||||||||||||||||||||||||
1 | unsigned byte | rectangle_count | The number of rectangle blocks which follow | ||||||||||||||||||||||||||||
7*rectangle_count | Rectangles:
|
||||||||||||||||||||||||||||||
Notes: The origin (0,0) is the top-left of the board. The rectangular regions are meant to be used for module failures, where all of the pixels have failed for the same reason (typically, a broken module). Thus the failure flags in the rectangle applies to every pixel specified in the rectangle. If a client sends this packet to a controller, the controller will treat it as an override packet, and will return this report for all subsequent queries. This mode of operation is meant for testing, and not for normal operation. |