BiDiB.org

Support for Vendors

Mail Group

User Configuration

DCC-Mapping

Code examples

Analysing tools

BiDiBus Logger

DCC-Mapping

When operating without a control program as a host, it should be possible to control BiDiB nodes as well as DCC vehicles and accessories with handheld controllers or similar that only support commands according to RCN 212 and RCN 213.

To do this, the DCC addresses and aspects received from the handheld controller must be mapped to the aspects and accessories of a BiDiB node for accessories (Aspect-Mapping) or to a BiDiB DCC generator node (Generator-Mapping).

The data required for this is transmitted using the text-based vendor messages (see chapter Messages for user configuration).

Aspect-Mapping

With aspect mapping, DCC accessory addresses and aspects can be mapped to the accessories of BiDiB nodes their aspects. It is an N:M mapping, the mapping is arbitrary and multiple mappings are possible. One line in the memory table therefore corresponds to one mapping of a DCC aspect to a BiDiB aspect. The following convention describes the use of certain vendor messages to transfer such a table from the host to an adapter node (typically of the handheld or hub class) and allows the listing, addition and deletion of rows.

Example scenario:

The aspect mapping is created by the user as part of the layout configuration and stored as an AspectMapping table in one (or more) nodes acting as DCC adapters. During operation, the adapter application accepts the DCC commands from the handheld controller, converts them into the BiDiB format for accessories and sends them to the corresponding BiDiB nodes according to the AspectMapping table.

Format

The messages follow the key/value standard of the general BiDiB specification: ASCII strings with a length byte as prefix.

The key to identify an entry contains alongside a prefix (AME) the full mapping, in which the individual parts are separated by one space each:

<VID><PID1><PID2><PID3><PID4> <ACC-Nr> <ASP-Nr> <DCC-Addr> <DCC-Aspect>

The value indicates whether the mapping exists in the table or not (via 0x01 "1" resp. 0x00 ""), which is used for both writing and reading.

Used abbreviations
Abbreviation	Name	Meaning	type
AME	AspectMappingEntry	Operation for an entry	constant
AMR	AspectMappingRange	Operation for a range	constant
`<VID><PID1><PID2><PID3><PID4>`	Node-ID	Vendor-ID and Product-ID-bytes of the node	hex string (two characters per byte)
`<ACC-Nr>`	Accessory	BiDiB-Accessory-Number	decimal number
`<ASP-Nr>`	Aspect	Aspect of the BiDiB accessory	decimal number
`<DCC-Addr>`	DCC Address	Accessory according to RCN 213	decimal number
`<DCC-Aspect>`	DCC Aspect	Aspect according to RCN 213	constant "R" or "G"
`0xnn`	Length	variable length of the key resp. value	raw byte
"1"	Value	the mapping entry exists	constant
""	Empty value	the mapping entry does not exist	constant
`<offset>`	Offset		decimal number
`<limit>`	Limit		decimal number
`<count>`	Count		decimal number

Operations

AME - Entry Write:
With this message, the specified AspectMapping table row is created in the node, symbolized by the value 0x01 "1". If the row already exists, it is kept.

The vendor message is structured as follows:
```
MSG_VENDOR_SET 0xnn "AME <VID><PID1><PID2><PID3><PID4> <ACC-Nr> <ASP-Nr> <DCC-Addr> <DCC-Aspect>" 0x01 "1"
```
The successful execution of the operation is acknowledged with the “mirrored” message including the value “1”. If the operation could not be applied, the acknowledgment contains the old value (empty) for the table entry. In addition, an error message can be sent to detail the reason.

Response - OK (input-value mirrored):
```
MSG_VENDOR 0xnn "AME <VID><PID1><PID2><PID3><PID4> <ACC-Nr> <ASP-Nr> <DCC-Addr> <DCC-Aspect>" 0x01 "1"
```
Response - NOK (old value):
```
MSG_VENDOR 0xnn "AME <VID><PID1><PID2><PID3><PID4> <ACC-Nr> <ASP-Nr> <DCC-Addr> <DCC-Aspect>" 0x00 ""
```
Response - NOK (e.g. out of memory):
```
MSG_VENDOR 0xnn "AME <VID><PID1><PID2><PID3><PID4> <ACC-Nr> <ASP-Nr> <DCC-Addr> <DCC-Aspect>" 0x00 ""
+ MSG_SYS_ERROR BIDIB_ERR_TXT "out of memory"
```
AME - Entry Delete:
With this message, the specified AspectMapping table row in the node is deleted, symbolized by the empty value (0x00 ""). If the row did not exist, it remains absent.

