# Printing subsystem Raw ESC/POS output to POS thermal printers via **USB printer-class**, **Windows spooler** (Windows), **USB-serial**, or **LAN TCP 9100** (optional). --- ## Goals 1. Discover printers (USB-direct, Windows spooler, serial ports, optional LAN TCP 9100) 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; LAN uses TCP) --- ## 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 | `*` top-level, `-` nested | `- item` / ` - nested`; hanging wrap | | Inline checkbox | ASCII `[ ]` / `[x]` | `[]` / `[x]` / `$[Name]` — same font as text | | Partial cut | GS V 66 0 | `@cut` in template only | | 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 | | 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 | network TCP │ ▼ 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 | |------|------| | 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` | | `NetworkTransport` | Raw ESC/POS over TCP (default port **9100**, `network.rs`) — not CUPS/IPP | | `MockTransport` | Tests — records bytes in `written` vec | ### Discovery `list_local_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) When **LAN printers** are enabled in Settings (`lan_printers_enabled`, default **off**), the print dialog additionally: 1. Validates the durable **LAN cache** (`lan_printer_cache` in config) with short TCP probes and shows hits immediately with local devices 2. Scans local IPv4 subnets for open TCP **9100** in the background, merges results, and updates the cache ### 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`, `net:192.168.1.50:9100` | | `display_name` | Human-readable label | | `target` | `Serial` / `UsbDirect` / `WinSpooler` / `Network` | --- ## Print dialog (UI) - One field per unique `${Parameter}`. - Printer list: USB printer-class, Windows spooler (Windows), connected USB-serial devices, and (if enabled) LAN TCP 9100 printers (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 / LAN `host` or `host:9100`. - 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 | 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. If the path is `http://` or `https://`, download (timeout + size limit, process cache); 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](POSPRINT-URL.md). --- ## 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 ```toml 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; evaluate already-connected devices only | | Printer status read | DLE EOT |