offlineLNSwitch (en)

The offline⚡️Switch

The offline⚡️Switch is a bitcoinSwitch based on a microcontroller board with ESP32 and user-friendly touch display interface. The special thing about the offline⚡️Switch is that it does not require an internet connection—the microcontroller does not need WLAN or any connection to the internet/server to receive a bitcoin lightning payment. Only the bitcoin lightning payer needs the internet connection. The payer scans the offline⚡️Switch’s QR code with his wallet, sends bitcoin over lightning, and with the send confirmation the payer’s wallet receives a response with a URL link. Selecting the link opens a browser and displays a page with a "secret" in the form of a four-digit PIN. The payer enters this PIN via the offline⚡️Switch touch display, and if the PIN matches, the offline⚡️Switch carries out the desired function. Et voilà! Add a power source such as an outlet or a battery and offline⚡️Switch can operate anywhere.

Rod data images of the surface:

1. The hardware

You need a Sunton 3.5" Smart Display, type ESP32-3248S035, e.g. from AliExpress. There are currently two versions available. The one with "resistive" touch and "capacitive" touch screen. In principle you can use both, but the capacitive touch display is a bit more robust and therefore I would also recommend that. Furthermore you need a 5V relay (High-Level-Triggered). E.g. this design.

The ESP32 itself can be connected and powered via the micro USB (5V) connection. The relay, can be connected directly with the supplied cable. Usually the 5V relays have three connections. Supply (5V), Ground (GND) and Signal (Sig). The Sunton ESP32 supplies only 3.3V, but for most relays this should be enough. Connect 3.3V (red), GND (black) and the signal IO21 (yellow) as shown in the picture. The blue line for IO22 remains unused here.

2. The software

You can easily flash the firmware via this Webinstaller for the offline⚡️Switch. You can choose the version you want to flash. Mostly it is the last version. Older or other versions can be selected from the drop-down menu. The version number is composed of the "block time" (the Bitcoin block height, when the version was created) and the appendix "c" for Capacitive or "r" for Resistive Touch. Followed by a designation, for better identification, which is extra arbitrary. At the bottom of the web installer web page you will also find a version hist

Run of the Flash process:

• Open the offline⚡️Switch Webinstaller page.
• Connect the EPS32 to your computer via USB cable.
• Check the required version and select Flash.
• A connection window will open where you have to select the ‘COM port’ for the ESP32 and then click on ‘Connect’.
• Now you see the Device Dashboard and select INSTALL OFFLINELNSWITCH.
• When flashing for the first time, activate Erase Device and then click on NEXT.
• Check the selected version once and press INSTALL.
• Now comes: Preparing installation… Erasing… Installing… Wrapping up… Installation complete!
• That’s it, the ESP32 has been written with the firmware and is ready for use. 🎉

Help if it didn’t work:.

• First try a browser refresh (F5). Often this helps to reinitialize the communication.
• If it still does not work, then reconnect the ESP32 and refresh again.
• If the connection problem persists, it could be due to a bad USB cable, replace it!
• If you get the message that the interface is already in use, then you may have opened a second window or another program that is already using the interface. Close all unnecessary applications.
• If you still have communication problems, then a driver update for the communication chip CH340C might be necessary. Follow this link for Windows or this one for MAC.
• For Linux devices, you may need to add the current user to the "dialout" group: $ sudo usermod -aG dialout $USER and $ sudo chmod 666 /dev/ttyXXXX.
• In very rare cases, the operating system simply refuses to cooperate. Then try it with another computer.

Another hint

After clicking the button Flash, you will also find the function LOGS & CONSOLE in the Device Dashboard. If your ESP32 is connected correctly and you press Reset once, you will see feedback from the ESP32. There you will also see certain program sequences and values. It is quite useful for debugging.

3. The LNbits wallet

The offline⚡️Switch needs an (online) Lightning Wallet (server) in the background with which the client can interact. For this we use LNbits. LNbits is Bitcoin Lightning Wallet and Account System, with many options, in the form of extensions that you can install. LNbits is Free and Open Source software. Anyone can set up their own LNbits server, but it is still technically quite challenging. The functions of LNbits can be tested with the free demo server legend.lnbits.com. So we also use the demo server in this example.

