bitcoinSwitch – The Bridge Between Two Worlds

“0” and “1” – these are the basic states of our digital world. Simple switching operations that can logically control or regulate something – and thus influence our real world. All our progress and comfort are based on these principles. But while technology is advancing rapidly, traditional payment systems are struggling to build a bridge for money between these two worlds. Cash involves immense verification and security efforts. For “digital” fiat money, swarms of intermediaries and strict regulations are involved – even for tiny amounts. Micropayments or infrequent payments often aren’t worth it because setup fees, base fees, or ongoing costs are too high. We hinder our development and must give part of our income to third parties – simply because the system is inefficient. Our traditional money hasn’t yet arrived in the 21st century. But that’s changing: There is a new form of money – BitcoinLightning.

1. bitcoinSwitch, briefly explained

The bitcoinSwitch is – simply put – nothing more than a microcontroller (a semiconductor chip with processor and peripheral functions), software, and a relay to switch power and voltage. The microcontroller is connected to the internet via WiFi and can check the balance of a Lightningwallet. If a payment is received, the microcontroller triggers the relay – which can then initiate any action: powering an outlet, driving a vending machine motor, unlocking something, heating, pumping, and more. The only limit is your imagination. “0” and “1” are not just the foundation of the digital world and Bitcoin, but also of automation.

2. The Setup

Small, neat, simple! A bit of electronics, some software, the functionality of Lightning and you’re ready to switch something.

3. The Components

You don’t need much, and it’s surprisingly affordable. The main parts like the relay and microcontroller cost less than 10 euros, and the software is free. The hardware components include an ESP32 microcontroller, a relay (high-level trigger), a USB data cable, jumper cables, and of course the power supply, e.g., a USB power bank or laptop. Depending on the ESP32 model you have, pin layout, button function, and the number of LEDs may vary slightly. In principle, all WiFi-enabled ESP32 boards are similar and should work.

To upload the program to the microcontroller, all you need now is a web browser. The actual bitcoinSwitch program is free and open source software (FOSS) on GitHub. Flashing the ESP32 with the bitcoinSwitch program is done via a website called the Web Installer. You can also configure the bitcoinSwitch there. It needs an internet connection and a wallet. The internet connection can be your home network or a hotspot.

For the wallet, you need a specific Lightning wallet called LNbits. LNbits is a wallet and account system with many extensions around the LNURL (Lightning URL) protocol. A good starting point is the free demo server wallet demo.lnbits.com. It’s free but without any guarantee or liability for functionality or funds. It’s completely sufficient for testing with small amounts.

4. Examples for the bitcoinSwitch

Here I briefly present three projects. You can find more information in the appendix.

4.1 Candy Machine

The Candy Machine is a candy dispenser. A small motor drives an auger that dispenses the candy. The original touch sensor under the dispenser was replaced by the bitcoinSwitch. If someone pays the Lightning invoice via the displayed QR code, a few candies are automatically dispensed.

4.2 Low Budget Beer Tap – For Plebs!

There are already some very good beer taps that allow payment via Lightning. However, they were all too complex and expensive for me – I wanted something simple and affordable, just right for any pleb. Then I came across the 5-liter fresh keg from Krombacher. They are a bit more expensive than conventional 5-liter kegs but include an integrated CO₂ cartridge. This keeps the beer fresh for up to 30 days – and, most importantly, ensures constant pressure. The tap system works with a lever that operates an internal valve. For this bitcoinSwitch project, the lever is automatically moved by a 12V linear actuator. When the bitcoinSwitch detects a payment, it switches two relays that reverse the polarity of the voltage for the actuator. For a set duration, the actuator moves in one direction or the other. The actuator has integrated limit switches. Additional manual switches can optionally be connected.

4.3 Universal bitcoinSwitch

I thought: why not build a universal switch that can handle 230V? The Universal bitcoinSwitch is a 230V extension cable with an integrated switch. This allows a power outlet to be activated, enabling various devices (up to a certain power limit!) to be powered for a set period of time. For example: a charging station, a pump, a heater, or the motor of a kiddie ride. This is definitely the mobile and universal version of the bitcoinSwitch.

Warning: 230V is a dangerous voltage!!! Only attempt this if you have sufficient knowledge and experience.

5. Setting Up the bitcoinSwitch

Setting up the bitcoinSwitch has now become very easy. Everything can be installed and configured via a web browser – no additional software is required anymore. The necessary website is called the Web Installer and works with the desktop browsers Chrome or Edge.

The only hurdle at the beginning is setting up a suitable driver for the connection between the computer and the ESP32 microcontroller. On some operating systems, the correct driver is recognized and installed automatically when the ESP32 is connected. However, this doesn’t always work – sometimes a driver update is needed to ensure proper functionality.

If you encounter any issues, check the appendix under chapter 7.6 – you’ll find help there.

Note: Documentation for versions older than LNbits v1.0 can be found in the archive.

5.1 Preparation: The LNbits Wallet

The bitcoinSwitch communicates with an LNbits Wallet. Here I’ll show you how to create a wallet and generate the necessary interface data. This allows the bitcoinSwitch to connect to the LNbits Wallet. As soon as a payment is received by the LNbits server, the bitcoinSwitch gets the information via internet / WiFi and then switches a relay to perform the desired action. You can get a free account for testing at demo.lnbits.com.

Note: If the bitcoinSwitch extension is not selectable in your LNbits instance, it may need to be installed by the administrator.

5.2 Flashing and Configuring the bitcoinSwitch

The ESP32 microcontroller is flashed, or programmed, via a website. Connect the ESP32 to your computer using a USB cable. Open the Web Installer at bitcoinswitch.lnbits.com and follow the instructions. Note: After flashing, or if you run into any issues, you may need to reinitialize the connection between your computer and the microcontroller. To do this, click “Reload Page” in the top left or press F5.

Flashing the Program

Configuring the bitcoinSwitch

Note on the Variable and Comment selection fields

If you select the Variable field, the switch time is adjusted proportionally to the payment amount. For example, if 10 satoshis correspond to 1000 ms of activation, then 30 satoshis will trigger the relay for 3000 ms – and conversely, 5 satoshis will only trigger it for 500 ms. If you select the Comment field, the payer can add a message or comment to the payment.

Note 893815: Currently, the functionality seems to be active even without selecting these fields. This is probably a bug.

Note on THRESHOLD OPTION

The THRESHOLD OPTION parameter allows you to override the standard behavior of bitcoinSwitch. If these fields are filled out, the SWITCH OPTION will be ignored, and only the parameters defined in THRESHOLD OPTION will be used. Instead of a fixed amount, a threshold value is set. The invoice amount shown to the payer is 1 satoshi – but they can enter any amount. If the entered amount exceeds the defined threshold (amount to hit to trigger), the specified pin (pin to trigger) will be activated for the defined duration (time to turn off for).

Unfortunately, this feature is not properly implemented in the current release version v0.1.1. However, I’ve submitted a pull request (#49) that restores this functionality. Feel free to give it a little push.

5.3 Testing and Troubleshooting the bitcoinSwitch

You can test the functionality of the bitcoinSwitch using the Web Installer. You’ll be able to see basic status feedback from the device. To do this, reconnect the ESP32 to your computer via USB, connect to the communication interface, and restart the ESP32 using Reset Device. Various status messages will appear, and once the ESP32 is properly connected to the LNbits server, it will show: [WSc] Connected to url: ....

Testing the bitcoinSwitch

Troubleshooting Tips

6. Summary

“Fascinating,” as Spock would say. In 2009, Bitcoin became the first digital asset to have real value. It’s digital, yet cannot be copied. It works peer-to-peer, without intermediaries, is permissionless, and resistant to censorship. Then in 2018 came Lightning , allowing us to transfer this asset quickly and inexpensively. If people accept an asset as a medium of exchange, it can become money. And with this new money, we can now even switch things. How awesome is that? We’ve built a bridge – paying from the digital world for something that brings us utility in the real world. If something creates value or solves a problem, people will be willing to pay for it. We now have both the money and the technology. We can build everything ourselves – simply, affordably, and even completely independently – thanks to BitcoinLightning.

I hope this little guide helped you get a basic understanding of the bitcoinSwitch. It can be a bit complex – especially for beginners – but maybe you’ve managed to replicate one of the projects or even created something entirely new. That’s my goal, after all: we need more “makers” building on this amazing Lightning technology.

If you have any questions or feedback, feel free to join the Telegram groups:

• MakerBits – All about the tech: https://t.me/makerbits
• LNbits – Everything about LNbits: https://t.me/lnbits
• bitcoinSwitch DACH – It is not public to keep spambots away. But you could buy a ticket for 10 Satoshi and you will be forwarded directly to the group. Note: The group is predominantly German-speaking.

If you want to contact me directly, you can reach me via Telegram at https://t.me/AxelHamburch or on Twitter via direct message: https://twitter.com/axelhamburch. All feedback is welcome – constructive criticism especially so.

Lastly, I want to give a huge thanks to the incredible Ben Arc, without whom none of this would be possible – through his work on LNbits and bitcoinSwitch. Hats off to this man! A real Gyro Gearloose of the 21st century.

If you liked this article or tutorial, or if it provided you with value, I’d appreciate it if you’d consider sending a few Satoshis via Bitcoin Lightning as a thank you. You can find options to do so on my contact page.

Stay curious, and see you in the next tutorial!

Axel

7. Appendix

If you want to get started right away, you can buy the Starter Kit from the LNbits Shop. Otherwise, you’ll find many more sources and additional information below.

7.1 Additional Resources

• Short Twitter video with info: link
• Video tutorial for the bitcoinSwitch: link
• GitHub page for bitcoinSwitch: link
• GitHub page for LNbits: link
• MakerBits on YouTube: MakerBits
• LNbits Shop: shop.lnbits.com

7.2 A Few Words About LNbits

• LNbits is a free and open-source wallet and account system. It uses an existing funding source, such as a Lightning Node. The LNbits wallets themselves are essentially just database entries – the actual Lightning sats are in the payment channels of the connected Lightning Node.
• You can use the free demo server at demo.lnbits.com – it is custodial and without warranty. Long-term, you should consider hosting your own LNbits server and Lightning Node. How to do this is a topic in itself and not exactly trivial. I may write an article on this once I’ve found a practical approach.
• Important note on wallet backups: If you lose access to your wallet, there’s no way to recover it. The sats aren’t lost, but you’ve effectively donated them. The operator of LNbits and the underlying node still has access – you won’t be able to reclaim them.

7.3 More About the Candy Machine

• You can buy the complete set in the LNbits Shop: Dispenser Kit
• Alternatively, get just the candy machine, for example here: Innovagoods – Mini Automatic Candy or here: ReWu Sweet Dispenser
• Quick disassembly help: Remove the four rubber pads on the bottom – screws are underneath. Turn the dome slightly left and lift it off. The black funnel is just laid in, you can pry it gently from the edge or lift it from the middle. The auger can simply be removed. Then loosen the three screws and carefully lift the internal holder with the gear. Be careful, it’s wired.
• You’ll now see the motor and a small PCB with a wire leading to a plate that acts as a sensor. Disconnect the small PCB and replace it with the relay. You can simply cut the wire to the sensor plate.
• A note about the machine featured in Ben Arc’s videos: he uses an ESP32 with display, also used in the LNPoS. The benefit of that ESP32 is that it has both a display and a direct LiPo battery port which can also be charged via USB. This battery can replace the candy machine’s internal batteries. So no need for a USB power bank anymore. I might document this in detail later.
• Since everything gets reassembled afterward and you may want to reconfigure it, it makes sense to wire the Touch Pin 4 externally – maybe even the USB port.
• Here are some assembly photos and the ESP32 datasheet for the standard ESP32.
• I also had an ESP32 TTGO with a display, which I damaged during installation (for a LNPoS). This model has a special connector on the back for a LiPo battery. That way, the Candy Machine becomes fully independent from external power. Here’s the wiring diagram.
• Update 810954: I’ve documented the Candy Machine installation in more detail in this PDF.

Equipment

7.4 More About the Beer Tap

• I used a Mini ESP32 here. But you can use any other variant as well. If you’re not confident with soldering, I recommend one with pre-soldered pins, like the ESP32-DevKit.
• For stepping up from 5V to 12V, you can use a HW-637 or this one from eBay. Warning: The mentioned voltage regulator is shipped with an output of up to 36V by default. To adjust it to 12V, connect only the 5V input and measure the output with a voltmeter. Then turn the small potentiometer (POT) on the board counterclockwise until you reach 12V.
• For the relays, you can use either a HW-482 or a KY-019.
• The linear actuator I used runs on 12V, has a 10 mm stroke, 128 N force, and moves at 7 mm/s. There are countless variants and suppliers, but this one fit perfectly for me.
• The mounting plate is 100 mm x 50 mm x 2 mm. The two screw holes for mounting are in the upper corners, each 12 mm from the edges. The third hole for anchoring the actuator is centered on the bottom edge and 10 mm from the rim. All holes have a max diameter of 5.0 mm. A sketch is included – thanks to Dezentralbanker for making one.
• You’ll need 5 screws (e.g., M4 x 16 mm), some washers, and nuts. Don’t forget the extra nuts as spacers and adjusters on the tap lever.
• To position the plate on the keg’s frame, center it opposite the tap cutout and align the corners with the frame. See the pictures! Use the plate holes to mark the drilling points. Then remove the plate and drill the holes if your marks are nicely centered.
• The position of the hole for the tap lever screw is tricky to explain. Let’s say: centered and 17 mm from the bottom arc.
• I used a 5-liter Krombacher Fresh Keg. It’s a beer that still tastes good even when not ice cold. However, this pils foams quite a bit and we don’t have the luxury of the famous 7 minutes to pour the perfect beer. A better choice is Starnberger Hell. It poured very smoothly and had a pleasantly mild taste. You can also use Heineken or even Desperados. Just make sure the keg has a built-in pressure cartridge – indicated by “Frische Fass.”
• Fun fact: The internal pressure cartridge looks like a spray can. It uses a very interesting patent that’s worth figuring out. “How does the cartridge get into the keg and only activate when tapped?” It’s really fascinating! Take the empty cartridge out later and try to solve the mystery.
• Changing the keg is easy. Just unscrew the two bolts holding the plate. You can gently remove the fully assembled tap lever from the plastic joint and reuse it. Use the plate to mark new holes on the new keg, drill them, mount the unit, done!
• Alternatively, you can replace the whole frame – no new drilling needed. See the “Frame Removal” picture in the appendix! The frame can be popped off and pressed onto the new keg so it clicks into place. Be careful during disassembly – it takes some finesse!
• You should also remove the tap lever if you don’t want beer spilling everywhere during testing or transport.
• There are two switches installed. Switch S2 toggles automatic mode ON/OFF. You can replace it with the tap lever pull or an optional connector to the actuator.
• Switch S1 is more useful. It can simulate a payment or microcontroller signal and activate the actuator. Handy for setup and mechanical alignment.
• Dezentralbanker kindly shared the AutoCAD file for the laser-cut beer tap mount. The DXF file and contact info can be found here: Beer-Tap-Laser-Cut-Grundplatte-221227.zip
• Picture update for BeerTap versions: “Workshop” (as simple as possible) and “LED-Button.” The workshop version uses the standard Web Installer. For the LED-Button version, use this special Web Installer. The GitHub project is available here.

7.5 More About the Universal bitcoinSwitch

• The housing is an Eaton surface-mounted enclosure M22-I3. It’s a very tight fit. Inside is an Eaton M22 selector switch (M22-WRK3/K20) and a 230V LED (M22-LEDC230). Important: the switch has a maximum current rating of 6A, so the fuse is rated at 6A, even though the relay supports 10A.
• As an alternative relay for 230V AC up to 10A, I used a Hailege relay with opto-isolation. The relays mentioned in other projects may also work, but watch their maximum specs closely.
• For safety, consider using an inline fuse.
• I was amazed by a mini power supply converting 230V AC to 5V DC. It doesn’t get much smaller. It works well – just make sure you insulate it properly.
• Tip: There are complete 230VAC relay boards (up to 10A) like this one from AliExpress. They include everything, but you’ll need a USB-TTL adapter to flash the program, as there’s no onboard USB port.
• If you plan to use the bitcoinSwitch in mobile setups, be sure to use proper cable glands. These provide strain relief and protect against splashing water. 230V AC is no joke – risk of electric shock and fire!

7.6 Notes on Setting Up and Checking Drivers

If you’re experiencing driver issues, the first step is to identify which driver you need. If your system doesn’t automatically suggest the right one, you can find out by inspecting your microcontroller closely.

The largest chip is the ESP32. The second-largest is the communication chip – that’s the one you need. It usually has a label like CP2102, CH340, or CH9102. With that, you can download the appropriate driver from the following sources:

CP2102 drivers: Windows & Mac
CH342, CH343, CH9102 drivers: Windows, Mac
CH340, CH341 drivers: Windows, Mac

Visit the driver provider’s website and select your operating system. Under “Downloads,” you’ll typically find a ZIP archive. After downloading and extracting it, point the driver installer to it – either when prompted by your system or during a manual update.

If you’re having persistent issues installing the bitcoinSwitch, try a driver update. Especially on Mac, updates often resolve recurring issues.

Special note for Linux users:

# Add current user to the "dialout" group
sudo usermod -aG dialout $USER
# Grant read/write permissions (e.g., ttyS0 or ttyUSB0-9)
sudo chmod 666 /dev/ttyXXXX
# You may need to log out and back in

On Linux systems, serial ports typically have permissions set to “rw-rw—-“, meaning only the owner and associated group have read/write access.

For the Chromium browser to communicate with the ESP32 over USB/TTL, the user must be in the dialout group or the port must have its permissions adjusted with chmod 666 /dev/ttyXXXX (replacing ttyXXXX with the actual device name).

Note: This setting may need to be reapplied each time the ESP32 is reconnected.

Another note on driver source:

The old Web Installer shows a window with driver source links. Visit the old Web Installer and click the Flash button. A window should pop up showing possible “Port Connections.” If it doesn’t, the connection might be faulty. Click Cancel to see a help window labeled No port selected.

This window always appears when no port (i.e., USB interface) has been selected. It also provides useful links to relevant drivers – in case the driver wasn’t installed automatically or you need an update.

---

Created with Since 749573 / 894092

---