The bitcoinSwitch for Everyone

I described the bitcoinSwitch in detail in an article. It is well suited for switching something in the physical world with Bitcoin⚡Lightning payments. However, handling it requires a certain technical understanding, especially when it comes to the hardware, wiring and assembly. The software installation and configuration with the common tool also repeatedly posed challenges for many people, and since the classic bitcoinSwitch has no display, feedback and the ability to analyze errors were very poor. So I decided to do something about it, and that is how the ZapBox came about.

1. What is the ZapBox?

The ZapBox is an electronic switch in a box, designed as a complete concept for everyone. It is easy to use, robust, gives good feedback to the user and offers optional functions that go far beyond those of the classic bitcoinSwitch. There is also not just “the one” ZapBox, but a whole family that is to be continuously expanded. Different use cases require different systems. Users should be able to concentrate on implementing their idea.

The ZapBox includes:

– An ESP32 microcontroller (with or without display)
– Relays for switching
– USB ports or terminals for easy connection
– Complete wiring (E-layout)
– Complete enclosure (3D printed)
– A website with a “Web Installer” for flashing and configuring the ZapBox
– LED buttons for the versions with product selection
– Two status LEDs for visual feedback on the version without display (Headless)
– An LNbits account in the backend for payment processing

2. The Current ZapBox Family

The ZapBox family now consists of many members that meet individual requirements. Basically, they can be divided into three groups: ZapBox with T-Display-S3, Headless and Touch 3.5.

Picture: The family

2.1 ZapBox Compact

As the name suggests, this is the simple, compact version of the ZapBox. One USB input for the power supply and one USB output that is switched. This is the entry-level version for simple switching applications. All important status information and the QR code are shown on the display. It is operated using the onboard buttons of the microcontroller. The Compact version has a 3-position slide switch for “AUTO / OFF / ON” and a 2-position slide switch to invert the output signal if you want to switch “inverted”.

2.2 ZapBox Duo

The version for power with two channels. If I want to switch more than one USB output, this is the right solution. A power relay (up to 30 A) with extra large terminals led to the outside, and a second relay that switches a dual USB output (A and C). The relays can be controlled separately or both together. The power relay switches the motor, the fanfare, the pump or whatever. The second output is used to visualize the action, trigger a counter or whatever. The Duo also has an LED button for convenient operation and product selection. If you do not need it and prefer something simpler, you can also choose the front panel without the LED button. The slide switches are identical to those of the Compact version.

2.3 ZapBox Quattro

If you want to switch several channels, as a kind of product selection, you can use the Quattro. Here, four relays are led to the outside as changeover contacts. Products are selected via LED buttons. In addition to the QR code, the display shows three lines in which, for example, the product names and the price can be shown. This way the Quattro can be used, for example, for vending machines or to simply switch the “product quantity” by time. The Quattro version has no slide switches.

2.4 ZapBox Headless

The ZapBox Headless is a version that gets by without a display but still combines the advantages of a ZapBox. A standard ESP32 is used here and everything is housed in a compact enclosure. Two LEDs provide feedback. One shows the READY operating state and blinks at startup during synchronization. In addition, the LED uses special blink patterns to indicate the “Configuration” mode or the respective error status. The second LED shows switching as ACTION, to help detect problems with the hardware. The LEDs thus offer a high degree of added comfort compared to the classic bitcoinSwitch. The READY LED signal is also shown on the ESP32 onboard LED (green). The Headless version has the 3-position slide switch for “AUTO / OFF / ON”. If you want to “invert” the output signal, you can do this with a small rewiring at the relay inside the enclosure.

2.5 ZapBox ZapOMat, Headless Servo, Simple, Headless Simple, Touch 3.5 ONE / FOUR / SIX+, ..

Description to follow..

3. Setting Up a ZapBox

To set up a ZapBox, you either have to get hold of one or build it yourself. On the website zapbox.space there is a current overview of the product family with pictures, and further documentation is to follow. All technical details as well as circuit diagrams and the 3D print files can be found on GitHub. The project is Free and Open Source; support in the form of feedback, GitHub contributions or donations is welcome.

In addition to the hardware, you need an LNbits account and the “Bitcoin Switch” extension. LNbits is a wallet and account system that can be extended with a wide variety of Bitcoin tools. You can host it yourself or share a community’s instance. At a later point I will look at the options on the zapbox.space site. For a first test run, however, you can use the demo version demo.lnbits.com. There you create an account with a wallet and add the Bitcoin Switch extension under Extensions. In the new extension you can then create a Bitcoin Switch. From it you only need the “Device string”, which you then enter in the ZapBox configuration.

The Web Installer was developed to write the current firmware to the ZapBox. Connect the USB port of the microcontroller to a PC or notebook with a data cable and click the “Flash” button. A popup window opens and you are asked which interface port to use. Usually it is the lower one if only one device is connected. After selecting it, click “Connect” and follow the instructions. You only need “Erase device” if you also want to delete the configuration data beforehand.

After flashing you can close the popup window. For the Headless version, please also disconnect it from power once and reconnect it. Further down the page is the “Load config values” section. Select “Connect” there to connect the ZapBox. Here too you have to select the COM port, and shortly afterwards a popup window shows a note that the connection has been established and that the ZapBox must be in “Config Mode” so that data can be transferred. This message is only a hint and can be confirmed with OK.

If the ZapBox is written to for the first time or has been flashed with “Erase Device”, it starts automatically in Config Mode after booting. You can recognize this on the display or, on the Headless version, by the slow blinking of the READY LED. In addition, the previously greyed-out buttons Ready/Write Config, Restart and Disconnect are now visible and can be used. If that is not the case because a configuration has already been loaded, the ZapBox still has to be put into Config Mode. There are different ways for the different devices, but the most common one is to hold the Next, Boot or LED button for several seconds. The successful switch is also shown in the black terminal window.

Now that the ZapBox is connected and ready to receive data, only three fields need to be filled in:

– WiFi SSID – Name of the WiFi network
– WiFi password – WiFi password
– Device settings string – The device string from the LNbits extension

Now click the “Write Config” button once and then “Restart”.

The ZapBox is now fully configured and starts its first boot. In the terminal window you can follow the technical steps. After initialization, the display should show the QR code with the product you created in LNbits, and the Headless version must show a continuously lit READY LED. Congratulations! 🤝🎉

4. Optional Settings and Functions

There are optional settings for the ZapBox that can be set either via the Web Installer or via the Bitcoin Switch extension.

4.1 Parameters Adjustable via the Web Installer

In addition to the mandatory fields mentioned above, WiFi SSID, WiFi password and Device settings string, there are further optional settings:

