Skip to content
P4 Software P4 Software / BarcoderX English

Add these docs to Claude

Ask Claude questions about these docs. Claude reads the published pages and links you back to them. Copy this address:

https://p4-software.opendocs.page/mcp

In claude.ai or Claude Desktop: open Settings, then Connectors, choose Add custom connector and paste the address.

In Claude Code, run:

claude mcp add --transport http docs https://p4-software.opendocs.page/mcp

ZPL output

ZPL output

Applies to: BarcoderX Basic and Ultimate

Status: Built, not yet released. The writer that turns a black-and-white picture of a label into ZPL commands exists and is tested, and it is now joined to the label engine: a template becomes the commands of one label, and the stateless web service has an address that returns them. Nothing is released yet and there is nothing to download. There is no released package. The one public way to produce commands takes a label that the licensed engine made, and nothing else. No form of the commands has been run on a physical printer yet, the plain form and the compressed form alike; the laboratory record is pending. Anything marked "planned" is not usable yet.

ZPL is a printer language. See Printer languages for the languages BarcoderX plans to write and what each is for. ZPL is a name that belongs to its owner, and BarcoderX uses it only to say which language it writes. This page describes the first ZPL writer, the one that sends a whole label to the printer as a picture, and how a template reaches it.

What it does

The writer takes the black-and-white picture of one label, at the resolution of the printer, and writes the ZPL commands that make the printer print exactly that picture. It sends no text of its own and no barcode commands of its own. Everything on the label, text and barcodes included, is part of the picture, so the printer prints exactly the picture that the writer is given. The evaluation mark, if the label carries one, is already in the picture, because the engine draws it with the rest of the label, and the writer adds nothing to it.

The picture reaches the writer only through the engine. Printer-resident text, the printer's own barcode commands, the setup of the printer and printing several labels in one job are planned. See Printer languages.

What is written

For one label the writer writes these commands, in this order:

CommandWhat it doesWhen it is written
^XAStarts the label format.Always, first.
^PWSets the print width, in dots.Only when you give a print width. The commands made from a template always give one, the width of the label.
^LLSets the label length, in dots.Only when you give a label length. The commands made from a template always give one, the height of the label.
^LHSets the label home, the position of the top left corner of the label, in dots.Always, because the printer keeps the last home it was given until it is switched off.
^FO and ^GFAPlace a band of the picture and give its dots.One pair for each band, from the top of the picture down.
^FSEnds the field of a band.After each band.
^PQSets the number of copies.Always, just before the end.
^XZEnds the label format, and the label prints.Always, last.

The smallest label that the tests write, a picture 8 dots wide and 1 dot high whose dots are the hexadecimal digits A5, gives these commands:

^XA
^LH0,0
^FO0,0^GFA,1,1,1,A5^FS
^PQ1
^XZ

The numbers in ^GFA,1,1,1,A5 are the number of bytes of the band, the same number again, the number of bytes in one row, and then the data.

The picture

  • Plain form. Each byte of the picture is written as two hexadecimal digits. The dot at the left of a row is the highest bit of its first byte, and a dot that is set is black. A row is padded to a whole byte, and the padding is always written as white, whatever the picture holds in its padding.
  • Compressed form. The shorthand of the ZPL programming guide that repeats a digit, fills the rest of a row with zeros or with ones, or repeats the row before. It is never longer than the plain form. A letter from G to Y repeats the digit that follows 1 to 19 times, a letter from g to z repeats it 20 to 400 times, a comma fills the rest of the row with zeros, an exclamation mark fills it with ones and a colon repeats the row before. The compressed form is off by default, and it has not been verified on a physical printer. The guide describes the shorthand for the commands that download graphics, and says that the graphic field follows the same format. A printer profile should turn it on only for a printer that is known to accept it. Two points are open: the exclamation mark is used for trailing bytes that are all ones, which is this project's reading of the guide, and the letters for 60 and 120 are read by their place in the alphabet.
  • Bands. A graphic field holds at most 99,999 bytes, so a tall picture is written as several bands, one under the other. For example, a picture 812 dots wide and 1,218 dots high is written as two bands, the first with rows 0 to 979 and the second with rows 980 to 1,217. The bands together hold every row exactly once.

For the 80 by 8 dot checkerboard of the programming guide, the eight rows are, in the plain form and in the compressed form:

