Entwickler-Wiki

Überblick

Der Stack ersetzt die abgeschaltete Hersteller-Cloud. Kern ist eine LTE-Bridge im Fahrzeug, die über einen Daemon auf der TBox die Fahrzeugdaten ausliest und per Mobilfunk an ein selbstgehostetes Backend schickt. Eine Flutter-App zeigt die Daten und sendet Fernbefehle; Home Assistant/EVCC hängen als Consumer dran.

• Zwei Wege ans Auto: BLE (lokal, App direkt) und LTE (remote, über die Bridge) — beide sprechen dasselbe fahrzeugeigene AICHI-Protokoll.
• Zwei Wege für Daten: Live-Signalfläche (dbcvpage, ~1000 Signale) und GB/T-32960-Ringpuffer (cache_data) plus History-Dumps (.inx).
• Selbstbestimmt: keine Hersteller-Cloud, keine Ad-/Tracking-SDKs.

Architektur

   ┌───────────────────── Fahrzeug (Aiways U5) ─────────────────────┐
   │  CAN / Fahrzeugbus                                              │
   │       │                                                        │
   │  ┌────▼─────────────────────┐        WLAN-AP 192.168.1.1:9000  │
   │  │ TBox (MDM9607 + AG35)     │◄───────────────┐                 │
   │  │  tbox_app  +  tbox_daemon │  /dbcvpage /cachedata /mqtt …    │
   │  └───┬──────────────────────┘                │                 │
   │      │ Port 50000 (0x301-Shell) / :7090 MQTT │                 │
   │      │                                  ┌─────┴───────┐          │
   │      │  BLE (AICHI, A001/B001)          │ LTE-Bridge  │          │
   │      └◄────────────────────────────────┤ ESP32-S3    │          │
   │                                         │ + A7670E    │          │
   └─────────────────────────────────────────┴─────┬───────┘         │
                                                    │ LTE (AT-HTTPS, X-Api-Key)
      ┌──────────────┐        REST / JWT     ┌──────▼───────┐
      │  AiwaysApp   │◄────────────────────► │   Backend    │
      │  (Flutter)   │   (+ BLE direkt)      │ Fastify + PG │
      └──────────────┘                       └──────┬───────┘
                                        REST/API-Key │
                                   ┌─────────────────┼───────────────┐
                              ┌────▼─────┐                     ┌──────▼────┐
                              │   Home   │                     │   EVCC    │
                              │ Assistant│                     │           │
                              └──────────┘                     └───────────┘
      

Die App kann Befehle direkt per BLE senden (in Reichweite) oder in die Backend-Command-Queue legen; die Bridge pollt sie und fährt sie per BLE ans Auto. Alles auf der Bridge läuft sequenziell — ein geteiltes LTE-Modem, ein BLE-Stack.

Datenfluss

Telemetrie (Auto → Cloud)

1. Der tbox_daemon liest die Live-Signale über die 0x301-Shell (Port 50000) und den GB/T-32960-Ringpuffer aus dem Dateisystem und hält sie im RAM.
2. Die Bridge verbindet sich mit dem TBox-WLAN, holt /dbcvpage (nur wenn das Auto wach ist), /mqtt (Backup inkl. Position) und 1×/Tag /cachedata, und POSTet sie über LTE an die Ingest-Routen (X-Api-Key).
3. Das Backend parst/bereinigt (Sanitize, Sleep-Schutz) und schreibt in Postgres; App und HA lesen per REST.

Befehle (Cloud → Auto)

1. App oder Backend legen ein Command in die Queue (POST /commands, Typ als freier String + JSON-Payload).
2. Die Bridge pollt GET /commands/pull, mappt den Typ auf den AICHI-BLE-Code, authentifiziert sich per A001 und sendet den B001-Frame.
3. Ergebnis zurück per POST /commands/:id/ack (status + result mit resCode/Detail).

Glossar

Backend TypeScript

Fastify + PostgreSQL (ESM/TypeScript). Nimmt Telemetrie an, verwaltet Nutzer/Fahrzeuge/Sharing, die Command-Queue, Firmware-Hosting & Web-Flasher, und liefert App-API, Admin-Dashboard, Landing-Page und dieses Wiki. https://forgejo.timo-erdbruegger.de/aiways/Backend ↗

