Merge pull request #26 from Valar-Systems/feat/birding-edition

Birding edition: eBird sightings radar + data screens (FEATURE_BIRDING)

Author: daniel-frenkel

.github/workflows/firmware.yml

@@ -35,6 +35,9 @@ jobs:
           # FEATURE_SEISMIC product: same boards, Seismic-edition firmware, own OTA channel
           # (firmware-seismic-<slug>.bin -- the slug must match FW_OTA_PREFIX + variant::SLUG).
           - { env: blipscope-seismic-s3-146, slug: seismic-s3-146 }
+          # FEATURE_BIRDING product: same boards, Birding-edition firmware, own OTA channel
+          # (firmware-birding-<slug>.bin -- the slug must match FW_OTA_PREFIX + variant::SLUG).
+          - { env: blipscope-birding-s3-146, slug: birding-s3-146 }
           # - { env: blipscope-lite-s3-128,       slug: s3-128 }
           # - { env: blipscope-pro-s3-175-amoled, slug: s3-175-amoled }
     steps:

CLAUDE.md

@@ -49,6 +49,13 @@ The radar SKUs are all S3: `blipscope-s3-146` (Waveshare ESP32-S3-Touch-LCD-1.46
 
 Unlike Space/EAM (rotating screens), the Seismic UI mirrors the **Aviation radar**: three swipe-able screens (Radar / List / Stats) with a tap-to-inspect detail-card overlay ([SeismicManager](src/seismic/SeismicManager.h) + [SeismicScreens.cpp](src/seismic/SeismicScreens.cpp)). Its quake radar is **static range rings**, not the aircraft PPI sweep, so [main.cpp](src/main.cpp) gates the sweep block out of the FEATURE_SEISMIC build (alongside EAM/Space). The data layer mirrors `SpaceFeedClient`: [SeismicFeedClient](src/seismic/SeismicFeedClient.h) runs one worker over the **USGS FDSN event query API** (a worldwide "recent" query + a radius-bounded "near me" query, both bounded by `limit` so the JSON stays small), with shapes + parsers in [SeismicModels.h](src/seismic/SeismicModels.h). It bakes in **no backend** (the optional `se-base-url` config is empty by default). ntfy alerts reuse the shared `ntfy-topic` on three toggles (big quake worldwide / quake near you / tsunami-flagged), edge-seeded at boot so the backlog never fires.
 
+## FEATURE_BIRDING — a fifth product (Birding edition)
+
+`-DFEATURE_BIRDING` (set on the `blipscope-birding-*` envs) swaps the radar app for the **Birding edition** — notable bird sightings near you, live from the **Cornell eBird API** — built from the same boards and shared infra. Its `build_src_filter` drops the radar-only TUs **and** `src/eam/` **and** `src/space/` **and** `src/seismic/`, and [main.cpp](src/main.cpp) picks `BirdingManager` at compile time. Everything lives in [src/birding/](src/birding/). The config page gains a `#elif defined(FEATURE_BIRDING)` branch in [ConfigurationWebServer.cpp](src/ConfigurationWebServer.cpp). OTA channel: `-DFW_OTA_PREFIX="birding-"`.
+
+- **Data / key:** the source is the eBird API 2.0; it needs the user's **own free token** (config `ebird-key`, sent as the `X-eBirdApiToken` header) — never a baked-in key, the same BYO pattern as the radar's OpenSky login and masked on the config page the same way (`*`-mask on GET, skip-if-masked on save). [BirdingFeedClient](src/birding/BirdingFeedClient.h) runs one worker over three endpoints (recent *notable* nearby, all recent nearby, nearby hotspots), all bounded by `dist`/`maxResults`; shapes + parsers in [BirdingModels.h](src/birding/BirdingModels.h). Nothing is polled until a key **and** a location are set.
+- **UI:** a **hybrid** of the two existing shells — a dwell-timed auto-rotation that skips empty feeds AND swipe-to-navigate (from Space/EAM), **plus** a tap-to-inspect detail-card overlay on the radar / notable screens (from the Seismic/Aviation radar). Screens: sightings Radar, Notable, Big-Day species count, nearest Hotspot, Targets, Splash, Clock ([BirdingManager](src/birding/BirdingManager.h) + [BirdingScreens.cpp](src/birding/BirdingScreens.cpp)). The sightings radar uses static range rings, so [main.cpp](src/main.cpp) gates the aircraft PPI sweep out of the build (alongside EAM/Space/Seismic). ntfy alerts on two toggles (notable sighting / target species), seeded at boot via a seen-species set so the backlog never fires.
+
 ## The C3's three hard constraints — read before changing memory, networking, or touch
 
 These applied to the now-**retired C3 Kit** SKU: a **single-core RISC-V** chip with a tight, fragmenting heap — most non-obvious shared code exists to live within that. The board is gone, but its guards stay in the tree (inert on S3, gated by capability flags), so this section stays as reference and a C3 could be revived: **don't "simplify" the guards away.** The S3 SKUs (dual-core + PSRAM) relax all three (full framebuffer, enrichment always-on, touch and network on separate cores) via the variant's capability flags rather than by deleting the guards:

RELEASING.md

@@ -75,6 +75,18 @@ and a CI slug prefixed to match so a Seismic device never pulls a radar, EAM, or
 
 Same `version.txt` gate (one `FW_VERSION` bump releases radar, EAM, Spacescope, and Seismic together).
 
+## Birding builds — another separate OTA channel
+
+The `blipscope-birding-*` envs build a fifth **product** (the Birding edition, `-DFEATURE_BIRDING`; see
+[CLAUDE.md](CLAUDE.md)) from the same boards. Same arrangement as EAM/Space/Seismic: `-DFW_OTA_PREFIX="birding-"`,
+and a CI slug prefixed to match so a Birding device never pulls another edition's image:
+
+| env | slug (CI + OTA asset) |
+| --- | --- |
+| `blipscope-birding-s3-146` | `birding-s3-146` → `firmware-birding-s3-146.bin` |
+
+Same `version.txt` gate (one `FW_VERSION` bump releases every edition together).
+
 ## Legacy note: the retired C3
 
 The original ESP32-C3 Kit is retired — Blipscope is S3-only going forward. The workflow no

platformio.ini

@@ -196,6 +196,41 @@ build_src_filter =
     -<eam/>
     -<space/>
 
+; ===================== Birding edition (eBird sightings radar) ========
+; A compile-time PRODUCT from the same repo and boards: -DFEATURE_BIRDING swaps the radar app for the
+; Birding edition (src/birding/) -- notable bird sightings near you, live from the Cornell eBird API.
+; Reuses all the shared infra (display, Wi-Fi, web config, storage, HTTP/TLS, OTA, ntfy) but NOT the
+; radar/aircraft/ADS-B code, the EAM cluster, the Space cluster, or the Seismic cluster, which
+; build_src_filter strips. FW_OTA_PREFIX puts it on its own OTA channel (firmware-birding-<slug>.bin).
+; It bakes in NO key: the user supplies their own free eBird token in web config (X-eBirdApiToken).
+; Runs on the S3 1.46".
+[env:blipscope-birding-s3-146]
+extends = common
+board = esp32-s3-devkitc-1
+board_build.arduino.memory_type = qio_opi
+board_build.flash_size = 16MB
+board_upload.flash_size = 16MB
+board_build.partitions = default_16MB.csv
+build_flags =
+    ${common.build_flags}
+    -DBLIPSCOPE_VARIANT_S3_146
+    -DFEATURE_BIRDING
+    -DFW_OTA_PREFIX=\"birding-\"
+    -DBOARD_HAS_PSRAM
+    -DARDUINO_USB_MODE=1
+    -DARDUINO_USB_CDC_ON_BOOT=1   ; native USB-CDC: upload + monitor over the USB-C port
+build_src_filter =
+    +<*>
+    -<AircraftManager.cpp>
+    -<MqttPublisher.cpp>
+    -<SpecialAircraft.cpp>
+    -<AircraftInfoFields.cpp>
+    -<Logbook.cpp>
+    -<models/>
+    -<eam/>
+    -<space/>
+    -<seismic/>
+
 ; ===================== Assembled S3 tiers (TODO) ======================
 ; Added at hardware bring-up: each needs a variant header in include/variants/
 ; (pins verified against the board's wiki) and a panel/touch block in LGFX.h.