bitcoinSwitch – The bridge between two worlds

"0" and "1" are the elementary states of our digital world. Simple switching processes that are logically processed can control or regulate something and thus influence our real world. All our progress and comfort is based on this, but the established payment systems have a hard time building a bridge between these two worlds. Our cash is subject to an enormous testing and security effort. With our "digital" fiat money, a crowd of intermediaries and the strictest regulations (even for the smallest payments) are used. Micropayments or infrequent payments are often not worthwhile because the costs for setup, basic fees or running costs are so high. We slow down our development, we have to give our earnings to third parties just because the system is inefficient. Our classic money has not yet arrived in the 21st century, but that is about to change because there is a new money – Bitcoin ⚡ Lightning.

1. bitcoinSwitch, briefly explained

To put it simply, the bitcoinSwitch is nothing more than a microcontroller (semiconductor chip with processor and peripheral function), software and a relay for switching current and voltage. The microcontroller is connected to the Internet via Wifi and can query the account balance of a Lightning ⚡ Wallet. If an incoming payment is registered, the microcontroller switches the relay, which can trigger any action. For example switching the electricity for a socket, driving the motor of a vending machine, releasing something, heating, pumping, etc. The possibilities are only limited by your own imagination. "0" and "1", are not only the basics of the digital world and that of Bitcoin, but also those of automation.

2. The structure

Small, fine, simple! A bit of electronics, some software, the functionality of Lightning ⚡ and you can switch something with it.

3. The components

It doesn’t take much and is surprisingly cheap. The main components, such as relays and microcontrollers, are available for less than 10 euros and the software is free. The hardware components consist of an ESP32 microcontroller, a relay (high-active), a USB data cable, jumper cable and of course the power supply, e.g. a USB power pack or laptop. Depending on which type of ESP32 microcontroller you have, the pin assignment, function and number of buttons or LEDs can vary slightly. In principle, all ESP32 with Wifi are similar and should work.

In order to write the program to the microcontroller, you only need a web browser. The actual bitcoinSwitch program is free and open source software (FOSS) on GitHub. Writing the ESP32 to the bitcoinSwitch program is done through a web page called Web Installer. You can use this to configure the bitcoin switch right away. Because the bitcoinSwitch requires an Internet connection and a wallet. The stored Internet access can be your home network or a hotspot.

As a wallet you have to use a special Lightning ⚡ wallet, the LNbits wallet. LNbits is a wallet and account system, with many extensions around the LNURL (Lightning URL) protocol. A wallet from the free demo server legend.lnbits.com is a good place to start. It is free, but without any warranty or guarantee on the function or the funds. For testing with small amounts, completely sufficient.

4. Examples of the bitcoinSwitch

Here I briefly present three projects. Further information can be found in the attachment.

4.1 Candy Machine

A machine that ejects sweets. A small motor drives a small screw conveyor. Here the original "touch button" under the ejection has been replaced by the bitcoin switch. If someone pays the Lightning Invoice from the QR code, a few candies are thrown out.

4.2 Low budget beer tap – for plebs!

There are already very good beer dispensers where you can pay with Lightning. But they were all too complex and expensive for me, I wanted something simple and cheap, for every pleb. Then I found the 5 liter Fresh Barrel from Krombacher. They are a bit more expensive than normal 5 liter kegs, but they have an integrated CO2 pressure cartridge. This keeps the beer fresh for 30 days and above all the pressure constant. The dispensing system is actuated by a lever, which in turn actuates an internal valve. For this bitcoinSwitch project, the lever is powered automatically via a 12V linear actuator. If the bitconSwitch registers an incoming payment, it switches two relays. These relays reverse the voltage for the linear drive. The drive then moves in one direction or the other for the set period of time. The drive has its own limit switch. The additional handsets are optional.

4.3 Universal bitcoinSwitch

I thought, why not build a universal switch that can switch 230V? The Universal bitcoinSwitch is a 230V extension cable with a built-in switch. With this you can switch a socket, which can then switch on all possible devices (up to a certain power!) for a certain period of time. For example: a charging station, a pump, a heater or a motor for a children’s ride. This is definitely the mobile and universal variant.

Caution: 230V is a dangerous voltage!!! Please only copy if you have sufficient knowledge and experience.

5. Setting up the bitcoinSwitch

Setting up the bitcoinSwitch has now become very easy. You can install and configure everything via a web browser. No additional software is required. The website required for this is called Web Installer. It works with the desktop browser Chrome or Edge. The only hurdle you have to overcome at the beginning is setting up a suitable driver for the connection between the computer and the ESP32 microcontroller. With some operating systems, the appropriate driver is automatically recognized and installed when the ESP32 is connected. But it doesn’t always work and sometimes you need a driver update to make it work properly. If you have problems with this, take a look at the appendix under point 7.6, you will get help there.