• Ingest: /ingest/dbcvpage, /ingest/cache-data, /ingest/cache-info, /ingest/inx, /ingest/telemetry, /ingest/mqtt, /ingest/bridge. Auth via machineOk (Device-Token oder API-Key).
• Fahrzeuge & Halter: Historie über vehicle_owners mit halboffenen [from_ts, to_ts)-Intervallen — mehrere offene Halter = geteiltes Fahrzeug.
• Command-Queue: Lifecycle pending → sent → acked | failed | expired, Pull markiert atomar (FOR UPDATE SKIP LOCKED), Ablauf nach COMMAND_MAX_AGE_MIN=5.
• Auth: JWT-Sessions + API-Keys (oaw_…), Rollen admin/user/device.
• Frontends: /, /admindashboard, /anleitung, /datenschutz, /konto-loeschen, /wiki, /sandbox (nur außerhalb Production).

Betrieb: docker-compose (Postgres 16 + App), Start npm run migrate && npm start, davor ein Caddy-Reverse-Proxy (TLS + Cache).

AiwaysApp Flutter / Dart

Community-App für iOS und Android: Fahrzeugübersicht, Lade-/Fahrhistorie, Klima & Fernbefehle, geführte Provisionierung. https://forgejo.timo-erdbruegger.de/aiways/AiwaysApp ↗

Command-Routing (lib/command_queue.dart)

1. Typen mit Präfix set_ (z.B. set_charge_limit) gehen direkt ans Backend (Konfig/Telemetrie, kein Aktor).
2. Aktor-Befehle: BLE zuerst — bei Erfolg fertig; sonst LTE-Fallback über die Backend-Queue.
3. Scheitert beides, wird lokal persistiert (commandQueue in SharedPreferences) und bei Neustart erneut versucht. Bewusst nie beides (keine Doppelausführung).

Backend→BLE-Typ-Mapping (bleTypeFor) ist identisch zur Firmware (backendToBleType). Datenlesen über /vehicles/:id/latest|timeseries|snapshots|details|diagnostics|bridge.

Bundle-IDs: Android de.itperspective.aiways_app, iOS de.itperspective.aiwaysApp. Release-Prozess: siehe PLAY_STORE_RELEASE.md / IOS_RELEASE.md im App-Repo.

LTE-Bridge (Firmware) C++ / PlatformIO

Firmware auf Waveshare ESP32-S3-A7670E-4G. Liest die TBox per WLAN, postet über LTE, steuert das Auto per BLE — akku-adaptiv. https://forgejo.timo-erdbruegger.de/aiways/LTEBridgeFirmware ↗

Hardware & Pins

ESP32-S3R8, 16 MB Flash; PSRAM deaktiviert und memory_type = qio_qspi (nicht OPI!) — sonst kollidiert OPI-PSRAM mit GPIO33 (Modem-Power) → Boot-Loop. PlatformIO-Env: waveshare-s3-a7670e.

Fuel-Gauge MAX17048 (I2C-Adresse 0x36): VCELL 0x02 (78,125 µV/LSB), SOC 0x04 (1/256 %/LSB), CRATE 0x16 (0,208 %/h, signed). Modem A7670E: LTE Cat-1 + 2G + GNSS, IO 1,8 V über TXB0104-Level-Shifter.

Akku-adaptives Polling (power_policy.h)

Reine, host-getestete powerPlan(). Am Laden (CRATE > −0,5 %/h) oder ohne Fuel-Gauge → immer Normalbetrieb. Sonst nach SoC:

Deep-Sleep (< 10 %, nicht am Laden): Modem stromlos, esp_sleep_enable_timer_wakeup alle 1200 s — nur Timer-Wake (kein Wake-on-USB). Akkustufe wird alle 30 s neu bestimmt; g_powerMode (normal|saver|deepsleep) geht ans Backend (/ingest/bridge).

Config / NVS (Namespace bridge)

