BlueGit

timfa posprint

Normalize remaining docs and desktop files to LF.

Finish the line-ending cleanup so markdown and packaging assets match .gitattributes.

Co-authored-by: Cursor <cursoragent@cursor.com>

timfa Tim Falken · pushed by timfa

Authored 2026-07-16 · 4 months ago

Hash
e9cd4249e092c4b22f57219ec3811f8e57dd472d
Parent
12fa4878
10 files changed +1369 −1369
docs/ARCHITECTURE.md +180 −180
@@ -1,180 +1,180 @@
1 # System architecture
2
3 ## Overview
4
5 posprint is a **single Rust binary** using **egui** (eframe). No separate frontend language, no WebView, no IPC layer.
6
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 └─────────────────────────────────────────┘
16 ```
17
18 ### Source layout
19
20 ```
21 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
31 ```
32
33 ### External dependencies (minimal)
34
35 | Crate | Role |
36 |-------|------|
37 | `eframe` / `egui` | Native UI |
38 | `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 |
42
43 ESC/POS command generation is **not** delegated to a third-party crate.
44
45 ---
46
47 ## UI structure
48
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 |
57
58 Bottom panel switches tabs. Top panel holds actions and settings.
59
60 ---
61
62 ## Data flow
63
64 ### Edit loop (live preview)
65
66 1. User types in the Editor tab.
67 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).
72
73 ### Save / load
74
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.
77
78 Image paths in `@image` resolve relative to the `.pos` file directory on print.
79
80 ### Print
81
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`.
86
87 If `metadata.cut_after_print` is true and the template has no `@cut`, a cut command is appended automatically. Add blank lines or `@feed` in the template to control spacing before the cut.
88
89 ---
90
91 ## Key types
92
93 Implemented in `dsl/mod.rs`, `io/mod.rs`, `print/mod.rs`:
94
95 ```rust
96 // dsl/
97 struct Document { blocks: Vec<Block> }
98
99 enum Block {
100 Paragraph { align, inlines },
101 Heading { level, inlines },
102 Rule,
103 Feed(u8),
104 Cut,
105 Image { path, width: ImageWidth, align },
106 Barcode { symbology, data, height, align, show_text },
107 Qr { data, size, ecc, align },
108 }
109
110 // io/
111 struct PosFile { version, metadata: PosMetadata, body }
112 struct PosMetadata { title, page_width_mm, preview_mode, chars_per_line, codepage, cut_after_print }
113
114 // print/
115 struct PrinterDevice { id, display_name, port_name }
116 trait PrinterTransport { write_all, flush }
117 ```
118
119 ---
120
121 ## Preview vs print fidelity
122
123 | Aspect | Preview | Print |
124 |--------|---------|-------|
125 | Text font | egui monospace/proportional | Printer built-in font |
126 | Line width | From `chars_per_line()` | ESC/POS dot width from `page_width_mm` |
127 | Images | `[image: path]` placeholder | Monochrome raster (GS v 0) |
128 | Barcodes / QR | Text placeholder | Native ESC/POS commands |
129 | Alignment | Canvas positioning | ESC a |
130
131 Both paths share the same **AST**; substitution happens only at print time. Preview shows unresolved `${Param}` tokens as-is.
132
133 ---
134
135 ## State persistence (current)
136
137 | Data | Storage | Notes |
138 |------|---------|-------|
139 | Template + metadata | `.pos` file on disk | User saves explicitly |
140 | Last parameter values | `PosPrintApp.last_params` | In-memory only; lost on quit |
141 | Recent files | — | Not implemented |
142 | Selected printer | — | Not persisted between sessions |
143
144 ---
145
146 ## Testing
147
148 | Layer | Location | Approach |
149 |-------|----------|----------|
150 | DSL parser | `dsl/parser.rs` | Unit tests |
151 | Parameters | `params.rs` | Unit tests |
152 | ESC/POS encoder | `escpos.rs` | Byte structure tests |
153 | Preview | `preview.rs` | Unit tests |
154 | `.pos` I/O | `io/mod.rs` | Round-trip + tempfile tests |
155 | Printer I/O | `print/mod.rs` | `MockTransport`; no hardware in CI |
156 | App | `app.rs` | Default template parse/param tests |
157
158 Run: `cargo test` (20 tests). CI runs this on Linux (Docker) and Windows (shell runner).
159
160 ---
161
162 ## Build and release
163
164 - **CI:** GitLab (`.gitlab-ci.yml`) — `cargo test` on push; release artifacts on tags.
165 - **Linux artifact:** `.deb` via `cargo-deb` (`[package.metadata.deb]` in `Cargo.toml`).
166 - **Windows artifact:** `target/release/posprint.exe`.
167 - **Versioning:** Semver in `Cargo.toml`; `.pos` `version` field for file-format migrations.
168
169 ---
170
171 ## Planned (not implemented)
172
173 - USB printer class (bulk OUT) without serial emulation
174 - Bluetooth SPP
175 - Network printers (TCP 9100)
176 - Baud-rate autodetect / settings UI
177 - Persisted last parameters and recent files
178 - Syntax highlighting in editor
179
180 See [PRINTING.md](PRINTING.md) and [DSL-SPEC.md](DSL-SPEC.md) for protocol and language details.
1 # System architecture
2
3 ## Overview
4
5 posprint is a **single Rust binary** using **egui** (eframe). No separate frontend language, no WebView, no IPC layer.
6
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 └─────────────────────────────────────────┘
16 ```
17
18 ### Source layout
19
20 ```
21 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
31 ```
32
33 ### External dependencies (minimal)
34
35 | Crate | Role |
36 |-------|------|
37 | `eframe` / `egui` | Native UI |
38 | `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 |
42
43 ESC/POS command generation is **not** delegated to a third-party crate.
44
45 ---
46
47 ## UI structure
48
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 |
57
58 Bottom panel switches tabs. Top panel holds actions and settings.
59
60 ---
61
62 ## Data flow
63
64 ### Edit loop (live preview)
65
66 1. User types in the Editor tab.
67 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).
72
73 ### Save / load
74
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.
77
78 Image paths in `@image` resolve relative to the `.pos` file directory on print.
79
80 ### Print
81
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`.
86
87 If `metadata.cut_after_print` is true and the template has no `@cut`, a cut command is appended automatically. Add blank lines or `@feed` in the template to control spacing before the cut.
88
89 ---
90
91 ## Key types
92
93 Implemented in `dsl/mod.rs`, `io/mod.rs`, `print/mod.rs`:
94
95 ```rust
96 // dsl/
97 struct Document { blocks: Vec<Block> }
98
99 enum Block {
100 Paragraph { align, inlines },
101 Heading { level, inlines },
102 Rule,
103 Feed(u8),
104 Cut,
105 Image { path, width: ImageWidth, align },
106 Barcode { symbology, data, height, align, show_text },
107 Qr { data, size, ecc, align },
108 }
109
110 // io/
111 struct PosFile { version, metadata: PosMetadata, body }
112 struct PosMetadata { title, page_width_mm, preview_mode, chars_per_line, codepage, cut_after_print }
113
114 // print/
115 struct PrinterDevice { id, display_name, port_name }
116 trait PrinterTransport { write_all, flush }
117 ```
118
119 ---
120
121 ## Preview vs print fidelity
122
123 | Aspect | Preview | Print |
124 |--------|---------|-------|
125 | Text font | egui monospace/proportional | Printer built-in font |
126 | Line width | From `chars_per_line()` | ESC/POS dot width from `page_width_mm` |
127 | Images | `[image: path]` placeholder | Monochrome raster (GS v 0) |
128 | Barcodes / QR | Text placeholder | Native ESC/POS commands |
129 | Alignment | Canvas positioning | ESC a |
130
131 Both paths share the same **AST**; substitution happens only at print time. Preview shows unresolved `${Param}` tokens as-is.
132
133 ---
134
135 ## State persistence (current)
136
137 | Data | Storage | Notes |
138 |------|---------|-------|
139 | Template + metadata | `.pos` file on disk | User saves explicitly |
140 | Last parameter values | `PosPrintApp.last_params` | In-memory only; lost on quit |
141 | Recent files | — | Not implemented |
142 | Selected printer | — | Not persisted between sessions |
143
144 ---
145
146 ## Testing
147
148 | Layer | Location | Approach |
149 |-------|----------|----------|
150 | DSL parser | `dsl/parser.rs` | Unit tests |
151 | Parameters | `params.rs` | Unit tests |
152 | ESC/POS encoder | `escpos.rs` | Byte structure tests |
153 | Preview | `preview.rs` | Unit tests |
154 | `.pos` I/O | `io/mod.rs` | Round-trip + tempfile tests |
155 | Printer I/O | `print/mod.rs` | `MockTransport`; no hardware in CI |
156 | App | `app.rs` | Default template parse/param tests |
157
158 Run: `cargo test` (20 tests). CI runs this on Linux (Docker) and Windows (shell runner).
159
160 ---
161
162 ## Build and release
163
164 - **CI:** GitLab (`.gitlab-ci.yml`) — `cargo test` on push; release artifacts on tags.
165 - **Linux artifact:** `.deb` via `cargo-deb` (`[package.metadata.deb]` in `Cargo.toml`).
166 - **Windows artifact:** `target/release/posprint.exe`.
167 - **Versioning:** Semver in `Cargo.toml`; `.pos` `version` field for file-format migrations.
168
169 ---
170
171 ## Planned (not implemented)
172
173 - USB printer class (bulk OUT) without serial emulation
174 - Bluetooth SPP
175 - Network printers (TCP 9100)
176 - Baud-rate autodetect / settings UI
177 - Persisted last parameters and recent files
178 - Syntax highlighting in editor
179
180 See [PRINTING.md](PRINTING.md) and [DSL-SPEC.md](DSL-SPEC.md) for protocol and language details.
@@ -1,180 +1,180 @@
1# System architecture
1# System architecture
2
2
3## Overview
3## Overview
4
4
5posprint is a **single Rust binary** using **egui** (eframe). No separate frontend language, no WebView, no IPC layer.
5posprint 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│ - Editor / Preview / Help tabs │
11│ - DSL parse → AST │
11│ - DSL parse → AST │
12│ - Preview layout + in-tree ESC/POS │
12│ - Preview layout + in-tree ESC/POS │
13│ - USB-serial printer discovery/print │
13│ - USB-serial printer discovery/print │
14│ - `.pos` JSON load/save (serde) │
14│ - `.pos` JSON load/save (serde) │
15└─────────────────────────────────────────┘
15└─────────────────────────────────────────┘
16```
16```
17
17
18### Source layout
18### Source layout
19
19
20```
20```
21src/
21src/
22├── main.rs # eframe entry point
22├── main.rs # eframe entry point
23├── app.rs # egui UI (editor, preview, help, print dialog)
23├── app.rs # egui UI (editor, preview, help, print dialog)
24├── lib.rs # crate root; exports + HELP_MARKDOWN
24├── lib.rs # crate root; exports + HELP_MARKDOWN
25├── dsl/ # Parser and AST (mod.rs, parser.rs)
25├── dsl/ # Parser and AST (mod.rs, parser.rs)
26├── params.rs # Parameter collect/substitute
26├── params.rs # Parameter collect/substitute
27├── escpos.rs # ESC/POS byte encoder (in-tree)
27├── escpos.rs # ESC/POS byte encoder (in-tree)
28├── preview.rs # Preview model for UI canvas
28├── preview.rs # Preview model for UI canvas
29├── io/mod.rs # .pos file format (PosFile, PosMetadata)
29├── io/mod.rs # .pos file format (PosFile, PosMetadata)
30└── print/mod.rs # USB-serial discovery, SerialTransport, MockTransport
30└── print/mod.rs # USB-serial discovery, SerialTransport, MockTransport
31```
31```
32
32
33### External dependencies (minimal)
33### External dependencies (minimal)
34
34
35| Crate | Role |
35| Crate | Role |
36|-------|------|
36|-------|------|
37| `eframe` / `egui` | Native UI |
37| `eframe` / `egui` | Native UI |
38| `serde` / `serde_json` | `.pos` file format |
38| `serde` / `serde_json` | `.pos` file format |
39| `serialport` | USB-serial enumeration and I/O |
39| `serialport` | USB-serial enumeration and I/O |
40| `image` | Decode/resize images for `@image` raster print |
40| `image` | Decode/resize images for `@image` raster print |
41| `rfd` | Native open/save file dialogs |
41| `rfd` | Native open/save file dialogs |
42
42
43ESC/POS command generation is **not** delegated to a third-party crate.
43ESC/POS command generation is **not** delegated to a third-party crate.
44
44
45---
45---
46
46
47## UI structure
47## UI structure
48
48
49| Tab / area | Module | Description |
49| Tab / area | Module | Description |
50|------------|--------|-------------|
50|------------|--------|-------------|
51| **Editor** | `app.rs` | Multiline `TextEdit` (monospace) for template source |
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 |
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!` |
53| **Help** | `app.rs` | Scrollable view of `docs/HELP.md` via `include_str!` |
54| Toolbar | `app.rs` | New, Open, Save, Save As, Print |
54| Toolbar | `app.rs` | New, Open, Save, Save As, Print |
55| Settings | `app.rs` | Page width (mm), preview mode |
55| Settings | `app.rs` | Page width (mm), preview mode |
56| Print dialog | `app.rs` | Parameter fields + USB-serial printer picker |
56| Print dialog | `app.rs` | Parameter fields + USB-serial printer picker |
57
57
58Bottom panel switches tabs. Top panel holds actions and settings.
58Bottom panel switches tabs. Top panel holds actions and settings.
59
59
60---
60---
61
61
62## Data flow
62## Data flow
63
63
64### Edit loop (live preview)
64### Edit loop (live preview)
65
65
661. User types in the Editor tab.
661. User types in the Editor tab.
672. Each frame, `parse(&body)` runs; errors show in the toolbar.
672. Each frame, `parse(&body)` runs; errors show in the toolbar.
683. On Preview tab, `render_preview(&doc, &metadata)` builds a `PreviewModel`.
683. On Preview tab, `render_preview(&doc, &metadata)` builds a `PreviewModel`.
694. Canvas draws text lines, rules, and placeholders for barcode/QR/image.
694. Canvas draws text lines, rules, and placeholders for barcode/QR/image.
70
70
71Preview is **not debounced** — it re-parses when the Preview tab is shown (and parse runs every frame for error display).
71Preview is **not debounced** — it re-parses when the Preview tab is shown (and parse runs every frame for error display).
72
72
73### Save / load
73### Save / load
74
74
751. **Open:** `rfd` file dialog → `PosFile::load_from_path` → populate `body`, `metadata`, `file_path`.
751. **Open:** `rfd` file dialog → `PosFile::load_from_path` → populate `body`, `metadata`, `file_path`.
762. **Save / Save As:** `PosFile::save_to_path` writes pretty-printed JSON.
762. **Save / Save As:** `PosFile::save_to_path` writes pretty-printed JSON.
77
77
78Image paths in `@image` resolve relative to the `.pos` file directory on print.
78Image paths in `@image` resolve relative to the `.pos` file directory on print.
79
79
80### Print
80### Print
81
81
821. User clicks **Print** → parse body → `collect_parameter_names(&doc)`.
821. User clicks **Print** → parse body → `collect_parameter_names(&doc)`.
832. Modal shows one field per unique parameter; pre-filled from `last_params` (in-memory).
832. Modal shows one field per unique parameter; pre-filled from `last_params` (in-memory).
843. User selects a USB-serial port from `list_usb_serial_printers()`.
843. User selects a USB-serial port from `list_usb_serial_printers()`.
854. `substitute_document` → `EscPosEncoder::encode_document` → `SerialTransport::open` (9600 baud) → `print_bytes`.
854. `substitute_document` → `EscPosEncoder::encode_document` → `SerialTransport::open` (9600 baud) → `print_bytes`.
86
86
87If `metadata.cut_after_print` is true and the template has no `@cut`, a cut command is appended automatically. Add blank lines or `@feed` in the template to control spacing before the cut.
87If `metadata.cut_after_print` is true and the template has no `@cut`, a cut command is appended automatically. Add blank lines or `@feed` in the template to control spacing before the cut.
88
88
89---
89---
90
90
91## Key types
91## Key types
92
92
93Implemented in `dsl/mod.rs`, `io/mod.rs`, `print/mod.rs`:
93Implemented in `dsl/mod.rs`, `io/mod.rs`, `print/mod.rs`:
94
94
95```rust
95```rust
96// dsl/
96// dsl/
97struct Document { blocks: Vec<Block> }
97struct Document { blocks: Vec<Block> }
98
98
99enum Block {
99enum Block {
100 Paragraph { align, inlines },
100 Paragraph { align, inlines },
101 Heading { level, inlines },
101 Heading { level, inlines },
102 Rule,
102 Rule,
103 Feed(u8),
103 Feed(u8),
104 Cut,
104 Cut,
105 Image { path, width: ImageWidth, align },
105 Image { path, width: ImageWidth, align },
106 Barcode { symbology, data, height, align, show_text },
106 Barcode { symbology, data, height, align, show_text },
107 Qr { data, size, ecc, align },
107 Qr { data, size, ecc, align },
108}
108}
109
109
110// io/
110// io/
111struct PosFile { version, metadata: PosMetadata, body }
111struct PosFile { version, metadata: PosMetadata, body }
112struct PosMetadata { title, page_width_mm, preview_mode, chars_per_line, codepage, cut_after_print }
112struct PosMetadata { title, page_width_mm, preview_mode, chars_per_line, codepage, cut_after_print }
113
113
114// print/
114// print/
115struct PrinterDevice { id, display_name, port_name }
115struct PrinterDevice { id, display_name, port_name }
116trait PrinterTransport { write_all, flush }
116trait PrinterTransport { write_all, flush }
117```
117```
118
118
119---
119---
120
120
121## Preview vs print fidelity
121## Preview vs print fidelity
122
122
123| Aspect | Preview | Print |
123| Aspect | Preview | Print |
124|--------|---------|-------|
124|--------|---------|-------|
125| Text font | egui monospace/proportional | Printer built-in font |
125| Text font | egui monospace/proportional | Printer built-in font |
126| Line width | From `chars_per_line()` | ESC/POS dot width from `page_width_mm` |
126| Line width | From `chars_per_line()` | ESC/POS dot width from `page_width_mm` |
127| Images | `[image: path]` placeholder | Monochrome raster (GS v 0) |
127| Images | `[image: path]` placeholder | Monochrome raster (GS v 0) |
128| Barcodes / QR | Text placeholder | Native ESC/POS commands |
128| Barcodes / QR | Text placeholder | Native ESC/POS commands |
129| Alignment | Canvas positioning | ESC a |
129| Alignment | Canvas positioning | ESC a |
130
130
131Both paths share the same **AST**; substitution happens only at print time. Preview shows unresolved `${Param}` tokens as-is.
131Both paths share the same **AST**; substitution happens only at print time. Preview shows unresolved `${Param}` tokens as-is.
132
132
133---
133---
134
134
135## State persistence (current)
135## State persistence (current)
136
136
137| Data | Storage | Notes |
137| Data | Storage | Notes |
138|------|---------|-------|
138|------|---------|-------|
139| Template + metadata | `.pos` file on disk | User saves explicitly |
139| Template + metadata | `.pos` file on disk | User saves explicitly |
140| Last parameter values | `PosPrintApp.last_params` | In-memory only; lost on quit |
140| Last parameter values | `PosPrintApp.last_params` | In-memory only; lost on quit |
141| Recent files | — | Not implemented |
141| Recent files | — | Not implemented |
142| Selected printer | — | Not persisted between sessions |
142| Selected printer | — | Not persisted between sessions |
143
143
144---
144---
145
145
146## Testing
146## Testing
147
147
148| Layer | Location | Approach |
148| Layer | Location | Approach |
149|-------|----------|----------|
149|-------|----------|----------|
150| DSL parser | `dsl/parser.rs` | Unit tests |
150| DSL parser | `dsl/parser.rs` | Unit tests |
151| Parameters | `params.rs` | Unit tests |
151| Parameters | `params.rs` | Unit tests |
152| ESC/POS encoder | `escpos.rs` | Byte structure tests |
152| ESC/POS encoder | `escpos.rs` | Byte structure tests |
153| Preview | `preview.rs` | Unit tests |
153| Preview | `preview.rs` | Unit tests |
154| `.pos` I/O | `io/mod.rs` | Round-trip + tempfile tests |
154| `.pos` I/O | `io/mod.rs` | Round-trip + tempfile tests |
155| Printer I/O | `print/mod.rs` | `MockTransport`; no hardware in CI |
155| Printer I/O | `print/mod.rs` | `MockTransport`; no hardware in CI |
156| App | `app.rs` | Default template parse/param tests |
156| App | `app.rs` | Default template parse/param tests |
157
157
158Run: `cargo test` (20 tests). CI runs this on Linux (Docker) and Windows (shell runner).
158Run: `cargo test` (20 tests). CI runs this on Linux (Docker) and Windows (shell runner).
159
159
160---
160---
161
161
162## Build and release
162## Build and release
163
163
164- **CI:** GitLab (`.gitlab-ci.yml`) — `cargo test` on push; release artifacts on tags.
164- **CI:** GitLab (`.gitlab-ci.yml`) — `cargo test` on push; release artifacts on tags.
165- **Linux artifact:** `.deb` via `cargo-deb` (`[package.metadata.deb]` in `Cargo.toml`).
165- **Linux artifact:** `.deb` via `cargo-deb` (`[package.metadata.deb]` in `Cargo.toml`).
166- **Windows artifact:** `target/release/posprint.exe`.
166- **Windows artifact:** `target/release/posprint.exe`.
167- **Versioning:** Semver in `Cargo.toml`; `.pos` `version` field for file-format migrations.
167- **Versioning:** Semver in `Cargo.toml`; `.pos` `version` field for file-format migrations.
168
168
169---
169---
170
170
171## Planned (not implemented)
171## Planned (not implemented)
172
172
173- USB printer class (bulk OUT) without serial emulation
173- USB printer class (bulk OUT) without serial emulation
174- Bluetooth SPP
174- Bluetooth SPP
175- Network printers (TCP 9100)
175- Network printers (TCP 9100)
176- Baud-rate autodetect / settings UI
176- Baud-rate autodetect / settings UI
177- Persisted last parameters and recent files
177- Persisted last parameters and recent files
178- Syntax highlighting in editor
178- Syntax highlighting in editor
179
179
180See [PRINTING.md](PRINTING.md) and [DSL-SPEC.md](DSL-SPEC.md) for protocol and language details.
180See [PRINTING.md](PRINTING.md) and [DSL-SPEC.md](DSL-SPEC.md) for protocol and language details.
docs/DSL-SPEC.md +269 −269
@@ -1,269 +1,269 @@
1 # Document DSL specification
2
3 A lightweight, markdown-inspired syntax for POS receipt templates. The DSL compiles to an AST and then to ESC/POS bytes or a screen preview.
4
5 > **Implementation:** Parser in `src/dsl/parser.rs`. All constructs below are implemented unless listed under [Future extensions](#future-extensions-not-implemented).
6
7 **Design goals:** easy to author, line-oriented, explicit about POS-specific features (barcodes, cut, feed), parameter-friendly.
8
9 ---
10
11 ## Document structure
12
13 A document is a sequence of **blocks** separated by blank lines. Blocks cannot be nested except for inline markup within text blocks.
14
15 ---
16
17 ## Text blocks
18
19 ### Paragraphs
20
21 Plain text with optional inline markup. One or more consecutive non-empty lines form a paragraph.
22
23 ```markdown
24 Thank you for your purchase!
25 Visit us again soon.
26 ```
27
28 ### Headings
29
30 ```markdown
31 # Store Name
32 ## Receipt
33 ```
34
35 - `#` → large / double-height text (ESC/POS emphasis)
36 - `##` → bold emphasis
37 - Maximum two levels in v1
38
39 ### Alignment
40
41 Prefix a paragraph with alignment markers:
42
43 ```markdown
44 :center:
45 Your Store Name
46
47 :right:
48 Total: ${Amount}
49 ```
50
51 | Marker | Effect |
52 |--------|--------|
53 | `:left:` | Left (default) |
54 | `:center:` | Centered |
55 | `:right:` | Right-aligned |
56
57 ### Inline markup
58
59 | Syntax | Effect |
60 |--------|--------|
61 | `**text**` | Bold |
62 | `*text*` | Italic / emphasized (printer secondary font if available) |
63 | `` `text` `` | Monospace / condensed |
64 | `${Name}` | Parameter placeholder (see Parameters) |
65
66 Parameters work inside any text, and inside barcode/QR/image directives (below).
67
68 **Example:**
69
70 ```markdown
71 Receipt #${DocumentNumber}
72 Date: ${Date}
73
74 Item: ${ItemName} **${LineTotal}**
75 ```
76
77 ### Horizontal rule
78
79 ```markdown
80 ---
81 ```
82
83 Renders a dashed or solid separator line across the print width.
84
85 ---
86
87 ## Directives (block-level)
88
89 Directives start with `@` at the beginning of a line.
90
91 ### Feed (blank lines)
92
93 ```markdown
94 @feed 3
95 ```
96
97 Advances paper by *n* lines.
98
99 ### Cut
100
101 ```markdown
102 @cut
103 ```
104
105 Partial cut after content (if printer supports). Often placed at document end.
106
107 ### Image
108
109 ```markdown
110 @image path/to/logo.png
111 @image ${LogoPath} width=50%
112 @image assets/qr-promo.png width=384
113 ```
114
115 | Attribute | Description |
116 |-----------|-------------|
117 | `path` (positional) | File path relative to `.pos` file or absolute; may be `${Param}` |
118 | `width` | `NN%` of printable width, or absolute dots (e.g. `384`) |
119 | `align` | `left` (default), `center`, `right` |
120
121 Images are converted to monochrome raster data, dithered, and scaled to width.
122
123 ### Barcode
124
125 ```markdown
126 @barcode CODE128 ${Sku}
127 @barcode EAN13 ${EanCode} height=80
128 ```
129
130 | Field | Values |
131 |-------|--------|
132 | Symbology | `CODE128`, `EAN13`, `EAN8`, `CODE39` |
133 | Data | Literal or `${Param}` |
134 | `height` | Module height in dots (default: 64) |
135 | `align` | `left`, `center`, `right` |
136 | `show_text` | `true` / `false` — HRI below barcode (default: true) |
137
138 ### QR code
139
140 ```markdown
141 @qr https://example.com/receipt/${DocumentNumber}
142 @qr ${PaymentUrl} size=6
143 ```
144
145 | Attribute | Description |
146 |-----------|-------------|
147 | Data (positional) | URL or text; may include `${Param}` |
148 | `size` | Module size 1–16 (default: 4) |
149 | `ecc` | Error correction: `L`, `M`, `Q`, `H` (default: `M`) |
150 | `align` | `left`, `center`, `right` |
151
152 ---
153
154 ## Parameters
155
156 ### Syntax
157
158 ```
159 ${ParameterName}
160 ```
161
162 - **Names:** `[A-Za-z_][A-Za-z0-9_]*` (ASCII letters, digits, underscore)
163 - **Case-sensitive:** `${DocNo}` and `${docno}` are different
164 - **Uniqueness at input:** all occurrences of the same name share one value entered at print time
165
166 ### Where parameters are allowed
167
168 | Location | Example |
169 |----------|---------|
170 | Text | `Order ${OrderId}` |
171 | Barcode data | `@barcode CODE128 ${OrderId}` |
172 | QR data | `@qr ${VerifyUrl}` |
173 | Image path | `@image ${LogoPath}` |
174
175 ### Print-time behavior
176
177 1. Before print, scan AST for all `${...}` tokens.
178 2. Deduplicate by name.
179 3. Show dialog with one field per unique name.
180 4. Pre-fill from last print session (global or per-file — implementation choice).
181 5. Substitute into AST, then render/print.
182
183 Missing parameter at print time: block print and highlight unresolved names in UI.
184
185 ---
186
187 ## Comments
188
189 ```markdown
190 <!-- This is a comment, not printed -->
191 ```
192
193 HTML-style comments are stripped at parse time.
194
195 ---
196
197 ## Example document
198
199 ```markdown
200 # ${StoreName}
201 :center:
202
203 123 Main Street
204 Tel: ${StorePhone}
205
206 ---
207 Date: ${Date} Time: ${Time}
208 Receipt: ${DocumentNumber}
209
210 Item Total
211 ${LineItems}
212
213 ---
214 :right:
215 **TOTAL: ${GrandTotal}**
216
217 @barcode CODE128 ${DocumentNumber}
218 @feed 2
219 @qr https://shop.example.com/r/${DocumentNumber}
220
221 Thank you!
222 @feed 4
223 @cut
224 ```
225
226 `${LineItems}` might be pre-formatted multi-line text passed as a single parameter (v1); structured line items are a future extension.
227
228 ---
229
230 ## Parse errors
231
232 The parser reports:
233
234 - Unknown directive
235 - Invalid barcode symbology
236 - Unclosed `**` or `` ` ``
237 - Invalid `${}` name
238 - Missing required directive argument
239
240 Errors include 1-based line and column for editor highlighting.
241
242 ---
243
244 ## ESC/POS mapping (summary)
245
246 | DSL | ESC/POS |
247 |-----|---------|
248 | `# heading` | Double width/height ON → text → OFF |
249 | `**bold**` | Bold ON/OFF |
250 | `:center:` | Justification center |
251 | `@feed n` | Print and feed n lines |
252 | `@cut` | GS V partial cut |
253 | `@barcode` | GS k / CODE128 native |
254 | `@qr` | GS ( k QR model 2 |
255 | `@image` | GS v 0 raster bit image |
256
257 Full command details live in the print encoder module; see [PRINTING.md](PRINTING.md).
258
259 ---
260
261 ## Future extensions (not implemented)
262
263 - `@table` for columnar line items
264 - `UPC-A` barcodes
265 - Conditionals: `@if ${HasDiscount} ... @endif`
266 - Loops / repeating sections
267 - `@signature` for custom ESC/POS hex escape
268 - Multiple code pages / Unicode subset
269 - Syntax highlighting in the editor
1 # Document DSL specification
2
3 A lightweight, markdown-inspired syntax for POS receipt templates. The DSL compiles to an AST and then to ESC/POS bytes or a screen preview.
4
5 > **Implementation:** Parser in `src/dsl/parser.rs`. All constructs below are implemented unless listed under [Future extensions](#future-extensions-not-implemented).
6
7 **Design goals:** easy to author, line-oriented, explicit about POS-specific features (barcodes, cut, feed), parameter-friendly.
8
9 ---
10
11 ## Document structure
12
13 A document is a sequence of **blocks** separated by blank lines. Blocks cannot be nested except for inline markup within text blocks.
14
15 ---
16
17 ## Text blocks
18
19 ### Paragraphs
20
21 Plain text with optional inline markup. One or more consecutive non-empty lines form a paragraph.
22
23 ```markdown
24 Thank you for your purchase!
25 Visit us again soon.
26 ```
27
28 ### Headings
29
30 ```markdown
31 # Store Name
32 ## Receipt
33 ```
34
35 - `#` → large / double-height text (ESC/POS emphasis)
36 - `##` → bold emphasis
37 - Maximum two levels in v1
38
39 ### Alignment
40
41 Prefix a paragraph with alignment markers:
42
43 ```markdown
44 :center:
45 Your Store Name
46
47 :right:
48 Total: ${Amount}
49 ```
50
51 | Marker | Effect |
52 |--------|--------|
53 | `:left:` | Left (default) |
54 | `:center:` | Centered |
55 | `:right:` | Right-aligned |
56
57 ### Inline markup
58
59 | Syntax | Effect |
60 |--------|--------|
61 | `**text**` | Bold |
62 | `*text*` | Italic / emphasized (printer secondary font if available) |
63 | `` `text` `` | Monospace / condensed |
64 | `${Name}` | Parameter placeholder (see Parameters) |
65
66 Parameters work inside any text, and inside barcode/QR/image directives (below).
67
68 **Example:**
69
70 ```markdown
71 Receipt #${DocumentNumber}
72 Date: ${Date}
73
74 Item: ${ItemName} **${LineTotal}**
75 ```
76
77 ### Horizontal rule
78
79 ```markdown
80 ---
81 ```
82
83 Renders a dashed or solid separator line across the print width.
84
85 ---
86
87 ## Directives (block-level)
88
89 Directives start with `@` at the beginning of a line.
90
91 ### Feed (blank lines)
92
93 ```markdown
94 @feed 3
95 ```
96
97 Advances paper by *n* lines.
98
99 ### Cut
100
101 ```markdown
102 @cut
103 ```
104
105 Partial cut after content (if printer supports). Often placed at document end.
106
107 ### Image
108
109 ```markdown
110 @image path/to/logo.png
111 @image ${LogoPath} width=50%
112 @image assets/qr-promo.png width=384
113 ```
114
115 | Attribute | Description |
116 |-----------|-------------|
117 | `path` (positional) | File path relative to `.pos` file or absolute; may be `${Param}` |
118 | `width` | `NN%` of printable width, or absolute dots (e.g. `384`) |
119 | `align` | `left` (default), `center`, `right` |
120
121 Images are converted to monochrome raster data, dithered, and scaled to width.
122
123 ### Barcode
124
125 ```markdown
126 @barcode CODE128 ${Sku}
127 @barcode EAN13 ${EanCode} height=80
128 ```
129
130 | Field | Values |
131 |-------|--------|
132 | Symbology | `CODE128`, `EAN13`, `EAN8`, `CODE39` |
133 | Data | Literal or `${Param}` |
134 | `height` | Module height in dots (default: 64) |
135 | `align` | `left`, `center`, `right` |
136 | `show_text` | `true` / `false` — HRI below barcode (default: true) |
137
138 ### QR code
139
140 ```markdown
141 @qr https://example.com/receipt/${DocumentNumber}
142 @qr ${PaymentUrl} size=6
143 ```
144
145 | Attribute | Description |
146 |-----------|-------------|
147 | Data (positional) | URL or text; may include `${Param}` |
148 | `size` | Module size 1–16 (default: 4) |
149 | `ecc` | Error correction: `L`, `M`, `Q`, `H` (default: `M`) |
150 | `align` | `left`, `center`, `right` |
151
152 ---
153
154 ## Parameters
155
156 ### Syntax
157
158 ```
159 ${ParameterName}
160 ```
161
162 - **Names:** `[A-Za-z_][A-Za-z0-9_]*` (ASCII letters, digits, underscore)
163 - **Case-sensitive:** `${DocNo}` and `${docno}` are different
164 - **Uniqueness at input:** all occurrences of the same name share one value entered at print time
165
166 ### Where parameters are allowed
167
168 | Location | Example |
169 |----------|---------|
170 | Text | `Order ${OrderId}` |
171 | Barcode data | `@barcode CODE128 ${OrderId}` |
172 | QR data | `@qr ${VerifyUrl}` |
173 | Image path | `@image ${LogoPath}` |
174
175 ### Print-time behavior
176
177 1. Before print, scan AST for all `${...}` tokens.
178 2. Deduplicate by name.
179 3. Show dialog with one field per unique name.
180 4. Pre-fill from last print session (global or per-file — implementation choice).
181 5. Substitute into AST, then render/print.
182
183 Missing parameter at print time: block print and highlight unresolved names in UI.
184
185 ---
186
187 ## Comments
188
189 ```markdown
190 <!-- This is a comment, not printed -->
191 ```
192
193 HTML-style comments are stripped at parse time.
194
195 ---
196
197 ## Example document
198
199 ```markdown
200 # ${StoreName}
201 :center:
202
203 123 Main Street
204 Tel: ${StorePhone}
205
206 ---
207 Date: ${Date} Time: ${Time}
208 Receipt: ${DocumentNumber}
209
210 Item Total
211 ${LineItems}
212
213 ---
214 :right:
215 **TOTAL: ${GrandTotal}**
216
217 @barcode CODE128 ${DocumentNumber}
218 @feed 2
219 @qr https://shop.example.com/r/${DocumentNumber}
220
221 Thank you!
222 @feed 4
223 @cut
224 ```
225
226 `${LineItems}` might be pre-formatted multi-line text passed as a single parameter (v1); structured line items are a future extension.
227
228 ---
229
230 ## Parse errors
231
232 The parser reports:
233
234 - Unknown directive
235 - Invalid barcode symbology
236 - Unclosed `**` or `` ` ``
237 - Invalid `${}` name
238 - Missing required directive argument
239
240 Errors include 1-based line and column for editor highlighting.
241
242 ---
243
244 ## ESC/POS mapping (summary)
245
246 | DSL | ESC/POS |
247 |-----|---------|
248 | `# heading` | Double width/height ON → text → OFF |
249 | `**bold**` | Bold ON/OFF |
250 | `:center:` | Justification center |
251 | `@feed n` | Print and feed n lines |
252 | `@cut` | GS V partial cut |
253 | `@barcode` | GS k / CODE128 native |
254 | `@qr` | GS ( k QR model 2 |
255 | `@image` | GS v 0 raster bit image |
256
257 Full command details live in the print encoder module; see [PRINTING.md](PRINTING.md).
258
259 ---
260
261 ## Future extensions (not implemented)
262
263 - `@table` for columnar line items
264 - `UPC-A` barcodes
265 - Conditionals: `@if ${HasDiscount} ... @endif`
266 - Loops / repeating sections
267 - `@signature` for custom ESC/POS hex escape
268 - Multiple code pages / Unicode subset
269 - Syntax highlighting in the editor
@@ -1,269 +1,269 @@
1# Document DSL specification
1# Document DSL specification
2
2
3A lightweight, markdown-inspired syntax for POS receipt templates. The DSL compiles to an AST and then to ESC/POS bytes or a screen preview.
3A lightweight, markdown-inspired syntax for POS receipt templates. The DSL compiles to an AST and then to ESC/POS bytes or a screen preview.
4
4
5> **Implementation:** Parser in `src/dsl/parser.rs`. All constructs below are implemented unless listed under [Future extensions](#future-extensions-not-implemented).
5> **Implementation:** Parser in `src/dsl/parser.rs`. All constructs below are implemented unless listed under [Future extensions](#future-extensions-not-implemented).
6
6
7**Design goals:** easy to author, line-oriented, explicit about POS-specific features (barcodes, cut, feed), parameter-friendly.
7**Design goals:** easy to author, line-oriented, explicit about POS-specific features (barcodes, cut, feed), parameter-friendly.
8
8
9---
9---
10
10
11## Document structure
11## Document structure
12
12
13A document is a sequence of **blocks** separated by blank lines. Blocks cannot be nested except for inline markup within text blocks.
13A document is a sequence of **blocks** separated by blank lines. Blocks cannot be nested except for inline markup within text blocks.
14
14
15---
15---
16
16
17## Text blocks
17## Text blocks
18
18
19### Paragraphs
19### Paragraphs
20
20
21Plain text with optional inline markup. One or more consecutive non-empty lines form a paragraph.
21Plain text with optional inline markup. One or more consecutive non-empty lines form a paragraph.
22
22
23```markdown
23```markdown
24Thank you for your purchase!
24Thank you for your purchase!
25Visit us again soon.
25Visit us again soon.
26```
26```
27
27
28### Headings
28### Headings
29
29
30```markdown
30```markdown
31# Store Name
31# Store Name
32## Receipt
32## Receipt
33```
33```
34
34
35- `#` → large / double-height text (ESC/POS emphasis)
35- `#` → large / double-height text (ESC/POS emphasis)
36- `##` → bold emphasis
36- `##` → bold emphasis
37- Maximum two levels in v1
37- Maximum two levels in v1
38
38
39### Alignment
39### Alignment
40
40
41Prefix a paragraph with alignment markers:
41Prefix a paragraph with alignment markers:
42
42
43```markdown
43```markdown
44:center:
44:center:
45Your Store Name
45Your Store Name
46
46
47:right:
47:right:
48Total: ${Amount}
48Total: ${Amount}
49```
49```
50
50
51| Marker | Effect |
51| Marker | Effect |
52|--------|--------|
52|--------|--------|
53| `:left:` | Left (default) |
53| `:left:` | Left (default) |
54| `:center:` | Centered |
54| `:center:` | Centered |
55| `:right:` | Right-aligned |
55| `:right:` | Right-aligned |
56
56
57### Inline markup
57### Inline markup
58
58
59| Syntax | Effect |
59| Syntax | Effect |
60|--------|--------|
60|--------|--------|
61| `**text**` | Bold |
61| `**text**` | Bold |
62| `*text*` | Italic / emphasized (printer secondary font if available) |
62| `*text*` | Italic / emphasized (printer secondary font if available) |
63| `` `text` `` | Monospace / condensed |
63| `` `text` `` | Monospace / condensed |
64| `${Name}` | Parameter placeholder (see Parameters) |
64| `${Name}` | Parameter placeholder (see Parameters) |
65
65
66Parameters work inside any text, and inside barcode/QR/image directives (below).
66Parameters work inside any text, and inside barcode/QR/image directives (below).
67
67
68**Example:**
68**Example:**
69
69
70```markdown
70```markdown
71Receipt #${DocumentNumber}
71Receipt #${DocumentNumber}
72Date: ${Date}
72Date: ${Date}
73
73
74Item: ${ItemName} **${LineTotal}**
74Item: ${ItemName} **${LineTotal}**
75```
75```
76
76
77### Horizontal rule
77### Horizontal rule
78
78
79```markdown
79```markdown
80---
80---
81```
81```
82
82
83Renders a dashed or solid separator line across the print width.
83Renders a dashed or solid separator line across the print width.
84
84
85---
85---
86
86
87## Directives (block-level)
87## Directives (block-level)
88
88
89Directives start with `@` at the beginning of a line.
89Directives start with `@` at the beginning of a line.
90
90
91### Feed (blank lines)
91### Feed (blank lines)
92
92
93```markdown
93```markdown
94@feed 3
94@feed 3
95```
95```
96
96
97Advances paper by *n* lines.
97Advances paper by *n* lines.
98
98
99### Cut
99### Cut
100
100
101```markdown
101```markdown
102@cut
102@cut
103```
103```
104
104
105Partial cut after content (if printer supports). Often placed at document end.
105Partial cut after content (if printer supports). Often placed at document end.
106
106
107### Image
107### Image
108
108
109```markdown
109```markdown
110@image path/to/logo.png
110@image path/to/logo.png
111@image ${LogoPath} width=50%
111@image ${LogoPath} width=50%
112@image assets/qr-promo.png width=384
112@image assets/qr-promo.png width=384
113```
113```
114
114
115| Attribute | Description |
115| Attribute | Description |
116|-----------|-------------|
116|-----------|-------------|
117| `path` (positional) | File path relative to `.pos` file or absolute; may be `${Param}` |
117| `path` (positional) | File path relative to `.pos` file or absolute; may be `${Param}` |
118| `width` | `NN%` of printable width, or absolute dots (e.g. `384`) |
118| `width` | `NN%` of printable width, or absolute dots (e.g. `384`) |
119| `align` | `left` (default), `center`, `right` |
119| `align` | `left` (default), `center`, `right` |
120
120
121Images are converted to monochrome raster data, dithered, and scaled to width.
121Images are converted to monochrome raster data, dithered, and scaled to width.
122
122
123### Barcode
123### Barcode
124
124
125```markdown
125```markdown
126@barcode CODE128 ${Sku}
126@barcode CODE128 ${Sku}
127@barcode EAN13 ${EanCode} height=80
127@barcode EAN13 ${EanCode} height=80
128```
128```
129
129
130| Field | Values |
130| Field | Values |
131|-------|--------|
131|-------|--------|
132| Symbology | `CODE128`, `EAN13`, `EAN8`, `CODE39` |
132| Symbology | `CODE128`, `EAN13`, `EAN8`, `CODE39` |
133| Data | Literal or `${Param}` |
133| Data | Literal or `${Param}` |
134| `height` | Module height in dots (default: 64) |
134| `height` | Module height in dots (default: 64) |
135| `align` | `left`, `center`, `right` |
135| `align` | `left`, `center`, `right` |
136| `show_text` | `true` / `false` — HRI below barcode (default: true) |
136| `show_text` | `true` / `false` — HRI below barcode (default: true) |
137
137
138### QR code
138### QR code
139
139
140```markdown
140```markdown
141@qr https://example.com/receipt/${DocumentNumber}
141@qr https://example.com/receipt/${DocumentNumber}
142@qr ${PaymentUrl} size=6
142@qr ${PaymentUrl} size=6
143```
143```
144
144
145| Attribute | Description |
145| Attribute | Description |
146|-----------|-------------|
146|-----------|-------------|
147| Data (positional) | URL or text; may include `${Param}` |
147| Data (positional) | URL or text; may include `${Param}` |
148| `size` | Module size 1–16 (default: 4) |
148| `size` | Module size 1–16 (default: 4) |
149| `ecc` | Error correction: `L`, `M`, `Q`, `H` (default: `M`) |
149| `ecc` | Error correction: `L`, `M`, `Q`, `H` (default: `M`) |
150| `align` | `left`, `center`, `right` |
150| `align` | `left`, `center`, `right` |
151
151
152---
152---
153
153
154## Parameters
154## Parameters
155
155
156### Syntax
156### Syntax
157
157
158```
158```
159${ParameterName}
159${ParameterName}
160```
160```
161
161
162- **Names:** `[A-Za-z_][A-Za-z0-9_]*` (ASCII letters, digits, underscore)
162- **Names:** `[A-Za-z_][A-Za-z0-9_]*` (ASCII letters, digits, underscore)
163- **Case-sensitive:** `${DocNo}` and `${docno}` are different
163- **Case-sensitive:** `${DocNo}` and `${docno}` are different
164- **Uniqueness at input:** all occurrences of the same name share one value entered at print time
164- **Uniqueness at input:** all occurrences of the same name share one value entered at print time
165
165
166### Where parameters are allowed
166### Where parameters are allowed
167
167
168| Location | Example |
168| Location | Example |
169|----------|---------|
169|----------|---------|
170| Text | `Order ${OrderId}` |
170| Text | `Order ${OrderId}` |
171| Barcode data | `@barcode CODE128 ${OrderId}` |
171| Barcode data | `@barcode CODE128 ${OrderId}` |
172| QR data | `@qr ${VerifyUrl}` |
172| QR data | `@qr ${VerifyUrl}` |
173| Image path | `@image ${LogoPath}` |
173| Image path | `@image ${LogoPath}` |
174
174
175### Print-time behavior
175### Print-time behavior
176
176
1771. Before print, scan AST for all `${...}` tokens.
1771. Before print, scan AST for all `${...}` tokens.
1782. Deduplicate by name.
1782. Deduplicate by name.
1793. Show dialog with one field per unique name.
1793. Show dialog with one field per unique name.
1804. Pre-fill from last print session (global or per-file — implementation choice).
1804. Pre-fill from last print session (global or per-file — implementation choice).
1815. Substitute into AST, then render/print.
1815. Substitute into AST, then render/print.
182
182
183Missing parameter at print time: block print and highlight unresolved names in UI.
183Missing parameter at print time: block print and highlight unresolved names in UI.
184
184
185---
185---
186
186
187## Comments
187## Comments
188
188
189```markdown
189```markdown
190<!-- This is a comment, not printed -->
190<!-- This is a comment, not printed -->
191```
191```
192
192
193HTML-style comments are stripped at parse time.
193HTML-style comments are stripped at parse time.
194
194
195---
195---
196
196
197## Example document
197## Example document
198
198
199```markdown
199```markdown
200# ${StoreName}
200# ${StoreName}
201:center:
201:center:
202
202
203123 Main Street
203123 Main Street
204Tel: ${StorePhone}
204Tel: ${StorePhone}
205
205
206---
206---
207Date: ${Date} Time: ${Time}
207Date: ${Date} Time: ${Time}
208Receipt: ${DocumentNumber}
208Receipt: ${DocumentNumber}
209
209
210Item Total
210Item Total
211${LineItems}
211${LineItems}
212
212
213---
213---
214:right:
214:right:
215**TOTAL: ${GrandTotal}**
215**TOTAL: ${GrandTotal}**
216
216
217@barcode CODE128 ${DocumentNumber}
217@barcode CODE128 ${DocumentNumber}
218@feed 2
218@feed 2
219@qr https://shop.example.com/r/${DocumentNumber}
219@qr https://shop.example.com/r/${DocumentNumber}
220
220
221Thank you!
221Thank you!
222@feed 4
222@feed 4
223@cut
223@cut
224```
224```
225
225
226`${LineItems}` might be pre-formatted multi-line text passed as a single parameter (v1); structured line items are a future extension.
226`${LineItems}` might be pre-formatted multi-line text passed as a single parameter (v1); structured line items are a future extension.
227
227
228---
228---
229
229
230## Parse errors
230## Parse errors
231
231
232The parser reports:
232The parser reports:
233
233
234- Unknown directive
234- Unknown directive
235- Invalid barcode symbology
235- Invalid barcode symbology
236- Unclosed `**` or `` ` ``
236- Unclosed `**` or `` ` ``
237- Invalid `${}` name
237- Invalid `${}` name
238- Missing required directive argument
238- Missing required directive argument
239
239
240Errors include 1-based line and column for editor highlighting.
240Errors include 1-based line and column for editor highlighting.
241
241
242---
242---
243
243
244## ESC/POS mapping (summary)
244## ESC/POS mapping (summary)
245
245
246| DSL | ESC/POS |
246| DSL | ESC/POS |
247|-----|---------|
247|-----|---------|
248| `# heading` | Double width/height ON → text → OFF |
248| `# heading` | Double width/height ON → text → OFF |
249| `**bold**` | Bold ON/OFF |
249| `**bold**` | Bold ON/OFF |
250| `:center:` | Justification center |
250| `:center:` | Justification center |
251| `@feed n` | Print and feed n lines |
251| `@feed n` | Print and feed n lines |
252| `@cut` | GS V partial cut |
252| `@cut` | GS V partial cut |
253| `@barcode` | GS k / CODE128 native |
253| `@barcode` | GS k / CODE128 native |
254| `@qr` | GS ( k QR model 2 |
254| `@qr` | GS ( k QR model 2 |
255| `@image` | GS v 0 raster bit image |
255| `@image` | GS v 0 raster bit image |
256
256
257Full command details live in the print encoder module; see [PRINTING.md](PRINTING.md).
257Full command details live in the print encoder module; see [PRINTING.md](PRINTING.md).
258
258
259---
259---
260
260
261## Future extensions (not implemented)
261## Future extensions (not implemented)
262
262
263- `@table` for columnar line items
263- `@table` for columnar line items
264- `UPC-A` barcodes
264- `UPC-A` barcodes
265- Conditionals: `@if ${HasDiscount} ... @endif`
265- Conditionals: `@if ${HasDiscount} ... @endif`
266- Loops / repeating sections
266- Loops / repeating sections
267- `@signature` for custom ESC/POS hex escape
267- `@signature` for custom ESC/POS hex escape
268- Multiple code pages / Unicode subset
268- Multiple code pages / Unicode subset
269- Syntax highlighting in the editor
269- Syntax highlighting in the editor
docs/FEASIBILITY.md +166 −166
@@ -1,166 +1,166 @@
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 # 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 +1,166 @@
1# Feasibility and complexity assessment
1# Feasibility and complexity assessment
2
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.
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
4
5## Executive summary
5## Executive summary
6
6
7| Question | Answer |
7| Question | Answer |
8|----------|--------|
8|----------|--------|
9| Is it feasible? | **Yes** — all required capabilities exist in mature libraries or documented protocols |
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 |
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) |
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 |
12| Recommended MVP scope | USB-serial printers first (**done**); USB-printer-class and Bluetooth later |
13
13
14A 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**.
14A 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
15
16---
16---
17
17
18## Requirements breakdown
18## Requirements breakdown
19
19
20### 1. Cross-platform desktop app (Windows + Linux)
20### 1. Cross-platform desktop app (Windows + Linux)
21
21
22| Aspect | Feasibility | Complexity |
22| Aspect | Feasibility | Complexity |
23|--------|-------------|------------|
23|--------|-------------|------------|
24| Single codebase, native binaries | High | Low–medium |
24| Single codebase, native binaries | High | Low–medium |
25| Packaged installers (.msi/.exe, .deb/AppImage) | High | Medium |
25| Packaged installers (.msi/.exe, .deb/AppImage) | High | Medium |
26
26
27Modern cross-platform desktop frameworks (Tauri, egui, Avalonia, Qt) all support Windows and Linux. Packaging is routine but needs CI and per-OS testing.
27Modern cross-platform desktop frameworks (Tauri, egui, Avalonia, Qt) all support Windows and Linux. Packaging is routine but needs CI and per-OS testing.
28
28
29### 2. Markdown-like document syntax + live preview
29### 2. Markdown-like document syntax + live preview
30
30
31| Aspect | Feasibility | Complexity |
31| Aspect | Feasibility | Complexity |
32|--------|-------------|------------|
32|--------|-------------|------------|
33| Custom lightweight DSL | High | Medium |
33| Custom lightweight DSL | High | Medium |
34| Live preview pane | High | Medium |
34| Live preview pane | High | Medium |
35| Width modes (auto-scale / fixed mm) | High | Low–medium |
35| Width modes (auto-scale / fixed mm) | High | Low–medium |
36
36
37The 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.
37The 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
38
39### 3. Save / load `.pos` files
39### 3. Save / load `.pos` files
40
40
41| Aspect | Feasibility | Complexity |
41| Aspect | Feasibility | Complexity |
42|--------|-------------|------------|
42|--------|-------------|------------|
43| JSON or TOML envelope + body text | High | Low |
43| JSON or TOML envelope + body text | High | Low |
44
44
45Trivial with serde (Rust) or equivalent. Version field supports forward-compatible evolution.
45Trivial with serde (Rust) or equivalent. Version field supports forward-compatible evolution.
46
46
47### 4. Parameter tokens (`${Name}`)
47### 4. Parameter tokens (`${Name}`)
48
48
49| Aspect | Feasibility | Complexity |
49| Aspect | Feasibility | Complexity |
50|--------|-------------|------------|
50|--------|-------------|------------|
51| Parse and collect unique names | High | Low |
51| Parse and collect unique names | High | Low |
52| Print-time modal with last-used values | High | Low |
52| Print-time modal with last-used values | High | Low |
53| Deduplicate same name across document | High | Low |
53| Deduplicate same name across document | High | Low |
54| Use in text, barcodes, QR, images | High | Low–medium |
54| Use in text, barcodes, QR, images | High | Low–medium |
55
55
56Straightforward string substitution after validation. Image parameters might reference file paths or base64 — define clearly in DSL spec.
56Straightforward string substitution after validation. Image parameters might reference file paths or base64 — define clearly in DSL spec.
57
57
58### 5. Barcodes, QR codes, images
58### 5. Barcodes, QR codes, images
59
59
60| Aspect | Feasibility | Complexity |
60| Aspect | Feasibility | Complexity |
61|--------|-------------|------------|
61|--------|-------------|------------|
62| Generate ESC/POS barcode commands | High | Low |
62| Generate ESC/POS barcode commands | High | Low |
63| Generate ESC/POS QR commands | High | Low |
63| Generate ESC/POS QR commands | High | Low |
64| Rasterize images to printer width | High | Medium |
64| Rasterize images to printer width | High | Medium |
65
65
66ESC/POS barcode, QR, and raster image commands are implemented in `src/escpos.rs` (in-tree). Preview uses text placeholders for barcodes/QR/images.
66ESC/POS barcode, QR, and raster image commands are implemented in `src/escpos.rs` (in-tree). Preview uses text placeholders for barcodes/QR/images.
67
67
68### 6. Direct USB / Bluetooth printing (raw bytes, no spooler)
68### 6. Direct USB / Bluetooth printing (raw bytes, no spooler)
69
69
70| Aspect | Feasibility | Complexity |
70| Aspect | Feasibility | Complexity |
71|--------|-------------|------------|
71|--------|-------------|------------|
72| USB serial (CDC-ACM, CH340, FTDI) | **High** | Medium |
72| USB serial (CDC-ACM, CH340, FTDI) | **High** | Medium |
73| USB printer class (bulk OUT) | Medium | **High** |
73| USB printer class (bulk OUT) | Medium | **High** |
74| Bluetooth Classic SPP | Medium | **High** |
74| Bluetooth Classic SPP | Medium | **High** |
75| Enumerate devices in UI | Medium | Medium |
75| Enumerate devices in UI | Medium | Medium |
76| Printer-specific quirks | Ongoing | **High** |
76| Printer-specific quirks | Ongoing | **High** |
77
77
78This is the **primary technical risk**.
78This is the **primary technical risk**.
79
79
80#### How POS printers actually connect
80#### How POS printers actually connect
81
81
82Most consumer thermal printers expose one of:
82Most consumer thermal printers expose one of:
83
83
841. **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.**
841. **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
85
862. **USB printer class (interface 7)** — bulk transfers; **not implemented**. Would need `nusb` or Windows `usbprint.sys`.
862. **USB printer class (interface 7)** — bulk transfers; **not implemented**. Would need `nusb` or Windows `usbprint.sys`.
87
87
883. **Bluetooth Classic SPP** — **not implemented**; deferred.
883. **Bluetooth Classic SPP** — **not implemented**; deferred.
89
89
904. **Network (TCP 9100)** — common in production but **out of scope** unless added later.
904. **Network (TCP 9100)** — common in production but **out of scope** unless added later.
91
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.
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
93
94#### Compatibility reality
94#### Compatibility reality
95
95
96- **MVP (done):** Epson-compatible ESC/POS over USB-serial at 9600 baud.
96- **MVP (done):** Epson-compatible ESC/POS over USB-serial at 9600 baud.
97- **Future:** USB printer class, Bluetooth SPP.
97- **Future:** USB printer class, Bluetooth SPP.
98
98
99Expect **per-printer testing**; some devices need init sequences, code pages, or cut commands that differ slightly.
99Expect **per-printer testing**; some devices need init sequences, code pages, or cut commands that differ slightly.
100
100
101---
101---
102
102
103## Complexity by subsystem
103## Complexity by subsystem
104
104
105```
105```
106 Effort (relative)
106 Effort (relative)
107Editor UI ████████░░ Medium
107Editor UI ████████░░ Medium
108Preview renderer ███████░░░ Medium
108Preview renderer ███████░░░ Medium
109DSL parser ██████░░░░ Medium
109DSL parser ██████░░░░ Medium
110File I/O ██░░░░░░░░ Low
110File I/O ██░░░░░░░░ Low
111Parameters ███░░░░░░░ Low
111Parameters ███░░░░░░░ Low
112Barcode/QR/image █████░░░░░ Low–medium
112Barcode/QR/image █████░░░░░ Low–medium
113Printer discovery ███████░░░ Medium
113Printer discovery ███████░░░ Medium
114Raw print I/O █████████░ High
114Raw print I/O █████████░ High
115Integration/polish ██████░░░░ Medium
115Integration/polish ██████░░░░ Medium
116```
116```
117
117
118---
118---
119
119
120## Effort estimate (one experienced developer)
120## Effort estimate (one experienced developer)
121
121
122| Phase | Scope | Duration |
122| Phase | Scope | Duration |
123|-------|-------|----------|
123|-------|-------|----------|
124| **0 — Design** | Specs, DSL, file format | 1 week |
124| **0 — Design** | Specs, DSL, file format | 1 week |
125| **1 — Core** | Parser, ESC/POS builder, preview, `.pos` I/O | 2–3 weeks |
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 |
126| **2 — UI** | Editor, preview split, settings, parameters dialog | 2 weeks |
127| **3 — Print MVP** | USB-serial enumeration + print | 1–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 |
128| **4 — Hardening** | USB class, BT, edge cases, packaging | 2–4 weeks |
129
129
130**MVP (serial USB only):** ~6–8 weeks
130**MVP (serial USB only):** ~6–8 weeks
131**Full v1 (USB + BT, packaged):** ~10–14 weeks
131**Full v1 (USB + BT, packaged):** ~10–14 weeks
132
132
133Add 30–50% if the developer is new to Rust or ESC/POS.
133Add 30–50% if the developer is new to Rust or ESC/POS.
134
134
135---
135---
136
136
137## Risks and mitigations
137## Risks and mitigations
138
138
139| Risk | Impact | Mitigation |
139| Risk | Impact | Mitigation |
140|------|--------|------------|
140|------|--------|------------|
141| Printer hardware diversity | Prints garbled or not at all | ESC/POS subset doc; test matrix; user-selectable code page |
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 |
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 |
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 |
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 |
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 |
146| Image size on narrow paper | Slow print or clipped | Auto-scale to page width; warn in UI |
147
147
148---
148---
149
149
150## Out of scope (current release)
150## Out of scope (current release)
151
151
152- Bluetooth printing
152- Bluetooth printing
153- USB printer class (non-serial)
153- USB printer class (non-serial)
154- Network printers (TCP 9100)
154- Network printers (TCP 9100)
155- Non-ESC/POS protocols (Star Line, ZPL)
155- Non-ESC/POS protocols (Star Line, ZPL)
156- Multi-column layout engines
156- Multi-column layout engines
157- Collaborative editing / cloud sync
157- Collaborative editing / cloud sync
158- macOS (feasible later with same stack)
158- macOS (feasible later with same stack)
159
159
160---
160---
161
161
162## Recommendation
162## Recommendation
163
163
164**MVP delivered.** Next increments: USB printer class, baud settings, persisted parameters, hardware test matrix. Bluetooth only if explicitly needed.
164**MVP delivered.** Next increments: USB printer class, baud settings, persisted parameters, hardware test matrix. Bluetooth only if explicitly needed.
165
165
166See [LANGUAGE-CHOICE.md](LANGUAGE-CHOICE.md) and [ARCHITECTURE.md](ARCHITECTURE.md).
166See [LANGUAGE-CHOICE.md](LANGUAGE-CHOICE.md) and [ARCHITECTURE.md](ARCHITECTURE.md).
docs/FILE-FORMAT.md +142 −142
@@ -1,142 +1,142 @@
1 # `.pos` file format
2
3 A `.pos` file stores a POS print template: metadata (page settings, title) plus the DSL document body as plain text.
4
5 **Format:** JSON envelope with a `.pos` extension (human-readable, git-friendly).
6 **MIME type (suggested):** `application/vnd.posprint+json`
7
8 ---
9
10 ## Top-level schema
11
12 ```json
13 {
14 "version": 1,
15 "metadata": { ... },
16 "body": "..."
17 }
18 ```
19
20 | Field | Type | Required | Description |
21 |-------|------|----------|-------------|
22 | `version` | `number` | yes | File format version (currently `1`) |
23 | `metadata` | `object` | yes | Document settings |
24 | `body` | `string` | yes | DSL source (UTF-8, `\n` line endings normalized on load) |
25
26 ---
27
28 ## Metadata schema (version 1)
29
30 ```json
31 {
32 "title": "Sales Receipt",
33 "page_width_mm": 80,
34 "preview_mode": "autoscale",
35 "chars_per_line": 48,
36 "codepage": "CP437",
37 "cut_after_print": true
38 }
39 ```
40
41 | Field | Type | Default | Description |
42 |-------|------|---------|-------------|
43 | `title` | `string?` | `null` | Display name in app title / recent files |
44 | `page_width_mm` | `number` | `80` | Physical paper width: `58` or `80` (others allowed) |
45 | `preview_mode` | `"autoscale"` \| `"fixed"` | `"autoscale"` | How preview panel sizes content |
46 | `chars_per_line` | `number?` | derived | Override character width for preview; derived from mm if omitted |
47 | `codepage` | `string?` | `"CP437"` | Character encoding for ESC/POS text |
48 | `cut_after_print` | `boolean` | `true` | Append cut command when printing if doc has no `@cut` |
49
50 ### Page width derivation
51
52 | `page_width_mm` | Typical dots (203 DPI) | Default `chars_per_line` (Font A) |
53 |-----------------|------------------------|-----------------------------------|
54 | 58 | 384 | 32 |
55 | 80 | 576 | 48 |
56
57 ---
58
59 ## Example file
60
61 **`receipt.pos`:**
62
63 ```json
64 {
65 "version": 1,
66 "metadata": {
67 "title": "Standard Receipt",
68 "page_width_mm": 80,
69 "preview_mode": "autoscale",
70 "codepage": "CP437",
71 "cut_after_print": true
72 },
73 "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"
74 }
75 ```
76
77 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.
78
79 ---
80
81 ## Asset resolution
82
83 - Paths in `@image` directives are resolved relative to the **directory containing the `.pos` file** unless absolute.
84 - Bundled assets: optional `assets/` subfolder next to the template.
85 - Parameterized image paths (`${LogoPath}`) resolve after substitution; relative paths still anchor to the `.pos` file directory.
86
87 ---
88
89 ## Version migration
90
91 | From | To | Migration |
92 |------|-----|-----------|
93 | — | 1 | Initial release |
94
95 On load, if `version` is newer than app supports → error with upgrade message.
96 If older → run migration chain (none yet).
97
98 ---
99
100 ## Alternative considered: two-file bundle
101
102 Rejected for v1: `.pos` + sidecar `.pos.json` adds friction. Single JSON file keeps save/load atomic.
103
104 A future `.poszip` could bundle images for portable templates.
105
106 ---
107
108 ## Validation rules
109
110 On save:
111
112 - `version` must equal supported version
113 - `page_width_mm` > 0
114 - `body` must be valid UTF-8
115
116 On load:
117
118 - Parse JSON; validate schema
119 - Parse `body` with DSL parser; warnings shown in UI but file still loads
120
121 ---
122
123 ## TypeScript / Rust types (reference)
124
125 ```typescript
126 interface PosFile {
127 version: number;
128 metadata: PosMetadata;
129 body: string;
130 }
131
132 interface PosMetadata {
133 title?: string;
134 page_width_mm: number;
135 preview_mode: "autoscale" | "fixed";
136 chars_per_line?: number;
137 codepage?: string;
138 cut_after_print?: boolean;
139 }
140 ```
141
142 Rust types use `serde` derive in `src/io/mod.rs` and are used directly by the egui app (no IPC layer).
1 # `.pos` file format
2
3 A `.pos` file stores a POS print template: metadata (page settings, title) plus the DSL document body as plain text.
4
5 **Format:** JSON envelope with a `.pos` extension (human-readable, git-friendly).
6 **MIME type (suggested):** `application/vnd.posprint+json`
7
8 ---
9
10 ## Top-level schema
11
12 ```json
13 {
14 "version": 1,
15 "metadata": { ... },
16 "body": "..."
17 }
18 ```
19
20 | Field | Type | Required | Description |
21 |-------|------|----------|-------------|
22 | `version` | `number` | yes | File format version (currently `1`) |
23 | `metadata` | `object` | yes | Document settings |
24 | `body` | `string` | yes | DSL source (UTF-8, `\n` line endings normalized on load) |
25
26 ---
27
28 ## Metadata schema (version 1)
29
30 ```json
31 {
32 "title": "Sales Receipt",
33 "page_width_mm": 80,
34 "preview_mode": "autoscale",
35 "chars_per_line": 48,
36 "codepage": "CP437",
37 "cut_after_print": true
38 }
39 ```
40
41 | Field | Type | Default | Description |
42 |-------|------|---------|-------------|
43 | `title` | `string?` | `null` | Display name in app title / recent files |
44 | `page_width_mm` | `number` | `80` | Physical paper width: `58` or `80` (others allowed) |
45 | `preview_mode` | `"autoscale"` \| `"fixed"` | `"autoscale"` | How preview panel sizes content |
46 | `chars_per_line` | `number?` | derived | Override character width for preview; derived from mm if omitted |
47 | `codepage` | `string?` | `"CP437"` | Character encoding for ESC/POS text |
48 | `cut_after_print` | `boolean` | `true` | Append cut command when printing if doc has no `@cut` |
49
50 ### Page width derivation
51
52 | `page_width_mm` | Typical dots (203 DPI) | Default `chars_per_line` (Font A) |
53 |-----------------|------------------------|-----------------------------------|
54 | 58 | 384 | 32 |
55 | 80 | 576 | 48 |
56
57 ---
58
59 ## Example file
60
61 **`receipt.pos`:**
62
63 ```json
64 {
65 "version": 1,
66 "metadata": {
67 "title": "Standard Receipt",
68 "page_width_mm": 80,
69 "preview_mode": "autoscale",
70 "codepage": "CP437",
71 "cut_after_print": true
72 },
73 "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"
74 }
75 ```
76
77 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.
78
79 ---
80
81 ## Asset resolution
82
83 - Paths in `@image` directives are resolved relative to the **directory containing the `.pos` file** unless absolute.
84 - Bundled assets: optional `assets/` subfolder next to the template.
85 - Parameterized image paths (`${LogoPath}`) resolve after substitution; relative paths still anchor to the `.pos` file directory.
86
87 ---
88
89 ## Version migration
90
91 | From | To | Migration |
92 |------|-----|-----------|
93 | — | 1 | Initial release |
94
95 On load, if `version` is newer than app supports → error with upgrade message.
96 If older → run migration chain (none yet).
97
98 ---
99
100 ## Alternative considered: two-file bundle
101
102 Rejected for v1: `.pos` + sidecar `.pos.json` adds friction. Single JSON file keeps save/load atomic.
103
104 A future `.poszip` could bundle images for portable templates.
105
106 ---
107
108 ## Validation rules
109
110 On save:
111
112 - `version` must equal supported version
113 - `page_width_mm` > 0
114 - `body` must be valid UTF-8
115
116 On load:
117
118 - Parse JSON; validate schema
119 - Parse `body` with DSL parser; warnings shown in UI but file still loads
120
121 ---
122
123 ## TypeScript / Rust types (reference)
124
125 ```typescript
126 interface PosFile {
127 version: number;
128 metadata: PosMetadata;
129 body: string;
130 }
131
132 interface PosMetadata {
133 title?: string;
134 page_width_mm: number;
135 preview_mode: "autoscale" | "fixed";
136 chars_per_line?: number;
137 codepage?: string;
138 cut_after_print?: boolean;
139 }
140 ```
141
142 Rust types use `serde` derive in `src/io/mod.rs` and are used directly by the egui app (no IPC layer).
@@ -1,142 +1,142 @@
1# `.pos` file format
1# `.pos` file format
2
2
3A `.pos` file stores a POS print template: metadata (page settings, title) plus the DSL document body as plain text.
3A `.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**MIME type (suggested):** `application/vnd.posprint+json`
7
7
8---
8---
9
9
10## Top-level schema
10## Top-level schema
11
11
12```json
12```json
13{
13{
14 "version": 1,
14 "version": 1,
15 "metadata": { ... },
15 "metadata": { ... },
16 "body": "..."
16 "body": "..."
17}
17}
18```
18```
19
19
20| Field | Type | Required | Description |
20| Field | Type | Required | Description |
21|-------|------|----------|-------------|
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, `\n` line endings normalized on load) |
25
25
26---
26---
27
27
28## Metadata schema (version 1)
28## Metadata schema (version 1)
29
29
30```json
30```json
31{
31{
32 "title": "Sales Receipt",
32 "title": "Sales Receipt",
33 "page_width_mm": 80,
33 "page_width_mm": 80,
34 "preview_mode": "autoscale",
34 "preview_mode": "autoscale",
35 "chars_per_line": 48,
35 "chars_per_line": 48,
36 "codepage": "CP437",
36 "codepage": "CP437",
37 "cut_after_print": true
37 "cut_after_print": true
38}
38}
39```
39```
40
40
41| Field | Type | Default | Description |
41| Field | Type | Default | Description |
42|-------|------|---------|-------------|
42|-------|------|---------|-------------|
43| `title` | `string?` | `null` | Display name in app title / recent files |
43| `title` | `string?` | `null` | Display name in app title / recent files |
44| `page_width_mm` | `number` | `80` | Physical paper width: `58` or `80` (others allowed) |
44| `page_width_mm` | `number` | `80` | Physical paper width: `58` or `80` (others allowed) |
45| `preview_mode` | `"autoscale"` \| `"fixed"` | `"autoscale"` | How preview panel sizes content |
45| `preview_mode` | `"autoscale"` \| `"fixed"` | `"autoscale"` | How preview panel sizes content |
46| `chars_per_line` | `number?` | derived | Override character width for preview; derived from mm if omitted |
46| `chars_per_line` | `number?` | derived | Override character width for preview; derived from mm if omitted |
47| `codepage` | `string?` | `"CP437"` | Character encoding for ESC/POS text |
47| `codepage` | `string?` | `"CP437"` | Character encoding for ESC/POS text |
48| `cut_after_print` | `boolean` | `true` | Append cut command when printing if doc has no `@cut` |
48| `cut_after_print` | `boolean` | `true` | Append cut command when printing if doc has no `@cut` |
49
49
50### Page width derivation
50### Page width derivation
51
51
52| `page_width_mm` | Typical dots (203 DPI) | Default `chars_per_line` (Font A) |
52| `page_width_mm` | Typical dots (203 DPI) | Default `chars_per_line` (Font A) |
53|-----------------|------------------------|-----------------------------------|
53|-----------------|------------------------|-----------------------------------|
54| 58 | 384 | 32 |
54| 58 | 384 | 32 |
55| 80 | 576 | 48 |
55| 80 | 576 | 48 |
56
56
57---
57---
58
58
59## Example file
59## Example file
60
60
61**`receipt.pos`:**
61**`receipt.pos`:**
62
62
63```json
63```json
64{
64{
65 "version": 1,
65 "version": 1,
66 "metadata": {
66 "metadata": {
67 "title": "Standard Receipt",
67 "title": "Standard Receipt",
68 "page_width_mm": 80,
68 "page_width_mm": 80,
69 "preview_mode": "autoscale",
69 "preview_mode": "autoscale",
70 "codepage": "CP437",
70 "codepage": "CP437",
71 "cut_after_print": true
71 "cut_after_print": true
72 },
72 },
73 "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"
73 "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"
74}
74}
75```
75```
76
76
77For 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.
77For 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.
78
78
79---
79---
80
80
81## Asset resolution
81## Asset resolution
82
82
83- Paths in `@image` directives are resolved relative to the **directory containing the `.pos` file** unless absolute.
83- Paths in `@image` directives are resolved relative to the **directory containing the `.pos` file** unless absolute.
84- Bundled assets: optional `assets/` subfolder next to the template.
84- Bundled assets: optional `assets/` subfolder next to the template.
85- Parameterized image paths (`${LogoPath}`) resolve after substitution; relative paths still anchor to the `.pos` file directory.
85- Parameterized image paths (`${LogoPath}`) resolve after substitution; relative paths still anchor to the `.pos` file directory.
86
86
87---
87---
88
88
89## Version migration
89## Version migration
90
90
91| From | To | Migration |
91| From | To | Migration |
92|------|-----|-----------|
92|------|-----|-----------|
93| — | 1 | Initial release |
93| — | 1 | Initial release |
94
94
95On load, if `version` is newer than app supports → error with upgrade message.
95On load, if `version` is newer than app supports → error with upgrade message.
96If older → run migration chain (none yet).
96If older → run migration chain (none yet).
97
97
98---
98---
99
99
100## Alternative considered: two-file bundle
100## Alternative considered: two-file bundle
101
101
102Rejected for v1: `.pos` + sidecar `.pos.json` adds friction. Single JSON file keeps save/load atomic.
102Rejected for v1: `.pos` + sidecar `.pos.json` adds friction. Single JSON file keeps save/load atomic.
103
103
104A future `.poszip` could bundle images for portable templates.
104A future `.poszip` could bundle images for portable templates.
105
105
106---
106---
107
107
108## Validation rules
108## Validation rules
109
109
110On save:
110On save:
111
111
112- `version` must equal supported version
112- `version` must equal supported version
113- `page_width_mm` > 0
113- `page_width_mm` > 0
114- `body` must be valid UTF-8
114- `body` must be valid UTF-8
115
115
116On load:
116On load:
117
117
118- Parse JSON; validate schema
118- Parse JSON; validate schema
119- Parse `body` with DSL parser; warnings shown in UI but file still loads
119- Parse `body` with DSL parser; warnings shown in UI but file still loads
120
120
121---
121---
122
122
123## TypeScript / Rust types (reference)
123## TypeScript / Rust types (reference)
124
124
125```typescript
125```typescript
126interface PosFile {
126interface PosFile {
127 version: number;
127 version: number;
128 metadata: PosMetadata;
128 metadata: PosMetadata;
129 body: string;
129 body: string;
130}
130}
131
131
132interface PosMetadata {
132interface PosMetadata {
133 title?: string;
133 title?: string;
134 page_width_mm: number;
134 page_width_mm: number;
135 preview_mode: "autoscale" | "fixed";
135 preview_mode: "autoscale" | "fixed";
136 chars_per_line?: number;
136 chars_per_line?: number;
137 codepage?: string;
137 codepage?: string;
138 cut_after_print?: boolean;
138 cut_after_print?: boolean;
139}
139}
140```
140```
141
141
142Rust types use `serde` derive in `src/io/mod.rs` and are used directly by the egui app (no IPC layer).
142Rust types use `serde` derive in `src/io/mod.rs` and are used directly by the egui app (no IPC layer).
docs/HELP-CLI-LINUX.md +66 −66
@@ -1,66 +1,66 @@
1 # Command-line printing (Linux)
2
3 Print a `.pos` template without opening the GUI.
4
5 ## Syntax
6
7 ```bash
8 posprint print <file.pos> --printer <DEVICE> --set Name=Value [--set Other=Value ...]
9 ```
10
11 Short form:
12
13 ```bash
14 posprint print receipt.pos -p /dev/ttyUSB0 --set StoreName="My Shop" --set DocumentNumber=1001
15 ```
16
17 ## Rules
18
19 - **`--printer` / `-p`** (required): serial device path, e.g. `/dev/ttyUSB0`, `/dev/ttyACM0`.
20 - **`--set NAME=VALUE`** (required for every parameter): one flag per `${Name}` in the template.
21 - If any `${Name}` is missing or empty, the command **fails** and lists missing parameters.
22 - The GUI is not started when using the `print` subcommand.
23
24 ## Permissions
25
26 Your user must be in the **`dialout`** group:
27
28 ```bash
29 sudo usermod -aG dialout "$USER"
30 # log out and back in
31 groups
32 ```
33
34 ## Examples
35
36 ```bash
37 posprint print ~/receipts/sale.pos -p /dev/ttyUSB0 \
38 --set StoreName="Corner Cafe" \
39 --set DocumentNumber=42 \
40 --set Date=2026-07-15 \
41 --set GrandTotal=19.99
42 ```
43
44 ## Printer device
45
46 ```bash
47 ls -l /dev/ttyUSB* /dev/ttyACM* 2>/dev/null
48 ```
49
50 Use the device node shown when the printer is connected.
51
52 ## Exit codes
53
54 | Code | Meaning |
55 |------|---------|
56 | `0` | Printed successfully |
57 | `1` | Error (missing parameters, parse error, permission denied, etc.) |
58
59 ## Help
60
61 ```bash
62 posprint print --help
63 posprint --help
64 ```
65
66 Launch the graphical designer by running `posprint` with **no** subcommand.
1 # Command-line printing (Linux)
2
3 Print a `.pos` template without opening the GUI.
4
5 ## Syntax
6
7 ```bash
8 posprint print <file.pos> --printer <DEVICE> --set Name=Value [--set Other=Value ...]
9 ```
10
11 Short form:
12
13 ```bash
14 posprint print receipt.pos -p /dev/ttyUSB0 --set StoreName="My Shop" --set DocumentNumber=1001
15 ```
16
17 ## Rules
18
19 - **`--printer` / `-p`** (required): serial device path, e.g. `/dev/ttyUSB0`, `/dev/ttyACM0`.
20 - **`--set NAME=VALUE`** (required for every parameter): one flag per `${Name}` in the template.
21 - If any `${Name}` is missing or empty, the command **fails** and lists missing parameters.
22 - The GUI is not started when using the `print` subcommand.
23
24 ## Permissions
25
26 Your user must be in the **`dialout`** group:
27
28 ```bash
29 sudo usermod -aG dialout "$USER"
30 # log out and back in
31 groups
32 ```
33
34 ## Examples
35
36 ```bash
37 posprint print ~/receipts/sale.pos -p /dev/ttyUSB0 \
38 --set StoreName="Corner Cafe" \
39 --set DocumentNumber=42 \
40 --set Date=2026-07-15 \
41 --set GrandTotal=19.99
42 ```
43
44 ## Printer device
45
46 ```bash
47 ls -l /dev/ttyUSB* /dev/ttyACM* 2>/dev/null
48 ```
49
50 Use the device node shown when the printer is connected.
51
52 ## Exit codes
53
54 | Code | Meaning |
55 |------|---------|
56 | `0` | Printed successfully |
57 | `1` | Error (missing parameters, parse error, permission denied, etc.) |
58
59 ## Help
60
61 ```bash
62 posprint print --help
63 posprint --help
64 ```
65
66 Launch the graphical designer by running `posprint` with **no** subcommand.
@@ -1,66 +1,66 @@
1# Command-line printing (Linux)
1# Command-line printing (Linux)
2
2
3Print a `.pos` template without opening the GUI.
3Print a `.pos` template without opening the GUI.
4
4
5## Syntax
5## Syntax
6
6
7```bash
7```bash
8posprint print <file.pos> --printer <DEVICE> --set Name=Value [--set Other=Value ...]
8posprint print <file.pos> --printer <DEVICE> --set Name=Value [--set Other=Value ...]
9```
9```
10
10
11Short form:
11Short form:
12
12
13```bash
13```bash
14posprint print receipt.pos -p /dev/ttyUSB0 --set StoreName="My Shop" --set DocumentNumber=1001
14posprint print receipt.pos -p /dev/ttyUSB0 --set StoreName="My Shop" --set DocumentNumber=1001
15```
15```
16
16
17## Rules
17## Rules
18
18
19- **`--printer` / `-p`** (required): serial device path, e.g. `/dev/ttyUSB0`, `/dev/ttyACM0`.
19- **`--printer` / `-p`** (required): serial device path, e.g. `/dev/ttyUSB0`, `/dev/ttyACM0`.
20- **`--set NAME=VALUE`** (required for every parameter): one flag per `${Name}` in the template.
20- **`--set NAME=VALUE`** (required for every parameter): one flag per `${Name}` in the template.
21- If any `${Name}` is missing or empty, the command **fails** and lists missing parameters.
21- If any `${Name}` is missing or empty, the command **fails** and lists missing parameters.
22- The GUI is not started when using the `print` subcommand.
22- The GUI is not started when using the `print` subcommand.
23
23
24## Permissions
24## Permissions
25
25
26Your user must be in the **`dialout`** group:
26Your user must be in the **`dialout`** group:
27
27
28```bash
28```bash
29sudo usermod -aG dialout "$USER"
29sudo usermod -aG dialout "$USER"
30# log out and back in
30# log out and back in
31groups
31groups
32```
32```
33
33
34## Examples
34## Examples
35
35
36```bash
36```bash
37posprint print ~/receipts/sale.pos -p /dev/ttyUSB0 \
37posprint print ~/receipts/sale.pos -p /dev/ttyUSB0 \
38 --set StoreName="Corner Cafe" \
38 --set StoreName="Corner Cafe" \
39 --set DocumentNumber=42 \
39 --set DocumentNumber=42 \
40 --set Date=2026-07-15 \
40 --set Date=2026-07-15 \
41 --set GrandTotal=19.99
41 --set GrandTotal=19.99
42```
42```
43
43
44## Printer device
44## Printer device
45
45
46```bash
46```bash
47ls -l /dev/ttyUSB* /dev/ttyACM* 2>/dev/null
47ls -l /dev/ttyUSB* /dev/ttyACM* 2>/dev/null
48```
48```
49
49
50Use the device node shown when the printer is connected.
50Use the device node shown when the printer is connected.
51
51
52## Exit codes
52## Exit codes
53
53
54| Code | Meaning |
54| Code | Meaning |
55|------|---------|
55|------|---------|
56| `0` | Printed successfully |
56| `0` | Printed successfully |
57| `1` | Error (missing parameters, parse error, permission denied, etc.) |
57| `1` | Error (missing parameters, parse error, permission denied, etc.) |
58
58
59## Help
59## Help
60
60
61```bash
61```bash
62posprint print --help
62posprint print --help
63posprint --help
63posprint --help
64```
64```
65
65
66Launch the graphical designer by running `posprint` with **no** subcommand.
66Launch the graphical designer by running `posprint` with **no** subcommand.
docs/HELP-CLI-WINDOWS.md +56 −56
@@ -1,56 +1,56 @@
1 # Command-line printing (Windows)
2
3 Print a `.pos` template without opening the GUI.
4
5 ## Syntax
6
7 ```powershell
8 posprint print <file.pos> --printer <PORT> --set Name=Value [--set Other=Value ...]
9 ```
10
11 Short form:
12
13 ```powershell
14 posprint print receipt.pos -p COM3 --set StoreName="My Shop" --set DocumentNumber=1001
15 ```
16
17 ## Rules
18
19 - **`--printer` / `-p`** (required): USB-serial port name, e.g. `COM3`, `COM4`.
20 - **`--set NAME=VALUE`** (required for every parameter): one flag per `${Name}` in the template.
21 - If any `${Name}` is missing or empty, the command **fails** and lists missing parameters.
22 - The GUI is not started when using the `print` subcommand.
23
24 ## Examples
25
26 List required parameters by opening the template in the designer, or inspect the `${...}` tokens in the file body.
27
28 ```powershell
29 posprint print C:\receipts\sale.pos -p COM3 `
30 --set StoreName="Corner Cafe" `
31 --set DocumentNumber=42 `
32 --set Date=2026-07-15 `
33 --set GrandTotal=19.99
34 ```
35
36 ## Printer port
37
38 - Open **Device Manager → Ports (COM & LPT)** to find the printer COM port.
39 - Install the USB-serial driver if the device is not listed.
40 - Close other programs using the same COM port before printing.
41
42 ## Exit codes
43
44 | Code | Meaning |
45 |------|---------|
46 | `0` | Printed successfully |
47 | `1` | Error (missing parameters, parse error, port error, etc.) |
48
49 ## Help
50
51 ```powershell
52 posprint print --help
53 posprint --help
54 ```
55
56 Launch the graphical designer by running `posprint` with **no** subcommand.
1 # Command-line printing (Windows)
2
3 Print a `.pos` template without opening the GUI.
4
5 ## Syntax
6
7 ```powershell
8 posprint print <file.pos> --printer <PORT> --set Name=Value [--set Other=Value ...]
9 ```
10
11 Short form:
12
13 ```powershell
14 posprint print receipt.pos -p COM3 --set StoreName="My Shop" --set DocumentNumber=1001
15 ```
16
17 ## Rules
18
19 - **`--printer` / `-p`** (required): USB-serial port name, e.g. `COM3`, `COM4`.
20 - **`--set NAME=VALUE`** (required for every parameter): one flag per `${Name}` in the template.
21 - If any `${Name}` is missing or empty, the command **fails** and lists missing parameters.
22 - The GUI is not started when using the `print` subcommand.
23
24 ## Examples
25
26 List required parameters by opening the template in the designer, or inspect the `${...}` tokens in the file body.
27
28 ```powershell
29 posprint print C:\receipts\sale.pos -p COM3 `
30 --set StoreName="Corner Cafe" `
31 --set DocumentNumber=42 `
32 --set Date=2026-07-15 `
33 --set GrandTotal=19.99
34 ```
35
36 ## Printer port
37
38 - Open **Device Manager → Ports (COM & LPT)** to find the printer COM port.
39 - Install the USB-serial driver if the device is not listed.
40 - Close other programs using the same COM port before printing.
41
42 ## Exit codes
43
44 | Code | Meaning |
45 |------|---------|
46 | `0` | Printed successfully |
47 | `1` | Error (missing parameters, parse error, port error, etc.) |
48
49 ## Help
50
51 ```powershell
52 posprint print --help
53 posprint --help
54 ```
55
56 Launch the graphical designer by running `posprint` with **no** subcommand.
@@ -1,56 +1,56 @@
1# Command-line printing (Windows)
1# Command-line printing (Windows)
2
2
3Print a `.pos` template without opening the GUI.
3Print a `.pos` template without opening the GUI.
4
4
5## Syntax
5## Syntax
6
6
7```powershell
7```powershell
8posprint print <file.pos> --printer <PORT> --set Name=Value [--set Other=Value ...]
8posprint print <file.pos> --printer <PORT> --set Name=Value [--set Other=Value ...]
9```
9```
10
10
11Short form:
11Short form:
12
12
13```powershell
13```powershell
14posprint print receipt.pos -p COM3 --set StoreName="My Shop" --set DocumentNumber=1001
14posprint print receipt.pos -p COM3 --set StoreName="My Shop" --set DocumentNumber=1001
15```
15```
16
16
17## Rules
17## Rules
18
18
19- **`--printer` / `-p`** (required): USB-serial port name, e.g. `COM3`, `COM4`.
19- **`--printer` / `-p`** (required): USB-serial port name, e.g. `COM3`, `COM4`.
20- **`--set NAME=VALUE`** (required for every parameter): one flag per `${Name}` in the template.
20- **`--set NAME=VALUE`** (required for every parameter): one flag per `${Name}` in the template.
21- If any `${Name}` is missing or empty, the command **fails** and lists missing parameters.
21- If any `${Name}` is missing or empty, the command **fails** and lists missing parameters.
22- The GUI is not started when using the `print` subcommand.
22- The GUI is not started when using the `print` subcommand.
23
23
24## Examples
24## Examples
25
25
26List required parameters by opening the template in the designer, or inspect the `${...}` tokens in the file body.
26List required parameters by opening the template in the designer, or inspect the `${...}` tokens in the file body.
27
27
28```powershell
28```powershell
29posprint print C:\receipts\sale.pos -p COM3 `
29posprint print C:\receipts\sale.pos -p COM3 `
30 --set StoreName="Corner Cafe" `
30 --set StoreName="Corner Cafe" `
31 --set DocumentNumber=42 `
31 --set DocumentNumber=42 `
32 --set Date=2026-07-15 `
32 --set Date=2026-07-15 `
33 --set GrandTotal=19.99
33 --set GrandTotal=19.99
34```
34```
35
35
36## Printer port
36## Printer port
37
37
38- Open **Device Manager → Ports (COM & LPT)** to find the printer COM port.
38- Open **Device Manager → Ports (COM & LPT)** to find the printer COM port.
39- Install the USB-serial driver if the device is not listed.
39- Install the USB-serial driver if the device is not listed.
40- Close other programs using the same COM port before printing.
40- Close other programs using the same COM port before printing.
41
41
42## Exit codes
42## Exit codes
43
43
44| Code | Meaning |
44| Code | Meaning |
45|------|---------|
45|------|---------|
46| `0` | Printed successfully |
46| `0` | Printed successfully |
47| `1` | Error (missing parameters, parse error, port error, etc.) |
47| `1` | Error (missing parameters, parse error, port error, etc.) |
48
48
49## Help
49## Help
50
50
51```powershell
51```powershell
52posprint print --help
52posprint print --help
53posprint --help
53posprint --help
54```
54```
55
55
56Launch the graphical designer by running `posprint` with **no** subcommand.
56Launch the graphical designer by running `posprint` with **no** subcommand.
docs/HELP.md +199 −199
@@ -1,199 +1,199 @@
1 # posprint Help
2
3 Built-in reference for the template editor and POS markup language.
4
5 ---
6
7 ## Application tabs
8
9 | Tab | Purpose |
10 |-----|---------|
11 | **Editor** | Write and edit template source |
12 | **Preview** | Live preview of rendered output |
13 | **Help** | This documentation |
14
15 ## Toolbar actions
16
17 | Action | Description |
18 |--------|-------------|
19 | **New** | Empty template with defaults |
20 | **Open** | Load a `.pos` file |
21 | **Save / Save As** | Write JSON `.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 |
24
25 ## Editor assistance
26
27 - Type `@` at the start of a line to see **directive autocomplete** (`feed`, `cut`, `image`, `barcode`, `qr`).
28 - Use **Insert → Barcode / QR code** to pick native or raster type before inserting a snippet.
29
30 ## Page settings
31
32 | Setting | Description |
33 |---------|-------------|
34 | **Page width (mm)** | Paper width, typically `58` or `80` |
35 | **Preview mode** | `Auto-scale` fits preview to panel; `Fixed` uses exact mm width |
36 | **Code page** | Character encoding sent to printer (default `CP437`) |
37 | **Cut after print** | Append paper feed + cut if template has no `@cut` |
38
39 ---
40
41 ## Template language
42
43 A template is plain text: paragraphs, headings, directives, and inline markup.
44
45 ### Paragraphs
46
47 Consecutive non-empty lines form one paragraph.
48
49 ### Headings
50
51 ```markdown
52 # Large heading
53 ## Bold heading
54 ```
55
56 ### Alignment
57
58 `:left:`, `:center:`, or `:right:` before a paragraph.
59
60 ### Inline markup
61
62 | Syntax | Effect |
63 |--------|--------|
64 | `**text**` | Bold |
65 | `*text*` | Italic |
66 | `` `text` `` | Monospace |
67 | `${Name}` | Parameter (filled at print time) |
68
69 ### Horizontal rule
70
71 ```markdown
72 ---
73 ```
74
75 ### Comments
76
77 ```markdown
78 <!-- not printed -->
79 ```
80
81 ---
82
83 ## Directives
84
85 Directives start with `@` at the beginning of a line.
86
87 ### Paper feed / cut
88
89 ```markdown
90 @feed 3
91 @cut
92 ```
93
94 ### Image
95
96 ```markdown
97 @image logo.png
98 @image ${LogoPath} width=50% align=center
99 ```
100
101 ### Barcode
102
103 **Native** (printer draws barcode via ESC/POS):
104
105 ```markdown
106 @barcode CODE128 ${OrderId}
107 @barcode UPC-A 012345678905
108 @barcode ITF 12345678 height=80
109 ```
110
111 **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.
112
113 ```markdown
114 @barcode RASTER CODE128 ${OrderId}
115 @barcode RASTER CODE93 ABC-1234
116 ```
117
118 | Native symbology | Notes |
119 |----------------|-------|
120 | `CODE128` | Alphanumeric |
121 | `EAN13`, `EAN8` | Numeric |
122 | `CODE39` | Alphanumeric |
123 | `UPC-A`, `UPC-E` | Numeric |
124 | `ITF` | Interleaved 2 of 5; even digit count |
125 | `CODABAR` | Numeric + A-D start/stop |
126
127 | Raster-only symbology | Use `RASTER` prefix |
128 |-----------------------|---------------------|
129 | `CODE93`, `CODE11` | No native ESC/POS in firmware |
130
131 | Attribute | Description |
132 |-----------|-------------|
133 | `height` | Height in dots (default `64`; raster PNG height) |
134 | `align` | `left`, `center`, `right` |
135 | `show_text` | Native only: human-readable text under barcode |
136
137 ### QR code
138
139 **Native** (ESC/POS QR, model 2):
140
141 ```markdown
142 @qr https://example.com/${Id}
143 @qr ${Url} size=6 ecc=H align=center
144 ```
145
146 **Raster** (bitmap; supports QR versions 1–40):
147
148 ```markdown
149 @qr RASTER https://example.com/${Id}
150 @qr RASTER ${Url} version=5 scale=4 ecc=M
151 ```
152
153 | Attribute | Native | Raster |
154 |-----------|--------|--------|
155 | `size` | Module dot size 1–16 | — |
156 | `scale` | — | Pixels per module (default `4`) |
157 | `version` | — | QR version 1–40 (optional; auto if omitted) |
158 | `ecc` | `L`, `M`, `Q`, `H` | Same |
159 | `align` | `left`, `center`, `right` | Same |
160
161 ---
162
163 ## Parameters
164
165 `${ParameterName}` in text, barcode data, QR data, or image paths.
166
167 - Same name → **one input** at print time (GUI or CLI).
168 - CLI requires **every** parameter via `--set Name=Value`.
169
170 ---
171
172 ## Example receipt
173
174 ```markdown
175 # ${StoreName}
176 :center:
177
178 Receipt: ${DocumentNumber}
179
180 @barcode CODE128 ${DocumentNumber}
181 @qr RASTER https://shop.example.com/r/${DocumentNumber} scale=4
182
183 @feed 4
184 @cut
185 ```
186
187 ---
188
189 ## GUI printing (USB)
190
191 1. **Print** → enter parameters → choose serial port → **Print**.
192
193 **Linux:** `dialout` group. **Windows:** printer appears as `COMx`.
194
195 ---
196
197 ## `.pos` file format
198
199 JSON with `version`, `metadata`, and `body` (template source).
1 # posprint Help
2
3 Built-in reference for the template editor and POS markup language.
4
5 ---
6
7 ## Application tabs
8
9 | Tab | Purpose |
10 |-----|---------|
11 | **Editor** | Write and edit template source |
12 | **Preview** | Live preview of rendered output |
13 | **Help** | This documentation |
14
15 ## Toolbar actions
16
17 | Action | Description |
18 |--------|-------------|
19 | **New** | Empty template with defaults |
20 | **Open** | Load a `.pos` file |
21 | **Save / Save As** | Write JSON `.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 |
24
25 ## Editor assistance
26
27 - Type `@` at the start of a line to see **directive autocomplete** (`feed`, `cut`, `image`, `barcode`, `qr`).
28 - Use **Insert → Barcode / QR code** to pick native or raster type before inserting a snippet.
29
30 ## Page settings
31
32 | Setting | Description |
33 |---------|-------------|
34 | **Page width (mm)** | Paper width, typically `58` or `80` |
35 | **Preview mode** | `Auto-scale` fits preview to panel; `Fixed` uses exact mm width |
36 | **Code page** | Character encoding sent to printer (default `CP437`) |
37 | **Cut after print** | Append paper feed + cut if template has no `@cut` |
38
39 ---
40
41 ## Template language
42
43 A template is plain text: paragraphs, headings, directives, and inline markup.
44
45 ### Paragraphs
46
47 Consecutive non-empty lines form one paragraph.
48
49 ### Headings
50
51 ```markdown
52 # Large heading
53 ## Bold heading
54 ```
55
56 ### Alignment
57
58 `:left:`, `:center:`, or `:right:` before a paragraph.
59
60 ### Inline markup
61
62 | Syntax | Effect |
63 |--------|--------|
64 | `**text**` | Bold |
65 | `*text*` | Italic |
66 | `` `text` `` | Monospace |
67 | `${Name}` | Parameter (filled at print time) |
68
69 ### Horizontal rule
70
71 ```markdown
72 ---
73 ```
74
75 ### Comments
76
77 ```markdown
78 <!-- not printed -->
79 ```
80
81 ---
82
83 ## Directives
84
85 Directives start with `@` at the beginning of a line.
86
87 ### Paper feed / cut
88
89 ```markdown
90 @feed 3
91 @cut
92 ```
93
94 ### Image
95
96 ```markdown
97 @image logo.png
98 @image ${LogoPath} width=50% align=center
99 ```
100
101 ### Barcode
102
103 **Native** (printer draws barcode via ESC/POS):
104
105 ```markdown
106 @barcode CODE128 ${OrderId}
107 @barcode UPC-A 012345678905
108 @barcode ITF 12345678 height=80
109 ```
110
111 **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.
112
113 ```markdown
114 @barcode RASTER CODE128 ${OrderId}
115 @barcode RASTER CODE93 ABC-1234
116 ```
117
118 | Native symbology | Notes |
119 |----------------|-------|
120 | `CODE128` | Alphanumeric |
121 | `EAN13`, `EAN8` | Numeric |
122 | `CODE39` | Alphanumeric |
123 | `UPC-A`, `UPC-E` | Numeric |
124 | `ITF` | Interleaved 2 of 5; even digit count |
125 | `CODABAR` | Numeric + A-D start/stop |
126
127 | Raster-only symbology | Use `RASTER` prefix |
128 |-----------------------|---------------------|
129 | `CODE93`, `CODE11` | No native ESC/POS in firmware |
130
131 | Attribute | Description |
132 |-----------|-------------|
133 | `height` | Height in dots (default `64`; raster PNG height) |
134 | `align` | `left`, `center`, `right` |
135 | `show_text` | Native only: human-readable text under barcode |
136
137 ### QR code
138
139 **Native** (ESC/POS QR, model 2):
140
141 ```markdown
142 @qr https://example.com/${Id}
143 @qr ${Url} size=6 ecc=H align=center
144 ```
145
146 **Raster** (bitmap; supports QR versions 1–40):
147
148 ```markdown
149 @qr RASTER https://example.com/${Id}
150 @qr RASTER ${Url} version=5 scale=4 ecc=M
151 ```
152
153 | Attribute | Native | Raster |
154 |-----------|--------|--------|
155 | `size` | Module dot size 1–16 | — |
156 | `scale` | — | Pixels per module (default `4`) |
157 | `version` | — | QR version 1–40 (optional; auto if omitted) |
158 | `ecc` | `L`, `M`, `Q`, `H` | Same |
159 | `align` | `left`, `center`, `right` | Same |
160
161 ---
162
163 ## Parameters
164
165 `${ParameterName}` in text, barcode data, QR data, or image paths.
166
167 - Same name → **one input** at print time (GUI or CLI).
168 - CLI requires **every** parameter via `--set Name=Value`.
169
170 ---
171
172 ## Example receipt
173
174 ```markdown
175 # ${StoreName}
176 :center:
177
178 Receipt: ${DocumentNumber}
179
180 @barcode CODE128 ${DocumentNumber}
181 @qr RASTER https://shop.example.com/r/${DocumentNumber} scale=4
182
183 @feed 4
184 @cut
185 ```
186
187 ---
188
189 ## GUI printing (USB)
190
191 1. **Print** → enter parameters → choose serial port → **Print**.
192
193 **Linux:** `dialout` group. **Windows:** printer appears as `COMx`.
194
195 ---
196
197 ## `.pos` file format
198
199 JSON with `version`, `metadata`, and `body` (template source).
@@ -1,199 +1,199 @@
1# posprint Help
1# posprint Help
2
2
3Built-in reference for the template editor and POS markup language.
3Built-in reference for the template editor and POS markup language.
4
4
5---
5---
6
6
7## Application tabs
7## Application tabs
8
8
9| Tab | Purpose |
9| Tab | Purpose |
10|-----|---------|
10|-----|---------|
11| **Editor** | Write and edit template source |
11| **Editor** | Write and edit template source |
12| **Preview** | Live preview of rendered output |
12| **Preview** | Live preview of rendered output |
13| **Help** | This documentation |
13| **Help** | This documentation |
14
14
15## Toolbar actions
15## Toolbar actions
16
16
17| Action | Description |
17| Action | Description |
18|--------|-------------|
18|--------|-------------|
19| **New** | Empty template with defaults |
19| **New** | Empty template with defaults |
20| **Open** | Load a `.pos` file |
20| **Open** | Load a `.pos` file |
21| **Save / Save As** | Write JSON `.pos` file (metadata + body) |
21| **Save / Save As** | Write JSON `.pos` file (metadata + body) |
22| **Insert** | Menu to insert images, barcodes, QR codes, `@feed`, `@cut` |
22| **Insert** | Menu to insert images, barcodes, QR codes, `@feed`, `@cut` |
23| **Print** | Substitute parameters, pick USB printer, send ESC/POS bytes |
23| **Print** | Substitute parameters, pick USB printer, send ESC/POS bytes |
24
24
25## Editor assistance
25## Editor assistance
26
26
27- Type `@` at the start of a line to see **directive autocomplete** (`feed`, `cut`, `image`, `barcode`, `qr`).
27- Type `@` at the start of a line to see **directive autocomplete** (`feed`, `cut`, `image`, `barcode`, `qr`).
28- Use **Insert → Barcode / QR code** to pick native or raster type before inserting a snippet.
28- Use **Insert → Barcode / QR code** to pick native or raster type before inserting a snippet.
29
29
30## Page settings
30## Page settings
31
31
32| Setting | Description |
32| Setting | Description |
33|---------|-------------|
33|---------|-------------|
34| **Page width (mm)** | Paper width, typically `58` or `80` |
34| **Page width (mm)** | Paper width, typically `58` or `80` |
35| **Preview mode** | `Auto-scale` fits preview to panel; `Fixed` uses exact mm width |
35| **Preview mode** | `Auto-scale` fits preview to panel; `Fixed` uses exact mm width |
36| **Code page** | Character encoding sent to printer (default `CP437`) |
36| **Code page** | Character encoding sent to printer (default `CP437`) |
37| **Cut after print** | Append paper feed + cut if template has no `@cut` |
37| **Cut after print** | Append paper feed + cut if template has no `@cut` |
38
38
39---
39---
40
40
41## Template language
41## Template language
42
42
43A template is plain text: paragraphs, headings, directives, and inline markup.
43A template is plain text: paragraphs, headings, directives, and inline markup.
44
44
45### Paragraphs
45### Paragraphs
46
46
47Consecutive non-empty lines form one paragraph.
47Consecutive non-empty lines form one paragraph.
48
48
49### Headings
49### Headings
50
50
51```markdown
51```markdown
52# Large heading
52# Large heading
53## Bold heading
53## Bold heading
54```
54```
55
55
56### Alignment
56### Alignment
57
57
58`:left:`, `:center:`, or `:right:` before a paragraph.
58`:left:`, `:center:`, or `:right:` before a paragraph.
59
59
60### Inline markup
60### Inline markup
61
61
62| Syntax | Effect |
62| Syntax | Effect |
63|--------|--------|
63|--------|--------|
64| `**text**` | Bold |
64| `**text**` | Bold |
65| `*text*` | Italic |
65| `*text*` | Italic |
66| `` `text` `` | Monospace |
66| `` `text` `` | Monospace |
67| `${Name}` | Parameter (filled at print time) |
67| `${Name}` | Parameter (filled at print time) |
68
68
69### Horizontal rule
69### Horizontal rule
70
70
71```markdown
71```markdown
72---
72---
73```
73```
74
74
75### Comments
75### Comments
76
76
77```markdown
77```markdown
78<!-- not printed -->
78<!-- not printed -->
79```
79```
80
80
81---
81---
82
82
83## Directives
83## Directives
84
84
85Directives start with `@` at the beginning of a line.
85Directives start with `@` at the beginning of a line.
86
86
87### Paper feed / cut
87### Paper feed / cut
88
88
89```markdown
89```markdown
90@feed 3
90@feed 3
91@cut
91@cut
92```
92```
93
93
94### Image
94### Image
95
95
96```markdown
96```markdown
97@image logo.png
97@image logo.png
98@image ${LogoPath} width=50% align=center
98@image ${LogoPath} width=50% align=center
99```
99```
100
100
101### Barcode
101### Barcode
102
102
103**Native** (printer draws barcode via ESC/POS):
103**Native** (printer draws barcode via ESC/POS):
104
104
105```markdown
105```markdown
106@barcode CODE128 ${OrderId}
106@barcode CODE128 ${OrderId}
107@barcode UPC-A 012345678905
107@barcode UPC-A 012345678905
108@barcode ITF 12345678 height=80
108@barcode ITF 12345678 height=80
109```
109```
110
110
111**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.
111**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.
112
112
113```markdown
113```markdown
114@barcode RASTER CODE128 ${OrderId}
114@barcode RASTER CODE128 ${OrderId}
115@barcode RASTER CODE93 ABC-1234
115@barcode RASTER CODE93 ABC-1234
116```
116```
117
117
118| Native symbology | Notes |
118| Native symbology | Notes |
119|----------------|-------|
119|----------------|-------|
120| `CODE128` | Alphanumeric |
120| `CODE128` | Alphanumeric |
121| `EAN13`, `EAN8` | Numeric |
121| `EAN13`, `EAN8` | Numeric |
122| `CODE39` | Alphanumeric |
122| `CODE39` | Alphanumeric |
123| `UPC-A`, `UPC-E` | Numeric |
123| `UPC-A`, `UPC-E` | Numeric |
124| `ITF` | Interleaved 2 of 5; even digit count |
124| `ITF` | Interleaved 2 of 5; even digit count |
125| `CODABAR` | Numeric + A-D start/stop |
125| `CODABAR` | Numeric + A-D start/stop |
126
126
127| Raster-only symbology | Use `RASTER` prefix |
127| Raster-only symbology | Use `RASTER` prefix |
128|-----------------------|---------------------|
128|-----------------------|---------------------|
129| `CODE93`, `CODE11` | No native ESC/POS in firmware |
129| `CODE93`, `CODE11` | No native ESC/POS in firmware |
130
130
131| Attribute | Description |
131| Attribute | Description |
132|-----------|-------------|
132|-----------|-------------|
133| `height` | Height in dots (default `64`; raster PNG height) |
133| `height` | Height in dots (default `64`; raster PNG height) |
134| `align` | `left`, `center`, `right` |
134| `align` | `left`, `center`, `right` |
135| `show_text` | Native only: human-readable text under barcode |
135| `show_text` | Native only: human-readable text under barcode |
136
136
137### QR code
137### QR code
138
138
139**Native** (ESC/POS QR, model 2):
139**Native** (ESC/POS QR, model 2):
140
140
141```markdown
141```markdown
142@qr https://example.com/${Id}
142@qr https://example.com/${Id}
143@qr ${Url} size=6 ecc=H align=center
143@qr ${Url} size=6 ecc=H align=center
144```
144```
145
145
146**Raster** (bitmap; supports QR versions 1–40):
146**Raster** (bitmap; supports QR versions 1–40):
147
147
148```markdown
148```markdown
149@qr RASTER https://example.com/${Id}
149@qr RASTER https://example.com/${Id}
150@qr RASTER ${Url} version=5 scale=4 ecc=M
150@qr RASTER ${Url} version=5 scale=4 ecc=M
151```
151```
152
152
153| Attribute | Native | Raster |
153| Attribute | Native | Raster |
154|-----------|--------|--------|
154|-----------|--------|--------|
155| `size` | Module dot size 1–16 | — |
155| `size` | Module dot size 1–16 | — |
156| `scale` | — | Pixels per module (default `4`) |
156| `scale` | — | Pixels per module (default `4`) |
157| `version` | — | QR version 1–40 (optional; auto if omitted) |
157| `version` | — | QR version 1–40 (optional; auto if omitted) |
158| `ecc` | `L`, `M`, `Q`, `H` | Same |
158| `ecc` | `L`, `M`, `Q`, `H` | Same |
159| `align` | `left`, `center`, `right` | Same |
159| `align` | `left`, `center`, `right` | Same |
160
160
161---
161---
162
162
163## Parameters
163## Parameters
164
164
165`${ParameterName}` in text, barcode data, QR data, or image paths.
165`${ParameterName}` in text, barcode data, QR data, or image paths.
166
166
167- Same name → **one input** at print time (GUI or CLI).
167- Same name → **one input** at print time (GUI or CLI).
168- CLI requires **every** parameter via `--set Name=Value`.
168- CLI requires **every** parameter via `--set Name=Value`.
169
169
170---
170---
171
171
172## Example receipt
172## Example receipt
173
173
174```markdown
174```markdown
175# ${StoreName}
175# ${StoreName}
176:center:
176:center:
177
177
178Receipt: ${DocumentNumber}
178Receipt: ${DocumentNumber}
179
179
180@barcode CODE128 ${DocumentNumber}
180@barcode CODE128 ${DocumentNumber}
181@qr RASTER https://shop.example.com/r/${DocumentNumber} scale=4
181@qr RASTER https://shop.example.com/r/${DocumentNumber} scale=4
182
182
183@feed 4
183@feed 4
184@cut
184@cut
185```
185```
186
186
187---
187---
188
188
189## GUI printing (USB)
189## GUI printing (USB)
190
190
1911. **Print** → enter parameters → choose serial port → **Print**.
1911. **Print** → enter parameters → choose serial port → **Print**.
192
192
193**Linux:** `dialout` group. **Windows:** printer appears as `COMx`.
193**Linux:** `dialout` group. **Windows:** printer appears as `COMx`.
194
194
195---
195---
196
196
197## `.pos` file format
197## `.pos` file format
198
198
199JSON with `version`, `metadata`, and `body` (template source).
199JSON with `version`, `metadata`, and `body` (template source).
docs/LANGUAGE-CHOICE.md +83 −83
@@ -1,83 +1,83 @@
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 # 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 +1,83 @@
1# Language and platform choice
1# Language and platform choice
2
2
3## Decision (implemented)
3## Decision (implemented)
4
4
5| Decision | Choice |
5| Decision | Choice |
6|----------|--------|
6|----------|--------|
7| Language | **Rust** (single codebase) |
7| Language | **Rust** (single codebase) |
8| UI | **egui** via **eframe** |
8| UI | **egui** via **eframe** |
9| Print protocol | **ESC/POS** (in-tree encoder) |
9| Print protocol | **ESC/POS** (in-tree encoder) |
10| MVP transport | **USB-serial** via `serialport` |
10| MVP transport | **USB-serial** via `serialport` |
11| Packaging | GitLab CI → Linux `.deb`, Windows `.exe` |
11| Packaging | GitLab CI → Linux `.deb`, Windows `.exe` |
12
12
13**Rationale:** One language, small dependency surface, direct control over ESC/POS bytes, native cross-platform UI without a WebView.
13**Rationale:** One language, small dependency surface, direct control over ESC/POS bytes, native cross-platform UI without a WebView.
14
14
15---
15---
16
16
17## Requirements
17## Requirements
18
18
19| Requirement | How it is met |
19| Requirement | How it is met |
20|-------------|---------------|
20|-------------|---------------|
21| Windows + Linux | Rust + egui + GitLab CI |
21| Windows + Linux | Rust + egui + GitLab CI |
22| Raw USB-serial print (no spooler) | `serialport` crate, 9600 baud |
22| Raw USB-serial print (no spooler) | `serialport` crate, 9600 baud |
23| ESC/POS generation | `src/escpos.rs` (no external ESC/POS crate) |
23| ESC/POS generation | `src/escpos.rs` (no external ESC/POS crate) |
24| Live preview | `src/preview.rs` + egui canvas in `app.rs` |
24| Live preview | `src/preview.rs` + egui canvas in `app.rs` |
25| Small distributable | No Chromium/Node; release build uses LTO + strip |
25| Small distributable | No Chromium/Node; release build uses LTO + strip |
26| Unit tests | Every module has `#[cfg(test)]` tests |
26| Unit tests | Every module has `#[cfg(test)]` tests |
27
27
28---
28---
29
29
30## Dependencies in use
30## Dependencies in use
31
31
32| Crate | Role | Why not hand-roll? |
32| Crate | Role | Why not hand-roll? |
33|-------|------|-------------------|
33|-------|------|-------------------|
34| `eframe` / `egui` | UI framework | Building a GUI toolkit is out of scope |
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 |
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 |
36| `serialport` | Cross-platform COM/tty access | OS-specific serial APIs differ |
37| `image` | PNG/JPEG/GIF/BMP decode | Many formats and decoders |
37| `image` | PNG/JPEG/GIF/BMP decode | Many formats and decoders |
38| `rfd` | Native file dialogs | OS-native UX expected |
38| `rfd` | Native file dialogs | OS-native UX expected |
39
39
40**Not used (by design):** `escpos`, `nusb`, `rusb`, `tauri`, TypeScript frontend.
40**Not used (by design):** `escpos`, `nusb`, `rusb`, `tauri`, TypeScript frontend.
41
41
42---
42---
43
43
44## Candidates considered (historical)
44## Candidates considered (historical)
45
45
46| Option | Verdict |
46| Option | Verdict |
47|--------|---------|
47|--------|---------|
48| Rust + Tauri 2 + TypeScript | Rejected — two languages, WebView dependency |
48| Rust + Tauri 2 + TypeScript | Rejected — two languages, WebView dependency |
49| Rust + egui | **Selected** |
49| Rust + egui | **Selected** |
50| C# + Avalonia | Viable but weaker serial/ESC/POS ecosystem |
50| C# + Avalonia | Viable but weaker serial/ESC/POS ecosystem |
51| Go + Fyne | Weaker hardware I/O ecosystem |
51| Go + Fyne | Weaker hardware I/O ecosystem |
52| Python + PyQt | Poor packaging for desktop release |
52| Python + PyQt | Poor packaging for desktop release |
53| Electron | Bundle size too large |
53| Electron | Bundle size too large |
54| C++ + Qt | Slower iteration for a small app |
54| C++ + Qt | Slower iteration for a small app |
55
55
56---
56---
57
57
58## Platform notes
58## Platform notes
59
59
60### Windows
60### Windows
61
61
62- Printers appear as `COMx` after USB-serial driver install.
62- Printers appear as `COMx` after USB-serial driver install.
63- Release: `posprint.exe` from `cargo build --release`.
63- Release: `posprint.exe` from `cargo build --release`.
64- CI requires a GitLab runner tagged `windows` + `shell`.
64- CI requires a GitLab runner tagged `windows` + `shell`.
65
65
66### Linux
66### Linux
67
67
68- Devices: `/dev/ttyUSB*`, `/dev/ttyACM*`, etc.
68- Devices: `/dev/ttyUSB*`, `/dev/ttyACM*`, etc.
69- User must be in the **`dialout`** group.
69- User must be in the **`dialout`** group.
70- Release: `.deb` via `cargo deb`; install with `sudo dpkg -i …`.
70- Release: `.deb` via `cargo deb`; install with `sudo dpkg -i …`.
71- CI uses `rust:bookworm` image with X11 dev libs for egui.
71- CI uses `rust:bookworm` image with X11 dev libs for egui.
72
72
73---
73---
74
74
75## Deferred
75## Deferred
76
76
77| Item | Notes |
77| Item | Notes |
78|------|-------|
78|------|-------|
79| USB printer class (bulk) | Would need `nusb` or Windows `usbprint` path |
79| USB printer class (bulk) | Would need `nusb` or Windows `usbprint` path |
80| Bluetooth SPP | Paired devices as serial ports; add when requested |
80| Bluetooth SPP | Paired devices as serial ports; add when requested |
81| macOS | Same stack should work; not in CI yet |
81| macOS | Same stack should work; not in CI yet |
82
82
83This document should be updated when transport or UI choices change.
83This document should be updated when transport or UI choices change.
docs/PRINTING.md +197 −197
@@ -1,197 +1,197 @@
1 # Printing subsystem
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.
6
7 ---
8
9 ## Goals
10
11 1. Discover serial ports (USB-serial adapters and CDC printers)
12 2. Let the user pick a port in the print dialog
13 3. Generate ESC/POS bytes from the AST (after parameter substitution)
14 4. Write bytes at **9600 baud** (fixed for now)
15
16 ---
17
18 ## Protocol: ESC/POS
19
20 Target **Epson ESC/POS** compatible printers (58 mm / 80 mm thermal).
21
22 ### Implemented commands
23
24 | Feature | ESC/POS | Source |
25 |---------|---------|--------|
26 | Initialize | ESC @ | `escpos.rs` |
27 | Code page | ESC t 0 (CP437) | Always CP437 today; metadata field reserved |
28 | Bold | ESC E | Headings level 2, `**text**` flattened at encode |
29 | Double size | GS ! | Heading level 1 |
30 | Alignment | ESC a | Paragraphs, images, barcodes, QR |
31 | Line feed | LF, ESC d | Text lines, `@feed` |
32 | Partial cut | GS V 66 0 | `@cut`, auto-cut after print |
33 | Barcode | GS k | CODE128, EAN13, EAN8, CODE39 |
34 | QR Code | GS ( k | Model 2 |
35 | Raster image | GS v 0 | `@image` via `image` crate → threshold |
36
37 Encoder: `EscPosEncoder` in `src/escpos.rs` — **not** the `escpos` crates.io package.
38
39 ---
40
41 ## Transport (implemented)
42
43 ```
44 Print button
45 │
46 ▼
47 substitute_document()
48 │
49 ▼
50 EscPosEncoder::encode_document()
51 │
52 ▼
53 SerialTransport::open(port, 9600)
54 │
55 ▼
56 print_bytes() → write_all + flush
57 ```
58
59 ### `PrinterTransport` trait
60
61 ```rust
62 pub trait PrinterTransport {
63 fn write_all(&mut self, data: &[u8]) -> io::Result<()>;
64 fn flush(&mut self) -> io::Result<()>;
65 }
66 ```
67
68 | Type | Role |
69 |------|------|
70 | `SerialTransport` | Production — opens port via `serialport` |
71 | `MockTransport` | Tests — records bytes in `written` vec |
72
73 ### Discovery
74
75 `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).
76
77 ### `PrinterDevice`
78
79 | Field | Example |
80 |-------|---------|
81 | `id` | `serial:COM3` |
82 | `display_name` | `COM3 — USB 04b8:0e15` |
83 | `port_name` | `COM3` |
84
85 ---
86
87 ## Print dialog (UI)
88
89 ```
90 ┌─────────────────────────────────────────┐
91 │ Print │
92 ├─────────────────────────────────────────┤
93 │ Parameters (one field per unique name) │
94 │ DocumentNumber: [________] │
95 │ │
96 │ USB printer │
97 │ [ Refresh ] │
98 │ ○ COM3 — USB 04b8:0e15 │
99 │ ○ /dev/ttyUSB0 — Serial │
100 │ │
101 │ [ Cancel ] [ Print ] │
102 └─────────────────────────────────────────┘
103 ```
104
105 - Parameters pre-filled from `last_params` (session memory).
106 - Same parameter name → one input, applied everywhere.
107 - Errors shown inline (parse, open port, write, barcode validation).
108
109 ---
110
111 ## Print pipeline
112
113 ```
114 Document body (DSL)
115 │
116 ▼
117 parse() → Document
118 │
119 ▼
120 collect_parameter_names() → UI dialog
121 │
122 ▼
123 substitute_document()
124 │
125 ▼
126 EscPosEncoder (in-tree)
127 │
128 ▼
129 SerialTransport::write_all
130 ```
131
132 ### Error handling (current)
133
134 | Condition | Behaviour |
135 |-----------|-----------|
136 | Parse error | Block print; show in toolbar |
137 | Port open failure | `PrintError::Open` message in dialog |
138 | Write failure | `PrintError::Write` message in dialog |
139 | EAN13/EAN8 invalid length | `EscPosError::Barcode` before write |
140 | Linux permission denied | User must join `dialout` group (documented in Help) |
141
142 Status polling (paper out, cover open) is **not** implemented.
143
144 ---
145
146 ## Images
147
148 1. Resolve path relative to `.pos` file directory (or absolute path).
149 2. Decode with `image` crate.
150 3. Convert to luma8, resize to target width (%, dots, or full printable width).
151 4. Threshold to 1-bit raster.
152 5. Emit `GS v 0` raster (`1D 76 30 00`, width/height LE, bitmap) — same format as print-bridge.
153
154 Preview shows `[image: path]` only — no bitmap preview yet.
155
156 ---
157
158 ## Preview vs print width
159
160 | `preview_mode` | Preview | Print |
161 |----------------|---------|-------|
162 | `autoscale` | Scales to panel width | Full paper width from metadata |
163 | `fixed` | Scaled by mm ratio | Full paper width |
164
165 ---
166
167 ## Testing without hardware
168
169 | Method | Location |
170 |--------|----------|
171 | `MockTransport` | `print/mod.rs` tests |
172 | ESC/POS byte checks | `escpos.rs` tests |
173 | `cargo test` | 20 tests; no printer required |
174
175 ---
176
177 ## Planned (not implemented)
178
179 | Feature | Notes |
180 |---------|-------|
181 | USB printer class | `nusb` / Windows `usbprint` |
182 | Bluetooth SPP | Serial port after OS pairing |
183 | Baud autodetect | Try 9600, 19200, 115200 |
184 | Printer status read | DLE EOT |
185 | Network TCP 9100 | Future |
186 | Image size warning in UI | Future |
187
188 ---
189
190 ## Dependencies
191
192 ```toml
193 serialport = "4"
194 image = { features = ["png", "jpeg", "gif", "bmp"] }
195 ```
196
197 No `escpos`, `nusb`, or `rusb` crates.
1 # Printing subsystem
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.
6
7 ---
8
9 ## Goals
10
11 1. Discover serial ports (USB-serial adapters and CDC printers)
12 2. Let the user pick a port in the print dialog
13 3. Generate ESC/POS bytes from the AST (after parameter substitution)
14 4. Write bytes at **9600 baud** (fixed for now)
15
16 ---
17
18 ## Protocol: ESC/POS
19
20 Target **Epson ESC/POS** compatible printers (58 mm / 80 mm thermal).
21
22 ### Implemented commands
23
24 | Feature | ESC/POS | Source |
25 |---------|---------|--------|
26 | Initialize | ESC @ | `escpos.rs` |
27 | Code page | ESC t 0 (CP437) | Always CP437 today; metadata field reserved |
28 | Bold | ESC E | Headings level 2, `**text**` flattened at encode |
29 | Double size | GS ! | Heading level 1 |
30 | Alignment | ESC a | Paragraphs, images, barcodes, QR |
31 | Line feed | LF, ESC d | Text lines, `@feed` |
32 | Partial cut | GS V 66 0 | `@cut`, auto-cut after print |
33 | Barcode | GS k | CODE128, EAN13, EAN8, CODE39 |
34 | QR Code | GS ( k | Model 2 |
35 | Raster image | GS v 0 | `@image` via `image` crate → threshold |
36
37 Encoder: `EscPosEncoder` in `src/escpos.rs` — **not** the `escpos` crates.io package.
38
39 ---
40
41 ## Transport (implemented)
42
43 ```
44 Print button
45 │
46 ▼
47 substitute_document()
48 │
49 ▼
50 EscPosEncoder::encode_document()
51 │
52 ▼
53 SerialTransport::open(port, 9600)
54 │
55 ▼
56 print_bytes() → write_all + flush
57 ```
58
59 ### `PrinterTransport` trait
60
61 ```rust
62 pub trait PrinterTransport {
63 fn write_all(&mut self, data: &[u8]) -> io::Result<()>;
64 fn flush(&mut self) -> io::Result<()>;
65 }
66 ```
67
68 | Type | Role |
69 |------|------|
70 | `SerialTransport` | Production — opens port via `serialport` |
71 | `MockTransport` | Tests — records bytes in `written` vec |
72
73 ### Discovery
74
75 `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).
76
77 ### `PrinterDevice`
78
79 | Field | Example |
80 |-------|---------|
81 | `id` | `serial:COM3` |
82 | `display_name` | `COM3 — USB 04b8:0e15` |
83 | `port_name` | `COM3` |
84
85 ---
86
87 ## Print dialog (UI)
88
89 ```
90 ┌─────────────────────────────────────────┐
91 │ Print │
92 ├─────────────────────────────────────────┤
93 │ Parameters (one field per unique name) │
94 │ DocumentNumber: [________] │
95 │ │
96 │ USB printer │
97 │ [ Refresh ] │
98 │ ○ COM3 — USB 04b8:0e15 │
99 │ ○ /dev/ttyUSB0 — Serial │
100 │ │
101 │ [ Cancel ] [ Print ] │
102 └─────────────────────────────────────────┘
103 ```
104
105 - Parameters pre-filled from `last_params` (session memory).
106 - Same parameter name → one input, applied everywhere.
107 - Errors shown inline (parse, open port, write, barcode validation).
108
109 ---
110
111 ## Print pipeline
112
113 ```
114 Document body (DSL)
115 │
116 ▼
117 parse() → Document
118 │
119 ▼
120 collect_parameter_names() → UI dialog
121 │
122 ▼
123 substitute_document()
124 │
125 ▼
126 EscPosEncoder (in-tree)
127 │
128 ▼
129 SerialTransport::write_all
130 ```
131
132 ### Error handling (current)
133
134 | Condition | Behaviour |
135 |-----------|-----------|
136 | Parse error | Block print; show in toolbar |
137 | Port open failure | `PrintError::Open` message in dialog |
138 | Write failure | `PrintError::Write` message in dialog |
139 | EAN13/EAN8 invalid length | `EscPosError::Barcode` before write |
140 | Linux permission denied | User must join `dialout` group (documented in Help) |
141
142 Status polling (paper out, cover open) is **not** implemented.
143
144 ---
145
146 ## Images
147
148 1. Resolve path relative to `.pos` file directory (or absolute path).
149 2. Decode with `image` crate.
150 3. Convert to luma8, resize to target width (%, dots, or full printable width).
151 4. Threshold to 1-bit raster.
152 5. Emit `GS v 0` raster (`1D 76 30 00`, width/height LE, bitmap) — same format as print-bridge.
153
154 Preview shows `[image: path]` only — no bitmap preview yet.
155
156 ---
157
158 ## Preview vs print width
159
160 | `preview_mode` | Preview | Print |
161 |----------------|---------|-------|
162 | `autoscale` | Scales to panel width | Full paper width from metadata |
163 | `fixed` | Scaled by mm ratio | Full paper width |
164
165 ---
166
167 ## Testing without hardware
168
169 | Method | Location |
170 |--------|----------|
171 | `MockTransport` | `print/mod.rs` tests |
172 | ESC/POS byte checks | `escpos.rs` tests |
173 | `cargo test` | 20 tests; no printer required |
174
175 ---
176
177 ## Planned (not implemented)
178
179 | Feature | Notes |
180 |---------|-------|
181 | USB printer class | `nusb` / Windows `usbprint` |
182 | Bluetooth SPP | Serial port after OS pairing |
183 | Baud autodetect | Try 9600, 19200, 115200 |
184 | Printer status read | DLE EOT |
185 | Network TCP 9100 | Future |
186 | Image size warning in UI | Future |
187
188 ---
189
190 ## Dependencies
191
192 ```toml
193 serialport = "4"
194 image = { features = ["png", "jpeg", "gif", "bmp"] }
195 ```
196
197 No `escpos`, `nusb`, or `rusb` crates.
@@ -1,197 +1,197 @@
1# Printing subsystem
1# Printing subsystem
2
2
3Direct raw-byte printing to POS thermal printers over **USB-serial** — without the Windows print spooler or CUPS.
3Direct raw-byte printing to POS thermal printers over **USB-serial** — without the Windows print spooler or CUPS.
4
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.
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
6
7---
7---
8
8
9## Goals
9## Goals
10
10
111. Discover serial ports (USB-serial adapters and CDC printers)
111. Discover serial ports (USB-serial adapters and CDC printers)
122. Let the user pick a port in the print dialog
122. Let the user pick a port in the print dialog
133. Generate ESC/POS bytes from the AST (after parameter substitution)
133. Generate ESC/POS bytes from the AST (after parameter substitution)
144. Write bytes at **9600 baud** (fixed for now)
144. Write bytes at **9600 baud** (fixed for now)
15
15
16---
16---
17
17
18## Protocol: ESC/POS
18## Protocol: ESC/POS
19
19
20Target **Epson ESC/POS** compatible printers (58 mm / 80 mm thermal).
20Target **Epson ESC/POS** compatible printers (58 mm / 80 mm thermal).
21
21
22### Implemented commands
22### Implemented commands
23
23
24| Feature | ESC/POS | Source |
24| Feature | ESC/POS | Source |
25|---------|---------|--------|
25|---------|---------|--------|
26| Initialize | ESC @ | `escpos.rs` |
26| Initialize | ESC @ | `escpos.rs` |
27| Code page | ESC t 0 (CP437) | Always CP437 today; metadata field reserved |
27| Code page | ESC t 0 (CP437) | Always CP437 today; metadata field reserved |
28| Bold | ESC E | Headings level 2, `**text**` flattened at encode |
28| Bold | ESC E | Headings level 2, `**text**` flattened at encode |
29| Double size | GS ! | Heading level 1 |
29| Double size | GS ! | Heading level 1 |
30| Alignment | ESC a | Paragraphs, images, barcodes, QR |
30| Alignment | ESC a | Paragraphs, images, barcodes, QR |
31| Line feed | LF, ESC d | Text lines, `@feed` |
31| Line feed | LF, ESC d | Text lines, `@feed` |
32| Partial cut | GS V 66 0 | `@cut`, auto-cut after print |
32| Partial cut | GS V 66 0 | `@cut`, auto-cut after print |
33| Barcode | GS k | CODE128, EAN13, EAN8, CODE39 |
33| Barcode | GS k | CODE128, EAN13, EAN8, CODE39 |
34| QR Code | GS ( k | Model 2 |
34| QR Code | GS ( k | Model 2 |
35| Raster image | GS v 0 | `@image` via `image` crate → threshold |
35| Raster image | GS v 0 | `@image` via `image` crate → threshold |
36
36
37Encoder: `EscPosEncoder` in `src/escpos.rs` — **not** the `escpos` crates.io package.
37Encoder: `EscPosEncoder` in `src/escpos.rs` — **not** the `escpos` crates.io package.
38
38
39---
39---
40
40
41## Transport (implemented)
41## Transport (implemented)
42
42
43```
43```
44Print button
44Print button
45 │
45 │
46 ▼
46 ▼
47substitute_document()
47substitute_document()
48 │
48 │
49 ▼
49 ▼
50EscPosEncoder::encode_document()
50EscPosEncoder::encode_document()
51 │
51 │
52 ▼
52 ▼
53SerialTransport::open(port, 9600)
53SerialTransport::open(port, 9600)
54 │
54 │
55 ▼
55 ▼
56print_bytes() → write_all + flush
56print_bytes() → write_all + flush
57```
57```
58
58
59### `PrinterTransport` trait
59### `PrinterTransport` trait
60
60
61```rust
61```rust
62pub trait PrinterTransport {
62pub trait PrinterTransport {
63 fn write_all(&mut self, data: &[u8]) -> io::Result<()>;
63 fn write_all(&mut self, data: &[u8]) -> io::Result<()>;
64 fn flush(&mut self) -> io::Result<()>;
64 fn flush(&mut self) -> io::Result<()>;
65}
65}
66```
66```
67
67
68| Type | Role |
68| Type | Role |
69|------|------|
69|------|------|
70| `SerialTransport` | Production — opens port via `serialport` |
70| `SerialTransport` | Production — opens port via `serialport` |
71| `MockTransport` | Tests — records bytes in `written` vec |
71| `MockTransport` | Tests — records bytes in `written` vec |
72
72
73### Discovery
73### Discovery
74
74
75`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).
75`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).
76
76
77### `PrinterDevice`
77### `PrinterDevice`
78
78
79| Field | Example |
79| Field | Example |
80|-------|---------|
80|-------|---------|
81| `id` | `serial:COM3` |
81| `id` | `serial:COM3` |
82| `display_name` | `COM3 — USB 04b8:0e15` |
82| `display_name` | `COM3 — USB 04b8:0e15` |
83| `port_name` | `COM3` |
83| `port_name` | `COM3` |
84
84
85---
85---
86
86
87## Print dialog (UI)
87## Print dialog (UI)
88
88
89```
89```
90┌─────────────────────────────────────────┐
90┌─────────────────────────────────────────┐
91│ Print │
91│ Print │
92├─────────────────────────────────────────┤
92├─────────────────────────────────────────┤
93│ Parameters (one field per unique name) │
93│ Parameters (one field per unique name) │
94│ DocumentNumber: [________] │
94│ DocumentNumber: [________] │
95│ │
95│ │
96│ USB printer │
96│ USB printer │
97│ [ Refresh ] │
97│ [ Refresh ] │
98│ ○ COM3 — USB 04b8:0e15 │
98│ ○ COM3 — USB 04b8:0e15 │
99│ ○ /dev/ttyUSB0 — Serial │
99│ ○ /dev/ttyUSB0 — Serial │
100│ │
100│ │
101│ [ Cancel ] [ Print ] │
101│ [ Cancel ] [ Print ] │
102└─────────────────────────────────────────┘
102└─────────────────────────────────────────┘
103```
103```
104
104
105- Parameters pre-filled from `last_params` (session memory).
105- Parameters pre-filled from `last_params` (session memory).
106- Same parameter name → one input, applied everywhere.
106- Same parameter name → one input, applied everywhere.
107- Errors shown inline (parse, open port, write, barcode validation).
107- Errors shown inline (parse, open port, write, barcode validation).
108
108
109---
109---
110
110
111## Print pipeline
111## Print pipeline
112
112
113```
113```
114Document body (DSL)
114Document body (DSL)
115 │
115 │
116 ▼
116 ▼
117 parse() → Document
117 parse() → Document
118 │
118 │
119 ▼
119 ▼
120 collect_parameter_names() → UI dialog
120 collect_parameter_names() → UI dialog
121 │
121 │
122 ▼
122 ▼
123 substitute_document()
123 substitute_document()
124 │
124 │
125 ▼
125 ▼
126 EscPosEncoder (in-tree)
126 EscPosEncoder (in-tree)
127 │
127 │
128 ▼
128 ▼
129 SerialTransport::write_all
129 SerialTransport::write_all
130```
130```
131
131
132### Error handling (current)
132### Error handling (current)
133
133
134| Condition | Behaviour |
134| Condition | Behaviour |
135|-----------|-----------|
135|-----------|-----------|
136| Parse error | Block print; show in toolbar |
136| Parse error | Block print; show in toolbar |
137| Port open failure | `PrintError::Open` message in dialog |
137| Port open failure | `PrintError::Open` message in dialog |
138| Write failure | `PrintError::Write` message in dialog |
138| Write failure | `PrintError::Write` message in dialog |
139| EAN13/EAN8 invalid length | `EscPosError::Barcode` before write |
139| EAN13/EAN8 invalid length | `EscPosError::Barcode` before write |
140| Linux permission denied | User must join `dialout` group (documented in Help) |
140| Linux permission denied | User must join `dialout` group (documented in Help) |
141
141
142Status polling (paper out, cover open) is **not** implemented.
142Status polling (paper out, cover open) is **not** implemented.
143
143
144---
144---
145
145
146## Images
146## Images
147
147
1481. Resolve path relative to `.pos` file directory (or absolute path).
1481. Resolve path relative to `.pos` file directory (or absolute path).
1492. Decode with `image` crate.
1492. Decode with `image` crate.
1503. Convert to luma8, resize to target width (%, dots, or full printable width).
1503. Convert to luma8, resize to target width (%, dots, or full printable width).
1514. Threshold to 1-bit raster.
1514. Threshold to 1-bit raster.
1525. Emit `GS v 0` raster (`1D 76 30 00`, width/height LE, bitmap) — same format as print-bridge.
1525. Emit `GS v 0` raster (`1D 76 30 00`, width/height LE, bitmap) — same format as print-bridge.
153
153
154Preview shows `[image: path]` only — no bitmap preview yet.
154Preview shows `[image: path]` only — no bitmap preview yet.
155
155
156---
156---
157
157
158## Preview vs print width
158## Preview vs print width
159
159
160| `preview_mode` | Preview | Print |
160| `preview_mode` | Preview | Print |
161|----------------|---------|-------|
161|----------------|---------|-------|
162| `autoscale` | Scales to panel width | Full paper width from metadata |
162| `autoscale` | Scales to panel width | Full paper width from metadata |
163| `fixed` | Scaled by mm ratio | Full paper width |
163| `fixed` | Scaled by mm ratio | Full paper width |
164
164
165---
165---
166
166
167## Testing without hardware
167## Testing without hardware
168
168
169| Method | Location |
169| Method | Location |
170|--------|----------|
170|--------|----------|
171| `MockTransport` | `print/mod.rs` tests |
171| `MockTransport` | `print/mod.rs` tests |
172| ESC/POS byte checks | `escpos.rs` tests |
172| ESC/POS byte checks | `escpos.rs` tests |
173| `cargo test` | 20 tests; no printer required |
173| `cargo test` | 20 tests; no printer required |
174
174
175---
175---
176
176
177## Planned (not implemented)
177## Planned (not implemented)
178
178
179| Feature | Notes |
179| Feature | Notes |
180|---------|-------|
180|---------|-------|
181| USB printer class | `nusb` / Windows `usbprint` |
181| USB printer class | `nusb` / Windows `usbprint` |
182| Bluetooth SPP | Serial port after OS pairing |
182| Bluetooth SPP | Serial port after OS pairing |
183| Baud autodetect | Try 9600, 19200, 115200 |
183| Baud autodetect | Try 9600, 19200, 115200 |
184| Printer status read | DLE EOT |
184| Printer status read | DLE EOT |
185| Network TCP 9100 | Future |
185| Network TCP 9100 | Future |
186| Image size warning in UI | Future |
186| Image size warning in UI | Future |
187
187
188---
188---
189
189
190## Dependencies
190## Dependencies
191
191
192```toml
192```toml
193serialport = "4"
193serialport = "4"
194image = { features = ["png", "jpeg", "gif", "bmp"] }
194image = { features = ["png", "jpeg", "gif", "bmp"] }
195```
195```
196
196
197No `escpos`, `nusb`, or `rusb` crates.
197No `escpos`, `nusb`, or `rusb` crates.
packaging/linux/posprint-print.desktop +11 −11
@@ -1,11 +1,11 @@
1 [Desktop Entry]
2 Type=Service
3 ServiceTypes=KonqPopupMenu/Plugin
4 MimeType=application/x-posprint;
5 Actions=Print;
6 X-KDE-Priority=TopLevel
7
8 [Desktop Action Print]
9 Name=Print
10 Icon=posprint
11 Exec=posprint --print %f
1 [Desktop Entry]
2 Type=Service
3 ServiceTypes=KonqPopupMenu/Plugin
4 MimeType=application/x-posprint;
5 Actions=Print;
6 X-KDE-Priority=TopLevel
7
8 [Desktop Action Print]
9 Name=Print
10 Icon=posprint
11 Exec=posprint --print %f
@@ -1,11 +1,11 @@
1[Desktop Entry]
1[Desktop Entry]
2Type=Service
2Type=Service
3ServiceTypes=KonqPopupMenu/Plugin
3ServiceTypes=KonqPopupMenu/Plugin
4MimeType=application/x-posprint;
4MimeType=application/x-posprint;
5Actions=Print;
5Actions=Print;
6X-KDE-Priority=TopLevel
6X-KDE-Priority=TopLevel
7
7
8[Desktop Action Print]
8[Desktop Action Print]
9Name=Print
9Name=Print
10Icon=posprint
10Icon=posprint
11Exec=posprint --print %f
11Exec=posprint --print %f