Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
c1b5989
docs(specs): name every spec in lowercase kebab case
claude Oct 29, 2026
cb49869
docs(specs): give obcr-route.md the common spec header
claude Oct 29, 2026
65ad9c2
docs(specs): common header and trim for the TrailView specs
claude Oct 29, 2026
68b385d
docs(specs): common header and trim for the planner, route and Wikime…
claude Oct 29, 2026
78febd7
docs: common README structure for firmware and the iOS companion
claude Oct 29, 2026
9910be7
docs(specs): common header and trim for OBCA and OBCT
claude Oct 29, 2026
52884d4
docs(specs): common header and trim for obc-data.md
claude Oct 29, 2026
5c46b2d
docs: common README structure for host, tools, fixtures and data
claude Oct 29, 2026
68fb546
docs: trim the nRF54L board README
claude Oct 29, 2026
1998f46
docs(specs): common header and trim for OBCC, OBCU and the ride archive
claude Oct 29, 2026
4830749
docs(specs): common header and trim for OBCM
claude Oct 29, 2026
0b8a21a
docs(specs): common header and trim for the flat store and BLE specs
claude Oct 29, 2026
1a97367
docs(specs): add an index and the rules for writing a spec
claude Oct 29, 2026
a6e5c29
docs: common README structure for sim, builder and planner
claude Oct 29, 2026
5f378bc
tools: record the shrunk prose sizes in the baseline
claude Oct 29, 2026
edebd8e
docs(specs): make obc-data and the planner specs match the code
claude Oct 29, 2026
1f4e819
docs(specs): make the flat store, BLE and OBCU specs match the code
claude Oct 29, 2026
2428ba9
docs(specs): make the OBCM, OBCA, OBCT and OBCC specs match the code
claude Oct 29, 2026
df9dd32
docs: make the vectors, fixture, DEM and iOS-host docs match the code
claude Oct 29, 2026
c356f28
style: rustfmt the line that the spec rename made too long
claude Oct 29, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/bake.yml
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ name: Bake
# Publishing needs R2 credentials, which live in repository secrets and are only
# passed on an explicit `workflow_dispatch` with `publish: true`. A scheduled run
# bakes and reports; it never uploads. Content first, root last, is the publisher's
# own invariant (`OBCC_Spec.md` §11) and is enforced in `obc-bake`, not
# own invariant (`obcc-catalog.md` §11) and is enforced in `obc-bake`, not
# here — this file only decides *whether* to publish.

on:
Expand Down Expand Up @@ -81,7 +81,7 @@ env:
europe/germany/saarland

jobs:
# ── The mandatory re-bake guard (OBCC_Spec.md §10) ────────────────────────────────
# ── The mandatory re-bake guard (obcc-catalog.md §10) ────────────────────────────────
#
# Three mechanisms enforce "an OBCM bump invalidates every baked artifact". Two are
# in the repository and already exist: the generator refuses a mixed tree, and
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/deploy-site.yml
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ name: Deploy site
# only change by redeploying the site, which is exactly what #905 says a fresh bake
# must not require. So the manifest lives **with the artifacts**, on whatever object
# storage the bakery (B1 #898) publishes to, where its cache policy is that host's
# to set (OBCC_Spec.md §11 states the ≤ 60 s expectation).
# to set (obcc-catalog.md §11 states the ≤ 60 s expectation).
#
# 2. **No cross-origin isolation, ever, on this host.** Setting
# `Cross-Origin-Opener-Policy: same-origin` + `Cross-Origin-Embedder-Policy:
Expand Down
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -138,7 +138,8 @@ This is the current direction, not a release schedule.

The hardware build uses the Nordic nRF54LM20 development kit and a Sharp LS021B7DD02 240 × 320
reflective memory LCD. It reads maps and routes from microSD and connects to the companion software
over BLE and USB. The custom PCB and enclosure are still under development. KiCad sources can be found in the repository, CAD sources for the enclosure will be made available later.
over BLE and USB. The custom PCB and enclosure are still under development. KiCad sources are in
[`hardware/`](hardware/README.md); CAD sources for the enclosure follow later.

## Repository layout

Expand Down
101 changes: 45 additions & 56 deletions builder/desktop/README.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,11 @@
# obc-desktop

The website's cell-catalog map builder, shipped in a Tauri v2 window. The Svelte coverage UI,
digest verification, corridor selection and wasm assembly engine are the same in both products.
Rust supplies native HTTPS, durable map-set output, USB and the ride library; it does not link
The website's cell-catalog map builder in a Tauri v2 window. The Svelte coverage UI, digest
verification, corridor selection and wasm assembly engine are the same in both products. Rust
supplies native HTTPS, durable map-set output, USB and the ride library; it does not link
`obc-pack` and it does not process `.osm.pbf` files.

