OpenLCB nodes interact to control the layout via the reporting and observation of "events".
The protocol used to transfer these events is described here. It is built on top of the standard interactions and messages.
OpenLCB nodes respond to local inputs and state changes by emitting Producer/Consumer Event Report (PCER) messages. When they do this, they are acting as "Producers". OpenLCB nodes receive these messages, and can act on them locally if desired. If they do so, they are acting as "Consumers".
The P/C Event ID included in a PCER message is a 8-byte unique identifier. The method for assigning these and ensuring their uniqueness is specified elsewhere.
There are many possible ways to use these 64 bits, some of which are discussed as examples below. In particular, OpenLCB does not require or enforce any particular partitioning of the eight bytes. More than one node may emit the same P/C Event ID (note that the NID of the emitting node is available in the message). More than one node may receive and act on a PCER message with a specific P/C Event ID. The only requirement is that the 8-byte quantity be unique to the event.
It is useful to be able to determine which, if any, nodes are listening for a specific P/C Event ID message.
This can be used as a configuration diagnostic, and as a way of building routing tables.
To determine which nodes are listening for a particular P/C Event ID, a node sends an Identify Consumers message carrying the desired P/C Event ID. This is an unaddressed message processed by all nodes.
All nodes that are listening for that P/C Event ID reply with a Consumer Identified broadcast message.
The "valid" bit indicates that the node is currently in the state it would be if this message had been received last. For example, assume a node sets its output active for P/C Event ID 2, and inactive for a P/C Event ID 4. Then if the output was active and the node was asked about P/C Event ID 2, it would reply "valid"; if asked about P/C Event ID 4, it would reply "not valid". Depending on the node's structure, it might not always be possible to set the "valid" bit with certainty, in which case the "unknown" bit must be set.
It is useful to be able to determine which, if any, nodes are configured to possibly emit a specific P/C Event ID message and their current state.
This can be used as a configuration diagnostic, and as a way of building filtering and routing tables.
To determine which nodes can send a particular P/C Event ID, a node sends an Identify Producers message carrying the desired P/C Event ID. This is an unaddressed message addressed to all nodes.
All nodes that are listening for that P/C Event ID reply with a Producer Identified broadcast message.
The "valid" bit indicates that the node's internal condition is consistent with sending this P/C Event ID. For example, assume a node sends P/C Event ID 2 when the input goes active and P/C Event ID 4 when the input goes inactive. Then if the input was active and the node was asked about P/C Event ID 2, it would reply "valid"; if asked about P/C Event ID 4, it would reply "not valid". Depending on the node's structure, it might not always be possible to set the "valid" bit with certainty, in which case the "unknown" bit must be set.
It is useful to be able to rapidly determine which, if any, P/C Event IDs that a particular node is listening for and that it can emit.
This can be used as a configuration diagnostic.
To determine which P/C Event IDs can be send by a particular node, the inquiring node sends an Identify Events message addressed to the target node.
The node must reply with a Producer Identified message for each P/C Event ID it can produce, and a Consumer Identified message for each P/C Event ID for which it is listening.
To ensure that event messages are properly routed, nodes must announce when they start to produce or consume messages. Specifically, they must do this at two times:
When the node is first initialized and the "Initialization Complete" message has been sent.
When a configuration change has added an event ID that can be produced or consumed.
To announce new Event IDs being consumed, the node must transmit a Producer Identified message for each P/C Event ID it can produce, and a Consumer Identified message for each P/C Event ID for which it is listening.
There are a small number of cases where a globally-allocated and reserved Event ID will simplify operation. These “well-known Event ID numbers” can be used to e.g. advertise that a node can provide a specific capability, or to tell locomotive control hardware to stop all trains instantly, etc.
For these to be useful, they not only have to be unique (so there are no collisions that accidentally trigger reactions to them), but they must also be well-known. So we have created a central spreadsheet on which uses can be recorded. This will eventually provide a machine-accessible record.
All of these are assigned with a reserved ID in their upper six bytes to ensure uniqueness and simplify recognition.
Nodes using these must mention them when listing the event IDs they produce and consume. Gateways may filter on these, but are not required to. (For ease of implementation, a gateway may just pass all events with the common top 6 bytes)
Site hosted by
This is SVN $Revision: 644 $