# `msc` command reference

This page is derived from the parser in `src/msc.cxx`, including commands that
the built-in help omits and corrections to misleading help labels.

## Invocation

```text
msc -d <device> [-p <password>] [-a <address>] [-c <command>] [-v|-w]
msc -s
```

| Option | Meaning |
|---|---|
| `-d device` | Ethernet submaster host name or IP address. A custom UDP port can be appended as `host:port`. |
| `-p password` | Submaster password; if rejected, the client prompts once interactively. |
| `-a address` | Select this node before executing commands. Command-line parsing is decimal. The C client otherwise assumes node 0 when `-c` is used. |
| `-c command` | Execute one command and exit. Use `-c @file` to execute non-empty lines from a command file. |
| `-s` | Discover Ethernet submasters on the local network, then exit. |
| `-v` | Diagnostic level 2; write verbose information to `mscb_debug.log`. |
| `-w` | Diagnostic level 1; log write commands to `mscb_write.log`. |

The Python `python/msc.py` also accepts `host:port` after `-d`.

## Input syntax and selection state

Commands are case-insensitive and may be abbreviated to a leading prefix. For
example, the displayed `mup` and `mwr` forms match the implemented `mupload`
and `mwrite` commands. Ambiguous abbreviations resolve in the parser's command
order, so full names are safer in scripts. Arguments containing spaces can be
surrounded by double quotes, single quotes, or backticks.

The prompt shows the current target:

```text
node12(0xC)>     one node
group7>          a group
all>             broadcast
>                no target
```

Node addresses accept decimal or `0x` hexadecimal notation inside the
interactive command loop. Most read/info/firmware commands require an
individual node. Group/broadcast state is limited to commands that need no
unique reply.

## Discovery and target selection

| Command | Description |
|---|---|
| `scan [r] [a] [q]` | Scan likely addresses. `a` checks all 65,536, `q` uses quick ping timing, and `r` repeats until interrupted. The optimized default checks 0–999, hundred boundaries, `0x100` boundaries, the `0xFF00` region, and expands around discoveries. |
| `ping address [r]` | Ping a node and make it current when successful; `r` repeats once per second. |
| `addr address` | Set an individual target without first validating it. |
| `gaddr group` | Select a group and prompt for a representative node address whose metadata will be used to encode writes. |
| `baddr` | Select broadcast mode. |
| `info` | Display current node identity, protocol/revision, RTC, uptime, buffer size, and SCS3000 diagnostics when present. |

`scan a` can take a long time. Prefer the default scan or a direct `ping` when
the expected address range is known.

## Node configuration

| Command | Description |
|---|---|
| `sa address` | Change the selected node address. For an individual node, the client first checks for an existing target at the new address. |
| `sg group` | Set the selected node(s)' group address. |
| `sn name` | Set an individual node name. The implementation accepts at most 15 characters plus terminator. Quote names containing spaces. |
| `baud` | Interactively select baud code 1–10; default shown is code 8 (115,200 bit/s). |
| `sync` | Set the selected node/group/broadcast real-time clock from local time. |
| `flash` | Copy current variables/configuration to node non-volatile storage. |
| `reboot` | Reboot selected node(s). |

Address, baud, flash, and firmware commands change persistent behavior. Run
`info` on an individual target first.

## Read and write variables

| Command | Description |
|---|---|
| `read` | Read all variables, suppressing hidden variables. |
| `read a` | Read all variables including hidden ones. |
| `read index [r [ms]] [a]` | Read one variable; optionally repeat, wait `ms`, and include hidden output. |
| `read first-last [r [ms]] [a]` | Read a consecutive range with one range transaction. |
| `write index value [r ms]` | Encode a value from metadata and write it; optionally repeat until interrupted. |
| `write first-last value` | Apply the supplied value to each variable in a range, using each variable's metadata. |
| `mwrite index value first-node last-node` | Write the same variable on every node in an inclusive address range. `mwr` is the help-screen abbreviation. |

The client understands string, ASCII, floating-point, signed and unsigned
integer variables from metadata. Hexadecimal numeric input begins with `0x`.
On a selected group, `write` uses an unacknowledged group write and the
representative node selected by `gaddr` for metadata.

## XML save and load

| Command | Description |
|---|---|
| `save file` | Save the current node to an XML dump. |
| `save file first last` | Probe and save all responding nodes in the inclusive range. If the file argument is omitted, prompt for it. |
| `load file` | Load variables by name from XML, then ask whether to persist them with `FLASH`. |

Loading by name tolerates index movement across firmware revisions, but names,
widths, and representations still need to be compatible. Review a saved dump
before applying it to a different node type.

## Firmware and memory

| Command | Description |
|---|---|
| `upload file [debug]` | Upload firmware to the current node. |
| `upload slot file [debug]` | Upload to a subaddress/slot of the current node. |
| `download file` | Download firmware/data from the current node into a new file. |
| `download slot file` | Download from a slot/subaddress. |
| `verify file` | Compare the current node with a firmware file. |
| `verify slot file` | Compare one slot/subaddress. The built-in help calls this optional value `adr`, but the implementation treats it as a slot. |
| `mupload file first-node last-node` | Upload to each node in an inclusive range. `mup` is the help-screen abbreviation. |
| `memrd slot address count` | Read `count` bytes from RAM-region memory at a slot/subaddress. |
| `memwr slot address value` | Write an 8-, 16-, or 32-bit value to RAM-region memory. Hex input width selects 1/2/4 bytes; decimal is 32-bit. |

`download` refuses to overwrite an existing output file. Raw memory operations
force the RAM base in this CLI; the library API can address the other defined
regions. Firmware and memory commands can leave a target unusable if the image,
slot, or address is wrong.

## Diagnostics and specialized commands

| Command | Description |
|---|---|
| `version` | Show host-library and protocol versions. |
| `debug 0|1|2` | Change diagnostic level. |
| `echo [f][c]` | Incrementing-byte echo test; `f` omits normal pacing and `c` continues after a mismatch. Stop with a key. |
| `user [byte]` | Issue the target firmware's application-specific USER command, with zero or one parameter byte. |
| `log` | Read the SCS3000 logging buffer until empty. |
| `log c` | Clear the SCS3000 logging buffer. |
| `terminal` | Find the first data-less variable and use it as an SCS-210-style character terminal. Escape exits. |
| `sr` | Reset the current submaster. |
| `submaster` | Print current submaster information. |
| `sm` | Interactively set submaster MAC/network configuration, then exit; intentionally omitted from built-in help because it is an administrative operation. |
| `help` or `?` | Show built-in command help. |
| `exit` or `quit` | Close the connection and exit. |

`t1`, `t2`, and `c1` are source-level engineering tests (link-cache test,
range-write throughput test, and MPDC current-offset calibration). They are
not general operator commands and their hard-coded indexes can modify device
state.

## Script example

```text
ping 12
info
read 0-7
save node12.xml
exit
```

Run it with:

```bash
msc -d 192.0.2.40 -c @commands.txt
```