diff --git a/public/screenshots/tui-position.png b/public/screenshots/tui-position.png deleted file mode 100644 index add2f0f..0000000 Binary files a/public/screenshots/tui-position.png and /dev/null differ diff --git a/src/content/docs/guides/tui.mdx b/src/content/docs/guides/tui.mdx index 637597c..877d2e1 100644 --- a/src/content/docs/guides/tui.mdx +++ b/src/content/docs/guides/tui.mdx @@ -1,6 +1,6 @@ --- 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: order: 8 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. -## Five Screens +## Six Screens -Navigate between screens with **F1**–**F5** keys or click the tab bar at the top. -The device status bar at the bottom persists across all screens — connection state, -serial port, firmware version, and current menu prompt are always visible. +Navigate between screens with **F1**–**F4** keys, plus **F5** and **F6** overlays. Click the +tab bar at the top or use the hotkeys. The device status bar at the bottom persists across +all screens — connection state, serial port, firmware version, and current menu prompt are +always visible. ### 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) -Where you actually point the dish. Three modes across the top: **Manual**, **Presets**, and **Track**. -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. +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 — [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 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) 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 ![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 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. + + + ## Demo Mode 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 - **Full NVS dump** — the complete 134-entry table from firmware 02.02.48, captured from a 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 — the only difference is what's on the other end of the bridge.