Beta - autocross and more

.github/workflows/beta.yml

@@ -103,7 +103,7 @@ jobs:
         run: |
           arduino-cli compile \
             --fqbn "${{ matrix.board.fqbn }}" \
-            --build-property "compiler.cpp.extra_flags=-D${{ matrix.board.define }} -DFIRMWARE_VERSION_OVERRIDE=${{ steps.ver.outputs.betaver }} -DSERIAL_BUFFER_SIZE=256 -DBIRDSEYE_ENABLE_SENSOREGG=1" \
+            --build-property "compiler.cpp.extra_flags=-D${{ matrix.board.define }} -DFIRMWARE_VERSION_OVERRIDE=${{ steps.ver.outputs.betaver }} -DSERIAL_BUFFER_SIZE=256 -DDOVES_DISABLE_DEBUG -DBIRDSEYE_ENABLE_SENSOREGG=1" \
             --output-dir dist \
             --warnings none \
             BirdsEye

.github/workflows/compile-sketch.yml

@@ -13,18 +13,31 @@ jobs:
     name: ${{ matrix.board.name }}
     runs-on: ubuntu-latest
     env:
-      # DovesLapTimer ref for this build: anything targeting (or running on)
-      # the BETA branch tracks the library's own BETA branch, so the two beta
-      # channels move together; everything else pins the known-good release
-      # tag (bump deliberately). base_ref is only set on pull_request events;
-      # ref_name covers push / workflow_dispatch.
-      LAPTIMER_REF: ${{ (github.base_ref == 'BETA' || github.ref_name == 'BETA') && 'BETA' || 'v4.2.0' }}
-      # Feature flags for this build, matched to the channel the code is
-      # headed for (see project.h). BETA enables the SensorEgg POC exactly
-      # as beta.yml does, so the flag-on build is compile-checked on the PR
-      # rather than first failing on the publish workflow. Everything else
-      # builds the master/release defaults (all flags off).
-      FEATURE_FLAGS: ${{ (github.base_ref == 'BETA' || github.ref_name == 'BETA') && '-DBIRDSEYE_ENABLE_SENSOREGG=1' || '' }}
+      # Channel this build belongs to. The channel follows the SOURCE tree
+      # being compiled, not just where it is headed:
+      #   base_ref == BETA  -> a feature PR into BETA (compiling BETA-era code)
+      #   head_ref == BETA  -> the long-lived BETA -> master integration PR
+      #                        (#113). Its source is still BETA's, so it must
+      #                        build with BETA's library + flags; without this
+      #                        it compiled BETA code against master's pins and
+      #                        failed on the sprint headers forever.
+      #   ref_name == BETA  -> push / workflow_dispatch on BETA itself
+      # Anything else is master/release. NOTE: merging BETA into master is
+      # what promotes the channel — at that point the fallbacks below must be
+      # bumped deliberately (a DovesLapTimer release tag carrying
+      # CrossingEngine/SprintTimer, plus a decision on the SensorEgg flag),
+      # here and in sim-build.yml / release.yml. (The condition is repeated
+      # rather than hoisted into its own env var because a job-level `env:`
+      # entry cannot reference its siblings.)
+      # DovesLapTimer ref: the beta channel tracks the library's own BETA
+      # branch so the two move together; everything else pins the known-good
+      # release tag.
+      LAPTIMER_REF: ${{ (github.base_ref == 'BETA' || github.head_ref == 'BETA' || github.ref_name == 'BETA') && 'BETA' || 'v4.2.0' }}
+      # Feature flags for this build (see project.h). BETA enables the
+      # SensorEgg POC exactly as beta.yml does, so the flag-on build is
+      # compile-checked on the PR rather than first failing on the publish
+      # workflow. Everything else builds the master/release defaults (off).
+      FEATURE_FLAGS: ${{ (github.base_ref == 'BETA' || github.head_ref == 'BETA' || github.ref_name == 'BETA') && '-DBIRDSEYE_ENABLE_SENSOREGG=1' || '' }}
     # Build both XIAO nRF52840 variants. The Sense board has the onboard
     # LSM6DS3 IMU; the plain board does not (accelerometer logging degrades
     # gracefully). Same MCU/BLE/bootloader otherwise.
@@ -74,7 +87,7 @@ jobs:
           # project.h static_asserts on it — keep all three workflows in sync.
           cli-compile-flags: |
             - --build-property
