BlueGit

timfa posprint

Files

posprint / docs / PRINTING.md

PRINTING.md

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, **text** flattened at encode
Double sizeGS !Heading level 1
AlignmentESC aParagraphs, images, barcodes, QR
Line feedLF, ESC dText lines, @feed
Partial cutGS V 66 0@cut, auto-cut after print
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). 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 paper width from metadata
fixedScaled by mm ratioFull paper 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, `**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
37Encoder: `EscPosEncoder` in `src/escpos.rs` — **not** the `escpos` crates.io package.
38
39---
40
41## Transport (implemented)
42
43```
44Print button
45 │
46 ▼
47substitute_document()
48 │
49 ▼
50EscPosEncoder::encode_document()
51 │
52 ▼
53SerialTransport::open(port, 9600)
54 │
55 ▼
56print_bytes() → write_all + flush
57```
58
59### `PrinterTransport` trait
60
61```rust
62pub 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```
114Document 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
142Status polling (paper out, cover open) is **not** implemented.
143
144---
145
146## Images
147
1481. Resolve path relative to `.pos` file directory (or absolute path).
1492. Decode with `image` crate.
1503. Convert to luma8, resize to target width (%, dots, or full printable width).
1514. Threshold to 1-bit raster.
1525. Emit `GS v 0` raster (`1D 76 30 00`, width/height LE, bitmap) — same format as print-bridge.
153
154Preview 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
193serialport = "4"
194image = { features = ["png", "jpeg", "gif", "bmp"] }
195```
196
197No `escpos`, `nusb`, or `rusb` crates.