📗 Tutorial: Aufbau Complete-Platine samt Inbetriebnahme und Tipps

biologist · 21. August 2025 um 20:22

Dies ist ein Tutorial, welches ausschließlich für die Complete-Platine gültig idst.

Allgemein

Lies dir ESPuino complete komplett durch. Es ist WICHTIG, dass alles, was dort steht, verstanden wird. Bei Fragen kannst du gerne hier im Forum nachfragen.

Warnung

Es gibt aktuell leider bei LFP-Akkus von Eremit ein Problem mit der Polarität der Akkus, nachdem diese geändert wurde, ohne dass ich dies wusste. Prüfe UNBEDINGT, ob du davon betroffen bist - es ist recht einfach, das Problem zu beheben. Details hier: Wichtig: Polarität von LFP-Akkus. LiPo-Akkus sind hiervon nicht betroffen.

Löten

Die Complete kommt komplett fertig gelötet zu dir. Es gibt jedoch auf der Unterseite verschiedene Lötbrücken, die zu konfigurieren sind. Zu diesen habe ich eine Kurzfassung und eine Langfassung geschrieben.

Löten des Drehencoders

Solltest du einen Drehencoder bei mir bestellt haben, so achte unbedingt darauf, wie dieser gelötet werden muss. Hier ist es beschrieben: Drehencoder by ESPuino.

Hardware

Achte beim Löten der Anschlussleitungen für Neopixel, RFID-Reader und ggf. Drehencoder (wenn du keinen von mir hast mit Steckanschluss) darauf, dass die Belegung 100% mit dem Platinenaufdruck übereinstimmt. Verlasse dich NIE (!) auf Farben der Anschlussleitungen. Vor allem das Anschließen des Neopixels ist sehr kritisch: Vertauschst du die Polarität, so kommt es zu einem Kurzschluss, der dir im schlimmsten Fall das Board zerstört!
Stecke, sofern vorhanden, die Anschlussleitung für die Kopfhörerplatine in den sechspoligen Anschluss auf der Complete und in die Kopfhörerplatine.
RFID: Für RC522 werden nicht alle Anschlüsse gebraucht, für PN5180 jedoch schon. Was wie wo anzuschließen ist, ist hier in einer Tabelle beschrieben. Adern, die nicht gebraucht werden, umwickelst du am besten mit Isolierband, so dass kein Kurzschluss entstehen kann.

Der erste Start deines ESPuinos

Sämtliche Complete-Platinen, die ich rausschicke, sind bereits mit ESPuino vorgeflasht - und zwar mit dem dev-Branch. Hierbei werden die [Standardeinstellungen]ESPuino complete) verwendet, die für die Complete notwendig sind. Davon abweichend ist Support für den RFID-Reader PN5180 einkompiliert (RFID_READER_TYPE_PN5180) und stattdessen Support für RC522 deaktiviert (RFID_READER_TYPE_MFRC522_SPI). Solltest du davon nicht abweichen wollen, so kannst du dir die Einrichtung von Visual Studio Code zur Not auch sparen. Oftmacht es aber schon Sinn, es installiert zu haben; nicht zuletzt zur Fehlersuche. Planst du keine Installation, so kannst du direkt zum Kapitel „Inbetriebnahme“ wechseln.

Welchen ESPuino-Branch benutzen?

Bei ESPuino gibt es zwei Branches (Entwicklungszweige):
Master: Dies ist der Hauptentwicklungszweig, er gilt als „stabil“, hat jedoch den Nachteil, dass er nicht immer alle neuen Features besitzt. Es gibt keinen festen Release-Zyklus.
Dev: Dies ist in der Entwicklungszweig. Hier kommen Neuentwicklungen rein und werden dort zuerst getestet, bevor sie später, wenn sie als stabil genug gelten, in den Master überführt („gemerged“) werden. Keine Angst: Sachen, die in den Dev-Branch integriert werden, sind nicht komplett ungetestet, jedoch möglicherweise nur von 1-2 Personen.

Fazit: Wer sich unsicher ist, benutzt am besten den Master-Branch. Wer den Dev-Branch benutzt, der muss keine Angst davor haben, aber sollte das einfach im Hinterkopf haben. D.h. im Gegenzug natürlich nicht, dass es im Master-Branch keine Fehler gibt (Software ist ja bekanntlich nie fehlerlos) und im Dev-Branch aber schon . Ich würde sagen: Wenn man den Dev-Branch benutzen möchte (was völlig ok ist), dann sollte man zum Zeitpunkt des Wechselns hier im Forum etwas mitlesen, damit man auf dem aktuellen Stand ist, was gerade entwickelt wird.

