BiDiB

• Summary
• Examples

Protocol

• Introduction
• General Messages
• Firmware Update
• Command Station
• Accessory Control
• Accessory Configuration
• Occupancy
• Booster
• Distributed Control

• Printable Version

BiDiB, a universal control set for model railways

Peripheral Equipment, Light, Switches

Content

• 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

General

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.29 of BiDiB, updated June 21, 2023.

The revision history can be found at the general section.

4.6.5. Controlling of peripheral functions

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.

In the type-based port model only port types of width 1 are used. Other widths are applicable only in the flat model, where a different number of ports may be available depending on the type configuration. Two outputs with exclusive activation can be represented as one SWITCH port in the type-based model.

4.6.6. Features for peripherals

The properties of the nodes (for example the quantity of each specific kind of output) can be read with feature-requests:

4.6.7. Downlink: Messages for peripheral / switching functions

• MSG_LC_OUTPUT:

  Direct output operation, followed by 3 Bytes: PORT₀, PORT₁, 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[2]	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, the following operations are available: Value Name Operation 0 BIDIB_PORT_TURN_OFF Stop playing 1 BIDIB_PORT_TURN_ON Play sound 2-255 - reserved BIDIB_PCFG_TICKS is used to distinguish between continuous (repeat) mode and moment activation. 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. 7 (=BIDIB_PORTTYPE_SWITCHPAIR) Alternating activation of two switch outputs, e.g. for coil drives. The following operations are available: Value Name Operation 0 BIDIB_PORT_TO_0 Switch first output on and second one off 1 BIDIB_PORT_TO_1 Switch first output off and second one on 2-255 - reserved Compare RCN 213, Description of the R-Bit in the format of basic accessory commands. For standard applications, PORTSTAT = 0 means turnout to diverging or left track resp. signal at stop ("red") and PORTSTAT = 1 means turnout to straight or right track resp. signal at clear ("green"). 7…15 reserved

  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.