The vendor message is structured as follows:
```
MSG_VENDOR_SET 0xnn "AME <VID><PID1><PID2><PID3><PID4> <ACC-Nr> <ASP-Nr> <DCC-Addr> <DCC-Aspect>" 0x00 ""
```
The response consists of the “mirrored” request with the value. A deleted mapping is acknowledged with the empty value (0x00 ""). If an mapping could not be deleted and still exists, this is reported with the value 0x01 "1" and optionally an error message with the reason.

Response - OK (value mirrored):
```
MSG_VENDOR 0xnn "AME <VID><PID1><PID2><PID3><PID4> <ACC-Nr> <ASP-Nr> <DCC-Addr> <DCC-Aspect>" 0x00 ""
```
Response - NOK (old value):
```
MSG_VENDOR 0xnn "AME <VID><PID1><PID2><PID3><PID4> <ACC-Nr> <ASP-Nr> <DCC-Addr> <DCC-Aspect>" 0x01 "1"
```
AME - Entry Read:
With this message, the presence of a mapping entry in the table is read from the node.

The vendor message is structured as follows:
```
MSG_VENDOR_GET 0xnn "AME <VID><PID1><PID2><PID3><PID4> <ACC-Nr> <ASP-Nr> <DCC-Addr> <DCC-Aspect>"
```
Both a present and a missing entry for this mapping are acknowledged with a message with a “mirrored” key:

Response - (entry found, exists):
```
MSG_VENDOR 0xnn "AME <VID><PID1><PID2><PID3><PID4> <ACC-Nr> <ASP-Nr> <DCC-Addr> <DCC-Aspect>" 0x01 "1"
```
Response - (entry is missing, does not exist):
```
MSG_VENDOR 0xnn "AME <VID><PID1><PID2><PID3><PID4> <ACC-Nr> <ASP-Nr> <DCC-Addr> <DCC-Aspect>" 0x00 ""
```
AMR - Range Delete All:
With this message, all mappings are deleted from the table of the node, symbolized by the empty value (0x00 "").

The vendor message is structured as follows:
```
MSG_VENDOR_SET 0x05 "AMR *" 0x00 ""
```
The acknowledgment consists of the “mirrored” request. If not all mappings could be deleted, the value contains the number of remaining mappings.

Response - OK:
```
MSG_VENDOR 0x05 "AMR *" 0x00 ""
```
Response - NOK:
```
MSG_VENDOR 0x05 "AMR *" 0xnn "<count>"
```
AMR - Range Read All (Stream):
With this message, all mappings stored in the table are read from the node.

The vendor message is structured as follows:
```
MSG_VENDOR_GET 0x05 "AMR *"
```
The answer consists of two parts:

The first message contains, in addition to the “mirrored” request key, the number of mappings subsequently supplied as a value. If there are no mappings, the value is 0x01 "0". (To differentiate from nodes that do not support any aspect mapping at all, the value is empty there.)

Subsequently, the node autonomously delivers one message for each stored mapping. The node itself is responsible for data flow control and ordering. The provided mappings conform to the format of the Entry-Read/Write responses.

Response(s) - OK:
```
MSG_VENDOR 0x05 "AMR *" 0xnn "<count>"
+ MSG_VENDOR 0xnn "AME <VID><PID1><PID2><PID3><PID4> <ACC-Nr> <ASP-Nr> <DCC-Addr> <DCC-Aspect>" 0x01 "1"
+ …
```
Response - NOK (aspect mapping not supported):
```
MSG_VENDOR 0x05 "AMR *" 0x00 ""
```
AMR - Range Read (Stream):
With this message, the mappings in the specified area of the table are read from the node.

