Entry-level OpenLCB users should be able to buy two OpenLCB nodes and configure them to do something useful with only the pushbutton(s) and LED(s) on them, without requiring a separate configuration tool, computer, etc.
This document outlines the OpenLCB protocol for doing this. It works without any central configuration mechanism, nor even any global knowledge of which producers and consumers are being configured.
This method is based on easily creating a known-unique new Event ID. When Event IDs are much longer than Node ID numbers (NIDs), it's straightforward to do this by using the NID followed by a sequential number when a new unique Event ID is needed.
This protocol does not mandate how a node defines its local UI. See the separate “Blue-Gold Protocol” document for that.
Nodes may also be configured using other mechanisms, including direct loading of configuration. Techniques for that are described elsewhere.
Producer-nodes (ones that implement buttons, toggle switches, BODs, etc) and consumers-nodes (signals, leds, displays, layout lighting, etc) need to be configured to use a common EventID, such that activating a producer will send the common EventID, which will cause one or more consumers to activate.
The protocol uses external mechanisms, e.g. walking around and pushing buttons, to select producers and consumers which will learn the common EventID. A single producer or consumer then provides the EventID that is to be learned in a “teach EventID” message. Specifically:
On one or more 'learner'-nodes, select a number of producers/consumers (p/c's).
On the 'teacher'-node select the p/c which will teach the other nodes and activate the teaching.
As a result, activating one of the producers will activate all the linked consumers.
'Learner'-nodes flag selected producers and consumers.
The 'teacher'-node sends a TeachEvent message containing the event# associated with the selected p/c.
On one or more 'learner'-node, using the Blue-button, choose a consumer/producer;
On the 'teacher'-node, using the Blue-button, choose a consumer/producer;
Push the Gold-button;
As a result, all producers selected above will activate all the consumers.
Notes:
Pushing the Blue-button selects p/s's in a circular fashion, with a 'no-selection' before starting again at the beginning.
The teaching- p/c can be a consumer.
New teaching will replace the previous teaching.
Pushing Gold for more than 3-seconds will reset the node to its factory events.
Given two Button-nodes, each with three buttons, A-C and D-F, respectively, and four Signals-nodes, 1-4:
Buttons set Aspects: Push the blue-button on Signal-1 until the 'green' aspect is selected. On the first Button-node, push the blue-button once to select button-A, then push the gold-button. On Signal-1 use the blue-button to select aspect 'red', and on the Button-node push the blue-button twice to select button-B, and then the gold. Now, pushing button-A will change Signal-1 to green, and button-B will change it to red.
Make a duplicate buttons: On the second Button-node, push blue once to select button-D, and on the first Button-node, push blue once and then gold. On the second Button-node, push blue twice to select button-E, and on the first Button-node, push blue twice and then gold. Now, button-D will turn Signal-1 to green, and button-E will turn it to red.
Add a second consumer-node: On Signal-2 push blue to select red, then on Signal-1 push blue to select green, push gold. On Signal-2 push blue to select green, then on Signal-1 push blue to select red, push gold. Now pushing button-A sets Signal-1 to green and signal-2 to red, and button-B turns Signal-1 to red and Signal-2 to green.
On one or more 'learner'-nodes, use the Blue-button to choose a consumer/producer, and then the Gold-button briefly to make it a learner. Repeat for other p/c's on this node, and note this includes teacher-node, if one of its p/c's is to be a learner.
On the 'teacher'-node, push the Gold-button, and use the Blue-button to choose a consumer/producer, push the Gold-button to activate the teaching session.
As a result, all producers selected above will activate all the consumers.
Notes:
Pushing the Blue-button selects p/s's in a circular fashion, with a 'no-selection' before starting again at the beginning.
The teaching- p/c can be a consumer.
New teaching will replace to previous teaching, to add to the previous teaching, push the Gold button for 2-seconds, this will let the selected p/c produce or consume two or more events, .
Pushing both Blue and Gold simultaneously for more than 5-seconds will reset the node to its factory events.
Given a Button-node with six buttons, A-F and four Signal-nodes:
Teach buttons-A and -D to set signal-1 to red and Signal-2 to green, and buttons-B and -E to set Signal-1 to green and Signal-2 to red:
On Button-node, push button-D and gold, on Signal-1 push blue to select red and gold, on Signal-2 push blue to select green and gold. Then on Button-node push gold, button-A and gold.
On Button-node, push button-E and gold, on Signal-1 push blue to select green and gold, on Signal-2 push blue to select red and gold. Then on Button-node push gold, button-B and gold.
Now, button-A or button-D sets Signal-1 to red and Signal-2 to green, and button-B or button-E sets Signal-1 to green and Signal-2 to red.
> Set turnout to straight
> Set turnout to diverging
< Turnout was set to straight
< Turnout set to diverging
< Turnout is occupied
< Turnout is unoccupied
The node would have three buttons and two digit seven-segment display to indicate active turnout and p/c. The first button would select the active turnout(1), the second would choose a p/c(2), and the third would be Gold. To set a learner, use button-1 to select a turnout, and 2 to select a p/c, then gold. To select a teacher, push gold, then 1&2 to select a p/c, and then gold to activate the teaching session.
Example
Align turnout-2 to turnout-1 if turnout-1 is occupied: using 1&2 select turnout-2-Set diverging and gold, then push gold, select turnout-1-occupied, and gold. Now if a train enters turnout-1, turnout-2 will change to align with it.
For this method to work, producers and consumers must start configured to unique EventIDs not in use anywhere else. This section describes how to ensure that.
Assume that a node can detect N conditions, each of which should send a unique P/C Event ID (the non-unique case is discussed below). The factory default condition is that each of those conditions will produce a PCER message with a P/C Event ID of the board's unique NID followed by the input number (1, 2, etc). This is enough to get the board up and working.
For example, a board with 48-bit NID 0x123456789ABC would by default send Event ID 0x123456789ABC001 when its first input condition happened, 0x123456789ABC002 when its second input condition happened, etc. These Event IDs could then be counted on for no- or low-configuration use.
Similarly, by default a board with M consumers will start with those consumers configured to match default EventIDs consisting of the NID followed by a sequential number that doesn't overlap with the producer sequence described above.
If the board is reset to its default configuration, e.g. a “factory reset”, it must set the default EventIDs to new numbers. If it had N EventIDs before, it could e.g. start with a suffix of N+1 to its NodeID. If it doesn't do this, the configuration process could reuse an EventID for a different purpose, causing conflicts.
There is a theoretical possibility that a node could run out of default EventIDs due to an excessive number of reset operations. There are 216 = 65535 possible suffixes. These can seemingly be consumed rapidly if there are e.g. 200 default EventIDs in a node, so that each reset raises the suffix by 200. But even in that unlikely case, it will take more than 300 factory resets to overflow. That's enough for a useful lifetime for a board. If a board has a very large number of defaults, it can build EventIDs using two or more consequtive NodeIDs, effectively providing more bits in the address space for the suffix. (That needs a figure to show the space; make it clear the node has one NodeID in any case)
Site hosted by
This is SVN $Revision: 720 $