When the firmware agent builds a knowledge bank automatically (parsers fetch datasheet PDFs, filter by timing/registers/protocol sections), repeating sources of error surface. This list comes from the real TASK-FW-001 bootstrap experience.
Surprise 1 — ST.com refuses scripts
All three VL53L0X PDFs (datasheet, UM2039, AN4846) from official st.com — timeout or HTTP/2 INTERNAL_ERROR. A script client is seen as unwanted.
Fix: mirrors. SparkFun / Pololu / Adafruit often publish the same PDFs themselves.
Surprise 2 — The SparkFun mirror was garbage
Downloaded cdn.sparkfun.com/.../VL53L0X_DS.pdf — inside was VL53L1X, a different sensor. Pin-compatible, but 4 m range instead of 2 and different timing budget. If I hadn’t checked page one, the driver would have used the wrong parameters.
Lesson: verify the PDF by the signature on page one, don’t trust the filename. Pololu (pololu.com/file/0J1187/vl53l0x.pdf) turned out to be the real DocID029104 from ST.
Surprise 3 — PixArt URL is dead
The PMW3901 datasheet was listed as pixart.com/uploads/PMW3901MB-TXQT_DS_R1.01...pdf — HTTP 404.
Where I found it: Espressif’s esp-drone repo hosts an official mirror — even a newer revision R1.10 instead of R1.01.
Surprise 4 — GitHub repo renamed
The original CLAUDE.md had budryerson/TFmini_TFLuna_Light — also 404. The real names:
budryerson/TFLuna-I2C(I2C mode)budryerson/TFMini-Plus(UART of the same family)
Lesson: don’t trust old links in command-documentation; add both variants to sources_inventory.json.
Surprise 5 — TF-Luna 9-byte frame fields were stale
In the original docs: [0x59 0x59 dist_L dist_H str_L str_H res mode checksum] — legacy from the older TFmini.
The real frame for A03 (our version) — bytes 4-7 are Amp_L Amp_H Temp_L Temp_H (signal amplitude + temperature), not str/res/mode.
Where to verify: Appendix I in the Benewake datasheet. Five minutes of reading saved a future bug in the driver. Also corrected in the UDP spec: range_down_str → range_down_amp, added temp_down_raw.
General source rule
- Every PDF — open it, read page one, verify against expectations.
- Every link in command-documentation — verify with curl before use.
- Store datasheets locally, in
output_data/datasheets/(gitignored, 25 MB cap), with asources_inventory.jsonentry —{url, mirror_url, doc_id, sha256, last_verified}. - Validate mirrors not by filename but by DocID / part of page one.