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:

python3 python/msc.py -d mscb123

By IP address:

python3 python/msc.py -d 192.0.2.10

Run one command and exit:

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. The source file itself is not run directly.

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

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

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

./msc -d mscb123

or, using an IP address:

./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:

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

Once connected, enter commands at the prompt:

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

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

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

To discover Ethernet submasters without opening an interactive session:

./msc -s

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

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

See the msc command reference for all startup options and interactive commands.

Find submasters and nodes

Discover Ethernet submasters on the local network:

python3 python/msc.py -s

After connecting, scan likely node addresses:

> 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

> 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

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

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.

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

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. For every CLI command and option, see msc command reference.