mrg-iot cmd
The cmd group sends commands to the devices in a deployed experiment. It has one subcommand per way of waiting: run waits for the result, async-run doesn't and leaves you a handle, wait/status pick that handle up later, and shell/ctl give you a prompt.
The spiot_ctl language
A command is a device name, a command, and its arguments, e.g. s-echodot-1 click_button. Capabilities differ between devices, so ask the device:
mrg-iot cmd run "s-echodot-1 commands" -e myexp # what it supports
mrg-iot cmd run "s-echodot-1 click_button help" -e myexp # how one command is used
Experiment-level commands are the same everywhere:
| Command | Description |
|---|---|
exp devices | List the devices in the experiment. |
exp cred <device> | Get a device's application credentials. |
exp sleep <seconds> | Pause for N seconds. |
exp read <file> | Read a command file on the XDC and queue every line. |
exp clear <variable> | Forget a stored variable. |
<device> help / <device> commands | The commands that device supports. |
<device> <command> help | Detailed usage for one device command. |
query state <device> <command> <id> | Where a queued job has got to. |
query get_result <device> <command> <id> | The result of a finished job. |
query wait_result <device> <command> <id> | Block until a job finishes, then return its result. |
The experiment validates device commands itself, so a bad argument is reported by the experiment rather than by mrg-iot. See Choose an interaction for a sample of device commands.
Queued jobs and tasks
A device command either answers immediately or is queued: the experiment hands back a job id and works in the background. cmd run waits for queued jobs. cmd async-run instead records each one as a task (t1, t2, …) in ~/.mrg-iot/tasks.json, which cmd wait, cmd status, and cmd tasks read later. Tasks are forgotten when their experiment is torn down.
Flags
Every command that talks to a running experiment takes the same four experiment flags, each with a default, so you usually pass only -e:
| Argument | Description |
|---|---|
--project, -p | Project name. Default: your only project; required when you belong to several. |
--experiment, -e | Experiment name. Default: your username. |
--realization, -r | Realization name. Default: realiot. |
--xdc, -x | XDC name. Default: <experiment>xdc. |
Commands
| Command | What it does |
|---|---|
cmd run | Run commands and wait for each result. |
cmd async-run | Run commands without waiting; leaves a task. |
cmd wait | Block until a task finishes, then print its result. |
cmd status | Where a task's job has got to. |
cmd tasks | List the background jobs on record. |
cmd shell | Interactive spiot_ctl > prompt. |
cmd ctl | The same prompt, from inside the XDC. |
Back to the full walkthrough: Using mrg-iot.