• MSG_LC_PORT_QUERY:

  (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.

  Hints:

  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.

• MSG_LC_KEY_QUERY:

  (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.

• MSG_LC_PORT_QUERY_ALL:

  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[2]	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[2]	These bytes address the first port to be transmitted.
  END[2]	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.

  Hints:

  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.

  Examples:

  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.

• MSG_LC_CONFIGX_SET:

  Port configuration. Followed by n parameter:

  MSG_LC_CONFIGX_SET parameters

  Parameter	Description
  PORT[2]	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	Pace for dimming to ON, as steps performed per 10ms (2), range 1…255
  BIDIB_PCFG_DIMM_DOWN	0x04	uint8	Pace for dimming to OFF, as steps performed per 10ms (2), range 1…255
  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_SERVO_EXTRA	0x0a	uint8	Special settings for servo, bitfield. Bit 0: Switch off voltage. If this bit is set, servo power is turned off after motion. This saves current and reduces possible small movements in the target position.
  BIDIB_PCFG_TICKS	0x0b	uint8	Output activation time, unit 10ms. After the stated time, the output is switched off automatically to prevent an overload. Through repeated switch commands the tripping may be postponed. The value 0 represents a continuous output.
  BIDIB_PCFG_SWITCH_CTRL	0x0d	uint8	Electrical behaviour of SWITCH ports. The upper nibble encodes the behaviour for the ON state, the lower nibble for the OFF state. Each of the two nibbles has the following value range: 0: LOW (put to GND) 1: HIGH (put to VCC) 2: Z (high impedance) 3: WEAK_LOW (pulled to GND with resistor, no current load) 4: WEAK_HIGH (pulled to VCC with resistor, no current load) If WEAK_LOW or WEAK_HIGH are not supported, the node has to treat them like Z.
  BIDIB_PCFG_INPUT_CTRL	0x0e	uint8	Electrical behaviour of INPUT ports. Value range: 0: ACTIVE_LOW (the input is active when connected to GND) 1: ACTIVE_HIGH (the input is active when VCC is applied) 2: ACTIVE_LOW + PULLUP (the input is pulled to VCC with a great resistor for well-defined idle state) 3: ACTIVE_HIGH + PULLDOWN (the input is pulled to VCC with a great resistor for well-defined idle state) If PULLUP or PULLDOWN are not supported, the node has to respect only the LSB.
  BIDIB_PCFG_LOAD_TYPE	0x0f	uint8	Load type of an OUTPUT port. Value range: 0: general (switch only, ignore possible errors) 1: resistive load 2: magnetic coil without limit stop 3: magnetic coil with limit stop If switch observation is not supported, the parameter is not used.
  BIDIB_PCFG_MOVE_TYPE	0x10	uint8	Servo motion pattern, motion curve (5) The value consists of 2 nibbles of 4 bits each. Each nibble selects a type of movement, with the low-order nibble (4 LSBs) applies to movements where the target value is greater than the start value. The higher-order nibble (4 MSBs) applies to movements, where the target value is less than the start value. Value range: 0=linear movement 1=Smooth start, smooth end 2=Smooth start, coasting with teetering. 3=Smooth start, coasting with rebound. 4-14=reserved 14=reserved for full user defined 1 15=reserved for full user defined 2 If the node does not support a BIDIB_PCFG_MOVE_TYPE, the default value 0=linear motion is used.
  BIDIB_PCFG_DIMM_UP_8_8	0x43	uint16	Pace for dimming to ON, as steps performed per 10ms (2), range 1…65535 (6)
  BIDIB_PCFG_DIMM_DOWN_8_8	0x44	uint16	Pace for dimming to OFF, as steps performed per 10ms (2), range 1…65535 (6)
  BIDIB_PCFG_TRANSITION_TIME	0x46	uint16	Time for gentle transition between port states, like fading colors or dimming brightness. Unit 10ms, range 0…65535
  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 (7)
  BIDIB_PCFG_CONTINUE	0xFF	none	an additional message will follow

  (1)

  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.

  (2)

  The dimming pace is specified as an increment, i.e. the maximum value '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.

  (3)

  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.

  (4)

  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.

  (5)

  The motion curves are scaled linearly with the adjustment values ​​of the servo (BIDIB_PCFG_SERVO_ADJ_L and BIDIB_PCFG_SERVO_ADJ_H) and stretched in time. The start and end points are inside the maximum possible range, in order to have some reserve, e.g. for planned overshoots when teetering.

  (6)

  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.

  (7)

  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 PORTMAP₀ PORTMAP₁. ACT_TYPE denotes the (to be) set port type. PORTMAP announces the available port types as a 16-bit-long bitmap; bit 0 of PORTMAP₀ corresponds to SWITCH, bit 1 to LIGHT and so on. The PORTMAP is ignored when setting the parameter.

  Hints:

  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.

• MSG_LC_CONFIGX_GET:

  Port configuration query. Followed by 2 parameters:

  MSG_LC_CONFIGX_GET parameters

  Parameter	Description
  PORT[2]	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.

  Hints:

  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.

• MSG_LC_CONFIGX_GET_ALL:

  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[2]	These bytes address the first port to be transmitted.
  END[2]	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.

  Hints:

  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.

  Examples:

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

• MSG_LC_CONFIG_SET:

  (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[2]	These bytes address the port (using the type-based port model)
  DATA[4]	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 0 (=BIDIB_PORTTYPE_SWITCH)	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.
  	IO-Setup (1)	BIDIB_PCFG_TICKS	reserved	reserved
  Light output 1 (=BIDIB_PORTTYPE_LIGHT)	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 2 (=BIDIB_PORTTYPE_SERVO)	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 6 (=BIDIB_OUTTYPE_BACKLIGHT)	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 analogue voltage outputs will follow.

  Reserved values are coded with 0.

  (1)

  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.

  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.

• MSG_LC_CONFIG_GET:

  (deprecated) Query of a port in terms of its parameters. Followed by 2 parameters:

  MSG_LC_CONFIG_GET parameters

  Parameter	Description
  PORT[2]	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.

4.6.8. Uplink: Messages for peripheral / switching functions.

• MSG_LC_NA:

  This port message is sent in exceptional cases. It might occur when switching or configuring an output errors, or when the end of a QUERY_ALL transmission is reached. Followed by 2 or 3 bytes stating the port and an error cause.

  MSG_LC_NA parameters

  Parameter	Description
  PORT[2]	These bytes address the port. Port 0xFFFF signals the completion of a transmission of multiple ports.
  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 SWITCHPAIR, 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.

  Hint:

  A host program should show the cause when the ERRCAUSE parameter exists. When the value is unknown, the plain number should be shown.

• MSG_LC_STAT:

  This message transmits the current state of a port. Followed by 3 bytes: PORT₀, PORT₁, 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[2]	These bytes address the port
  PORTSTAT	Depending on the port type: output status, coded like for MSG_LC_OUTPUT, or input status: 0: inactive (open). 1: active (closed). (Usually switches/push buttons are connected to ground, they will pull the processor input to low if the key is closed/pressed (=active low). This can be configured differently through PCFG_INPUT_CTRL if available.)

  Hint:

  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.

• MSG_LC_WAIT:

  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: PORT₀, PORT₁, TIME.

  MSG_LC_WAIT parameters

  Parameter	Description
  PORT[2]	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.

• MSG_LC_KEY:

  (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.

• MSG_LC_CONFIGX:

  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[2]	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.

  Hints:

  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.

• MSG_LC_CONFIG:

  (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.

4.6.9. Local macros

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 implementation 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.

4.6.10. Features for local macros

The ability to perform and the level of support for macros can be ckecked with feature-requests:

4.6.11. Downlink: Messages for local macros

There are the following commands to create and manage macros:

• MSG_LC_MACRO_HANDLE:

  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). A following command BIDIB_MACRO_SAVE will also delete the content in flash memory.

  Hint:

  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.

• MSG_LC_MACRO_SET:

  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[2]: These bytes address the port	SYS_CMD: System function, e.g. the end of an macro
  DATA4		SYS_ARG[2]: 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.

• MSG_LC_MACRO_GET:

  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.

• MSG_LC_MACRO_PARA_SET:

  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). A macro always starts when the node detects a match at minute, hour and day. 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) Examples: 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.

• MSG_LC_MACRO_PARA_GET:

  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.

4.6.12. Uplink: Messages for local macros

• MSG_LC_MACRO_STATE:

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

• MSG_LC_MACRO:

  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.

• MSG_LC_MACRO_PARA:

  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)