Bridge-Modus aktiv wenn ssid + backend + apikey gesetzt, sonst Diagnose-Modus. Einrichtung per serieller cfg-Konsole (cfg set …, cfg show, cfg test, cfg bat, cfg i2cscan, cfg blescan, cfg blekey, cfg blecmd <type>, cfg bletest, cfg inx[efs][dry]) — oder per BLE-Provisioning aus der App (nur im Diagnose-Modus advertised).

Read-/Post-Strecke

Remote-Verwaltung (bridge_-Commands)

Aus /commands/pull gezogen, lokal auf der Bridge ausgeführt (kein BLE), acken selbst:

Self-OTA: Update.begin(U_FLASH) in die inaktive OTA-Partition; große Downloads laufen erst ins Modem-EFS (AT+HTTPREADFILE) und dann fensterweise per AT+CFTRANTX ins ESP (CAT-1 hat nur ~10 KB HTTP-Puffer).

TBox-Daemon C

Läuft auf der TBox parallel zur originalen tbox_app. Single-Thread, hält die Fahrzeugdaten im RAM und serialisiert einen HTTP-Server auf :9000. https://forgejo.timo-erdbruegger.de/aiways/tbox_daemon ↗

Quellen

• 0x301-Shell auf 127.0.0.1:50000 — dbcvpage-Seiten, setmode (Keep-Awake).
• MQTT-IPC (admups) auf 127.0.0.1:7090 — carState/battery/power/netInfo/carInfo. Client-ID tboxd (nicht upclientOtaApp, um die echte OTA-App nicht zu verdrängen).

HTTP-Endpunkte (:9000)

Auth: Header X-Token == API_TOKEN. Datei-Zugriff nur unter FILE_ROOTS (Default /usrdata/,/mnt/sdcard/), kein ... Leerer Token ⇒ /file//ls ganz aus.

Cross-Build: Quectel ql-ol-crosstool (arm-oe-linux-gnueabi-), dynamisch gegen glibc 2.22; bei GLIBC_… not found als -static neu bauen. Version via -DDAEMON_BUILD=$(git rev-list --count HEAD). Installation per FTP nach /usrdata/tbox_daemon, Autostart-Hook in fota.sh.

TBox & Head-Unit

TBox-System

• SoC/Modem: Qualcomm MDM9607 + Quectel AG35 (armv7l), Hostname mdm9607, glibc 2.22.
• Netz: QCMAP + dnsmasq, AP-Gateway 192.168.1.1; SIM/WAN i.d.R. tot (kein DNS/WAN).
• Zugang (Reverse-Engineering): FTP als root mit werksseitigem Default-Passwort (root:oelinux123) → voller FS-Zugriff; Root ursprünglich über unsignierte fota.sh. Details im Research-Repo.
• Wichtige Pfade: /usrapp/current/ (tbox_app), /usrdata/pem/ (BLE-/FOTA-Schlüssel), /mnt/sdcard/ACQB/ (cache_data), /usrdata/tbox_carinfo (VIN).

Head-Unit (Dev-Werkzeug)

Freescale i.MX6DQ, Android 4.4.2 (armeabi-v7a), kein dm-verity → Root trivial. Dient nur zum Provisionieren; im Endprodukt nicht nötig. USB-Update-Partitionen via reference/imx6.ini.

Provisionierung

Die Provisioning-App wird per USB-Stick (ES-Browser) sideloaded. Sie stellt einen QR-Code bereit, den die AiwaysApp scannt:

{ "type":"aiways-provision", "api_token":"<tbx_…>",
  "ap_ssid":"MyAiways-XXXXXXXX", "ap_key":"<wlan_pw>", "vin":"<VIN>" }

Die App entdeckt die TBox (GET :9000/), erzeugt das Fahrzeug-Keypair lokal und registriert das Fahrzeug (POST /provision/vehicle) — der private Schlüssel verlässt das Gerät nie und geht per BLE an die LTE-Bridge. Das öffentliche Bundle deployt sie per PUT :9000/file?path=…&mode=600 (X-Token) nach /usrdata/pem/:

Head-Unit-Bedienung („Entwickleroptionen freischalten"): die konkrete Tipp-Geste steht in der Nutzer-Anleitung; sie ist geräteseitig, nicht im Code. Bebilderte Schritte dort.

Home-Assistant-Integration Python

Custom-Integration (Domain aiways): legt in Home Assistant eine Fahrzeug-Entität mit Sensoren an (Reichweite, Akku, Reifendruck, Standort …), gespeist aus der Backend-API. https://forgejo.timo-erdbruegger.de/aiways/HA-Aiways-Integration ↗

Für die Ladeoptimierung lässt sich analog EVCC anbinden; das System ist offen für weitere Consumer der REST-API.

Datenformat: dbcvpage

Primärer Lesepfad. Quelle: TBox-Port 50000, Kommando dbcvpage <n> liefert je „Seite" einen Teil der Live-Signalfläche. Ein voller Sweep ≈ 1000 benannte Signale (mehr als MQTT/cache_data: HV-Pack, 96 Zellspannungen, Temps, Odometer).

Sweep-Log-Format

===== dbcvpage 24  (15 Signale) =====
BMSStateOfCharge = 30
BMSCellVoltA1 = 3.649000
...

Seiten-Header-Regex ^=+\s*dbcvpage\s+(\d+), Signalzeile ^\s*([A-Za-z_]\w*)\s*=\s*(-?\d+(\.\d+)?)\s*$; Erst-Treffer gewinnt bei Dopplung. Zeitstempel aus Dateiname aichi_dbcvpage_<unix>.txt.

Einordnung & Tiers

Jedes Signal bekommt Domäne (Präfix: BMS, VCU, MCU, OBC, DCDC, TPMS, BCM, …) und einen Tier. Physikalischer Wert = raw × scale + offset (aus dem Katalog dbcvpageCatalog.ts).

Kern-Signale (→ telemetry)

Erster vorhandener Kandidat gewinnt: soc ← BMSStateOfCharge; packVoltage ← BMSPackVoltage; packCurrent ← BMSPackCurrent; odometer ← IPTotalOdometer; rangeKm ← VCUDrivingrange; cells ← BMSCellVoltA1..96; temps ← BMSCellTempA1..24. Keine Position (dbcvpage hat kein GPS).

Datenformat: cache_data

Datei /mnt/sdcard/ACQB/cache_data — Ringpuffer aus Fixed-Size-Records à 0x418 = 1048 Byte, GB/T-32960-Realtime-Struktur, Big-Endian. cache_info (9 B) liefert index_r/index_w; gültig sind die ersten index_w Records, neuester bei index_w−1 (Ring kann wrappen).

0x01-Block (Offsets, gültig wenn rec[6]==0x01)

Verifiziert per Ghidra (FUN_00030594) + echten Daten. Zell-/Temp-Block kommt hier nicht mit (nur über JSON/.inx-Pfad).

Datenformat: .inx

INTEST-History-Dump. Container-Header „INTEST 2.1"/„INTEST INZ V001", danach viele zlib-Blöcke (78 9c):

• Text-Blöcke: Schema mit ~991 CAN-Signalnamen + Einheiten + GPS/Summary-Spalten.
• Binär-Blöcke: float32-LE-Snapshots (~ein Sample alle 2–3 s); ~1835 Floats vs ~1050 Namen → nicht positionsstabil, daher signaturbasiert dekodiert.
• Geliefert je Sample: Datum/Zeit, Pack-Spannung, 96 Zellspannungen (Median-gefiltert), ~24 Zelltemperaturen, GPS-Spur (lat/lon/Höhe/Kurs), Speed, Odometer.

SoC/Reichweite/GPS-Skalare noch nicht kalibriert → beim .inx-Ingest bleibt soc null. Upload-Route POST /ingest/inx?vin=… (auch ?dry=1).

Protokoll: AICHI-BLE

Fernbefehle laufen über das fahrzeugeigene AICHI-Protokoll (V1). Gerätename-Präfix AICHI*. Verbindung ist transient pro Command (Scan/connect → A001 → B001 → deinit), Auto-MAC wird gecacht (NVS carmac) für spätere Direktverbindung.

GATT

Write in 20-Byte-Chunks (write-with-response, ~30 ms Pause); Notify-Reassembly per LE4-Längenpräfix im 4 KB-Puffer.

Krypto (Konstanten)

• AES-128-CBC + PKCS7, fester IV = ASCII 0123456789ABCDEF.
• LOGIN_KEY = ASCII 1234567890123456 (für A001 + A001-Antwort).
• Session-Key (16 B) aus der A001-Antwort → für alle B001/B002.
• RSA-1024, PKCS#1 v1.5: Signatur = private-encrypt; der per-Fahrzeug-Privatschlüssel liegt im NVS (n/e/d/p/q als Dezimalstrings) — nie im Klartext hier.

Frame-Aufbau

Wire: LE4(ct_len) + AES(origin). Origin (Klartext, Leerzeichen-getrennt): <HeadFlag> <FuncCode> 1.0 <tid> <date> <body-json> <check>. tid = UUIDv4-Hex (32), date = yyMMddHHmmssSSS (das Auto lehnt alte Zeitstempel ab → Netzzeit nötig).

• A001 (Auth): Body {"userType":"<btkeyId>","btkeyId":"<btkeyId>"}, check = RSA-Signatur über MD5(body + LOGIN_KEY + tid). Antwort mit LOGIN_KEY entschlüsseln → resCode="0" + Feld rk → RSA-decrypt → 16-B-Session-Key. Fehler: resCode="-9", errCode 1 = kein key_<btkeyId>, errCode 2 = Signatur ungültig.
• B001 (Command): mit Session-Key verschlüsselt, Body {"type":"<N>"} bzw. mit param; check = MD5(body + sessionKey + tid).
• Quittung B001 (HeadFlag ATR): resCode (0 = angenommen). Async B002 (HeadFlag TA): result + reason (0 = ausgeführt).

type-Codes (B001)

Klima-Zieltemperatur als param (z.B. {"temp":"215"} = 21,5 °C; App-Bereich 16–32 °C). Mapping identisch in App (bleTypeFor) und Firmware (backendToBleType) — das Backend selbst reicht type nur durch.

resCode / reason

resCode (Quittung): 0 OK, −1 Format, −2 unbekannter Typ, −3 Version, −4 Service abgelaufen, −5 andere App verbunden, −9 unbekannt. reason (Async): 1 anderer Befehl läuft, 2 nicht ausgeschaltet, 3 Spannungsfehler, 4 Tür offen, 6 fährt, 8 Schlüssel im Fahrzeug, 11 nicht verriegelt, 13 Bremse getreten, 241/242 Ausführbedingung/ECU-Fehler.

Referenz-Implementierung/Experimente: BLEAndroidApp ↗, dekompiliertes App-Protokoll im Research-Repo.

Protokoll: A7670E-Modem (AT)

Kommunikation per AT über UART. Start-Baud 115200, Ziel 38400 (AT+IPR=38400); Fallback 19200 bei defekten großen POSTs (kein HW-Flow-Control). Server-Zert wird pragmatisch nicht geprüft.

HTTPS-POST (RAM / HTTPDATA)

AT+HTTPINIT
AT+CSSLCFG="authmode",0,0
AT+HTTPPARA="URL","<url>"
AT+HTTPPARA="CONTENT","<ctype>"
AT+HTTPPARA="USERDATA","X-Api-Key: <key>"
AT+HTTPDATA=<len>,60          ; auf DOWNLOAD-Prompt warten, Body in 256-B-Chunks
AT+HTTPACTION=1                ; 1 = POST, async: +HTTPACTION: 1,<code>,<len>
AT+HTTPREAD=0,700
AT+HTTPTERM

Große Bodies via EFS (CFTRANRX + HTTPPOSTFILE)

Der A7670 lehnt ~MB-Bodies bei HTTPDATA ab (kein DOWNLOAD-Prompt), daher der Umweg über das Modem-EFS:

AT+FSCD=C:
AT+FSDEL=inx.bin
AT+CFTRANRX="c:/inx.bin",<len>   ; auf '>' warten, Bytes host→EFS
AT+HTTPINIT ... HTTPPARA ...
AT+HTTPPOSTFILE="inx.bin",1,1,0  ; path=1(C:/), method=1(POST)

TBox Port 50000 (Assist-Modul)

TCP 50000 in tbox_app.bin. Wire-Format (verifiziert am Fahrzeug):

Req : 7E | cnt(4 LE) | 01 | opLo opHi [args] | XOR | 7E
Resp: 7E | cnt(4) | 01 | opLo opHi | len(2 LE) | [format,data] | XOR | 7E
       Byte-Stuffing 7D→7D01 / 7E→7D02 ; resp-op = req-op | 0x8000

Der Daemon nutzt v.a. 0x301 (dbcvpage, setmode) und 0x20C. Details/Opcode-Inventur im Research-Repo.

Backend-API

Referenzinstanz: https://aiways.it-perspective.de. Auth-Header: X-API-Key: oaw_… oder Authorization: Bearer <oaw_… | jwt>. machineOk = Device-Token oder API-Key.

Auth / Konto

Ingest (machineOk)

Fahrzeuge / Telemetrie

Provisioning / Firmware / Geräte

Command-Queue

curl -X POST https://aiways.it-perspective.de/ingest/telemetry \
  -H "X-Api-Key: oaw_…" -H "Content-Type: application/json" \
  -d '{"vin":"…","records":[{"ts":"2026-09-07T20:00:00Z","soc":72,"rangeKm":305}]}'

Interaktive Übersicht mit Try-Buttons: /sandbox (außer Production).

Auth & Sicherheit

• JWT-Sessions (Bearer <jwt>) — Nutzer/App. Kontoverwaltung & API-Key-Ausstellung nur mit Session, nie per API-Key.
• API-Keys (oaw_…) — Geräte/Integrationen; SHA-256-Hash gespeichert, Rollen admin/user/device, owner-gebunden, einzeln widerrufbar.
• Fahrzeug-BLE-Auth: pro Fahrzeug ein RSA-1024-Keypair; Privatschlüssel bei App/Bridge, Public-Key auf der TBox (key_<btkeyId>). App/Bridge signieren, TBox verifiziert.
• Selbstregistrierung standardmäßig aus (ALLOW_REGISTRATION=false).

CI/CD & Deployment

Jedes Repo hat eine Forgejo-Actions-Pipeline mit einem Gate auf die Commit-Message.

Build & lokale Entwicklung

Backend

git clone https://forgejo.timo-erdbruegger.de/aiways/Backend.git && cd Backend
npm install && npm run build
docker compose up -d        # Postgres + App
# lokal alternativ: npm run migrate && npm start

AiwaysApp

git clone https://forgejo.timo-erdbruegger.de/aiways/AiwaysApp.git && cd AiwaysApp
flutter pub get
flutter run                          # Debug aufs Gerät
flutter build appbundle --release    # signiert via android/key.properties

LTE-Bridge (PlatformIO)

git clone https://forgejo.timo-erdbruegger.de/aiways/LTEBridgeFirmware.git && cd LTEBridgeFirmware
pio run -e waveshare-s3-a7670e       # Compile-Check vor dem Push
pio run -e waveshare-s3-a7670e -t upload   # Flashen (oder Web-Flasher /flash)

TBox-Daemon (Cross)

git clone https://forgejo.timo-erdbruegger.de/aiways/tbox_daemon.git && cd tbox_daemon
make cross CROSS=/opt/ql-ol-crosstool/.../arm-oe-linux-gnueabi-
# bei GLIBC-Fehler: statisch bauen (-static)

Beitragen

• Issues & Merge Requests auf Forgejo; Reverse-Engineering-Notizen ins Research-Repo.
• Commit-Prefixes feat: / fix: / docs:; Deploy/Publish nur mit den Trigger-Wörtern.
• Keine Secrets committen (Keystores, API-Keys, private Schlüssel, echte VINs) — CI-Secrets nutzen.
• Backend/Firmware: vor dem Commit git status prüfen (teils geteilte Checkouts).

Alle Repositories