Differences

This shows you the differences between two versions of the page.

--- dev [2026/08/08 01:12] – external edit 127.0.0.1
+++ dev [2026/08/18 21:47] (current) – external edit 127.0.0.1
@@ Line 2: / Line 2: @@
 How to set a machine up to build, sign, install and debug apps for the Aiways U5 head unit
-(Adayo i.MX6, Android 4.4.2). See [[hardware|Hardware & OS]] for the platform and [[access|Root / ADB]]
+(Adayo i.MX6, Android 4.4.2). See [[hardware|Hardware & OS]] for the platform and [[access|How to get in]]
 for getting in.
-===== What you need =====
+===== Examples =====
+Four small apps you can install on the car — good starting points that show how the pieces fit together. Each runs as system (''sharedUserId="android.uid.system"''), is platform-signed.
+^ App ^ What it does ^ Download ^
+| **OpenAiways Connect** | Automatically connects to a given Wi-Fi and enables ADB-over-Wi-Fi. | [[https://codeberg.org/noonscoomo/openaiways/raw/branch/main/android-connect/openaiways-connect.apk|openaiways-connect.apk]] |
+| **OpenAiways Telemetry** | Reads CAN signals and publishes them to MQTT with Home Assistant auto-discovery. | {{:openaiways_telemetry.apk|openaiways-telemetry.apk}} |
+| **OpenAiways Terminal** | A VT100 terminal with an advanced keyboard; runs as system, or as **root** if you press the **su** button . | {{:openaiways_terminal.apk|openaiways-terminal.apk}} |
+| **OpenAiways Speedwarning** | Shows the current speed limit on the driver panel and warns when you exceed it — fully offline, from an on-board map index. | {{:openaiways_speedwarning.apk|openaiways-speedwarning.apk}} |
+==== Installing ====
+  - Sideload the ''.apk'' (copy to a USB stick or download it on the unit) — see [[access|How to get in]] for the file-manager route.
+  - **Open each app once** after installing. Android keeps a freshly-installed app in a "stopped" state where it does not receive the boot broadcast, so this first manual launch is what arms auto-start.
+  - Configure it (below). Connect and Telemetry then **auto-start on every reboot**; Terminal is launched by hand when you want a shell.
+==== OpenAiways Connect ====
+Add your Wi-Fi networks (SSID + password, as a priority list) and tick **ADB**. After boot it reconnects Wi-Fi and re-enables adb-over-Wi-Fi.
+Source: https://codeberg.org/noonscoomo/openaiways/src/branch/main/android-connect
+==== OpenAiways Telemetry ====
+Enter your MQTT broker (host, port, user, password) and a base topic. With Home Assistant auto-discovery the car shows up automatically — state of charge, voltage, current, range, charging and more.
+==== OpenAiways Terminal ====
+A proper terminal (based on jackpal's emulatorview) with its own on-screen US keyboard, so the device's IME is not needed.
+  * The **''su''** key switches the shell to **root** and back — when you are root it reads **''system''**. Root is a real ''uid 0'' PTY served by the local adbd. **warning - you can do everything as root, even kill you system. Use on your own risk**
+  * The **×** in the top-right corner closes the terminal.
+  * **One adb client at a time:** the unit's adbd serves a single connection, so while the terminal holds the root shell a laptop's ''adb'' cannot connect (and vice-versa). Leaving or closing the terminal frees adb again automatically.
+{{:terminal_keyboard.png?600|OpenAiways Terminal — built-in US keyboard and root/su switch}}
+==== OpenAiways Speedwarning ====
+Shows the current **speed limit** on the driver panel and blinks + beeps when you drive faster than it — fully **offline**, no cloud and no OEM data.
+**How it works:** live speed comes from the **CAN bus**, position from **GPS**. An on-board **HMM map-matcher** (Newson–Krumm style) fits the GPS track to the road //sequence// in an offline **OpenStreetMap** index — so it stays on the correct road under bridges, in tunnels (it coasts on CAN odometry until GPS re-acquires), and past parallel streets, then reads that road's limit (including time-dependent //"30 km/h 07–19h"// style zones). The sign renders on the reachable **driver panel** (see [[architecture]]).
+**The map index (required):** the app reads an offline road/speed index at ''/sdcard/region_route.sqlite''. A ready-made one:
+  * {{:region_route.sqlite|region_route.sqlite}} — **Berlin / Brandenburg** region (~34 MB; 144k roads, 129k with limits, 4,879 time-dependent zones, 311 tunnels; bbox lat 52.07–52.68, lng 12.67–14.74).
+For another area you build your own index from OpenStreetMap with the map-matcher pipeline (source to follow). Without an index the app runs but shows no limit.
+**Install:**
+  - Sideload ''openaiways-speedwarning.apk'' and **open it once** (arms auto-start; it then runs on every boot).
+  - Put the index on the unit as ''/sdcard/region_route.sqlite'' (e.g. ''adb push region_route.sqlite /sdcard/''), then tap **Restart service**. The status screen should read //Map DB: loaded//.
+  - Drive — the limit shows on the driver panel and warns when you're over it.
+//It also records your drives to ''/sdcard/aiways_track.csv'' (size-capped, auto-rotated to ≤32 MB) to help improve the matcher.//
+===== What you need to make your own software =====
   * **Android Studio** (any recent version) + the **Android SDK**. The unit is **Android 4.4.2 (API 19)**, so set **''minSdkVersion 19''** (''compileSdk'' / ''targetSdk'' can be higher). The ABI is **armeabi-v7a** — don't ship arm64/x86-only native libraries.
@@ Line 22: / Line 76: @@
 '' then ''stop adbd; start adbd''.
-===== Signing — the one thing to know =====
+===== Signing — the platform key =====
-Several of our apps declare **''sharedUserId="android.uid.system"''** so they can bind the OEM services
+Several of these apps declare **''sharedUserId="android.uid.system"''** and use ''signature''-level permissions, so they must be signed with the **platform key** — the key the device's own framework is signed with. Android only grants that system identity to an app whose signing certificate matches the platform's.
-and use system permissions. That requires the APK to be signed with the **platform key**.
-**On this setup no signing config is needed:** the build machine's **''~/.android/debug.keystore'' is
+**The head unit was never re-keyed.** (at least for my 1.7.0 firmware) It is a Freescale/NXP **i.MX6 Android BSP** build, and the OEM shipped it signed with the BSP's **public test key** instead of a private release key — so signing an app with that same public key is enough to run as system. The key is self-signed:
-the AOSP platform test-key**, so a plain debug build is already platform-signed. Build and install:
+  Subject : C=US, O=Android, CN=Android, emailAddress=android@freescale.com
+  Valid   : 2011-07-14 -> 2038-11-29
+  SHA-256 : 7F:BA:E8:17:B7:DB:24:64:2D:89:59:C3:47:B5:61:C0:03:C6:CF:DE:2C:B1:0F:90:9C:93:2F:21:A4:D6:D8:04
+Because that key is **public**, anyone can sign a system-privileged app for this unit — an OEM security lapse, and exactly what makes this project possible. NXP reused the same key across every i.MX BSP for about a decade, so it is easy to find.
+==== Where to get it ====
+It lives in the i.MX device tree under ''common/security/'': ''platform.pk8'' (private key) and ''platform.x509.pem'' (certificate). A public mirror:
+  https://github.com/Avnet/android-imx-device-fsl/tree/maaxboard_android_p9.0.0_1.0.0/common/security
+Check you have the right one — the certificate must match the fingerprint above:
+  openssl x509 -in platform.x509.pem -noout -fingerprint -sha256
+==== Make a keystore and build ====
+Turn the BSP key pair into a keystore Gradle can use (''platform.pk8'' is DER PKCS#8):
+  openssl pkcs8 -inform DER -nocrypt -in platform.pk8 -out platform.key.pem
+  openssl pkcs12 -export -in platform.x509.pem -inkey platform.key.pem -name platform -out platform.p12 -passout pass:android
+Point the app's ''signingConfig'' at ''platform.p12'' (store & key password ''android'', alias ''platform''), then build and install:
   ./gradlew :app:assembleDebug
   adb -s <HEAD-UNIT-IP>:5555 install -r app/build/outputs/apk/debug/app-debug.apk
-''install -r'' replaces in place, and on a **signature mismatch it fails safely** (the old app stays),
+''install -r'' replaces in place and **fails safely on a signature mismatch** (the old app stays), so it is safe to try. //Alternatively, put the same key at ''~/.android/debug.keystore'' so ordinary debug builds are platform-signed without a ''signingConfig''.//
-so it's safe to try. //(On a machine whose debug key is NOT the platform key, an app with the system
-sharedUserId won't install — put the platform test-key at ''~/.android/debug.keystore'', or add an
-explicit ''signingConfig''.)//
 ===== Talking to the car from an app =====
@@ Line 59: / Line 133: @@
 ===== No-code CAN probing =====
-To try keys without writing an app, the **CarMqttBridge** bridge has a built-in probe (it already
+To try keys without writing an app, **[[dev#openaiways_telemetry|OpenAiways Telemetry]]** has a built-in
-binds ''ICanbusService'') — read or command any [[cansignals|key]] straight from adb. See
+probe (it already binds ''ICanbusService'') — read or command any [[cansignals|key]] straight from adb.
-**[[canbus#probing_signals_live|CAN bus → Probing signals live]]**.
+See **[[canbus#probing_signals_live|CAN bus → Probing signals live]]**.
+===== Also: the ESP32-S3 companion (separate hardware) =====
+Not a head-unit app — a standalone **ESP32-S3** you wire into the car, for people who don't want to (or can't) get onto the head unit at all. One board does four things at once:
+  * **Talks to the TBox over BLE** (BlueGate protocol) → **preconditioning** and **remote control** (lock/unlock/flash lights/trunk/windows).
+  * **Reads a BLE OBD2 dongle** (ELM327) → SoC, HV voltage/current, cell voltages, temperatures; kept in flash so the last-known values survive when the car is off/unreachable.
+  * **Publishes to MQTT with Home Assistant auto-discovery** — sensors plus Precondition/Lock/Unlock/Flash/Trunk controls appear automatically in HA.
+  * **Runs a Wi-Fi hotspot + web dashboard** at the same time as the home-Wi-Fi/MQTT link, so you can control/monitor from a phone even with no home Wi-Fi nearby. Firmware updates go out **over Wi-Fi** after the first USB flash.
+A prebuilt image and a browser-based flasher (no toolchain needed) are on its own page:
+  https://codeberg.org/noonscoomo/openaiways/src/branch/main/esp32-companion
+//🤖 AI-assisted development — reviewed before trusting it on a real vehicle, same disclaimer as the apps above.//