Einrichtung Visual Studio Code

Möchtest du beispielsweise vom RFID-Reader PN5180 auf RC522 wechseln, so musst du Visual Studio Code einrichten und eine eigene Firmware kompilieren.

Vorgehensweise:

Zuerst musst du Visual Studio Code (nachfolgend VSC) installieren und anschließend Platformio als Plugin. Wie das geht steht hier: 📗 Einrichtung von Visual Studio Code mit Platformio.
Am linken Rand in VSC findest du allerlei Symbole. Nachfolgend ein paar Infos zu diesen Symbolen. Über das oberste Symbol hast du Zugriff auf Dateien. Wenn du später (folgt weiter unten) das Projekt ausgecheckt hast, dann siehst du sie dort:

Klickst du dort drauf, wo du im Bild die 6 siehst, öffnest du den GIT-Browser, in dem du z.B. siehst, welche Dateien von dir bearbeitet wurden. Weiter Infos dazu findest du hier.

Etwas weiter unten, bei der 1, findest du den Plugin-Browser. Hier kannst du Plugins installieren (Platformio brauchst du zwingend, ich würde zusätzlich auch Gitlens empfehlen).

Das vielleicht wichtigste Symbol ist jedoch der Alien-Kopf, welcher das Platformio-Plugin repräsentiert. Hier kannst du mittels „Upload and Monitor“ in einem Schritt die Firmware kompilieren, auf den ESP32 hochladen und anschließend den seriellen Monitor aktivieren. Um nur den seriellen Monitor zu aktivieren klickst du auf „Monitor“.

Wichtig ist es nun, in das richtige Environment (auch HAL genannt) zu wechseln. Im oberen Bereich ist es hier beschrieben, aber nochmal in Kürze: Ganz unten am Bildschirmrand von VSC siehst du irgendwas mit „env:…“ stehen. Das klickst du an und wechselst auf env:complete. Achte drauf, dass du es nicht verwechselst.

Passend ausgewähltes Environment444×256 2.83 KB

Hier die Liste aller verfügbaren Environments:

Im Anschluss musst du den ESPuino-Code in VSC auschecken: 📗 ESPuino in Platformio anlegen und mit git aktuell halten.
In src/settings.h bzw. src/complete.h musst du nun deine Anpassungen vornehmen. Der Port-Expander wird inzwischen zwangsweise aktiviert, da das ständig Leute vergessen haben.
Ganz allgemein sind alle Optionen, die man anpassen kann, nochmal zentral beschrieben: 📗 Welche Optionen beim Kompilieren gibt es?. In Zukunft wird einiges davon in das ESPuino-Webinterface wandern, aber es ist noch unklar, wann das fertig sein wird.
Hast du alles fertig konfiguriert, dann schließt du deine Complete an den Rechner an. Unter Windows könnte es sein, dass der Treiber für CH340 installiert werden muss, damit das Develboard erkannt wird. Ab Windows 11 sollte das jedoch automatisch funktionieren. Schließe es einfach mal an und schaue, ob’s auch ohne Treiber-Installation klappt. Unter Linux und Mac OS ist dies jedenfalls nicht notwendig. Hintergrund dafür ist, dass sich auf dem Develboard ein Chip (CH340C) befindet, der die seriellen Signale des ESP32 zu USB übersetzt und umgekehrt.
Nun klickst du in VSC links oben unter „Project Tasks“ auf „Upload and Monitor“. Die Firmware wird nun kompiliert (kann ein paar Minuten dauern) und im Anschluss auf dein Develboard geflasht. Anschließend kannst du im unteren Bildschirmbereich in der Konsole sehen, ob alles geklappt hat. Hier siehst du z.B. auch, ob ein etwaiger PN5180 erkannt wurde. Später dann auch die IP-Adresse, die dein WLAN-Router dem ESPuino in deinem Netzwerk zugewiesen hat (dazu nachfolgend gleich mehr).
Dein ESPuino ist, wenn alles geklappt hat, nun startklar.
Noch ein Tipp für die Profis (der „normale User“ muss hier nie etwas ändern!): Es gibt eine zentrale Datei, die platformio.ini heißt, in der das Projekt und die einzelnen Environments konfiguriert werden. Falls du dort Anpassungen machen willst oder musst: Hier gibt’s weitere Informationen dazu: Espressif 32 — PlatformIO latest documentation.

Weitere Tipps