RowPlain formCompressed form
1FFFFFFFFFFFFFFFFFFFF!
28000FFFF0000FFFF00018I0JFJ0JFI01
3 and 4The same as the row before: each
5FFFF0000FFFF0000FFFFJFJ0JFJ0!
6 and 7The same as the row before: each
8FFFFFFFFFFFFFFFFFFFF!

The commands and their ranges follow the ZPL II programming guide (part number P1134473-11EN, revision A).

What goes in

InputWhat it is
The pictureThe label as a black-and-white picture, with one bit for each dot.
The resolutionThe resolution of the printer, in dots per inch, from 96 to 1,200. ZPL itself carries no resolution, so the writer only checks that it is in this range.
The print widthOptional. From 2 dots. If you give none, the printer keeps its own width.
The label lengthOptional. From 1 dot. If you give none, the printer keeps its own length. The guide says that the length applies by default to media that is not divided into separate labels, so on other media the printer may keep its own length.
The label homeThe horizontal and the vertical position of the label, in dots. The default is 0 and 0.
The number of copiesFrom 1 to 99,999,999. The default is 1.
The form of the picturePlain or compressed. The default is plain.
The limit of the outputThe most bytes that one label may take.

A value that is outside its range is refused with a message and is never clamped. The limit of the output is the one exception: a value below 1 counts as 1, and a value above 64 MiB counts as 64 MiB.

Limits

BarcoderX checks every limit before it writes anything. A label that breaks a limit gets a message and no commands. The limit on the size of the output protects the program that hosts the writer.

