TSPL Command Reference

Clears the image buffer before drawing a new label. Think of it as pressing "New Document" — it erases any previous content so you start fresh. Every label should begin with CLS after SIZE and GAP.

Triggers printing of the label. The first parameter sets the number of label sets; the optional second sets the number of copies per set. This is always the last command in a TSPL label — like pressing "Print".

Feeds the label stock forward by the specified number of dots. Useful for advancing past a label without printing, or for calibration.

Feeds the media backward by `n` dots (TSPL2 PG §BACKFEED p22–23). Range 1–9999. Used to retract the label after printing so the tear-off or cutter position is correct. TSPL printers use the alias `BACKUP n` for the same semantic (BACKFEED is the TSPL2 spelling; BACKUP is the older TSPL one). Conversion: at 200 DPI, 1 mm = 8 dots; at 300 DPI, 1 mm = 12 dots. ⚠️ Inappropriate values can cause paper jam or media wrinkle.

Advances the media to the start of the next label (TSPL2 PG §FORMFEED p24). The printer uses the GAP or BLINE sensor to detect the boundary and stops there. Takes no parameters. Runtime hardware behaviour; no SVG rendering effect.

Feeds the media until the internal sensor finds the next label origin (TSPL2 PG §HOME p25–26). Whether the printer back-feeds or feed-forwards to home depends on the per-model behaviour table on PG p25. Takes no parameters. ⚠️ `SIZE` and `GAP` (or `BLINE`) must have been issued first — HOME without prior geometry definition produces undefined behaviour. Runtime hardware behaviour; no SVG rendering effect.

Triggers the printer to print a diagnostic page covering its current configuration, firmware version, dot/line counters, and sensor state (TSPL2 PG §SELFTEST p31). Takes no parameters. Per-printer support table on PG p31 lists which TTP / TDP / M23 series models honour the command. Runtime hardware behaviour; the playground can't simulate a real self-test page (output depends on live printer state and counters).

⚠️ Factory-reset opcode — clears all `SET *` settings, downloaded fonts/images, and stored programs. Takes no parameters. Not in the 2009 TSPL2 PG; appears in later TSC firmware addenda for the TX/TE/MH-series. On models that don't expose the opcode, the equivalent recovery procedure is "hold FEED during power-on" (per the DOWNLOAD section's AUTO.BAS-disable note on PG p81). Runtime hardware behaviour; no SVG rendering effect. Use with care — this is destructive and irreversible.

Marks the end of a stored program. When downloading label templates to the printer's memory, EOP signals where the program ends.

Triggers the printer's beeper for a tone at the specified level and duration. TSPL2 PG §SOUND p28. `level` is the sound level / tone (0–9, 10 discrete steps), `interval` is the timing control (1–4095). Chain multiple SOUND lines to play a tune. No visual rendering effect — runtime hardware behaviour. Useful for signalling end-of-batch or alerting the operator.

Sets the width and height of the label. You can specify the dimensions in mm (millimetres) or inch. This must be the first configuration command — it tells the printer how big the label is.

Sets the gap distance between labels and the offset from the gap to the start of the printable area. The gap is the transparent space between die-cut labels on a roll.

Configures black-mark media mode and extra-feeding offset (TSPL2 PG §BLINE p8). Used instead of GAP for continuous media with black registration marks printed on the backing. `m` is the height of the black mark (0–1 inch, or 0–25.4 mm). `n` is extra label-feeding length after the mark (0 to label-length; `0,0` = continuous label). Two forms: bare numbers = inches; numbers followed by ` mm` (with a leading space) = millimetres. ⚠️ When changing the sensor type from "GAP" to "Black Mark", BLINE **must** be sent to the printer first — before SIZE / GAP / TEXT. Engine-recognised but no visible SVG effect today (the playground treats labels as already-isolated).

Sets the reference origin point for all coordinates on the label. All subsequent X,Y positions are relative to this point. It is like setting page margins — shifting the entire design.

Sets the print direction. 0 = head moves forward (default), 1 = head moves backward. The optional second parameter mirrors the output.