Sollten die LEDs auf deinem Neopixel-Ring sich entgegen des Uhrzeigersinns aufbauen, so kannst du das mittels NEOPIXEL_REVERSE_ROTATION korrigieren (settings.h). Es geht jedoch auch komfortabel im Webinterface.
Ist dir der Lautsprecher des ESPuinos im unteren Lautstärke-Bereich zu laut, so teste die Anpassung der Option VOLUMECURVE (settings.h). Ansonsten prüfe, ob die Lötjumper JP2 und JP3 auf der Rückseite: In der leistesten Variante (+3 dB) ist JP2 gesetzt, JP3 jedoch nicht. Setze nicht beide Lötjumper gleichzeitig.
Ist die Drehrichtung des Drehencoders anders rum, als du es erwartest, so kannst du das über das Webinterface in den allg. Einstellungen umkehren. Weitere Infos hier.
Du kannst alle Buttons und auch Mehrtasten-Kombinationen auch mit anderen Aktionen belegen. Die Konfiguration findet in der settings.h statt. Welche Optionen es gibt, das findet du hier: 📗 Das dynamische Button-Layout. Sogar virtuelle Karten gibt es: 📗 Virtual RFID-Cards.

Inbetriebnahme

Viele Infos zur Inbetriebnahme findest du hier: 📗 Der erste Start deines ESPuino.
Das Webinterface ist hier dokumentiert: 📗 Dokumentation Webinterface.
Du musst auf deinem Computer nun in das WLAN deines ESPuinos wechseln, um dort die Zugangsdaten deines Heim-WLANs zu konfigurieren. D.h. kann ESPuino selbst sich nicht an einem WLAN anmelden (entweder weil noch keine Zugangsdaten konfiguriert wurden oder weil es aus sonstigen Gründen nicht geklappt hat), so spannt es selbst ein WLAN auf. Sofern du es nicht anders benannt hast, heißt es standardmäßig „ESPuino“ (ohne Passwort); du kannst das über den Parameter accessPointNetworkSSID (settings.h) auch ändern. Auch ein Passwort kann gesetzt werden. Hast du in das ESPuino-WLAN gewechselt, so wird der ESP32 deinem Rechner eine IP-Adresse zuweisen und üblicherweise automatisch ein Fenster (Captive Portal) erscheinen, in dem du die WLAN-Zugangsdaten eintragen musst. Dort legst du auch den Namen (Hostname) des ESPuinos im Netzwerk fest. Sollte das mit dem Captive Portal nicht klappen, so musst du dich im Webbrowser per http://192.168.4.1 mit deinem ESPuino verbinden. Wichtig: Du kannst das grundsätzlich auch mit einem Smartphone machen, aber es kann dir z.B. mit Android passieren, dass der Zugriff scheitert, da Android erkennt, dass im ESPuino-WLAN kein Internetzugang vorhanden ist. Dann wird alles über LTE/5G geschickt und landet im Nirvana. Bei iOS weiß ich es nicht.
Nach dem Abspeichern der Konfiguration (Button ganz unten im Captive Portal) und einem sich anschließenden ESPuino-Neustart sollte dein ESPuino Teil deines WLANs sein: Konnte er sich dort erfolgreich anmelden, so wechselt die LED-Farbe von grün auf auf weiß. Bleibt sie bei grün, so hat es nicht geklappt (dann wiederhole den Prozess und überprüfe deine WLAN-Zugangsdaten). Falls es geklappt hat: Schaue, dass sich dein Computer/Handy auch wieder mit dem gleichen WLAN verbunden hat, in dem sich dein ESPuino befindet. Ab jetzt kannst du problemlos auch dein Smartphone verwenden, so lange es Verbindung zum WLAN hat, in dem sich auch dein ESPuino befindet.
Du musst nun entweder die IP-Adresse deines ESPuinos im Webbrowser eintragen (nur http, kein https!) oder den konfigurierten Hostname: Hast du ihn z.B. einfach bei espuino belassen, so kannst du via http://espuino.local darauf zugreifen (dauert ggf. ein paar Sekunden). Fritzbox-Benutzer können auch http://espuino.fritz.box eingeben oder im Webinterface der Fritzbox die IP-Adresse des ESPuinos raussuchen. Auch in der Konsole von VSC findest du die IP-Adresse. Es ist auf jeden Fall mit extrem großer Wahrscheinlichkeit NICHT die o.g. 192.168.4.1 .
Du kannst den Namen des ESPuinos auch nachträglich über das Webinterface von deinem ESPuino ändern (macht vor allem bei mehreren ESPuinos im gleichen Haushalt absolut Sinn). Du kannst dort auch mehrere WLANs konfigurieren, falls du an verschiedenen Orten WLAN-Konnektivität benötigst. Es wird immer zuerst dasjenige verwendet, das zuletzt funktioniert hat. Klappt das nicht, klappert dein ESPuino alle WLANs nacheinander ab, für die du Zugangsdaten hinterlegt hast.
Im ESPuino-Webinterface angekommen solltest du die Spannungen noch anpassen, die der Neopixel dir visualisiert. Welche das sind, hängt davon ab, ob du eine LFP-Complete oder LiPo-Complete hast. Die nachfolgenden Spannungen sind meine Vorschläge - du kannst das natürlich anpassen:

