Introduction

This server allows you to integrate an ESC/POS compatible receipt printer via MQTT. It translates programs written in a DSL an received via MQTT into ESC/POS programs, and forwards these programs to a printer.

Connection to the printer

Currently only networked ESC/POS printers are supported. They are auto-discovered via network. A log message will indicate which printers were found. Discovery is done using Epsons discovery protocol which records responses to a UDP multicast packet. The printer is then identified via SNMP.

Connections to all printers are initiated on port 9100 (RAW printing port).

You also have the option to manually configure a printers network settings. To do so, specify the hostname or IP address in the MANUAL_PRINTER_HOST environment variable. You also have the option to specify the printer model for that printer in the MANUAL_PRINTER_MODEL variable.

The default fallback model (if it cannot be discovered for example) can be overriden using the DEFAULT_PRINTER_MODEL variable.

See a list of supported printer model values in the documentation of escpos-db.

Connection to MQTT

Configure the connection to your MQTT broker using the MQTT_URL variable. Example values for that may be:

mqtt://username:password@mqtt-broker/
mqtt://broker/

Printing

To print, send a program to the printers MQTT topic. A program is a newline-separated listed of commands. See the command reference for a description of all commands.

The specific topic of a printer follows the structure escpos/{printer_id}/print, where printer_id is the printers ID. Find the printers ID by checking the logs, or manual if you want to use the manual printer.

HomeAssistant

The service will create notify entities for HomeAssistant MQTT discovery. Send programs to these notify endpoints to print receipts via HomeAssistant easily. Alternatively, you can publish raw MQTT messages to the correct topics.

Deployment

This is a long running service and should be deployed as such.

It is recommend to use a containerized solution for that. Container images are made available in this repository and are available via the GitHub Container Registry. Right now there is only one tag which is the most recent version of the main branch:

ghcr.io/jhbruhn/escpos2mqtt:main

To enable UDP-broadcast-based discovery of printers in your network, use host networking to give the service access to the hosts interfaces which sends out the discovery messages and receives the answers from the printers. Alternatively you can use a bridge network and manually configure your printer.

Compose

A deployment using docker (or podman) compose might look like this:

services:
  escpos2mqtt:
    image: ghcr.io/jhbruhn/escpos2mqtt:main
    restart: unless-stopped
    environment:
      MQTT_URL: "mqtt://rolf:12345678@192.168.1.5"
    network_mode: host

Note how the network mode is set to host!

HomeAssistant Add-On

A HomeAssistant Add-On of this service is provided. To install, add the repository available at https://github.com/jhbruhn/escpos2mqtt-hassio and install the escpos2mqtt add-on from there. See the add-on there for further information on configuration. The MQTT-broker is discovered automatically using the HA mechanisms. That on the other hand means that the MQTT broker must also be managed by HomeAssistant.

Command Reference

This page contains the complete reference for all available printer commands in the escpos2mqtt DSL. This document describes the Domain Specific Language (DSL) used to send printing commands to ESC/POS-compatible printers. The documentation below is automatically generated from the parser implementation.

Overview

The DSL consists of commands that are executed sequentially. Each command must be on its own line. Empty lines are ignored. String arguments must be enclosed in double quotes.

Text Output

write

Syntax: write "<text>"

Outputs text to the printer without a line break at the end

Examples:

write "Hello World"
write "Price: $19.99"

writeln

Syntax: writeln "<text>"

Outputs text to the printer followed by a line break

Examples:

writeln "Hello World"
writeln "Order #12345"

Text Formatting

bold

Syntax: bold <true|false>

Enables or disables bold text

Examples:

bold true
bold false

underline

Syntax: underline <none|single|double>

Sets the underline mode for text

Examples:

underline none
underline single
underline double

double_strike

Syntax: double_strike <true|false>

Enables or disables double-strike for text

Examples:

double_strike true
double_strike false

font

Syntax: font <a|b|c>

Sets the font type. Available fonts depend on printer model and might fallback to another font if unavailable.

Examples:

font a
font b
font c

flip

Syntax: flip <true|false>

Flips text 180 degrees

Examples:

flip true
flip false

reverse

Syntax: reverse <true|false>

Enables or disables inverted text colors (white text on black background)

Examples:

reverse true
reverse false

size

Syntax: size <width>,<height>

Sets character size multiplier (1-8 for both width and height)

Examples:

size 1,1
size 2,2
size 3,1

reset_size

Syntax: reset_size

Resets text size to default (1,1)

Examples:

reset_size

Layout & Spacing

justify

Syntax: justify <left|center|right>

Sets text justification/alignment

Examples:

justify left
justify center
justify right

feed

Syntax: feed <lines>

Feeds paper forward by the specified number of lines

Examples:

feed 1
feed 3
feed 10

feed

Syntax: feed

Feeds paper forward by 1 line (default)

Examples:

feed

Barcodes & QR Codes

ean13

Syntax: ean13 <12-13 digits>

Prints an EAN-13 barcode (12 or 13 digits)

Examples:

ean13 1234567890123
ean13 123456789012

ean8

Syntax: ean8 <7-8 digits>

Prints an EAN-8 barcode (7 or 8 digits)

Examples:

ean8 12345678
ean8 1234567

qr_code

Syntax: qr_code "<data>"

Prints a QR code with the specified data

Examples:

qr_code "https://example.com"
qr_code "Hello World"

Special Commands

sudoku

Syntax: sudoku

Generates and prints a random Sudoku puzzle

Examples:

sudoku

minicrossword

Syntax: minicrossword

Generates and prints a mini crossword puzzle

Examples:

minicrossword

cut

Syntax: cut

Cuts the paper (if printer has auto-cutter)

Examples:

cut

todo

Syntax: todo "<task>"

Adds a line rendered as a todo item

Examples:

todo "Buy groceries"
todo "Call dentist"

Complete Example

justify center
bold true
size 2,2
writeln "RECEIPT"
reset_size
bold false
feed 1
justify left
writeln "Item 1          $10.00"
writeln "Item 2          $15.00"
underline single
writeln "Total:          $25.00"
underline none
feed 2
justify center
qr_code "https://example.com/receipt/12345"
feed 2
cut