BlueGit

timfa posprint

Files

posprint / docs / PRINTING.md

PRINTING.md

PRINTING.md 4.7 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 bulletASCII *- item lines in templates
Partial cutGS V 66 0@cut in template only
BarcodeGS kNative symbologies; 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. 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

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

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

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 | ASCII `*` | `- item` lines in templates |
32| Partial cut | GS V 66 0 | `@cut` in template only |
33| Barcode | GS k | Native symbologies; raster via GS v 0 |
34| QR Code | GS ( k | Model 2; or raster GS v 0 |
35| Raster image | GS v 0 | `@image` / raster barcode / raster QR |
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 ▼
53open_printer(target) # USB-direct | Win spooler | serial
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| USB-direct (`rusb`) | USB printer-class bulk OUT (`usb_direct.rs`) |
71| Windows spooler | Raw jobs via Win32 spooler (`win_spool.rs`, Windows only) |
72| `SerialTransport` | USB-serial / CDC ports via `serialport` |
73| `MockTransport` | Tests — records bytes in `written` vec |
74
75### Discovery
76
77`list_printers()` returns, in order:
78
791. USB printer-class devices (`usb_direct`)
802. Windows spooler queues (Windows)
813. Serial ports (`serialport::available_ports()`, with VID/PID labels when available)
82
83### Serial baud rates
84
85`SerialTransport::open` tries, in order:
86
87`115200`, `9600`, `19200`, `38400`, `57600`, `4800`
88
89### `PrinterDevice`
90
91| Field | Example |
92|-------|---------|
93| `id` | `serial:COM3`, `usb:04b8:0e15:…`, `spool:POS-58` |
94| `display_name` | Human-readable label |
95| `target` | `Serial` / `UsbDirect` / `WinSpooler` |
96
97---
98
99## Print dialog (UI)
100
101- One field per unique `${Parameter}`.
102- Printer list: USB, spooler, and serial (Refresh button).
103- Optional manual serial port name.
104- While open, the main Design UI is disabled (including editor autocomplete).
105- Errors shown inline (parse, open, write, barcode validation).
106
107---
108
109## Print pipeline
110
111```
112Document body (DSL)
113 │
114 ▼
115 parse() → Document
116 │
117 ▼
118 collect_parameter_names() → UI dialog / CLI --set
119 │
120 ▼
121 substitute_document()
122 │
123 ▼
124 EscPosEncoder (in-tree)
125 │
126 ▼
127 open_printer → write_all
128```
129
130### Error handling
131
132| Condition | Behaviour |
133|-----------|-----------|
134| Parse error | Block print; show in toolbar |
135| Open failure | Message in dialog / CLI |
136| Write failure | Message in dialog / CLI |
137| Invalid barcode data | Error before write |
138| Linux serial permission | Join `dialout` group |
139
140Status polling (paper out, cover open) is **not** implemented.
141
142---
143
144## Images and rasters
145
1461. Resolve path relative to the `.pos` file (or absolute).
1472. Decode with `image`, convert to luma, scale to printable width (`chars_per_line × 12` dots).
1483. Threshold to 1-bit; emit `GS v 0` (`1D 76 30 00` + width/height LE + bitmap).
1494. Append **LF** after the raster so following content (including blank-line feeds) advances correctly.
150
151Preview draws the same bitmaps on the canvas (scaled for screen).
152
153---
154
155## Testing without hardware
156
157| Method | Location |
158|--------|----------|
159| `MockTransport` | `print/mod.rs` tests |
160| ESC/POS byte checks | `escpos.rs` tests |
161| `cargo test` | ~100 unit tests; no printer required |
162
163---
164
165## Dependencies
166
167```toml
168serialport = "4"
169rusb = "0.9"
170image = { features = ["png", "jpeg", "gif", "bmp"] }
171```
172
173On Windows, spooler access uses Win32 APIs (`winreg` / system libs as needed). No `escpos` or `nusb` crates.
174
175---
176
177## Planned (not implemented)
178
179| Feature | Notes |
180|---------|-------|
181| Bluetooth SPP | After OS pairing |
182| Network TCP 9100 | Future |
183| Printer status read | DLE EOT |