# Developer Documentation – Smart Chain Oiler Diese Datei richtet sich an Entwickler\:innen, die das Projekt aufbauen, erweitern oder debuggen wollen. Ergänzend zur [README.md](README.md) (Überblick & Features) enthält dieses Dokument Details zu Build‑Prozess, Debugging, Protokollen und internen Architekturen. --- ## Build & Flash ### PlatformIO Environments * `pcb_rev_1-2_serial`, `pcb_rev_1-2_ota` * `pcb_rev_1-3_serial`, `pcb_rev_1-3_ota` * `pcb_rev_1-4_serial`, `pcb_rev_1-4_ota` Default: **pcb\_rev\_1-4\_serial** ### Serial Flash ```bash pio run -e pcb_rev_1-4_serial -t upload ``` ### OTA Flash ```bash pio run -e pcb_rev_1-4_ota -t upload ``` * Port: 8266 * Auth: `ADMIN_PASSWORD` (aus `wifi_credentials.ini`) ### Filesystem Update (LittleFS) * **Immer zuerst** FS‑Image flashen, wenn „Benötigte Flash‑Version“ ≠ „Installierte“ * `.fs.gz` hochladen → danach `.fw.bin` --- ## Serial Console (115200 Baud) Der ESP8266 bietet ein einfaches CLI (über UART oder USB). Nützliche Befehle: | Befehl | Funktion | | ------------------ | ------------------------------ | | `help` | Liste aller Kommandos | | `sysinfo` | Systeminfo (Versionen, Uptime) | | `netinfo` | Netzwerkinfos (IP, WiFi) | | `dtc_list` | Aktive DTCs anzeigen | | `dtc_clear` | DTC‑Liste zurücksetzen | | `purge` | Entlüften/Pumpimpulse starten | | `toggle_wifi` | WiFi‑AP ein/aus | | `tank_refill` | Tankfüllstand zurücksetzen | | `isr_debug on/off` | Debug-Ausgabe zu Impuls‑ISR | --- ## WebSocket API ### Endpoint `ws:///ws` ### Server → Client Events * `NOTIFY:;` → Toast/Alert im UI * `DEBUG:` → Debugausgabe * `DTC:` → aktive DTCs (Format: `ts,code,severity,active;…`) * `MAPPING_STATUS:` → Mapping Keys → Labels (Statuswerte) * `MAPPING_STATIC:` → Mapping Keys → Labels (Staticwerte) * `STATUS:` → Livewerte (z. B. Distanzzähler, Tank %) * `STATIC:` → Konfiguration, Versionen ### Client → Server Events * Generisches Schema: `btn-:` * Beispiel: `btn-refill:1` (Tankreset), `btn-purge:25` (25 Impulse) --- ## DTC Framework Severity: * **INFO** – nur Anzeige im WebUI * **WARN (Orange)** – Hinweis, Betrieb läuft weiter * **CRITICAL (Rot)** – Pumpe gestoppt DTC‑Definitionen: siehe [`dtc_defs.txt`](dtc_defs.txt). Im WebUI werden Codes per `dtc_table.json` in Titel & Beschreibung gemappt. --- ## Tankmodell & Persistenz * `amountPerDose_microL` definiert Ölmenge pro Puls * Virtueller Tank (ml, Warnschwelle %, Restreichweite) * Daten persistiert in EEPROM/Flash (Partition PDS) * Sanity/Checksum‑Prüfungen → passende DTCs --- ## Speed Sources * **Impuls/Pickup:** via Interrupt (konfigurierbar: Puls/Umdrehung, Reifenmaße) * **GPS (TinyGPSPlus):** Baudrate wählbar, Distanzberechnung * **CAN (KTM‑spezifisch):** tested mit KTM 890 Adventure R & 1290 SuperDuke * **OBD2 CAN/K‑Line:** in Testphase (PCB ≥ 1.4 für K‑Line) --- ## LED Control * Implementiert in `ledcontrol.cpp` * Farben + Muster (`led_colors.h`) * Brightness‑Range konfigurierbar (WebUI) * DTC Severity → LED Orange/Rot --- ## Codegen & Versionsverwaltung * `struct2json.cpp` wird **automatisch generiert** (nicht manuell editieren) * Git‑Revision via `codegen/git_rev_macro.py` eingebettet * Flash‑Version Check: „Benötigte vs. Installierte Flash‑Version“ (WebUI‑Update‑Tab) --- ## Hardware Pin‑Mapping & PCB Revisionen ### Power‑Pfad (Rev 1.4) * **+12 V Eingang** → **Verpolschutz‑Diode** → **Step‑Down auf 5 V** → versorgt **Wemos D1 mini** * **3,3 V** wird vom **Wemos** bereitgestellt (per LDO) und speist Peripherie (CAN, K‑Line, OLED, EEPROM, WS2812‑Data‑Level ok am D3) * **Pumpe**: Low‑Side‑MOSFET mit **Freilaufdiode** (Entstörung gegen induktive Spannungsspitzen) ### Wemos D1 mini (ESP8266) – Pins | Funktion | Board‑Pin | GPIO | Bemerkung | | ---------------------------------- | --------- | ------ | ------------------------------------------------------------------------------------------- | | **Pumpe (MOSFET, Low‑Side)** | D0 | GPIO16 | Schaltausgang für Pumpentreiber | | **I²C SCL (OLED/EEPROM)** | D1 | GPIO5 | U8g2 + I2C‑EEPROM auf gleichem Bus | | **I²C SDA (OLED/EEPROM)** | D2 | GPIO4 | Pull‑Ups auf 3,3 V vorhanden | | **WS2812 LED – Data** | D3 | GPIO0 | Serieller Widerstand im Datenpfad | | **Cockpit‑Taster** | D4 | GPIO2 | gegen **GND**, Schutzdiode, interner Pull‑Up | | **SPI SCK (MCP2515)** | D5 | GPIO14 | CAN‑Controller | | **SPI MISO (MCP2515)** | D6 | GPIO12 | shared mit internen Leitungen, siehe K‑Line/UART Hinweis | | **SPI MOSI (MCP2515)** | D7 | GPIO13 | CAN‑Controller | | **CS / CEN / Impuls (per Jumper)** | D8 | GPIO15 | **Jumper‑Funktion**: CS für MCP2515 **oder** **CEN\_K‑Line** **oder** **Impuls‑Eingang** | | **UART0 TX** | TX (J4‑4) | GPIO1 | geht an USB‑UART **und** an K‑Line‑Transceiver (aktiv nur wenn **CEN\_K‑Line** gesetzt) | | **UART0 RX / GPS‑Eingang** | RX (J4‑3) | GPIO3 | USB‑UART **und** GPS‑Eingang; GPS‑Frames werden vom Parser konsumiert, Rest an CLI geroutet | > **Hinweis zu K‑Line:** Der MC33660 wird über **CEN\_K‑Line** (D8, per Löt‑Jumper) nur aktiviert, wenn gesendet/empfangen werden soll. Dadurch bleibt die serielle Konsole (USB) im Normalbetrieb verfügbar. ### CAN / OBD‑K‑Line / GPS – Anschlüsse * **CAN:** MCP2515 (SPI) + MCP2551, Signale **CAN\_H**/**CAN\_L** nach außen geführt * **K‑Line:** MC33660, UART0 TX/RX zugeschaltet über **CEN\_K‑Line** * **GPS (seriell):** UART0 RX an **J4‑Pin 3**, Baudrate im WebUI wählbar; nur RX genutzt ### PCB‑Revisionen * **Rev 1.2:** Basis (Pumpe, Taster, LED, optional OLED/I²C) * **Rev 1.3:** Verbesserte CAN‑Integration/Power‑Pfad * **Rev 1.4:** K‑Line‑Transceiver, Jumper‑Mux auf **D8** (CS/CEN/Impuls), GPS‑Header (J4) \-------------------|------|-----------------|-------------------------------------------| \| Taster | D3 | GPIO0 | Pull‑Up, ISR‑Abfrage | \| RGB‑LED (WS2812) | D4 | GPIO2 | Adafruit NeoPixel‑Lib | \| Pumpe (MOSFET) | D1 | GPIO5 | Low‑Side Treiber | \| CAN‑CS | D8 | GPIO15 | MCP2515 CS | \| CAN‑INT | D0 | GPIO16 | Interrupt vom MCP2515 | \| OBD2 K‑Line | D7 | GPIO13 | ab PCB Rev 1.4, Pegelwandler erforderlich | \| GPS RX | D6 | GPIO12 | Seriell, TinyGPSPlus | \| OLED I²C SCL | D5 | GPIO14 | U8g2‑Lib | \| OLED I²C SDA | D2 | GPIO4 | U8g2‑Lib | > Hinweis: tatsächliches Mapping je nach `config.h` und PCB‑Revision. Tabelle zeigt Standardzuordnung Rev 1.4. ### PCB Revisionen * **Rev 1.2:** Basisfunktionen, kein OBD2‑Support * **Rev 1.3:** Verbesserte CAN‑Integration, stabileres Power‑Design * **Rev 1.4:** zusätzlicher Pegelwandler für **OBD2 K‑Line**, vorbereitet für GPS‑Modul --- ## Known Limitations / TODO * OBD2 CAN/K‑Line: nur Basisfunktionen, erweiterte PID‑Unterstützung offen * GPS: bei schlechtem Empfang kann DTC „NO GPS SIGNAL“ spammen * OLED: nur Basic‑Statusanzeigen; keine volle UI ---