Sync docs and rules with multi-transport printing and current UI.
Update HELP/ARCHITECTURE/PRINTING/DSL/FILE-FORMAT/README; drop obsolete FEASIBILITY and LANGUAGE-CHOICE; align cursor rules. Co-authored-by: Cursor <cursoragent@cursor.com>
@@ -10,35 +10,36 @@ alwaysApply: true
10
10
11
11
- **Rust only** — no TypeScript/JavaScript frontend.
12
12
- **egui / eframe** for UI (`src/app.rs`, `src/main.rs`).
13
- **USB-serial printing only** — `src/print/mod.rs` via `serialport`. No Bluetooth or USB printer-class code until explicitly requested.
13
- **Printing:** USB printer-class (`rusb`), Windows spooler (Windows), and USB-serial (`serialport`) via `src/print/`.
14
14
15
15
## Module responsibilities
16
16
17
17
| Module | Responsibility |
18
18
|--------|----------------|
19
19
| `dsl/` | Parse template text → `Document` AST |
20
| `params.rs` | Collect `${Name}` tokens; substitute at print time |
20
| `params.rs` | Collect `${Name}` tokens; substitute at print / preview |
21
21
| `escpos.rs` | AST → ESC/POS bytes (in-tree; no `escpos` crate) |
22
22
| `preview.rs` | AST → `PreviewModel` for UI canvas |
23
23
| `io/` | `PosFile` JSON load/save |
24
| `print/` | Port enumeration, `SerialTransport`, `MockTransport` |
25
| `app.rs` | All egui UI: editor, preview, help, print dialog |
24
| `print/` | Discovery + transports (USB-direct, spooler, serial, mock) |
25
| `print_dialog.rs` | Shared print UI |
26
| `app.rs` | Full designer egui UI |
26
27
27
28
Keep business logic out of `app.rs` where possible — UI should call `lib` modules.
28
29
29
30
## Dependencies
30
31
31
Add a crate only when hand-rolling is unreasonable. Current allowed set:
32
Add a crate only when hand-rolling is unreasonable. Current set includes:
32
33
33
- `eframe`, `serde`, `serde_json`, `serialport`, `image`, `rfd`
34
- `eframe`, `serde`, `serde_json`, `serialport`, `rusb`, `image`, `rfd`, `barcoders`, `qrcode`, `clap`, `chrono`
34
35
35
36
Do **not** add `escpos`, `nusb`, `tauri`, or a JS toolchain without a deliberate stack change and doc update.
36
37
37
38
## Preview vs print
38
39
39
- **Preview:** approximate layout; placeholders for barcode/QR/image; unresolved `${Param}` shown literally.
40
- **Print:** substitute parameters first, then encode ESC/POS, then write to serial port at **9600 baud**.
40
- **Preview:** layout from shared wrap; bitmaps for image/barcode/QR; sample or dialog params for `${Param}`.
41
- **Print:** substitute parameters, encode ESC/POS, write via the chosen transport (serial baud is probed).
41
42
42
43
## Planned features (not in codebase yet)
43
44
44
USB printer class, Bluetooth, baud autodetect, persisted recent files/parameters, syntax highlighting. Document these only under "Planned" sections — do not implement stubs without a task.
45
Bluetooth, network TCP 9100, persisted recent files/parameters, syntax highlighting. Document these only under "Planned" sections — do not implement stubs without a task.
@@ -10,35 +10,36 @@ alwaysApply: true10
10
11
- **Rust only** — no TypeScript/JavaScript frontend.
11
- **Rust only** — no TypeScript/JavaScript frontend.
12
- **egui / eframe** for UI (`src/app.rs`, `src/main.rs`).
12
- **egui / eframe** for UI (`src/app.rs`, `src/main.rs`).
13
- **USB-serial printing only** — `src/print/mod.rs` via `serialport`. No Bluetooth or USB printer-class code until explicitly requested.
13
- **Printing:** USB printer-class (`rusb`), Windows spooler (Windows), and USB-serial (`serialport`) via `src/print/`.
14
14
15
## Module responsibilities
15
## Module responsibilities
16
16
17
| Module | Responsibility |
17
| Module | Responsibility |
18
|--------|----------------|
18
|--------|----------------|
19
| `dsl/` | Parse template text → `Document` AST |
19
| `dsl/` | Parse template text → `Document` AST |
20
| `params.rs` | Collect `${Name}` tokens; substitute at print time |
20
| `params.rs` | Collect `${Name}` tokens; substitute at print / preview |
21
| `escpos.rs` | AST → ESC/POS bytes (in-tree; no `escpos` crate) |
21
| `escpos.rs` | AST → ESC/POS bytes (in-tree; no `escpos` crate) |
22
| `preview.rs` | AST → `PreviewModel` for UI canvas |
22
| `preview.rs` | AST → `PreviewModel` for UI canvas |
23
| `io/` | `PosFile` JSON load/save |
23
| `io/` | `PosFile` JSON load/save |
24
| `print/` | Port enumeration, `SerialTransport`, `MockTransport` |
24
| `print/` | Discovery + transports (USB-direct, spooler, serial, mock) |
25
| `app.rs` | All egui UI: editor, preview, help, print dialog |
25
| `print_dialog.rs` | Shared print UI |
26
| `app.rs` | Full designer egui UI |
26
27
27
Keep business logic out of `app.rs` where possible — UI should call `lib` modules.
28
Keep business logic out of `app.rs` where possible — UI should call `lib` modules.
28
29
29
## Dependencies
30
## Dependencies
30
31
31
Add a crate only when hand-rolling is unreasonable. Current allowed set:
32
Add a crate only when hand-rolling is unreasonable. Current set includes:
32
33
33
- `eframe`, `serde`, `serde_json`, `serialport`, `image`, `rfd`
34
- `eframe`, `serde`, `serde_json`, `serialport`, `rusb`, `image`, `rfd`, `barcoders`, `qrcode`, `clap`, `chrono`
34
35
35
Do **not** add `escpos`, `nusb`, `tauri`, or a JS toolchain without a deliberate stack change and doc update.
36
Do **not** add `escpos`, `nusb`, `tauri`, or a JS toolchain without a deliberate stack change and doc update.
36
37
37
## Preview vs print
38
## Preview vs print
38
39
39
- **Preview:** approximate layout; placeholders for barcode/QR/image; unresolved `${Param}` shown literally.
40
- **Preview:** layout from shared wrap; bitmaps for image/barcode/QR; sample or dialog params for `${Param}`.
40
- **Print:** substitute parameters first, then encode ESC/POS, then write to serial port at **9600 baud**.
41
- **Print:** substitute parameters, encode ESC/POS, write via the chosen transport (serial baud is probed).
41
42
42
## Planned features (not in codebase yet)
43
## Planned features (not in codebase yet)
43
44
44
USB printer class, Bluetooth, baud autodetect, persisted recent files/parameters, syntax highlighting. Document these only under "Planned" sections — do not implement stubs without a task.
45
Bluetooth, network TCP 9100, persisted recent files/parameters, syntax highlighting. Document these only under "Planned" sections — do not implement stubs without a task.
@@ -11,7 +11,7 @@ alwaysApply: true
11
11
- Single language: **Rust** with **egui** (eframe) for the UI.
12
12
- Prefer std library and in-house code. Add a crate only when reimplementing would be unreasonable (e.g. `serialport`, `serde`, `image`, UI framework).
13
13
- ESC/POS encoding lives in `src/escpos.rs` — do not add the `escpos` crates.io package.
14
- Printing: **USB-serial only** in v0.1.x. No Bluetooth or USB printer-class until explicitly requested.
14
- Printing: USB printer-class (`rusb`), Windows spooler, and USB-serial (`serialport`). Do not add Bluetooth or network printing until explicitly requested.
15
15
16
16
## Testing
17
17
@@ -60,7 +60,7 @@ alwaysApply: true
60
60
61
61
## Releases
62
62
63
- GitLab CI (`.gitlab-ci.yml`) runs tests on push.
63
- GitLab CI (`.gitlab-ci.yml`) runs tests on **merge requests**; tagged releases build artifacts.
64
64
- Tagged releases produce Windows `.exe`, Debian `.deb` (apt), and Arch `.pkg.tar.zst` (pacman).
65
65
- Debian packages use `cargo-deb` and `[package.metadata.deb]` in `Cargo.toml`.
66
66
- Arch packages use `packaging/arch/PKGBUILD` and `makepkg`.
@@ -11,7 +11,7 @@ alwaysApply: true11
- Single language: **Rust** with **egui** (eframe) for the UI.
11
- Single language: **Rust** with **egui** (eframe) for the UI.
12
- Prefer std library and in-house code. Add a crate only when reimplementing would be unreasonable (e.g. `serialport`, `serde`, `image`, UI framework).
12
- Prefer std library and in-house code. Add a crate only when reimplementing would be unreasonable (e.g. `serialport`, `serde`, `image`, UI framework).
13
- ESC/POS encoding lives in `src/escpos.rs` — do not add the `escpos` crates.io package.
13
- ESC/POS encoding lives in `src/escpos.rs` — do not add the `escpos` crates.io package.
14
- Printing: **USB-serial only** in v0.1.x. No Bluetooth or USB printer-class until explicitly requested.
14
- Printing: USB printer-class (`rusb`), Windows spooler, and USB-serial (`serialport`). Do not add Bluetooth or network printing until explicitly requested.
15
15
16
## Testing
16
## Testing
17
17
@@ -60,7 +60,7 @@ alwaysApply: true60
60
61
## Releases
61
## Releases
62
62
63
- GitLab CI (`.gitlab-ci.yml`) runs tests on push.
63
- GitLab CI (`.gitlab-ci.yml`) runs tests on **merge requests**; tagged releases build artifacts.
64
- Tagged releases produce Windows `.exe`, Debian `.deb` (apt), and Arch `.pkg.tar.zst` (pacman).
64
- Tagged releases produce Windows `.exe`, Debian `.deb` (apt), and Arch `.pkg.tar.zst` (pacman).
65
- Debian packages use `cargo-deb` and `[package.metadata.deb]` in `Cargo.toml`.
65
- Debian packages use `cargo-deb` and `[package.metadata.deb]` in `Cargo.toml`.
66
- Arch packages use `packaging/arch/PKGBUILD` and `makepkg`.
66
- Arch packages use `packaging/arch/PKGBUILD` and `makepkg`.
@@ -14,8 +14,8 @@ alwaysApply: true
14
14
| System design | `docs/ARCHITECTURE.md` | — |
15
15
| DSL grammar | `docs/DSL-SPEC.md` | `docs/HELP.md` (user subset) |
16
16
| `.pos` file schema | `docs/FILE-FORMAT.md` | — |
17
| Printing / ESC/POS | `docs/PRINTING.md` | `docs/HELP.md` (USB section) |
18
| Stack choice | `docs/LANGUAGE-CHOICE.md` | `README.md` summary |
17
| Printing / ESC/POS | `docs/PRINTING.md` | `docs/HELP.md` (print section) |
18
| Build / packages | `docs/BUILD.md` | `README.md` summary |
19
19
20
20
## When to update docs
21
21
@@ -14,8 +14,8 @@ alwaysApply: true14
| System design | `docs/ARCHITECTURE.md` | — |
14
| System design | `docs/ARCHITECTURE.md` | — |
15
| DSL grammar | `docs/DSL-SPEC.md` | `docs/HELP.md` (user subset) |
15
| DSL grammar | `docs/DSL-SPEC.md` | `docs/HELP.md` (user subset) |
16
| `.pos` file schema | `docs/FILE-FORMAT.md` | — |
16
| `.pos` file schema | `docs/FILE-FORMAT.md` | — |
17
| Printing / ESC/POS | `docs/PRINTING.md` | `docs/HELP.md` (USB section) |
17
| Printing / ESC/POS | `docs/PRINTING.md` | `docs/HELP.md` (print section) |
18
| Stack choice | `docs/LANGUAGE-CHOICE.md` | `README.md` summary |
18
| Build / packages | `docs/BUILD.md` | `README.md` summary |
19
19
20
## When to update docs
20
## When to update docs
21
21
@@ -1,38 +1,42 @@
1
1
# posprint
2
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 directly to USB serial POS printers via raw ESC/POS bytes.
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, or USB-serial).
4
4
5
5
**Target platforms:** Windows and Linux (x64).
6
6
7
7
## Status
8
8
9
**v0.2.0** — Rust + egui app with editor, preview, help, `.pos` files, parameters, and USB-serial printing.
9
**v0.2.0** — Rust + egui app with editor, preview, help, `.pos` files, parameters, and multi-transport printing.
10
10
11
11
## Build and run
12
12
13
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
14
15
15
```bash
16
cargo test # 31 unit tests
16
cargo test # unit tests
17
17
cargo run # launch the designer
18
18
cargo build --release
19
19
```
20
20
21
**Scripts:** `scripts/build-windows.ps1`, `scripts/build-linux.sh`, `scripts/build-arch.sh`
21
**Scripts:** `scripts/build-windows.ps1`, `scripts/build-linux.sh`, `scripts/build-arch.sh`
22
(Interactive shells offer to install missing dependencies.)
22
23
23
24
### Command-line printing
24
25
25
26
```bash
26
# Windows
27
# Windows (serial or spooler queue name)
27
28
posprint print receipt.pos -p COM3 --set StoreName="Shop" --set DocumentNumber=42
28
29
29
30
# Linux
30
31
posprint print receipt.pos -p /dev/ttyUSB0 --set StoreName="Shop" --set DocumentNumber=42
32
33
# Embedded CLI help for this OS
34
posprint cli-help
31
35
```
32
36
33
37
All `${Parameters}` must be supplied via `--set NAME=VALUE` or the command fails.
34
38
35
**Linux:** add your user to the `dialout` group for USB-serial printer access.
39
**Linux serial:** add your user to the `dialout` group.
36
40
37
41
## Releases (GitLab CI)
38
42
@@ -42,39 +46,22 @@ All `${Parameters}` must be supplied via `--set NAME=VALUE` or the command fails
42
46
| Linux (Arch) | `.pkg.tar.zst` (x86_64) | `sudo pacman -U posprint_*_x86_64.pkg.tar.zst` |
43
47
| Windows | `posprint.exe` | Download from GitLab release job artifacts |
44
48
45
Tag a version (e.g. `v0.1.0`) to trigger release builds.
49
Tag a version (e.g. `0.2.0`) to trigger release builds.
46
50
47
51
## Features
48
52
49
- Markdown-like template editor with live preview
50
- Page width: auto-scale or fixed width (mm)
53
- Markdown-like template editor with live preview (Design tab)
54
- Page width (mm) and calibrated preview zoom
51
55
- 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
56
- Parameter tokens (`${DocumentNumber}`) with print dialog and CLI `--set`
57
- Bullet lists, headings, `@date` / `@time`, barcodes, QR, images
58
- Print via USB-direct, Windows spooler, or serial (baud probed)
55
59
- In-app **Help** tab (from [docs/HELP.md](docs/HELP.md))
56
60
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
70
ESC/POS encoding is implemented in-tree.
71
72
## Design documents
61
## Documentation
73
62
74
63
| Document | Description |
75
64
|----------|-------------|
76
| [FEASIBILITY.md](docs/FEASIBILITY.md) | Feasibility assessment, complexity estimate, risks |
77
| [LANGUAGE-CHOICE.md](docs/LANGUAGE-CHOICE.md) | Language and framework recommendation |
78
65
| [HELP.md](docs/HELP.md) | **User reference** (mirrored in-app Help tab) |
79
66
| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | System architecture and module breakdown |
80
67
| [DSL-SPEC.md](docs/DSL-SPEC.md) | Document markup language (`.pos` body syntax) |
@@ -84,21 +71,18 @@ ESC/POS encoding is implemented in-tree.
84
71
85
72
Documentation must stay aligned with the codebase; see `.cursor/rules/documentation.mdc`.
86
73
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.
74
## Dependencies (minimal)
94
75
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 |
76
| Crate | Why |
77
|-------|-----|
78
| `eframe` / `egui` | Native UI |
79
| `serde` / `serde_json` | `.pos` file format |
80
| `serialport` | Serial printer I/O |
81
| `rusb` | USB printer-class devices |
82
| `image` | Load PNG/JPEG for `@image` |
83
| `rfd` | Native open/save dialogs |
84
| `barcoders` | Raster barcode rendering |
85
| `qrcode` | Raster QR rendering |
86
| `clap` | CLI `print` / `cli-help` |
103
87
104
Stack: **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).
88
ESC/POS encoding is implemented in-tree.
@@ -1,38 +1,42 @@1
# posprint1
# posprint2
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 directly to USB serial POS printers via raw ESC/POS bytes.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, or USB-serial).4
4
5
**Target platforms:** Windows and Linux (x64).5
**Target platforms:** Windows and Linux (x64).6
6
7
## Status7
## Status8
8
9
**v0.2.0** — Rust + egui app with editor, preview, help, `.pos` files, parameters, and USB-serial printing.9
**v0.2.0** — Rust + egui app with editor, preview, help, `.pos` files, parameters, and multi-transport printing.10
10
11
## Build and run11
## Build and run12
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.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
14
15
```bash15
```bash16
cargo test # 31 unit tests16
cargo test # unit tests17
cargo run # launch the designer17
cargo run # launch the designer18
cargo build --release18
cargo build --release19
```19
```20
20
21
**Scripts:** `scripts/build-windows.ps1`, `scripts/build-linux.sh`, `scripts/build-arch.sh`21
**Scripts:** `scripts/build-windows.ps1`, `scripts/build-linux.sh`, `scripts/build-arch.sh` 22
(Interactive shells offer to install missing dependencies.)22
23
23
### Command-line printing24
### Command-line printing24
25
25
```bash26
```bash26
# Windows27
# Windows (serial or spooler queue name)27
posprint print receipt.pos -p COM3 --set StoreName="Shop" --set DocumentNumber=4228
posprint print receipt.pos -p COM3 --set StoreName="Shop" --set DocumentNumber=4228
29
29
# Linux30
# Linux30
posprint print receipt.pos -p /dev/ttyUSB0 --set StoreName="Shop" --set DocumentNumber=4231
posprint print receipt.pos -p /dev/ttyUSB0 --set StoreName="Shop" --set DocumentNumber=4232
33
# Embedded CLI help for this OS34
posprint cli-help31
```35
```32
36
33
All `${Parameters}` must be supplied via `--set NAME=VALUE` or the command fails.37
All `${Parameters}` must be supplied via `--set NAME=VALUE` or the command fails.34
38
35
**Linux:** add your user to the `dialout` group for USB-serial printer access.39
**Linux serial:** add your user to the `dialout` group.36
40
37
## Releases (GitLab CI)41
## Releases (GitLab CI)38
42
@@ -42,39 +46,22 @@ All `${Parameters}` must be supplied via `--set NAME=VALUE` or the command fails42
| Linux (Arch) | `.pkg.tar.zst` (x86_64) | `sudo pacman -U posprint_*_x86_64.pkg.tar.zst` |46
| 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 |47
| Windows | `posprint.exe` | Download from GitLab release job artifacts |44
48
45
Tag a version (e.g. `v0.1.0`) to trigger release builds.49
Tag a version (e.g. `0.2.0`) to trigger release builds.46
50
47
## Features51
## Features48
52
49
- Markdown-like template editor with live preview53
- Markdown-like template editor with live preview (Design tab)50
- Page width: auto-scale or fixed width (mm)54
- Page width (mm) and calibrated preview zoom51
- Save and load `.pos` files55
- Save and load `.pos` files52
- Parameter tokens (`${DocumentNumber}`) with print-time popup and value reuse56
- Parameter tokens (`${DocumentNumber}`) with print dialog and CLI `--set`53
- Barcodes, QR codes, and images (including parameterized content)57
- Bullet lists, headings, `@date` / `@time`, barcodes, QR, images54
- Print to USB-serial POS printers via raw ESC/POS bytes58
- Print via USB-direct, Windows spooler, or serial (baud probed)55
- In-app **Help** tab (from [docs/HELP.md](docs/HELP.md))59
- In-app **Help** tab (from [docs/HELP.md](docs/HELP.md))56
60
57
## Dependencies (minimal)61
## Documentation58
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
70
ESC/POS encoding is implemented in-tree.71
72
## Design documents73
62
74
| Document | Description |63
| Document | Description |75
|----------|-------------|64
|----------|-------------|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) |65
| [HELP.md](docs/HELP.md) | **User reference** (mirrored in-app Help tab) |79
| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | System architecture and module breakdown |66
| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | System architecture and module breakdown |80
| [DSL-SPEC.md](docs/DSL-SPEC.md) | Document markup language (`.pos` body syntax) |67
| [DSL-SPEC.md](docs/DSL-SPEC.md) | Document markup language (`.pos` body syntax) |@@ -84,21 +71,18 @@ ESC/POS encoding is implemented in-tree.84
71
85
Documentation must stay aligned with the codebase; see `.cursor/rules/documentation.mdc`.72
Documentation must stay aligned with the codebase; see `.cursor/rules/documentation.mdc`.86
73
87
## Planned features74
## Dependencies (minimal)88
89
- Bluetooth printer support (deferred)90
91
## Quick feasibility summary92
93
**Verdict: feasible** for a small team or solo developer, with the printing layer as the main engineering risk.94
75
95
| Area | Complexity | Notes |76
| Crate | Why |96
|------|------------|-------|77
|-------|-----|97
| Editor + preview UI | Medium | Well-trodden path |78
| `eframe` / `egui` | Native UI |98
| DSL parser + renderer | Medium | Custom grammar, bounded scope |79
| `serde` / `serde_json` | `.pos` file format |99
| Parameters | Low | Straightforward substitution |80
| `serialport` | Serial printer I/O |100
| Barcodes / QR / images | Low–Medium | Mature libraries exist |81
| `rusb` | USB printer-class devices |101
| USB / BT printer I/O | **High** | OS differences, device quirks |82
| `image` | Load PNG/JPEG for `@image` |102
| **Overall (MVP)** | **Medium–High** | ~6–10 weeks for one experienced dev |83
| `rfd` | Native open/save dialogs |84
| `barcoders` | Raster barcode rendering |85
| `qrcode` | Raster QR rendering |86
| `clap` | CLI `print` / `cli-help` |103
87
104
Stack: **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).88
ESC/POS encoding is implemented in-tree.@@ -5,57 +5,73 @@
5
5
posprint is a **single Rust binary** using **egui** (eframe). No separate frontend language, no WebView, no IPC layer.
6
6
7
7
```
8
┌─────────────────────────────────────────┐
9
│ posprint (Rust + egui) │
10
│ - Editor / Preview / Help tabs │
11
│ - DSL parse → AST │
12
│ - Preview layout + in-tree ESC/POS │
13
│ - USB-serial printer discovery/print │
14
│ - `.pos` JSON load/save (serde) │
15
└─────────────────────────────────────────┘
8
┌──────────────────────────────────────────────────┐
9
│ posprint (Rust + egui) │
10
│ - Design (editor + preview) / Help │
11
│ - DSL parse → AST → preview + ESC/POS │
12
│ - USB-direct / Win spooler / serial printing │
13
│ - `.pos` JSON load/save (serde) │
14
└──────────────────────────────────────────────────┘
16
15
```
17
16
18
17
### Source layout
19
18
20
19
```
21
20
src/
22
├── main.rs # eframe entry point
23
├── app.rs # egui UI (editor, preview, help, print dialog)
24
├── lib.rs # crate root; exports + HELP_MARKDOWN
25
├── dsl/ # Parser and AST (mod.rs, parser.rs)
26
├── params.rs # Parameter collect/substitute
27
├── escpos.rs # ESC/POS byte encoder (in-tree)
28
├── preview.rs # Preview model for UI canvas
29
├── io/mod.rs # .pos file format (PosFile, PosMetadata)
30
└── print/mod.rs # USB-serial discovery, SerialTransport, MockTransport
21
├── main.rs # CLI + eframe / print-only entry
22
├── app.rs # Full designer UI
23
├── print_only_app.rs # Print-only window (--print)
24
├── print_dialog.rs # Shared print dialog
25
├── cli.rs # clap: print, cli-help
26
├── lib.rs # crate root; HELP_MARKDOWN
27
├── dsl/ # Parser and AST
28
├── params.rs # Parameter collect / substitute / preview samples
29
├── escpos.rs # ESC/POS byte encoder (in-tree)
30
├── preview.rs # PreviewModel for UI canvas
31
├── text_wrap.rs # Shared wrap (preview + print)
32
├── datetime.rs # @date / @time formatting
33
├── raster.rs # Barcode / QR bitmaps
34
├── editor_assist.rs # @ autocomplete, Insert snippets
35
├── help_view.rs # Markdown help renderer
36
├── io/mod.rs # PosFile, PosMetadata
37
├── pipeline.rs # Encode / print helpers
38
├── print/
39
│ ├── mod.rs # list_printers, SerialTransport, MockTransport
40
│ ├── usb_direct.rs # USB printer-class (rusb)
41
│ └── win_spool.rs # Windows spooler (Windows)
42
└── shell_integration/ # OS “Print” context menu helpers
31
43
```
32
44
33
### External dependencies (minimal)
45
### External dependencies
34
46
35
47
| Crate | Role |
36
48
|-------|------|
37
49
| `eframe` / `egui` | Native UI |
38
50
| `serde` / `serde_json` | `.pos` file format |
39
| `serialport` | USB-serial enumeration and I/O |
40
| `image` | Decode/resize images for `@image` raster print |
41
| `rfd` | Native open/save file dialogs |
51
| `serialport` | Serial enumeration and I/O |
52
| `rusb` | USB printer-class devices |
53
| `image` | Decode/resize images |
54
| `rfd` | Native open/save dialogs |
55
| `barcoders` / `qrcode` | Raster barcodes and QR |
56
| `clap` | CLI |
57
| `chrono` | Date/time |
58
| `pulldown-cmark` | In-app Help markdown |
42
59
43
ESC/POS command generation is **not** delegated to a third-party crate.
60
ESC/POS generation is **in-tree** (`escpos.rs`), not the `escpos` crates.io package.
44
61
45
62
---
46
63
47
64
## UI structure
48
65
49
| Tab / area | Module | Description |
50
|------------|--------|-------------|
51
| **Editor** | `app.rs` | Multiline `TextEdit` (monospace) for template source |
52
| **Preview** | `app.rs` + `preview.rs` | Canvas render of `PreviewModel`; auto-scale or fixed mm |
53
| **Help** | `app.rs` | Scrollable view of `docs/HELP.md` via `include_str!` |
54
| Toolbar | `app.rs` | New, Open, Save, Save As, Print |
55
| Settings | `app.rs` | Page width (mm), preview mode |
56
| Print dialog | `app.rs` | Parameter fields + USB-serial printer picker |
66
| Area | Module | Description |
67
|------|--------|-------------|
68
| **Design** | `app.rs` | Editor + side preview |
69
| **Help** | `help_view.rs` | `docs/HELP.md` via `include_str!` |
70
| Toolbar | `app.rs` | New, Open, Save, Save As, Insert, Print |
71
| Settings | `app.rs` | Page width (mm), preview zoom |
72
| Print dialog | `print_dialog.rs` | Parameters + multi-transport printer picker |
57
73
58
Bottom panel switches tabs. Top panel holds actions and settings.
74
While the print dialog is open, the main UI is disabled and editor autocomplete does not steal focus.
59
75
60
76
---
61
77
@@ -63,117 +79,94 @@ Bottom panel switches tabs. Top panel holds actions and settings.
63
79
64
80
### Edit loop (live preview)
65
81
66
1. User types in the Editor tab.
82
1. User edits the template on the Design tab.
67
83
2. Each frame, `parse(&body)` runs; errors show in the toolbar.
68
3. On Preview tab, `render_preview(&doc, &metadata)` builds a `PreviewModel`.
69
4. Canvas draws text lines, rules, and placeholders for barcode/QR/image.
70
71
Preview is **not debounced** — it re-parses when the Preview tab is shown (and parse runs every frame for error display).
84
3. `render_preview` builds a `PreviewModel` (text, rules, bitmaps, spacers).
85
4. Canvas draws with calibrated zoom (`PREVIEW_SCREEN_CALIBRATION`) and Font A–matched text size.
72
86
73
87
### Save / load
74
88
75
1. **Open:** `rfd` file dialog → `PosFile::load_from_path` → populate `body`, `metadata`, `file_path`.
76
2. **Save / Save As:** `PosFile::save_to_path` writes pretty-printed JSON.
89
1. **Open:** `rfd` → `PosFile::load_from_path`.
90
2. **Save / Save As:** pretty-printed JSON.
77
91
78
Image paths in `@image` resolve relative to the `.pos` file directory on print.
92
`@image` paths resolve relative to the `.pos` directory on preview and print.
79
93
80
94
### Print
81
95
82
1. User clicks **Print** → parse body → `collect_parameter_names(&doc)`.
83
2. Modal shows one field per unique parameter; pre-filled from `last_params` (in-memory).
84
3. User selects a USB-serial port from `list_usb_serial_printers()`.
85
4. `substitute_document` → `EscPosEncoder::encode_document` → `SerialTransport::open` (9600 baud) → `print_bytes`.
96
1. **Print** → parse → `collect_parameter_names`.
97
2. Dialog: one field per parameter; `list_printers()` for USB / spooler / serial.
98
3. `substitute_document` → `EscPosEncoder` → `open_printer` → `print_bytes`.
99
4. Serial baud is probed (`115200` first, then `9600`, …).
86
100
87
101
---
88
102
89
103
## Key types
90
104
91
Implemented in `dsl/mod.rs`, `io/mod.rs`, `print/mod.rs`:
92
93
105
```rust
94
106
// dsl/
95
107
struct Document { blocks: Vec<Block> }
96
97
108
enum Block {
98
109
Paragraph { align, inlines },
99
110
List { align, items },
100
Heading { level, inlines },
101
Rule,
102
Feed(u8),
103
Cut,
104
Image { path, width: ImageWidth, align },
105
Barcode { symbology, data, height, align, show_text },
106
Qr { data, size, ecc, align },
111
Heading { level, align, inlines },
112
Rule, Feed(u8), Cut,
113
Image { path, width, align },
114
Barcode { mode, symbology, data, height, align, show_text },
115
Qr { mode, data, size, ecc, version, align },
116
Date { format, align },
117
Time { format, align },
107
118
}
119
enum Inline { Text(String), Param(String) }
108
120
109
121
// io/
110
struct PosFile { version, metadata: PosMetadata, body }
111
struct PosMetadata { title, page_width_mm, preview_mode, chars_per_line, codepage }
122
struct PosMetadata { title, page_width_mm, chars_per_line, codepage }
123
// printable_dots() = chars_per_line() * 12
112
124
113
125
// print/
114
struct PrinterDevice { id, display_name, port_name }
115
trait PrinterTransport { write_all, flush }
126
enum PrinterTarget { Serial(String), UsbDirect { … }, WinSpooler(String) }
116
127
```
117
128
129
Legacy JSON fields `preview_mode` and `cut_after_print` are ignored if present.
130
118
131
---
119
132
120
133
## Preview vs print fidelity
121
134
122
135
| Aspect | Preview | Print |
123
136
|--------|---------|-------|
124
| Text font | egui monospace/proportional | Printer built-in font |
125
| Line width | From `chars_per_line()` | ESC/POS dot width from `page_width_mm` |
126
| Images | `[image: path]` placeholder | Monochrome raster (GS v 0) |
127
| Barcodes / QR | Text placeholder | Native ESC/POS commands |
128
| Alignment | Canvas positioning | ESC a |
129
130
Both paths share the same **AST**; substitution happens only at print time. Preview shows unresolved `${Param}` tokens as-is.
137
| Text | egui monospace (print-matched size) | Printer Font A |
138
| Line width | `chars_per_line` / `printable_dots` | Same wrap model |
139
| Images / barcode / QR | Raster bitmaps | ESC/POS native or GS v 0 |
140
| Blank lines | Spacer = line spacing dots | ESC d |
141
| Parameters | Sample / dialog values | Substituted values |
131
142
132
143
---
133
144
134
## State persistence (current)
145
## State persistence
135
146
136
| Data | Storage | Notes |
137
|------|---------|-------|
138
| Template + metadata | `.pos` file on disk | User saves explicitly |
139
| Last parameter values | `PosPrintApp.last_params` | In-memory only; lost on quit |
140
| Recent files | — | Not implemented |
141
| Selected printer | — | Not persisted between sessions |
147
| Data | Storage |
148
|------|---------|
149
| Template + metadata | `.pos` file |
150
| Last parameter values | In-memory (`print_dialog.last_params`) |
151
| Recent files / selected printer | Not persisted |
142
152
143
153
---
144
154
145
155
## Testing
146
156
147
| Layer | Location | Approach |
148
|-------|----------|----------|
149
| DSL parser | `dsl/parser.rs` | Unit tests |
150
| Parameters | `params.rs` | Unit tests |
151
| ESC/POS encoder | `escpos.rs` | Byte structure tests |
152
| Preview | `preview.rs` | Unit tests |
153
| `.pos` I/O | `io/mod.rs` | Round-trip + tempfile tests |
154
| Printer I/O | `print/mod.rs` | `MockTransport`; no hardware in CI |
155
| App | `app.rs` | Default template parse/param tests |
157
| Layer | Location |
158
|-------|----------|
159
| DSL, params, ESC/POS, preview, wrap, I/O, print mocks | `src/**` unit tests |
160
| App / shell helpers | `src/main.rs` tests |
156
161
157
Run: `cargo test` (20 tests). CI runs this on Linux (Docker) and Windows (shell runner).
162
Run: `cargo test` (~100 tests). CI: tests on merge requests; release artifacts on tags.
158
163
159
164
---
160
165
161
166
## Build and release
162
167
163
- **CI:** GitLab (`.gitlab-ci.yml`) — `cargo test` on push; release artifacts on tags.
164
- **Linux artifact:** `.deb` via `cargo-deb` (`[package.metadata.deb]` in `Cargo.toml`).
165
- **Windows artifact:** `target/release/posprint.exe`.
166
- **Versioning:** Semver in `Cargo.toml`; `.pos` `version` field for file-format migrations.
167
168
---
169
170
## Planned (not implemented)
171
172
- USB printer class (bulk OUT) without serial emulation
173
- Bluetooth SPP
174
- Network printers (TCP 9100)
175
- Baud-rate autodetect / settings UI
176
- Persisted last parameters and recent files
177
- Syntax highlighting in editor
168
- **CI:** GitLab (`.gitlab-ci.yml`)
169
- **Artifacts:** Windows `.exe`, Debian `.deb`, Arch `.pkg.tar.zst`
170
- **Versioning:** Semver in `Cargo.toml`; `.pos` `version` for file-format migrations
178
171
179
See [PRINTING.md](PRINTING.md) and [DSL-SPEC.md](DSL-SPEC.md) for protocol and language details.
172
See [PRINTING.md](PRINTING.md), [DSL-SPEC.md](DSL-SPEC.md), and [BUILD.md](BUILD.md).
@@ -5,57 +5,73 @@5
posprint is a **single Rust binary** using **egui** (eframe). No separate frontend language, no WebView, no IPC layer.5
posprint is a **single Rust binary** using **egui** (eframe). No separate frontend language, no WebView, no IPC layer.6
6
7
```7
```8
┌─────────────────────────────────────────┐8
┌──────────────────────────────────────────────────┐9
│ posprint (Rust + egui) │9
│ posprint (Rust + egui) │10
│ - Editor / Preview / Help tabs │10
│ - Design (editor + preview) / Help │11
│ - DSL parse → AST │11
│ - DSL parse → AST → preview + ESC/POS │12
│ - Preview layout + in-tree ESC/POS │12
│ - USB-direct / Win spooler / serial printing │13
│ - USB-serial printer discovery/print │13
│ - `.pos` JSON load/save (serde) │14
│ - `.pos` JSON load/save (serde) │14
└──────────────────────────────────────────────────┘15
└─────────────────────────────────────────┘16
```15
```17
16
18
### Source layout17
### Source layout19
18
20
```19
```21
src/20
src/22
├── main.rs # eframe entry point21
├── main.rs # CLI + eframe / print-only entry23
├── app.rs # egui UI (editor, preview, help, print dialog)22
├── app.rs # Full designer UI24
├── lib.rs # crate root; exports + HELP_MARKDOWN23
├── print_only_app.rs # Print-only window (--print)25
├── dsl/ # Parser and AST (mod.rs, parser.rs)24
├── print_dialog.rs # Shared print dialog26
├── params.rs # Parameter collect/substitute25
├── cli.rs # clap: print, cli-help27
├── escpos.rs # ESC/POS byte encoder (in-tree)26
├── lib.rs # crate root; HELP_MARKDOWN28
├── preview.rs # Preview model for UI canvas27
├── dsl/ # Parser and AST29
├── io/mod.rs # .pos file format (PosFile, PosMetadata)28
├── params.rs # Parameter collect / substitute / preview samples30
└── print/mod.rs # USB-serial discovery, SerialTransport, MockTransport29
├── escpos.rs # ESC/POS byte encoder (in-tree)30
├── preview.rs # PreviewModel for UI canvas31
├── text_wrap.rs # Shared wrap (preview + print)32
├── datetime.rs # @date / @time formatting33
├── raster.rs # Barcode / QR bitmaps34
├── editor_assist.rs # @ autocomplete, Insert snippets35
├── help_view.rs # Markdown help renderer36
├── io/mod.rs # PosFile, PosMetadata37
├── pipeline.rs # Encode / print helpers38
├── print/39
│ ├── mod.rs # list_printers, SerialTransport, MockTransport40
│ ├── usb_direct.rs # USB printer-class (rusb)41
│ └── win_spool.rs # Windows spooler (Windows)42
└── shell_integration/ # OS “Print” context menu helpers31
```43
```32
44
33
### External dependencies (minimal)45
### External dependencies34
46
35
| Crate | Role |47
| Crate | Role |36
|-------|------|48
|-------|------|37
| `eframe` / `egui` | Native UI |49
| `eframe` / `egui` | Native UI |38
| `serde` / `serde_json` | `.pos` file format |50
| `serde` / `serde_json` | `.pos` file format |39
| `serialport` | USB-serial enumeration and I/O |51
| `serialport` | Serial enumeration and I/O |40
| `image` | Decode/resize images for `@image` raster print |52
| `rusb` | USB printer-class devices |41
| `rfd` | Native open/save file dialogs |53
| `image` | Decode/resize images |54
| `rfd` | Native open/save dialogs |55
| `barcoders` / `qrcode` | Raster barcodes and QR |56
| `clap` | CLI |57
| `chrono` | Date/time |58
| `pulldown-cmark` | In-app Help markdown |42
59
43
ESC/POS command generation is **not** delegated to a third-party crate.60
ESC/POS generation is **in-tree** (`escpos.rs`), not the `escpos` crates.io package.44
61
45
---62
---46
63
47
## UI structure64
## UI structure48
65
49
| Tab / area | Module | Description |66
| Area | Module | Description |50
|------------|--------|-------------|67
|------|--------|-------------|51
| **Editor** | `app.rs` | Multiline `TextEdit` (monospace) for template source |68
| **Design** | `app.rs` | Editor + side preview |52
| **Preview** | `app.rs` + `preview.rs` | Canvas render of `PreviewModel`; auto-scale or fixed mm |69
| **Help** | `help_view.rs` | `docs/HELP.md` via `include_str!` |53
| **Help** | `app.rs` | Scrollable view of `docs/HELP.md` via `include_str!` |70
| Toolbar | `app.rs` | New, Open, Save, Save As, Insert, Print |54
| Toolbar | `app.rs` | New, Open, Save, Save As, Print |71
| Settings | `app.rs` | Page width (mm), preview zoom |55
| Settings | `app.rs` | Page width (mm), preview mode |72
| Print dialog | `print_dialog.rs` | Parameters + multi-transport printer picker |56
| Print dialog | `app.rs` | Parameter fields + USB-serial printer picker |57
73
58
Bottom panel switches tabs. Top panel holds actions and settings.74
While the print dialog is open, the main UI is disabled and editor autocomplete does not steal focus.59
75
60
---76
---61
77
@@ -63,117 +79,94 @@ Bottom panel switches tabs. Top panel holds actions and settings.63
79
64
### Edit loop (live preview)80
### Edit loop (live preview)65
81
66
1. User types in the Editor tab.82
1. User edits the template on the Design tab.67
2. Each frame, `parse(&body)` runs; errors show in the toolbar.83
2. Each frame, `parse(&body)` runs; errors show in the toolbar.68
3. On Preview tab, `render_preview(&doc, &metadata)` builds a `PreviewModel`.84
3. `render_preview` builds a `PreviewModel` (text, rules, bitmaps, spacers).69
4. Canvas draws text lines, rules, and placeholders for barcode/QR/image.85
4. Canvas draws with calibrated zoom (`PREVIEW_SCREEN_CALIBRATION`) and Font A–matched text size.70
71
Preview is **not debounced** — it re-parses when the Preview tab is shown (and parse runs every frame for error display).72
86
73
### Save / load87
### Save / load74
88
75
1. **Open:** `rfd` file dialog → `PosFile::load_from_path` → populate `body`, `metadata`, `file_path`.89
1. **Open:** `rfd` → `PosFile::load_from_path`.76
2. **Save / Save As:** `PosFile::save_to_path` writes pretty-printed JSON.90
2. **Save / Save As:** pretty-printed JSON.77
91
78
Image paths in `@image` resolve relative to the `.pos` file directory on print.92
`@image` paths resolve relative to the `.pos` directory on preview and print.79
93
80
### Print94
### Print81
95
82
1. User clicks **Print** → parse body → `collect_parameter_names(&doc)`.96
1. **Print** → parse → `collect_parameter_names`.83
2. Modal shows one field per unique parameter; pre-filled from `last_params` (in-memory).97
2. Dialog: one field per parameter; `list_printers()` for USB / spooler / serial.84
3. User selects a USB-serial port from `list_usb_serial_printers()`.98
3. `substitute_document` → `EscPosEncoder` → `open_printer` → `print_bytes`.85
4. `substitute_document` → `EscPosEncoder::encode_document` → `SerialTransport::open` (9600 baud) → `print_bytes`.99
4. Serial baud is probed (`115200` first, then `9600`, …).86
100
87
---101
---88
102
89
## Key types103
## Key types90
104
91
Implemented in `dsl/mod.rs`, `io/mod.rs`, `print/mod.rs`:92
93
```rust105
```rust94
// dsl/106
// dsl/95
struct Document { blocks: Vec<Block> }107
struct Document { blocks: Vec<Block> }96
97
enum Block {108
enum Block {98
Paragraph { align, inlines },109
Paragraph { align, inlines },99
List { align, items },110
List { align, items },100
Heading { level, inlines },111
Heading { level, align, inlines },101
Rule,112
Rule, Feed(u8), Cut,102
Feed(u8),113
Image { path, width, align },103
Cut,114
Barcode { mode, symbology, data, height, align, show_text },104
Image { path, width: ImageWidth, align },115
Qr { mode, data, size, ecc, version, align },105
Barcode { symbology, data, height, align, show_text },116
Date { format, align },106
Qr { data, size, ecc, align },117
Time { format, align },107
}118
}119
enum Inline { Text(String), Param(String) }108
120
109
// io/121
// io/110
struct PosFile { version, metadata: PosMetadata, body }122
struct PosMetadata { title, page_width_mm, chars_per_line, codepage }111
struct PosMetadata { title, page_width_mm, preview_mode, chars_per_line, codepage }123
// printable_dots() = chars_per_line() * 12112
124
113
// print/125
// print/114
struct PrinterDevice { id, display_name, port_name }126
enum PrinterTarget { Serial(String), UsbDirect { … }, WinSpooler(String) }115
trait PrinterTransport { write_all, flush }116
```127
```117
128
129
Legacy JSON fields `preview_mode` and `cut_after_print` are ignored if present.130
118
---131
---119
132
120
## Preview vs print fidelity133
## Preview vs print fidelity121
134
122
| Aspect | Preview | Print |135
| Aspect | Preview | Print |123
|--------|---------|-------|136
|--------|---------|-------|124
| Text font | egui monospace/proportional | Printer built-in font |137
| Text | egui monospace (print-matched size) | Printer Font A |125
| Line width | From `chars_per_line()` | ESC/POS dot width from `page_width_mm` |138
| Line width | `chars_per_line` / `printable_dots` | Same wrap model |126
| Images | `[image: path]` placeholder | Monochrome raster (GS v 0) |139
| Images / barcode / QR | Raster bitmaps | ESC/POS native or GS v 0 |127
| Barcodes / QR | Text placeholder | Native ESC/POS commands |140
| Blank lines | Spacer = line spacing dots | ESC d |128
| Alignment | Canvas positioning | ESC a |141
| Parameters | Sample / dialog values | Substituted values |129
130
Both paths share the same **AST**; substitution happens only at print time. Preview shows unresolved `${Param}` tokens as-is.131
142
132
---143
---133
144
134
## State persistence (current)145
## State persistence135
146
136
| Data | Storage | Notes |147
| Data | Storage |137
|------|---------|-------|148
|------|---------|138
| Template + metadata | `.pos` file on disk | User saves explicitly |149
| Template + metadata | `.pos` file |139
| Last parameter values | `PosPrintApp.last_params` | In-memory only; lost on quit |150
| Last parameter values | In-memory (`print_dialog.last_params`) |140
| Recent files | — | Not implemented |151
| Recent files / selected printer | Not persisted |141
| Selected printer | — | Not persisted between sessions |142
152
143
---153
---144
154
145
## Testing155
## Testing146
156
147
| Layer | Location | Approach |157
| Layer | Location |148
|-------|----------|----------|158
|-------|----------|149
| DSL parser | `dsl/parser.rs` | Unit tests |159
| DSL, params, ESC/POS, preview, wrap, I/O, print mocks | `src/**` unit tests |150
| Parameters | `params.rs` | Unit tests |160
| App / shell helpers | `src/main.rs` tests |151
| ESC/POS encoder | `escpos.rs` | Byte structure tests |152
| Preview | `preview.rs` | Unit tests |153
| `.pos` I/O | `io/mod.rs` | Round-trip + tempfile tests |154
| Printer I/O | `print/mod.rs` | `MockTransport`; no hardware in CI |155
| App | `app.rs` | Default template parse/param tests |156
161
157
Run: `cargo test` (20 tests). CI runs this on Linux (Docker) and Windows (shell runner).162
Run: `cargo test` (~100 tests). CI: tests on merge requests; release artifacts on tags.158
163
159
---164
---160
165
161
## Build and release166
## Build and release162
167
163
- **CI:** GitLab (`.gitlab-ci.yml`) — `cargo test` on push; release artifacts on tags.168
- **CI:** GitLab (`.gitlab-ci.yml`)164
- **Linux artifact:** `.deb` via `cargo-deb` (`[package.metadata.deb]` in `Cargo.toml`).169
- **Artifacts:** Windows `.exe`, Debian `.deb`, Arch `.pkg.tar.zst`165
- **Windows artifact:** `target/release/posprint.exe`.170
- **Versioning:** Semver in `Cargo.toml`; `.pos` `version` for file-format migrations166
- **Versioning:** Semver in `Cargo.toml`; `.pos` `version` field for file-format migrations.167
168
---169
170
## Planned (not implemented)171
172
- USB printer class (bulk OUT) without serial emulation173
- Bluetooth SPP174
- Network printers (TCP 9100)175
- Baud-rate autodetect / settings UI176
- Persisted last parameters and recent files177
- Syntax highlighting in editor178
171
179
See [PRINTING.md](PRINTING.md) and [DSL-SPEC.md](DSL-SPEC.md) for protocol and language details.172
See [PRINTING.md](PRINTING.md), [DSL-SPEC.md](DSL-SPEC.md), and [BUILD.md](BUILD.md).@@ -10,7 +10,7 @@ A lightweight, markdown-inspired syntax for POS receipt templates. The DSL compi
10
10
11
11
## Document structure
12
12
13
A document is a sequence of **blocks** separated by blank lines. Blocks cannot be nested except for inline markup within text blocks.
13
A document is a sequence of **blocks**. Blank lines become paper feeds (`@feed 1`). Blocks are not nested except for `${parameters}` inside text.
14
14
15
15
---
16
16
@@ -18,7 +18,7 @@ A document is a sequence of **blocks** separated by blank lines. Blocks cannot b
18
18
19
19
### Paragraphs
20
20
21
Plain text with optional inline markup. One or more consecutive non-empty lines form a paragraph.
21
Plain text (and `${parameters}`). One or more consecutive non-empty lines form a paragraph. There is **no** inline bold/italic/code markup.
22
22
23
23
```markdown
24
24
Thank you for your purchase!
@@ -132,36 +132,61 @@ Partial cut after content (if printer supports). Often placed at document end.
132
132
| `width` | `NN%` of printable width, or absolute dots (e.g. `384`) |
133
133
| `align` | `left` (default), `center`, `right` |
134
134
135
Images are converted to monochrome raster data, dithered, and scaled to width.
135
Images are converted to monochrome raster data and scaled to width (never wider than `printable_dots`).
136
137
### Date / time
138
139
```markdown
140
@date
141
@date DD-MM-YYYY
142
@time
143
@time 12h
144
@time 24h
145
```
146
147
| Directive | Behaviour |
148
|-----------|-----------|
149
| `@date` | System regional short date (`%x`) |
150
| `@date PATTERN` | Custom pattern (`YYYY`, `MM`, `DD`, …) |
151
| `@time` / `@time 24h` | 24-hour `HH:MM` |
152
| `@time 12h` | 12-hour with AM/PM |
136
153
137
154
### Barcode
138
155
139
156
```markdown
140
157
@barcode CODE128 ${Sku}
141
158
@barcode EAN13 ${EanCode} height=80
159
@barcode RASTER CODE128 ${Sku}
160
@barcode RASTER CODE93 ABC-1234
142
161
```
143
162
144
163
| Field | Values |
145
164
|-------|--------|
146
| Symbology | `CODE128`, `EAN13`, `EAN8`, `CODE39` |
165
| Mode | Optional `RASTER` prefix; otherwise native ESC/POS |
166
| Symbology | Native: `CODE128`, `EAN13`, `EAN8`, `CODE39`, `UPC-A`, `UPC-E`, `ITF`, `CODABAR`. Raster-only: `CODE93`, `CODE11` |
147
167
| Data | Literal or `${Param}` |
148
| `height` | Module height in dots (default: 64) |
168
| `height` | Module / PNG height in dots (default: 64) |
149
169
| `align` | `left`, `center`, `right` |
150
| `show_text` | `true` / `false` — HRI below barcode (default: true) |
170
| `show_text` | Native only: HRI below barcode |
171
172
Raster barcodes stretch horizontally to full printable width.
151
173
152
174
### QR code
153
175
154
176
```markdown
155
177
@qr https://example.com/receipt/${DocumentNumber}
156
@qr ${PaymentUrl} size=6
178
@qr ${PaymentUrl} size=6 ecc=H
179
@qr RASTER ${PaymentUrl} version=5 scale=4 ecc=M
157
180
```
158
181
159
| Attribute | Description |
160
|-----------|-------------|
161
| Data (positional) | URL or text; may include `${Param}` |
162
| `size` | Module size 1–16 (default: 4) |
163
| `ecc` | Error correction: `L`, `M`, `Q`, `H` (default: `M`) |
164
| `align` | `left`, `center`, `right` |
182
| Attribute | Native | Raster |
183
|-----------|--------|--------|
184
| Data | URL/text; may include `${Param}` | Same |
185
| `size` | Module size 1–16 (default 4) | — |
186
| `scale` | — | Pixels per module (default 4) |
187
| `version` | — | QR version 1–40 (optional) |
188
| `ecc` | `L`, `M`, `Q`, `H` (default `M`) | Same |
189
| `align` | `left`, `center`, `right` | Same |
165
190
166
191
---
167
192
@@ -190,67 +215,38 @@ ${ParameterName}
190
215
191
216
1. Before print, scan AST for all `${...}` tokens.
192
217
2. Deduplicate by name.
193
3. Show dialog with one field per unique name.
194
4. Pre-fill from last print session (global or per-file — implementation choice).
195
5. Substitute into AST, then render/print.
218
3. Show dialog with one field per unique name (or require CLI `--set`).
219
4. Pre-fill from last print session (in-memory).
220
5. Substitute into AST, then encode/print.
196
221
197
Missing parameter at print time: block print and highlight unresolved names in UI.
222
Missing parameter at print time: block print and highlight unresolved names.
198
223
199
224
---
200
225
201
226
## Comments
202
227
203
228
```markdown
204
<!-- This is a comment, not printed -->
229
<!-- this is not printed -->
205
230
```
206
231
207
HTML-style comments are stripped at parse time.
208
209
---
210
211
## Example document
212
213
```markdown
214
# ${StoreName}
215
:center:
216
217
123 Main Street
218
Tel: ${StorePhone}
219
220
---
221
Date: ${Date} Time: ${Time}
222
Receipt: ${DocumentNumber}
223
224
Item Total
225
${LineItems}
232
HTML-style comments are stripped before parse.
226
233
227
234
---
228
:right:
229
**TOTAL: ${GrandTotal}**
230
235
231
@barcode CODE128 ${DocumentNumber}
232
@feed 2
233
@qr https://shop.example.com/r/${DocumentNumber}
234
235
Thank you!
236
@feed 4
237
@cut
238
```
236
## Blank lines
239
237
240
`${LineItems}` might be pre-formatted multi-line text passed as a single parameter (v1); structured line items are a future extension.
238
A blank line (or whitespace-only line) inserts `Feed(1)` — same paper advance as `@feed 1`. On print this becomes `ESC d 1` (reliable after raster graphics).
241
239
242
240
---
243
241
244
## Parse errors
242
## Error reporting
245
243
246
The parser reports:
244
Parse errors include 1-based line and column. Typical causes:
247
245
248
- Unknown directive
249
246
- Invalid barcode symbology
250
247
- Invalid `${}` name
251
248
- Missing required directive argument
252
253
Errors include 1-based line and column for editor highlighting.
249
- Unknown `@time` format
254
250
255
251
---
256
252
@@ -262,22 +258,50 @@ Errors include 1-based line and column for editor highlighting.
262
258
| `## heading` | Bold ON → text → OFF |
263
259
| `- item` | ASCII `* ` bullet + hanging wrap |
264
260
| `:center:` | Justification center |
265
| `@feed n` | Print and feed n lines |
261
| `@feed n` / blank line | ESC d n |
266
262
| `@cut` | GS V partial cut |
267
| `@barcode` | GS k / CODE128 native |
268
| `@qr` | GS ( k QR model 2 |
263
| `@barcode` | GS k or GS v 0 raster |
264
| `@qr` | GS ( k or GS v 0 raster |
269
265
| `@image` | GS v 0 raster bit image |
266
| `@date` / `@time` | Plain text lines |
270
267
271
Full command details live in the print encoder module; see [PRINTING.md](PRINTING.md).
268
Full command details: [PRINTING.md](PRINTING.md).
272
269
273
270
---
274
271
275
272
## Future extensions (not implemented)
276
273
277
274
- `@table` for columnar line items
278
- `UPC-A` barcodes
279
- Conditionals: `@if ${HasDiscount} ... @endif`
280
- Loops / repeating sections
281
- `@signature` for custom ESC/POS hex escape
282
- Multiple code pages / Unicode subset
275
- Nested lists / numbered lists
276
- Bluetooth / network printer transports
283
277
- Syntax highlighting in the editor
278
279
---
280
281
## Example document
282
283
```markdown
284
# ${StoreName}
285
:center:
286
287
123 Main Street
288
289
---
290
@date
291
@time
292
Receipt: ${DocumentNumber}
293
294
- Item one
295
- Item two
296
297
:right:
298
TOTAL: ${GrandTotal}
299
300
@barcode CODE128 ${DocumentNumber}
301
@feed 2
302
@qr RASTER https://shop.example.com/r/${DocumentNumber} scale=4
303
304
Thank you!
305
@feed 4
306
@cut
307
```
@@ -10,7 +10,7 @@ A lightweight, markdown-inspired syntax for POS receipt templates. The DSL compi10
10
11
## Document structure11
## Document structure12
12
13
A document is a sequence of **blocks** separated by blank lines. Blocks cannot be nested except for inline markup within text blocks.13
A document is a sequence of **blocks**. Blank lines become paper feeds (`@feed 1`). Blocks are not nested except for `${parameters}` inside text.14
14
15
---15
---16
16
@@ -18,7 +18,7 @@ A document is a sequence of **blocks** separated by blank lines. Blocks cannot b18
18
19
### Paragraphs19
### Paragraphs20
20
21
Plain text with optional inline markup. One or more consecutive non-empty lines form a paragraph.21
Plain text (and `${parameters}`). One or more consecutive non-empty lines form a paragraph. There is **no** inline bold/italic/code markup.22
22
23
```markdown23
```markdown24
Thank you for your purchase!24
Thank you for your purchase!@@ -132,36 +132,61 @@ Partial cut after content (if printer supports). Often placed at document end.132
| `width` | `NN%` of printable width, or absolute dots (e.g. `384`) |132
| `width` | `NN%` of printable width, or absolute dots (e.g. `384`) |133
| `align` | `left` (default), `center`, `right` |133
| `align` | `left` (default), `center`, `right` |134
134
135
Images are converted to monochrome raster data, dithered, and scaled to width.135
Images are converted to monochrome raster data and scaled to width (never wider than `printable_dots`).136
137
### Date / time138
139
```markdown140
@date141
@date DD-MM-YYYY142
@time143
@time 12h144
@time 24h145
```146
147
| Directive | Behaviour |148
|-----------|-----------|149
| `@date` | System regional short date (`%x`) |150
| `@date PATTERN` | Custom pattern (`YYYY`, `MM`, `DD`, …) |151
| `@time` / `@time 24h` | 24-hour `HH:MM` |152
| `@time 12h` | 12-hour with AM/PM |136
153
137
### Barcode154
### Barcode138
155
139
```markdown156
```markdown140
@barcode CODE128 ${Sku}157
@barcode CODE128 ${Sku}141
@barcode EAN13 ${EanCode} height=80158
@barcode EAN13 ${EanCode} height=80159
@barcode RASTER CODE128 ${Sku}160
@barcode RASTER CODE93 ABC-1234142
```161
```143
162
144
| Field | Values |163
| Field | Values |145
|-------|--------|164
|-------|--------|146
| Symbology | `CODE128`, `EAN13`, `EAN8`, `CODE39` |165
| Mode | Optional `RASTER` prefix; otherwise native ESC/POS |166
| Symbology | Native: `CODE128`, `EAN13`, `EAN8`, `CODE39`, `UPC-A`, `UPC-E`, `ITF`, `CODABAR`. Raster-only: `CODE93`, `CODE11` |147
| Data | Literal or `${Param}` |167
| Data | Literal or `${Param}` |148
| `height` | Module height in dots (default: 64) |168
| `height` | Module / PNG height in dots (default: 64) |149
| `align` | `left`, `center`, `right` |169
| `align` | `left`, `center`, `right` |150
| `show_text` | `true` / `false` — HRI below barcode (default: true) |170
| `show_text` | Native only: HRI below barcode |171
172
Raster barcodes stretch horizontally to full printable width.151
173
152
### QR code174
### QR code153
175
154
```markdown176
```markdown155
@qr https://example.com/receipt/${DocumentNumber}177
@qr https://example.com/receipt/${DocumentNumber}156
@qr ${PaymentUrl} size=6178
@qr ${PaymentUrl} size=6 ecc=H179
@qr RASTER ${PaymentUrl} version=5 scale=4 ecc=M157
```180
```158
181
159
| Attribute | Description |182
| Attribute | Native | Raster |160
|-----------|-------------|183
|-----------|--------|--------|161
| Data (positional) | URL or text; may include `${Param}` |184
| Data | URL/text; may include `${Param}` | Same |162
| `size` | Module size 1–16 (default: 4) |185
| `size` | Module size 1–16 (default 4) | — |163
| `ecc` | Error correction: `L`, `M`, `Q`, `H` (default: `M`) |186
| `scale` | — | Pixels per module (default 4) |164
| `align` | `left`, `center`, `right` |187
| `version` | — | QR version 1–40 (optional) |188
| `ecc` | `L`, `M`, `Q`, `H` (default `M`) | Same |189
| `align` | `left`, `center`, `right` | Same |165
190
166
---191
---167
192
@@ -190,67 +215,38 @@ ${ParameterName}190
215
191
1. Before print, scan AST for all `${...}` tokens.216
1. Before print, scan AST for all `${...}` tokens.192
2. Deduplicate by name.217
2. Deduplicate by name.193
3. Show dialog with one field per unique name.218
3. Show dialog with one field per unique name (or require CLI `--set`).194
4. Pre-fill from last print session (global or per-file — implementation choice).219
4. Pre-fill from last print session (in-memory).195
5. Substitute into AST, then render/print.220
5. Substitute into AST, then encode/print.196
221
197
Missing parameter at print time: block print and highlight unresolved names in UI.222
Missing parameter at print time: block print and highlight unresolved names.198
223
199
---224
---200
225
201
## Comments226
## Comments202
227
203
```markdown228
```markdown204
<!-- This is a comment, not printed -->229
<!-- this is not printed -->205
```230
```206
231
207
HTML-style comments are stripped at parse time.232
HTML-style comments are stripped before parse.208
209
---210
211
## Example document212
213
```markdown214
# ${StoreName}215
:center:216
217
123 Main Street218
Tel: ${StorePhone}219
220
---221
Date: ${Date} Time: ${Time}222
Receipt: ${DocumentNumber}223
224
Item Total225
${LineItems}226
233
227
---234
---228
:right:229
**TOTAL: ${GrandTotal}**230
235
231
@barcode CODE128 ${DocumentNumber}236
## Blank lines232
@feed 2233
@qr https://shop.example.com/r/${DocumentNumber}234
235
Thank you!236
@feed 4237
@cut238
```239
237
240
`${LineItems}` might be pre-formatted multi-line text passed as a single parameter (v1); structured line items are a future extension.238
A blank line (or whitespace-only line) inserts `Feed(1)` — same paper advance as `@feed 1`. On print this becomes `ESC d 1` (reliable after raster graphics).241
239
242
---240
---243
241
244
## Parse errors242
## Error reporting245
243
246
The parser reports:244
Parse errors include 1-based line and column. Typical causes:247
245
248
- Unknown directive249
- Invalid barcode symbology246
- Invalid barcode symbology250
- Invalid `${}` name247
- Invalid `${}` name251
- Missing required directive argument248
- Missing required directive argument252
249
- Unknown `@time` format253
Errors include 1-based line and column for editor highlighting.254
250
255
---251
---256
252
@@ -262,22 +258,50 @@ Errors include 1-based line and column for editor highlighting.262
| `## heading` | Bold ON → text → OFF |258
| `## heading` | Bold ON → text → OFF |263
| `- item` | ASCII `* ` bullet + hanging wrap |259
| `- item` | ASCII `* ` bullet + hanging wrap |264
| `:center:` | Justification center |260
| `:center:` | Justification center |265
| `@feed n` | Print and feed n lines |261
| `@feed n` / blank line | ESC d n |266
| `@cut` | GS V partial cut |262
| `@cut` | GS V partial cut |267
| `@barcode` | GS k / CODE128 native |263
| `@barcode` | GS k or GS v 0 raster |268
| `@qr` | GS ( k QR model 2 |264
| `@qr` | GS ( k or GS v 0 raster |269
| `@image` | GS v 0 raster bit image |265
| `@image` | GS v 0 raster bit image |266
| `@date` / `@time` | Plain text lines |270
267
271
Full command details live in the print encoder module; see [PRINTING.md](PRINTING.md).268
Full command details: [PRINTING.md](PRINTING.md).272
269
273
---270
---274
271
275
## Future extensions (not implemented)272
## Future extensions (not implemented)276
273
277
- `@table` for columnar line items274
- `@table` for columnar line items278
- `UPC-A` barcodes275
- Nested lists / numbered lists279
- Conditionals: `@if ${HasDiscount} ... @endif`276
- Bluetooth / network printer transports280
- Loops / repeating sections281
- `@signature` for custom ESC/POS hex escape282
- Multiple code pages / Unicode subset283
- Syntax highlighting in the editor277
- Syntax highlighting in the editor278
279
---280
281
## Example document282
283
```markdown284
# ${StoreName}285
:center:286
287
123 Main Street288
289
---290
@date291
@time292
Receipt: ${DocumentNumber}293
294
- Item one295
- Item two296
297
:right:298
TOTAL: ${GrandTotal}299
300
@barcode CODE128 ${DocumentNumber}301
@feed 2302
@qr RASTER https://shop.example.com/r/${DocumentNumber} scale=4303
304
Thank you!305
@feed 4306
@cut307
```@@ -1,166 +0,0 @@
1
# Feasibility and complexity assessment
2
3
> **Status:** MVP (v0.1.0) **implemented** — Rust + egui, USB-serial printing, 20 unit tests. This document retains the original feasibility analysis; see [ARCHITECTURE.md](ARCHITECTURE.md) for what is built today.
4
5
## Executive summary
6
7
| Question | Answer |
8
|----------|--------|
9
| Is it feasible? | **Yes** — all required capabilities exist in mature libraries or documented protocols |
10
| Overall complexity | **Medium–high** for a complete v1; **medium** if Bluetooth is deferred |
11
| Biggest risk | Cross-platform raw printer I/O (USB class, serial, Bluetooth SPP) |
12
| Recommended MVP scope | USB-serial printers first (**done**); USB-printer-class and Bluetooth later |
13
14
A focused MVP is realistic for one developer in roughly **6–10 weeks**. A polished v1 with broad printer compatibility is closer to **3–4 months**.
15
16
---
17
18
## Requirements breakdown
19
20
### 1. Cross-platform desktop app (Windows + Linux)
21
22
| Aspect | Feasibility | Complexity |
23
|--------|-------------|------------|
24
| Single codebase, native binaries | High | Low–medium |
25
| Packaged installers (.msi/.exe, .deb/AppImage) | High | Medium |
26
27
Modern cross-platform desktop frameworks (Tauri, egui, Avalonia, Qt) all support Windows and Linux. Packaging is routine but needs CI and per-OS testing.
28
29
### 2. Markdown-like document syntax + live preview
30
31
| Aspect | Feasibility | Complexity |
32
|--------|-------------|------------|
33
| Custom lightweight DSL | High | Medium |
34
| Live preview pane | High | Medium |
35
| Width modes (auto-scale / fixed mm) | High | Low–medium |
36
37
The DSL does not need full CommonMark — a small, POS-oriented grammar keeps the parser simple. Preview renders to a monospace layout matching printer dot width (e.g. 384 dots @ 58 mm, 576 dots @ 80 mm). Matching exact printer fonts is approximate in preview; exact fidelity is only guaranteed at print time.
38
39
### 3. Save / load `.pos` files
40
41
| Aspect | Feasibility | Complexity |
42
|--------|-------------|------------|
43
| JSON or TOML envelope + body text | High | Low |
44
45
Trivial with serde (Rust) or equivalent. Version field supports forward-compatible evolution.
46
47
### 4. Parameter tokens (`${Name}`)
48
49
| Aspect | Feasibility | Complexity |
50
|--------|-------------|------------|
51
| Parse and collect unique names | High | Low |
52
| Print-time modal with last-used values | High | Low |
53
| Deduplicate same name across document | High | Low |
54
| Use in text, barcodes, QR, images | High | Low–medium |
55
56
Straightforward string substitution after validation. Image parameters might reference file paths or base64 — define clearly in DSL spec.
57
58
### 5. Barcodes, QR codes, images
59
60
| Aspect | Feasibility | Complexity |
61
|--------|-------------|------------|
62
| Generate ESC/POS barcode commands | High | Low |
63
| Generate ESC/POS QR commands | High | Low |
64
| Rasterize images to printer width | High | Medium |
65
66
ESC/POS barcode, QR, and raster image commands are implemented in `src/escpos.rs` (in-tree). Preview uses text placeholders for barcodes/QR/images.
67
68
### 6. Direct USB / Bluetooth printing (raw bytes, no spooler)
69
70
| Aspect | Feasibility | Complexity |
71
|--------|-------------|------------|
72
| USB serial (CDC-ACM, CH340, FTDI) | **High** | Medium |
73
| USB printer class (bulk OUT) | Medium | **High** |
74
| Bluetooth Classic SPP | Medium | **High** |
75
| Enumerate devices in UI | Medium | Medium |
76
| Printer-specific quirks | Ongoing | **High** |
77
78
This is the **primary technical risk**.
79
80
#### How POS printers actually connect
81
82
Most consumer thermal printers expose one of:
83
84
1. **Virtual COM port (USB-serial)** — very common; appears as `COM3` (Windows) or `/dev/ttyUSB0` / `/dev/ttyACM0` (Linux). Raw ESC/POS bytes are written to the serial port. **Easiest path.**
85
86
2. **USB printer class (interface 7)** — bulk transfers; **not implemented**. Would need `nusb` or Windows `usbprint.sys`.
87
88
3. **Bluetooth Classic SPP** — **not implemented**; deferred.
89
90
4. **Network (TCP 9100)** — common in production but **out of scope** unless added later.
91
92
“No drivers” in practice means **no Windows print spooler / CUPS job** — the app opens the device directly and writes bytes. USB-serial devices often need only the generic CDC driver already present. USB-printer-class devices on Windows may still use `usbprint.sys`, which is a kernel driver but not a vendor-specific print driver.
93
94
#### Compatibility reality
95
96
- **MVP (done):** Epson-compatible ESC/POS over USB-serial at 9600 baud.
97
- **Future:** USB printer class, Bluetooth SPP.
98
99
Expect **per-printer testing**; some devices need init sequences, code pages, or cut commands that differ slightly.
100
101
---
102
103
## Complexity by subsystem
104
105
```
106
Effort (relative)
107
Editor UI ████████░░ Medium
108
Preview renderer ███████░░░ Medium
109
DSL parser ██████░░░░ Medium
110
File I/O ██░░░░░░░░ Low
111
Parameters ███░░░░░░░ Low
112
Barcode/QR/image █████░░░░░ Low–medium
113
Printer discovery ███████░░░ Medium
114
Raw print I/O █████████░ High
115
Integration/polish ██████░░░░ Medium
116
```
117
118
---
119
120
## Effort estimate (one experienced developer)
121
122
| Phase | Scope | Duration |
123
|-------|-------|----------|
124
| **0 — Design** | Specs, DSL, file format | 1 week |
125
| **1 — Core** | Parser, ESC/POS builder, preview, `.pos` I/O | 2–3 weeks |
126
| **2 — UI** | Editor, preview split, settings, parameters dialog | 2 weeks |
127
| **3 — Print MVP** | USB-serial enumeration + print | 1–2 weeks |
128
| **4 — Hardening** | USB class, BT, edge cases, packaging | 2–4 weeks |
129
130
**MVP (serial USB only):** ~6–8 weeks
131
**Full v1 (USB + BT, packaged):** ~10–14 weeks
132
133
Add 30–50% if the developer is new to Rust or ESC/POS.
134
135
---
136
137
## Risks and mitigations
138
139
| Risk | Impact | Mitigation |
140
|------|--------|------------|
141
| Printer hardware diversity | Prints garbled or not at all | ESC/POS subset doc; test matrix; user-selectable code page |
142
| Linux permissions (`dialout`) | Cannot open serial port | Document group membership; clear error UI |
143
| Windows USB access | Admin / driver conflicts | Prefer serial-first; use `usbprint` where applicable |
144
| Bluetooth pairing UX | Users cannot find printer | Defer BT; link to OS pairing instructions |
145
| Preview ≠ print | User confusion | Label preview as approximate; same backend for print |
146
| Image size on narrow paper | Slow print or clipped | Auto-scale to page width; warn in UI |
147
148
---
149
150
## Out of scope (current release)
151
152
- Bluetooth printing
153
- USB printer class (non-serial)
154
- Network printers (TCP 9100)
155
- Non-ESC/POS protocols (Star Line, ZPL)
156
- Multi-column layout engines
157
- Collaborative editing / cloud sync
158
- macOS (feasible later with same stack)
159
160
---
161
162
## Recommendation
163
164
**MVP delivered.** Next increments: USB printer class, baud settings, persisted parameters, hardware test matrix. Bluetooth only if explicitly needed.
165
166
See [LANGUAGE-CHOICE.md](LANGUAGE-CHOICE.md) and [ARCHITECTURE.md](ARCHITECTURE.md).
@@ -1,166 +0,0 @@1
# Feasibility and complexity assessment2
3
> **Status:** MVP (v0.1.0) **implemented** — Rust + egui, USB-serial printing, 20 unit tests. This document retains the original feasibility analysis; see [ARCHITECTURE.md](ARCHITECTURE.md) for what is built today.4
5
## Executive summary6
7
| Question | Answer |8
|----------|--------|9
| Is it feasible? | **Yes** — all required capabilities exist in mature libraries or documented protocols |10
| Overall complexity | **Medium–high** for a complete v1; **medium** if Bluetooth is deferred |11
| Biggest risk | Cross-platform raw printer I/O (USB class, serial, Bluetooth SPP) |12
| Recommended MVP scope | USB-serial printers first (**done**); USB-printer-class and Bluetooth later |13
14
A focused MVP is realistic for one developer in roughly **6–10 weeks**. A polished v1 with broad printer compatibility is closer to **3–4 months**.15
16
---17
18
## Requirements breakdown19
20
### 1. Cross-platform desktop app (Windows + Linux)21
22
| Aspect | Feasibility | Complexity |23
|--------|-------------|------------|24
| Single codebase, native binaries | High | Low–medium |25
| Packaged installers (.msi/.exe, .deb/AppImage) | High | Medium |26
27
Modern cross-platform desktop frameworks (Tauri, egui, Avalonia, Qt) all support Windows and Linux. Packaging is routine but needs CI and per-OS testing.28
29
### 2. Markdown-like document syntax + live preview30
31
| Aspect | Feasibility | Complexity |32
|--------|-------------|------------|33
| Custom lightweight DSL | High | Medium |34
| Live preview pane | High | Medium |35
| Width modes (auto-scale / fixed mm) | High | Low–medium |36
37
The DSL does not need full CommonMark — a small, POS-oriented grammar keeps the parser simple. Preview renders to a monospace layout matching printer dot width (e.g. 384 dots @ 58 mm, 576 dots @ 80 mm). Matching exact printer fonts is approximate in preview; exact fidelity is only guaranteed at print time.38
39
### 3. Save / load `.pos` files40
41
| Aspect | Feasibility | Complexity |42
|--------|-------------|------------|43
| JSON or TOML envelope + body text | High | Low |44
45
Trivial with serde (Rust) or equivalent. Version field supports forward-compatible evolution.46
47
### 4. Parameter tokens (`${Name}`)48
49
| Aspect | Feasibility | Complexity |50
|--------|-------------|------------|51
| Parse and collect unique names | High | Low |52
| Print-time modal with last-used values | High | Low |53
| Deduplicate same name across document | High | Low |54
| Use in text, barcodes, QR, images | High | Low–medium |55
56
Straightforward string substitution after validation. Image parameters might reference file paths or base64 — define clearly in DSL spec.57
58
### 5. Barcodes, QR codes, images59
60
| Aspect | Feasibility | Complexity |61
|--------|-------------|------------|62
| Generate ESC/POS barcode commands | High | Low |63
| Generate ESC/POS QR commands | High | Low |64
| Rasterize images to printer width | High | Medium |65
66
ESC/POS barcode, QR, and raster image commands are implemented in `src/escpos.rs` (in-tree). Preview uses text placeholders for barcodes/QR/images.67
68
### 6. Direct USB / Bluetooth printing (raw bytes, no spooler)69
70
| Aspect | Feasibility | Complexity |71
|--------|-------------|------------|72
| USB serial (CDC-ACM, CH340, FTDI) | **High** | Medium |73
| USB printer class (bulk OUT) | Medium | **High** |74
| Bluetooth Classic SPP | Medium | **High** |75
| Enumerate devices in UI | Medium | Medium |76
| Printer-specific quirks | Ongoing | **High** |77
78
This is the **primary technical risk**.79
80
#### How POS printers actually connect81
82
Most consumer thermal printers expose one of:83
84
1. **Virtual COM port (USB-serial)** — very common; appears as `COM3` (Windows) or `/dev/ttyUSB0` / `/dev/ttyACM0` (Linux). Raw ESC/POS bytes are written to the serial port. **Easiest path.**85
86
2. **USB printer class (interface 7)** — bulk transfers; **not implemented**. Would need `nusb` or Windows `usbprint.sys`.87
88
3. **Bluetooth Classic SPP** — **not implemented**; deferred.89
90
4. **Network (TCP 9100)** — common in production but **out of scope** unless added later.91
92
“No drivers” in practice means **no Windows print spooler / CUPS job** — the app opens the device directly and writes bytes. USB-serial devices often need only the generic CDC driver already present. USB-printer-class devices on Windows may still use `usbprint.sys`, which is a kernel driver but not a vendor-specific print driver.93
94
#### Compatibility reality95
96
- **MVP (done):** Epson-compatible ESC/POS over USB-serial at 9600 baud.97
- **Future:** USB printer class, Bluetooth SPP.98
99
Expect **per-printer testing**; some devices need init sequences, code pages, or cut commands that differ slightly.100
101
---102
103
## Complexity by subsystem104
105
```106
Effort (relative)107
Editor UI ████████░░ Medium108
Preview renderer ███████░░░ Medium109
DSL parser ██████░░░░ Medium110
File I/O ██░░░░░░░░ Low111
Parameters ███░░░░░░░ Low112
Barcode/QR/image █████░░░░░ Low–medium113
Printer discovery ███████░░░ Medium114
Raw print I/O █████████░ High115
Integration/polish ██████░░░░ Medium116
```117
118
---119
120
## Effort estimate (one experienced developer)121
122
| Phase | Scope | Duration |123
|-------|-------|----------|124
| **0 — Design** | Specs, DSL, file format | 1 week |125
| **1 — Core** | Parser, ESC/POS builder, preview, `.pos` I/O | 2–3 weeks |126
| **2 — UI** | Editor, preview split, settings, parameters dialog | 2 weeks |127
| **3 — Print MVP** | USB-serial enumeration + print | 1–2 weeks |128
| **4 — Hardening** | USB class, BT, edge cases, packaging | 2–4 weeks |129
130
**MVP (serial USB only):** ~6–8 weeks 131
**Full v1 (USB + BT, packaged):** ~10–14 weeks 132
133
Add 30–50% if the developer is new to Rust or ESC/POS.134
135
---136
137
## Risks and mitigations138
139
| Risk | Impact | Mitigation |140
|------|--------|------------|141
| Printer hardware diversity | Prints garbled or not at all | ESC/POS subset doc; test matrix; user-selectable code page |142
| Linux permissions (`dialout`) | Cannot open serial port | Document group membership; clear error UI |143
| Windows USB access | Admin / driver conflicts | Prefer serial-first; use `usbprint` where applicable |144
| Bluetooth pairing UX | Users cannot find printer | Defer BT; link to OS pairing instructions |145
| Preview ≠ print | User confusion | Label preview as approximate; same backend for print |146
| Image size on narrow paper | Slow print or clipped | Auto-scale to page width; warn in UI |147
148
---149
150
## Out of scope (current release)151
152
- Bluetooth printing153
- USB printer class (non-serial)154
- Network printers (TCP 9100)155
- Non-ESC/POS protocols (Star Line, ZPL)156
- Multi-column layout engines157
- Collaborative editing / cloud sync158
- macOS (feasible later with same stack)159
160
---161
162
## Recommendation163
164
**MVP delivered.** Next increments: USB printer class, baud settings, persisted parameters, hardware test matrix. Bluetooth only if explicitly needed.165
166
See [LANGUAGE-CHOICE.md](LANGUAGE-CHOICE.md) and [ARCHITECTURE.md](ARCHITECTURE.md).@@ -3,7 +3,7 @@
3
3
A `.pos` file stores a POS print template: metadata (page settings, title) plus the DSL document body as plain text.
4
4
5
5
**Format:** JSON envelope with a `.pos` extension (human-readable, git-friendly).
6
**MIME type (suggested):** `application/vnd.posprint+json`
6
**Installed MIME type:** `application/x-posprint` (see packaging MIME XML).
7
7
8
8
---
9
9
@@ -21,7 +21,7 @@ A `.pos` file stores a POS print template: metadata (page settings, title) plus
21
21
|-------|------|----------|-------------|
22
22
| `version` | `number` | yes | File format version (currently `1`) |
23
23
| `metadata` | `object` | yes | Document settings |
24
| `body` | `string` | yes | DSL source (UTF-8, `\n` line endings normalized on load) |
24
| `body` | `string` | yes | DSL source (UTF-8) |
25
25
26
26
---
27
27
@@ -38,18 +38,30 @@ A `.pos` file stores a POS print template: metadata (page settings, title) plus
38
38
39
39
| Field | Type | Default | Description |
40
40
|-------|------|---------|-------------|
41
| `title` | `string?` | `null` | Display name in app title / recent files |
42
| `page_width_mm` | `number` | `80` | Physical paper width: `58` or `80` (others allowed) |
43
| `preview_mode` | `"autoscale"` \| `"fixed"` | `"autoscale"` | How preview panel sizes content |
44
| `chars_per_line` | `number?` | derived | Override character width for preview/print width model; derived from mm if omitted |
45
| `codepage` | `string?` | `"CP437"` | Character encoding for ESC/POS text |
41
| `title` | `string?` | `null` | Display name in app title |
42
| `page_width_mm` | `number` | `80` | Physical paper width (mm) |
43
| `chars_per_line` | `number?` | derived | Override column count; derived from mm if omitted |
44
| `codepage` | `string?` | `"CP437"` | Reserved; encoder uses CP437 today |
46
45
47
### Page width derivation
46
### Printable width model
48
47
49
| `page_width_mm` | Effective printable dots (Font A) | Default `chars_per_line` (Font A) |
50
|-----------------|----------------------------------|-----------------------------------|
51
| 53-58 | 384 | 32 |
52
| >58 | 576 | 48 |
48
Effective print/preview width uses Font A columns:
49
50
`printable_dots = chars_per_line() × 12`
51
52
| `page_width_mm` | Default `chars_per_line` | `printable_dots` |
53
|-----------------|--------------------------|------------------|
54
| ≤ 58 | 32 | 384 |
55
| > 58 | 48 | 576 |
56
57
### Legacy fields (ignored)
58
59
Unknown JSON keys are ignored by serde. Notably:
60
61
| Field | Former meaning | Current behaviour |
62
|-------|----------------|-------------------|
63
| `preview_mode` | autoscale / fixed preview | Ignored; UI uses zoom slider |
64
| `cut_after_print` | auto-cut after job | Ignored; use `@cut` in the template |
53
65
54
66
---
55
67
@@ -65,19 +77,16 @@ A `.pos` file stores a POS print template: metadata (page settings, title) plus
65
77
"page_width_mm": 80,
66
78
"codepage": "CP437"
67
79
},
68
"body": "# ${StoreName}\n:center:\n\nReceipt: ${DocumentNumber}\n\n---\n\n:right:\n**TOTAL: ${GrandTotal}**\n\n@barcode CODE128 ${DocumentNumber}\n@feed 4\n@cut\n"
80
"body": "# ${StoreName}\n:center:\n\nReceipt: ${DocumentNumber}\n\n---\n\n:right:\nTOTAL: ${GrandTotal}\n\n@barcode CODE128 ${DocumentNumber}\n@feed 4\n@cut\n"
69
81
}
70
82
```
71
83
72
For readability, the app may save `body` with literal newlines (pretty-printed JSON) when the user chooses “formatted save”; both pretty and escaped forms are valid.
73
74
84
---
75
85
76
86
## Asset resolution
77
87
78
- Paths in `@image` directives are resolved relative to the **directory containing the `.pos` file** unless absolute.
79
- Bundled assets: optional `assets/` subfolder next to the template.
80
- Parameterized image paths (`${LogoPath}`) resolve after substitution; relative paths still anchor to the `.pos` file directory.
88
- Paths in `@image` resolve relative to the **directory containing the `.pos` file** unless absolute.
89
- Parameterized paths (`${LogoPath}`) resolve after substitution; relative paths still anchor to the `.pos` directory.
81
90
82
91
---
83
92
@@ -87,42 +96,16 @@ For readability, the app may save `body` with literal newlines (pretty-printed J
87
96
|------|-----|-----------|
88
97
| — | 1 | Initial release |
89
98
90
On load, if `version` is newer than app supports → error with upgrade message.
91
If older → run migration chain (none yet).
99
On load, if `version` is newer than the app supports → error. Older versions would migrate (none yet).
92
100
93
101
---
94
102
95
## Validation rules
96
97
On save:
103
## Validation
98
104
99
- `version` must equal supported version
100
- `page_width_mm` > 0
101
- `body` must be valid UTF-8
102
103
On load:
104
105
- Parse JSON; validate schema
106
- Parse `body` with DSL parser; warnings shown in UI but file still loads
105
On save / load: JSON parse, `version == 1`, `page_width_mm > 0`, UTF-8 body. DSL parse errors show in the UI; the file can still load.
107
106
108
107
---
109
108
110
## TypeScript / Rust types (reference)
111
112
```typescript
113
interface PosFile {
114
version: number;
115
metadata: PosMetadata;
116
body: string;
117
}
118
119
interface PosMetadata {
120
title?: string;
121
page_width_mm: number;
122
preview_mode: "autoscale" | "fixed";
123
chars_per_line?: number;
124
codepage?: string;
125
}
126
```
109
## Rust types
127
110
128
Rust types use `serde` derive in `src/io/mod.rs` and are used directly by the egui app (no IPC layer).
111
Defined in `src/io/mod.rs` (`PosFile`, `PosMetadata`) with `serde` derive. Used directly by the egui app (no IPC).
@@ -3,7 +3,7 @@3
A `.pos` file stores a POS print template: metadata (page settings, title) plus the DSL document body as plain text.3
A `.pos` file stores a POS print template: metadata (page settings, title) plus the DSL document body as plain text.4
4
5
**Format:** JSON envelope with a `.pos` extension (human-readable, git-friendly). 5
**Format:** JSON envelope with a `.pos` extension (human-readable, git-friendly). 6
**MIME type (suggested):** `application/vnd.posprint+json`6
**Installed MIME type:** `application/x-posprint` (see packaging MIME XML).7
7
8
---8
---9
9
@@ -21,7 +21,7 @@ A `.pos` file stores a POS print template: metadata (page settings, title) plus21
|-------|------|----------|-------------|21
|-------|------|----------|-------------|22
| `version` | `number` | yes | File format version (currently `1`) |22
| `version` | `number` | yes | File format version (currently `1`) |23
| `metadata` | `object` | yes | Document settings |23
| `metadata` | `object` | yes | Document settings |24
| `body` | `string` | yes | DSL source (UTF-8, `\n` line endings normalized on load) |24
| `body` | `string` | yes | DSL source (UTF-8) |25
25
26
---26
---27
27
@@ -38,18 +38,30 @@ A `.pos` file stores a POS print template: metadata (page settings, title) plus38
38
39
| Field | Type | Default | Description |39
| Field | Type | Default | Description |40
|-------|------|---------|-------------|40
|-------|------|---------|-------------|41
| `title` | `string?` | `null` | Display name in app title / recent files |41
| `title` | `string?` | `null` | Display name in app title |42
| `page_width_mm` | `number` | `80` | Physical paper width: `58` or `80` (others allowed) |42
| `page_width_mm` | `number` | `80` | Physical paper width (mm) |43
| `preview_mode` | `"autoscale"` \| `"fixed"` | `"autoscale"` | How preview panel sizes content |43
| `chars_per_line` | `number?` | derived | Override column count; derived from mm if omitted |44
| `chars_per_line` | `number?` | derived | Override character width for preview/print width model; derived from mm if omitted |44
| `codepage` | `string?` | `"CP437"` | Reserved; encoder uses CP437 today |45
| `codepage` | `string?` | `"CP437"` | Character encoding for ESC/POS text |46
45
47
### Page width derivation46
### Printable width model48
47
49
| `page_width_mm` | Effective printable dots (Font A) | Default `chars_per_line` (Font A) |48
Effective print/preview width uses Font A columns:50
|-----------------|----------------------------------|-----------------------------------|49
51
| 53-58 | 384 | 32 |50
`printable_dots = chars_per_line() × 12`52
| >58 | 576 | 48 |51
52
| `page_width_mm` | Default `chars_per_line` | `printable_dots` |53
|-----------------|--------------------------|------------------|54
| ≤ 58 | 32 | 384 |55
| > 58 | 48 | 576 |56
57
### Legacy fields (ignored)58
59
Unknown JSON keys are ignored by serde. Notably:60
61
| Field | Former meaning | Current behaviour |62
|-------|----------------|-------------------|63
| `preview_mode` | autoscale / fixed preview | Ignored; UI uses zoom slider |64
| `cut_after_print` | auto-cut after job | Ignored; use `@cut` in the template |53
65
54
---66
---55
67
@@ -65,19 +77,16 @@ A `.pos` file stores a POS print template: metadata (page settings, title) plus65
"page_width_mm": 80,77
"page_width_mm": 80,66
"codepage": "CP437"78
"codepage": "CP437"67
},79
},68
"body": "# ${StoreName}\n:center:\n\nReceipt: ${DocumentNumber}\n\n---\n\n:right:\n**TOTAL: ${GrandTotal}**\n\n@barcode CODE128 ${DocumentNumber}\n@feed 4\n@cut\n"80
"body": "# ${StoreName}\n:center:\n\nReceipt: ${DocumentNumber}\n\n---\n\n:right:\nTOTAL: ${GrandTotal}\n\n@barcode CODE128 ${DocumentNumber}\n@feed 4\n@cut\n"69
}81
}70
```82
```71
83
72
For readability, the app may save `body` with literal newlines (pretty-printed JSON) when the user chooses “formatted save”; both pretty and escaped forms are valid.73
74
---84
---75
85
76
## Asset resolution86
## Asset resolution77
87
78
- Paths in `@image` directives are resolved relative to the **directory containing the `.pos` file** unless absolute.88
- Paths in `@image` resolve relative to the **directory containing the `.pos` file** unless absolute.79
- Bundled assets: optional `assets/` subfolder next to the template.89
- Parameterized paths (`${LogoPath}`) resolve after substitution; relative paths still anchor to the `.pos` directory.80
- Parameterized image paths (`${LogoPath}`) resolve after substitution; relative paths still anchor to the `.pos` file directory.81
90
82
---91
---83
92
@@ -87,42 +96,16 @@ For readability, the app may save `body` with literal newlines (pretty-printed J87
|------|-----|-----------|96
|------|-----|-----------|88
| — | 1 | Initial release |97
| — | 1 | Initial release |89
98
90
On load, if `version` is newer than app supports → error with upgrade message. 99
On load, if `version` is newer than the app supports → error. Older versions would migrate (none yet).91
If older → run migration chain (none yet).92
100
93
---101
---94
102
95
## Validation rules103
## Validation96
97
On save:98
104
99
- `version` must equal supported version105
On save / load: JSON parse, `version == 1`, `page_width_mm > 0`, UTF-8 body. DSL parse errors show in the UI; the file can still load.100
- `page_width_mm` > 0101
- `body` must be valid UTF-8102
103
On load:104
105
- Parse JSON; validate schema106
- Parse `body` with DSL parser; warnings shown in UI but file still loads107
106
108
---107
---109
108
110
## TypeScript / Rust types (reference)109
## Rust types111
112
```typescript113
interface PosFile {114
version: number;115
metadata: PosMetadata;116
body: string;117
}118
119
interface PosMetadata {120
title?: string;121
page_width_mm: number;122
preview_mode: "autoscale" | "fixed";123
chars_per_line?: number;124
codepage?: string;125
}126
```127
110
128
Rust types use `serde` derive in `src/io/mod.rs` and are used directly by the egui app (no IPC layer).111
Defined in `src/io/mod.rs` (`PosFile`, `PosMetadata`) with `serde` derive. Used directly by the egui app (no IPC).@@ -18,7 +18,7 @@ posprint print receipt.pos -p /dev/ttyUSB0 --set StoreName="My Shop" --set Docum
18
18
19
19
## Rules
20
20
21
- **`--printer` / `-p`** (required): serial device path, e.g. `/dev/ttyUSB0`, `/dev/ttyACM0`.
21
- **`--printer` / `-p`** (required): serial device path (e.g. `/dev/ttyUSB0`, `/dev/ttyACM0`), or another printer id accepted by discovery.
22
22
- **`--set NAME=VALUE`** (required for every parameter): one flag per `${Name}` in the template.
23
23
- If any `${Name}` is missing or empty, the command **fails** and lists missing parameters.
24
24
- The GUI is not started when using the `print` subcommand.
@@ -18,7 +18,7 @@ posprint print receipt.pos -p /dev/ttyUSB0 --set StoreName="My Shop" --set Docum18
18
19
## Rules19
## Rules20
20
21
- **`--printer` / `-p`** (required): serial device path, e.g. `/dev/ttyUSB0`, `/dev/ttyACM0`.21
- **`--printer` / `-p`** (required): serial device path (e.g. `/dev/ttyUSB0`, `/dev/ttyACM0`), or another printer id accepted by discovery.22
- **`--set NAME=VALUE`** (required for every parameter): one flag per `${Name}` in the template.22
- **`--set NAME=VALUE`** (required for every parameter): one flag per `${Name}` in the template.23
- If any `${Name}` is missing or empty, the command **fails** and lists missing parameters.23
- If any `${Name}` is missing or empty, the command **fails** and lists missing parameters.24
- The GUI is not started when using the `print` subcommand.24
- The GUI is not started when using the `print` subcommand.@@ -18,7 +18,7 @@ posprint print receipt.pos -p COM3 --set StoreName="My Shop" --set DocumentNumbe
18
18
19
19
## Rules
20
20
21
- **`--printer` / `-p`** (required): USB-serial port name, e.g. `COM3`, `COM4`.
21
- **`--printer` / `-p`** (required): serial port (`COM3`), or a Windows printer queue name for spooler printing.
22
22
- **`--set NAME=VALUE`** (required for every parameter): one flag per `${Name}` in the template.
23
23
- If any `${Name}` is missing or empty, the command **fails** and lists missing parameters.
24
24
- The GUI is not started when using the `print` subcommand.
@@ -35,10 +35,10 @@ posprint print C:\receipts\sale.pos -p COM3 `
35
35
--set GrandTotal=19.99
36
36
```
37
37
38
## Printer port
38
## Printer target
39
39
40
- Open **Device Manager → Ports (COM & LPT)** to find the printer COM port.
41
- Install the USB-serial driver if the device is not listed.
40
- Serial: **Device Manager → Ports (COM & LPT)** for the COM port; install the USB-serial driver if needed.
41
- Spooler: use the Windows printer queue name as `-p` (same name as in Settings → Printers).
42
42
- Close other programs using the same COM port before printing.
43
43
44
44
## Exit codes
@@ -18,7 +18,7 @@ posprint print receipt.pos -p COM3 --set StoreName="My Shop" --set DocumentNumbe18
18
19
## Rules19
## Rules20
20
21
- **`--printer` / `-p`** (required): USB-serial port name, e.g. `COM3`, `COM4`.21
- **`--printer` / `-p`** (required): serial port (`COM3`), or a Windows printer queue name for spooler printing.22
- **`--set NAME=VALUE`** (required for every parameter): one flag per `${Name}` in the template.22
- **`--set NAME=VALUE`** (required for every parameter): one flag per `${Name}` in the template.23
- If any `${Name}` is missing or empty, the command **fails** and lists missing parameters.23
- If any `${Name}` is missing or empty, the command **fails** and lists missing parameters.24
- The GUI is not started when using the `print` subcommand.24
- The GUI is not started when using the `print` subcommand.@@ -35,10 +35,10 @@ posprint print C:\receipts\sale.pos -p COM3 `35
--set GrandTotal=19.9935
--set GrandTotal=19.9936
```36
```37
37
38
## Printer port38
## Printer target39
39
40
- Open **Device Manager → Ports (COM & LPT)** to find the printer COM port.40
- Serial: **Device Manager → Ports (COM & LPT)** for the COM port; install the USB-serial driver if needed.41
- Install the USB-serial driver if the device is not listed.41
- Spooler: use the Windows printer queue name as `-p` (same name as in Settings → Printers).42
- Close other programs using the same COM port before printing.42
- Close other programs using the same COM port before printing.43
43
44
## Exit codes44
## Exit codes@@ -8,8 +8,7 @@ Built-in reference for the template editor and POS markup language.
8
8
9
9
| Tab | Purpose |
10
10
|-----|---------|
11
| **Editor** | Write and edit template source |
12
| **Preview** | Live preview of rendered output |
11
| **Design** | Side-by-side template editor and live preview |
13
12
| **Help** | This documentation |
14
13
15
14
## Toolbar actions
@@ -19,22 +18,24 @@ Built-in reference for the template editor and POS markup language.
19
18
| **New** | Empty template with defaults |
20
19
| **Open** | Load a `.pos` file |
21
20
| **Save / Save As** | Write `.pos` file (metadata + body) |
22
| **Insert** | Menu to insert images, barcodes, QR codes, `@feed`, `@cut` |
23
| **Print** | Substitute parameters, pick USB printer, send ESC/POS bytes |
21
| **Insert** | Images, barcodes, QR, date/time, parameters, `@feed`, `@cut` |
22
| **Print** | Enter parameters, pick a printer, send ESC/POS bytes |
23
24
While the Print dialog is open, the rest of the UI (including editor autocomplete) is disabled so parameter fields keep focus.
24
25
25
26
## Editor assistance
26
27
27
- Type `@` at the start of a line to see **directive autocomplete** (`feed`, `cut`, `image`, `barcode`, `qr`).
28
- Type `@` at the start of a line for **directive autocomplete** (`feed`, `cut`, `image`, `barcode`, `qr`, `date`, `time`).
28
29
- Use **Insert → Barcode / QR code** to pick native or raster type before inserting a snippet.
29
30
30
31
## Page settings
31
32
32
33
| Setting | Description |
33
34
|---------|-------------|
34
| **Page width (mm)** | Paper width — set this to match your physical roll (e.g. `53`, `58`, `80`) |
35
| **Page width (mm)** | Paper width — match your physical roll (e.g. `53`, `58`, `80`) |
35
36
| **Preview zoom** | Screen zoom; `100%` is calibrated to typical receipt width on screen |
36
37
37
Preview width and text both use the same calibrated screen scale. Preview font size is bumped to match printed Font A (~same visual size as the receipt). Blank lines / `@feed` use the same line spacing as printed text. Heading `#` uses double width/height like GS `!` on the printer; `##` uses bold only.
38
Preview width and text use the same calibrated screen scale. Preview font size is bumped to match printed Font A. Blank lines / `@feed` use the same line spacing as printed text. Heading `#` uses double width/height like GS `!` on the printer; `##` uses bold only.
38
39
39
40
If the document does not end with `@cut` (ignoring blank lines after it), a red warning appears next to **Help**.
40
41
@@ -42,7 +43,7 @@ If the document does not end with `@cut` (ignoring blank lines after it), a red
42
43
43
44
## Template language
44
45
45
A template is plain text: paragraphs, headings, directives, and inline markup.
46
A template is plain text: paragraphs, headings, lists, directives, and `${parameters}`. There is **no** inline bold/italic/code markup — asterisks and backticks print literally.
46
47
47
48
### Paragraphs
48
49
@@ -66,7 +67,7 @@ Consecutive non-empty lines form one paragraph.
66
67
- second item
67
68
```
68
69
69
Long items wrap with a hanging indent:
70
Long items wrap with a hanging indent (printed/previewed as ASCII `*`):
70
71
71
72
```text
72
73
* this is a
@@ -104,6 +105,22 @@ Directives start with `@` at the beginning of a line.
104
105
@cut
105
106
```
106
107
108
Blank lines in the editor also feed one line (same as `@feed 1`).
109
110
### Date / time
111
112
```markdown
113
@date
114
@date DD-MM-YYYY
115
@time
116
@time 12h
117
@time 24h
118
```
119
120
- `@date` with no pattern uses the system regional short date.
121
- Custom patterns use tokens such as `YYYY`, `MM`, `DD`.
122
- `@time` defaults to 24-hour; use `12h` or `24h`.
123
107
124
### Image
108
125
109
126
```markdown
@@ -121,7 +138,7 @@ Directives start with `@` at the beginning of a line.
121
138
@barcode ITF 12345678 height=80
122
139
```
123
140
124
**Raster** (rendered as bitmap — works with any symbology below). Raster barcodes are stretched horizontally to the full paper width for reliable scanning; height follows the `height` attribute.
141
**Raster** (bitmap). Raster barcodes stretch horizontally to full paper width; height follows `height`.
125
142
126
143
```markdown
127
144
@barcode RASTER CODE128 ${OrderId}
@@ -137,13 +154,13 @@ Directives start with `@` at the beginning of a line.
137
154
| `ITF` | Interleaved 2 of 5; even digit count |
138
155
| `CODABAR` | Numeric + A-D start/stop |
139
156
140
| Raster-only symbology | Use `RASTER` prefix |
141
|-----------------------|---------------------|
157
| Raster-only | Use `RASTER` prefix |
158
|-------------|---------------------|
142
159
| `CODE93`, `CODE11` | No native ESC/POS in firmware |
143
160
144
161
| Attribute | Description |
145
162
|-----------|-------------|
146
| `height` | Height in dots (default `64`; raster PNG height) |
163
| `height` | Height in dots (default `64`) |
147
164
| `align` | `left`, `center`, `right` |
148
165
| `show_text` | Native only: human-readable text under barcode |
149
166
@@ -156,7 +173,7 @@ Directives start with `@` at the beginning of a line.
156
173
@qr ${Url} size=6 ecc=H align=center
157
174
```
158
175
159
**Raster** (bitmap; supports QR versions 1–40):
176
**Raster** (bitmap; QR versions 1–40):
160
177
161
178
```markdown
162
179
@qr RASTER https://example.com/${Id}
@@ -167,7 +184,7 @@ Directives start with `@` at the beginning of a line.
167
184
|-----------|--------|--------|
168
185
| `size` | Module dot size 1–16 | — |
169
186
| `scale` | — | Pixels per module (default `4`) |
170
| `version` | — | QR version 1–40 (optional; auto if omitted) |
187
| `version` | — | QR version 1–40 (optional) |
171
188
| `ecc` | `L`, `M`, `Q`, `H` | Same |
172
189
| `align` | `left`, `center`, `right` | Same |
173
190
@@ -189,6 +206,8 @@ Directives start with `@` at the beginning of a line.
189
206
:center:
190
207
191
208
Receipt: ${DocumentNumber}
209
@date
210
@time
192
211
193
212
@barcode CODE128 ${DocumentNumber}
194
213
@qr RASTER https://shop.example.com/r/${DocumentNumber} scale=4
@@ -199,14 +218,31 @@ Receipt: ${DocumentNumber}
199
218
200
219
---
201
220
202
## GUI printing (USB)
221
## GUI printing
222
223
1. **Print** → enter parameters → choose a printer → **Print**.
203
224
204
1. **Print** → enter parameters → choose serial port → **Print**.
225
Printers may appear as:
226
227
- **USB printer-class** devices (direct bulk OUT)
228
- **Windows spooler** queues (Windows)
229
- **Serial / USB-serial** ports (`COMx`, `/dev/ttyUSB0`, …)
230
231
**Linux serial:** join the `dialout` group.
232
233
---
234
235
## CLI
236
237
```bash
238
posprint print receipt.pos -p COM3 --set StoreName=Shop
239
posprint cli-help
240
```
205
241
206
**Linux:** `dialout` group. **Windows:** printer appears as `COMx`.
242
`-p` accepts a serial port name, USB device label from discovery, or (on Windows) a spooler queue name. See platform CLI help via `posprint cli-help`.
207
243
208
244
---
209
245
210
246
## `.pos` file format
211
247
212
JSON with `version`, `metadata`, and `body` (template source).
248
JSON with `version`, `metadata`, and `body` (template source). See [FILE-FORMAT.md](FILE-FORMAT.md).
@@ -8,8 +8,7 @@ Built-in reference for the template editor and POS markup language.8
8
9
| Tab | Purpose |9
| Tab | Purpose |10
|-----|---------|10
|-----|---------|11
| **Editor** | Write and edit template source |11
| **Design** | Side-by-side template editor and live preview |12
| **Preview** | Live preview of rendered output |13
| **Help** | This documentation |12
| **Help** | This documentation |14
13
15
## Toolbar actions14
## Toolbar actions@@ -19,22 +18,24 @@ Built-in reference for the template editor and POS markup language.19
| **New** | Empty template with defaults |18
| **New** | Empty template with defaults |20
| **Open** | Load a `.pos` file |19
| **Open** | Load a `.pos` file |21
| **Save / Save As** | Write `.pos` file (metadata + body) |20
| **Save / Save As** | Write `.pos` file (metadata + body) |22
| **Insert** | Menu to insert images, barcodes, QR codes, `@feed`, `@cut` |21
| **Insert** | Images, barcodes, QR, date/time, parameters, `@feed`, `@cut` |23
| **Print** | Substitute parameters, pick USB printer, send ESC/POS bytes |22
| **Print** | Enter parameters, pick a printer, send ESC/POS bytes |23
24
While the Print dialog is open, the rest of the UI (including editor autocomplete) is disabled so parameter fields keep focus.24
25
25
## Editor assistance26
## Editor assistance26
27
27
- Type `@` at the start of a line to see **directive autocomplete** (`feed`, `cut`, `image`, `barcode`, `qr`).28
- Type `@` at the start of a line for **directive autocomplete** (`feed`, `cut`, `image`, `barcode`, `qr`, `date`, `time`).28
- Use **Insert → Barcode / QR code** to pick native or raster type before inserting a snippet.29
- Use **Insert → Barcode / QR code** to pick native or raster type before inserting a snippet.29
30
30
## Page settings31
## Page settings31
32
32
| Setting | Description |33
| Setting | Description |33
|---------|-------------|34
|---------|-------------|34
| **Page width (mm)** | Paper width — set this to match your physical roll (e.g. `53`, `58`, `80`) |35
| **Page width (mm)** | Paper width — match your physical roll (e.g. `53`, `58`, `80`) |35
| **Preview zoom** | Screen zoom; `100%` is calibrated to typical receipt width on screen |36
| **Preview zoom** | Screen zoom; `100%` is calibrated to typical receipt width on screen |36
37
37
Preview width and text both use the same calibrated screen scale. Preview font size is bumped to match printed Font A (~same visual size as the receipt). Blank lines / `@feed` use the same line spacing as printed text. Heading `#` uses double width/height like GS `!` on the printer; `##` uses bold only.38
Preview width and text use the same calibrated screen scale. Preview font size is bumped to match printed Font A. Blank lines / `@feed` use the same line spacing as printed text. Heading `#` uses double width/height like GS `!` on the printer; `##` uses bold only.38
39
39
If the document does not end with `@cut` (ignoring blank lines after it), a red warning appears next to **Help**.40
If the document does not end with `@cut` (ignoring blank lines after it), a red warning appears next to **Help**.40
41
@@ -42,7 +43,7 @@ If the document does not end with `@cut` (ignoring blank lines after it), a red42
43
43
## Template language44
## Template language44
45
45
A template is plain text: paragraphs, headings, directives, and inline markup.46
A template is plain text: paragraphs, headings, lists, directives, and `${parameters}`. There is **no** inline bold/italic/code markup — asterisks and backticks print literally.46
47
47
### Paragraphs48
### Paragraphs48
49
@@ -66,7 +67,7 @@ Consecutive non-empty lines form one paragraph.66
- second item67
- second item67
```68
```68
69
69
Long items wrap with a hanging indent:70
Long items wrap with a hanging indent (printed/previewed as ASCII `*`):70
71
71
```text72
```text72
* this is a73
* this is a@@ -104,6 +105,22 @@ Directives start with `@` at the beginning of a line.104
@cut105
@cut105
```106
```106
107
108
Blank lines in the editor also feed one line (same as `@feed 1`).109
110
### Date / time111
112
```markdown113
@date114
@date DD-MM-YYYY115
@time116
@time 12h117
@time 24h118
```119
120
- `@date` with no pattern uses the system regional short date.121
- Custom patterns use tokens such as `YYYY`, `MM`, `DD`.122
- `@time` defaults to 24-hour; use `12h` or `24h`.123
107
### Image124
### Image108
125
109
```markdown126
```markdown@@ -121,7 +138,7 @@ Directives start with `@` at the beginning of a line.121
@barcode ITF 12345678 height=80138
@barcode ITF 12345678 height=80122
```139
```123
140
124
**Raster** (rendered as bitmap — works with any symbology below). Raster barcodes are stretched horizontally to the full paper width for reliable scanning; height follows the `height` attribute.141
**Raster** (bitmap). Raster barcodes stretch horizontally to full paper width; height follows `height`.125
142
126
```markdown143
```markdown127
@barcode RASTER CODE128 ${OrderId}144
@barcode RASTER CODE128 ${OrderId}@@ -137,13 +154,13 @@ Directives start with `@` at the beginning of a line.137
| `ITF` | Interleaved 2 of 5; even digit count |154
| `ITF` | Interleaved 2 of 5; even digit count |138
| `CODABAR` | Numeric + A-D start/stop |155
| `CODABAR` | Numeric + A-D start/stop |139
156
140
| Raster-only symbology | Use `RASTER` prefix |157
| Raster-only | Use `RASTER` prefix |141
|-----------------------|---------------------|158
|-------------|---------------------|142
| `CODE93`, `CODE11` | No native ESC/POS in firmware |159
| `CODE93`, `CODE11` | No native ESC/POS in firmware |143
160
144
| Attribute | Description |161
| Attribute | Description |145
|-----------|-------------|162
|-----------|-------------|146
| `height` | Height in dots (default `64`; raster PNG height) |163
| `height` | Height in dots (default `64`) |147
| `align` | `left`, `center`, `right` |164
| `align` | `left`, `center`, `right` |148
| `show_text` | Native only: human-readable text under barcode |165
| `show_text` | Native only: human-readable text under barcode |149
166
@@ -156,7 +173,7 @@ Directives start with `@` at the beginning of a line.156
@qr ${Url} size=6 ecc=H align=center173
@qr ${Url} size=6 ecc=H align=center157
```174
```158
175
159
**Raster** (bitmap; supports QR versions 1–40):176
**Raster** (bitmap; QR versions 1–40):160
177
161
```markdown178
```markdown162
@qr RASTER https://example.com/${Id}179
@qr RASTER https://example.com/${Id}@@ -167,7 +184,7 @@ Directives start with `@` at the beginning of a line.167
|-----------|--------|--------|184
|-----------|--------|--------|168
| `size` | Module dot size 1–16 | — |185
| `size` | Module dot size 1–16 | — |169
| `scale` | — | Pixels per module (default `4`) |186
| `scale` | — | Pixels per module (default `4`) |170
| `version` | — | QR version 1–40 (optional; auto if omitted) |187
| `version` | — | QR version 1–40 (optional) |171
| `ecc` | `L`, `M`, `Q`, `H` | Same |188
| `ecc` | `L`, `M`, `Q`, `H` | Same |172
| `align` | `left`, `center`, `right` | Same |189
| `align` | `left`, `center`, `right` | Same |173
190
@@ -189,6 +206,8 @@ Directives start with `@` at the beginning of a line.189
:center:206
:center:190
207
191
Receipt: ${DocumentNumber}208
Receipt: ${DocumentNumber}209
@date210
@time192
211
193
@barcode CODE128 ${DocumentNumber}212
@barcode CODE128 ${DocumentNumber}194
@qr RASTER https://shop.example.com/r/${DocumentNumber} scale=4213
@qr RASTER https://shop.example.com/r/${DocumentNumber} scale=4@@ -199,14 +218,31 @@ Receipt: ${DocumentNumber}199
218
200
---219
---201
220
202
## GUI printing (USB)221
## GUI printing222
223
1. **Print** → enter parameters → choose a printer → **Print**.203
224
204
1. **Print** → enter parameters → choose serial port → **Print**.225
Printers may appear as:226
227
- **USB printer-class** devices (direct bulk OUT)228
- **Windows spooler** queues (Windows)229
- **Serial / USB-serial** ports (`COMx`, `/dev/ttyUSB0`, …)230
231
**Linux serial:** join the `dialout` group.232
233
---234
235
## CLI236
237
```bash238
posprint print receipt.pos -p COM3 --set StoreName=Shop239
posprint cli-help240
```205
241
206
**Linux:** `dialout` group. **Windows:** printer appears as `COMx`.242
`-p` accepts a serial port name, USB device label from discovery, or (on Windows) a spooler queue name. See platform CLI help via `posprint cli-help`.207
243
208
---244
---209
245
210
## `.pos` file format246
## `.pos` file format211
247
212
JSON with `version`, `metadata`, and `body` (template source).248
JSON with `version`, `metadata`, and `body` (template source). See [FILE-FORMAT.md](FILE-FORMAT.md).@@ -1,83 +0,0 @@
1
# Language and platform choice
2
3
## Decision (implemented)
4
5
| Decision | Choice |
6
|----------|--------|
7
| Language | **Rust** (single codebase) |
8
| UI | **egui** via **eframe** |
9
| Print protocol | **ESC/POS** (in-tree encoder) |
10
| MVP transport | **USB-serial** via `serialport` |
11
| Packaging | GitLab CI → Linux `.deb`, Windows `.exe` |
12
13
**Rationale:** One language, small dependency surface, direct control over ESC/POS bytes, native cross-platform UI without a WebView.
14
15
---
16
17
## Requirements
18
19
| Requirement | How it is met |
20
|-------------|---------------|
21
| Windows + Linux | Rust + egui + GitLab CI |
22
| Raw USB-serial print (no spooler) | `serialport` crate, 9600 baud |
23
| ESC/POS generation | `src/escpos.rs` (no external ESC/POS crate) |
24
| Live preview | `src/preview.rs` + egui canvas in `app.rs` |
25
| Small distributable | No Chromium/Node; release build uses LTO + strip |
26
| Unit tests | Every module has `#[cfg(test)]` tests |
27
28
---
29
30
## Dependencies in use
31
32
| Crate | Role | Why not hand-roll? |
33
|-------|------|-------------------|
34
| `eframe` / `egui` | UI framework | Building a GUI toolkit is out of scope |
35
| `serde` / `serde_json` | `.pos` files | Error-prone to parse/emit JSON manually |
36
| `serialport` | Cross-platform COM/tty access | OS-specific serial APIs differ |
37
| `image` | PNG/JPEG/GIF/BMP decode | Many formats and decoders |
38
| `rfd` | Native file dialogs | OS-native UX expected |
39
40
**Not used (by design):** `escpos`, `nusb`, `rusb`, `tauri`, TypeScript frontend.
41
42
---
43
44
## Candidates considered (historical)
45
46
| Option | Verdict |
47
|--------|---------|
48
| Rust + Tauri 2 + TypeScript | Rejected — two languages, WebView dependency |
49
| Rust + egui | **Selected** |
50
| C# + Avalonia | Viable but weaker serial/ESC/POS ecosystem |
51
| Go + Fyne | Weaker hardware I/O ecosystem |
52
| Python + PyQt | Poor packaging for desktop release |
53
| Electron | Bundle size too large |
54
| C++ + Qt | Slower iteration for a small app |
55
56
---
57
58
## Platform notes
59
60
### Windows
61
62
- Printers appear as `COMx` after USB-serial driver install.
63
- Release: `posprint.exe` from `cargo build --release`.
64
- CI requires a GitLab runner tagged `windows` + `shell`.
65
66
### Linux
67
68
- Devices: `/dev/ttyUSB*`, `/dev/ttyACM*`, etc.
69
- User must be in the **`dialout`** group.
70
- Release: `.deb` via `cargo deb`; install with `sudo dpkg -i …`.
71
- CI uses `rust:bookworm` image with X11 dev libs for egui.
72
73
---
74
75
## Deferred
76
77
| Item | Notes |
78
|------|-------|
79
| USB printer class (bulk) | Would need `nusb` or Windows `usbprint` path |
80
| Bluetooth SPP | Paired devices as serial ports; add when requested |
81
| macOS | Same stack should work; not in CI yet |
82
83
This document should be updated when transport or UI choices change.
@@ -1,83 +0,0 @@1
# Language and platform choice2
3
## Decision (implemented)4
5
| Decision | Choice |6
|----------|--------|7
| Language | **Rust** (single codebase) |8
| UI | **egui** via **eframe** |9
| Print protocol | **ESC/POS** (in-tree encoder) |10
| MVP transport | **USB-serial** via `serialport` |11
| Packaging | GitLab CI → Linux `.deb`, Windows `.exe` |12
13
**Rationale:** One language, small dependency surface, direct control over ESC/POS bytes, native cross-platform UI without a WebView.14
15
---16
17
## Requirements18
19
| Requirement | How it is met |20
|-------------|---------------|21
| Windows + Linux | Rust + egui + GitLab CI |22
| Raw USB-serial print (no spooler) | `serialport` crate, 9600 baud |23
| ESC/POS generation | `src/escpos.rs` (no external ESC/POS crate) |24
| Live preview | `src/preview.rs` + egui canvas in `app.rs` |25
| Small distributable | No Chromium/Node; release build uses LTO + strip |26
| Unit tests | Every module has `#[cfg(test)]` tests |27
28
---29
30
## Dependencies in use31
32
| Crate | Role | Why not hand-roll? |33
|-------|------|-------------------|34
| `eframe` / `egui` | UI framework | Building a GUI toolkit is out of scope |35
| `serde` / `serde_json` | `.pos` files | Error-prone to parse/emit JSON manually |36
| `serialport` | Cross-platform COM/tty access | OS-specific serial APIs differ |37
| `image` | PNG/JPEG/GIF/BMP decode | Many formats and decoders |38
| `rfd` | Native file dialogs | OS-native UX expected |39
40
**Not used (by design):** `escpos`, `nusb`, `rusb`, `tauri`, TypeScript frontend.41
42
---43
44
## Candidates considered (historical)45
46
| Option | Verdict |47
|--------|---------|48
| Rust + Tauri 2 + TypeScript | Rejected — two languages, WebView dependency |49
| Rust + egui | **Selected** |50
| C# + Avalonia | Viable but weaker serial/ESC/POS ecosystem |51
| Go + Fyne | Weaker hardware I/O ecosystem |52
| Python + PyQt | Poor packaging for desktop release |53
| Electron | Bundle size too large |54
| C++ + Qt | Slower iteration for a small app |55
56
---57
58
## Platform notes59
60
### Windows61
62
- Printers appear as `COMx` after USB-serial driver install.63
- Release: `posprint.exe` from `cargo build --release`.64
- CI requires a GitLab runner tagged `windows` + `shell`.65
66
### Linux67
68
- Devices: `/dev/ttyUSB*`, `/dev/ttyACM*`, etc.69
- User must be in the **`dialout`** group.70
- Release: `.deb` via `cargo deb`; install with `sudo dpkg -i …`.71
- CI uses `rust:bookworm` image with X11 dev libs for egui.72
73
---74
75
## Deferred76
77
| Item | Notes |78
|------|-------|79
| USB printer class (bulk) | Would need `nusb` or Windows `usbprint` path |80
| Bluetooth SPP | Paired devices as serial ports; add when requested |81
| macOS | Same stack should work; not in CI yet |82
83
This document should be updated when transport or UI choices change.@@ -1,17 +1,15 @@
1
1
# Printing subsystem
2
2
3
Direct raw-byte printing to POS thermal printers over **USB-serial** — without the Windows print spooler or CUPS.
4
5
> **Implementation status (v0.1.0):** USB-serial only. In-tree ESC/POS encoder in `src/escpos.rs`. USB printer class and Bluetooth are **not** implemented.
3
Raw ESC/POS output to POS thermal printers via **USB printer-class**, **Windows spooler** (Windows), or **USB-serial**.
6
4
7
5
---
8
6
9
7
## Goals
10
8
11
1. Discover serial ports (USB-serial adapters and CDC printers)
12
2. Let the user pick a port in the print dialog
9
1. Discover printers (USB-direct, Windows spooler, serial ports)
10
2. Let the user pick a target in the print dialog
13
11
3. Generate ESC/POS bytes from the AST (after parameter substitution)
14
4. Write bytes at **9600 baud** (fixed for now)
12
4. Write bytes to the chosen transport (serial baud is probed)
15
13
16
14
---
17
15
@@ -28,12 +26,13 @@ Target **Epson ESC/POS** compatible printers (58 mm / 80 mm thermal).
28
26
| Bold | ESC E | Headings level 2 only |
29
27
| Double size | GS ! | Heading level 1 |
30
28
| Alignment | ESC a | Paragraphs, images, barcodes, QR |
31
| Line feed | LF (text lines), ESC d (`@feed` / blank lines) | Text lines end with LF; explicit feeds use ESC d |
29
| Line feed | LF (text lines), ESC d (`@feed` / blank lines) | Text ends with LF; blank/`@feed` use ESC d |
30
| Raster flush | LF after GS v 0 | Ensures spacing after images/barcodes/QR rasters |
32
31
| List bullet | ASCII `*` | `- item` lines in templates |
33
| Partial cut | GS V 66 0 | `@cut` in template |
34
| Barcode | GS k | CODE128, EAN13, EAN8, CODE39 |
35
| QR Code | GS ( k | Model 2 |
36
| Raster image | GS v 0 | `@image` via `image` crate → threshold |
32
| Partial cut | GS V 66 0 | `@cut` in template only |
33
| Barcode | GS k | Native symbologies; raster via GS v 0 |
34
| QR Code | GS ( k | Model 2; or raster GS v 0 |
35
| Raster image | GS v 0 | `@image` / raster barcode / raster QR |
37
36
38
37
Encoder: `EscPosEncoder` in `src/escpos.rs` — **not** the `escpos` crates.io package.
39
38
@@ -51,7 +50,7 @@ substitute_document()
51
50
EscPosEncoder::encode_document()
52
51
│
53
52
▼
54
SerialTransport::open(port, 9600)
53
open_printer(target) # USB-direct | Win spooler | serial
55
54
│
56
55
▼
57
56
print_bytes() → write_all + flush
@@ -68,44 +67,42 @@ pub trait PrinterTransport {
68
67
69
68
| Type | Role |
70
69
|------|------|
71
| `SerialTransport` | Production — opens port via `serialport` |
70
| USB-direct (`rusb`) | USB printer-class bulk OUT (`usb_direct.rs`) |
71
| Windows spooler | Raw jobs via Win32 spooler (`win_spool.rs`, Windows only) |
72
| `SerialTransport` | USB-serial / CDC ports via `serialport` |
72
73
| `MockTransport` | Tests — records bytes in `written` vec |
73
74
74
75
### Discovery
75
76
76
`list_usb_serial_printers()` calls `serialport::available_ports()` and labels USB ports with VID/PID when available. All serial ports are listed (no POS-specific filter).
77
`list_printers()` returns, in order:
78
79
1. USB printer-class devices (`usb_direct`)
80
2. Windows spooler queues (Windows)
81
3. Serial ports (`serialport::available_ports()`, with VID/PID labels when available)
82
83
### Serial baud rates
84
85
`SerialTransport::open` tries, in order:
86
87
`115200`, `9600`, `19200`, `38400`, `57600`, `4800`
77
88
78
89
### `PrinterDevice`
79
90
80
91
| Field | Example |
81
92
|-------|---------|
82
| `id` | `serial:COM3` |
83
| `display_name` | `COM3 — USB 04b8:0e15` |
84
| `port_name` | `COM3` |
93
| `id` | `serial:COM3`, `usb:04b8:0e15:…`, `spool:POS-58` |
94
| `display_name` | Human-readable label |
95
| `target` | `Serial` / `UsbDirect` / `WinSpooler` |
85
96
86
97
---
87
98
88
99
## Print dialog (UI)
89
100
90
```
91
┌─────────────────────────────────────────┐
92
│ Print │
93
├─────────────────────────────────────────┤
94
│ Parameters (one field per unique name) │
95
│ DocumentNumber: [________] │
96
│ │
97
│ USB printer │
98
│ [ Refresh ] │
99
│ ○ COM3 — USB 04b8:0e15 │
100
│ ○ /dev/ttyUSB0 — Serial │
101
│ │
102
│ [ Cancel ] [ Print ] │
103
└─────────────────────────────────────────┘
104
```
105
106
- Parameters pre-filled from `last_params` (session memory).
107
- Same parameter name → one input, applied everywhere.
108
- Errors shown inline (parse, open port, write, barcode validation).
101
- One field per unique `${Parameter}`.
102
- Printer list: USB, spooler, and serial (Refresh button).
103
- Optional manual serial port name.
104
- While open, the main Design UI is disabled (including editor autocomplete).
105
- Errors shown inline (parse, open, write, barcode validation).
109
106
110
107
---
111
108
@@ -118,7 +115,7 @@ Document body (DSL)
118
115
parse() → Document
119
116
│
120
117
▼
121
collect_parameter_names() → UI dialog
118
collect_parameter_names() → UI dialog / CLI --set
122
119
│
123
120
▼
124
121
substitute_document()
@@ -127,41 +124,31 @@ Document body (DSL)
127
124
EscPosEncoder (in-tree)
128
125
│
129
126
▼
130
SerialTransport::write_all
127
open_printer → write_all
131
128
```
132
129
133
### Error handling (current)
130
### Error handling
134
131
135
132
| Condition | Behaviour |
136
133
|-----------|-----------|
137
134
| Parse error | Block print; show in toolbar |
138
| Port open failure | `PrintError::Open` message in dialog |
139
| Write failure | `PrintError::Write` message in dialog |
140
| EAN13/EAN8 invalid length | `EscPosError::Barcode` before write |
141
| Linux permission denied | User must join `dialout` group (documented in Help) |
135
| Open failure | Message in dialog / CLI |
136
| Write failure | Message in dialog / CLI |
137
| Invalid barcode data | Error before write |
138
| Linux serial permission | Join `dialout` group |
142
139
143
140
Status polling (paper out, cover open) is **not** implemented.
144
141
145
142
---
146
143
147
## Images
144
## Images and rasters
148
145
149
1. Resolve path relative to `.pos` file directory (or absolute path).
150
2. Decode with `image` crate.
151
3. Convert to luma8, resize to target width (%, dots, or full printable width), and never exceed the effective page width.
152
4. Threshold to 1-bit raster.
153
5. Emit `GS v 0` raster (`1D 76 30 00`, width/height LE, bitmap) — same format as print-bridge.
146
1. Resolve path relative to the `.pos` file (or absolute).
147
2. Decode with `image`, convert to luma, scale to printable width (`chars_per_line × 12` dots).
148
3. Threshold to 1-bit; emit `GS v 0` (`1D 76 30 00` + width/height LE + bitmap).
149
4. Append **LF** after the raster so following content (including blank-line feeds) advances correctly.
154
150
155
Preview shows `[image: path]` only — no bitmap preview yet.
156
157
---
158
159
## Preview vs print width
160
161
| `preview_mode` | Preview | Print |
162
|----------------|---------|-------|
163
| `autoscale` | Scales to panel width | Full effective print width |
164
| `fixed` | Scaled by dot ratio | Full effective print width |
151
Preview draws the same bitmaps on the canvas (scaled for screen).
165
152
166
153
---
167
154
@@ -171,20 +158,7 @@ Preview shows `[image: path]` only — no bitmap preview yet.
171
158
|--------|----------|
172
159
| `MockTransport` | `print/mod.rs` tests |
173
160
| ESC/POS byte checks | `escpos.rs` tests |
174
| `cargo test` | 20 tests; no printer required |
175
176
---
177
178
## Planned (not implemented)
179
180
| Feature | Notes |
181
|---------|-------|
182
| USB printer class | `nusb` / Windows `usbprint` |
183
| Bluetooth SPP | Serial port after OS pairing |
184
| Baud autodetect | Try 9600, 19200, 115200 |
185
| Printer status read | DLE EOT |
186
| Network TCP 9100 | Future |
187
| Image size warning in UI | Future |
161
| `cargo test` | ~100 unit tests; no printer required |
188
162
189
163
---
190
164
@@ -192,7 +166,18 @@ Preview shows `[image: path]` only — no bitmap preview yet.
192
166
193
167
```toml
194
168
serialport = "4"
169
rusb = "0.9"
195
170
image = { features = ["png", "jpeg", "gif", "bmp"] }
196
171
```
197
172
198
No `escpos`, `nusb`, or `rusb` crates.
173
On Windows, spooler access uses Win32 APIs (`winreg` / system libs as needed). No `escpos` or `nusb` crates.
174
175
---
176
177
## Planned (not implemented)
178
179
| Feature | Notes |
180
|---------|-------|
181
| Bluetooth SPP | After OS pairing |
182
| Network TCP 9100 | Future |
183
| Printer status read | DLE EOT |
@@ -1,17 +1,15 @@1
# Printing subsystem1
# Printing subsystem2
2
3
Direct raw-byte printing to POS thermal printers over **USB-serial** — without the Windows print spooler or CUPS.3
Raw ESC/POS output to POS thermal printers via **USB printer-class**, **Windows spooler** (Windows), or **USB-serial**.4
5
> **Implementation status (v0.1.0):** USB-serial only. In-tree ESC/POS encoder in `src/escpos.rs`. USB printer class and Bluetooth are **not** implemented.6
4
7
---5
---8
6
9
## Goals7
## Goals10
8
11
1. Discover serial ports (USB-serial adapters and CDC printers)9
1. Discover printers (USB-direct, Windows spooler, serial ports)12
2. Let the user pick a port in the print dialog10
2. Let the user pick a target in the print dialog13
3. Generate ESC/POS bytes from the AST (after parameter substitution)11
3. Generate ESC/POS bytes from the AST (after parameter substitution)14
4. Write bytes at **9600 baud** (fixed for now)12
4. Write bytes to the chosen transport (serial baud is probed)15
13
16
---14
---17
15
@@ -28,12 +26,13 @@ Target **Epson ESC/POS** compatible printers (58 mm / 80 mm thermal).28
| Bold | ESC E | Headings level 2 only |26
| Bold | ESC E | Headings level 2 only |29
| Double size | GS ! | Heading level 1 |27
| Double size | GS ! | Heading level 1 |30
| Alignment | ESC a | Paragraphs, images, barcodes, QR |28
| Alignment | ESC a | Paragraphs, images, barcodes, QR |31
| Line feed | LF (text lines), ESC d (`@feed` / blank lines) | Text lines end with LF; explicit feeds use ESC d |29
| Line feed | LF (text lines), ESC d (`@feed` / blank lines) | Text ends with LF; blank/`@feed` use ESC d |30
| Raster flush | LF after GS v 0 | Ensures spacing after images/barcodes/QR rasters |32
| List bullet | ASCII `*` | `- item` lines in templates |31
| List bullet | ASCII `*` | `- item` lines in templates |33
| Partial cut | GS V 66 0 | `@cut` in template |32
| Partial cut | GS V 66 0 | `@cut` in template only |34
| Barcode | GS k | CODE128, EAN13, EAN8, CODE39 |33
| Barcode | GS k | Native symbologies; raster via GS v 0 |35
| QR Code | GS ( k | Model 2 |34
| QR Code | GS ( k | Model 2; or raster GS v 0 |36
| Raster image | GS v 0 | `@image` via `image` crate → threshold |35
| Raster image | GS v 0 | `@image` / raster barcode / raster QR |37
36
38
Encoder: `EscPosEncoder` in `src/escpos.rs` — **not** the `escpos` crates.io package.37
Encoder: `EscPosEncoder` in `src/escpos.rs` — **not** the `escpos` crates.io package.39
38
@@ -51,7 +50,7 @@ substitute_document()51
EscPosEncoder::encode_document()50
EscPosEncoder::encode_document()52
│51
│53
▼52
▼54
SerialTransport::open(port, 9600)53
open_printer(target) # USB-direct | Win spooler | serial55
│54
│56
▼55
▼57
print_bytes() → write_all + flush56
print_bytes() → write_all + flush@@ -68,44 +67,42 @@ pub trait PrinterTransport {68
67
69
| Type | Role |68
| Type | Role |70
|------|------|69
|------|------|71
| `SerialTransport` | Production — opens port via `serialport` |70
| USB-direct (`rusb`) | USB printer-class bulk OUT (`usb_direct.rs`) |71
| Windows spooler | Raw jobs via Win32 spooler (`win_spool.rs`, Windows only) |72
| `SerialTransport` | USB-serial / CDC ports via `serialport` |72
| `MockTransport` | Tests — records bytes in `written` vec |73
| `MockTransport` | Tests — records bytes in `written` vec |73
74
74
### Discovery75
### Discovery75
76
76
`list_usb_serial_printers()` calls `serialport::available_ports()` and labels USB ports with VID/PID when available. All serial ports are listed (no POS-specific filter).77
`list_printers()` returns, in order:78
79
1. USB printer-class devices (`usb_direct`)80
2. Windows spooler queues (Windows)81
3. Serial ports (`serialport::available_ports()`, with VID/PID labels when available)82
83
### Serial baud rates84
85
`SerialTransport::open` tries, in order:86
87
`115200`, `9600`, `19200`, `38400`, `57600`, `4800`77
88
78
### `PrinterDevice`89
### `PrinterDevice`79
90
80
| Field | Example |91
| Field | Example |81
|-------|---------|92
|-------|---------|82
| `id` | `serial:COM3` |93
| `id` | `serial:COM3`, `usb:04b8:0e15:…`, `spool:POS-58` |83
| `display_name` | `COM3 — USB 04b8:0e15` |94
| `display_name` | Human-readable label |84
| `port_name` | `COM3` |95
| `target` | `Serial` / `UsbDirect` / `WinSpooler` |85
96
86
---97
---87
98
88
## Print dialog (UI)99
## Print dialog (UI)89
100
90
```101
- One field per unique `${Parameter}`.91
┌─────────────────────────────────────────┐102
- Printer list: USB, spooler, and serial (Refresh button).92
│ Print │103
- Optional manual serial port name.93
├─────────────────────────────────────────┤104
- While open, the main Design UI is disabled (including editor autocomplete).94
│ Parameters (one field per unique name) │105
- Errors shown inline (parse, open, write, barcode validation).95
│ DocumentNumber: [________] │96
│ │97
│ USB printer │98
│ [ Refresh ] │99
│ ○ COM3 — USB 04b8:0e15 │100
│ ○ /dev/ttyUSB0 — Serial │101
│ │102
│ [ Cancel ] [ Print ] │103
└─────────────────────────────────────────┘104
```105
106
- Parameters pre-filled from `last_params` (session memory).107
- Same parameter name → one input, applied everywhere.108
- Errors shown inline (parse, open port, write, barcode validation).109
106
110
---107
---111
108
@@ -118,7 +115,7 @@ Document body (DSL)118
parse() → Document115
parse() → Document119
│116
│120
▼117
▼121
collect_parameter_names() → UI dialog118
collect_parameter_names() → UI dialog / CLI --set122
│119
│123
▼120
▼124
substitute_document()121
substitute_document()@@ -127,41 +124,31 @@ Document body (DSL)127
EscPosEncoder (in-tree)124
EscPosEncoder (in-tree)128
│125
│129
▼126
▼130
SerialTransport::write_all127
open_printer → write_all131
```128
```132
129
133
### Error handling (current)130
### Error handling134
131
135
| Condition | Behaviour |132
| Condition | Behaviour |136
|-----------|-----------|133
|-----------|-----------|137
| Parse error | Block print; show in toolbar |134
| Parse error | Block print; show in toolbar |138
| Port open failure | `PrintError::Open` message in dialog |135
| Open failure | Message in dialog / CLI |139
| Write failure | `PrintError::Write` message in dialog |136
| Write failure | Message in dialog / CLI |140
| EAN13/EAN8 invalid length | `EscPosError::Barcode` before write |137
| Invalid barcode data | Error before write |141
| Linux permission denied | User must join `dialout` group (documented in Help) |138
| Linux serial permission | Join `dialout` group |142
139
143
Status polling (paper out, cover open) is **not** implemented.140
Status polling (paper out, cover open) is **not** implemented.144
141
145
---142
---146
143
147
## Images144
## Images and rasters148
145
149
1. Resolve path relative to `.pos` file directory (or absolute path).146
1. Resolve path relative to the `.pos` file (or absolute).150
2. Decode with `image` crate.147
2. Decode with `image`, convert to luma, scale to printable width (`chars_per_line × 12` dots).151
3. Convert to luma8, resize to target width (%, dots, or full printable width), and never exceed the effective page width.148
3. Threshold to 1-bit; emit `GS v 0` (`1D 76 30 00` + width/height LE + bitmap).152
4. Threshold to 1-bit raster.149
4. Append **LF** after the raster so following content (including blank-line feeds) advances correctly.153
5. Emit `GS v 0` raster (`1D 76 30 00`, width/height LE, bitmap) — same format as print-bridge.154
150
155
Preview shows `[image: path]` only — no bitmap preview yet.151
Preview draws the same bitmaps on the canvas (scaled for screen).156
157
---158
159
## Preview vs print width160
161
| `preview_mode` | Preview | Print |162
|----------------|---------|-------|163
| `autoscale` | Scales to panel width | Full effective print width |164
| `fixed` | Scaled by dot ratio | Full effective print width |165
152
166
---153
---167
154
@@ -171,20 +158,7 @@ Preview shows `[image: path]` only — no bitmap preview yet.171
|--------|----------|158
|--------|----------|172
| `MockTransport` | `print/mod.rs` tests |159
| `MockTransport` | `print/mod.rs` tests |173
| ESC/POS byte checks | `escpos.rs` tests |160
| ESC/POS byte checks | `escpos.rs` tests |174
| `cargo test` | 20 tests; no printer required |161
| `cargo test` | ~100 unit tests; no printer required |175
176
---177
178
## Planned (not implemented)179
180
| Feature | Notes |181
|---------|-------|182
| USB printer class | `nusb` / Windows `usbprint` |183
| Bluetooth SPP | Serial port after OS pairing |184
| Baud autodetect | Try 9600, 19200, 115200 |185
| Printer status read | DLE EOT |186
| Network TCP 9100 | Future |187
| Image size warning in UI | Future |188
162
189
---163
---190
164
@@ -192,7 +166,18 @@ Preview shows `[image: path]` only — no bitmap preview yet.192
166
193
```toml167
```toml194
serialport = "4"168
serialport = "4"169
rusb = "0.9"195
image = { features = ["png", "jpeg", "gif", "bmp"] }170
image = { features = ["png", "jpeg", "gif", "bmp"] }196
```171
```197
172
198
No `escpos`, `nusb`, or `rusb` crates.173
On Windows, spooler access uses Win32 APIs (`winreg` / system libs as needed). No `escpos` or `nusb` crates.174
175
---176
177
## Planned (not implemented)178
179
| Feature | Notes |180
|---------|-------|181
| Bluetooth SPP | After OS pairing |182
| Network TCP 9100 | Future |183
| Printer status read | DLE EOT |