Überblick

Das OBD-Adapter-BRIDGE-Projekt liest Fahrzeugdaten über einen handelsüblichen BLE-OBD-Dongle aus und stellt sie gleichzeitig auf drei unabhängigen Kanälen bereit: OLED-Display, TCP/WLAN und LoRa-Funk. Smartphone, App oder Abo sind nicht erforderlich.

Das System besteht aus vier eigenständigen Modulen, die über gemeinsame Header-Dateien (Symlinks) konfiguriert werden. Alle Module sind über ein einheitliches Telnet-CLI steuerbar — entweder per USB-Serial oder per TCP auf Port 1234.

Voraussetzungen

Hardware

Software / Entwicklungsumgebung

• Arduino IDE ≥ 2.x mit ESP32-Boardpaket (espressif/arduino-esp32)
• Heltec ESP32 Boards-Bibliothek
• NimBLE-Arduino 1.4.x
• LoRaWan_APP / Heltec LoRa-Bibliothek (für SX1262)
• MCP_CAN-Bibliothek (nur für MOD-04)
• Python 3 mit tkinter (Standard, für MOD-03)
• arduino-cli für obd_flash.sh (optional, aber empfohlen)

Quickstart

1. Datei wifi_config.h im Projektroot mit eigenen WLAN-Daten befüllen (SSID, Passwort, AP-Credentials)
2. Bridge flashen: obd_identify.sh erkennt den Port automatisch, dann obd_flash.sh bridge
3. Heltec starten, OLED zeigt Bootsequenz — Bridge verbindet sich ins WLAN oder öffnet eigenen AP (192.168.4.1)
4. Mit nc <IP> 1234 verbinden und live on eingeben — Fahrzeugdaten werden live ausgegeben
5. Python-GUI starten: python3 obd_gui2.py --bridge <IP>
6. Optionaler LoRa-Receiver: Receiver-Firmware flashen, zweites Heltec-Board starten

Systemaufbau

Alle Verbindungen laufen über offene Protokolle auf Standard-Hardware. Der Simulator ermöglicht vollständige Tests ohne laufendes Fahrzeug.

Gestrichelt: optionaler Test-Pfad — MOD-04 (Simulator + MCP2515) ersetzt das Fahrzeug via CAN-Bus.

Kommunikationskanäle

Symlinks & Shared Headers

Drei Konfigurationsdateien sind als Symlinks realisiert, damit alle Module stets denselben Stand haben. Es gibt einen einzigen Änderungspunkt: die echten Dateien liegen in src/obd_bridge/ bzw. src/wifi_config.h.

wifi_config.h — Struktur

// wifi_config.h — gemeinsam für Bridge, Receiver, Simulator
#define WIFI_SSID     "MeinHeimnetz"
#define WIFI_PASS     "meinPasswort"
#define AP_SSID       "obdBT-Bridge"
#define AP_PASS       "obd12345"
#define TCP_PORT      1234
#define HTTP_PORT     80

PID-Registry

Die Datei pid_registry.h/.cpp definiert alle 43 OBD-PIDs zentral. Bridge und Receiver teilen sich dieselbe Tabelle über Symlinks — ein Sync-Fehler zwischen den µCs ist damit strukturell ausgeschlossen.

Jeder Eintrag enthält: OBD-Modus und PID-Byte, Anzeigename, Einheit, Scaling-Faktor (×1 / ×10 / ×100), Priorität (HIGH / MED / LOW) und Gruppe (Motor, Kraftstoff, Abgas, Zündung, Fehler, Info). Der Blind-Scan beim Start testet automatisch, welche PIDs das angeschlossene Fahrzeug unterstützt.

MOD-01 · obd_bridge

Die Bridge ist das Kernmodul. Sie verbindet sich per BLE mit dem OBD-Dongle, liest alle verfügbaren PIDs in einem Prioritätspoller aus und stellt die Daten gleichzeitig auf OLED, TCP und LoRa bereit. Das Polling läuft dauerhaft und unabhängig von aktiven TCP-Verbindungen.

BLE-Client

Die Bridge scannt eigenständig nach BLE-OBD-Dongles. Beim Start durchsucht sie alle in Reichweite befindlichen Geräte nach bekannten Service-UUIDs:

Bei Verbindungsverlust startet automatisch ein erneuter Scan. Ein Hardware-Watchdog (60 s Timeout, esp_task_wdt) verhindert, dass die Bridge dauerhaft hängt.

TCP & HTTP

Die Bridge öffnet nach dem WLAN-Connect einen TCP-Server auf Port 1234. Mehrere gleichzeitige Clients sind möglich. Das Protokoll ist Klartext (UTF-8): Zeilenpräfixe BSC (Basis-PIDs) und EXT (erweiterte PIDs) kennzeichnen die Datenzeilen.

Auf Port 80 läuft ein minimaler HTTP-Server, der eine JSON-Statusseite und eine einfache HTML-Übersicht liefert. Konfiguriert über http_server.h.

WiFi-Verhalten: Die Bridge versucht sich zuerst ins konfigurierte Heimnetz (STA) einzubuchen. Schlägt das nach dem Timeout fehl, öffnet sie automatisch einen eigenen Access-Point (192.168.4.1).

LoRa TX

Die Bridge sendet ausschließlich Extended-Pakete (Typ 0x03, TLV-Format) mit allen aktiven PIDs. Das Sendeintervall wird dynamisch aus der tatsächlichen Airtime berechnet (Semtech-Formel), sodass der 1%-Duty-Cycle für DE/EU (868 MHz, SRD-Band) zu keiner Zeit überschritten wird.

Zusätzlich wird beim Start ein Config-Paket (Typ 0x02) gesendet, das dem Receiver die aktuellen LoRa-Parameter mitteilt (SF, Region, Sendeleistung).

OLED-Display

Das SSD1306-Display (128×64 Pixel, I²C) zeigt bis zu 5 konfigurierbare Seiten. Ein Button steuert kurzen Druck (Seite blättern) und langen Druck (aktuelle Seite fixieren). Die Helligkeit ist per CLI-Befehl dim 0..255 regelbar; dim 0 versetzt das Display in den Sleep-Modus (SSD1306 Display-Off).

Jede Seite zeigt unten links ein Status-Cluster (B/R · ST/AP/-- · OBD/SIM/---) und rechts unten den Page-Indicator (Punkte). Fehlerzustände blinken als !.

Die Punkte unten rechts zeigen die aktuelle Seite (ausgefüllt). Das Status-Cluster unten links: B=Bridge / R=Receiver · ST=WLAN-Client / AP=Access Point / --=kein WLAN · OBD=Fahrzeugdaten / SIM=Simulation / ---=keine Daten. ! blinkt bei Fehler.

CLI-Befehle (Bridge)

MOD-02 · obd_lora_receiver

Der Receiver empfängt die LoRa-Pakete der Bridge, dekodiert den TLV-Payload und stellt die Werte auf seinem eigenen OLED sowie per TCP auf Port 1234 bereit. Er benötigt keine direkte Verbindung zum Fahrzeug oder zum Dongle.

LoRa RX & Paket-Dekodierung

Der Receiver empfängt Extended-Pakete (Typ 0x03) und Config-Pakete (Typ 0x02). Extended-Pakete werden per TLV dekodiert — jeder Tag entspricht einem PID-Index aus der gemeinsamen pid_registry. Eine Sequenznummer ermöglicht die Zählung verlorener Pakete.

Das OLED zeigt 5 Seiten; Seite 4 scrollt durch alle empfangenen Extended-PIDs. Der Paket-Modus ist per CLI umschaltbar: pkt auto (Standard), pkt basic oder pkt extended.

WiFi-Verhalten: STA ins Heimnetz → bei Fehler automatisch STA in den AP der Bridge (192.168.4.1).

CLI-Befehle (Receiver)

MOD-03 · obd_gui2.py

Das Python-Dashboard verbindet sich per TCP mit der Bridge oder dem Receiver und zeigt die Fahrzeugdaten als animierte Rundinstrumente (Gauges) und Balkenanzeigen an. Es läuft auf jedem Desktop-System mit Python 3 und tkinter.

Starten

# Direkt mit Bridge verbinden (RSSI-Balken ausgeblendet)
python3 obd_gui2.py --bridge <IP-der-Bridge>

# Mit Receiver verbinden (LoRa-RSSI-Balken aktiv)
python3 obd_gui2.py <IP-des-Receivers>

