BlueGit

timfa posprint

Files

posprint / README.md

README.md

12fa4878 History
README.md 4.0 KiB Download Raw

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 directly to USB serial POS printers via raw ESC/POS bytes.

Target platforms: Windows and Linux (x64).

Status

v0.1.0 MVP — Rust + egui app with editor, preview, help, .pos files, parameters, and USB-serial printing.

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          # 31 unit tests
cargo run           # launch the designer
cargo build --release

Scripts: scripts/build-windows.ps1, scripts/build-linux.sh, scripts/build-arch.sh

Command-line printing

# Windows
posprint print receipt.pos -p COM3 --set StoreName="Shop" --set DocumentNumber=42

# Linux
posprint print receipt.pos -p /dev/ttyUSB0 --set StoreName="Shop" --set DocumentNumber=42

All ${Parameters} must be supplied via --set NAME=VALUE or the command fails.

Linux: add your user to the dialout group for USB-serial printer access.

Releases (GitLab CI)

PlatformArtifactInstall
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
Windowsposprint.exeDownload from GitLab release job artifacts

Tag a version (e.g. v0.1.0) to trigger release builds.

Features

  • Markdown-like template editor with live preview
  • Page width: auto-scale or fixed width (mm)
  • Save and load .pos files
  • Parameter tokens (${DocumentNumber}) with print-time popup and value reuse
  • Barcodes, QR codes, and images (including parameterized content)
  • Print to USB-serial POS printers via raw ESC/POS bytes
  • In-app Help tab (from docs/HELP.md)

Dependencies (minimal)

CrateWhy
eframe / eguiNative UI
serde / serde_json.pos file format
serialportUSB-serial printer I/O
imageLoad PNG/JPEG for @image
rfdNative open/save dialogs
barcodersRaster barcode rendering
qrcodeRaster QR rendering
clapCLI print subcommand

ESC/POS encoding is implemented in-tree.

Design documents

DocumentDescription
FEASIBILITY.mdFeasibility assessment, complexity estimate, risks
LANGUAGE-CHOICE.mdLanguage and framework recommendation
HELP.mdUser reference (mirrored in-app Help tab)
ARCHITECTURE.mdSystem architecture and module breakdown
DSL-SPEC.mdDocument markup language (.pos body syntax)
FILE-FORMAT.md.pos file envelope (metadata + body)
PRINTING.mdPrinter discovery, transport, ESC/POS pipeline
BUILD.mdLocal build scripts and Linux package formats

Documentation must stay aligned with the codebase; see .cursor/rules/documentation.mdc.

Planned features

  • Bluetooth printer support (deferred)

Quick feasibility summary

Verdict: feasible for a small team or solo developer, with the printing layer as the main engineering risk.

AreaComplexityNotes
Editor + preview UIMediumWell-trodden path
DSL parser + rendererMediumCustom grammar, bounded scope
ParametersLowStraightforward substitution
Barcodes / QR / imagesLow–MediumMature libraries exist
USB / BT printer I/OHighOS differences, device quirks
Overall (MVP)Medium–High~6–10 weeks for one experienced dev

Stack: Rust + egui (single language, minimal dependencies). USB-serial printing only in v1. See LANGUAGE-CHOICE.md and docs/HELP.md.