Below I will explain every step you need to set up the bitcoinSwitch and provide pictures for a better understanding. 📖🤓

5.1 Preparation: The LNbits wallet

The bitcoinSwitch communicates with a LNbits Wallet. Here I show you how you can create a wallet on the free LNbits demo server and how you create the necessary interface data. This allows the bitcoinSwitch to connect to the LNbits wallet. As soon as a payment has been received, the bitcoinSwitch receives the information from the LNbits server and then switches a relay that carries out the desired action.

1. Visit the website legend.lnbits.com and create a wallet
2. You can now see the wallet on the top left and can add extensions under Manage extentions
3. There you select LNURLDevice and with ENABLE you activate the extension
4. Now you will find the item Extensions LNURLDevice under Extensions. Select it and create a new LNURLDevice Instance. This defines the parameters and generates an interface.
5. Fill in all fields and select Create LNURLDevice
6. Then click the small button LNURLDevice Settings in the middle and copy the displayed link to the clipboard. You will later add this "string" to the configuration menu of the Web Installer. See chapter 5.3 / point 20.
7. The last thing you need is the Lightning URL (LNURL). To do this, press the little eye once. In the window you will then see a LNURL QR code to scan with your cell phone and the LNURL as text for the clipboard. It is best to print out the QR code and put it with your bitcoin switch. Alternatively, copy the LNURL to your notes. So you have everything you need for the later configuration.

Info: LNURL comes from Lightning URL, which is a URL (internet address) to the LNbits server. This is a fixed URL that creates a new invoice for each request on the server. You can think of it a bit like a static or reusable invoice, at least that’s how it appears to the user as they don’t have to consciously ask for an invoice. Ultimately, however, only the URL is static, the invoice is always generated on request.

Note: In the LNURL window there is also a green indicator: Websocket connected That doesn’t say much, just that this LNURL is a WebSocket API. After scanning the QR code and paying the invoice, the field will change to Message received: 12-3000. Unfortunately, this still doesn’t tell me whether the connection to my bitcoinSwitch worked, but it shows that the payment has been received and which data should be transferred to the bitcoinSwitch. Here pin 12 and 3000 ms. The message Connection Closed just says that the website is not connected to the LNbits server. This can have various reasons. For a more precise diagnosis and feedback, look at chapter 5.4 later.

More: In the appendix chapter 7.2 I added a few more words about LNbits

5.2 Installation of the bitcoinSwitch

Let’s start now with the installation. There is the official website of the webinstaller: bitcoinswitch.lnbits.com. However, I have not yet been able to understand how it works correctly. That’s why I recommend an old version of the webinstaller here. You can find them here: Lightning Ledflash Web Installer. This webinstaller was originally intended for a variant of the Bitcoinswitch. The output pulsates in different variants. The version "V0.1 Classic" is the classic Bitcoinswitch and you have to use it. So choose from the drop-down menu instead of "V0.2 Flash" simply "V0.1 Classic" and then goes to "Flash".

8. Connect the ESP32 to your computer with a USB cable. Wait a moment for your computer to recognize the new device and then click on the ‘Flash’ button
9. Now select the correct connection and press Connect. Note: If the ESP32 is not recognized or not recognized correctly, look again at chapter 7.6. "Note on setting up and checking the driver".
10. Now select Install LNbits bitcoinSwitch in the "Device Dashboard".
11. Select Erase Device and press Next. Note: If you want to keep old configuration data like the WiFi and interface data, then leave it deselected.
12. Now the program will be installed (fashed). When the installation is complete go to NEXT and look at the next chapter with the configuration.

5.3 Configuration of bitcoinSwitch

After you have successfully installed the bitcoinSwitch on the ESP32, it still needs the WiFi and interface data for communication with the LNbits server. In order to be able to write the data to the bitcoinSwitch, it must be in a special mode or a specific portal must be open. The website offers you a special window called "Logs & Console". There you can check whether the ESP32 is ready to receive or in "Configuration" mode by showing "Launch portal" in the window. To get him to open the portal, you have to touch pin 4 at start or reset the ESP32. It’s always difficult to estimate whether that worked or not, but with the reference to "Launch portal" you can check that well. I’ll show you how in a moment.

You can either configure the bitcoinSwitch directly after installing it or later if you want to make changes. To do this, go back to the Web Installer, click on Flash, select the interface and carry out the following points.

