Ethernet submaster transport

Current host software talks to an Ethernet submaster over UDP. This envelope is distinct from the MSCB node-bus bytes carried on RS-485.

Endpoint and header

The default UDP port is 1177. Every datagram begins with a six-byte header:

typedef struct {
    uint16_t size;       /* network byte order */
    uint16_t seq_num;    /* network byte order */
    uint8_t  flags;
    uint8_t  version;
} UDP_HEADER;

size is the payload size excluding the six-byte UDP header, and seq_num correlates replies with requests. The sequence number increments modulo 65536. The current transport protocol version is 5; a mismatch returns EMSCB_PROTOCOL_VERSION instead of attempting an ambiguous exchange.

Flags

Bit	Constant	Meaning
0	RS485_FLAG_BIT9	Send address-cycle bytes with ninth bit set
1	RS485_FLAG_NO_ACK	Do not wait for a node reply
2	RS485_FLAG_SHORT_TO	Short timeout class
3	RS485_FLAG_LONG_TO	Long timeout class
4	RS485_FLAG_CMD	Submaster command rather than transparent bus data
5	RS485_FLAG_ADR_CYCLE	Treat request as an address cycle
6	RS485_FLAG_NO_RETRY	Suppress retransmission
7	RS485_FLAG_VERYLONG_TO	Very-long timeout class

The library builds separate datagrams for address cycles and normal command bytes so the submaster can generate the ninth serial bit correctly.

Authentication and initialization

Initialization first exchanges a submaster echo to verify the endpoint. If a password was supplied, it sends a token command with the password padded to a 20-byte field. 0x78 accepts the token; the submaster's rejection status is reported as EMSCB_WRONG_PASSWORD/MSCB_WRONG_PASS as appropriate.

Passwords protect access to the submaster but do not encrypt UDP traffic. Place MSCB control networks on a trusted or isolated network when confidentiality or hostile-traffic resistance matters.

Retries and timeouts

The Ethernet exchange code uses a configurable retry count. Its ordinary receive timeout grows as 300 × (retry + 1) ms. Long operations use a 1000 ms class, and very-long operations use 5000 ms after the first retry. A one-byte 0xFF reply indicates that the remote RS-485 operation timed out, which is reported separately from an absent UDP response.

mscb_set_eth_max_retry() changes retry behavior for one connection. mscb_set_eth_pause() controls the minimum pause between Ethernet exchanges.

Device names

Pass the submaster host name or IP address to mscb_init() or the -d option of msc. The C source retains older USB and RPC paths for compatibility, but the Python implementation in this repository intentionally implements only Ethernet/UDP communication.

Discovery

mscb_scan_udp() sends the current discovery request and prints responding submasters. Discovery depends on broadcast reachability; routers and host firewalls commonly block it. A known IP address remains the most reliable connection method.