# upApp: upXlink as an Android app

Kotlin Android app that talks to the media unit of a VW e-up! (and Citigo e iV / Mii electric).
It reimplements two Python projects:

- MIBBridge: tunnel protocol over Bluetooth RFCOMM channel 5.
- upXlink: registration, TLS-PSK session, REST (VIWI) access, entity parsing.

## How the original works

1. Phone opens RFCOMM channel 5 to the car.
2. MIBBridge protocol multiplexes virtual TCP connections over that socket.
   Segment header: `port u16le | type u8 | ...`. Types: TRANSMIT 0 (`len u16le` + data), OPEN 1 (`dst u16le`), CLOSE 2, HEARTBEAT 3 (echo it).
3. `GET http://car:80/car/info/vin` (plain HTTP) returns the VIN.
4. No stored credentials for that VIN: `POST http://car:80/auth/registration` returns 303 with `content-location`.
   `GET https://car:443<location>` with TLS 1.2, `ECDHE-RSA-AES128-GCM-SHA256`, no cert check, legacy renegotiation allowed.
   The user confirms a PIN on the car display. The body is `username,password`.
5. All further requests use TLS 1.2 with `PSK-AES128-CBC-SHA256` (identity = username, key = password).
6. REST endpoints: `/car/batteries`, `/car/info`, `/car/ranges`, `/chargingmanager/{providers,profiles,timers}`.
   The first profile is the default profile. Departure times are UTC.

## Key technical decisions

- **TLS: BouncyCastle low-level API (`bctls`).** Android's Conscrypt (BoringSSL) has no `TLS_PSK_WITH_AES_128_CBC_SHA256`.
  BC's `PSKTlsClient` supports it. BC also lets us skip cert checks and allow legacy renegotiation for registration.
- **No localhost TCP bridge.** MIBBridge listens on local ports so that `requests` can connect.
  On Android we run TLS directly on the in-process tunnel streams. This removes ports, threads and the proxy layer.
- **Minimal HTTP/1.1 client** over the TLS stream (request line, headers, Content-Length or chunked body).
  OkHttp cannot use a BC TLS-PSK stream.
- **JSON: `org.json`** (part of Android). No serialization library.
- **Credentials:** app-private SharedPreferences keyed by VIN. `allowBackup=false`.
- **Bluetooth:** pick from bonded devices, no scanning. Permission `BLUETOOTH_CONNECT` (API 31+).
  Connect by the SDP service UUID from maps+more. See docs/maps-and-more.md.
- **UI:** Jetpack Compose, Material 3, single activity, coroutines on `Dispatchers.IO`.
- **License:** AGPL-3.0-or-later (EUPL-compatible). Attribution to upXlink and MIBBridge in the README.

## Files (target)

```
app/src/main/java/.../
  Tunnel.kt        MIBBridge segment codec, reader loop, heartbeat, virtual connection streams
  Tls.kt           BC TLS clients: registration (ECDHE-RSA) and session (PSK)
  Http.kt          minimal HTTP/1.1 request/response
  Car.kt           connect flow: VIN, credentials, registration, get/post
  Model.kt         Battery, Info, Range, ChargingManager parsing
  MainActivity.kt  Compose UI: device picker, dashboard, charging manager, raw GET/POST console
app/src/test/...   codec test, parser tests (ported from upXlink fixtures)
```

## Phases

1. **Setup.** Android SDK, Gradle project, JDK 21.
2. **Transport.** Tunnel, TLS, HTTP, registration, raw GET/POST console. First car session: register and read `/`.
3. **Read parity.** Battery, range, info, charging manager. Unit tests with the upXlink fixtures.
4. **Roadmap items** (see below). Each needs car sessions.
5. **Docs.** README with protocol notes and the endpoint list we discover.

## Roadmap items from upXlink

| Item | Status | Needs |
|---|---|---|
| Charging manager write | Done | Tested in the car: timer edits, off-peak days, location create and delete. Location and options edits untested. |
| WebSocket events | Done | Tested in the car. |
| Cert check at registration | Done | Tested in the car. |
| PIN calculation | Done | Tested in the car. |
| Documentation | Done | README and docs/maps-and-more.md. |
| MediaControl | Open | Explore `/` and `/media/*` on the car. Scope depends on what the car exposes. |
| Infotainment keys | Open | Events arrive and are logged. Map keys to screens, like maps+more. |
| Missing location fields | Open | Temperature, min. level, more operations in the location editor. |
| Car clock sync | Open | maps+more sets the car date and time from the phone. |
| Release build | Open | R8, signing, Play listing. Debug logging of raw responses still on. |

## Debugging in the car

- Laptop to phone over USB or wireless adb: install, `logcat`, run the raw console.
- API exploration needs no new code: run upXlink on the laptop over the laptop's own Bluetooth.
- Optional: Bluetooth HCI snoop log of maps+more. Payloads are TLS encrypted, so value is limited.