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
| Feature | ESC/POS | Source |
|---|---|---|
| Initialize | ESC @ | escpos.rs |
| Code page | ESC t 0 (CP437) | Always CP437 today; metadata field reserved |
| Bold | ESC E | Headings level 2, **text** flattened at encode |
| Double size | GS ! | Heading level 1 |
| Alignment | ESC a | Paragraphs, images, barcodes, QR |
| Line feed | LF, ESC d | Text lines, @feed |
| Partial cut | GS V 66 0 | @cut in template |
| Barcode | GS k | CODE128, EAN13, EAN8, CODE39 |
| QR Code | GS ( k | Model 2 |
| Raster image | GS 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<()>;
}
| Type | Role |
|---|---|
SerialTransport | Production — opens port via serialport |
MockTransport | Tests — 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
| Field | Example |
|---|---|
id | serial:COM3 |
display_name | COM3 — USB 04b8:0e15 |
port_name | COM3 |
---
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)
| Condition | Behaviour |
|---|---|
| Parse error | Block print; show in toolbar |
| Port open failure | PrintError::Open message in dialog |
| Write failure | PrintError::Write message in dialog |
| EAN13/EAN8 invalid length | EscPosError::Barcode before write |
| Linux permission denied | User 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_mode | Preview | |
|---|---|---|
autoscale | Scales to panel width | Full paper width from metadata |
fixed | Scaled by mm ratio | Full paper width |
---
Testing without hardware
| Method | Location |
|---|---|
MockTransport | print/mod.rs tests |
| ESC/POS byte checks | escpos.rs tests |
cargo test | 20 tests; no printer required |
---
Planned (not implemented)
| Feature | Notes |
|---|---|
| USB printer class | nusb / Windows usbprint |
| Bluetooth SPP | Serial port after OS pairing |
| Baud autodetect | Try 9600, 19200, 115200 |
| Printer status read | DLE EOT |
| Network TCP 9100 | Future |
| Image size warning in UI | Future |
---
Dependencies
serialport = "4"
image = { features = ["png", "jpeg", "gif", "bmp"] }
No escpos, nusb, or rusb crates.
Source
| 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` in template | |
| 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. |