⚠️ Despite the historical 'OFFSET' name, this is NOT a horizontal coordinate offset — for that, use REFERENCE (origin shift) or SHIFT (vertical translate). TSPL2 §OFFSET p9 defines it as the **selective extra label-feeding length** the printer takes on each form-feed, used in peel-off and cutter modes to adjust where the label stops. The printer back-tracks this extra length before the next print run. Range −1 ≤ m ≤ 1 (inch). Two forms: bare number = inches; followed by ` mm` (with leading space) = millimetres. ⚠️ An out-of-range or otherwise inappropriate value may cause a paper jam. Engine-recognised but no SVG effect today (playground does not simulate the feed/back-feed cycle).

Shifts the entire imaged label vertically by `n` dots (positive or negative). Used to align with pre-printed stock, correct registration drift, or fine-tune the print position without re-issuing every coordinate. TSPL2 PG §SHIFT p15–16: range is ±203 dots on 200 DPI printers, ±300 on 300 DPI printers (max 1 inch absolute). A positive value moves the label further from the printing direction; negative moves it toward.

Draws a text field at the specified position. You choose the font, rotation, and enlargement multipliers. TSPL combines position, font, and text data in a single command — unlike SBPL which uses separate commands for each.

Draws a rectangle (box) from the top-left corner (x1,y1) to the bottom-right corner (x2,y2) with the specified line thickness. An optional radius parameter rounds the corners.

Draws a filled rectangular bar (solid black) at the specified position with the given width and height. Use this for solid divider lines, section fills, or thick separators.

Inverts the specified rectangular area on the label — black becomes white and white becomes black. Use it over text to create white-on-black reversed text blocks.

Erases (clears to white) the specified rectangular area in the image buffer. Anything previously drawn in that area is removed. Per TSPL2 PG §ERASE (p43); the PG's canonical example draws BAR 100,100,300,300 then ERASE 150,150,200,200 to carve a hole out of the centre — document order matters, since ERASE paints over earlier draw commands.

Draws a straight line from (x1,y1) to (x2,y2) with the given stroke thickness. Useful for crosses, voided-label diagonals, and quick separator strokes.

Draws a multi-line text block with automatic word-wrap inside a width × height bounding box. Like TEXT but words break at whitespace once they would exceed `width`, and the engine clips at `height` once `floor(height / fontHeight)` lines have been laid out. BLOCK is a TSPL2 firmware addendum (TX/TE/MH-series) — not in the 2009 PG.

Draws a circle. (x,y) anchors the upper-left corner of the bounding box — not the centre — so the rendered centre lands at (x + diameter/2, y + diameter/2). Per TSPL2 PG §CIRCLE (p41).

Draws an ellipse inside a width × height bounding box. Like CIRCLE, (x,y) anchors the upper-left corner of the bounding box — not the centre — so the rendered centre lands at (x + width/2, y + height/2). ELLIPSE is a TSC firmware addendum (TX/TE/MH-series) — not in the 2009 TSPL2 PG.

Draws a 1D barcode at the specified position. The "type" string selects the symbology — 30 values are valid per TSPL2 PG §BARCODE, covering Code 128, Code 39, EAN/UPC families, CODABAR, ITF, MSI, Plessey, and US/Chinese postal codes. The engine validates the type at parse time and emits a "did you mean" diagnostic on unknown values.

Draws a QR code at the specified position. You control the error correction level, cell size, encoding mode, and rotation. QR codes can store URLs, text, and other data.

Draws a Data Matrix ECC 200 symbol — the compact square 2D barcode used for pharmaceutical labelling, automotive parts marking, and unit identification. (x,y) anchors the upper-left of the bounding rectangle; width × height define the maximum area the symbol may occupy. Real DataMatrix encoding is performed via `@rfid-me/epc-parser`. Per TSPL2 PG §DMATRIX (p47–48).

Dispatches an RFID Gen2 tag operation. The first word after RFID picks the action — READ pulls data out of a memory bank, WRITE encodes data into a bank, LOCK applies a Gen2 lock policy, KILL irreversibly disables the tag, and PERMALOCK irreversibly locks a bank. The bank selector (in quotes) is one of "EPC", "USER", "TID", or "RESERVED". This command only works on TSPL2 printers with an RFID head fitted (e.g. TSC TTP-247R, TTP-2410MT, MH-241).

