~DY - Download Objects

~DY is the general download command.

~DG takes a raw raster only; ~DY takes a PNG, a PCX, a TrueType font or a GRF, and it is the preferred command for a TrueType font. Two arguments of it are easy to confuse: b gives the payload encoding on the wire, and x gives the object type. The file name carries no extension, because x supplies it. The renderer stores the raw bitmap case and reports the rest.

Syntax

~DYd:f,b,x,t,w,data

Support

Partially supportedparsed: full · state: partial · rendered: partial

The command renders, with the caveat below.

The renderer stores a raw bitmap (x of G) sent as ASCII hex or raw binary, and recalls it like a ~DG object. A font download (x of T) is validated and stored, so ^A@ and ^CW resolve it, but no field draws with the face yet. A .BMP or .PNG download is parsed and reported rather than stored, so a label that downloads one this way loses that object. — not pinned by a test

Labelary renders this command. Scheduled for milestone 5.9.

Parameters

dStorage deviceoptional · single character

Which memory device to store the object on.

Default: R:
Invalid value: discarded, and the default applies
Test coverage: The invalid-value rule is not pinned by a test.

fFile namerequired · text

Name to store the object under, 1 to 8 alphanumeric characters, written **without** an extension. The extension comes from x.

Invalid value: enough to make the whole command be ignored
Test coverage: The invalid-value rule is pinned by 1 test.

bPayload encodingrequired · one of a set

How the payload in data is encoded. This is the encoding on the wire, not the kind of stored object.

Invalid value: enough to make the whole command be ignored
Test coverage: Values exercised: B. Not exercised: A, C, P. The invalid-value rule is pinned by 2 tests.

A: ASCII hexadecimal, or a ZB64 wrapper
B: Raw binary
C: AR-compressed, used only by Zebra's BAR-ONE v5
P: ZB64-encoded PNG

xObject extensionoptional · one of a set

Which kind of object the payload is, and the extension for it. Labelary honors only G, B, P and T.

Default: G
Invalid value: discarded, and the default applies. The guide states that the printer treats any value outside the accepted set as .GRF.
Test coverage: Values exercised: P, T. Not exercised: B, E, G, X. The invalid-value rule is pinned by 1 test.

B: Bitmap
E: Encoding table, added by later firmware and absent from the 2006 guide
G: GRF raster graphic (default)
P: Store as a compressed .PNG
T: TrueType .TTF font
X: Paintbrush .PCX image

tTotal bytesrequired · integer

Size of the object in bytes: the file itself, not the storage it occupies. For a .GRF this is the size after decompression into memory.

Invalid value: enough to make the whole command be ignored
Test coverage: The invalid-value rule is pinned by 1 test.

wBytes per rowoptional · integer

Bytes per raster row. Read only for a .GRF; ignored for .PNG, .TTF and every other self-describing format.

Default: 0
Invalid value: discarded, and the default applies
Test coverage: The invalid-value rule is pinned by 1 test.

dataObject datarequired · text

The object's bytes, in the encoding named by b.

Invalid value: enough to make the whole command be ignored
Test coverage: The invalid-value rule is pinned by 2 tests, including the diagnostic it emits.

Behavior

The two type arguments are independent. A PNG can arrive as ASCII hex (b = A, x = P) or as raw binary (b = B). A GRF sent as hex is A,G, which is ~DG in a different spelling. b = P is the ZB64-wrapped PNG case. A printer reads bytes-per-row for a .GRF and ignores it for every other type, because a PNG or a TrueType font describes its own geometry.

~DY is a tilde command and acts as the parser reads it, so it goes before the ^XA of the label that uses the object.

^XG recalls a downloaded graphic, and ^A@ selects a downloaded font. The object must reach the printer before the ^A@ that names it.

The guide accepts the command and its binary payload as two separate files, and the printer then waits for the declared byte count. A graphic must be monochrome, because a thermal printer has no color.

The renderer stores an x of G, the raw bitmap, sent as ASCII hex or as raw binary. x is the authority for the stored extension, whatever the name slot said: ~DYR:LOGO,A,G and ~DYR:LOGO.GRF,A,G are one object, recalled as R:LOGO.GRF. An omitted x is G. The other object types are parsed and reported rather than stored.

A letter outside T, G, B and P is rejected outright, as is a format letter outside A, B, C and P. Both report the offending character back. A path with no name stores nothing and says nothing. We measured these against Labelary on 2026-08-19.

No printer holds the object, so it lives for one conversion request only.

Differences from the specification

Labelary against the ZPL II guide

Where Labelary — our compatibility target — behaves differently from the printed specification.

Labelary honors only extensions T, G, B and P, and rejects the whole command for any other letter rather than defaulting it to .GRF as the guide describes. We measured this on 2026-08-19: ~DYR:LOGO,A,Q,80,10,... answers Command was ignored because 'Q' is not a valid extension (T/G/B/P) and stores nothing. — not pinned by a test

zpl.tools against Labelary

Where our output differs from Labelary for the same input. These are the differences that break a migration.

Labelary stores every kind of object ~DY downloads. The renderer stores raw bitmaps only, so a .TTF, .BMP or .PNG download reports UNSUPPORTED_COMMAND here and is missing from the output. — not pinned by a test

Example

The 80 × 8 dot checkerboard from the ~DG page, sent through ~DY instead: hex payload (A), stored as a GRF (G), name written without its extension, then recalled as LOGO.GRF:

~DYR:LOGO,A,G,80,10,
FFFFFFFFFFFFFFFFFFFF
8000FFFF0000FFFF0001
8000FFFF0000FFFF0001
8000FFFF0000FFFF0001
FFFF0000FFFF0000FFFF
FFFF0000FFFF0000FFFF
FFFF0000FFFF0000FFFF
FFFFFFFFFFFFFFFFFFFF
^XA
^FO50,50^XGR:LOGO.GRF^FS
^XZ

Open in viewer

~DG Download GraphicDownloads an ASCII-hex bitmap into printer memory as a `.GRF` object.
^XG Recall GraphicDraws a previously downloaded graphic, optionally magnified.
~DU Download Unbounded TrueType FontDownloads a TrueType font with a full, unrestricted character set.
~DT Download TrueType FontDownloads a TrueType font.