mrg-iot 1.3.0

IoT Testbed Experiment Automation CLI for MergeTB / Sphere Testbed

mrg-iot

A Python CLI for automating IoT testbed experiments on the Sphere / Merge Testbed platform.

mrg-iot drives the full experiment lifecycle so you don't have to:

• Create an experiment and its network model for the selected devices.
• Realize and materialize the model.
• Create an XDC (eXperimental Data Center) and attach it to the materialization.
• Set up SSH port forwarding for RTSP streams and file downloads.
• (Optional) De-materialize and clean up resources when you're done.

Installation

pipx install mrg-iot

(Or pip install mrg-iot inside a virtualenv.)

mrg-iot requires Python 3.9+ and a working VLC install on the host for RTSP playback — pip can't install VLC for you.

Usage

Interactive mode

mrg-iot login        # save credentials to ~/.mrg-iot/session.json
mrg-iot              # walk through the experiment flow

Non-interactive mode

mrg-iot --non-interactive \
    --project neuiot \
    --devices s-echodot-1 \
    --exp-name myexp \
    --exp-desc "my experiment" \
    --realization realiot \
    --duration 1w \
    --xdc myxdc

Cleanup subcommands

mrg-iot exp delete         --project neuiot --name myexp
mrg-iot exp dematerialize  --project neuiot --name myexp --realization realiot
mrg-iot xdc detach         --project neuiot --name myxdc --experiment myexp --realization realiot
mrg-iot xdc delete         --project neuiot --name myxdc

Run mrg-iot --help for the full flag list.

Debug logging

mrg-iot --debug      # verbose logs to stderr + debug.log

Input validation

The CLI validates inputs upfront so bad args fail fast rather than deep inside a portal call:

• Names (exp-name, realization, xdc, network): start with a letter, lowercase letters and digits only, max 32 chars.
• Description: letters, digits, spaces, commas, periods, hyphens; max 256 chars.
• Duration: minimum 4 days. Accepts 1w, 4d, 1w2d, 1 week, etc.

macOS SSL note

If portal calls fail with an SSL error on macOS:

export SSL_CERT_FILE="$(python -m certifi)"
export REQUESTS_CA_BUNDLE="$SSL_CERT_FILE"

Development

git clone https://gitlab.com/sphere-neu/mrg-iot.git
cd mrg-iot
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

mypy .
pylint *.py
black *.py
isort *.py

License

MIT — see LICENSE.