Bleskomat POS

The Bleskomat POS is an offline point-of-sale terminal device for the Bitcoin Lightning Network. This repository includes the open-source firmware, instructions how to build your own hardware device, and scripts to compile the firmware from source.

Main features include the following:

• Works offline - the device itself can work without an internet connection
• Localization to support mutliple languages - see include/locale directory for full list of supported languages
• Deep sleep mode of the ESP32 is used when device is battery-powered
• JSON-RPC API over serial (USB) allows configuration of device via browser using BleskomatWebSerial

The Bleskomat POS must be paired with a server to facilitate Lightning Network payments on its behalf; see the options below:

• Bleskomat Platform - non-custodial, requires a subscription
• bleskomat-server - non-custodial, open-source, self-hosted solution
• lnbits via the LNURLDevice extension - open-source, self-hosted and possible to use custodial instances hosted by others; public instances of lnbits:
  • legend.lnbits.com - unstable, don't leave funds on this instance for very long

The rest of this document details the hardware and software requirements, how to build the hardware device, and instructions to compile firmware from source.

• Requirements
  • Hardware Requirements
  • Software Requirements
• Building the Hardware Device
  • Lilygo T-Display Kit
  • ESP32 Devkit
    • Wiring the TFT Display
    • Wiring the Membrane Keypad
• Installing Libraries and Dependencies
• Compiling and Uploading to Device
• Generate Font Header Files
• Configuring the Device
  • List of Configuration Options
  • Browser-Based Configuration Tool
  • Command-Line Configuration Tool
  • Hard-Coded Configuration
• Changelog
• Support
• License
• Trademark

Requirements

This section includes information about the software and hardware requirements needed to build this project.

Hardware Requirements

Components needed to build your own Bleskomat POS:

• Lilygo TTGO T-Display kit - this includes the following:
  • Lilygo T-Display Module
  • Keyboard
  • USB-C cable
  • JST connector (for battery)
  • With or without 3D-printed case
• 3.7V Lipo battery with built-in over/under charge protection

Alternative build components using an ESP32 Devkit:

• ESP32 Devkit
• 1.8" TFT display
• 2 x 400-pin breadboards
• Jumper wires (M-M)
• Membrane keypad (4x4 or 4x3)
• Standard USB to micro USB cable

Equipment/tools needed:

• Soldering iron
• Multimeter

Software Requirements

• make
• PlatformIO Core (CLI)
  • Version 5 or newer
  • Only the CLI ("Core") is required

Building the Hardware Device

Before proceeding, be sure that you have all the project's hardware requirements.

Step-by-step build process for the hardware device.

Lilygo T-Display Kit

If using a battery, insert the battery's JST connector into the JST socket on the under-side of the T-Display devkit board. Insert the T-Display devkit board's pins into the keyboard module's sockets - they should line-up perfectly. The USB-C port should be pointing to the right.

ESP32 Devkit

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.

ESP32 devkit pinout

Wiring the TFT Display

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
GPIO22	CS
GPIO4	RESET (RST)
GPIO2	AO (RS)
GPIO23	SDA
GPIO18	SCK (CLK)
3V3	LED (NC)

Notes on pin naming:

• There are boards where GPIXXX are marked as GXX instead of DXX.
• The G23 may be there twice - the correct one is next to GND.
• 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.

Wiring the Membrane Keypad

Use the table below to connect the ESP32 devkit to the 4x4 membrane keypad:

ESP32	Keypad
GPIO13	R1
GPIO14	R2
GPIO26	R3
GPIO25	R4
GPIO33	C1
GPIO32	C2
GPIO15	C3
GPIO21	C4

Use the table below to connect the ESP32 devkit to the 4x3 membrane keypad:

ESP32	Keypad
GPIO13	R1
GPIO14	R2
GPIO26	R3
GPIO25	C1
GPIO33	C2
GPIO32	C3

Refer to the ESP32 devkit pinout for help identifying the pins on your ESP32.

Installing Libraries and Dependencies

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.

Compiling and Uploading to Device

To compile the firmware (without uploading to a device):

make compile

To compile and upload to your device:

make upload DEVICE=/dev/ttyACM1

The device path for your operating system might be different. If you receive a "Permission denied" error about /dev/ttyACM1 then you will need to set permissions for that file on your system:

sudo chown $USER:$USER /dev/ttyACM1

To open the serial monitor:

make monitor DEVICE=/dev/ttyACM1

Again the device path here could be different for your operating system.

Generate Font Header Files

This project includes font header files in various sizes. These header files were generated using the fontconvert tool from Adafruit-GFX-Library. If you would like to use your own font, generate more font sizes of the existing fonts, or to expand the character set; you can use the following command as an example:

./scripts/generate-font-header-files.sh "./assets/fonts/Courier Prime Code/Courier Prime Code.ttf" 32-382 6,7,8,9,10,12,14,16,18,20,22,24,28

• 32-382 - this is the character range (e.g. first character = 32, last = 382). More characters = larger header files.
• 6,7,8,9,10,12,14,16,18,20,22,24,28 - comma-separated list of font sizes

Note that this requires the fontconvert tool to have been built locally. Use the following command to build it:

make fontconvert

Configuring the Device

It is possible to configure the device via the following methods:

• Browser-Based Configuration Tool
• Command-Line Configuration Tool
• Hard-Coded Configuration

List of Configuration Options

The following is a list of possible configuration options for the Bleskomat POS:

• apiKey.key - The API key secret that is used to generate cryptographic signatures and encrypted payloads.
• 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://p.bleskomat.com/pay/<apiKey.id>
• 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.g uriSchemaPrefix=) 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.
• keypadRowPins - Comma-separated list of GPIO numbers for the keypad's row pins.
• keypadColPins - Comma-separated list of GPIO numbers for the keypad's column pins.
• keypadCharList - The keypad character list read left-to-right, top-to-bottom. Examples:
  • T-Display Keyboard = "123456789*0#"
  • Membrane Keypad (4x3) = "123456789*0#"
  • Membrane Keypad (4x4) = "123A456B789C*0#D"
• locale - The locale used when rendering text to the screen. See the ./include/locale directory for the full list of supported languages.
• sleepModeDelay - Number of milliseconds of inactivity to wait before the device will enter power-saving mode.
• contrastLevel - The contrast level between text and background colors. If the ambient light level is low, decreasing the contrast can improve scannability of QR codes.
• tftRotation The orientation of the TFT display. This is useful to allow different positions of the display. The possible rotation values are:
  • 0 = 0 degrees
  • 1 = 90 degrees
  • 2 = 180 degrees
  • 3 = 270 degrees
  • 3 = 270 degrees
• logLevel - Possible values:
  • trace - everything
  • debug
  • info - default
  • warn
  • error
  • none - nothing

Browser-Based Configuration Tool

The Bleskomat Platform provides a browser-based configuration tool to upload pre-built device firmware, view real-time log output, update device configurations, run JSON-RPC serial commands, and more.

Command-Line Configuration Tool

It is also possible to use the bleskomat-cli command-line utility to communicate with a Bleskomat hardware device via JSON-RPC over serial API. Please refer to that project's readme for installation and usage information.

Hard-Coded Configuration

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.

Changelog

See CHANGELOG.md

Support

Need some help? Join us in the official Telegram group or send us an email at [email protected] and we will try our best to respond in a reasonable time. If you have a feature request or bug to report, please open an issue in this project repository.

License

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.

Trademark

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