Raw agent reports — firmware

Append-only. Source material for /dev-log/2026/MM/week_* digests after the Humaned filter pass.

2026-05-10 — TASK-FW-001 — Genesis / repo bootstrap

Status: done. Acceptance criteria 137 / 87 / 50 (targets ≥50 / ≥20 / ≥10) — comfortably over.

What got done:

1. Repo skeleton claudedrone-firmware/: README, ROADMAP, platformio.ini, .env_firmware, plus directories boards/, src/, parsers/, output_data/, sorted_data/, best_data/, experiments/, tests/, tools/.
2. Three external-knowledge parsers (idempotent, local PDF cache ~25 MB, gitignored):
   • Datasheet parser — PDF → pypdf → regex extraction over timing/registers/protocol sections.
   • GitHub issues parser — REST API without auth, filtered to closed issues only.
   • PlatformIO platforms parser — registry API → summary + per-version details.
3. Filters: sort.py routes items into topic folders by keyword; curate.py marks load-bearing material (for datasheets — all of them; for PlatformIO — latest + summary; for GitHub issues — strong signals like lockup / freeze / wdt / crash).
4. Three knowledge articles with code snippets and back-links to datasheet pages:
   • uart-timing.md — TF-Luna 9-byte frame (frame sync, checksum, common errors).
   • i2c-address-conflict.md — VL53L0X×6 via TCA9548A (three wiring options, lockup recovery, mutex).
   • esp32-watchdog.md — TWDT/IWDT configuration for cooperative scheduling, intentional-reboot policy.
5. UDP-spec v0.1 — frame layout for the future ESP32 ↔ simulation link (queued for the simulation handoff).

Five source-surprise findings (lifted into Datasheet pitfalls):

• ST.com refuses scripted access (HTTP/2 INTERNAL_ERROR from bot defense).
• The SparkFun VL53L0X mirror turned out to be misnamed — it actually contained the VL53L1X documentation (different sensor, different I²C protocol).
• The PixArt URL for the PMW3901 datasheet returns 404; a working mirror exists inside the esp-drone Espressif repository.
• The expected budryerson/TFmini_TFLuna_Light library is a 404; the real names are budryerson/TFLuna-I2C and TFMini-Plus as separate libraries.
• The 9-byte TF-Luna frame layout in the original CLAUDE.md instructions was stale: bytes 4-7 are Amp/Temp, not str/res/mode (the latter being a legacy from the older TFmini sensor).

Aleks’s principle: the agent is a technician, not a researcher. Parsers download everything-you-need-to-know about a sensor once; afterward the agent reads the cached material and writes code, instead of re-Googling the same datasheet every session.

Deferred: actual GitLab push (no origin remote yet — Aleks’s call).

2026-05-10 — TASK-FW-002 — TF-Luna UART driver

Status: in-progress (code is ready, hardware pending — ESP32 hasn’t arrived at D2 yet).

Approach: code-only (no hardware bring-up), 7 host-side unit tests — all green.

Artifacts:

• src/drivers/tf_luna/{tf_luna.h, tf_luna.cpp, README.md}.
• main.cpp skeleton — once flashed, will dump frames to the serial monitor immediately.
• 7 host tests (real packet / bad checksum / bad magic / low amplitude / overexposure / checksum formula / temperature).

Key decisions (full detail in TF-Luna driver and Host-testable Arduino pattern):

• Pure C++ functions plus an Arduino-class wrapper behind #if defined(ARDUINO) — unit tests compile the .cpp directly without mocking Serial.
• Frame sync via scan-for-magic (0x59 0x59); a partial sync drops one byte at a time rather than discarding the whole 9-byte chunk.
• UART RX buffer raised to 512 bytes (default is 256 — fills up in ~285 ms at 100 Hz frame rate).
• Health flag (valid=false when amp<100 or amp==0xFFFF) — the encoder can now distinguish blind (sensor reports invalid) from missed (frame never arrived) for diagnostics.

Two self-inflicted bugs (caught by tests):

• pio test -e native failed initially — test_build_src=no was blocking the linker. Fix: #include "../../src/drivers/tf_luna/tf_luna.cpp" directly in the test file. Ugly but compiles.
• The checksum-formula test had 0x8E instead of the correct 0xEE (paper-arithmetic mistake). The test caught it — ideal behavior, exactly why the unit tests exist.

PlatformIO Core 6.1.19 installed (pip install --user). ESP32-S3 toolchain deferred until hardware arrives (~5-10 min first-time fetch).

Next:

• When the ESP32 lands at D2: pio run -e esp32s3_devkit → --target upload → pio device monitor → six-step bring-up checklist (static-target measurements, amplitude check on shiny surfaces, 60 s stress test, connector-yank recovery, latency).
• In parallel, TASK-FW-003 (VL53L0X driver) can start in the same code-only mode — same patterns, but I²C + multiplexer instead of UART.

Aleks’s score: 9.0 (early read) + bronze medal.