added documentation
This commit is contained in:
247
README.md
247
README.md
@@ -0,0 +1,247 @@
|
||||
# Smart Chain Oiler
|
||||
|
||||
Ein intelligenter, mikrocontroller‑gesteuerter Kettenöler für Motorräder. Bedient wird das System mit **nur einem Taster** und einer **RGB‑LED**. Alle erweiterten Einstellungen und Wartung erfolgen über ein **WebUI** (WiFi‑Access Point, plattformunabhängig, keine App nötig). Der reguläre Betrieb läuft komplett autark – Smartphone bleibt in der Tasche.
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
|
||||
* **Automatische Schmierung**
|
||||
|
||||
* Normalmodus: Impuls alle **8 000 m** (Standard, anpassbar)
|
||||
* Regenmodus: Impuls alle **4 000 m** (Standard, anpassbar)
|
||||
* Metergenaue Distanzzählung **über Neustarts hinweg** (setzt nicht auf 0 zurück)
|
||||
* **Modi**
|
||||
|
||||
* **Normal** / **Regen** (per Taster umschaltbar, letzter Modus wird gespeichert)
|
||||
* **Wash‑Mode**: für xy m (Standard **500 m**) **alle 10 m** ein Impuls; danach automatische Rückkehr zum vorherigen Modus
|
||||
* **Prime/Entlüften**: feste Impulsanzahl (Standard **25 Pulse**) zum Spülen/Entlüften
|
||||
* **WiFi‑AP**: Zugriff auf WebUI für Setup, Wartung, Updates
|
||||
* **Virtuelle Tanküberwachung**
|
||||
* Details zum Tankmodell & zur Pumpensteuerung siehe weiter unten.
|
||||
* **Diagnose (DTC) & Live‑Status**
|
||||
|
||||
* DTC‑Schweregrade: **INFO**, **WARN (Orange)**, **CRITICAL (Rot, stoppt Pumpe)**
|
||||
* Alle DTCs mit Klartext im WebUI; Push via WebSocket
|
||||
* **Mehrere Geschwindigkeitsquellen**
|
||||
|
||||
* **Impuls/Pickup** (Tachosignal)
|
||||
* **GPS** (seriell; Baudrate wählbar)
|
||||
* **CAN** (KTM‑spezifisch)
|
||||
* **OBD2 über CAN** (in Test)
|
||||
* **OBD2 über K‑Line** (ab PCB‑Rev 1.4)
|
||||
* **RGB‑LED Feedback**
|
||||
|
||||
* Farben: Grün (Normal), Blau (Regen), Pink blinkend (Prime), Türkis (Wash), Gelb (AP aktiv), Orange (Warnung), Rot (kritisch)
|
||||
* Helligkeit **min/max** und Blinkmodus konfigurierbar
|
||||
* **OTA‑Updates**
|
||||
|
||||
* OTA (Port 8266, Passwort), mit optionaler OLED‑Progressanzeige
|
||||
* **Dateisystem & Kompatibilität**
|
||||
|
||||
* LittleFS mit **„required flash version“**‑Check; WebUI‑Tab zeigt Firmware‑, Flash‑ und Git‑Version
|
||||
* **EEPROM‑Architektur**
|
||||
|
||||
* Partitionen **CFG**/**PDS** mit Checksummen, Sanity‑Checks & Wear‑Leveling; passende DTCs bei Inkonsistenzen
|
||||
|
||||
---
|
||||
|
||||
## Tankmodell & Pumpensteuerung
|
||||
|
||||
* **Dosis pro Puls**: einstellbar in µl (Standard auf McCoi-Pumpe abgestimmt)
|
||||
* **Virtuelles Tankmodell**: berechnet Füllstand und Restreichweite basierend auf Tankgröße und Dosiermenge
|
||||
* **Warnung & Stopp**: Orange bei niedrigem Füllstand, Rot & Abschaltung bei 0 %
|
||||
* **Prime/Purge**: feste Pulsanzahl (Standard 25), konfigurierbar im WebUI
|
||||
* **Wash-Mode**: spezielles Muster – z. B. alle 10 m ein Puls über definierte Gesamtdistanz
|
||||
* **Pumpen-Timing**: auf die McCoi Spezial-Ölpumpe abgestimmt, für gleichmäßige Dosierung
|
||||
|
||||
---
|
||||
|
||||
## Hardware
|
||||
|
||||
* **MCU:** ESP8266 (Wemos D1 mini, Arduino‑Framework)
|
||||
* **PCB:** Revisionen 1.2–1.4 (ab **1.4**: OBD2 **K‑Line**)
|
||||
* **Pumpe:**
|
||||
|
||||
* Ursprünglich **Dellorto Ölpumpe PLE 8**
|
||||
* Aktuell **McCoi Spezial‑Ölpumpe** – **Software‑Ansteuerung dieses Projekts ist auf diese Pumpe abgestimmt**. Dank hilfreicher Hinweise von Steffen Koberitz (McCoi) zur optimalen Ansteuerung; **keine Mitarbeit** an der Pumpen‑Hardwareentwicklung.
|
||||
* **Option:** I²C OLED‑Display 128×64 (Standard Arduino/„China“‑Module)
|
||||
|
||||
### Getestete Motorräder
|
||||
|
||||
* **KTM 890 Adventure R (2021)**
|
||||
* **KTM 1290 Super Duke (2023)**
|
||||
|
||||
---
|
||||
|
||||
## Tankmodell & Pumpensteuerung
|
||||
|
||||
*Implementierung: `lubeapp.cpp`*
|
||||
|
||||
* **Dosierung (µl/Puls):** konfigurierbar im WebUI (Schlüssel: *amountPerDose\_microL*). Werte und Pulszeit sind **auf die McCoi‑Pumpe abgestimmt**.
|
||||
* **Virtueller Tank:** Tankgröße (ml) → Füllstand (%) → **Warnschwelle** (Orange) → **0 %** stoppt die Pumpe (Rot). Tank‑Reset unter **Wartung**.
|
||||
* **Prime/Purge:** feste Impulsanzahl (Standard **25**), zum Spülen/Entlüften; Start per Taster oder WebUI.
|
||||
* **Wash‑Mode:** Impuls‑Pattern pro Strecke (Standard: **alle 10 m** über **500 m**), danach automatische Rückkehr zu Normal/Regen.
|
||||
* **Persistenz:** Laufende Zähler & Tankstand werden **über Neustarts** mitgeführt (EEPROM/Flash + Sanity/Checksum).
|
||||
|
||||
---
|
||||
|
||||
## GPS‑Quelle (seriell)
|
||||
|
||||
*Implementierung: `gps.cpp`, TinyGPSPlus*
|
||||
|
||||
* **Parser:** TinyGPSPlus; Baudrate im WebUI wählbar.
|
||||
* **Verwendung:** Geschwindigkeit/Distanz als Basis für Schmierintervalle, metergenau.
|
||||
* **Fallback & DTC:** Kein GPS → DTC‑Meldung (je nach Konfiguration WARN/CRIT) und LED‑Signalisierung; alternative Quellen (Impuls/CAN/OBD) bleiben nutzbar.
|
||||
* **Praxis:** Geeignet, wenn kein Pickup/Tachosignal verfügbar ist oder als zusätzliche Prüfinstanz.
|
||||
|
||||
---
|
||||
|
||||
## Bedienung (Taster & LED)
|
||||
|
||||
> **Prinzip:** Taster gedrückt halten → **LED‑Farbe beobachten** → bei gewünschter Farbe **loslassen**.
|
||||
|
||||
* **0,5–3,5 s**: **Normal ↔ Regen** (Grün/Blau)
|
||||
* **3,5–6,5 s**: **Wash‑Mode** (Türkis)
|
||||
* **6,5–9,5 s**: **Prime/Entlüften** (Pink blinkend)
|
||||
* **9,5–12,5 s**: **WiFi‑AP** an/aus (Gelb)
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A[Button hold] --> B{Hold‑Dauer}
|
||||
B -->|0.5–3.5 s| C[Toggle Normal↔Regen]
|
||||
B -->|3.5–6.5 s| D[Wash‑Mode aktiv]
|
||||
B -->|6.5–9.5 s| E[Prime/Entlüften]
|
||||
B -->|9.5–12.5 s| F[WiFi‑AP Toggle]
|
||||
C --> G[LED: Grün/Blau]
|
||||
D --> H[LED: Türkis]
|
||||
E --> I[LED: Pink blinkend]
|
||||
F --> J[LED: Gelb]
|
||||
```
|
||||
|
||||
**LED‑Bedeutung (Auswahl):** Grün = Normal · Blau = Regen · Pink blinkend = Prime · Türkis = Wash · Gelb = AP aktiv · Orange = Warnung · Rot = Kritisch (Stopp)
|
||||
|
||||
---
|
||||
|
||||
## WebUI (WiFi‑AP)
|
||||
|
||||
**Stack:** WebSocket · JavaScript · Bootstrap · jQuery · responsive.
|
||||
|
||||
**Tabs & Funktionen:**
|
||||
|
||||
* **Home**: Tank % (Progressbar), aktueller Systemstatus, DTC‑Tabelle
|
||||
* **Wartung**: Tank **zurücksetzen**, Entlüften (Pulsezahl einstellen & starten), **Einmessen** (Pulsecounter), **Live‑Debug** (Start/Stop), **Reboot**
|
||||
* **Einstellungen**:
|
||||
|
||||
* **Signalquelle** (Impuls/CAN/GPS/…)
|
||||
|
||||
* **Impuls**: Reifenbreite, Verhältnis, Felgendurchmesser, Pulse/Umdrehung
|
||||
* **CAN**: Modellwahl
|
||||
* **GPS**: Baudrate
|
||||
* **Dosierung**: Normal, Regen, Waschdistanz, Waschintervall
|
||||
* **Öltank**: Kapazität (ml), Warnschwelle (%), Menge/Puls (µl)
|
||||
* **LED**: Blinkmodus, Min-/Max‑Brightness
|
||||
* **WiFi**: SSID‑Liste, Passwort, Auto‑Connect
|
||||
* **Speichern** (Hinweis: Wechsel der Signalquelle triggert Neustart)
|
||||
* **Update**:
|
||||
|
||||
* Versionen: **Firmware**, **Benötigte Flash‑Version**, **Installierte Flash‑Version**, **Git‑Revision**
|
||||
* **EEPROM‑Backup** (Download) & **Restore** (Upload `.ee.json`)
|
||||
* **Firmware‑Update** (Upload `.fw.bin` oder `.fs.gz`)
|
||||
|
||||
> Für den Alltag ist das WebUI nicht nötig; es dient Setup, Tank‑Reset und Diagnose/Updates.
|
||||
|
||||
### Frontend‑Dateien
|
||||
|
||||
* `index.htm` (Haupt‑UI)
|
||||
* `static/js/websocket.js` (WebSocket‑Client & Live‑Update)
|
||||
* `static/js/script.js` (UI‑Helpers, z. B. Passwort‑Toggle, File‑Label)
|
||||
* `static/js/dtc_table.js` + `static/dtc_table.json` (DTC‑Mapping mit Titel & Beschreibung)
|
||||
* `post.htm` (Zwischenseite nach Speichern/Update)
|
||||
|
||||
### WebSocket‑Protokoll (Client ← Server)
|
||||
|
||||
* `NOTIFY:<type>;<message>` → UI‑Toast/Alert
|
||||
* `DEBUG:<text>` → Live‑Debug‑Fenster (append)
|
||||
* `DTC:<dtcList>` → aktive DTCs, z. B. `ts,code,severity,active;...`
|
||||
→ UI: **processDTCNotifications** & **fillDTCTable** (Titel/Beschreibung via `dtc_table.json`)
|
||||
* `MAPPING_STATUS:<map>` → Schlüssel‑Mapping für **STATUS**
|
||||
* `MAPPING_STATIC:<map>` → Schlüssel‑Mapping für **STATIC**
|
||||
* `STATUS:<values>` → Laufzeitwerte, in UI gerendert
|
||||
* `STATIC:<values>` → statische Werte (Konfiguration/Versionen)
|
||||
|
||||
> **WebSocket‑Endpoint:** `ws://<host>/ws`
|
||||
|
||||
### WebSocket‑Protokoll (Client → Server)
|
||||
|
||||
* Generischer UI‑Event: `btn-<elementId>:<value>`
|
||||
Beispiel: Button‑Klicks/Bestätigungen senden `btn-…` an den Server.
|
||||
|
||||
---
|
||||
|
||||
## Build & Flash (PlatformIO)
|
||||
|
||||
* **Projekt:** `platformio.ini` mit Environments für PCB‑Revisionen **1.2**, **1.3**, **1.4** (Serial/OTA)
|
||||
* **Default‑Env:** `pcb_rev_1-4_serial`
|
||||
* **Filesystem:** LittleFS (automatisierte Vorbereitung via Pre/Post‑Scripts)
|
||||
* **OTA:** `espota` (Port 8266, Passwort aus `wifi_credentials.ini`)
|
||||
* **Git‑Revision:** wird als Macro eingebettet (Codegen‑Script)
|
||||
* **Libs (Auszug):** U8g2, Adafruit NeoPixel, Ticker, I2C\_EEPROM, ESPAsyncWebServer‑esphome, ArduinoJson 7, MCP\_CAN, TinyGPSPlus
|
||||
|
||||
### Beispiel
|
||||
|
||||
```bash
|
||||
# Firmware bauen (Standard‑Env)
|
||||
pio run
|
||||
|
||||
# Seriell flashen (z. B. PCB Rev 1.4)
|
||||
pio run -e pcb_rev_1-4_serial -t upload
|
||||
|
||||
# OTA flashen
|
||||
pio run -e pcb_rev_1-4_ota -t upload
|
||||
```
|
||||
|
||||
**Konfiguration über Build‑Flags** (Auszug):
|
||||
|
||||
* `-DPCB_REV=…` (automatisch je nach Env)
|
||||
* `-DFEATURE_ENABLE_OLED`, `-DATOMIC_FS_UPDATE`, `-DCAN_DEBUG_MESSAGE`
|
||||
* WiFi/Passwörter via `wifi_credentials.ini` (`WIFI_SSID_CLIENT`, `WIFI_PASSWORD_CLIENT`, `ADMIN_PASSWORD`, `WIFI_AP_PASSWORD`)
|
||||
|
||||
### Flash‑Version & Updatepfad
|
||||
|
||||
* Wenn „**Benötigte Flash‑Version**“ ≠ „**Installierte Flash‑Version**“: zuerst **FS‑Image** (`.fs.gz`) im WebUI unter **Update → Firmware‑Update** hochladen; danach die eigentliche Firmware (`.fw.bin`).
|
||||
|
||||
---
|
||||
|
||||
## Diagnose (DTC)
|
||||
|
||||
* **WARN (Orange)**: Hinweis/Warnung, Betrieb läuft weiter
|
||||
* **CRITICAL (Rot)**: kritischer Fehler, Öler stoppt
|
||||
* DTCs erscheinen live im WebUI (Tabelle & Detail‑Modal); zusätzlich LED‑Signale
|
||||
* **Vollständige DTC‑Liste** inkl. Beschreibungen siehe **Manual.md**
|
||||
|
||||
---
|
||||
|
||||
## Roadmap / Status
|
||||
|
||||
* OBD2 über CAN & K‑Line: **in aktiver Testphase**
|
||||
* GPS‑Quelle: **funktionsfähig**, weitere Feldtests
|
||||
* Weitere Bikes/Modelle: Community‑Feedback willkommen
|
||||
|
||||
---
|
||||
|
||||
## Lizenz
|
||||
|
||||
- **Firmware & WebUI (Software):** [GNU GPLv3](COPYING.GPLv3)
|
||||
- **PCB & Schaltpläne (Hardware):** [CERN OHL-S v2.0](LICENSE.CERN-OHL-S-2.0)
|
||||
- **Dokumentation & Bilder:** [CC BY-NC-SA 4.0](LICENSE.CC-BY-NC-SA-4.0)
|
||||
|
||||
👉 Zusammenfassung: Basteln, Nachbauen, Lernen erlaubt ✅ – kommerzieller Vertrieb oder Closed-Source-Nutzung verboten ❌. Details siehe [LICENSE.md](LICENSE.md).
|
||||
|
||||
---
|
||||
|
||||
## Autor & Dank
|
||||
|
||||
Entwickelt von **Souko „Shakaru“ Hiabuto**
|
||||
|
||||
Besonderer Dank an **Steffen Koberitz (McCoi)** für Hinweise zur optimalen Ansteuerung der McCoi‑Pumpe.
|
||||
|
||||
Reference in New Issue
Block a user