mirror of
https://github.com/firestar5683/StarPilot.git
synced 2026-11-15 00:43:46 +08:00
firestar5683
ab81464bd1
Add navigation and map matching providers with the vendored map service sources. Co-authored-by: Daniel Koepping <elkoled@gmail.com> Co-authored-by: Danny <dannyirwin31@yahoo.com> Co-authored-by: Prabhaav Pillai <prabhaav@msu.edu> Co-authored-by: dirwin31 <83434411+dirwin31@users.noreply.github.com>
57 lines
3.6 KiB
Markdown
57 lines
3.6 KiB
Markdown
# Development Mapd shadow lifecycle
|
||
|
||
`MapdShadowEnabled` is an optional, persistent, nonlogged Boolean with default
|
||
false. The manager reads its exact raw `1` byte only onroad in a real car;
|
||
missing, malformed, symlinked, oversized or special-file values remain off.
|
||
The registered native child launches only the fixed packaged `mapd --shadow
|
||
--offline-root /data/media/0/starpilot/maps/offline` command. It uses the
|
||
ordinary manager SIGINT/SIGKILL stop path and reaps a failed child with a
|
||
bounded 1–60 second retry. The offline root must already exist under the new
|
||
StarPilot-owned storage tree. A named `OPENPILOT_PREFIX` uses its separate
|
||
`starpilot-<prefix>/maps/offline` store, shared with that instance's downloader. No legacy Mapd directory is moved, read as a
|
||
fallback, downloaded or repaired by this owner.
|
||
|
||
The package is **generated**, never committed. On a Linux ARM64 build host
|
||
with Go 1.25.1, cached pinned modules, C compiler and zlib, run
|
||
`python -m openpilot.starpilot.maps.package_shadow --go /absolute/pinned/go`
|
||
from the checkout. The recipe uses read-only modules and disabled Go network,
|
||
stamps the current provider source digest and pinned upstream revision, checks
|
||
the actual ELF ARM64/static headers and writes `provider/mapd` plus a bounded
|
||
manifest. Launch preflight checks the fixed files, executable permission,
|
||
binary hash, embedded stamps, current source digest/pin and an owned, non-symlink
|
||
offline root. A changed provider source or binary leaves the feature unavailable
|
||
until a matching package is rebuilt.
|
||
|
||
The root also requires an admitted `current.json` snapshot selector and a
|
||
bounded receipt whose exact bytes hash to the selected generation name.
|
||
Python preflight checks the selector/receipt identity; the Go shadow checks
|
||
aligned coverage metadata at startup and hashes/decodes each requested tile
|
||
against that pinned receipt. Admission is available through explicit offline
|
||
commands and the separate parked map-operation owner. Neither restarts an already running shadow, and prior
|
||
generations remain in place. See
|
||
`mapd_repo/maps/SNAPSHOTS.md` for format and import limitations.
|
||
|
||
`tools/release/release_files.py` copies **tracked files only**, so this generated
|
||
package is **not** in a release by default. A reviewed release assembly would
|
||
run the same packaging command with
|
||
`--output <staging>/openpilot/starpilot/maps/provider` **after** tracked source
|
||
copy and **before** image finalization. The disposable staging fixture test
|
||
checks this insertion path; it does not install anything or make an image.
|
||
There is no manager default shadow activation, `mapdIn` publisher,
|
||
plannerd subscription, or SLC numeric authority. Authenticated Galaxy can
|
||
request a bounded region download through the parked owner described in
|
||
`MAP_OPERATIONS.md`. Existing Galaxy observations remain diagnostic and `MapTracker` continues to return UNKNOWN
|
||
for control.
|
||
|
||
`TestShadowExecutableHostGpsIPC` explicitly requires a host Python and an
|
||
environment gate. It builds a temporary executable from the current pinned
|
||
toolchain, admits a tiny synthetic PBF with `--snapshot-admit`, then runs
|
||
**only** `--shadow` with private IPC/Params and the selected generated tile.
|
||
It verifies actual host GPS events through the Go subscriber,
|
||
MapdOut and Python status, including invalid/old GPS, fallback, stale loss,
|
||
restart and ignored non-GPS inputs. The fixture proves transport/lifecycle,
|
||
not map correctness, real offline data licensing, Linux device timing or a
|
||
qualified road speed limit. The full-provider path remains inactive; its
|
||
separate `mapdOut` queue-size mismatch and ungated car/model/selfdrive inputs
|
||
must be resolved before any future full mode.
|