platformio.ini

; LoRaTrace RX — Cardputer-Adv (ESP32-S3) + M5Stack Cap LoRa-1262 (SX1262)
; Hardware rationale: docs/DESIGN.md §1. Project rules: CLAUDE.md.
;
; Phase 1 scope only (docs/DESIGN.md §9 step 1): RadioLib bring-up + hardcoded
; Meshtastic RX, no task/queue architecture yet. lib_deps stays minimal
; until Phase 2 adds GPS/SD/display libraries — see docs/history/PROGRESS.md.

[env:cardputer-adv]
; Pin the registry platform: Meshtastic's pioarduino build temporarily
; installs a same-named global override, while this project depends on the
; Arduino-ESP32 2.0.17 ABI used by GFX Library 1.4.0.
platform = espressif32@7.0.1
; No confirmed dedicated PlatformIO board definition for Cardputer-Adv at
; time of writing. esp32-s3-devkitc-1 is what the M5Stack community uses in
; practice for this ESP32-S3FN8-based board (verified via web search, not
; bench-confirmed here). Swap if M5Stack ships an official board file.
board = esp32-s3-devkitc-1
framework = arduino

; ESP32-S3FN8: 8MB flash, NO PSRAM (CLAUDE.md hardware assumptions). Do not
; add board_build.arduino.memory_type / PSRAM-enabling flags for this chip.
board_build.flash_size = 8MB
board_build.partitions = default_8MB.csv

; Cardputer-family boards use native USB-CDC for the serial console, not a
; UART bridge chip — TODO(verify) on real hardware; if serial monitor stays
; silent, this is the first thing to check.
build_flags =
    -D CORE_DEBUG_LEVEL=3
    -D ARDUINO_USB_CDC_ON_BOOT=1
    -D ARDUINO_USB_MODE=1

; Injects FIRMWARE_BUILD_REV (git short SHA, plus "-dirty" for a modified
; tree) so every binary is traceable to a commit. src/version.h holds the
; deliberate semantic version; this is the automated half. Python, not a
; shell command, because this project gets built on Windows where
; $(git ...) in build_flags does not work.
extra_scripts = pre:scripts/build_rev.py

monitor_speed = 115200
upload_speed = 921600

; src/gps_probe.cpp is a standalone bring-up sketch with its own
; setup()/loop() — see [env:gps-probe] below. It MUST be excluded here or
; it collides with main.cpp's setup()/loop() at link time.
build_src_filter = +<*> -<gps_probe.cpp>

lib_deps =
    ; Exact, not caret: a caret range lets a library the radio depends on
    ; change under a tagged release, and this is the SX1262 driver — the one
    ; dependency whose behaviour IS the measurement (audit A17). Bump
    ; deliberately, with a hardware check.
    jgromes/RadioLib@7.7.1
    ; Added for the Phase 1 boot-status splash (docs/history/CHANGELOG.md);
    ; now also what ui_task.cpp draws every page/menu through (`Arduino_GFX
    ; *tft`, ui_task.h). PINNED, not caret-ranged like RadioLib above: releases from
    ; ~v1.5 on (latest at the time this was added was v1.6.7) need
    ; esp32-hal-periman.h, which only exists on Arduino-ESP32 core 3.x —
    ; this project intentionally pins registry espressif32@7.0.1, which
    ; resolves to core 2.0.17 (confirmed: core 3.x fails on this header).
    ; v1.4.0 is confirmed building clean against the pinned core.
    ; Bumping this requires bumping the ESP32 platform/core in step, not on
    ; its own — don't let Library Manager silently float this one.
    moononournation/GFX Library for Arduino@1.4.0
    ; Cardputer ADV's keyboard is a TCA8418 I2C controller, not the base
    ; Cardputer's GPIO matrix (board_pins.h). Same library bmorcelli/Launcher
    ; uses for this board, so the wake sequence is a known-good path rather
    ; than hand-rolled register writes against a datasheet we haven't read.
    ; Exact for the same reason as RadioLib above. 1.0.2, not the 1.0.1 the
    ; old caret range named: ^1.0.1 had been resolving to 1.0.2 all along, so
    ; the number in this file did not describe the build (audit A17).
    adafruit/Adafruit TCA8418@1.0.2

; GPS bring-up probe — a standalone sketch (src/gps_probe.cpp) that does
; nothing but dump raw NMEA from the GPS UART and report whether a fix ever
; lands. Not part of the shipping firmware and not the Phase 2 gps_task:
; it exists so the GPS can be proven on its own, the way the radio should
; have been (see docs/history/PROGRESS.md 2026-08-23, the sync-word bug — hardware
; entangled with other hardware hides its own failure mode).
;
;   pio run -e gps-probe --target upload     # probe the GPS
;   pio run -e cardputer-adv --target upload # back to the real firmware
;
; Inherits board/flash/USB-CDC settings from the main env so the probe runs
; on an identically-configured chip; only the source filter differs.
; io_expander.cpp is required, not optional: P0 powers the GPS as well as
; switching the RF antenna path, so a probe without it reads a dead module.
[env:gps-probe]
extends = env:cardputer-adv
build_src_filter = -<*> +<gps_probe.cpp> +<io_expander.cpp>

; Bench-only Cardputer image. Fault hooks are compile-time gated and the
; normal cardputer-adv image has no way to arm them.
[env:cardputer-adv-bench]
extends = env:cardputer-adv
build_flags =
    ${env:cardputer-adv.build_flags}
    -D LORATRACE_BENCH_FAULTS=1
    ; Pins the bench receiver's home channel into the image so it no longer
    ; depends on config.txt surviving on the bench SD card. Focus receives at
    ; the home bandwidth, so a card swap that reverts home to the built-in
    ; default silently changes a measurement's bandwidth. Matches the channel
    ; the 2026-09-04 dwell matrix ran at; production is unaffected.
    -D LORATRACE_BENCH_HOME_FREQ_MHZ=918.5f
    -D LORATRACE_BENCH_HOME_SF=8
    -D LORATRACE_BENCH_HOME_BW_KHZ=125.0f
    -D LORATRACE_BENCH_HOME_CR=5
    -D LORATRACE_BENCH_HOME_SYNC=0x2B

; Host-native unit test env — for pure-logic headers (channel_plans.h and
; onward: fingerprint.h, log-schema formatting) that don't touch hardware.
; Runs in CI without an ESP32 toolchain; much faster than testing on-target.
; Doesn't build src/main.cpp (that needs Arduino/RadioLib) — see
; test/test_channel_plans/README or docs/history/PROGRESS.md for scope.
[env:native]
platform = native
test_framework = unity
; src/main.cpp needs Arduino.h/RadioLib, which native can't build. Tests
; reach into src/ via relative #include instead, so exclude src/ entirely
; from this env's build rather than relying on filename-based skipping.
build_src_filter = -<*>