Receipt Printer Server

The receipt printer server connects over serial to an ESC/POS printer and exposes a REST api which allows custom external services to interact with the printer.

This daemon is only tested on NixOS and Ubuntu (Raspberry Pi 5). Only the Epson TM-T88IV printer over serial to USB have been tested.

The web server exposes:

• / - The frontend
• /api/status - Printer Status, number of queued documents
• /api/preview - Returns a PNG of how the "Receipt Document" would look like if printed.
• /api/print - Actually prints the "Receipt Document"
• /api/schema - JSON Schema of how to structure the "Receipt Document"
  • used by the frontend to generate documentation using the IR as the single source of truth
  • the autocomplete blocks currently don't use this schema...

Quick Start

Create a config.toml file and place it along with the binary/daemon crate, or in the root folder. The config must at least contain:

printer_device_path = "/dev/ttyUSB0"

[api_keys]
my_token_label = "<token>"

There is a config.example.toml for inspiration.

The token is needed to interact with the API, and allows you to have the service exposed public. TLS/HTTPS is recommended to not leak the token etc. The token is something arbitrary you set yourself. The token label is also arbitrary to help you organize tokens.

Tip: Generate random tokens with:

openssl rand -hex 32

Make sure to correctly configure Baud rates etc.

See daemon/src/settings.rs for all options.

Start the debug service with cargo run.

Note: the path to the config.toml is relative, so if you put it in daemon you need to first cd daemon then cargo run.

See the documentation page on the web frontend for more detailed API information. Also check out the .hurl files in daemon/examples.

Project Structure

receipt-printer-server
├── daemon                  # the service that connects to the printer and exposes the REST API
├── frontend                # Svelte frontend for interacting with the printer
├── ir                      # immediate representation of a "receipt document"
├── preview                 # generates a png preview of a "receipt document"
├── raster                  # converts svgs, graphs and images to b&w dots
├── config.example.toml     # example config needed to use the service
├── config.toml             # actual config (not tracked by git)
├── Cross.toml              # needed for cross compiling to Raspberry Pi
├── deploy.sh               # example script for deploying to a remote Raspberry Pi
└── receipt-daemon.service  # example systemd service file

Deployment

The service can easily be cross-compiled and deployed to a Raspberry Pi. See Cross.toml, receipt-daemon.service and deploy.sh.

Note: You need to change the PI= variable to point to your ssh server, or add a home entry in your .ssh/config

Alternatively you can clone the repo onto the Raspberry Pi and build locally with cargo build.

Dependencies

• rust with cargo
• node & npm

For cross compilation:

• cross-rs
• docker

Development

You can have hot reloading while working on the Svelte frontend by setting the proxy option in frontend/vite.config.ts to the port you're hosting the REST api. Then just run both the daemon for the API and npm run dev for the frontend.