1. Display color → Color combination adjustable as desired or according to ambient conditions (light/dark).
2. Display orientation → All four variants, adjustable depending on the mounting position.
3. QR code format (bech32 and LUD17 (raw)) → Purely optional setting according to preference.
4. LED button (No/Yes) → Deactivates the text display for HELP and NEXT, since the button exists.
5. Special Mode (Standard ON/OFF, Blink, Pulse, Strobe, Custom) → Defines how the relay is switched.
6. Multi-Channel Mode (Single, Duo, Quattro) → Sets the behavior of the outputs for the different versions. In the Single version, the QR code (or BTC ticker) is always shown. In the Duo or Quattro version, a “Select Product” page is shown first.
7. Vending machine with light barrier (No/Yes) → A special function for a vending machine, in which the signal of a light barrier at input GPIO 5 is polled and the switching action (ACTION TIME) is ended immediately.
8. Special function Channel 4 (Off / Ambient lightning switch) → An option for the 4-channel Quattro ZapBox. The fourth channel can be used to control ambient lighting. Channel 4 – or the light connected to it – is switched on automatically as soon as the display is active. If the display is deactivated by the screensaver function (see item 12), the ambient lighting also switches off.
9. BTC Ticker Mode (OFF / ON-always / ON-when selecting) → Shows the BTC ticker with price, Moscow time (satoshis / dollar) and block time in the foreground at all times (always). You then have to preselect the product with the button. Alternatively, this also works by selection (when selecting). The selection page or a product is then always shown, and you have to select the BTC ticker page manually.
10. Currency (ISO code) → All common currency units for the display on the BTC ticker.
11. Threshold Mode (with various parameters) → A special form of the bitcoinSwitch. Here the ZapBox is not controlled via an instance of the Bitcoin Switch extension, but the selected wallet is monitored. If a threshold is exceeded on an incoming payment, the configured output is switched for the configured time. In addition, you can create a Lightning address or LNURL with the “Pay Links” extension and store it here. It is then shown as a QR code.
12. Screensaver / Deep sleep / Time until activation → Options to protect the display (backlight switched off → still fully ready for use) or to save energy radically, e.g. for battery operation (→ reboot required).
13. NFC Bolt Card support → The ZapBox can accept NFC Bolt Card payments if the corresponding NFC module is connected and the extension ZapBox (zapbox_extension) has been installed and activated in LNbits. This extension is a fork of the Bitcoin Switch extension and additionally supports NFC cards of type NTAG424 DNA that are set up as a Bolt Card. The user interface and functions of the ZapBox extension correspond completely to those of the Bitcoin Switch extension. The ZapBox automatically detects which extension it has to connect to. As feedback for the Lightning payment status “Pending”, the version with display shows a Pending NFC screen. On the Headless version, the Ready LED blinks in rapid succession. NTAG 213/215/216 cards with the simple LNbits withdraw function (Withdraw) are also supported.

4.2 Parameters Adjustable in the Bitcoin Switch / ZapBox Extension

In addition to the settings and functions available via the Web Installer, a few more settings can be made in the LNbits Bitcoin Switch or ZapBox extension.

Required settings are:

– Title → A title that is also shown to the user
– Wallet → The selection of the wallet, if you have several in the account
– Currency → The currency you want
– Amount → The amount with a period as decimal separator, e.g. 0.01 euro (1 cent)
– duration (ms) → Switching duration in milliseconds. 5000 ms → 5 seconds
– GPIO pin → The pins are fixed on the ZapBox because they are wired. These are 12, 13, 10 and 11
– Label → Enter here what will later be shown on the display. The display has three lines. The first two spaces separate the lines and the rest is written in line three. E.g. “Coca Cola 1.20 Euro”

Optional settings are:

