diff --git a/.github/workflows/bake.yml b/.github/workflows/bake.yml index 81e7c5b4f3..c16686dd6e 100644 --- a/.github/workflows/bake.yml +++ b/.github/workflows/bake.yml @@ -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: @@ -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 diff --git a/.github/workflows/deploy-site.yml b/.github/workflows/deploy-site.yml index d0e215f494..8e8dd3a0db 100644 --- a/.github/workflows/deploy-site.yml +++ b/.github/workflows/deploy-site.yml @@ -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: diff --git a/README.md b/README.md index d09de9d8dd..2213d4cbac 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/builder/desktop/README.md b/builder/desktop/README.md index 8e0249573c..3e75854ea8 100644 --- a/builder/desktop/README.md +++ b/builder/desktop/README.md @@ -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 | | | |---|---| @@ -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: @@ -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: @@ -82,12 +87,12 @@ 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 @@ -95,19 +100,20 @@ 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 | | | |---|---| @@ -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. | | | |---|---| @@ -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. diff --git a/builder/presets/skins/default.json b/builder/presets/skins/default.json index 5246ee2906..80f12c4ab6 100644 --- a/builder/presets/skins/default.json +++ b/builder/presets/skins/default.json @@ -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": { diff --git a/builder/presets/skins/dusk.json b/builder/presets/skins/dusk.json index 55bb76e156..05b178e230 100644 --- a/builder/presets/skins/dusk.json +++ b/builder/presets/skins/dusk.json @@ -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": { diff --git a/builder/tests/corpus/README.md b/builder/tests/corpus/README.md index 2c98f4bb21..7f5dbd1819 100644 --- a/builder/tests/corpus/README.md +++ b/builder/tests/corpus/README.md @@ -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 | @@ -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. diff --git a/builder/web/src/lib/catalog/manifest.ts b/builder/web/src/lib/catalog/manifest.ts index 56e63e54dd..4d6de963bc 100644 --- a/builder/web/src/lib/catalog/manifest.ts +++ b/builder/web/src/lib/catalog/manifest.ts @@ -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 diff --git a/builder/web/src/lib/firmware/obcu.ts b/builder/web/src/lib/firmware/obcu.ts index 0d13b668db..22cd1159c1 100644 --- a/builder/web/src/lib/firmware/obcu.ts +++ b/builder/web/src/lib/firmware/obcu.ts @@ -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" diff --git a/builder/web/src/lib/trailview/README.md b/builder/web/src/lib/trailview/README.md index 6dacc3c428..d483efa10e 100644 --- a/builder/web/src/lib/trailview/README.md +++ b/builder/web/src/lib/trailview/README.md @@ -1,9 +1,10 @@ # TrailView -TrailView is the 3D view of the planner: TypeScript, raw WebGPU and WGSL, no framework. The page is `builder/web/trailview.html`. The terrain streams with LOD from -the master terrain tiles: zooms 0 to 12 from the tile service, zoom 13 from its packs. The ground -look comes from the TrailView layers of the release ([specs/trailview-tiles.md](../../../../../specs/trailview-tiles.md)) -and the planner's snow tiles. +The 3D view of the planner: TypeScript, raw WebGPU and WGSL, no framework. The page is +`builder/web/trailview.html`. The terrain streams with LOD from the master terrain tiles: zooms 0 +to 12 from the tile service, zoom 13 from its packs. The ground comes from the TrailView layers of +the release ([specs/trailview-tiles.md](../../../../../specs/trailview-tiles.md)) and the planner's +snow tiles. ## Build and run @@ -15,9 +16,9 @@ VITE_PLANNER_CATALOG=URL npm run dev -- --mode trailview # open /trailview.htm npm run build:trailview # dist/trailview ``` -The page reads the `active` entry of the planner catalogue, or `VITE_PLANNER_CONFIG`. The ground needs -`trailview_rules` and the `trailview-*` archives in `layers` of the entry; without them the ground -is the palette of the `world` region. +The page reads the `active` entry of the planner catalogue, or `VITE_PLANNER_CONFIG`. The ground +needs `trailview_rules` and the `trailview-*` archives in `layers` of the entry; without them it is +the palette of the `world` region. ## Layout @@ -63,8 +64,9 @@ The HUD lists the keys; Ctrl+C and Ctrl+V copy and paste the view as an address. ## Labs A lab is an entry in `LABS` of `labs.ts`, with its variants and the default first; `?lab=` selects -one. The HUD has a menu per lab, which loads the page again at the same view. The terrain has no lab: CDLOD by distance, bicubic synthesized levels, and 16-bit -pages with an offset and a scale per page. +one. The HUD has a menu per lab, which loads the page again at the same view. The terrain has no +lab: CDLOD by distance, bicubic synthesized levels, and 16-bit pages with an offset and a scale per +page. ## Shots and flights @@ -80,13 +82,14 @@ node trailview/network.mjs [--view V] [--mbit 25] [--rtt 40] [--web DIR] # a co npm run test:trailview # every browser test; CI adds -- --grep-invert @gpu ``` -`shoot.mjs` writes one PNG per view of `views.json` after `waitForIdle()`. Two runs can differ -in a few pixels by a few levels: compare shots by their difference. `flight.mjs` prints the GPU -time per pass, the CPU selection time, the nodes, triangles and pages of each flight of `flights.json`. The `ground` pass runs only when ground pages arrive: -read its `amortized` time. Run it on the M1 Pro with `--gpu`: Chrome then draws -2560 × 1600 pixels and reports exact timestamps. `--tiles` serves a `planner-dem` MBTiles instead -of the fixture, and `--features` a folder `z/x/y.bin`; build the page with a config -whose `bounds` are its box. `--lab NAME:VARIANT` adds the lab to each view. `--cracks 10` counts the red pixels of every tenth frame with +`shoot.mjs` writes one PNG per view of `views.json` after `waitForIdle()`. Two runs can differ in +a few pixels by a few levels: compare shots by their difference. `flight.mjs` prints the GPU time +per pass, the CPU selection time, and the nodes, triangles and pages of each flight of +`flights.json`. The `ground` pass runs only when ground pages arrive: read its `amortized` time. +Run it on the M1 Pro with `--gpu`: Chrome then draws 2560 × 1600 pixels and reports exact +timestamps. `--tiles` serves a `planner-dem` MBTiles instead of the fixture, and `--features` a +folder `z/x/y.bin`; build the page with a config whose `bounds` are its box. `--lab NAME:VARIANT` +adds the lab to each view. `--cracks 10` counts the red pixels of every tenth frame with `debug=cracks`; such a flight looks down on known terrain only, as `cracks.json` does over the box. `--ground DIR` serves the bakes of `tools/trailview` and `tools/planner_snow.py` as the tile service @@ -99,7 +102,7 @@ the page with a config whose `layers` name `https://tiles.test/.json` and prints the RMS of the drawn skyline against the photograph's, per quarter-degree column. It exits 1 past an `rms_limit_deg`. -## Checks +## Test ```sh npx vitest run src/lib/trailview @@ -122,12 +125,12 @@ cargo run --release --locked -p obc-trailview-features -- --osm OSM.pbf \ uv run --locked --group planner-maps python builder/web/tests/browser/trailview/make-fixture.py terrain.mbtiles features.pmtiles ``` -## What bites +## Pitfalls - SwiftShader times are not GPU times. Measure on a GPU. - macOS lowers the GPU clock when a frame has time to spare, so a pass measures long; `flight.mjs --gpu` keeps the clock high. -- A browser test that draws for minutes on SwiftShader takes `{ tag: '@gpu' }`: pull requests skip +- Tag a browser test that draws for minutes on SwiftShader `{ tag: '@gpu' }`: pull requests skip it, `test-weekly.yml` runs it each Monday. - Headless Chromium on Linux with no GPU shows a WebGPU canvas only with `--use-vulkan=swiftshader` (`SWIFTSHADER` in `harness.js`). Else the device is lost: "A valid @@ -151,4 +154,5 @@ uv run --locked --group planner-maps python builder/web/tests/browser/trailview/ part of a page) and loads most tile bodies again: a view's bodies exceed the 96 MiB cache. - Mountain shadows need the `trailview-ground` layer. - The ground noise is in frame metres about the first view: far from it, float32 coarsens its - finest grains, and a view that starts elsewhere draws other grains, so compare shots of one first view. + finest grains, and a view that starts elsewhere draws other grains. Compare shots of one first + view. diff --git a/builder/web/src/lib/usb/protocol.ts b/builder/web/src/lib/usb/protocol.ts index 637795beeb..2a69473d16 100644 --- a/builder/web/src/lib/usb/protocol.ts +++ b/builder/web/src/lib/usb/protocol.ts @@ -2,7 +2,7 @@ * Protocol v4's shared vocabulary in TypeScript: the opcode, kind, flag and error tables, the * decoded response shapes, and the few byte helpers the client and its parsers share. * - * `specs/FLAT_Store_Protocol.md` is the sole authority. The wire codec itself is the Rust + * `specs/flat-store-protocol.md` is the sole authority. The wire codec itself is the Rust * `obc_link::flat` client, which the browser runs through the wasm bridge. * * Every `u64` is a `bigint`, never a `number`: `Number` loses integers above 2^53, and a codec that diff --git a/builder/web/tests/browser/trailview/box.sh b/builder/web/tests/browser/trailview/box.sh index 747641fd99..8c58e19be2 100755 --- a/builder/web/tests/browser/trailview/box.sh +++ b/builder/web/tests/browser/trailview/box.sh @@ -94,7 +94,7 @@ else: for tx in range(x(w), x(e) + 1): for ty in range(y(n), y(s) + 1): blocks.setdefault(f"10-{tx >> 2}-{ty >> 2}", []).append(f"12-{tx}-{ty}=ch") - elif kind == "terrain": # specs/OBCT_Spec.md: origin -2^28 µdeg, tiles of 2^16 µdeg, 4 × 4 to a block + elif kind == "terrain": # specs/obct-terrain.md: origin -2^28 µdeg, tiles of 2^16 µdeg, 4 × 4 to a block t = lambda deg: (round(deg * 1e6) + 2**28) >> 16 for ti in range(t(s), t(n) + 1): for tj in range(t(w), t(e) + 1): diff --git a/builder/web/tests/device-smoke/README.md b/builder/web/tests/device-smoke/README.md index 630ad46e69..f197272530 100644 --- a/builder/web/tests/device-smoke/README.md +++ b/builder/web/tests/device-smoke/README.md @@ -1,15 +1,15 @@ # Device upload smoke -One command sends a map to a connected board over USB, restarts the board, and proves the board -opened what was sent. It exists to catch a transfer that completes and still leaves the wrong bytes, +One command sends a map to a connected board over USB, restarts the board, and proves that the +board opened what was sent. It catches a transfer that completes and still leaves the wrong bytes, the wrong revision or an unreadable map on the card. -It needs hardware. There is no mock device behind it: the cable is `usb`'s WebUSB object under the -shipping `openWebUsbLink`, and the reboot is `tools/board.py`. Without a board the command fails. -The phases themselves are `builder/web/test-support/device-smoke/smoke.ts`, and -`smoke.test.ts` drives them against the real flat engine in wasm, which is what CI runs. +It needs hardware; without a board the command fails. The cable is `usb`'s WebUSB object under the +shipping `openWebUsbLink`, and the reboot is `tools/board.py`. The phases are +`builder/web/test-support/device-smoke/smoke.ts`; CI runs `smoke.test.ts`, which drives them +against the real flat engine in wasm. -## Prerequisites +## Setup - A board flashed with the **release** image, running from the ELF you will pass, plugged into the host twice: **J4** for the debug probe and **J3** for the product cable @@ -35,7 +35,7 @@ The ELF **must** be the image that is running. probe-rs reads it back first and when it already matches; a different ELF is programmed, and a stale one decodes the boot log to noise. -## What it proves +## Reference | Phase | Evidence | | --- | --- | @@ -49,31 +49,23 @@ Each phase has its own deadline and fails with the phase that ran out. A refusal mismatch, a stale selection, an unreadable terrain region or a lost object each fail on their own name rather than on a timeout. -## The map - -`sim/desktop/assets/grimsel-demo.obcm`, whose sources, producer and digests are pinned in -`fixtures/sources/ride-assistant/grimsel-demo-v19.json`. Nothing is assembled at run time and the -digest is checked before the first byte moves. - -Its length is exactly 19,715 whole **card blocks**. The flat store lays an object out over 512-byte -blocks inside its extents, so a payload that is not a multiple of 512 ends inside a block and the -device's last write carries a partial tail; this one does not. The producer pads the authored style -tail so the complete paired-style map ends on the boundary. +The map is `sim/desktop/assets/grimsel-demo.obcm`, whose sources, producer and digests are pinned +in `fixtures/sources/ride-assistant/grimsel-demo-v19.json`. Nothing is assembled at run time, and +the digest is checked before the first byte moves. Its length is exactly 19,715 whole +**card blocks** of 512 bytes, so the device's last write carries no partial tail. The producer +pads the authored style tail so the complete paired-style map ends on the boundary. This is not the USB packet boundary. A stream record on the wire is four bytes of record prefix, a sixteen-byte frame header and its payload, batched into writes of tens of kilobytes, so no host write in this path is a multiple of the 512-byte bulk packet size at any file length. -## The result - -A JSON record per run under `.artifacts/device-smoke/`, beside the RTT log: the tool commit, the -firmware ELF and its digest, the identity strings the device reported, the store identity, the map's -digest, the committed object's full reference, what the firmware said at boot, and each phase's -duration. Attach it to the issue that asks for the physical run. +Each run writes a JSON record under `.artifacts/device-smoke/`, beside the RTT log: the tool +commit, the firmware ELF and its digest, the identity strings the device reported, the store +identity, the map's digest, the committed object's full reference, what the firmware said at boot, +and each phase's duration. Attach it to the issue that asks for the physical run. ## Limits -The boot evidence is what the release image already prints. It proves the firmware opened that -object at that revision, parsed that map's header, and mounted and parsed the embedded terrain -container off the card. It does not sample an elevation at a pinned coordinate; that would need a -new diagnostic. +The boot evidence is what the release image already prints. It proves that the firmware opened +that object at that revision, parsed that map's header, and mounted and parsed the embedded +terrain container off the card. It does not sample an elevation at a pinned coordinate. diff --git a/companion-ios/OBCProtocol.md b/companion-ios/OBCProtocol.md index 87a7d0ca52..3b76ae3b03 100644 --- a/companion-ios/OBCProtocol.md +++ b/companion-ios/OBCProtocol.md @@ -1,25 +1,25 @@ # OBC protocol — iOS implementation notes The normative wire contract is -[`../specs/obc-ble-interface-spec.md`](../specs/obc-ble-interface-spec.md). It owns every UUID, +[`../specs/ble-interface.md`](../specs/ble-interface.md). It owns every UUID, byte layout, state transition and security rule, and it wins over anything here. The ride archive -rules are in [`../specs/Ride_Archive_Contract.md`](../specs/Ride_Archive_Contract.md). Shared +rules are in [`../specs/ride-archive-receipts.md`](../specs/ride-archive-receipts.md). Shared fixtures under `specs/vectors/` pin the codecs byte for byte. This file records only the choices an iOS contributor needs while reading the implementation. ## Versioning and store identity -Protocol version `4`. `protocolVersion` is exactly one little-endian `u16`. The client issues -`LIST` before its first object operation and takes the exact 128-bit `StoreId` from that response. -Durable phone state is scoped to `(device serial, StoreId)`, so a reset or a card swap cannot -alias an old object id. **A version mismatch is surfaced, never decoded optimistically.** +The client checks `protocolVersion` (`ble-interface.md` §3.3). It issues `LIST` before its first +object operation and takes the exact 128-bit `StoreId` from that response. Durable phone state is +scoped to `(device serial, StoreId)`, so a reset or a card swap cannot alias an old object id. +**A version mismatch is surfaced, never decoded optimistically.** ## Transport -The app discovers DIS (`0x180A`), BAS (`0x180F`) and OBC Control (`3C920000-…`). The DIS Firmware -Revision String is either an installed OBCU version or a bare Git hash; **a hash is never parsed -as a release version**, so it never produces an automatic update offer. +The app discovers DIS, BAS and OBC Control (`ble-interface.md` §3). It follows the §3.1 +firmware-revision dialect: **a bare Git hash is never parsed as a release version**, so it never +produces an automatic update offer. Bulk objects move over one encrypted L2CAP CoC. `L2CAPByteChannel` owns bytes, `BLEChannel` preserves v4 stream-record boundaries, `TransferClient` owns request ids and the @@ -35,39 +35,28 @@ request and stream record at the link. ## Object formats -- Routes are OBCR v5 files. GPX and TCX conversion happens on the phone, and the device stores the - OBCR bytes verbatim. The device never parses XML. +- Routes are OBCR v5 files. The device stores the OBCR bytes verbatim and never parses XML. - Ride bytes are recorded samples plus an OBRF footer. The phone decodes them to `Ride` before archiving or exporting GPX. - Route, ride and trip catalogs are v4 `LIST` entries. Catalog flag bit 3 (`assistantAccepted`) marks an accepted Assistant route; the decoder accepts it and rejects undefined flag bits. -- Trips hold route object ids, not route bytes. Upload the stages first and the trip last. - Deleting a trip does not implicitly delete its routes. +- Trips reference route objects (`ble-interface.md` §7.7). Upload the stages first and the trip + last. Deleting a trip does not implicitly delete its routes. - Firmware images are signed OBCU containers carried as update objects. The wire codecs are under `OBCTransport/Codecs/`; interchange-file parsing is in `OBCFormats`. ## Ride archives -The catalog and download path preserve StoreId, ObjectId, the served Revision, the verified length -and the CRC. The archive publishes the canonical summary, samples, source and local sync state in -one transaction, and **file and directory persistence barriers must succeed before a local archive -receipt is returned**. An in-memory save cannot produce a receipt. - -The coordinator sends ARCHIVE_RIDE after a durable commit, and for a revalidated matching archive -even when no download is needed. **Only the matching ARCHIVE_RIDE response confirms proof**; -STATUS and local save counts cannot. The device uses archive proof for the synced indicator, and -rides stay on the device until the user deletes them. - -A ten-second receipt-response deadline cancels the parked receive. A timeout or a failed receipt -leaves the local archive intact and the device confirmation pending in the sync banner; resume or -reconnect revalidates and retries without downloading saved rides. A changed source is terminal -for that receipt. +`ride-archive-receipts.md` owns the archive commit, the receipt, its deadline and the retry rules. +The coordinator sends ARCHIVE_RIDE; **only the matching ARCHIVE_RIDE response confirms proof**. +Rides stay on the device until the user deletes them. ## Names and imports - **The device name lives in Config.** Renaming is a `Config` object write; there is no rename - command. The UTF-8 name is capped at 48 bytes and truncated only at a Character boundary. + command (`ble-interface.md` §7.3). The app truncates the UTF-8 name to the 48-byte cap only at a + Character boundary. - **The phone accepts GPX and TCX.** Either decodes into `ImportedRoute`, which is encoded as OBCR before upload. `RouteSource` and the import UI expose the same two-format boundary. @@ -77,7 +66,7 @@ for that receipt. | --- | --- | | `OBCProtocol` | Pinned version and feature-bit constants | | `DeviceInfo` | DIS plus the v4 StoreId learned through `LIST` | -| `DeviceConfig` | Append-only Config blob, including name and raw refresh byte | +| `DeviceConfig` | Append-only Config blob: device name and units | | `RouteBlob` / `RouteDetail` | Opaque OBCR upload and decoded route-object detail | | `Ride` / `RidePoint` | Canonical decoded ride and export input | | `ImportedRoute` / `RoutePoint` | Canonical GPX and TCX import model | diff --git a/companion-ios/Packages/OBCKit/Sources/OBCDomain/BikeType.swift b/companion-ios/Packages/OBCKit/Sources/OBCDomain/BikeType.swift index 6515c5a5be..183cb462bc 100644 --- a/companion-ios/Packages/OBCKit/Sources/OBCDomain/BikeType.swift +++ b/companion-ios/Packages/OBCKit/Sources/OBCDomain/BikeType.swift @@ -1,6 +1,6 @@ import Foundation -/// The four fixed bike types of `specs/OBCR_Spec.md` §1.2. The raw value is the OBCR header byte +/// The four fixed bike types of `specs/obcr-route.md` §1.2. The raw value is the OBCR header byte /// and the map's routing-profile index. public enum BikeType: UInt8, CaseIterable, Sendable { case road = 0 diff --git a/companion-ios/Packages/OBCKit/Sources/OBCDomain/OBCProtocol.swift b/companion-ios/Packages/OBCKit/Sources/OBCDomain/OBCProtocol.swift index dd548971ed..f553e4bd34 100644 --- a/companion-ios/Packages/OBCKit/Sources/OBCDomain/OBCProtocol.swift +++ b/companion-ios/Packages/OBCKit/Sources/OBCDomain/OBCProtocol.swift @@ -1,6 +1,6 @@ import Foundation -/// The frozen wire-protocol surface, in code form. `specs/obc-ble-interface-spec.md` is +/// The frozen wire-protocol surface, in code form. `specs/ble-interface.md` is /// canonical: if this and the firmware disagree, the firmware wins and this is corrected. public enum OBCProtocol { /// The `protocol_version` this app build is written against. The connect path compares the diff --git a/companion-ios/Packages/OBCKit/Sources/OBCDomain/Ride.swift b/companion-ios/Packages/OBCKit/Sources/OBCDomain/Ride.swift index 0a39c8aeb4..45731558e5 100644 --- a/companion-ios/Packages/OBCKit/Sources/OBCDomain/Ride.swift +++ b/companion-ios/Packages/OBCKit/Sources/OBCDomain/Ride.swift @@ -239,7 +239,7 @@ public struct RideSummary: Identifiable, Equatable, Sendable { } } -/// The trip day a ride started on (`specs/obc-ble-interface-spec.md` §7.2). +/// The trip day a ride started on (`specs/ble-interface.md` §7.2). public struct RideTrip: Equatable, Sendable { /// The trip key of the trip object; never 0. public var key: UInt64 diff --git a/companion-ios/Packages/OBCKit/Sources/OBCDomain/RideZoneLimits.swift b/companion-ios/Packages/OBCKit/Sources/OBCDomain/RideZoneLimits.swift index d9d283d5aa..6d854b05ab 100644 --- a/companion-ios/Packages/OBCKit/Sources/OBCDomain/RideZoneLimits.swift +++ b/companion-ios/Packages/OBCKit/Sources/OBCDomain/RideZoneLimits.swift @@ -1,7 +1,7 @@ import Foundation /// The rider's effort limits that were in force when a ride started -/// (`specs/obc-ble-interface-spec.md` §7.2). A ride keeps them when the rider's settings change +/// (`specs/ble-interface.md` §7.2). A ride keeps them when the rider's settings change /// later. Nil is not set on the device at ride time, and that metric then has no zones. public struct RideZoneLimits: Equatable, Sendable, Codable { public let maxHeartRate: Int? diff --git a/companion-ios/Packages/OBCKit/Sources/OBCDomain/Waypoint.swift b/companion-ios/Packages/OBCKit/Sources/OBCDomain/Waypoint.swift index 5af1d416ee..49bfb4f147 100644 --- a/companion-ios/Packages/OBCKit/Sources/OBCDomain/Waypoint.swift +++ b/companion-ios/Packages/OBCKit/Sources/OBCDomain/Waypoint.swift @@ -15,7 +15,7 @@ public struct Waypoint: Identifiable, Equatable, Sendable { public var category: WaypointCategory? /// Signed lateral distance from the route line, in metres: positive is right of the /// direction of travel, negative is left, `0` is on-route. Fixed at import by the same - /// projection that yields `distanceAlongMeters` (`OBCR_Spec.md`), because a riding device + /// projection that yields `distanceAlongMeters` (`obcr-route.md`), because a riding device /// cannot re-measure it from the decimated geometry it keeps. public var lateralOffsetMeters: Double public var provenance: WaypointProvenance? diff --git a/companion-ios/Packages/OBCKit/Sources/OBCDomain/WaypointCategory.swift b/companion-ios/Packages/OBCKit/Sources/OBCDomain/WaypointCategory.swift index bfdbecbb56..b0468e2a10 100644 --- a/companion-ios/Packages/OBCKit/Sources/OBCDomain/WaypointCategory.swift +++ b/companion-ios/Packages/OBCKit/Sources/OBCDomain/WaypointCategory.swift @@ -4,7 +4,7 @@ import Foundation /// map already uses, reused verbatim so one icon language covers both sources. /// /// The raw values are the stable wire ids stored in an OBCR waypoint record's category byte -/// (`OBCR_Spec.md`). `0` is not a case: it means generic, which this type models as `nil`. +/// (`obcr-route.md`). `0` is not a case: it means generic, which this type models as `nil`. public enum WaypointCategory: UInt8, CaseIterable, Sendable { case water = 1 case campsite = 2 diff --git a/companion-ios/Packages/OBCKit/Sources/OBCTransport/BLE/BLEChannel.swift b/companion-ios/Packages/OBCKit/Sources/OBCTransport/BLE/BLEChannel.swift index 1996f74043..267f961d49 100644 --- a/companion-ios/Packages/OBCKit/Sources/OBCTransport/BLE/BLEChannel.swift +++ b/companion-ios/Packages/OBCKit/Sources/OBCTransport/BLE/BLEChannel.swift @@ -17,7 +17,8 @@ public struct BLEChannel: Sendable { self.chunkSize = max(1, chunkSize) } - /// One complete protocol-v4 stream record in one CoC SDU. + /// Writes one complete protocol-v4 stream record. The CoC is a byte stream, so the link can + /// split the write; the receiver reassembles by the header's payload length. public func sendRecord(_ record: Data) async throws { guard record.count <= chunkSize else { throw DeviceError.transferRejected } _ = try StreamRecord(decoding: record) diff --git a/companion-ios/Packages/OBCKit/Sources/OBCTransport/BLE/GATT.swift b/companion-ios/Packages/OBCKit/Sources/OBCTransport/BLE/GATT.swift index b20f4f4b1c..464b46c4c2 100644 --- a/companion-ios/Packages/OBCKit/Sources/OBCTransport/BLE/GATT.swift +++ b/companion-ios/Packages/OBCKit/Sources/OBCTransport/BLE/GATT.swift @@ -2,7 +2,7 @@ @preconcurrency import CoreBluetooth /// The GATT service and characteristic map `BLETransport` discovers: the control plane of -/// `obc-ble-interface-spec.md`. +/// `ble-interface.md`. /// /// The OBC Control UUIDs use the random base `3C92XXXX-9916-4EBA-ABC2-342FE08F6B10`, where the /// 16-bit `XXXX` block selects the entity (`0000` is the service, `000N` characteristic N). A diff --git a/companion-ios/Packages/OBCKit/Sources/OBCTransport/Codecs/RouteObjectCodec.swift b/companion-ios/Packages/OBCKit/Sources/OBCTransport/Codecs/RouteObjectCodec.swift index 3e870a95e3..4b27222b6f 100644 --- a/companion-ios/Packages/OBCKit/Sources/OBCTransport/Codecs/RouteObjectCodec.swift +++ b/companion-ios/Packages/OBCKit/Sources/OBCTransport/Codecs/RouteObjectCodec.swift @@ -3,7 +3,7 @@ import OBCDomain import OBCHost /// The Rust OBCR v5 encoder and the Swift decoder. Stored geometry owns the route totals. -/// Missing elevation and incoming graph validity stay explicit. The exact bytes are in specs/OBCR_Spec.md, and shared +/// Missing elevation and incoming graph validity stay explicit. The exact bytes are in specs/obcr-route.md, and shared /// Rust-produced vectors pin the reader. public enum RouteObjectCodec { // MARK: Format constants diff --git a/companion-ios/Packages/OBCKit/Sources/OBCTransport/Codecs/TripObjectCodec.swift b/companion-ios/Packages/OBCKit/Sources/OBCTransport/Codecs/TripObjectCodec.swift index 6f6a8a7eab..95cf914acb 100644 --- a/companion-ios/Packages/OBCKit/Sources/OBCTransport/Codecs/TripObjectCodec.swift +++ b/companion-ios/Packages/OBCKit/Sources/OBCTransport/Codecs/TripObjectCodec.swift @@ -5,7 +5,7 @@ import OBCDomain /// reconcile download. A trip object references one route per day by its device object id and never /// carries route bytes. /// -/// The layout is little-endian (`obc-ble-interface-spec.md` §7.7): a fixed 64-byte header, then one +/// The layout is little-endian (`ble-interface.md` §7.7): a fixed 64-byte header, then one /// 16-byte record per day in ride order. The header holds the version, the day count, a /// length-prefixed, zero-padded name of at most 48 bytes, the start date and the trip key. /// diff --git a/companion-ios/Packages/OBCKit/Sources/OBCTransport/Firmware/FirmwareImage.swift b/companion-ios/Packages/OBCKit/Sources/OBCTransport/Firmware/FirmwareImage.swift index abeee7fe54..b1bfde6149 100644 --- a/companion-ios/Packages/OBCKit/Sources/OBCTransport/Firmware/FirmwareImage.swift +++ b/companion-ios/Packages/OBCKit/Sources/OBCTransport/Firmware/FirmwareImage.swift @@ -33,7 +33,7 @@ public struct OBCUHeader: Equatable, Sendable { /// Bytes of the header covered by the header CRC, which is everything but the CRC. public static let headerCRCLength = 60 /// The device's whole application slot, and so the largest raw image it can flash - /// (`obc_dfu::MAX_IMAGE_LEN`, `OBCU_Spec.md` 1.1). An announced object past it is rejected at + /// (`obc_dfu::MAX_IMAGE_LEN`, `obcu-update.md` 1.1). An announced object past it is rejected at /// announce, so the app refuses it here first. public static let maxImageLength: UInt32 = 2_023_424 diff --git a/companion-ios/Packages/OBCKit/Sources/OBCTransport/Transfer/CRC32.swift b/companion-ios/Packages/OBCKit/Sources/OBCTransport/Transfer/CRC32.swift index 4e9661defe..330f14995d 100644 --- a/companion-ios/Packages/OBCKit/Sources/OBCTransport/Transfer/CRC32.swift +++ b/companion-ios/Packages/OBCKit/Sources/OBCTransport/Transfer/CRC32.swift @@ -1,9 +1,9 @@ import Foundation /// Whole-object CRC-32: the end-to-end integrity check, verified once before commit -/// (`OBCProtocol.md`). The BLE Link Layer already CRCs and retransmits every packet, so this -/// adds only what the link CRC cannot: coverage of the whole path from the phone's encode to -/// MCU flash. One CRC per object, never per chunk. +/// (`specs/flat-store-protocol.md` Conventions and §3.6). The BLE Link Layer already CRCs and +/// retransmits every packet, so this adds only what the link CRC cannot: coverage of the whole path +/// from the phone's encode to MCU flash. One CRC per object, never per chunk. /// /// Standard CRC-32/IEEE: reflected, poly `0xEDB88320`, init and xorout `0xFFFFFFFF`, check /// value `crc32("123456789") == 0xCBF43926`. The `Hasher` streams chunk by chunk with O(1) diff --git a/companion-ios/Packages/OBCKit/Sources/OBCUI/Detail/RouteDetailModel.swift b/companion-ios/Packages/OBCKit/Sources/OBCUI/Detail/RouteDetailModel.swift index dd75a4ed3a..8e775202c4 100644 --- a/companion-ios/Packages/OBCKit/Sources/OBCUI/Detail/RouteDetailModel.swift +++ b/companion-ios/Packages/OBCKit/Sources/OBCUI/Detail/RouteDetailModel.swift @@ -72,7 +72,7 @@ public final class RouteDetailModel { /// False for a ride whose points carry no elevation, or that has no points and no climb, so /// its climb and descent read as unknown, not 0. private let hasElevation: Bool - /// The `OBCR_Spec.md` §1.2 estimate. Distance and climb hold the upload's header figures, so it + /// The `obcr-route.md` §1.2 estimate. Distance and climb hold the upload's header figures, so it /// is the estimate the device shows for this route and type. private var estimatedDuration: TimeInterval? { if case .tracked = dressing { return nil } diff --git a/companion-ios/Packages/OBCKit/Tests/OBCTransportTests/BikeTypeTests.swift b/companion-ios/Packages/OBCKit/Tests/OBCTransportTests/BikeTypeTests.swift index fe65544386..abb7811b77 100644 --- a/companion-ios/Packages/OBCKit/Tests/OBCTransportTests/BikeTypeTests.swift +++ b/companion-ios/Packages/OBCKit/Tests/OBCTransportTests/BikeTypeTests.swift @@ -3,7 +3,7 @@ import Testing import OBCDomain import OBCTransport -/// The `OBCR_Spec.md` §1.2 estimate against the shared vector file, and the bike-type byte in +/// The `obcr-route.md` §1.2 estimate against the shared vector file, and the bike-type byte in /// the OBCR header. struct BikeTypeTests { private static let vectorsDir = URL(fileURLWithPath: #filePath) diff --git a/companion-ios/Packages/OBCKit/Tests/OBCTransportTests/TripDatesTests.swift b/companion-ios/Packages/OBCKit/Tests/OBCTransportTests/TripDatesTests.swift index 141d0d97d7..3dbd9d7ab1 100644 --- a/companion-ios/Packages/OBCKit/Tests/OBCTransportTests/TripDatesTests.swift +++ b/companion-ios/Packages/OBCKit/Tests/OBCTransportTests/TripDatesTests.swift @@ -2,7 +2,7 @@ import Testing import Foundation import OBCDomain -/// Dates follow the rides (`obc-ble-interface-spec.md` §7.7 "Day dates"). +/// Dates follow the rides (`ble-interface.md` §7.7 "Day dates"). struct TripDatesTests { private func trip(days: Int, start: Int?) -> Trip { let files = (0.. OBCTransport -> OBCMock - \-> OBCFormats -OBCUI -> OBCDomain + OBCTransport + OBCPlanner + MapLibre (iOS) -OBCPlanner -> OBCDomain (online client, offline installation and selection) -``` - -`OBCCompanion/` is the composition root and the only target that chooses a concrete transport and planner provider. -`PlannerDataSource` supplies one release for maps, search, routes, and viewport layers. -`obcPlannerSource` passes that provider to map views. The app uses `LocalFirstPlanner`. -`OfflinePlanner` connects installed releases to native routing, search and map files. -Offline maps live in Settings, with a shortcut in the planner's map menu. -`project.yml` is the Xcode project source of truth; **never edit or commit the generated -pbxproj.** - -## Build and test - -Needs Xcode 26.x, an iOS simulator runtime, XcodeGen, Node.js 22 or later, and the Rust toolchain. XcodeGen installs the pinned replay renderer and builds native map styles and search with npm. -App builds link `OBCHost` and compile `planner-service` for the selected Rust iOS target. -Map styles and POI kinds come from the web planner sources. Before package tests without XcodeGen, run -`npm ci --prefix companion-ios/ReplayAssets` from the repository root. -The existing host build script also connects the package to the Rust framework. +Map styles and POI kinds come from the web planner sources. App builds link `OBCHost` and compile +`planner-service` for the selected Rust iOS target. The host build script also connects the +package to the Rust framework. -For a simulator, prepare the framework before XcodeGen resolves the package: +For a simulator, prepare the framework before XcodeGen resolves the package, then use the +`OBCCompanion` scheme: ```sh -tools/build-ios-host.sh --sim-only +obc ios-host --sim-only cd companion-ios xcodegen generate ``` -For package tests, start at the repository root and prepare the macOS slice: +`obc ios-companion` builds Release with real Bluetooth and installs it on the paired iPhone; +`obc ios-device` does the same for the `OBCDevice` shell. + +`project.yml` is the Xcode project source of truth; **never edit or commit the generated +pbxproj.** + +## Test + +Before package tests without XcodeGen, run `npm ci --prefix companion-ios/ReplayAssets` from the +repository root. Then, from the repository root, prepare the macOS slice: ```sh -tools/build-ios-host.sh --mac-only +obc ios-host --mac-only cd companion-ios/Packages/OBCKit swift test --disable-keychain --disable-netrc ``` -CI runs the package tests plus Debug and Release simulator builds. For a simulator, generate the -project and use the `OBCCompanion` scheme. `obc ios-companion` builds Release with real Bluetooth -and installs it on the paired iPhone; `obc ios-device` does the same for the `OBCDevice` shell. -Personal signing belongs in `project.local.yml`: it is tracked with an empty team id, and its -header says how to keep your edit out of git. +CI runs the package tests plus Debug and Release simulator builds. ## Mock and captures @@ -79,3 +64,24 @@ catalogue, such as the one that `obc data serve` prints. Offline downloads use the downloads service of the active release in that catalogue. - On a device, accept the Local Network alert. To answer it again, use Settings › Privacy & Security › Local Network. + +## Architecture + +View models depend on capability-sized protocols declared by `OBCTransport`, so the same UI runs +against CoreBluetooth on a device and against the deterministic mock in tests and the simulator. +Use the broad `DeviceTransport` aggregate only for true aggregate consumers and composition-root +wiring. CoreBluetooth stays in `OBCTransport/BLE/`, and mock code stays in `OBCMock` behind +`#if DEBUG`. Tests enforce these boundaries. + +```text +OBCDomain -> OBCTransport -> OBCMock + \-> OBCFormats +OBCUI -> OBCDomain + OBCTransport + OBCPlanner + MapLibre (iOS) +OBCPlanner -> OBCDomain (online client, offline installation and selection) +``` + +`OBCCompanion/` is the composition root and the only target that chooses a concrete transport and +planner provider. `PlannerDataSource` supplies one release for maps, search, routes, and viewport +layers. `obcPlannerSource` passes that provider to map views. The app uses `LocalFirstPlanner`. +`OfflinePlanner` connects installed releases to native routing, search and map files. Offline maps +live in Settings, with a shortcut in the planner's map menu. diff --git a/data/machines.toml b/data/machines.toml index 25180ed9e9..b1ebdafec6 100644 --- a/data/machines.toml +++ b/data/machines.toml @@ -1,4 +1,4 @@ # The machines that run `obc data ui`. The name of a table is the name of the machine: -# `OBC_DATA_MACHINE`, or else its short host name. specs/obc-data.md, "Machines", gives the format. -# A machine that is not here has the charcoal header of a laptop, and `obc data open NAME` tunnels -# to the SSH host NAME. +# `OBC_DATA_MACHINE`, or else its short host name. The section "`data/machines.toml`" of +# specs/obc-data.md gives the format. A machine that is not here has the charcoal header of a +# laptop, and `obc data open NAME` tunnels to the SSH host NAME. diff --git a/data/trailview/README.md b/data/trailview/README.md index 1eb2abcb19..7d1e95398a 100644 --- a/data/trailview/README.md +++ b/data/trailview/README.md @@ -14,13 +14,13 @@ The rules that the TrailView ground layers index and that the engine reads. The | `ground.json` | The ground sources of the material and the lithology, in the order they apply: [specs/trailview-tiles.md](../../specs/trailview-tiles.md#ground-sources) | | `roads.json` | The rules per class of road and track, from the most important down: the grade and smoothing of the road solver, the stamp profile of the engine | -## Check +## Test ```sh uv run --locked --group trailview python -m tools.trailview.rules ``` -## What bites +## Pitfalls - Codes in `materials.json` are indexes in the ground tiles. Append only. - A region id is a region and a place: one id per region, and one per country or subdivision diff --git a/docs/BLOG.md b/docs/BLOG.md index 0c975fd7f6..54663d6987 100644 --- a/docs/BLOG.md +++ b/docs/BLOG.md @@ -1,9 +1,9 @@ # Writing a log entry -The blog ("expedition log") is markdown in `docs/content/blog//index.md`, -rendered by the same stdlib-only `build_docs.py` that builds the docs, published at -`/blog/` by the same Trunk build. One folder per post; images and models sit next to -the markdown and are copied verbatim next to the rendered page. +The blog ("expedition log") is markdown in `docs/content/blog//index.md`. The docs build +(`build_docs.py`, standard library only) renders it, and the same Trunk build publishes it at +`/blog/`. One folder per post; images and models sit next to the markdown and are copied verbatim +next to the rendered page. ## The loop @@ -13,10 +13,9 @@ trunk serve --config docs/Trunk.toml # live preview at 127.0.0.1:8 python3 docs/tools/paste_images.py my-post-title # paste/drop images -> post folder ``` -`trunk serve` re-renders on every save (the `pre_build` hook) and hot-reloads the -browser. The paste tool (port 8091) saves clipboard images or dropped files into the -post folder — downscaled to 1600 px if Pillow is installed — and puts the matching -`![](file.png)` line on your clipboard. +`trunk serve` re-renders on every save (the `pre_build` hook) and reloads the browser. The paste +tool (port 8091) saves clipboard images or dropped files into the post folder, downscaled to +1600 px if Pillow is installed, and puts the matching `![](file.png)` line on your clipboard. ## Front matter @@ -28,18 +27,17 @@ description: One-line teaser. # shown on the timeline + in the Atom feed --- ``` -The h1 comes from `title:` — start the body with a paragraph, not a heading. The -first paragraph renders as the lede. Posts are sorted newest-first and grouped by -month on `/blog/`; an Atom feed is generated at `/blog/feed.xml`. +The h1 comes from `title:`: start the body with a paragraph, not a heading. The first paragraph +renders as the lede. `/blog/` sorts posts newest first and groups them by month; the Atom feed is +`/blog/feed.xml`. -HTML comments (`` starting at the beginning of a line) are stripped from -the rendered page — use them for drafts, notes-to-self, or to park an example -without publishing it (the scaffold does exactly that). +The renderer strips HTML comments (`` at the start of a line) from the page. Use them +for drafts and notes, or to park an example without publishing it, as the scaffold does. ## Images -A paragraph containing just one image becomes a framed, click-to-zoom exhibit -(the alt text is the lightbox caption): +A paragraph with only one image becomes a framed, click-to-zoom exhibit. The alt text is the +lightbox caption: ```markdown ![The first assembled unit](assembly.png) @@ -59,8 +57,8 @@ caption: What changed. # optional ## Interactive 3D models -Convert a STEP export once, commit the `.glb` (and the `.step`, if you want the -download button) next to `index.md`: +Convert a STEP export once. Commit the `.glb` next to `index.md`, and the `.step` too if you want +the download button: ```sh pip install cascadio # one-time; prebuilt OpenCascade wheels @@ -75,10 +73,10 @@ caption: Drag to orbit. # optional ``` ```` -The viewer (`assets/glb-viewer.js`) is hand-rolled WebGL for the subset our -converter emits — keep models under ~4 MB (coarsen `--linear` if needed). +The viewer (`assets/glb-viewer.js`) reads only the subset that the converter writes. Keep models +under about 4 MB; coarsen `--linear` if necessary. ## Publishing -Commit the post folder and push — CI renders and link-checks the whole site -(`python3 docs/build_docs.py --check-links` runs the same check locally). +Commit the post folder and push. CI renders and link-checks the whole site; +`python3 docs/build_docs.py --check-links` runs the same check locally. diff --git a/docs/content/software/companion-link.md b/docs/content/software/companion-link.md index bca9b498b9..efb2cb99ec 100644 --- a/docs/content/software/companion-link.md +++ b/docs/content/software/companion-link.md @@ -10,9 +10,9 @@ out. Bluetooth and USB carry the same protocol frames, so there is one transfer of rules. Bluetooth adds the device-local controls: pairing, the clock, the settings, and bond removal. USB carries objects and device information only. -The normative contracts are the [flat-store protocol](src:specs/FLAT_Store_Protocol.md), the -[card format](src:specs/FLAT_Store_Format.md), and the -[BLE control surface](src:specs/obc-ble-interface-spec.md). +The normative contracts are the [flat-store protocol](src:specs/flat-store-protocol.md), the +[card format](src:specs/flat-store-format.md), and the +[BLE control surface](src:specs/ble-interface.md). ## Two planes: control and data @@ -93,7 +93,7 @@ The phone then sends the device proof that it holds that exact finalized ride, a commits and reads back that proof. Proof turns the synced indicator on. It is deliberately not a deletion trigger: routes and rides stay on the device until the rider removes them, and a full card offers the rider an age-based cleanup instead of deciding alone. The durable format is in the -[metadata contract](src:specs/Ride_Archive_Metadata.md). +[metadata contract](src:specs/ride-archive-metadata.md). ## Pairing and the Bluetooth controls diff --git a/docs/content/software/firmware-updates.md b/docs/content/software/firmware-updates.md index 2ac47565a7..caacd71a62 100644 --- a/docs/content/software/firmware-updates.md +++ b/docs/content/software/firmware-updates.md @@ -6,7 +6,7 @@ description: How a firmware package is released, delivered, validated, installed # Firmware updates The device has one application slot and a small bootloader, and the update design reserves storage -for the previous image. An update package uses the [OBCU format](src:specs/OBCU_Spec.md) and is +for the previous image. An update package uses the [OBCU format](src:specs/obcu-update.md) and is stored as an ordinary object on the card. Uploading a package does not install it. Installation is a separate, explicit step, and the rider @@ -49,7 +49,7 @@ The package carries a CRC for integrity and an Ed25519 signature for authenticit message covers a context string, the version, the image length, and the image, so a package cannot be replayed as a different version. The application verifies the signature before it arms; the bootloader verifies the image CRC before it erases. See the -[OBCU specification](src:specs/OBCU_Spec.md). +[OBCU specification](src:specs/obcu-update.md). ## Release publication @@ -128,8 +128,8 @@ during an install. ## Implementation -- OBCU and boot-state formats: [`OBCU_Spec.md`](src:specs/OBCU_Spec.md) -- Install protocol: [`FLAT_Store_Protocol.md`](src:specs/FLAT_Store_Protocol.md) +- OBCU and boot-state formats: [`obcu-update.md`](src:specs/obcu-update.md) +- Install protocol: [`flat-store-protocol.md`](src:specs/flat-store-protocol.md) - Shared update logic: [`obc-dfu`](src:firmware/obc-dfu) - Bootloader: [`obc-boot`](src:firmware/obc-boot) - Package tool: [`obc-mkimage`](src:host/obc-mkimage) diff --git a/docs/content/software/formats.md b/docs/content/software/formats.md index 8c883e5162..fe10bac171 100644 --- a/docs/content/software/formats.md +++ b/docs/content/software/formats.md @@ -59,7 +59,7 @@ coarsest scale it serves, so the renderer opens one level and reads nothing else The header addresses the global sections. An absent section has a zero offset and length, which is how a map without terrain, landmarks, or peak articles says so. The paired Light and Dark style -tables apply to the same geometry at every level. [OBCM](src:specs/OBCM_Spec.md) defines each field. +tables apply to the same geometry at every level. [OBCM](src:specs/obcm-map.md) defines each field. ### The quadtree index @@ -112,7 +112,7 @@ Each POI category has its own index, so a search for water reads no campsite rec carries its source identity and, where a source node lies on a routable way, a mapped approach. That approach is what lets the device plan a ride to a place instead of to a coordinate beside it. Separate categories hold named summits and settlement names. See -[OBCM section 7](src:specs/OBCM_Spec.md). +[OBCM section 7](src:specs/obcm-map.md). ### Opening hours: a pooled weekly schedule @@ -162,7 +162,7 @@ the file keeps, so the summary and the route agree. Missing elevation is an explicit unknown value, because zero meters is a valid height at the coast. An unknown point pauses ascent integration instead of adding a false climb. See the -[OBCR specification](src:specs/OBCR_Spec.md). +[OBCR specification](src:specs/obcr-route.md). ## Recorded rides @@ -180,7 +180,7 @@ everything written before the interruption. The footer also records the bike typ that the ride started on, so the device and the phone group the rides of a trip without dates. It keeps the rider's maximum heart rate and FTP from the start too, so a ride keeps its effort zones when the rider changes those settings later. The byte contract is in -[the BLE interface specification](src:specs/obc-ble-interface-spec.md). +[the BLE interface specification](src:specs/ble-interface.md). ## OBCT — the terrain raster @@ -222,7 +222,7 @@ fetched over a network, so the catalog, not the transport, decides what the righ The split between schema and skin is why a map can be restyled cheaply. The schema controls geometry, levels, style identifiers, routing, and chunk size, and changing it needs a rebake. A skin controls only colors, weights, line style, paint order, and priority, and changing it does -not. See [`OBCC_Spec.md`](src:specs/OBCC_Spec.md). +not. See [`obcc-catalog.md`](src:specs/obcc-catalog.md). ## Cells and assemblies @@ -246,7 +246,7 @@ a seam merge when their coordinates are equal. All cells in one assembly share the schema digest and the map version. The assembler writes the selected Light and Dark presentation records into one file. The browser runs the same engine as the command line, through [`obc-builder-bridge`](src:builder/wasm), and -verifies the result with the production readers. See [`OBCA_Spec.md`](src:specs/OBCA_Spec.md). +verifies the result with the production readers. See [`obca-assembly.md`](src:specs/obca-assembly.md). ## Source index diff --git a/docs/content/software/packer-routing.md b/docs/content/software/packer-routing.md index 80edca9cd5..f66ab91c89 100644 --- a/docs/content/software/packer-routing.md +++ b/docs/content/software/packer-routing.md @@ -146,7 +146,7 @@ Shared OSM node identities become junctions. The packer splits ways there, remov and drops small disconnected components. A legality filter rejects private access, motor roads, and bicycle prohibitions, and each accepted edge is classified by highway and surface into one way-kind byte, which is what the profile weights read. See -[OBCM section 8](src:specs/OBCM_Spec.md). +[OBCM section 8](src:specs/obcm-map.md). An assembled map keeps one graph: the assembler copies each surviving edge geometry record unchanged and rebuilds the identities, the adjacency, and the indexes. @@ -154,7 +154,7 @@ unchanged and rebuilds the identities, the adjacency, and the indexes. ### Weighting the graph: bike profiles A map carries four bike profiles in fixed order: Road, Gravel, MTB, and Touring -([OBCM §8.6](src:specs/OBCM_Spec.md)). A profile gives a multiplier for each highway class and +([OBCM §8.6](src:specs/obcm-map.md)). A profile gives a multiplier for each highway class and surface, and a climb weight. Every multiplier is at least one, and zero means forbidden. That is not a style choice: A* needs a diff --git a/docs/content/software/terrain.md b/docs/content/software/terrain.md index 17afbb3f1f..faf43bd3c6 100644 --- a/docs/content/software/terrain.md +++ b/docs/content/software/terrain.md @@ -31,7 +31,7 @@ The packer and the device use the same `no_std` sampler, the ascent the router weighs, and the device measures the climb the rider sees. If the two sampled differently, a route would promise one climb and report another. -[OBCT section 5](src:specs/OBCT_Spec.md) specifies the integer interpolation exactly, so an +[OBCT section 5](src:specs/obct-terrain.md) specifies the integer interpolation exactly, so an independent implementation returns the same whole-meter height. Cells own their seam samples, so a position on a cell boundary has one answer. @@ -169,8 +169,8 @@ nowhere else. map. The posting and the cell size are header fields, so changing them is a re-bake and not a format -version. See the [OBCT specification](src:specs/OBCT_Spec.md) for the limits and the byte layout, -and [OBCC section 13](src:specs/OBCC_Spec.md) for the catalog contract. +version. See the [OBCT specification](src:specs/obct-terrain.md) for the limits and the byte layout, +and [OBCC section 13](src:specs/obcc-catalog.md) for the catalog contract. ## Attribution @@ -189,7 +189,7 @@ Map data carries the OpenStreetMap credit of the same registry. ## Implementation -- OBCT contract: [`OBCT_Spec.md`](src:specs/OBCT_Spec.md) +- OBCT contract: [`obct-terrain.md`](src:specs/obct-terrain.md) - Reader and sampler: [`obc-elevation`](src:firmware/obc-elevation) - DEM converter: [`obc-dem`](src:host/obc-dem) - Terrain publisher: [`terrain.rs`](src:host/obc-bake/src/terrain.rs) diff --git a/docs/content/software/trips.md b/docs/content/software/trips.md index 7650e4c4f9..6d78636b18 100644 --- a/docs/content/software/trips.md +++ b/docs/content/software/trips.md @@ -14,9 +14,9 @@ device, and keeps the rides as a journal on the phone. Three rules shape the des changes after sync. The contracts are the trip object (§7.7) and the ride footer (§7.2) in the -[BLE interface spec](src:specs/obc-ble-interface-spec.md), the route format with its bike-type -table in [OBCR](src:specs/OBCR_Spec.md), and the device's trip progress record in the -[ride-archive Metadata](src:specs/Ride_Archive_Metadata.md). +[BLE interface spec](src:specs/ble-interface.md), the route format with its bike-type +table in [OBCR](src:specs/obcr-route.md), and the device's trip progress record in the +[ride-archive Metadata](src:specs/ride-archive-metadata.md). ## One line on the phone, day routes on the device diff --git a/docs/content/software/ui.md b/docs/content/software/ui.md index bb042c9691..c7ec5cb71a 100644 --- a/docs/content/software/ui.md +++ b/docs/content/software/ui.md @@ -234,7 +234,7 @@ promises a rideable connection. The line shows the remaining route, with places ahead below the rider. Settlements group nearby services; waypoints and the route end stay visible through filters. Larger spaces mark long distances between stops. Select opens details. Hold refreshes the list. -Service records follow the [map format](src:specs/OBCM_Spec.md). +Service records follow the [map format](src:specs/obcm-map.md). ### Nearby landmarks diff --git a/firmware/README.md b/firmware/README.md index 0222899540..a2ed595974 100644 --- a/firmware/README.md +++ b/firmware/README.md @@ -2,16 +2,16 @@ This directory holds the crates the device image reaches: the shared `no_std` render path, the platform adapters, the board crate and the bootloader. The device application and the desktop -simulator share one rendering path for `.obcm` maps. - -This file is the build, test and dev-loop guide for all the Rust in the repo. For how the system -works, read the docs site: . Per-crate roles are tabulated in the +simulator share one rendering path for `.obcm` maps. This file is the build, test and dev-loop +guide for all the Rust in the repo. For how the system works, read the docs site: +. Per-crate roles are in the [repo README](../README.md#repository-layout). -The workspace is rooted at the repo root (`../Cargo.toml`) and spans `firmware/`, `../host/` and -`../planner/`, `../sim/`, and `../builder/` — one `Cargo.lock`, one `target/`. Only `firmware/` is device-reachable; that is the -rule `firmware/tools/check_dependencies.py` enforces. Dev-dependencies cross the boundary on -purpose, because a dev-dep never enters the `no_std` build, so `cargo test` wants GEOS. +The workspace is rooted at the repo root (`../Cargo.toml`) and spans `firmware/`, `../host/`, +`../planner/`, `../sim/` and `../builder/`: one `Cargo.lock`, one `target/`. Only `firmware/` is +device-reachable; `firmware/tools/check_dependencies.py` enforces that rule. Dev-dependencies +cross the boundary, because a dev-dependency never enters the `no_std` build. So `cargo test` +needs GEOS. Four crates are excluded from the workspace and built from **inside their own directory**, each with its own `Cargo.lock`, `fmt`, `clippy`, `test` and CI job: @@ -23,14 +23,14 @@ with its own `Cargo.lock`, `fmt`, `clippy`, `test` and CI job: | [`obc-desktop`](../builder/desktop/README.md) | the Tauri app: a platform webview | | [`obc-sensor-sim`](obc-sensor-sim/README.md) | the sensor simulator: its own MCU target | -## Prerequisites +## Setup | For… | You need | | :-- | :-- | | Anything Rust | A stable toolchain (`rustup`). | -| The desktop simulator | Just Rust — the GUI is pure eframe/egui. | +| The desktop simulator | Only Rust — the GUI is pure eframe/egui. | | The packer (`obc-pack`) | System **GEOS ≥ 3.14** (`brew install geos`), its only native dependency. | -| The desktop app (`obc-desktop`) | **CMake** and a C++ compiler (it vendors GEOS), plus Node. Linux also wants WebKitGTK — see [its README](../builder/desktop/README.md). | +| The desktop app (`obc-desktop`) | **CMake** and a C++ compiler (it vendors GEOS), plus Node. Linux also needs WebKitGTK — see [its README](../builder/desktop/README.md). | | Compiling the shared crates for the device | `rustup target add thumbv8m.main-none-eabihf`. | ## Build @@ -43,14 +43,53 @@ cargo build --release # → target/release/{obc-sim, obc-pack} cargo build -p obc-app --target thumbv8m.main-none-eabihf ``` -The board crate is built from inside its own directory. Its target comes from -`.cargo/config.toml`, which cargo finds by working directory, so building it through -`--manifest-path` from here silently targets the host and fails: +Build the board crate from inside its own directory. Cargo finds its target in +`.cargo/config.toml` by working directory, so a build through `--manifest-path` from here silently +targets the host and fails: ```sh cd firmware/obc-fw-nrf54l && cargo build --release # see that crate's README to flash ``` +### Web builder core + +Build the browser core and its test-only device variant with `wasm-pack`: + +```sh +# From builder/web. +npm run build:wasm +``` + +The frontend needs this output before `npm run check`, `npm test`, or `npm run build`. +See [the bridge README](../builder/wasm/README.md) for paths and checks. + +## Run + +### Simulator + +`obc-sim` renders a packed `.obcm` map through the exact code the firmware runs. Pack one with +`obc pack `. + +```sh +obc sim # the Grimsel demo +./target/release/obc-sim map.obcm # device look, 240×320, 3× window scale +./target/release/obc-sim map.obcm --size 480x640 --scale 2 +./target/release/obc-sim map.obcm --gpx ride.gpx # replay a GPX as a fake GPS +./target/release/obc-sim map.obcm --png out.png # headless one-frame render +``` + +See the [simulator guide](../sim/desktop/README.md) or `obc-sim --help` for the rest. + +### Web demo (`obc-web-demo`) + +The landing page's live demo is the shared crates compiled to wasm. Trunk drives the build +(`rustup target add wasm32-unknown-unknown` and `cargo install trunk` once): + +```sh +trunk serve --config docs/Trunk.toml # http://127.0.0.1:8080/ +trunk build --release --config docs/Trunk.toml # → docs/dist/, what CI and Pages deploy +``` + ## Test ```sh @@ -81,9 +120,9 @@ regenerates it in the same pull request, with the reason stated. ## Format -`.rustfmt.toml` is committed, so let rustfmt own style. Formatting takes five invocations, and CI -checks all of them: the workspace is a *virtual* manifest, so `--all` is required or it formats -nothing, and `--all` skips the four excluded crates. +`.rustfmt.toml` is committed, so let rustfmt own style. CI checks all five invocations. The +workspace is a *virtual* manifest, so `--all` is required or it formats nothing, and `--all` skips +the four excluded crates. `obc fmt` runs all five. ```sh cargo fmt --all # the workspace @@ -93,50 +132,11 @@ cargo fmt --manifest-path builder/desktop/Cargo.toml cargo fmt --manifest-path firmware/obc-sensor-sim/Cargo.toml ``` -`obc fmt` runs all five. - -## Run the simulator - -`obc-sim` renders a packed `.obcm` map through the exact code the firmware runs. Pack one with -`obc pack `. - -```sh -obc sim # the Grimsel demo -./target/release/obc-sim map.obcm # device look, 240×320, 3× window scale -./target/release/obc-sim map.obcm --size 480x640 --scale 2 -./target/release/obc-sim map.obcm --gpx ride.gpx # replay a GPX as a fake GPS -./target/release/obc-sim map.obcm --png out.png # headless one-frame render -``` - -See the [simulator guide](../sim/desktop/README.md) or `obc-sim --help` for the rest. - -## Run the web demo (`obc-web-demo`) - -The landing page's live demo is the same shared crates compiled to wasm. Trunk drives the build -(`rustup target add wasm32-unknown-unknown` and `cargo install trunk` once): - -```sh -trunk serve --config docs/Trunk.toml # http://127.0.0.1:8080/ -trunk build --release --config docs/Trunk.toml # → docs/dist/, what CI and Pages deploy -``` - -## Build the web builder core - -Build the browser core and its test-only device variant with `wasm-pack`: - -```sh -# From builder/web. -npm run build:wasm -``` - -The frontend needs this output before `npm run check`, `npm test`, or `npm run build`. -See [the bridge README](../builder/wasm/README.md) for paths and checks. - ## Firmware update images (OBCU) A field update is an OBCU container a client uploads as an update-package object. The byte format -is [`OBCU_Spec.md`](../specs/OBCU_Spec.md); the codec and boot decision live in `obc-dfu`, and the -producer is `obc-mkimage`. The pipeline is objcopy, then wrap and sign: +is [`obcu-update.md`](../specs/obcu-update.md); the codec and boot decision live in `obc-dfu`, and +the producer is `obc-mkimage`. The pipeline is objcopy, then wrap and sign: ```sh # From the board crate, whose .cargo/config.toml selects the nRF54L target. @@ -156,25 +156,24 @@ cargo run -p obc-mkimage -- wrap \ cargo run -p obc-mkimage -- inspect UPDATE.BIN ``` -`wrap` refuses an image over `MAX_IMAGE_LEN` and warns if the binary's first word is not a -plausible initial stack pointer, which usually means an ELF or a wrong section order slipped -through. +`wrap` refuses an image over `MAX_IMAGE_LEN`. It warns if the binary's first word is not a +plausible initial stack pointer, which usually means an ELF or a wrong section order. **Signing is not optional on the device.** Without a seed, `wrap` emits an unsigned container and the armer rejects it. `obc-mkimage sign` attaches the trailer to an already-wrapped container, so -an artifact can be built on one machine and signed on the one that holds the key; `keygen` makes a -keypair. Keys, the `OBCU_SIGNING_SEED` secret and the **rotation still owed before the first real -release** are in [`obc-dfu/keys/README.md`](obc-dfu/keys/README.md). +you can build an artifact on one machine and sign it on the one that holds the key; `keygen` makes +a keypair. Keys, the `OBCU_SIGNING_SEED` secret and the **rotation still owed before the first +real release** are in [`obc-dfu/keys/README.md`](obc-dfu/keys/README.md). To install, upload the container and confirm on the device, or trigger the armer over the debug -VCOM link ([board README](obc-fw-nrf54l/README.md#driving-it-from-a-host-debug-uart)). The armer +VCOM link ([board README](obc-fw-nrf54l/README.md#host-input-and-firmware-update)). The armer validates the object, writes the running image into a rollback reserve, arms the boot-state page and resets into `obc-boot` ([its README](obc-boot/README.md) has the LED codes). ## Terrain tiles (OBCT) `obc-dem` turns Copernicus GLO-30 GeoTIFF into the `.obcd` artifact carried beside a map -([`OBCT_Spec.md`](../specs/OBCT_Spec.md)). It has no native dependency. +([`obct-terrain.md`](../specs/obct-terrain.md)). It has no native dependency. ```sh # The tiles a box needs, from the AWS Open Data mirror (~44 MB each). @@ -197,14 +196,14 @@ the mix-up. `--posting-log2` and `--cell-log2` default to the v1 baked pairing. Both are OBCT header data, so a different pairing is a re-bake, not a format change. -`fetch` is the only thing that touches the network. A bake is a pure function of a tile directory -and a box, and byte-identical output for identical inputs is a contract pinned by a digest test. A -source void becomes `NODATA` and nothing is ever inpainted. +`fetch` is the only command that uses the network. A bake is a pure function of a tile directory +and a box: identical inputs give byte-identical output, and a digest test pins that contract. A +source void becomes `NODATA`; nothing is inpainted. Anything derived from GLO-30 must carry the Copernicus credit; `bake` prints it. Its single copy is the `copernicus-glo-30` entry of [`data/sources.toml`](../data/sources.toml). For a published catalog, use `obc bake terrain`, which drives this crate as a library over the -curated coverage (see the root [README](../README.md#baking-and-publishing-the-catalog)). The two -committed terrain sidecars are regenerated by -[`fixtures/build-map-package.sh terrain`](../fixtures/build-map-package.sh). +curated coverage (usage: the `bake` recipe in [`tools/justfile`](../tools/justfile), or +`just --show bake`). [`fixtures/build-map-package.sh terrain`](../fixtures/build-map-package.sh) +regenerates the two committed terrain sidecars. diff --git a/firmware/obc-app/src/trip.rs b/firmware/obc-app/src/trip.rs index de04662ad3..6c55448729 100644 --- a/firmware/obc-app/src/trip.rs +++ b/firmware/obc-app/src/trip.rs @@ -5,7 +5,7 @@ //! resident route [`Catalog`](crate::route::Catalog) into a [`TripSummary`]: the stage indices into //! the catalog, in ride order, plus the summed distance and climb over the resolvable stages. //! -//! A stage is a day: day `k` is `stage_ids[k]`. The day rules of `obc-ble-interface-spec.md` §7.7 +//! A stage is a day: day `k` is `stage_ids[k]`. The day rules of `ble-interface.md` §7.7 //! (next day, ticks, dates) read a [`TripSummary`] and the device's [`TripProgress`] for it. //! //! A route a stored trip references is filed and shows only inside its folder. A dangling ref diff --git a/firmware/obc-boot/README.md b/firmware/obc-boot/README.md index 0ba6f6db2d..e0e94fe3af 100644 --- a/firmware/obc-boot/README.md +++ b/firmware/obc-boot/README.md @@ -1,41 +1,14 @@ # obc-boot — the nRF54L bootloader -The 32 KB first-stage bootloader for the SD-staged DFU path. It reads the `BOOT_STATE` RRAM page, -decodes it with the shared [`obc-dfu`](../obc-dfu) crate, and runs `obc_dfu::engine`: an `Armed` -page verifies the staged image's CRC, flashes the app slot through RRAMC, verifies the readback, -writes `Trial` and jumps into the new image; a `Trial` still present at a later entry rolls back. -This crate only wires the card transport, RRAMC and GPIO into that engine (`src/semmc.rs`, -`src/install.rs`, `src/led.rs`). The byte formats and the boot decision table are normative in -[`OBCU_Spec.md`](../../specs/OBCU_Spec.md). +The 32 KB first-stage bootloader for the SD-staged DFU path. It decodes the `BOOT_STATE` RRAM page +with the shared [`obc-dfu`](../obc-dfu) crate and runs `obc_dfu::engine`. This crate only wires the +card transport, RRAMC and GPIO into that engine (`src/semmc.rs`, `src/install.rs`, `src/led.rs`). +The byte formats and the boot decision table are normative in +[`obcu-update.md`](../../specs/obcu-update.md). -The card transport is the sEMMC soft peripheral. The card exists only behind a ~13.6 KB -coprocessor image this crate cannot embed, so the app-side armer stages that image into the -`SEMMC_STAGE` RRAM carve before every arm and `src/semmc.rs` validates it before it boots it on -the FLPR. - -RRAM layout ([`memory.x`](memory.x), which must agree with `../obc-fw-nrf54l/build.rs`): - -| Address | Region | Size | -| --- | --- | ---: | -| `0x0000_0000` | `obc-boot` (this crate) | 32 KB | -| `0x0000_8000` | app slot (`obc-fw-nrf54l`) | 1976 KB | -| `0x001F_6000` | `SEMMC_STAGE` (the staged sEMMC blob) | 20 KB | -| `0x001F_B000` | `BOOT_STATE` page | 4 KB | -| `0x001F_C000` | `SETTINGS` page (the app's) | 4 KB | - -## LED codes (LED0 — the bootloader's entire UI) - -| Pattern | Meaning | -| :-- | :-- | -| one short pulse | proof of life on every entry, then the app boots | -| slow heartbeat | verifying the staged image; nothing is written yet | -| fast heartbeat | flashing the app slot and reading it back | -| 2 blinks, then boot | the arm was abandoned and the old app is intact: the staged image or the staged sEMMC blob failed verification, or the card stayed unreadable past the retry budget | -| 3 blinks, pause, repeat | the card is missing or reads are failing; retrying with backoff. Reinsert the card or power-cycle. A pre-erase `Armed` arm gives up after about a minute; a `Rollback` or a mid-flash error retries forever | -| SOS, forever | the readback never matched. Halted, still `Armed`, so a power cycle retries the install | - -The panel is not dark during an install: the app paints a static "Installing update" card as its -last frame, and `src/com.rs` keeps the memory-in-pixel glass alive with a software COM wave. +The card transport is the sEMMC soft peripheral, a ~13.6 KB coprocessor image this crate cannot +embed. The app-side armer stages it into the `SEMMC_STAGE` RRAM carve before every arm, and +`src/semmc.rs` validates it before it boots it on the FLPR. ## Build @@ -80,12 +53,11 @@ cd ../obc-fw-nrf54l && cargo run --release # app @ 0x8000 No LED blink and no boot means there is no bootloader at `0x0`. One blink and then nothing means there is no app at `0x8000`. -## Bring-up: the install path runs only on glass +## Test -The `Idle` fast path is the only path an ordinary boot takes, and no host test can run this crate -at all. The card, the FLPR, the RRAM writes, the trial boot and the rollback therefore have one -verification: a board. Run it after any change to `src/semmc.rs`, `src/install.rs` or the engine -wiring. +No host test can run this crate, and an ordinary boot takes only the `Idle` fast path. So only a +board verifies the card, the FLPR, the RRAM writes, the trial boot and the rollback. Run this +after any change to `src/semmc.rs`, `src/install.rs` or the engine wiring. 1. Build the app twice, with version strings that differ. Wrap and sign both with `obc-mkimage`. 2. Write the second container to the card as a kind-7 update object with the WebUSB client. @@ -107,7 +79,33 @@ wiring. A fault on this path leaves the `Armed` page behind, so every later boot repeats it. Reflash both images to recover. -## Constraints +## LED codes (LED0 — the bootloader's entire UI) + +| Pattern | Meaning | +| :-- | :-- | +| one short pulse | proof of life on every entry, then the app boots | +| slow heartbeat | verifying the staged image; nothing is written yet | +| fast heartbeat | flashing the app slot and reading it back | +| 2 blinks, then boot | the arm was abandoned and the old app is intact: the staged image or the staged sEMMC blob failed verification, or the card stayed unreadable past the retry budget | +| 3 blinks, pause, repeat | the card is missing or reads are failing; retrying with backoff. Reinsert the card or power-cycle. A pre-erase `Armed` arm gives up after about a minute; a `Rollback` or a mid-flash error retries forever | +| SOS, forever | the readback never matched. Halted, still `Armed`, so a power cycle retries the install | + +The panel is not dark during an install: the app paints a static "Installing update" card as its +last frame, and `src/com.rs` keeps the memory-in-pixel glass alive with a software COM wave. + +## RRAM layout + +[`memory.x`](memory.x) must agree with `../obc-fw-nrf54l/build.rs`. + +| Address | Region | Size | +| --- | --- | ---: | +| `0x0000_0000` | `obc-boot` (this crate) | 32 KB | +| `0x0000_8000` | app slot (`obc-fw-nrf54l`) | 1976 KB | +| `0x001F_6000` | `SEMMC_STAGE` (the staged sEMMC blob) | 20 KB | +| `0x001F_B000` | `BOOT_STATE` page | 4 KB | +| `0x001F_C000` | `SETTINGS` page (the app's) | 4 KB | + +## Pitfalls - The image must fit **32 KB** of flash. `firmware/tools/resource_guard.py boot` gates it in CI, against the default shape. The `rtt` feature must never be load-bearing for the budget. diff --git a/firmware/obc-boot/memory.x b/firmware/obc-boot/memory.x index 8e8b81fe65..7e7cfc1d80 100644 --- a/firmware/obc-boot/memory.x +++ b/firmware/obc-boot/memory.x @@ -5,7 +5,7 @@ * * 0x0000_0000 obc-boot 32 KB (this crate — FLASH below) * 0x0000_8000 app slot 1976 KB (the board crate, linked at 0x8000) - * 0x001F_6000 SEMMC_STAGE 20 KB (the armer-staged sEMMC blob — OBCU_Spec.md §3, read here) + * 0x001F_6000 SEMMC_STAGE 20 KB (the armer-staged sEMMC blob — obcu-update.md §3, read here) * 0x001F_B000 BOOT_STATE page 4 KB (the obc-dfu handoff page — read here) * 0x001F_C000 SETTINGS page 4 KB (the app's persistent settings, #193 — never ours) * @@ -29,8 +29,8 @@ MEMORY { FLASH : ORIGIN = 0x00000000, LENGTH = 32K - SEMMC_STAGE : ORIGIN = 0x001F6000, LENGTH = 20K /* armer-staged sEMMC blob (OBCU_Spec.md §3) */ - BOOT_STATE : ORIGIN = 0x001FB000, LENGTH = 4K /* boot-state handoff page (OBCU_Spec.md §2) */ + SEMMC_STAGE : ORIGIN = 0x001F6000, LENGTH = 20K /* armer-staged sEMMC blob (obcu-update.md §3) */ + BOOT_STATE : ORIGIN = 0x001FB000, LENGTH = 4K /* boot-state handoff page (obcu-update.md §2) */ RAM : ORIGIN = 0x20000000, LENGTH = 480K } @@ -38,7 +38,7 @@ MEMORY * (the magic address lives only in the linker script; main.rs reads the symbol). */ PROVIDE(__boot_state_base = ORIGIN(BOOT_STATE)); -/* Base of the blob-stage carve (#1158, OBCU_Spec.md §3) — where the armer left the sEMMC +/* Base of the blob-stage carve (#1158, obcu-update.md §3) — where the armer left the sEMMC * soft-peripheral image this bootloader boots the card through. Also the app slot's END: * the install engine's slot length is `__semmc_stage_base - __app_slot_base`, so nothing * the engine flashes can ever touch the carve. */ diff --git a/firmware/obc-dfu/keys/README.md b/firmware/obc-dfu/keys/README.md index 6b03883e86..b7c1c51b38 100644 --- a/firmware/obc-dfu/keys/README.md +++ b/firmware/obc-dfu/keys/README.md @@ -1,6 +1,6 @@ # OBCU update-signing keys -Ed25519 keys for the OBCU v2 update container ([`specs/OBCU_Spec.md`](../../../specs/OBCU_Spec.md) +Ed25519 keys for the OBCU v2 update container ([`specs/obcu-update.md`](../../../specs/obcu-update.md) §1.3). Every file here is one line of 64 lowercase hex characters (32 raw bytes) and a newline — what `obc-mkimage keygen` writes and [`obc_dfu::sig::hex32`](../src/sig.rs) parses at compile time. A malformed file is a build error. diff --git a/firmware/obc-dfu/src/armer.rs b/firmware/obc-dfu/src/armer.rs index 8593a86799..44b4df3045 100644 --- a/firmware/obc-dfu/src/armer.rs +++ b/firmware/obc-dfu/src/armer.rs @@ -7,7 +7,7 @@ //! the half that ships with every image (see [`crate::sig`]). //! //! The extent chain a [`StageIo`] resolves covers the whole staged object, header included, while -//! the [`StagedRef`]'s `len`/`crc32` stay raw-image values (`OBCU_Spec.md`). The install engine +//! the [`StagedRef`]'s `len`/`crc32` stay raw-image values (`obcu-update.md`). The install engine //! consumes it with the same skip arithmetic. use crate::crc32::Crc32; diff --git a/firmware/obc-dfu/src/blobstage.rs b/firmware/obc-dfu/src/blobstage.rs index faa6d5a6a2..7b4192136d 100644 --- a/firmware/obc-dfu/src/blobstage.rs +++ b/firmware/obc-dfu/src/blobstage.rs @@ -1,4 +1,4 @@ -//! The storage-blob stage carve (`OBCU_Spec.md`): how the bootloader gets the sEMMC +//! The storage-blob stage carve (`obcu-update.md`): how the bootloader gets the sEMMC //! soft-peripheral image that the card is only reachable through. //! //! The app ships that image in its own flash. The 32 KB bootloader cannot carry it, and it cannot diff --git a/firmware/obc-dfu/src/engine.rs b/firmware/obc-dfu/src/engine.rs index 9c5e80f8ab..73eaef1ff5 100644 --- a/firmware/obc-dfu/src/engine.rs +++ b/firmware/obc-dfu/src/engine.rs @@ -5,7 +5,7 @@ //! pattern and a jump, reset or halt. //! //! The armer resolves the whole staged object, so the extent chain reads as `64-byte OBCU -//! header ‖ raw image` (`OBCU_Spec.md`). Both passes skip the first [`HEADER_LEN`] bytes: the +//! header ‖ raw image` (`obcu-update.md`). Both passes skip the first [`HEADER_LEN`] bytes: the //! verify CRC covers the raw image only, and the flash pass writes the raw image to the app slot. //! //! Nothing writes the state page before the readback passes, so a torn install re-enters as diff --git a/firmware/obc-dfu/src/image.rs b/firmware/obc-dfu/src/image.rs index 9701fbb2f8..3b3dbbeed4 100644 --- a/firmware/obc-dfu/src/image.rs +++ b/firmware/obc-dfu/src/image.rs @@ -1,4 +1,4 @@ -//! The OBCU update-image container header (`OBCU_Spec.md`). +//! The OBCU update-image container header (`obcu-update.md`). //! //! An update image on the card is a fixed 64-byte header, the raw application image, and an //! optional signature trailer. The header carries the image length, a CRC-32 over the raw image, a diff --git a/firmware/obc-dfu/src/sig.rs b/firmware/obc-dfu/src/sig.rs index 7594e7e8ed..8e409bb20a 100644 --- a/firmware/obc-dfu/src/sig.rs +++ b/firmware/obc-dfu/src/sig.rs @@ -1,4 +1,4 @@ -//! OBCU v2 image signatures: Ed25519 over a domain-separated message (`OBCU_Spec.md`). +//! OBCU v2 image signatures: Ed25519 over a domain-separated message (`obcu-update.md`). //! //! The signed message is: //! diff --git a/firmware/obc-dfu/src/state.rs b/firmware/obc-dfu/src/state.rs index 739dac3b5b..568bb99558 100644 --- a/firmware/obc-dfu/src/state.rs +++ b/firmware/obc-dfu/src/state.rs @@ -1,4 +1,4 @@ -//! The boot-state RRAM handoff page and the bootloader's decision logic (`OBCU_Spec.md`). +//! The boot-state RRAM handoff page and the bootloader's decision logic (`obcu-update.md`). //! //! One CRC-framed blob in a dedicated 4 KB RRAM page, the only channel from the app (the armer) to //! the bootloader (the installer). Anything that does not decode cleanly is [`BootState::Idle`], so diff --git a/firmware/obc-dfu/tests/cases/boot_state.rs b/firmware/obc-dfu/tests/cases/boot_state.rs index 05825a95b0..5501ce36b3 100644 --- a/firmware/obc-dfu/tests/cases/boot_state.rs +++ b/firmware/obc-dfu/tests/cases/boot_state.rs @@ -1,5 +1,5 @@ //! Boot-state page codec and `decide()` contract tests. The byte layout they exercise is the -//! handoff between the bootloader and the app; keep it in step with `OBCU_Spec.md`. +//! handoff between the bootloader and the app; keep it in step with `obcu-update.md`. use obc_dfu::{ decide, verdict, BootDecision, BootState, Extent, ImageHeader, LastOutcome, OutcomeKind, StagedRef, Verdict, diff --git a/firmware/obc-formats/src/bike.rs b/firmware/obc-formats/src/bike.rs index deeefa445a..87d2adea42 100644 --- a/firmware/obc-formats/src/bike.rs +++ b/firmware/obc-formats/src/bike.rs @@ -1,4 +1,4 @@ -//! The four fixed bike types (`OBCR_Spec.md` §1.2, `OBCM_Spec.md` §8.6). +//! The four fixed bike types (`obcr-route.md` §1.2, `obcm-map.md` §8.6). //! //! The wire value is also the map's routing-profile index, so `BikeType as u8` is the profile //! the router uses. @@ -38,7 +38,7 @@ impl BikeType { } /// Flat-ground speed (km/h) and climb cost (tenths of a second per metre climbed): the - /// estimate table of `OBCR_Spec.md` §1.2. + /// estimate table of `obcr-route.md` §1.2. const fn eta_row(self) -> (u64, u64) { match self { BikeType::Road => (22, 16), diff --git a/firmware/obc-formats/src/obcm.rs b/firmware/obc-formats/src/obcm.rs index 394efcd2ff..4c5f4de64e 100644 --- a/firmware/obc-formats/src/obcm.rs +++ b/firmware/obc-formats/src/obcm.rs @@ -1,4 +1,4 @@ -//! OBCM map-format constants from `OBCM_Spec.md`. +//! OBCM map-format constants from `obcm-map.md`. use crate::io::{validate_prefix, DecodeError}; diff --git a/firmware/obc-formats/src/obcr.rs b/firmware/obc-formats/src/obcr.rs index bda22014a0..27b9dde9e4 100644 --- a/firmware/obc-formats/src/obcr.rs +++ b/firmware/obc-formats/src/obcr.rs @@ -1,4 +1,4 @@ -//! OBCR route-format constants from `OBCR_Spec.md`. +//! OBCR route-format constants from `obcr-route.md`. use crate::io::{validate_prefix, DecodeError}; diff --git a/firmware/obc-formats/src/ride.rs b/firmware/obc-formats/src/ride.rs index 7ef7b81491..461a4f7e27 100644 --- a/firmware/obc-formats/src/ride.rs +++ b/firmware/obc-formats/src/ride.rs @@ -69,7 +69,7 @@ impl Default for Name { } } -/// The trip day a ride started on (`obc-ble-interface-spec.md` §7.7 names the trip key). +/// The trip day a ride started on (`ble-interface.md` §7.7 names the trip key). #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub struct TripRef { /// Nonzero, so an `Option` costs no tag. diff --git a/firmware/obc-formats/src/trip_progress.rs b/firmware/obc-formats/src/trip_progress.rs index de924ba1e1..a5e06b1b8f 100644 --- a/firmware/obc-formats/src/trip_progress.rs +++ b/firmware/obc-formats/src/trip_progress.rs @@ -1,5 +1,5 @@ -//! The device's trip progress records (`obc-ble-interface-spec.md` §7.7). The Metadata singleton -//! holds them; `Ride_Archive_Metadata.md` has the bytes. +//! The device's trip progress records (`ble-interface.md` §7.7). The Metadata singleton +//! holds them; `ride-archive-metadata.md` has the bytes. use crate::io::{put_u32, rd_u16, rd_u32}; diff --git a/firmware/obc-fw-nrf54l/README.md b/firmware/obc-fw-nrf54l/README.md index 717d48838d..b1562f3b15 100644 --- a/firmware/obc-fw-nrf54l/README.md +++ b/firmware/obc-fw-nrf54l/README.md @@ -1,9 +1,9 @@ # obc-fw-nrf54l — nRF54LM20-DK firmware -`obc-app` runs on the nRF54LM20-DK. Maps, routes and rides use microSD. -The FLPR drives the LS021B7DD02 memory LCD. Check pins against -[`src/board.rs`](src/board.rs) and constructors against [`src/main.rs`](src/main.rs). -See the [display protocol](https://openbikecomputer.com/hardware/display-protocol/). +`obc-app` on the nRF54LM20-DK, with microSD storage and the LS021B7DD02 memory LCD on the FLPR. +Check pins against [`src/board.rs`](src/board.rs) and constructors against +[`src/main.rs`](src/main.rs). See the +[display protocol](https://openbikecomputer.com/hardware/display-protocol/). ## One-time board configuration @@ -13,87 +13,13 @@ each change; blue dots mean unwritten. Settings persist across power cycles. 1. **VDD / VDDM → 3.3 V.** The default 1.8 V is too low for panel logic. Feed panel `Vin` from 5 V / VBUS for its 3.3 V LDO. 2. **External memory → OFF.** This frees P2.00–P2.05 from QSPI for native SD. -3. **VCOM hardware flow control → OFF.** `debug-uart` never asserts RTS. - With HWFC on, telemetry works but injected fixes and buttons do not. - -## Full pin map - -**Port P2 — MCU/fast domain.** All 11 pins are used: the microSD bus and the panel's source bus, -two of them shared. The card's six pads are fixed by Nordic's sEMMC soft peripheral. - -| Pin | sEMMC | Display | Notes | -|-------|-------|---------|--------------------------------------------------------------| -| P2.00 | D3 | **B0** | shared — `CTRLSEL` per mode; internal pull-up in storage mode | -| P2.01 | CLK | — | card only; parked as an input in display mode | -| P2.02 | D0 | — | card only; parked as an input in display mode | -| P2.03 | D2 | — | card only; parked as an input in display mode | -| P2.04 | D1 | **B1** | shared — `CTRLSEL` per mode; internal pull-up in storage mode | -| P2.05 | CMD | — | card only; parked as an input in display mode | -| P2.06 | — | R0 | source data (even-`x` R) | -| P2.07 | — | BCK | source shift clock | -| P2.08 | — | R1 | source data (odd-`x` R) | -| P2.09 | — | G0 | source data (even-`x` G) | -| P2.10 | — | G1 | source data (odd-`x` G) | - -The packed wire word is `DATA_MASK = 0x751` (`B0`→0, `B1`→4, `R0`→6, `R1`→8, `G0`→9, `G1`→10). -`even`/`odd` is 0-based `x`, so the `*0` lines carry `x = 0, 2, 4, …`; the panel datasheet numbers -columns from 1 and calls that same line the *odd* column. - -**Pad configuration per mode** (`src/semmc.rs`, `configure_storage_pads` / `configure_display_pads`): - -| | the six card pads | the four card-only pads | -|---|---|---| -| **storage** | Output, input Disconnect, E0/E1 drive, `CTRLSEL = VPR`, `GPIOHSPADCTRL.BIAS = 2`; internal pull-up on `D3`/`D1` only | same — all six are the card's | -| **display** | `P2.00`/`P2.04` → Output, S drive, no pull, `CTRLSEL = GPIO`, `GPIOHSPADCTRL.BIAS = 2` | Input, no pull, `CTRLSEL = GPIO`; the external pull-ups hold the bus idle-high and the card stays inert | - -`GPIOHSPADCTRL.BIAS` is port-global, not per-pin, so both modes set the same constant 2 -(`semmc::HS_PAD_BIAS`). Only `D3`/`D1` get an internal pull-up, because this desk breakout carries -its own resistors on the rest. **The production board should fit external 10–100 kΩ pull-ups on -`CMD`/`DAT0–3` (none on `CLK`) and turn all internal pulls off.** - -**Port P1 — PERI domain, ≤8 MHz** (gate/BSP, sensors, COM, VCOM and buttons): - -| Pin | Signal | Notes | -|-------|--------------|-----------------------------------------------------------| -| P1.03 | I²C SCL | shared GPS + altimeter + compass bus (TWIM22) | -| P1.04 | I²C SDA | same bus | -| P1.05 | GPS TX-Ready | optional DDC data-ready IRQ (active-high) | -| P1.06 | unused PWM pad | held low; do not wire | -| P1.07 | unused PWM pad | held low; do not wire | -| P1.08 | BTN2 | BACK | -| P1.09 | BTN1 | DOWN | -| P1.10 | GSP | gate start pulse | -| P1.11 | GCK | gate clock | -| P1.12 | GEN | gate enable | -| P1.13 | INTB | frame envelope | -| P1.14 | BSP | source sub-line start (the lone P1 source line) | -| P1.16 | VCOM TX | UARTE20 → host (`debug-uart` builds only) | -| P1.17 | VCOM RX | UARTE20 ← host (`debug-uart` only; needs HWFC OFF) | -| P1.22 | VCOM (COM) | COM electrode, HighDrive | -| P1.23 | VB | COM electrode | -| P1.24 | VA | COM electrode (inverse phase) | -| P1.25 | LED1 | liveness heartbeat | -| P1.26 | BTN0 | UP | -| P1.27 | backlight | **PROVISIONAL** — PWM20 ch0, 1 kHz; also DK LED2 | - -**Ports P0 and P3:** - -| Pin | Signal | Notes | -|-------|---------|-------| -| P0.05 | BTN3 | SELECT; low-power domain | -| P3.00 | piezo A | **PROVISIONAL** — PWM21 ch0; header P5 | -| P3.01 | piezo B | **PROVISIONAL** — PWM21 ch1; header P5; wire a passive piezo between A and B, not to ground | - -**Schematic-time: the backlight gate needs an external pull-down.** P1.27 idles low, but only -after `PanelBacklight::new` has run (`src/panel_power.rs`). Before that, and through all of -`obc-boot`, the pin is input, no pull, high impedance, and System OFF stops the PWM wherever the -waveform left the line. A floating MOSFET gate is not a defined lamp state. +3. **VCOM hardware flow control → OFF.** With HWFC on, telemetry works but injected fixes and + buttons do not. ## Build and flash Flash [`obc-boot`](../obc-boot/README.md) first: run `obc flash-boot` from the -checkout root, or `cargo run --release` in `../obc-boot`. The app starts at -`0x8000`, above the bootloader's 32 KB. Without it, the device never boots. +checkout root, or `cargo run --release` in `../obc-boot`. Without it, the device never boots. App flashes preserve it. Builds need an `rv32emc` GNU compiler: `brew install riscv64-elf-gcc`, the apt @@ -104,9 +30,8 @@ Select a probe with `PROBE_RS_PROBE=VID:PID:SERIAL`. BLE and USB are enabled. `obc flash factory-demo-ride` over J4 writes the Grimsel Pass demo as a ride, dated 1 January of the current production year, with synthetic sensors. Wait for `factory demo ride: complete`, stop the probe, then run `obc flash`. -The factory image stays idle. Normal firmware never seeds rides. -Existing objects stay. Unformatted cards, active recordings and conflicting names -are refused. Set `OBC_DEMO_RIDE_FILE` to an absolute path for another marked demo. +Normal firmware never seeds rides. Existing objects stay. Unformatted cards, active recordings +and conflicting names are refused. Set `OBC_DEMO_RIDE_FILE` to an absolute path for another marked demo. | Feature | Purpose | | --- | --- | @@ -115,12 +40,51 @@ are refused. Set `OBC_DEMO_RIDE_FILE` to an absolute path for another marked dem | `resource-report` | `.obc_resources` for the resource guard; never flash or package this diagnostic image. | | `flat-store-reset` | Destructive `flat_store_bench` maintenance mode. | +## Host input and firmware update + +Flash `debug-uart` and disable VCOM HWFC. From the repository root: + +```sh +obc flash debug-uart +obc uart # optional: path/to/ride.gpx +obc debug # flash and open the feeder +``` + +The feeder sends buttons and sensor values, and displays telemetry. +`--list` shows serial ports. Disconnect J3 if the test also needs BLE. +On macOS, use `cu.usbmodem*133`, not `*131` or `tty.*`. Use pyserial; +`stty` with `printf` or `cat` loses termios settings across opens. + +For a [signed update package](../README.md#firmware-update-images-obcu) in the store, send +`dfu-install\n` to the live CDC port and read the `D` status lines: + +```sh +uv venv /tmp/dfu-venv && uv pip install --python /tmp/dfu-venv/bin/python pyserial +/tmp/dfu-venv/bin/python -c "import serial; p = serial.Serial('/dev/cu.usbmodem<...>133', 115200, \ + rtscts=False, timeout=90); p.write(b'dfu-install\n'); [print(p.readline()) for _ in range(40)]" +``` + +The device resets into `obc-boot` to install it; see its README for LED codes. +Unsigned packages and triggers during recording are refused. If VCOM returns +nothing and RTT has no `dfu:` line, power-cycle the DK to clear the CDC bridge. + +## Flat store bench + +```sh +cargo run --release --bin flat_store_bench +cargo run --release --bin flat_store_bench --features flat-store-reset +``` + +**Both commands destroy the partition table and every object from raw LBA 0.** +The bench refuses another `StoreId` unless `FORCE_REINIT` overrides it. +See the [bench module](src/bin/flat_store_bench.rs) for phases and output. + ## Display and microSD -The M33 renders one 240 × 320 RGB222 plane and sends up to 16 dirty-row spans to -the FLPR. [`flpr_scan.c`](src/flpr/flpr_scan.c) owns panel timing. -`build.rs` generates the memory layout, linker script and shared constants. -Never commit a crate-root `memory.x`: it overrides the generated layout. +The M33 renders one 240 × 320 RGB222 plane and sends up to 16 dirty-row spans to the FLPR. +[`flpr_scan.c`](src/flpr/flpr_scan.c) owns panel timing. `build.rs` generates the memory layout, +linker script and shared constants. Never commit a crate-root `memory.x`: it overrides the +generated layout. The pin ledger, scan masks and physical FPC harness must agree. If a gate line stays dark, check that the DK header exposes it before remapping all three. @@ -151,15 +115,14 @@ Wire `V_BCKP` to an always-on rail, supercap or coin cell to preserve RTC and ephemeris for warm fixes. Acquisition runs for up to 150 s at boot; then GPS power follows recording. -Indefinite software standby needs receiver power removal; I²C traffic cannot wake it. -The firmware uses controlled stop while idle and START at startup, so its standby -recovers on an MCU reset. See the +I²C traffic cannot wake the receiver from indefinite software standby, so the firmware uses +controlled stop while idle and START at startup; an MCU reset recovers it. See the [SAM-M10Q integration manual](https://content.u-blox.com/sites/default/files/documents/SAM-M10Q_IntegrationManual_UBX-22020019.pdf), sections 3.3 and 3.5.3.3. ## BLE -See the [BLE contract](../../specs/obc-ble-interface-spec.md) and -[object protocol](../../specs/FLAT_Store_Protocol.md). +See the [BLE contract](../../specs/ble-interface.md) and +[object protocol](../../specs/flat-store-protocol.md). - Use the internal LF RC clock with MPSL calibration. `ExternalXtal` connections fail with HCI `0x3E` unless the DK's `OSCILLATORS` INTCAP registers are set @@ -169,18 +132,17 @@ See the [BLE contract](../../specs/obc-ble-interface-spec.md) and - Settings and one bond slot live in RRAM above the image and survive reflashes. An occupied slot refuses new pairings. Clear it with **Forget phone** in Settings → Connections, or a factory reset. -- DIS reports the installed OBCU version, or the build's git hash. Hosts do not - offer automatic updates to probe-flashed images that report a hash. +- DIS reports a git hash for a probe-flashed image, so hosts offer it no automatic update + (`ble-interface.md` §3.1). - Build large async values in `.bss` statics with `#[inline(never)]` initializers to avoid permanent poll-frame slots. CI and MSPLIM guard their size. ## Native USB J3 is the SoC USB connector; J4 is the debugger and VCOM. Use both cables. -USBHS needs AHB ≥ 30 MHz; this board uses 128 MHz. VBUS gates core access, -and VREGUSB wakes the task without polling when J3 is empty. -The vendored USB driver arms bulk OUT in bursts. Changing -`BULK_OUT_BURST_PACKETS` in `src/usb/mod.rs` changes RAM use. +USBHS needs AHB ≥ 30 MHz; this board uses 128 MHz. VBUS gates core access; VREGUSB interrupts +wake the task when J3 is empty. `BULK_OUT_BURST_PACKETS` in `src/usb/mod.rs` sets the bulk OUT +burst and so the RAM use. Prototype VID/PID is `1209:0001`. MS OS 2.0 descriptors bind WinUSB on Windows. ### Bring-up @@ -202,6 +164,86 @@ Prototype VID/PID is `1209:0001`. MS OS 2.0 descriptors bind WinUSB on Windows. | Plug is not detected | Both VREGUSB interrupt handlers remain bound. | | Enumeration at 12 Mb/s | Full-speed fallback; 512 B bulk descriptors are invalid. | +## Peak View + +The menu appears when the selected map (lowest-ID Map object) has indexed terrain. +See [simulator controls](../../sim/desktop/README.md). Generation uses the shared +128 KiB scratch arena; Back must release it before navigation, rendering or USB. +`obc-bake bake` writes the surface index. Convert standalone native terrain with +`obc-dem surface native.obcd indexed.obcd`. + +## Full pin map + +**Port P2 — MCU/fast domain.** The sEMMC soft peripheral fixes the card's six pads. + +| Pin | sEMMC | Display | Notes | +|-------|-------|---------|--------------------------------------------------------------| +| P2.00 | D3 | **B0** | shared — `CTRLSEL` per mode; internal pull-up in storage mode | +| P2.01 | CLK | — | card only; parked as an input in display mode | +| P2.02 | D0 | — | card only; parked as an input in display mode | +| P2.03 | D2 | — | card only; parked as an input in display mode | +| P2.04 | D1 | **B1** | shared — `CTRLSEL` per mode; internal pull-up in storage mode | +| P2.05 | CMD | — | card only; parked as an input in display mode | +| P2.06 | — | R0 | source data (even-`x` R) | +| P2.07 | — | BCK | source shift clock | +| P2.08 | — | R1 | source data (odd-`x` R) | +| P2.09 | — | G0 | source data (even-`x` G) | +| P2.10 | — | G1 | source data (odd-`x` G) | + +The packed wire word is `DATA_MASK = 0x751` (`B0`→0, `B1`→4, `R0`→6, `R1`→8, `G0`→9, `G1`→10). +`even`/`odd` is 0-based `x`, so the `*0` lines carry `x = 0, 2, 4, …`; the panel datasheet numbers +columns from 1 and calls that same line the *odd* column. + +**Pad configuration per mode** (`src/semmc.rs`, `configure_storage_pads` / `configure_display_pads`): + +| | the six card pads | the four card-only pads | +|---|---|---| +| **storage** | Output, input Disconnect, E0/E1 drive, `CTRLSEL = VPR`, `GPIOHSPADCTRL.BIAS = 2`; internal pull-up on `D3`/`D1` only | same — all six are the card's | +| **display** | `P2.00`/`P2.04` → Output, S drive, no pull, `CTRLSEL = GPIO`, `GPIOHSPADCTRL.BIAS = 2` | Input, no pull, `CTRLSEL = GPIO`; the external pull-ups hold the bus idle-high and the card stays inert | + +`GPIOHSPADCTRL.BIAS` is port-global, not per-pin, so both modes set the same constant 2 +(`semmc::HS_PAD_BIAS`). Only `D3`/`D1` get an internal pull-up, because this desk breakout carries +its own resistors on the rest. **The production board should fit external 10–100 kΩ pull-ups on +`CMD`/`DAT0–3` (none on `CLK`) and turn all internal pulls off.** + +**Port P1 — PERI domain, ≤8 MHz** (gate/BSP, sensors, COM, VCOM and buttons): + +| Pin | Signal | Notes | +|-------|--------------|-----------------------------------------------------------| +| P1.03 | I²C SCL | shared GPS + altimeter + compass bus (TWIM22) | +| P1.04 | I²C SDA | same bus | +| P1.05 | GPS TX-Ready | optional DDC data-ready IRQ (active-high) | +| P1.06 | unused PWM pad | held low; do not wire | +| P1.07 | unused PWM pad | held low; do not wire | +| P1.08 | BTN2 | BACK | +| P1.09 | BTN1 | DOWN | +| P1.10 | GSP | gate start pulse | +| P1.11 | GCK | gate clock | +| P1.12 | GEN | gate enable | +| P1.13 | INTB | frame envelope | +| P1.14 | BSP | source sub-line start (the lone P1 source line) | +| P1.16 | VCOM TX | UARTE20 → host (`debug-uart` builds only) | +| P1.17 | VCOM RX | UARTE20 ← host (`debug-uart` only; needs HWFC OFF) | +| P1.22 | VCOM (COM) | COM electrode, HighDrive | +| P1.23 | VB | COM electrode | +| P1.24 | VA | COM electrode (inverse phase) | +| P1.25 | LED1 | liveness heartbeat | +| P1.26 | BTN0 | UP | +| P1.27 | backlight | **PROVISIONAL** — PWM20 ch0, 1 kHz; also DK LED2 | + +**Ports P0 and P3:** + +| Pin | Signal | Notes | +|-------|---------|-------| +| P0.05 | BTN3 | SELECT; low-power domain | +| P3.00 | piezo A | **PROVISIONAL** — PWM21 ch0; header P5 | +| P3.01 | piezo B | **PROVISIONAL** — PWM21 ch1; header P5; wire a passive piezo between A and B, not to ground | + +**Schematic-time: the backlight gate needs an external pull-down.** P1.27 idles low, but only +after `PanelBacklight::new` has run (`src/panel_power.rs`). Before that, and through all of +`obc-boot`, the pin is input, no pull, high impedance, and System OFF stops the PWM wherever the +waveform left the line. + ## Board connection and recovery `obc board doctor` reports probes, serial owners and USB enumeration on macOS @@ -226,50 +268,3 @@ resetting. Use the exact installed ELF, features and `DEFMT_LOG` for decoding. | J3 does not enumerate | Check native cable, VID/PID and RTT VBUS lines. J4 serial does not prove native USB works. | | J3 enumerates but connection fails | Close the desktop or browser interface owner, then reconnect. | | Restart and capture boot logs | `obc board run ELF --preverify` verifies, resets and streams RTT. It programs only if the installed image differs. `--preverify` applies to `run` and `download`. | - -## Host input and firmware update - -Flash `debug-uart` and disable VCOM HWFC. From the repository root: - -```sh -obc flash debug-uart -obc uart # optional: path/to/ride.gpx -obc debug # flash and open the feeder -``` - -The feeder sends buttons and sensor values, and displays telemetry. -`--list` shows serial ports. Disconnect J3 if the test also needs BLE. -On macOS, use `cu.usbmodem*133`, not `*131` or `tty.*`. Use pyserial; -`stty` with `printf` or `cat` loses termios settings across opens. - -For a [signed update package](../README.md) in the store, send `dfu-install\n` -to the live CDC port and read the `D` status lines: - -```sh -uv venv /tmp/dfu-venv && uv pip install --python /tmp/dfu-venv/bin/python pyserial -/tmp/dfu-venv/bin/python -c "import serial; p = serial.Serial('/dev/cu.usbmodem<...>133', 115200, \ - rtscts=False, timeout=90); p.write(b'dfu-install\n'); [print(p.readline()) for _ in range(40)]" -``` - -The device resets into `obc-boot` to install it; see its README for LED codes. -Unsigned packages and triggers during recording are refused. If VCOM returns -nothing and RTT has no `dfu:` line, power-cycle the DK to clear the CDC bridge. - -## Flat store bench - -```sh -cargo run --release --bin flat_store_bench -cargo run --release --bin flat_store_bench --features flat-store-reset -``` - -**Both commands destroy the partition table and every object from raw LBA 0.** -The bench refuses another `StoreId` unless `FORCE_REINIT` overrides it. -See the [bench module](src/bin/flat_store_bench.rs) for phases and output. - -## Peak View - -The menu appears when the selected map (lowest-ID Map object) has indexed terrain. -See [simulator controls](../../sim/desktop/README.md). Generation uses the shared -128 KiB scratch arena; Back must release it before navigation, rendering or USB. -`obc-bake bake` writes the surface index. Convert standalone native terrain with -`obc-dem surface native.obcd indexed.obcd`. diff --git a/firmware/obc-fw-nrf54l/build.rs b/firmware/obc-fw-nrf54l/build.rs index 9a05d0db0d..6f59974e61 100644 --- a/firmware/obc-fw-nrf54l/build.rs +++ b/firmware/obc-fw-nrf54l/build.rs @@ -130,8 +130,8 @@ fn flpr_memory_x() -> String { MEMORY {{ FLASH : ORIGIN = {APP_SLOT_BASE:#010X}, LENGTH = {app_len:#X} /* app slot ({app_kb}K) above the 32K obc-boot (#617) */ - SEMMC_STAGE : ORIGIN = {SEMMC_STAGE_BASE:#010X}, LENGTH = {stage_kb}K /* staged sEMMC blob — armer→boot handoff (#1158, OBCU_Spec.md §3) */ - BOOT_STATE : ORIGIN = {BOOT_STATE_BASE:#010X}, LENGTH = 4K /* DFU boot-state handoff page (#617, OBCU_Spec.md §2) */ + SEMMC_STAGE : ORIGIN = {SEMMC_STAGE_BASE:#010X}, LENGTH = {stage_kb}K /* staged sEMMC blob — armer→boot handoff (#1158, obcu-update.md §3) */ + BOOT_STATE : ORIGIN = {BOOT_STATE_BASE:#010X}, LENGTH = 4K /* DFU boot-state handoff page (#617, obcu-update.md §2) */ SETTINGS : ORIGIN = {SETTINGS_BASE:#010X}, LENGTH = 4K /* persistent settings page (#193) — top of RRAM */ RAM : ORIGIN = {SRAM_BASE:#010X}, LENGTH = {ram_kb}K /* M33 .data/.bss/stack */ /* Reserved for the FLPR (not linked by the M33; see the generated flpr.ld): @@ -144,7 +144,7 @@ PROVIDE(__settings_base = ORIGIN(SETTINGS)); /* Base of the carved boot-state page: the armer's write target. */ PROVIDE(__boot_state_base = ORIGIN(BOOT_STATE)); /* Base of the blob-stage carve, where the armer copies the sEMMC image for the - bootloader's Install/Rollback card bring-up (OBCU_Spec.md §3). */ + bootloader's Install/Rollback card bring-up (obcu-update.md §3). */ PROVIDE(__semmc_stage_base = ORIGIN(SEMMC_STAGE)); /* Base of the app slot, where the armer's rollback snapshot reads the running image from (memory-mapped; RRAM is XIP-readable). The linker map stays the only address authority. */ diff --git a/firmware/obc-fw-nrf54l/src/bin/flat_store_bench.rs b/firmware/obc-fw-nrf54l/src/bin/flat_store_bench.rs index 97f431f8af..5a50d507b7 100644 --- a/firmware/obc-fw-nrf54l/src/bin/flat_store_bench.rs +++ b/firmware/obc-fw-nrf54l/src/bin/flat_store_bench.rs @@ -2,7 +2,7 @@ //! //! cargo run --release --bin flat_store_bench //! -//! `FLAT_Store_Format.md` states five figures that only the board can check: a first boot "well +//! `flat-store-format.md` states five figures that only the board can check: a first boot "well //! under a second", a mount "about 100 ms", a commit "about 15-20 ms at a few hundred entries", a //! read path that is arithmetic rather than a chain walk, and a resident cost of the 8 KiB free //! bitmap plus the ride tail. This binary measures each of them against a card in the slot. It is diff --git a/firmware/obc-fw-nrf54l/src/ble/gatt.rs b/firmware/obc-fw-nrf54l/src/ble/gatt.rs index e3f59fbb4e..5ed3a99bb5 100644 --- a/firmware/obc-fw-nrf54l/src/ble/gatt.rs +++ b/firmware/obc-fw-nrf54l/src/ble/gatt.rs @@ -63,8 +63,8 @@ pub(crate) struct ObcControlService { /// at boot, re-seeded canonical after every accepted write. #[characteristic(uuid = "3C920004-9916-4EBA-ABC2-342FE08F6B10", read, write, permissions(authenticated))] pub config: heapless09::Vec, - /// The L2CAP CoC PSM the app opens the channel on — protocol v4's stream channel, one complete - /// stream frame per SDU. + /// The L2CAP CoC PSM the app opens the channel on — protocol v4's stream channel. It is a byte + /// stream: a stream frame can span SDUs, and each frame's header sets its length. #[characteristic(uuid = "3C920007-9916-4EBA-ABC2-342FE08F6B10", read, permissions(authenticated), value = OBC_PSM)] pub psm: u16, /// `protocolVersion` — read without encryption, because a peer reads the transport version diff --git a/firmware/obc-link/src/flat/engine.rs b/firmware/obc-link/src/flat/engine.rs index 1a6aca231d..43183de548 100644 --- a/firmware/obc-link/src/flat/engine.rs +++ b/firmware/obc-link/src/flat/engine.rs @@ -1,4 +1,4 @@ -//! The transfer engine for `FLAT_Store_Protocol.md`: one state machine, both links. +//! The transfer engine for `flat-store-protocol.md`: one state machine, both links. //! //! It owns no transport and no medium. A record comes in, a [`Reaction`] names the bytes to send, //! and every card access goes through [`Store`]. An adapter hands the engine whole records and then @@ -1367,7 +1367,7 @@ mod tests { assert_eq!(commit_refusal(StoreError::Invalid, 0).code, ErrorCode::Internal); } - /// The detail is what a client's retry policy reads, and `FLAT_Store_Protocol.md` freezes it. + /// The detail is what a client's retry policy reads, and `flat-store-protocol.md` freezes it. #[test] fn a_full_hold_table_is_busy_with_the_holds_detail() { assert_eq!(open_refusal(StoreError::Busy), Refusal::new(ErrorCode::Busy, detail::busy::HOLDS)); diff --git a/firmware/obc-link/src/flat/ids.rs b/firmware/obc-link/src/flat/ids.rs index 98a50672c5..23aa663abd 100644 --- a/firmware/obc-link/src/flat/ids.rs +++ b/firmware/obc-link/src/flat/ids.rs @@ -1,7 +1,7 @@ //! The vocabulary both sides of the engine speak: three identities, the kind table, the entry //! flags, a display name, and the metadata half of a catalog entry. //! -//! `FLAT_Store_Format.md` is the authority for every value here. The types are declared in this +//! `flat-store-format.md` is the authority for every value here. The types are declared in this //! crate rather than imported from the store, because the dependency runs the other way (see //! [`super::store`]), and the binder's pinning test holds the two definitions equal. @@ -40,7 +40,7 @@ impl Revision { } } -/// The kind table of `FLAT_Store_Format.md`, carried unchanged on the wire. +/// The kind table of `flat-store-format.md`, carried unchanged on the wire. #[derive(Debug, Clone, Copy, PartialEq, Eq)] #[repr(u16)] pub enum ObjectKind { diff --git a/firmware/obc-link/src/flat/mod.rs b/firmware/obc-link/src/flat/mod.rs index 2da5363a38..1f77c08364 100644 --- a/firmware/obc-link/src/flat/mod.rs +++ b/firmware/obc-link/src/flat/mod.rs @@ -1,14 +1,14 @@ //! The wire the flat store speaks, and the one engine that speaks it. //! -//! [`FLAT_Store_Protocol.md`] is the normative contract and [`FLAT_Store_Format.md`] is what the +//! [`flat-store-protocol.md`] is the normative contract and [`flat-store-format.md`] is what the //! card holds. Nothing here is negotiated: every version is a fixed fact and every message is a //! fixed layout. //! //! [`ids`] is the vocabulary, [`wire`] is the bytes, [`store`] is the seam declared from the side //! that consumes it, and [`engine`] sits on both. //! -//! [`FLAT_Store_Protocol.md`]: ../../../../specs/FLAT_Store_Protocol.md -//! [`FLAT_Store_Format.md`]: ../../../../specs/FLAT_Store_Format.md +//! [`flat-store-protocol.md`]: ../../../../specs/flat-store-protocol.md +//! [`flat-store-format.md`]: ../../../../specs/flat-store-format.md pub mod engine; pub mod ids; pub mod records; diff --git a/firmware/obc-link/src/flat/vectors.rs b/firmware/obc-link/src/flat/vectors.rs index 07754206c5..968ce43573 100644 --- a/firmware/obc-link/src/flat/vectors.rs +++ b/firmware/obc-link/src/flat/vectors.rs @@ -1,6 +1,6 @@ //! The spec-derived fixture producer for `specs/vectors/flat-store-v4/`. //! -//! Every byte below is laid down by hand, at the offset `FLAT_Store_Protocol.md` states, through the +//! Every byte below is laid down by hand, at the offset `flat-store-protocol.md` states, through the //! [`raw`] helpers and never through [`super::wire`]. A golden vector a codec produced proves only //! that the codec agrees with itself; here the two sides share the specification alone, and the //! tests in [`tests`] close the loop in both directions. diff --git a/firmware/obc-link/src/flat/wire.rs b/firmware/obc-link/src/flat/wire.rs index 18bb0086b5..8bfe0e33cc 100644 --- a/firmware/obc-link/src/flat/wire.rs +++ b/firmware/obc-link/src/flat/wire.rs @@ -1,7 +1,7 @@ //! The protocol's bytes: the control frame, the nine request bodies, the response bodies, the //! stream frame and the error body. //! -//! `FLAT_Store_Protocol.md` is the sole authority and every offset below is transcribed from its +//! `flat-store-protocol.md` is the sole authority and every offset below is transcribed from its //! tables. Decoding is total: an input is either a typed message or a typed [`Refusal`], and //! nothing here panics on hostile bytes. Encoding writes into a caller-provided slice and reports //! the length; nothing is allocated. diff --git a/firmware/obc-link/src/lib.rs b/firmware/obc-link/src/lib.rs index 64d34c5af7..b32e8f0a25 100644 --- a/firmware/obc-link/src/lib.rs +++ b/firmware/obc-link/src/lib.rs @@ -1,6 +1,6 @@ //! The protocol-v4 codec, device engine and optional host client. //! -//! [`flat`] implements the [`FLAT store protocol`](../../../specs/FLAT_Store_Protocol.md): +//! [`flat`] implements the [`FLAT store protocol`](../../../specs/flat-store-protocol.md): //! control and stream records, the store seam, and one transport-free transfer engine. //! The device codec and engine are allocation-free. Host-only fixture production is enabled by //! `std`; `client` enables the transport-free host client with owned records and catalog results. diff --git a/firmware/obc-link/tests/flat_break_matrix.rs b/firmware/obc-link/tests/flat_break_matrix.rs index 1cd234c022..9bb9f7fc76 100644 --- a/firmware/obc-link/tests/flat_break_matrix.rs +++ b/firmware/obc-link/tests/flat_break_matrix.rs @@ -1,6 +1,6 @@ //! The break matrix: every opcode flow, cut at every protocol step boundary. //! -//! It discharges one obligation of `FLAT_Store_Protocol.md`: any break before the commit leaves the +//! It discharges one obligation of `flat-store-protocol.md`: any break before the commit leaves the //! card as if nothing happened. Each flow is run once to the end to establish the card after it, //! then run again for every prefix of its records with the link torn down at that point. Three //! things must then hold: diff --git a/firmware/obc-link/tests/flat_engine.rs b/firmware/obc-link/tests/flat_engine.rs index 699d0bb828..19b274bf61 100644 --- a/firmware/obc-link/tests/flat_engine.rs +++ b/firmware/obc-link/tests/flat_engine.rs @@ -1,4 +1,4 @@ -//! The engine against a real flat store: one behaviour per rule of `FLAT_Store_Protocol.md`. +//! The engine against a real flat store: one behaviour per rule of `flat-store-protocol.md`. //! //! The card underneath is the sim-backed [`FlatStore`](obc_storage::flat::FlatStore), so a claim //! about the catalog here is a claim about the bytes on a card. diff --git a/firmware/obc-link/tests/flat_harness/mod.rs b/firmware/obc-link/tests/flat_harness/mod.rs index 3e55805149..c80bfd0f92 100644 --- a/firmware/obc-link/tests/flat_harness/mod.rs +++ b/firmware/obc-link/tests/flat_harness/mod.rs @@ -5,7 +5,7 @@ //! The device is the assembly the browser's tests run on too, so a behaviour proved here is proved //! against the same engine and the same card. The harness is what only a Rust test wants: a pump //! that collects every record of one exchange into a [`Wire`], store probes, and request bytes -//! written at the offsets `FLAT_Store_Protocol.md` states. The device never encodes a request, so +//! written at the offsets `flat-store-protocol.md` states. The device never encodes a request, so //! writing those bytes by hand keeps the tests honest about what a phone would send. #![allow(dead_code)] @@ -300,7 +300,7 @@ impl obc_formats::io::ByteSink for VecSink { use obc_storage::flat::seam::Store; -/// Request bytes, written at the offsets `FLAT_Store_Protocol.md` states. +/// Request bytes, written at the offsets `flat-store-protocol.md` states. pub mod client { use super::*; diff --git a/firmware/obc-route/src/eta.rs b/firmware/obc-route/src/eta.rs index bcf5001df2..754c0f8ea0 100644 --- a/firmware/obc-route/src/eta.rs +++ b/firmware/obc-route/src/eta.rs @@ -1,6 +1,6 @@ //! Time to go along a route: the ride's ETA and TIME TO GO tiles. //! -//! The estimate itself is [`BikeType::ride_time_s`], the contract table of `OBCR_Spec.md` §1.2 +//! The estimate itself is [`BikeType::ride_time_s`], the contract table of `obcr-route.md` §1.2 //! that the phone shares. This module only feeds it the remaining distance and the remaining //! ascent from [`Profile::ascent_between_m`], the curve the elevation profile already builds. diff --git a/firmware/obc-route/src/lib.rs b/firmware/obc-route/src/lib.rs index 783d7fda73..8d391d6274 100644 --- a/firmware/obc-route/src/lib.rs +++ b/firmware/obc-route/src/lib.rs @@ -2,7 +2,7 @@ //! //! `no_std`, so the same code runs in the desktop simulator and in the nRF firmware. A route is a //! single ordered polyline with per-point elevation plus precomputed ride stats. The on-disk -//! layout is specified in `OBCR_Spec.md`. +//! layout is specified in `obcr-route.md`. //! //! The elevation dead-band that every module here integrates through lives in [`obc_elevation`], //! not in this crate. One home for the hysteresis keeps the packer's ascent, the profile's climb diff --git a/firmware/obc-route/src/reader.rs b/firmware/obc-route/src/reader.rs index 61978ab1dd..58d0962f92 100644 --- a/firmware/obc-route/src/reader.rs +++ b/firmware/obc-route/src/reader.rs @@ -70,7 +70,7 @@ pub struct RoutePosition { } /// One chunk's index entry: its bbox, the absolute anchor it decodes from, and the cumulative -/// stats at its first point. See `OBCR_Spec.md`. +/// stats at its first point. See `obcr-route.md`. #[derive(Debug, Clone, Copy)] pub struct ChunkMeta { pub bbox: BBox, @@ -873,7 +873,7 @@ pub(crate) fn for_each_stored_point( /// One stored route waypoint as it sits on disk, every field included. The ride geometry path /// skips the section; [`RouteReader::load_waypoints`] distils the named ones into the resident -/// [`Waypoints`] table the UI reads. See `OBCR_Spec.md`. +/// [`Waypoints`] table the UI reads. See `obcr-route.md`. #[derive(Debug, Clone, PartialEq, Eq)] pub struct Waypoint { /// Distance from the route start to this waypoint's position, meters. diff --git a/firmware/obc-route/src/symbol.rs b/firmware/obc-route/src/symbol.rs index 21e33e3b5b..1b93485358 100644 --- a/firmware/obc-route/src/symbol.rs +++ b/firmware/obc-route/src/symbol.rs @@ -1,4 +1,4 @@ -//! The canonical GPX symbol to [`PoiCategory`] mapping. `OBCR_Spec.md` mirrors it row for row. +//! The canonical GPX symbol to [`PoiCategory`] mapping. `obcr-route.md` mirrors it row for row. //! //! A GPX `` carries its icon as freeform text in `` or ``. There is no registry, //! so this table is a curation read off real exports, not a standard. diff --git a/firmware/obc-route/src/trip.rs b/firmware/obc-route/src/trip.rs index 97b3b6d7ec..935d7cf543 100644 --- a/firmware/obc-route/src/trip.rs +++ b/firmware/obc-route/src/trip.rs @@ -1,6 +1,6 @@ //! The trip object: the phone-authored metadata object that describes a trip's days. A trip //! references one route object per day, in ride order, and holds no route bytes. The layout is in -//! `obc-ble-interface-spec.md` §7.7 and pinned by `specs/vectors/trip-v3.bin`. +//! `ble-interface.md` §7.7 and pinned by `specs/vectors/trip-v3.bin`. //! //! The object length is fully determined by the header: `64 + 16·day_count` bytes. A decoder //! rejects a payload of any other length with [`Error::BadOffset`], which is also the torn-write diff --git a/firmware/obc-route/tests/cases/format.rs b/firmware/obc-route/tests/cases/format.rs index e9eea0a492..d49f891020 100644 --- a/firmware/obc-route/tests/cases/format.rs +++ b/firmware/obc-route/tests/cases/format.rs @@ -1,7 +1,7 @@ //! Format-contract tests for the OBCR reader. //! //! Each test builds a synthetic `.obcr` byte buffer with the shared handwritten builder, which -//! mirrors `OBCR_Spec.md`, then asserts the reader parses it back. Hand-emitting the bytes instead +//! mirrors `obcr-route.md`, then asserts the reader parses it back. Hand-emitting the bytes instead //! of going through the converter pins the reader to the spec independently. use core::cell::Cell; diff --git a/firmware/obc-route/tests/cases/waypoints.rs b/firmware/obc-route/tests/cases/waypoints.rs index b2b54f2109..558d558817 100644 --- a/firmware/obc-route/tests/cases/waypoints.rs +++ b/firmware/obc-route/tests/cases/waypoints.rs @@ -1,4 +1,4 @@ -//! OBCR waypoint-section tests: the hand-built format contract from `OBCR_Spec.md`, the converter's +//! OBCR waypoint-section tests: the hand-built format contract from `obcr-route.md`, the converter's //! `` emission (category from ``/``, signed lateral offset), and the storage-only //! guarantee that a waypoint-bearing route rides identically to the same route without waypoints. diff --git a/firmware/obc-route/tests/common/mod.rs b/firmware/obc-route/tests/common/mod.rs index ca0bdb5dbe..848573c737 100644 --- a/firmware/obc-route/tests/common/mod.rs +++ b/firmware/obc-route/tests/common/mod.rs @@ -58,7 +58,7 @@ pub fn route_points(obcr: &[u8]) -> Vec { // The hand-rolled OBCR writer, the format tests' independent oracle. It deliberately does not go // through `gpx_to_obcr`: the converter decides chunk boundaries, decimation and totals itself, so a // fixture built with it could only prove that the reader agrees with the writer. Emitting the bytes -// here against `OBCR_Spec.md` pins both sides to the spec, and lets a test place points in a chosen +// here against `obcr-route.md` pins both sides to the spec, and lets a test place points in a chosen // chunk with chosen cumulative distances, or lie about a field on purpose. Only the fields the // reader reads are populated. diff --git a/firmware/obc-storage/src/flat/bitmap.rs b/firmware/obc-storage/src/flat/bitmap.rs index 0f0e80793a..5316cb716f 100644 --- a/firmware/obc-storage/src/flat/bitmap.rs +++ b/firmware/obc-storage/src/flat/bitmap.rs @@ -1,4 +1,4 @@ -//! The free-extent bitmap (`FLAT_Store_Format.md`): the complement of the catalog, recomputed at +//! The free-extent bitmap (`flat-store-format.md`): the complement of the catalog, recomputed at //! mount. //! //! There is no free list on the card and nothing to reconcile — an extent is free exactly when no diff --git a/firmware/obc-storage/src/flat/catalog.rs b/firmware/obc-storage/src/flat/catalog.rs index 9d3ff94784..86a35aebfb 100644 --- a/firmware/obc-storage/src/flat/catalog.rs +++ b/firmware/obc-storage/src/flat/catalog.rs @@ -1,4 +1,4 @@ -//! The catalog (`FLAT_Store_Format.md`): the header, the 128-byte entry, the gate sector, and the +//! The catalog (`flat-store-format.md`): the header, the 128-byte entry, the gate sector, and the //! structural rules an entry array must satisfy. //! //! The catalog is the store. It names every object that exists and which extents each one occupies, diff --git a/firmware/obc-storage/src/flat/journal.rs b/firmware/obc-storage/src/flat/journal.rs index 63b3937ecb..4ed9dbfa9b 100644 --- a/firmware/obc-storage/src/flat/journal.rs +++ b/firmware/obc-storage/src/flat/journal.rs @@ -1,4 +1,4 @@ -//! The ride journal (`FLAT_Store_Format.md`): the one place in this format where bytes become +//! The ride journal (`flat-store-format.md`): the one place in this format where bytes become //! durable without a commit. //! //! Each slot's tail is one full program page. Its header lives in a separate, page-isolated record and diff --git a/firmware/obc-storage/src/flat/layout.rs b/firmware/obc-storage/src/flat/layout.rs index d324eef8ba..f50f2fac28 100644 --- a/firmware/obc-storage/src/flat/layout.rs +++ b/firmware/obc-storage/src/flat/layout.rs @@ -1,5 +1,5 @@ //! Card geometry, the extent area, and the address arithmetic that is the whole read path -//! (`FLAT_Store_Format.md`). +//! (`flat-store-format.md`). //! //! Every address is arithmetic on these constants and on the one value that is not a constant: the //! extent size, which initialization scales to the card and the superblock records. [`Geometry`] is diff --git a/firmware/obc-storage/src/flat/seam.rs b/firmware/obc-storage/src/flat/seam.rs index 13560f0a62..b2e4b16806 100644 --- a/firmware/obc-storage/src/flat/seam.rs +++ b/firmware/obc-storage/src/flat/seam.rs @@ -1,5 +1,5 @@ //! The store seam: the five operations, the two members beside them, and the whole vocabulary they -//! speak (`FLAT_Store_Protocol.md`). +//! speak (`flat-store-protocol.md`). //! //! Nothing here names a block, an extent, an LBA, a path or a filename. [`EntryMeta`] is the metadata //! half of a catalog entry and [`Allocation`] is an opaque token that stands for reserved extents. @@ -26,7 +26,7 @@ impl ObjectId { pub const NONE: ObjectId = ObjectId(0); } -/// `FLAT_Store_Format.md` is the sole authority for these values. +/// `flat-store-format.md` is the sole authority for these values. #[derive(Debug, Clone, Copy, PartialEq, Eq)] #[repr(u16)] pub enum ObjectKind { diff --git a/firmware/obc-storage/src/flat/store.rs b/firmware/obc-storage/src/flat/store.rs index 82047aa690..eac191f944 100644 --- a/firmware/obc-storage/src/flat/store.rs +++ b/firmware/obc-storage/src/flat/store.rs @@ -1,5 +1,5 @@ //! The store: mount, initialization, the alternating catalog commit, the ride journal's write half -//! and the seam operations (`FLAT_Store_Format.md`, `FLAT_Store_Protocol.md`). The entry array stays +//! and the seam operations (`flat-store-format.md`, `flat-store-protocol.md`). The entry array stays //! on the card; resident state is the 8 KiB free bitmap and a few rows. //! //! Every operation takes `&self`, mutators included, and the resident state that moves lives behind diff --git a/firmware/obc-storage/src/flat/superblock.rs b/firmware/obc-storage/src/flat/superblock.rs index 4687ae9802..303269d758 100644 --- a/firmware/obc-storage/src/flat/superblock.rs +++ b/firmware/obc-storage/src/flat/superblock.rs @@ -1,4 +1,4 @@ -//! The superblock (`FLAT_Store_Format.md`): written once by initialization and never again. +//! The superblock (`flat-store-format.md`): written once by initialization and never again. //! //! Nothing in normal operation updates it, which is why it carries no gate and no sequence. Two //! copies of identical bytes exist so that one bad block does not make the card unreadable. diff --git a/firmware/obc-storage/src/flat/vectors.rs b/firmware/obc-storage/src/flat/vectors.rs index e08dc7bfc3..f7afba079b 100644 --- a/firmware/obc-storage/src/flat/vectors.rs +++ b/firmware/obc-storage/src/flat/vectors.rs @@ -1,7 +1,7 @@ //! Every test vector in both frozen specs, pinned byte for byte. //! -//! `FLAT_Store_Format.md`'s vectors are the on-card ones, and this crate encodes them, so they are -//! pinned against the encoder's own output. `FLAT_Store_Protocol.md`'s frames belong to the engine; +//! `flat-store-format.md`'s vectors are the on-card ones, and this crate encodes them, so they are +//! pinned against the encoder's own output. `flat-store-protocol.md`'s frames belong to the engine; //! what is pinned of them here is the half this contract owns — they carry the format's objects and //! offsets, and the two documents agree about them or one of the two is wrong. //! @@ -247,7 +247,7 @@ fn capacity_table() { assert_eq!(TAIL_CAPACITY, 16_384); } -/// `FLAT_Store_Protocol.md`'s `LIST` response carries the two objects. Its 88-byte entries are the +/// `flat-store-protocol.md`'s `LIST` response carries the two objects. Its 88-byte entries are the /// format entries' metadata, and this is the seam between the two specs. #[test] fn wire_list_entries_carry_the_same_metadata() { diff --git a/firmware/tools/ui_frames/environments.py b/firmware/tools/ui_frames/environments.py index a6387f2ff6..9079bbfd85 100644 --- a/firmware/tools/ui_frames/environments.py +++ b/firmware/tools/ui_frames/environments.py @@ -61,7 +61,7 @@ def plain_route(stage: Stage) -> Staging: def _ride(samples, name, start, distance_m, moving_s, climb_m, descent_m, hr, trip): - """A ride object as `specs/obc-ble-interface-spec.md` §7.2 lays it out: 20-byte samples, then + """A ride object as `specs/ble-interface.md` §7.2 lays it out: 20-byte samples, then the 154-byte footer. `samples` are `(lon, lat, ele)`; `hr` is one heart rate per sample or `None`, and a ride with heart rate records a 185 bpm max HR and a 250 W FTP; `trip` is `(key, day index, day count, name)` or `None`. @@ -136,7 +136,7 @@ def tracks(stage: Stage) -> Staging: def _shift_route_lon(route: bytearray, dlon: int) -> None: - """Move a waypoint-less OBCR east by `dlon` µdeg (`specs/OBCR_Spec.md`: the header start and + """Move a waypoint-less OBCR east by `dlon` µdeg (`specs/obcr-route.md`: the header start and bbox, and each chunk meta's bbox and anchor). Points are deltas from the anchor, so they follow. """ for off in (8, 16, 24): @@ -149,7 +149,7 @@ def _shift_route_lon(route: bytearray, dlon: int) -> None: def _rename_route(route: bytearray, name: str) -> None: - """Rewrite an OBCR header's name (`specs/OBCR_Spec.md` §1: Name Len at 6, Name at 64).""" + """Rewrite an OBCR header's name (`specs/obcr-route.md` §1: Name Len at 6, Name at 64).""" raw = name.encode() route[6] = len(raw) route[64:112] = raw.ljust(48, b"\0") @@ -181,7 +181,7 @@ def trips(stage: Stage) -> Staging: def trip_week(stage: Stage) -> Staging: """A seven-day trip, "Alpen Traverse Nord", on seven renamed copies of the plain vector route, starting Monday 2025-09-29. Its day list scrolls, so the title bar shows the counter. The trip - object is written here as `specs/obc-ble-interface-spec.md` §7.7 lays it out; the simulator + object is written here as `specs/ble-interface.md` §7.7 lays it out; the simulator maps each day's route index to the imported route. """ where = stage.dir("trip-week") diff --git a/fixtures/README.md b/fixtures/README.md index 2f5906314c..c353bc60c9 100644 --- a/fixtures/README.md +++ b/fixtures/README.md @@ -6,7 +6,11 @@ crate's `assets/` directory. The catalog is tracked. Large generated and captured bytes are not. -## Daily use +## Setup + +Python 3.11 or newer. No Python package dependencies. + +## Run ```sh obc fixtures list # scenarios, cache state, download size @@ -27,8 +31,6 @@ extraction are atomic, and archives, manifests and every extracted file are veri `tracked_sources` mappings make CI fail if a small authored source changes without its external package being rebuilt. -Python 3.11 or newer. No Python package dependencies. - ## Add or replace data 1. Make a clean staging directory holding only the package's final layout. @@ -55,15 +57,15 @@ terrain before its map, or use the `all` target. | Country-scale raw landmark captures | The map-baker's local source cache only | **Do not register or publish a country capture as a development fixture**, in any profile. The -1 GiB archive limit is a backstop, not -a target: use the smallest input that covers the scenario. Generated design-review screenshots -belong in a pull request, not in a runtime asset folder. +1 GiB archive limit is a backstop, not a target: use the smallest input that covers the scenario. +Generated design-review screenshots belong in a pull request, not in a runtime asset folder. ## Package provenance -Every registered map is an OBCM v19 file with Light and Dark styles. The geographic payload comes -from a canonical bbox that is never self-sourced from a header. Each one has a build record in -`sources/ride-assistant/` that pins its source and output digests. +Every registered map is an OBCM v19 file with Light and Dark style tables. The Dark table holds the +authored Dusk skin. The geographic payload comes from a canonical bbox that is never self-sourced +from a header. Each one has a build record in `sources/ride-assistant/` that pins its source and +output digests. | Package | Source | Build record | | --- | --- | --- | @@ -112,7 +114,7 @@ The verifier rebuilds discovery and compares two offline compilations. `fixtures.openbikecomputer.com` is a read-only custom domain for the EU-jurisdiction R2 bucket `obc-dev-fixture`. Developers and CI need no cloud credentials. Upload credentials are -maintainer-only and are deliberately not shared with the production map publisher. +maintainer-only and are not shared with the production map publisher. The publisher reads `OBC_FIXTURE_R2_BUCKET`, `OBC_FIXTURE_R2_ENDPOINT`, `OBC_FIXTURE_R2_ACCESS_KEY_ID` and `OBC_FIXTURE_R2_SECRET_ACCESS_KEY` from diff --git a/fixtures/sources/peak-view/README.md b/fixtures/sources/peak-view/README.md index 0fc2e55073..003584744c 100644 --- a/fixtures/sources/peak-view/README.md +++ b/fixtures/sources/peak-view/README.md @@ -8,13 +8,13 @@ Observer locations and the peak catalogue are in [locations.json](locations.json coordinates are reconstructed from rounded bearings and distances; production map summit records keep exact OSM coordinates. -## Obtain +## Setup -`obc fixtures sync sim-peak-view`. The package is also in the `sim` profile, and the simulator +`obc fixtures sync sim-peak-view`. The package is also in the `sim` profile; the simulator resolves it through the standard fixture cache. `OBC_PEAK_TERRAIN_DIR` overrides it for a local bake. **The simulator never downloads data.** -## Generate +## Build Install NumPy and Pillow, then run from the repository root: @@ -41,7 +41,7 @@ coverage radii of 28, 53 and 103 km. The generator puts the finest available sou coordinate onto one 2^9-microdegree lattice; coarser outer sources extend coverage and interpolation adds no detail. `obc-dem surface` then creates the lower levels and the bounds. Geographic cells span 2^16 microdegrees. Runtime level changes happen at 25 and 50 km and all rays -end at 100 km, so the extra coverage is what lets a nearby observer position work. +end at 100 km; the extra coverage lets a nearby observer position work. `--source-levels PATH` reuses the three source grids from an earlier bake. That directory must hold `{site}-9.obcd`, `{site}-10.obcd` and `{site}-11.obcd` per site, and this path reads and @@ -54,7 +54,7 @@ generator, and the location and Rust catalogues. Lighting is fixed relative to geography, 25 degrees above the horizon and to the north-west. It describes terrain form only: **no snow, no rock texture, no cast shadows and no real sunlight.** -Source resolution and level changes limit detail. It is not a photographic reconstruction. +Source resolution and level changes limit detail. Named summits use measured terrain at their catalogue distance and within half a degree of their bearing, with a quarter-degree tolerance on visibility. **Terrain is never raised to meet a @@ -68,8 +68,8 @@ completed image and touches no terrain storage. Terrain starts 2 m from the observer. Curvature uses an effective Earth radius with refraction coefficient 0.13. -A GPS displacement above 20 m starts a replacement job; smaller changes keep the current panorama, -to limit GPS jitter. At a moved observer, ground elevation plus two metres is the viewing height. +A GPS displacement above 20 m starts a replacement job; smaller changes keep the current panorama. +At a moved observer, ground elevation plus two metres is the viewing height. Missing distant terrain and clipped coverage show a partial-coverage notice and bearing marks. Missing observer terrain or a failed read is an unavailable state. diff --git a/fixtures/sources/ride-assistant/CAPTURE.md b/fixtures/sources/ride-assistant/CAPTURE.md index 4efd88a9a0..8f9d405fb2 100644 --- a/fixtures/sources/ride-assistant/CAPTURE.md +++ b/fixtures/sources/ride-assistant/CAPTURE.md @@ -4,8 +4,8 @@ A one-shot acquisition command that writes country-scale raw sources to a local directory. **Do not publish that directory to the dev fixture bucket or the production maps bucket**, and do not register it as a fixture; see [the fixture package workflow](../../README.md#add-or-replace-data) for what does belong there. -The compiled landmark content travels in ordinary maps, so no simulator or device ever needs the -raw archive. +The compiled landmark content travels in ordinary maps; no simulator or device needs the raw +archive. ## Acquire @@ -28,8 +28,8 @@ python3 tools/landmark_capture.py \ ``` Candidates are the QIDs the extract's own objects carry in a `wikidata` tag. Nothing is matched by -name or by coordinate, so discovery is offline and every landmark has a map object with an -approach. A tag that is not a QID is listed in `rejected` and does not stop the run. +name or by coordinate: discovery is offline, and every landmark has a map object with an approach. +A tag that is not a QID is listed in `rejected` and does not stop the run. The command uses two workers and at most ten requests per second in total. It sends `maxlag=5` and a descriptive User-Agent, and it waits for the `Retry-After` of a `429` or a `503` before it asks @@ -37,19 +37,18 @@ again. It captures the entities fifty per request, their P279 class closure, the articles at exact revisions, and the P18 and lead-image candidates with their Commons metadata. A batch whose response is larger than the compiler reads is asked for again in halves. Responses land in `entities/`, `classes/`, `locales/`, `articles/` and `images/`, with -`manifest.json` recording every URL, byte count, SHA-256 and outcome. The response -limit is 32 MiB. +`manifest.json` recording every URL, byte count, SHA-256 and outcome. The response limit is +32 MiB. -`obc-bake landmark-content` makes every text, image and attribution decision afterwards, offline. Site -eligibility comes from the exact polygon and the category policy, not from P17 country claims or a -curated list, and the acquisition checks its category file digest against the compiler's embedded -policy digest so the two cannot disagree. +`obc-bake landmark-content` makes every text, image and attribution decision afterwards, offline. +Site eligibility comes from the exact polygon and the category policy, not from P17 country claims +or a curated list. The acquisition checks its category file digest against the compiler's embedded +policy digest. **Resume with the same arguments and the same output directory.** A completed request is reused only after its URL, byte count and digest check out. Failed requests stay failed. A changed candidate list, boundary, category policy, language set or locale policy needs a **new** output -directory. -Never run two capture processes against one output directory. +directory. Never run two capture processes against one output directory. Manifest schema 2 records the request identity of every Commons category page. You can resume a schema 1 capture in the same output directory to add missing continuation pages and write schema @@ -57,8 +56,8 @@ schema 1 capture in the same output directory to add missing continuation pages category records because they cannot prove that every page was consumed. An incomplete acquisition exits with status 2 and keeps the bytes it captured. Unresolved source -requests or class closure make country coverage incomplete: do not report their -absence as zero landmarks or zero images. A `wikidata` tag that names no item is a fact about the +requests or class closure make country coverage incomplete: do not report their absence as zero +landmarks or zero images. A `wikidata` tag that names no item is a fact about the extract, not a failure: `unresolved_identities` counts those and coverage stays complete. Keep a separate copy of the built `obc-bake` when another build can replace the target binary; the diff --git a/fixtures/sources/ride-assistant/PLACES-VALIDATION.md b/fixtures/sources/ride-assistant/PLACES-VALIDATION.md index 7615028a90..c2ab004fa8 100644 --- a/fixtures/sources/ride-assistant/PLACES-VALIDATION.md +++ b/fixtures/sources/ride-assistant/PLACES-VALIDATION.md @@ -10,13 +10,13 @@ python3 fixtures/verify-assistant-places.py It reads the pinned `assistant-osm/switzerland.osm.pbf` from the fixture cache and crops it to `8.17,46.55,8.38,46.74`, keeping complete source ways at the crop edge. The test uses the repository routing preset and the production ingest, OBCM serializer, map reader and place -continuation query, so it checks place identity and access rather than rendering: it packs real -service records and the real navigation graph with an empty render layer and no DEM. +continuation query. It checks place identity and access, not rendering: it packs real service +records and the real navigation graph with an empty render layer and no DEM. A place gets an approach only through its source node's membership in a routable way. **No proximity join is used**, so a place with a road nearby but no such membership keeps an unavailable approach. The shared query returns bounded pages in stable order and keeps the original eligibility time -across continuation. No coverage map can prove that an installed map has no internal holes, so -results report `coverage_complete: false`, including for an empty result. +across continuation. Results report `coverage_complete: false`, including for an empty result: no +coverage map can prove that an installed map has no internal holes. diff --git a/fixtures/sources/ride-assistant/README.md b/fixtures/sources/ride-assistant/README.md index 3f99d86808..accabc90ee 100644 --- a/fixtures/sources/ride-assistant/README.md +++ b/fixtures/sources/ride-assistant/README.md @@ -22,7 +22,7 @@ source needs a new immutable package. No acquisition command runs during map gen `fixtures/verify-assistant-places.py` runs the `fixtures.assistant-places` suite against the pinned Swiss PBF; see [place query validation](PLACES-VALIDATION.md). -## Build the maps offline +## Build Build the shipping tools once while Cargo dependencies are available, then work from cached inputs: @@ -62,6 +62,31 @@ pre-extract would change the data in the boundary cells. These map-selection bou from the wider acquisition and replay bounds in `regions.geojson`. The catalog region ID is `europe/switzerland`; the assembled package is `sim-assistant-meiringen`. +## Run + +```sh +tools/obc sim assistant-dunlough-access +tools/obc sim assistant-monaco-dense +tools/obc sim assistant-out-and-back +tools/obc sim assistant-forward-rejoin +tools/obc sim assistant-loop-crossing +``` + +Once the packages and Cargo dependencies are cached, these need no live source API. + +For a persistent card, start with a path that does not exist: + +```sh +tools/obc sim assistant-dunlough-access -- --create-card .artifacts/west-cork.obc +cargo run --release -p obc-sim -- --card .artifacts/west-cork.obc --physical \ + --clock 2026-09-14T10:00 --utc-offset-min 60 +``` + +The second command reopens saved routes and recordings without importing the fixture again. +**The card is user state**: fixture sync does not replace it, so create a new card to test a new +package. See the [simulator README](../../../sim/desktop/README.md) for imports and recording +recovery. + ## Sources and licences Each `sources[]` entry in the JSON records below pins `path`, `url`, `retrieved_at`, `bytes` and @@ -112,29 +137,3 @@ The Dunlough paths carry `sac_scale=mountain_hiking` and mud or ground surfaces unknown. Hours are absent on the selected landmark objects. Dunlough Castle is Wikidata `Q5315471` through OSM way `300189816`, with real article and photo Sources; a truthful unavailable Visit is a valid result there. - -## Run the scenarios - -```sh -tools/obc sim assistant-dunlough-access -tools/obc sim assistant-monaco-dense -tools/obc sim assistant-out-and-back -tools/obc sim assistant-forward-rejoin -tools/obc sim assistant-loop-crossing -``` - -These use ordinary map loading and authored GPS replay. Once the packages and Cargo dependencies -are cached they need no live source API. - -For a persistent card, start with a path that does not exist: - -```sh -tools/obc sim assistant-dunlough-access -- --create-card .artifacts/west-cork.obc -cargo run --release -p obc-sim -- --card .artifacts/west-cork.obc --physical \ - --clock 2026-09-14T10:00 --utc-offset-min 60 -``` - -The second command reopens saved routes and recordings without importing the fixture again. -**The card is user state**: fixture sync does not replace it, so create a new card to test a new -package. See the [simulator README](../../../sim/desktop/README.md) for imports and recording -recovery. diff --git a/fixtures/sources/route-import/README.md b/fixtures/sources/route-import/README.md index 68937c4519..fc158936ec 100644 --- a/fixtures/sources/route-import/README.md +++ b/fixtures/sources/route-import/README.md @@ -12,5 +12,5 @@ test holds the two byte-identical. | --- | --- | --- | --- | | `komoot-schwarzwald.gpx` | komoot export, `creator="https://www.komoot.de"`, "Schwarzwald Tour · Tag 2": 150 track points and five ``. The symbols are Garmin names komoot copies through — `Flag, Blue` three times, `Restaurant`, and `Fishing Hot Spot Facility`, which no category fits. Who exported it is not recorded anywhere in the tree; it arrived as the iOS companion's import fixture. | ODbL-1.0 for the track, which is komoot's routing output over OSM ways. **The authored part — the chosen route and the five waypoint names — is unconfirmed**, pending the owner. | `companion-ios/Packages/OBCKit/Sources/OBCMock/Fixtures/sample-import.gpx` | -SwiftPM processes `Sources/OBCMock/Fixtures` as the `OBCMock` target's bundled resources, and a -resource must live inside its own target directory. The iOS copy therefore stays where it is. +Do not move the iOS copy: SwiftPM bundles `Sources/OBCMock/Fixtures` as resources of the `OBCMock` +target, and a resource must live inside its own target directory. diff --git a/host/obc-bake/assets/README.md b/host/obc-bake/assets/README.md index 7259cff12a..af54763163 100644 --- a/host/obc-bake/assets/README.md +++ b/host/obc-bake/assets/README.md @@ -5,10 +5,9 @@ Teningen camera through the production map renderer. The file is never published itself. `teningen-preview.obcd` is the OBCT terrain sidecar for the same square. `obc-bake` does not use -it yet; it exists so the preview geometry has real elevation available when terrain reaches the -shared render path. +it yet. -## Regenerate +## Build `fixtures/build-map-package.sh` is the only supported way, as it is for every built fixture here. The map is packed from a Geofabrik `europe/germany/baden-wuerttemberg/freiburg-regbez` extract @@ -30,13 +29,11 @@ fixtures/build-map-package.sh terrain ``` It is baked at the real v1 posting (`2^9` µdeg) with a `2^16` cell, so the 1 × 2 cell rectangle is -65 576 B rather than a 2 MiB v1 cell that is mostly outside the crop. `OBCT_Spec.md` §1.3 makes -both header data and §4.5 requires a reader to accept the pairing. +65 576 B. `obct-terrain.md` §1.3 makes both header data and §4.5 requires a reader to accept the +pairing. -There is no terrain in the map, deliberately: the Rhine plain has nothing to show in a 1.2 km -frame, and a preview whose subject is the skin should not double as a contour test. There is no -golden preview PNG either — the tests assert that the skins render distinctly and -deterministically, and that residential fills cover the frame. +The map has no terrain, and there is no golden preview PNG: the tests assert that the skins render +distinctly and deterministically, and that residential fills cover the frame. ## When to refresh it @@ -44,11 +41,10 @@ deterministically, and that residential fills cover the frame. checks the assignment before it starts a region bake and fails with this path rather than publishing stale previews. -One case deliberately owes no refresh: feature types *appended* to the schema take the next free -ids and leave every id in this file meaning what it meant, so `check_source` in -`host/obc-bake/src/previews.rs` requires the fixture's table to be a leading run of the schema's -assignment rather than all of it. A schema that stops covering an id this file carries still -fails. +Feature types *appended* to the schema owe no refresh: they take the next free ids, so +`check_source` in `host/obc-bake/src/previews.rs` requires the fixture's table to be a leading run +of the schema's assignment rather than all of it. A schema that stops covering an id this file +carries still fails. ## The published camera @@ -56,8 +52,7 @@ The 240 × 240 image is centred at `7.814,48.130` at 5 m/px. The live skin edito camera, allows pan and zoom, and treats the crop above as its dense coverage. The crop is wider than the frame, and the packer's relation-complete selection also pulls in every member of a land-cover multipolygon reached from inside it, which keeps residential, forest and farmland fills -whole. That is already enough for the interactive preview to select every rung of the ladder, so -no second browser fixture is needed. +whole. OSM complete-way retention can push the OBCM header beyond the requested bbox. **Those overhanging coordinates are not a licence to pan into sparse space**: at wide scales the camera diff --git a/host/obc-bake/src/cells.rs b/host/obc-bake/src/cells.rs index d96f205efe..dcaafb0baf 100644 --- a/host/obc-bake/src/cells.rs +++ b/host/obc-bake/src/cells.rs @@ -1,5 +1,5 @@ -//! The cell bake: named regions in, an [`OBCA`](../../../specs/OBCA_Spec.md) cell store plus an -//! [`OBCC`](../../../specs/OBCC_Spec.md) catalog out. +//! The cell bake: named regions in, an [`OBCA`](../../../specs/obca-assembly.md) cell store plus an +//! [`OBCC`](../../../specs/obcc-catalog.md) catalog out. //! //! `data/regions/` stays the curation surface — a region is still one reviewable file — but it names //! a selection rather than an artifact: the set of grid cells its coverage polygon touches, per @@ -893,7 +893,7 @@ impl CellBakery<'_> { if !existing.sidecar.partial && dest.is_file() { progress.warn(format!( " {} [{}]: kept the canonical cell — this run's sources ({}) do not cover its square, \ - and a partial cell must never replace a covering bake (OBCA_Spec.md §3.7). Co-bake {} \ + and a partial cell must never replace a covering bake (obca-assembly.md §3.7). Co-bake {} \ to refresh it.", artifact.id, artifact.band, diff --git a/host/obc-bake/src/cut.rs b/host/obc-bake/src/cut.rs index 7e6bb0c721..e8081b2cb5 100644 --- a/host/obc-bake/src/cut.rs +++ b/host/obc-bake/src/cut.rs @@ -1,5 +1,5 @@ //! The cell cutter: one ingested extract in, the cell artifacts of every band it touches out -//! (`OBCA_Spec.md`). +//! (`obca-assembly.md`). //! //! A cell artifact is an ordinary OBCM file a device could open on its own. What makes it a cell is //! a set of constraints, and every one of them is here. The header bbox is the grid square and not diff --git a/host/obc-bake/src/guard.rs b/host/obc-bake/src/guard.rs index d145ceba5e..3f62ab5ce0 100644 --- a/host/obc-bake/src/guard.rs +++ b/host/obc-bake/src/guard.rs @@ -43,7 +43,7 @@ impl GuardOutcome { let mut s = format!( "obcm-version guard: FAILED — this build writes OBCM v{expected}, but {} of {cells} \ published cells are a different version.\n\nAn OBCM bump invalidates every baked cell \ - (OBCC_Spec.md §10): every assembly from the catalog is unreadable to this firmware until the bakery \ + (obcc-catalog.md §10): every assembly from the catalog is unreadable to this firmware until the bakery \ re-runs. Re-bake and re-publish:\n\n obc-bake bake --out --force\n obc-bake \ publish --base-url --target r2\n\nStale schemas:\n", found.len() @@ -158,7 +158,7 @@ impl CellStoreOutcome { let _ = writeln!( s, " {} cell(s) are `partial` — co-bake the neighbouring extract to complete them \ - (OBCA_Spec.md §3.7):", + (obca-assembly.md §3.7):", self.partial.len() ); for id in self.partial.iter().take(10) { @@ -335,7 +335,7 @@ pub fn check_cell_store(tree: &std::path::Path) -> Result --force ", name_revision(network_terrain_revision), doc.revision diff --git a/host/obc-bake/src/main.rs b/host/obc-bake/src/main.rs index 28f4f24f99..a2455404c9 100644 --- a/host/obc-bake/src/main.rs +++ b/host/obc-bake/src/main.rs @@ -62,7 +62,7 @@ usage: obc-bake terrain [REGION…] --sources DIR [flags] Bake the curated coverage's OBCT terrain cells into the tree's terrain band. Terrain has its OWN revision track: this never re-bakes an OBCM cell, and a - schema bump never re-bakes a terrain cell (OBCC_Spec.md §13). + schema bump never re-bakes a terrain cell (obcc-catalog.md §13). --out TREE output tree (default: ./obc-bake) --sources DIR source DEM GeoTIFFs (default: fetched into /dem) --dataset-id ID source dataset (default: copernicus-glo-30) @@ -73,9 +73,9 @@ usage: --reference DIR reference archive mirror: `index.json` plus the tiles of the box, from host/obc-dem/reference/ingest.py. Where it covers a crest, the baked samples carry the finer model's height - (OBCT_Spec.md §9), each cell records the sources it used, and + (obct-terrain.md §9), each cell records the sources it used, and their credits reach the catalog. A reference change is a - terrain revision bump (OBCC_Spec.md §13.2), which + terrain revision bump (obcc-catalog.md §13.2), which re-stamps every cell and re-bakes only the cells the changed archive tiles reach. A cell the mirror is short of tiles for is REFUSED, with the --bbox to mirror: it diff --git a/host/obc-bake/src/source.rs b/host/obc-bake/src/source.rs index 07b1582783..215cffc5dc 100644 --- a/host/obc-bake/src/source.rs +++ b/host/obc-bake/src/source.rs @@ -152,7 +152,7 @@ impl ExtractSource for LocalExtracts { } Err(format!( "no coverage polygon for `{}` — looked for {} and {}. A cell bake needs it: it is what decides which \ - cells the region selects and whether a border cell is canonical (OBCA_Spec.md §3.7)", + cells the region selects and whether a border cell is canonical (obca-assembly.md §3.7)", region.id, nested.display(), flat.display() diff --git a/host/obc-bake/src/terrain.rs b/host/obc-bake/src/terrain.rs index 54bfce4e12..4dc82f4933 100644 --- a/host/obc-bake/src/terrain.rs +++ b/host/obc-bake/src/terrain.rs @@ -196,11 +196,11 @@ fn validate_doc(doc: &TerrainDoc) -> Result<(), String> { return Err("`dataset_id` and `dataset_version` must be non-empty — they are half the lockstep key".into()); } if doc.attribution.trim().is_empty() { - return Err("`attribution` must be non-empty — the credit travels with the data (OBCC_Spec.md §13.5)".into()); + return Err("`attribution` must be non-empty — the credit travels with the data (obcc-catalog.md §13.5)".into()); } obc_formats::obct::cell_samples_log2(doc.posting_log2, doc.cell_log2).ok_or_else(|| { format!( - "posting 2^{} µdeg with cell 2^{} µdeg is not a pairing OBCT permits (OBCT_Spec.md §1.3)", + "posting 2^{} µdeg with cell 2^{} µdeg is not a pairing OBCT permits (obct-terrain.md §1.3)", doc.posting_log2, doc.cell_log2 ) })?; diff --git a/host/obc-bake/src/verify.rs b/host/obc-bake/src/verify.rs index 31e77f283d..bbb1439ba5 100644 --- a/host/obc-bake/src/verify.rs +++ b/host/obc-bake/src/verify.rs @@ -63,7 +63,7 @@ pub fn verify_cell(path: &Path, square: (i64, i64, i64, i64)) -> Result Result Result Result Result Result( if sha != sha256 { problems.push(format!( "{rel}: sha256 {sha}, root pinned {sha256} — a satellite that does not match its pin MUST be rejected \ - and the root retained (OBCC_Spec.md §9)" + and the root retained (obcc-catalog.md §9)" )); return None; } diff --git a/host/obc-data/README.md b/host/obc-data/README.md index be3467860b..c78833fd71 100644 --- a/host/obc-data/README.md +++ b/host/obc-data/README.md @@ -10,19 +10,11 @@ The [data contract](../../specs/obc-data.md) defines bytes and admission checks. Prepare Rust, Python with `uv`, GEOS and Osmium before an update, and a Java 21 JDK and Maven for the planner layers; `obc data` does not install them. `obc data setup` shows what this machine can do and the tools and credentials that it has. -A changed producer does not rebuild its layer. Raise the `revision` of the layer in the change -that changes its output; a reader that needs new data raises its `format`. - -Each step runs in a process of its own. A Rust step shows as `obc-data obc_data_step FUNCTION` -in `ps`. Add the function of a new Rust step to `host/obc-data-steps/src/functions.rs`: a -function that is not there fails its step. A test binary that runs a Rust step needs a test -`obc_data_step` that calls `obc_data::engine::child` with its functions. Without that test, the -step fails because it did not write its output. `data/targets.toml` names the targets: `local` is a folder beside the store, and `prod` the public bucket. An update or a rollback of `prod` needs the `OBC_R2_*` variables and rclone. The -settings of a target (region, parts, refresh policies) are in the release that it -serves, so they need no commit. +settings of a target (region, parts, refresh policies) are in the release that it serves; they +need no commit. | Configuration or credential | Purpose | | --- | --- | @@ -51,7 +43,7 @@ serves, so they need no commit. Set a source credential on the Machine screen, or pipe it to `obc data source credential ID`. Put other secrets, such as the R2 key, in `credentials.env`, never in `tools/obc.local`. -## Daily commands +## Run | Command | Action | | --- | --- | @@ -88,12 +80,6 @@ or stops frees the lock. A crash or an out-of-memory kill keeps it; the next run machine takes it over. From another machine, `obc data unlock TARGET --from MACHINE` frees it after 10 minutes without a heartbeat. -`cargo test -p obc-data --test r2_live -- --ignored` writes the bucket of the `OBC_R2_*` variables -in a throwaway folder `test/