13. Reconnect to the ESP32 and this time select Logs & Console
14. Click once on RESET DEVICE in the lower right corner and then immediately touch pin 4 on the ESP32 board. The row of numbers must stop as soon as you touch the pin and Launch Portal will be displayed. If the row of numbers stops after two seconds and Lauch Portal is not displayed, then repeat the whole thing. The "Launch portal" tells you that the ESP32 is ready for configuration. The ESP32 can only be configured in this state. Then press Back to exit the window.
15. Close the "Device Dashboard" and then click on Config
16. You will now see the message "To enter config mode: reboot the device holding boot pin". You can ignore this message because you have already taken the step that precedes it, namely started the portal for configuration. Close the window and then press ‘Connect’ a little further down.
17. Now you have to select the interface connection for the second time and confirm with ‘Connect’. This is somewhat incomprehensible, but unfortunately necessary.
18. You will then get Connected to Serial Port as a response. Close the window with Close and scroll down a little further.
19. Now you can see that you are ‘Connected’ with the ESP32. Select the button Select Template and there the bitcoinSwitch Config.
20. Now you can parameterize your bitcoinSwitch. You have to enter the Wifi (SSID / password) and the interface, i.e. the link to the LNURLDevice Extension of your LNbits wallet from chapter 5.1. The "Password for PoS AP Wifi" and "LNURL" fields are pre-filled with the values ​​"ToTheMoon1" and "true" by default, so you don’t need to change anything. Then click once on Save to Device to transfer the data. Once the transfer is complete, you have set up your first bitcoin switch. Congratulation! 🎉 To test the bitcoinSwitch, you have to restart it once. To do this, take him off the voltage or refresh the website and press the reset button once.

Tip: You can check if the transfer of the configuration worked. Simply make a change to a setting and then select Download from Device. The change should then be corrected again. This allows you to understand whether the data was actually written to the ESP32. Because unfortunately there is no feedback after the transfer and therefore you will not get an error message if something went wrong during the transfer. With the download function you can make changes to the configuration later without having to re-enter all the data. If the fields are not updated, then you probably did not open the configuration portal correctly. Go back to step 13 and try again.

5.4 Test and messages

Now the bitcoinSwitch is finally set up and everything is hopefully working as it should. But that often doesn’t work the first time, and then you have a big question mark on your face. A valuable diagnostic tool is again the Logs & Console window. You get the necessary feedback from the bitcoin switch. To do this, go back to the Web Installer page or if you’re still connected, refresh the page once. Click on Flash, select the interface, go to Logs & Console and press RESET DEVICE on the bottom right.

21. The Logs & Console window shows a correct execution of a bitcoinSwitch function. After the reset you can see the query for pin 4, whereby the portal was not activated, then the WiFi data and the connected wallet. As soon as an incoming payment has been registered, the bitcoin switch is instructed to switch output pin 12 for the desired time.
22. Here are a few typical (error) messages. USB triggered shows you that the WiFi connection could not be established. The error can sometimes occur with a bad WiFi connection. So just press the reset button again. If that doesn’t help, check your set WiFi. Note: If you are in "Launch Portal" mode, then the message is normal, since the bitcoinSwitch does not have to connect to the WiFi at the moment. So you can ignore them. The serial interface ports can only establish one connection at a time. If you see the message Failed to execute 'open' on 'SerialPort' then you have probably used a port before. Just refresh the page and try again. Failed to initialize depends on the type of ESP32 used. Some require permission to install (flash) the software. To do this, hold down the BOOT button on the ESP32 as soon as you press the INSTALL LNBITS BTICOINSWITCH button. After that you can let go of him. With other ESP32s, you have to hold down the BOOT button while the ESP32 is booting. This depends on the ESP32 used and is not necessary for most. Another possibility for this error message is an uninstalled or wrong driver. Pay attention to the window where a connection for the serial port is suggested.
23. Not connected to device or Cannot update file!. A common mistake, as it is easy to forget to press "Connect" before pressing Save to Device or Download from Device. So connect with "Connect". And then there is a bug in the LNbits extension LNURLDevice. This is expressed by LNURLdevice = empty. The reason for this is that you forgot to fill out a field such as "Fiat currency". Sometimes you have to click on the wallet at the top left to fix it, so that everything gets going again.
24. Disconnected in the Logs & Console window shows you that your ESP32 has lost the WiFi network. No file path specified!. Before you can parameterize the bitcoinSwitch, you always have to select a template. IMPROVxxxx.. Weird characters are often seen on the first attempt to connect. Just press reset again, then it usually starts again.
25. Serial port is not readable/writable You will get the message if you have the Logs & Console window open and then disconnect the ESP32. As soon as you close the window, the message appears. Just do a browser refresh. If the message appears when you try to connect, try to press and hold the "BOOT" button on your ESP32 and then connect. Should that not help either, you could do a driver update, see Appendix 7.6. No port selected is a message that always comes up when the interface to the ESP32 is not recognized. Either not connected correctly or the driver is wrong. It is also best to have a look at chapter 7.6 in the appendix. Failed to download manifest is given when the download server has a problem or the internet connection is not working.
26. Serial port is not ready. Close any other applications using it and try again. This seems to be a Windows driver problem of the interface converter CP210x version 11.2.0. A downgrade to the previous version 11.1.0 should fix the problem. You can check your version with the device manager. Press the Windows key + X and go in the device manager to Connections (COM & LPT). There you select the CP210x entry. If you trust me, you can download the older driver here. I haven’t found an official site for the older driver yet. You should first uninstall the current driver under "Uninstall device". Also check the box "Delete driver software for this device". Then restart the PC once and install the new driver by clicking on "Update driver" and then "Search on computer". Now select the folder of the driver v.11.1.0 and then with "Next" let the driver search and install itself. Make sure that the checkbox "Include subfolders" is selected, because the actual driver is located one folder below. After that, completely reflash the ESP32 once with the webinstaller and everything should work again.