The architecture and the map pipeline are in the public docs. This file is the desktop build, run
and platform reference.

## Requirements
## Setup

| | |
|---|---|
Expand All @@ -18,6 +15,15 @@ and platform reference.

No GEOS, CMake, libusb or Python dependency. `nusb` talks to each platform's native USB stack.

USB on macOS and Windows needs no extra setup. On Linux:

```sh
sudo cp linux/99-openbikecomputer.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger
# unplug and reconnect the device
```

## Build and run

Build the two wasm bridges and the desktop frontend first, then run the standalone Rust crate:
Expand Down Expand Up @@ -45,31 +51,30 @@ cargo run --no-default-features

Packaged builds compile their catalog root from `OBC_CATALOG_URL`, which defaults to
`https://maps.openbikecomputer.com/cell-catalog/catalog.json`. A runtime variable of the same name
overrides it for testing an unpublished catalog:
overrides it to test an unpublished catalog:

```sh
OBC_CATALOG_URL=https://maps.example.test/catalog.json cargo run --release
```

The catalog root, every satellite and every cell are fetched through Rust. Object URLs must use
the configured root's HTTPS origin, with loopback HTTP allowed for local testing, so the webview
is never handed a general network proxy.
Rust fetches the catalog root, every satellite and every cell. Object URLs must use the configured
root's HTTPS origin; loopback HTTP is allowed for local testing. The webview never gets a general
network proxy.

## Basemap

The region picker, ride library and route previews draw the same basemap from
`tiles.openbikecomputer.com`. Each map reads the active release from
`https://maps.openbikecomputer.com/planner/catalog.json` when it opens.

The basemap needs WebGL2 and shows detail only within the published tile coverage. If it cannot
load, the map shows a notice and keeps the selection or route overlays. It sends no tile requests
to a third-party map server.
`https://maps.openbikecomputer.com/planner/catalog.json` when it opens. The basemap needs WebGL2
and shows detail only within the published tile coverage. If it cannot load, the map shows a
notice and keeps the selection or route overlays. It sends no tile requests to a third-party map
server.

The webview loads tiles, fonts and symbols itself. The Content Security Policy in
`tauri.conf.json` names the two hosts. The asset host must list the app origin in its CORS rules:
`tauri://localhost` on macOS and Linux, `http://tauri.localhost` on Windows.

## Checks
## Test

This is a standalone cargo root, like `obc-fw-nrf54l` and `obc-boot`, so it needs its own checks:

Expand All @@ -82,32 +87,33 @@ cargo test --release --locked -- --nocapture

The shared Svelte checks run from `builder/web`: `npm run check`, `npm test`, `npm run build:all`.

## Linux release-launch test
### Linux release-launch test

The manual suite `manual.desktop-linux-launch` opens the real window under Xvfb, checks its
`tauri://localhost` origin, searches for Switzerland and adds it to the map, against a loopback
catalog. CI does not run it. To run it on a Linux host with no OBC device attached, build the
release app first, then from the repository root:
catalog. CI does not run it. On a Linux host with no OBC device attached, build the release app
first, then from the repository root:

```sh
sudo apt-get install webkit2gtk-driver xvfb imagemagick dbus-daemon
cargo install tauri-driver --version 2.0.6 --locked
xvfb-run -a dbus-run-session -- uv run --locked --group desktop-e2e python builder/desktop/e2e/launch.py
```

**Use a WebKit driver with the same version as the installed WebKitGTK runtime.** `dbus-run-session` gives the app and the
desktop portal services a private session bus with the Xvfb display.
**Use a WebKit driver with the same version as the installed WebKitGTK runtime.**
`dbus-run-session` gives the app and the desktop portal services a private session bus with the
Xvfb display.

`OBC_DESKTOP_BINARY` names an existing release executable. Evidence goes to
`target/desktop-launch`, or `OBC_DESKTOP_EVIDENCE`: `result.json`, native catalog request logs,
application and driver logs, rendered HTML and a screenshot, plus `failure.png` when a webview
session is available.

This suite covers Linux software launch and catalog integration only. It establishes no USB
permission, no enumeration with a physical device and no route upload. Windows launch is not
automated, and Tauri's native WebDriver route does not support macOS.
The suite covers Linux software launch and catalog integration only: no USB permission, no
enumeration with a physical device and no route upload. Windows launch is not automated, and
Tauri's native WebDriver route does not support macOS.

## Files and storage
## Reference

