1. Project Basics
- This tutorial is based on the hardware, e.g. the kit from fulmo.org:
- https://shop.fulmo.org/product/the-lightning-atm-bitcoin-construction-set/
- Alternatively, you can also purchase the parts individually. Here is a parts list (English).
- The software from the GitHub project: https://github.com/21isenough/LightningATM
Below is additional documentation you can look at, though not required for implementation:
- The original LightningATM documentation for the larger version with camera and button:
- https://docs.lightningatm.me/
- Fulmo’s guide, specifically created for the Pocket Edition:
- https://blog.fulmo.org/the-lightningatm-pocket-edition/
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...
withyes
- 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:
$
representspi@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
orq
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
- Note: A brief guide on how to set up an LNbits wallet can be found here: Quick guide on how to set up an 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 theATM 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 useadmin
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 thensource ~/.bashrc
- This tutorial is based on the hardware, e.g. the kit from fulmo.org:
- https://shop.fulmo.org/product/the-lightning-atm-bitcoin-construction-set/
- Alternatively, you can also purchase the parts individually. Here is a parts list (English).
- The software from the GitHub project: https://github.com/21isenough/LightningATM
- The original LightningATM documentation for the larger version with camera and button:
- https://docs.lightningatm.me/
- Fulmo’s guide, specifically created for the Pocket Edition:
- https://blog.fulmo.org/the-lightningatm-pocket-edition/
- 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)
- 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
- 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)
- 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.
- 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!
- 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...
withyes
- 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:
$
representspi@raspberrypi:~ $
in the CLI and does not need to be typed. Enable the SPI interface for the Waveshare displays - Note: During the update you may have to confirm with
y
orq
occasionally - Now disconnect the power supply once and reconnect via SSH using the new password
- Log in to your Raspberry Pi via CLI:
ssh pi@192.168.x.x
- 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
- Don’t be surprised — the path is really
~/.lightningATM/config.ini
with a dot and all lowercase - Note: A brief guide on how to set up an LNbits wallet can be found here: Quick guide on how to set up an LNbits
- To save and exit the editor:
CTRL+x → y → ENTER
- 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 theATM turned off
- Split tmux window:
CTRL+b → %
- 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. - If needed, move the divider:
CTRL+b → CTRL+arrow left/right
- Return to single window:
CTRL+b → d
- 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
- 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 useadmin
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 thensource ~/.bashrc
- This tutorial is based on the hardware, e.g. the kit from fulmo.org:
- https://shop.fulmo.org/product/the-lightning-atm-bitcoin-construction-set/
- Alternatively, you can also purchase the parts individually. Here is a parts list (English).
- The software from the GitHub project: https://github.com/21isenough/LightningATM
- The original LightningATM documentation for the larger version with camera and button:
- https://docs.lightningatm.me/
- Fulmo’s guide, specifically created for the Pocket Edition:
- https://blog.fulmo.org/the-lightningatm-pocket-edition/
- 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)
- 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
- 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)
- 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.
- 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!
- 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...
withyes
- 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:
$
representspi@raspberrypi:~ $
in the CLI and does not need to be typed. Enable the SPI interface for the Waveshare displays - Note: During the update you may have to confirm with
y
orq
occasionally - Now disconnect the power supply once and reconnect via SSH using the new password
- Log in to your Raspberry Pi via CLI:
ssh pi@192.168.x.x
- 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
- Don’t be surprised — the path is really
~/.lightningATM/config.ini
with a dot and all lowercase - Note: A brief guide on how to set up an LNbits wallet can be found here: Quick guide on how to set up an LNbits
- To save and exit the editor:
CTRL+x → y → ENTER
- 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 theATM turned off
- Split tmux window:
CTRL+b → %
- 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. - If needed, move the divider:
CTRL+b → CTRL+arrow left/right
- Return to single window:
CTRL+b → d
- 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
- 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 useadmin
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 thensource ~/.bashrc
- This tutorial is based on the hardware, e.g. the kit from fulmo.org:
- https://shop.fulmo.org/product/the-lightning-atm-bitcoin-construction-set/
- Alternatively, you can also purchase the parts individually. Here is a parts list (English).
- The software from the GitHub project: https://github.com/21isenough/LightningATM
- The original LightningATM documentation for the larger version with camera and button:
- https://docs.lightningatm.me/
- Fulmo’s guide, specifically created for the Pocket Edition:
- https://blog.fulmo.org/the-lightningatm-pocket-edition/
- 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)
- 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
- 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)
- 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.
- 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!
- 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...
withyes
- 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:
$
representspi@raspberrypi:~ $
in the CLI and does not need to be typed. Enable the SPI interface for the Waveshare displays - Note: During the update you may have to confirm with
y
orq
occasionally - Now disconnect the power supply once and reconnect via SSH using the new password
- Log in to your Raspberry Pi via CLI:
ssh pi@192.168.x.x
- 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
- Don’t be surprised — the path is really
~/.lightningATM/config.ini
with a dot and all lowercase - Note: A brief guide on how to set up an LNbits wallet can be found here: Quick guide on how to set up an LNbits
- To save and exit the editor:
CTRL+x → y → ENTER
- 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 theATM turned off
- Split tmux window:
CTRL+b → %
- 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. - If needed, move the divider:
CTRL+b → CTRL+arrow left/right
- Return to single window:
CTRL+b → d
- 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
- 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 useadmin
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 thensource ~/.bashrc
- This tutorial is based on the hardware, e.g. the kit from fulmo.org:
- https://shop.fulmo.org/product/the-lightning-atm-bitcoin-construction-set/
- Alternatively, you can also purchase the parts individually. Here is a parts list (English).
- The software from the GitHub project: https://github.com/21isenough/LightningATM
- The original LightningATM documentation for the larger version with camera and button:
- https://docs.lightningatm.me/
- Fulmo’s guide, specifically created for the Pocket Edition:
- https://blog.fulmo.org/the-lightningatm-pocket-edition/
- 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)
- 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
- 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)
- 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.
- 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!
- 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...
withyes
- 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:
$
representspi@raspberrypi:~ $
in the CLI and does not need to be typed. Enable the SPI interface for the Waveshare displays - Note: During the update you may have to confirm with
y
orq
occasionally - Now disconnect the power supply once and reconnect via SSH using the new password
- Log in to your Raspberry Pi via CLI:
ssh pi@192.168.x.x
- 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
- Don’t be surprised — the path is really
~/.lightningATM/config.ini
with a dot and all lowercase - Note: A brief guide on how to set up an LNbits wallet can be found here: Quick guide on how to set up an LNbits
- To save and exit the editor:
CTRL+x → y → ENTER
- 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 theATM turned off
- Split tmux window:
CTRL+b → %
- 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. - If needed, move the divider:
CTRL+b → CTRL+arrow left/right
- Return to single window:
CTRL+b → d
- 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
- 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 useadmin
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 thensource ~/.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:
Just follow the instructions step by step, and you’ll reach your goal quickly.
2. Hardware Preparation
2.1 Preparing the Voltage Converter
2.2 Configure the coin validator (6 types, 5 cents to 2 euros)
2.3 Calibrate Coin Validator with Coins
2.4 Wiring the Hardware
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
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
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.
6.1 Start the ATM once to generate config.ini
cd ~/LightningATM/ ./app.py
6.2 Open the config.ini file
nano ~/.lightningATM/config.ini
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
Test the settings (or the entire ATM)
cd ~/LightningATM/ ./app.py
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
Start the app.py
process (ATM)
cd ~/LightningATM ./app.py
Start debug.log
tail -f ~/.lightningATM/debug.log
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!
11. A few more tips
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:
Just follow the instructions step by step, and you’ll reach your goal quickly.
2. Hardware Preparation
2.1 Preparing the Voltage Converter
2.2 Configure the coin validator (6 types, 5 cents to 2 euros)
2.3 Calibrate Coin Validator with Coins
2.4 Wiring the Hardware
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
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
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.
6.1 Start the ATM once to generate config.ini
cd ~/LightningATM/ ./app.py
6.2 Open the config.ini file
nano ~/.lightningATM/config.ini
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
Test the settings (or the entire ATM)
cd ~/LightningATM/ ./app.py
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
Start the app.py
process (ATM)
cd ~/LightningATM ./app.py
Start debug.log
tail -f ~/.lightningATM/debug.log
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!
11. A few more tips
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:
Just follow the instructions step by step, and you’ll reach your goal quickly.
2. Hardware Preparation
2.1 Preparing the Voltage Converter
2.2 Configure the coin validator (6 types, 5 cents to 2 euros)
2.3 Calibrate Coin Validator with Coins
2.4 Wiring the Hardware
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
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
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.
6.1 Start the ATM once to generate config.ini
cd ~/LightningATM/ ./app.py
6.2 Open the config.ini file
nano ~/.lightningATM/config.ini
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
Test the settings (or the entire ATM)
cd ~/LightningATM/ ./app.py
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
Start the app.py
process (ATM)
cd ~/LightningATM ./app.py
Start debug.log
tail -f ~/.lightningATM/debug.log
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!
11. A few more tips
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:
Just follow the instructions step by step, and you’ll reach your goal quickly.
2. Hardware Preparation
2.1 Preparing the Voltage Converter
2.2 Configure the coin validator (6 types, 5 cents to 2 euros)
2.3 Calibrate Coin Validator with Coins
2.4 Wiring the Hardware
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
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
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.
6.1 Start the ATM once to generate config.ini
cd ~/LightningATM/ ./app.py
6.2 Open the config.ini file
nano ~/.lightningATM/config.ini
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
Test the settings (or the entire ATM)
cd ~/LightningATM/ ./app.py
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
Start the app.py
process (ATM)
cd ~/LightningATM ./app.py
Start debug.log
tail -f ~/.lightningATM/debug.log
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!
11. A few more tips
Here is the video for the tutorial:
Created with love! 🧡 Block 720899 / 896440 updated