birdcage/CLAUDE.md

Winegard Trav'ler

Control a Winegard Trav'ler motorized satellite dish via RS-485 for amateur radio satellite tracking.

Project

• Package: travler-rotor (installed via uv sync)
• CLI entry point: travler-rotor (init / serve / pos / move)
• Source layout: src/travler_rotor/ (src-layout)
• Original upstream: Trav-ler-Rotor-For-HAL-2.05/ — Gabe Emerson's scripts, kept as reference (do not modify)

Build & Lint

uv sync                           # Install deps + package
uv run ruff check src/             # Lint
uv run ruff format --check src/    # Format check
uv run travler-rotor --help        # CLI smoke test

Architecture

protocol.py   — FirmwareProtocol ABC + HAL205Protocol / HAL000Protocol
                Serial I/O owned here. Each firmware version is a subclass.
leapfrog.py   — Pure function: apply_leapfrog(target, current) -> adjusted
                Predictive overshoot to compensate for mechanical motor lag.
antenna.py    — TravlerAntenna: high-level control wrapping protocol + leapfrog
                This is what consumers (CLI, rotctld, future MCP server) call.
rotctld.py    — RotctldServer: Hamlib rotctld TCP protocol (p/P/S/_/q)
                Bridges Gpredict to the antenna.
cli.py        — Click CLI with init/serve/pos/move subcommands

Firmware Variants

Three known Winegard dish variants exist (Gabe Emerson / saveitforparts):

Detail	HAL 0.0.00	HAL 2.05.003	Trav'ler Pro
Repo	saveitforparts/Travler_Rotor	saveitforparts/Trav-ler-Rotor-For-HAL-2.05	saveitforparts/Travler-Pro-Rotor
Connection	RS-485 / RJ-25	RS-485 / RJ-25	USB A-to-A
Motor submenu	mot	motor	mot
Search kill	os -> kill Search -> q	ngsearch -> s -> q	os -> kill Search
Boot signal	NoGPS	NoGPS or No LNB Voltage	undocumented
Max elevation	90 deg	90 deg	75 deg (hardware limit)
Tested model	LG-2112	LG-2112	SK2DISH

Related: saveitforparts/Carryout-Rotor (Winegard Carryout, HAL 1.00.065, very similar commands).

Hardware Protocol Notes

• RS-485 serial, 57600 baud, 8N1 (via USB-to-RS232 + DTECH RS232-to-RS485 + RJ-25)
• Motor commands: a <motor_id> <degrees> (0=azimuth, 1=elevation)
• Position query: a (in motor submenu) returns AZ = <val> EL = <val> SK = <val>
• Two motor control methods:
  • a <id> <deg> — queues command, waits for current motor to stop before next
  • g <az> <el> <sk> — immediate move, aborts on any new keystroke
• Elevation floor: HAL 2.05 unreliable below 15 degrees with direct motor commands
• Cable wrap limit: usually 360 or 455 degrees, dish reverses at limit

RS-485 Pinout (RJ-25, bottom view, tip up)

Pin	Function
1	GND
2	T/R-
3	T/R+
4	RXD-
5	RXD+
6	Not used

Firmware Console Commands

?              — list available commands
motor / mot    — enter motor submenu (firmware-dependent)
a              — show position (in motor submenu)
a <id> <deg>   — move motor to absolute position
g <az> <el>    — go to AZ/EL (aborts on new input)
q              — exit current submenu
os             — enter OS submenu
  tasks        — list running tasks
  kill <name>  — kill a named task (e.g. "kill Search")
ngsearch       — enter search submenu (HAL 2.05 only)
  s            — stop search
nvs            — enter non-volatile storage submenu
  e <idx>      — read NVS value
  e <idx> <v>  — write NVS value
  s            — save changes
reboot         — reboot firmware

Known NVS Indices

Index	Setting
102	Max elevation
125	Search minimum elevation
127	Safe minimum elevation

IDU/ODU Cable Wiring (if cut)

Top row: Green, Yellow, Orange. Bottom row: Red, Brown, Black.

Power

48-52VDC power supply for the IDU. The internal coax supplies 14-18VDC bias — do not connect 5V equipment without bypassing the power injector.

Known Bugs (from upstream)

• Leap-frog elevation bug: original travler_rotor.py lines 98-105 modify target_az instead of target_el. Fixed in leapfrog.py. See docs/bugs.md.

Testing

No hardware-in-the-loop tests yet. Protocol implementations can be mocked for unit testing — FirmwareProtocol is an ABC with clear method contracts.