# Style beim Start wählen (1=F1, 2=Sci-Fi, 3=Aviation, 4=Luxury)
python3 obd_gui2.py --bridge <IP> --style 2

Styles & Tastenkürzel

Im --bridge-Modus wird der LoRa-RSSI-Balken ausgeblendet, da die Verbindung direkt zur Bridge läuft. CSV-Logging schreibt alle empfangenen Werte mit Zeitstempel in eine Datei; Sentinel-Werte (fehlerhafte Antworten des Dongles) werden automatisch herausgefiltert.

MOD-04 · obd_simulator

Der Simulator emuliert ein Fahrzeug-ECU via CAN-Bus nach ISO 15765-4. Er antwortet auf OBD-II-Anfragen des Dongles, sodass die komplette Toolchain ohne laufendes Fahrzeug getestet werden kann.

Ab dem Boot sendet der Simulator automatisch BSC- und EXT-Live-Pakete mit realistisch simulierten Fahrdynamikwerten (Drehzahl, Geschwindigkeit, Temperatur usw.). Über ein Web-Interface können alle Werte manuell gesetzt werden.

Unterstützte OBD-Modi

CLI-Befehle (Simulator)

Hardware-Verdrahtung

MOD-01 · Bridge (Heltec WiFi LoRa 32 V3)

Der Heltec LoRa V3 hat SX1262, OLED und LoRa-Antenne bereits onboard. Externe Verdrahtung beschränkt sich auf den Beeper.

MOD-02 · LoRa-Receiver (Heltec WiFi LoRa 32 V3)

Identische Hardware wie MOD-01, identische Pin-Belegung. Kein Beeper. Kein externer Anschluss nötig.

MOD-04 · Simulator (ESP32 WROOM-32 + MCP2515)

Der MCP2515 CAN-Controller wird per SPI angebunden. Der TJA1050 CAN-Transceiver ist auf dem MCP2515-Modul (HW-184) bereits integriert.

OBD-II-Stecker beim Test ohne Fahrzeug

Der BLE-OBD-Dongle wird direkt am Simulator-Board betrieben. Es werden nur die Pins belegt die für CAN-OBD (ISO 15765-4) benötigt werden.

Für den Testaufbau empfiehlt sich ein 3D-gedruckter OBD-II-Stecker (Buchse): Thingiverse Thing 6350647 von TA1GI, lizenziert unter CC BY-SA 4.0. Die Kabel werden direkt an die gewünschten Pins angelötet, Zugentlastung über die Trägerplatte.

CAN-Bus Diagnose

Bei CAN ERROR vom Dongle oder ausbleibenden OBD-Antworten systematisch vorgehen:

Schritt 1 — Simulator-Hardware prüfen (Loopback-Test)

Im Simulator per Serial oder Telnet:

can test loopback

Erwartete Ausgabe: [CAN-TEST] Loopback: OK — MCP2515, SPI und TX/RX-Puffer funktionieren. Schlägt dieser Test fehl, liegt das Problem am Simulator-Board selbst (SPI-Verdrahtung, Stromversorgung, Quarz).

Schritt 2 — Spannungen messen (Multimeter)

CAN-Bus im Ruhezustand (kein aktiver Traffic) hat definierte Ruhepegel:

Schritt 3 — Häufige Fehler

Taster-Belegung

Freie GPIOs (Bridge & Receiver)

Folgende GPIOs des Heltec LoRa V3 sind im aktuellen Code nicht belegt und für Erweiterungen verfügbar:

Flash-Workflow

Das Projekt enthält zwei Shell-Skripte, die den Flash-Prozess automatisieren: obd_identify.sh erkennt die angeschlossenen Module und obd_flash.sh kompiliert und flasht.

obd_identify.sh

Das Skript liest die USB-Gerätebeschreibungen aus und vergleicht sie mit bekannten Heltec- und ESP32-Signaturen. Es gibt für jedes erkannte Modul den fertigen Flash-Befehl aus — inklusive korrektem Port.

# Alle angeschlossenen Module anzeigen
./obd_identify.sh

# Beispielausgabe:
[PORT]  /dev/ttyUSB0  →  Heltec LoRa V3  (Bridge)
[PORT]  /dev/ttyUSB1  →  Heltec LoRa V3  (Receiver / Bridge?)
[CMD]   obd_flash.sh bridge --port /dev/ttyUSB0

obd_flash.sh

Kompiliert das jeweilige Modul mit arduino-cli und flasht es. Der Build-Zeitstempel wird als Compiler-Define ins Binary eingebettet (BUILD_TIME, SKETCH_MTIME) und ist per version-Befehl abrufbar.

# Bridge flashen (Port automatisch erkannt)
./obd_flash.sh bridge

# Bridge mit explizitem Port
./obd_flash.sh bridge --port bridge=/dev/ttyUSB0

# Receiver flashen
./obd_flash.sh receiver

# Simulator flashen
./obd_flash.sh simulator

# Remote-Flash: Kompilierung auf PC1, Flash über SSH auf PC2
./obd_flash.sh bridge --ssh user@pc2

PID-Tabelle (alle 43)

Die vollständige Tabelle aus pid_registry.h/.cpp. Scale: ×1 = Ganzzahl, ×10 = eine Dezimalstelle, ×100 = zwei Dezimalstellen (TLV-Scaling).

TCP-Protokoll

Alle Daten werden als UTF-8-Klartext auf Port 1234 übertragen. Der Stream enthält abwechselnd BSC- und EXT-Zeilen, getrennt durch \n.

# BSC-Zeile (Basis-PIDs, hohe Priorität)
BSC RPM:2847 SPD:92 T:91 Ld:38.4 MAP:102 V:13.82 TX#1247

# EXT-Zeile (erweiterte PIDs)
EXT Ansaugluft:34 TPS:22.35 Gaspedal:28.62 Zuendwinkel:12.0 Lambda:1.000 Oeltemp:82

# Status-/Info-Zeile (kein festes Format)
[INFO] BLE connected: OBD-DONGLE-BT  RSSI:-58

CLI-Eingaben werden auf derselben TCP-Verbindung gesendet und mit \n abgeschlossen. IAC-Bytes (Telnet-Steuersequenzen) werden automatisch herausgefiltert — die Verbindung ist damit vollständig telnet-kompatibel.

LoRa-Paketformat

Alle LoRa-Pakete beginnen mit einem 1-Byte-Typ-Feld. Aktuell verwendet werden Typ 0x02 (Config) und Typ 0x03 (Extended / TLV).

Extended-Paket (Typ 0x03)

Byte 0:  0x03            Pakettyp Extended
Byte 1:  SeqNr           Sequenznummer (uint8, rollover)
Byte 2:  N               Anzahl TLV-Einträge

# TLV-Eintrag (wiederholt N-mal):
Byte k+0: Tag             PID-Index (aus pid_registry, 0–42)
Byte k+1: Len             Länge Value (1 oder 2 Bytes)
Byte k+2: Value[Len]      Skalierter Wert (int16, Big-Endian)

Der tatsächliche Wert ergibt sich durch Division mit dem Scale-Faktor aus der PID-Registry: Wert = Value / Scale.

Config-Paket (Typ 0x02)

Byte 0:  0x02            Pakettyp Config
Byte 1:  SF              Spreading Factor (7–12)
Byte 2:  Region          0x01 = EU868, 0x02 = US915
Byte 3:  Power           Sendeleistung in dBm

Verzeichnisstruktur & Deployment

Das Archiv OBD.tgz entpackt sich direkt in das Webserver-Verzeichnis. Nach dem Entpacken nach / liegt die Website unter /OBD/, die Quelldateien unter /OBD/src/.

Verzeichnisstruktur nach dem Entpacken

/OBD/
├── index.shtml          # Einstiegspunkt (SSI-Includes)
├── includes/            # Website-Bausteine (nav, hero, story, …)
├── images/              # Fotos, Screenshots, friese.png, friese.jpg
├── favicon.ico          # Favicon (Friese, 16×16 + 32×32)
├── favicon.png          # Favicon als PNG (32×32)
├── doku.html            # Diese Dokumentation
├── .htaccess            # Apache SSI + Kompression
├── LICENSE              # GPL v3 (englisch, rechtsverbindlich)
├── LICENSE.de           # GPL v3 (deutsch, nicht rechtsverbindlich)
├── OBD.tgz              # Komplettarchiv (hier ablegen für Download-Link)
└── src/
    ├── wifi_config.h    # Gemeinsame Konfiguration (SSID, AP, TCP-Port)
    ├── obd_flash.sh     # Flash-Script (erkennt src/-Struktur automatisch)
    ├── obd_identify.sh  # Modul-Erkennung an USB-Ports
    ├── obd_gui2.py      # Python-Dashboard
    ├── obd_bridge/      # Bridge-Firmware + echte Header-Dateien
    ├── obd_lora_receiver/ # Receiver-Firmware + Symlinks auf obd_bridge/
    └── obd_simulator/   # Simulator-Firmware + Symlink auf wifi_config.h

Deployment auf Apache

# 1. Archiv entpacken
cd /
tar -xzf OBD.tgz

# 2. Rechte setzen
bash /OBD/src/fix_permissions.sh

# 3. Apache mod_include aktivieren
a2enmod include
systemctl restart apache2

# 4. VHost: AllowOverride All  (damit .htaccess greift)
# 5. OBD.tgz in /OBD/ ablegen (für den Download-Link auf der Seite)
cp OBD.tgz /OBD/

# Aufruf: https://deinedomain.de/OBD/

Rechte setzen (fix_permissions.sh)

Das Script src/fix_permissions.sh setzt alle Rechte kollisionsfrei für den Webserver: Verzeichnisse 755, Dateien 644, Shell- und Python-Scripts 755.

cd /
sudo bash /OBD/src/fix_permissions.sh

Nginx (Alternative)

# nginx.conf — SSI aktivieren
location /OBD/ {
    ssi on;
    ssi_silent_errors on;
}

Lokaler Test mit Docker

docker run -p 8080:80 \
  -v $(pwd)/OBD:/usr/local/apache2/htdocs/OBD \
  httpd:alpine
# Aufruf: http://localhost:8080/OBD/index.shtml

Website-Features

Die Website enthält mehrere interaktive Elemente, die clientseitig per JavaScript realisiert sind — kein externes Framework, kein CDN.

Animierte Rundinstrumente (Hero-Bereich)

Im Hero-Bereich laufen 6 Canvas-Rundinstrumente mit simulierten OBD-Werten: Drehzahl, Speed, Kühlmitteltemperatur, Motorlast, MAP und ECU-Spannung. Jedes Instrument zeigt eine vollständige Rundinstrumenten-Skala mit Skalenstrichen, Beschriftung, farbigem Warnbereich und einem feinen beweglichen Zeiger. Der Zeiger wechselt bei Grenzwertüberschreitung auf Orange bzw. Rot. Die Simulation läuft dauerhaft im Hintergrund — ohne Server, ohne WebSocket.

Lightbox

Alle Bilder auf der Seite — Fotos, Screenshots und der Friese — sind klickbar und öffnen eine Lightbox in voller Größe. Klick auf den Hintergrund oder Escape schließt sie wieder. Implementiert als einzelner <div id="lb-overlay"> in head.html, gesteuert per lbOpen(src, event).

Favicon

Der Friese dient als Favicon (favicon.ico mit 16×16 und 32×32 px, zusätzlich favicon.png). Beide Dateien liegen direkt im /OBD/-Verzeichnis. Die <link>-Tags stehen in includes/head.html mit relativem Pfad ohne führendes ./ — damit funktioniert die Auflösung korrekt durch SSI.

SSI-Struktur

index.shtml besteht ausschließlich aus <!--#include virtual="./includes/..."-->-Direktiven. Jeder Seitenbereich ist eine eigene Datei in includes/ — Änderungen an einzelnen Bereichen erfordern kein Anfassen von index.shtml.

Lizenz

Alle Quelltexte dieses Projekts stehen unter der GNU General Public License v3 (GPL v3). Das bedeutet: freie Nutzung, Veränderung und Weitergabe — aber Derivate müssen ebenfalls unter GPL v3 veröffentlicht werden. Closed-Source-Derivate sind nicht zulässig.

Die originalen Copyright-Hinweise (Copyright (C) 2026 Ralf Burger) müssen in allen Kopien und abgeleiteten Werken erhalten bleiben.

ralf@RalfBurger.com · Systemintegration Ralf Burger · Roenskenstr. 37 · 46562 Voerde