BiDiB, a universal control set for model railways
Peripheral Equipment, Light, Switches
- 4.6.5. Controlling of peripheral functions
- 4.6.6. Features for peripherals
- 4.6.7. Downlink: Messages for peripheral / switching functions
- 4.6.8. Uplink: Messages for peripheral / switching functions.
- 4.6.9. Local macros
- 4.6.10. Features for local macros
- 4.6.11. Downlink: Messages for local macros
- 4.6.12. Uplink: Messages for local macros
The intention of BiDiB protocol is to control a model railway. It allows the control of locomotives, accessories and safe transmission of feedback information from the model railway to the controlling computer.
BiDiB can be transported over different transmission media, framing and protection of messages is guaranteed.
The used terms and the basic principles will be explained in the general part of the protocol description. Hints for usage and the license can be found there too.
This section of the protocol description explains only a part of the messages.
Current revision status
This document describes revision 1.26 of BiDiB, updated aug 15, 2016.
The revision history can be found at the general section.
Nodes with switching functions could be used for light effects, animations (with movement) or similar. Another possibility is an operator panel, nodes could have key inputs. The class-ID flag 'Peripheral' is set for Nodes with switching functions.
Nodes with switching functionality have one or more in- and outputs, which are referred to as 'ports'. Each port can be configured, queried, and activated individually.
Peripherals can have significant differences, depending on the kind of outputs: There are pure switching outputs, light outputs with dimming or blinking functions, servo (with positioning), sound, analogue outputs etc. According to this there are execution commands which result in a change of the output, and configuration commands to set the properties.
Nodes can offer different functionalities on one port, for example they might be able to change the type of a port from output to input. Such reconfiguration shall take place during setup, not in operation mode. It shall not have any impact on the other properties of the port.
Furthermore a peripheral node may support macros, this optional feature allows for further commands and configuration abilities:
- Configuration of the controlling source for a port (via switching command, via time)
- Combination of switching functions to local macro sequences
- Configuration for those macro sequences (sequence speed, start condition)
For the accessing of ports, there are two different addressing models since protocol version 0.6. Both use two bytes, but they differ in the alignment of the available ports in this address space.
|type-based port model||flat port model|
|Definition||Each output and input port has a fixed type. Each port type has its own number range, which is counted from 0, the addresses are distributed over the types. The port function is therefore directly encoded in its address.||All output and input ports share a common number range, the addresses are appointed linearly. Their type (function) is only defined by the configuration of the respective port. This scheme also allows to change the type of a port with a reconfiguration message when supported by the node.|
|Activation||The type-based port model is active on nodes whose
FEATURE_CTRL_PORT_FLAT_MODEL and FEATURE_CTRL_PORT_FLAT_MODEL_EXTENDED do not exist or are set to 0.
The number of available ports per type is announced via the respective FEATURE_CTRL_*_COUNT.
|The flat port model is active on nodes where FEATURE_CTRL_PORT_FLAT_MODEL
and/or FEATURE_CTRL_PORT_FLAT_MODEL_EXTENDED is > 0. Their values also determine the total number of available ports
as the sum PORT_FLAT_MODEL_EXTENDED*256+PORT_FLAT_MODEL.
If present, the FEATURE_CTRL_*_COUNTs denote the maximum count of ports configurable to the respective type.
This scheme is only available since protocol version 0.6.
|PORT0||PTYPE||port type.||PORTADDRESS||Number of ports on the node, counted from 0 in principle. It is encoded as a 16 bit little endian integer whose 4 MSB are reserved (0). Value range 0…4095|
|PORT1||PORTNUM||Number of the port per type, counted from 0 in principle. Value range 0…127, bit 7 is reserved (0)|
|0||SWITCH||Switching output (fka SPORT)||off/on||none|
|1||LIGHT||Light output (fka LPORT)||off/on/blinking/dimming||Brightness, Speed of dimming|
|2||SERVO||Output for servo||Positioning||end position, rotational speed|
|3||SOUND||sound output||play/pause/stop||volume, source|
|4||MOTOR||Motor output||Rotating /Speed||Regulation|
|5||ANALOGOUT||general purpose||Voltage||Maximum values|
|6||BACKLIGHT||Light output||Brightness||Speed of dimming, channel mapping|
|15||INPUT||Contact input, e.g. push button or micro switch||open/closed||none|
|255||reserved||(internal use in nodes or host programs)|
The properties of the nodes (for example the quantity of each specific kind of output) can be read with feature-requests:
|50||FEATURE_CTRL_INPUT_COUNT||Quantity of inputs (e.g. for keys)|
|51||FEATURE_CTRL_INPUT_NOTIFY||Spontaneous messages of key inputs are allowed.
The node provides changes of the key status to the host of its own.|
|52||FEATURE_CTRL_SWITCH_COUNT||Quantity of standard outputs|
The number of switching outputs will be provided. Range: 0…128.
|53||FEATURE_CTRL_LIGHT_COUNT||Quantity of light outputs|
Light outputs have extended properties like blinking, dimming, etc.
The number of light outputs will be provided. Range: 0…128.
|54||FEATURE_CTRL_SERVO_COUNT||Quantity of Servo outputs|
The number of servo outputs will be provided. Range: 0…128.
|55||FEATURE_CTRL_SOUND_COUNT||Quantity of playable sounds|
The number of sounds will be provided. Range: 0…128.
|56||FEATURE_CTRL_MOTOR_COUNT||Quantity of motor outputs|
Motor outputs for accessories (e.g. carousel)
|57||FEATURE_CTRL_ANALOGOUT_COUNT||Quantity of analogue outputs|
The number of analogue outputs will be provided. Range: 0…128.
|58||FEATURE_CTRL_STRETCH_DIMM||Additional slow down for brightness transitions. Range 1…250|
|59||FEATURE_CTRL_BACKLIGHT_COUNT||Quantity of light outputs (dimmable, for room lights)|
This addresses environmental light, the brightness will be set with the operational command.
|70||FEATURE_CTRL_PORT_FLAT_MODEL||Support of the flat port model, low byte of the number of
addressable ports. Total count of the existing output and input ports.|
|71||FEATURE_CTRL_PORT_FLAT_MODEL_EXTENDED||Support of the flat port model, high byte of the number of
addressable ports. Total count of the existing output and input ports.|
|66||FEATURE_CTRL_PORT_QUERY_AVAILABLE||Query of port states|
0 = output states cannot be queried. (default)
1 = output states can be queried, the node will respond to MSG_LC_PORT_QUERY(_ALL).
|67||FEATURE_SWITCH_CONFIG_AVAILABLE||(deprecated, from protocol version 0.6 use MSG_LC_CONFIGX for port configuration)|
Configuration of switch ports possible
0 = ports are simple, no configuration possible. (default)
1 = ports can be configured.
Direct output operation, followed by 3 Bytes: PORT0, PORT1, PORTSTAT. These 3 bytes define the number of the output and the operation which is carried out at this output.
MSG_LC_OUTPUT parameters Parameter Description PORT These bytes address the port PORTSTAT This byte describes the status of the port, the meaning depends on the output type. Output type Encoding of output commands 0 (=BIDIB_PORTTYPE_SWITCH) Normal switch output, the following operations are available: Value Name Operation 0 BIDIB_PORT_TURN_OFF Switch output OFF 1 BIDIB_PORT_TURN_ON Switch output ON 2-255 - reserved
Other possible modes: Output pulse (for turnouts)
1 (=BIDIB_PORTTYPE_LIGHT) Switch output for light control, the following operations are available: Value Name Operation 0 BIDIB_PORT_TURN_OFF Switch output directly to brightness OFF 1 BIDIB_PORT_TURN_ON Switch output directly to brightness ON 2 BIDIB_PORT_DIMM_OFF Dim output directly to brightness OFF 3 BIDIB_PORT_DIMM_ON Dim output directly to brightness ON 4 BIDIB_PORT_TURN_ON_NEON Switch output to brightness ON with neon flickering 5 BIDIB_PORT_BLINK_A Output flashes with approx. 1Hz, flashing starts with the ON-phase. A configured dimming is active here. 6 BIDIB_PORT_BLINK_B Output flashes with approx. 1Hz, flashing starts with the OFF-phase. A configured dimming is active here. 7 BIDIB_PORT_FLASH_A Output flashes with approx. 3Hz, flashing starts with the ON-phase. 8 BIDIB_PORT_FLASH_B Output flashes with approx. 3Hz, flashing starts with the OFF-phase. 9 BIDIB_PORT_DOUBLE_FLASH Output drives double flashes, repetitive (rescue vehicle)
Modes 5 and 6 are intended for railway crossings, the modes 7 and 8 for warning lights.
2 (=BIDIB_PORTTYPE_SERVO) Servo output, PORTSTAT is the target position of the servo in this case. A PORTSTAT of 0 corresponds to the lower stop, 255 to the higher stop.
The stops can optionally be configurable (see below), their maximum range shall be a servo pulse width from 0.5 ms to 2.5ms. These values are chosen broader than the normed 1ms to 2ms, as many real servos are controllable beyond those.
3 (= BIDIB_PORTTYPE_SOUND) Sound function (Detailed definition will follow) 4 (= BIDIB_PORTTYPE_MOTOR) Motor function, PORTSTAT denotes the speed. The encoding equals that of DCC128:
- The MSB encodes the direction of rotation: 1 = Forward, 0 = Reverse
- The LSBs (Bit 6…0) encode the 126-step speed value with 0 = Stop and 1 = Emergeny stop.
5 (= BIDIB_PORTTYPE_ANALOGOUT) Analog function (Detailed definition will follow) 6 (= BIDIB_PORTTYPE_BACKLIGHT) Light function, direct dimming. PORTSTAT denotes the target brightness, range 0…255.
If the port is part of a pair, when it is switched on then its neighbor must be switched off.
A node responds with a MSG_LC_STAT message if he receive a switch command. If a port outside of the available range is selected or a switching state which is not supported, the node responds with a MSG_LC_NA message. If a node does not support a particular state transition, he should perform the next possible transition: e.g. neon flickering is not available, it should be switch on normal.
(up to and including protocol version 0.6 known as MSG_LC_OUTPUT_QUERY, for outputs only)
This message queries the state of an output or input port, followed by 2 Bytes to address the port. The node shall respond with a MSG_LC_STAT, or MSG_LC_NA in case.
- This message is optional for outputs. Whether this message is answered by the node is defined by the feature FEATURE_CTRL_PORT_QUERY_AVAILABLE. If this feature is missing or has a value of 0, there may be no answer to MSG_LC_PORT_QUERY. When the node has inputs, these always are queryable.
- This message is supposed to allow the host to retrieve the state of output ports so that it can e.g. display them appropriately on the screen.
- Output states are internal to the node, they may change at any time through accessory switching, macro execution, as reaction to inputs, caused by timers or more. The host is not automatically notified of such changes. If that is necessary an accessory should be used instead, for which the protocol provides the respective safety messages.
(deprecated, from declared protocol version 0.7 use MSG_LC_PORT_QUERY)
With this message, the state of a local push button on a node can be queried. Whether the node has push buttons (and how many) must be read from the node by a feature-query. Followed by one byte: PORT.
MSG_LC_KEY_QUERY parameters Parameter Description PORT Button number. Corresponds to PORT0 in the flat port model and to PORTNUM in the type-based one (with PTYPE=15).
The node responds with a MSG_LC_KEY message, which contains the present status of the button, or with MSG_LC_NA in case.
Query of multiple port states. Followed by 0, 2 or 6 bytes. If any parameters follow, they set the requested types and range.
MSG_LC_QUERY_GET_ALL parameters Parameter Description SELECT These bytes form a 16 bit long bitmap that allows to filter the queried ports by type. Bit 0 of SELECT0 corresponds to SWITCH, bit 1 to LIGHT and so on. If the respective bit is not set, the port will be skipped. START These bytes address the first port to be transmitted. END These bytes address the first port to be no more transmitted.
If the parameters are omitted, SELECT takes the value 0xFFFF, START the value 0 and END the value 0xFFFF. It is required that START <= END.
The node responds with multiple MSG_LC_STAT messages, one for every port on the node that lies in the range denoted by START and END and for which the bit corresponding to its type is set in SELECT. The order of the ports must be adhered, the answer messages need to be sequenced by the port address in ascending order.
At the end of the transmission, the node sends a MSG_LC_NA with the port address 0xFFFF.
- The request for multiple port states of a node is available from declared protocol version 0.7.
- If the node does not support queries for output states (FEATURE_CTRL_PORT_QUERY_AVAILABLE),
those ports are ignored (
SELECT &= 0xFF00).
- This message is destined for quickly reading in the port states of a node. The transmission of the responses uses the block transfer capabilities of the transport protocol, with the node adjusting to the available capacity itself. The host does not need to take any precautions against data flow stalling (cp. MSG_STALL). The node must be able to receive and respond to other messages while processing the answer sequence.
- The number of answer messages to be expected can be determined using suitable feature queries.
- MSG_LC_PORT_QUERY_ALL messages are not buffered. When a new MSG_LC_PORT_QUERY_ALL message is sent to the node during an ongoing transmission, the current sequence is aborted and a new transmission is started. By requesting an empty range, a transmission can be aborted through this.
- The MSG_LC_NA is a marker that allows to safely detect the end of the transmission even without any knowledge about the existing ports and their types.
- A query MSG_LC_PORT_QUERY_ALL 0xFF 0xFF, 0x00 0x00, 0xFF 0xFF returns the states of all ports of the node (like a query without parameters would).
- A query MSG_LC_PORT_QUERY_ALL 0x00 0xFF, 0x00, 0x00, 0x08, 0x00 on a node with the type-based port model returns only MSG_LC_NA 0xFF 0xFF, as the filter selects only inputs and the range only outputs.
- A query MSG_LC_PORT_QUERY_ALL 0x06 0x00, 0x01 0x00, 0xFF 0xFF returns the states of all light and servo ports from port address 16 and up.
Port configuration. Followed by n parameter:
MSG_LC_CONFIGX_SET parameters Parameter Description PORT These bytes address the port DATA[2…41] List with 1 to 8 key-value pairs, consisting of parameter type and value.
P_LIST ::= P_PAIR | P_PAIR P_LIST P_PAIR ::= P_ENUM P_VALUE
The node stores the parameters and responds with a MSG_LC_CONFIGX message, all filed values will be transmitted and possible parameter problems be reported via BIDIB_PCFG_NONE. If a port outside of the available range is selected, the node responds with a MSG_LC_NA message instead.
Encoding of port configuration parameters Name Code Value type Description BIDIB_PCFG_NONE 0x00 uint8 0: no parameters available
1…n: parameter error (unknown or unavailable type, invalid value). The byte denotes that parameter code. For merely invalid values, the old setting shall be conserved and sent along.
BIDIB_PCFG_LEVEL_PORT_ON 0x01 uint8 Analog brightness value for status ON, value range 0…255; (1) BIDIB_PCFG_LEVEL_PORT_OFF 0x02 uint8 Analog brightness value for status OFF, value range 0…255 BIDIB_PCFG_DIMM_UP 0x03 uint8 Step width for dimming to ON, unit 10ms (2) BIDIB_PCFG_DIMM_DOWN 0x04 uint8 Step width for dimming to OFF, unit 10ms (2) BIDIB_PCFG_OUTPUT_MAP 0x06 uint8 Mapping to output channel (like for DMX) (3) BIDIB_PCFG_SERVO_ADJ_L 0x07 uint8 Servo Adjust Low (4) BIDIB_PCFG_SERVO_ADJ_H 0x08 uint8 Servo Adjust High (4) BIDIB_PCFG_SERVO_SPEED 0x09 uint8 Servo Speed BIDIB_PCFG_IO_CTRL 0x0a uint8 IO Setup (5) BIDIB_PCFG_TICKS 0x0b uint8 Output activation time S for pulse outputs, unit 10ms BIDIB_PCFG_IS_PAIRED 0x0c uint8 Flag whether a port and its neighbor (XOR 1, i.e. addresses 0 and 1, 2 and 3, …) constitute a pair so that they cannot be activated at the same time (6). Value range: 0, 1. Only takes effect when the flag is set for the neighbor as well and both have the same type. BIDIB_PCFG_DIMM_UP_8_8 0x43 uint16 Step width for dimming to ON, unit 10ms, range 1…65535 (7) BIDIB_PCFG_DIMM_DOWN_8_8 0x44 uint16 Step width for dimming to OFF, unit 10ms, range 1…65535 (7) BIDIB_PCFG_RGB 0x80 uint24 RGB value of a coloured output: first byte Red, second Green, third Blue BIDIB_PCFG_RECONFIG 0x81 uint24 Port Reconfiguration (8) BIDIB_PCFG_CONTINUE 0xFF none an additional message will follow
- If the light control system have a different internal resolution, the values will be converted by the light control system to their own resolution. A possible need for an gamma correction should be calculated by the node itself.
- The dimming time is specified as an increment, i.e. a value of 255 'passes through' the brightness range in one step (no intermediate steps). An step width of 1 controls all possible intermediate steps. The time for one dimming step is 10ms, so times up to 2.5s can be achieved which meets the typical behaviour of light signals.
- Channel mapping: By specifying a sequence number, different LIGHT or BACK LIGHT LIGHT ports can be mapped to a common output. This allows for a configuration of different dimming speeds applied on one output.
- The values are always specified in the range from 0 to 255 and will be mapped to the servo pulse width range of 0.5ms to 2.5ms.
- IO behaviour:
- 0=output (direct controlled) (default setting),
- 1=High pulse (if turned on (1), the output will go off (0) alone after the given time S).
- 2=Low pulse (if turned off (0), the output will go on (1) alone after the given time S).
- 3=Tristate (high Z)
- 4=Input, pullup.
- 5=Input, pulldown.
- A pair of ports is treated specially when operated or queried to prevent conflicting states in outputs. Especially the simultaneous but opposite activation of double coil drives, motors and similar, which in extreme cases may damage the component, can be prohibited with this.
- If a node provides dimming times with 16-bit values, then this node can provide slower dimming ramps. This is particularly interesting for an day/night simulation at the layout illumination systems. A Node may either use 8 bit oder 16 bit values for dimming, not both.
- The type configuration parameter describes which port types are possible for the respective port, and which type is currently in use. The value consists of 3 Bytes: ACT_TYPE PORTMAP0 PORTMAP1. ACT_TYPE denotes the (to be) set port type. PORTMAP announces the available port types as a 16-bit-long bitmap; bit 0 of PORTMAP0 corresponds to SWITCH, bit 1 to LIGHT and so on. The PORTMAP is ignored when setting the parameter.
- This message obsoletes MSG_LC_CONFIG_SET. Port configuration with 'CONFIGX…' messages is available and mandatory from declared protocol version 0.6 and further.
- P_ENUM = BIDIB_PCFG_NONE is only necessary at the upstream.
- If a node cannot immediately apply the saved parameter values, it should deactivate the respective port; i.e. so that any output or query messages are declined using MSG_LC_NA with the cause BIDIB_ERR_LC_PORT_INACTIVE until the configuration becomes enabled. Additionally the node may detail the reason via MSG_SYS_ERROR, e.g. the need for a reset.
- If a port has more than 8 configuration parameters, an P_ENUM BIDIB_PCFG_CONTINUE is added after the last parameter of the first message; only one answer (consisting of multiple messages) of the node is then expected.
- A host program may only send those P_ENUMs to a node that previously has been reported from this node and this port.
Port configuration query. Followed by 2 parameters:
MSG_LC_CONFIGX_GET parameters Parameter Description PORT These bytes address the port
Message MSG_LC_CONFIGX_GET will be answered by a MSG_LC_CONFIGX message, while all current values will be received. If a port outside of the available range is selected, the node responds with a MSG_LC_NA message instead.
- This message obsoletes MSG_LC_CONFIG_GET. Port configuration with 'CONFIGX…' messages is available and mandatory from declared protocol version 0.6 and further.
- The response length of an MSG_LC_CONFIGX_GET can be up to 45 bytes, this needs to be considered in the data flow control. Typically, it is necessary to wait for the reply from MSG_LC_CONFIGX_GET before a new requests can be send to this node. MSG_LC_CONFIGX_GET_ALL doesn't have this restriction.
Query of multiple port configurations. Followed by 0 or 4 bytes; those parameters set the requested range.
MSG_LC_CONFIGX_GET_ALL parameters Parameter Description START These bytes address the first port to be transmitted. END These bytes address the first port to be no more transmitted.
If the parameters are omitted, START takes the value 0 and END the value 0xFFFF. It is required that START <= END.
The node returns multiple MSG_LC_CONFIGX messages, one for every port that is present on the node and lies in the range denoted by START and END. The order of the ports must be adhered, the answer messages need to be sequenced by the port address in ascending order.
- Port configuration with 'CONFIGX…' messages is available and mandatory from declared protocol version 0.6 and further.
- This message is destined for quickly reading in the port configuration of a node. The transmission of the answers uses the block transfer capabilities of the transport protocol, with the node adjusting to the available capacity itself. The Host does not need to take any precautions against data flow stalling. The node must be able to receive and respond to other messages while processing the answer sequence.
- The number of answer messages to be expected can be determined using suitable feature queries.
- MSG_LC_CONFIGX_GET_ALL messages are not buffered. When a new MSG_LC_CONFIGX_GET_ALL message is sent to the node during an ongoing transmission, the current sequence is aborted and a new transmission is started.
- A query MSG_LC_CONFIGX_GET_ALL 0, 0, 0xFF, 0xFF returns all ports of a node (just like a query without parameters).
- With the type-based port model in effect, the query
MSG_LC_CONFIGX_GET_ALL BIDIB_PORTTYPE_SERVO, 0, BIDIB_PORTTYPE_SERVO+1, 0 returns all servo ports of the node.
The same result can be obtained with MSG_LC_CONFIGX_GET_ALL BIDIB_PORTTYPE_SERVO, 0, BIDIB_PORTTYPE_SERVO, $SERVO_COUNT (using the memorized number of servos).
(deprecated, use MSG_LC_CONFIGX_SET instead) Port configuration in terms of its parameters. Followed by 6 parameters:
MSG_LC_CONFIG_SET parameters Parameter Description PORT These bytes address the port (using the type-based port model) DATA Configuration values
The configuration values are always given as a uint8 (in the range 0…255). Their meaning depends on the port type, each of them corresponds to a CONFIGX-key-value-pair:
Typ (PORT0) DATA0 DATA1 DATA2 DATA3 Switch output
Typically, there is no configuration for switch outputs. However, for special applications a configuration may be useful. The feature FEATURE_SWITCH_CONFIG_AVAILABLE defines whether this configuration of switch ports is available. If the feature is missing, configuration is not possible and the switches can only be set. BIDIB_PCFG_IO_CTRL BIDIB_PCFG_TICKS reserved reserved Light output
For light outputs, the minimum / maximum brightness and the dimming speed can be configured. It is possible to additionally slow down the dimming via the feature FEATURE_CTRL_STRETCH_DIMM (if available) up to a factor of 250. The whole transition may last up to 10min and can be used for daylight-night simulations on a layout. BIDIB_PCFG_LEVEL_PORT_OFF BIDIB_PCFG_LEVEL_PORT_ON BIDIB_PCFG_DIMM_DOWN BIDIB_PCFG_DIMM_UP Servo output
For servo outputs, the lower and upper limits and the turnaround speed of the servo are adjustable. BIDIB_PCFG_SERVO_ADJ_L BIDIB_PCFG_SERVO_ADJ_H BIDIB_PCFG_SERVO_SPEED reserved Light output
For light outputs with directly settable brightness a channel mapping for the assignment to actual hardware and the dimming speed can be configured. BIDIB_PCFG_DIMM_DOWN BIDIB_PCFG_DIMM_UP BIDIB_PCFG_OUTPUT_MAP reserved 3, 4, 5, … Detailed definitions for sound, motor and analog voltage outputs will follow.
Reserved values are coded with 0.
The node stores this parameters and responds with a MSG_LC_CONFIG message. If an non existing port (outside of the available range) is selected, the node responds with a MSG_LC_NA message instead.
(deprecated) Query of a port in terms of its parameters. Followed by 2 parameters:
MSG_LC_CONFIG_GET parameters Parameter Description PORT These bytes address the port
If a port outside of the available range is selected, the node responds with a MSG_LC_NA message instead of MSG_LC_CONFIG.
This message is sent when an attempt was made to switch an output, which is not present on the node. Followed by 2 or 3 bytes with type, number of this oputput and cause of the error.
MSG_LC_NA parameters Parameter Description PORT These bytes address the port ERRCAUSE[0…1] Optional for cause of the exception Encoding of error causes Value Name Meaning 0 reserved (internal use in nodes or host programs) 1 BIDIB_ERR_LC_PORT_GENERAL (or when omitted) Error cause not detailed 2 BIDIB_ERR_LC_PORT_UNKNOWN Port is unknown and not usable. The addressed port or type does not exist on this node. This problem is not salvageable.
Example: A node announces only 16 ports via its features, but port 20 is addressed.
3 BIDIB_ERR_LC_PORT_INACTIVE Port is currently unusable because of the node configuration. It is deactivated, not available for the requested action. This error can be averted through a reconfiguration.
Example 1: Assuming the flat port model, port 0 can be configured as either SWITCH or SERVO, but blocks port 1 in the second case. Port 1 then responds to commands with BIDIB_ERR_LC_PORT_INACTIVE.
Example 2: A port has been configured with incompatible (but on its own valid) parameters, or a parameter change is not yet effective until a reboot. Meanwhile, it declines switching commands.
4 BIDIB_ERR_LC_PORT_EXEC Execution of operation impossible.
Examples: A SWITCH port receives a command with PORTSTAT 5. Or an output port in the flat port model is getting a MSG_LC_KEY_QUERY request.
5…254 reserved 255 BIDIB_ERR_LC_PORT_BROKEN Problem with hardware. This message is dedicated for the announced port. More precise reports on the cause (like internal exception, power supply, etc) may be sent through the generic error messages.
- A host program should show the cause when the ERRCAUSE parameter exists. When the value is unknown, the plain number should be shown.
This message transmits the current state of a port. Followed by 3 bytes: PORT0, PORT1, PORTSTAT.
For outputs, it is sent as the answer to a query or as the acknowledgement to an operation command when the output reaches the desired state. If the output has more than 100 ms switching time, a MSG_LC_WAIT message is sent back immediately after receiving the MSG_LC_OUTPUT.
For inputs, it is sent as the answer to a query or also spontaneously when the condition of the port changes while the node is enabled and has the FEATURE_CTRL_INPUT_NOTIFY set.
MSG_LC_STAT parameters Parameter Description PORT These bytes address the port PORTSTAT Depending on the port type: output status, coded like for MSG_LC_OUTPUT, or input status:
- 0: open.
- 1: closed.
If an input is part of a pair, its neighbor is queried as well, it is expected that its state will be complementary. When their states are equal it is counted as an error, a MSG_LC_NA will be sent instead of MSG_LC_STAT.
- This message is supposed to allow the host to access the node-internal port states, e.g. for displaying them appropriately. However, the transmission is not specially secured with acknowledgements or message repetition. Where this is required, accessories or detectors should be used.
This message is sent as an immediate acknowledgement when the output reaches its requested state only after a time of 100ms or more.
Followed by 3 bytes: PORT0, PORT1, TIME.
MSG_LC_WAIT parameters Parameter Description PORT These bytes address the port TIME Predicted rotation time. This rotation time is coded analogously to the railcom specification as follows: The lower 7 bits of the remaining running time indicates the running time until the end-status of the requested switching action (predicted rotation time). Depending on the MSB, the time is specified in units of 1/10 seconds (MSB = 0), or 1 second (MSB = 1). A time of 0 means: no switching time can be determined. This results in a value range from 0…12,7 seconds or 0…127 seconds.
(deprecated, from declared protocol version 0.7 only MSG_LC_STAT is used)
This message is sent when the node contains local buttons and these have been pressed or when an explicit request was made. This message occurs spontaneously (MSG_SYS_ENABLE and the corresponding feature must be set) and will not be repeated. Followed by 2 bytes: PORT, KSTATE.
MSG_LC_KEY parameters Parameter Description PORT Button number. Corresponds to PORT0 in the flat port model and to PORTNUM in the type-based one (with PTYPE=15). KSTATE Status of the button:
- 0: not pressed.
- 1: pressed.
Messages of a port concerning his parameters. Followed by 4 or up to an maximum of 43 parameter bytes.
MSG_LC_CONFIGX parameters Parameter Description PORT These bytes address the port DATA[2…42] List with 1 to 8 key-value pairs, consisting of parameter type and value. Their encoding corresponds to the MSG_LC_CONFIGX_SET message.
- This message obsoletes MSG_LC_CONFIG. Port configuration with 'CONFIGX…' messages is available and mandatory from declared protocol version 0.6 and further.
- If a port has more than 8 configuration parameters, an P_ENUM BIDIB_PCFG_CONTINUE is added after the last parameter of the first message. This informs the host program about an transmission of an additional MSG_LC_CONFIGX message.
- P_ENUM = BIDIB_PCFG_RECONFIG is only needed when the flat port model is used. It always has to sent in the upstream to announce the active port type to the host – even when the node does not support reconfigurations and the current type is the only available one.
(deprecated) This message is sent after a configuration or after a query using MSG_LC_CONFIG_GET.
Followed by 6 parameters, order and coding is equal to MSG_LC_CONFIG_SET.
Accessories controllers can have the ability to provide macro functionality, this ability may vary significantly and is defined by a level. Whether macros are supported and which level of the macro capability is supported, can be checked by a feature query.
Similarly, the number and possible length of macro channels can also be checkes through a feature query.
Macros with level 1 functionality contain a linear list of switchpoints with the ability to perfom certain actions. A switching point is defined by the time interval to the previous switchpoint, by the port that is acted on and the command value. Each of those action corresponds to a MSG_LC_OUTPUT instruction. In addition, a macro have also general parameters, such as step speed on which the macro itself is running.
(Note: Through smart programming, the MSG_LC_OUTPUT command can be reduced to 2 bytes. This allows a large number of switching points in macros even with low memory.)
Macros with level 2 functionality also contain a linear list of switching points (corresponding to level 1), in addition, there are switching points with the ability to start and stop other macros and synchronize different macro runs and also allows input queries (e.g. limit switches or control buttons). This allows the implemention of small local sequences, often used for animated scenes on the model railroad.
A macro is therefore a sequence of actions on a node that is executed in a specific pattern. The grid for macro execution is defined by MACRO_TICK. MACRO_TICK is given by BIDIB_MACRO_PARA_SLOWDOWN (see below), multiplied by the base unit of 20ms.
Example: Adjust BIDIB_MACRO_PARA_SLOWDOWN to 50, the result is MACRO_TICK value 50 * 20ms = 1s. The macro will be incremented by one TICK at every second.
Macros are independent. Macros can be individually loaded, modified and started. A specific action or a specific output port may appear in several different macros. The number of simultaneously started macros is depending on the decoder.
This example shows a traffic light, a macro A should change the traffic light to the aspect 'STOP', another macro B should switch the traffic light to aspect 'GO'.
|0||Turn on output for 'YELLOW'.|
|0||Turn off output for 'GREEN'.|
|10||Turn on output for 'RED'.|
|0||Turn off output for 'YELLOW'.|
Explanation: At the macro start, YELLOW will be switched on and GREEN will be switched off without any delay (i.e. the traffic light jumps to yellow). The next action is delayed for 10 ticks, after this waiting time the RED light will be switch on and the YELLOW light switch off without any further delay.
|0||Turn on output for 'YELLOW'.|
|10||Turn off output for 'RED'.|
|0||Turn off output for 'YELLOW'.|
|0||Turn on output for 'GREEN'.|
With this macro, YELLOW is switched on first, then RED and YELLOW will be switched off after a delay and GREEN will be switched on at the same time.
The ability to perform and the level of support for macros can be ckecked with feature-requests:
|60||FEATURE_CTRL_MAC_LEVEL||Supported level for macros|
0 = No macro support
1 = Macros of level 1 (simple list of actions)
2 = Macros of Level 2 (list of actions, with requests, start, stop, random)
|61||FEATURE_CTRL_MAC_SAVE||Persistent storage of macros|
0 = No persistent storage available;
1…n = Number of storage locations for persistent storage usable
|62||FEATURE_CTRL_MAC_COUNT||Quantity of possible macros|
0 = No macro support
1…n = Quantity of macros whith the given level
|63||FEATURE_CTRL_MAC_SIZE||Size of local macros|
0 = no macro support;
1…n = Number of steps for each macro
|64||FEATURE_CTRL_MAC_START_MAN||Starting macros caused by local inputs|
0 = It is not possible to start macros because of local inputs
1 = Macros can be started because of local inputs. The following assignment is valid: Input 0 is starting macro 0, input 1 is starting macro 1, etc.
|65||FEATURE_CTRL_MAC_START_DCC||Starting macros caused by DCC|
0 = It is not possible to start macros because of DCC.
1 = Macros can be started by DCC commands. The selection of the DCC address will be done with the usual actions (e.g. via programming key or CV programming). accessory command 0 is starting macro 0, etc.
There are the following commands to create and manage macros:
Followed by 2 bytes: macro index, operation code. The respective operation will be answered with a MSG_LC_MACRO_STATE.
Encoding of macro operation code Value Name Meaning 0 BIDIB_MACRO_OFF Macro should be canceled. 1 BIDIB_MACRO_START Macro should be started. 2…0xFB reserved. 0xFC (=252) BIDIB_MACRO_RESTORE Restore. The defined macro will be loaded from the flash memory (if available, this can be verified by a features query) and overwrites the currently loaded macro. If no permanent memory is available, the macros will be deleted. (same as BIDIB_MACRO_DELETE). 0xFD (=253) BIDIB_MACRO_SAVE Save. The defined macro will be saved into the flash memory (if available, this can be verified by a features query) and is again available after system restart. 0xFE (=254) BIDIB_MACRO_DELETE Deletion of a macro. The contents of the specified macro will be deleted. This operation is identical with the set of all(!) switching states to 255, 255 (END_OF_MACRO).
- Saving a macro can take some time in the node. Depending on the implementation of this node, the node might be not able to answer on request at this time. It is therefore necessary to wait for the confirmation of this command before sending any other commands.
Setting a macro switch point, this defines an individual macro point. Followed by 6 parameters:
MSG_LC_MACRO_SET parameters Parameter Description DATA0 Macro index DATA1 Index of the point within the macro DATA2 DELAY: delay time in relation to the previous point. Value range 0…250 SYS_TYPE: undelayed invocation of a system function. Value range 251…255 DATA3 PORT: These bytes address the port SYS_CMD: System function, e.g. the end of an macro DATA4 SYS_ARG: Arguments for the system function.
Bytes not used by the respective function are coded with 0, they will be transferred but not evaluated.
DATA5 PORTSTAT: Switching status according to the table at MSG_LC_OUTPUT
Setting a macro switch point is answered with a MSG_LC_MACRO message. If a configured port outside of the available port range, the macro is terminated at execution at this point.
The end of an macro is signaled through setting all parameters to 255, or when the available memory for macros is full.
DELAY, Delay time: The number which is specified at this point is the time, relative to the previous macro point. A time of 0 means no time gap between the actions (although they are usually executed one after the other because of physical reasons). The time specified here is the number of MAKRO_TICKs, which pass until the command will be executed. The valid range is 0…250.
The actual waiting time is given by this number, multiplied with the macro execution speed. Times from 20 ms up to over 20 min can be realized in this way.
For Level 2 macros, the following system functions are defined in the following table (for delay = 255):
Encoding of system functions for DELAY=255 (macro level 2) Value Name Function 255 BIDIB_MSYS_END_OF_MACRO The macro will be terminated. 254 BIDIB_MSYS_START_MACRO The macro specified in SYS_ARG0 will be started. This may also be the current macro, it will start again. 253 BIDIB_MSYS_STOP_MACRO The macro specified in SYS_ARG0 will be stopped. "Stop" here means end, not pause. If the target macro is in a critical section, the stop request is executed after the critical section. 252 BIDIB_MSYS_BEGIN_CRITCAL The macro is not stopped by a stop request, the current sequence has to be completed (until END_CRITICAL).
Example: The motion of an mechanical object can't be stopped on 'halfway'.
251 BIDIB_MSYS_END_CRITCAL The macro can be stopped by a stop request (default) 250 BIDIB_MSYS_FLAG_QUERY1 The flag specified in SYS_ARG0 is queried. If it's not set, the macro execution is paused until the flag (e.g. by another macro) is set. 249 BIDIB_MSYS_FLAG_SET The flag specified in SYS_ARG0 will be set. Value range: 0…15 248 BIDIB_MSYS_FLAG_CLEAR The flag specified in SYS_ARG0 will be unset. Value range: 0…15 247 BIDIB_MSYS_INPUT_QUERY1 The input or switch specified in SYS_ARG is queried like with MSG_LC_PORT_QUERY. For the flat port model, the port address is given, for the type-based one only the PORTNUM is coded in SYS_ARG0 (with PTYPE=15).
If the switch is open (PORTSTATE=0), the macro execution is paused; when the switch is closed (PORTSTATE=1), the macro execution continues.
246 BIDIB_MSYS_INPUT_QUERY0 The input or switch specified in SYS_ARG is queried like with MSG_LC_PORT_QUERY. For the flat port model, the port address is given, for the type-based one only the PORTNUM is coded in SYS_ARG0 (with PTYPE=15).
If the switch is closed (PORTSTATE=1), the macro execution is paused; when the switch is open (PORTSTATE=0), the macro execution continues.
245 BIDIB_MSYS_DELAY_RANDOM The macro execution is delayed by a random time. The time span is randomly chosen from an interval of 0…SYS_ARG0 MACRO_TICKS on every invocation. This for example allows realistic sequences of building lights. 244 BIDIB_MSYS_DELAY_FIXED The macro execution is delayed by a fixed time from 0 to 255 MACRO_TICKS. The time is specified at the SYS_ARG0 field. 243 BIDIB_MSYS_ACC_OKAY_QIN1 The input or switch specified in SYS_ARG is queried like with MSG_LC_PORT_QUERY. For the flat port model, the port address is given, for the type-based one only the PORTNUM is coded in SYS_ARG0 (with PTYPE=15).
If the switch is closed (PORTSTATE=1), the associated accessory will get a notify 'position reached and verified by feedback'. If the switch is open (PORTSTATE=0), a feedback error will be reported.
242 BIDIB_MSYS_ACC_OKAY_QIN0 The input or switch specified in SYS_ARG is queried like with MSG_LC_PORT_QUERY. For the flat port model, the port address is given, for the type-based one only the PORTNUM is coded in SYS_ARG0 (with PTYPE=15).
If the switch is open (PORTSTATE=0), the associated accessory will get a notify 'position reached and verified by feedback'. If the switch is closed (PORTSTATE=1), a feedback error will be reported.
241 BIDIB_MSYS_ACC_OKAY_NF The associated accessory will get a notify 'position reached' (with the additional info: no Feedback available). 240 BIDIB_MSYS_SERVOMOVE_QUERY The servo specified in SYS_ARG is queried. For the flat port model, the port address is given, for the type-based one only the PORTNUM is coded in SYS_ARG0 (with PTYPE=2).
If the servo is still moving, the macro execution is paused. If the movement is finished, the macro execution will continue.
239 BIDIB_MSYS_FLAG_QUERY0 The flag specified in SYS_ARG0 is queried for value 0. If the flag is set, the macro execution is paused until the flag (e.g. by another macro) is cleared.
Query of an macro point, followed by 2 bytes with macro index and switchpoint index. This query will be answered with an MSG_LC_MACRO message.
MSG_LC_MACRO_GET parameters Parameter Description DATA0 Index of the macro in which the switching point is queried. DATA1 Index of the switching point within the macro.
The indices will be counted from 0.
Puts a general parameter for a macro, this defines the execution parameters of the macro: Macrospeed, execution mode (e.g. repetitive), start condition and so on. Followed by 6 parameters:
MSG_LC_MACRO_SET_PARA parameters Parameter Description DATA0 Macro index DATA1 Parameter index DATA2 Parameter value (LSB) DATA3 Parameter value DATA4 Parameter value DATA5 Parameter value (MSB)
Setting of an macro parameter is answered with a MSG_LC_MACRO_PARA message.
Index values of the parameters:
Encoding of macro configuration parameters Value Name Meaning 1 BIDIB_MACRO_PARA_SLOWDOWN Speed of the macro. The processing speed will be defined. with this value. The base unit is 20ms.
Value range: 1…250
Default setting: 1.
Example: At a setting of 5, the macro switchs every 100ms to the next macro tick. So if then 2 is specified in the macro list, this means a time interval of 200ms between the actions in total.
2 BIDIB_MACRO_PARA_REPEAT Repetitions of the macro. The macro is repeated as often as indicated here. If this value is set to 0, then the macro will be repeated continuously.
Value range: 0…250
Default setting: 1, this means, the macro will be executed one time.
3 BIDIB_MACRO_PARA_START_CLK Enable macro start by system clock. DATA2 until DATA5 contains the time as TCODE (see also the explanations at the MSG_SYS_CLOCK command).
In addition to the start at a particular model-time, there is also the possibility to define repetitive macro starts, e.g. every hour, or every day at the same hour. This is achieved by specifying a TCODEs which can not be contained in a normal time message. Such TCODEs are trigger conditions, similar to a 'wildcard' and they will be fulfilled at several time points:
TCODEx Description 00mmmmmm mmmmmm = Specification of minute:
0…59: defined start time
60: Start every minute
61: Start every half hour (this means at 0,30)
62: Start every quarter hour (this means at 0,15,30,45)
100HHHHH HHHHH = Specification of hour:
0…23: defined start time
24: Start every hour
25: Start every hour, 8:00 until 17:00
01000www www = Week day, 0=Monday, 1=Tuesday, … 6=Sunday.
7: Start every day
110fffff fffff = Clock acceleration factor (not relevant for macro).
If the start should prevented via TCODE, all trigger conditions have to be set to void, i.e. for min/hr/day the data value 0x3F must be specified. So if the trigger must be switched off completely, then 0x3f, 0xbf, 0x7f, 0xff needs to be transmitted.
Default setting: 0x3f, 0xbf, 0x7f, 0xff (=off)
TCODE = (0x00 + 15), (0x80 + 24), (0x40 + 7): One start every day, every hour, always at minute 15.
TCODE = (0x00 + 00), (0x80 + 18), (0x40 + 7): One start every day at 18:00
tbd. tbd. Enable macrostart via DCC-switch command. tbd. tbd. Enable macrostart via external input.
If a node is able to store macros permanently, the macro parameters must be also stored during this process.
Query of an makro parameter, followed by 2 bytes with macro index und parameter index. This query will be answered with a MSG_LC_MACRO_PARA message.
The message is sent as an acknowledgement after the change of state (operation) of a macro. followed by 2 bytes with macro index and status.
Encoding of macro status Value Name Meaning 0 BIDIB_MACRO_OFF Macro is halted 1 BIDIB_MACRO_START Macro will be started 2 BIDIB_MACRO_RUNNING Macro is already running 252 BIDIB_MACRO_RESTORE Macro has been restored 253 BIDIB_MACRO_SAVE Macro has been saved 254 BIDIB_MACRO_DELETE Macro has been erased 255 BIDIB_MACRO_NOTEXIST Macro is not existing (Macro index to large during call;)
Transmission of a requested macro point, followed by 6 bytes with macro index and switchpoint index and the content of this point. The coding is identical to MSG_LC_MACRO_SET.
Transmission of a requested macro parameter, followed by 6 bytes with macro index, parameter index and parameter value (data). If the parameter does not exist in the node, then the value 0xFF will be returned for all data bytes.
MSG_LC_MACRO_PARA parameters Parameter Description DATA0 Macro index DATA1 Parameter index DATA2 Parameter value(LSB) DATA3 Parameter value DATA4 Parameter value DATA5 Parameter value (MSB)