Tutorial 8 Operator GUI

← 7. Robot Framework test · Tutorial index · 9. Advanced deploy (with-services, multi-board) →

---

Chapter 8 — The operator GUI

Your app is deployed and running. This chapter is about observing and operating it live. Theia gives you three lenses, from CLI to GUI to the fleet web UI.

9.1 tdb — the debug bridge (CLI)

tdb (Theia Debug Bridge) is a Python CLI that speaks to the supervisor's control surface and the trace hub. It's the fastest way to look at a live system. Run it from a host that can reach the board's that shares its TIPC namespace.

tdb apps          # the SUPERVISOR TREE: supervisor → services → your app FCs
tdb ps            # flat Linux-ps view: one row per worker (PID/TID/name/stats)

apps is the hierarchy (what the GUI calls Applications); ps is the flat process list (the GUI's Processes panel). After your Distribution deploy, tdb apps shows your p1..p4 nodes merged into the supervised tree — proof the SWP landed and the supervisor is running them.

Following traces (the firehose)

Every node can emit Tracer records when selectively enabled. tdb tracecat subscribes to the trace hub (log[trace]) and follows the firehose live:

tdb tracecat           # follow decoded trace records as they happen
tdb tracecat --json    # machine-readable
tdb logcat             # the LOG-line firehose (vs tracecat's trace records)

This is how you watch your CounterNode.handle_cast ticks or a GenStateM transition in real time, decoded into readable rows (the framework + your workspace trace decoders are loaded automatically).

9.2 rtdb — the remote debug bridge

rtdb is tdb over the com gRPC bridge to a remote board — same verbs (apps/ps/tracecat/logcat), but pointed at a board across the network rather than the local TIPC namespace. Use it to inspect a deployed board from your laptop.

9.3 The supervisor-GUI (desktop)

supervisor-gui (in the theia-tools package, Ubuntu 24.04) is a wx desktop GUI that wraps the same gRPC control surface in panels — a left-hand rail lists the connected machines; the tabs on the right are the views:

• System — per machine: a Deployment box (the software versions — the runtime/base release_version, the app version and campaign UCM records in per), plus System & Architecture, Resources, Supervisor Statistics, and GPU/accelerators (the tdb info surface, live).
• Applications — the supervised tree (the tdb apps view), with live state.
• Processes — the flat worker list (the tdb ps view) with CPU/mem/threads.
• Trace — the live trace firehose, decoded, with per-node enable toggles.
• Control — the supervisor's control actions: RestartChild, TerminateChild/StartChild, ConfigureTrace, ConfigureLogLevel.

It's the single-board operator console: watch your FCs, flip trace on for one node, restart a misbehaving child — all without a shell.

System — the versions running on each machine + host facts:

Applications — the live supervised tree (root → per-FC supervisors → nodes; the ↻N badge is a child's restart count):

Processes — one row per worker (pid, cpu%, rss, threads, parent supervisor, machine, restarts):

9.4 The Ground Station (fleet web UI)

For the fleet, the Ground Station is the web operator surface you've already used in Chapters 6–7. Its views:

• Fleet — every board (accepted / pending / preauthorized), its name, device-type, base runtime, installed app, and health. Enrol/Connect/Preauthorize live here.
• Releases — the raw build catalog: the runtime builds + Software Packages in the S3 planes (the parts a Distribution is assembled from).
• Distributions — prepare the deployable bundles (per-role abi + runtime + SWP).
• Deployment — the Targets | Distributions | Action History board: pick a Distribution, assign roles to abi-compatible machines, one-click deploy.
• Rollouts — the combined view of a deploy in flight: the transport plane (Mender download/install stats) and the ECU plane (per-device UCM/SM lifecycle over com) in one place — you see the bytes arriving and the on-device install running.

The Ground Station stays stateless: everything it shows is read live from Mender, colony, and the S3 planes. It's the one surface that unifies the two deploy authorities (base via colony, app via Mender) behind one operator workflow.

9.5 Putting it together — the operator's day

Ground Station Fleet      → enrol + accept a board
Ground Station Deploy     → push a Distribution (runtime + your app, per role)
Ground Station Rollouts   → watch it land (Mender bytes + on-device install)
supervisor-GUI / rtdb     → inspect the running board: tree, processes, traces
tdb tracecat              → tail a node's live behaviour while you test it

---

You've completed the tutorial. You installed Theia from .deb, scaffolded a workspace, wrote and modelled an FC, shaped a rig, cut a Distribution, published it to S3, provisioned a board, deployed your app, tested it with Robot Framework, and observed it live.

Where to go next

• Deploy at scale, over time — Chapter 9 — Advanced deployment: higher-arity fleets (one master + N workers, the role-vs-name identity split), semantic versioning of an app SWP, and config migrations.
• Deeper .art — references/art-lang-grammar.md (the full grammar), references/artheia-gen-app.md (the codegen split).
• The deployment internals — references/deployment.md, references/provision-orchestrate.md.
• Config evolution — references/migration.md (per-node config <Msg> migrations, transform.json).
• The dogfood reference — the in-repo demo/ workspace exercises this whole flow; read its system/apps/, manifest/, and tests/ for fuller examples.

---

← 7. Robot Framework test · Tutorial index · 9. Advanced deploy (with-services, multi-board) →