# 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:

```c
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`. Both the C and Python implementations use Ethernet/UDP
communication.

## Discovery

`mscb_scan_udp()` follows the conventional submaster naming scheme: it resolves
`MSCB000` through `MSCB999` and sends an ECHO request to each hostname that
exists. Responding devices are printed with protocol version, revision, and
uptime. Local DNS or mDNS must therefore resolve the `MSCBxxx` names. A known
hostname or IP address remains the most reliable direct connection method.