OpenLCB OpenLCB Specification Conventions

OpenLCB is not a formal standards-making body, but we are interested in making it clear what's required and not required for interoperation between OpenLCB nodes. Therefore, we are creating a series documents that are intended to form a stable basis for OpenLCB implementors.

At the same time, we're interested in forwarding the NMRA's effort to create a common standard, so we're proposing documents to them and cooperating in those discussions. More information on that effort can be found on a separate page.

We're creating three general types of documents:

Standards: Standards are agreed to be normative, to the extent that anything this bunch of happy campers does can be proscriptive. A statement should be included in a standard when it's "clearly necessary" and "clearly correct".
Technical Notes: These are agreed-to documents that explain a standard and provide stable information useful to implementors. Statements should be included in a technical note when they are "likely to be useful" and "not clearly wrong"; this is a lower standard than the one for standards. Opinions and less-desirable options are OK when clearly labelled as such.
Development documents: These are things that are in significant flux, but still useful to developers and implementers. One formal type is “Working Notes”, which are one step below Technical Notes and Standards. They are intended as the last step before writing the more formal documents. Others are less formal and can be found in the “documents” section of the web site.

The first two can appear in "preliminary", "draft" or "adopted" form. Adopted documents have received extensive review, and one can rely on their content. "Draft" documents are complete, but still under discussion. "Preliminary" documents are still being written, will certainly change very much during that process, and in general are only of interest to the people actively working to advance the protocol in that particular area.

Generally, an implementer should start with the relevant adopted standards and be sure to understand what's really required for the implementation to work well. Then, the implementor should move on to the adopted technical notes to make sure the background is understood, learn about issues to be considered and decisions to be made, and get information about possible approaches. Finally, the implementer may want to spend time on the draft and development documents to get an idea of what the future might bring.

The work to date is available here for Standards and Technical Notes, and here for development documents.

OpenLCB is loosely versioned. Documents can be referenced via their last change date, which is displayed at the upper right of the first page of every document. Older versions can be retrieved by date from SVN. The collection of documents is given a version number, such as 0.5, on the specification index page. That number is updated when the specifications (and associated implementations) are changed in a way that breaks compatibility with existing adopted documents and/or shipped code. The pre-decimal digit(s) represent fundamental structures such as basic state machines and protocols; the post-decimal digit(s) represent minor changes to values and field sizes.

Implementation Points:

We write stuff in bog-standard Open Office .odf format by convention. The drafts/Template.odt file is a starting point. Leave change tracking on, because that helps handle collisions between two people who might be editing at overlapping times. Commit back to SVN early and often to avoid collisions.

(We have considered DocBook and other formats in the past, may still go that way, but don't want to invest in the infrastructure now)

To make direct access easier, the file naming convention is (wire)(topic)(type).html, in Pascal case (leading-capital camel case). For example, "CanMessageTransportS.html" vs "CanMessageTransportTN.html" vs "TcpMessageTransportS.html". Use "Gen" for the general case, true for any wire protocol.

"Shall" should get used in standards in preference to "must". The reason for this is that "The board shall be flat..." reads as a statement about the board, but using "must" makes it seem a statement about what you, the designer or manufacturer, must do. "Must" is OK in technical notes, which are more information and non-normative: "Designers must remember that wires get hot..."

Standards can describe options using "Devices may, but are not required to, ...", but they can also just be silent about options.

The various parts of standards should be identified as normative or informative, because there are always non-normative parts of standards. Try to keep the informative parts in the explanation technical note, but when they need to be present so the standard can be read by itself, be sure to label them clearly.

Generally, standards should use short paragraphs focused on a single point. Think of the paragraphs as unit tests, which should be individually satisfied (or not).

Make the status of "reserved" things clear: "Shall be set to 1 on creation and shall not checked upon reception" and "Shall be set to 1 on creation, and shall be received as 1 to be considered valid" are different. One works for a bit that's reserved for some orthogonal future expansion; the other is needed to define an exclusive (hence non-orthogonal) future option.

Make numbers clear instead of using "large" or "small". (One web page referred to OpenLCB being usable unchanged on "up to huge modular layouts", which engendered a long discussion in July 2011; we decided that meant "up to 4999 nodes" and at 5000 or above you might have to do special things to handle traffic)

Considerations

When designing or documenting a protocol, please address the following points (note that these aren't goals, but rather possible problems/complexities that should be addressed):

What happens if N nodes want to do this at once? Either independently or all trying to act in concert with a single target node.
What happens when a node joins late and wants to take part? How does the day start?
Are there any critical resources, e.g. single nodes that have to be present and working?
Where can this be expanded later? Not be expanded later? How will original (unmodified nodes) interact with expanded ones?
How much buffering does the protocol require? What bounds that? How are buffer shortages handled?
How are the message priorities allocated? What does this protocol block? What does it defer to? How does priority order the various messages in overlapping interactions?
How does the protocol map to CAN, or other limited-size-frame wire protocols?
Do participant nodes have to have full node IDs for their targets, or can everything be done with already-known aliases? If node IDs are needed, how are they acquired?
How much traffic does this generate on a very large layout? Is that commensurate with the provided function?
Do the protocols respect the “Simple Node” concept? Do any new MTIs have their simple-node bit set properly?

Promoting a Document

When a document has been judged to be “adopted”, the technical steps are:

Copy (or if the 1^st time, svn copy) the .odt file from the specs/drafts/ directory to the specs/ directory
Change the specs/ document to say “Adopted” in the header. Remove “Draft” watermark. Turn on “Track changes” if it was off. Turn off “show changes”, if it was on. Make a PDF version.
Add the specs/ document and .pdf to the index.html file if needed. Color it green (#00ff00).
Change the specs/drafts document to say “Preliminary” in the header. Accept all changes to remove them from the log. Turn on “Track changes” if it was off. Make a PDF version.
Add the specs/drafts document and .pdf to the index.html file as "future version" if needed. Reset its color to the default.
If the document includes any figures from the images/ directory, svn cp them from specs/drafts/images to specs/images/.
If the document includes any message state diagrams from the mscgen/ directory, svn cp them from specs/drafts/images to specs/images/. Run make in the mscgen/ directory and svn add any new files.
Commit all to SVN with a common comment.

Site hosted by

This is SVN $Revision: 3143 $