Revision 9

Display Driver

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

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).

Versions

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.)

Version 1

The initial implementation of this protocol.

Version 2

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

Version 3 adds Set Test Mode Packet and Test Module Packet to allow module testing remotely.

Handshake

The protocol handshake works according to the Solartech Protocol Handshake & Authentication specification. The current protocol version is 3.

After the Handshake

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.

The Packets

Sequence Packet
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.
Sequence Query Packet
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.
Capabilities Query Packet
Byte Count Data Type Value Description
1 unsigned byte 2 Packet Type
Notes:
This causes the Display Driver to send a Capabilities Packet.
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:
Display Intensity Packet
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.
Display Intensity Query Packet
Byte Count Data Type Value Description
1 unsigned byte 5 Packet Type
Notes:
Requests that the server send a Display Intensity Packet
Display Shutdown 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.
Everything Working Perfectly? Packet
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.
Sign Status Packet
Byte Count Data Type Value Description
1 unsigned byte 8 Packet Type
1 unsigned byte Status Code:
0Working Perfectly
1Sign Panel Communication Failure
4Bad LED(s)
8Message Rendering Problem
Notes:
This packet indicates whether the sign is working or malfunctioning. The fields form a bitfield indicating their problems.
Set Test Mode Packet
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.
Test Module Packet
Byte Count Data Type Value Description
1 unsigned byte 10 Packet Type
1 unsigned byte row
1 unsigned byte column
1 unsigned byte pattern
0x00 All LEDs on
0x01 All LEDs off
0x02 module specific
0x03 module specific
0x04 module specific
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.
Pixel Failure Report Request Packet
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.
Pixel Failure Report Packet
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:
Byte Count Data Type Description
2 unsigned short x coordinate
2 unsigned short y coordinate
1 unsigned byte Failure Flags, bitfield:
0 stuck on
1 color error
2 electrical error (i.e. error unknown)
3 mechanical error
4 stuck off
5 partial failure
6 reserved
7 reserved
(this corresponds to the NTCIP bitfield, so not all fields apply to us)
1 unsigned byte rectangle_count The number of rectangle blocks which follow
7*rectangle_count Rectangles:
Byte Count Data Type Description
2 unsigned short top-left x coordinate
2 unsigned short top-left y coordinate
1 unsigned byte width
1 unsigned byte height
1 unsigned byte Failure Flags, bitfield, identical to the Failure Flags in the records.
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.

Appendix A. Display Driver Protocol Packet Types

Packet Type # Packet Type
0 Sequence Packet
1 Sequence Query Packet
2 Capabilities Query Packet
3 Capabilities Packet
4 Display Insensity Packet
5 Display Intensity Query Packet
6 Display Shutdown Packet
7 Everything Working Perfectly? Packet
8 Sign Status Packet
9 Set Test Mode Packet
10 Test Module Packet
11 Pixel Failure Report Request Packet
12 Pixel Failure Report Packet

Last modified: Thu Sep 23 15:41:20 Eastern Daylight Time 2004