# Stick 'Em Workshop — Build Your Own Robot App Welcome! In the next two hours you are going to dream up and build a **web app that controls a Stick 'Em build over Bluetooth**, straight from your laptop. No servers, no installs, no frameworks. Just a single HTML file you can vibe-code with your AI assistant. The output you build does **not** have to be a humanoid robot. It can be a snake, a flower, a giant eyeball, a cardboard cat — anything you can make move with up to 8 small motors. This document is your **starting kit**. Drop it into Claude Code (or Cursor, Windsurf, Copilot — whatever you use). Your AI assistant will read it, ask you a few questions about what you want to build, and then scaffold the project with you. **What is in this starter kit (two files):** 1. **This guide** (`Stick-Em-Workshop-Instructions.md`) tells your AI helper everything it needs. Give it this file first. 2. **`Humanoid-Robot-Example.html`** is a complete, working robot app in ONE file. Open it to see how a finished Stick 'Em app is built, then make your own. Works with any AI helper: Claude, Codex, DeepSeek, Copilot, Cursor, Gemini. Everything you build is a single `.html` file, so there is nothing to unzip and no folders to wire together. If your AI helper cannot open files (for example DeepSeek in the browser), just paste the text of this guide straight into the chat. --- ## ⚠️ Before You Start — Check Your Device **This is the most important thing on this page. Read it first.** Web Bluetooth, the technology your app will use to talk to the Stick 'Em board, **does not work on iPhones or iPads in Safari**. Apple has not added it. If you build your project planning to test on an iPhone at the end, it will not work and you will be sad. | Device | Will it work? | |---|---| | **Windows / Mac / Linux laptop in Chrome or Edge** | ✅ Yes, this is the easy path. Build here. | | **Android phone in Chrome** | ✅ Yes, works natively. | | **iPhone or iPad in Safari / Chrome / Firefox** | ❌ No. Web Bluetooth is blocked. | | **iPhone or iPad with the *Bluefy* app from the App Store** | ✅ Yes — *Bluefy* is a third-party browser that supports Web Bluetooth. Open your web page inside Bluefy. | **👉 Plan on developing and demoing on a laptop in Chrome.** If your project specifically wants the phone to be the controller, make sure your phone is Android — or be ready to install *Bluefy* on iPhone. When you start chatting with your AI assistant, **tell it which device you plan to use** before it writes any code. --- ## 🛠 How the Stick 'Em Motors Actually Work (read this — it surprises everyone) The motors in your Stick 'Em kit are **MG90S continuous rotation servos**. There are two things you must understand before you build: **1. They don't know what an angle is.** These motors have **no idea what "90 degrees" means.** Forget anything you have heard about servos having "positions." They cannot move to a specific angle, and there is no way to ask one where it is currently pointing. The only thing you can tell them is: > *"Spin this way at this speed, for this many milliseconds, then stop."* That's it. So if you want the motor to "turn a quarter turn," you instead say *"spin forward for about 400 milliseconds at medium speed,"* and you fiddle with the number until the physical movement looks about right. **2. No two motors behave identically.** Even between the *forward* and *backward* directions of the same motor, the speed is not the same. One direction will travel further in the same number of milliseconds than the other. Two different motors will be different again. This is normal for cheap motors. That is exactly why every project you build in this workshop comes with a **Servo Calibration Tool** baked into the bottom of the page — so you can nudge each motor until forward and backward look balanced. More on that further down. The two numbers you have control over for any motion are therefore: - **Speed**: how far the PWM value is from `1500`. `1500` means *stop*. `1700` is a moderate forward spin. `2000` is full speed forward. `1300` and `1000` are the same in the other direction. - **Duration**: how many milliseconds you keep that speed before stopping. To make a movement bigger, spin **longer** or **faster**. To get it more accurate, **tune the duration in small steps** until it matches what you want. > ⚠️ If you find yourself asking your AI assistant *"can you make it rotate 45 degrees?"* — stop. The motor cannot do that. Ask instead: *"can you spin it forward for about 300 ms at medium speed and let me tune it from there?"* --- ## What Do You Want to Build? This is the fun part. **You decide.** The Stick 'Em board exposes up to 8 motors over Bluetooth — that is your output. Anything in the browser can be your input: microphone, camera, mouse, keyboard, phone tilt, AI models, audio files, the time of day, the weather, whatever you can imagine. Take a few minutes to think before you start typing. A good project is **specific, simple, and weird**. "A snake that sways when I play music" is a better starting point than "an AI assistant." If you are stuck for inspiration, here are some directions other people have explored — but please **invent your own** instead of just picking one of these. - A **snake charmer** — play music or whistle and a servo-jointed snake sways with the rhythm. - A **sound-reactive flower** — each petal is a servo; music opens it, silence closes it. - A **giant watching eyeball** that pans and tilts to follow your face around the room. - A **sunflower tracker** — a cardboard sunflower that turns toward the brightest spot on the webcam. - An **eight-tentacle octopus** where each tentacle reacts to a different input (mic, mouse, hand, weather…). - A **lip-sync puppet** — speak into the mic and the puppet's mouth flaps in time with your voice. - A **paper face** that smiles, frowns, or raises an eyebrow when you do. - A **cardboard hand** that mirrors your real fingers via the webcam. - A **drumming pair of sticks** that beats in time with music in the room. - A **live audio equalizer** — eight motors as eight EQ bars, dancing to whatever's playing. - A **cardboard cat** whose paw swats at your mouse cursor on screen. - An **object follower** — a head or eye that tracks a coloured ball, fruit, or pet across the room. - A **phone-tilt steering rig** — tilt an Android phone, the build leans the same way. - A **morse-code tapper** — type a message, the motor taps it out on a desk. - A **magic 8-ball** — ask any question; an LLM picks the answer and a needle points at "yes / no / maybe". - A **hat-tipping gentleman** — a cardboard figure that tips its top hat whenever you say "thank you". - A **typing speedometer** — a needle that physically moves with how fast you type. - An **excitable pet** that dances when you type or play music, and droops in silence. - A **lonely plant** that slowly droops over time and perks back up when you talk to it. - A **cuckoo inbox** where a figure pops out every time a "notification" arrives. The point is: pick something you can describe in one sentence, and which you can build a first version of in **under an hour**. You can always make it weirder afterwards. --- ## How to Use This File 1. Open this file with your AI helper (Claude, Codex, DeepSeek, Copilot, Cursor...). 2. Ask it: *"Read this whole file, then help me build my own Stick 'Em app."* 3. The AI will **interview you**: what device, what idea, what build, how many motors, what skill level. **Answer honestly.** Saying "I don't know yet" is fine; the AI will help you narrow down. 4. Once your idea is clear, the AI builds you a single `.html` file. That one file IS your whole app. There are no other files to manage. 5. To test it, ask your AI helper: *"Please run this on a local web server and open it in Chrome."* It will do it for you. (Why a server? See Quick Setup below.) 6. Test on a real Stick 'Em board as early as possible. Real motors behave differently from your imagination. That is what the calibration tool at the bottom of your page is for. 7. Stuck for how it should look or move? Open `Humanoid-Robot-Example.html` and show it to your AI helper as a reference. --- ## Quick Setup **The easy way: ask your AI helper to run it for you.** Say *"run this on a local web server and open it in Chrome"* and it will handle everything below. Only read on if you want to do it by hand. Your app talks to the robot over Bluetooth. Browsers only allow that on a real website (`https`) or on your own computer's `localhost`. Opening the file by double-clicking it (a `file://` address) is blocked for safety. So you run a tiny local web server. Open a terminal in the folder with your `.html` file: ```bash # Mac / Linux python3 -m http.server 8000 # Windows (PowerShell or Command Prompt) python -m http.server 8000 # Or, with Node installed: npx serve . ``` Then visit **http://localhost:8000** in Chrome. **Not** `127.0.0.1`, **not** `file://`, **not** Safari. --- ## When Things Break - **"My Connect Board button does nothing."** → Make sure you are in Chrome / Edge, on `http://localhost`, not `file://`. iOS Safari will not work. - **"I clicked a button or triggered a movement, but the robot didn't move and nothing on the page looked broken."** → This was the #1 mystery in earlier workshops. The fix: look at the **Debug Log** panel at the bottom of your page (the scaffold mounts one automatically). Every command actually transmitted over Bluetooth shows up there with a timestamp. - **If you see the command listed in green** → the robot received it. The bug is physical: check wiring, check that the calibration speed isn't set so low the motor can't overcome friction, check the duration isn't a few milliseconds. - **If nothing shows up** → your event handler never called `sendServos` or `pulseServo`. Add a `console.log` to the start of your handler and check it actually fires. - **If you see a red `error:` line** → the BLE write failed, usually because the board just disconnected. Reconnect. - **"It connects but the motor does not move."** → Open the Chrome DevTools console (F12) and look for BLE write errors. Check your command string has a trailing comma. Check your PWM values are between 1000 and 2000. - **"The motor jitters or whines."** → You are sending values too fast or with too big a jump. Add smoothing. The starter scaffold caps sends at ~40Hz already. - **"It moves further forward than backward."** → That's the asymmetry. Open the Servo Calibration Tool at the bottom of your page and adjust the trim sliders until forward and backward match. - **"I asked it to move 90 degrees and nothing sensible happens."** → These motors don't know what degrees are. Tell your AI to spin the motor for a short burst of milliseconds and let you tune the duration by feel. - **"The motor suddenly stops responding."** → BLE disconnected. Reconnect. Cheap modules drop sometimes. The scaffold automatically re-sends the last command every 200 ms while connected, so brief drops normally self-heal once you reconnect. - **"I clicked Stop and the robot kept moving. I reloaded the page and it STILL kept moving. Only the physical reset button on the robot stopped it."** → This is the dangerous one. Two things have to be true for Stop to actually stop: 1. Your Stop button must send the literal string `stopAll,` — *not* `mv:1500:1500:...`. The latter says "drive all motors at PWM 1500" which depends on each motor's mechanical neutral; the former literally halts the PWM signal. 2. The firmware has no connection-loss watchdog — whatever command it last heard keeps running. So your page must fire one more `stopAll,` on `beforeunload` and `pagehide` (page reload, tab close), AND your Stop button should spam `stopAll,` 5× directly to the BLE characteristic (bypassing dedup) to guarantee at least one lands before the user closes the tab. The scaffold's `window.stickemPanicStop()` does this for you — call it instead of `stopAll()` from your Stop button. - **"The robot moves but reacts slowly / does the wrong thing for the current line/object position."** → You are flooding BLE with too-frequent writes and old commands are queued ahead of new ones. Apply all three: rate-limit BLE writes to **20 Hz max** (50 ms minimum interval), **EMA-smooth** your CV signal (`smoothed = smoothed * 0.6 + raw * 0.4`) before computing PWM, and **quantize PWM to multiples of 5** so sub-detectable adjustments don't generate new command strings. See pitfall §C in the AI section below for the technical why. - **`stopAll,`** is your friend. Wire a big red Stop button into your UI early. --- Have fun. The build is forgiving. Your code does not need to be elegant — it just needs to produce numbers between 1000 and 2000, hold them for a measured number of milliseconds, then stop. --- --- # 🤖 AI ASSISTANT — READ THIS WHOLE SECTION BEFORE WRITING ANY CODE The rest of this document is the technical spec for the AI coding assistant helping the workshop participant. Everything above this line was for the human; everything below is for you, the assistant. ## STEP 1 — Interview the User FIRST. Do Not Skip This. **Before you write a single line of code, ask the user the following questions, one at a time, in plain conversation.** Do not present them as a numbered list. Wait for an answer before moving to the next. 1. **What device are you developing on?** (Windows laptop / Mac / Linux / Android phone / iPad / iPhone.) → If iPhone or iPad: warn them that Safari does not support Web Bluetooth, point them at the *Bluefy* app on the App Store, and confirm they understand before continuing. If Windows / Mac / Linux: confirm they will use Chrome or Edge. 2. **In one sentence, what do you want to build?** → If they say "I don't know" or hand you a vague idea, **help them brainstorm**. Offer 2–3 specific, weird, achievable suggestions tied to whatever they seem interested in — but encourage them to land on something *they* invented. The output does **not** have to be a humanoid robot; remind them they can build a snake, a flower, a giant eyeball, a cardboard cat, an octopus, anything. **Once the idea is locked, immediately commit to a strong visual theme for the UI based on that idea — see Step 5. Do not default to a generic-looking page.** 3. **What is the input?** (Mic? Camera? Mouse / keyboard? Phone tilt? Typed text? An audio file? An AI model?) → If the answer involves a phone, double-check the phone is Android. 4. **How many motors are you using, and what does each one do on the physical build?** → This determines which servo slots (1–8) you send commands to. Write this down — the calibration tool you generate must include one card per motor they list here. 5. **Does the project need precise positioning** (e.g., "point at this exact spot," "rotate by a specific angle")? → If yes, **warn them**: these are **continuous rotation servos**. They do not know angles or absolute positions. The only thing you can control is *direction*, *speed* (PWM offset from 1500), and *duration* (in milliseconds). To get an approximate "position," they will pulse the motor for a calibrated duration and tune by trial and error. Ask if they are OK with that constraint; if not, help them reshape the project into something motion-based rather than position-based. 6. **What is their experience level?** (Never coded / some HTML / experienced dev / AI engineer.) → Adjust how much you explain. For beginners, keep the code in one file and over-comment. For experienced devs, skip the hand-holding. 7. **What does "done" look like for the next 90 minutes?** → Get them to commit to a v1 they can demo. They can always extend it after. Once you have answers, **summarise the project back to the user in 3–4 sentences and ask them to confirm** before you write code. If they want to change anything, iterate. Only start coding when they say "go". --- ## STEP 2 — Hardware Facts - The **Stick 'Em servo controller board** has **8 servo ports** (servo 1 through servo 8). - The board uses an HM-10 style **UART-over-BLE module**. - The motors are **MG90S continuous rotation servos**. **Critical:** - They are **NOT positional**. They cannot move to "an angle." - PWM = `1500` means **STOP**, not "centred position." - PWM > `1500` means **spin in one direction at a speed proportional to the offset from 1500**. So `1700` is a moderate forward spin; `2000` is full forward. - PWM < `1500` means **spin in the other direction**. `1300` moderate, `1000` full reverse. - The "amount" the motor turns is determined by **how long you hold the spin** in milliseconds. - Motors have **asymmetric behaviour**: forward speed and backward speed at the same PWM offset are usually different, and two motors on the same board will also differ. This is why every project must include the Servo Calibration Tool (Step 7). - Useful PWM offset range is usually `1300–1700` (gentler control); `1000` and `2000` are full-speed and can be too fast for delicate builds. Start gentle. - Servos are wired to whatever the participant built. **Ask** — do not assume servo 1 is "the head." **Do not use the word "degrees" or "angle" or "position" when describing servo movement in chat with the user or in code comments.** Talk about *direction*, *speed*, and *duration* in milliseconds. ## STEP 3 — BLE Protocol (exact spec — follow precisely) | Item | Value | |---|---| | BLE Service UUID | `0xFFE0` | | TX Characteristic UUID | `0xFFE1` (write only, no notifications) | | Device picker filter | `namePrefix: '⠀'` (Braille blank — only Stick 'Em boards include this) | | Fallback picker | `acceptAllDevices: true, optionalServices: [0xFFE0]` if the namePrefix filter fails on the user's OS Bluetooth stack | | Command encoding | UTF-8 text via `new TextEncoder().encode(cmd)` | | Send cadence | **~20 Hz max (50 ms minimum interval), with deduplication.** See pitfall §C below — higher cadences saturate the OS BLE stack and the robot processes stale commands instead of the latest one. | | Write concurrency | **Strictly one GATT write at a time.** Use a `writing` boolean guard. Overlapping writes will throw. | | Halt command | `stopAll,` — **the explicit firmware halt.** *Not* equivalent to `mv:1500:1500:...` See pitfall §A below. | | Disconnect behaviour | The firmware has **no connection-loss watchdog.** Whatever command was last received keeps running forever. See pitfall §B below. | ### Command Format Move command (mandatory trailing comma): ``` mv::::::::, ``` - Each `mN` is either an integer PWM value `1000–2000`, OR `-` to skip that slot (leaves the motor doing whatever it was doing). - `1500` = **stop spinning**. Other values = spin at a speed proportional to offset. - Trailing comma is a **firmware delimiter** and must always be present. Stop command: ``` stopAll, ``` ### Examples ``` mv:1500:1500:1500:1500:1500:1500:1500:1500, // all 8 motors stopped mv:1700:-:-:-:-:-:-:-, // motor 1 spins moderate forward; others untouched mv:1300:-:-:-:-:-:-:-, // motor 1 spins moderate reverse mv:1500:-:-:-:-:-:-:-, // motor 1 stop stopAll, // emergency stop / all idle ``` ### Buzzer Commands (piezo on the Stick 'Em board) Every Stick 'Em PCB has a piezo buzzer wired into the firmware. There are four buzzer commands, and **every numeric argument MUST be wrapped in the Scratch-block text form `{(num:{N})}`**. Bare integers (e.g. `playToneDuration:262:120:0`) fail the firmware's parser silently — the buzzer simply doesn't update and the previous tone stays stuck. The `bg` flag is a literal `{0}` or `{1}` (boolean-like, not number-typed). ``` playToneDuration:{(num:{})}:{(num:{})}:{}, // play a tone for ms milliseconds playTone:{(num:{})}:{(num:{})}:{}, // play a tone for beats beats at the current BPM setBPM:{(num:{})}, // set tempo used by playTone stopAllSounds, // silence the buzzer immediately ``` - `Hz` is the tone frequency. Audible piezo range is roughly 100–5000 Hz; below 80 Hz or above 8 kHz the buzzer is inaudible or unpleasant. - `bg` is `0` for **blocking** (firmware will not accept new commands until the tone finishes) or `1` for **background** (fire-and-forget; the firmware keeps accepting commands). For continuous-update apps like a theremin, use `bg=1` with overlapping durations so each new write overrides the previous tone smoothly. - `playTone` uses musical beats, scaled by whatever you last set via `setBPM:`. Default firmware BPM is 120. - The buzzer is a single-voice piezo — there is **no polyphony and no real volume control.** In speaker-mode (Web Audio) apps you get true amplitude control; on the piezo the right hand can only operate as an on/off gate. - **Multiple commands per write.** The firmware splits one BLE write at commas (at brace level 0 — braces nest!) and runs each piece as a sequential program on one parser task. Pack a stop+play pair as `stopAllSounds,playToneDuration:{(num:{440})}:{(num:{120})}:{1},` in ONE write so they execute as a unit; two separate writes spawn two parser tasks and can race. #### Examples ``` playToneDuration:{(num:{262})}:{(num:{1000})}:{0}, // C4 (262 Hz) for one second, blocking playToneDuration:{(num:{440})}:{(num:{120})}:{1}, // A4 background tone for 120 ms (good for theremin refresh) setBPM:{(num:{90})}, // slower tempo playTone:{(num:{523})}:{(num:{2})}:{1}, // C5 for two beats at 90 BPM, background stopAllSounds, // silence stopAllSounds,playToneDuration:{(num:{330})}:{(num:{150})}:{1}, // atomic pitch change in ONE write ``` #### Buzzer Recipes (real code you can lift) Pull these directly into your project. All four are wired up in the scaffold via `window.sendBuzzerTone`, `window.sendBuzzerStop`, etc. — never assemble the raw `playToneDuration:...` strings yourself. **Recipe 1 — One-shot "tick" beep (countdown timers, metronome, heartbeat).** Pair it with a `pulseServo` call for a synchronised tick. Use `background = true` so the firmware accepts the next tick without waiting for the previous tone to finish. ```js function tick() { if (!window.stickemIsConnected()) return; window.pulseServo(1, +1, 100); // 100 ms servo flick window.sendBuzzerTone(1000, 30, true); // 1 kHz beep for 30 ms, background } setInterval(tick, 1000); ``` **Recipe 2 — Continuous siren / alarm (timer expired, defuse-me, robot startled).** Re-fire the tone every ~480 ms so it overlaps with the previous 400 ms tone and the buzzer sounds continuous. Pair it with a continuous servo spin (`sendServos(2000, ...)` or `1000` for the other direction) to escalate the panic. ```js let alarmInterval = null; function startAlarm() { if (window.stickemIsConnected()) { window.sendServos(2000, null, null, null, null, null, null, null); // continuous spin } alarmInterval = setInterval(() => { if (window.stickemIsConnected()) window.sendBuzzerTone(1000, 400, true); }, 480); // 400 ms tone, fire every 480 ms — slight overlap = continuous siren } function stopAlarm() { if (alarmInterval) { clearInterval(alarmInterval); alarmInterval = null; } window.stopAll(); window.sendBuzzerStop(); } ``` **Recipe 3 — Pitched theremin / continuous-pitch instrument.** Use `sendBuzzerChangeTone(hz, ms, true)` — it's an atomic stop+play in ONE BLE write so the firmware doesn't spawn two parser tasks. Pick a `ms` slightly longer than your refresh rate so each new pitch overrides cleanly. ```js function setPitch(hz) { if (!window.stickemIsConnected()) return; window.sendBuzzerChangeTone(hz, 150, true); // 150 ms refresh, atomic } setInterval(() => setPitch(440 + Math.sin(performance.now()/200) * 200), 80); ``` **Recipe 4 — Musical beats (note runs, melodies, success/fail jingles).** Set a BPM, then send notes by beat count. Use blocking `bg=false` if you want a melody to play through cleanly without being interrupted. ```js function playSuccessJingle() { if (!window.stickemIsConnected()) return; window.sendBuzzerBPM(120); window.sendBuzzerNote(523, 0.5, false); // C5 for half a beat (250 ms at 120 BPM) window.sendBuzzerNote(659, 0.5, false); // E5 window.sendBuzzerNote(784, 1.0, false); // G5 for a full beat } ``` **Buzzer-only apps.** If your project doesn't drive motors (sound art, metronome, etc.), call this right after `stickemConnect()`: ```js window.stickemSetMotorKeepalive(false); // stops the 200 ms `mv:` keepalive so the buzzer gets the BLE channel ``` ### Disconnect Handling Attach a `gattserverdisconnected` listener on the BLE device object. On disconnect: set internal state to disconnected, change the page background to red, and show a Reconnect button. ### ⚠️ Pitfalls Discovered the Hard Way (bake all of these into the scaffold) These three patterns were learned by burning hours debugging real workshops. Every scaffold you generate must include all of them — they are not optional. **§A. Stop must send the literal string `stopAll,` — NEVER `mv:1500:...`** The firmware treats them differently. `stopAll,` halts the PWM signal entirely. `mv:1500:1500:...` says "drive every motor at PWM 1500" — which on continuous-rotation servos depends on each motor's mechanical neutral, and drifty motors will *creep slowly forever* at PWM 1500. So: ```js window.stopAll = function () { desired.fill(1500); // keep local state coherent pending = 'stopAll,'; // but actually halt the firmware }; ``` NOT this (it looks right and is subtly broken): ```js // WRONG — produces "mv:1500:1500:..." which is NOT a halt command: window.stopAll = function () { desired.fill(1500); rebuildPending(); }; ``` **§B. The firmware has no connection-loss watchdog — guarantee the LAST command is a stop** When the page reloads or the BLE channel drops, the firmware keeps executing whatever command it last heard. Forever. The only way to halt from JavaScript is to make sure the very last command on the wire before disconnect is `stopAll,`. The scaffold's normal send loop (25 ms dedup) is too lazy for this — by the time the next tick fires, the page is already closed. So: 1. Expose a `window.stickemPanicStop()` that writes `stopAll,` **directly** to `bleChar` 5× with 70 ms gaps, bypassing the dedup loop. This guarantees at least one lands even if a write is in flight or the page is unloading. 2. Wire BOTH `beforeunload` and `pagehide` to call `stickemPanicStop()`. Mobile Safari fires `pagehide` reliably; desktop Chrome fires `beforeunload`. Cover both. 3. Make the Stop button call `stickemPanicStop()`, not `stopAll()`. ```js async function panicStop() { desired.fill(1500); pending = 'stopAll,'; if (!bleChar || !connected) return; for (let i = 0; i < 5; i++) { // wait for any in-flight write to drain let waited = 0; while (writing && waited < 120) { await new Promise(r => setTimeout(r, 20)); waited += 20; } writing = true; try { await bleChar.writeValue(new TextEncoder().encode('stopAll,')); lastSent = 'stopAll,'; } catch (e) { /* log */ } finally { writing = false; } await new Promise(r => setTimeout(r, 70)); } } window.stickemPanicStop = panicStop; window.addEventListener('beforeunload', () => { try { panicStop(); } catch {} }); window.addEventListener('pagehide', () => { try { panicStop(); } catch {} }); ``` **§C. Rate-limit BLE writes to 20 Hz max, EMA-smooth CV signals, quantize PWM** The original scaffold cadence (`~40 Hz max`) was too aggressive. BLE acknowledged-write round-trips take 25-50 ms; hammering `writeValue()` faster than the peripheral can drain causes the OS BLE stack to queue commands. Symptoms: the robot appears to lag, or processes stale commands several hundred ms after the user moved a hand / line / face. The triple fix is non-negotiable for any project that derives motor commands from a continuous input (camera, mic, motion sensor): 1. **Rate limit in the scaffold**: 50 ms minimum interval between BLE writes (20 Hz cap). Tracked via `lastSendAt`: ```js const MIN_SEND_INTERVAL_MS = 50; setInterval(() => { if (!connected || writing || !pending) return; const now = Date.now(); if (now - lastSendAt < MIN_SEND_INTERVAL_MS) return; const due = now - lastForceMs >= 200; if (pending !== lastSent || due) { sendRaw(pending); lastSendAt = now; if (due) lastForceMs = now; } }, 25); ``` 2. **EMA-smooth the input signal** (in the project, not the scaffold) before deriving PWM. α between 0.3-0.5 is the sweet spot — kills frame-to-frame jitter with ~40-60 ms of effective lag, which servos can't even respond to faster than: ```js smoothedErr = smoothedErr * (1 - 0.4) + rawErr * 0.4; ``` 3. **Quantize PWM to multiples of 5** before calling `sendServos(...)` so identical-after-rounding commands dedup naturally: ```js const Q = 5; const leftPwm = Math.round((1500 + leftOffset) / Q) * Q; const rightPwm = Math.round((1500 + rightOffset) / Q) * Q; ``` Without all three, the BLE channel saturates with sub-detectable adjustments and the robot lags the input by hundreds of milliseconds. --- ## STEP 4 — Starter Scaffold (use this verbatim as your base) Build the project as a **single self-contained `index.html`** file. Start from this scaffold and extend it. The scaffold handles: - BLE connection + write guard + 40 Hz send loop - **Per-motor desired-state tracking** so rapid-fire commands never overwrite each other (this is the fix for the #1 workshop bug where "I clicked but the robot didn't move") - **200 ms keepalive** that re-sends the current motor state even when nothing changes, so a single dropped BLE packet does not freeze the build - A `window.sendServos(...)` function for continuous speed control - A `window.pulseServo(...)` helper for "spin for N ms then stop" actions, with per-direction calibration trim - `window.sendBuzzerTone(hz, ms, background)`, `sendBuzzerNote(hz, beats, background)`, `sendBuzzerBPM(bpm)`, `sendBuzzerStop()`, `sendBuzzerChangeTone(hz, ms, background)` (atomic stop+play in one BLE write), and the escape-hatch `sendBuzzerCommand(raw)` for driving the on-board piezo. All numeric args are auto-wrapped in the firmware's Scratch-block `{(num:{N})}` format. One-shots queue separately from motor commands so they cannot starve each other. - `window.stickemSetMotorKeepalive(false)` for buzzer-only apps that never call `sendServos` — silences the 200 ms `mv:` keepalive so buzzer commands have the BLE channel to themselves. - A `window.mountCalibrationTool(servoCount, container)` function that auto-generates the Servo Calibration Tool UI for however many motors the project uses - A **per-motor pulse lock** so the Calibration Tool's Test buttons fire even while the participant's project code is continuously calling `sendServos` every frame. When the project is "active," continuous control on a motor is paused for the duration of a calibration pulse, then resumes automatically. - A **visible Debug Log panel** at the bottom of the page that shows every command actually transmitted (or errored), with timestamps — so participants can immediately tell whether a missing movement was a BLE problem, an event-handler problem, or a wiring problem - `localStorage` persistence of calibration trims **You must keep all the scaffold below intact, and you must call `window.mountCalibrationTool(N, container)` at the end of your project code with `N` = the number of motors in the build.** ```html My Stick 'Em App

My Stick 'Em App

Not connected
🐞 Debug Log — live view of every command sent over Bluetooth
``` --- ## STEP 5 — UI/UX: Thematic, but Clear and Readable First **Two non-negotiables for the first draft:** 1. **It must look thematic.** Colours, central visual, background, and accent fonts all serve the project's world. Plain grey + `system-ui` is a fail. 2. **It must be immediately understandable.** Readable body text, obvious "what do I press next," and clear functional labels. Tacky decorative fonts on body text, illegible cursive scripts, and copy that hides what the button actually does are all fails. **The F1 console example is the bar.** Strong theme (carbon black, red, industrial dashboard), huge readable text, an obvious sequence of actions. Aim for that level of clarity in every project. The earlier Ouija and flower mock-ups were too tacky and the fonts were unreadable — that is what we are *not* doing. ### Typography Rules (read these carefully) - **Body text = always a clean, readable sans-serif.** Use `Inter`, `Manrope`, `DM Sans`, `Work Sans`, or `Nunito Sans` for the page body. Never use a cursive, dripping, gothic, or pixel-grunge font for body copy, button labels, status messages, or the calibration tool. Bad fonts for body text include `Creepster`, `Pirata One`, `Nosifer`, `Pacifico`, `Caveat`, `Press Start 2P`, `Bungee` — they're decorative only. - **Display / accent fonts are for the headline and the headline only.** Reserve thematic display fonts for the page title (`

