# 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 | 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 k | Native symbologies; 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 │ ▼ 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` | | `MockTransport` | Tests — 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` | Field | Example | |-------|---------| | `id` | `serial:COM3`, `usb:04b8:0e15:…`, `spool:POS-58` | | `display_name` | Human-readable label | | `target` | `Serial` / `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_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 | | Network TCP 9100 | Future | | Printer status read | DLE EOT |