Metadata-Version: 2.4
Name: mrg-iot
Version: 1.5.4
Summary: IoT Testbed Experiment Automation CLI for MergeTB / Sphere Testbed
Author: Sphere / NEU IoT Testbed contributors
License: MIT
Project-URL: Homepage, https://gitlab.com/sphere-neu/mrg-iot
Project-URL: Repository, https://gitlab.com/sphere-neu/mrg-iot
Project-URL: Issues, https://gitlab.com/sphere-neu/mrg-iot/-/issues
Keywords: iot,testbed,mergetb,sphere,automation,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Distributed Computing
Classifier: Topic :: System :: Networking
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: bcrypt>=5.0.0
Requires-Dist: betterproto==2.0.0b7
Requires-Dist: certifi
Requires-Dist: cffi>=2.0.0
Requires-Dist: cryptography>=46.0.3
Requires-Dist: filelock>=3.12
Requires-Dist: grpclib>=0.4.8
Requires-Dist: h2>=4.3.0
Requires-Dist: hpack>=4.1.0
Requires-Dist: hyperframe>=6.1.0
Requires-Dist: mergetbapi==1.3.41
Requires-Dist: multidict>=6.7.0
Requires-Dist: packaging>=25.0
Requires-Dist: paramiko>=4.0.0
Requires-Dist: pycparser>=2.23
Requires-Dist: PyNaCl>=1.6.0
Requires-Dist: python-dateutil>=2.9.0
Requires-Dist: requests>=2.32.0
Requires-Dist: rich>=13.0.0
Requires-Dist: six>=1.17.0
Requires-Dist: typing_extensions>=4.15.0
Provides-Extra: dev
Requires-Dist: astroid==4.0.1; extra == "dev"
Requires-Dist: black==25.9.0; extra == "dev"
Requires-Dist: dill==0.4.0; extra == "dev"
Requires-Dist: invoke==2.2.1; extra == "dev"
Requires-Dist: isort==7.0.0; extra == "dev"
Requires-Dist: mccabe==0.7.0; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: mypy_extensions==1.1.0; extra == "dev"
Requires-Dist: pathspec==1.1.1; extra == "dev"
Requires-Dist: platformdirs==4.5.0; extra == "dev"
Requires-Dist: pylint==4.0.2; extra == "dev"
Requires-Dist: pytokens==0.2.0; extra == "dev"
Requires-Dist: tomlkit==0.13.3; extra == "dev"
Requires-Dist: types-paramiko; extra == "dev"
Requires-Dist: types-requests; extra == "dev"
Dynamic: license-file

# mrg-iot

IoT testbed experiment automation for the [Sphere / Merge Testbed](https://sphere-testbed.net) platform.

[![PyPI version](https://img.shields.io/pypi/v/mrg-iot.svg)](https://pypi.org/project/mrg-iot/)
[![Python versions](https://img.shields.io/pypi/pyversions/mrg-iot.svg)](https://pypi.org/project/mrg-iot/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

![mrg-iot exp setup: create, realize, materialize, XDC and attach in one command](https://raw.githubusercontent.com/darshpandya02/mrg-iot-assets/main/images/exp-setup.png)

`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](https://mergetb.gitlab.io/testbeds/sphere/sphere-docs/docs/experimentation/iot-devices/) | Key concepts, how the pieces fit together, and the device catalog. |
| [Installation](https://mergetb.gitlab.io/testbeds/sphere/sphere-docs/docs/experimentation/iot-devices/installation/) | Installing `mrg-iot` and the optional media tools. |
| [Quickstart](https://mergetb.gitlab.io/testbeds/sphere/sphere-docs/docs/experimentation/iot-devices/quickstart/) | Install, then drive a real device in a few commands. |
| [Using mrg-iot](https://mergetb.gitlab.io/testbeds/sphere/sphere-docs/docs/experimentation/iot-devices/using-mrg-iot/) | Account setup, experiments, device commands, camera streams, files and teardown. |
| [Troubleshooting & FAQ](https://mergetb.gitlab.io/testbeds/sphere/sphere-docs/docs/experimentation/iot-devices/troubleshooting/) | Common errors, their causes and fixes. |

The full device list is at
[devices.iot.sphere-testbed.net](https://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](https://mergetb.gitlab.io/testbeds/sphere/sphere-docs/docs/experimentation/iot-devices/using-mrg-iot/#1-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](https://mergetb.gitlab.io/testbeds/sphere/sphere-docs/docs/experimentation/iot-devices/installation/#media-tools-optional). |

## Installation

We recommend [`pipx`](https://pipx.pypa.io/), which installs `mrg-iot` into its
own environment and puts it on your `PATH`:

```bash
pipx install mrg-iot
```

You can also install it into a regular virtual environment:

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

Check that it worked:

```bash
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:

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

## Quick start

```bash
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](https://mergetb.gitlab.io/testbeds/sphere/sphere-docs/docs/experimentation/iot-devices/quickstart/)
goes through the same commands with example output, and
[Using mrg-iot](https://mergetb.gitlab.io/testbeds/sphere/sphere-docs/docs/experimentation/iot-devices/using-mrg-iot/)
covers everything else.

## License

[MIT](LICENSE) © Sphere / NEU IoT Testbed contributors