Set up wallet:

• Go to the legend.lnbits.com page.
• Choose a name for your wallet and then click ADD A NEW WALLET.
• Now please save the website link of the wallet as a favorite in your browser, or better yet, additionally copy and save it as text somewhere. This is your access to the Wallet. There is no username and password or similar, so watch out for the link.
• Click on Extensions and search for "LNURLevice".
• Activate the extension with ENABLE.
• Now you will find LNURLDevice on the left side under Extensions. Please select this once.
• Click on NEW LNURLDEVICE INSTANCE to create an instance for your offline⚡️Switch.
• Give it a title (it will be displayed during the payment process), choose which wallet you want to use (if you have more than one) and select the fiat currency.
• The function we need is PoS and already preset.
• Profit margin is still set to "0" so that the payer doesn’t pay extra fees and then press CREATE LNURLDEVICE once.

Now you see in the line under LNURLDevice, to the right of the title, the id and the key. These are the wallet data that you need for the offline⚡️Switch. Add the chosen fiat currency, here e.g. "EUR" and the host server that manages your wallet. Here e.g. "legend.lnbits.com" for the LNbits Host. Now you are ready for the parameterization of the ESP32. ⚙️

4. Set up the offline⚡️Switch

For the input of the data, it needs due to the size of it panel, some fingertip feeling, but is otherwise very simple.

Connect your offline⚡️Switch to a power supply and follow these instructions:

• Select the gear icon at the bottom left ⚙️ The default PIN is 123456.
• On the page Setup up config you enter the wallet data:
• LNbitsHost = e.g. legend.lnbits.com
• DeviceID = e.g. 7vDYV
• DeviceKey = e.g. 3v9i65KL36yhtw2xCNwD8k
• Currency = e.g. 0.21 (Attention: dot as decimal separator)
• You can also set a personal ConfigPIN here.
• Under Set up Switch you can set up the product and the relay:
• Name = Product name, will be shown at the QR-Code
• Price = Price of the product
• Time = Time in ms the relay should switch. E.G. 3000
• GPIO = Output which should be controlled. Default: 21
• Then there is the switch Toggle Switch. This can be used to control the relay manually or to invert the signal.
• Back to the Config menu with the button Config.
• Check the settings once and select Save+Exit.

Finished the offline⚡️Switch, it is now ready for use. 🎉

5. Compatible wallets

All Lightning⚡️Wallets that use LUD-09 of the LNURL-specification also support the feature to display a text/URL after payment. This is now the vast majority.

An overview of the tested wallets:

BitBanana / Blixt / Breez / LNbits / LightningTipBot / Phoenix / Wallet of Satoshi / Zeus / BlueWallet with Alby LNDHub

Where it is known not to work yet: Blink -> Feature Request #2660 opened.

On some the link is very well displayed and on others it can be a bit hidden. With some wallets (Breez, Blixt, BlueWallet/Alby, LNbits, LightningTipBot, Phoenix, WoS) there is a possibility to display the link afterwards. For some wallets (BitBanana, Zeus,..) unfortunately not yet, but for this there are issues and feature requests 😉

6. Appendix

The option shown here (Webinstaller), to describe the ESP32, is a possibility that is very user-friendly. However, the software is FOSS, that is Free and Open Source Software. Therefore, for the "savvy" user, there is also the possibility to check the software beforehand. According to the motto: Don’t trust, verify.

The whole project is available on Github. You can copy it, edit it or whatever. As development environment (Integrated Development Environment) I would recommend PlatformIO on VSCode. As a graphical user interface LVGL (Light and Versatile Embedded Graphics Library) was used and mostly created by the application SquareLine Studio.

Still mentioned its two great projects that were instrumental in helping me come up with the idea and from which I used parts for this project. One is the BliksemBier from Pieter and the bitcoinVend from Ben Arc. 🙏 Without them the offline⚡️Switch wouldn’t exist yet.