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

Five known Winegard dish variants documented by Gabe Emerson (KL1FI) / saveitforparts and cdavidson0522:

Detail	HAL 0.0.00	HAL 2.05.003	Trav'ler Pro	Carryout	Carryout G2
Repo	Travler_Rotor	Trav-ler-Rotor-For-HAL-2.05	Travler-Pro-Rotor	Carryout-Rotor	winegard-sky-scan
Connection	RS-485 / RJ-25	RS-485 / RJ-25	USB A-to-A (ttyACM0)	RS-485 / RJ-25	RS-422 / RJ-12 6P6C
Baud rate	57600	57600	57600	57600	115200
Motor submenu	mot	motor	odu then mot	N/A (target + g)	mot
Motor control	a <id> <deg>	a <id> <deg>	a <id> <deg>	g <az> <el> only	a <id> <deg>
Search kill	os -> kill Search	ngsearch -> s -> q	os -> kill Search	N/A	NVS 20 (permanent disable)
Boot signal	NoGPS	NoGPS or No LNB Voltage	undocumented	N/A	Boot Complete then Loc Startup: IDU NOT Present
Min elevation	15 deg (firmware)	15 deg (firmware)	12 deg (firmware)	22 deg (firmware-enforced)	18 deg (firmware)
Max elevation	90 deg	90 deg	75 deg (hardware cap!)	73 deg (firmware default, NVS 102 override)	65 deg (firmware)
Position query	a -> AZ = / EL =	a -> AZ = / EL =	a -> AZ = / EL =	raw ints / 100	a -> floats
Tested model	LG-2112	LG-2112	SK2DISH	2003 Carryout	Carryout G2
HAL version	0.0.00	2.05.003	unknown	1.00.065	02.02.48
Prompt char	> (likely)	> (likely)	undocumented	undocumented	TRK> / MOT> / NVS> (confirmed)
Position format	AZ = / EL =	AZ = / EL =	AZ = / EL =	raw ints / 100	Angle[0] = / Angle[1] =
DVB tuner	unknown	unknown	unknown	unknown	BCM4515 (Broadcom)
MCU	unknown	unknown	unknown	unknown	NXP MK60DN512VLQ10 (Kinetis K60, Cortex-M4, 96MHz, 512KB flash, 128KB RAM)
Motor driver	unknown	unknown	unknown	unknown	2× Allegro A3981 (SPI, 1/16 microstep, AUTO mode)

Key Variant Differences

• Trav'ler Pro odu command: The Pro's IDU has its own MCU. You must first tunnel to the ODU with odu before entering the motor submenu. The regular Trav'ler's IDU is a dumb RS-485 passthrough.
• Carryout uses g not a: The Carryout has no individual motor addressing. It uses target to enter targeting mode, then g <az> <el> for combined moves. It also can't query its initial position.
• Carryout has no limit switches: Uses motor stalling to detect mechanical boundaries (audible grinding).
• Pro has the same leap-frog bug as the regular Trav'ler (copy-pasted).
• NVS d command dumps all NVS values. Confirmed on Pro and Carryout G2; likely available on all variants.
• Carryout DIP switches: All switches to off (up) may disable search mode, but behavior varies by unit.
• Carryout G2 uses a not g: Unlike the 2003 Carryout, the G2 uses standard a <id> <deg> motor addressing and the mot submenu — protocol-compatible with the Trav'ler family.
• Carryout G2 is RS-422 full-duplex: Separate TX/RX pairs at 115200 baud via RJ-12 6P6C, vs. RS-485 half-duplex at 57600 on the Trav'ler variants. Tested with DSD TECH SH-U11 USB-to-RS422 adapter (FTDI FT232R). Polarity matters — A/B (or +/-) labeling is not standardized; if you get garbled data at the correct baud rate, swap the +/- wires on the RX pair. TX pair polarity swap causes the dish to not receive commands (silent failure).
• Carryout G2 position format differs from Trav'ler: Position query a in MOT> submenu returns Angle[0] = 180.00 / Angle[1] = 45.00 — not the AZ = / EL = format used by HAL 0.0.00 and HAL 2.05. Move confirmation returns Angle = 46.00 (no array index). CarryoutG2Protocol.get_position() uses Angle\[0\]/Angle\[1\] regex. Motor overshoot is direction-dependent: +0.01–0.05° in travel direction, -0.02–0.06° on return (stepper backlash).
• Carryout G2 firmware version 02.02.48 confirmed (Copyright 2013 - Winegard Company). Bootloader version 1.01. MCU: Kinetis (NXP ARM Cortex-M). DVB tuner: BCM4515 (Broadcom).
• Carryout G2 boot sequence: Bootloader → SPI init → Motor init (System=12Inch, master=40000 steps, slave=24960 steps, ratio=1.602564) → DVB tuner init (BCM4515) → NVS load → EL home (stall detect, 2s timeout) → AZ home (stall detect, 8s timeout) → Antenna Facing Front → TRK> prompt (if tracker disabled) or search start.
• Carryout G2 cable wrap: Confirmed from homing output: wrap_min:-42333 wrap_max:2333 (centidegrees). Total range ~446.66°.
• Carryout G2 has h <id> homing: Explicit motor home-to-reference command. Not documented on other variants.
• Carryout G2 has DVB/RSSI: BCM4515 tuner (ID 0x4515, Rev B0, firmware v113.37). DVB submenu provides rssi <n> (bounded, returns Reads:<n> RSSI[avg: <v> cur: <v>]), agc (streaming RF/IF AGC + SNR + NID), snr, lnbdc odu (enable LNA 13V), lnbv (streaming voltage monitor), dis (channel params), config (hardware ID), table (transponder scan), and DiSEqC 2.x commands (di2*, send). RSSI noise floor is ~500. lnbdc odu sets 13V (V-pol); boot default is 18V (H-pol). Streaming commands run until interrupted by q or another command.

