Ereignishorizont
LightningATM

LightningATM

1. Project Basics

Below is additional documentation you can look at, though not required for implementation:

Recommended tools:

  • Flathead screwdriver, multimeter, side cutters, double-sided tape (thick/thin), electrical tape, needle-nose pliers, hot glue, magnifying glass, terminal blocks, soldering iron (if available)

Just follow the instructions step by step, and you’ll reach your goal quickly.

2. Hardware Preparation

2.1 Preparing the Voltage Converter

  • Cut the Micro USB cable about 15 cm from the Micro USB plug
  • Strip both ends and solder them together in parallel (++ / –), if you have a soldering iron
  • Connect both ends to the input of the voltage converter and screw them in place
  • Plug the USB connector into a power adapter or USB power pack
  • Connect a voltmeter to the output side
  • Use a screwdriver to turn the small potentiometer (see image) several times (probably to the left) until the voltage reads 12.1 volts
  • Warning: The initial voltage can be very high. Mine was 35 volts. So do not connect it directly to the coin validator and set the meter to the correct measurement range
  • Prepare the wiring for the output side:
  • Connect positive and negative (GND) from the voltage converter to the coin validator
  • Connect one wire from the GND of the voltage converter to pin 25 of the Raspberry Pi
  • See the wiring diagram below the images

2.2 Configure the coin validator (6 types, 5 cents to 2 euros)

  • Set the switch on the coin validator to “NO” and “Medium”
  • Apply 12V to the coin validator (without the Raspberry Pi)
  • Press and hold the ADD and MINUS buttons at the same time until “A” appears on the display
  • If “B” appears, press a button again to switch back to “A”
  • Press and briefly hold the SET button, then “E” appears on the display
  • This indicates that you are now in the menu for setting the number of different coin types
  • Use ADD (or MINUS) to set it to 6 (coins = 5 cents to 2 euros) and press SET
  • The display now shows “H1” (for the first coin), and the first of 6 LEDs has lit up
  • Now specify how many times the coin should be inserted for calibration
  • Use ADD (or MINUS) to set to 20, then press SET
  • The display now shows P1 for further settings of coin 1, and the output signal can be defined
  • 5 cents = 2 pulses / 10 cents = 3 / 20 cents = 4 / 50 cents = 5 / 1 euro = 6 / 2 euros = 7
  • Use ADD (or MINUS) to set to 2 pulses (for 5 cents), then press SET
  • Finally, F1 appears on the display and stands for the accuracy of coin detection. A value of 8 has worked well
  • Use ADD (or MINUS) to set it to 8, then press SET
  • The parameters for the first coin are now complete, and the remaining 5 must follow
  • Now the second LED has lit up, and the display shows H2
  • Repeat the same steps again for the second through sixth coin
  • Once all coins are set, all LEDs briefly flash for confirmation, and the display shows A again
  • After a short time, the display will again show 0 (zero)

2.3 Calibrate Coin Validator with Coins

  • Press the SET button twice
  • The first LED lights up and A1 is shown on the display
  • Now insert the first coin (5 cents) 20 times
  • It’s recommended to use as many different coins of the same type as possible
  • After that, all LEDs blink briefly for confirmation and the display shows A2
  • Repeat the whole process for the remaining coins
  • All LEDs blink again briefly for confirmation and the display shows 0 (zero) again
  • The coin validator is now ready.

2.4 Wiring the Hardware

  • Wire the hardware according to the diagram (see images), but do not install it into the ATM case yet
  • Set the switches on the e-paper display HAT to A and 0
  • Be careful when inserting the thin display flat ribbon cable!
  • The clamp has a small locking mechanism that must be released first. See image!

3. Create SD Card

To flash the Raspberry Pi image, it’s best to use the official Raspberry Pi Imager. The software is quite easy to use.

On the first main screen, set the following:

Raspberry Pi Model: Raspberry Pi Zero 2 W
Operating System (OS): Raspberry Pi OS (Legacy, 32-bit)
SD Card: Your SD card

On the next page, you can make some settings. Configure the following:

Hostname: atm
Username: pi
Password: raspberry
SSID: YourWifi
Password: YourPassword

Here are a few pictures to go along with it:

You can also modify the Wi-Fi configuration file afterwards:

    sudo nano /etc/wpa_supplicant/wpa_supplicant.conf

However, the password must be generated first. You can do that with this command:

    wpa_passphrase "YourWifi" "YourPassword"

This also allows you to add a second Wi-Fi network. Simply add a second network={ .. } block with the new ssid= and psk=.

4. Perform Basic Software Setup and Updates

  • Insert the SD card into the Raspberry Pi
  • Carefully check the wiring again and then power it on
  • Wait a while and then look for the assigned Wi-Fi IP address in your Wi-Fi router
  • Login to the Raspberry Pi via CLI: ssh pi@192.168.x.x
  • Confirm The authenticity... with yes
  • When prompted for a password, enter “raspberry”
  • If you are logged in correctly, you’ll now see: pi@raspberrypi:~ $. Change the password (if desired) and make sure to remember it! $ passwd
  • Note: $ represents pi@raspberrypi:~ $ in the CLI and does not need to be typed. Enable the SPI interface for the Waveshare displays

To do that, go into raspi-config with:

    sudo raspi-config

Then select Interface Options - Configure.. -> SPI - enable/disable.. and activate it with Yes.

That’s it, now you can begin the installation.

Run an update, clone the ATM GitHub, and install required packages

    sudo apt update && sudo apt upgrade
    git clone https://github.com/21isenough/LightningATM.git
    cd LightningATM
    pip3 install -r requirements.txt
  • Note: During the update you may have to confirm with y or q occasionally
  • Now disconnect the power supply once and reconnect via SSH using the new password

5. Set Up and Test the Display

5.1 Download and Install Display Software

cd ~
git clone https://github.com/waveshare/e-Paper   
cd ~/e-Paper/RaspberryPi*/python
sudo python3 setup.py install

5.2 Test the Display

cd ~/e-Paper/RaspberryPi_JetsonNano/python/examples
sudo python3 ./epd_2in13_V2_test.py

If everything is correctly connected and installed, the display will now show a demonstration and then clear the screen.

Note: If you have a different display type, you must use a different test script instead of “epd_2in13_V2_test.py”. For example, use “epd_2in13_V3_test.py” for the newer version — check the back of the display. Or use “epd_2in13d_test.py” for the flexible (gold-colored) (D) version.

6. Configure settings via config.ini

The config.ini is used for basic settings.

  • Log in to your Raspberry Pi via CLI: ssh pi@192.168.x.x

6.1 Start the ATM once to generate config.ini

cd ~/LightningATM/
./app.py
  • At first start, you’ll see the message No display configuration matched. Exiting... because you haven’t specified a matching display yet. You can ignore this message. The config.ini we need has now been created in the background.
  • Now edit the config.ini as described below

6.2 Open the config.ini file

nano ~/.lightningATM/config.ini
  • Don’t be surprised — the path is really ~/.lightningATM/config.ini with a dot and all lowercase

6.3 Configure the config.ini file

Under [atm] specify the display type
    display = waveshare2in13v2

Note: Please check your display type. Your model may require different settings.

Delay time (set from 0 to 12 seconds. 0 is only for ATMs with button)
    payoutdelay = 12
Activate wallet types
    activewallet = lnbits
Under [lnbits] provide the interface data for the LNbits wallet
[lnbits]
# api credentials
url = https://demo.lnbits.com/api/v1
apikey = YourAdminKey
# One of "invoice" or "lnurlw"
method = lnurlw
# only for lnurlw - seconds to redeem the lnurlw
timeout = 90

Note: You only need to provide apikey = Admin key. You can get this from your LNbits wallet, for example: Admin key = apikey = 8682516eaf0c457…

Image: Example LNbits Wallet. You only need to activate the LNURLw extension (→ ENABLE).

Note: If you want to replace the obsolete LNTXBOT wallet with an LNbits wallet on an existing ATM, you will need to take a few additional steps. See the instructions for this on the original GitHub.

Assign coins to pulses
[coins]
# Pulsecount, fiat value, name
coin_types = 2,0.05,5  eur cent
             3,0.10,10 eur cent
             4,0.20,20 eur cent
             5,0.50,50 eur cent
             6,1.00,1 eur
             7,2.00,2 eur
  • To save and exit the editor: CTRL+x → y → ENTER
Test the settings (or the entire ATM)
cd ~/LightningATM/
./app.py
  • The display should now show LightningATM
  • If everything is entered correctly, the ATM should now be ready for use
  • It’s best to test it with a few cents
  • If it doesn’t work, the chapter on tmux will follow later for diagnostics
  • To stop the ATM, just press CTRL+C
  • After a short moment, Manually Interrupted will appear and the display will show that the ATM turned off

7. Debugger and Monitoring System (tmux)

The easiest way to monitor multiple processes simultaneously is to open multiple terminal windows. You could open one for “app.py” and another for the debug logger $ tail -f ~/.lightningATM/debug.log and display them side by side. But to view both processes in a single window, you can also use “tmux” (Terminal Multiplexer).

Terminal Multiplexer (tmux) Command Overview:
CTRL + b -> % = split window
CTRL + b -> arrow left/right = switch between windows
CTRL + b -> CTRL + arrow left/right = move divider
CTRL + b -> d = return to single window

This allows the CLI window to be split vertically and two processes to be monitored simultaneously → see image!

Install tmux
sudo apt install tmux
Start and use tmux
tmux
  • Split tmux window: CTRL+b → %
Start the app.py process (ATM)
cd ~/LightningATM
./app.py
  • Switch to the right window: CTRL+b → right arrow
  • Note: If the ATM is already running (check with $ sudo systemctl status LightningATM.service), you should stop it (with $ sudo systemctl stop LightningATM.service) before starting it manually (with ./app.py) in the tmux terminal. Otherwise, strange behavior may occur. Afterwards, don’t forget to restart the LightningATM service (with $ sudo systemctl start LightningATM.service). This ensures that the ATM will start automatically on next boot.
Start debug.log
tail -f ~/.lightningATM/debug.log
  • If needed, move the divider: CTRL+b → CTRL+arrow left/right
  • Return to single window: CTRL+b → d

8. Autostart

Enable:
cd ~/LightningATM
sudo cp LightningATM.service /etc/systemd/system/LightningATM.service
sudo systemctl enable LightningATM.service
sudo reboot
Additional commands to manage the service:
sudo systemctl status LightningATM.service
sudo systemctl stop LightningATM.service
sudo systemctl start LightningATM.service

9. Extension: LED Button and Lock Relay

LED Button

An LED button greatly enhances the ATM. It allows for many additional functions, improves usability, and also looks nice. I’ve put together a construction kit so you don’t even need to solder — everything is plug & play. For more info, check out my dedicated page: LED-Button-CSet

Lock Relay (electromagnetic gate)

The electromagnetic gate is a locking pin that redirects coins to the reject slot. If the coin validator is unpowered, the pin stays locked and all coins are rejected. Only after a valid coin is detected does the solenoid retract the locking pin, allowing coins to fall into the fiat vault. This gate can be externally controlled or blocked. The function can be used to prevent multiple pulses (from rapid coin insertion) or to block coin insertion during certain states (like display pause or when ATM is offline).

If you want to learn more about the lock relay, I’ve written detailed documentation in English on the GitHub page: Lock Relay

10. Well done, that’s it!

  • I hope everything worked and your ATM is running 🙂
  • For more help, join the Telegram group: https://t.me/lightningatm_building
  • If you find any errors in the documentation or have suggestions, you can reach me at:
  • Telegram: @AxelHamburch
  • Twitter: @AxelHamburch

