From 4b20820dedfa72f0c1f384a36e24754149767888 Mon Sep 17 00:00:00 2001 From: Ashin Walpola Date: Mon, 8 Jun 2026 16:23:08 +0200 Subject: [PATCH] docs: add project README --- README.md | 80 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 79 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index fac56d5..6006d33 100644 --- a/README.md +++ b/README.md @@ -1 +1,79 @@ -# hi this is the app for micrOBU \ No newline at end of file +# MicrOBU Android App + +Android companion app for the micrOBU; a compact V2X on-board unit developed by HAW Hamburg and consider it GmbH for vulnerable road users (cyclists, e-bike riders, pedestrians). + +The app serves as the HMI for the micrOBU hardware, handling V2X message display, sensor data collection, trip recording, and OBU communication over USB-C, Wi-Fi (dev), and Bluetooth (upcoming). + +**Platform:** Android (Kotlin) · **Min SDK:** 29 (Android 10) · **Target SDK:** 36 + +## What it does + +**Real-time V2X monitoring**; subscribes to the OBU's MQTT broker and displays live CAM, DENM, SPAT, MAP, and CPM messages grouped by topic with pretty-printed JSON and TX/RX badges. + +**DENM transmission**; triggers DENM use cases (e.g. stationary vehicle warning `hln-sv`) on the OBU via the consider it Use Case API (`v2x-uca/input/denmtrg`) with a single tap. + +**Sensor monitoring**; live readout of phone GNSS, accelerometer, gyroscope, magnetometer, and barometer alongside OBU GNSS for cross-reference. + +**Trip recording**; foreground service records all sensor streams and detects cycling events (braking, turning, stopping) using orientation-independent signal processing. Works fully offline with no OBU connected. + +**Trip review**; past trips displayed on an OpenStreetMap layer with detected events overlaid as coloured pins. Tap any pin for event details. + +**CSV export**; every sensor sample written to a timestamped CSV in real time during a session. Shareable via the standard Android share sheet. + +## Architecture + +MVVM with Repository pattern throughout. Jetpack Compose for all UI (no XML layouts). Hilt for dependency injection. + +``` +ui/screens/ Compose screens (Dashboard, V2X Monitor, Sensors, Recording, Trip History, Settings…) +ui/navigation/ Navigation graph and bottom nav bar +viewmodel/ MqttViewModel, SensorViewModel, TripRecordingViewModel +data/mqtt/ MQTT repository, Paho client, exponential-backoff reconnection +data/transport/ USB tethering detection and gateway IP resolution +data/db/ Room database (sessions, trips, detected events) +data/ SensorRepository, TripRepository, CsvExporter +domain/detection/ EventDetector, RunningStats sliding window (orientation-independent) +service/ TripRecordingService (foreground service) +``` + +## Connectivity + +The app uses a phased transport strategy. The MQTT client, topic subscriptions, and all UI are identical across transports; only the underlying network path changes. + +| Phase | Transport | Status | +|---|---|----------| +| Phase 01 | Wi-Fi | Complete | +| Phase 02 | USB-C tethering | Active | +| Phase 03 | Bluetooth BLE | Future | + +The MQTT broker runs on the OBU hardware (Mosquitto 2.0.11, port 1883). In Phase 02, Android USB tethering exposes the OBU as a virtual Ethernet interface at `192.168.42.x`. The app auto-detects the gateway IP on plug-in. + +## Key dependencies + +| Library | Purpose | +|---|---| +| Jetpack Compose + Material3 | UI | +| Eclipse Paho MQTT | OBU communication | +| Room | Local database | +| Hilt | Dependency injection | +| OSMDroid | Trip review map | +| DataStore | Settings persistence | +| FusedLocationProviderClient | GNSS | + +## Getting started + +1. Open in Android Studio (Hedgehog or newer). +2. Connect a device running Android 10+ (API 29). +3. Build and run the `app` module. +4. For Phase 02 testing: plug the phone into the OBU via USB-C, enable USB tethering on the phone, and the app will detect the interface and connect automatically. Broker IP can be overridden manually in Settings → Connection. +5. For standalone trip recording: no OBU required. Go to the Record tab and tap Record. + +The Wi-Fi transport (Phase 01 broker at `192.168.3.202`) remains available in developer builds and can be toggled in Settings → Developer. + +## Project context + +The micrOBU project is funded under the ZIM program (BMWK) and targets micromobility users in Hamburg. The companion app offloads processing from the compact OBU hardware to the smartphone; GNSS fusion, event detection, and future antenna coordination all run on the phone to keep the OBU lightweight and power-efficient. + +V2X communication uses ITS-G5 (IEEE 802.11p / DSRC) at 5.9 GHz. The app communicates with the OBU exclusively via the consider it MQTT API v6 (processed JSON messages); no ASN.1 encoding in the app. + +**Owner:** HAW Hamburg