BlueGit

timfa posprint

Files

posprint / docs / PRINTING.md

PRINTING.md

PRINTING.md 5.5 KiB Download Raw

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

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 ends with LF; blank/@feed use ESC d
Raster flushLF after GS v 0Ensures spacing after images/barcodes/QR rasters
List bullet* top-level, - nested- item / - nested; hanging wrap
Inline checkboxASCII [ ] / [x][] / [x] / $[Name] — same font as text
Partial cutGS V 66 0@cut in template only
BarcodeGS H, GS h, GS w, GS kNative: HRI off by default (GS H 0); show_text=true → GS H 2. Raster via GS v 0
QR CodeGS ( kModel 2; or raster GS v 0
Raster imageGS 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<()>;
}
TypeRole
USB-direct (rusb)USB printer-class bulk OUT (usb_direct.rs)
Windows spoolerRaw jobs via Win32 spooler (win_spool.rs, Windows only)
SerialTransportUSB-serial / CDC ports via serialport
MockTransportTests — records bytes in written vec

Discovery

list_printers() returns, in order:

1. USB printer-class devices (usb_direct) 2. Windows spooler queues (Windows) 3. USB-serial ports only (SerialPortType::UsbPort — skips empty PCI/ttyS* ports common on Linux)

Serial baud rates

SerialTransport::open tries, in order:

115200, 9600, 19200, 38400, 57600, 4800

PrinterDevice

FieldExample
idserial:COM3, usb:04b8:0e15:…, spool:POS-58
display_nameHuman-readable label
targetSerial / UsbDirect / WinSpooler

---

Print dialog (UI)

  • One field per unique ${Parameter}.
  • Printer list: USB printer-class, Windows spooler (Windows), and connected USB-serial devices (Refresh button). Empty motherboard serial ports are omitted; use manual entry for those.
  • Print sits next to Refresh; close the dialog with the window ✕.
  • The printer list uses a fixed-height scroll area so long lists stay usable.
  • Optional manual serial port / queue 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_parameters() → UI dialog / CLI --set
     │  (${Name} text fields, $[Name] checkboxes)
        │
        ▼
 substitute_document()
        │
        ▼
 EscPosEncoder (in-tree)
        │
        ▼
 open_printer → write_all

Error handling

ConditionBehaviour
Parse errorBlock print; show in toolbar
Open failureMessage in dialog / CLI
Write failureMessage in dialog / CLI
Invalid barcode dataError before write
Linux serial permissionJoin dialout group

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

---

Images and rasters

1. If the path is http:// or https://, download (timeout + size limit, process cache; TLS cert verification disabled for remote logos); otherwise resolve 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).

posprint:// print links embed the .pos JSON in the URL; use remote @image https://… for logos. See POSPRINT-URL.md.

---

Testing without hardware

MethodLocation
MockTransportprint/mod.rs tests
ESC/POS byte checksescpos.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)

FeatureNotes
Bluetooth SPPAfter OS pairing
Network TCP 9100Future
Printer status readDLE EOT
Source
1# Printing subsystem
2
3Raw ESC/POS output to POS thermal printers via **USB printer-class**, **Windows spooler** (Windows), or **USB-serial**.
4
5---
6
7## Goals
8
91. Discover printers (USB-direct, Windows spooler, serial ports)
102. Let the user pick a target in the print dialog
113. Generate ESC/POS bytes from the AST (after parameter substitution)
124. Write bytes to the chosen transport (serial baud is probed)
13
14---
15
16## Protocol: ESC/POS
17
18Target **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 | `*` top-level, `-` nested | `- item` / ` - nested`; hanging wrap |
32| Inline checkbox | ASCII `[ ]` / `[x]` | `[]` / `[x]` / `$[Name]` — same font as text |
33| Partial cut | GS V 66 0 | `@cut` in template only |
34| Barcode | GS H, GS h, GS w, GS k | Native: HRI off by default (`GS H 0`); `show_text=true` → `GS H 2`. 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
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 ▼
54open_printer(target) # USB-direct | Win spooler | serial
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| 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
801. USB printer-class devices (`usb_direct`)
812. Windows spooler queues (Windows)
823. USB-serial ports only (`SerialPortType::UsbPort` — skips empty PCI/`ttyS*` ports common on Linux)
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 printer-class, Windows spooler (Windows), and connected USB-serial devices (Refresh button). Empty motherboard serial ports are omitted; use manual entry for those.
104- **Print** sits next to **Refresh**; close the dialog with the window ✕.
105- The printer list uses a fixed-height scroll area so long lists stay usable.
106- Optional manual serial port / queue name.
107- While open, the main Design UI is disabled (including editor autocomplete).
108- Errors shown inline (parse, open, write, barcode validation).
109
110---
111
112## Print pipeline
113
114```
115Document body (DSL)
116 │
117 ▼
118 parse() → Document
119 │
120 ▼
121 collect_parameters() → UI dialog / CLI --set
122 │ (${Name} text fields, $[Name] checkboxes)
123 │
124 ▼
125 substitute_document()
126 │
127 ▼
128 EscPosEncoder (in-tree)
129 │
130 ▼
131 open_printer → write_all
132```
133
134### Error handling
135
136| Condition | Behaviour |
137|-----------|-----------|
138| Parse error | Block print; show in toolbar |
139| Open failure | Message in dialog / CLI |
140| Write failure | Message in dialog / CLI |
141| Invalid barcode data | Error before write |
142| Linux serial permission | Join `dialout` group |
143
144Status polling (paper out, cover open) is **not** implemented.
145
146---
147
148## Images and rasters
149
1501. If the path is `http://` or `https://`, download (timeout + size limit, process cache; TLS cert verification disabled for remote logos); otherwise resolve relative to the `.pos` file (or absolute).
1512. Decode with `image`, convert to luma, scale to printable width (`chars_per_line × 12` dots).
1523. Threshold to 1-bit; emit `GS v 0` (`1D 76 30 00` + width/height LE + bitmap).
1534. Append **LF** after the raster so following content (including blank-line feeds) advances correctly.
154
155Preview draws the same bitmaps on the canvas (scaled for screen).
156
157`posprint://` print links embed the `.pos` JSON in the URL; use remote `@image https://…` for logos. See [POSPRINT-URL.md](POSPRINT-URL.md).
158
159---
160
161## Testing without hardware
162
163| Method | Location |
164|--------|----------|
165| `MockTransport` | `print/mod.rs` tests |
166| ESC/POS byte checks | `escpos.rs` tests |
167| `cargo test` | ~100 unit tests; no printer required |
168
169---
170
171## Dependencies
172
173```toml
174serialport = "4"
175rusb = "0.9"
176image = { features = ["png", "jpeg", "gif", "bmp"] }
177```
178
179On Windows, spooler access uses Win32 APIs (`winreg` / system libs as needed). No `escpos` or `nusb` crates.
180
181---
182
183## Planned (not implemented)
184
185| Feature | Notes |
186|---------|-------|
187| Bluetooth SPP | After OS pairing |
188| Network TCP 9100 | Future |
189| Printer status read | DLE EOT |