Groundrun docs
Reference material for driving Groundrun: the groundrun command-line
tool, the YAML format for rig and scenario files, and how the rig, the
coordinator, and the flow builder fit together. This is written for an
agent or engineer working with the product, not as marketing copy.
Each page below has a raw Markdown twin at the same path with a .md
extension, so an agent can fetch the content directly. See
/docs/llms.txt for the full list.
- CLI cheat sheet: every
groundruncommand. - YAML format cheat sheet: the rig and scenario YAML file formats.
System overview
Groundrun is a hardware-in-the-loop testing product for IoT devices. It automates test scenarios that span firmware, mobile apps, and cloud backends, running the real hardware a product ships with rather than a simulation of it.
This section gives a conceptual orientation to the three parts of the
system — the rig, the coordinator, and the flow builder — and how they
connect. For the commands to drive a rig, see
cli-cheat-sheet.md; for the YAML files that
describe a rig and a scenario, see
yaml-format-cheat-sheet.md.
The rig
The rig is the physical hardware at a customer site: the devices under test, plus the mini-PC or Raspberry Pi-class devices that drive and power them.
| Component | What it does | How it connects |
|---|---|---|
| Runner device | A mini-PC or Raspberry Pi-class device that plugs into the boards and phones under test and executes a compiled scenario against them: flashing firmware, sending commands, and collecting results. A rig can have more than one runner device, for example to drive several boards or phones in parallel. | Connects locally to boards over USB and to a phone over USB/ADB. Receives compiled test scripts from the coordinator and reports results back to it. |
| Supervisory device | A mini-PC or Raspberry Pi-class device that controls power to one or more runner devices at a site, so every test run can start from a full power cycle rather than whatever state the hardware was left in. | Connects to one or more power switches over the local network and to the coordinator, which tells it when to cycle power for a run. |
| Boards | The embedded hardware under test — a development board, or the actual production hardware connected over JTAG or a similar debug interface, running the customer's firmware. | Connects to a runner device over USB/UART or JTAG (or a similar debug interface), so the runner can flash new firmware and exchange commands with it. |
| Phone | An Android or iOS device the rig drives as part of a scenario, running the customer's mobile app. Its camera is a generic capability a scenario can use, for example to read a QR code or other visual output a board's screen displays, the same way a person would use the app. | Connects to a runner device over USB. The runner drives the phone's app and, when a scenario calls for it, its camera. |
| Power switch | A network-controlled smart plug that cuts and restores power to the rig's hardware. Every run starts with a full power cycle, because a board or phone left in an unknown state after the previous run cannot be trusted to represent a fresh boot. | Connects to the local network. The supervisory device switches it for each run. |
A runner or supervisory device gets its software from an SD card image built for it — burn the image, boot the device, plug in the hardware, and it is ready to run tests.
The coordinator
The coordinator is the on-prem control plane for a customer site. It runs on a server or VM the customer manages, separate from the rig hardware itself.
| Component | What it does | How it connects |
|---|---|---|
| Coordinator | Compiles scenarios against a site's own rig definitions, orchestrates a run across the supervisory device and runner devices, stores results and a device-status dashboard, and is how a customer's own engineers or CI trigger a run. | Connects outbound to the flow builder to pull scenarios and push results; connects to each rig's supervisory and runner devices to drive runs; exposes a local API and dashboard for the customer's own engineers and CI. |
The coordinator only ever connects out — to the flow builder, and to whatever CI system is pulling it in as a job runner. Nothing needs to connect in to the customer's site, and a site keeps running tests fully offline if its internet connection drops; it only loses the authoring feedback loop and any cross-site summaries until connectivity returns.
The flow builder
| Component | What it does | How it connects |
|---|---|---|
| Flow builder | The authoring surface where a person describes a user flow the product goes through — unboxing, turning on a light, unlocking a door, adding a user — without needing to know anything about the underlying test infrastructure. Breaks each flow down into the scenarios a coordinator can run, described using the YAML format the other cheat sheet covers. | A web application. A coordinator connects out to it to pull scenario descriptions and queued run requests, and to push back results, screenshots, and rig status. |
How they connect
A person writes a flow in the flow builder in plain, product-level terms. The flow builder breaks that flow down into the scenarios a coordinator can run, each one written against abstract actors — "a board", "a phone" — rather than any specific physical device. A coordinator at a customer site pulls those scenarios, compiles them against the specific rig hardware it knows about, and hands the compiled test to a runner device. For each run, the coordinator directs the supervisory device to power-cycle the hardware first, then the runner device to deploy the test, execute it, and collect the results. Results and device status stay on the coordinator; summaries flow back up to the flow builder so a person authoring flows can see how they perform across every site running them.