BlueGit

timfa posprint

Files

posprint / docs / PRINTING.md

PRINTING.md

cfe7435b History
PRINTING.md 5.5 KiB Download Raw

Printing subsystem

Direct raw-byte printing to POS thermal printers over USB-serial — without the Windows print spooler or CUPS.

> 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.

---

Goals

1. Discover serial ports (USB-serial adapters and CDC printers) 2. Let the user pick a port in the print dialog 3. Generate ESC/POS bytes from the AST (after parameter substitution) 4. Write bytes at 9600 baud (fixed for now)

---

Protocol: ESC/POS

Target Epson ESC/POS compatible printers (58 mm / 80 mm thermal).

Implemented commands

FeatureESC/POSSource
InitializeESC @escpos.rs
Code pageESC t 0 (CP437)Always CP437 today; metadata field reserved
BoldESC EHeadings level 2 only
Double sizeGS !Heading level 1
AlignmentESC aParagraphs, images, barcodes, QR
Line feedLF (text lines), ESC d (@feed / blank lines)Text lines end with LF; explicit feeds use ESC d
List bulletASCII *- item lines in templates
Partial cutGS V 66 0@cut in template
BarcodeGS kCODE128, EAN13, EAN8, CODE39
QR CodeGS ( kModel 2
Raster imageGS v 0@image via image crate → threshold

Encoder: EscPosEncoder in src/escpos.rs — not the escpos crates.io package.

---

Transport (implemented)

Print button
     │
     ▼
substitute_document()
     │
     ▼
EscPosEncoder::encode_document()
     │
     ▼
SerialTransport::open(port, 9600)
     │
     ▼
print_bytes() → write_all + flush

PrinterTransport trait

pub trait PrinterTransport {
    fn write_all(&mut self, data: &[u8]) -> io::Result<()>;
    fn flush(&mut self) -> io::Result<()>;
}
TypeRole
SerialTransportProduction — opens port via serialport
MockTransportTests — records bytes in written vec

Discovery

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).

PrinterDevice

FieldExample
idserial:COM3
display_nameCOM3 — USB 04b8:0e15
port_nameCOM3

---

Print dialog (UI)

┌─────────────────────────────────────────┐
│  Print                                  │
├─────────────────────────────────────────┤
│  Parameters (one field per unique name) │
│  DocumentNumber: [________]             │
│                                         │
│  USB printer                            │
│  [ Refresh ]                            │
│  ○ COM3 — USB 04b8:0e15                 │
│  ○ /dev/ttyUSB0 — Serial                │
│                                         │
│  [ Cancel ]              [ Print ]      │
└─────────────────────────────────────────┘
  • Parameters pre-filled from last_params (session memory).
  • Same parameter name → one input, applied everywhere.
  • Errors shown inline (parse, open port, write, barcode validation).

---

Print pipeline

Document body (DSL)
        │
        ▼
   parse() → Document
        │
        ▼
 collect_parameter_names() → UI dialog
        │
        ▼
 substitute_document()
        │
        ▼
 EscPosEncoder (in-tree)
        │
        ▼
 SerialTransport::write_all

Error handling (current)

ConditionBehaviour
Parse errorBlock print; show in toolbar
Port open failurePrintError::Open message in dialog
Write failurePrintError::Write message in dialog
EAN13/EAN8 invalid lengthEscPosError::Barcode before write
Linux permission deniedUser must join dialout group (documented in Help)

Status polling (paper out, cover open) is not implemented.

---

Images

1. Resolve path relative to .pos file directory (or absolute path). 2. Decode with image crate. 3. Convert to luma8, resize to target width (%, dots, or full printable width), and never exceed the effective page width. 4. Threshold to 1-bit raster. 5. Emit GS v 0 raster (1D 76 30 00, width/height LE, bitmap) — same format as print-bridge.

Preview shows [image: path] only — no bitmap preview yet.

---

Preview vs print width

preview_modePreviewPrint
autoscaleScales to panel widthFull effective print width
fixedScaled by dot ratioFull effective print width

---

Testing without hardware

MethodLocation
MockTransportprint/mod.rs tests
ESC/POS byte checksescpos.rs tests
cargo test20 tests; no printer required

---

Planned (not implemented)

FeatureNotes
USB printer classnusb / Windows usbprint
Bluetooth SPPSerial port after OS pairing
Baud autodetectTry 9600, 19200, 115200
Printer status readDLE EOT
Network TCP 9100Future
Image size warning in UIFuture

---

Dependencies

serialport = "4"
image = { features = ["png", "jpeg", "gif", "bmp"] }

No escpos, nusb, or rusb crates.

