# 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 |
