English · 简体中文文档
Foot-mounted laser altimeter for parachute flare timing. It owns only the last ~13 m above ground: a TF02-Pro rangefinder measures height, a BNO085 IMU corrects for foot tilt, and the firmware beeps once per 50 cm of height lost (pitch = how far from the flare point, beep rate = how fast it is closing), then holds a continuous tone below the changeover height.
This is a DIY validation device, not a life-critical instrument. It cross-checks flare timing after the fact; nobody relies on it in the air.
The one rule: when it sounds, it is right. A cue that cannot be vouched for is not given. Every stage therefore fails towards silence, and the device says on the ground, with a chime, whether it is in a state to be right at all: two rising notes = ready, three falling notes = not ready (and the console says why).
| docs/README.md | The full document, in English: what you hear, how a height reaches the buzzer, hardware and wiring, console commands, what has and has not been verified, known limits, references. |
| docs/README.zh-CN.md | 同一份文档的中文版。 |
docs/wiring-xiao-grove-shield.svg |
Wiring on the Seeed Grove Shield for XIAO (中文版). |
docs/ describes the device as it is now. The history behind it — decision
records, dated session logs, toolchain troubleshooting — is kept in the
author's Obsidian vault, outside this repo
(G:\My Drive\AI-Base\2-Projects\Personal-flare-altimeter\). Findings from a
work session go into every document they affect, in both places.
VSCode + PlatformIO, Arduino-ESP32 core 2.0.17.
pio run -e xiao -t upload # Seeed XIAO ESP32S3; no button press needed
pio device monitor -e xiao # console, 115200; press s for status
.\tools\viewer.ps1 # live view of attitude, range and alarm stateHost tests (149 in 8 suites), under WSL or any shell with g++:
bash tools/run_native_tests.sh # all suites
FLARE_FUZZ_N=20000 .pio/native_tests/test_pipeline # 20,000 randomized landings
bash tools/mutation_check.sh # do the tests notice a removed protection?
bash tools/make_docs.sh # redraw the diagrams in docs/imgAfter a fresh clone, run pio pkg install -e native once so the test script
finds Unity.
Two boards are supported, chosen by PlatformIO environment; the pin sets live
side by side in src/pins.h.
| Env | Board | Console | Role |
|---|---|---|---|
xiao |
Seeed XIAO ESP32S3 on the Seeed Grove Shield for XIAO | native USB CDC | the device |
esp32s3 |
ESP32-S3 N16R8 DevKitC-form clone | CH340K bridge | older bench board |
On the bench board, do not remove the qio_opi / default_16MB.csv / 16 MB
overrides in platformio.ini: the stock esp32-s3-devkitc-1
profile is the N8 no-PSRAM variant and the board faults at boot without them.
A serial port allows one reader. If an upload fails with Access is denied,
close the viewer or any pio device monitor holding the port.
lib/tf02 TF02-Pro frame parser, the range validity gate (host-testable)
lib/flare_math attitude and geometry maths (tilt correction) (host-testable)
lib/track is this height continuous with the one before it? (host-testable)
lib/height frame + attitude -> a height, or why there is none (host-testable)
lib/alert beep ladder, arming, changeover, auto-stop (host-testable)
lib/health readiness, and the ready / not-ready chimes (host-testable)
lib/flare_config validation of the persisted runtime settings (host-testable)
src/hw_* hardware layer: IMU, lidar, buzzer, console, diag
src/main.cpp wiring and the main loop
src/sim.* on-board descent simulator (synthetic height ramp into the alert engine)
test/test_* Unity tests: one per lib module, plus test_pipeline (end to end)
tools/ host-side viewer, mock descent generator, replay / test / docs scripts
docs/ the documentation, in English and Chinese, and its diagrams
The split is deliberate: everything that decides something lives in lib/
and does not include Arduino.h, so it compiles and runs on a desktop. Only
register writes and printf remain in src/.
- Code comments are bilingual: English first, then a fuller
// 中文说明:block for anything non-obvious (hardware quirks, timing constants, why a workaround exists). - The two documents in
docs/are kept in step: a change to one is a change to both. The landing and track-gate diagrams are generated from the real modules bytools/make_docs.sh, not drawn by hand. - One component per step on the bench: verify, then integrate.
- Contested design points: AI suggests, user decides.