The “offset” refers to the start index (in the order used by the node) of the mappings to be delivered, the “limit” denotes the maximum number of mappings to be delivered. The inclusion of the “offset” enables repetitions in the event of message loss.

The vendor message is structured as follows:
```
MSG_VENDOR_GET 0xnn "AMR <offset> <limit>"
```
The response consists of two parts:

The first message contains, in addition to the “mirrored” request key, the number of mappings subsequently supplied as a value. If there are no mappings, the value is 0x01 "0". (To differentiate from nodes that do not support any aspect mapping at all, the value is empty there.)

Subsequently, the node autonomously delivers one message for each stored mapping. The node itself is responsible for data flow control and sequencing. The provided mappings conform to the format of the Entry-Read/Write responses.

Response(s) - OK:
```
MSG_VENDOR 0xnn "AMR <offset> <limit>" 0xnn "<count>"
+ MSG_VENDOR 0xnn "AME <VID><PID1><PID2><PID3><PID4> <ACC-Nr> <ASP-Nr> <DCC-Addr> <DCC-Aspect>" 0x01 "1"
+ …
```
Response - NOK (aspect mapping not supported):
```
MSG_VENDOR 0xnn "AMR <offset> <limit>" 0x00 ""
```

Example AME - Entry Write:

Write an AspectMapping entry for the mapping of Accessory 18, Aspect 2 on the node with id 0DEA00D62E to the DCC Accessory 12 and DCC Aspect 1:

MSG_VENDOR_SET   24   'A'M'E' '0'D'E'A'0'0'D'6'2'E' '1'8' '2' '1'2' '0'   1   '1'

The message starts with the type MSG_VENDOR_SET, then comes the length byte of 24, followed by the key 'AME 0DEA00D62E 18 2 12 0'. Another length byte (1) follows, then the parameter value (here '1').
This message is sent to an adapter node for a DCC handheld controller.

The response of the adapter node after successfully processing the message:

MSG_VENDOR   24   'A'M'E' '0'D'E'A'0'0'D'6'2'E' '1'8' '2' '1'2' '0'   1   '1'

The message begins with the type MSG_VENDOR, then comes the exactly mirrored request with a length byte of 24 and the key 'AME 0DEA00D62E 18 2 12 0'. Another length byte (1) follows, then the parameter value (here '1').

If processing by the adapter node is not successful:

MSG_VENDOR   24   'A'M'E' '0'D'E'A'0'0'D'6'2'E' '1'8' '2' '1'2' '0'   0

The message begins with the type MSG_VENDOR, then comes the length byte of 24, followed by the mirrored key 'AME 0DEA00D62E 18 2 12 0'. This is followed by a length byte (0) and no value.
If necessary, an additional error message can be sent, e.g.:

MSG_SYS_ERROR   BIDIB_ERR_TXT   'o'u't' 'o'f' 'm'e'm'o'r'y'

Example AMR - Range Read All (Stream):

Read all AspectMapping entries from an adapter node:

MSG_VENDOR_GET   5   'A'M'R' '*'

The message begins with the type MSG_VENDOR_GET, then there is only the length byte of 5, followed by the key 'AMR *'.
The message is sent to an adapter node for a DCC handheld controller.

The adapter node responds with the number of AspectMapping entries (4 in the example) followed by the entries themselves:

MSG_VENDOR   5   'A'M'R' '*'   1   '4'
MSG_VENDOR   24   'A'M'E' '0'D'E'A'0'0'D'6'2'E' '1'8' '1' '1'2' '0'   1   '1'
MSG_VENDOR   24   'A'M'E' '0'D'E'A'0'0'D'6'2'E' '1'8' '2' '1'2' '1'   1   '1'
MSG_VENDOR   24   'A'M'E' '0'D'E'A'0'0'D'E'E'E' '1'0' '1' '1'1' '0'   1   '1'
MSG_VENDOR   24   'A'M'E' '0'D'E'A'0'0'D'E'E'E' '1'0' '2' '1'1' '1'   1   '1'

The message starts with the type MSG_VENDOR, then comes the exactly mirrored request with a length byte of 5 and the key 'AME *'. Another length byte (1) follows, then the parameter value (here '4').
Now the specified AspectMapping entries follow, in the example with an mapping for two different BiDiB nodes:

Node 0DEA00D62E with BiDiB-Accessory=18/Aspect=1 on DCC-Addr=12/Asp=0 and BiDiB-Accessory=18/Aspect =2 on DCC-Addr=12/Asp=1
Node 0DEA00DEEE with BiDiB-Accessory=10/Aspect=1 on DCC-Addr=11/Asp=0 and BiDiB-Accessory=10/Aspect=2 on DCC-Addr=11 /Asp=1

The format of the AspectMapping entries is exactly the same as that of the responses to a successful write or single read.

Generator-Mapping

With generator mapping, the DCC addresses for vehicles and accessories are mapped to the node IDs of the BiDiB DCC-generator nodes on which they should be addressed.

Example-Scenario:

The generator mapping is created by the user as part of the layout configuration and stored as a GeneratorMapping table in one (or more) nodes acting as DCC adapters. During operation, the adapter application accepts the DCC commands from the handheld controller, converts them into the BiDiB format for vehicles or DCC accessories and sends them to the corresponding generator node via BiDiB according to the GeneratorMapping table.

Format

The format for vehicles and accessories differs only by the prefix of the key - GML… for vehicles (locomotives) and GMA… for DCC accessories (accessory).

The messages follow the key/value standard of the general BiDiB specification: ASCII strings with a length byte as prefix.

The key contains alongside a the prefix (GMLE, GMAE, GMLR und GMAR) either the DCC-address or an asterisk (*) for the entire range.

The value contains the node ID of the desired generator node (Unique-ID without class bits):

<VID><PID1><PID2><PID3><PID4>

Used abbreviations
Abbreviation	Name	Meaning	type
GMLE	GneratorMappingLocoEntry	Operation for a vehicle (loco)	constant
GMAE	GneratorMappingAccessoryEntry	Operation for an accessory	constant
GMLR	GneratorMappingLocoRange	Operation for multiple vehicles	constant
GMAR	GneratorMappingAccessoryRange	Operation for multiple accessories	constant
`<VID><PID1><PID2><PID3><PID4>`	Node-ID	Vendor and product ID bytes of the node	hex string (two characters per byte)
`<DCC-Addr>`	DCC-Address	Vehicle or accessory address according to RCN 212 resp. RCN 213	decimal number
`0xnn`	Length	variable length of the key or value	raw byte
""	Empty value	no generator stored	constant

Operations

GMLE - Entry Loco Write
GMAE - Entry Accessory Write:
With this message, a DCC address is mapped to a generator node. A previously existing mapping is overwritten.

The vendor message is structured as follows:
```
MSG_VENDOR_SET 0xnn "GMLE <DCC-Addr>" 0x0A "<VID><PID1><PID2><PID3><PID4>"
MSG_VENDOR_SET 0xnn "GMAE <DCC-Addr>" 0x0A "<VID><PID1><PID2><PID3><PID4>"
```
The successful execution of the operation is acknowledged with the “mirrored” message. If the operation could not be executed, the acknowledgment contains the old table entry. In addition, an error message can be sent with the reason.

Response - OK (input-value mirrored):
```
MSG_VENDOR 0xnn "GMLE <DCC-Addr>" 0x0A "<VID><PID1><PID2><PID3><PID4>"
MSG_VENDOR 0xnn "GMAE <DCC-Addr>" 0x0A "<VID><PID1><PID2><PID3><PID4>"
```
Response - NOK (if no value stored):
```
MSG_VENDOR 0xnn "GMLE <DCC-Addr>" 0x00 ""
MSG_VENDOR 0xnn "GMAE <DCC-Addr>" 0x00 ""
```
Response - NOK (example out of memory for vehicles):
```
MSG_VENDOR 0xnn "GMLE <DCC-Addr>" 0x00 ""
+ MSG_SYS_ERROR BIDIB_ERR_TXT "out of memory"
```
GMLE - Loco Entry Delete
GMAE - Accessory Entry Delete:
With this message, the mapping of the specified DCC address to a generator node is deleted, symbolized by the empty value (0x00 "").

