BinaryKits.ZPL Documentation

For quick development and testing of new ZPL features, use the CustomTest.cs file. You can load your specific ZPL data into Data/Zpl/custom.zpl2 to test changes.

Note: Changes to custom.zpl2 are not tracked by source control by default. If you need to track changes to this file, use the following Git commands:

• To enable tracking: git update-index --no-skip-worktree custom.zpl2
• To disable tracking: git update-index --skip-worktree custom.zpl2

git update-index --no-skip-worktree Data/Zpl/custom.zpl2

To preview ZPL data, use the ZplAnalyzer to parse the ZPL string into label information, and then use ZplElementDrawer to render those elements into image bytes (PNG format).

IPrinterStorage printerStorage = new PrinterStorage();
var drawer = new ZplElementDrawer(printerStorage);

var analyzer = new ZplAnalyzer(printerStorage);
var analyzeInfo = analyzer.Analyze(request.ZplData);

foreach (var labelInfo in analyzeInfo.LabelInfos)
{
	var imageData = drawer.Draw(labelInfo.ZplElements);
	// imageData is bytes of png image
}

The following elements are currently not supported by the viewer:

1D Barcodes

• MSI (^BM)
• Databar/RSS-14 (^BR)
• Code 11 (^B1)
• POSTNET (^BB)
• PLANET (^B8)
• Composite (^BC)

2D Barcodes

• Micro PDF417 (^B7)
• Micro QR Code (^BQ)

Graphic Elements

• Graphic Ellipse (^GE)
• Graphic Symbol (^GS)
• Graphic Diagonal Line (^GD)

The viewer supports the following barcode formats:

1D Barcodes

• Code 39 (^B3)
• Code 93 (^BA)
• Code 128 (^BC)
• EAN-13 (^BE)
• UPC-A (^BU)
• UPC-E (^B9)
• UPC Extension (^BS)
• Interleaved 2 of 5 (^B2)
• ANSI Codabar (^BK)

2D Barcodes

• QR Code (^BQ)
• Data Matrix (^BX)
• PDF417 (^B7)
• Aztec (^B0)
• MaxiCode (^BD)

To create a new ZPL command, you must inherit from the CommandBase abstract class. You are required to implement two primary methods:

1. ToZpl(): Returns the string representation of the command in ZPL format.
2. ParseCommand(string zplCommand): Logic to parse an existing ZPL command string back into the object's properties.

When initializing the base class, you must provide a commandPrefix (e.g., the specific ZPL command identifier like ^A or ^B).

public class MyCustomCommand : CommandBase
{
    public MyCustomCommand(string commandPrefix) : base(commandPrefix) { }

    public override string ToZpl()
    {
        // Return the formatted ZPL string
        return $"{CommandPrefix}DATA...";
    }

    public override void ParseCommand(string zplCommand)
    {
        // Implement parsing logic here
    }
}

When implementing ParseCommand, use the following helper methods to convert ZPL character codes back into usable C# types:

• ConvertBoolean(string value): Returns true for "Y", false for "N" (defaults to false).
• ConvertOrientation(string orientation): Returns Orientation enum (defaults to Orientation.Normal).
• ConvertErrorCorrectionLevel(string errorCorrectionLevel): Returns ErrorCorrectionLevel enum (defaults to ErrorCorrectionLevel.HighReliability).

The ~DY command is used to download graphic objects or fonts to the printer in any supported format. It is the preferred command for downloading TrueType fonts on printers with firmware version X.13 or later, as it is faster than ~DU and offers more saving/loading options than ~DG. It also supports downloading wireless certificate files.

In the BinaryKits.Zpl.Protocol library, you can use the DownloadObjectsCommand class to construct this command programmatically.

var command = new DownloadObjectsCommand(
    "R:",               // storageDevice
    "MYFONT",            // fileName
    'A',                 // formatDownloadedInDataField
    ".TTF",             // extensionOfStoredFile
    1024,                // totalNumberOfBytesInFile
    256,                 // totalNumberOfBytesPerRow
    "DATA_STRING"
);

string zpl = command.ToZpl();

The ChangeAlphanumericDefaultFontCommand (ZPL ^CF command) sets the default font used by the printer. This is useful for simplifying ZPL programs by establishing a baseline font for text elements.

Parameters

• specifiedDefaultFont (char): The character representing the specified default font.
• individualCharacterHeight (int?, optional): The height of individual characters. Valid range is 0 to 32000.
• individualCharacterWidth (int?, optional): The width of individual characters. Valid range is 0 to 32000.

Usage

When calling the constructor, you can provide the font and optional dimensions. The ToZpl() method will generate the formatted ^CF command string.

// Example: Set default font to 'A' with height 30 and width 40
var command = new ChangeAlphanumericDefaultFontCommand('A', 30, 40);
string zpl = command.ToZpl(); // Returns "^CFA,30,40"

The LabelHomeCommand (ZPL ^LH command) sets the label home position, which serves as the axis reference point for all subsequent printing. By default, the home position is the upper-left corner (0,0).

Use this command to adjust the reference point, which is particularly useful when working with preprinted labels to ensure the print area starts below the preprinted section.

Important: This command only affects fields that appear after it in the ZPL stream. It is recommended to place ^LH near the beginning of your label format.

// Example: Setting the home position to X=10, Y=20
var labelHome = new LabelHomeCommand(x: 10, y: 20);
string zpl = labelHome.ToZpl(); // Returns "^LH10,20"