LimitValue
Size of the picture1 to 32,000 dots on each side (builder's choice, owner confirmation pending)
Print width, label length and homeThe ranges of the programming guide: 2 or more for the width, 1 to 32,000 for the length, 0 to 32,000 for the home. The upper bound of the width, 32,000, is a builder's choice, owner confirmation pending.
Number of copies1 to 99,999,999
Bytes of the commands of one label16 MiB by default, and no more than 64 MiB (builder's choice, owner confirmation pending)
Bytes of one bandAt most 99,999

The size of the output is worked out from the plain form and checked before anything is written. The compressed form is never larger. The default of 16 MiB holds the plain form of a picture of 64 megapixels. The limit is per label, so a program that writes many labels into one job should give each label the budget that is left for the job.

Some figures, measured in a security review on one development computer. A label of 4 by 6 inches at 300 dots per inch (1,200 by 1,800 dots) takes about 540,000 bytes of commands, and one at 600 dots per inch (2,400 by 3,600 dots) about 2,160,000 bytes, whatever is on it in the plain form: each byte of the picture becomes two characters. The compressed form is never larger. Writing such a label took less than 3 milliseconds in the plain form, and less than 50 milliseconds in the compressed form with the worst content. For the largest picture that the limits admit, writing took about 0.1 second in the plain form and up to about 1.5 seconds in the compressed form on noisy content.

If you host the writer

  • Discard the commands of a label that was refused or canceled. If the output does not accept the commands part way through a label (BX5113), or the work is canceled, what has been written can hold a format that was started and not closed (^XA with no ^XZ). A printer takes that as the start of the next label. Write each label into a buffer of its own, or roll back to the size the buffer had before the call, and never send the bytes of a label that did not finish.
  • Count copies yourself. The writer accepts up to 99,999,999 copies for one label. Check the copies against the limits of the job before you pass them on.
  • Let a long write be canceled. The writer checks a cancellation token before it writes the first byte and once for each row.
  • Pass a budget for the job. Each label has its own limit of output, so give each label what is left of the job's budget.

From a template to commands

The label engine hands the label it made to the ZPL composer, and the composer returns the commands of that label. The engine lays the label out in dots at the resolution you ask for. The composer draws it on a black-and-white surface, in the same way as the black-and-white PNG picture is drawn, and the writer above writes that surface as commands. The dots that the printer receives are therefore the dots of the black-and-white picture, one for one. A test reads both back with code written for it and compares them dot by dot, for several labels and resolutions.

The commands of one label, in order: ^XA; ^PW with the width of the label in dots (left out for a label one dot wide, because the command takes 2 or more); ^LL with the height of the label in dots; ^LH0,0; one ^FO and ^GFA pair for each band; ^PQ1; ^XZ. The plain form is used, never the compressed form. The start of the commands of the sample label (100 by 50 mm at 203 dots per inch, 799 by 400 dots):

^XA
^PW799
^LL400
^LH0,0
^FO0,0^GFA,...

One notice for each label. The composer sends the whole label as one picture, so it reports one notice for the label, BX5130, and not one for each text, barcode or box. The printer's own fonts and barcode commands are not used in this release. The commands for them are planned, and they will be used only where they are proven equal to the picture.

Limits. The host that runs the composer sets two limits: the most dots of a label, and the most bytes of the commands (16 MiB by default, and no more than 64 MiB). Both are checked before anything is drawn or allocated, and a label over a limit gets a message and no commands. A label whose drawing cannot finish gets the code of the drawing library and no commands, because a half-drawn barcode must never reach a printer.

The commands address of the service

The stateless web service has one address for the commands of a label. It is the same handler as the picture address (POST /api/v1/render/png), so the same controls apply: the key, the size of the body, the rate limits, the places for drawing labels (shared by both addresses), the time limit and the write deadline. Their values and the settings that change them are in The label service.

PartWhat it is
AddressPOST /api/v1/commands?dialect=zpl
BodyThe template as JSON, up to 262,144 bytes, with the content type application/json.
dialectRequired. zpl is the only value, in lower case.
dpiOptional. The resolution in dots per inch, in the range of the service (96 to 600 by default). Without it, the resolution written in the template is used. ZPL itself carries no resolution, so use the resolution of your printer.
AnswerStatus 200 with the content type text/plain; charset=utf-8: the commands, as plain ASCII text. The header BarcoderX-Warnings lists the codes of the notices about the label, and BX5130 is always there.
A problemA problem document in English or Spanish, as for the picture address. The commands of a label that was stopped are never returned in part.
Limitlimits.maxCommandsBytes in settings.json: 16,777,216 bytes by default, from 1,024 up to 67,108,864. GET /api/v1/meta/limits shows it as maxCommandsBytes. The most dots of a label is the limit of the black-and-white picture.

A curl call, from a folder that holds label.json:

curl -X POST "http://127.0.0.1:5187/api/v1/commands?dialect=zpl&dpi=203" -H "Content-Type: application/json" --data-binary @label.json -o label.zpl

The typed .NET client that is built for the picture route also asks for the commands. It takes the template text and the options (the printer language, the resolution and the language of the messages), and gives back the commands and the warning codes, or the problem document and the number of seconds to wait. It throws only for a network failure or a canceled request, never for a problem that the service reports. See The label service.

The evaluation mark in the commands

The label engine draws the evaluation mark with the rest of the label, so the mark is part of the dots that the commands carry. It is the same mark as in the PNG picture, dot for dot: a test compares the dots of the commands with the dots of the black-and-white picture of a marked label. When no valid license covers the label, or when the license check itself fails, the label still prints and its commands carry the mark. A licensed run produces unmarked commands, which is the product. See Evaluation mark and license keys.

  • Nothing about the license is in the commands. Neither the license id nor the name of the licensee is written in a printer command stream, and no comment or field is used for it.
  • A ZPL stream is plain text, so the mark in it is a deterrent and not a lock.
  • How to tell. The result of the composer has a Marked flag, and the web service lists the note BX9001 ("No license is registered") in the BarcoderX-Warnings header of an answer that is marked because no license is registered (when the license check itself fails, the note is BX9030 and the commands are marked all the same). The free playground always returns marked commands.

What is not built yet

  • ZPL from a stored template or with data. The commands address takes a complete template in the request. Stored templates and data come with the server.
  • The printer's own text and barcode commands. BarcoderX plans to use them where they are proven equal to the picture. See Printer languages.
  • Setup commands such as media tracking, print mode, speed, darkness and orientation. Today only the width, the length, the home and the number of copies are written.
  • RFID commands, serialization and TrueType fonts in the printer.
  • Verifying the commands on a physical printer, the plain form and the compressed form. The compressed form is not offered by the commands address.

The diagnostic codes of the writer and the composer are BX5101 to BX5113, BX5120, BX5121 and BX5130 to BX5133. See Diagnostic codes.


BarcoderX is a product of P4 Software.

Was this page helpful?