Skip to content

Add onboarding & gesture docs, sensor field notes, and improve optical sensor normalization - #18

Merged
bseverns merged 2 commits into
mainfrom
codex/document-project-structure-and-overview
Jan 6, 2026
Merged

bseverns merged 2 commits into
mainfrom
codex/document-project-structure-and-overview

Conversation

@bseverns

@bseverns bseverns commented Jan 5, 2026

Copy link
Copy Markdown
Owner

Motivation

  • Provide a concise, teachable onboarding path so new collaborators can run and teach the full pipeline in a single session.
  • Make the gesture heuristics narratable and tied to firmware knobs so instructors can tune and explain behavior live.
  • Expand sensor front‑ends from terse stubs into readable field notes that are classroom‑friendly and actionable.
  • Improve the optical front‑end so the normalization and baseline behavior is robust and narratable in noisy/low‑contrast rooms.

Description

  • Add docs/Onboarding90Min.md with a 90‑minute workshop syllabus that walks hardware → firmware → visualizer.
  • Add docs/GestureVocabulary.md linking human‑readable gesture rules to the exact knobs in firmware/include/gesture_engine.h.
  • Add sensor field notes docs/Sensors/OpticalReflective.md and docs/Sensors/CapacitiveSingleWire.md, plus update docs/Sensors/README.md, docs/SensingSurvey.md, and top‑level README.md to include the new pages.
  • Enhance firmware/src/optical_sensor.cpp to track an ambient floor, subtract it before normalization, apply a small gain, and smooth the resulting envelope (ambient_floor_, gain_, env_), making the front‑end more stable and easier to teach.

Testing

  • No automated tests were run on these changes.
  • Changes are primarily documentation plus a small sensor front‑end tweak; recommended automated checks are pio test -d firmware -e native for gesture unit tests and building the firmware targets for CI validation.

Codex Task

@bseverns
bseverns merged commit 2deb9b4 into main Jan 6, 2026
8 checks passed
@bseverns
bseverns deleted the codex/document-project-structure-and-overview branch January 6, 2026 04:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant