Der bitcoinSwitch für Jedermann

Den bitcoinSwitch habe ich ausführlich in einem Artikel beschrieben. Er eignet sich dafür, mit Bitcoin⚡Lightning-Zahlungen etwas in der physischen Welt zu schalten. Die Handhabung erfordert aber ein gewisses technisches Verständnis, gerade was die Hardware mit der Verdrahtung und Montage betrifft. Auch die softwaretechnische Installation und Parametrierung mit dem gängigen Werkzeug stellte viele immer wieder vor Herausforderungen, und da der klassische bitcoinSwitch kein Display hat, war die Rückmeldung und Fehleranalysemöglichkeit sehr dürftig. Also entschloss ich mich, etwas dagegen zu tun, und so entstand die ZapBox.

1. Was ist die ZapBox?

Die ZapBox ist ein elektronischer Schalter in der Box, als Gesamtkonzept für Jedermann. Einfach in der Handhabung, stabil, mit guter Benutzer-Rückmeldung und optionalen Funktionen, die weit über die des klassischen bitcoinSwitch hinausgehen. Es gibt auch nicht nur die „eine“ ZapBox, sondern es ist eine ganze Familie, die kontinuierlich ausgebaut werden soll. Verschiedene Anwendungsfälle erfordern verschiedene Systeme. Der Nutzer soll sich darauf konzentrieren können, seine Idee umzusetzen.

Zur ZapBox gehört:

– Ein ESP32-Mikrocontroller (mit oder ohne Display)
– Relais zum Schalten
– USB-Anschlüsse bzw. Klemmen zum einfachen Anschluss
– Komplette Verdrahtung (E-Layout)
– Komplettes Gehäuse (3D-Druck)
– Eine Webseite mit „Web Installer“ zum Beschreiben und Parametrieren der ZapBox
– LED-Taster für die Versionen mit Produktauswahl
– Bei der Version ohne Display (Headless) zwei Status-LEDs für das visuelle Feedback
– Ein LNbits-Account im Backend für die Zahlungsabwicklung

2. Die aktuelle ZapBox-Familie

Die ZapBox-Familie besteht aktuell aus vier Mitgliedern, die individuelle Anforderungen erfüllen sollen.

2.1 ZapBox Compact

Wie der Name schon sagt, die einfache, kompakte Version der ZapBox. Ein USB-Eingang zur Spannungsversorgung und ein USB-Ausgang, der geschaltet wird. Das ist die Version für den Einstieg und für einfache Schaltanwendungen. Alle wichtigen Statusinformationen und der QR-Code werden am Display angezeigt. Die Bedienung erfolgt über die Onboard-Buttons des Mikrocontrollers. Die Compact-Version hat einen 3-fach-Schiebeschalter für „AUTO / OFF / ON“ und einen 2-fach-Schiebeschalter, um das Ausgangssignal zu invertieren, falls man „invers“ schalten möchte.

2.2 ZapBox Duo

Die Version für Leistung mit zwei Kanälen. Möchte ich mehr als einen USB-Ausgang schalten, bekomme ich hiermit die passende Lösung. Ein Leistungsrelais (bis 30 A) mit extra großen Klemmen, die nach außen geführt sind, und ein zweites Relais, das einen Doppel-USB-Ausgang (A und C) schaltet. Die Relais können separat angesteuert werden oder beide zusammen. Das Leistungsrelais schaltet den Antrieb, die Fanfare, die Pumpe oder was auch immer. Und der zweite Ausgang wird dafür genutzt, um die Aktion zu visualisieren, einen Zähler zu triggern oder was auch immer. Die Duo verfügt auch über einen LED-Button zur komfortablen Bedienung und zur Produktauswahl. Wer das nicht benötigt und es schlichter möchte, kann die Frontblende auch ohne LED-Button wählen. Die Schiebeschalter sind hier identisch mit denen der Compact-Version.

2.3 ZapBox Quattro

Möchte man mehrere Kanäle schalten, als eine Art der Produktauswahl, kann man die Quattro verwenden. Hier sind vier Relais als Wechselkontakt nach außen geführt. Die Produktauswahl erfolgt über LED-Buttons. Das Display zeigt neben dem QR-Code noch drei Zeilen an, in denen z. B. die Produktnamen und der Preis angezeigt werden können. So kann die Quattro z. B. für Automaten verwendet werden oder um einfach die „Produktmenge“ nach Zeit schalten zu können. Die Quattro-Version hat keine Schiebeschalter.

2.4 ZapBox Headless

