# Printing subsystem Raw ESC/POS output to POS thermal printers via **USB printer-class**, **Windows spooler** (Windows), **USB-serial**, or **Classic Bluetooth SPP** after OS pairing. --- ## Goals 1. Discover printers (USB-direct, Windows spooler, USB-serial, paired Bluetooth SPP) 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 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 │ ▼ 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 and paired Classic Bluetooth SPP 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. USB-serial (`SerialPortType::UsbPort`) and OS-paired Classic Bluetooth SPP (`BluetoothPort`, plus Linux `/dev/rfcomm*`). Empty PCI/`ttyS*` ports are skipped. BLE is not scanned. ### Serial baud rates `SerialTransport::open` tries, in order: `115200`, `9600`, `19200`, `38400`, `57600`, `4800` ### `PrinterDevice` | Field | Example | |-------|---------| | `id` | `serial:COM3`, `serial:COM5`, `usb:04b8:0e15:…`, `spool:POS-58` | | `display_name` | Human-readable label (`COM5 — Bluetooth` for paired SPP) | | `target` | `Serial` / `UsbDirect` / `WinSpooler` | --- ## Print dialog (UI) - One field per unique `${Parameter}`. - Printer list: USB printer-class, Windows spooler (Windows), USB-serial, and paired Classic Bluetooth SPP serial ports (Refresh button). Empty motherboard serial ports are omitted; use manual entry for those. BLE is out of scope. - **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. - 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; TLS cert verification disabled for remote logos); 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. --- ### Classic Bluetooth SPP (implemented) Pair the printer in the OS first. Posprint does not scan, pair, or talk BLE/GATT. | Platform | After pairing | Discovery | |----------|---------------|-----------| | Windows | Bluetooth SPP virtual COM (`COMx`) | `SerialPortType::BluetoothPort` | | Linux | RFCOMM node (often `/dev/rfcomm0`) | `BluetoothPort`, or `/dev/rfcomm*` if typed Unknown | Printing reuses `SerialTransport` (same baud probe as USB-serial). Manual port entry still works (`COM5`, `/dev/rfcomm0`). --- ## Planned (not implemented) | Feature | Notes | |---------|-------| | BLE (GATT) | Out of scope — Classic SPP only | | Network TCP 9100 | Future | | Printer status read | DLE EOT |