From 4126a1040a1ece404aceb051d615e06fa7043c4f Mon Sep 17 00:00:00 2001 From: Ben Severns Date: Sun, 4 Jan 2026 23:33:42 -0600 Subject: [PATCH 1/2] Add first session quickstart guide --- README.md | 4 +++ docs/FirstSession.md | 69 +++++++++++++++++++++++++++++++++++++++++ docs/OSCSerialBridge.md | 4 +++ 3 files changed, 77 insertions(+) create mode 100644 docs/FirstSession.md diff --git a/README.md b/README.md index ee71909..a3413f5 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,10 @@ StringField explores the sensation of playing an “imaginary string” stretche Want the turnkey, print-and-go version? See [`docs/BuildKit.md`](docs/BuildKit.md) for the finalized BOM, wiring snapshots per sensor stack, flashing steps, calibration micro-rituals, and classroom handouts + first-play lesson plan. +## First Session + +Need the fastest “we’re alive” path? The first‑play ritual lives in [`docs/FirstSession.md`](docs/FirstSession.md). It’s a 10‑minute, no‑excuses script: connect hardware, flash firmware, open serial, run the bridge, fire up the visualizer, and paste a known‑good gesture packet to prove the loop. + ## Runtime note-set auditions (Serial preset browser) When you hear someone shout “try it in Hirajōshi!”, you no longer have to recompile. diff --git a/docs/FirstSession.md b/docs/FirstSession.md new file mode 100644 index 0000000..1b2607b --- /dev/null +++ b/docs/FirstSession.md @@ -0,0 +1,69 @@ +# First Session (from plug‑in to projector in ~10 minutes) + +You want the **fastest path to “it works”** without skipping the pedagogy. This is the first‑play ritual: a short, auditable chain from hardware → firmware → serial → bridge → visualizer. It’s written like a studio notebook, but it doubles as a teaching script you can read out loud. + +## 0. Pre‑flight (2 minutes, no heroics) + +- **Hardware on the table:** Sensor stack + Teensy/ESP32 board, USB cable, and whatever you’re using as the “string” (conductive tape, touch pad, ToF, etc.). +- **Software on the laptop:** PlatformIO + Processing installed. Keep it boring on purpose. +- **Why this matters:** You can’t teach sensor/gesture semantics if you’re still fighting drivers. + +## 1. Connect hardware (30 seconds) + +1. Plug the board into USB. +2. Connect the sensor stack per your build notes (or the default kit wiring in `docs/BuildKit.md`). +3. **Sanity check:** LEDs light, no smoke, no dangling ground. + +## 2. Flash the firmware (2 minutes) + +Pick the target you actually have in hand: + +- **Teensy 4.0:** `pio run -d firmware -e teensy40 -t upload` +- **ESP32‑S3 DevKitC:** `pio run -d firmware -e esp32s3 -t upload` + +If upload is clean, you’re already winning. If not, don’t panic—drivers and permissions are 90% of early friction. + +## 3. Open a serial monitor (1 minute) + +The firmware speaks JSON at **115200 baud**. Use whatever you like: + +- `pio device monitor -b 115200` +- Any serial terminal you trust. + +You should see boot chatter and JSON lines when you touch the sensor. + +## 4. Run the OSC/Serial bridge (2 minutes) + +1. Open `software/processing/OSCSerialBridge/OSCSerialBridge.pde` in Processing. +2. Hit **Run**. +3. Tap `n` if the wrong port is selected. + +You’re now mirroring gesture JSON to OSC and getting the classroom overlay. + +## 5. Open a visualizer (2 minutes) + +Pick your flavor: + +- **Processing:** `software/processing/StringFieldViz.pde` +- **p5.js:** `software/p5js/sketch.js` (if you want to run in a browser) + +Run it and keep it side‑by‑side with the bridge. The point is to make the system legible for the room. + +## Known‑good gesture packet (copy/paste test) + +If you want a guaranteed “does the pipeline even work?” probe, paste this single line into the serial monitor: + +```json +{"gesture":"pluck","value":96} +``` + +### Expected visual response + +- **State name:** `PLUCK` (uppercase in the visualizer ticker) +- **Velocity:** ~`96/127` ≈ `0.76` (you’ll see the velocity bar jump and the history cell print the numeric value) + +If the state name appears and the velocity jumps, the pipeline is alive. If not, check the serial port, baud rate, or whether the visualizer is listening to the right stream. + +## Next move (if you’re teaching) + +Once the room sees the overlay and hears the gesture in the synth, you can introduce **why** the mapping exists. That’s where the punk‑rock part kicks in: we’re not hiding the system, we’re showing it. diff --git a/docs/OSCSerialBridge.md b/docs/OSCSerialBridge.md index 43c8788..ee1a9e1 100644 --- a/docs/OSCSerialBridge.md +++ b/docs/OSCSerialBridge.md @@ -6,6 +6,10 @@ This bridge reads the firmware's JSON gesture packets over serial and forwards t - **OSC address:** `/stringfield/gesture` with `[gesture (string), value (0-127), normalized (0-1)]` - **Shortcuts:** `n` = rotate serial port, `p` = send OSC ping, `h` = print handout beats in the console +## If you only have 10 minutes + +Jump to [`docs/FirstSession.md`](FirstSession.md). It’s the fastest end‑to‑end ritual: plug in hardware, flash firmware, open serial, run this bridge, and bring up the visualizer with a known‑good packet so you can prove the pipeline before the class walks in. + ## Setup 1. Install Processing 4.x and add the **oscP5** library (Sketch → Import Library → Add Library → search "oscP5"). From 6ab53e5be600e45be283c797d306a2c01b104f80 Mon Sep 17 00:00:00 2001 From: Ben Severns Date: Sun, 4 Jan 2026 23:36:42 -0600 Subject: [PATCH 2/2] Format FirstSession doc --- docs/FirstSession.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/FirstSession.md b/docs/FirstSession.md index 1b2607b..3c33214 100644 --- a/docs/FirstSession.md +++ b/docs/FirstSession.md @@ -54,7 +54,7 @@ Run it and keep it side‑by‑side with the bridge. The point is to make the sy If you want a guaranteed “does the pipeline even work?” probe, paste this single line into the serial monitor: ```json -{"gesture":"pluck","value":96} +{ "gesture": "pluck", "value": 96 } ``` ### Expected visual response