-            - compiler.cpp.extra_flags=-D${{ matrix.board.define }} -DSERIAL_BUFFER_SIZE=256 ${{ env.FEATURE_FLAGS }}
+            - compiler.cpp.extra_flags=-D${{ matrix.board.define }} -DSERIAL_BUFFER_SIZE=256 -DDOVES_DISABLE_DEBUG ${{ env.FEATURE_FLAGS }}
           enable-deltas-report: true
 
       # Hard flash-size gate. The XIAO nRF52840's app flash is shared
@@ -126,10 +139,21 @@ jobs:
       # bootloader is exactly that size. The program's flash usage equals the
       # app .bin that gets streamed/flashed, so gate it against that cap: warn
       # as it approaches, fail if it crosses (the image would be un-OTA-able).
+      #
+      # There are TWO caps, because the cap lives in the *installed* firmware,
+      # not in the image being delivered:
+      #   OTA_IMAGE_MAX_BYTES  — this layout's cap. Hard failure past it.
+      #   OTA_LEGACY_MAX_BYTES — the cap on units still running <= 3.0.x, which
+      #     stage at the old 0xA4000. Those units reject a larger image with
+      #     FWERR:SIZE and would need the USB UF2 path (FWDFU) instead, so
+      #     crossing it is a warning: it means the fleet has split.
+      # Drop the legacy warning once every unit you care about has taken a
+      # build carrying the 0x8E000 layout.
       - name: OTA image size gate
         env:
           # Keep in sync with FW_MAX_IMAGE_SIZE in BirdsEye/firmware_ota.ino.
-          OTA_IMAGE_MAX_BYTES: 327680   # 320 KiB
+          OTA_IMAGE_MAX_BYTES: 417792   # 408 KiB
+          OTA_LEGACY_MAX_BYTES: 327680  # 320 KiB — pre-3.1 staging layout
           OTA_WARN_PERCENT: 90
         run: |
           report="$(find sketches-reports -name '*.json' | head -1)"
@@ -149,13 +173,18 @@ jobs:
           pct="$(awk "BEGIN { printf \"%.1f\", ($flash_abs / $OTA_IMAGE_MAX_BYTES) * 100 }")"
           echo "OTA image: ${flash_abs} / ${OTA_IMAGE_MAX_BYTES} bytes (${pct}% of the OTA cap)"
           if [ "$flash_abs" -gt "$OTA_IMAGE_MAX_BYTES" ]; then
-            echo "::error::Image ${flash_abs} B exceeds the OTA cap ${OTA_IMAGE_MAX_BYTES} B — FWBEGIN would reject it (FWERR:SIZE). Shrink the image or raise FW_MAX_IMAGE_SIZE (which moves the staging base down, costing app space)."
+            echo "::error::Image ${flash_abs} B exceeds the OTA cap ${OTA_IMAGE_MAX_BYTES} B — FWBEGIN would reject it (FWERR:SIZE). Shrink the image, or finish plan 0004's SD-direct apply (which removes the staging region and the cap with it)."
             exit 1
           fi
           warn="$(awk "BEGIN { print (($flash_abs / $OTA_IMAGE_MAX_BYTES) * 100 >= ${OTA_WARN_PERCENT}) ? 1 : 0 }")"
           if [ "$warn" = "1" ]; then
             echo "::warning::OTA image at ${pct}% of the ${OTA_IMAGE_MAX_BYTES} B cap (>= ${OTA_WARN_PERCENT}%) — getting close to un-OTA-able; plan to shrink or raise the cap."
           fi
+          # Fleet-split check: an image past the legacy cap can no longer be
+          # installed by units still running the pre-3.1 staging layout.
+          if [ "$flash_abs" -gt "$OTA_LEGACY_MAX_BYTES" ]; then
+            echo "::warning::Image ${flash_abs} B exceeds the legacy ${OTA_LEGACY_MAX_BYTES} B cap — units still on <= 3.0.x will answer FWERR:SIZE and can only take this build over USB (FWDFU -> UF2). Ship a <= ${OTA_LEGACY_MAX_BYTES} B build first if any such unit still needs to migrate."
+          fi
 
       - name: Upload size deltas report
         if: always()

.github/workflows/release.yml

@@ -79,7 +79,7 @@ jobs:
         run: |
           arduino-cli compile \
             --fqbn "${{ matrix.board.fqbn }}" \
-            --build-property "compiler.cpp.extra_flags=-D${{ matrix.board.define }} -DSERIAL_BUFFER_SIZE=256" \
+            --build-property "compiler.cpp.extra_flags=-D${{ matrix.board.define }} -DSERIAL_BUFFER_SIZE=256 -DDOVES_DISABLE_DEBUG" \
             --output-dir dist \
             --warnings none \
             BirdsEye

ARCHITECTURE.md

@@ -36,7 +36,8 @@ own header first so declaration/definition drift is caught at compile
 time.
 
 The **pure units** (`haversine`, `gps_time`, `gps_validation`,
-`dovex_header`, `filename_validator`) deliberately avoid Arduino headers.
+`dovex_header`, `filename_validator`, `course_creator`, `track_json`, …)
+deliberately avoid Arduino headers.
 The *same* `.cpp` is compiled into both the firmware (Arduino picks up
 `.cpp` files in the sketch folder) and the host test binary (CMake). There
 is no copy-paste — the tests exercise the exact code that ships.
@@ -97,16 +98,25 @@ to the matching `*_LOOP()`.
   remote-button notifications.
 - **SensorEgg** (`sensoregg` + the `sensoregg_protocol` pure unit) —
   wireless EGT proof of concept: a passive BLE observer receives the
-  DovesSensorEgg pod's `PW-ADV-1` advertising broadcasts (14-byte
-  manufacturer data: EGT + cold junction as int16 deci-degC, fault flags,
-  sequence counter) and feeds the `Temp1`/`Junction1` DOVEX columns and
-  the Temp1 race page. Observer + peripheral coexist natively on S140;
-  passive scanning never transmits, so the camera link is untouched.
-  Readings older than 1 s go NaN — never held across a dropout. Gated on
-  the `BIRDSEYE_ENABLE_SENSOREGG` build flag: on in the beta channel, off
-  in master/release, where the scanner and Temp1 page are compiled out,
-  BLE returns to lazy init, and the DOVEX `Temp1`/`Junction1` columns are
-  written as `nan` so the log format stays identical across channels.
+  DovesSensorEgg pod's `PW-ADV` advertising broadcasts, v1 (14-byte:
+  EGT + cold junction as int16 deci-degC, fault flags, sequence counter)
+  and v2 (16-byte: + aux intake-air thermistor, real battery percent),
+  and feeds the `Temp1`/`Junction1`/`Temp2` DOVEX columns and the
+  Temp1/Temp2 race pages. Observer + peripheral coexist natively on
+  S140; passive scanning never transmits, so the camera link is
+  untouched. Readings older than 1 s go NaN — never held across a
+  dropout. Gated on the `BIRDSEYE_ENABLE_SENSOREGG` build flag: on in
+  the beta channel, off in master/release, where the scanner and temp
+  pages are compiled out, BLE returns to lazy init, and the DOVEX
+  `Temp1`/`Junction1`/`Temp2` columns are written as `nan` so the log
+  format stays identical across channels.
+- **Course creator** (`course_creator` + `track_json` pure units, glued
+  into the menu/pages/SD modules) — authors a track course on the device
+  by walking to each cone and holding for a 3 s GPS average. Autocross
+  venues re-lay their course every event, so the alternative was a laptop
+  in a paddock. No text is ever entered on-device: names come from the GPS
+  clock and are renamed later in the web app. This is also the firmware's
+  only track-JSON *writer* — everywhere else the format is read-only.
 - **Replay** (`replay`) — instant DOVEX header replay.
 - **Settings** (`settings`) — JSON key/value store on the SD card.
 - **CourseManager** (external library) — owns course detection, sector
@@ -181,7 +191,12 @@ the last resort.
 ### Shutdown is System OFF, wake is a reboot
 There is no power switch (deliberately — the next hardware revision drops
 it), so "off" is nRF52 **System OFF** at ~µA with GPIO SENSE armed on the
-tach pin and the three buttons, plus VBUS. Waking is a full chip reset:
+tach pin and the three buttons, plus VBUS. The tach's SENSE polarity is
+not hardcoded: the pickup circuit's output stage idles high or low
+depending on the build, so shutdown samples the parked line and arms
+SENSE for the opposite level (majority vote in the host-tested
+`wake_cause` unit) — arming toward the idle level satisfied DETECT
+immediately and battery sleep reboot-looped. Waking is a full chip reset:
 `setup()` runs fresh, and the very first thing it does is read (then
 clear) the sticky `RESETREAS` + GPIO `LATCH` registers to decode *why* it
 booted (the host-tested `wake_cause` unit). An engine-start (tach) wake