The vendor message is structured as follows:
```
MSG_VENDOR_SET 0xnn "GMLE <DCC-Addr>" 0x00 ""
MSG_VENDOR_SET 0xnn "GMAE <DCC-Addr>" 0x00 ""
```
The successful execution of the operation is acknowledged with the “mirrored” message. If the operation could not be executed, the acknowledgment contains the old table entry.

Response - OK (input-value mirrored):
```
MSG_VENDOR 0xnn "GMLE <DCC-Addr>" 0x00 ""
MSG_VENDOR 0xnn "GMLE <DCC-Addr>" 0x00 ""
```
Response - NOK (old value):
```
MSG_VENDOR 0xnn "GMLE <DCC-Addr>" 0x0A "<VID><PID1><PID2><PID3><PID4>"
MSG_VENDOR 0xnn "GMLE <DCC-Addr>" 0x0A "<VID><PID1><PID2><PID3><PID4>"
```
GMLE - Loco Entry Read
GMAE - Accessory Entry Read:
With this message, the generator node to which the specified DCC address is mapped is read.

The vendor message is structured as follows:
```
MSG_VENDOR_GET 0xnn "GMLE <DCC-Addr>"
MSG_VENDOR_GET 0xnn "GMAE <DCC-Addr>"
```
An existing mapping is answered with the node ID of the generator node. If there is no mapping, the value remains empty (0x00 "").

Response - (exists):
```
MSG_VENDOR 0xnn "GMLE <DCC-Addr>" 0x0A "<VID><PID1><PID2><PID3><PID4>"
MSG_VENDOR 0xnn "GMAE <DCC-Addr>" 0x0A "<VID><PID1><PID2><PID3><PID4>"
```
Response - (doesn't exist):
```
MSG_VENDOR 0xnn "GMLE <DCC-Addr>" 0x00 ""
MSG_VENDOR 0xnn "GMAE <DCC-Addr>" 0x00 ""
```
GMLR - Loco Range Delete All
GMAR - Accessory Range Delete All:
With this message, the generator mappings of all vehicle or all accessory DCC addresses are deleted, symbolized by the empty value (0x00 "").

The vendor message is structured as follows:
```
MSG_VENDOR_SET 0x06 "GMLR *" 0x00 ""
MSG_VENDOR_SET 0x06 "GMAR *" 0x00 ""
```
The acknowledgment consists of the “mirrored” request. If not all mappings could be deleted, the value contains the number of remaining mappings.

Response - OK:
```
MSG_VENDOR 0x06 "GMLR *" 0x00 ""
MSG_VENDOR 0x06 "GMAR *" 0x00 ""
```
Response - NOK:
```
MSG_VENDOR 0x06 "GMLR *" 0xnn "<count>"
MSG_VENDOR 0x06 "GMAR *" 0xnn "<count>"
```
GMLR - Loco Range Read All (Stream)
GMAR - Accessory Range Read All (Stream):
With this message, all generator mappings of vehicle or accessory DCC addresses are read.

The vendor message is structured as follows:
```
MSG_VENDOR_GET 0x06 "GMLR *"
MSG_VENDOR_GET 0x06 "GMAR *"
```
The response consists of two parts:

The first message contains, in addition to the “mirrored” request key, the number of mappings subsequently supplied as a value. If there are no mappings, the value is 0x01 "0". (To differentiate from nodes that do not support any generator mapping at all, the value is empty there.)

Subsequently, the node autonomously delivers one message for each stored mapping. The node itself is responsible for data flow control and ordering. The provided mappings conform to the format of the Entry-Read/Write responses.

Response(s):
```
MSG_VENDOR 0x06 "GMLR *" 0xnn "<count>"
+ MSG_VENDOR 0xnn "GMLE <DCC-Addr>" 0x0A "<VID><PID1><PID2><PID3><PID4>"
+ …
MSG_VENDOR 0x06 "GMAR *" 0xnn "<count>"
+ MSG_VENDOR 0xnn "GMAE <DCC-Addr>" 0x0A "<VID><PID1><PID2><PID3><PID4>"
+ …
```
Response - NOK (generator mapping not supported):
```
MSG_VENDOR 0x06 "GMLR *" 0x00 ""
MSG_VENDOR 0x06 "GMAR *" 0x00 ""
```