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>
@@ -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 architecture2
2
3
## Overview
3
## Overview4
4
5
posprint is a **single Rust binary** using **egui** (eframe). No separate frontend language, no WebView, no IPC layer.
5
posprint is a **single Rust binary** using **egui** (eframe). No separate frontend language, no WebView, no IPC layer.6
6
7
```
7
```8
┌─────────────────────────────────────────┐
8
┌─────────────────────────────────────────┐9
│ posprint (Rust + egui) │
9
│ posprint (Rust + egui) │10
│ - Editor / Preview / Help tabs │
10
│ - 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 layout19
19
20
```
20
```21
src/
21
src/22
├── main.rs # eframe entry point
22
├── main.rs # eframe entry point23
├── 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_MARKDOWN25
├── 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/substitute27
├── 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 canvas29
├── 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, MockTransport31
```
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
43
ESC/POS command generation is **not** delegated to a third-party crate.
43
ESC/POS command generation is **not** delegated to a third-party crate.44
44
45
---
45
---46
46
47
## UI structure
47
## UI structure48
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
58
Bottom panel switches tabs. Top panel holds actions and settings.
58
Bottom panel switches tabs. Top panel holds actions and settings.59
59
60
---
60
---61
61
62
## Data flow
62
## Data flow63
63
64
### Edit loop (live preview)
64
### Edit loop (live preview)65
65
66
1. User types in the Editor tab.
66
1. User types in the Editor tab.67
2. Each frame, `parse(&body)` runs; errors show in the toolbar.
67
2. Each frame, `parse(&body)` runs; errors show in the toolbar.68
3. On Preview tab, `render_preview(&doc, &metadata)` builds a `PreviewModel`.
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.
69
4. Canvas draws text lines, rules, and placeholders for barcode/QR/image.70
70
71
Preview is **not debounced** — it re-parses when the Preview tab is shown (and parse runs every frame for error display).
71
Preview 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 / load74
74
75
1. **Open:** `rfd` file dialog → `PosFile::load_from_path` → populate `body`, `metadata`, `file_path`.
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.
76
2. **Save / Save As:** `PosFile::save_to_path` writes pretty-printed JSON.77
77
78
Image paths in `@image` resolve relative to the `.pos` file directory on print.
78
Image paths in `@image` resolve relative to the `.pos` file directory on print.79
79
80
### Print
80
### Print81
81
82
1. User clicks **Print** → parse body → `collect_parameter_names(&doc)`.
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).
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()`.
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`.
85
4. `substitute_document` → `EscPosEncoder::encode_document` → `SerialTransport::open` (9600 baud) → `print_bytes`.86
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.
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
88
89
---
89
---90
90
91
## Key types
91
## Key types92
92
93
Implemented in `dsl/mod.rs`, `io/mod.rs`, `print/mod.rs`:
93
Implemented in `dsl/mod.rs`, `io/mod.rs`, `print/mod.rs`:94
94
95
```rust
95
```rust96
// dsl/
96
// dsl/97
struct Document { blocks: Vec<Block> }
97
struct Document { blocks: Vec<Block> }98
98
99
enum Block {
99
enum 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/111
struct PosFile { version, metadata: PosMetadata, body }
111
struct PosFile { version, metadata: PosMetadata, body }112
struct PosMetadata { title, page_width_mm, preview_mode, chars_per_line, codepage, cut_after_print }
112
struct PosMetadata { title, page_width_mm, preview_mode, chars_per_line, codepage, cut_after_print }113
113
114
// print/
114
// print/115
struct PrinterDevice { id, display_name, port_name }
115
struct PrinterDevice { id, display_name, port_name }116
trait PrinterTransport { write_all, flush }
116
trait PrinterTransport { write_all, flush }117
```
117
```118
118
119
---
119
---120
120
121
## Preview vs print fidelity
121
## Preview vs print fidelity122
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
131
Both paths share the same **AST**; substitution happens only at print time. Preview shows unresolved `${Param}` tokens as-is.
131
Both 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
## Testing147
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
158
Run: `cargo test` (20 tests). CI runs this on Linux (Docker) and Windows (shell runner).
158
Run: `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 release163
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 emulation174
- Bluetooth SPP
174
- Bluetooth SPP175
- Network printers (TCP 9100)
175
- Network printers (TCP 9100)176
- Baud-rate autodetect / settings UI
176
- Baud-rate autodetect / settings UI177
- Persisted last parameters and recent files
177
- Persisted last parameters and recent files178
- Syntax highlighting in editor
178
- Syntax highlighting in editor179
179
180
See [PRINTING.md](PRINTING.md) and [DSL-SPEC.md](DSL-SPEC.md) for protocol and language details.
180
See [PRINTING.md](PRINTING.md) and [DSL-SPEC.md](DSL-SPEC.md) for protocol and language details.@@ -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 specification2
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.
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
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 structure12
12
13
A document is a sequence of **blocks** separated by blank lines. Blocks cannot be nested except for inline markup within text blocks.
13
A document is a sequence of **blocks** 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 blocks18
18
19
### Paragraphs
19
### Paragraphs20
20
21
Plain text with optional inline markup. One or more consecutive non-empty lines form a paragraph.
21
Plain text with optional inline markup. One or more consecutive non-empty lines form a paragraph.22
22
23
```markdown
23
```markdown24
Thank you for your purchase!
24
Thank you for your purchase!25
Visit us again soon.
25
Visit us again soon.26
```
26
```27
27
28
### Headings
28
### Headings29
29
30
```markdown
30
```markdown31
# Store Name
31
# Store Name32
## Receipt
32
## Receipt33
```
33
```34
34
35
- `#` → large / double-height text (ESC/POS emphasis)
35
- `#` → large / double-height text (ESC/POS emphasis)36
- `##` → bold emphasis
36
- `##` → bold emphasis37
- Maximum two levels in v1
37
- Maximum two levels in v138
38
39
### Alignment
39
### Alignment40
40
41
Prefix a paragraph with alignment markers:
41
Prefix a paragraph with alignment markers:42
42
43
```markdown
43
```markdown44
:center:
44
:center:45
Your Store Name
45
Your Store Name46
46
47
:right:
47
:right:48
Total: ${Amount}
48
Total: ${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 markup58
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
66
Parameters work inside any text, and inside barcode/QR/image directives (below).
66
Parameters work inside any text, and inside barcode/QR/image directives (below).67
67
68
**Example:**
68
**Example:**69
69
70
```markdown
70
```markdown71
Receipt #${DocumentNumber}
71
Receipt #${DocumentNumber}72
Date: ${Date}
72
Date: ${Date}73
73
74
Item: ${ItemName} **${LineTotal}**
74
Item: ${ItemName} **${LineTotal}**75
```
75
```76
76
77
### Horizontal rule
77
### Horizontal rule78
78
79
```markdown
79
```markdown80
---
80
---81
```
81
```82
82
83
Renders a dashed or solid separator line across the print width.
83
Renders 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
89
Directives start with `@` at the beginning of a line.
89
Directives start with `@` at the beginning of a line.90
90
91
### Feed (blank lines)
91
### Feed (blank lines)92
92
93
```markdown
93
```markdown94
@feed 3
94
@feed 395
```
95
```96
96
97
Advances paper by *n* lines.
97
Advances paper by *n* lines.98
98
99
### Cut
99
### Cut100
100
101
```markdown
101
```markdown102
@cut
102
@cut103
```
103
```104
104
105
Partial cut after content (if printer supports). Often placed at document end.
105
Partial cut after content (if printer supports). Often placed at document end.106
106
107
### Image
107
### Image108
108
109
```markdown
109
```markdown110
@image path/to/logo.png
110
@image path/to/logo.png111
@image ${LogoPath} width=50%
111
@image ${LogoPath} width=50%112
@image assets/qr-promo.png width=384
112
@image assets/qr-promo.png width=384113
```
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
121
Images are converted to monochrome raster data, dithered, and scaled to width.
121
Images are converted to monochrome raster data, dithered, and scaled to width.122
122
123
### Barcode
123
### Barcode124
124
125
```markdown
125
```markdown126
@barcode CODE128 ${Sku}
126
@barcode CODE128 ${Sku}127
@barcode EAN13 ${EanCode} height=80
127
@barcode EAN13 ${EanCode} height=80128
```
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 code139
139
140
```markdown
140
```markdown141
@qr https://example.com/receipt/${DocumentNumber}
141
@qr https://example.com/receipt/${DocumentNumber}142
@qr ${PaymentUrl} size=6
142
@qr ${PaymentUrl} size=6143
```
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
## Parameters155
155
156
### Syntax
156
### Syntax157
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 different164
- **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 time165
165
166
### Where parameters are allowed
166
### Where parameters are allowed167
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 behavior176
176
177
1. Before print, scan AST for all `${...}` tokens.
177
1. Before print, scan AST for all `${...}` tokens.178
2. Deduplicate by name.
178
2. Deduplicate by name.179
3. Show dialog with one field per unique 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).
180
4. Pre-fill from last print session (global or per-file — implementation choice).181
5. Substitute into AST, then render/print.
181
5. Substitute into AST, then render/print.182
182
183
Missing parameter at print time: block print and highlight unresolved names in UI.
183
Missing parameter at print time: block print and highlight unresolved names in UI.184
184
185
---
185
---186
186
187
## Comments
187
## Comments188
188
189
```markdown
189
```markdown190
<!-- This is a comment, not printed -->
190
<!-- This is a comment, not printed -->191
```
191
```192
192
193
HTML-style comments are stripped at parse time.
193
HTML-style comments are stripped at parse time.194
194
195
---
195
---196
196
197
## Example document
197
## Example document198
198
199
```markdown
199
```markdown200
# ${StoreName}
200
# ${StoreName}201
:center:
201
:center:202
202
203
123 Main Street
203
123 Main Street204
Tel: ${StorePhone}
204
Tel: ${StorePhone}205
205
206
---
206
---207
Date: ${Date} Time: ${Time}
207
Date: ${Date} Time: ${Time}208
Receipt: ${DocumentNumber}
208
Receipt: ${DocumentNumber}209
209
210
Item Total
210
Item Total211
${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 2219
@qr https://shop.example.com/r/${DocumentNumber}
219
@qr https://shop.example.com/r/${DocumentNumber}220
220
221
Thank you!
221
Thank you!222
@feed 4
222
@feed 4223
@cut
223
@cut224
```
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 errors231
231
232
The parser reports:
232
The parser reports:233
233
234
- Unknown directive
234
- Unknown directive235
- Invalid barcode symbology
235
- Invalid barcode symbology236
- Unclosed `**` or `` ` ``
236
- Unclosed `**` or `` ` ``237
- Invalid `${}` name
237
- Invalid `${}` name238
- Missing required directive argument
238
- Missing required directive argument239
239
240
Errors include 1-based line and column for editor highlighting.
240
Errors 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
257
Full command details live in the print encoder module; see [PRINTING.md](PRINTING.md).
257
Full 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 items264
- `UPC-A` barcodes
264
- `UPC-A` barcodes265
- Conditionals: `@if ${HasDiscount} ... @endif`
265
- Conditionals: `@if ${HasDiscount} ... @endif`266
- Loops / repeating sections
266
- Loops / repeating sections267
- `@signature` for custom ESC/POS hex escape
267
- `@signature` for custom ESC/POS hex escape268
- Multiple code pages / Unicode subset
268
- Multiple code pages / Unicode subset269
- Syntax highlighting in the editor
269
- Syntax highlighting in the editor@@ -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 assessment2
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 summary6
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
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**.
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
15
16
---
16
---17
17
18
## Requirements breakdown
18
## Requirements breakdown19
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
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.
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
28
29
### 2. Markdown-like document syntax + live preview
29
### 2. Markdown-like document syntax + live preview30
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
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.
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
38
39
### 3. Save / load `.pos` files
39
### 3. Save / load `.pos` files40
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
45
Trivial with serde (Rust) or equivalent. Version field supports forward-compatible evolution.
45
Trivial 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
56
Straightforward string substitution after validation. Image parameters might reference file paths or base64 — define clearly in DSL spec.
56
Straightforward 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, images59
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
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.
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
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
78
This is the **primary technical risk**.
78
This is the **primary technical risk**.79
79
80
#### How POS printers actually connect
80
#### How POS printers actually connect81
81
82
Most consumer thermal printers expose one of:
82
Most consumer thermal printers expose one of:83
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.**
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
85
86
2. **USB printer class (interface 7)** — bulk transfers; **not implemented**. Would need `nusb` or Windows `usbprint.sys`.
86
2. **USB printer class (interface 7)** — bulk transfers; **not implemented**. Would need `nusb` or Windows `usbprint.sys`.87
87
88
3. **Bluetooth Classic SPP** — **not implemented**; deferred.
88
3. **Bluetooth Classic SPP** — **not implemented**; deferred.89
89
90
4. **Network (TCP 9100)** — common in production but **out of scope** unless added later.
90
4. **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 reality95
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
99
Expect **per-printer testing**; some devices need init sequences, code pages, or cut commands that differ slightly.
99
Expect **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 subsystem104
104
105
```
105
```106
Effort (relative)
106
Effort (relative)107
Editor UI ████████░░ Medium
107
Editor UI ████████░░ Medium108
Preview renderer ███████░░░ Medium
108
Preview renderer ███████░░░ Medium109
DSL parser ██████░░░░ Medium
109
DSL parser ██████░░░░ Medium110
File I/O ██░░░░░░░░ Low
110
File I/O ██░░░░░░░░ Low111
Parameters ███░░░░░░░ Low
111
Parameters ███░░░░░░░ Low112
Barcode/QR/image █████░░░░░ Low–medium
112
Barcode/QR/image █████░░░░░ Low–medium113
Printer discovery ███████░░░ Medium
113
Printer discovery ███████░░░ Medium114
Raw print I/O █████████░ High
114
Raw print I/O █████████░ High115
Integration/polish ██████░░░░ Medium
115
Integration/polish ██████░░░░ Medium116
```
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
133
Add 30–50% if the developer is new to Rust or ESC/POS.
133
Add 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 mitigations138
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 printing153
- 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 engines157
- Collaborative editing / cloud sync
157
- Collaborative editing / cloud sync158
- macOS (feasible later with same stack)
158
- macOS (feasible later with same stack)159
159
160
---
160
---161
161
162
## Recommendation
162
## Recommendation163
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
166
See [LANGUAGE-CHOICE.md](LANGUAGE-CHOICE.md) and [ARCHITECTURE.md](ARCHITECTURE.md).
166
See [LANGUAGE-CHOICE.md](LANGUAGE-CHOICE.md) and [ARCHITECTURE.md](ARCHITECTURE.md).@@ -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 format2
2
3
A `.pos` file stores a POS print template: metadata (page settings, title) plus the DSL document body as plain text.
3
A `.pos` file stores a POS print template: metadata (page settings, title) plus the DSL document body as plain text.4
4
5
**Format:** JSON envelope with a `.pos` extension (human-readable, git-friendly).
5
**Format:** JSON envelope with a `.pos` extension (human-readable, git-friendly). 6
**MIME type (suggested):** `application/vnd.posprint+json`
6
**MIME type (suggested):** `application/vnd.posprint+json`7
7
8
---
8
---9
9
10
## Top-level schema
10
## Top-level schema11
11
12
```json
12
```json13
{
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
```json31
{
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": true38
}
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 derivation51
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 file60
60
61
**`receipt.pos`:**
61
**`receipt.pos`:**62
62
63
```json
63
```json64
{
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": true72
},
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
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.
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
78
79
---
79
---80
80
81
## Asset resolution
81
## Asset resolution82
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 migration90
90
91
| From | To | Migration |
91
| From | To | Migration |92
|------|-----|-----------|
92
|------|-----|-----------|93
| — | 1 | Initial release |
93
| — | 1 | Initial release |94
94
95
On load, if `version` is newer than app supports → error with upgrade message.
95
On load, if `version` is newer than app supports → error with upgrade message. 96
If older → run migration chain (none yet).
96
If older → run migration chain (none yet).97
97
98
---
98
---99
99
100
## Alternative considered: two-file bundle
100
## Alternative considered: two-file bundle101
101
102
Rejected for v1: `.pos` + sidecar `.pos.json` adds friction. Single JSON file keeps save/load atomic.
102
Rejected for v1: `.pos` + sidecar `.pos.json` adds friction. Single JSON file keeps save/load atomic.103
103
104
A future `.poszip` could bundle images for portable templates.
104
A future `.poszip` could bundle images for portable templates.105
105
106
---
106
---107
107
108
## Validation rules
108
## Validation rules109
109
110
On save:
110
On save:111
111
112
- `version` must equal supported version
112
- `version` must equal supported version113
- `page_width_mm` > 0
113
- `page_width_mm` > 0114
- `body` must be valid UTF-8
114
- `body` must be valid UTF-8115
115
116
On load:
116
On load:117
117
118
- Parse JSON; validate schema
118
- Parse JSON; validate schema119
- 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 loads120
120
121
---
121
---122
122
123
## TypeScript / Rust types (reference)
123
## TypeScript / Rust types (reference)124
124
125
```typescript
125
```typescript126
interface PosFile {
126
interface PosFile {127
version: number;
127
version: number;128
metadata: PosMetadata;
128
metadata: PosMetadata;129
body: string;
129
body: string;130
}
130
}131
131
132
interface PosMetadata {
132
interface 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
142
Rust types use `serde` derive in `src/io/mod.rs` and are used directly by the egui app (no IPC layer).
142
Rust types use `serde` derive in `src/io/mod.rs` and are used directly by the egui app (no IPC layer).@@ -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
3
Print a `.pos` template without opening the GUI.
3
Print a `.pos` template without opening the GUI.4
4
5
## Syntax
5
## Syntax6
6
7
```bash
7
```bash8
posprint print <file.pos> --printer <DEVICE> --set Name=Value [--set Other=Value ...]
8
posprint print <file.pos> --printer <DEVICE> --set Name=Value [--set Other=Value ...]9
```
9
```10
10
11
Short form:
11
Short form:12
12
13
```bash
13
```bash14
posprint print receipt.pos -p /dev/ttyUSB0 --set StoreName="My Shop" --set DocumentNumber=1001
14
posprint print receipt.pos -p /dev/ttyUSB0 --set StoreName="My Shop" --set DocumentNumber=100115
```
15
```16
16
17
## Rules
17
## Rules18
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
## Permissions25
25
26
Your user must be in the **`dialout`** group:
26
Your user must be in the **`dialout`** group:27
27
28
```bash
28
```bash29
sudo usermod -aG dialout "$USER"
29
sudo usermod -aG dialout "$USER"30
# log out and back in
30
# log out and back in31
groups
31
groups32
```
32
```33
33
34
## Examples
34
## Examples35
35
36
```bash
36
```bash37
posprint print ~/receipts/sale.pos -p /dev/ttyUSB0 \
37
posprint 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.9942
```
42
```43
43
44
## Printer device
44
## Printer device45
45
46
```bash
46
```bash47
ls -l /dev/ttyUSB* /dev/ttyACM* 2>/dev/null
47
ls -l /dev/ttyUSB* /dev/ttyACM* 2>/dev/null48
```
48
```49
49
50
Use the device node shown when the printer is connected.
50
Use the device node shown when the printer is connected.51
51
52
## Exit codes
52
## Exit codes53
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
## Help60
60
61
```bash
61
```bash62
posprint print --help
62
posprint print --help63
posprint --help
63
posprint --help64
```
64
```65
65
66
Launch the graphical designer by running `posprint` with **no** subcommand.
66
Launch the graphical designer by running `posprint` with **no** subcommand.@@ -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
3
Print a `.pos` template without opening the GUI.
3
Print a `.pos` template without opening the GUI.4
4
5
## Syntax
5
## Syntax6
6
7
```powershell
7
```powershell8
posprint print <file.pos> --printer <PORT> --set Name=Value [--set Other=Value ...]
8
posprint print <file.pos> --printer <PORT> --set Name=Value [--set Other=Value ...]9
```
9
```10
10
11
Short form:
11
Short form:12
12
13
```powershell
13
```powershell14
posprint print receipt.pos -p COM3 --set StoreName="My Shop" --set DocumentNumber=1001
14
posprint print receipt.pos -p COM3 --set StoreName="My Shop" --set DocumentNumber=100115
```
15
```16
16
17
## Rules
17
## Rules18
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
## Examples25
25
26
List required parameters by opening the template in the designer, or inspect the `${...}` tokens in the file body.
26
List required parameters by opening the template in the designer, or inspect the `${...}` tokens in the file body.27
27
28
```powershell
28
```powershell29
posprint print C:\receipts\sale.pos -p COM3 `
29
posprint 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.9934
```
34
```35
35
36
## Printer port
36
## Printer port37
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 codes43
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
## Help50
50
51
```powershell
51
```powershell52
posprint print --help
52
posprint print --help53
posprint --help
53
posprint --help54
```
54
```55
55
56
Launch the graphical designer by running `posprint` with **no** subcommand.
56
Launch the graphical designer by running `posprint` with **no** subcommand.@@ -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 Help2
2
3
Built-in reference for the template editor and POS markup language.
3
Built-in reference for the template editor and POS markup language.4
4
5
---
5
---6
6
7
## Application tabs
7
## Application tabs8
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 actions16
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 assistance26
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 settings31
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 language42
42
43
A template is plain text: paragraphs, headings, directives, and inline markup.
43
A template is plain text: paragraphs, headings, directives, and inline markup.44
44
45
### Paragraphs
45
### Paragraphs46
46
47
Consecutive non-empty lines form one paragraph.
47
Consecutive non-empty lines form one paragraph.48
48
49
### Headings
49
### Headings50
50
51
```markdown
51
```markdown52
# Large heading
52
# Large heading53
## Bold heading
53
## Bold heading54
```
54
```55
55
56
### Alignment
56
### Alignment57
57
58
`:left:`, `:center:`, or `:right:` before a paragraph.
58
`:left:`, `:center:`, or `:right:` before a paragraph.59
59
60
### Inline markup
60
### Inline markup61
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 rule70
70
71
```markdown
71
```markdown72
---
72
---73
```
73
```74
74
75
### Comments
75
### Comments76
76
77
```markdown
77
```markdown78
<!-- not printed -->
78
<!-- not printed -->79
```
79
```80
80
81
---
81
---82
82
83
## Directives
83
## Directives84
84
85
Directives start with `@` at the beginning of a line.
85
Directives start with `@` at the beginning of a line.86
86
87
### Paper feed / cut
87
### Paper feed / cut88
88
89
```markdown
89
```markdown90
@feed 3
90
@feed 391
@cut
91
@cut92
```
92
```93
93
94
### Image
94
### Image95
95
96
```markdown
96
```markdown97
@image logo.png
97
@image logo.png98
@image ${LogoPath} width=50% align=center
98
@image ${LogoPath} width=50% align=center99
```
99
```100
100
101
### Barcode
101
### Barcode102
102
103
**Native** (printer draws barcode via ESC/POS):
103
**Native** (printer draws barcode via ESC/POS):104
104
105
```markdown
105
```markdown106
@barcode CODE128 ${OrderId}
106
@barcode CODE128 ${OrderId}107
@barcode UPC-A 012345678905
107
@barcode UPC-A 012345678905108
@barcode ITF 12345678 height=80
108
@barcode ITF 12345678 height=80109
```
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
```markdown114
@barcode RASTER CODE128 ${OrderId}
114
@barcode RASTER CODE128 ${OrderId}115
@barcode RASTER CODE93 ABC-1234
115
@barcode RASTER CODE93 ABC-1234116
```
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 code138
138
139
**Native** (ESC/POS QR, model 2):
139
**Native** (ESC/POS QR, model 2):140
140
141
```markdown
141
```markdown142
@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=center144
```
144
```145
145
146
**Raster** (bitmap; supports QR versions 1–40):
146
**Raster** (bitmap; supports QR versions 1–40):147
147
148
```markdown
148
```markdown149
@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=M151
```
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
## Parameters164
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 receipt173
173
174
```markdown
174
```markdown175
# ${StoreName}
175
# ${StoreName}176
:center:
176
:center:177
177
178
Receipt: ${DocumentNumber}
178
Receipt: ${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=4182
182
183
@feed 4
183
@feed 4184
@cut
184
@cut185
```
185
```186
186
187
---
187
---188
188
189
## GUI printing (USB)
189
## GUI printing (USB)190
190
191
1. **Print** → enter parameters → choose serial port → **Print**.
191
1. **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 format198
198
199
JSON with `version`, `metadata`, and `body` (template source).
199
JSON with `version`, `metadata`, and `body` (template source).@@ -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 choice2
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
## Requirements18
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 use31
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 notes59
59
60
### Windows
60
### Windows61
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
### Linux67
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
## Deferred76
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
83
This document should be updated when transport or UI choices change.
83
This document should be updated when transport or UI choices change.@@ -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 subsystem2
2
3
Direct raw-byte printing to POS thermal printers over **USB-serial** — without the Windows print spooler or CUPS.
3
Direct 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
## Goals10
10
11
1. Discover serial ports (USB-serial adapters and CDC printers)
11
1. Discover serial ports (USB-serial adapters and CDC printers)12
2. Let the user pick a port in the print dialog
12
2. Let the user pick a port in the print dialog13
3. Generate ESC/POS bytes from the AST (after parameter substitution)
13
3. Generate ESC/POS bytes from the AST (after parameter substitution)14
4. Write bytes at **9600 baud** (fixed for now)
14
4. Write bytes at **9600 baud** (fixed for now)15
15
16
---
16
---17
17
18
## Protocol: ESC/POS
18
## Protocol: ESC/POS19
19
20
Target **Epson ESC/POS** compatible printers (58 mm / 80 mm thermal).
20
Target **Epson ESC/POS** compatible printers (58 mm / 80 mm thermal).21
21
22
### Implemented commands
22
### Implemented commands23
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
37
Encoder: `EscPosEncoder` in `src/escpos.rs` — **not** the `escpos` crates.io package.
37
Encoder: `EscPosEncoder` in `src/escpos.rs` — **not** the `escpos` crates.io package.38
38
39
---
39
---40
40
41
## Transport (implemented)
41
## Transport (implemented)42
42
43
```
43
```44
Print button
44
Print button45
│
45
│46
▼
46
▼47
substitute_document()
47
substitute_document()48
│
48
│49
▼
49
▼50
EscPosEncoder::encode_document()
50
EscPosEncoder::encode_document()51
│
51
│52
▼
52
▼53
SerialTransport::open(port, 9600)
53
SerialTransport::open(port, 9600)54
│
54
│55
▼
55
▼56
print_bytes() → write_all + flush
56
print_bytes() → write_all + flush57
```
57
```58
58
59
### `PrinterTransport` trait
59
### `PrinterTransport` trait60
60
61
```rust
61
```rust62
pub trait PrinterTransport {
62
pub 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
### Discovery74
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 pipeline112
112
113
```
113
```114
Document body (DSL)
114
Document body (DSL)115
│
115
│116
▼
116
▼117
parse() → Document
117
parse() → Document118
│
118
│119
▼
119
▼120
collect_parameter_names() → UI dialog
120
collect_parameter_names() → UI dialog121
│
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_all130
```
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
142
Status polling (paper out, cover open) is **not** implemented.
142
Status polling (paper out, cover open) is **not** implemented.143
143
144
---
144
---145
145
146
## Images
146
## Images147
147
148
1. Resolve path relative to `.pos` file directory (or absolute path).
148
1. Resolve path relative to `.pos` file directory (or absolute path).149
2. Decode with `image` crate.
149
2. Decode with `image` crate.150
3. Convert to luma8, resize to target width (%, dots, or full printable width).
150
3. Convert to luma8, resize to target width (%, dots, or full printable width).151
4. Threshold to 1-bit raster.
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.
152
5. Emit `GS v 0` raster (`1D 76 30 00`, width/height LE, bitmap) — same format as print-bridge.153
153
154
Preview shows `[image: path]` only — no bitmap preview yet.
154
Preview shows `[image: path]` only — no bitmap preview yet.155
155
156
---
156
---157
157
158
## Preview vs print width
158
## Preview vs print width159
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 hardware168
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
## Dependencies191
191
192
```toml
192
```toml193
serialport = "4"
193
serialport = "4"194
image = { features = ["png", "jpeg", "gif", "bmp"] }
194
image = { features = ["png", "jpeg", "gif", "bmp"] }195
```
195
```196
196
197
No `escpos`, `nusb`, or `rusb` crates.
197
No `escpos`, `nusb`, or `rusb` crates.@@ -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]2
Type=Service
2
Type=Service3
ServiceTypes=KonqPopupMenu/Plugin
3
ServiceTypes=KonqPopupMenu/Plugin4
MimeType=application/x-posprint;
4
MimeType=application/x-posprint;5
Actions=Print;
5
Actions=Print;6
X-KDE-Priority=TopLevel
6
X-KDE-Priority=TopLevel7
7
8
[Desktop Action Print]
8
[Desktop Action Print]9
Name=Print
9
Name=Print10
Icon=posprint
10
Icon=posprint11
Exec=posprint --print %f
11
Exec=posprint --print %f