6. Summary

"Fascinating" would say Spock 🖖😑. In 2009, Bitcoin was the first digital asset that could have real value. It’s digital, but still not copyable. It works P2P, is divisible, does not need an intermediary, the use is permissionless and also resistant to censorship. Then came Lightning ⚡ 2018 and we were also able to transfer this good quickly and inexpensively. When people use a good as a medium of exchange, it can become money. And with this new money, you can now even switch things. How cool is that? We built a bridge. Paying for something from the digital world that will benefit us in the real world. If added value is created, or if something can solve a problem for someone, then they will be willing to pay appropriately for it. We now have the money and the technology. We can now build everything ourselves, very easily, very cheaply and who wants to build it completely independently – thanks to Bitcoin ⚡ Lightning.

I hope my little guide could help you to get a basic overview of the bitcoinSwitch. It’s all a little complex, especially when you’re new to it, but maybe you were able to replicate one or the other project or even create something completely new. At least that’s my goal, because we need more "Makers" to build something on top of this wonderful ⚡ Lightning.

If you have any questions or suggestions, please join the Telegram groups:

• MakerBits – Everything about technology: https://t.me/makerbits
• LNbits – Everything about LNbits: https://t.me/lnbits

And now a new German-speaking (DACH) group especially for the bitcoinSwitch:

• bitcoinSwitch DACH – The link is not public, please ask me: AxelHamburch

Note: The group also has an anti-spam bot and it charges 21 ⚡-Sats entry as a ticket. Background, spam bots don’t have a Lightning Wallet. 😉 So have your Lightning Wallet ready. You have 15 minutes. It’s easiest to use the LightningTipBot wallet because that’s the gatekeeper, but other wallets will work as well. If the bot kicked you after 15 minutes, it’s best to write to me via Telegram or Twitter. I will then unlock you again and can also help you.

If you want to reach me directly, either via Telegram at https://t.me/AxelHamburch or via Twitter [https://twitter.com/axelhamburch](https:/ /twitter.com/axelhamburch) via direct message. Any feedback is welcome, constructive criticism is expressly desired.

Other than that, I just have to thank the incredible Ben Arc who did it all through his LNbits and the bitcoinSwitch made it possible in the first place. Hats off to this man! A Gyro Gearloose of the 21st century.

If you liked my article or the tutorial or if it could even offer you some added value, I would be happy if you use Bitcoin ⚡ Lightning and send me some Satoshis in appreciation. You can find ways to do so on my contact page.

Stay curious and until the next tutorial

Axel

7. Appendix

If you want to get started right away, you can buy the Starter Kit in the LNbits shop. Otherwise you will find many other sources and information below.

7.1 Other information material

• Short Twitter video with info link
• Video tutorial for the bitcoin switch link
• The GitHub page of bitcoinSwitch link
• The GitHub page of LNbits link
• MakerBits auf 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. LNbits wallets are actually just database entries. The real Lightning Satoshis are in the payment channels of the Lightning node that has been set as a funding source. You can use the free server legend.lnbits.com, it is custody and without guarantee. Later you should start hosting your LNbits server and the Lightning Node yourself. How to do this is a topic in itself and not entirely trivial. When I find a reasonably workable solution, I might write an article about it.
• A note on securing the wallet! LNbits is a pure browser wallet. You get access via a URL website link. There is no classic login. So put the link under Favorites or copy it from the browser input field and save it somewhere safe. If you lose the link, there is no longer any way to access the wallet. The Satoshis aren’t gone, you just donated them. Whoever runs LNbits and especially the Lightning Node behind it still has control over the Satoshis in the channels. You won’t be able to reclaim them though, that’s the deal. Own sovereignty comes with own responsibility.
• To make it easier for you to get started, here are a few pictures of setting up the LNbits wallet

