Bike Playground

Overview

Bike Playground is a four-surface webapp built for live events. Riders pedal a stationary bike; their cadence (RPM) drives a fullscreen p5.js sketch on a projector while a separate operator dashboard runs the show.

The four surfaces

Three audiences in one app

Each surface is a distinct UX. The operator is in a noisy venue, one hand free, making decisions in seconds — their UI is dense, glanceable, and live. The display is an installation, not a webpage — fullscreen, no chrome, branded. The studio is a creative coding IDE — for sketch authors at a focused desk.

Architecture

Where the bike data actually flows

The bike's microcontroller speaks USB-serial — even though the physical cable is USB, the protocol on the wire is the old serial standard. The browser reads this directly via the Web Serial API. The server does not talk to the bike; it never has. The operator's Chrome tab owns the serial port, reads RPM 5–20 times per second, smooths the signal, and forwards each tick to the server over WebSocket. The server's job is purely fanout — it rebroadcasts every bike:rpm message to every connected display, plus any future operator/admin tabs.

Roles

Every WebSocket client registers as one of three roles. The server uses the role to route messages — operator commands flow to displays, ride results flow to operators, RPM goes to everyone.

Server modules

Client modules

Quick Start

Local development

npm install
npm start
# Setup:   http://127.0.0.1:3000/setup
# Display: http://127.0.0.1:3000/display
# Studio:  http://127.0.0.1:3000/studio

The Setup page on http://127.0.0.1:3000/setup is the operator dashboard. The Display page on http://127.0.0.1:3000/display is what gets projected. Both tabs talk to the same WebSocket server.

Production (Cloudflare)

The live build is on Cloudflare Pages at bpe-bike-playground.pages.dev. Git push to main auto-deploys via the Pages git integration. Real-time fanout runs on Cloudflare Durable Objects; session storage is D1. See the team's deployment notes for details.

Event-day operator checklist

