# 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 ```rust 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), and never exceed the effective page 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 | Print | |----------------|---------|-------| | `autoscale` | Scales to panel width | Full effective print width | | `fixed` | Scaled by dot ratio | Full effective print 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 ```toml serialport = "4" image = { features = ["png", "jpeg", "gif", "bmp"] } ``` No `escpos`, `nusb`, or `rusb` crates.