Update README.md
This commit is contained in:
XPS\Micro
parent
7cdb899e01
commit
10859fc2fc
1
.gitignore
vendored
1
.gitignore
vendored
|
|
@ -57,3 +57,4 @@ hardware/gerber/*.drl
|
|||
.DS_Store
|
||||
Thumbs.db
|
||||
desktop.ini
|
||||
CLAUDE.md
|
||||
503
README.md
Normal file
503
README.md
Normal 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
|
||||
|
|
@ -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,
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user