Aktion	LFP	LiPo
Unter dieser Spannung (in Volt) wird eine Warnung angezeigt	3.0 V	3.2 V
Eine LED leuchtet bei dieser Spannung (in Volt)	2.9 V	3.1 V
Alle LEDs leuchten bei dieser Spannung (in Volt)	3.25 V	4.2 V

Wir leiten den Füllstand des Akkus indirekt über dessen Spannung ab, was insbesondere bei LiFePO4 nur so bedingt genau ist, da die Entladekurve sehr flach ist. Der ESP32 ist in der Disziplin Spannungsmessung auch kein Präzisionswunder. Dennoch: Sollte dein Akku voll geladen sein und dir dein ESPuino bei der Spannungsmessung melden, dass er trotzdem nicht voll ist, so musst du in der settings-complete.h den Parameter offsetVoltage anpassen. Am besten du misst die Akkuspannung mit einem Multimeter und vergleichst es mit dem, was ESPuino dir als Spannung liefert: Die Differenz aus beidem musst du dort korrigieren und entsprechend addieren oder subtrahieren. Die Spannungsmessung ist dennoch nicht hochpräzise, aber für unsere Zwecke hier sollte es reichen. Früher war das Offset, das man einstellen musste, teilweise recht groß. Nach meiner Überarbeitung funktioniert die Messung auch ohne Korrektur ziemlich gut. Die gemessene Spannung findest du entweder in VSC unten in der Konsole (wenn ESPuino angeschlossen ist an den Rechner) oder im Webinterface unter Infos.

Damit sollte dein ESPuino vollständig betriebsbereit sein. Generell gibt es hier massig Anleitungen. Solltest du noch keine Idee für ein Gehäuse haben, so kannst du dich hier vielleicht inspirieren lassen: Gehäuse - ESPuino :: Rfid-controlled musicplayer.
Viel Spaß mit deinem ESPuino!

Fehlersuche

Es geht nicht immer alles glatt. Hier ein paar wenige Fehlerbilder und deren Abhilfe.

Wenn die µSD-Karte nicht gelesen werden kann überlege, ob diese größer als 32 GB ist. Ist das der Fall, so sei darauf hingewiesen, dass µSD-Karten für den ESP32 immer FAT32 formatiert sein müssen. Üblicherweise ist das bei Karten, die man frisch auspackt, nur bis 32 GB der Fall. Karten, die größer sind, sind üblicherweise exFat-formatiert, was vom ESP32 jedoch nicht gelesen werden kann! Bisschen schwierig ist, dass man das Fehlerbild vom ersten Punkt nicht unterscheiden kann, da in beiden Fällen die Fehlermeldung kommt, dass die µSD-Karte nicht gelesen werden kann.
Miss die Spannung am Ext-Konnektor zwischen Pin 4 (switched 3.3 V) und Pin 12 (GND). Hier sollten, wenn ESPuino gestartet ist, 3,3 V anliegen.
Miss die Spannung am Ext-Konnektor zwischen Pin 2 (3.3 V) und Pin 12 (GND) bei reinem USB-Betrieb (ohne Akku). Hier sollten ebenfalls stabil 3,3 V ankommen. Ist das nicht der Fall, so ist ggf. der Spannungsregler defekt.
Wenn der RFID-Reader nicht funktioniert, so kontrolliere einerseits, ob der passende Support (RC522 bzw PN5180) einkompiliert ist. Andererseits, ob auf der Rückseite der Complete JP8 gelötet ist (1+2 oder 2+3). Ist Letztgenanntes nicht der Fall, so wird das Modul nicht ausreichend mit Spannung versorgt.
Hast du einen PN5180 und möchtest gerne das LPCD-Feature nutzen, so sind mehrere Dinge zu beachten. Erstens muss PN5180_ENABLE_LPCD (settings.h) aktiviert sein. Zusätzlich muss sich auf dem PN5180 mind. die Firmware 4.1 befinden und weiterhin muss auf der Rückseite der Lötjumper JP1 gejumpert sein. Zusätzlich JP8 (1+2).
Wurde dein Problem hier nicht behandelt, dann benutze bitte die Suchfunktion des Forums - vielleicht findest du dort was. Ansonsten öffne bitte einen neuen Diskussionsfaden.