Reads `<length>` bytes from `<bank>` starting at byte `<offset>` (TSPL2 PG §RFID READ p113). Offset and length are byte counts, not word counts. The read result is returned to the host as a hex string over the back-channel and may be displayed on the printer LCD on firmware that supports it. Engine-recognised but no SVG output — RFID operations don't produce label content.

Encodes `<hex-data>` into `<bank>` starting at byte `<offset>` (TSPL2 PG §RFID WRITE p114). `<hex-data>` is a hex-character string — each pair of hex chars = 1 byte. EPC bank typically takes 24 hex chars for the 96-bit SGTIN-96 encoding. If `<data>` length doesn't match the bank's word boundary, the write is padded or truncated per the Gen2 spec. Note: the TID bank is factory-locked and not writable — the engine emits a warning when targeting it.

Applies a Gen2 access-policy lock to `<bank>` using the 32-bit access password (TSPL2 PG §RFID LOCK p116). `<password>` is 8 hex characters. `<policy>` is the Gen2 lock-action enum (0–3). Policy 3 is irreversible (use `RFID PERMALOCK` as the convenience wrapper). Note: the RESERVED bank exposes two named partitions on some firmware — `"KILL"` for the kill-password area and `"ACCESS"` for the access-password area.

⚠️ **Permanently and irreversibly disables the tag — cannot be undone.** Issues the Gen2 Kill command using the tag's 32-bit kill password (TSPL2 PG §RFID KILL p118). `<kill-password>` is 8 hex characters. A non-zero kill password is required by the Gen2 spec — the tag will reject KILL if its kill-password is all-zero (the engine surfaces this as a diagnostic). The kill password must have been previously written into the RESERVED bank (bytes 0–3) and is typically locked at the same time. Once successfully killed, the tag is permanently silent — no further reads or writes are possible. Used at end-of-life destruction stations for items leaving the supply chain.

⚠️ **Irreversibly locks `<bank>` — the bank cannot be unlocked again.** Convenience wrapper for `RFID LOCK "<bank>", "<password>", 3` (Gen2 policy 3 = permanently-locked). `<password>` is the 8-hex-character (32-bit) access password. After successful execution, the bank's lock state cannot be changed — subsequent `RFID LOCK` or `RFID PERMALOCK` calls against that bank will fail.

Sets the print darkness (density). Higher values produce darker output. The range is 0-15. Start at 8 and adjust up or down based on scan results and visual quality.

Sets the print speed in inches per second. Higher speeds are faster but may reduce print quality. Available speeds depend on your printer model.

Selects the character encoding for TEXT data (TSPL2 PG §CODEPAGE p18–19). Different code pages support different glyph sets — critical for international characters. Default at power-on is `437` (US OEM). The PG enumerates four families: 7-bit national variants (USA / BRI / GER / FRE / DAN / ITA / SPA / SWE / SWI), 8-bit DOS codepages (437 / 850 / 852 / 860 / 863 / 865 / 857), Windows codepages (1250 / 1252 / 1253 / 1254 / WPC1251 / WPC1255 / WPC1257 / 866), plus per-model UTF-8 / CJK additions in the model-specific appendix. Engine-recognised but doesn't currently apply byte→glyph mapping in TEXT (always passes through UTF-8/ASCII). Follow-up tracked for the mapping work.

Generic printer-configuration dispatcher (TSPL2 PG §SET p132–148). The first word after SET picks the setting being changed. Engine-recognised sub-actions cover the full PG-documented set except GAP, which requires lexer-mode disambiguation (tracked separately). All SET settings are persistent across power cycles unless the sub-page says otherwise (RIBBON is non-persistent). Engine-recognised but not rendered — labels with SET configure the printer hardware rather than producing label content.

Toggles the printer's peel-off mode (TSPL2 PG §SET p142). When ON, the printer waits for the operator to remove each label from the liner before printing the next; when OFF, labels print continuously. Persistent across power cycles.

Toggles the printer's tear-off behaviour (TSPL2 PG §SET p143–144; alias STRIPER on some models). When ON, the printer advances each label past the tear bar after printing so the operator can tear it off cleanly; when OFF, the label stops at the print head. Persistent across power cycles.

