Cross-link Craft as tracking controller alongside Gpredict
Satellite tracking guide now covers both Gpredict and Craft (space.warehack.ing) as rotctld clients. Architecture docs updated to be protocol-first rather than Gpredict-specific. TUI guide mentions Track mode's rotctld server for external controller integration.
This commit is contained in:
parent
3ede7d7eb6
commit
696f85b1af
@ -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
|
||||
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.
|
||||
</Aside>
|
||||
|
||||
## 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).
|
||||
|
||||
<Aside type="tip" title="Extended protocol on G2 hardware">
|
||||
When Birdcage is running with a Carryout G2, Craft can use the extended rotctld commands -- `R` for RSSI signal strength, `L` to toggle the LNA, and `D` to discover which extensions are available. This means Craft can read signal strength during a pass and enable the LNA for reception, all through the standard rotor connection. See [Rotctld protocol extensions](#rotctld-protocol-extensions-g2-only) below.
|
||||
</Aside>
|
||||
|
||||
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.
|
||||
|
||||
@ -73,6 +73,7 @@ on connect, and the one you come back to when you're done adjusting.
|
||||
|
||||
|
||||
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)
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user