34 lines
2.1 KiB
Markdown
34 lines
2.1 KiB
Markdown
# Android companion
|
|
|
|
The Android app is a focused native companion rather than a copy of the web dashboard. It connects directly to the Pi's BLE GATT service and provides:
|
|
|
|
- live Pi health, temperature, memory, storage, and ADB connection status;
|
|
- live car speed, gear, steering, battery, range, and lifetime statistics;
|
|
- launch access to ADB shortcuts that were explicitly saved in the web dashboard;
|
|
- phone GPS, speed, bearing, accuracy, battery, and network-state uplink;
|
|
- background BLE reconnection and location updates through a foreground service.
|
|
|
|
## Pairing
|
|
|
|
1. Deploy the latest Pi release with `./install.sh` so BlueZ and the Bluetooth bridge are installed.
|
|
2. Open **Settings → Mobile** in the web dashboard and select **Pair a phone**.
|
|
3. If needed, turn Bluetooth on and select **Make discoverable**. The Pi remains discoverable for three minutes.
|
|
4. Install and open the Android application and grant Bluetooth, notification, and precise-location permissions.
|
|
5. Enter the six-digit code shown by the dashboard.
|
|
|
|
The one-use code expires after ten minutes. The resulting credential is encrypted with Android Keystore and can be revoked from **Settings → Mobile**. A phone can only launch existing allowlisted ADB shortcuts; the Bluetooth protocol has no shell, arbitrary ADB, APK upload, update, or power operation.
|
|
|
|
## Build
|
|
|
|
Open this `android/` directory in Android Studio (JDK 17, Android SDK 35) and run the `app` configuration, or build the downloadable APK from the repository root:
|
|
|
|
```bash
|
|
./build-apk.sh
|
|
```
|
|
|
|
The debug APK is copied to [`apks/pi-car-companion-debug.apk`](../apks/pi-car-companion-debug.apk). Hardware validation requires an Android 8+ phone with BLE and a Raspberry Pi with a BlueZ-compatible BLE adapter.
|
|
|
|
## BLE protocol
|
|
|
|
The custom service UUID is `6c7a0001-7c6d-4f74-9bb0-c5a4e5efc001`. RX and TX carry newline-delimited UTF-8 JSON, fragmented into BLE-sized chunks. Protocol version 1 exposes only `pair`, `snapshot`, `location`, and `launchShortcut` operations. Android sends GPS at most every second and refreshes the dashboard snapshot every five seconds.
|