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.
| Guide | What's in it |
|---|---|
| IoT Devices | Key concepts, how the pieces fit together, and the device catalog. |
| Installation | Installing mrg-iot and the optional media tools. |
| Quickstart | Install, then drive a real device in a few commands. |
| Using mrg-iot | Account setup, experiments, device commands, camera streams, files and teardown. |
| Troubleshooting & FAQ | Common errors, their causes and fixes. |
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
| Requirement | Notes |
|---|---|
| Python 3.9+ | 3.9, 3.10, 3.11 and 3.12 are tested in CI. |
| A Merge Testbed account | With access to at least one IoT project (neuiot, iotbeta or iotdev). See Create a SPHERE account. |
| Network access | To the gRPC portal (grpc.sphere-testbed.net:443) and the SSH jump host (jump.sphere-testbed.net:2022). |
| VLC / ffmpeg / Wireshark | Optional. VLC is used by stream open, ffmpeg by stream push and Wireshark by stream capture. None can be installed with pip; see Media tools. |
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
1 maintainer
Metadata
1 maintainer
Release files for mrg-iot 1.5.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| mrg_iot-1.5.6.tar.gz | 268.7 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| mrg_iot-1.5.6-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 465.8 kB
Release files / mrg_iot-1.5.6.tar.gz
| Download URL | mrg_iot-1.5.6.tar.gz |
|---|---|
| Size | 268.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
61096d7cf8a9a3eec5a19e33195c1bae5a82e1db2f5804ab1d58e5a5d23b22df
|
|
BLAKE2b-256 checksum How to use checksums |
13544b062923feed4ab24f61a6a797f9d08cc8151d99527119adbdddeb01d1cb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.12.15
|
Release files / mrg_iot-1.5.6-py3-none-any.whl
| Download URL | mrg_iot-1.5.6-py3-none-any.whl |
|---|---|
| Size | 197.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
da56a094ff55cfe2bc8131ee931941c2172407380d4804a8e5ab7fc5d3a18e0d
|
|
BLAKE2b-256 checksum How to use checksums |
2cdb33e6b66cb565ad55f486cccc05eb919b0f979ae9144cb2a834dcc3199b65
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.12.15
|
Security for mrg-iot 1.5.6
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