1. Plug the bike into the operator laptop via USB.
2. Open Chrome (must be Chromium-based — Web Serial doesn't work in Firefox or Safari).
3. Navigate to the Setup page. If the "Connect Bike" modal opens automatically, click Choose Device and pick the bike from Chrome's permission prompt, then Connect.
4. Confirm the sidebar LIVE RPM updates as you spin the pedal.
5. Click + Code in the header to generate a fresh BIKE-XXXX access code.
6. On the display PC, open the same site's /display URL. Enter the access code. Pick a sketch.
7. Read the code aloud to anyone else who needs display access (rider phones, secondary projectors).

Sketch API Reference

Every sketch runs with two globals available: bike (or bikes[] for multi-bike) and params. They're injected by sketch-loader.js before setup() runs.

The bike object

The params object

Live parameter store. Initially populated from the sketch's config.json defaults. The operator can change values from the Setup page's Params modal — updates arrive via WebSocket and overwrite keys on this object between frames. The sketch picks up the new value on the next draw() call without any subscription needed.

// config.json declares "speed" with default 72
// Operator drags the slider to 90
// Next frame:
console.log(params.speed); // 90

Read defensively in case a parameter is missing:

const speed = params.speed ?? 72;

Multi-bike sketches

For sketches that take input from two bikes (Tug of War, Versus Bars, Race Track):

Single-player sketches that only read bike keep working — bike aliases bikes[0]. The v2 WebSocket contract carries a bikeId field on every bike:rpm message, so multi-bike grows additively as hardware support lands.

Reference sketch

/**
 * @sketch     speed-rings
 * @category   particles
 * @idle       Single faint ring, slow drift
 * @cruise     8 concentric rings, hue shifts with RPM
 * @sprint     Rings flash and expand outward at 120+ RPM
 */

let displayRpm = 0;

function setup() {
  createCanvas(windowWidth, windowHeight);
  colorMode(HSB, 360, 100, 100, 100);
}

function draw() {
  // 1. Smooth the noisy raw signal.
  displayRpm += (bike.rpm - displayRpm) * 0.08;

  // 2. Background: never pure black on projectors.
  background('#04040e');
  // (Use a low-alpha background for a trail effect.)

  // 3. Map RPM to visual parameters — never multiply raw RPM.
  const numRings = Math.floor(map(displayRpm, 0, 160, 1, params.maxRings ?? 12));
  const hue      = map(displayRpm, 0, 160, 200, 360);

  stroke(hue, 80, 100);
  noFill();
  strokeWeight(2);

  for (let i = 0; i < numRings; i++) {
    const r = map(i, 0, numRings, 20, min(width, height) * 0.45);
    ellipse(width / 2, height / 2, r * 2, r * 2);
  }

  // 4. Sprint state — explicit qualitative shift.
  if (displayRpm > 120) {
    fill(0, 0, 100, 20);
    rect(0, 0, width, height);  // brief flash overlay
  }
}

function windowResized() {
  resizeCanvas(windowWidth, windowHeight);
}

Writing Sketches

Sketches live in sketches/. Each is a folder with sketch.js + config.json. The server discovers them on demand — no manifest to update.

Step-by-step: add a sketch

1. Pick a folder name (lowercase, hyphen-separated). This becomes the sketch's slug in the API.
2. Create sketches/<slug>/sketch.js. Write the @sketch header comment first (see Aesthetic Brief for the convention) — describe what idle, cruise, and sprint should look like before you write code.
3. Create sketches/<slug>/config.json. Declare parameters the operator should be able to tune (see below).
4. Optionally add thumbnail.png for the sketch picker.
5. Restart the server (or just reload the page if the server's already running — sketches are scanned per request).

The contract every sketch must hit

Every sketch responds to three named states:

Non-negotiables

• Smooth the RPM signal on every frame: displayRpm += (bike.rpm - displayRpm) * 0.08;
• Background is never pure black. Use #04040e — pure black reads as off-state on projectors.
• Map, don't multiply. speed = map(rpm, 0, 160, minSpeed, maxSpeed), never rpm * constant.
• No internet dependencies. Sketches load assets from their own folder or bundled libraries. No CDN.
• Frame rate target: 60fps at 1920×1080. Profile on actual hardware (Pi 5, Intel NUC, Mac mini).
• Reset cleanly on sketch switch. background() every frame.

Sketch Configuration

A sketch's config.json declares its name, category, tier, and the parameters the operator can tune at runtime. The server normalizes two shapes — the new array form (preferred) and the legacy object form (still works).

config.json — preferred (array) form

{
  "name":     "Warp Stars",
  "description": "Hyperspace starfield. Pedal faster for warp.",
  "category": "particles",
  "tier":     "flagship",
  "hue":      220,
  "parameters": [
    { "name": "speed",   "label": "Speed",        "type": "range",  "default": 72,  "min": 0,  "max": 100 },
    { "name": "density", "label": "Star Density", "type": "range",  "default": 200, "min": 50, "max": 500 },
    { "name": "color",   "label": "Color Mode",   "type": "select", "default": "auto", "options": ["auto", "brand", "mono"] }
  ]
}

Top-level fields

Parameter types

Legacy (object) form — still supported

Older sketches declare parameters keyed by name with type: "number". The server adapter converts them on read — no migration required.

{
  "parameters": {
    "starCount": { "type": "number", "default": 800, "min": 200, "max": 2000 },
    "color":     { "type": "select", "default": "white", "options": ["white", "blue", "rainbow"] }
  }
}

type: "number" maps to type: "range". Both array and object forms produce the same UI.

Sprint & Sessions

A "ride" is a timed sprint with a recorded score. The operator clicks START RIDE on the Setup page; the Display overlays a countdown, runs a 20-second sprint, shows an end card with the rider's score and rank, then returns to the running sketch. The result is persisted to the leaderboard for that deployment.

The lifecycle

Score formula

Default scoring is W·s (watt-seconds). Each second of the sprint, the overlay smooths the rider's RPM, multiplies by 2.2 to estimate watts, and adds that to a running total. Peak watts and average watts are recorded separately. The score formula is configurable per deployment via ride.scoreFormula.

Sprint configuration (deployment-level)

"ride": {
  "durationSeconds": 20,    // length of the sprint
  "warmupSeconds":   3,     // countdown length
  "scoreFormula":    "watts" // currently only "watts" is implemented
}

Operator HUD during a sprint

The Setup page's sidebar still shows live RPM the whole time. The sparkline records the sprint. The right-panel preview iframe shows the actual display HUD. The operator can hit BLACKOUT at any time to cut the display to black (display:blackout WS message) — useful during speeches, glitches, or kids crying.

Sessions storage

Each completed sprint appends one JSON line to deployments/<id>/sessions.jsonl (local mode) or to the equivalent D1 row (cloud mode):

{"name":"Alex","score":5120,"peakWatts":287,"avgWatts":256,"duration":20,"sketch":"warp-stars","timestamp":"2026-05-21T19:14:32.412Z"}

Leaderboard API

Retention

The retention field in deployment.json controls how long sessions stick around. A sweep runs at server startup:

Deployment Profiles

A deployment is a per-event configuration bundle: event name, client branding, allowed sketches, ride settings, retention. Lives in deployments/<id>/deployment.json.

v2 schema

{
  "name":   "Default",
  "event":  "Acme Wellness Day 2026",
  "client": "Acme Corporation",
  "venue":  "HQ Atrium — Building 3",
  "date":   "2026-05-20",

  "branding": {
    "logo":       "assets/acme-logo.svg",
    "primary":    "#1A3A8F",
    "accent":     "#E8402A",
    "onDark":     "#F4F2EE",
    "footerText": "Acme Corp Wellness Day 2026"
  },

  "sketches": ["kaleidoscope", "warp-stars", "aurora-borealis"],

  "ride": {
    "durationSeconds": 20,
    "scoreFormula":    "watts",
    "warmupSeconds":   3
  },

  "features": {
    "leaderboard": true,
    "requireName": true,
    "prize":       false,
    "qr":          true,
    "qrUrl":       "bike.local/leaderboard",
    "blackout":    true
  },

  "accessCode": {
    "duration": "8h"
  },

  "retention": "24h"
}

Fields

Switching deployments

The active deployment is set via the BPE_DEPLOYMENT environment variable. Defaults to default. To run a different event:

BPE_DEPLOYMENT=acme-wellness npm start

Per-deployment overrides (per-sketch parameter defaults different from the sketch's own config.json) live under an optional overrides key — see server/deployments.js.

Branding System

The deployment's branding block drives visual identity across every surface: logo, primary color, accent, on-dark text color, footer text. branding.js fetches the deployment from the API and applies it two ways — as CSS custom properties on :root, and by filling DOM elements marked with data-brand attributes.

How a logo + color reaches the screen

CSS custom properties

Any page can use these — they're set on :root as soon as branding.js fetches the deployment:

DOM slots

Any element with a data-brand attribute gets populated automatically:

<img data-brand="logo" alt="Logo">
<span data-brand="event-name">Bike Playground</span>
<span data-brand="client"></span>
<span data-brand="footer-text"></span>
<span data-brand="qr-url"></span>

Wiring branding into a new page

<!-- in your HTML -->
<script src="/js/branding.js"></script>

<!-- in your CSS -->
.btn-primary { background: var(--brand-primary, #4d7fff); }

The fallback in var(...) is what's shown before branding.js finishes its fetch, or if the deployment doesn't override that token.

Reacting to branding from JS

branding.js dispatches a branding:applied event on window once branding lands. The Display page listens for this to know when it's safe to instantiate the Sprint Overlay (which needs the deployment object for QR URL + sprint duration):

window.addEventListener('branding:applied', ({ detail }) => {
  overlay = new SprintOverlay({ bike, deployment: detail.deployment, onEnd: ... });
});

WebSocket Message Contract

Every real-time message in v2 flows through one WebSocket per client. Each message is a JSON object with a type field. The server routes by type and the sender's registered role.

Direction legend

C → S client to server (a tab sends to the server)
S → C server to client (server broadcasts to clients)
both client sends, server relays

Connection lifecycle

Bike data

Ride lifecycle

Display control

Hardware Setup

The bike → laptop connection

The bike's microcontroller plugs into the operator's laptop via USB. Even though the cable is USB, the microcontroller presents itself to the operating system as a serial port — a stream of bytes, framed as newline-delimited JSON. This is an old, stable convention that USB-to-serial chips have supported for decades.

The browser reaches that data through the Web Serial API. There is no native serial reader on the server. Everything goes through the operator's Chrome tab.

Browser requirements

• Chromium-based browser only. Chrome, Edge, Brave, Arc — all work. Firefox and Safari do not implement Web Serial.
• Secure context required. Must be https:// or http://127.0.0.1. Reaching the dev server via localhost is silently redirected to 127.0.0.1 so the permission grant sticks.
• Permission is per-device. Chrome remembers the user's choice and re-uses it on subsequent visits.

The Connect Bike flow (operator UI)

The Setup page opens the Connect Bike modal automatically if the bike isn't yet detected. The modal preserves the five-button serial flow that handles every edge case Chrome's API throws:

1. Choose Device — opens Chrome's native picker. The operator selects the bike (usually labeled something like "BPLED" or by USB vendor ID).
2. Connect — opens a serial connection to the previously-chosen device.
3. Scan All — when an authorized device is already remembered, tries each one until one matches the BPLED data pattern. Useful when the laptop has been to many events.
4. Disconnect — closes the active connection. Lets another tab claim the port.
5. Refresh — re-queries Chrome for the list of currently-authorized devices.
6. Simulator slider — drives RPM by hand. Use this for demos without hardware.

Serial protocol

The microcontroller emits one JSON line per reading at 9600 baud:

{"rpm": 75}
{"rpm": 82}
{"rpm": 0}
{"rpm": 65, "watts": 120, "distance": 1.4}

Any additional fields pass through as bike.raw. bike-client.js handles partial lines, occasional garbled bytes, and reconnection silently.

Hardware reality check

• Target hardware for the display PC is Pi 5 or x86 (Intel NUC, Mac mini). 3D and WebGL sketches run fine on this class of machine.
• The operator laptop just needs Chrome and a USB port. Any modern laptop works.
• The display PC does not need to be on the same network as the operator — once they're both pointed at the live site, the WebSocket handles the connection over the internet.

Access Codes

Access codes gate the Display page. They're a practical barrier, not cryptographic security — they prevent random people on the network from opening /display mid-event.

Format

BIKE-XXXX where XXXX is four random digits. Examples: BIKE-7294, BIKE-0182.

• Case-insensitive. bike-7294 works.
• Time-limited. Expires after the deployment's accessCode.duration. Default 8 hours.
• One active at a time per deployment. Generating a new code invalidates the previous one.
• Memory only. Server restart wipes all codes. Generate fresh ones after a restart.

Operator workflow

1. Open the Setup page on the operator laptop.
2. Click + Code in the header.
3. A code appears (BIKE-XXXX).
4. Read the code aloud to anyone who needs Display access (projector PC, secondary screens, rider phones).
5. If the code expires mid-event, generate a fresh one and repeat.

API

Troubleshooting