Printing subsystem
Raw ESC/POS output to POS thermal printers via USB printer-class, Windows spooler (Windows), or USB-serial.
---
Goals
1. Discover printers (USB-direct, Windows spooler, serial ports) 2. Let the user pick a target in the print dialog 3. Generate ESC/POS bytes from the AST (after parameter substitution) 4. Write bytes to the chosen transport (serial baud is probed)
---
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 only |
| Double size | GS ! | Heading level 1 |
| Alignment | ESC a | Paragraphs, images, barcodes, QR |
| Line feed | LF (text lines), ESC d (@feed / blank lines) | Text ends with LF; blank/@feed use ESC d |
| Raster flush | LF after GS v 0 | Ensures spacing after images/barcodes/QR rasters |
| List bullet | ASCII * | - item lines in templates |
| Inline checkbox | ESC & user-defined Font A chars (2 cells) | [] / [ ] / [x]; surrounding text uses native font |
| Partial cut | GS V 66 0 | @cut in template only |
| Barcode | GS k | Native symbologies; raster via GS v 0 |
| QR Code | GS ( k | Model 2; or raster GS v 0 |
| Raster image | GS v 0 | @image / raster barcode / raster QR |
Encoder: EscPosEncoder in src/escpos.rs — not the escpos crates.io package.
---
Transport (implemented)
Print button
│
▼
substitute_document()
│
▼
EscPosEncoder::encode_document()
│
▼
open_printer(target) # USB-direct | Win spooler | serial
│
▼
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 |
|---|---|
USB-direct (rusb) | USB printer-class bulk OUT (usb_direct.rs) |
| Windows spooler | Raw jobs via Win32 spooler (win_spool.rs, Windows only) |
SerialTransport | USB-serial / CDC ports via serialport |
MockTransport | Tests — records bytes in written vec |
Discovery
list_printers() returns, in order:
1. USB printer-class devices (usb_direct) 2. Windows spooler queues (Windows) 3. Serial ports (serialport::available_ports(), with VID/PID labels when available)
Serial baud rates
SerialTransport::open tries, in order:
115200, 9600, 19200, 38400, 57600, 4800
PrinterDevice
| Field | Example |
|---|---|
id | serial:COM3, usb:04b8:0e15:…, spool:POS-58 |
display_name | Human-readable label |
target | Serial / UsbDirect / WinSpooler |
---
Print dialog (UI)
- One field per unique
${Parameter}. - Printer list: USB, spooler, and serial (Refresh button).
- Optional manual serial port name.
- While open, the main Design UI is disabled (including editor autocomplete).
- Errors shown inline (parse, open, write, barcode validation).
---
Print pipeline
Document body (DSL)
│
▼
parse() → Document
│
▼
collect_parameter_names() → UI dialog / CLI --set
│
▼
substitute_document()
│
▼
EscPosEncoder (in-tree)
│
▼
open_printer → write_all
Error handling
| Condition | Behaviour |
|---|---|
| Parse error | Block print; show in toolbar |
| Open failure | Message in dialog / CLI |
| Write failure | Message in dialog / CLI |
| Invalid barcode data | Error before write |
| Linux serial permission | Join dialout group |
Status polling (paper out, cover open) is not implemented.
---
Images and rasters
1. Resolve path relative to the .pos file (or absolute). 2. Decode with image, convert to luma, scale to printable width (chars_per_line × 12 dots). 3. Threshold to 1-bit; emit GS v 0 (1D 76 30 00 + width/height LE + bitmap). 4. Append LF after the raster so following content (including blank-line feeds) advances correctly.
Preview draws the same bitmaps on the canvas (scaled for screen).
---
Testing without hardware
| Method | Location |
|---|---|
MockTransport | print/mod.rs tests |
| ESC/POS byte checks | escpos.rs tests |
cargo test | ~100 unit tests; no printer required |
---
Dependencies
serialport = "4"
rusb = "0.9"
image = { features = ["png", "jpeg", "gif", "bmp"] }
On Windows, spooler access uses Win32 APIs (winreg / system libs as needed). No escpos or nusb crates.
---
Planned (not implemented)
| Feature | Notes |
|---|---|
| Bluetooth SPP | After OS pairing |
| Network TCP 9100 | Future |
| Printer status read | DLE EOT |
Source
| 1 | # Printing subsystem |
| 2 | |
| 3 | Raw ESC/POS output to POS thermal printers via **USB printer-class**, **Windows spooler** (Windows), or **USB-serial**. |
| 4 | |
| 5 | --- |
| 6 | |
| 7 | ## Goals |
| 8 | |
| 9 | 1. Discover printers (USB-direct, Windows spooler, serial ports) |
| 10 | 2. Let the user pick a target in the print dialog |
| 11 | 3. Generate ESC/POS bytes from the AST (after parameter substitution) |
| 12 | 4. Write bytes to the chosen transport (serial baud is probed) |
| 13 | |
| 14 | --- |
| 15 | |
| 16 | ## Protocol: ESC/POS |
| 17 | |
| 18 | Target **Epson ESC/POS** compatible printers (58 mm / 80 mm thermal). |
| 19 | |
| 20 | ### Implemented commands |
| 21 | |
| 22 | | Feature | ESC/POS | Source | |
| 23 | |---------|---------|--------| |
| 24 | | Initialize | ESC @ | `escpos.rs` | |
| 25 | | Code page | ESC t 0 (CP437) | Always CP437 today; metadata field reserved | |
| 26 | | Bold | ESC E | Headings level 2 only | |
| 27 | | Double size | GS ! | Heading level 1 | |
| 28 | | Alignment | ESC a | Paragraphs, images, barcodes, QR | |
| 29 | | Line feed | LF (text lines), ESC d (`@feed` / blank lines) | Text ends with LF; blank/`@feed` use ESC d | |
| 30 | | Raster flush | LF after GS v 0 | Ensures spacing after images/barcodes/QR rasters | |
| 31 | | List bullet | ASCII `*` | `- item` lines in templates | |
| 32 | | Inline checkbox | ESC `&` user-defined Font A chars (2 cells) | `[]` / `[ ]` / `[x]`; surrounding text uses native font | |
| 33 | | Partial cut | GS V 66 0 | `@cut` in template only | |
| 34 | | Barcode | GS k | Native symbologies; raster via GS v 0 | |
| 35 | | QR Code | GS ( k | Model 2; or raster GS v 0 | |
| 36 | | Raster image | GS v 0 | `@image` / raster barcode / raster QR | |
| 37 | |
| 38 | Encoder: `EscPosEncoder` in `src/escpos.rs` — **not** the `escpos` crates.io package. |
| 39 | |
| 40 | --- |
| 41 | |
| 42 | ## Transport (implemented) |
| 43 | |
| 44 | ``` |
| 45 | Print button |
| 46 | │ |
| 47 | ▼ |
| 48 | substitute_document() |
| 49 | │ |
| 50 | ▼ |
| 51 | EscPosEncoder::encode_document() |
| 52 | │ |
| 53 | ▼ |
| 54 | open_printer(target) # USB-direct | Win spooler | serial |
| 55 | │ |
| 56 | ▼ |
| 57 | print_bytes() → write_all + flush |
| 58 | ``` |
| 59 | |
| 60 | ### `PrinterTransport` trait |
| 61 | |
| 62 | ```rust |
| 63 | pub 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 | | USB-direct (`rusb`) | USB printer-class bulk OUT (`usb_direct.rs`) | |
| 72 | | Windows spooler | Raw jobs via Win32 spooler (`win_spool.rs`, Windows only) | |
| 73 | | `SerialTransport` | USB-serial / CDC ports via `serialport` | |
| 74 | | `MockTransport` | Tests — records bytes in `written` vec | |
| 75 | |
| 76 | ### Discovery |
| 77 | |
| 78 | `list_printers()` returns, in order: |
| 79 | |
| 80 | 1. USB printer-class devices (`usb_direct`) |
| 81 | 2. Windows spooler queues (Windows) |
| 82 | 3. Serial ports (`serialport::available_ports()`, with VID/PID labels when available) |
| 83 | |
| 84 | ### Serial baud rates |
| 85 | |
| 86 | `SerialTransport::open` tries, in order: |
| 87 | |
| 88 | `115200`, `9600`, `19200`, `38400`, `57600`, `4800` |
| 89 | |
| 90 | ### `PrinterDevice` |
| 91 | |
| 92 | | Field | Example | |
| 93 | |-------|---------| |
| 94 | | `id` | `serial:COM3`, `usb:04b8:0e15:…`, `spool:POS-58` | |
| 95 | | `display_name` | Human-readable label | |
| 96 | | `target` | `Serial` / `UsbDirect` / `WinSpooler` | |
| 97 | |
| 98 | --- |
| 99 | |
| 100 | ## Print dialog (UI) |
| 101 | |
| 102 | - One field per unique `${Parameter}`. |
| 103 | - Printer list: USB, spooler, and serial (Refresh button). |
| 104 | - Optional manual serial port name. |
| 105 | - While open, the main Design UI is disabled (including editor autocomplete). |
| 106 | - Errors shown inline (parse, open, write, barcode validation). |
| 107 | |
| 108 | --- |
| 109 | |
| 110 | ## Print pipeline |
| 111 | |
| 112 | ``` |
| 113 | Document body (DSL) |
| 114 | │ |
| 115 | ▼ |
| 116 | parse() → Document |
| 117 | │ |
| 118 | ▼ |
| 119 | collect_parameter_names() → UI dialog / CLI --set |
| 120 | │ |
| 121 | ▼ |
| 122 | substitute_document() |
| 123 | │ |
| 124 | ▼ |
| 125 | EscPosEncoder (in-tree) |
| 126 | │ |
| 127 | ▼ |
| 128 | open_printer → write_all |
| 129 | ``` |
| 130 | |
| 131 | ### Error handling |
| 132 | |
| 133 | | Condition | Behaviour | |
| 134 | |-----------|-----------| |
| 135 | | Parse error | Block print; show in toolbar | |
| 136 | | Open failure | Message in dialog / CLI | |
| 137 | | Write failure | Message in dialog / CLI | |
| 138 | | Invalid barcode data | Error before write | |
| 139 | | Linux serial permission | Join `dialout` group | |
| 140 | |
| 141 | Status polling (paper out, cover open) is **not** implemented. |
| 142 | |
| 143 | --- |
| 144 | |
| 145 | ## Images and rasters |
| 146 | |
| 147 | 1. Resolve path relative to the `.pos` file (or absolute). |
| 148 | 2. Decode with `image`, convert to luma, scale to printable width (`chars_per_line × 12` dots). |
| 149 | 3. Threshold to 1-bit; emit `GS v 0` (`1D 76 30 00` + width/height LE + bitmap). |
| 150 | 4. Append **LF** after the raster so following content (including blank-line feeds) advances correctly. |
| 151 | |
| 152 | Preview draws the same bitmaps on the canvas (scaled for screen). |
| 153 | |
| 154 | --- |
| 155 | |
| 156 | ## Testing without hardware |
| 157 | |
| 158 | | Method | Location | |
| 159 | |--------|----------| |
| 160 | | `MockTransport` | `print/mod.rs` tests | |
| 161 | | ESC/POS byte checks | `escpos.rs` tests | |
| 162 | | `cargo test` | ~100 unit tests; no printer required | |
| 163 | |
| 164 | --- |
| 165 | |
| 166 | ## Dependencies |
| 167 | |
| 168 | ```toml |
| 169 | serialport = "4" |
| 170 | rusb = "0.9" |
| 171 | image = { features = ["png", "jpeg", "gif", "bmp"] } |
| 172 | ``` |
| 173 | |
| 174 | On Windows, spooler access uses Win32 APIs (`winreg` / system libs as needed). No `escpos` or `nusb` crates. |
| 175 | |
| 176 | --- |
| 177 | |
| 178 | ## Planned (not implemented) |
| 179 | |
| 180 | | Feature | Notes | |
| 181 | |---------|-------| |
| 182 | | Bluetooth SPP | After OS pairing | |
| 183 | | Network TCP 9100 | Future | |
| 184 | | Printer status read | DLE EOT | |