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.

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.

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

Site hosted by

This is SVN $Revision: 1493 $