MSCB protocol¶

This section specifies the node-bus protocol implemented by the current software and firmware.

Communication model¶

MSCB uses a master/slave exchange on a half-duplex RS-485 bus. A master sends an address cycle followed by a command. Only the addressed node replies. More than one master can share a bus when ownership is passed through the token-ring mechanism; ordinary node traffic remains master initiated.

Each serial character has an additional ninth data bit:

ninth bit 1: address byte;
ninth bit 0: command, parameter, response, or CRC byte.

This lets every node recognize an address cycle in hardware, without parsing all traffic. The bit order and electrical levels are described under RS-485 bus.

Command-byte encoding¶

The upper five bits identify the command family. The lower three bits encode the number of bytes that follow the command byte:

Low bits	Meaning
`0`–`6`	Exactly that many bytes follow
`7`	A separate length field follows

For the extended form, a length byte below 0x80 represents 0–127 bytes. If its high bit is set, it is the most significant byte of a two-byte, 15-bit length, allowing 128–32767 bytes. The length counts command parameters and data, but not the command byte or final CRC.

Examples:

0xA1 index crc                         READ, 1-byte payload
0xAF 0x06 first last data... crc       WRITE_RANGE, 6-byte payload
0xBF 0x80 0x07 ... crc                 READ_MEM, long length = 7

Byte order¶

Multi-byte parameters are generally sent least significant byte first. Several command formats deliberately specify another order, notably 16-bit node addresses and variable values, which are transmitted most significant byte first. Follow the byte order shown in each command table; it is authoritative for that field.

CRC-8¶

All complete command and response telegrams use an 8-bit CRC with polynomial x⁸ + x⁵ + x⁴ + 1 (0x31). The CRC covers the command or response byte and all length, parameter, and data bytes before the CRC. Address-cycle bytes are not part of the command CRC.

Reference algorithm:

unsigned char crc8(const unsigned char *data, int len)
{
    unsigned char crc = 0;
    while (len--) {
        crc ^= *data++;
        for (int i = 0; i < 8; i++)
            crc = (crc & 0x80) ? (crc << 1) ^ 0x31 : crc << 1;
    }
    return crc;
}

A receiver silently discards a telegram with a bad CRC. For acknowledged writes the node returns the received command CRC; the master compares it and retries if it differs.

Address cycle¶

An address telegram is the command byte, the address bytes listed below, and a CRC. Every byte of that telegram, including the CRC, is sent with the ninth bit set.

Command	Value	Bytes following	Purpose
`MCMD_ADDR_NODE8`	`0x09`	node low byte	Select an 8-bit node address
`MCMD_ADDR_NODE16`	`0x0A`	node MSB, node LSB	Select a 16-bit node address
`MCMD_ADDR_GRP8`	`0x11`	group low byte	Select an 8-bit group address
`MCMD_ADDR_GRP16`	`0x12`	group MSB, group LSB	Select a 16-bit group address
`MCMD_ADDR_BC`	`0x10`	none	Broadcast to all nodes
`MCMD_PING8`	`0x19`	node low byte	Probe an 8-bit node address
`MCMD_PING16`	`0x1A`	node MSB, node LSB	Probe a 16-bit node address

Fresh nodes use node address 0xFFFF. Ping is itself an address-cycle command; a matching node responds with 0x78 and no CRC. The response target is an acknowledgement within 100 µs, while the documented master ping timeout is 400 µs.

For an 8-bit address cycle, every participating node must have a zero high address byte. Once a node or group is selected it remains selected for normal commands until another address cycle is issued.

Group and broadcast addressing can only be used with operations that do not need a unique reply: unacknowledged write, set baud rate, freeze, and synchronization. A group address cannot safely be used with a normal read or acknowledged write because several nodes could transmit simultaneously.

Transaction shape¶

sequenceDiagram
    participant M as Master
    participant S as Submaster
    participant N as Addressed node
    M->>S: UDP request
    S->>N: address cycle (bit 9 = 1)
    S->>N: command + parameters + CRC (bit 9 = 0)
    N-->>S: ACK/data + CRC
    S-->>M: UDP reply

The UDP envelope is a submaster transport and is not placed on the RS-485 wire. See Ethernet transport.

Variable model¶

A node exposes up to 256 variables at indexes 0–255. A variable has a width of 1–256 bytes, a name, flags, a unit and metric prefix, and optional status bits. Nodes normally map variables onto RAM and copy persistent values to flash or EEPROM when FLASH is issued. Metadata queries make the network self-documenting; no central register map is required.

Node firmware invokes its application hook when a variable is read or written, allowing the value to be transferred to an ADC, DAC, or other physical entity. Pure configuration variables can remain as local RAM values.

Robustness rules¶

Discard any telegram whose CRC is wrong.
An omitted channel/index defaults to zero for commands that permit that shorthand.
On an acknowledged write, compare the returned CRC with the command CRC and retry on mismatch.
Do not expect replies to group or broadcast operations.
Use the timeout class appropriate to the operation; flash and upgrade are intentionally much slower than reads.

Continue with the command reference and response formats.