菜单
Build, upload, and monitor firmware on the ESP32-C3. TRIGGER when the user asks to flash the device, check serial output, build firmware, set up OTA, or debug a build/upload failure. DO NOT trigger for host-side test runs (use /tdd) or for hardware wiring questions (use /hardware).
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
BNO085 sensor calibration and install-time boat-frame alignment (mount_quat). TRIGGER when the user asks about calibration, mount orientation, "which way is forward", drift, roll/pitch showing wrong values, or installing the sensor on the boat. DO NOT trigger for general BNO085 datasheet questions unrelated to calibration.
IMU and seastate domain reference — quaternions, reference frames, heave estimation, significant wave height, motion metrics that matter for sailing performance analysis. TRIGGER when the user asks what a metric means, why we capture a particular report, how seastate is characterized, or how IMU motion relates to polar performance. DO NOT trigger for BNO085 register-level or install questions (use /calibrate).
Hardware reference — BOM, ESP32-C3 pinout, BNO085 wiring, power, enclosure, mounting. TRIGGER when the user asks about wiring, pins, which connector, what board to buy, enclosure, physical install, or "can I use pin X for Y". DO NOT trigger for calibration math (use /calibrate) or firmware build issues (use /flash).
Pre-PR verification for imu4helmlog — host tests, device build, clang-format, docs, risk-tier-appropriate checks. TRIGGER when the user is about to open a PR, asks "am I ready to push", or wants a pre-merge review. DO NOT trigger mid-implementation; use /tdd during development.
Ingest protocol reference between the ESP32-C3 device and the helmlog server — schema, versioning, idempotency, endpoint contract. TRIGGER when adding fields to the sample payload, bumping the schema version, implementing the helmlog-side endpoint, or debugging an ingest round-trip. DO NOT trigger for BNO085 register-level questions (use /calibrate or /domain).
Test-driven development for firmware logic using PlatformIO's native env. TRIGGER when adding or changing code under lib/sampler/, lib/packetizer/, lib/ringbuf/, lib/config/, or any pure-logic C++ in this repo. DO NOT trigger for docs, platformio.ini, scripts, or hardware-only modules (lib/imu/, lib/net/, lib/uploader/) where behavior can't be exercised without a board.
| name | flash |
| description | Build, upload, and monitor firmware on the ESP32-C3. TRIGGER when the user asks to flash the device, check serial output, build firmware, set up OTA, or debug a build/upload failure. DO NOT trigger for host-side test runs (use /tdd) or for hardware wiring questions (use /hardware). |
platformio.ini defines two environments:
| Env | Target | Purpose |
|---|---|---|
esp32c3 | Seeed XIAO ESP32-C3 / DevKitM-1 | Real firmware |
native | Host (Mac) | Unit tests only — see /tdd |
Always specify -e explicitly. Forgetting it builds both and confuses errors.
pio run -e esp32c3 # compile only
pio run -e esp32c3 -v # verbose — use when link errors are obscure
A clean rebuild:
pio run -e esp32c3 -t clean && pio run -e esp32c3
ESP32-C3 has built-in USB-serial-JTAG. No DTR/RTS reset dance; esptool
triggers via USB CDC. Plug into the Mac's USB-C port directly.
pio run -e esp32c3 -t upload
If upload fails with Failed to connect:
ls /dev/tty.usbmodem* — the port must appearupload_speed = 460800 to platformio.inipio device monitor -b 115200
Exit: Ctrl-C then Ctrl-]. Or use pio device monitor --filter=esp32_exception_decoder
to get readable crash backtraces.
pio run -e esp32c3 -t buildfs # build the FS image from data/
pio run -e esp32c3 -t uploadfs # flash the FS image (wipes existing FS)
uploadfs is destructive — it erases any buffered batches stored on the
device. Don't run it on a unit that's been collecting data in the field
without first pulling the ring buffer contents via scripts/decode_capture.py
over serial.
After the device has been provisioned once, OTA is the preferred path — you don't want to climb to the mast to re-flash.
pio run -e esp32c3 -t upload --upload-port imu4.local
OTA requires the device to be on BigAir2.4 and reachable. If OTA is
unavailable (wifi down, firmware panicking in boot), fall back to USB.
ESP32-C3 panics print a register dump and a backtrace of PC addresses. The monitor filter decodes them against the ELF:
pio device monitor --filter=esp32_exception_decoder
If the filter isn't showing symbols, confirm the build on the device
matches the ELF at .pio/build/esp32c3/firmware.elf. A mismatch after
OTA means you're decoding against the wrong binary.
Serial.begin()
is missing or runs too late, you won't see early boot logs. Use
CORE_DEBUG_LEVEL=5 in platformio.ini for verbose core loggingmonitor_filters = esp32_exception_decoder in platformio.ini is
preferred over the CLI flag — it persists across invocations