11. A few more tips

  • When using the Command Line Interface (CLI), it’s best to copy & paste commands:
  • → Copy the command with CTRL+C, then right-click the blinking cursor in the CLI window to paste it
  • Tooltips for images can be seen when viewing the site in desktop mode — just hover over them
  • Or if you download the ZIP file with images, you’ll see the filenames as hints
  • If you get the error bash: $: command not found, it means you copied the dollar sign $ with the command
  • If you get the error bash: cd: too many arguments, you may need to go back one level using $ cd ~
    • When logging in via SSH, make sure to use the correct user pi. If you accidentally use admin or make a typo, you won’t get an error message, but the password will not be accepted.
    • You can change the Wi-Fi parameters afterwards using the following command:
    • $ sudo nano /etc/wpa_supplicant/wpa_supplicant.conf
    • If you’re prompted for a username and password while cloning a repository, try restarting your PC and Raspberry Pi. That worked for me.
    • SSH login issues on Windows: Check under Settings / Apps / Apps & Features or Optional Features to ensure OpenSSH Client AND OpenSSH Server are installed.
    • If you’re not yet comfortable with the CLI and Raspberry Pi, I recommend starting with a smaller project like the BTC-Ticker.
    • One more note: I try to keep this German-language tutorial up to date, but my priority right now is the English version on GitHub. If something isn’t clear, check here.
    • If you see: “WARNING: The script qr is installed in ‘/home/pi/.local/bin’ which is not on PATH”, run the following: echo 'export PATH=$PATH:/home/pi/.local/bin' >> ~/.bashrc and then source ~/.bashrc

    Here is the video for the tutorial:


    Created with love! 🧡 Block 720899 / 896440 updated


    1. Project Basics

    Below is additional documentation you can look at, though not required for implementation:

    Recommended tools:

    • Flathead screwdriver, multimeter, side cutters, double-sided tape (thick/thin), electrical tape, needle-nose pliers, hot glue, magnifying glass, terminal blocks, soldering iron (if available)

    Just follow the instructions step by step, and you’ll reach your goal quickly.

    2. Hardware Preparation

    2.1 Preparing the Voltage Converter

    • Cut the Micro USB cable about 15 cm from the Micro USB plug
    • Strip both ends and solder them together in parallel (++ / –), if you have a soldering iron
    • Connect both ends to the input of the voltage converter and screw them in place
    • Plug the USB connector into a power adapter or USB power pack
    • Connect a voltmeter to the output side
    • Use a screwdriver to turn the small potentiometer (see image) several times (probably to the left) until the voltage reads 12.1 volts
    • Warning: The initial voltage can be very high. Mine was 35 volts. So do not connect it directly to the coin validator and set the meter to the correct measurement range
    • Prepare the wiring for the output side:
    • Connect positive and negative (GND) from the voltage converter to the coin validator
    • Connect one wire from the GND of the voltage converter to pin 25 of the Raspberry Pi
    • See the wiring diagram below the images

    2.2 Configure the coin validator (6 types, 5 cents to 2 euros)

    • Set the switch on the coin validator to “NO” and “Medium”
    • Apply 12V to the coin validator (without the Raspberry Pi)
    • Press and hold the ADD and MINUS buttons at the same time until “A” appears on the display
    • If “B” appears, press a button again to switch back to “A”
    • Press and briefly hold the SET button, then “E” appears on the display
    • This indicates that you are now in the menu for setting the number of different coin types
    • Use ADD (or MINUS) to set it to 6 (coins = 5 cents to 2 euros) and press SET
    • The display now shows “H1” (for the first coin), and the first of 6 LEDs has lit up
    • Now specify how many times the coin should be inserted for calibration
    • Use ADD (or MINUS) to set to 20, then press SET
    • The display now shows P1 for further settings of coin 1, and the output signal can be defined
    • 5 cents = 2 pulses / 10 cents = 3 / 20 cents = 4 / 50 cents = 5 / 1 euro = 6 / 2 euros = 7
    • Use ADD (or MINUS) to set to 2 pulses (for 5 cents), then press SET
    • Finally, F1 appears on the display and stands for the accuracy of coin detection. A value of 8 has worked well
    • Use ADD (or MINUS) to set it to 8, then press SET
    • The parameters for the first coin are now complete, and the remaining 5 must follow
    • Now the second LED has lit up, and the display shows H2
    • Repeat the same steps again for the second through sixth coin
    • Once all coins are set, all LEDs briefly flash for confirmation, and the display shows A again
    • After a short time, the display will again show 0 (zero)

    2.3 Calibrate Coin Validator with Coins

    • Press the SET button twice
    • The first LED lights up and A1 is shown on the display
    • Now insert the first coin (5 cents) 20 times
    • It’s recommended to use as many different coins of the same type as possible
    • After that, all LEDs blink briefly for confirmation and the display shows A2
    • Repeat the whole process for the remaining coins
    • All LEDs blink again briefly for confirmation and the display shows 0 (zero) again
    • The coin validator is now ready.

    2.4 Wiring the Hardware

    • Wire the hardware according to the diagram (see images), but do not install it into the ATM case yet
    • Set the switches on the e-paper display HAT to A and 0
    • Be careful when inserting the thin display flat ribbon cable!
    • The clamp has a small locking mechanism that must be released first. See image!

    3. Create SD Card

    To flash the Raspberry Pi image, it’s best to use the official Raspberry Pi Imager. The software is quite easy to use.

    On the first main screen, set the following:

    Raspberry Pi Model: Raspberry Pi Zero 2 W
    Operating System (OS): Raspberry Pi OS (Legacy, 32-bit)
    SD Card: Your SD card

    On the next page, you can make some settings. Configure the following:

    Hostname: atm
    Username: pi
    Password: raspberry
    SSID: YourWifi
    Password: YourPassword

    Here are a few pictures to go along with it:

    You can also modify the Wi-Fi configuration file afterwards:

        sudo nano /etc/wpa_supplicant/wpa_supplicant.conf

    However, the password must be generated first. You can do that with this command:

        wpa_passphrase "YourWifi" "YourPassword"

    This also allows you to add a second Wi-Fi network. Simply add a second network={ .. } block with the new ssid= and psk=.

    4. Perform Basic Software Setup and Updates

    • Insert the SD card into the Raspberry Pi
    • Carefully check the wiring again and then power it on
    • Wait a while and then look for the assigned Wi-Fi IP address in your Wi-Fi router
    • Login to the Raspberry Pi via CLI: ssh pi@192.168.x.x
    • Confirm The authenticity... with yes
    • When prompted for a password, enter “raspberry”
    • If you are logged in correctly, you’ll now see: pi@raspberrypi:~ $. Change the password (if desired) and make sure to remember it! $ passwd
    • Note: $ represents pi@raspberrypi:~ $ in the CLI and does not need to be typed. Enable the SPI interface for the Waveshare displays

    To do that, go into raspi-config with:

        sudo raspi-config

    Then select Interface Options - Configure.. -> SPI - enable/disable.. and activate it with Yes.

    That’s it, now you can begin the installation.

    Run an update, clone the ATM GitHub, and install required packages

        sudo apt update && sudo apt upgrade
        git clone https://github.com/21isenough/LightningATM.git
        cd LightningATM
        pip3 install -r requirements.txt
    • Note: During the update you may have to confirm with y or q occasionally
    • Now disconnect the power supply once and reconnect via SSH using the new password

    5. Set Up and Test the Display

    5.1 Download and Install Display Software

    cd ~
    git clone https://github.com/waveshare/e-Paper   
    cd ~/e-Paper/RaspberryPi*/python
    sudo python3 setup.py install
    

    5.2 Test the Display

    cd ~/e-Paper/RaspberryPi_JetsonNano/python/examples
    sudo python3 ./epd_2in13_V2_test.py
    

    If everything is correctly connected and installed, the display will now show a demonstration and then clear the screen.

    Note: If you have a different display type, you must use a different test script instead of “epd_2in13_V2_test.py”. For example, use “epd_2in13_V3_test.py” for the newer version — check the back of the display. Or use “epd_2in13d_test.py” for the flexible (gold-colored) (D) version.

    6. Configure settings via config.ini

    The config.ini is used for basic settings.

    • Log in to your Raspberry Pi via CLI: ssh pi@192.168.x.x

    6.1 Start the ATM once to generate config.ini

    cd ~/LightningATM/
    ./app.py
    
    • At first start, you’ll see the message No display configuration matched. Exiting... because you haven’t specified a matching display yet. You can ignore this message. The config.ini we need has now been created in the background.
    • Now edit the config.ini as described below

    6.2 Open the config.ini file

    nano ~/.lightningATM/config.ini
    
    • Don’t be surprised — the path is really ~/.lightningATM/config.ini with a dot and all lowercase

    6.3 Configure the config.ini file

    Under [atm] specify the display type
        display = waveshare2in13v2
    

    Note: Please check your display type. Your model may require different settings.

    Delay time (set from 0 to 12 seconds. 0 is only for ATMs with button)
        payoutdelay = 12
    
    Activate wallet types
        activewallet = lnbits
    
    Under [lnbits] provide the interface data for the LNbits wallet
    [lnbits]
    # api credentials
    url = https://demo.lnbits.com/api/v1
    apikey = YourAdminKey
    # One of "invoice" or "lnurlw"
    method = lnurlw
    # only for lnurlw - seconds to redeem the lnurlw
    timeout = 90
    

    Note: You only need to provide apikey = Admin key. You can get this from your LNbits wallet, for example: Admin key = apikey = 8682516eaf0c457…

    Image: Example LNbits Wallet. You only need to activate the LNURLw extension (→ ENABLE).

    Note: If you want to replace the obsolete LNTXBOT wallet with an LNbits wallet on an existing ATM, you will need to take a few additional steps. See the instructions for this on the original GitHub.

    Assign coins to pulses
    [coins]
    # Pulsecount, fiat value, name
    coin_types = 2,0.05,5  eur cent
                 3,0.10,10 eur cent
                 4,0.20,20 eur cent
                 5,0.50,50 eur cent
                 6,1.00,1 eur
                 7,2.00,2 eur
    
    • To save and exit the editor: CTRL+x → y → ENTER
    Test the settings (or the entire ATM)
    cd ~/LightningATM/
    ./app.py
    
    • The display should now show LightningATM
    • If everything is entered correctly, the ATM should now be ready for use
    • It’s best to test it with a few cents
    • If it doesn’t work, the chapter on tmux will follow later for diagnostics
    • To stop the ATM, just press CTRL+C
    • After a short moment, Manually Interrupted will appear and the display will show that the ATM turned off

    7. Debugger and Monitoring System (tmux)

    The easiest way to monitor multiple processes simultaneously is to open multiple terminal windows. You could open one for “app.py” and another for the debug logger $ tail -f ~/.lightningATM/debug.log and display them side by side. But to view both processes in a single window, you can also use “tmux” (Terminal Multiplexer).

    Terminal Multiplexer (tmux) Command Overview:
    CTRL + b -> % = split window
    CTRL + b -> arrow left/right = switch between windows
    CTRL + b -> CTRL + arrow left/right = move divider
    CTRL + b -> d = return to single window
    

    This allows the CLI window to be split vertically and two processes to be monitored simultaneously → see image!

    Install tmux
    sudo apt install tmux
    
    Start and use tmux
    tmux
    
    • Split tmux window: CTRL+b → %
    Start the app.py process (ATM)
    cd ~/LightningATM
    ./app.py
    
    • Switch to the right window: CTRL+b → right arrow
    • Note: If the ATM is already running (check with $ sudo systemctl status LightningATM.service), you should stop it (with $ sudo systemctl stop LightningATM.service) before starting it manually (with ./app.py) in the tmux terminal. Otherwise, strange behavior may occur. Afterwards, don’t forget to restart the LightningATM service (with $ sudo systemctl start LightningATM.service). This ensures that the ATM will start automatically on next boot.
    Start debug.log
    tail -f ~/.lightningATM/debug.log
    
    • If needed, move the divider: CTRL+b → CTRL+arrow left/right
    • Return to single window: CTRL+b → d

    8. Autostart

    Enable:
    cd ~/LightningATM
    sudo cp LightningATM.service /etc/systemd/system/LightningATM.service
    sudo systemctl enable LightningATM.service
    sudo reboot
    
    Additional commands to manage the service:
    sudo systemctl status LightningATM.service
    sudo systemctl stop LightningATM.service
    sudo systemctl start LightningATM.service
    

    9. Extension: LED Button and Lock Relay

    LED Button

    An LED button greatly enhances the ATM. It allows for many additional functions, improves usability, and also looks nice. I’ve put together a construction kit so you don’t even need to solder — everything is plug & play. For more info, check out my dedicated page: LED-Button-CSet

    Lock Relay (electromagnetic gate)

    The electromagnetic gate is a locking pin that redirects coins to the reject slot. If the coin validator is unpowered, the pin stays locked and all coins are rejected. Only after a valid coin is detected does the solenoid retract the locking pin, allowing coins to fall into the fiat vault. This gate can be externally controlled or blocked. The function can be used to prevent multiple pulses (from rapid coin insertion) or to block coin insertion during certain states (like display pause or when ATM is offline).

    If you want to learn more about the lock relay, I’ve written detailed documentation in English on the GitHub page: Lock Relay

    10. Well done, that’s it!

    • I hope everything worked and your ATM is running 🙂
    • For more help, join the Telegram group: https://t.me/lightningatm_building
    • If you find any errors in the documentation or have suggestions, you can reach me at:
    • Telegram: @AxelHamburch
    • Twitter: @AxelHamburch

    11. A few more tips

    • When using the Command Line Interface (CLI), it’s best to copy & paste commands:
    • → Copy the command with CTRL+C, then right-click the blinking cursor in the CLI window to paste it
    • Tooltips for images can be seen when viewing the site in desktop mode — just hover over them
    • Or if you download the ZIP file with images, you’ll see the filenames as hints
    • If you get the error bash: $: command not found, it means you copied the dollar sign $ with the command
    • If you get the error bash: cd: too many arguments, you may need to go back one level using $ cd ~
      • When logging in via SSH, make sure to use the correct user pi. If you accidentally use admin or make a typo, you won’t get an error message, but the password will not be accepted.
      • You can change the Wi-Fi parameters afterwards using the following command:
      • $ sudo nano /etc/wpa_supplicant/wpa_supplicant.conf
      • If you’re prompted for a username and password while cloning a repository, try restarting your PC and Raspberry Pi. That worked for me.
      • SSH login issues on Windows: Check under Settings / Apps / Apps & Features or Optional Features to ensure OpenSSH Client AND OpenSSH Server are installed.
      • If you’re not yet comfortable with the CLI and Raspberry Pi, I recommend starting with a smaller project like the BTC-Ticker.
      • One more note: I try to keep this German-language tutorial up to date, but my priority right now is the English version on GitHub. If something isn’t clear, check here.
      • If you see: “WARNING: The script qr is installed in ‘/home/pi/.local/bin’ which is not on PATH”, run the following: echo 'export PATH=$PATH:/home/pi/.local/bin' >> ~/.bashrc and then source ~/.bashrc

      Here is the video for the tutorial:


      Created with love! 🧡 Block 720899 / 896440 updated


      Lightning ATM

      Bitcoin Lightning ATM – Pocket Edition

      This is a tutorial for the Bitcoin Lightning ATM – Pocket Edition. It’s a “Do It Yourself” project consisting of a mini computer (Raspberry Pi Zero), a coin validator, a display, a 3D-printed case, and a Bitcoin Lightning wallet as the funding source. The machine acts as a currency exchanger. It converts fiat coins into valuable Bitcoin Lightning ⚡ Satoshis 丰. The user can retrieve the Satoshis via QR code (LNURL-withdraw) to their mobile wallet. There are already good instructions, which I will reference later, but I missed a step-by-step guide specifically for this Pocket Edition with LNbits wallet integration. Connection to a BTCPay Server is also possible but not further explained here. You can purchase the components individually and build the case yourself. All necessary data can be found in the guides I’ll link to later. However, I made it easy for myself and ordered the kit from Fulmo.org. You can even pay in Bitcoin and Lightning ⚡ in the shop.

      The entire LightningATM project is based on FOSS (free and open source software) under the MIT license. I will also publish all data, images, and information from this website in the same way. You are free to copy, link, and reuse everything as you like. However, warranty and liability are excluded.

      I think the project is moderately difficult, suitable for advanced beginners who already have experience with the Command Line Interface (CLI) and the Raspberry Pi. If you’re not confident in those areas yet, I recommend starting with the DIY project BTC-Ticker. That project uses similar components and commands, though it’s a bit less complex and extensive.

      1. Project Basics

      Below is additional documentation you can look at, though not required for implementation:

      Recommended tools:

      • Flathead screwdriver, multimeter, side cutters, double-sided tape (thick/thin), electrical tape, needle-nose pliers, hot glue, magnifying glass, terminal blocks, soldering iron (if available)

      Just follow the instructions step by step, and you’ll reach your goal quickly.

      2. Hardware Preparation

      2.1 Preparing the Voltage Converter

      • Cut the Micro USB cable about 15 cm from the Micro USB plug
      • Strip both ends and solder them together in parallel (++ / –), if you have a soldering iron
      • Connect both ends to the input of the voltage converter and screw them in place
      • Plug the USB connector into a power adapter or USB power pack
      • Connect a voltmeter to the output side
      • Use a screwdriver to turn the small potentiometer (see image) several times (probably to the left) until the voltage reads 12.1 volts
      • Warning: The initial voltage can be very high. Mine was 35 volts. So do not connect it directly to the coin validator and set the meter to the correct measurement range
      • Prepare the wiring for the output side:
      • Connect positive and negative (GND) from the voltage converter to the coin validator
      • Connect one wire from the GND of the voltage converter to pin 25 of the Raspberry Pi
      • See the wiring diagram below the images

      2.2 Configure the coin validator (6 types, 5 cents to 2 euros)

      • Set the switch on the coin validator to “NO” and “Medium”
      • Apply 12V to the coin validator (without the Raspberry Pi)
      • Press and hold the ADD and MINUS buttons at the same time until “A” appears on the display
      • If “B” appears, press a button again to switch back to “A”
      • Press and briefly hold the SET button, then “E” appears on the display
      • This indicates that you are now in the menu for setting the number of different coin types
      • Use ADD (or MINUS) to set it to 6 (coins = 5 cents to 2 euros) and press SET
      • The display now shows “H1” (for the first coin), and the first of 6 LEDs has lit up
      • Now specify how many times the coin should be inserted for calibration
      • Use ADD (or MINUS) to set to 20, then press SET
      • The display now shows P1 for further settings of coin 1, and the output signal can be defined
      • 5 cents = 2 pulses / 10 cents = 3 / 20 cents = 4 / 50 cents = 5 / 1 euro = 6 / 2 euros = 7
      • Use ADD (or MINUS) to set to 2 pulses (for 5 cents), then press SET
      • Finally, F1 appears on the display and stands for the accuracy of coin detection. A value of 8 has worked well
      • Use ADD (or MINUS) to set it to 8, then press SET
      • The parameters for the first coin are now complete, and the remaining 5 must follow
      • Now the second LED has lit up, and the display shows H2
      • Repeat the same steps again for the second through sixth coin
      • Once all coins are set, all LEDs briefly flash for confirmation, and the display shows A again
      • After a short time, the display will again show 0 (zero)

      2.3 Calibrate Coin Validator with Coins

      • Press the SET button twice
      • The first LED lights up and A1 is shown on the display
      • Now insert the first coin (5 cents) 20 times
      • It’s recommended to use as many different coins of the same type as possible
      • After that, all LEDs blink briefly for confirmation and the display shows A2
      • Repeat the whole process for the remaining coins
      • All LEDs blink again briefly for confirmation and the display shows 0 (zero) again
      • The coin validator is now ready.

      2.4 Wiring the Hardware

      • Wire the hardware according to the diagram (see images), but do not install it into the ATM case yet
      • Set the switches on the e-paper display HAT to A and 0
      • Be careful when inserting the thin display flat ribbon cable!
      • The clamp has a small locking mechanism that must be released first. See image!

      3. Create SD Card

      To flash the Raspberry Pi image, it’s best to use the official Raspberry Pi Imager. The software is quite easy to use.

      On the first main screen, set the following:

      Raspberry Pi Model: Raspberry Pi Zero 2 W
      Operating System (OS): Raspberry Pi OS (Legacy, 32-bit)
      SD Card: Your SD card

      On the next page, you can make some settings. Configure the following:

      Hostname: atm
      Username: pi
      Password: raspberry
      SSID: YourWifi
      Password: YourPassword

      Here are a few pictures to go along with it:

      You can also modify the Wi-Fi configuration file afterwards:

          sudo nano /etc/wpa_supplicant/wpa_supplicant.conf

      However, the password must be generated first. You can do that with this command:

          wpa_passphrase "YourWifi" "YourPassword"

      This also allows you to add a second Wi-Fi network. Simply add a second network={ .. } block with the new ssid= and psk=.

      4. Perform Basic Software Setup and Updates

      • Insert the SD card into the Raspberry Pi
      • Carefully check the wiring again and then power it on
      • Wait a while and then look for the assigned Wi-Fi IP address in your Wi-Fi router
      • Login to the Raspberry Pi via CLI: ssh pi@192.168.x.x
      • Confirm The authenticity... with yes
      • When prompted for a password, enter “raspberry”
      • If you are logged in correctly, you’ll now see: pi@raspberrypi:~ $. Change the password (if desired) and make sure to remember it! $ passwd
      • Note: $ represents pi@raspberrypi:~ $ in the CLI and does not need to be typed. Enable the SPI interface for the Waveshare displays

      To do that, go into raspi-config with:

          sudo raspi-config

      Then select Interface Options - Configure.. -> SPI - enable/disable.. and activate it with Yes.

      That’s it, now you can begin the installation.

      Run an update, clone the ATM GitHub, and install required packages

          sudo apt update && sudo apt upgrade
          git clone https://github.com/21isenough/LightningATM.git
          cd LightningATM
          pip3 install -r requirements.txt
      • Note: During the update you may have to confirm with y or q occasionally
      • Now disconnect the power supply once and reconnect via SSH using the new password

      5. Set Up and Test the Display

      5.1 Download and Install Display Software

      cd ~
      git clone https://github.com/waveshare/e-Paper   
      cd ~/e-Paper/RaspberryPi*/python
      sudo python3 setup.py install
      

      5.2 Test the Display

      cd ~/e-Paper/RaspberryPi_JetsonNano/python/examples
      sudo python3 ./epd_2in13_V2_test.py
      

      If everything is correctly connected and installed, the display will now show a demonstration and then clear the screen.

      Note: If you have a different display type, you must use a different test script instead of “epd_2in13_V2_test.py”. For example, use “epd_2in13_V3_test.py” for the newer version — check the back of the display. Or use “epd_2in13d_test.py” for the flexible (gold-colored) (D) version.

      6. Configure settings via config.ini

      The config.ini is used for basic settings.

      • Log in to your Raspberry Pi via CLI: ssh pi@192.168.x.x

      6.1 Start the ATM once to generate config.ini

      cd ~/LightningATM/
      ./app.py
      
      • At first start, you’ll see the message No display configuration matched. Exiting... because you haven’t specified a matching display yet. You can ignore this message. The config.ini we need has now been created in the background.
      • Now edit the config.ini as described below

      6.2 Open the config.ini file

      nano ~/.lightningATM/config.ini
      
      • Don’t be surprised — the path is really ~/.lightningATM/config.ini with a dot and all lowercase

      6.3 Configure the config.ini file

      Under [atm] specify the display type
          display = waveshare2in13v2
      

      Note: Please check your display type. Your model may require different settings.

      Delay time (set from 0 to 12 seconds. 0 is only for ATMs with button)
          payoutdelay = 12
      
      Activate wallet types
          activewallet = lnbits
      
      Under [lnbits] provide the interface data for the LNbits wallet
      [lnbits]
      # api credentials
      url = https://demo.lnbits.com/api/v1
      apikey = YourAdminKey
      # One of "invoice" or "lnurlw"
      method = lnurlw
      # only for lnurlw - seconds to redeem the lnurlw
      timeout = 90
      

      Note: You only need to provide apikey = Admin key. You can get this from your LNbits wallet, for example: Admin key = apikey = 8682516eaf0c457…

      Image: Example LNbits Wallet. You only need to activate the LNURLw extension (→ ENABLE).

      Note: If you want to replace the obsolete LNTXBOT wallet with an LNbits wallet on an existing ATM, you will need to take a few additional steps. See the instructions for this on the original GitHub.

      Assign coins to pulses
      [coins]
      # Pulsecount, fiat value, name
      coin_types = 2,0.05,5  eur cent
                   3,0.10,10 eur cent
                   4,0.20,20 eur cent
                   5,0.50,50 eur cent
                   6,1.00,1 eur
                   7,2.00,2 eur
      
      • To save and exit the editor: CTRL+x → y → ENTER
      Test the settings (or the entire ATM)
      cd ~/LightningATM/
      ./app.py
      
      • The display should now show LightningATM
      • If everything is entered correctly, the ATM should now be ready for use
      • It’s best to test it with a few cents
      • If it doesn’t work, the chapter on tmux will follow later for diagnostics
      • To stop the ATM, just press CTRL+C
      • After a short moment, Manually Interrupted will appear and the display will show that the ATM turned off

      7. Debugger and Monitoring System (tmux)

      The easiest way to monitor multiple processes simultaneously is to open multiple terminal windows. You could open one for “app.py” and another for the debug logger $ tail -f ~/.lightningATM/debug.log and display them side by side. But to view both processes in a single window, you can also use “tmux” (Terminal Multiplexer).

      Terminal Multiplexer (tmux) Command Overview:
      CTRL + b -> % = split window
      CTRL + b -> arrow left/right = switch between windows
      CTRL + b -> CTRL + arrow left/right = move divider
      CTRL + b -> d = return to single window
      

      This allows the CLI window to be split vertically and two processes to be monitored simultaneously → see image!

      Install tmux
      sudo apt install tmux
      
      Start and use tmux
      tmux
      
      • Split tmux window: CTRL+b → %
      Start the app.py process (ATM)
      cd ~/LightningATM
      ./app.py
      
      • Switch to the right window: CTRL+b → right arrow
      • Note: If the ATM is already running (check with $ sudo systemctl status LightningATM.service), you should stop it (with $ sudo systemctl stop LightningATM.service) before starting it manually (with ./app.py) in the tmux terminal. Otherwise, strange behavior may occur. Afterwards, don’t forget to restart the LightningATM service (with $ sudo systemctl start LightningATM.service). This ensures that the ATM will start automatically on next boot.
      Start debug.log
      tail -f ~/.lightningATM/debug.log
      
      • If needed, move the divider: CTRL+b → CTRL+arrow left/right
      • Return to single window: CTRL+b → d

      8. Autostart

      Enable:
      cd ~/LightningATM
      sudo cp LightningATM.service /etc/systemd/system/LightningATM.service
      sudo systemctl enable LightningATM.service
      sudo reboot
      
      Additional commands to manage the service:
      sudo systemctl status LightningATM.service
      sudo systemctl stop LightningATM.service
      sudo systemctl start LightningATM.service
      

      9. Extension: LED Button and Lock Relay

      LED Button

      An LED button greatly enhances the ATM. It allows for many additional functions, improves usability, and also looks nice. I’ve put together a construction kit so you don’t even need to solder — everything is plug & play. For more info, check out my dedicated page: LED-Button-CSet

      Lock Relay (electromagnetic gate)

      The electromagnetic gate is a locking pin that redirects coins to the reject slot. If the coin validator is unpowered, the pin stays locked and all coins are rejected. Only after a valid coin is detected does the solenoid retract the locking pin, allowing coins to fall into the fiat vault. This gate can be externally controlled or blocked. The function can be used to prevent multiple pulses (from rapid coin insertion) or to block coin insertion during certain states (like display pause or when ATM is offline).

      If you want to learn more about the lock relay, I’ve written detailed documentation in English on the GitHub page: Lock Relay

      10. Well done, that’s it!

      • I hope everything worked and your ATM is running 🙂
      • For more help, join the Telegram group: https://t.me/lightningatm_building
      • If you find any errors in the documentation or have suggestions, you can reach me at:
      • Telegram: @AxelHamburch
      • Twitter: @AxelHamburch

      11. A few more tips

      • When using the Command Line Interface (CLI), it’s best to copy & paste commands:
      • → Copy the command with CTRL+C, then right-click the blinking cursor in the CLI window to paste it
      • Tooltips for images can be seen when viewing the site in desktop mode — just hover over them
      • Or if you download the ZIP file with images, you’ll see the filenames as hints
      • If you get the error bash: $: command not found, it means you copied the dollar sign $ with the command
      • If you get the error bash: cd: too many arguments, you may need to go back one level using $ cd ~
        • When logging in via SSH, make sure to use the correct user pi. If you accidentally use admin or make a typo, you won’t get an error message, but the password will not be accepted.
        • You can change the Wi-Fi parameters afterwards using the following command:
        • $ sudo nano /etc/wpa_supplicant/wpa_supplicant.conf
        • If you’re prompted for a username and password while cloning a repository, try restarting your PC and Raspberry Pi. That worked for me.
        • SSH login issues on Windows: Check under Settings / Apps / Apps & Features or Optional Features to ensure OpenSSH Client AND OpenSSH Server are installed.
        • If you’re not yet comfortable with the CLI and Raspberry Pi, I recommend starting with a smaller project like the BTC-Ticker.
        • One more note: I try to keep this German-language tutorial up to date, but my priority right now is the English version on GitHub. If something isn’t clear, check here.
        • If you see: “WARNING: The script qr is installed in ‘/home/pi/.local/bin’ which is not on PATH”, run the following: echo 'export PATH=$PATH:/home/pi/.local/bin' >> ~/.bashrc and then source ~/.bashrc

        Here is the video for the tutorial:


        Created with love! 🧡 Block 720899 / 896440 updated


        1. Project Basics

        Below is additional documentation you can look at, though not required for implementation:

        Recommended tools:

        • Flathead screwdriver, multimeter, side cutters, double-sided tape (thick/thin), electrical tape, needle-nose pliers, hot glue, magnifying glass, terminal blocks, soldering iron (if available)

        Just follow the instructions step by step, and you’ll reach your goal quickly.

        2. Hardware Preparation

        2.1 Preparing the Voltage Converter

        • Cut the Micro USB cable about 15 cm from the Micro USB plug
        • Strip both ends and solder them together in parallel (++ / –), if you have a soldering iron
        • Connect both ends to the input of the voltage converter and screw them in place
        • Plug the USB connector into a power adapter or USB power pack
        • Connect a voltmeter to the output side
        • Use a screwdriver to turn the small potentiometer (see image) several times (probably to the left) until the voltage reads 12.1 volts
        • Warning: The initial voltage can be very high. Mine was 35 volts. So do not connect it directly to the coin validator and set the meter to the correct measurement range
        • Prepare the wiring for the output side:
        • Connect positive and negative (GND) from the voltage converter to the coin validator
        • Connect one wire from the GND of the voltage converter to pin 25 of the Raspberry Pi
        • See the wiring diagram below the images

        2.2 Configure the coin validator (6 types, 5 cents to 2 euros)

        • Set the switch on the coin validator to “NO” and “Medium”
        • Apply 12V to the coin validator (without the Raspberry Pi)
        • Press and hold the ADD and MINUS buttons at the same time until “A” appears on the display
        • If “B” appears, press a button again to switch back to “A”
        • Press and briefly hold the SET button, then “E” appears on the display
        • This indicates that you are now in the menu for setting the number of different coin types
        • Use ADD (or MINUS) to set it to 6 (coins = 5 cents to 2 euros) and press SET
        • The display now shows “H1” (for the first coin), and the first of 6 LEDs has lit up
        • Now specify how many times the coin should be inserted for calibration
        • Use ADD (or MINUS) to set to 20, then press SET
        • The display now shows P1 for further settings of coin 1, and the output signal can be defined
        • 5 cents = 2 pulses / 10 cents = 3 / 20 cents = 4 / 50 cents = 5 / 1 euro = 6 / 2 euros = 7
        • Use ADD (or MINUS) to set to 2 pulses (for 5 cents), then press SET
        • Finally, F1 appears on the display and stands for the accuracy of coin detection. A value of 8 has worked well
        • Use ADD (or MINUS) to set it to 8, then press SET
        • The parameters for the first coin are now complete, and the remaining 5 must follow
        • Now the second LED has lit up, and the display shows H2
        • Repeat the same steps again for the second through sixth coin
        • Once all coins are set, all LEDs briefly flash for confirmation, and the display shows A again
        • After a short time, the display will again show 0 (zero)

        2.3 Calibrate Coin Validator with Coins

        • Press the SET button twice
        • The first LED lights up and A1 is shown on the display
        • Now insert the first coin (5 cents) 20 times
        • It’s recommended to use as many different coins of the same type as possible
        • After that, all LEDs blink briefly for confirmation and the display shows A2
        • Repeat the whole process for the remaining coins
        • All LEDs blink again briefly for confirmation and the display shows 0 (zero) again
        • The coin validator is now ready.

        2.4 Wiring the Hardware

        • Wire the hardware according to the diagram (see images), but do not install it into the ATM case yet
        • Set the switches on the e-paper display HAT to A and 0
        • Be careful when inserting the thin display flat ribbon cable!
        • The clamp has a small locking mechanism that must be released first. See image!

        3. Create SD Card

        To flash the Raspberry Pi image, it’s best to use the official Raspberry Pi Imager. The software is quite easy to use.

        On the first main screen, set the following:

        Raspberry Pi Model: Raspberry Pi Zero 2 W
        Operating System (OS): Raspberry Pi OS (Legacy, 32-bit)
        SD Card: Your SD card

        On the next page, you can make some settings. Configure the following:

        Hostname: atm
        Username: pi
        Password: raspberry
        SSID: YourWifi
        Password: YourPassword

        Here are a few pictures to go along with it:

        You can also modify the Wi-Fi configuration file afterwards:

            sudo nano /etc/wpa_supplicant/wpa_supplicant.conf

        However, the password must be generated first. You can do that with this command:

            wpa_passphrase "YourWifi" "YourPassword"

        This also allows you to add a second Wi-Fi network. Simply add a second network={ .. } block with the new ssid= and psk=.

        4. Perform Basic Software Setup and Updates

        • Insert the SD card into the Raspberry Pi
        • Carefully check the wiring again and then power it on
        • Wait a while and then look for the assigned Wi-Fi IP address in your Wi-Fi router
        • Login to the Raspberry Pi via CLI: ssh pi@192.168.x.x
        • Confirm The authenticity... with yes
        • When prompted for a password, enter “raspberry”
        • If you are logged in correctly, you’ll now see: pi@raspberrypi:~ $. Change the password (if desired) and make sure to remember it! $ passwd
        • Note: $ represents pi@raspberrypi:~ $ in the CLI and does not need to be typed. Enable the SPI interface for the Waveshare displays

        To do that, go into raspi-config with:

            sudo raspi-config

        Then select Interface Options - Configure.. -> SPI - enable/disable.. and activate it with Yes.

        That’s it, now you can begin the installation.

        Run an update, clone the ATM GitHub, and install required packages

            sudo apt update && sudo apt upgrade
            git clone https://github.com/21isenough/LightningATM.git
            cd LightningATM
            pip3 install -r requirements.txt
        • Note: During the update you may have to confirm with y or q occasionally
        • Now disconnect the power supply once and reconnect via SSH using the new password

        5. Set Up and Test the Display

        5.1 Download and Install Display Software

        cd ~
        git clone https://github.com/waveshare/e-Paper   
        cd ~/e-Paper/RaspberryPi*/python
        sudo python3 setup.py install
        

        5.2 Test the Display

        cd ~/e-Paper/RaspberryPi_JetsonNano/python/examples
        sudo python3 ./epd_2in13_V2_test.py
        

        If everything is correctly connected and installed, the display will now show a demonstration and then clear the screen.

        Note: If you have a different display type, you must use a different test script instead of “epd_2in13_V2_test.py”. For example, use “epd_2in13_V3_test.py” for the newer version — check the back of the display. Or use “epd_2in13d_test.py” for the flexible (gold-colored) (D) version.

        6. Configure settings via config.ini

        The config.ini is used for basic settings.

        • Log in to your Raspberry Pi via CLI: ssh pi@192.168.x.x

        6.1 Start the ATM once to generate config.ini

        cd ~/LightningATM/
        ./app.py
        
        • At first start, you’ll see the message No display configuration matched. Exiting... because you haven’t specified a matching display yet. You can ignore this message. The config.ini we need has now been created in the background.
        • Now edit the config.ini as described below

        6.2 Open the config.ini file

        nano ~/.lightningATM/config.ini
        
        • Don’t be surprised — the path is really ~/.lightningATM/config.ini with a dot and all lowercase

        6.3 Configure the config.ini file

        Under [atm] specify the display type
            display = waveshare2in13v2
        

        Note: Please check your display type. Your model may require different settings.

        Delay time (set from 0 to 12 seconds. 0 is only for ATMs with button)
            payoutdelay = 12
        
        Activate wallet types
            activewallet = lnbits
        
        Under [lnbits] provide the interface data for the LNbits wallet
        [lnbits]
        # api credentials
        url = https://demo.lnbits.com/api/v1
        apikey = YourAdminKey
        # One of "invoice" or "lnurlw"
        method = lnurlw
        # only for lnurlw - seconds to redeem the lnurlw
        timeout = 90
        

        Note: You only need to provide apikey = Admin key. You can get this from your LNbits wallet, for example: Admin key = apikey = 8682516eaf0c457…

        Image: Example LNbits Wallet. You only need to activate the LNURLw extension (→ ENABLE).

        Note: If you want to replace the obsolete LNTXBOT wallet with an LNbits wallet on an existing ATM, you will need to take a few additional steps. See the instructions for this on the original GitHub.

        Assign coins to pulses
        [coins]
        # Pulsecount, fiat value, name
        coin_types = 2,0.05,5  eur cent
                     3,0.10,10 eur cent
                     4,0.20,20 eur cent
                     5,0.50,50 eur cent
                     6,1.00,1 eur
                     7,2.00,2 eur
        
        • To save and exit the editor: CTRL+x → y → ENTER
        Test the settings (or the entire ATM)
        cd ~/LightningATM/
        ./app.py
        
        • The display should now show LightningATM
        • If everything is entered correctly, the ATM should now be ready for use
        • It’s best to test it with a few cents
        • If it doesn’t work, the chapter on tmux will follow later for diagnostics
        • To stop the ATM, just press CTRL+C
        • After a short moment, Manually Interrupted will appear and the display will show that the ATM turned off

        7. Debugger and Monitoring System (tmux)

        The easiest way to monitor multiple processes simultaneously is to open multiple terminal windows. You could open one for “app.py” and another for the debug logger $ tail -f ~/.lightningATM/debug.log and display them side by side. But to view both processes in a single window, you can also use “tmux” (Terminal Multiplexer).

        Terminal Multiplexer (tmux) Command Overview:
        CTRL + b -> % = split window
        CTRL + b -> arrow left/right = switch between windows
        CTRL + b -> CTRL + arrow left/right = move divider
        CTRL + b -> d = return to single window
        

        This allows the CLI window to be split vertically and two processes to be monitored simultaneously → see image!

        Install tmux
        sudo apt install tmux
        
        Start and use tmux
        tmux
        
        • Split tmux window: CTRL+b → %
        Start the app.py process (ATM)
        cd ~/LightningATM
        ./app.py
        
        • Switch to the right window: CTRL+b → right arrow
        • Note: If the ATM is already running (check with $ sudo systemctl status LightningATM.service), you should stop it (with $ sudo systemctl stop LightningATM.service) before starting it manually (with ./app.py) in the tmux terminal. Otherwise, strange behavior may occur. Afterwards, don’t forget to restart the LightningATM service (with $ sudo systemctl start LightningATM.service). This ensures that the ATM will start automatically on next boot.
        Start debug.log
        tail -f ~/.lightningATM/debug.log
        
        • If needed, move the divider: CTRL+b → CTRL+arrow left/right
        • Return to single window: CTRL+b → d

        8. Autostart

        Enable:
        cd ~/LightningATM
        sudo cp LightningATM.service /etc/systemd/system/LightningATM.service
        sudo systemctl enable LightningATM.service
        sudo reboot
        
        Additional commands to manage the service:
        sudo systemctl status LightningATM.service
        sudo systemctl stop LightningATM.service
        sudo systemctl start LightningATM.service
        

        9. Extension: LED Button and Lock Relay

        LED Button

        An LED button greatly enhances the ATM. It allows for many additional functions, improves usability, and also looks nice. I’ve put together a construction kit so you don’t even need to solder — everything is plug & play. For more info, check out my dedicated page: LED-Button-CSet

        Lock Relay (electromagnetic gate)

        The electromagnetic gate is a locking pin that redirects coins to the reject slot. If the coin validator is unpowered, the pin stays locked and all coins are rejected. Only after a valid coin is detected does the solenoid retract the locking pin, allowing coins to fall into the fiat vault. This gate can be externally controlled or blocked. The function can be used to prevent multiple pulses (from rapid coin insertion) or to block coin insertion during certain states (like display pause or when ATM is offline).

        If you want to learn more about the lock relay, I’ve written detailed documentation in English on the GitHub page: Lock Relay

        10. Well done, that’s it!

        • I hope everything worked and your ATM is running 🙂
        • For more help, join the Telegram group: https://t.me/lightningatm_building
        • If you find any errors in the documentation or have suggestions, you can reach me at:
        • Telegram: @AxelHamburch
        • Twitter: @AxelHamburch

        11. A few more tips

        • When using the Command Line Interface (CLI), it’s best to copy & paste commands:
        • → Copy the command with CTRL+C, then right-click the blinking cursor in the CLI window to paste it
        • Tooltips for images can be seen when viewing the site in desktop mode — just hover over them
        • Or if you download the ZIP file with images, you’ll see the filenames as hints
        • If you get the error bash: $: command not found, it means you copied the dollar sign $ with the command
        • If you get the error bash: cd: too many arguments, you may need to go back one level using $ cd ~
          • When logging in via SSH, make sure to use the correct user pi. If you accidentally use admin or make a typo, you won’t get an error message, but the password will not be accepted.
          • You can change the Wi-Fi parameters afterwards using the following command:
          • $ sudo nano /etc/wpa_supplicant/wpa_supplicant.conf
          • If you’re prompted for a username and password while cloning a repository, try restarting your PC and Raspberry Pi. That worked for me.
          • SSH login issues on Windows: Check under Settings / Apps / Apps & Features or Optional Features to ensure OpenSSH Client AND OpenSSH Server are installed.
          • If you’re not yet comfortable with the CLI and Raspberry Pi, I recommend starting with a smaller project like the BTC-Ticker.
          • One more note: I try to keep this German-language tutorial up to date, but my priority right now is the English version on GitHub. If something isn’t clear, check here.
          • If you see: “WARNING: The script qr is installed in ‘/home/pi/.local/bin’ which is not on PATH”, run the following: echo 'export PATH=$PATH:/home/pi/.local/bin' >> ~/.bashrc and then source ~/.bashrc

          Here is the video for the tutorial:


          Created with love! 🧡 Block 720899 / 896440 updated


          Lightning ATM

          Bitcoin Lightning ATM – Pocket Edition

          This is a tutorial for the Bitcoin Lightning ATM – Pocket Edition. It’s a “Do It Yourself” project consisting of a mini computer (Raspberry Pi Zero), a coin validator, a display, a 3D-printed case, and a Bitcoin Lightning wallet as the funding source. The machine acts as a currency exchanger. It converts fiat coins into valuable Bitcoin Lightning ⚡ Satoshis 丰. The user can retrieve the Satoshis via QR code (LNURL-withdraw) to their mobile wallet. There are already good instructions, which I will reference later, but I missed a step-by-step guide specifically for this Pocket Edition with LNbits wallet integration. Connection to a BTCPay Server is also possible but not further explained here. You can purchase the components individually and build the case yourself. All necessary data can be found in the guides I’ll link to later. However, I made it easy for myself and ordered the kit from Fulmo.org. You can even pay in Bitcoin and Lightning ⚡ in the shop.

          The entire LightningATM project is based on FOSS (free and open source software) under the MIT license. I will also publish all data, images, and information from this website in the same way. You are free to copy, link, and reuse everything as you like. However, warranty and liability are excluded.

          I think the project is moderately difficult, suitable for advanced beginners who already have experience with the Command Line Interface (CLI) and the Raspberry Pi. If you’re not confident in those areas yet, I recommend starting with the DIY project BTC-Ticker. That project uses similar components and commands, though it’s a bit less complex and extensive.

          1. Project Basics

          Below is additional documentation you can look at, though not required for implementation:

          Recommended tools:

          • Flathead screwdriver, multimeter, side cutters, double-sided tape (thick/thin), electrical tape, needle-nose pliers, hot glue, magnifying glass, terminal blocks, soldering iron (if available)

          Just follow the instructions step by step, and you’ll reach your goal quickly.

          2. Hardware Preparation

          2.1 Preparing the Voltage Converter

          • Cut the Micro USB cable about 15 cm from the Micro USB plug
          • Strip both ends and solder them together in parallel (++ / –), if you have a soldering iron
          • Connect both ends to the input of the voltage converter and screw them in place
          • Plug the USB connector into a power adapter or USB power pack
          • Connect a voltmeter to the output side
          • Use a screwdriver to turn the small potentiometer (see image) several times (probably to the left) until the voltage reads 12.1 volts
          • Warning: The initial voltage can be very high. Mine was 35 volts. So do not connect it directly to the coin validator and set the meter to the correct measurement range
          • Prepare the wiring for the output side:
          • Connect positive and negative (GND) from the voltage converter to the coin validator
          • Connect one wire from the GND of the voltage converter to pin 25 of the Raspberry Pi
          • See the wiring diagram below the images

          2.2 Configure the coin validator (6 types, 5 cents to 2 euros)

          • Set the switch on the coin validator to “NO” and “Medium”
          • Apply 12V to the coin validator (without the Raspberry Pi)
          • Press and hold the ADD and MINUS buttons at the same time until “A” appears on the display
          • If “B” appears, press a button again to switch back to “A”
          • Press and briefly hold the SET button, then “E” appears on the display
          • This indicates that you are now in the menu for setting the number of different coin types
          • Use ADD (or MINUS) to set it to 6 (coins = 5 cents to 2 euros) and press SET
          • The display now shows “H1” (for the first coin), and the first of 6 LEDs has lit up
          • Now specify how many times the coin should be inserted for calibration
          • Use ADD (or MINUS) to set to 20, then press SET
          • The display now shows P1 for further settings of coin 1, and the output signal can be defined
          • 5 cents = 2 pulses / 10 cents = 3 / 20 cents = 4 / 50 cents = 5 / 1 euro = 6 / 2 euros = 7
          • Use ADD (or MINUS) to set to 2 pulses (for 5 cents), then press SET
          • Finally, F1 appears on the display and stands for the accuracy of coin detection. A value of 8 has worked well
          • Use ADD (or MINUS) to set it to 8, then press SET
          • The parameters for the first coin are now complete, and the remaining 5 must follow
          • Now the second LED has lit up, and the display shows H2
          • Repeat the same steps again for the second through sixth coin
          • Once all coins are set, all LEDs briefly flash for confirmation, and the display shows A again
          • After a short time, the display will again show 0 (zero)

          2.3 Calibrate Coin Validator with Coins

          • Press the SET button twice
          • The first LED lights up and A1 is shown on the display
          • Now insert the first coin (5 cents) 20 times
          • It’s recommended to use as many different coins of the same type as possible
          • After that, all LEDs blink briefly for confirmation and the display shows A2
          • Repeat the whole process for the remaining coins
          • All LEDs blink again briefly for confirmation and the display shows 0 (zero) again
          • The coin validator is now ready.

          2.4 Wiring the Hardware

          • Wire the hardware according to the diagram (see images), but do not install it into the ATM case yet
          • Set the switches on the e-paper display HAT to A and 0
          • Be careful when inserting the thin display flat ribbon cable!
          • The clamp has a small locking mechanism that must be released first. See image!

          3. Create SD Card

          To flash the Raspberry Pi image, it’s best to use the official Raspberry Pi Imager. The software is quite easy to use.

          On the first main screen, set the following:

          Raspberry Pi Model: Raspberry Pi Zero 2 W
          Operating System (OS): Raspberry Pi OS (Legacy, 32-bit)
          SD Card: Your SD card

          On the next page, you can make some settings. Configure the following:

          Hostname: atm
          Username: pi
          Password: raspberry
          SSID: YourWifi
          Password: YourPassword

          Here are a few pictures to go along with it:

          You can also modify the Wi-Fi configuration file afterwards:

              sudo nano /etc/wpa_supplicant/wpa_supplicant.conf

          However, the password must be generated first. You can do that with this command:

              wpa_passphrase "YourWifi" "YourPassword"

          This also allows you to add a second Wi-Fi network. Simply add a second network={ .. } block with the new ssid= and psk=.

          4. Perform Basic Software Setup and Updates

          • Insert the SD card into the Raspberry Pi
          • Carefully check the wiring again and then power it on
          • Wait a while and then look for the assigned Wi-Fi IP address in your Wi-Fi router
          • Login to the Raspberry Pi via CLI: ssh pi@192.168.x.x
          • Confirm The authenticity... with yes
          • When prompted for a password, enter “raspberry”
          • If you are logged in correctly, you’ll now see: pi@raspberrypi:~ $. Change the password (if desired) and make sure to remember it! $ passwd
          • Note: $ represents pi@raspberrypi:~ $ in the CLI and does not need to be typed. Enable the SPI interface for the Waveshare displays

          To do that, go into raspi-config with:

              sudo raspi-config

          Then select Interface Options - Configure.. -> SPI - enable/disable.. and activate it with Yes.

          That’s it, now you can begin the installation.

          Run an update, clone the ATM GitHub, and install required packages

              sudo apt update && sudo apt upgrade
              git clone https://github.com/21isenough/LightningATM.git
              cd LightningATM
              pip3 install -r requirements.txt
          • Note: During the update you may have to confirm with y or q occasionally
          • Now disconnect the power supply once and reconnect via SSH using the new password

          5. Set Up and Test the Display

          5.1 Download and Install Display Software

          cd ~
          git clone https://github.com/waveshare/e-Paper   
          cd ~/e-Paper/RaspberryPi*/python
          sudo python3 setup.py install
          

          5.2 Test the Display

          cd ~/e-Paper/RaspberryPi_JetsonNano/python/examples
          sudo python3 ./epd_2in13_V2_test.py
          

          If everything is correctly connected and installed, the display will now show a demonstration and then clear the screen.

          Note: If you have a different display type, you must use a different test script instead of “epd_2in13_V2_test.py”. For example, use “epd_2in13_V3_test.py” for the newer version — check the back of the display. Or use “epd_2in13d_test.py” for the flexible (gold-colored) (D) version.

          6. Configure settings via config.ini

          The config.ini is used for basic settings.

          • Log in to your Raspberry Pi via CLI: ssh pi@192.168.x.x

          6.1 Start the ATM once to generate config.ini

          cd ~/LightningATM/
          ./app.py
          
          • At first start, you’ll see the message No display configuration matched. Exiting... because you haven’t specified a matching display yet. You can ignore this message. The config.ini we need has now been created in the background.
          • Now edit the config.ini as described below

          6.2 Open the config.ini file

          nano ~/.lightningATM/config.ini
          
          • Don’t be surprised — the path is really ~/.lightningATM/config.ini with a dot and all lowercase

          6.3 Configure the config.ini file

          Under [atm] specify the display type
              display = waveshare2in13v2
          

          Note: Please check your display type. Your model may require different settings.

          Delay time (set from 0 to 12 seconds. 0 is only for ATMs with button)
              payoutdelay = 12
          
          Activate wallet types
              activewallet = lnbits
          
          Under [lnbits] provide the interface data for the LNbits wallet
          [lnbits]
          # api credentials
          url = https://demo.lnbits.com/api/v1
          apikey = YourAdminKey
          # One of "invoice" or "lnurlw"
          method = lnurlw
          # only for lnurlw - seconds to redeem the lnurlw
          timeout = 90
          

          Note: You only need to provide apikey = Admin key. You can get this from your LNbits wallet, for example: Admin key = apikey = 8682516eaf0c457…

          Image: Example LNbits Wallet. You only need to activate the LNURLw extension (→ ENABLE).

          Note: If you want to replace the obsolete LNTXBOT wallet with an LNbits wallet on an existing ATM, you will need to take a few additional steps. See the instructions for this on the original GitHub.

          Assign coins to pulses
          [coins]
          # Pulsecount, fiat value, name
          coin_types = 2,0.05,5  eur cent
                       3,0.10,10 eur cent
                       4,0.20,20 eur cent
                       5,0.50,50 eur cent
                       6,1.00,1 eur
                       7,2.00,2 eur
          
          • To save and exit the editor: CTRL+x → y → ENTER
          Test the settings (or the entire ATM)
          cd ~/LightningATM/
          ./app.py
          
          • The display should now show LightningATM
          • If everything is entered correctly, the ATM should now be ready for use
          • It’s best to test it with a few cents
          • If it doesn’t work, the chapter on tmux will follow later for diagnostics
          • To stop the ATM, just press CTRL+C
          • After a short moment, Manually Interrupted will appear and the display will show that the ATM turned off

          7. Debugger and Monitoring System (tmux)

          The easiest way to monitor multiple processes simultaneously is to open multiple terminal windows. You could open one for “app.py” and another for the debug logger $ tail -f ~/.lightningATM/debug.log and display them side by side. But to view both processes in a single window, you can also use “tmux” (Terminal Multiplexer).

          Terminal Multiplexer (tmux) Command Overview:
          CTRL + b -> % = split window
          CTRL + b -> arrow left/right = switch between windows
          CTRL + b -> CTRL + arrow left/right = move divider
          CTRL + b -> d = return to single window
          

          This allows the CLI window to be split vertically and two processes to be monitored simultaneously → see image!

          Install tmux
          sudo apt install tmux
          
          Start and use tmux
          tmux
          
          • Split tmux window: CTRL+b → %
          Start the app.py process (ATM)
          cd ~/LightningATM
          ./app.py
          
          • Switch to the right window: CTRL+b → right arrow
          • Note: If the ATM is already running (check with $ sudo systemctl status LightningATM.service), you should stop it (with $ sudo systemctl stop LightningATM.service) before starting it manually (with ./app.py) in the tmux terminal. Otherwise, strange behavior may occur. Afterwards, don’t forget to restart the LightningATM service (with $ sudo systemctl start LightningATM.service). This ensures that the ATM will start automatically on next boot.
          Start debug.log
          tail -f ~/.lightningATM/debug.log
          
          • If needed, move the divider: CTRL+b → CTRL+arrow left/right
          • Return to single window: CTRL+b → d

          8. Autostart

          Enable:
          cd ~/LightningATM
          sudo cp LightningATM.service /etc/systemd/system/LightningATM.service
          sudo systemctl enable LightningATM.service
          sudo reboot
          
          Additional commands to manage the service:
          sudo systemctl status LightningATM.service
          sudo systemctl stop LightningATM.service
          sudo systemctl start LightningATM.service
          

          9. Extension: LED Button and Lock Relay

          LED Button

          An LED button greatly enhances the ATM. It allows for many additional functions, improves usability, and also looks nice. I’ve put together a construction kit so you don’t even need to solder — everything is plug & play. For more info, check out my dedicated page: LED-Button-CSet

          Lock Relay (electromagnetic gate)

          The electromagnetic gate is a locking pin that redirects coins to the reject slot. If the coin validator is unpowered, the pin stays locked and all coins are rejected. Only after a valid coin is detected does the solenoid retract the locking pin, allowing coins to fall into the fiat vault. This gate can be externally controlled or blocked. The function can be used to prevent multiple pulses (from rapid coin insertion) or to block coin insertion during certain states (like display pause or when ATM is offline).

          If you want to learn more about the lock relay, I’ve written detailed documentation in English on the GitHub page: Lock Relay

          10. Well done, that’s it!

          • I hope everything worked and your ATM is running 🙂
          • For more help, join the Telegram group: https://t.me/lightningatm_building
          • If you find any errors in the documentation or have suggestions, you can reach me at:
          • Telegram: @AxelHamburch
          • Twitter: @AxelHamburch

          11. A few more tips

          • When using the Command Line Interface (CLI), it’s best to copy & paste commands:
          • → Copy the command with CTRL+C, then right-click the blinking cursor in the CLI window to paste it
          • Tooltips for images can be seen when viewing the site in desktop mode — just hover over them
          • Or if you download the ZIP file with images, you’ll see the filenames as hints
          • If you get the error bash: $: command not found, it means you copied the dollar sign $ with the command
          • If you get the error bash: cd: too many arguments, you may need to go back one level using $ cd ~
            • When logging in via SSH, make sure to use the correct user pi. If you accidentally use admin or make a typo, you won’t get an error message, but the password will not be accepted.
            • You can change the Wi-Fi parameters afterwards using the following command:
            • $ sudo nano /etc/wpa_supplicant/wpa_supplicant.conf
            • If you’re prompted for a username and password while cloning a repository, try restarting your PC and Raspberry Pi. That worked for me.
            • SSH login issues on Windows: Check under Settings / Apps / Apps & Features or Optional Features to ensure OpenSSH Client AND OpenSSH Server are installed.
            • If you’re not yet comfortable with the CLI and Raspberry Pi, I recommend starting with a smaller project like the BTC-Ticker.
            • One more note: I try to keep this German-language tutorial up to date, but my priority right now is the English version on GitHub. If something isn’t clear, check here.
            • If you see: “WARNING: The script qr is installed in ‘/home/pi/.local/bin’ which is not on PATH”, run the following: echo 'export PATH=$PATH:/home/pi/.local/bin' >> ~/.bashrc and then source ~/.bashrc

            Here is the video for the tutorial:


            Created with love! 🧡 Block 720899 / 896440 updated