| | |
|---|---|
Expand All @@ -117,14 +123,10 @@ automated, and Tauri's native WebDriver route does not support macOS.

Each completed assembly is a uniquely named folder. Files are written to `.part`, flushed and
atomically renamed before the assembly is reported complete. The website gets the same
worker-produced bytes through browser downloads.

The visible ride folder holds GPX files only; device ride objects and the index live in the
internal archive, and `src/rides.rs` documents the durable import and relocation rules. Catalog
cells are held only for the assembly run: there is no `.pbf`, land-polygon, Geofabrik-index or
persistent cell cache.

## Layout
worker-produced bytes through browser downloads. The visible ride folder holds GPX files only;
device ride objects and the index live in the internal archive, and `src/rides.rs` documents the
durable import and relocation rules. Catalog cells are held only for the assembly run: there is no
`.pbf`, land-polygon, Geofabrik-index or persistent cell cache.

| | |
|---|---|
Expand All @@ -135,27 +137,14 @@ persistent cell cache.
| `src/rides.rs` | Managed GPX library plus the durable ride archive |
| `src/usb/` | Native USB discovery and byte pipes beneath the shared TypeScript protocol |

The window is granted `core:default` and no filesystem, shell or HTTP plugin; those policies live
in Rust commands. `dragDropEnabled: false` in `tauri.conf.json` turns off Tauri's OS-level
interception so the shared HTML5 GPX drop targets get files normally.

## USB permissions

macOS and Windows need no extra setup. On Linux:

```sh
sudo cp linux/99-openbikecomputer.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger
# unplug and reconnect the device
```

The device protocol stays the shared TypeScript implementation in `builder/web/src/lib/usb/`;
Rust supplies the native pipes only. Large app-owned files stream straight from the maps folder
without entering the webview. A newly assembled volume set streams to the device with the manifest
last, and the device page also accepts a standalone `.obcm` obtained elsewhere.
The window has `core:default` and no filesystem, shell or HTTP plugin; Rust commands hold those
policies. `dragDropEnabled: false` in `tauri.conf.json` turns off Tauri's OS-level interception so
the shared HTML5 GPX drop targets get files.

## Not here yet
The device protocol is the shared TypeScript implementation in `builder/web/src/lib/usb/`; Rust
supplies the native pipes only. Large app-owned files stream from the maps folder without entering
the webview. A newly assembled volume set streams to the device with the manifest last. The device
page also accepts a standalone `.obcm` from elsewhere.

