# Getting started

## Requirements

- an Ethernet MSCB submaster reachable by hostname or IPv4 address;
- one or more powered MSCB nodes on its RS-485 bus;
- Python 3.9 or newer for the Python tools, or a built C++ `msc` executable;
- the optional password configured on the submaster.

The default UDP port is `1177`. The Python tools also accept `host:port`; the
C++ `msc` executable uses the configured MSCB default port.

## Use the Python CLI

From the repository root:

```bash
python3 python/msc.py -d mscb123
```

By IP address:

```bash
python3 python/msc.py -d 192.0.2.10
```

Run one command on a specific node and exit:

```bash
python3 python/msc.py -d mscb123 -a 1 -c info
```

No `pip` installation is required for `mscb.py`: `msc.py` imports the sibling
module directly.

## Build and run the `msc` executable

The interactive C++ client is implemented in `src/msc.cxx`. It is built as the
`msc` executable together with the C MSCB library implementation, command-line
editor, and XML support via the CMake command.

You need CMake 3.10 or newer and a C++17 compiler. From the repository root,
configure and compile the `msc` target:

```bash
mkdir -p build && cd build
cmake ..
make
```

With a single-configuration generator on Linux or macOS, the executable is:

```bash
./msc -d mscb123
```

or, using an IP address:

```bash
./msc -d 192.0.2.10
```

For Visual Studio and other multi-configuration generators, select a build
configuration and run the executable from that configuration directory:

```powershell
cmake --build . --config Release --target msc
.\Release\msc.exe -d 192.0.2.10
```

Once connected, enter commands at the prompt:

```text
> scan
> addr 1
node1(0x1)> info
node1(0x1)> read 0-7
node1(0x1)> exit
```

To select a node, execute one command, and exit immediately:

```bash
./msc -d mscb123 -a 1 -c info
```

To discover Ethernet submasters without opening an interactive session:

```bash
./msc -s
```

The executable can optionally be installed. This example keeps the installation
inside the repository:

```bash
cmake --install . --prefix "$PWD/install"
./install/bin/msc -d mscb123
```

See the [`msc` command reference](reference/msc-cli.md) for all startup options
and interactive commands.

## Find submasters and nodes

Discover Ethernet submasters on the local network:

```bash
python3 python/msc.py -s
```

After connecting, scan likely node addresses:

```text
> scan
Found node "SCS-2001", NA 1 (0x0001), GA 65535 (0xFFFF), Rev. 0x1234
```

Use `scan a` for all 65,536 addresses; this is much slower than the optimized
default scan.

## Inspect and operate a node

```text
> addr 1
node1(0x1)> info
node1(0x1)> read
node1(0x1)> read 3
node1(0x1)> write 8 1.25
```

`read` without an index reads all available variables except hidden variables.
Use `read a` to include hidden variables.

## Save and restore configuration

```text
node1(0x1)> save node1.xml
node1(0x1)> load node1.xml
```

The save file contains node identity and variable values in XML. Loading maps
variables by name, so it can tolerate index changes when names remain stable.
The tool asks whether loaded values should be flashed to non-volatile memory.

## Firmware operations

```text
node1(0x1)> upload firmware.hex
node1(0x1)> verify firmware.hex
```

Supported formats depend on the target and implementation and include Intel
HEX, Xilinx BIT, S-record, and binary images. Firmware operations can make a
node temporarily unavailable. Confirm target address, subaddress, image type,
and power stability before proceeding.

!!! warning "Flash and address operations change persistent state"

    `flash`, `sa`, `sg`, `sn`, `baud`, and firmware commands alter node or
    submaster configuration. Verify the selected target first with `info`.

## Minimal Python application

```python
import mscb

with mscb.MSCB("mscb123") as bus:
    if not bus.ping(1):
        raise RuntimeError("node 1 did not respond")

    raw = bus.read(1, 0)
    print(raw)
```

For a C-style call sequence in Python, initialize an `fd` and call module
functions such as `mscb.mscb_ping(fd, 1)` directly.

For C applications, see [C library](software/c-library.md). For every CLI
command and option, see [`msc` command reference](reference/msc-cli.md).