`), the giant central visual's caption, and *maybe* the main call-to-action button if the font is still legible at button size. Test by reading the headline at arm's length — if you'd squint, switch to a sturdier display font (e.g., `Orbitron`, `Bebas Neue`, `Cinzel`, `Bowlby One`). - **Always set high contrast on text.** WCAG AA at minimum — light text on a dark themed background or vice versa. Use the browser's contrast eyedropper if in doubt. ### Recommended Theme Palettes & Fonts (these all keep readability) | Theme | Display font (headlines only) | Body font | Palette | |---|---|---|---| | F1 console / sci-fi cockpit | `Orbitron`, `Rajdhani` | `Inter`, `Manrope` | Black / carbon, neon red `#ef4444`, lime telemetry `#22c55e` | | Ouija board / séance | `Cinzel`, `IM Fell English SC` | `Inter` | Deep brown `#1a0f08`, parchment `#e8d9b8`, candle orange `#c2410c` | | Cute flower / pastel | `Fraunces`, `DM Serif Display` | `Nunito Sans`, `Manrope` | Sky blue `#bae6fd`, blush `#fda4af`, mint `#bbf7d0`, lavender `#ddd6fe` | | Robot dog | `Fredoka` (also OK for body if regular weight) | `Nunito Sans` | Tan `#d6b48a`, chocolate `#5b3a1d`, cream `#fff8ec` | | Snake charmer | `Cinzel`, `Yatra One` | `Inter` | Sand `#e7c89c`, terracotta `#c2410c`, deep teal `#134e4a` | | Eyeball / horror | `Cinzel` (in red), or `Bebas Neue` | `Inter` | Near-black, sclera off-white, vein-red `#dc2626` | | Rock drumming | `Bebas Neue`, `Bowlby One` | `Work Sans` | Spotlight yellow `#facc15` on black | ### Button Label Rule — Theme Word + Bracketed Action Every button label must communicate both the *flavour* and the *functional action*. Theme-only labels like "Summon the Spirits" are ambiguous — the user doesn't know if that connects, starts listening, or summons something else. Solve it by always appending the literal action in brackets: - **"Summon the Spirits (Connect)"** — Ouija connect button - **"Banish (Disconnect)"** — Ouija disconnect button - **"Bloom (Connect)"** — flower connect - **"Wilt (Stop)"** — flower stop - **"Engage Telemetry (Connect)"** — F1 - **"Pit In (Stop)"** — F1 emergency stop - **"Wake the Pup (Connect)"** — robot dog - **"Activate Servos (Start)"** — generic next-step after connect - **"Start Listening (Microphone)"** — voice projects Style the bracket in a smaller weight or lighter colour if you want, but it must be present and readable in the first draft. The same rule applies to switches and links. ### Progressive Disclosure & The Jiggle Breadcrumb (from humanoid.stickem.sg) The scaffold already includes everything you need to use the exact UX pattern from `humanoid.stickem.sg`. **Use it.** It is what makes the workshop's projects feel polished. How it works: 1. **The Connect button starts with `class="jiggle"`** — a gentle rotating shake animation. The participant's eye immediately knows where to start. 2. **When the participant clicks Connect and BLE pairs**, the scaffold fires its connect event. Your project listens with `window.stickemOnConnect(...)` and moves the jiggle to whatever the *next-step* button is (e.g., "Start Listening", "Start Camera", "Activate Servos"). 3. **When that next button is clicked**, you remove the jiggle by calling `window.setJiggleTarget(null)` — or pass another selector if there are *more* steps after it (e.g., RPS goes Connect → Start Camera → Throw). 4. **There must only ever be one button jiggling at a time.** `setJiggleTarget` strips `.jiggle` from any previously-animating button before adding it to the new one. So the participant's experience is: page loads with one shaking button → click → next shaking button → click → things start happening. Always *one* obvious thing to do next. What you write in your project code: ```html ``` ```js // After BLE pairs, the scaffold fires the connect event — move the jiggle onward. window.stickemOnConnect(() => window.setJiggleTarget('#activate')); // When the participant clicks the next button, stop the jiggle (or chain it to a third button). document.getElementById('activate').addEventListener('click', () => { window.setJiggleTarget(null); // …start the project loop… }); ``` For a multi-step flow (e.g. Connect → Start Camera → Throw), keep chaining: ```js window.stickemOnConnect(() => window.setJiggleTarget('#cam')); document.getElementById('cam').addEventListener('click', () => window.setJiggleTarget('#play')); document.getElementById('play').addEventListener('click', () => window.setJiggleTarget(null)); ``` The scaffold's CSS already declares the `@keyframes stickem-jiggle` and the `.jiggle` class. Do not redeclare them. Just use the API above. ### Background Colour Should Reflect State Mirror the humanoid.stickem.sg approach — the background colour itself communicates state at a glance: - **Not connected:** desaturated thematic background (e.g., a muted grey-brown for Ouija, dim charcoal for F1). The theme is *visible* but feels asleep. - **Connected:** full thematic colour. The page "lights up." - **Project actively running:** subtle accent (e.g., a glowing edge, a tinted vignette, a "REC" indicator). - **Unexpectedly disconnected:** background goes light red and the Reconnect button jiggles. ### Layout & Visual Hierarchy - **Make the central thematic visual huge** — an enormous emoji, inline SVG, or `` front and centre on first load. The user should see it the moment the page loads. - **Background must reinforce the theme** — a CSS gradient, an SVG pattern (e.g., `https://www.transparenttextures.com/`), a free Unsplash image (`https://images.unsplash.com/...`), or repeating thematic icons. **But do not let the background hurt the body text contrast** — a busy texture often needs a semi-transparent dark or light panel underneath the text. - **Group controls by purpose.** Connection controls top. Project controls middle. Calibration tool at the bottom (the scaffold already does this — leave it). - **Theme the Debug Log header copy** if you like (`Crystal Ball`, `Pit Crew Radio`, `Doggy Diary`) but **leave its monospaced dark styling alone**. It's a debug surface; legibility wins over theme. ### Concrete Implementation Pattern (drop into ``) ```html ``` ### Keyboard Shortcuts: Space, Escape, and Other Single-Key Triggers Every project that has a primary start/pause action **must** also accept the spacebar as that trigger, and every project that uses a fullscreen mode **must** accept `Escape` to exit. Single-key bindings are how presenters drive a Stick 'Em demo — they cannot click while holding the robot. **Mandatory bindings:** - `Space` → play / pause / stop the active alarm (one key, context-sensitive based on app state) - `Escape` → exit fullscreen if currently fullscreen **Optional but encouraged** for projects with a primary toggle (start / stop / record / fire): keep the spacebar as the shortcut even if you also add a button. **Drop this into every project's `