Hardware Specs (SK-1000)

Spec	Value
Weight	45 lbs
Stow dimensions	10"H x 42"L x 26"W
Stow height	9.75"
Max deployed height	37" above mount
Arm reach	32.5" from base center
Dish size	~33" x 23" (Ku-band reflector)
Azimuth range	0-455 deg (before cable wrap)
Power input	120VAC -> 12VDC (RP-SK87 supply)
LNB bias	12-18VDC via coax
Motor type	Likely stepper with gearing (unconfirmed)
Satellites (DISH)	110, 119, 129 (61.5 manual only)
Satellites (Bell)	82, 91

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 finish. Tolerant of rapid command streams from Gpredict.
  • g <az> <el> <sk> — immediate move, aborts on any new keystroke/character. Some firmware has a typo listing the order as az/sk/el.
• Skew motor can run simultaneously with AZ or EL (the others are mutually exclusive)
• 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
• Console does not accept backspace — hit enter to clear on typo
• Firmware prompt character is > (ASCII 62) — used for reliable response termination in prompt-terminated read strategies

RS-485 vs RS-422 — Serial Bus Differences

The Winegard variants use two different differential signaling standards. Understanding which one matters for choosing the right USB adapter.

RS-485 half-duplex (2-wire): One shared differential pair carries both TX and RX. Only one device talks at a time — the transmitter drives the bus, then releases it so the other side can respond. This is how the Trav'ler IDU communicates with the ODU: the IDU sends a command on the shared T/R pair, then listens for the response on the same wires. Simple wiring (2 signal wires + ground), but throughput is limited by the turn-around time between send and receive.

RS-422 full-duplex (4-wire): Two separate differential pairs — one dedicated TX pair and one dedicated RX pair. Both sides can transmit simultaneously because the signals don't share wires. Higher throughput (no bus turnaround penalty), and the Carryout G2 uses this at 115200 baud. Point-to-point only (one transmitter per pair).

RS-485 full-duplex (4-wire): Electrically identical to RS-422 wiring (same 4-wire differential pairs), but the RS-485 spec allows multiple transmitters on each pair (multi-drop bus). For our point-to-point dish↔computer connection, 4-wire RS-485 and RS-422 are interchangeable.

Property	RS-485 half-duplex	RS-422 / RS-485 full-duplex
Signal wires	2 (+ GND)	4 (+ GND)
Direction	One direction at a time	Both directions simultaneously
Max nodes	32 drivers + 32 receivers	1 driver + 10 receivers (RS-422)
Max distance	1200m / 4000ft	1200m / 4000ft
Max baud	~10 Mbps	~10 Mbps
Voltage swing	±1.5V to ±5V differential	±2V to ±5V differential
Bus turnaround	Required (adds latency)	Not needed
Typical adapter	USB-to-RS485 (DTECH, etc.)	USB-to-RS422 (FTDI, DIYables, etc.)

Practical consequence for this project: The Trav'ler's RJ-25 connector exposes both a half-duplex pair (pins 2-3, labeled T/R) and a dedicated receive pair (pins 4-5, labeled RXD). Gabe's code uses only the half-duplex pair via an RS-485 adapter. Davidson's G2 code uses all four wires as RS-422. The same physical connector may support both modes depending on the firmware — this is unconfirmed on the Trav'ler but worth testing if you have a 4-wire adapter available.

