Terminal-based dashboard for Beam Bots robots.

BB.TUI provides a TUI interface for monitoring and controlling BB robots — safety controls, runtime state, joint positions, event stream, and command display — in terminal environments.

Usage

# Interactive — from IEx when robot is already running
BB.TUI.run(MyApp.Robot)

# Supervised — add to the app's supervision tree
children = [
  {BB.Supervisor, MyApp.Robot},
  {BB.TUI, robot: MyApp.Robot}
]

# Mix task — standalone
$ mix bb.tui --robot MyApp.Robot

Remote attach (distribution)

When the robot is running on a different BEAM node — for example a Nerves device on the network — pass the :node option so the TUI renders on the local terminal but pulls all data and dispatches all commands across distribution:

# On the dev node, after Node.connect/1 with the robot node
BB.TUI.run(MyApp.Robot, node: :"robot@192.168.1.42")

See BB.TUI.Robot for the routing layer that backs this option.

SSH transport

When the robot runs on a headless device (Nerves board, container, remote host), the dashboard can be served over SSH so any SSH client can connect without a local Elixir node or distribution setup on the client side:

# In the robot's supervision tree
children = [
  {BB.Supervisor, MyApp.Robot},
  {BB.TUI, robot: MyApp.Robot, transport: :ssh, port: 2222,
   auto_host_key: true, auth_methods: ~c"password",
   user_passwords: [{~c"admin", ~c"s3cret"}]}
]

Then from any machine:

ssh admin@robot.local -p 2222

Each SSH client gets its own isolated session with independent panel selection, scroll positions, and event streams. Multiple operators can monitor the same robot simultaneously.

For Nerves devices already running nerves_ssh, plug into the existing daemon as a subsystem instead — see subsystem/1.

See ExRatatui.SSH.Daemon for the full list of SSH options.

Distributed transport (attach from a connected node)

As an alternative to the :node option — which keeps mount/render local and routes data calls through :rpc — the TUI app can run on the robot node and be attached from any connected BEAM node. This is the ExRatatui.Distributed transport: the remote node runs the app (mount/render/handle_event), and the local node only renders the widgets it receives and forwards terminal events back.

1. On the robot node, add the Distributed listener to its supervision tree (alongside whatever else the node normally supervises):

children = [
  {BB.Supervisor, MyApp.Robot},
  ExRatatui.Distributed.Listener
]

2. From any connected node, attach:

iex --name dev@127.0.0.1 --cookie secret -S mix
iex> Node.connect(:"robot@192.168.1.42")
iex> ExRatatui.Distributed.attach(:"robot@192.168.1.42", BB.TUI.App,
...>   listener: ExRatatui.Distributed.Listener)

For local experimentation, Dev.Application already supervises a matching ExRatatui.Distributed.Listener wired to Dev.TestRobot, so two named shells sharing a cookie are enough to exercise the full round-trip — see the README's "Testing distribution locally" section.

:node option vs Distributed.attach/3 — which do I want?

Both require Erlang distribution (same cookie, reachable EPMD/ports).

Runtime inspection and tracing

The supervising runtime exposes a few debugging hooks — handy when something goes wrong inside an SSH session that isn't otherwise observable:

# Quick headless-or-not check plus dimensions, render count, etc.
ExRatatui.Runtime.snapshot(pid)

# Capture the last N state transitions in memory.
ExRatatui.Runtime.enable_trace(pid, limit: 200)
ExRatatui.Runtime.trace_events(pid)
ExRatatui.Runtime.disable_trace(pid)

# Deterministically drive input in tests (see test/bb/tui/integration_test.exs)
ExRatatui.Runtime.inject_event(pid, %ExRatatui.Event.Key{code: "tab", kind: "press"})

See ExRatatui.Runtime for the full API.

Telemetry

Every TUI session emits :ex_ratatui-prefixed :telemetry events (mount, every keyboard/info dispatch, every frame, transport connect/disconnect, session lifecycle). Metadata carries :mod (always BB.TUI.App here) and :transport, so consumers running multiple ex_ratatui apps can filter accordingly. For local debugging, attach the default Logger handler:

BB.TUI.attach_telemetry_logger()
BB.TUI.detach_telemetry_logger()

For production observability, attach a custom :telemetry handler. See ExRatatui.Telemetry for the event surface and the README's Telemetry section for a Telemetry.Metrics-style wiring example.

Reducer runtime

BB.TUI.App is built on the ExRatatui reducer runtime (use ExRatatui.App, runtime: :reducer). Every keyboard event, PubSub message, async result, and subscription tick flows through a single update/2 arrow; pure state transitions live in BB.TUI.State.

• init/1 — validates the robot, subscribes to PubSub, snapshots ETS state.
• update({:event, ev}, state) — terminal input.
• update({:info, msg}, state) — PubSub, async results, send_after deliveries, subscription ticks.
• subscriptions/1 — declares the 100ms throbber tick whenever the dashboard has something animating; the runtime diffs the result so the timer only runs when needed.

Long-running command execution is owned by the runtime via ExRatatui.Command.async/2, batched with Command.send_after/2 for the timeout. Both reach the reducer as {:info, _} messages. Fast, fire-and-forget robot calls (arm / disarm / set_actuator / set_parameter / publish) are invoked inline from update/2.

See the README for the full rationale and the cross-references to ExRatatui.Command, ExRatatui.Subscription, and ExRatatui.Runtime.