The bitcoinSwitch for Everyone

I have described the bitcoinSwitch in detail in a previous article. It is designed to switch something in the physical world using Bitcoin⚡Lightning payments. However, using it requires a certain level of technical understanding, especially regarding the hardware, wiring, and assembly. The software installation and configuration with common tools also regularly posed challenges, and since the classic bitcoinSwitch has no display, the feedback and error analysis capabilities were very limited. So I decided to do something about it, and that’s how the ZapBox was born.

1. What is the ZapBox?

The ZapBox is an electronic switch in a box — a complete concept for everyone. Easy to use, stable, with good user feedback and optional features that go far beyond those of the classic bitcoinSwitch. And there isn’t just “one” ZapBox; it’s an entire family that is intended to grow continuously. Different use cases require different systems. The user should be able to focus on implementing their idea.

The ZapBox includes:

– An ESP32 microcontroller (with or without display)
– Relay for switching
– USB ports or terminals for easy connection
– Complete wiring (electrical layout)
– Complete housing (3D-printed)
– A website with a “Web Installer” for flashing and configuring the ZapBox
– LED button for versions with product selection
– For the display-less version (Headless): two status LEDs for visual feedback
– An LNbits account in the backend for payment processing

2. The Current ZapBox Family

The ZapBox family currently consists of four members, each designed to meet individual requirements.

2.1 ZapBox Compact

As the name suggests, this is the simple, compact version of the ZapBox. One USB input for 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 displayed on the screen. Operation is handled via the onboard buttons of the microcontroller. The Compact version features 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 in “inverted” mode.

2.2 ZapBox Duo

The high-power version with two channels. If you want to switch more than one USB output, this is the right solution. A power relay (up to 30 A) with extra-large terminals brought 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 drive, the buzzer, the pump, or whatever you need. The second output is used to visualize the action, trigger a counter, or anything else. The Duo also features an LED button for convenient operation and product selection. If you don’t need that and prefer a cleaner look, the front panel can also be chosen without an LED button. The slide switches are identical to those of the Compact version.

2.3 ZapBox Quattro

If you want to switch multiple channels as a kind of product selection, you can use the Quattro. Here, four relays with changeover contacts are brought to the outside. Product selection is done via LED buttons. The display shows the QR code plus three lines where, for example, product names and prices can be displayed. The Quattro can therefore be used for vending machines or simply to switch the “product quantity” based on time. The Quattro version has no slide switches.

2.4 ZapBox Headless

The ZapBox Headless is a version that works without a display while still combining the advantages of a ZapBox. A standard ESP32 is used and everything is housed in a compact enclosure. Two LEDs provide feedback. One indicates the READY operating state and blinks during synchronization at startup. Additionally, the LED indicates “Configuration” mode or various error states through special blink patterns. The second LED shows the switching action as ACTION to help identify hardware problems. The LEDs therefore offer a high degree of improvement in usability compared to the classic bitcoinSwitch. The READY LED signal is also mirrored on the ESP32’s 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 perform a small rewiring of the relay inside the housing.

3. Setting Up a ZapBox

To set up a ZapBox, you either need to obtain one or build it yourself. The website zapbox.space provides a current overview of the product family with images; further documentation will follow. All technical details, schematics, and 3D print files can be found on GitHub. The project is free and open source — feedback, GitHub contributions, and donations are welcome.

In addition to the hardware, you will 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 use a community-run instance. At a later point, I will cover these options on zapbox.space. For an initial test, you can use the demo version at 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. You will only need the “Device string” from it to enter it in the ZapBox configuration below.

To flash the current firmware onto the ZapBox, the Web Installer was developed. Connect the USB port of the microcontroller to a PC or laptop using a data cable and click the “Flash” button. A popup window will open, asking you to select the interface port to use. Usually it’s the lower one if only one device is connected. After selecting it, click “Connect” and follow the instructions. “Erase device” is only needed 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 to the ZapBox. Again, you need to select the COM port, and shortly after, a popup window will indicate that the connection has been established and that the ZapBox must be in “Config Mode” for data to be transferred. This message is only a notice and can be confirmed with OK.

If the ZapBox is being flashed for the first time or has been flashed with “Erase Device”, it will automatically start in Config Mode after booting. You can recognize this by the display or, for the Headless version, by the slow blinking of the READY LED. Additionally, the previously grayed-out buttons Ready/Write Config, Restart, and Disconnect are now visible and usable. If that’s not the case because a configuration has already been loaded, the ZapBox must still be put into Config Mode. There are various ways for different devices, but the most common is to hold down the Next, Boot, or LED button for several seconds. The successful switch will also be 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 – your Wi-Fi network name
– WiFi password – your Wi-Fi password
– Device settings string – the device string from the LNbits extension

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

The ZapBox is now fully configured and will start its first boot process. You can follow the technical steps in the terminal window. 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 Features

The ZapBox has optional settings that can be configured either via the Web Installer or via the Bitcoin Switch extension.

4.1 Configurable Parameters via the Web Installer

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

