Laser Cutter Dot Matrix Display und MQTT Client

Dieses Projekt implementiert einen ESP32-basierten MQTT-Client mit Dot-Matrix-Display für einen Laser Cutter. Es misst und visualisiert die aktive Laserzeit, sendet Session-Daten an einen MQTT-Broker und bietet ein Browser-Webinterface zur Konfiguration und Steuerung.

---

Inhaltsverzeichnis

1. Hardware
2. Pinbelegung
3. Display
4. Laser-Signaldetektion
5. Zeit-Tracking & Gratiszeit
6. MQTT Client
7. Webinterface
8. Konfiguration & Persistenz
9. WiFi-Setup (WiFiManager)
10. OTA Firmware-Update
11. Fehlerverhalten
12. Bibliotheken
13. Build & Flash

---

Hardware

Komponente	Modell / Beschreibung
Mikrocontroller	AZ-Delivery ESP32 DevKit V4
Dot-Matrix-Display	8× GYMAX7219 Module (kompatibel zu MAX7219), 8×8 LEDs je Modul
Display-Anordnung	4 Module nebeneinander × 2 Reihen = 32×16 LEDs
Display-Kaskadierung	Alle 8 Module in einer einzigen SPI-Kette
Laser-Aktivsignal	Potentialfreier Ausgang des Laser Cutters (Optokoppler empfohlen)
Optional	Shelly PM Mini G3 als externer Leistungsmesser (separater MQTT-Service)

---

Pinbelegung

Signal	ESP32 GPIO	Beschreibung
MAX7219 MOSI	GPIO 23	SPI Data (VSPI)
MAX7219 CLK	GPIO 18	SPI Clock (VSPI)
MAX7219 CS	GPIO 5	SPI Chip Select
Laser-Signal	GPIO 4	Potentialfreier Eingang (INPUT_PULLUP, konfigurierbar invertierbar)

Die Polarität des Laser-Signals (HIGH = aktiv oder LOW = aktiv) ist über das Webinterface konfigurierbar.

---

Display

Das Display besteht aus 8 GYMAX7219-Modulen in einer 4×2-Anordnung (32×16 LEDs gesamt).
Es ist in zwei Zonen aufgeteilt, die unabhängig voneinander beschrieben werden:

Zone	Module (Kette)	Anzeige-Inhalt
Oben	Module 0–3	Akkumulierte aktive Laserzeit in Minuten (z.B. 42.5 min)
Unten	Module 4–7	Laufender Countdown in Sekunden der Gratiszeit, danach ---

• Die Anzeige aktualisiert sich sekündlich, solange der Laser aktiv ist.
• Bei inaktivem Laser bleibt die letzte gemessene Zeit dauerhaft sichtbar.
• Fehlerzustände (WLAN, MQTT) werden in der unteren Zeile, erstes Modul angezeigt.
• Die Bibliotheken MD_Parola + MD_MAX72XX werden für die Ansteuerung verwendet.

---

Laser-Signaldetektion

Der ESP32 überwacht einen digitalen GPIO-Eingang mit internem Pull-Up-Widerstand (INPUT_PULLUP).
Der potentialfreie Ausgang des Laser Cutters (z.B. Schließer-Kontakt über Optokoppler) wird an diesen Pin angeschlossen.

• Polarität konfigurierbar: Im Webinterface einstellbar, ob LOW oder HIGH den aktiven Zustand bedeutet.
• Debounce: Software-Entprellung, um Fehlmessungen bei Schaltflanken zu vermeiden.
• Eine Session beginnt, wenn der Laser aktiv wird, und endet, wenn er inaktiv wird.

---

Zeit-Tracking & Gratiszeit

• Die Laserzeit wird akkumulativ in Minuten gezählt und über Neustarts hinaus im NVS (Non-Volatile Storage) des ESP32 gespeichert.
• Gratiszeit: Eine konfigurierbare Zeitspanne (0–120 Sekunden) am Anfang jeder Session wird nicht zur akkumulierten Zeit gezählt. Dies erlaubt kurze Testläufe zum Einstellen des Laser Cutters ohne Kosten.
  • Standard: 20 Sekunden
  • Einstellbar über das Webinterface
• Die untere Display-Zeile zeigt während der Gratiszeit einen Countdown an.

---

MQTT Client

Der ESP32 verbindet sich mit einem MQTT-Broker (konfigurierbar über Webinterface).

Topics

