OpenBikeComputer documentation
A from-scratch bikepacking computer: offline vector maps in a custom binary format, GPX route navigation with live map-matching, and ride recording — with the firmware and a desktop simulator sharing one rendering path. These docs explain how it all fits together.
These pages are a conceptual companion to the code, not an API reference. The source is already documented in depth; what's hard to reconstruct by reading files one at a time is the shape of the thing — the pipelines, the boundaries, the why. That's what lives here.
obc-web-demo wasm host), and on the device — where live sensors feed the app the data the other hosts get from a GPX replay.The whole project is built around two ideas: compact binary formats a microcontroller can read directly off flash (no JSON, no reparsing, no heap churn), and a single rendering path the simulator and the firmware both run, so the desktop and the device can never drift apart.
Where to find what
Rendering pipeline
How one map frame is drawn — projection, level-of-detail, the quadtree cull, the stub-select collector, and the polygon/line rasterisers.
SoftwareSystem architecture
The crate graph, the per-frame loop, the "two hosts, one render path" model, and the seams that keep the device-specific bits at the edges.
SoftwareData formats
OBCM (maps) and OBCR (routes): why they're binary, the LOD pyramid, the quadtree index, and delta-encoded geometry.
SoftwareThe UI system
The screen stack, five gestures, render-on-demand, and the "adding a screen is a local edit" philosophy behind the on-device interface.
HardwareHardware
The reflective memory-LCD panel, the nRF54L microcontroller, schematic and PCB. coming soon
Building oneBuild guide
Bill of materials, the tools you'll need, flashing the firmware, and putting it together. coming soon
The stack at a glance
| Layer | Crate / file | What it does |
|---|---|---|
| Map packer | obc-pack | OSM .osm.pbf → .obcm (ingest, multipolygon assembly, quadtree build) |
| Map reader | obc-reader | Parses OBCM directly off bytes — header, styles, LOD table, quadtree, chunk decode |
| Route reader | obc-route | OBCR reading, GPX → OBCR conversion, map-matching, elevation profile |
| Renderer | obc-render | The shared draw path — projection, culling, rasterising. no_std, zero-alloc |
| Application | obc-app | Camera, screen stack, input model, ride tracking — one per-frame entry point |
| Simulator host | obc-sim | Desktop shell: window, control panel, colour policy, GPX replay, headless capture |
| Web demo host | obc-web-demo | The landing page's thin wasm host — same crates, a JS-driven frame loop, no GUI framework (shared host glue: obc-host-core) |
| Conversion bridge | obc-web-convert | The web builder's wasm shim over the same GPX ↔ OBCR routines — route conversion runs in the tab, no server |
New here? Start with System architecture for the lay of the land, then the Rendering pipeline. The data formats page is the reference the other two lean on.
A note on these docs
This documentation is open-source and lives in the repo. It's written by hand in Markdown with bespoke diagrams; if you spot something out of date with the code, the code is the source of truth — and a correction is always welcome.