7.3 More about the candy machine

• You can buy the whole set in the LNbits shop:: Dispenser Kit
• Just the candy machine you get here Innovagoods – Mini Automatic Candy or here ReWu Sweet Dispenser
• Short help for disassembly: Take out the four rubber buffers from below, the screws are behind them. Turn the dome slightly to the left from above and then simply remove it. The black funnel is only inserted, you can carefully lever it out from the edge or lift it from the middle. The screw conveyor can be easily removed. Then loosen the three screws and carefully lift the inner bracket with the gear wheel. Attention, the part is wired.
• Now you can also see the motor and a small board with a cable to the board that is supposed to represent the sensor. You have to disconnect the small circuit board and replace it with the relay. You can simply cut the cable to the sensor plate.
• Another note about the vending machine that Ben Arc presents in his videos. He uses an ESP32 with a display, which is also used in LNPoS. The advantage of the ESP32 is that, in addition to the display, it also has a direct connection for a Lipo battery and can also charge it via the 5V USB connection. In principle, the rechargeable battery can also be used to replace the batteries in the candy machine. You no longer need a USB power pack for this. Maybe I’ll get around to documenting that in more detail later.
• Since everything is then reassembled and you might want to change the parameterization again, it makes sense to route at least touch pin 4 externally. Possibly even the USB connection.
• Attached are a few pictures of the assembly and the ESP32 data sheet of the standard ESP32
• I still had an ESP32 TTGO with a display, where the display broke during installation (for an LNPoS). The TTGO ESP32 has a special connector on the back. You can connect a Lipo battery there. This means that the Candy Machine is independent of an external power supply. Attached is the circuit diagram.
• Update 810954: I have documented the installation of the Candy Machine in more detail in a PDF.

7.4 More about the Beer Tap

