Skip to content

Findings from documenting foundations #3363

Open

Description

@timohueser

These findings come from writing the design doc for the foundations system (docs/design/foundations.md). Each finding has a place in the code, what happens, and the suggested action.

Rules with no check

  • The foundation dependency rule is only partly checked. firmware/obc-formats/Cargo.toml, firmware/obc-map-scene/Cargo.toml, firmware/obc-ports/Cargo.toml, firmware/obc-crc/Cargo.toml, host/obc-file-source/Cargo.toml. cairn check already refuses a dependency on a crate of another system, because the foundations doc lists depends_on: []. Nothing checks third-party crates: a foundation crate can add an executor or a driver crate from crates.io. The owner approved a guard: it allows only heapless, libm and the other foundation crates. Also, the foundations doc says that no check exists, which is wrong for repository crates. Action: fix. Fixed in foundations: fix the small findings of #3363 #3365.

Wrong placement

  • The index block cache is used only by the map reader. firmware/obc-formats/src/cache.rs:81. IndexBlockCache has three users, and all of them are in obc-reader: reader/cache.rs, reader/nav/cache.rs and reader/places/cache.rs. The terrain reader (obc-elevation) and the route reader (obc-route) use only lru_victim, a 14-line function that picks the slot to evict. The cache moved into obc-formats because a move of the terrain cache was expected next, and that move did not happen. As a result, a format crate holds reader caching policy. Action: refactor issue: move IndexBlockCache and INDEX_BLOCK into obc-reader, and give obc-elevation and obc-route their own copy of the small eviction rule.
  • The distance helpers live in the map-scene interface. firmware/obc-map-scene/src/lib.rs:353. About eight crates use ground_dist_m, cos_lat, delta_m and M_PER_DEG, among them obc-bake, obc-network, obcm-assemble and obc-dem, which do not draw a map. Other crates still have their own copy of the 111,320 m-per-degree constant, for example builder/wasm/src/gpx.rs, host/obc-network/src/nav.rs and host/obc-search-bake/src/postcodes.rs. Action: refactor issue: move the helpers into a small geo module in obc-formats, next to one shared latitude and longitude range check, and remove the copies.
  • The sound cues are in the ports crate. firmware/obc-ports/src/lib.rs:216. Cue lists the named sound events. This is correct: the app chooses the cue, and each platform (obc-platform/src/sound.rs) chooses how it sounds, so the cue is the value that crosses the boundary. Action: intended choice: the Decisions section of the doc explains it (foundations: fix the small findings of #3363 #3365).

Duplicates

  • The latitude and longitude range check is written four times. firmware/obc-formats/src/assistant.rs:73, obcm.rs:400, obcr.rs:176, obcm/landmarks.rs:82. A change to the coordinate range must be made in four places. Action: refactor issue: part of the geo refactor above.
  • The ContentRef encode and decode functions are written by hand three times. firmware/obc-formats/src/articles.rs:27, obcm/peaks.rs:49, and the private copy in obcm/landmarks.rs:36. Action: fix: make the landmarks codec public and reuse it. Fixed in foundations: fix the small findings of #3363 #3365.

Drift between the guides and the code

  • The architecture guide lists the wrong foundation crates. docs/content/software/architecture.md:34. It names obc-elevation, which belongs to the map-reading system, and it leaves out obc-crc and obc-file-source. Action: fix. Fixed in foundations: fix the small findings of #3363 #3365.
  • The route spec and the route readers disagree about waypoint categories. specs/obcr-route.md:204 says that a category byte outside 1..=6 renders as generic. The readers decode the byte with PoiCategory::from_id, so ids 8 and 10–12 render as their categories. The GPX import writes only 0..=6. Action: owner decision: correct the spec or the readers.

Confusing code and comments

  • A comment gives the wrong range of POI category ids. firmware/obc-formats/src/obcr.rs:41 says that 1..=6 are the PoiCategory wire ids. The ids go up to 12 (obcm.rs:485). A reader who trusts the comment treats a restaurant waypoint as generic. Action: fix. Fixed in foundations: fix the small findings of #3363 #3365 (also two doc comments in obc-route/src/reader.rs).
  • DateTime::to_unix truncates to u32 with no warning. firmware/obc-ports/src/lib.rs:117. After 2106 it gives a wrong time; to_unix_i64 is the safe form. Action: fix: say it in the doc comment. Fixed in foundations: fix the small findings of #3363 #3365.
  • obcm.rs mixes several jobs in 1,050 lines. firmware/obc-formats/src/obcm.rs. It holds the header constants, the producer-only UnitWriter, the navigation record walk and the POI tables. Action: refactor issue: split it into modules inside the crate.
  • The file name assistant.rs does not match its content. firmware/obc-formats/src/assistant.rs:1. The file holds the Navigator checkpoint codec. Action: fix: rename the module to navigator. Fixed in foundations: fix the small findings of #3363 #3365.
  • Comments state the version history. firmware/obc-formats/src/obcr.rs:6 ("Older files must be re-imported") and firmware/obc-formats/src/cache.rs:218 ("because it was the one eviction rule written twice"). The project's comment rule allows only present behavior. Action: fix. Fixed in foundations: fix the small findings of #3363 #3365.
  • The CRC function exists twice under two names. firmware/obc-crc/src/lib.rs:110. Crc32::checksum and the free function crc32 do the same thing. crc32 has about 100 callers and Crc32::checksum has 3. Action: fix: remove Crc32::checksum. Fixed in foundations: fix the small findings of #3363 #3365.

Plan

The work is one fix pull request, then three refactors. Each refactor gets its own issue and goes through design before code. The refactors are independent, so their order is free; the one below starts with the smallest.

1. Fix pull request (Size: S): #3365

One pull request, Mode: fix. It does all findings with the action fix:

  1. Dependency guard. Add a check that reads the [dependencies] of the five foundation crates and allows only heapless, libm and the other foundation crates. Cite it in the Rules table of docs/design/foundations.md, together with the existing cairn check dependency rule, and remove the sentence that says no check exists.
  2. ContentRef codec. Make the landmarks codec public and use it in articles.rs and obcm/peaks.rs.
  3. Architecture guide. Correct the list of foundation crates in docs/content/software/architecture.md, as its own docs: commit.
  4. Comments and names. Correct the 1..=6 comment in obcr.rs, add the 2106 limit to the to_unix doc comment, rename assistant.rs to navigator.rs, and remove the two version-history comments.
  5. CRC. Remove Crc32::checksum and move its 3 callers to crc32.
  6. Doc. Add the Cue decision to the Decisions section of the foundations doc.

After #3365 and #3356 merge, one flash test on the board covers both: the display checks of #2986 ("Done when"), one map or route transfer over USB or BLE (CRC), and one navigation resume after a restart (checkpoint).

2. Move the index block cache into obc-reader (Size: S)

IndexBlockCache and INDEX_BLOCK move with their tests into obc-reader. obc-elevation and obc-route each keep a private copy of the eviction rule (14 lines), so they do not depend on the map reader. The cache rows of the foundations doc move to the map-reading doc. To check in design: the device RAM and boot layout must stay the same (resource_baseline.json), because the cache must stay 4-byte aligned.

3. Split obcm.rs (Size: S)

Split obcm.rs into modules inside obc-formats, for example the header and offset scale, UnitWriter, the navigation edge walk and the POI tables. The public paths stay the same through re-exports, or the callers change in the same pull request. No behavior changes.

4. One geo module for coordinates and distance (Size: M)

Move ground_dist_m, cos_lat, delta_m and M_PER_DEG from obc-map-scene into a new obc-formats::geo module, with one latitude and longitude range check. obc-formats then needs libm, which is allowed by the guard. Remove the local copies of the 111,320 m-per-degree constant and the four range checks. To check in design: the copies must give the same results. A copy that differs is a behavior change, and its pull request must say so; the map and route test vectors must not change.

Activity

  1. added a commit that references this issue on Nov 11, 2026
  2. timohueser commented on Nov 11, 2026

    @timohueser
    OwnerAuthor

    Combined flash test for #3365 and #3356

    Both pull requests are merged (#3365 as a98ff2ebf). One flash of develop covers both. Run obc flash and keep RTT open.

    Display (#3356, from "Done when" of #2986)

    • The boot frame and the home screen show no stale rows.
    • Pan the map: only the changed parts update, with no stripes.
    • Hold a button: the bulge appears, the map redraws around it with no flash of the bulge, and on release the bulge rows clear with no remains.
    • RTT shows no frame TIMEOUT. If a timeout or a relaunch occurs, the next frame repaints the whole panel outside the bulge. After one failed bulge push during a hold, look for a stall or a flash.

    Foundations fixes (#3365)

    • Send one map or route to the device over USB or BLE. The transfer completes (the CRC still matches the companion app).
    • Start navigation, restart the device, and check that navigation continues (the Navigator checkpoint still reads back).

    Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions