obdBT Bridge - Website  [Paket V2.1]
=====================================
Copyright (C) 2026 Ralf Burger - GNU General Public License v3 (GPL v3)
ralf@RalfBurger.com

Projektversion : V2.1
Webserver-Pfad : OBD/
Firmware       : Bridge v3.1 · Receiver v1.3 · Simulator v1.1 · GUI v2.1
Stand          : 12. April 2026


QUELLCODE
---------
Das Projekt liegt auf Codeberg — bewusst nicht auf GitHub.
Codeberg ist auch fuer mich neu, aber es ist mir einfach sympathischer,
als es bei einem Konzern liegen zu haben, der sich fuer 7500 Millionen
eine weisse Weste kaufen will ;-)

  https://codeberg.org/wicki/obdBT



PLATTFORM
---------
Entwickelt und getestet unter Linux (Ubuntu/Debian).

Windows: Das Paket sollte grundsaetzlich funktionieren, aber die im Projekt
verwendeten Symlinks (wifi_config.h, hw_config.h, pid_registry.h/.cpp in den
Modulverzeichnissen zeigen auf ../wifi_config.h usw.) koennen unter Windows
fuer Irritationen sorgen:
  - git clone unter Windows loest Symlinks standardmaessig nicht auf
    (git config core.symlinks true kann helfen, erfordert aber Admin-Rechte)
  - Explorer und manche Editoren zeigen Symlinks als leere Dateien
  - Empfehlung Windows-Nutzer: WSL2 (Ubuntu) verwenden, dort verhaelt sich
    alles wie erwartet


STRUKTUR
--------
index.shtml          Hauptdatei (nur SSI-Include-Direktiven)
.htaccess            Apache mod_include aktivieren
includes/
  head.html          <head>: CSS, Fonts, Variablen
  nav.html           Navigation + Logo + Versionsstring
  hero.html          Hero-Bereich + animiertes Live-Demo-Panel
  story.html         Entstehungsgeschichte des Projekts
  architektur.html   Systemaufbau-Diagramm (Bridge, Receiver, Simulator)
  features.html      Feature-Karten inkl. vollstaendiger CLI-Referenz
  terminal.html      Terminal-Beispiel (obdBT CLI-Ausgabe)
  fotos.html         Projektfotos (Heltec-Board + Python-GUI)
  pids.html          PID-Tabelle (43 Eintraege aus pid_registry)
  module.html        Hardware-Module MOD-01 bis MOD-05
  download.html      Download-Links fuer alle Quelldateien
  impressum.html     Impressum gemaess SS 5 TMG
  footer.html        Footer + GPL-v3-Lizenz-Modal + JavaScript


MODULE
------
MOD-01  obd_bridge          Bridge-Firmware (Heltec LoRa V3, ESP32-S3)
MOD-02  obd_lora_receiver   Receiver-Firmware (Heltec LoRa V3, ESP32-S3)
MOD-03  obd_gui2.py         Python-Dashboard (PC/Smartphone, tkinter)
MOD-04  obd_simulator       OBD2-Simulator (ESP32 WROOM + MCP2515)
MOD-05  Shared Headers      pid_registry.h/.cpp, wifi_config.h, http_server.h


ARDUINO-ABHAENGIGKEITEN (getestet mit)
---------------------------------------
Board-Paket : esp32 by Espressif Systems  2.0.x
              (Arduino IDE: Boardverwalter -> "esp32" suchen)

Bibliotheken (Arduino-Bibliotheksverwalter):
  NimBLE-Arduino        1.4.x   (BLE-Stack, leichtgewichtig)
  RadioLib              6.x     (SX1262 LoRa-Treiber)
  Adafruit SSD1306      2.5.x   (OLED-Display)
  Adafruit GFX Library  1.11.x  (Grafikgrundlage fuer SSD1306)
  MCP_CAN               2.0.x   (nur obd_simulator: MCP2515 CAN-Bus)

Hinweis: wifi_config.h vor dem Flashen anpassen (SSID/Passwort eintragen).


PYTHON-ABHAENGIGKEITEN (obd_gui2.py)
--------------------------------------
Python    : 3.8 oder neuer
tkinter   : in Python-Standardinstallation enthalten
            Linux (falls fehlend): sudo apt install python3-tk
Sonstige  : keine externen Pakete erforderlich (nur Python-Stdlib)

Start:
  python3 obd_gui2.py                         # TCP, F1-Style
  python3 obd_gui2.py --host 192.168.1.100    # andere Bridge-IP
  python3 obd_gui2.py --style scifi           # Stil: f1/scifi/aviation/luxury
  python3 obd_gui2.py --bridge                # Direkt mit Bridge verbinden


