Impulse docs¶
Every long-form document in the workspace, in one tree, inside the Obsidian vault at ~/Impulse/vault/docs/ — so the specs are browsable and linkable next to the daily logs and the launch tracking. The code repos keep only their own README.md; each file below is the real file, and a symlink at its original in-repo path points here, so existing links and any [spec §5.4]-style references still resolve from inside a repo.
Nothing here is version-controlled. The vault is not a git repo and neither is the workspace root, so every document in this tree exists in exactly one place, on one disk.
specs/ — normative. Read these before changing behaviour.¶
| Doc | Covers | Authority |
|---|---|---|
| firmware_spec_v2.md | Watch and anchor both, on ESP32-C3. §4 anchor, §5 watch, §6 wire formats, §7 constants, §9 commitment integrity, §10-A proximity roadmap. | The reconciled-against-code source, and the only spec describing firmware that exists. Wins over every other document. |
| firmware_spec_v3_nrf.md | The nRF54LM20A / Zephyr port. Platform, pin map, channel sounding, the port plan. 📋 nothing built. | Authoritative for the nRF build where it speaks; its §0.2 inherits the MCU-independent chapters from v2 by reference rather than restating them. Read both. |
| proximity_engine_spec_v2.1.md | Engine physics, phase map, §13 threat model, the math behind the verdict. | Wins on why; the firmware spec wins on wire formats and constants. |
| MOBILE_APP_SPEC.md | The Flutter app, including the GATT contract from the app's side. | Authoritative for the app. |
| CALIBRATION_V2_DESIGN.md | Per-anchor demonstrated-zone calibration (INSIDE/EDGE + FINALIZE). | Authoritative for calibration. |
| impulse_overview.md | Product framing, voice, what the thing is for. | Authoritative for copy and positioning. |
Status markers. firmware_spec_v2.md marks every proximity-v2 block ✅ shipped / 🟡 partly shipped / 📋 planned. Honour them — several sections describe wire formats that do not exist on any device (the proximity vector is still the v0.8 [count][N×8] layout). A parser written against a 📋 block will not work.
When code and spec disagree, the code is the fact and the spec is the bug — fix the spec in the same change, and update §0.1's parity table and §0.2's change log, which is what §0 asks for.
hardware-notes/ — measurements and spike write-ups¶
| Doc | What it settles |
|---|---|
| prox_v2_spikes.md | Feasibility spikes S1–S6 and their results. |
| spike_s1a_txlo.md | The TX-power sweep that set BEACON_TX_LO_DBM. |
| prox_v2_p1_notes.md | Where Phase 1 deliberately deviated from the spec, and why. Read before "correcting" the engine. |
| version_bump.md | The toolchain-bump spike: why the watch stays on IDF 4.4.7. Self-contained handoff. |
| battlog_usage.md | Invoking ImpulseFirmware/dump_battlog.py. |
| cs_ranging_how_it_works.md | How the watch and anchor range each other today, end to end: discovery, link setup, CS config, estimation, bursts, verdicts, lost-link rule, measured rates and open defects. |
| cs_tuning_plan.md | Channel Sounding: what is settled and what still needs measuring. CS works and ifft is accurate to ±0.20 m after one constant. Read before tuning any proximity constant. |
marketing/ — the website's non-code content¶
marketing_strategy.md · launch-plan.md · content-push.md · kickstarter-page.md · launch_video_draft.md · website_issues.md · email-capture-setup.md
archive/ — superseded. Not authoritative. Do not cite.¶
Kept for provenance only. Every one of these has a live replacement:
| Archived | Superseded by |
|---|---|
firmware_spec_v0.9_amendment.md |
Merged into specs/firmware_spec_v2.md at v0.10. It had drifted from the code — see that file's v0.10 change-log entry for the specific stale values. |
new_prox_engine_spec.md |
Engine spec v1.0 → specs/proximity_engine_spec_v2.1.md. |
firmware_spec_v0.1_draft.md |
Early draft → specs/firmware_spec_v2.md. |
app_spec_v0.3_draft.md |
Early draft → specs/MOBILE_APP_SPEC.md. |
website_firmware_spec_v2.md |
Stale 1441-line copy of the 2400-line real spec. |
website_impulse_overview.md |
Stale copy of specs/impulse_overview.md. |
Not here, on purpose¶
Repo README.md files stay in their repos — they orient you inside a codebase and are the best writing in this project. Start with the one for whatever you're touching:
WatchFirmware ·
AnchorFirmware ·
proximity_engine ·
impulse_app ·
phone_sim
Directory-local READMEs (proximity_engine/corpus/, bench/pdr_sweep/) also stay put.