# winegard-birdcage

Serial control library for Winegard motorized satellite dishes, repurposed for amateur radio satellite tracking.

Turns surplus RV/marine satellite TV antennas into steerable ground station dishes via RS-485 or RS-422.

## Install

```bash
pip install winegard-birdcage
```

## CLI Tools

Two entry points are included:

**birdcage** -- antenna control and rotctld server:

```bash
birdcage init --port /dev/ttyUSB0 --firmware hal205
birdcage pos
birdcage move --az 180.0 --el 45.0
birdcage serve --host 127.0.0.1 --port 4533   # rotctld for Gpredict
```

**console-probe** -- automated firmware exploration:

```bash
console-probe --port /dev/ttyUSB0 --baud 115200 --discover-only --json report.json
console-probe --port /dev/ttyUSB0 --baud 115200 --deep --wordlist wordlist.txt
```

## Supported Hardware

| Variant | Connection | Baud | Motor Command |
|---------|-----------|------|---------------|
| Trav'ler (HAL 0.0.00) | RS-485 / RJ-25 | 57600 | `a <id> <deg>` |
| Trav'ler (HAL 2.05) | RS-485 / RJ-25 | 57600 | `a <id> <deg>` |
| Trav'ler Pro | USB A-to-A | 57600 | `a <id> <deg>` |
| Carryout | RS-485 / RJ-25 | 57600 | `g <az> <el>` |
| Carryout G2 | RS-422 / RJ-12 | 115200 | `a <id> <deg>` |

## Architecture

```
protocol.py   -- FirmwareProtocol ABC + per-variant subclasses (HAL205, HAL000, G2)
leapfrog.py   -- Predictive overshoot compensation for mechanical motor lag
antenna.py    -- BirdcageAntenna: high-level control wrapping protocol + leapfrog
rotctld.py    -- Hamlib rotctld TCP server (p/P/S/_/q) for Gpredict integration
cli.py        -- Click CLI: init / serve / pos / move
```

## Related Packages

| Package | Description |
|---------|-------------|
| [birdcage-tui](https://pypi.org/project/birdcage-tui/) | Six-screen terminal UI for dish control |
| [mcbirdcage](https://pypi.org/project/mcbirdcage/) | MCP server for AI-assisted dish operations |

## Documentation

Full hardware details, wiring guides, firmware command reference, and NVS tables:
**[birdcage.warehack.ing](https://birdcage.warehack.ing)**

## Credits

- **Gabe Emerson (KL1FI / [saveitforparts](https://github.com/saveitforparts))** -- original Trav'ler, Trav'ler Pro, and Carryout rotor scripts
- **Chris Davidson ([cdavidson0522](https://github.com/cdavidson0522))** -- Carryout G2 sky scan and rotator control

## License

MIT