1. Display Color → Color combination can be set as desired or based on ambient conditions (light/dark).
2. Display Orientation → All four orientations adjustable depending on mounting position.
3. QR Code Format (bech32 and LUD17 (raw)) → Purely optional setting based on preference.
4. LED Button (No/Yes) → Disables the HELP and NEXT text labels, since the button is present.
5. Special Mode (Standard ON/OFF, Blink, Pulse, Strobo, 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 Single mode, the QR code (or BTC ticker) is always shown. In Duo or Quattro mode, a “Select Product” screen is shown first.
7. Vending machine with light barrier (No/Yes) → A special feature for vending machines that reads a light barrier signal on GPIO pin 5 and immediately ends the switching action (ACTION TIME).
8. BTC Ticker Mode (OFF / ON-always / ON-when selecting) → Displays the BTC ticker with price, Moscow Time (satoshis/dollar), and block time permanently in the foreground (always). The product must then be pre-selected using the button. Alternatively, use the (when selecting) option: the selection page or a product is always shown by default and you manually switch to the BTC ticker screen.
9. Currency (ISO code) → All common currency units for display on the BTC ticker.
10. Threshold Mode (with various parameters) → A special form of the bitcoinSwitch. Instead of being controlled via a Bitcoin Switch extension instance, the selected wallet is monitored. If an incoming payment exceeds a threshold value, the configured output is switched for the configured duration. Additionally, you can create a Lightning address or LNURL using the “Pay Links” extension and store it here. It will then be displayed as a QR code.
11. Screensaver / Deep sleep / Time until activation → Options to protect the display (backlight off → still fully operational) or to radically save energy, e.g. for battery-powered operation (→ reboot required).

In addition to the settings and features available via the Web Installer, a few more settings can also be configured in the LNbits Bitcoin Switch Extension.

4.2 Configurable Parameters in the Bitcoin Switch Extension

Required settings are:

– Title → A title that is also displayed to the user
– Wallet → Select the wallet if you have multiple in your account
– Currency → The currency you want
– Amount → The amount using 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 in the ZapBox since they are hardwired. These are 12, 13, 10, and 11
– Label → Enter what will be displayed on the screen. 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) → Remotely disable/enable the payment function of the ZapBox. When set to “disable”, the user receives a message after scanning the QR code stating that the switch is disabled. No payment is possible.
– Paylink is (stored/disposable) (LUD11) → If supported by the wallet, this defines whether the payment link generated upon scanning is reusable or not. This is a feature that must also be supported by the wallet.
– [ ] Variable → The switching duration then depends on the payment amount and increases linearly, but has limit values.
– [ ] Comment → Defines whether the user can also leave a comment. These can be viewed in the transaction list in LNbits.
– Password (optional) → An optional password check can be activated alongside the payment. The server only triggers the ZapBox if both the payment amount and the password are correct. This is not a “two-factor authentication” (2FA), as the Lightning payment itself is not a standalone security feature. However, brute-force attacks are significantly more difficult. The payment itself is always accepted. If no password or an incorrect password is sent, the user’s Lightning wallet will only display the following message: “xx sats sent, but password was incorrect! :(“
Prerequisite for transmitting the password: The comment function “[ ] Comment” must be enabled.

5. Possible Errors and Solutions

5.1 Error Messages

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

Priority	Error Name	Detection Method	Description
1 (Highest)	NO WIFI	Wi-Fi connection status	No Wi-Fi connection -> Wi-Fi credentials correct? -> Wi-Fi signal too weak?
2	NO INTERNET	HTTP check to Google	Internet connection interrupted -> Internet access available?
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 errors are resolved — for example when the Wi-Fi connection is restored — the messages clear themselves after some time and the ZapBox returns to normal operation.

Additionally, all messages are counted. If an error only occurs sporadically, it is still automatically logged. The frequency can then be viewed on the report page. How to access the page depends on the model:

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

The ZapBox Headless has no display, but it features the same error monitoring. If an error occurs, the Ready LED starts blinking. The blink pattern depends on the specific error.

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

5.2 Connection and Transmission Problems

The causes of connection and transmission problems can be varied — from a wrong cable to driver issues, version conflicts, or obscure memory states.

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

5.3 Typical ZapBox Headless Errors

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

6. Do You Have Further Questions?

The fastest and easiest way to get help is via Telegram. The Zap⚡Box has its own Telegram group. To get the link to the group, you need to purchase a Ticket 🎟️. This is meant to keep bots and other unwanted visitors out. If you are a real person and don’t have any satoshis yet, you can grab 21 satoshis on my Onboarding or BoltFaucet page. There you will find a Lightning⚡Faucet button. All you need to claim it 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, your wallet will display a link that you can follow — that link leads directly to the ZapBox Telegram group.

7. Miscellaneous

7.1 Flexible Mounting & Modular Design

The ZapBox is designed for easy and flexible integration. Thanks to well-thought-out mounting hole options, it can be quickly and securely installed in enclosures or existing systems. The modular front panel system enables various mounting configurations:

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

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

7.2 Operating Options of the ZapBox

The Compact & Headless versions come 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 standard with a high-quality LED button. Alternatively, they can be operated with a front panel that uses the ESP32’s internal buttons — or completely without physical buttons.

7.3 Touch Variant – Completely Without Physical Buttons

With the T-Display-S3 Touch version, the ZapBox is also available as a fully buttonless solution. The software is fully integrated and is flashed via the same Web Installer. The system automatically detects which hardware is being used (with or without touch) and activates the corresponding functions independently — with no manual configuration required. Work is currently still ongoing on an optimal housing for the Touch version, as the form factor of the T-Display-S3-Touch places special demands on the design.

---

Created with ❤️ Since 936899 / 937263

---