- README.md for all three packages (core, TUI, MCP)
- pyproject.toml readme field for PyPI rendering
- 8 new tests for MCP resources (5) and prompts (3)
- Total MCP test coverage: 57 tests, 37 tools + 5 resources + 3 prompts
Bumped version to 2026.02.17, added classifiers/keywords/URLs.
Documented camera extra (Pillow + astropy) in CLAUDE.md.
Added TUI section with uvx usage and extras table.
Core library published as winegard-birdcage (import stays `birdcage`).
MCP server renamed birdcage-mcp → mcbirdcage, matching mcserial pattern.
Both packages live on PyPI — `uvx mcbirdcage` works out of the box.
Bridge: set_lnb_voltage(mode) wraps firmware lnbdc command, enable_lna()
now delegates to it. MCP: new set_lnb_voltage tool + 3 tests. TUI: Signal
screen button toggles between V-pol and H-pol instead of one-way LNA enable.
Move bridge.py, demo.py, craft_client.py from tui/src/birdcage_tui/ to
src/birdcage/ so both TUI and MCP server can share the device layer
without a circular dependency on textual.
- DemoCraftClient in demo.py: duck-typed CraftClient replacement with
8 canned satellites, synthetic pass predictions, and time-varying LEO
arcs that drive real AOS/TCA/LOS pass events to the camera overlay
- Fix sky map EL signal fidelity: snap _el to _target_el at sweep start
so 2D scans compute correct per-row RSSI (was using stale elevation)
- Branch on demo_mode in app.py _setup_craft_client() to inject
DemoCraftClient instead of the HTTP CraftClient
- Add test_demo_craft.py: 5 tests exercising search, passes, tracking,
and WAITING state through the full TUI without mocks
- Update take_screenshots.py to cover all 8 screens (dashboard, control,
craft search, craft tracking, signal, system, console, camera)
Camera backend abstraction wrapping fswebcam/ffmpeg/libcamera-still via
subprocess, with DemoCamera fallback generating valid JPEG from raw bytes.
Capture pipeline writes JPEG + JSON sidecar always, optional FITS (astropy)
and EXIF (Pillow) when available. Thread-safe orchestrator with session
tracking, sequence numbering, and date-based output directories.
Trigger system: manual capture, configurable interval timer, and pass event
detection (AOS/TCA/LOS) with 0.5-degree TCA hysteresis. PassEventDetector
runs in the Craft tracking loop, fires callbacks to the camera overlay.
F6 overlay follows the F5 ConsoleOverlay pattern — ModalScreen with
install_screen persistence. Status panel, scrollable capture log, interval
controls, and AOS/TCA/LOS toggle buttons.
Tagline: "a generic AZ/EL positioner that doesn't care about wavelength"
added to TUI header subtitle.
51 new tests (77 total passing).
New F2 Control sub-mode that searches the Craft orbital catalog (22k+
objects), displays pass predictions, and drives the dish in real-time
using server-computed AZ/EL positions from /api/sky/up.
Tracking loop polls at ~1Hz, filters for the tracked target by
target_type + target_id (str, not int — handles satellites, planets,
stars, comets), and issues motor commands through the existing serial
bridge. Verified end-to-end with Carryout G2 hardware tracking NOAA 17.
New files:
- craft_client.py — stdlib HTTP client (urllib only, no deps)
- widgets/craft_panel.py — search table, pass info, tracking status
- tests/test_craft_mode.py — 5 unit tests with mocked API
- tests/test_craft_integration.py — 3 hardware integration tests
TUI-compatible Hamlib rotctld TCP server that works with the
existing SerialBridge/DemoDevice interface. F2 Control's Track
tab now starts/stops a real TCP server on the configured port.
Status callbacks report connection state, move count, and command
rate back to the TrackingPanel via thread-safe call_from_thread.
Includes 7 pilot tests exercising the full protocol path through
asyncio TCP clients against the DemoDevice.
F2 Control screen Manual mode now has a row of step-size buttons
(0.1°, 0.5°, 1°, 5°, 10°) that scale arrow key nudges, plus
AZ/EL velocity inputs with Apply button for runtime motor speed
tuning via firmware mv/ma commands.
Bridge: set_max_velocity(), set_max_acceleration() write methods.
Demo: mutable dynamics + console mv/ma write handling.
Tests: 8 Textual pilot tests covering button toggle, nudge math,
velocity population, and apply round-trip.
Allegro A3981 stepper motor driver: datasheet, KiCad symbols/footprint,
3D model (TSSOP-28). Two per G2 board, SPI-controlled, AUTO microstep.
NXP MK60DN512VLQ10 (Kinetis K60): datasheet and 1300-page reference
manual. Cortex-M4 96MHz MCU running the G2 firmware.
Reyax RYS352A GPS module: datasheet and PAIR command guide.
GPS receiver on the G2 board (used for auto-location/satellite lookup).
All extracted as markdown + page images + vector SVGs for LLM context.
Binary assets (PDFs, PNGs, SVGs, STEP, WRL) stored via git-lfs.
Track PDFs, images (PNG/JPG), SVGs, and 3D models (STEP/WRL) via
git-lfs to keep repo clone size manageable as datasheets and
extracted page images accumulate.
Automated deep probe of Winegard firmware console interfaces.
Discovers available commands via help parsing, submenu probing,
and wordlist brute-force. Handles prompt-terminated serial I/O
with the > character termination strategy.
Modules: serial_io (prompt-aware I/O), discovery (auto-discovery),
profile (DeviceProfile dataclass), report (JSON output), cli (argparse).
boot_baud_probe.py: Probe all standard baud rates during G2 power-on
to detect bootloader UART configuration differences.
boot_capture.py: Capture and analyze G2 boot sequence output, with
optional interrupt sequence injection to explore bootloader entry.
ee_dump.py: Dump EEPROM indices from EE> submenu, identifying
initialized vs. uninitialized (0x10101 sentinel) entries.
Replace sidebar + 5-screen layout with horizontal tab bar (F1-F4)
and persistent StatusStrip. Consolidate Position + Scan screens into
Signal (F3) with Monitor/Sweep/Sky Map sub-modes via ModeBar.
Screens:
- F1 Dashboard: system health, tracking panel, quick actions, presets
- F2 Control: motor tuning, compass rose, preset management
- F3 Signal: RSSI monitor, 1D sweep (SweepPlot), 2D sky map (heatmap)
- F4 System: NVS editor with regex filter, EEPROM, firmware info
- F5 Console: push/pop overlay (no longer a tab)
New widgets: StatusStrip, ModeBar, SweepPlot, QuickActions, PresetList,
ReceiverInfo, MotorTuning, NvsFilter, SystemHealth, TrackingPanel.
Removed: PositionScreen, ScanScreen, DeviceStatusBar (functionality
absorbed into new screens and StatusStrip).
App-level position poll feeds StatusStrip and active screen at ~2 Hz.
Fix shared threading.Event across instances (class-level mutable default).
Stop handler now calls cancel_operation() on the device bridge,
which sets a threading.Event that interrupts the 2s-timeout serial
read loop in send_with_timeout(). InterruptedError is caught
separately to prevent falling back to software sweep on cancel.
disconnect() uses acquire(timeout=5) with force-close fallback
instead of blocking lock acquisition — prevents deadlock when a
stuck worker holds the serial lock during shutdown.
Add 3 Textual async tests (pytest-asyncio) to verify Stop behavior:
firmware sweep stop, software sweep stop, and sweep restart.
The sweep/scan finally blocks call self.app.call_from_thread() to
reset button state, but self.app raises NoActiveAppError if the
Textual context is already torn down during Ctrl+C shutdown.
Wrap with contextlib.suppress so the flag reset still happens.
send_with_timeout now uses a 2s per-byte timeout with a deadline
loop instead of one long blocking read, checking a cancel event
between reads. SerialBridge.disconnect() sets the cancel event
before acquiring the lock, so a blocked firmware sweep aborts
within ~2s and releases the lock for clean port shutdown.
_sweeping/_scanning flags were never reset when workers finished,
leaving the UI stuck in "Stopping..." forever. Both _do_sweep and
_do_scan now use try/finally to always clear state and reset button
styles. Firmware sweep checks the flag after the blocking serial
call returns and discards results if Stop was pressed mid-execution.
Adds send_with_timeout() to CarryoutG2Protocol for long-running
commands, and az_sweep_firmware() to both SerialBridge and DemoDevice.
Sweep and Sky Map modes now try the firmware path first (single
azscanwxp command, streaming results) and fall back to software
step-dwell-measure on error or when "Software mode" checkbox is
checked. Software sweep fixed to set EL once and move AZ only.
Replace time.sleep() with threading.Event.wait() in all poll
loops so worker threads exit immediately on shutdown instead of
blocking for up to 500ms per iteration. Fixes the on_unmount
crash (NoMatches from querying removed DOM nodes) by signaling
the event directly rather than iterating child widgets.
Three shutdown paths covered: q key (on_unmount), Ctrl+C
(try/finally in main), and Textual internal shutdown.
Poll threads (position at 2 Hz, signal when monitoring) run
while-loops with time.sleep() that never exit on app quit.
Add on_unmount() to PositionScreen, SignalScreen, and BirdcageApp
to clear polling flags and disconnect the device, so worker threads
exit within the sleep interval instead of hitting the 300s timeout.
F1 Position (compass rose, motor control, sparklines),
F2 Signal (RSSI gauge with sub-char precision, DVB/ADC sparklines, LNA toggle),
F3 Scan (AZ/EL grid sweep with heatmap and CSV export),
F4 System (NVS table, A3981 diagnostics, motor dynamics),
F5 Console (raw serial terminal with prompt detection and safety gates).
Includes SerialBridge (thread-safe protocol wrapper), DemoDevice
(synthetic simulation for --demo mode), dark RF theme with rounded
borders and teal accents, and send_raw() on CarryoutG2Protocol.
The radome looks like a birdcage, ham operators call satellites
"birds", and it's a nod to saveitforparts saving dishes "for parts."
Package, CLI entry point, class names (BirdcageAntenna), env vars
(BIRDCAGE_PORT, etc.), and CLAUDE.md updated. Hardware references
(Winegard Trav'ler, Trav'ler Pro, Carryout G2) unchanged.
Rewrote hidden_menu_probe.py from Winegard-hardcoded to auto-discovering:
detects prompt, error string, and submenu structure from any firmware console.
Extracted Winegard-specific candidate words to scripts/wordlists/winegard.txt.
Deep probe of all 12 G2 submenus discovered commands across A3981 (driver
diagnostics), ADC (RSSI monitoring + position sweep), DVB (extended help via
man, transponder selection), EEPROM (read/write), GPIO (pin R/W), LATLON
(calculator), MOT (azscan, sw), PEAK (EchoStar switch), and STEP (raw
stepper control). NVS submenu generates false positives — treats any input
as sequential index reads.
Safety: added q/Q to default blocklist, bare-CR check before navigate_to_root
to prevent accidental shell termination between submenus.
Position parser now matches the actual Angle[0]/Angle[1] format
instead of falling back to fragile raw-float extraction. RSSI parser
uses a proper named-group regex matching the real firmware output
format (Reads:<n> RSSI[avg: <v> cur: <v>]) — the old index-based
approach would fail on the actual 5-field response.
Motor test results: both axes move correctly, direction-dependent
overshoot of 0.01-0.06 degrees confirmed. DVB subsystem explored:
BCM4515 Rev B0, firmware v113.37, full command set documented
including DiSEqC 2.x, transponder scanning, and streaming AGC/SNR.
RSSI noise floor is ~500.
Confirmed via DSD TECH SH-U11 RS-422 adapter at 115200 baud:
- Firmware version 02.02.48, bootloader 1.01, Kinetis MCU, BCM4515 DVB
- Position format is Angle[0]/Angle[1], not AZ=/EL= like Trav'ler
- Prompts are TRK>/MOT>/NVS> (not bare >)
- NVS 20 disable tracker confirmed working after power cycle
- Full NVS dump captured (indices 0-143)
- RJ-12 wire colors documented (differ from Davidson's guide)
- RS-422 polarity swap symptoms documented (garbled RX vs silent TX)
- Cable wrap range confirmed: -423.33° to +23.33° (446.66° total)
Replace altitude-validity heuristic with authoritative GGA quality
field (SPS/DGPS/RTK) and GSA nav mode (2D/3D) via TinyGPSCustom
extractors. Send $PAIR062 commands at boot to filter NMEA output
to only GGA/GSA/RMC/GSV and configure PPS for fix-only pulses.
GpsPayload struct gains fix_quality field (16 -> 14 bytes packed).
The RYS352A uses Airoha AG3352 engine with $PAIR proprietary
commands. UBX is u-blox, PMTK is MediaTek — neither applies.
Also document TinyGPS++ v1.1 requirement for GN talker ID
(multi-constellation) support and reference the PAIR command guide.
The AG3352 GNSS engine in the RYS352A ships at 115200 8N1 per
the datasheet spec table. 9600 was a generic assumption that
would cause the UART to read garbage and never acquire a fix.
RYS352A GPS on UART2 (GPIO5/6) with PPS interrupt (GPIO7),
MPU-9250 IMU and BMP388 barometer on shared I2C bus (GPIO8/9).
Sensor data exposed via dedicated BLE service with binary
notify characteristics alongside the existing NUS serial bridge.
Sensors degrade gracefully if not wired.
MPU-9250 provides magnetometer (auto north alignment), accelerometer
(elevation verification), and gyroscope (slew quality). BMP388 provides
pressure and temperature for atmospheric refraction correction at low
elevation angles. Both share I2C bus on GPIO8/9.
NimBLE-based Nordic UART Service (NUS) bridge on ESP32-S3-DevKitC-1.
Transparent passthrough: BLE client writes → UART1 TX → RS-422 → G2,
and G2 → RS-422 → UART1 RX → BLE notifications. USB serial serves as
debug monitor and fallback input.
Uses two MAX485 modules (one locked TX, one locked RX) with a SparkFun
BSS138 level converter for 3.3V/5V translation. Wiring schematic and
RJ-12 pinout documented in docs/ble-bridge-wiring.md.
Extend the rotctld wire protocol with three new commands that enable
signal strength measurement through the Carryout G2's DVB subsystem:
- R [n]: Read RSSI (handles motor→dvb→rssi→motor menu dance internally)
- L: Enable LNA for signal reception (one-time pre-scan setup)
- D: Discover capabilities (returns CAPS:rssi,lna for G2, empty for others)
Non-G2 protocols return RPRT -6 (not available) for R and L commands.
The menu state invariant is maintained after every operation so P commands
continue to work between RSSI reads.
Implement CarryoutG2Protocol based on cdavidson0522/winegard-sky-scan:
prompt-terminated reads via '>' char, 115200 baud RS-422, h <id>
motor homing, DVB/RSSI signal strength measurement. Update CLAUDE.md
with G2 variant column, NVS index 20, dvb sub-commands, and wiring
differences. CLI now accepts --firmware g2.
Add Carryout and Trav'ler Pro to firmware variant table, SK-1000
physical specs, error messages, calibration procedures, emergency
stow notes, motor behavior details, and Gpredict setup config.
Note leap-frog bug is also present in Pro repo.
HAL 0.0.00 kills the search task via the OS task manager (os -> kill Search)
rather than the ngsearch submenu used by HAL 2.05. Boot signal is NoGPS only.
Source: saveitforparts/Travler_Rotor upstream repo.
CLAUDE.md now includes firmware variant comparison table, full command
reference, NVS indices, RS-485 pinout, and cable wiring notes.
Extract Gabe Emerson's Trav'ler rotor scripts into a proper Python
library with firmware protocol abstraction (HAL 2.05 + HAL 0.0.00),
Hamlib rotctld TCP server, Click CLI, and isolated leap-frog algorithm
with the elevation copy-paste bug fixed.
