Repository navigation
Description
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 checkalready refuses a dependency on a crate of another system, because the foundations doc listsdepends_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 onlyheapless,libmand 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.IndexBlockCachehas three users, and all of them are inobc-reader:reader/cache.rs,reader/nav/cache.rsandreader/places/cache.rs. The terrain reader (obc-elevation) and the route reader (obc-route) use onlylru_victim, a 14-line function that picks the slot to evict. The cache moved intoobc-formatsbecause 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: moveIndexBlockCacheandINDEX_BLOCKintoobc-reader, and giveobc-elevationandobc-routetheir 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 useground_dist_m,cos_lat,delta_mandM_PER_DEG, among themobc-bake,obc-network,obcm-assembleandobc-dem, which do not draw a map. Other crates still have their own copy of the 111,320 m-per-degree constant, for examplebuilder/wasm/src/gpx.rs,host/obc-network/src/nav.rsandhost/obc-search-bake/src/postcodes.rs. Action: refactor issue: move the helpers into a smallgeomodule inobc-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.Cuelists 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 thegeorefactor above. - The
ContentRefencode and decode functions are written by hand three times.firmware/obc-formats/src/articles.rs:27,obcm/peaks.rs:49, and the private copy inobcm/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 namesobc-elevation, which belongs to the map-reading system, and it leaves outobc-crcandobc-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:204says that a category byte outside1..=6renders as generic. The readers decode the byte withPoiCategory::from_id, so ids 8 and 10–12 render as their categories. The GPX import writes only0..=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:41says that1..=6are thePoiCategorywire 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 inobc-route/src/reader.rs). DateTime::to_unixtruncates tou32with no warning.firmware/obc-ports/src/lib.rs:117. After 2106 it gives a wrong time;to_unix_i64is the safe form. Action: fix: say it in the doc comment. Fixed in foundations: fix the small findings of #3363 #3365.obcm.rsmixes several jobs in 1,050 lines.firmware/obc-formats/src/obcm.rs. It holds the header constants, the producer-onlyUnitWriter, the navigation record walk and the POI tables. Action: refactor issue: split it into modules inside the crate.- The file name
assistant.rsdoes not match its content.firmware/obc-formats/src/assistant.rs:1. The file holds the Navigator checkpoint codec. Action: fix: rename the module tonavigator. 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") andfirmware/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::checksumand the free functioncrc32do the same thing.crc32has about 100 callers andCrc32::checksumhas 3. Action: fix: removeCrc32::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:
- Dependency guard. Add a check that reads the
[dependencies]of the five foundation crates and allows onlyheapless,libmand the other foundation crates. Cite it in the Rules table ofdocs/design/foundations.md, together with the existingcairn checkdependency rule, and remove the sentence that says no check exists. ContentRefcodec. Make the landmarks codec public and use it inarticles.rsandobcm/peaks.rs.- Architecture guide. Correct the list of foundation crates in
docs/content/software/architecture.md, as its owndocs:commit. - Comments and names. Correct the
1..=6comment inobcr.rs, add the 2106 limit to theto_unixdoc comment, renameassistant.rstonavigator.rs, and remove the two version-history comments. - CRC. Remove
Crc32::checksumand move its 3 callers tocrc32. - Doc. Add the
Cuedecision 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
Merge pull request #3365 from timohueser/claude/3363-foundations-fixes
timohueser commentedon Nov 11, 2026
Combined flash test for #3365 and #3356
Both pull requests are merged (#3365 as
a98ff2ebf). One flash ofdevelopcovers both. Runobc flashand keep RTT open.Display (#3356, from "Done when" of #2986)
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)
Generated by Claude Code