Add uvx install instructions and PyPI package references

Three pages updated: home, getting-started, TUI guide.
All now show uvx as the primary install method with tabbed
alternatives for pip install and from-source. Documents the
camera extra and lists all three PyPI packages.
This commit is contained in:
Ryan Malloy 2026-02-17 18:42:22 -07:00
parent 7da16815ec
commit 75f8de90c1
3 changed files with 103 additions and 40 deletions

View File

@ -5,7 +5,7 @@ sidebar:
order: 0 order: 0
--- ---
import { Card, CardGrid, Aside, LinkCard } from '@astrojs/starlight/components'; import { Card, CardGrid, Aside, LinkCard, Tabs, TabItem } from '@astrojs/starlight/components';
Before you start, you need three things: a dish, a way to talk to it, and the software to drive it. This page covers all three. Before you start, you need three things: a dish, a way to talk to it, and the software to drive it. This page covers all three.
@ -82,24 +82,69 @@ RS-485 half-duplex shares one differential pair for both transmit and receive. R
### Installing the software ### Installing the software
Clone the repository and install both packages: All three packages are on [PyPI](https://pypi.org/) — install with `uvx` (no clone needed) or from source.
```bash <Tabs>
git clone https://github.com/your-org/winegard-travler.git <TabItem label="uvx (recommended)">
cd winegard-travler Run any tool directly — `uvx` creates a temporary environment, installs dependencies, and cleans up after:
uv sync
```
This installs two CLI tools: ```bash
# Terminal UI (includes the core library automatically)
uvx birdcage-tui --demo
# Core CLI tools
uvx winegard-birdcage --help
# MCP server (for Claude Code / AI-assisted control)
uvx mcbirdcage
```
For the camera overlay (F6) with JPEG annotation and FITS export:
```bash
uvx --with 'birdcage-tui[camera]' birdcage-tui --demo
```
</TabItem>
<TabItem label="pip install">
Install persistently into a virtual environment:
```bash
pip install winegard-birdcage # Core library + CLI tools
pip install birdcage-tui # Terminal UI
pip install mcbirdcage # MCP server
```
</TabItem>
<TabItem label="From source">
Clone the repository for development:
```bash
git clone https://git.supported.systems/warehack.ing/birdcage.git
cd birdcage
uv sync # Core library + CLI tools
cd tui && uv sync # Terminal UI
cd ../mcp && uv sync # MCP server
```
</TabItem>
</Tabs>
This gives you three CLI tools:
- **`birdcage`** -- antenna control, rotctld server, position queries, manual moves - **`birdcage`** -- antenna control, rotctld server, position queries, manual moves
- **`console-probe`** -- firmware exploration and command discovery tool - **`console-probe`** -- firmware exploration and command discovery tool
- **`birdcage-tui`** -- six-screen terminal interface (demo mode works without hardware)
| PyPI Package | What it is |
|-------------|------------|
| [`winegard-birdcage`](https://pypi.org/project/winegard-birdcage/) | Core library: serial protocol, antenna control, rotctld server, CLI |
| [`birdcage-tui`](https://pypi.org/project/birdcage-tui/) | Textual TUI with 6 screens, satellite tracking, camera capture |
| [`mcbirdcage`](https://pypi.org/project/mcbirdcage/) | MCP server: 35 tools for AI-assisted dish control |
Verify the installation: Verify the installation:
```bash ```bash
uv run birdcage --help birdcage --help
uv run console-probe --help console-probe --help
birdcage-tui --demo
``` ```
## Next steps ## Next steps

View File

@ -27,26 +27,44 @@ Birdcage is what happens when you take all of that and give it a proper interfac
## Quick Start ## Quick Start
<Steps> <Tabs>
1. **Clone and install** (from the `tui/` directory inside the Birdcage repo): <TabItem label="uvx (no clone needed)">
```bash ```bash
# Demo mode — no hardware, no clone, no install
uvx birdcage-tui --demo
# With camera capture support (Pillow + astropy)
uvx --with 'birdcage-tui[camera]' birdcage-tui --demo
# Connect to a real dish
uvx birdcage-tui --port /dev/ttyUSB0 --firmware g2
```
</TabItem>
<TabItem label="From source">
```bash
# Clone and install
cd tui/ cd tui/
uv sync uv sync
```
2. **Run in demo mode** (no hardware required): # Demo mode
```bash
uv run birdcage-tui --demo uv run birdcage-tui --demo
```
3. **Connect to a real dish:** # Connect to a real dish
```bash
uv run birdcage-tui --port /dev/ttyUSB0 --firmware g2 uv run birdcage-tui --port /dev/ttyUSB0 --firmware g2
``` ```
</Steps> </TabItem>
</Tabs>
### Extras
The base install includes everything except image processing. Optional extras add camera capabilities:
| Extra | Install | What it adds |
|-------|---------|-------------|
| *(base)* | `uvx birdcage-tui` | Full TUI, all 6 screens, demo mode |
| `camera` | `uvx --with 'birdcage-tui[camera]' birdcage-tui` | JPEG annotation (Pillow) + FITS export for radio astronomy (astropy) |
The camera screen (F6) works without the `camera` extra — it falls back to minimal JPEG output. The extra adds annotated frames and FITS file export for integration with DS9, CASA, and other astronomy tools.
<Aside type="tip"> <Aside type="tip">
Demo mode simulates a complete Carryout G2 — motor physics at 10°/s with settling noise, Demo mode simulates a complete Carryout G2 — motor physics at 10°/s with settling noise,

View File

@ -19,7 +19,7 @@ hero:
variant: minimal variant: minimal
--- ---
import { Card, CardGrid, LinkCard, Aside, Steps } from '@astrojs/starlight/components'; import { Card, CardGrid, LinkCard, Aside, Tabs, TabItem } 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. 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.
@ -69,20 +69,20 @@ Six screens, one terminal. Everything from pass prediction to raw firmware comma
Demo mode runs the full TUI with simulated data — every screen, every interaction. It's the fastest way to see what Birdcage can do. 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> </Aside>
<Steps> <Tabs>
1. **Clone and install** (from the `tui/` directory): <TabItem label="uvx (no clone needed)">
```bash
uvx birdcage-tui --demo
```
</TabItem>
<TabItem label="From source">
```bash ```bash
cd tui/ cd tui/
uv sync uv sync
```
2. **Run in demo mode:**
```bash
uv run birdcage-tui --demo uv run birdcage-tui --demo
``` ```
</Steps> </TabItem>
</Tabs>
## Why "Birdcage"? ## Why "Birdcage"?