# CharGraph-Basic

Ein ESP8266-basiertes Firmware-Update-System mit Web-Interface für die OTA (Over-The-Air) Programmierung von Mikrocontrollern.

## 🎯 Projektbeschreibung

CharGraph-Basic ist ein vollständige FOTA-Update-Lösung für ESP8266-Mikrocontroller. Das Projekt bietet:

- **Web-basierte Benutzeroberfläche** für Firmware-Updates und Gerätekonfiguration
- **Zwei Update-Modi**: Direkter Upload und URL-basiertes Herunterladen
- **Echtzeit-Fortschrittsanzeige** während des Update-Prozesses
- **Responsive Design** mit Dark-Mode-Unterstützung
- **GZIP-komprimierte HTML** (82,6% Kompression) für minimalen Flash-Speicherverbrauch
- **Dual-Mode WiFi** (Access Point + Station) für flexible Konnektivität
- **Fehlerbehandlung** und Status-Reporting
- **EEPROM-basiertes Tracking** von Update-Status und Versionsinfo

## ✨ Features

### Hardware-Unterstützung
- **Zielplattform**: ESP8266 (ESP-12E/F kompatibel)
- **Flash-Speicher**: 4MB (2MB für Sketch, 2MB OTA-Reserve)
- **CPU-Frequenz**: 160MHz
- **Serial-Geschwindigkeit**: 115200 Baud
- **Spezial-Unterstützung** für ESP8266-Clone-Boards (DIO Flash-Mode)

### WiFi & Netzwerk
- **AP-Modus**: Access Point mit eigenem SSID für drahtlose Verbindung
  - Standard SSID: `CharGraph-01`
  - Standard Passwort: `MeinPasswort123`
  - IP-Adresse: `192.168.4.1`
- **Station-Modus**: Verbindung zu existierendem WLAN (für URL-basierte Updates)
- **DNS-Server**: Integrierter DNS-Server für AP-Zugang

### Web-Interface
- **Moderne, responsive UI** mit Gradient-Hintergrund
- **Dark-Mode** für bessere Lesbarkeit in verschiedenen Lichtverhältnissen
- **Live-Systeminformationen**:
  - Firmware-Version
  - Build-Datum und -Zeit
  - Verfügbarer Flash-Speicher
  - Sketch-Größe
  - Chip-ID und Flash-Größe
- **Firmware-Upload** via Browser (Multipart-Form)
- **URL-basierte Updates** mit Fortschrittsanzeige
- **Fehler-Anzeige** und Status-Feedback

### OTA Update-System
- **Sichere Flash-Programmierung** via ESP8266 Updater-Klasse
- **Fortschritts-Callbacks** für Echtzeit-Feedback
- **Auto-Restart** nach erfolgreichem Update
- **Fehlerbehandlung** mit aussagekräftigen Fehlermeldungen
- **EEPROM-Logging** von Update-Status

## 🔧 Anforderungen

### Hardware
- ESP8266 Mikrocontroller (D1 Mini, NodeMCU, oder ESP-12E/F Module)
- USB-zu-Serial-Adapter (für Upload während Entwicklung)
- Stromversorgung (3,3V/500mA minimum)

### Software
- **Python 3.x** (für Build-Skripte)
- **PlatformIO** (für Build und Upload)
- **Texteditor/IDE** (VS Code mit PlatformIO-Extension empfohlen)

#### Abhängigkeiten (in Firmware)
- Arduino Framework für ESP8266
- ESP8266WiFi Library
- ESP8266WebServer Library
- DNSServer Library
- ESP8266httpUpdate Library
- Updater Library (für OTA)
- EEPROM Library (für Persistierung)
- Wire Library (für I2C)

## 📦 Installation

### 1. Repository klonen
```bash
git clone <repository-url>
cd CharGraph-Basic
```

### 2. Abhängigkeiten installieren
```bash
# PlatformIO installieren (falls nicht vorhanden)
pip install platformio

# Erforderliche Python-Module für HTML-Generierung
pip install gzip  # Ist standardmäßig enthalten
```

### 3. Konfiguration anpassen
Bearbeite `src/main.cpp`:

