posprint
Cross-platform designer for POS (point-of-sale) receipt documents. Edit templates in a markdown-like syntax, preview output live, substitute runtime parameters, and print via raw ESC/POS (USB printer-class, Windows spooler, USB-serial, or Classic Bluetooth SPP after OS pairing).
Target platforms: Windows, Linux (x64), and macOS (Apple Silicon / Intel).
Status
v0.5.7 — Classic Bluetooth SPP after OS pairing (Windows COM / Linux rfcomm); BLE still out of scope.
Build and run
Requires Rust 1.88+ (rustup or pacman -S rust on Arch). See docs/BUILD.md for OS libraries and package scripts.
cargo test # unit tests
cargo run # launch the designer
cargo build --release
Scripts: scripts/build-windows.ps1, scripts/build-linux.sh, scripts/build-arch.sh, scripts/build-macos.sh (Interactive shells offer to install missing dependencies.)
Command-line printing
# List discovered printers (USB, spooler, serial, paired Bluetooth SPP)
posprint list
# Windows (serial, Bluetooth COM after pairing, or spooler queue name)
posprint print receipt.pos -p COM3 --set StoreName="Shop" --set DocumentNumber=42
# Linux / macOS (USB-direct, 'auto', USB-serial, or RFCOMM/Bluetooth SPP)
posprint print receipt.pos -p auto --set StoreName="Shop" --set DocumentNumber=42
posprint print receipt.pos -p /dev/ttyUSB0 --set StoreName="Shop" --set DocumentNumber=42
# Embedded CLI help for this OS
posprint cli-help
All ${Parameters} must be supplied via --set NAME=VALUE or the command fails.
Linux serial: add your user to the dialout group.
Releases (BlueGit CI)
| Platform | Artifact | Install |
|---|---|---|
| Linux (Debian/Ubuntu) | .deb (amd64) | sudo dpkg -i posprint_*_amd64.deb then sudo apt-get install -f |
| Linux (Arch) | .pkg.tar.zst (x86_64) | sudo pacman -U posprint-*-x86_64.pkg.tar.zst or AUR posprint / posprint-bin |
| Windows | posprint.exe | Download from the BlueGit releases |
Every master pipeline on BlueGit builds all packages. Start the manual release job to create the next tag (highest tag + 1 patch, or RELEASE_VERSION) with the packages as release assets; publish:aur then updates the posprint and posprint-bin AUR packages. See blue-ci-cd.yml. Releases up to 0.5.8 are on the old GitLab project.
Features
- Markdown-like template editor with live preview (Design tab)
- Page width (mm) and calibrated preview zoom
- Save and load
.posfiles - Parameter tokens:
${Name}(text) and$[Name](bool checkbox) via print dialog and CLI--set - Inline ASCII checkboxes (
[]/[ ]/[x]) — CP437-safe on thermal printers - Nested bullet lists, headings,
@date/@time, barcodes, QR, images - Print via USB-direct, Windows spooler, USB-serial, or paired Classic Bluetooth SPP (baud probed; BLE not supported)
- In-app Help tab (from docs/HELP.md)
Documentation
| Document | Description |
|---|---|
| HELP.md | User reference (mirrored in-app Help tab) |
| ARCHITECTURE.md | System architecture and module breakdown |
| DSL-SPEC.md | Document markup language (.pos body syntax) |
| FILE-FORMAT.md | .pos file envelope (metadata + body) |
| PRINTING.md | Printer discovery, transport, ESC/POS pipeline |
| POSPRINT-URL.md | posprint:// deep links and lib/ helpers |
| AUR.md | AUR package layout, secrets, and tag-driven publishing |
| BUILD.md | Local build scripts and Linux package formats |
Documentation must stay aligned with the codebase; see .cursor/rules/documentation.mdc.
Dependencies (minimal)
| Crate | Why |
|---|---|
eframe / egui | Native UI |
serde / serde_json | .pos file format |
serialport | Serial printer I/O |
rusb | USB printer-class devices |
image | Load PNG/JPEG for @image |
rfd | Native open/save dialogs |
barcoders | Raster barcode rendering |
qrcode | Raster QR rendering |
clap | CLI print / link / cli-help |
flate2 / base64 | posprint:// URL payload |
ureq | Download @image http(s)://… |
ESC/POS encoding is implemented in-tree.
Source
| 1 | # posprint |
| 2 | |
| 3 | Cross-platform designer for POS (point-of-sale) receipt documents. Edit templates in a markdown-like syntax, preview output live, substitute runtime parameters, and print via raw ESC/POS (USB printer-class, Windows spooler, USB-serial, or Classic Bluetooth SPP after OS pairing). |
| 4 | |
| 5 | **Target platforms:** Windows, Linux (x64), and macOS (Apple Silicon / Intel). |
| 6 | |
| 7 | ## Status |
| 8 | |
| 9 | **v0.5.7** — Classic Bluetooth SPP after OS pairing (Windows COM / Linux rfcomm); BLE still out of scope. |
| 10 | |
| 11 | ## Build and run |
| 12 | |
| 13 | Requires **Rust 1.88+** ([rustup](https://rustup.rs/) or `pacman -S rust` on Arch). See [docs/BUILD.md](docs/BUILD.md) for OS libraries and package scripts. |
| 14 | |
| 15 | ```bash |
| 16 | cargo test # unit tests |
| 17 | cargo run # launch the designer |
| 18 | cargo build --release |
| 19 | ``` |
| 20 | |
| 21 | **Scripts:** `scripts/build-windows.ps1`, `scripts/build-linux.sh`, `scripts/build-arch.sh`, `scripts/build-macos.sh` |
| 22 | (Interactive shells offer to install missing dependencies.) |
| 23 | |
| 24 | ### Command-line printing |
| 25 | |
| 26 | ```bash |
| 27 | # List discovered printers (USB, spooler, serial, paired Bluetooth SPP) |
| 28 | posprint list |
| 29 | |
| 30 | # Windows (serial, Bluetooth COM after pairing, or spooler queue name) |
| 31 | posprint print receipt.pos -p COM3 --set StoreName="Shop" --set DocumentNumber=42 |
| 32 | |
| 33 | # Linux / macOS (USB-direct, 'auto', USB-serial, or RFCOMM/Bluetooth SPP) |
| 34 | posprint print receipt.pos -p auto --set StoreName="Shop" --set DocumentNumber=42 |
| 35 | posprint print receipt.pos -p /dev/ttyUSB0 --set StoreName="Shop" --set DocumentNumber=42 |
| 36 | |
| 37 | # Embedded CLI help for this OS |
| 38 | posprint cli-help |
| 39 | ``` |
| 40 | |
| 41 | All `${Parameters}` must be supplied via `--set NAME=VALUE` or the command fails. |
| 42 | |
| 43 | **Linux serial:** add your user to the `dialout` group. |
| 44 | |
| 45 | ## Releases (BlueGit CI) |
| 46 | |
| 47 | | Platform | Artifact | Install | |
| 48 | |----------|----------|---------| |
| 49 | | Linux (Debian/Ubuntu) | `.deb` (amd64) | `sudo dpkg -i posprint_*_amd64.deb` then `sudo apt-get install -f` | |
| 50 | | Linux (Arch) | `.pkg.tar.zst` (x86_64) | `sudo pacman -U posprint-*-x86_64.pkg.tar.zst` or AUR `posprint` / `posprint-bin` | |
| 51 | | Windows | `posprint.exe` | Download from the [BlueGit releases](https://git.timfalken.com/timfa/posprint/-/releases) | |
| 52 | |
| 53 | Every master pipeline on [BlueGit](https://git.timfalken.com/timfa/posprint) builds all packages. Start the manual `release` job to create the next tag (highest tag + 1 patch, or `RELEASE_VERSION`) with the packages as release assets; `publish:aur` then updates the `posprint` and `posprint-bin` AUR packages. See `blue-ci-cd.yml`. Releases up to 0.5.8 are on the old [GitLab project](https://gitlab.com/Timfa/posprint/-/releases). |
| 54 | |
| 55 | ## Features |
| 56 | |
| 57 | - Markdown-like template editor with live preview (Design tab) |
| 58 | - Page width (mm) and calibrated preview zoom |
| 59 | - Save and load `.pos` files |
| 60 | - Parameter tokens: `${Name}` (text) and `$[Name]` (bool checkbox) via print dialog and CLI `--set` |
| 61 | - Inline ASCII checkboxes (`[]` / `[ ]` / `[x]`) — CP437-safe on thermal printers |
| 62 | - Nested bullet lists, headings, `@date` / `@time`, barcodes, QR, images |
| 63 | - Print via USB-direct, Windows spooler, USB-serial, or paired Classic Bluetooth SPP (baud probed; BLE not supported) |
| 64 | - In-app **Help** tab (from [docs/HELP.md](docs/HELP.md)) |
| 65 | |
| 66 | ## Documentation |
| 67 | |
| 68 | | Document | Description | |
| 69 | |----------|-------------| |
| 70 | | [HELP.md](docs/HELP.md) | **User reference** (mirrored in-app Help tab) | |
| 71 | | [ARCHITECTURE.md](docs/ARCHITECTURE.md) | System architecture and module breakdown | |
| 72 | | [DSL-SPEC.md](docs/DSL-SPEC.md) | Document markup language (`.pos` body syntax) | |
| 73 | | [FILE-FORMAT.md](docs/FILE-FORMAT.md) | `.pos` file envelope (metadata + body) | |
| 74 | | [PRINTING.md](docs/PRINTING.md) | Printer discovery, transport, ESC/POS pipeline | |
| 75 | | [POSPRINT-URL.md](docs/POSPRINT-URL.md) | `posprint://` deep links and `lib/` helpers | |
| 76 | | [AUR.md](docs/AUR.md) | AUR package layout, secrets, and tag-driven publishing | |
| 77 | | [BUILD.md](docs/BUILD.md) | Local build scripts and Linux package formats | |
| 78 | |
| 79 | Documentation must stay aligned with the codebase; see `.cursor/rules/documentation.mdc`. |
| 80 | |
| 81 | ## Dependencies (minimal) |
| 82 | |
| 83 | | Crate | Why | |
| 84 | |-------|-----| |
| 85 | | `eframe` / `egui` | Native UI | |
| 86 | | `serde` / `serde_json` | `.pos` file format | |
| 87 | | `serialport` | Serial printer I/O | |
| 88 | | `rusb` | USB printer-class devices | |
| 89 | | `image` | Load PNG/JPEG for `@image` | |
| 90 | | `rfd` | Native open/save dialogs | |
| 91 | | `barcoders` | Raster barcode rendering | |
| 92 | | `qrcode` | Raster QR rendering | |
| 93 | | `clap` | CLI `print` / `link` / `cli-help` | |
| 94 | | `flate2` / `base64` | `posprint://` URL payload | |
| 95 | | `ureq` | Download `@image http(s)://…` | |
| 96 | |
| 97 | ESC/POS encoding is implemented in-tree. |