Version 0.0.1

View:

General Overview

Note: Since the current internal names for products are somewhat confusing (i.e. have an inconvenient amount of phoenetic similitude), this document will introduce a naming structure with phonetically distinct names that still suggest the relationships involved.

A customer will purchase, from his perspective one or more logical units:

These are the logical units. Of course the real units can be more complex in some configurations. In particular, larger or otherwise non-standard Message Boards will be achieved with One or more Control Boxes, each of which drives up to four Strings per Message Board, with one of the Control Boxes being the master.

Control Box (overview)

A Control Box will use a highly modular design. Every control box will run one or more daemons which control the Strings called String Drivers which interface to one or more Aggregators through a simple networked protocol. Aggregators are interfaced to everything else through a network protocol called MBCP, or Message Board Control Protocol. MBCP is a generalized interface which allows any program connected to an Aggregator to interoperate with the Aggregator in every way (though any given program will probably only use a subset of MBCP).

This generality will allow future expansion of Message Board's capabilities in ways that we can't currently forsee but will want to be easy when we do see them.

The other daemons running on a Control Box might include:

Control Box's Daemons

A Control Box will generally run one or more of a variety of daemons:

String Driver

A String Driver is a simple daemon which offers the network protocol STring Control Protocol (STCP). A String Driver is responsible for discovering the geomtry of its string and presenting a simple networked interface for the string to an Aggregator. STCP includes some caching information to help reduce processor load.

Each String Driver is assigned an identification number. For example, the String Driver driving the first serial port will be String Driver #1, the next will be String Driver #2, etc.

On startup, a String Driver will discover the number of modules on its string. It will then determine its geometry from a configuration file if such is present. If there is a configuration file present, it will verify that the geometry in the configuration file is possible. If there is no configuration file present, it will assume that it is a single (horizontal) row of maximum length.

(The typical case will be the latter, but the configuration file option is included for flexibility. Typically when there are such configuration files, they will be automatically generated from some user-friendly interface at sign installation time and retained on file to facilitate replacement of controllers.)

String Drivers only understand graphics. It is the job of the Aggregator driving the string to create the appropriate bitmaps from text messages.

Aggregator

An Aggregator is a daemon responsible for presenting the interface to a single Message Board. It speaks Message Board Control Protocol (MBCP) to the rest of the world, and STCP to the String Drivers which make up the message board. Aggregators are also responsible for implementing Sequences and Queues.

An Aggregator can drive an arbitrary number of String Drivers, from an arbitrary number of Control Boxes, each of which having aribtrary geometry, to create an arbitrarily large rectangular Message Board composed of the smaller rectangles. This will, of course, not be the typical case.

Typical Geometry Configuration

If there is no Geometry Definition File present, the Aggregator will attempt to connect to all of the local String Drivers in order. The String drivers are presumed to be stacked vertically in order with String Driver #1 being on the top. The Aggregator will stack as many of the String Drivers as are present.

Without a Geometry Configuration File, the Aggregator will never initiate a network connection.

Full Flexibility Geometry Configuration

To achieve complete flexibility, an Aggregator can be supplied with a Geometry Definition File which is a mapping of pixel rectangles in the Message Board to the strings which drive those rectangles. This allows fairly simply for Message Boards of virtually unlimited size (though the signs will have a finite maximum size due to the computer itself having finite memory, this maximum size will be well past the bounds of sanity and possibly at the border of human imagination, though when discussing the limits of imagination, one should always bear in mind the words of Han Solo, "I don't know. I can imagine quite a lot.").

