Update README.md

This commit is contained in:
XPS\Micro 2026-01-25 17:10:55 +01:00
parent 7cdb899e01
commit 10859fc2fc
3 changed files with 505 additions and 1 deletions

1
.gitignore vendored
View File

@ -57,3 +57,4 @@ hardware/gerber/*.drl
.DS_Store .DS_Store
Thumbs.db Thumbs.db
desktop.ini desktop.ini
CLAUDE.md

503
README.md Normal file
View File

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

View File

@ -10,7 +10,7 @@
// GZIP-komprimierte HTML-Seite // GZIP-komprimierte HTML-Seite
const uint8_t HTML_PAGE_GZIP[] PROGMEM = { 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, 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, 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, 0x40, 0x00, 0xc8, 0x62, 0x22, 0x13, 0x9b, 0x99, 0x20, 0x25, 0x56, 0x6b, 0x6d, 0x3e, 0x74, 0x8f,