BlueGit

timfa posprint

Files

posprint / docs / PRINTING.md

PRINTING.md

PRINTING.md 4.8 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
Inline checkboxESC & user-defined Font A chars (2 cells)[] / [ ] / [x]; surrounding text uses native font
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| 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
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. 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```
113Document 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
141Status polling (paper out, cover open) is **not** implemented.
142
143---
144
145## Images and rasters
146
1471. Resolve path relative to the `.pos` file (or absolute).
1482. Decode with `image`, convert to luma, scale to printable width (`chars_per_line × 12` dots).
1493. Threshold to 1-bit; emit `GS v 0` (`1D 76 30 00` + width/height LE + bitmap).
1504. Append **LF** after the raster so following content (including blank-line feeds) advances correctly.
151
152Preview 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
169serialport = "4"
170rusb = "0.9"
171image = { features = ["png", "jpeg", "gif", "bmp"] }
172```
173
174On 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 |