This is a Linux (Ubuntu, Debian etc.) manual.
This is the do-it-yourself (DIY) version of the Bleskomat ATM. If you're looking for the product which comes ready-to-go, you can find more information and order your own on the official website: Bleskomat Bitcoin Lightning ATM.
The Bleskomat ATM uses the Lightning Network to send bitcoin payments instantly and with very low fees. The key features include:
- Works offline - no WiFi required
- Inexpensive, easily-sourced components
- Easily hackable and extendible
- Plug it in and it's ready to accept fiat in seconds
The Bleskomat ATM must be paired with a server which supports Signed LNURLs. The server facilitates Lightning payments on behalf of your Bleskomat ATM. Below is a list of server software which you can use with your Bleskomat:
- bleskomat-server - supports several Lightning backends including Lightning Network Daemon (lnd), coinos, lnbits, lndhub (BlueWallet), lnpay, lntxbot, opennode.
- lnbits w/ the Bleskomat extension
The rest of this document details how you can build your own version of the Bleskomat ATM project:
- Requirements
- Building the Hardware Device
- Configure and Train Coin Acceptor
- Installing Libraries and Dependencies
- Compiling and Uploading to Device
- Configuring The Bleskomat
- License
- Trademark
This section includes information about the software and hardware requirements needed to build this project.
Basic components/equipment needed to build your own Bleskomat (DIY) ATM:
- 2 x breadboard (400-pin)
- Jumper wires (M-M)
- Jumper wires (M-F)
- ESP32 Devkit
- DG600F Coin Acceptor
- 1.8" TFT display
- Button
- 10k ohm resistor
- DC 5.5/2.1 mm DIP adapter
- 12V DC power adaptor with ~1A
- Standard USB to micro USB cable
- Multimeter
Optional components/equipment:
- Soldering iron
- 2.54 mm pins
- To power the ESP32 devkit from the 12V DC power supply:
- XL4005 step-down converter
- USB (F) adapter
- Alternatively, you could use a USB car charger which includes both a step-down converter and USB (F) output
- If you wish to configure your Bleskomat via SD card:
- Micro SD card with macro adapter
See the Parts Suppliers section below for links to suppliers for each component/equipment.
Below are parts lists based on geographic location:
If you'd like to add your own list, please create a pull-request using this template as a guide. Links with referral codes will not be accepted.
- make
- PlatformIO Core (CLI)
- Version 5 or newer
- Only the CLI ("Core") is required
Before proceeding, be sure that you have all the project's hardware requirements.
Step-by-step build process for the hardware device.
One breadboard is not large enough to accommodate all the pins of the ESP32 devkit due to the width of the devkit. This is why we recommend to connect two breadboards together.
Remove one of the power rails from one of the breadboards. Use the notches on the sides of the breadboards to connect them together length-wise.
Insert the ESP32 devkit into the pin holes of the new, combined breadboard.
Familiarize yourself with the ESP32 devkit's pinout reference below.
The first step to building the device is wiring the power supply. If already plugged in, unplug the 12V DC power supply now. Connect the DC 5.5/2.1 end of the power supply to the DIP adapter. The positive (+) pins should be the power pins and the negative (-) pins should be the ground. You can use your multimeter to check in case you want to be extra safe:
- Plug-in the power supply to electricity
- Turn on your multimeter and set it to measure voltage in the appropriate range (probably 20V)
- Touch the red lead of your multimeter to one of the positive pins
- Touch the black lead of your multimeter to one of the negative pins
- If you see a negative voltage reading, swap the leads between the two wires
- The pin touched by the black lead is the ground ("GND")
- The pin touched by the red lead is the hot wire ("DC12V")
- Unplug the power supply again
Use a pair of M-F jumper wires to connect the DC 5.5/2.1 DIP adapter to one of the breadboard's power rails. Negative to negative, positive to positive. This rail will be your 12V DC power (positive) and the common ground (negative).
If you'd like to make your Bleskomat build a little bit more portable, you can power the ESP32 devkit via its 5V pin. To do this you will need the XL4005 (or equivalent) step-down converter and the USB (F) adapter. Note that powering the ESP32 devkit via its micro USB port requires a regulated voltage of approximately 5V.
It's also possible to use a USB car charger in case you have an extra one lying around.
Connect the step-down converter's input pins to the 12V DC power rail and common ground using (M-F) jumper wires. Use a multimeter to measure the voltage at the out pins. In the case of the XL4005, use a small screwdriver to turn the screw on the little blue box. Turning the screw counter clockwise should lower the voltage, turning it the opposite direction should increase the voltage. Once you have the voltage set to 5V, connect the out pins to the center power rails of the breadboard. This will be your 5V DC power rail.
Use a soldering iron to solder four 2.54 mm pins to the USB (F) DIP adapter. Insert the pins directly into the breadboard wherever you have space available. Using (M-M) jumper wires, connect the negative and positive pins of the USB (F) DIP adapter to the 5V DC power rail.
Connect the negative pin of the 5V DC power rail to the negative of the 12V DC power rail to ensure that they share a common ground (this could be already done, check the negative pins of step-down convertor, they should be connected so no other action required). This is important because without a common ground shared between the coin acceptor and ESP32 devkit, the ESP32 will not receive a clean signal from the coin acceptor.
Use a standard USB to micro USB cable to connect the USB (F) DIP adapter to the ESP32 devkit.
There are other options when powering the ESP32 - e.g via the 3.3V pin or the 5V/VIN pin. You should never power the ESP32 via more than one of these options at the same time. For example, do not power the ESP32 via its 3.3V pin while also connecting the ESP32 via USB to your computer. This can damage the ESP32 and possibly also your computer.
Insert the pins of the TFT display module into the breadboard where you have space available.
Use the table below to connect the ESP32 devkit to the TFT display module.
| ESP32 | TFT |
|---|---|
| VIN (V5) | VCC |
| GND | GND |
| GND | GND |
| NC | |
| NC | |
| NC | |
| GPIO18 | CLK |
| GPIO23 | SDA |
| GPIO2 | RS |
| GPIO4 | RST |
| GPIO22 | CS |
Notes on pin naming:
- There are boards where
GPIXXXare marked asGXXinstead ofDXX. - The
G23may be there twice - the correct one is next toGND. - Some boards have typos so a bit of guess-and-check is necessary sometimes.
Refer to the ESP32 devkit pinout for help identifying the pins on your ESP32.
This step is only needed if you would like to configure your Bleskomat via an SD card.
The TFT display includes an SD card slot. The pins are located above the screen and not soldered to the module by default but the pins can be added. The table of mappings is the following:
| ESP32 | TFT |
|---|---|
| GPIO15 | SD_CS |
| GPIO13 | SD_MOSI |
| GPIO12 | SD_MISO |
| GPIO14 | SD_SCK |
Refer to the ESP32 devkit pinout for help identifying the pins on your ESP32.
Insert button pins into the breadboard wherever you have space available. Typically, its best to place the button at the center of a breadboard (over the gap).
Connect the button using the following table as a guide:
| ESP32 | Button |
|---|---|
| VIN (V5) | left pin |
| GPIO33 | right pin |
Connect the right pin of the button to GND with a 10k ohm resistor.
Refer to the ESP32 devkit pinout for help identifying the pins on your ESP32.
| ESP32 | DG600F | Power Supply |
|---|---|---|
| GPIO1 (TX0) | INHIBIT | |
| COUNTER | ||
| GND | - Ground | |
| GPIO3 (RX0) | SIGNAL | |
| DC12V | + 12V DC |
Refer to the ESP32 devkit pinout for help identifying the pins on your ESP32.
Physical switches on the DG600F should set as follows:
| Switch | State |
|---|---|
| 1 (Port Level) | Down (NO) |
| 2 (Security) | Down (Normal) |
| 3 (Transmitting) | Up (RS232) |
| 4 (Inhibiting) | Down (> +3V) |
Open the DG600F manual to "Coin Acceptor Parameters Setting" on page 18. Set the parameters as follows:
| Parameter | Description | Value | Meaning |
|---|---|---|---|
| A1 | machine charge amount | 01 | min. coin value before data sent |
| A2 | serial output signal pulse-width | 01 | 25ms / 9600 bps (RS232 baud rate) |
| A3 | faulty alarm option | 01 | (rings only one time) |
| A4 | serial port RS232 signal length | 03 | 3 bytes: 0xAA, coin value, XOR of prev two bytes |
| A5 | serial port output | 01 | output to serial pin |
To train the coin acceptor, have a look at "Coin Parameters Setting" on page 16 of the DG600F manual. Be sure to set the "coin value" for each coin in series, incremented by 1. For example:
CZK:
- 1 CZK = 1 coin value
- 2 CZK = 2 coin value
- 5 CZK = 3 coin value
- 10 CZK = 4 coin value
- 20 CZK = 5 coin value
- 50 CZK = 6 coin value
EUR:
- 0.05 EUR = 1 coin value
- 0.10 EUR = 2 coin value
- 0.20 EUR = 3 coin value
- 0.50 EUR = 4 coin value
- 1.00 EUR = 5 coin value
- 2.00 EUR = 6 coin value
Then in bleskomat.conf, set the coinValues setting as follows:
CZK:
coinValues=1,2,5,10,20,50
EUR:
coinValues=0.05,0.10,0.20,0.50,1,2
Before proceeding, be sure that you have all the project's software requirements.
Use make to install libraries and dependencies needed to build the firmware:
make install- The firmware's dependencies are defined in its platformio.ini file located at
./platformio.ini
If while developing you need to install a new library, use the following as a guide:
platformio lib install LIBRARY_NAME[@VERSION]You can find PlatformIO's libraries repository here.
To compile the firmware (without uploading to a device):
make compileTo compile and upload to your device:
make upload DEVICE=/dev/ttyUSB0The device path for your operating system might be different. If you receive a "Permission denied" error about /dev/ttyUSB0 then you will need to set permissions for that file on your system:
sudo chown $USER:$USER /dev/ttyUSB0To open the serial monitor:
make monitor DEVICE=/dev/ttyUSB0Again the device path here could be different for your operating system.
The following is a list of possible configuration options for your Bleskomat (DIY) ATM:
apiKey.id- The API key ID of the device. This is needed by the server to verify signatures created by the device.apiKey.key- The API key secret that is used to generate signatures.apiKey.encoding- The explicit encoding of the API key secret. This can be "hex", "base64", or empty-string (e.g "") to mean no encoding. When generating a new API key on the server, it will store the encoding along with the ID and secret.callbackUrl- The LNURL server base URL plus endpoint path. Example:https://your-bleskomat-server.com/u
shorten- Whether or not to shorten the LNURL; see the lnurl-node module for more details.uriSchemaPrefix- The URI schema prefix for LNURLs generated by the device. It has been discovered that some wallet apps mistakenly only support lowercase URI schema prefixes. Uppercase is better because when encoded as a QR code, the generated image is less complex and so easier to scan. Set this config to empty-string (e.guriSchemaPrefix=) to not prepend any URI schema prefix.fiatCurrency- The fiat currency symbol for which the device is configured; see ISO 4217.fiatPrecision- The number of digits to the right of the decimal point when rendering fiat currency amounts.coinValues- The value of coins for which the coin acceptor has been configured. Each value separated by a comma. Integers and floating point (decimal) values are accepted. For example, when trained with EUR coins this configuration could be set to0.05,0.10,0.20,0.50,1,2or1,2,5,10,20,50for CZK.
It is possible to configure your Bleskomat via the following methods:
Hard-coded configurations can be set by modifying the source file config.cpp.
Each time you make changes to the hard-coded configurations, you will need to re-compile and flash the ESP32's firmware.
First you will need to format the SD card with the FAT32 filesystem.
Create a new file named bleskomat.conf at the root of the SD card's filesystem.
The following is an example bleskomat.conf file:
apiKey.id=6d830ddeb0
apiKey.key=b11cd6b002916691ccf3097eee3b49e51759225704dde88ecfced76ad95324c9
apiKey.encoding=hex
callbackUrl=https://your-bleskomat-server/u
shorten=true
uriSchemaPrefix=
fiatCurrency=EUR
fiatPrecision=2
coinValues=0.05,0.10,0.20,0.50,1,2
The project is licensed under the GNU General Public License v3 (GPL-3):
You may copy, distribute and modify the software as long as you track changes/dates in source files. Any modifications to or software including (via compiler) GPL-licensed code must also be made available under the GPL along with build & install instructions.
"Bleskomat" is a registered trademark. You are welcome to hack, fork, build, and use the source code and instructions found in this repository. However, the right to use the name "Bleskomat" with any commercial products or services is withheld and reserved for the trademark owner.