birdcage-docs/src/content/docs/index.mdx

---
title: "Birdcage"
description: A generic AZ/EL positioner that doesn't care about wavelength — repurposing motorized satellite TV dishes for amateur radio tracking
template: splash
hero:
  tagline: A generic AZ/EL positioner that doesn't care about wavelength
  image:
    file: ../../assets/carryout-g2.jpg
    alt: Winegard Carryout G2 satellite dish — the white dome radome that inspired the project name
  actions:
    - text: Get Started
      link: /getting-started/
      icon: right-arrow
    - text: Try Demo Mode
      link: /guides/tui/#quick-start
      variant: minimal
    - text: Browse Guides
      link: /guides/wiring/
      variant: minimal
---

import { Card, CardGrid, LinkCard, Aside, Steps } from '@astrojs/starlight/components';

Birdcage turns salvaged RV satellite dishes into general-purpose AZ/EL positioners. Point them at LEO satellites, map the RF sky, capture images during passes — the hardware doesn't care what you're tracking or why.

## What it does

<CardGrid>
  <Card title="Satellite Tracking" icon="star">
    Real-time pass prediction from the [Craft API](https://space.warehack.ing), or connect Gpredict via the built-in rotctld server. Search by name, filter by elevation, track automatically.
    [Tracking guide &rarr;](/guides/satellite-tracking/)
  </Card>
  <Card title="Camera Capture" icon="seti:image">
    Manual, interval, and pass-event triggered image capture. Produces JPEG frames with JSON metadata and optional FITS output for scientific workflows.
    [TUI guide &rarr;](/guides/tui/)
  </Card>
  <Card title="Radio Telescope" icon="sun">
    2D RF sky mapping with `azscanwxp` — a firmware command that sweeps azimuth while cycling DVB transponders and logging RSSI at each grid point.
    [Radio telescope guide &rarr;](/guides/radio-telescope/)
  </Card>
  <Card title="Signal Analysis" icon="bars">
    Live RSSI monitoring, automated sweep peaking, DVB tuner access, and LNB polarity switching — all from the Signal screen.
    [Signal screen &rarr;](/guides/tui/#f3--signal)
  </Card>
  <Card title="Motor Control" icon="setting">
    Keyboard nudging, position presets, velocity tuning, configurable step sizes. Direct motor commands with safety gates to prevent accidental stow.
    [Control screen &rarr;](/guides/tui/#f2--control)
  </Card>
  <Card title="Raw Console" icon="terminal">
    Full firmware shell access through the TUI. 12 submenus, 100+ commands, with history and prompt-aware I/O.
    [Command reference &rarr;](/reference/console-commands/)
  </Card>
</CardGrid>

## The TUI

![Birdcage TUI — six screens shown in demo mode](/screenshots/tui-collage.png)

Six screens, one terminal. Everything from pass prediction to raw firmware commands:

- **F1 — Dashboard:** Satellite list, pass predictions, active tracking status, position readout
- **F2 — Control:** Motor nudging, presets, velocity controls, step size selector
- **F3 — Signal:** RSSI plots, DVB tuner status, sweep peaking, LNB diagnostics
- **F4 — System:** NVS settings, firmware identification, motor lifetime stats
- **F5 — Console:** Direct firmware shell with prompt-terminated I/O and command history
- **F6 — Camera:** Live capture overlay with manual, interval, and pass-event triggers

<Aside type="note" title="No hardware? No problem.">
Demo mode runs the full TUI with simulated data — every screen, every interaction. It's the fastest way to see what Birdcage can do.
</Aside>

<Steps>
1. **Clone and install** (from the `tui/` directory):

   ```bash
   cd tui/
   uv sync
   ```

2. **Run in demo mode:**

   ```bash
   uv run birdcage-tui --demo
   ```
</Steps>

## Why "Birdcage"?

In ham radio, satellites are called "birds." The Carryout G2's white dome radome looks like a birdcage — and a birdcage catches birds from the sky.

It's also a nod to [saveitforparts](https://www.youtube.com/@saveitforparts). Gabe saves discarded RV satellite dishes "for parts." We took the parts and built a birdcage from them.

<Aside type="tip" title="Standing on the shoulders of saveitforparts">
This project builds directly on the open-source work of **Gabe Emerson (KL1FI)** and his
[saveitforparts](https://www.youtube.com/@saveitforparts) YouTube channel. Gabe documented
five different Winegard dish variants, wrote Python control scripts for each, and shared
everything on GitHub. Chris Davidson ([cdavidson0522](https://github.com/cdavidson0522/winegard-sky-scan))
figured out the G2's RS-422 wiring and discovered the built-in radio telescope mode.
Without their work, none of this would exist.
[Read the full story &rarr;](/journal/origins/)
</Aside>

## Supported hardware

Five Winegard dish variants are documented, with varying levels of testing:

| Variant | Connection | Status |
|---------|-----------|--------|
| Trav'ler (HAL 0.0.00) | RS-485 / RJ-25 | Supported (Gabe's original) |
| Trav'ler (HAL 2.05) | RS-485 / RJ-25 | Supported (Gabe's original) |
| Trav'ler Pro | USB A-to-A | Partially supported |
| Carryout (2003) | RS-485 / RJ-25 | Supported (different protocol) |
| Carryout G2 | RS-422 / RJ-12 | **Fully reverse-engineered** |

The Carryout G2 has the most complete documentation — over 100 firmware commands mapped across 12 submenus, NVS settings dumped, GPIO pins identified, and motor control characterized.

<LinkCard title="Firmware Variant Comparison" href="/reference/firmware-variants/" description="Detailed comparison table of all five variants: baud rates, motor commands, position formats, and protocol differences." />

## Where to start

<CardGrid>
  <Card title="Getting Started" icon="rocket">
    What hardware you need, how to connect, and your first satellite track.
    [Start here &rarr;](/getting-started/)
  </Card>
  <Card title="Guides" icon="open-book">
    Wiring, calibration, satellite tracking, camera capture, radio telescope, BLE wireless bridge.
    [Browse guides &rarr;](/guides/wiring/)
  </Card>
  <Card title="Reference" icon="document">
    100+ firmware commands, NVS settings, GPIO pin maps, hardware specs, serial protocol.
    [See reference &rarr;](/reference/firmware-variants/)
  </Card>
  <Card title="Project Journal" icon="pencil">
    Discovery stories, debugging sessions, and the ongoing narrative of reverse-engineering these dishes.
    [Read the journal &rarr;](/journal/)
  </Card>
</CardGrid>

## Project journal

This isn't just a reference manual. The [project journal](/journal/) captures the story of how we got here — the debugging sessions, the discoveries, the moments where a `?` in the right submenu revealed a whole new capability.

<LinkCard title="Read the journal" href="/journal/" description="Discovery stories, debugging sessions, and the ongoing narrative of this project." />