Richtung	Topic	Format	Beschreibung
Publish	lasercutter/session	JSON	Wird beim Ende einer Session gesendet
Subscribe	lasercutter/reset	"1"	Setzt die akkumulierte Laserzeit auf 0
Publish	lasercutter/status	JSON	Heartbeat alle 60 Sekunden (online/offline)

JSON-Format lasercutter/session

{
  "session_s": 125,
  "total_min": 42.5,
  "gratiszeit_s": 20,
  "ts": "2026-02-22T10:30:00Z"
}

JSON-Format lasercutter/status

{
  "online": true,
  "total_min": 42.5,
  "ip": "192.168.1.100",
  "uptime_s": 3600
}

Verhalten

• Reconnect im Hintergrund, falls MQTT-Broker nicht erreichbar.
• Bei aktivem Laser läuft die Zeitmessung unabhängig vom MQTT-Status weiter.
• QoS 1 für Session- und Reset-Topics.

---

Webinterface

Das Webinterface ist über die IP-Adresse des ESP32 im Browser erreichbar.

Seite	URL	Funktion
Status	/	Aktuelle Laserzeit, letzter Session-Wert, Systemstatus
Konfiguration	/config	MQTT-Broker (IP, Port, User, Passwort), Gratiszeit, Polarität
Reset	/reset	Setzt akkumulierte Laserzeit zurück
OTA Update	/update	Firmware-Update über Browser

---

Konfiguration & Persistenz

Alle Einstellungen werden im NVS (Non-Volatile Storage) des ESP32 gespeichert und sind über das Webinterface änderbar:

Einstellung	Standard	Beschreibung
MQTT Broker IP	192.168.1.1	IP-Adresse des MQTT-Brokers
MQTT Port	1883	Port des MQTT-Brokers
MQTT User	(leer)	MQTT Benutzername (optional)
MQTT Passwort	(leer)	MQTT Passwort (optional)
Gratiszeit	20	Sekunden, 0–120
Signal-Polarität	LOW_ACTIVE	LOW_ACTIVE oder HIGH_ACTIVE
Akkumulierte Zeit	0.0	Gespeicherte Laserzeit in Minuten (NVS)

---

WiFi-Setup (WiFiManager)

Beim ersten Start (oder wenn keine gespeicherten WLAN-Daten vorhanden) öffnet das Gerät einen Access Point mit Captive Portal:

• SSID: LaserCutter-Setup
• Im Browser öffnet sich automatisch die Konfigurationsseite.
• WLAN-Credentials werden nach erfolgreicher Verbindung im NVS gespeichert.

---

OTA Firmware-Update

Firmware-Updates können kabellos über die Weboberfläche unter /update eingespielt werden (ElegantOTA).

---

Fehlerverhalten

Zustand	Display-Anzeige (untere Zeile, Modul 1)	Verhalten
WLAN getrennt	WiFi ERR	Zeiterfassung läuft weiter, Reconnect
MQTT nicht erreichbar	MQTT ERR	Zeiterfassung läuft weiter, Reconnect
WLAN + MQTT OK	Normaler Betrieb (Countdown/---)	–

---

Bibliotheken

Bibliothek	Zweck
MD_Parola	Dot-Matrix-Display Textausgabe
MD_MAX72XX	Treiber für MAX7219/GYMAX7219
PubSubClient	MQTT Client
WiFiManager	WiFi Captive Portal
ESPAsyncWebServer	Asynchroner Webserver
AsyncTCP	TCP-Basis für ESPAsyncWebServer
ArduinoJson	JSON Serialisierung/Deserialisierung
Preferences	NVS-Zugriff (built-in ESP32 Arduino)
ElegantOTA	OTA-Update über Webinterface

---

Build & Flash

# PlatformIO CLI
pio run --target upload

# Serieller Monitor
pio device monitor

Ziel-Board: az-delivery-devkit-v4 (ESP32), Upload-Port: COM3

---

Projektstruktur

MQTT-Display-LaserCutter/
├── src/
│   └── main.cpp              # Hauptprogramm
├── include/
│   ├── config.h              # Pin-Definitionen, Konstanten
│   ├── display_manager.h     # Display-Logik (MD_Parola)
│   ├── laser_tracker.h       # Signal-Detektion & Zeiterfassung
│   ├── mqtt_client.h         # MQTT-Wrapper (PubSubClient)
│   ├── web_server.h          # Webinterface (ESPAsyncWebServer)
│   └── settings.h            # NVS-Persistenz (Preferences)
├── parser/
│   └── shelly_parser.py      # Separater Python-Parser für Shelly PM G3
├── platformio.ini
└── README.md