Kettenoeler/README.md

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)

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

# 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
• PCB & Schaltpläne (Hardware): CERN OHL-S v2.0
• Dokumentation & Bilder: CC BY-NC-SA 4.0

👉 Zusammenfassung: Basteln, Nachbauen, Lernen erlaubt ✅ – kommerzieller Vertrieb oder Closed-Source-Nutzung verboten ❌. Details siehe LICENSE.md.

---

Autor & Dank

Entwickelt von Souko „Shakaru“ Hiabuto

Besonderer Dank an Steffen Koberitz (McCoi) für Hinweise zur optimalen Ansteuerung der McCoi‑Pumpe.