Configures the optional auto-cutter (TSPL2 PG §SET p133). OFF disables the cutter; BATCH cuts once at the end of a print batch; a numeric argument cuts every N labels. Persistent across power cycles. Only effective on cutter-equipped printers — sending this to a non-cutter model is a recognised no-op.

Toggles the head-open sensor (TSPL2 PG §SET p147). When ON (the safe default), the printer halts printing if the print head is opened mid-job; when OFF, the sensor is ignored. Persistent across power cycles. **Do not disable in production** — head-open during printing can damage the print head or smear ink/ribbon.

Toggles the ribbon-detect sensor (TSPL2 PG §SET p148). When ON, the printer halts if it doesn't detect a thermal-transfer ribbon (i.e. assumes thermal-transfer mode); when OFF, the printer assumes direct-thermal media and ignores the ribbon sensor. **Non-persistent — reverts on power cycle.** This is the only SET sub-action whose value isn't kept across reboots.

Initialises or increments a printer-side counter variable (TSPL2 PG §SET COUNTER p132). `@n` is the counter index (typically `@0`–`@9`); `step` is the increment applied between labels in a print batch. Counter values are referenced from TEXT/BARCODE payloads via the `@n` placeholder. Useful for serialised label batches without round-tripping to the host for each value. Engine recognises the command but doesn't currently model the `@n` placeholder substitution in TEXT/BARCODE — placeholder rendering is a separate feature.

Configures the partial-cutter accessory (TSPL2 PG §SET PARTIAL_CUTTER p134). Sibling of `SET CUTTER` — partial cut leaves a small tab so the next label hangs from the previous, useful for catalog/peel-off workflows. OFF disables the partial cutter; BATCH cuts once at the end of a print batch; a numeric argument cuts every N labels. Persistent across power cycles. Only effective on partial-cutter-equipped hardware — sending this to a non-cutter model is a recognised no-op.

Toggles automatic back-feed after each print (TSPL2 PG §SET BACK p135). When ON, the printer retracts to its print-start position after each label — useful for peel-off and tear-off workflows where the label needs to be repositioned before the next print. Persistent across power cycles. Distinct from the top-level `BACKFEED n` command, which is a one-shot retract by N dots.

Remaps the printer's front-panel KEY1 to a chosen action (TSPL2 PG §SET KEY1 p136–137). Useful for tuning printer behaviour to a specific deployment — e.g. mapping KEY1 to PAUSE for an interactive workflow, or to CALIBRATION for a maintenance role. Persistent across power cycles.

Remaps the printer's front-panel KEY2 to a chosen action (TSPL2 PG §SET KEY2 p137–138). Identical action enum to `SET KEY1`. Persistent across power cycles. Useful for printers with a two-key front panel where each key gets a distinct workflow role (e.g. KEY1 = PAUSE, KEY2 = FEED).

Toggles external-rewinder support (TSPL2 PG §SET REWIND p139). When ON, the printer drives an attached external-rewinder accessory; when OFF, no rewinder signalling is generated. Persistent across power cycles. Only effective on rewinder-equipped deployments — sending this to a printer without the accessory is a recognised no-op.

Configures the front-panel print-key behaviour (TSPL2 PG §SET PRINTKEY p140). OFF disables the print key; ON makes a single press print one label; AUTO triggers auto-repeat printing while the key is held; a numeric value `<n>` prints N labels per press. Persistent across power cycles.

Alias of `SET TEAR` on some firmware revisions (TSPL2 PG §SET STRIPER p143–144). Same semantics, alternate keyword surfaced for models that ship with a "striper" label on the front panel. See `SET TEAR` for the canonical documentation — anything you can do with one, you can do with the other. Persistent across power cycles.

Caps the distance the printer feeds while searching for the next label gap during calibration / HOME. TSPL2 PG §LIMITFEED p30. Prevents runaway feeds on mis-cut or misaligned stock. Default 10 inches at boot. Two forms: `LIMITFEED n` (inches, English system) or `LIMITFEED n mm` (metric — must have a space before `mm`). Resident in memory across the session. No visual rendering effect — runtime hardware behaviour.

