Escpos skill

ESC/POS Printer Skill

When to activate: Use this skill whenever the user needs to generate, debug, or reason about ESC/POS printer command streams. Triggers include: thermal receipt printers, POS printers, ESC/POS commands, byte sequences for printing, barcode printing, QR code printing, cash drawer control, paper cutting, receipt layout, label printing, page mode, NV images, or any mention of printer commands like LF, GS V, GS k, DLE EOT, or similar. Use this skill even when the user asks general questions like "how do I center text on a receipt" or "how do I print a logo" -- if it involves a thermal printer, always consult this skill first.

A structured reference for generating correct ESC/POS command streams for thermal receipt and label printers. All command data is sourced from the canonical ESC/POS command PDF.

How to use this skill: Start with the Workflow Patterns section to understand job structure, then look up specific commands in the Quick Command Index. For full parameter details and edge cases, read the appropriate reference file from references/.

---

Workflow Patterns

Standard Receipt Job

ESC @           ← Initialize (safe start)
ESC t 0         ← Set code page (PC437 default)
ESC a 1         ← Center alignment (for header)
[logo or header text + LF]
ESC a 0         ← Left alignment (for body)
[line items with HT tab stops or ESC $ absolute positioning]
ESC a 2         ← Right alignment (for totals, if needed)
[totals]
ESC d 3         ← Feed 3 lines before cut
GS V 1          ← Partial cut

Page Mode Label

ESC @           ← Initialize
ESC L           ← Enter page mode
ESC T 0         ← Direction: left-to-right, upper-left start
ESC W [xL xH yL yH dxL dxH dyL dyH]  ← Define print area
[compose content using GS $, GS \, ESC $, ESC \]
FF              ← Print and exit page mode

Barcode Block

GS H 2          ← HRI below barcode
GS f 0          ← HRI font A
GS h 80         ← Height 80 dots
GS w 3          ← Width multiplier 3
GS k [type] [data] NUL  ← Print barcode

QR Code Block

