diff --git a/.gitignore b/.gitignore index 432215e..384b38a 100644 --- a/.gitignore +++ b/.gitignore @@ -57,3 +57,4 @@ hardware/gerber/*.drl .DS_Store Thumbs.db desktop.ini +CLAUDE.md \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..fd3047d --- /dev/null +++ b/README.md @@ -0,0 +1,503 @@ +# 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 +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=` +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 diff --git a/include/html.h b/include/html.h index 41bf424..54498c4 100644 --- a/include/html.h +++ b/include/html.h @@ -10,7 +10,7 @@ // GZIP-komprimierte HTML-Seite const uint8_t HTML_PAGE_GZIP[] PROGMEM = { - 0x1f, 0x8b, 0x08, 0x00, 0x23, 0x3b, 0x76, 0x69, 0x02, 0xff, 0xed, 0xbd, 0x6b, 0x73, 0x1b, 0x49, + 0x1f, 0x8b, 0x08, 0x00, 0x01, 0x3e, 0x76, 0x69, 0x02, 0xff, 0xed, 0xbd, 0x6b, 0x73, 0x1b, 0x49, 0x92, 0x20, 0xf8, 0x5d, 0xbf, 0x22, 0xc4, 0xea, 0x12, 0x80, 0x2e, 0x00, 0x04, 0xc0, 0x87, 0x28, 0x52, 0xa4, 0x8c, 0xe2, 0x43, 0xe2, 0x88, 0xa2, 0x78, 0x04, 0x25, 0xed, 0xd6, 0x63, 0xba, 0x13, 0x40, 0x00, 0xc8, 0x62, 0x22, 0x13, 0x9b, 0x99, 0x20, 0x25, 0x56, 0x6b, 0x6d, 0x3e, 0x74, 0x8f,