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

git clone <repository-url>
cd CharGraph-Basic

2. Abhängigkeiten installieren

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

// 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:

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

5. Build und Upload

# 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

# 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

# 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

{
  "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:

{
  "success": true,
  "message": "Update erfolgreich"
}

oder bei Fehler:

{
  "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:

{
  "success": true,
  "message": "Update gestartet"
}

Fehlerbehandlung:

{
  "success": false,
  "message": "URL fehlt"
}

---

GET /ota/status

Gibt aktuellen Update-Fortschritt zurück.

Response: 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)

[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)

-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)

// 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

# 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

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

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
• ESP8266 Arduino Core
• ESP8266 Technical Reference
• Arduino OTA Update Guide

---

Zuletzt aktualisiert: 25. Januar 2026