Die ZapBox Headless ist eine Version, die ohne Display auskommt, aber dennoch die Vorteile einer ZapBox vereint. Hier wird ein Standard-ESP32 verwendet und alles in einem kompakten Gehäuse untergebracht. Für die Rückmeldung gibt es zwei LEDs. Eine zeigt den Betriebszustand READY an und blinkt zum Start während der Synchronisation. Zusätzlich zeigt die LED durch spezielle Blinkmuster den Modus „Configuration“ oder den jeweiligen Fehlerstatus an. Die zweite LED zeigt das Schalten als ACTION an, um Probleme mit der Hardware zu erkennen. Die LEDs bieten damit einen hohen Grad an Komfortgewinn gegenüber dem klassischen bitcoinSwitch. Das Signal der LED READY wird auch auf der ESP32-Onboard-LED (grün) angezeigt. Die Headless-Version verfügt über den 3-fach-Schiebeschalter für „AUTO / OFF / ON“. Möchte man das Ausgangssignal „invertieren“, kann man dafür im Gehäuse eine kleine Umverdrahtung am Relais vornehmen.

3. Eine ZapBox aufsetzen

Möchte man eine ZapBox aufsetzen, muss man sich entweder eine ZapBox beschaffen oder selber bauen. Auf der Webseite zapbox.space gibt es eine aktuelle Übersicht der Produktfamilie mit Bildern, weitere Dokumentation soll folgen. Alle technischen Details sowie Schaltpläne und die 3D-Druckdateien findet man auf GitHub. Das Projekt ist Free and Open Source, Support in Form von Rückmeldungen, GitHub-Beiträgen oder Spenden sind willkommen.

Zu der Hardware benötigt man noch einen LNbits-Account und die Erweiterung „Bitcoin Switch“. LNbits ist ein Wallet- und Account-System, das mit verschiedensten Bitcoin-Tools erweitert werden kann. Man kann es selber hosten oder die Instanz einer Gemeinschaft mitnutzen. Zu einem späteren Zeitpunkt werde ich auf der Seite zapbox.space die Optionen beleuchten. Für den ersten Start zum Testen kann man aber die Demo-Version demo.lnbits.com verwenden. Dort legt man sich einen Account mit Wallet an und fügt unter Extensions die Erweiterung Bitcoin Switch hinzu. In der neuen Erweiterung kann man dann einen Bitcoin Switch anlegen. Von diesem benötigt man dann nur den „Device string“, um ihn nachfolgend in der Parametrierung der ZapBox zu hinterlegen.

Um die aktuelle Firmware auf die ZapBox zu schreiben, wurde der Web Installer entwickelt. Man schließt den USB-Port des Mikrocontrollers mit einem Datenkabel an einen PC oder Notebook an und klickt auf den Button „Flash“. Ein Popup-Fenster öffnet sich und man wird nach dem zu verwendenden Schnittstellenport gefragt. Meistens ist es der untere, wenn nur ein Gerät angeschlossen ist. Nach der Auswahl auf „Verbinden“ gehen und den Anweisungen folgen. „Erase device“ benötigt ihr nur, wenn ihr vorher auch die Parameterdaten löschen möchtet.

Nach dem Flashvorgang könnt ihr das Popup-Fenster schließen. Die Headless-Version bitte zusätzlich einmal von der Spannung nehmen und neu anschließen. Weiter unten auf der Seite ist der Bereich „Load config values“. Dort „Connect“ auswählen, um die ZapBox zu verbinden. Auch hier muss man wieder den COM-Port auswählen und kurz darauf zeigt ein Popup-Fenster den Hinweis, dass die Verbindung hergestellt wurde und die ZapBox im „Config Mode“ sein muss, damit Daten übertragen werden können. Diese Meldung ist nur ein Hinweis, sie kann mit OK bestätigt werden.

Wird die ZapBox zum ersten Mal beschrieben oder hat man sie mit „Erase Device“ geflasht, startet sie nach dem Booten automatisch im Config Mode. Das erkennt man am Display oder bei der Headless-Version am langsamen Blinken der READY-LED. Zusätzlich sind die vorher ausgegrauten Buttons Ready/Write Config, Restart und Disconnect jetzt sichtbar und damit bedienbar. Sollte das nicht der Fall sein, weil man schon eine Konfiguration geladen hat, muss die ZapBox noch in den Config Mode versetzt werden. Es gibt verschiedene Wege für die unterschiedlichen Geräte, aber der gängigste ist, den Next-, Boot- oder LED-Button für mehrere Sekunden lang gedrückt zu halten. Die erfolgreiche Umstellung wird euch auch im schwarzen Terminalfenster angezeigt.