Installers, signing and auto-update. A native arbitrary-file picker is not exposed; files selected
in the webview use the ordinary chunked transfer path.
There are no installers, signing or auto-update. There is no native arbitrary-file picker; files
selected in the webview use the ordinary chunked transfer path.
2 changes: 1 addition & 1 deletion builder/presets/skins/default.json
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
"#55AA55",
"#AAAAAA"
],
"skin_note": "Presentation only. Every feature type and every style id comes from `schema.json` and is referenced by the feature headers of every baked chunk (OBCM_Spec.md §5.2), so a skin may restate the presentation values in the style record and nothing else — the catalog generator refuses one that adds, drops, reorders or renumbers a feature type (OBCC_Spec.md §5). The values below are the schema's own, which is what makes this the default look; `min_lod`, the LOD ladder, the merge passes and the routing profiles are schema data and are deliberately absent."
"skin_note": "Presentation only. Every feature type and every style id comes from `schema.json` and is referenced by the feature headers of every baked chunk (obcm-map.md §5.2), so a skin may restate the presentation values in the style record and nothing else — the catalog generator refuses one that adds, drops, reorders or renumbers a feature type (obcc-catalog.md §5). The values below are the schema's own, which is what makes this the default look; `min_lod`, the LOD ladder, the merge passes and the routing profiles are schema data and are deliberately absent."
},
"features": {
"highway": {
Expand Down
2 changes: 1 addition & 1 deletion builder/presets/skins/dusk.json
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
"#005500",
"#AAAAAA"
],
"skin_note": "Presentation only, same rules as `default.json` (OBCC_Spec.md §5). The night inversion of the schema's field-guide look (epic #1016 §4): the cream paper becomes black ground, big fills go dark (deep-blue water, forest green, olive fields, a navy town lift), and everything a rider follows stays light — the warm through-road ramp is kept verbatim from the day skin because deep orange and amber already read on black, local streets drop from white to grey so a town grid does not glare, tracks lift from brown to tan, cycleways from indigo to light violet. Rail keeps its day values: black dashes on a grey base read as a grey dashed line on black ground with no edit at all. Buildings are dark grey — the quietest mark that still exists on plain black ground (a town without mapped landuse, e.g. central Monaco, would swallow black buildings whole). Every value lands exactly on the panel's RGB222 grid (4 levels/channel: 0/85/170/255) and every pair meant to differ occupies a distinct bucket; the catalog tests assert both. One more rule this document obeys deliberately: the bake merges features whose *schema* styles render identically (obc-pack's merge_fills/merge_lines retag merged geometry to one canonical style id), so feature types the schema merges — {unclassified, residential}, {service, pedestrian}, {drain, ditch}, {wood, forest}, {bare_rock, scree, shingle}, the grass family, the built-up landuse family — are restated with identical values here: a skin that split them would style only the canonical id's share of the merged geometry."
"skin_note": "Presentation only, same rules as `default.json` (obcc-catalog.md §5). The night inversion of the schema's field-guide look (epic #1016 §4): the cream paper becomes black ground, big fills go dark (deep-blue water, forest green, olive fields, a navy town lift), and everything a rider follows stays light — the warm through-road ramp is kept verbatim from the day skin because deep orange and amber already read on black, local streets drop from white to grey so a town grid does not glare, tracks lift from brown to tan, cycleways from indigo to light violet. Rail keeps its day values: black dashes on a grey base read as a grey dashed line on black ground with no edit at all. Buildings are dark grey — the quietest mark that still exists on plain black ground (a town without mapped landuse, e.g. central Monaco, would swallow black buildings whole). Every value lands exactly on the panel's RGB222 grid (4 levels/channel: 0/85/170/255) and every pair meant to differ occupies a distinct bucket; the catalog tests assert both. One more rule this document obeys deliberately: the bake merges features whose *schema* styles render identically (obc-pack's merge_fills/merge_lines retag merged geometry to one canonical style id), so feature types the schema merges — {unclassified, residential}, {service, pedestrian}, {drain, ditch}, {wood, forest}, {bare_rock, scree, shingle}, the grass family, the built-up landuse family — are restated with identical values here: a skin that split them would style only the canonical id's share of the merged geometry."
},
"features": {
"highway": {
Expand Down
15 changes: 6 additions & 9 deletions builder/tests/corpus/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# obc-pack test fixtures

Hand-authored OSM extracts for the `host/obc-pack` packer tests, whose ingest outcome is known by
Hand-authored OSM extracts for the `host/obc-pack` packer tests. Each ingest outcome is known by
construction.

| Fixture | What it pins | Test |
Expand All @@ -14,16 +14,13 @@ construction.
`area=yes` or an area tag, and never when it carries `area=no`. Relations are always areas. So a
closed `highway=residential` loop is a line and not also a filled blob.

## Rebuild the `.pbf` files
## Build

```sh
./build_corpus.sh
```

It converts each source to `data/*.osm.pbf` with `osmium cat`. **The derived `.pbf` files are
committed too, and the tests hard-fail without them**, so re-run the script and commit the
regenerated `.pbf` whenever a source `.osm` changes.

This script is the last thing in the tree that wants `osmium-tool` (`brew install osmium-tool`),
and only as an XML-to-PBF converter. Nothing here packs a map, and the packer itself needs no
osmium.
The script converts each source to `data/*.osm.pbf` with `osmium cat`. It needs `osmium-tool`
(`brew install osmium-tool`) only as an XML-to-PBF converter; the packer needs no osmium.
**The derived `.pbf` files are committed too, and the tests hard-fail without them**, so re-run the
script and commit the regenerated `.pbf` whenever a source `.osm` changes.
2 changes: 1 addition & 1 deletion builder/web/src/lib/catalog/manifest.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
// The cell catalog root: one schema, the skins, the named regions, and the pins on
// the per-band cell indices. Normative in `OBCC_Spec.md`, produced by
// the per-band cell indices. Normative in `obcc-catalog.md`, produced by
// `obc-pack catalog` / `obc-bake`.
//
// This takes a *string* because a document is read whole and parsed as one JSON
Expand Down
2 changes: 1 addition & 1 deletion builder/web/src/lib/firmware/obcu.ts
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ const OBCU_SIG_SCHEME_ED25519 = 1;
/** Bytes of the Ed25519 signature trailer. */
export const OBCU_SIG_LEN = 64;

/** The device's whole application slot (`obc_dfu::MAX_IMAGE_LEN`, `OBCU_Spec.md` 1.1). */
/** The device's whole application slot (`obc_dfu::MAX_IMAGE_LEN`, `obcu-update.md` 1.1). */
const OBCU_MAX_IMAGE_LEN = 2_023_424;

const MAGIC = 0x4f424355; // "OBCU"
Expand Down
Loading
Loading