ESC Commands

ESC is a binary printer command language widely used by thermal receipt and label printers.

Overview

ESC commands are hexadecimal byte sequences. Each command generally starts with a specific control code.

Command structure

[Control code] [Function code] [Parameters...]

Common control codes

Control code	Hex	Name	Purpose
ESC	`0x1B`	Escape	Standard control commands
GS	`0x1D`	Group Separator	Graphics/Advanced features
DLE	`0x10`	Data Link Escape	Real-time status commands
FS	`0x1C`	File Separator	Chinese character mode commands
LF	`0x0A`	Line Feed	Line feed

Character encoding

Printer control commands

Wake the printer

Wake the printer from sleep.

Hex: 00 00 00 00 00 00 00 00

Send eight null bytes to wake the printer.

Enable the printer

Enable the printer so it can receive print data.

Hex: 10 FF 20 00

Initialize the printer (ESC @)

Initialize the printer, clear the print buffer, and restore default settings.

ESC @
Hex: 1B 40

End the print job

End the current print job.

Hex: 1B 40 10 FF FE 01

Image printing commands

Print a bitmap image (GS v 0)

Print a raster bitmap image.

GS v 0 m xL xH yL yH [Data]
Hex: 1D 76 30 m xL xH yL yH [Data]

Parameter	Description
m	Print mode
xL xH	Horizontal byte count (low byte, high byte)
yL yH	Vertical dot count (low byte, high byte)
Data	Image bitmap data

Print mode (m)

m value	Description
0	Normal printing
1	Double-width printing
2	Double-height printing
3	Double-width and double-height printing

Compressed image printing

Printers that support compression can receive image data in compressed mode.

Hex: 1F 00 [Width high byte] [Width low byte] [Height high byte] [Height low byte] [Data length 4 Bytes] [Compressed data]

Image binarization threshold

The SDK supports a configurable binarization threshold. The default is 190.

Threshold range	Effect
0-127	Darker image
128-190	Normal (recommended)
191-255	Lighter image

Positioning commands

Position the paper

Position the paper at the next label (for label paper mode).

Hex: 10 FF 04

Learn label gaps

Automatically learn/detect the gap between labels.

Hex: 10 FF 30 F2 31

Feed paper (ESC J)

Feed the paper forward by the specified number of dots.

ESC J n
Hex: 1B 4A n

Parameter	Description
n	Feed distance in dots (0-255)

Feed a specified number of dot rows

Hex: 10 FF F0 [Dot count low byte] [Dot count high byte]

Reverse feed

Feed the paper backward by the specified number of dots.

Hex: 10 FF F1 [Dot count low byte] [Dot count high byte]

Set print starting position

Set the horizontal print starting position.

Hex: 10 FF 12 [Position value]

Paper configuration commands

Set paper type (A4 series)

Set the printer’s paper type.

Hex: 10 FF 10 03 [Type]

Type value	Paper type
0	Fanfold black mark paper
1	Continuous roll paper
2	Adhesive gap labels
3	Punched paper
4	Tattoo paper
5	Tattoo paper (anti-wrinkle mode)
6	Transparent black mark paper

Set paper type (Q series)

For models such as Q1, Q2, Q3, D11, D30, B21, and B22.

Hex: 10 FF 40 F4 [Type]

Type value	Paper type
0	Gap paper
1	Black mark paper
2	Continuous paper

Query current paper type

Hex: 10 FF 40 F3

Return values:

0x01 - Black mark paper
0x02 - Continuous paper
Other values - Gap paper

Print configuration commands

Set print density

Set the printer’s print density.

Hex: 10 FF 10 00 [Density value]

Density value	Description
0	Low density
1	Medium density
2	High density

Set shutdown timeout

Set the automatic shutdown timeout.

Hex: 10 FF 10 0A [Time low byte] [Time high byte]

Parameter	Description
Time	Shutdown timeout (minutes), 0 disables automatic shutdown

Query shutdown timeout

Hex: 10 FF 10 0B

