# Node-bus command reference

Values below include the encoded payload-length bits. `CRC` is the CRC-8 over
the command byte and every following byte except the CRC itself.

## Control and metadata

| Value | Name | Payload | Description |
|---:|---|---|---|
| `0x20` | `MCMD_INIT` | none | Initialize/reset protocol state |
| `0x28` | `MCMD_GET_INFO` | none | Read general node information |
| `0x29` | `MCMD_GET_INFO` | variable index | Read one variable's metadata |
| `0x33` | `MCMD_SET_ADDR` | mode, address MSB, LSB | Set node or group address |
| `0x37` | `MCMD_SET_NAME` | extended length, 1–16 name bytes | Set the node name |
| `0x39` | `MCMD_SET_BAUD` | baud code | Change node-bus baud rate |
| `0x41` | `MCMD_FREEZE` | enable (`1`/`0`) | Freeze/unfreeze sampled values |
| `0x49` | `MCMD_SYNC` | enable (`1`/`0`) | Buffer/release hardware demand updates |
| `0x4E` | `MCMD_SET_TIME` | six BCD bytes | Set real-time clock: DD MM YY HH MM SS |
| `0x50` | `MCMD_UPGRADE` | none | Enter firmware-upgrade mode |
| `0x58`–`0x5E` | `MCMD_USER` | 0–6 user bytes | Node-specific user command |
| `0x61` | `MCMD_ECHO` | one byte | Return the supplied byte |
| `0x68` | `MCMD_TOKEN` | none | Token operation; reserved on node bus |
| `0x70` | `MCMD_GET_UPTIME` | none | Read uptime in seconds |

`SET_ADDR` modes are `1` for the full node address, `2` for only its high byte,
and `3` for the group address. Modes 1 and 3 carry a complete 16-bit value.
The new address is stored non-volatilely.

Broadcast `FREEZE 1` after selecting a group to make members measure and hold
their current values; `FREEZE 0` ends that mode. With `SYNC 1`, members retain
new demand values in an internal buffer; `SYNC 0` applies them to hardware
together. These operations provide simultaneous sampling and simultaneous
application without requiring colliding replies.

### Baud codes

The source defines these values:

| Code | bit/s | Code | bit/s |
|---:|---:|---:|---:|
| 1 | 2,400 | 6 | 38,400 |
| 2 | 4,800 | 7 | 57,600 |
| 3 | 9,600 | 8 | 115,200 |
| 4 | 19,200 | 9 | 172,800 |
| 5 | 28,800 | 10 | 345,600 |

## Variable write commands

| Value | Name | Wire format after command | Reply |
|---:|---|---|---|
| `0x80+n` | `MCMD_WRITE_NA` | index, 1–4 value bytes, CRC | none |
| `0x88+n` | `MCMD_WRITE_ACK` | index, 1–4 value bytes, CRC | received CRC |
| `0x98` | `MCMD_FLASH` | CRC | flash confirmation |
| `0xAF` | `MCMD_WRITE_RANGE` | length, first index, last index, packed values, CRC | received CRC |

For the fixed-size forms, `n` is the number of bytes following the command,
including the index: `n = 2` through `5` for 1–4-byte values. Values are sent
most significant byte first. `WRITE_NA` is the only suitable write for group
or broadcast addressing.

`WRITE_RANGE` writes consecutive variables. The payload is `first index`,
`last index`, then each variable's bytes in metadata order. Its extended length
uses the normal short/long length encoding.

## Variable read commands

| Value | Name | Payload | Result |
|---:|---|---|---|
| `0xA1` | `MCMD_READ` | index | One variable |
| `0xA2` | `MCMD_READ` | first index, last index | Consecutive variables |

The one-variable response is `0x78 + width` for widths 1–4, followed by the
value MSB first and CRC. Larger or ranged results use the extended response
form described under [responses](responses.md#read-responses).

## Arbitrary memory access

| Value | Name | Payload after length | Meaning |
|---:|---|---|---|
| `0xB7` | `MCMD_WRITE_MEM` | subaddress, 32-bit address, data | Write memory |
| `0xBF` | `MCMD_READ_MEM` | subaddress, 32-bit address | Read memory |

The extended payload length for `WRITE_MEM` is `5 + data size`. `READ_MEM` is
exactly:

```text
0xBF 0x07 size-MSB size-LSB subaddress address-MSB address-2 address-3 address-LSB CRC
```

The `0x07` is the extended payload length; the requested byte count is the
16-bit `size` field. These operations are intended for firmware transfer and
diagnostics, not ordinary node variables.

The high nibble selects the memory region:

| Address range | Region |
|---|---|
| `0x0.......` | RAM |
| `0x1.......` | non-volatile RAM |
| `0x2.......` | EEPROM or flash data |
| `0x3.......` | program/code space |

The exact valid address range and write permissions are device-specific.

## Logging

`MCMD_LOG` is `0xC1` with a one-byte operation:

| Operation | Meaning | Response |
|---:|---|---|
| `0` | Read log | Extended data response |
| `1` | Clear log | `0x78`, CRC |