DOKUMENTATION
-------------
OBD_Doku.docx   Master-Dokument (Word) — hier werden Aenderungen gemacht.
doku.html       Generierte Web-Version — NICHT manuell bearbeiten.

Aus dem docx eine neue doku.html erzeugen:
  bash src/doku_convert.sh

Voraussetzung: pandoc >= 2.x
  Linux:   sudo apt install pandoc
  macOS:   brew install pandoc
  Windows: https://pandoc.org/installing.html

Optionen:
  --check   Nur Voraussetzungen pruefen
  --diff    Diff zwischen alter und neuer HTML ausgeben


DEPLOYMENT (Apache)
-------------------
Die Website verwendet SSI (Server Side Includes) — index.shtml bindet alle
includes/*.html per <!--#include virtual="--> ein. Dafuer ist ein Webserver
mit SSI-Unterstuetzung erforderlich; ein einfacher Datei-Server genuegt nicht.

1. Alle Dateien auf den Server laden (Verzeichnisstruktur beibehalten)
2. Apache mod_include aktivieren:
     a2enmod include
     systemctl restart apache2
3. In der Apache VHost-Konfiguration:
     AllowOverride All   (damit .htaccess greift)
4. Aufruf: https://deinedomain.de/OBD/

Bilder liegen in images/ (relative Pfade in fotos.html bereits gesetzt).


NGINX-ALTERNATIVE
-----------------
Nginx unterstuetzt SSI mit ngx_http_ssi_module (in den meisten Paketen enthalten):
  nginx.conf: ssi on; ssi_silent_errors on;

Alternativ: Reverse-Proxy auf Apache.


EINZELNE BEREICHE AENDERN
--------------------------
Nur die entsprechende includes/*.html-Datei bearbeiten.
index.shtml muss dabei nicht angefasst werden.

Haeufige Aenderungen:
  Fotos           -> includes/fotos.html  (img src= anpassen)
  Download-Links  -> includes/download.html
  Impressum       -> includes/impressum.html
  Versionsstring  -> includes/nav.html + includes/footer.html
  Projektversion  -> includes/nav.html, hero.html, footer.html, head.html, doku.html, README.txt
  PID-Tabelle     -> includes/pids.html (bei Aenderung pid_registry)


LOKALER TEST
------------
Die Website verwendet SSI — fuer eine vollstaendige Vorschau liegt ein
kleines Python-Script bei, das alle Includes selbst aufloest:

  cd OBD
  python3 src/ssi_preview.py

Das Script baut aus index.shtml eine fertige index.html, startet einen
lokalen HTTP-Server und rauemt beim Beenden automatisch auf.
Dann im Browser: http://localhost:8080

Kein Apache, kein Docker, kein Webserver-Setup noetig.
---------------
Bridge verbindet sich nicht per BLE:
  - OBD-Dongle eingesteckt und Zuendung an?
  - Dongle per Smartphone-App pruefen (z.B. Car Scanner)
  - "scan" im CLI neu starten
  - Bridge neu booten (Boot-Taster druecken oder "reboot")

WiFi nicht erreichbar:
  - SSID/Passwort in wifi_config.h pruefen und neu flashen
  - Bei Verbindungsfehler oeffnet Bridge automatisch AP "obdBT-Bridge"
    (PW: obdBT123) -> nc 192.168.4.1 1234

LoRa sendet nicht (loraOk=false):
  - SPI-Pins in hw_config.h pruefen (LORA_CS, LORA_IRQ, LORA_RST, LORA_BUSY)
  - radio.begin() Fehlercode im Serial-Monitor pruefen

Receiver empfaengt nichts:
  - Bridge und Receiver auf gleicher Frequenz und gleichem SF? (lora status)
  - Entfernung/Hindernisse? LoRa-Reichweite pruefen
  - "lora sf7" auf beiden Seiten fuer kuerzeste Airtime / hoehere Rate

OBD: nur "NO DATA" oder "UNABLE TO CONNECT":
  - Zuendung an (Klemme 15)?
  - ATSP6 (ISO 15765-4 CAN 11bit 500k) ist fest eingestellt; bei aelteren
    Fahrzeugen ggf. "ATSP0" (Auto) per Direktbefehl im CLI senden
  - Dongle-LED pruefen: blinkt sie beim Verbinden?

GUI zeigt keine Daten:
  - Bridge erreichbar? ping <IP>
  - "live on" im CLI -> Daten im Terminal sichtbar?
  - Firewall: TCP-Port 1234 freigeben
