Thermal printer
print-to-thermal is on PATH while this plugin is enabled: a small Python program
bundled with the plugin (standard library only). It needs Python 3.9 or newer; if it
says Python is missing, help the user install it from python.org, or point
THERMAL_PYTHON at an existing one. It keeps the user's printer
settings and templates in ~/.config/thermal/ (or $THERMAL_HOME), so plugin
updates never lose them. (It is not called thermal because macOS ships an
unrelated /usr/bin/thermal that would shadow it.)
Printer connection entered at install (blank or a ${...} placeholder if
none): ${user_config.printer}
First run: set up the printer
Run print-to-thermal config. If it exits with code 3 ("not configured"), set the
printer up before printing anything. Take it a step at a time with the user:
- How is it connected? If a connection was entered at install (above),
use it and skip to step 2. Otherwise: network (Wi-Fi/Ethernet) or USB. Run
print-to-thermal discover to list CUPS queues, Windows printers and USB/serial devices. Office laser
and inkjet printers show up too: ask which one is the receipt printer, and
never send to one of those. For a
network printer, ask for its IP (often on a self-test page: hold FEED
while switching it on), or with their OK run print-to-thermal discover --scan to
look for port 9100 on the local network. The connection is one of:
tcp://<ip>:9100: a network printer
cups:<queue>: a USB printer added to CUPS (macOS/Linux) as a raw queue
win32:<printer name>: a USB printer installed in Windows (sent raw through the spooler)
/dev/usb/lp0 or a serial device: a USB printer on Linux
- Which model? Run
print-to-thermal models and pick the closest preset. Most
clones are generic-80mm or generic-58mm.
- Write the config:
print-to-thermal setup --printer <conn> --model <id>. This
creates one roll at the printer's full width.
- Measure the paper. Ask the user to load a roll, then, with their OK,
run
print-to-thermal calibrate. It prints a numbered ruler. Ask for the last number
that is fully on the paper: that is the roll's width in dots. Never guess
it, because printers do not print edge to edge.
- Record each roll they own:
print-to-thermal stock add <id>=<width_mm>:<dots>[:adhesive].
Use short, descriptive ids (receipt-80, labels-50-sticky), mark sticky
label stock adhesive, and remove the placeholder (print-to-thermal stock rm roll-80)
once a real roll is loaded (print-to-thermal stock <id>).
- Print a short test, such as the
note template, and ask how it looks.
If a connection was entered at install and differs from the one
print-to-thermal config shows, the user changed it: run print-to-thermal set connection <it>.
Settings can be changed later with print-to-thermal set <key> <value>. The keys are
connection, model, max_text_size, cutter (none, partial, full),
qr (native, raster), status and the other printer fields. Use it when a
test print shows something is off: no cut means cutter none, a missing QR
code means qr raster, and so on.
Printing
- Know the medium.
print-to-thermal stocks gives the printer's limits, every
roll with its characters per line at each text size, and which roll is
loaded.
- Check the roll when it matters. The printer cannot sense which roll is
in it, so
loaded is only what was last recorded. If the job needs a
particular stock, ask; anything that must stick needs an adhesive roll.
When they swap rolls, run print-to-thermal stock <id>.
- Compose an ad-hoc job, or use a template (
print-to-thermal templates).
- Preview.
print-to-thermal preview <job>. Fix every warning: and OVERFLOW.
- Print.
print-to-thermal print <job> checks the paper sensor (network printers
only), then sends it. "sent" means the printer accepted the bytes, not that
paper came out. Say so.
<job> is inline JSON ('{...}'), - for stdin, a .json file, or a
template name. Template values: --set key=value (JSON parses, so
--set items='["a","b"]' works) or --data '{...}'. Other flags: --stock,
--copies, --force, --dry-run, --json.
A job naming a stock other than the loaded one is refused without
--force. Name the stock when it matters, so this protects the adhesive roll.
Limits that apply to every printer
- Built-in
text sizes run from 1 up to the printer's max_text_size
(usually 4); characters per line at each size come from print-to-thermal stocks.
For anything larger, use big.
- Built-in text is ASCII only.
° — ½ é and the like are folded to ASCII
automatically. If a symbol matters, use big, which draws any character.
- Some printers leave a blank margin before the first line (
dead_zone_mm).
It is mechanical; do not try to remove it.
- Without a cutter (
cutter: none), a cut becomes a feed to the tear bar.
Job format
{ "stock": "receipt-80", "copies": 1, "cut": "partial", "feed": 3,
"blocks": [ ... ] }
stock, copies (each copy is cut separately), cut (partial|full|none)
and feed (lines before each cut) are all optional.
| block |
fields (all optional except the first) |
text |
text; size 1-max or [w,h]; bold, underline, invert; align left/center/right; bullet (hanging indent, e.g. "[ ] "); wrap (default true) |
big |
text; height (capital height in mm, default 10, shrunk to fit with a warning); fit (fill the width); sideways (a banner along the strip); align (default center). Each newline starts a new line. |
rule |
char (default -; patterns such as "= " work); size |
row |
left, right; fill (e.g. "."); size; bold. Gives Milk ........ 2 |
space |
lines or mm |
barcode |
data; symbology (CODE128 by default, plus EAN13, EAN8, UPC_A, UPC_E, CODE39, ITF, CODABAR); height mm; module 2-6; hri none/above/below/both; align. Shrinks to fit; refused if it cannot fit. |
qr |
data; module 1-16 (default 6, shrinks to fit); ec L/M/Q/H |
image |
path (CLI) or base64; width (dots or "full"); align; dither (for photos; line art looks better without it) |
cut |
kind: cut mid-job, to print several labels in one job |
A block whose text or data is empty is skipped, so optional template values
simply vanish. Unknown fields are rejected, so a typo fails loudly instead of
printing wrong.
Design tips: wider text sizes make lists readable at a glance (size 2 bold
headings, size 2 items work well on 80mm), checkboxes come from
"bullet": "[ ] ", and a big title stands out.
Templates
A template is a job plus description, params (name -> what to pass) and
defaults. Any string can hold {{name}}. A string that is exactly
"{{name}}" passes the raw value, so arrays and numbers work. An each block
loops over a list:
{ "type": "each", "items": "{{items}}", "as": "item", "blocks": [
{ "type": "row", "left": "{{index}}. {{item.name}}", "right": "{{item.qty}}", "fill": "." } ] }
Built in: shopping-list, folder-tab, item-label, note, day.
For folder labels of a given size, or a batch of them, use the folder-labels
skill instead of the folder-tab template.
print-to-thermal templates lists them with the user's own; print-to-thermal templates <name>
shows one. Save a template in ~/.config/thermal/templates/<name>.json (a
user template replaces a built-in one of the same name).
Default to ad hoc. Save a template only when the user wants to reuse a layout,
or the same kind of print keeps coming up.
Example
print-to-thermal print - <<'EOF'
{ "blocks": [
{ "type": "big", "text": "Saturday", "height": 8 },
{ "type": "rule", "char": "=" },
{ "type": "text", "text": "ERRANDS", "size": 2, "bold": true },
{ "type": "text", "text": "Hardware store", "bullet": "[ ] ", "size": 2 },
{ "type": "text", "text": "Post office", "bullet": "[ ] ", "size": 2 },
{ "type": "space" },
{ "type": "row", "left": "Eggs", "right": "2 doz", "fill": "." },
{ "type": "qr", "data": "https://example.com/list" }
] }
EOF
Over the network
print-to-thermal serve [--bind 0.0.0.0:8631] [--token T] [--allow ip,ip] runs the same
operations as an HTTP API with an OpenAPI spec (/openapi.json, Swagger UI at
/docs). When THERMAL_URL is set, call it with curl: GET /stocks,
POST /preview, POST /print?force=&dry_run=&copies=&stock= (the body is a
job, or {"template": "<name>", "data": {...}}), with
Authorization: Bearer <token> if a token is set. Over HTTP, images must be
base64. Setup is CLI-only.
1---2name: thermal3description: Print on the user's ESC/POS thermal receipt or label printer — shopping and to-do lists, agendas, jar/bin/box labels, folder tabs, notes, tickets, barcodes, QR codes and images. Compose a job from primitives (text sizes, big bitmap text, rules, rows, space, barcode, QR, image, cut), preview it against the paper, then print. Also sets the printer up the first time (find it, pick a model, measure the paper), records which roll is loaded, checks for paper, and saves reusable print templates. TRIGGER when the user asks to print something, make or print a label or sticker, print a list or receipt, label a jar/bin/folder, or mentions a thermal, receipt or label printer.4allowed-tools: Bash(print-to-thermal *)5metadata:6 source: https://skillmd.com/skills/matmar10/thermal7---89# Thermal printer1011`print-to-thermal` is on PATH while this plugin is enabled: a small Python program12bundled with the plugin (standard library only). It needs Python 3.9 or newer; if it13says Python is missing, help the user install it from python.org, or point14`THERMAL_PYTHON` at an existing one. It keeps the user's printer15settings and templates in `~/.config/thermal/` (or `$THERMAL_HOME`), so plugin16updates never lose them. (It is not called `thermal` because macOS ships an17unrelated `/usr/bin/thermal` that would shadow it.)1819Printer connection entered at install (blank or a `${...}` placeholder if20none): `${user_config.printer}`2122## First run: set up the printer2324Run `print-to-thermal config`. If it exits with code 3 ("not configured"), set the25printer up before printing anything. Take it a step at a time with the user:26271. **How is it connected?** If a connection was entered at install (above),28 use it and skip to step 2. Otherwise: network (Wi-Fi/Ethernet) or USB. Run29 `print-to-thermal discover` to list CUPS queues, Windows printers and USB/serial devices. Office laser30 and inkjet printers show up too: ask which one is the receipt printer, and31 never send to one of those. For a32 network printer, ask for its IP (often on a self-test page: hold FEED33 while switching it on), or with their OK run `print-to-thermal discover --scan` to34 look for port 9100 on the local network. The connection is one of:35 - `tcp://<ip>:9100`: a network printer36 - `cups:<queue>`: a USB printer added to CUPS (macOS/Linux) as a raw queue37 - `win32:<printer name>`: a USB printer installed in Windows (sent raw through the spooler)38 - `/dev/usb/lp0` or a serial device: a USB printer on Linux392. **Which model?** Run `print-to-thermal models` and pick the closest preset. Most40 clones are `generic-80mm` or `generic-58mm`.413. **Write the config:** `print-to-thermal setup --printer <conn> --model <id>`. This42 creates one roll at the printer's full width.434. **Measure the paper.** Ask the user to load a roll, then, with their OK,44 run `print-to-thermal calibrate`. It prints a numbered ruler. Ask for the last number45 that is fully on the paper: that is the roll's width in dots. Never guess46 it, because printers do not print edge to edge.475. **Record each roll they own:** `print-to-thermal stock add <id>=<width_mm>:<dots>[:adhesive]`.48 Use short, descriptive ids (`receipt-80`, `labels-50-sticky`), mark sticky49 label stock `adhesive`, and remove the placeholder (`print-to-thermal stock rm roll-80`)50 once a real roll is loaded (`print-to-thermal stock <id>`).516. Print a short test, such as the `note` template, and ask how it looks.5253If a connection was entered at install and differs from the one54`print-to-thermal config` shows, the user changed it: run `print-to-thermal set connection <it>`.5556Settings can be changed later with `print-to-thermal set <key> <value>`. The keys are57`connection`, `model`, `max_text_size`, `cutter` (`none`, `partial`, `full`),58`qr` (`native`, `raster`), `status` and the other printer fields. Use it when a59test print shows something is off: no cut means `cutter none`, a missing QR60code means `qr raster`, and so on.6162## Printing63641. **Know the medium.** `print-to-thermal stocks` gives the printer's limits, every65 roll with its characters per line at each text size, and which roll is66 `loaded`.672. **Check the roll when it matters.** The printer cannot sense which roll is68 in it, so `loaded` is only what was last recorded. If the job needs a69 particular stock, ask; anything that must stick needs an adhesive roll.70 When they swap rolls, run `print-to-thermal stock <id>`.713. **Compose** an ad-hoc job, or use a template (`print-to-thermal templates`).724. **Preview.** `print-to-thermal preview <job>`. Fix every `warning:` and `OVERFLOW`.735. **Print.** `print-to-thermal print <job>` checks the paper sensor (network printers74 only), then sends it. "sent" means the printer accepted the bytes, not that75 paper came out. Say so.7677`<job>` is inline JSON (`'{...}'`), `-` for stdin, a `.json` file, or a78template name. Template values: `--set key=value` (JSON parses, so79`--set items='["a","b"]'` works) or `--data '{...}'`. Other flags: `--stock`,80`--copies`, `--force`, `--dry-run`, `--json`.8182A job naming a `stock` other than the loaded one is **refused** without83`--force`. Name the stock when it matters, so this protects the adhesive roll.8485## Limits that apply to every printer8687- Built-in `text` sizes run from 1 up to the printer's `max_text_size`88 (usually 4); characters per line at each size come from `print-to-thermal stocks`.89 For anything larger, use `big`.90- Built-in text is **ASCII only**. `° — ½ é` and the like are folded to ASCII91 automatically. If a symbol matters, use `big`, which draws any character.92- Some printers leave a blank margin before the first line (`dead_zone_mm`).93 It is mechanical; do not try to remove it.94- Without a cutter (`cutter: none`), a cut becomes a feed to the tear bar.9596## Job format9798```json99{ "stock": "receipt-80", "copies": 1, "cut": "partial", "feed": 3,100 "blocks": [ ... ] }101```102103`stock`, `copies` (each copy is cut separately), `cut` (`partial`|`full`|`none`)104and `feed` (lines before each cut) are all optional.105106| block | fields (all optional except the first) |107|---|---|108| `text` | `text`; `size` 1-max or `[w,h]`; `bold`, `underline`, `invert`; `align` left/center/right; `bullet` (hanging indent, e.g. `"[ ] "`); `wrap` (default true) |109| `big` | `text`; `height` (capital height in mm, default 10, shrunk to fit with a warning); `fit` (fill the width); `sideways` (a banner along the strip); `align` (default center). Each newline starts a new line. |110| `rule` | `char` (default `-`; patterns such as `"= "` work); `size` |111| `row` | `left`, `right`; `fill` (e.g. `"."`); `size`; `bold`. Gives `Milk ........ 2` |112| `space` | `lines` or `mm` |113| `barcode` | `data`; `symbology` (CODE128 by default, plus EAN13, EAN8, UPC_A, UPC_E, CODE39, ITF, CODABAR); `height` mm; `module` 2-6; `hri` none/above/below/both; `align`. Shrinks to fit; refused if it cannot fit. |114| `qr` | `data`; `module` 1-16 (default 6, shrinks to fit); `ec` L/M/Q/H |115| `image` | `path` (CLI) or `base64`; `width` (dots or `"full"`); `align`; `dither` (for photos; line art looks better without it) |116| `cut` | `kind`: cut mid-job, to print several labels in one job |117118A block whose text or data is empty is skipped, so optional template values119simply vanish. Unknown fields are rejected, so a typo fails loudly instead of120printing wrong.121122Design tips: wider text sizes make lists readable at a glance (size 2 bold123headings, size 2 items work well on 80mm), checkboxes come from124`"bullet": "[ ] "`, and a `big` title stands out.125126## Templates127128A template is a job plus `description`, `params` (name -> what to pass) and129`defaults`. Any string can hold `{{name}}`. A string that is *exactly*130`"{{name}}"` passes the raw value, so arrays and numbers work. An `each` block131loops over a list:132133```json134{ "type": "each", "items": "{{items}}", "as": "item", "blocks": [135 { "type": "row", "left": "{{index}}. {{item.name}}", "right": "{{item.qty}}", "fill": "." } ] }136```137138Built in: `shopping-list`, `folder-tab`, `item-label`, `note`, `day`.139For folder labels of a given size, or a batch of them, use the `folder-labels`140skill instead of the `folder-tab` template.141`print-to-thermal templates` lists them with the user's own; `print-to-thermal templates <name>`142shows one. Save a template in `~/.config/thermal/templates/<name>.json` (a143user template replaces a built-in one of the same name).144145Default to ad hoc. Save a template only when the user wants to reuse a layout,146or the same kind of print keeps coming up.147148## Example149150```sh151print-to-thermal print - <<'EOF'152{ "blocks": [153 { "type": "big", "text": "Saturday", "height": 8 },154 { "type": "rule", "char": "=" },155 { "type": "text", "text": "ERRANDS", "size": 2, "bold": true },156 { "type": "text", "text": "Hardware store", "bullet": "[ ] ", "size": 2 },157 { "type": "text", "text": "Post office", "bullet": "[ ] ", "size": 2 },158 { "type": "space" },159 { "type": "row", "left": "Eggs", "right": "2 doz", "fill": "." },160 { "type": "qr", "data": "https://example.com/list" }161] }162EOF163```164165## Over the network166167`print-to-thermal serve [--bind 0.0.0.0:8631] [--token T] [--allow ip,ip]` runs the same168operations as an HTTP API with an OpenAPI spec (`/openapi.json`, Swagger UI at169`/docs`). When `THERMAL_URL` is set, call it with curl: `GET /stocks`,170`POST /preview`, `POST /print?force=&dry_run=&copies=&stock=` (the body is a171job, or `{"template": "<name>", "data": {...}}`), with172`Authorization: Bearer <token>` if a token is set. Over HTTP, images must be173`base64`. Setup is CLI-only.