offlineLNSwitch

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. ⚙️

Note: There are at least three classic error possibilities that give different messages depending on the wallet used:

1. the error message "Failed to decode invoice, please try again." or "LNURL service has an error" indicates that the LNbitsHost is not correct.
2. comes "HAMAC is invalid" or "LNURL service has an error", then maybe the wallet key is not correct.
3. if you get the error "lnurldevice xyz not found…" or "LNURL service has an error", then you most likely have misspelled the wallet ID.

The characters have their pitfalls. Check all the data again very meticulously character by character. 🔍🧐

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. Supplement

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.

Here is another example of a type application case, a newspaper vending machine. The prototype is being built. They stand freely at e.g. gas stations and are filled and emptied once a week. So the battery has to last a week. They should soon work with Lightning ⚡️ Sats 丰 in addition to "Quarters". 🔥 This would be the first time in the decades-long history of newspaper vending machines. 🏅

7. Appendix: Deep Sleep or Shutdown

The offline⚡️Switch is particularly suitable for being operated autonomously using a battery. Unfortunately, the backlit display consumes quite a lot of energy. In one measurement I measured about 0.85 watts and 170 mA at 5V for a simple system with relays. Of course, sooner or later this forces every battery to fail or consumes electricity unnecessarily. In order to still be able to operate the offline⚡️Switch well, I have implemented various options for saving energy. Deep sleep mode is recommended for power supply operation, i.e. with a continuous power supply. For battery operation, you can dig deeper into your bag of tricks and switch off the supply voltage with a time relay to minimize power consumption. However, you should pay attention to battery protection.

Deep Sleep Mode

By the software implementation of the Deep Sleep Mode the display and large parts of the Sunton ESP32 are switched off. The ESP32 then only runs in maintenance mode with low power consumption. It can be reactivated via the external push button. However, the time until shutdown can also be reset by a "page change". This ensures that the ESP32 does not go into deep sleep mode when it is being operated. Thus, the unit is not used for at least 5 minutes before the system enters Deep Sleep mode. In Deep Sleep mode, the system only needs one fifth of the power. It varies a bit, but roughly I measured 0.17 watts and 30 mA. To wake the Sunton ESP32 from Deep Sleep, or to retrigger the time before, an external pushbutton must be connected to the GPIO 35 input as a "normally open" switch, with a pull-down resistor of about 10 kOhm. Without this it does not work (❗️), because the inputs of the ESP32 are very sensitive to interference and need a reference point. Otherwise you have undefined states and the input switches back and forth. Deep sleep mode is the best alternative to operating the offline⚡️Switch on a power supply.

Shutdown via time relay

The second option is an external hardware time relay. This has the advantage that the quiescent current can be reduced even further. According to the data sheet it should be 0.025 watts and 5 mA, I even measured only 4 mA. So in sleep mode it only uses one-thirtieth. The time relay can be "triggered" once using the button, but is also retriggered via output GPIO 22 when the display changes pages. Of course, it must also be mentioned that the time relay also consumes power when switched. However, it will still pay off quickly because the system can be switched off after, for example, 3-5 minutes and is inactive for significantly more time than active. The additional relay for retriggering also consumes a few mA per pulse. However, this is negligible as it is only switched on for a short pulse. All in all, this is probably the most energy-saving solution to allow the system to be powered by a battery for as long as possible.

Battery protection / undervoltage release

Batteries have a voltage range in which they can work optimally. Batteries that are loaded beyond their performance limit can be irreversibly damaged. Since we are using a power supply or a step-down converter and the downstream voltage is lower than the supply voltage, there is a risk of putting too much strain on the battery. To prevent this, it makes sense to install an undervoltage release between the battery and the time relay. This can set a hysteresis, for example: switching on at 12.1V and switching off at 11.5V. Good, fully charged car batteries usually have more than 12.3V. Discharged and heavily loaded batteries show less than 12V and can drop significantly. If they are subjected to further loads below 10V, they can even be damaged. Therefore, reliable load disconnection is crucial. Only when the battery is replaced or recharged will the voltage be released again. Unfortunately, the consumption is not exactly small at 0.44 watts (cheap measuring device!!). Since this is a protective circuit, we can’t get around it. Unless we use a battery or something similar that protects itself, for example a USB power pack.

The components

Time relay (1): Make Hilitand, Type Yosoo-1322, ASIN B01N6QGSRK. You can get it e.g. from Amazon. With jumper bridges for range selection and a potentiometer the adjustment is really easy. You can find the double relay (2) e.g. here. Unfortunately only one of the small 4-pin connectors is included. If you want to order some, they are called JST 1.25 MM 4 pins. Undervoltage release (3) as battery protection: Amazon oder AliExpress. [ Power supply or step-down converter (4): Amazon / AliExpress. ] -> Better alternative, see later (6). The power supply for setting the undervoltage release (5): Amazon / AliExpress. Alternative step-down converter with integrated display for checking (6): Amazon / AliExpress. The module can be used to check the battery voltage and display and set the output voltage (turn the potentiometer to the left for less than 12V). The display can also be switched off with the button. Note the polarity of the battery!

Images and graphics for illustrative purposes: