# 0016. Printing

- Status: Accepted
- Date: 2026-10-27

## Context

Shops use many brands of thermal printer, mostly cheap ESC/POS models from China plus Epson,
and Sunmi Android terminals with built-in printers. Printer vendors ship SDKs, but several are
closed binaries or carry "all rights reserved" licences that conflict with the AGPL. Printers also
disagree on less common commands, and they go offline, run out of paper or get unplugged during
service.

## Decision

- OpenKedai builds ESC/POS bytes itself (`packages/escpos`) from a small command subset that
  common printers share. Each job starts by resetting the printer and leaving Chinese
  double-byte mode (`ESC @`, `FS .`); text is ASCII, with accents and symbols transliterated.
- Network printers get raw bytes over TCP port 9100 from our own native module (Network.framework
  on iOS, `java.net.Socket` on Android). Bytes go in 4 KB chunks with short pauses, and every
  connect and send has a timeout.
- Sunmi built-in printers go through Sunmi's SDKs (both Apache-2.0): `com.sunmi:printerlibrary`
  for the classic print service, with `com.sunmi:printerx` as the fallback for newer devices
  such as the P-series. No other vendor SDK is used: the Epson ePOS SDK and closed binaries such as
  `libPrinterSDK.a` are not AGPL-compatible, and raw TCP works on those printers anyway.
- QR codes print as images (`GS v 0`) by default, because not every printer has a QR command;
  the printer's own QR command is an option.
- Every printer's profile (characters per line, cutter, QR mode, drawer) is a setting with
  defaults by paper width (ADR 0014).
- All printing goes through a stored queue that sends one job at a time per printer, in order,
  and retries with growing delays. Checkout and kitchen actions only add jobs to the queue, so a
  printer can never block a sale (ADR 0002).

## Consequences

- No printer app or driver to install, and nothing proprietary in the build except Sunmi's
  Apache-2.0 libraries (listed in `THIRD_PARTY_NOTICES.md`).
- Chinese text needs a raster fallback or a printer font (M8); until then it prints as "?".
- Printer status queries (`DLE EOT`) aren't used yet. A failed connection is the offline signal.
- Before targeting Android 17 (SDK 37), the app must request `ACCESS_LOCAL_NETWORK`. Without it,
  network printing fails with timeouts that look like an offline printer.