added documentation
This commit is contained in:
192
DEV.md
Normal file
192
DEV.md
Normal file
@@ -0,0 +1,192 @@
|
||||
# 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://<host>/ws`
|
||||
|
||||
### Server → Client Events
|
||||
|
||||
* `NOTIFY:<type>;<msg>` → Toast/Alert im UI
|
||||
* `DEBUG:<text>` → Debugausgabe
|
||||
* `DTC:<list>` → aktive DTCs (Format: `ts,code,severity,active;…`)
|
||||
* `MAPPING_STATUS:<map>` → Mapping Keys → Labels (Statuswerte)
|
||||
* `MAPPING_STATIC:<map>` → Mapping Keys → Labels (Staticwerte)
|
||||
* `STATUS:<values>` → Livewerte (z. B. Distanzzähler, Tank %)
|
||||
* `STATIC:<values>` → Konfiguration, Versionen
|
||||
|
||||
### Client → Server Events
|
||||
|
||||
* Generisches Schema: `btn-<elementId>:<value>`
|
||||
* 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
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user