Selects the country / language code that orients the KP-200-series LCD keyboard and affects special-character mapping for built-in fonts. TSPL2 PG §COUNTRY p17. `n` is a 3-digit code: 001 USA, 002 Canadian-French, 003 Spanish (Latin America), 031 Dutch, 032 Belgian, 033 French, 034 Spanish (Spain), 036 Hungarian, 038 Yugoslavian, 039 Italian, 041 Switzerland, 042 Slovak, 044 United Kingdom, 045 Danish, 046 Swedish, 047 Norwegian, 048 Polish, 049 German, 055 Brazil, 061 English (International), 351 Portuguese, 358 Finnish. Engine accepts the code but doesn't currently apply locale-specific TEXT formatting — flagged as supported:false until the date-placeholder feature lands.

Begins downloading a file (program, font, or image) to the printer's internal flash memory. The data follows on subsequent lines until EOP.

Generic Bluetooth configuration dispatcher. The first word after BT picks the sub-action — NAME sets the device name visible to pairing hosts, PIN sets the legacy-pairing PIN. Not in the 2009 TSPL2 PG: Bluetooth is an optional module on later TSC models (TX/TE/MH-series and Alpha-series with optional BT) and the commands are documented in per-model BT setup addenda. Engine-recognised but not rendered — labels with BT configure the printer hardware rather than producing label content.

Sets the Bluetooth friendly-name the printer advertises over GAP, visible to pairing hosts during device discovery. Not in the 2009 TSPL2 PG — refer to the target model's BT setup addendum for the supported character set and maximum length on that firmware.

⚠️ Credential — appears in label source; do NOT commit to public repositories. Sets the Bluetooth legacy-pairing PIN (BT 2.1+EDR), typically a 4-digit numeric string. Modern Bluetooth SSP (Simple Secure Pairing) doesn't use a static PIN — on SSP-only firmware this command may document as a no-op. Not in the 2009 TSPL2 PG; refer to the target model's BT setup addendum.

Generic Wi-Fi configuration dispatcher. The first word after WLAN picks the sub-action — SSID sets the network name, PSK sets the WPA passphrase, ENCRYPTION picks the security mode, IP/GATEWAY/NETMASK/DNS configure a static-IP profile, and DHCP toggles automatic addressing (which overrides the static-IP commands). Not in the 2009 TSPL2 PG: Wi-Fi is an optional module on later TSC models (TX/TE/MH-series and Alpha-series with optional Wi-Fi) and the commands are documented in per-model WLAN setup addenda. Engine-recognised but not rendered — labels with WLAN configure the printer hardware rather than producing label content.

Sets the Wi-Fi network name (ESSID) the printer joins. Verify any length limits and allowed characters against the target model's WLAN setup addendum.

⚠️ Credential — appears in label source; do NOT commit to public repositories. Sets the WPA/WPA2/WPA3 pre-shared key passphrase (8–63 ASCII characters per IEEE 802.11i, or a 64-hex-char raw PSK). Effective only when `WLAN ENCRYPTION` is set to a WPA-family mode.

Selects the Wi-Fi security mode the printer uses to associate. OPEN is unencrypted; WEP is legacy and insecure; WPA / WPA2 / WPA3 are the modern pre-shared-key modes (PSK comes from `WLAN PSK`). Enterprise-capable firmware may also accept WPA2-ENTERPRISE / WPA-EAP, which require certificate-handling sibling commands per the model's addendum. Verify exact spelling against the target model's WLAN setup addendum.

Sets the static IPv4 address the Wi-Fi interface uses when DHCP is off. Ignored at boot when `WLAN DHCP ON` has been issued in the same profile.

Toggles DHCP client mode on the Wi-Fi interface. When ON, the printer obtains an IP/gateway/netmask/DNS automatically and the static-IP commands (`WLAN IP`, `WLAN GATEWAY`, `WLAN NETMASK`, `WLAN DNS`) are ignored at boot. When OFF, the static-IP commands take effect.

Sets the default-gateway IPv4 address the Wi-Fi interface routes traffic through when DHCP is off. Ignored at boot when `WLAN DHCP ON` has been issued.

Sets the IPv4 subnet mask the Wi-Fi interface uses when DHCP is off. Ignored at boot when `WLAN DHCP ON` has been issued.

Sets the primary DNS server IPv4 address the Wi-Fi interface uses for hostname resolution when DHCP is off. Ignored at boot when `WLAN DHCP ON` has been issued.