Source
1# Printing subsystem
2
3Direct 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
111. Discover serial ports (USB-serial adapters and CDC printers)
122. Let the user pick a port in the print dialog
133. Generate ESC/POS bytes from the AST (after parameter substitution)
144. Write bytes at **9600 baud** (fixed for now)
15
16---
17
18## Protocol: ESC/POS
19
20Target **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 only |
29| Double size | GS ! | Heading level 1 |
30| Alignment | ESC a | Paragraphs, images, barcodes, QR |
31| Line feed | LF (text lines), ESC d (`@feed` / blank lines) | Text lines end with LF; explicit feeds use ESC d |
32| List bullet | ASCII `*` | `- item` lines in templates |
33| Partial cut | GS V 66 0 | `@cut` in template |
34| Barcode | GS k | CODE128, EAN13, EAN8, CODE39 |
35| QR Code | GS ( k | Model 2 |
36| Raster image | GS v 0 | `@image` via `image` crate → threshold |
37
38Encoder: `EscPosEncoder` in `src/escpos.rs` — **not** the `escpos` crates.io package.
39
40---
41
42## Transport (implemented)
43
44```
45Print button
46 │
47 ▼
48substitute_document()
49 │
50 ▼
51EscPosEncoder::encode_document()
52 │
53 ▼
54SerialTransport::open(port, 9600)
55 │
56 ▼
57print_bytes() → write_all + flush
58```
59
60### `PrinterTransport` trait
61
62```rust
63pub trait PrinterTransport {
64 fn write_all(&mut self, data: &[u8]) -> io::Result<()>;
65 fn flush(&mut self) -> io::Result<()>;
66}
67```
68
69| Type | Role |
70|------|------|
71| `SerialTransport` | Production — opens port via `serialport` |
72| `MockTransport` | Tests — records bytes in `written` vec |
73
74### Discovery
75
76`list_usb_serial_printers()` calls `serialport::available_ports()` and labels USB ports with VID/PID when available. All serial ports are listed (no POS-specific filter).
77
78### `PrinterDevice`
79
80| Field | Example |
81|-------|---------|
82| `id` | `serial:COM3` |
83| `display_name` | `COM3 — USB 04b8:0e15` |
84| `port_name` | `COM3` |
85
86---
87
88## Print dialog (UI)
89
90```
91┌─────────────────────────────────────────┐
92│ Print │
93├─────────────────────────────────────────┤
94│ Parameters (one field per unique name) │
95│ DocumentNumber: [________] │
96│ │
97│ USB printer │
98│ [ Refresh ] │
99│ ○ COM3 — USB 04b8:0e15 │
100│ ○ /dev/ttyUSB0 — Serial │
101│ │
102│ [ Cancel ] [ Print ] │
103└─────────────────────────────────────────┘
104```
105
106- Parameters pre-filled from `last_params` (session memory).
107- Same parameter name → one input, applied everywhere.
108- Errors shown inline (parse, open port, write, barcode validation).
109
110---
111
112## Print pipeline
113
114```
115Document body (DSL)
116 │
117 ▼
118 parse() → Document
119 │
120 ▼
121 collect_parameter_names() → UI dialog
122 │
123 ▼
124 substitute_document()
125 │
126 ▼
127 EscPosEncoder (in-tree)
128 │
129 ▼
130 SerialTransport::write_all
131```
132
133### Error handling (current)
134
135| Condition | Behaviour |
136|-----------|-----------|
137| Parse error | Block print; show in toolbar |
138| Port open failure | `PrintError::Open` message in dialog |
139| Write failure | `PrintError::Write` message in dialog |
140| EAN13/EAN8 invalid length | `EscPosError::Barcode` before write |
141| Linux permission denied | User must join `dialout` group (documented in Help) |
142
143Status polling (paper out, cover open) is **not** implemented.
144
145---
146
147## Images
148
1491. Resolve path relative to `.pos` file directory (or absolute path).
1502. Decode with `image` crate.
1513. Convert to luma8, resize to target width (%, dots, or full printable width), and never exceed the effective page width.
1524. Threshold to 1-bit raster.
1535. Emit `GS v 0` raster (`1D 76 30 00`, width/height LE, bitmap) — same format as print-bridge.
154
155Preview shows `[image: path]` only — no bitmap preview yet.
156
157---
158
159## Preview vs print width
160
161| `preview_mode` | Preview | Print |
162|----------------|---------|-------|
163| `autoscale` | Scales to panel width | Full effective print width |
164| `fixed` | Scaled by dot ratio | Full effective print width |
165
166---
167
168## Testing without hardware
169
170| Method | Location |
171|--------|----------|
172| `MockTransport` | `print/mod.rs` tests |
173| ESC/POS byte checks | `escpos.rs` tests |
174| `cargo test` | 20 tests; no printer required |
175
176---
177
178## Planned (not implemented)
179
180| Feature | Notes |
181|---------|-------|
182| USB printer class | `nusb` / Windows `usbprint` |
183| Bluetooth SPP | Serial port after OS pairing |
184| Baud autodetect | Try 9600, 19200, 115200 |
185| Printer status read | DLE EOT |
186| Network TCP 9100 | Future |
187| Image size warning in UI | Future |
188
189---
190
191## Dependencies
192
193```toml
194serialport = "4"
195image = { features = ["png", "jpeg", "gif", "bmp"] }
196```
197
198No `escpos`, `nusb`, or `rusb` crates.