# 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.