--- marp: true paginate: true --- # Building on the Kilter Board ## A developer's tutorial: from the Aurora API to lighting up the wall --- ## Building on the Kilter Board - A hands-on developer tutorial - API • data model • BLE control - Rangle.io --- ## What is the Kilter Board? - A modular LED training wall for climbers - Holds at fixed positions; LEDs mark a 'climb' - Driven by a mobile app + cloud (Aurora Climbing platform) - Thousands of community-created, graded climbs --- ## Why build on it? - Custom training dashboards & analytics - Alternative climb browsers and filters - Logging, projecting, and progress tracking - Fun: control the wall from your own code --- ## What we'll build today - Authenticate against the Aurora/Kilter API - Sync the climb + hold database locally - Decode and render a climb - Send a climb to a real board over Bluetooth --- ## Prerequisites & tooling - Comfortable with HTTP/REST and JSON - Python 3.11+ (examples) or your language of choice - SQLite + an HTTP client (requests/httpx) - For BLE: a Bluetooth adapter + bleak (or Web Bluetooth) --- ## Ecosystem at a glance - Mobile app → talks to Aurora cloud over HTTPS - Cloud → stores users, climbs, holds, ascents - App → talks to board over Bluetooth LE - Board → just lights LEDs from a packet --- ## The Aurora data model - One shared schema across Aurora boards - Core tables: climbs, holds, placements, sets, products - 'product' = a board layout/size variant - Everything keyed by stable UUID/int ids --- ## Key vocabulary - Hold: a physical grip on the wall - Placement: a hold mounted at a coordinate on a product - Climb: an ordered set of lit placements (a route) - Frame: the compact string encoding a climb's holds --- ## Setting up the project - Create a virtualenv and install deps - `pip install requests bleak` - Project layout: api.py, sync.py, render.py, board.py - Keep credentials in env vars, never in code --- ## Talking to the API - Base URL: https://kilterboardapp.com/... - JSON over HTTPS, mobile-app style endpoints - Two endpoints do most of the work: login + sync - Inspect traffic with a proxy if unsure --- ## Authentication flow - POST username + password to the sign-in endpoint - Receive a session token + user id - Send token on subsequent requests - Tokens are long-lived — cache them --- ## Login — code - resp = requests.post(f'{BASE}/sessions', json={'username':U,'password':P}) - token = resp.json()['session']['token'] - user_id = resp.json()['session']['user_id'] - Store token + user_id for reuse --- ## The sync endpoint - One endpoint returns deltas across many tables - POST a map of table -> last synced timestamp - Server returns only rows newer than your watermark - Empty watermarks = full initial download --- ## Understanding the sync tables - users, climbs, climb_stats, ascents - holds, placements, sets, products, product_sizes - Each row carries a 'last updated' timestamp - You mirror exactly what the app caches --- ## A local SQLite mirror - Create tables matching the sync payload - Upsert rows by primary key - Persist per-table sync watermarks in a meta table - Now you can query offline, fast --- ## Your first sync — code - body = {'client':{'enforces_product_passwords':1}, 'GET':{'query':{'syncs':marks}}} - data = requests.post(f'{BASE}/sync', json=body, headers=auth).json() - for table, rows in data['PUT'].items(): upsert(table, rows) - save_watermarks(data['PUT'].get('shared_syncs')) --- ## Anatomy of a climb record - uuid, name, setter, description - layout_id / product references - angle (board tilt) lives in climb_stats - frames: the encoded hold list --- ## Decoding the frames string - Format: pNNNNNrMM repeated, no separators - 'p' + placement_id, 'r' + role_id - Split on 'p', then on 'r' - Yields (placement_id, role_id) pairs --- ## Mapping placements to holds — code - import re - pairs = re.findall(r'p(\d+)r(\d+)', frames) - for pid, role in pairs: hold = placements[int(pid)] - x, y = hold['x'], hold['y'] --- ## Hold roles & colors - Start holds (green) - Hand/intermediate holds (blue) - Foot holds (orange/yellow) - Finish holds (purple/magenta) --- ## Rendering a climb - Use placement x/y as image coordinates - Draw a circle per lit hold in its role color - Overlay on a board background image - Great sanity check before touching hardware --- ## Querying climbs locally — code - SELECT c.uuid, c.name, s.difficulty, s.angle - FROM climbs c JOIN climb_stats s ON s.climb_uuid = c.uuid - WHERE s.angle = 40 - ORDER BY s.quality_average DESC --- ## Filtering by grade & angle - difficulty is a numeric grade ladder - Map difficulty -> V-scale / font via a lookup table - Angle changes the grade — always filter on both - Quality + ascent counts help rank results --- ## Going physical: BLE - Board advertises as a BLE peripheral - Find it by name prefix, connect, discover services - Write LED data to a specific characteristic - No pairing PIN — just connect and write --- ## The LED packet protocol - Build a byte stream of (position, r, g, b) entries - Wrap with header + checksum bytes - Split into ~20-byte BLE chunks with markers - Board reassembles and lights the holds --- ## Sending a climb to the board — code - leds = [(pos_for(pid), color_for(role)) for pid,role in pairs] - packets = encode_ble(leds) # framing + chunking - async with BleakClient(addr) as c: - for p in packets: await c.write_gatt_char(CHAR_UUID, p) --- ## Putting it together: the mini client - login() → sync() → store locally - search() climbs by grade/angle - render(climb) to verify - send(climb) to the board --- ## Error handling & rate limits - Handle 401 → re-authenticate and retry once - Back off on 429 / network errors - Don't hammer sync — respect watermarks - Validate frames before rendering --- ## Caching & offline strategy - First run: full sync (can be large) - Subsequent runs: tiny delta syncs - Cache token + watermarks on disk - App works fully offline after first sync --- ## Gotchas & lessons learned - API is unofficial — expect occasional changes - Angle-specific grades trip people up - BLE MTU/chunking bugs are the #1 hardware issue - Always look up colors/grades from synced tables --- ## Resources & community - Open-source clients on GitHub (boardlib & friends) - Aurora schema notes from the community - Climbing-dev forums and Discords - Read responsibly — it's an unofficial API --- ## Recap & next steps - You can auth, sync, decode, render, and light up - Next: build a training log or recommender - Try Web Bluetooth for a browser version - Go build something — and share it

Revisions — Building on the Kilter Board