• I used a Mini ESP32 here. But you can also take anyone else. If you’re not that familiar with soldering, I’d recommend getting one with the pins already soldered. E.g. the ESP32-DevKit.
• As a step-up converter for the transformation from 5V to 12V you can use a HW-637 or this one from the bay. . Caution, the specified voltage converter is delivered with an output voltage of up to 36V as standard. To set that to 12V, just connect the 5V input voltage and measure the output voltage with a voltmeter. Then turn the small potentiometer (potentiometer) on the circuit board several turns to the left with a small slotted screwdriver until you get the desired 12V displayed.
• For the relays you can use a HW-482 or a [KY-019](https://www.google.com/search ?q=KY-019).
• The linear drive has the performance data 12V, 10 mm travel, 128 N, 7 mm/s. There are countless variants and providers. But it fit me perfectly right away.
• The holder plate has the dimensions 100 mm x 50 mm x 2 mm. The two mounting holes are each in the top corners at 12mm x 12mm from the edge. The third drill hole, for anchoring the linear drive, is in the middle of the lower 100 mm edge and 10 mm from the edge. All drill holes are max. 5.0 mm in diameter. You can find a sketch of it here. The decentral banker kindly made one.
• You also need 5 screws (e.g. M4 x 16 mm), a couple of washers and nuts. Think of the extra nuts as a spacer and correction piece on the tap lever.
• To align the plate on the keg frame, center the plate opposite the tap recess and then center the corners on the frame. See pictures! Now use the drill holes in the plate to mark the drill holes on the frame. If you now remove the plate and the preliminary drawings are relatively centered on the frame, you can drill the holes in the frame.
• The position of the drill hole for the screw on the tap lever is a bit difficult to explain. I describe it like this: In the middle and 17 mm from the lower arch.
• I used a 5 liter Krombacher freshness barrel here. This is a beer that you can drink even if it is not chilled. However, the Pils foams quite strongly and we don’t have the famous 7 minutes for a good draft beer here. Starnberger Hell is more suitable. The light beer was easy to tap and I found it pleasantly mild in taste. Alternatively, you can also order a Heineke or even a [Desperados](https://www.google.com/search?q =desperados+freshness+barrel). The only important thing to note is that the dispenser is at the top and the keg has its own pressure cartridge. You can tell by the name "fresh barrel".
• Fun Fact: The inner pressure cartridge looks like a spray can. She has a very interesting patent that you have to understand first. "How does the cartridge get into the keg and only activate when the tap is tapped?" That’s really interesting! Get the empty cartridge out later and try to solve the puzzle. 😄
• Changing a barrel is quite easy. All you have to do is loosen the two screws that hold the plate to the frame. You can carefully pull the tap lever fully assembled out of the plastic joint and use it again. Mark the drill holes on the new barrel using the plate. After drilling the holes, put the unit back on and you’re done!
• Alternatively, you can also change the whole frame at once, then you don’t have to drill anything again. See the picture "Remove the frame" in the appendix! You can remove the frame with the plate relatively easily and press it onto the new barrel so that the frame clicks into place. But be careful when dismantling, a little sensitivity is required!
• You should also remove the tap lever if you don’t want the whole beer to be distributed during commissioning or transport. 😉
• Two switches are installed. The switch S2 switches the automatic ON and OFF. You can easily replace it, as described above, by pulling the tap lever or by using the optional plug-in connection to the linear drive.
• Switch S1 makes more sense. With the S1 you can simulate an incoming payment or the output of the microcontroller and control the linear drive. This is very useful when starting up and aligning the mechanics.
• Kindly, the decentral banker has now also made the AutoCAD file for the laser cut of the Beer Tap holder available. The DXF file and contact details can be found here: Beer-Tap-Laser-Cut-Grundplatte-221227.zip
• Update the images with BeerTap version "Workshop" (as simple as possible) and version "LED Button". The BeerTap for the Workshop is the classic Web Installer. For the Beer Tap with LED-Button you have to use this special Web Installer created by me. You can find the GitHub project here

7.5 More about the Universal bitcoinSwitch

• The housing is an Eaton surface mount housing M22-I3. That’s already borderline narrow in it. It contains an Eaton M22 selector switch (M22-WRK3/K20) and an LED (M22-LEDC230) for 230V. Please note the maximum current load of the switches (6A). That’s why the back-up fuse is designed for 6 A, although the relay can handle 10 A.
• As an alternative relay for 230V AC and up to 10 A switching current, I used a Hailege with OPTO isolation. The relays already mentioned in other projects can also work, but you have to be careful with the maximum performance data.
• An inline backup can be used as a backup
• I was fascinated by a mini power supply. 230V AC to 5V DC. It really couldn’t be any smaller. 😁 But it works really well. You just have to isolate it yourself.
• Tip: There are also complete boards for 230VAC connection with a relay (up to 10A !!!). E.g. here from AliExpress. Everything is already on it, but you still need a USB-TTL adapter to fash the program, since the board doesn’t have a USB connection and has no adapters on board.
• If you want to use the bitcoinSwitch mobile, remember to also use suitable screw connections for the cable entry. This serves as strain relief and protects against splashing water. The 230VAC should not be underestimated. Electric shock and fire hazard! ⚠️

7.6 Note on setting up and checking the driver

Here you will find help for the basic requirement, the connection between the computer and the microcontroller. Important is, the communication works only with Chromium Browser like Chrome or Edge.

Connects the ESP32 to the computer via USB cable. With a bit of luck, the system will automatically install the appropriate driver and not display an error message. Then let’s assume that everything is set up properly. Whether you get an error message or not, now go to the Web Installer website and click the Flash button once. A window pops up in which possible "port connections" are now displayed. If not, something is wrong with the connection. Now go to ‘Cancel’. Then you will see a help window that says No port selected.

The window always appears if you have not selected a port (USB interface port). It also offers you the appropriate links for possible drivers if the driver was not installed independently or if you want to update the driver.

Now you will surely ask yourselves, which driver do I need at all? If the system does not already provide you with the necessary driver, you can easily find out for yourself by taking a closer look at the microcontroller. The largest chip on the board is the ESP32. The next smaller is the communications processor and that’s exactly the type you need. The designation is usually on the chip, e.g. CP2102, CH340 or CH9102. So now you know what the driver has to be called and with the help page from above you can also find the right source for the driver. Go to the website of the driver provider and look for the right operating system. Under Downloads you will then usually find a compressed folder. Once you’ve downloaded and unzipped it, you can refer to it whenever your system searches for a driver or when you want to update it. If, for example, you have recurring problems installing the bitcoinSwitch, try a driver update. Especially with Mac systems there have been problems from time to time and an update could help.

Another hint especially for Linux machines.

On Linux machines the serial ports are by default set to "rw-rw—-". So "rw" only for the user and the group, but not for all other users. For the communication of the Chromium Browser with the ESP32 over the USB/TTL interface, either the user must be added to the group "dialout", or the rights must be changed with the command "chmod 666 /dev/ttyXXXX", for the serial port, which one would like to use. You may have to repeat this procedure every time you plug in the ESP32.

# add current user to the group "dialout"
sudo usermod -aG dialout $USER
# add read/write permission (r+w) (for e.g. ttyS0 or ttyUSB(0-9))
sudo chmod 666 /dev/ttyXXXX
# After that log in the user once again if necessary

7.7 Using Arduino IDE

Here is some help for the technicians among you. ⚙️ With Arduino IDE you can upload your own sketches. The description is no longer up to date, since the earlier version of the bitcoinSwitch is described here, but the basic principle can still be seen there.

7.7.1 Prepare hardware and software

• Install Arduino IDE on your computer. Caution: There is already version 2.0.0, but I currently recommend using the Legacy IDE 1.8.X below. Background: The 2.0.0 has a slightly different structure and therefore does not follow this documentation. But the version is also a bit buggy. So only use the 2nd if you know what you are doing. As soon as version 2.0.1 is available, I will update the tutorial for it.
• Opens the "File/Preferences/Settings" page. Note the path under "Sketchbook location", e.g. "C:\Users\User\Documents\Arduino" and open the "Arduino" folder in File Explorer. You need the folder right away.
• To specify the path for the ESP32 board drivers, go to the "File/Preferences/Settings" tab and field "Additional Borads Manger URLs" and paste the following link https://raw.githubusercontent.com/espressif/arduino-esp32 /gh-pages/package_esp32_index.json
• Then confirm with OK so that Arduino knows the resource for the driver package
• Now search under "Tools/Board: ../Board Manager" for "ESP32"
• Installs the board driver package "esp32 Espressif Systems version 2.0.x"
• Look under "Tools/Board:../ESP32 Arduino" and set the type of your ESP32 board
• Try what suits your ESP32 board best. E.g. ESP32 Dev Module, NodeMCU-32S or WEMOS D1 MINI ESP32. They are related and can work even if they do not match exactly. If not, try another type. It’s best to try the ESP32 Dev Module first, it works for a lot of people.
• Check "Show verbose output during: compilation / upload" so that you can also see what happens during compilation and uploading. And so that you can see the line numbers in the program, check "Display line numbers".
• For the new bitcoinSwitch you still have to install a library manually. To do this, go to Sketch -> Include Library -> Manage Libraries -> search for "WebSockets" -> by Markus Sattler -> install.
• The Arduino software is now ready. First close the Arduino software.
• Now comes the download of the project and the actual setup
• Go to the bitcoinSwitch page https://github.com/lnbits/bitcoinswitch
• Download the ZIP file. You can find the file behind the green button "Code". Note: The button is only visible in a desktop browser!!
• Extract the zip folder and check if there is another folder named "bitcoinSwitch-main" in the folder. It contains the ".ino" file and the "libaries" folder.
• Rename the folder to "bitcoinSwitch" and move the whole folder to the "Arduino" folder from the top of this section
• Now go to the moved folder "..\Arduino\bitcoinSwitch" and copy the "libraries" folder to the "Arduino" folder to update the library. Overwrite, you can confirm with "Yes".
• Go back to the "bitcoinSwitch" folder and double-click the "bitcoinSwitch.ino" file
• This opens the Arduino IDE again and the actual project
• In the program code from line 20 there is "///////////CHANGE////////////////". Check the settings there
• "usingM5 = false‘ because you are using an ESP32 and not an M5Stack
• "format = false‘ because you don’t want to reformat. If it does, only once to true -> reflash and once more to false -> reflash.
• You can leave "portalPin = 4" as it is. This is later your touch pin to open the Access Point (AP) portal (the web interface).
• The preparations are hereby done 👏

7.7.2 Write the program to the ESP32

• For the interface configuration – microcontroller <-> computer – look in the Arduino IDE under "Tools/Port" and check what is there. E.g. Serial ports, COM1
• Now connect the ESP32 to the computer via the USB cable and briefly change the tab (the registration card) in Arduino so that the update is displayed
• If the computer has found the connection, another COM port should now be displayed under "Tools/Port", e.g. Serial ports, COM1, COM3
• You have to actively select the port once so that it gets a tick in front of it. Only then can the computer connect to the microcontroller.
• Notice for MAC and Windows 11 users. You probably have to install the interface driver manually first. You can find the driver here: [https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers](https://www.silabs.com/developers/usb-to-uart– bridge-vcp-drivers)
• Note: If the COM port is not recognized even after the restart, the problem is often the cable. Try a different cable or a different USB port.
• Note: For an alternative COM port diagnosis under Windows, open the device manager with Win+X and then look under "Ports (COM & LPT)" and check the ports
• To write the program to the microcontroller, go to "Sketch/Upload"
• First the program is compiled "Compiling sketch". This can take several minutes. You can ignore "Warnings".
• Then comes "Uploading.." and the window says: esptool.py v3.3, Serial port COM3, Connecting...
• Depending on which microcontroller or driver you use, you now have to confirm the upload on your microcontroller with the "BOOT" button
• If you are too slow, you will get the error message A fatal error occurred: Failed to connect to ESP32... Just repeat the process and press the "BOOT" button quickly enough when you see Connecting....
• Note: You don’t have to confirm the upload for all microcontrollers, for many you can do without
• If the upload was successful, you will now see "Done uploading" and Leaving..., Hard resetting via RTS pin...
• Congratulations, you have described the microcontroller with the bitcoinSwitch software
• To configure the bitcoinSwitch and assign a WiFi, you can now use the web installer.

7.7.3 Other useful information and diagnostics with the "Serial Monitor"

• If the microcontroller is in "Normal operation" mode, you will see no "Device-…" in the WLAN overview of your cell phone. The microcontroller is now "passive" in the WLAN network. Thanks to your stored access data, he should now have access to the Internet and thus be able to check the LNbits wallet for incoming payments.
• But you can check whether he has logged into your WLAN. To do this, check your router to see which participants are active there. There should now be an "ESP32-…" to be found.
• Do you want to reconfigure the bitcoinSwitch? Then you have to activate the access point mode again with the touch pin 4 – when starting the microcontroller – and log in to the web interface again via the active search of the WLAN participant.
• It is precisely this difference between "normal operation" and "access point operation" that is difficult for beginners to understand and also difficult to recognize from the outside. Some ESP32 boards have a special blink rate, but not all. To check which mode it is currently in, use your mobile phone to search for the participant "Device-…" . If it cannot be found, then it will be in "normal operation".
• Instead of the mobile phone, you can of course also use a laptop or a tablet to log into the microcontroller. For the sake of clarity, I only mentioned the mobile phone here in the instructions.
• You can use the Serial Monitor for troubleshooting. To do this, you have to connect the ESP32 to the computer via USB cable and set the correct port under "Tools/Port". Then click on the small magnifying glass 🔍 in the upper right corner of the Arduino IDE software. Another window should open. There you may have to set the baud rate to 115200, for example.
• If the connection with the serial monitor works and the ESP32 is in "normal operation", individual lines are described in the window. For a better overview activate "Autoscroll" and "Show timestamp" at the bottom left.
• The Serial Monitor shows you extensive information. Among other things, your wallet balance (in millisatoshi), whether a payment has been received, which pin was selected and for what time. You can also see the boot process of the ESP32 and whether the portal has been "launched". Try it out with the RESET button while the Serial Monitor window is still open.
• One more clue. My article LNPoS also uses an ESP32 microcontroller, the Arduino IDE software and LNbits. It certainly doesn’t hurt to read the article sideways.

7.8 Miscellaneous

• If you don’t have a Lightning Wallet yet, a very simple one is walletofsatoshi.com

• If you don’t have any Lightning Satoshis yet, exchange a few on-chain coins for off-chain Lightning Satoshis at fixedfloat.com, for example. All you have to do is specify Bitcoin for "RECEIVE" and then you can "Try lightning!" select.

• One more note on the GIPOs. Pins 14 and 15 have a special function on the ESP32. They output a PWM signal when booting. The pins should not be used on the , otherwise you will get your relay switched for a few seconds each time you boot.

• The bitcoinSwitch also works under certain conditions with a self-hosted LNbits on e.g. a Raspiblitz. However, you have to go through IP2TOR if you don’t have a clearnet connection. At the time of this writing, there was a Pull request that allows using IP2TOP. With the PR you can also define an individual port for the LNbits server. Otherwise, the standard HTTPS port 443 is always stored and that doesn’t work with IP2TOR.

• Link to the driver source for the board managers: espressif – board manager

• If you want to test an output: gpio-pins-esp32-led-blinking-example

• If you want to build an LED button to test inputs and outputs. For the Lightning ATM I have already put together a kit for an LED illuminated pushbutton. led-button-cset

• ESP32 data sheet: espressif esp32

• Here are two tips for all those who use a mobile wifi hotspot with SIM card or use their cell phone as a hotspot with limited data volume:

1. To make the ESP32 work immediately with the right WLAN, create a guest WLAN account at home with the SSID and password of your hotspot. Then you can set up everything at home and the bitcoinSwitch will work spontaneously on the road.

2. If you also connect your laptop or other devices to your hotspot, select for the wifi "clocked connection" or "treat as a chargeable network". This way, no automatic updates of the operating systems are performed via this wifi connection, which can save large data volumes. Under Windows: Start -> Settings -> Networks and Internet -> wifi -> Manage known networks -> <wifi network> -> Properties -> ‘Set as clocked connection’. On Android: Settings -> Connections -> wifi -> <wifi network> -> Settings (gear icon) -> Advanced -> Charged network -> Treat as charged.

7.9 WebInstaller

Here you can find some links to WebInstaller pages

1. bitcoinSwitch – The Original
2. BeerTap LED Button – BeerTap with LED-Button
3. KanutoSwitch – Two impulse
4. LEDflash – LED decoration lamp with multiple flash function