diff --git a/src/content/docs/guides/satellite-tracking.mdx b/src/content/docs/guides/satellite-tracking.mdx index 5211ee9..6448813 100644 --- a/src/content/docs/guides/satellite-tracking.mdx +++ b/src/content/docs/guides/satellite-tracking.mdx @@ -1,13 +1,13 @@ --- -title: "Satellite Tracking with Gpredict" -description: End-to-end guide for tracking amateur radio satellites using Gpredict and the birdcage CLI +title: "Satellite Tracking" +description: End-to-end guide for tracking amateur radio satellites using Gpredict, Craft, or any Hamlib-compatible controller with the birdcage CLI sidebar: order: 4 --- import { Steps, Aside, LinkCard } from '@astrojs/starlight/components'; -This guide walks through the complete setup: installing the software, connecting to the dish, starting the rotctld server, configuring Gpredict, and tracking your first satellite pass. +This guide walks through the complete setup: installing the software, connecting to the dish, starting the rotctld server, and configuring a tracking controller. Two options are covered -- [Gpredict](#configuring-gpredict) (lightweight, local) and [Craft](#tracking-with-craft) (full ground station dashboard with pass prediction and MCP integration). ## Prerequisites @@ -55,11 +55,11 @@ Before starting, make sure you have: The signal chain looks like this: ``` -Gpredict ──TCP:4533──► rotctld server ──serial──► dish firmware -(tracking) (birdcage) (motor submenu) +Controller ──TCP:4533──► rotctld server ──serial──► dish firmware +(tracking) (birdcage) (motor submenu) ``` -Gpredict computes the satellite's predicted AZ/EL position and sends it to the rotctld server over TCP using the Hamlib rotctld protocol. The server translates those coordinates into motor commands and sends them over RS-485/RS-422 to the dish firmware. The firmware drives the stepper motors. +The tracking controller -- Gpredict, [Craft](https://space.warehack.ing), or anything else that speaks the Hamlib rotctld protocol -- computes the satellite's predicted AZ/EL position and sends it to the rotctld server over TCP. The server translates those coordinates into motor commands and sends them over RS-485/RS-422 to the dish firmware. The firmware drives the stepper motors. The `birdcage` package implements this full chain: @@ -160,6 +160,29 @@ The `serve` command accepts these options: The "0 -> 180 -> 360" azimuth mode is required. This tells Gpredict that the rotator measures azimuth as 0-360 degrees (North through East). The alternative "180 -> 360 -> 180" mode is for rotators that use a different reference. Using the wrong mode will cause the dish to point in the wrong direction. +## Tracking with Craft + +[Craft](https://space.warehack.ing) is a self-hosted ground station dashboard that tracks 22,000+ objects from the NORAD catalog -- satellites, debris, stations -- and can drive antenna rotors through the same Hamlib rotctld protocol that Gpredict uses. If your rotctld server is already running, Craft connects to it the same way. + +What Craft adds beyond Gpredict: + +- **Pass prediction** -- AOS/TCA/LOS for any tracked object, with scheduling +- **Continuous tracking at 2 Hz** -- position updates every 500 ms during a pass +- **Satellite catalog search** -- find objects by name, NORAD ID, or category instead of manually updating TLE files +- **WebSocket streams** -- live rotor position available to other tools and dashboards +- **MCP tools** -- `point_at` and `track` tools for programmatic or AI-driven satellite tracking +- **REST API** -- `POST /api/rotors/{id}/point`, `POST /api/rotors/{id}/track`, `DELETE /api/rotors/{id}/track` + +### Connecting Craft to Birdcage + +Start the rotctld server exactly as described [above](#starting-the-rotctld-server) -- Craft doesn't need anything different on the Birdcage side. In Craft's rotor configuration, point it at the host and port where `birdcage serve` is listening (default `127.0.0.1:4533`, or the machine's LAN address if Craft runs on a different host). + + + +For Craft's own setup and configuration, see the [Craft rotor control guide](https://space.warehack.ing/docs/guides/rotor-control/). + ## The leapfrog algorithm Satellite tracking requires continuous correction -- by the time the motors finish moving to a commanded position, a fast-moving LEO satellite has already moved. The leapfrog algorithm compensates by overshooting slightly in the direction of travel. diff --git a/src/content/docs/guides/tui.mdx b/src/content/docs/guides/tui.mdx index f9b0037..637597c 100644 --- a/src/content/docs/guides/tui.mdx +++ b/src/content/docs/guides/tui.mdx @@ -73,6 +73,7 @@ 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. 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) diff --git a/src/content/docs/understanding/architecture.mdx b/src/content/docs/understanding/architecture.mdx index af2e7d8..e548ae4 100644 --- a/src/content/docs/understanding/architecture.mdx +++ b/src/content/docs/understanding/architecture.mdx @@ -26,7 +26,7 @@ protocol.py FirmwareProtocol ABC + HAL205 / HAL000 / CarryoutG2 subclasses (owns the serial port) ``` -Data flows top-down: Gpredict sends a position command to the rotctld server, which calls the antenna, which applies leapfrog correction and hands the adjusted target to the protocol, which sends the serial bytes to the dish. +Data flows top-down: a tracking controller (Gpredict, Craft, or any Hamlib client) sends a position command to the rotctld server, which calls the antenna, which applies leapfrog correction and hands the adjusted target to the protocol, which sends the serial bytes to the dish. ### protocol.py -- firmware abstraction @@ -134,9 +134,9 @@ class BirdcageAntenna: `AntennaConfig` holds serial port, baud rate, minimum elevation, and the leapfrog toggle. The G2 defaults to 115200 baud and 18-degree minimum elevation; the Trav'ler defaults to 57600 and 15 degrees. -### rotctld.py -- Gpredict bridge +### rotctld.py -- tracking controller bridge -A plain TCP socket server implementing the subset of the Hamlib rotctld protocol that Gpredict uses: +A plain TCP socket server implementing the Hamlib rotctld protocol. Any controller that speaks this protocol can drive the dish -- [Gpredict](/guides/satellite-tracking/#configuring-gpredict) for lightweight local tracking, [Craft](https://space.warehack.ing) for a full ground station dashboard with pass prediction and MCP integration, or raw `nc` commands for scripting. | Command | Handler | Response | |---------|---------|----------| @@ -154,7 +154,7 @@ For CarryoutG2 specifically, three extension commands are available: | `L` | `_handle_enable_lna()` | Enable LNA for signal reception | | `D` | `_handle_capabilities()` | Report supported extensions | -The RSSI handler is noteworthy -- it has to switch firmware submenus mid-operation. It exits the motor menu, enters the DVB menu, reads RSSI, exits DVB, and re-enters the motor menu. Non-G2 rotors return `RPRT -6` (not available) for these commands. +The RSSI handler is noteworthy -- it has to switch firmware submenus mid-operation. It exits the motor menu, enters the DVB menu, reads RSSI, exits DVB, and re-enters the motor menu. Non-G2 rotors return `RPRT -6` (not available) for these commands. Controllers like [Craft](https://space.warehack.ing) use the `D` (discover) command first to detect which extensions are available, then use `R` and `L` when supported. ### cli.py -- the entry point