GS ( k cn=49 fn=65: Set QR model (model 2 typical)
GS ( k cn=49 fn=67: Set module size (dot width)
GS ( k cn=49 fn=69: Set error correction level
GS ( k cn=49 fn=80: Store QR data (compute pL/pH from payload length + 3)
GS ( k cn=49 fn=81: Print QR code

Logo Print (NV Image)

FS q n [image definitions]  ← Define NV image (burns NV memory — max 10x/day)
[power-cycle / ESC @ after write completes]
FS p n m                    ← Print the stored NV image slot n

Cash Drawer

ESC p m t1 t2   ← Buffered pulse (fires after preceding print job finishes)
DLE DC4 n m t   ← Real-time pulse (fires immediately, bypasses buffer)

---

Modes: Standard vs Page

Concern	Standard Mode	Page Mode
Enter / Exit	Default; ESC S re-enters	ESC L to enter, FF to print+exit, ESC S to abort
Positioning	ESC $ (abs), ESC \ (rel), ESC a (justify)	GS $ (abs secondary axis), GS \ (rel secondary axis)
Motion axis	Always horizontal = paper width	Depends on ESC T orientation
Images	ESC *, GS *, GS /, FS p	GS v 0 only; FS p/q not available
Justification	Live	ESC a buffers flag only; does not apply

---

Quick Command Index

Look up a command here, then read the reference file for full byte sequences and parameter details.

Control & Flow (references/01-control-flow.md)

Command	Hex	Description
HT	09	Horizontal tab to next configured tab stop
LF	0A	Print buffer and advance one line
CR	0D	Carriage return (device-dependent; prefer LF)
FF	0C	Print page-mode buffer and return to standard mode
CAN	18	Discard page-mode buffer without printing
ESC @	1B 40	Initialize printer to power-on defaults
ESC FF	1B 0C	Print page-mode buffer without exiting page mode
ESC L	1B 4C	Enter page mode
ESC S	1B 53	Exit page mode, discard page buffer
ESC i	1B 69	Full paper cut (requires auto cutter)
ESC m	1B 6D	Partial paper cut (requires auto cutter)
GS V	1D 56 m [n]	Buffered cut with optional pre-feed (partial cut only via GS V)
GS :	1D 3A	Start/end macro definition (confirm hardware support)
GS ^	1D 5E r t m	Execute macro r times (confirm hardware support)

Text Formatting (references/02-text-formatting.md)

Command	Hex	Description
ESC !	1B 21 n	Combined mode byte: font, bold, width, height, underline
ESC E	1B 45 n	Emphasized (bold) on/off
ESC G	1B 47 n	Double-strike on/off (same visual as ESC E on this device)
ESC M	1B 4D n	Select font A or B
ESC -	1B 2D n	Underline on/off with thickness selection
ESC SP	1B 20 n	Set right-side character spacing
ESC t	1B 74 n	Select character code table (code page)
ESC R	1B 52 n	Select international character set variant
ESC V	1B 56 n	90-degree clockwise character rotation on/off
ESC {	1B 7B n	Upside-down line printing on/off
GS !	1D 21 n	Independent width and height multipliers (1×–8×)
GS B	1D 42 n	White/black reverse printing on/off
ESC %	1B 25 n	Enable/disable user-defined character set
ESC &	1B 26 y c1 c2 …	Define custom RAM glyphs
ESC ?	1B 3F n	Cancel a single user-defined character slot

Positioning & Layout (references/03-positioning-layout.md)

Command	Hex	Description
ESC 2	1B 32	Restore default line spacing (≈4.23 mm)
ESC 3	1B 33 n	Set custom line spacing in motion units
ESC D	1B 44 … 00	Define horizontal tab stop positions
ESC $	1B 24 nL nH	Set absolute print position from line start
ESC \	1B 5C nL nH	Set relative print position
ESC a	1B 61 n	Justify: left / center / right
ESC J	1B 4A n	Print and feed n motion units (one-shot)
ESC d	1B 64 n	Print and feed n whole lines
ESC T	1B 54 n	Set page-mode print direction and start corner
ESC W	1B 57 …	Set page-mode print area rectangle
GS $	1D 24 nL nH	Absolute secondary-axis position (page mode)
GS \	1D 5C nL nH	Relative secondary-axis position (page mode)
GS L	1D 4C nL nH	Set left margin (standard mode)
GS W	1D 57 nL nH	Set printing area width (standard mode)
GS P	1D 50 x y	Set horizontal and vertical motion units

Hardware & Status (references/04-hardware-status.md)

Command	Hex	Description
DLE EOT	10 04 n	Real-time status query: printer/offline/error/paper
DLE ENQ	10 05 n	Real-time error recovery after auto-cutter fault
DLE DC4	10 14 01 m t	Real-time drawer-kick pulse
ESC =	1B 3D n	Enable/disable printer (print-data gate)
ESC p	1B 70 m t1 t2	Buffered drawer-kick pulse
ESC c 3	1B 63 33 n	Select sensors that drive paper-end output signal
ESC c 4	1B 63 34 n	Select sensors that stop printing
ESC c 5	1B 63 35 n	Enable/disable panel FEED button
GS a	1D 61 n	Enable/configure Automatic Status Back (ASB)
GS r	1D 72 n	Transmit paper sensor status on demand
GS I	(not in PDF)	Transmit printer ID (device docs required)

Images & Graphics (references/05-images-graphics.md)

Command	Hex	Description
ESC *	1B 2A m nL nH d…	Inline column-format bit image
GS *	1D 2A x y d…	Define downloaded (RAM) bit image
GS /	1D 2F m	Print downloaded (RAM) bit image
GS v 0	1D 76 30 m dxL dxH dyL dyH d…	Raster-format image (standard mode only)
FS p	1C 70 n m	Print NV bit image from slot n
FS q	1C 71 n …	Define NV bit image batch (≤10 writes/day)

Barcodes & 2D Symbols (references/06-barcodes-2d.md)

Command	Hex	Description
GS k	1D 6B m d… NUL / m n d…	Print 1D barcode
GS H	1D 48 n	HRI position: none / above / below / both
GS f	1D 66 n	HRI font selection
GS h	1D 68 n	Barcode height in dots
GS w	1D 77 n	Barcode module width
GS x	(not in PDF)	Barcode horizontal size (device docs required)
GS ( k cn=49 fn=65	1D 28 6B … 31 41	QR: select model
GS ( k cn=49 fn=67	1D 28 6B … 31 43	QR: set module size
GS ( k cn=49 fn=69	1D 28 6B … 31 45	QR: set error correction level
GS ( k cn=49 fn=80	1D 28 6B pL pH 31 50 30 d…	QR: store data
GS ( k cn=49 fn=81	1D 28 6B 03 00 31 51 30	QR: print stored symbol
GS ( k cn=48 fn=65–69	1D 28 6B … 30 41–45	PDF417: columns / rows / module width / module height / error correction
GS ( k cn=48 fn=80/81	1D 28 6B … 30 50/51	PDF417: store data / print

---

Common Pitfalls

• CR vs LF: Always use LF (0A) for line advances. CR behavior depends on the printer's auto-LF DIP setting.
• ESC @ scope: Resets runtime state but does NOT clear the receive buffer, NV images, or macro definitions.
• pL/pH calculation: For GS ( k payload fields — length = data_bytes + 3; then pL = length % 256, pH = length / 256.
• Motion units: Commands that specify distances in motion units (ESC 3, ESC J, ESC $, etc.) depend on the current GS P setting. Default: horizontal = 1/180 in, vertical = 1/360 in.
• Page mode commands that silently buffer: ESC a, ESC V, GS L, GS W in page mode only update flags — they don't execute.
• NV image write limit: FS q rewrites NV flash. Limit writes to ≤10/day to avoid wear.
• Real-time vs buffered commands: DLE-family commands (DLE EOT, DLE ENQ, DLE DC4) bypass the print buffer and execute immediately. All ESC/GS commands are buffered.
• GS V only partial-cuts: GS V does not support full cut on this printer family. Use m=1 or m=49 for partial cut. For full cut use ESC i (1B 69); for a simpler partial cut use ESC m (1B 6D). Both require an auto cutter.

---

Reference Files

Read the relevant file for full JSON command objects with byte sequences, parameter ranges, bit maps, and agent instructions:

File	Contents
references/01-control-flow.md	HT, LF, CR, FF, CAN, ESC @, ESC FF, ESC L, ESC S, ESC i, ESC m, GS V, GS :, GS ^
references/02-text-formatting.md	ESC !, ESC E, ESC G, ESC M, ESC -, ESC SP, ESC t, ESC R, ESC V, ESC {, GS !, GS B, ESC %, ESC &, ESC ?
references/03-positioning-layout.md	ESC 2, ESC 3, ESC D, ESC $, ESC , ESC a, ESC J, ESC d, ESC T, ESC W, GS $, GS , GS L, GS W, GS P
references/04-hardware-status.md	DLE EOT, DLE ENQ, DLE DC4, ESC =, ESC p, ESC c 3, ESC c 4, ESC c 5, GS a, GS r, GS I
references/05-images-graphics.md	ESC *, GS *, GS /, GS v 0, FS p, FS q
references/06-barcodes-2d.md	GS k, GS H, GS f, GS h, GS w, all GS ( k QR and PDF417 subcommands