```cpp
// Zeile 18-19: WiFi-Zugangsdaten für Station-Mode
const char* ssid     = "DEIN_WLAN_SSID";
const char* password = "DEIN_WLAN_PASSWORT";

// Zeile 21-22: Access Point Einstellungen
char AP_SSID[AP_SSID_LENGHT]         = "CharGraph-01";
char AP_PASSWORD[AP_PASSWORD_LENGTH] = "MeinPasswort123";

// Zeile 37: Firmware-Versionsnummer
char firmwareVersion[32] = "BASIC";
```

### 4. Serielle Verbindung konfigurieren
Bearbeite `platformio.ini`:

```ini
[env:esp8266clone]
upload_port = COM13  # Angepasst an Ihr System (COM3, /dev/ttyUSB0, etc.)
```

### 5. Build und Upload
```bash
# Projekt bauen
pio run -e esp8266clone

# In ein Gerät hochladen
pio run -e esp8266clone -t upload

# Mit seriellem Monitor starten
pio device monitor -e esp8266clone
```

## 🚀 Verwendung

### Auf das Gerät zugreifen

1. **Verbindung herstellen**:
   - WLAN nach `CharGraph-01` suchen
   - Mit Passwort `MeinPasswort123` verbinden
   - Im Browser zu `192.168.4.1` navigieren

2. **Web-Interface öffnen**:
   - Automatische Umleitung zur Konfigurationsseite
   - Falls nicht: `http://192.168.4.1/`

### Firmware aktualisieren

#### Methode 1: Direkter Upload
1. Im Web-Interface zum Abschnitt "Firmware-Upload" navigieren
2. Binärdatei (`.bin`) auswählen
3. "Upload" klicken
4. Fortschritt beobachten
5. Gerät startet automatisch neu

#### Methode 2: URL-basiertes Update
1. Im Web-Interface zur Option "Update von URL" navigieren
2. URL zur Firmware-Binärdatei eingeben
3. "Update starten" klicken
4. Gerät lädt und installiert Firmware
5. Automatischer Neustart

#### Methode 3: Über REST-API
```bash
# Firmware-Information abrufen
curl http://192.168.4.1/ota/info

# Status des laufenden Updates
curl http://192.168.4.1/ota/status

# Update von URL starten
curl -X POST "http://192.168.4.1/ota/url?url=http://example.com/firmware.bin"

# Firmware-Datei hochladen
curl -F "file=@firmware.bin" http://192.168.4.1/ota/upload
```

### Serielle Konsole nutzen
```bash
# Monitor starten
pio device monitor -e esp8266clone

# Baud-Rate (Standard: 115200)
pio device monitor -e esp8266clone -b 115200
```

Die serielle Ausgabe zeigt:
- Verbindungsstatus
- IP-Adressen
- Update-Fortschritt
- Fehler und Debugging-Informationen

## 📁 Projektstruktur

```
CharGraph-Basic/
├── src/
│   └── main.cpp              # Hauptanwendungscode
├── include/
│   └── html.h                # Auto-generierte GZIP-komprimierte HTML
├── html/
│   └── index.html            # HTML-UI Quellcode
├── platformio.ini            # PlatformIO Konfiguration
├── html_to_header.py         # Build-Script für HTML-Komprimierung
├── .gitignore                # Git-Ignorierregeln
└── README.md                 # Diese Datei
```

### Wichtige Dateien

| Datei | Zweck |
|-------|-------|
| `src/main.cpp` | Web-Server, WiFi-Setup, OTA-Handler, API-Endpoints |
| `html/index.html` | Web-Interface (UI/UX) |
| `include/html.h` | Komprimierte HTML für Flash-Speicher (Auto-generiert) |
| `html_to_header.py` | Python-Script zur HTML-Komprimierung |
| `platformio.ini` | Build-Konfiguration, Compiler-Flags, Abhängigkeiten |

## 🔌 API-Dokumentation

### REST-API Endpoints

#### GET `/`
Serviert die Hauptseite (HTML-Interface).

**Response**: HTML (GZIP-komprimiert)

```
Content-Type: text/html
Content-Encoding: gzip
```

---

#### GET `/ota/info`
Gibt Geräteinformationen und Update-Status zurück.

