P4 Software
/
BarcoderX English
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.
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.
For one label the writer writes these commands, in this order:
| Command | What it does | When it is written |
|---|---|---|
^XA | Starts the label format. | Always, first. |
^PW | Sets 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. |
^LL | Sets 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. |
^LH | Sets 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 ^GFA | Place a band of the picture and give its dots. | One pair for each band, from the top of the picture down. |
^FS | Ends the field of a band. | After each band. |
^PQ | Sets the number of copies. | Always, just before the end. |
^XZ | Ends 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.
For the 80 by 8 dot checkerboard of the programming guide, the eight rows are, in the plain form and in the compressed form:
| Row | Plain form | Compressed form |
|---|---|---|
| 1 | FFFFFFFFFFFFFFFFFFFF | ! |
| 2 | 8000FFFF0000FFFF0001 | 8I0JFJ0JFI01 |
| 3 and 4 | The same as the row before | : each |
| 5 | FFFF0000FFFF0000FFFF | JFJ0JFJ0! |
| 6 and 7 | The same as the row before | : each |
| 8 | FFFFFFFFFFFFFFFFFFFF | ! |
The commands and their ranges follow the ZPL II programming guide (part number P1134473-11EN, revision A).
| Input | What it is |
|---|---|
| The picture | The label as a black-and-white picture, with one bit for each dot. |
| The resolution | The 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 width | Optional. From 2 dots. If you give none, the printer keeps its own width. |
| The label length | Optional. 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 home | The horizontal and the vertical position of the label, in dots. The default is 0 and 0. |
| The number of copies | From 1 to 99,999,999. The default is 1. |
| The form of the picture | Plain or compressed. The default is plain. |
| The limit of the output | The 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.
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.
| Limit | Value |
|---|---|
| Size of the picture | 1 to 32,000 dots on each side (builder's choice, owner confirmation pending) |
| Print width, label length and home | The 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 copies | 1 to 99,999,999 |
| Bytes of the commands of one label | 16 MiB by default, and no more than 64 MiB (builder's choice, owner confirmation pending) |
| Bytes of one band | At 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.
^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.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 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.
| Part | What it is |
|---|---|
| Address | POST /api/v1/commands?dialect=zpl |
| Body | The template as JSON, up to 262,144 bytes, with the content type application/json. |
dialect | Required. zpl is the only value, in lower case. |
dpi | Optional. 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. |
| Answer | Status 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 problem | A problem document in English or Spanish, as for the picture address. The commands of a label that was stopped are never returned in part. |
| Limit | limits.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 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.
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.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?