Set Bluetooth type

Set the Bluetooth communication type (required for printers that support compression).

Hex: 10 FF 40 F1

Set current time

Set the printer’s current time (supported on some models).

Hex: 10 FF 40 A0 [Year] [Month] [Day] [Hour] [Minute] [Second]

Cutter commands

Cut immediately

Cut the paper immediately.

Hex: 1D 56 00

Feed and cut

Feed a fixed distance and then cut the paper. The firmware determines the feed distance.

Hex: 1D 56 42 00

Cutting modes

Command	Hex	Description
GS V 0	`1D 56 00`	Full cut
GS V 1	`1D 56 01`	Partial cut
GS V 66 n	`1D 56 42 n`	Feed n lines, then cut

Line drawing commands

Draw horizontal/vertical lines

Draw a straight line.

Hex: 10 FF 21 [X Low] [X High] [Y Low] [Y High] [Width low byte] [Width high byte] [Height low byte] [Height high byte]

Parameter	Description
X	Starting X coordinate
Y	Starting Y coordinate
Width	Line width
Height	Line height

Query commands

Query all printer information

Query all printer information.

Hex: 10 FF 00 FF

Query printer status

Query the current printer status.

Hex: 10 FF F9

Query battery level

Query the printer’s battery level.

Hex: 10 FF 50 00

Query Bluetooth name

Hex: 10 FF 50 11

Query MAC address

Hex: 10 FF 30 00

Query serial number (SN)

Hex: 10 FF 20 00

Query printer model

Hex: 10 FF 30 F0

Query firmware version

Hex: 10 FF 20 F0

Query Bluetooth firmware version

Hex: 10 FF 50 14

Query NN

Hex: 10 FF 30 02

NFC tag commands

Some printers support NFC tags.

Get label paper information

Hex: 10 FF A0 00

Get tag UID

Hex: 10 FF A0 01

Get used length

Hex: 10 FF A0 02

Get remaining length

Hex: 10 FF A0 03

Grayscale printing commands

Some printers support grayscale printing.

Enable grayscale mode

Hex: 10 FF E1 03

Print grayscale images

Print an image in grayscale mode for a wider range of gray levels.

Unsolicited reports

The printer sends unsolicited status information to the application in certain situations.

Device status reports

When an abnormal condition occurs, the printer sends a two-byte status message.

Header	Status type	Meaning
0xFF	0x00	Printer normal
0xFF	0x01	Overheated
0xFF	0x02	Cover open
0xFF	0x04	Out of paper
0xFF	0x08	Low voltage

Paper type reports

The device sends a report when the detected paper does not match the configured paper type.

Header	Status type	Meaning
0xFE	0x01	Fanfold black mark paper
0xFE	0x02	Continuous roll paper
0xFE	0x03	Adhesive gap labels

Print cancellation reports

Reports sent when the user cancels a print job.

Header	Status type	Meaning
0xFD	0x01	Start clearing the current page’s print job
0xFD	0x02	Current print job cleared

Complete printing workflow

Recommended print sequence:

Wake the printer - Send the wakeup command
Enable the printer - Enable printing
Print the image - Send image data
Position the paper - Advance to the next label (not needed for continuous paper)
End the print job - Finish printing

Example command sequence

00 00 00 00 00 00 00 00    # Wake the printer
10 FF 20 00                # Enable the printer
10 FF 10 00 01             # Set medium density
10 FF 10 03 02             # Set adhesive gap labels
1D 76 30 00 ...            # Print image data
10 FF 04                   # Position the paper
1B 40 10 FF FE 01          # End the print job

SDK integration

Each language SDK wraps ESC command construction. See the following guides for usage:

Java SDK (Android) - Native Android development
Objective-C SDK (iOS) - Native iOS development
Swift SDK - Modern iOS/macOS development
Dart SDK - Cross-platform Flutter development
JavaScript SDK - Mini Program development
OpenHarmony SDK - HarmonyOS / OpenHarmony applications

References

Complete ESC command reference (PDF)