Jetzt, wo die ZapBox verbunden und bereit ist, Daten zu empfangen, müssen nur drei Felder ausgefüllt werden:

– WiFi SSID – WLAN-Kennzeichnung
– WiFi password – WLAN-Passwort
– Device settings string – Der Device string der LNbits-Erweiterung

Jetzt einmal auf den Button „Write Config“ und danach auf „Restart“.

Die ZapBox ist jetzt fertig konfiguriert und startet den ersten Bootvorgang. Im Terminalfenster könnt ihr die technischen Schritte verfolgen. Nach der Initialisierung sollte das Display den QR-Code mit dem Produkt, das ihr in LNbits angelegt habt, anzeigen und die Headless-Version muss eine kontinuierlich leuchtende READY-LED anzeigen. Glückwunsch! 🤝🎉

4. Optionale Einstellungen und Funktionen

Für die ZapBox gibt es optionale Einstellungen, die entweder über den Web Installer oder über die bitcoinSwitch-Erweiterung eingestellt werden können.

4.1 Einstellbare Parameter über den Web Installer

Neben den genannten Pflichtfeldern WiFi SSID, WiFi password und Device settings string gibt es noch weitere optionale Einstellungen:

1. Display Farbe → Farbkombination nach Wunsch oder Umgebungsbedingung (hell/dunkel) einstellbar.
2. Display Orientierung → Alle vier Varianten, je nach Einbaulage einstellbar.
3. QR-Code-Format (bech32 und LUD17 (raw)) → Rein optionale Einstellung nach Vorliebe.
4. LED-Button (No/Yes) → Deaktiviert die Textanzeige für HELP und NEXT, da es den Button gibt.
5. Special Mode (Standard ON/OFF, Blink, Puls, Strobo, Custom) → Gibt vor, wie das Relais geschaltet wird.
6. Multi-Channel Mode (Single, Duo, Quattro) → Setzt das Verhalten der Ausgänge für die verschiedenen Versionen. Bei der Single-Version wird immer der QR-Code (oder BTC-Ticker) angezeigt. Bei der Version Duo oder Quattro wird eine „Select Product“-Seite vorgeschaltet.
7. Vending machine with light barrier (No/Yes) → Eine Spezialfunktion für einen Verkaufsautomaten, bei der das Signal einer Lichtschranke am Eingang GPIO 5 abgefragt wird und die Schaltaktion (ACTION TIME) sofort beendet.
8. BTC-Ticker Mode (OFF / ON-always / ON-when selecting) → Zeigt den BTC-Ticker mit Kurs, die Moscow-Time (Satoshis / Dollar) und die Blockzeit immer (always) vordergründig an. Man muss das Produkt dann mit dem Button vorwählen. Alternativ geht das auch per Auswahl (when selecting). Es wird dann immer die Auswahlseite oder ein Produkt angezeigt und man muss manuell die BTC-Ticker-Seite auswählen.
9. Currency (ISO Code) → Alle gängigen Währungseinheiten für die Anzeige am BTC-Ticker.
10. Threshold Mode (mit verschiedenen Parametern) → Eine Spezialform des bitcoinSwitch. Die ZapBox wird hier nicht über eine Instanz der Bitcoin Switch-Erweiterung gesteuert, sondern es wird das ausgewählte Wallet überwacht. Wird bei einem Zahlungseingang ein Schwellwert überschritten, wird der eingestellte Ausgang mit der eingestellten Zeit geschaltet. Zusätzlich kann man mit der Erweiterung „Pay Links“ eine Lightning-Adresse oder LNURL anlegen und hier hinterlegen. Sie wird dann als QR-Code angezeigt.
11. Screensaver / Deep sleep / Time until activation → Optionen, um das Display zu schonen (Abschaltung Hintergrundbeleuchtung → trotzdem voll einsatzbereit) oder um radikal Energie einzusparen, für z. B. einen Batteriebetrieb (→ Reboot erforderlich).

Zusätzlich zu den Einstellungen und Funktionen über den Web Installer kann man in der LNbits Bitcoin Switch Extension auch noch ein paar Einstellungen vornehmen.

4.2 Einstellbare Parameter in der Bitcoin Switch Erweiterung

Notwendige Einstellungen sind:

– Titel → Ein Titel, der auch dem Nutzer angezeigt wird
– Wallet → Die Auswahl des Wallets, falls man mehrere im Account hat
– Currency → Die Währung, die man wünscht
– Amount → Der Betrag mit einem Punkt als Dezimaltrennung, z. B. 0.01 Euro (1 Cent)
– duration (ms) → Schaltdauer in Millisekunden. 5000 ms → 5 Sekunden
– GPIO pin → Die Pins sind bei der ZapBox fest vorgegeben, da sie verdrahtet sind. Das sind 12, 13, 10 und 11
– Label → Hier wird eingetragen, was später auf dem Display angezeigt wird. Die Anzeige hat drei Zeilen. Die ersten zwei Leerzeichen trennen die Zeilen und der Rest wird in Zeile drei geschrieben. Z. B. „Coca Cola 1,20 Euro“

Optionale Einstellungen sind:

– Switch is (enable/disable) → Die Zahlungsfunktion der ZapBox aus der Ferne deaktivieren/aktivieren. Bei „disable“ bekommt der Nutzer nach dem Scannen des QR-Codes eine Meldung, dass der Switch deaktiviert ist. Es ist keine Zahlung möglich.
– Paylink is (stored/disposable) (LUD11) → Falls das Wallet es unterstützt, wird hier festgelegt, ob der Zahlungslink, der mit dem Scannen erzeugt wurde, wiederverwendbar ist oder nicht. Das ist eine Funktion, die auch vom Wallet unterstützt werden muss.
– [ ] Variable → Die Schaltdauer ist dann abhängig vom Zahlungsbetrag und steigt linear, hat aber Grenzwerte.
– [ ] Comment → Legt fest, ob der Nutzer auch einen Kommentar hinterlassen kann. Diese können in der Transaktionsliste von LNbits eingesehen werden.
– Password (optional) → Mit der Zahlung kann optional eine Passwortabfrage aktiviert werden. Der Server triggert die ZapBox nur dann, wenn sowohl der Zahlungsbetrag als auch das Passwort korrekt sind. Es handelt sich dabei nicht um eine „Zwei-Faktor-Authentifizierung“ (2FA), da die Lightning-Zahlung keine eigenständige Sicherheitsfunktion darstellt. Brute-Force-Angriffe werden jedoch deutlich erschwert. Die Zahlung selbst wird immer akzeptiert. Wird jedoch kein oder ein falsches Passwort mitgesendet, zeigt das Lightning-Wallet des Nutzers nur folgende Meldung an: „xx sats sent, but password was incorrect! :(„
Voraussetzung für die Übertragung des Passworts: Die Kommentarfunktion „[ ] Comment“ muss aktiviert sein.

5. Fehlermöglichkeiten und Lösungswege

5.1 Fehlermeldungen

Die ZapBox ist speziell darauf ausgelegt, dem Nutzer eine einfache und komfortable Bedienung zu ermöglichen. Fehler werden automatisch erkannt und über das Display angezeigt. Der QR-Code für das Produkt wird überlagert, und eine Zahlung ist nicht möglich. Das Display zeigt eine von vier priorisierten Fehlerkategorien an.

Priorität	Fehler Name	Erkennungsmethode	Beschreibung
1 (Höchste)	NO WIFI	WLAN-Verbindungsstatus	Keine WLAN-Verbindung -> WLAN-Daten korrekt? -> WLAN-Signal zu schwach?
2	NO INTERNET	HTTP-Überprüfung an Google	Internetverbindung unterbrochen -> Internetzugang?
3	NO SERVER	TCP-Port 443-Prüfung	LNbits-Server nicht erreichbar -> Serverhardware ausgefallen? -> Device string korrekt?
4 (Niedrigste)	NO WEBSOCKET	WebSocket-Verbindungsstatus	WebSocket-Protokoll-/Handshake-Fehler -> LNbits ausgefallen? -> Device string korrekt?

Werden die Fehler behoben, beispielsweise wenn die WLAN-Verbindung wiederhergestellt wird, quittieren sich die Meldungen nach einiger Zeit selbst, und die ZapBox geht wieder in den Normalbetrieb über.

Zusätzlich werden alle Meldungen gezählt. Tritt ein Fehler beispielsweise nur sporadisch auf, wird er dennoch automatisch „geloggt“. Die Häufigkeit kann anschließend auf der Report-Seite eingesehen werden. Der Seitenaufruf ist abhängig vom Modell:

- HELP-Taste: 2-mal schnell hintereinander drücken
- LED-Taste: 4-mal schnell hintereinander drücken

Die ZapBox Headless verfügt zwar über kein Display, jedoch über die gleiche Fehlerüberwachung. Tritt ein Fehler auf, beginnt die Ready-LED zu blinken. Der Blinkrhythmus ist abhängig vom jeweiligen Fehler.

Eine genaue Beschreibung findet sich auf der Seite Web Installer bzw. Web Installer Headless unter „Error Detection & Report“.

5.2 Verbindungsprobleme und Übertragungsprobleme

Die Ursachen von Verbindungs- und Übertragungsproblemen können vielfältig sein – von einem falschen Kabel über Treiberprobleme oder Versionskonflikte bis hin zu obskuren Speicherzuständen.

Eine Liste der gängigsten Fehlerursachen sowie entsprechende Behebungsmöglichkeiten findet ihr auf der Seite Web Installer bzw. Web Installer Headless unter „Troubleshoot – Connection Problems“.

5.3 Typische ZapBox-Headless-Fehler

Symptom: Die READY-LED blinkt dreimal kurz, dann für 5 Sekunden schnell und das Ganze wiederholt sich in der Schleife.
Ursache: Einige ESP32 trennen die Kommunikation nach einer Verbindung mit dem Web Installer nicht sauber und bleiben in der Boot-Schleife hängen.
Behebung: Die ZapBox einmal von der Spannung nehmen und neu anschließen.

6. Habt ihr weitere Fragen?

Der schnellste und einfachste Weg ist Telegram. Die Zap⚡Box hat eine eigene Telegram-Gruppe. Für den Link zur Gruppe müsst ihr ein Ticket 🎟️ lösen. Damit sollen Bots und sonstige unerwünschte Gäste ferngehalten werden. Wer ein echter Mensch ist und noch keine Satoshis hat, kann sich auf meiner Onboarding oder BoltFaucet Webseite 21 Satoshis holen. Dort findet ihr eine Lightning⚡Faucet Button. Voraussetzung dafür das beanspruchen ist lediglich ein Telegram-Account.

Eure Lightning-Wallet sollte sich beim Anklicken des Links automatisch öffnen. Alternativ könnt ihr den QR-Code rechts scannen. Nach der Zahlung von 10 Sats wird euch das Wallet einen Link anzeigen, den ihr anwählen könntet. Das ist bereits der Link zur ZapBox-Telegram-Gruppe.

7. Sonstiges

7.1 Flexible Montage & Modulares Design

Die ZapBox ist für eine einfache und flexible Integration konzipiert. Dank durchdachter Bohrlochoptionen lässt sie sich schnell und sicher in Gehäusen oder bestehenden Systemen montieren. Das modulare Frontblenden-System ermöglicht verschiedene Einbauvarianten:

90°-Planversion für eine gerade, bündige Montage
35°-abgeschrägte Version für ergonomische oder angewinkelte Einbausituationen
180°-Version ist angedacht, aktuell aber noch nicht in Planung

Für Automaten oder Gehäuseeinbauten ist die 90°-Frontblende auch als Einbauversion mit planer Oberfläche erhältlich.
Mit einer passenden Abdeckung (z. B. Plexiglas) und entsprechender Abdichtung kann die ZapBox zusätzlich effektiv vor Staub, Schmutz und Spritzwasser geschützt werden.

7.2 Bedienungsoptionen der ZapBox

Diese Versionen Compact & Headless kommen ohne LED-Button aus. Die Compact-Version nutzt die integrierten Taster des Mikrocontroller-Boards und eignet sich ideal für kompakte oder integrierte Anwendungen. Duo & Quattro sind standardmäßig mit einem hochwertigen LED-Button ausgestattet. Alternativ können sie mit einer Frontblende betrieben werden, die die internen Buttons des ESP32 verwendet – oder komplett ohne physische Taster.

7.3 Touch-Variante – Komplett ohne physische Buttons

Mit der T-Display-S3-Touch-Version ist die ZapBox auch als vollständig tasterlose Lösung verfügbar. Die Software ist fertig integriert und wird über denselben Web-Installer übertragen. Das System erkennt automatisch, welche Hardware (mit oder ohne Touch) verwendet wird, und aktiviert die entsprechenden Funktionen selbstständig – ganz ohne manuelle Konfiguration. Aktuell wird noch an einem optimalen Gehäuse für die Touch-Version gearbeitet, da die Bauform des T-Display-S3-Touch besondere Anforderungen an das Design stellt.

---

Created with ❤️ Since 936899 / 937259

---