mrg-iot

IoT testbed experiment automation for the Sphere / Merge Testbed platform.

mrg-iot is a command-line tool for running IoT experiments on the Merge Testbed without chaining mergetb and ssh calls together by hand. It creates the experiment and its device model, allocates the hardware, sets up and attaches an XDC, and tunnels to the experiment's camera streams, file server and control channel. From there you can send device commands, download what the devices produced, and release everything when you're done. If provisioning fails partway, it cleans up whatever it had already allocated.

Documentation

User documentation is on the SPHERE docs site. This README only covers installing the package and working on the code.

The full device list is at devices.iot.sphere-testbed.net.

Run mrg-iot --help, or --help on any subcommand, for the full list of flags and their defaults.

Requirements

Installation

We recommend pipx, which installs mrg-iot into its own environment and puts it on your PATH:

pipx install mrg-iot

You can also install it into a regular virtual environment:

python3 -m venv .venv && source .venv/bin/activate
pip install mrg-iot

Check that it worked:

mrg-iot --version
mrg-iot --help

If you get mrg-iot: command not found, pipx's install directory (~/.local/bin) probably isn't on your PATH. Run pipx ensurepath and open a new shell.

On macOS, portal calls can fail with certificate verify failed because the system Python often has no usable CA bundle. Set these to fix it:

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

Quick start

mrg-iot login                                        # cached in ~/.mrg-iot/session.json
mrg-iot devices list --available                     # devices free to reserve
mrg-iot exp setup myexp --devices s-echodot-1        # create and deploy the experiment
mrg-iot cmd run "s-echodot-1 click_button" -e myexp  # send a device command
mrg-iot file download -e myexp                       # download captured files
mrg-iot exp teardown myexp                           # release everything

Most names have defaults: the experiment is named after your username, the XDC is <experiment>xdc, the realization is realiot, and the project is used automatically if you only have one. So mrg-iot exp setup --devices s-echodot-1 works by itself, and none of the commands above prompt for input.

For an interactive version, mrg-iot run provisions an experiment, opens the spiot_ctl > prompt, and cleans up when you type exit.

The Quickstart goes through the same commands with example output, and Using mrg-iot covers everything else.

License

MIT © Sphere / NEU IoT Testbed contributors