This geometry file will typically be generated by some easy-to-use program, and then stored to make the replacement of controllers easier (i.e. so that replacing a controller doesn't require work to reconfigure, just giving it the appropriate configuration file.

MBCP

MBCP is a simple but powerful authenticated network protocol. It provides all of the functionality of the message board. Its areas of functionality are:

Queues, Sequences, and Messages

An Aggregator keeps track of all of the messages, sequences, and queues that it will dislpay, but it has no libraries. Keeping only the data it needs to display reduces the possibility of accidentally displaying the wrong data.

Queues are maintained in a stack. Each queue is a schedule of sequences. The sequences have a sequence ID, but they are stored immediately (not by reference or ID). A sequence is an ordered list of messages to play with a delay between each, plus an optional unordered collection of messages to be used as alternates in case of data source failures. Messages have a message ID, but they are stored immediately in a sequence (not by reference or ID). If a message is repeated, its entire data will appear as many times as it is repeated in the sequence. This guarantees that queues and sequences will never fall out of sync with any libraries. Moreover, it makes the stack-based operation of the queues simpler since each queue is self-contained. There is less chance for memory or disk leaks.

Configuration Daemon

This daemon is responsible for handling the configuration of the Control Box and starting everything up properly at boot time. For example, it is responsible for knowing how many String Drivers, Aggregators, etc. to start up. (Of course it has sensible and useful defaults.)

Log Daemon

This optional daemon provides a simple interface to store logs. It provides an easy way to log information without having to manually timestamp it, etc.

The Librarian

Each Control Box has a librarian whose role is to house libraries of messages, sequences, and queues for use by the various daemons on a Control Box. All daemons which deal with a library use the Librarian to store the library so that other applications can get at the stored libraries. This enables the interfaces to interoperate in a maximally useful way.

The Librarian speaks the subset of MBCP appropriate to sequences, queues, etc.

Group Daemon

The group daemon is responsible for handling syncing among groups. Each aggregator on a Control Box can be part of one domain and one or more groups in that domain.

Message boards can be arranged in either a master/slaves network or a peer-to-peer network (configured when the domain is set up). There is a password for a domain.

When a group daemon gets a message for any group in the domain, it first sends this message to the Aggregator(s) on the local control box, then forwards it to all of the other members in a group. Group messages are sequenced, and a controller which was in a domain and dropped out temporarily can request from a neighbor all of the messages since a particular sequence number. The Group daemons in a domain should store at least 32 messages, but may store up to any number. This is configured on a per-domain basis, with all of the daemons in a domain implementing the same cache depth.

Webserver (& CGI Scripts)

The webserver & cgi scripts provides the web interface. This may also be implemented as a single program which itself serves port 80 (and serves simple GET requests).

Touchscreen Daemon

The touchscreen daemon controls the LCD touchscreen and provides the on-board interface to the String Drivers. It may not be as featureful as the web interface; for example, it may not be able to drive multiple message boards simultaneously.

Radar Daemon

The Radar Daemon exists to supply a data source to the Control Box's String Drivers. Secondarily, it can record statistics or do other analysis of radar data and provide this as a data source or make it available to some aggregator.

Phased Array Radar Daemon

The Radar Daemon exists to supply data sources to the Control Box's Town Criers. Secondarily, it can record statistics or do other analysis of radar data and provide this as data sources or make it available to some aggregator.

Temperature Daemon

The temperature daemon exists to supply three data sources with the temperature (Degrees Farenheit, degrees Celcius, degrees Kelvin).

NTCIP Daemon

The NTCIP daemon's job is to implement the NTCIP protocol. It interfaces with an external NTCIP controller and one or more Town Criers and essentially just translates NCTIP to the appropriate subset of MBCP, though it will operate with both the Aggregator(s) as well as the Librarian.

Sources

Any program which connects to an Aggregator via MBCP will be able to register one or more data sources. Data sources may provide either text or graphics, and are referenced by an ID string which they provide during registration. Image sources must be fixed size and strings can be either fixed or variable size. Images must specify the size of the rectangle that they provide. Strings must specify the character length (or range of lengths) that it provides. (Space calculations involving variable-length strings will use the maximum size, but the actual size of the string will be used for layout and centering.)

Data sources can send data (prefixed by the ID) at any time after they register the source (the String Driver will only record the most recent data, in effect having a 1 data unit FIFO buffer). The Aggregator may also request a unit of data from a data source. If the Aggregator's request is not answered within 20 milliseconds, the String Driver will either use the last piece of data sent for this ID, or it will display an alternate message. (more below)

In Strings

Data sources will be available to use in text messages by using a special escape sequence and naming the data source. For example, if a radar gun registers a data source called Radar (which provides a string of length 2), a message source which uses it would look like:




Which would display as, for example:

YOUR
SPEED IS
43 MPH

If a source requires an argument, it may be passed by adding a colon to the source ID and appending the arguments, either a string which does not contain a > character, or by enclosing the argument in quotation marks and using standard C-style backslash escaping. While this is available, it is not the recommended idiom, and sources should supply multiple source IDs in preference to using an argument.

An example argument:




Alternate Messages

When a program registers a source ID, it must specify the default behavior for when it does not answer a String Driver's request in time. If the default is an alternate message, the program must specify a (text) message to display. The defaults may be overwritten by anyone creating a new message.

To override the default failure behavior of a message, one supplies a text message in square brackets after the source ID, but before any arguments. Multiple lines are separated with semicolons. Thus it might look like:




or, if an argument is also required:




This should typically not be necessary, as a source should specify an appropriate failure behavior, but it is available to the user if they want something else.

If a user simply wants to skip the message entirely if the source fails, and this is not already the default behavior, they should just supply a blank Message. E.g.




This will result in a blank sign when the message is the only one in the sequence.

In Graphics

In graphics creation, one will be able to specify rectangles which

PC Control Software (overview)

Since the web interface on a Control Box will be able to support all of the functions necessary to control a group of message boards, the PC control software will just be a simple port of the web interface to the PC platform.

This will greatly reduce duplication of effort among software.

Master Librarian (overview)

The master librarian will just be a copy of the librarian daemon which is run from some central networked computer and defined by policy to be the master.

STCP

STCP is a binary, packet-based protocol with variable length packets. It must be transmitted over a reliable, sequenced transport layer such as a unix pipe or TCP/IP. An asymmetric protocol, the originator of the connection is called the Master and the receiver is called the Slave.

(Note: there is much room for expansion here. For example, one could easily add packets to negotiate and use shared memory for when the Master and Slave are on the same Control Box for zero-copy operation; that does not change the concept, however. It is just an optional speed improvement that would fit in to this model very smoothly. Moreover, with a shared memory implementation, this networked protocol would be extremely close in performance to a single application, and essentially indistinguishable in performance from a multi-threaded application, which is the right way to go if we ever want the option of using the Nios processor in a multi-CPU configuration. With the networked approach, we are multi-cpu ready, plus have flexible network ability and good code modularity without sacrificing any performance.)

The first byte of a packet defines the type. When a master sends it, the packet types are:

Master Packet Types
0x00 No-Op
0x01 Version Request
0x02 Status Request
0x03 Geometry Request
0x04 Formatted Image Data request
0x05 PNG Image Transmission
0x06 Formatted Image Data transmission
0x07 Disable Display
0x08 Enable Display

The following descriptions of the packet types indicate the size of the packet excluding the initial packet type byte. I.e. they give the size of the data to read once the packet type byte has been read and the packet type has been identified.

No-Op Packet
A No-Op is a zero byte packet. The slave should silently ignore any No-Ops that it receives.
Version Request Packet
A Version Request packet is a zero byte packet.. The slave should respond with a Version Information Packet.
Status Request Packet
A Status Request packet is a zero byte packet. The slave should respond with a Status Information Packet.
Geometry Request Packet
A Geometry Request packet is a zero byte packet. The slave should respond with a Geometry Information Packet.
Formatted Image Data Request Packet
A Formatted Image Data Request Packet is a variable length packet. It's first through fourth bytes are a little-endian unsigned 32-bit integer specifying the length of the rest of the packet, and the rest of its bytes are a PNG file. The slave should respond with a Formatted Image Data Packet corresponding to the PNG.
PNG Image Transmission Packet
A PNG Image Transmission Packet is a variable length packet. It's first through fourth bytes are a little-endian unsigned 32-bit integer specifying the length of the rest of the packet. The rest of its bytes are a PNG file. The slave should immediately convert the PNG to the appropriate format for display and display it on its String.
Formatted Image Data Transmission Packet
A Formatted Image Data Transmission Packet is a fixed-length packet. Its bytes are the formatted image data. Since a string driver knows the size of the formatted image data which it hands out (which is static during the run-time of a String Driver), it does not need to be told this, so there is no size information in this packet.
Disable Display Packet
This is a zero byte packet which instructs the slave to immediately turn off the display. If this packet is received while the display is already off, it should be ignored. The slave should respond with a status packet.
Enable Display Packet
This is a zero byte packet which instructs the slave to immediately turn the display on and display with a blank image. The slave should immediately turn on the display, send it blank data, and respond to the master with a status packet.

When the slave sends a packet, the packet types are:

Slave Packet Types
0x00 No-Op
0x01 Version Information
0x02 Status Information
0x03 Geometry Information
0x04 Formatted Image Data
0x05 Success/Failure Packet

The following descriptions of the packet types indicate the size of the packet excluding the initial packet type byte. I.e. they give the size of the data to read once the packet type byte has been read and the packet type has been identified.

No-Op Packet
A No-Op packet is a zero-byte packet. The master should silently ignore any No-Ops that it receives.
Version Information Packet
This is a 2 byte packet. The first byte is an unsigned integer representing the minor version number. The second byte is an unsigned integer representing the major version number.
Status Information Packet
This is a fixed length packet. It contains all of the appropriate information, such as whether the String is working, whether it is on, the intensity level it is displaying at, when it last receieved a message to display, etc.
Geometry Information Packet
This is a four-byte packet consisting of two unsigned little-endian 16 bit integers. The first gives the pixel count of the width of the String's display, the second gives the pixel count of the height of the String's display.
Formatted Image Data Packet
This packet's first four bytes are a little-endian 32-bit unsigned integer indicating the length in bytes of the rest of the packet. The rest of the packet is a complete set of bytes to send to the String for display. The data should be formatted so that absolutely no processing of any kind is required, only transmission to the string.
Success/Failure packet

This is a one-byte packet which indicates the success or failure of the most recent protocol action (e.g. displaying a message). It's values are:

0x00Failure
0x01Success

MBCP

Could this just be NTCIP? My gut feeling is that that is not a good idea since NTCIP is such a massive protocol, and that would cause the core to be really huge and hence more difficult to debug.

Plus it wouldn't be flexible. It would be ridiculous to add our own proprietary extensions to NTCIP because that virtually guarantees conflict down the road with later revisions. Agile Displays might take us down other roads than NTCIP was meant for, and it would be better if we had the flexibility to go down those roads cleanly (as well as support NTCIP, of course).

Glossary

LED Module
A collection of LEDs and a controller, currently 6x9 pixels. There may be more than one LED module per LED board.
LED Board
A circuit board with one or more LED modules on it.
String
The collection of LED modules which receive data from a single RS232 cable.
String Driver
The software daemon running on a control box responsible for implementing queues, converting text and images to the appropriate format, etc. Only aggregators directly connect to String Drivers.
Aggregator
The software daemon running on a control box which handles one or more string drivers and presents itself as a single, unified string driver. An aggregator is capable of handling both local and remote string drivers.
Control Box
A control board with optional LCD panel. It runs one or more Message Daemons and Aggregators. It may run any number of other programs to provide interfaces, data sources, etc.
Message Board
A collection of LED modules which are viewed and used as a single full matrix display. It may contain any number of LED modules driven by any number of control boxes, but it must be a rectangle.