Satellite Tracking with Gpredict

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.

Prerequisites

Before starting, make sure you have:

• A Winegard dish connected via serial (see Cable Wiring)
• The dish powered on and the TV search disabled (see Disabling TV Search)
• Motors homed and calibrated (see Calibration & Homing)
• The base aligned with “BACK” marking pointing to true North
• Clear sky view — no obstructions taller than 8 inches within 32.5 inches of the base center

Software installation

1. Install the birdcage package.

   # From the project directory
   uv sync
   
   # Verify installation
   uv run birdcage --help

2. Install Gpredict.

   # Arch Linux
   sudo pacman -S gpredict
   
   # Debian/Ubuntu
   sudo apt install gpredict
   
   # macOS (Homebrew)
   brew install gpredict

3. Update TLE data in Gpredict. On first launch, go to Edit > Update TLE Data from Network to fetch current orbital elements.

Architecture overview

The signal chain looks like this:

Gpredict  ──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 birdcage package implements this full chain:

• protocol.py — FirmwareProtocol ABC with implementations for HAL 2.05, HAL 0.0.00, and Carryout G2. Handles serial I/O, motor submenu navigation, position parsing.
• leapfrog.py — Predictive overshoot algorithm to compensate for mechanical motor lag.
• antenna.py — BirdcageAntenna class wrapping protocol + leapfrog. High-level move_to() and get_position().
• rotctld.py — RotctldServer TCP server implementing the p/P/S/_/q command set.
• cli.py — Click CLI with init, serve, pos, and move subcommands.

Starting the rotctld server

1. Initialize the dish. This waits for boot, kills the TV search, and enters the motor submenu.

   # HAL 2.05 (default)
   uv run birdcage init --port /dev/ttyUSB0
   
   # Carryout G2
   uv run birdcage init --port /dev/ttyUSB0 --firmware g2

   Wait for the “Antenna initialized and ready” message.

2. Start the rotctld server.

   # HAL 2.05
   uv run birdcage serve --port /dev/ttyUSB0
   
   # Carryout G2
   uv run birdcage serve --port /dev/ttyUSB0 --firmware g2
   
   # If the dish is already initialized (skip boot wait)
   uv run birdcage serve --port /dev/ttyUSB0 --firmware g2 --skip-init

   You should see:

   rotctld server listening on 127.0.0.1:4533
   Ctrl-C to stop

3. Verify with a manual test. In another terminal:

   # Query position
   echo "p" | nc 127.0.0.1 4533
   
   # Move to AZ=180, EL=45
   echo "P 180.0 45.0" | nc 127.0.0.1 4533

CLI options

The serve command accepts these options:

Option	Env Var	Default	Description
--port	BIRDCAGE_PORT	/dev/ttyUSB0	Serial port for the adapter
--firmware	BIRDCAGE_FIRMWARE	hal205	Firmware variant (hal205, hal000, g2)
--host	BIRDCAGE_LISTEN_HOST	127.0.0.1	TCP listen address
--listen-port	BIRDCAGE_LISTEN_PORT	4533	TCP listen port
--skip-init	—	false	Skip boot wait and search kill

Configuring Gpredict

1. Open Gpredict and go to Edit > Preferences > Interfaces > Rotators.

2. Add a new rotator with these settings:

   Setting	Value
   Name	Winegard Trav’ler
   Host	127.0.0.1
   Port	4533
   Az type	0 -> 180 -> 360
   Min El	15 (or 18 for G2)
   Max El	90 (or 65 for G2)

3. Open the rotor control panel. In the main Gpredict window, click the arrow in the bottom-right of a module and select Antenna Control.

4. Select your rotator from the dropdown in the antenna control panel.

5. Select a satellite to track from the satellite dropdown.

6. Click “Track” to begin automated tracking. Gpredict will send position updates to the rotctld server as the satellite moves across the sky.

Azimuth mode matters

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.

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.

For each axis, if the difference between the target and current position exceeds a threshold, the target is nudged further:

Delta (degrees)	Overshoot applied
> 2.0	+/- 1.0 degree
> 1.0	+/- 0.5 degree
≤ 1.0	None

The direction of overshoot matches the direction of travel. This keeps the dish slightly ahead of the satellite, reducing tracking error during a pass.

The leapfrog algorithm is enabled by default. To disable it for a manual move:

uv run birdcage move --port /dev/ttyUSB0 --az 180 --el 45 --no-leapfrog

Bug fix from upstream

The original birdcage.py from Gabe’s repo had a copy-paste bug where the elevation delta adjustments modified target_az instead of target_el. This is fixed in the leapfrog.py module. The same bug exists in the Trav’ler Pro repo.

Physical setup checklist

For accurate tracking, verify these physical conditions:

• North alignment. The base marking “BACK” should point to true North (not magnetic north). Use a compass and apply your local magnetic declination.
• Level mounting. The base should be level. A tilted base shifts all AZ/EL readings.
• Clear horizon. No obstructions taller than 8 inches within 32.5 inches of the base center. The dish arm sweeps a 32.5-inch radius.
• Power. Stable 120VAC to the RP-SK87 supply. Voltage dips during motor moves can cause missed steps.

Quick reference: manual commands

While the rotctld server handles everything automatically, you can also control the dish directly:

# Query current position
uv run birdcage pos --port /dev/ttyUSB0 --firmware g2

# Move to a specific AZ/EL
uv run birdcage move --port /dev/ttyUSB0 --firmware g2 --az 180 --el 45

Rotctld protocol extensions (G2 only)

When running with a Carryout G2, the rotctld server supports additional commands beyond the standard Hamlib protocol:

Command	Function
R [n]	Read RSSI signal strength (averaged over n samples)
L	Enable LNA for signal reception
D	Discover supported protocol extensions

These commands allow integration with sky-scanning workflows. A non-G2 rotator returns RPRT -6 (not available) for these commands.

Radio Telescope Mode Use the G2's built-in DVB tuner for RF sky mapping with the azscanwxp command.