– Switch is (enable/disable) → Disable/enable the payment function of the ZapBox remotely. With “disable”, the user receives a message after scanning the QR code that the switch is deactivated. No payment is possible.
– Paylink is (stored/disposable) (LUD11) → If the wallet supports it, this defines whether the payment link generated by the scan is reusable or not. This is a function that must also be supported by the wallet.
– [ ] Variable → The switching duration then depends on the payment amount and increases linearly, but has limits.
– [ ] Comment → Defines whether the user can also leave a comment. These can be viewed in the transaction list of LNbits.
– Password (optional) → A password prompt can optionally be activated with the payment. The server only triggers the ZapBox if both the payment amount and the password are correct. This is not “two-factor authentication” (2FA), since the Lightning payment is not a standalone security feature. However, brute-force attacks are made considerably more difficult. The payment itself is always accepted. But if no password or a wrong password is sent along, the user’s Lightning wallet only shows the following message: “xx sats sent, but password was incorrect! :(“
Requirement for transmitting the password: the comment function “[ ] Comment” must be activated.

5. Possible Errors and Solutions

5.1 Error Messages

The ZapBox is specifically designed to give the user simple and convenient operation. Errors are detected automatically and shown on the display. The QR code for the product is overlaid, and a payment is not possible. The display shows one of four prioritized error categories.

Priority	Error name	Detection method	Description
1 (Highest)	NO WIFI	WiFi connection status	No WiFi connection -> WiFi data correct? -> WiFi signal too weak?
2	NO INTERNET	HTTP check against Google	Internet connection interrupted -> Internet access?
3	NO SERVER	TCP port 443 check	LNbits server not reachable -> Server hardware down? -> Device string correct?
4 (Lowest)	NO WEBSOCKET	WebSocket connection status	WebSocket protocol/handshake error -> LNbits down? -> Device string correct?

Once the errors are resolved, for example when the WiFi connection is restored, the messages clear themselves after a while and the ZapBox returns to normal operation.

In addition, all messages are counted. If an error occurs only sporadically, for example, it is still “logged” automatically. The frequency can then be viewed on the Report page. How to open the page depends on the model:

- HELP button: press twice in quick succession
- LED button: press four times in quick succession

The ZapBox Headless has no display, but it has the same error monitoring. If an error occurs, the Ready LED starts to blink. The blink rhythm depends on the respective error.

A detailed description can be found on the page Web Installer or Web Installer Headless under “Error Detection & Report”.

5.2 Connection and Transfer Problems

The causes of connection and transfer problems can be manifold – from a wrong cable to driver problems or version conflicts to obscure memory states.

A list of the most common causes of errors and corresponding remedies can be found on the page Web Installer or Web Installer Headless under “Troubleshoot – Connection Problems”.

5.3 Typical ZapBox Headless Errors

Symptom: The READY LED blinks briefly three times, then rapidly for 5 seconds, and the whole sequence repeats in a loop.
Cause: Some ESP32s do not cleanly end communication after a connection with the Web Installer and get stuck in the boot loop.
Fix: Disconnect the ZapBox from power once and reconnect it.

6. Do You Have More Questions?

The quickest and easiest way is Telegram. The Zap⚡Box has its own Telegram group. To get the link to the group, you have to redeem a ticket 🎟️. This is meant to keep out bots and other unwanted guests. If you are a real human and do not have any satoshis yet, you can get 21 satoshis on my Onboarding or BoltFaucet website. There you will find a Lightning⚡Faucet button. The only requirement for claiming is a Telegram account.

Your Lightning wallet should open automatically when you click the link. Alternatively, you can scan the QR code on the right. After paying 10 sats, the wallet will show you a link that you can tap. That is already the link to the ZapBox Telegram group.

7. Miscellaneous

7.1 Flexible Mounting & Modular Design

The ZapBox is designed for simple and flexible integration. Thanks to well-thought-out drill hole options, it can be mounted quickly and securely in enclosures or existing systems. The modular front panel system enables different installation variants:

90° flat version for straight, flush mounting
35° angled version for ergonomic or angled installation situations
A 180° version is envisaged, but is not currently planned

For vending machines or enclosure installations, the 90° front panel is also available as a built-in version with a flat surface.
With a suitable cover (e.g. acrylic glass) and appropriate sealing, the ZapBox can also be effectively protected against dust, dirt and splashing water.

7.2 Operating Options of the ZapBox

The versions Compact & Headless get by without an LED button. The Compact version uses the integrated buttons of the microcontroller board and is ideal for compact or integrated applications. Duo & Quattro come with a high-quality LED button as standard. Alternatively, they can be operated with a front panel that uses the internal buttons of the ESP32 – or with no physical buttons at all.

7.3 Touch Variant – Completely Without Physical Buttons

With the T-Display-S3 Touch version, the ZapBox is also available as a completely button-free solution. The software is fully integrated and is transferred via the same Web Installer. The system automatically detects which hardware (with or without touch) is used and activates the corresponding functions on its own – with no manual configuration at all. Work is still under way on an optimal enclosure for the Touch version, since the form factor of the T-Display-S3 Touch places special demands on the design.

---

Created with ❤️ Since 936899 / 973969

---