mg4/OTA.md

Updating the car app over the air

How a new car build reaches the head unit without the Bluetooth-settings detour, and what to check when it does not.

build-car ─▶ publish-car ─▶ forge pre-release (private repo, git.stinnesbeck.com/nils/mg4)
                                   │  read with FORGE_TOKEN (read-only, server Secret)
                                   ▼
                           car server  /v1/app/releases, /v1/app/assets/…
                                   │  the car's own paired token
                                   ▼
          app: Settings → Check for updates → SHA-256 → install

The repository stays private and the forge token stays on the server: the car asks its own server, with its own token, and never holds a forge credential. The server only relays bytes. Every check that decides whether code gets installed is in the app.

Publishing a release

1. Raise the version in app/build.gradle (versionCode must increase; versionName is three-part, e.g. 2.16.0). The car build reports it as 2.16.0-unstable.
2. Build: nix develop, then build-car. It signs with the AOSP platform key the head unit trusts, checks the signer, and writes build/car/NilsMG4-unstable-<version>.apk and its .sha256.
3. Publish: publish-car. It creates the pre-release car-<version> on the current commit and attaches the APK and the .sha256. It needs a forge token that may write the repository's releases, in ~/.config/nilsmg4/forge-token (or $FORGE_TOKEN); the token is only sent in a header, never printed. It refuses a version that is already published.

By hand, the same: in the forge's web UI create a release with tag car-<version>, tick pre-release, and attach both files with exactly their names.

What the updater accepts

The app asks the car server for the releases (GET /v1/app/releases) and walks every one, keeping the highest version:

Requirement	Where it is enforced	Otherwise
Marked pre-release, not a draft	selectUpdate	Skipped
Asset name contains unstable and ends -<version>.apk	ASSET_VERSION regex	Ignored
Version strictly higher than installed	isNewer()	"Up to date"
Every URL https and exactly the configured server's host	isAllowedUrl()	Refused
A matching .sha256 (or SHA256SUMS) asset, and the APK's bytes match it	fetchExpectedSha256(), download()	Refused, file deleted
The archive is this app's package	archiveIsThisPackage()	Refused
Signed with the same certificate as the installed app	Android's installer	Not installed

The version comes from the asset file name, not the tag.

Installing

Press Check for updates on the Settings tab. The app checks, downloads the APK into Downloads (with progress), verifies its SHA-256, and hands it to a PackageInstaller session. As the system user it may install without asking; if the platform wants a confirmation, the confirmation screen opens. When a session cannot start at all, the file manager opens in Downloads (or, where the head unit has none, open the APK there with the Files app). The verified APK stays in Downloads either way.

At start the app only checks, and shows "Update available" when there is one. It never downloads or installs on its own, and the upload service never checks: installing restarts the app, which must not happen mid-drive on its own.

Installing from a USB stick

For development, without the forge: copy NilsMG4-unstable-<version>.apk and its .sha256 from build/car/ to the top folder of a USB stick, plug it in, and press Install from USB stick on the Settings tab. The app takes the newest such file that is newer than the installed version, checks it against the .sha256, checks the package, and installs it with the same installer session as an over-the-air update. The car build only; the stable build has no button.

On the Android 9 emulator (car build, system user) this installed without asking, from the storage's top folder; on the car the stick's top folder is used the same way.

When it says something else

Message	Meaning
Up to date (2.16.0-unstable)	No published pre-release is newer. Check the pre-release tick and the asset name.
Set up the server first (Server tab): updates come through it	The app has no server URL and token.
Update check failed	The server could not be reached, or answered with an error: 404 when updates are off on the server (no FORGE_TOKEN), 502 when the forge refused the server's token.
Update refused: no SHA-256 verification	The release has no matching .sha256, or it is unreadable.
Download or SHA-256 verification failed (…)	The download broke off, or the bytes do not match the published hash.
Update refused: the downloaded file is not this app	The archive does not parse, or it is another package.
Installing 2.16.0… the app restarts when it is done	The session was committed; the result follows as its own toast.
Installation failed: INSTALL_FAILED_… The APK is in Downloads.	The package manager's own words. A signature error means the APK was not signed by build-car.
… is in Downloads — tap the file to install	A session could not start; install from Downloads by hand.

On the car's Logs tab, or with a cable: adb logcat -s EVABRP.Update OtaUpdater.

Why a PackageInstaller session, not pm install

Upstream first shelled out to /system/bin/pm install -r with the APK in the app's private cache. That fails on this head unit: pm hands the path to the package manager service, which opens it from its own process and SELinux context, where an app's private cache is not readable — and the failure surfaced as a signature error it never was. A session takes no path: the app opens the archive itself and streams it in. The approach comes from merthankaraman/DriveHub_Dort, which hit the same wall on the same hardware. Upstream later fell back to "download to Downloads and tap it"; this fork tries the session first and keeps that as the fallback.

Not yet tried on this car: whether the session installs silently as the system user, or asks for a confirmation.