Add Craft mode and Camera sections to TUI guide

Document the F2 Craft sub-mode (search, passes, 1 Hz tracking via
space.warehack.ing API) and F6 Camera overlay (manual, interval, and
pass-event triggers). Update screen count from five to six, add
satellite catalog to demo mode bullet list, remove orphaned
tui-position.png screenshot.
This commit is contained in:
Ryan Malloy 2026-02-17 14:19:41 -07:00
parent b95e116f16
commit c477a112e3
2 changed files with 58 additions and 7 deletions

Binary file not shown.

Before

Width:  |  Height:  |  Size: 76 KiB

View File

@ -1,6 +1,6 @@
--- ---
title: "The Birdcage TUI" title: "The Birdcage TUI"
description: A five-screen terminal interface for controlling Winegard satellite dishes — from a $75 RV salvage find to something that looks like it belongs in a ground station. description: A six-screen terminal interface for controlling Winegard satellite dishes — from a $75 RV salvage find to something that looks like it belongs in a ground station.
sidebar: sidebar:
order: 8 order: 8
badge: badge:
@ -54,11 +54,12 @@ a Gaussian RSSI signal model, and all 12 firmware submenus. Every screen works,
does something. You don't need a dish on the roof to try it. does something. You don't need a dish on the roof to try it.
</Aside> </Aside>
## Five Screens ## Six Screens
Navigate between screens with **F1****F5** keys or click the tab bar at the top. Navigate between screens with **F1****F4** keys, plus **F5** and **F6** overlays. Click the
The device status bar at the bottom persists across all screens — connection state, tab bar at the top or use the hotkeys. The device status bar at the bottom persists across
serial port, firmware version, and current menu prompt are always visible. all screens — connection state, serial port, firmware version, and current menu prompt are
always visible.
### F1 — Dashboard ### F1 — Dashboard
@ -72,8 +73,9 @@ on connect, and the one you come back to when you're done adjusting.
![Birdcage TUI Control screen showing compass rose, step size selector, and manual controls](/screenshots/tui-control.png) ![Birdcage TUI Control screen showing compass rose, step size selector, and manual controls](/screenshots/tui-control.png)
Where you actually point the dish. Three modes across the top: **Manual**, **Presets**, and **Track**. Where you actually point the dish. Four modes across the top: **Manual**, **Presets**, **Track**, and **Craft**.
Track mode starts a rotctld server on port 4533 so external controllers -- [Craft](https://space.warehack.ing) or [Gpredict](/guides/satellite-tracking/#configuring-gpredict) -- can drive the dish with live satellite tracking. Track mode starts a rotctld server on port 4533 so external controllers — [Gpredict](/guides/satellite-tracking/#configuring-gpredict) or a remote [Craft](https://space.warehack.ing) instance — can drive the dish with live satellite tracking.
Craft mode talks to the [space.warehack.ing](https://space.warehack.ing) API directly — no rotctld needed.
In Manual mode, a compass rose shows current azimuth with a bearing indicator. AZ and EL In Manual mode, a compass rose shows current azimuth with a bearing indicator. AZ and EL
readouts update live — the G2's stepper resolution is 0.009° azimuth (40,000 steps/rev) readouts update live — the G2's stepper resolution is 0.009° azimuth (40,000 steps/rev)
@ -87,6 +89,27 @@ max velocity in °/s and hit Apply. The firmware stores these in STEP> as micros
but the TUI handles the conversion. Home AZ, Home EL, and E/R (engage/release motors) but the TUI handles the conversion. Home AZ, Home EL, and E/R (engage/release motors)
round out the bottom toolbar. round out the bottom toolbar.
#### Craft Mode
![Birdcage TUI Craft mode showing search results for satellites and celestial bodies](/screenshots/tui-craft-search.png)
Craft mode connects directly to the [space.warehack.ing](https://space.warehack.ing) API for
satellite and celestial body tracking — no rotctld server, no external controller. Type a name
in the search bar and the catalog returns matches with NORAD ID, type, and group. Select a
target from the results table, then hit **Track** to start following it at 1 Hz.
![Birdcage TUI Craft mode tracking the Moon at AZ 145.00° EL 32.01°](/screenshots/tui-craft-tracking.png)
The status panel shows the tracking lifecycle: **IDLE** (nothing selected), **TRACKING** (target
above minimum elevation, dish is moving), or **WAITING** (target below the minimum elevation
floor — the dish holds position until the target rises). Sat AZ and Sat EL update each second
with the target's computed position. The **Passes** button fetches upcoming pass predictions
for LEO targets — rise time, peak elevation, and duration.
Pass state transitions (WAITING → TRACKING at AOS, TRACKING → WAITING at LOS) feed into the
Camera overlay's automatic trigger system, so you can capture images at acquisition of signal,
closest approach, or loss of signal without manual intervention.
### F3 — Signal ### F3 — Signal
![Birdcage TUI Signal screen showing RSSI gauge, DVB and ADC sparklines](/screenshots/tui-signal.png) ![Birdcage TUI Signal screen showing RSSI gauge, DVB and ADC sparklines](/screenshots/tui-signal.png)
@ -127,6 +150,31 @@ The safety gates matter here: the console warns before sending `q` at root level
kills the firmware shell — requires power cycle to recover), before `reboot`, and before kills the firmware shell — requires power cycle to recover), before `reboot`, and before
NVS writes. The firmware doesn't have an "are you sure?" prompt. Birdcage does. NVS writes. The firmware doesn't have an "are you sure?" prompt. Birdcage does.
### F6 — Camera
![Birdcage TUI Camera overlay showing capture status, output format, and pass-event trigger buttons](/screenshots/tui-camera.png)
A modal overlay for image capture during satellite passes. Toggle it with **F6** or dismiss
with **Escape** — it floats over whichever screen you're on.
Three trigger modes:
- **Manual** — press **c** to capture a single frame on demand
- **Interval** — set a timer and capture automatically at a fixed cadence
- **Pass events** — fire on AOS (acquisition of signal), TCA (time of closest approach),
or LOS (loss of signal) transitions from the Craft or Track tracking loops
Each capture produces a JPEG frame paired with a JSON sidecar containing dish position,
target name, timestamp, trigger type, and tracking state at the moment of capture. The
status bar at the top of the overlay shows the active camera, capture count, last capture
time, output formats, and which triggers are armed.
<Aside type="tip">
Pass-event triggers work in demo mode — the simulated LEO satellites cycle through
AOS → TCA → LOS transitions, so you can test the full capture pipeline without hardware
or a live pass.
</Aside>
## Demo Mode ## Demo Mode
Pass `--demo` and Birdcage substitutes a `DemoDevice` for the serial bridge. The simulator models: Pass `--demo` and Birdcage substitutes a `DemoDevice` for the serial bridge. The simulator models:
@ -140,6 +188,9 @@ Pass `--demo` and Birdcage substitutes a `DemoDevice` for the serial bridge. The
etc. and `q` to go back all work correctly etc. and `q` to go back all work correctly
- **Full NVS dump** — the complete 134-entry table from firmware 02.02.48, captured from a - **Full NVS dump** — the complete 134-entry table from firmware 02.02.48, captured from a
live unit on 2026-02-12 live unit on 2026-02-12
- **Satellite catalog** — 8 canned objects (ISS, NOAA 19, SO-50, TEVEL-2, AO-91, Moon, Sun,
Jupiter) with time-varying LEO arcs that cycle through AOS → TCA → LOS transitions on
~10-minute periods. Camera pass-event triggers fire on these transitions.
Every screen, every widget, every button works in demo mode. It's the same code path — Every screen, every widget, every button works in demo mode. It's the same code path —
the only difference is what's on the other end of the bridge. the only difference is what's on the other end of the bridge.