OpenLCB achieves flexibility and economy of implementation by using many small, general, common protocols to provide larger control functions. This note describes a common protocol for driving small information displays around a layout. These might include small screens in throttles, fixed displays at stations, and similar.
Provide character-oriented multi-line displays.
Must support multiple displays on a single node.
Multiple formats (fonts, sizes, colors) desirable.
Graphical display as a future extension.
Nodes with displays should be able to advertise them globally.
Display users should be able to enquire about display capabilities.
Stream access for large display transfers should be available, but not required.
Single directional, point-to-point datagram protocol, where the sender knows the node ID of the receiver, works well in OpenLCB.
Node provides single-point-of-contact for all attached displays, similar to X11 display vs display manager addressing.
Uses global event to advertise that this node has one or more displays. This allows interested nodes later on to “find all nodes providing displays” by asking for all producers of this event.
Minimal capability should be assumed, but if more is needed, the sender has more resources than the receiver.
HTML provides a useful lingua franca for formatted text, but adds length to messages. Can be too large for single datagram, so must provide stream option for formated text.
Reservation capability needed? Optional?
Other than reservation, want protocol to be stateless and idempotent, so that multiple users can share a display by e.g. writing to different lines.
Operations besides load text: Clear? Address to a specific character? Single frames too small for even a single line, but datagrams are a good size.
Writing character data is conceptually different from writing HTML. Characters has e.g. locations, while HTML is just “content”. Not clear how you e.g. specify a starting location for HTML text.
Eventually, want support for definable characters (LED style), bit map displays, etc. HTML forms a good example of this.
Basic format is datagram-ID-byte, display-protocol-command-byte, then variable arguments. Arguments are usually one byte display, two bytes character address, leaving 64+ bytes in the datagram for writes & reads.
|
|
|
Command |
Arguments |
|---|---|---|---|
|
|
|
Enquire Node; Enquire Display |
Node: 2 bytes flags, Low display number, high display number, number of displays |
|
|
|
Node Capability;Display Capability |
Display, Flags (2 bytes), lines, characters |
|
|
|
Formatting: Clear, Clear Line, Set Character Address, Set Line Address |
|
|
|
|
Write Text; Write HTML |
(Display)(line)(character) |
|
|
|
Read (same format as Write Text, with just 1 bit changed) |
|
|
|
|
Reserve, Reserve Reply, Release |
|
|
|
|
|
|
Each node can have one or more displays. Each display is separate, and may have different characteristics. The details of this are found using the “Enquire/Capability” part of the protocol, which can be done with canned messages.
Once that's done, addressing is via a single 8-bit number in each message. The numbers are assigned by the display node, and don't have to be consecutive, but it's easier for users of the protocol if they are. The convention is that the first display is 0.
256x256 is perhaps too small for an addressable character screen, but it's not a clearly too small in total characters, just in each dimension. Anything bigger than that might be e.g. 2048x1. Use 12 bits for each? Use 2 bytes total, with movable rows vs column divide? That's just too complicated.
Do we need a way to say “whatever is next”? E.g. not require the sender control character location if not desired?
Streams Available – node can accept stream writes
Read Available – node can return content of display
Read Stream Available – node can return content of display via stream
HTML Available – (basic) HTML will be accepted, but not necessary all features will be displayed
Clear Available; Clear Line Available
Character Direct Addressing Available; Line Direct Addressing Available
Reserve Available
Reserve/release is a simple flagging protocol, it doesn't require the display node to modify it's behavior.
If the node is not reserved, a request to reserve it will put the requesting node and key in the “reserved by field”. If it is reserved, the field won't be changed. In either case, the reserve field is returned.
If the requester finds the requested node and key in the reply, the reserve request succeeded. If not, it didn't.
It would be useful to show how this works for a throttle, or for a fast clock repeater, or for giving train orders at a remote station.
A node locates the display, perhaps via a global event, and wants to make it display “Hello World”. Datagram segmentation and replies omitted.
Enquire Node →
← Reply (low display = 0)
Display 0: Clear → (might or might not work, but doesn't hurt)
Display 0: Write at 0,0 “Hello World” →
Enquire Node →
← Reply (low display = 0, high display = 4)
Display 3: Enquire: →
← Display 3: Reply (Display 0: Reserve available; “East Entrance”)
Display 3: Reserve for Node NN with key KK→
← Display 3: Reserved by Node NN with key KK
Display 3: Clear → (might or might not work, but doesn't hurt)
Display 3: Write at 0,0 “East Entrance Closed” →
…
Display 3: Release →
Site hosted by
This is SVN $Revision: 721 $