Source
1# posprint
2
3Cross-platform designer for POS (point-of-sale) receipt documents. Edit templates in a markdown-like syntax, preview output live, substitute runtime parameters, and print directly to USB serial POS printers via raw ESC/POS bytes.
4
5**Target platforms:** Windows and Linux (x64).
6
7## Status
8
9**v0.1.0 MVP** — Rust + egui app with editor, preview, help, `.pos` files, parameters, and USB-serial printing.
10
11## Build and run
12
13Requires **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
16cargo test # 31 unit tests
17cargo run # launch the designer
18cargo build --release
19```
20
21**Scripts:** `scripts/build-windows.ps1`, `scripts/build-linux.sh`, `scripts/build-arch.sh`
22
23### Command-line printing
24
25```bash
26# Windows
27posprint print receipt.pos -p COM3 --set StoreName="Shop" --set DocumentNumber=42
28
29# Linux
30posprint print receipt.pos -p /dev/ttyUSB0 --set StoreName="Shop" --set DocumentNumber=42
31```
32
33All `${Parameters}` must be supplied via `--set NAME=VALUE` or the command fails.
34
35**Linux:** add your user to the `dialout` group for USB-serial printer access.
36
37## Releases (GitLab CI)
38
39| Platform | Artifact | Install |
40|----------|----------|---------|
41| Linux (Debian/Ubuntu) | `.deb` (amd64) | `sudo dpkg -i posprint_*_amd64.deb` then `sudo apt-get install -f` |
42| Linux (Arch) | `.pkg.tar.zst` (x86_64) | `sudo pacman -U posprint_*_x86_64.pkg.tar.zst` |
43| Windows | `posprint.exe` | Download from GitLab release job artifacts |
44
45Tag a version (e.g. `v0.1.0`) to trigger release builds.
46
47## Features
48
49- Markdown-like template editor with live preview
50- Page width: auto-scale or fixed width (mm)
51- Save and load `.pos` files
52- Parameter tokens (`${DocumentNumber}`) with print-time popup and value reuse
53- Barcodes, QR codes, and images (including parameterized content)
54- Print to USB-serial POS printers via raw ESC/POS bytes
55- In-app **Help** tab (from [docs/HELP.md](docs/HELP.md))
56
57## Dependencies (minimal)
58
59| Crate | Why |
60|-------|-----|
61| `eframe` / `egui` | Native UI |
62| `serde` / `serde_json` | `.pos` file format |
63| `serialport` | USB-serial printer I/O |
64| `image` | Load PNG/JPEG for `@image` |
65| `rfd` | Native open/save dialogs |
66| `barcoders` | Raster barcode rendering |
67| `qrcode` | Raster QR rendering |
68| `clap` | CLI `print` subcommand |
69
70ESC/POS encoding is implemented in-tree.
71
72## Design documents
73
74| Document | Description |
75|----------|-------------|
76| [FEASIBILITY.md](docs/FEASIBILITY.md) | Feasibility assessment, complexity estimate, risks |
77| [LANGUAGE-CHOICE.md](docs/LANGUAGE-CHOICE.md) | Language and framework recommendation |
78| [HELP.md](docs/HELP.md) | **User reference** (mirrored in-app Help tab) |
79| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | System architecture and module breakdown |
80| [DSL-SPEC.md](docs/DSL-SPEC.md) | Document markup language (`.pos` body syntax) |
81| [FILE-FORMAT.md](docs/FILE-FORMAT.md) | `.pos` file envelope (metadata + body) |
82| [PRINTING.md](docs/PRINTING.md) | Printer discovery, transport, ESC/POS pipeline |
83| [BUILD.md](docs/BUILD.md) | Local build scripts and Linux package formats |
84
85Documentation must stay aligned with the codebase; see `.cursor/rules/documentation.mdc`.
86
87## Planned features
88
89- Bluetooth printer support (deferred)
90
91## Quick feasibility summary
92
93**Verdict: feasible** for a small team or solo developer, with the printing layer as the main engineering risk.
94
95| Area | Complexity | Notes |
96|------|------------|-------|
97| Editor + preview UI | Medium | Well-trodden path |
98| DSL parser + renderer | Medium | Custom grammar, bounded scope |
99| Parameters | Low | Straightforward substitution |
100| Barcodes / QR / images | Low–Medium | Mature libraries exist |
101| USB / BT printer I/O | **High** | OS differences, device quirks |
102| **Overall (MVP)** | **Medium–High** | ~6–10 weeks for one experienced dev |
103
104Stack: **Rust + egui** (single language, minimal dependencies). USB-serial printing only in v1. See [LANGUAGE-CHOICE.md](docs/LANGUAGE-CHOICE.md) and [docs/HELP.md](docs/HELP.md).