Skip to content

Repository navigation

AGENTS.md

Latest commit

 

History

History
65 lines (50 loc) · 3.41 KB

AGENTS.md

File metadata and controls

65 lines (50 loc) · 3.41 KB
Raw

AGENTS.md — EVHardware

Shared vehicle-access library for the SAIC MG4 (AAOS 9, MT2712), consumed by EVProfile, EVTasker, EVABRPUploader and EVChargePilot via git submodule + Gradle subproject.

EVHardware is the shared vehicle layer for EVSuite. The workspace AGENTS.md and normative workspace DESIGN.md apply; this file defines library-specific invariants.

Commit author: malys.training@gmail.com

License exception: EVHardware's own sources use PolyForm Noncommercial 1.0.0, not the workspace MIT default.

Why this exists

One implementation of the reflection hardware layer, the 0 km/h gate, the models, and the condition/action catalogue — so the apps do not each re-derive vehicle access and drift. The apps are thin; the vehicle lives here.

Non-negotiables

  • The 0 km/h gate is here. VehicleWriteGate decides every vehicle-setting write inside the low-level write primitives. Every setter carries @RequiresStandstill; coverage keeps the set honest. Unknown or negative speed fails closed, and a moving reading is never rescued by anything. The threshold is fixed at a readable 0 km/h, with no caller override and no park rescue.
  • Per-firmware routing, never universal. SWI68/69/131/132/133/165 differ; dispatch through FirmwareInfo. Any new vehicle call must branch per generation.
  • Unreadable ≠ a value. Getters return null / -1 when the layer is not ready or the property is absent; callers must treat that as "unknown", never as 0/false.
  • Energy semantics are shared. Property ids, units, sign convention, physical validation, fallback order, trip integration and charging-session integration belong in telemetry/. Consumers own their UI, sampling cadence and network payload only.
  • @SupportedOn is the source of truth for docs/firmware-matrix.md (generated, never hand-edited) and for consumers' runtime filters. A vehicle catalogue entry without it fails the tests.
  • Never write an unverified AOSP id. The climate and window ids currently known are used for reads only. Writes go through saic.*, with every constant documented and validated per supported firmware generation.
  • English only — code, comments, commits, docs. User strings in values/ (English) + values-fr/.

Consuming it

Submodule at ./EVHardware; settings.gradle.kts includes EVHardware/lib as :evhardware; app depends on project(":evhardware"). The library declares no permissions and no sharedUserId — vehicle-write capability is the app's platform-signing decision, not the library's.

Every consuming app tracks the HEAD of master. Never pin an older commit, and never commit on a detached submodule HEAD: the catalogue is shared, so an entry removed here must disappear from every app at once, and two apps on two lines of this library means the same change written twice and reconciled by hand afterwards. Land library work in the standalone checkout, push it, then move each app's pointer forward and run that app's tests.

Reflection + R8

All vehicle access reflects android.car (absent from the compile SDK). consumer-rules.pro keeps the reflected names (android.car / SAIC / models / catalogue enums / @SupportedOn) so a consumer's R8 does not strip them. Verify a minified consumer on a vehicle.

Build

mise run test | build | check. JDK 17. Tests are JVM-only (no emulator): gate decision, firmware annotations, catalogue consistency, matrix generation.