Serial Connector Pinout

The physical connector is an RJ-25 (6P6C) on the Trav'ler or RJ-12 (6P6C) on the G2 — same form factor, same 6-pin modular jack.

Trav'ler pinout (RJ-25, bottom view, clip up):

Pin	Label	RS-485 use	RS-422 use
1	GND	Ground	Ground
2	T/R-	Shared data-	TX- (computer→dish)
3	T/R+	Shared data+	TX+ (computer→dish)
4	RXD-	(unused in half-duplex)	RX- (dish→computer)
5	RXD+	(unused in half-duplex)	RX+ (dish→computer)
6	N/C	Not connected	Not connected

Carryout G2 pinout (RJ-12, clip away, per Davidson's wiring guide):

Pin	Wire Color (Davidson)	Wire Color (confirmed)	RS-422 Function
1	White	Orange/White	GND (PE)
2	Red	Orange	TX+ (TA) — computer→dish
3	Black	Green/White	TX- (TB) — computer→dish
4	Yellow	Blue	RX+ (RA) — dish→computer
5	Green	Blue/White	RX- (RB) — dish→computer
6	Blue	Green	Not connected

Note: Wire colors vary by cable manufacturer. The "confirmed" column is from a standard 6P6C flat cable tested 2026-02-12. Always verify with a multimeter before connecting. Polarity is critical: swapping +/- on the RX pair produces garbled data at the correct baud rate (systematic bit inversion, not random noise). Swapping +/- on the TX pair causes silent failure (dish doesn't respond because it can't decode the inverted framing).

Adapter chain by variant:

Variant	Adapter	Wires Used
Trav'ler (Gabe's setup)	USB→RS232→RS485 (DTECH)	Pins 2-3 only (half-duplex)
Carryout G2 (Davidson)	USB→RS422 (5V TTL)	Pins 2-5 (full-duplex)
Carryout G2 (confirmed)	DSD TECH SH-U11 USB→RS422 (FTDI FT232R)	Pins 1-5 (full-duplex + GND)
Carryout G2 (ESP32)	ESP32 UART2→RS422 module (DIYables)	Pins 2-5 (full-duplex)

RS-422 Module Notes (DIYables MAX490)

The DIYables RS422-to-TTL module uses the MAX490 transceiver chip (2.5 Mbps max, well above our 115200 baud). Key specs:

• 5V TTL logic on the microcontroller side (RXD/TXD)
• 15 kV ESD protection on RS-422 lines
• TVS diode for lightning/spike suppression
• 10 ohm current-limiting resistors for overcurrent protection
• Built-in 120 ohm termination resistor (reduces echo on long runs)
• Power + TX/RX activity LEDs
• Board size: 5.0cm x 2.7cm

Failsafe concern: The MAX490 does not have failsafe logic, and the module has no provisions for passive failsafe bias resistors. When the RS-422 bus tri-states (no driver active — e.g., between commands, during power transitions, or if the dish firmware is slow to respond), the receiver inputs float and may see random transitions interpreted as garbage data. This can cause spurious bytes in the serial stream.

Workaround options:

1. Add external bias resistors — pull A/RX+ toward V+ and B/RX- toward GND through ~560 ohm resistors. This biases the idle bus to a known logic-high state (RS-422 "mark" / idle). Solder to the module or add inline on the RJ-12 breakout.
2. Use the prompt-terminated read strategy — our CarryoutG2Protocol._send() reads until > (ASCII 62) which naturally filters out garbage between commands, since random transitions are unlikely to produce a valid > in context.
3. Ignore idle noise in firmware — the Winegard firmware likely ignores unexpected input while it's processing or idle, but any bytes received during the bus float could corrupt the next valid command if they land in the UART buffer at the wrong time.

For short cable runs (under ~3m between ESP32 and dish), the built-in 120 ohm termination is sufficient and bus float is less likely to cause issues. For longer runs or electrically noisy environments (near motors, power supplies), add the bias resistors.

Firmware Console Commands

Full command inventory from automated deep probe (firmware 02.02.48, 2026-02-12). Probed with scripts/hidden_menu_probe.py --deep --wordlist scripts/wordlists/winegard.txt.

Root Menu (TRK>)

?              — list available commands (alias: help)
command        — undocumented (accepts input, purpose unknown)
a3981          — enter motor driver submenu
adc            — enter ADC submenu
dipswitch      — enter dipswitch submenu
dvb            — enter DVB tuner submenu
eeprom         — enter EEPROM submenu
gpio           — enter GPIO submenu
latlon         — enter lat/lon calculator submenu
mot            — enter motor control submenu
nvs            — enter non-volatile storage submenu
os             — enter OS submenu
peak           — enter peak/DiSEqC switch submenu
step           — enter stepper motor submenu
q              — terminate shell (WARNING: kills UART, requires power cycle!)
reboot         — reboot firmware
stow           — fold dish flat (caution: modified feeds may not survive)
odu            — tunnel to outdoor unit (Trav'ler Pro only)
ngsearch       — enter search submenu (HAL 2.05 only)

A3981 Submenu (A3981>) — Allegro Stepper Driver

reset          — reset Az/El A3981 fault flags
diag           — read AZ/EL diagnostic status (OK / fault)
cm             — Hi/Lo current control (torque) mode
help / ?       — list available commands
q              — return to TRK>

ADC Submenu (ADC>) — Analog-to-Digital Converter

m              — monitor RSSI (streaming, interrupt with q)
rssi           — read RSSI (single-shot, returns raw ADC value)
scan           — position sweep with RSSI readings (AZ/EL + lock + SNR)
help / ?       — list available commands
q              — return to TRK>

DIPSWITCH Submenu (DIPSWITCH>)

dipswitch      — read interpreted dipswitch value
help / ?       — list available commands
q              — return to TRK>

DVB Submenu (DVB>) — BCM4515 Tuner

agc            — stream RF/IF AGC + SNR + NID (continuous, interrupt with q)
config         — BCM hardware/firmware version
diag           — multi-block per-transponder diagnostics
dis            — display channel parameters (frequency, symbol rate, LNB polarity)
e <n> <v>      — edit channel parameter
freqs          — tuner frequency list
h <n>          — select transponder by ID (1-13)
help / ?       — list available commands (first page)
lnbdc odu      — enable LNA in ODU mode (13V = V-pol; boot default 18V = H-pol)
lnbv           — stream LNB voltage readings (continuous, interrupt with q)
ls             — lock status
man            — extended help (srch_mode, stats, t, etc.)
qls            — quick lock status
rssi <n>       — RSSI averaged over n samples (bounded, returns avg + cur)
snr            — SNR level (streaming)
srch_mode      — auto search mode (from man page)
stats          — satellite read stats (from man page)
t <n>          — select transponder
table          — generate transponder table
di2id          — DiSEqC read LNB hardware ID
di2stat        — DiSEqC read LNB status flags
send <hex>     — raw DiSEqC packet (max 6 bytes, space-delimited hex)
q              — return to TRK>

EEPROM Submenu (EEPROM>)

ee <idx> [<v>] — read/write EEPROM value at index
inv [<idx>]    — EEPROM inventory (from help)
def            — restore defaults (from help)
help / ?       — list available commands
q              — return to TRK>

GPIO Submenu (GPIO>)

dir            — set GPIO pin direction
r              — read GPIO pin (returns e.g. "B0 = 1")
w              — write GPIO pin (requires parameters)
help / ?       — list available commands
q              — return to TRK>

LATLON Submenu (LATLON>)

l              — calculate lat/lon position (requires 4 parameters)
help / ?       — list available commands
q              — return to TRK>

MOT Submenu (MOT>) — Motor Control

a              — show position: Angle[0] (AZ), Angle[1] (EL)
a <id> <deg>   — move motor to absolute angle (0=AZ, 1=EL)
a <id> +/-deg  — relative move (G2 only, undocumented)
azscan         — scan AZ from EL min to max (from help, untested)
e              — engage motors (energize steppers)
g <az> <el>    — go to AZ/EL (aborts on new input)
h <id>         — home motor to reference position
l              — list motors and state (0=AZIMUTH, 1=ELEVATION)
ma             — read max acceleration per motor
p              — read raw step positions
r              — release motors (de-energize steppers)
sd             — stall detection test (motor, direction, timeout)
sw             — undocumented (requires parameters)
v              — read motor velocities
w              — undocumented (requires parameters)
help / ?       — list available commands
q              — return to TRK>

NVS Submenu (NVS>) — Non-Volatile Storage

Caution: NVS e <idx> <value> writes values. Any unrecognized input is treated as a sequential index read (no error string), which generates false positives during probing but is harmless. s saves pending changes to flash.

d              — dump all NVS values (name/current/saved/default)
d <idx>        — dump single value with details
e <idx>        — read NVS value at index
e <idx> <v>    — write NVS value at index (NOT saved until `s`)
s              — save pending changes to flash
help / ?       — list available commands
q              — return to TRK>

OS Submenu (OS>)

id             — full MCU/firmware identification (NVS version, System ID, chip)
reboot         — reboot microcontroller
tasks          — list running tasks (HAL 0.0.00 only, not on G2)
kill <name>    — kill a named task (HAL 0.0.00 only, not on G2)
help / ?       — list available commands
q              — return to TRK>

PEAK Submenu (PEAK>) — Signal Peak / DiSEqC Switch

ts             — EchoStar switch toggle status
pw             — peak signal (from help, details truncated)
help / ?       — list available commands
q              — return to TRK>

STEP Submenu (STEP>) — Low-Level Stepper Control

e              — engage motor (same as MOT `e`)
ma             — set/read max acceleration
p              — read step positions (raw counts, not degrees)
r              — release motor (same as MOT `r`)
v              — read velocity (raw, not degrees/sec)
help / ?       — list available commands
q              — return to TRK>

Known NVS Indices

Full dump in docs/g2-nvs-dump.md (firmware 02.02.48, captured 2026-02-12).

Index	Setting	Default	Notes
20	Disable Tracker Proc?	FALSE	Set TRUE to prevent TV satellite search on boot
38	Sleep Mode Timer Secs	420	7 minutes before sleep
41	Satellite Scan Velocity	55.00	°/s during TV search
80	AZ Max Vel	65.00	°/s azimuth max velocity
81	AZ Max Accel	400.00	°/s² azimuth max acceleration
83	AZ Steps/Rev	40000	Stepper steps per full rotation
85	EL Max Vel	45.00	°/s elevation max velocity
88	EL Steps/Rev	24960	Stepper steps per full EL rotation
101	Minimum Elevation Angle	18.00	Firmware floor (degrees)
102	Maximum Elevation Angle	65.00	Firmware ceiling (degrees)
103	Elevation Home Angle	65.00	EL position after homing
112	Disable Dipswitch?	FALSE	Override physical DIP switches
113	Dipswitch Value	101	DirecTV config (ignored when tracker disabled)
128-133	AZ/EL PID Gains	varies	Kp/Kv/Ki tuning parameters

Error Messages

Message	Meaning
AZ MOTOR STALLED	Obstruction preventing rotation
EL MOTOR STALLED	Obstruction preventing elevation change
EL Motor Home Failure	Requires EL recalibration via IDU menu

IDU/ODU Cable Wiring (if cut)

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

Power

120VAC input to RP-SK87 power supply, outputs 12VDC to IDU. Internal coax carries 12-18VDC bias for LNB — do not connect 5V equipment (SDR LNAs, etc.) without bypassing the power injector.

Physical Setup

• Base marked with arrows and "BACK" at 0/360 deg (North)
• Align "BACK" with true North for accurate tracking
• Gpredict rotor config: 127.0.0.1:4533, 0->180->360 mode, min EL 15, max EL 90
• No obstructions taller than 8" within 32.5" of base center

Calibration

On power-up, the dish performs calibration movements to establish position and cable wrap limits (~10-15 minutes on Carryout, shorter on Trav'ler). After calibration, firmware automatically starts a TV satellite search — the init sequence kills this.

Carryout uses motor stalling (not limit switches) to detect mechanical boundaries — expect audible grinding during calibration.

EL recalibration (via IDU buttons): POWER -> ENTER (hold 2s) -> User Menu -> INSTALLATION -> Calibrate EL -> confirm hard stop position.

Emergency Manual Stow

Last resort only. 5/16" socket + 6" extension into auxiliary drive hole. Turn clockwise slowly. Ensure arm faces "rear" label before lowering. Improper execution can damage motor.

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. Present in both Trav'ler and Trav'ler Pro repos. See docs/bugs.md.

Upstream References

• github.com/saveitforparts/Travler_Rotor (HAL 0.0.00)
• github.com/saveitforparts/Trav-ler-Rotor-For-HAL-2.05 (HAL 2.05)
• github.com/saveitforparts/Travler-Pro-Rotor (Pro, USB)
• github.com/saveitforparts/Carryout-Rotor (Carryout, HAL 1.00.065)
• github.com/saveitforparts/Carryout-Radio-Telescope (RF scanning/imaging)
• github.com/cdavidson0522/winegard-sky-scan (Carryout G2 sky scan + rotator)
• Gabe Emerson / KL1FI — gabe@saveitforparts.com
• YouTube: Trav'ler v1 demo (youtu.be/X1hnReHepFI), v2 demo (youtube.com/watch?v=URJZjo5EcpQ)

Testing

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