**Response**: JSON
```json
{
  "version": "BASIC",
  "buildDate": "Jan 25 2026",
  "buildTime": "17:00:00",
  "freeSpace": 204800,
  "sketchSize": 307200,
  "chipId": "12a4b5c",
  "flashSize": 4194304,
  "otaReady": true
}
```

---

#### POST `/ota/upload`
Multipart-File-Upload für direkte Firmware-Installation.

**Request**:
```
Content-Type: multipart/form-data
Body: [binary firmware data]
```

**Response**:
```json
{
  "success": true,
  "message": "Update erfolgreich"
}
```

oder bei Fehler:
```json
{
  "success": false,
  "message": "Begin failed"
}
```

**Mögliche Fehler**:
- `"Begin failed"` - Flash-Programmierer konnte nicht initialisiert werden
- `"Write failed"` - Daten konnten nicht geschrieben werden
- Andere Update-Fehler von der ESP8266 Updater-Klasse

---

#### POST `/ota/url?url=<firmware-url>`
Lädt Firmware von URL und installiert sie.

**Parameter**:
- `url` (Query-Parameter): Vollständige URL zur `.bin`-Datei

**Request**: POST ohne Body

**Response**:
```json
{
  "success": true,
  "message": "Update gestartet"
}
```

**Fehlerbehandlung**:
```json
{
  "success": false,
  "message": "URL fehlt"
}
```

---

#### GET `/ota/status`
Gibt aktuellen Update-Fortschritt zurück.

**Response**: JSON
```json
{
  "inProgress": false,
  "progress": 100,
  "error": "",
  "elapsed": 45000
}
```

**Felder**:
- `inProgress`: Boolean - Lädt Update gerade
- `progress`: Integer (0-100) - Prozentuale Fortschrittsanzeige
- `error`: String - Fehlermeldung (leer bei Erfolg)
- `elapsed`: Integer - Millisekunden seit Update-Start

---

#### GET `*` (Alle anderen Routen)
Leitet zu `/` um (Fehlerbehandlung).

**Response**: HTTP 302 Redirect

---

## ⚙️ Konfiguration

### Hardware-Einstellungen (`platformio.ini`)

```ini
[env:esp8266clone]
board = esp12e                    # ESP8266 Variant
framework = arduino               # Arduino Framework
platform = espressif8266          # ESP8266 Platform

# Flash-Einstellungen für Clone-Kompatibilität
board_build.flash_mode = dio      # DIO statt QIO
board_build.f_cpu = 160000000L    # CPU-Frequenz
board_build.f_flash = 40000000L   # Flash-Frequenz

# Memory-Layout
board_build.ldscript = eagle.flash.4m2m.ld  # 2MB Sketch + 2MB OTA

# Serial-Einstellungen
upload_speed = 115200
monitor_speed = 115200
monitor_dtr = 1                   # RTS/DTR für Clone-Reset
monitor_rts = 1
```

### Build-Flags (`platformio.ini`)

```cpp
-DDEBUG_MODE=false               // Debug-Ausgabe aktivieren (false/true)
-DDEBUG_SOURCE=true              // Firmware Debug-Messages
-DDEBUG_ESP_CORE=false            // ESP-Core Debug
-DDEBUG_ESP_WIFI=0                // WiFi-Debug
-DNDEBUG                          // Assertions deaktivieren
-DUSE_RTC=false                   // RTC-Unterstützung
-DTEST_RGB=false                  // RGB-Tests deaktivieren
-DPOWERLOSSDETECT=false           // Stromausfall-Erkennung
```

### Anwendungskonfiguration (`src/main.cpp`)

```cpp
// EEPROM-Speicheradressen für OTA-Tracking
#define ADDR_OTA_VERSION    166    // Firmware-Version (32 Bytes)
#define ADDR_OTA_BUILD_DATE 198    // Build-Datum (20 Bytes)
#define ADDR_OTA_FLAGS      218    // Status-Flags (1 Byte)

// Access Point Einstellungen
IPAddress apIP(192, 168, 4, 1);   // AP-IP-Adresse
char AP_SSID[14] = "CharGraph-01";
char AP_PASSWORD[17] = "MeinPasswort123";

// Station Mode (für URL-Updates)
const char* ssid = "YOUR_SSID";
const char* password = "YOUR_PASSWORD";
```

## 🔄 Build-Prozess

Das Projekt nutzt einen **Pre-Build-Script** (`html_to_header.py`) zur Vorkomprimierung der HTML:

1. HTML-Datei (`html/index.html`) wird gelesen
2. Mit GZIP (Kompressionslevel 9) komprimiert
3. Als Hex-Array in Header-Datei (`include/html.h`) geschrieben
4. Konstanten definiert:
   - `HTML_PAGE_GZIP[]` - Komprimierte Daten
   - `HTML_PAGE_GZIP_LEN` - Größe der komprimierten Daten

**Kompression-Ergebnis**:
- Original: ~122 KB
- Komprimiert: ~20 KB
- Ratio: 82,6% Einsparung

### Nach HTML-Änderungen
```bash
# Script manuell ausführen (optional, wird automatisch bei Build ausgeführt)
python html_to_header.py

# Dann normal bauen
pio run -e esp8266clone
```

## 🐛 Troubleshooting

### Upload schlägt fehl
```
error: espcomm_open failed
```
**Lösung**:
1. USB-Kabel prüfen
2. Richtigen COM-Port in `platformio.ini` einstellen
3. Device Manager (Windows) oder `dmesg` (Linux) prüfen
4. DTR/RTS-Einstellungen in Konfiguration überprüfen

### Gerät nicht erreichbar
**Problem**: Kann sich nicht mit AP verbinden

**Lösungen**:
1. SSID/Passwort überprüfen (Standard: CharGraph-01 / MeinPasswort123)
2. Gerät mit serieller Konsole verbinden, um Fehler zu sehen
3. Power-Cycle durchführen (ausschalten, 2-3 Sek. warten, einschalten)

### Update schlägt mit "Begin failed" fehl
**Problem**: OTA-Update kann nicht initialisiert werden

**Gründe**:
- Firmware-Datei ist zu groß (>2MB)
- Nicht genug freier Speicher
- Fehlerhafte Firmware-Binärdatei

**Lösung**:
1. Firmware-Größe prüfen: `ls -lh firmware.bin`
2. Serielle Ausgabe für Error-Details prüfen
3. Firmware mit korrekter ESP8266-Konfiguration neu bauen

### Speicherfehler bei Build
```
MemoryError: python memory exceeded
```
**Lösung**: Größere Binärdatei komprimieren - System RAM reicht nicht aus

```bash
# Fallback: HTML ohne maximale Kompression (Level 6)
# In html_to_header.py ändern:
compressed = gzip.compress(html_bytes, compresslevel=6)
```

### Serial-Monitor zeigt Müll
**Problem**: Lesbar-Output wie `¿¬?ü╬¬¬`

**Lösung**: Baud-Rate überprüfen (sollte 115200 sein)
```bash
pio device monitor -e esp8266clone -b 115200
```

## 🔒 Sicherheitshinweise

### ⚠️ WiFi-Zugangsdaten
- Zugangsdaten sind im Quellcode hardcodiert
- Für Produktion: Sichere Speicherung (z.B. EEPROM-Verschlüsselung) erwägen
- Standard-Passwort ändern und neu kompilieren

### ⚠️ OTA-Updates
- Keine Authentifizierung/Autorisierung auf API-Endpoints
- Für Netzwerk-Updates HTTPS/TLS erwägen (verbraucht zusätzliche Resources)
- Update-Quelle validieren (URL-Schema prüfen)

### ⚠️ Firmware-Binärdateien
- Keine Signaturen-Verifizierung im Moment
- Updates nur aus vertrauenswürdigen Quellen installieren

## 📝 Lizenz

[Lizenz eintragen, z.B. MIT, Apache 2.0, GPL, etc.]

## 👤 Autor & Support

**Projekt**: CharGraph-Basic
**Version**: 1.0.0 (BASIC)

### Weitere Ressourcen
- [PlatformIO Dokumentation](https://docs.platformio.org/)
- [ESP8266 Arduino Core](https://github.com/esp8266/Arduino)
- [ESP8266 Technical Reference](https://www.espressif.com/en/products/socs/esp8266/resources)
- [Arduino OTA Update Guide](https://arduino-esp8266.readthedocs.io/en/latest/ota_updates/readme.html)

---

**Zuletzt aktualisiert**: 25. Januar 2026