ZPL-Tutorial: Befehle und Beispiele

Dieses ZPL-Tutorial erklärt die paar Befehle hinter jedem Zebra-Etikett: ^XA und ^XZ für Anfang und Ende, ^FO zum Platzieren eines Felds, ^A0 für die Schrift, ^FD und ^FS für die Daten sowie ^BC und ^BQ für Barcodes. Zu jedem gibt es ein Beispiel, das du in einen Viewer einfügen kannst.

• Gut fürZPL lesen, das du geerbt hast, ein Etikett debuggen oder Etiketten aus einem Backend senden.
• Du brauchstNichts, um zu drucken. Der Etiketten-Editor schreibt das ZPL für dich.
• Gut zu wissenZPL rechnet in Punkten (Dots), deshalb druckt derselbe Code bei jeder DPI anders.

Was ZPL ist

Jedes Etikett, das eine Zebra druckt, ist ein winziges Programm in ZPL, der Zebra Programming Language.

Der Drucker nimmt keine PDFs oder Word-Dateien an. Er nimmt ZPL-Befehle, einen nach dem anderen, bis er eine Markierung erreicht, die sagt: Das Etikett ist fertig. Dann legt der Druckkopf los.

Um zu drucken, musst du kein ZPL lernen. Der kostenlose Etiketten-Editor schreibt es für dich. Die Grundlagen helfen trotzdem, aus zwei Gründen:

• Wenn etwas schiefgeht (ein unscharfer Barcode, abgeschnittener Text, ein fehlendes Feld), lässt es sich meist auf einen bestimmten Befehl zurückführen.
• Wenn du eine Backend-Automatisierung baust, etwa eine Druckwarteschlange, eine ERP-Anbindung oder ein Fulfillment-Skript, kopierst du irgendwann ZPL aus einem Editor und sendest es aus deinem eigenen Code. Dann hilft es zu wissen, was in diesem String steht.

Am Ende kannst du einen ZPL-String ansehen und ungefähr erkennen, welches Etikett daraus wird. Der letzte Teil zeigt, wie Copy ZPL funktioniert, damit du es in deine eigene Pipeline einbauen kannst.

Der Aufbau eines ZPL-Etiketts

Das einfachste mögliche ZPL-Etikett sieht so aus:

// Start a label
^XA

// Move to position (50, 50) and print "Hello World"
^FO50,50^A0N,36,36^FDHello World^FS

// End the label, fire the printer
^XZ

Jedes Etikett, egal wie komplex, beginnt mit ^XA und endet mit ^XZ. Alles dazwischen ist eine Folge von Befehlen.

Jeder Befehl besteht aus einem Zirkumflex (^) und zwei Buchstaben, die ihn benennen, plus optionalen Parametern, getrennt durch Kommas.

Das Beispiel nutzt das absolute Minimum:

• ^FO50,50 ist Field Origin. Es legt die Position für das Nächste fest, das du zeichnest, in Punkten von der oberen linken Ecke. 50,50 heißt also 50 Punkte nach rechts und 50 Punkte nach unten.
• ^A0N,36,36 wählt eine eingebaute Schrift: Schrift 0, keine Drehung, 36 Punkte hoch und 36 Punkte breit. Stell es dir als Auswahl für Schrift und Größe vor.
• ^FD ist Field Data, gefolgt vom Text, den du drucken willst. ^FS, Field Separator, beendet das Feld.

Punkte, DPI und warum sich Koordinaten seltsam anfühlen

Alle Koordinaten und Größen in ZPL sind in Punkten (Dots) angegeben, der physischen Auflösung des Druckkopfs. Drei DPI-Stufen decken fast alles ab:

• 203 DPI: 1 Zoll sind 203 Punkte. Ein 4 Zoll breites Etikett ist 812 Punkte breit.
• 300 DPI: 1 Zoll sind 300 Punkte. Ein 4 Zoll breites Etikett ist 1.200 Punkte breit.
• 600 DPI: 1 Zoll sind 600 Punkte. Ein 4 Zoll breites Etikett ist 2.400 Punkte breit.

Das klingt nach einem Detail, verändert aber den Druck. Derselbe ZPL-String landet auf Druckern mit unterschiedlicher DPI an unterschiedlichen Stellen.

Ein ^FO100,100 setzt dein Feld auf einem 203-DPI-Drucker etwa einen halben Zoll nach innen. Auf einem 600-DPI-Drucker setzt derselbe Befehl es nur etwa 0.17 Zoll nach innen. ZPL hat keine Ahnung, was ein Zoll ist. Alles sind Punkte.

Deshalb merkt sich mylabelmaker die DPI des aktiven Druckers und rendert in der nativen Auflösung des Druckers. Warum deine Zebra bei 300 DPI unscharf druckt erzählt die ganze Geschichte.

Die ZPL-Befehle, die du am häufigsten siehst

Mit nur diesen Befehlen kannst du ein komplettes Etikett von Hand schreiben. Ein kleines Produktetikett mit Name, Preis und Barcode hat etwa zehn Zeilen.

Füge einen kurzen Auftrag ein und sieh dir das ZPL im Browser an, um ^FO, ^A, ^BC oder ^BQ vor dem Drucken zu prüfen.

Ein ZPL-Beispiel, Zeile für Zeile

Hier ein umfangreicheres Etikett, so wie mylabelmaker es erzeugt, wenn du ein Versandetikett gestaltest:

^XA
^MD12
^PR4
^PW812
^PQ1
^FO0,0
^GFA,121800,121800,150,[hex bitmap data omitted]^FS
^XZ

• ^XA beginnt das Etikett.
• ^MD12 setzt die Druckschwärze auf 12, ein vernünftiger mittlerer Wert für ein frisches Farbband.
• ^PR4 druckt mit 4 Zoll pro Sekunde.
• ^PW812 setzt die Druckbreite auf 812 Punkte, das sind 4 Zoll bei 203 DPI.
• ^PQ1 druckt 1 Exemplar.
• ^FO0,0 setzt das nächste Feld in die obere linke Ecke.
• ^GFA,121800,121800,150,… bettet eine Bitmap mit 121.800 Byte ein, 150 Byte pro Zeile, als ganzes Etikett.
• ^FS schließt das Feld.
• ^XZ löst den Druck aus.

Dieses ^GFA ist der Standardweg von mylabelmaker. Es rendert die ganze Arbeitsfläche (Text, Barcodes, QR, Formen, Bilder) in der nativen DPI des Druckers zu einer Bitmap und sendet sie als ein einziges Grafikfeld.

So stimmt das gedruckte Etikett am zuverlässigsten mit dem Bildschirm überein, weil die druckereigene Schriftdarstellung, Barcode-Erzeugung und alle Firmware-Eigenheiten umgangen werden.

ZPL aus mylabelmaker holen

Nichts davon musst du selbst schreiben. Der Editor erzeugt das ZPL für alles, was du gestaltest. So holst du es dir:

1. Öffne https://app.mylabelmaker.com. Ohne Anmeldung.
2. Wähle eine Größe und füge Text, Barcodes, QR-Codes oder Bilder ein, was das Etikett eben braucht.
3. Öffne die Druckereinstellungen (das Zahnrad) und nutze Auto-detect (automatisch erkennen), damit das Etikett in der tatsächlichen DPI deines Druckers gerendert wird.
4. Klicke oben rechts im Editor auf Options und dann auf Copy ZPL (ZPL kopieren). Der komplette ^XA … ^XZ-String für das aktuelle Etikett landet in deiner Zwischenablage.
5. Füge ihn ein, wo du ihn brauchst: in eine Textdatei, einen Druckserver, eine Anfrage an deine Fulfillment-API, eine Chatnachricht.

Variablen und Stapeldruck

Wenn du einen Stapeldruck aus einer CSV oder einem Google Sheet startest, erzeugt mylabelmaker für jede Zeile einen eigenen ZPL-String mit den Werten dieser Zeile und sendet sie nacheinander.

Copy ZPL kopiert nur die aktuelle Zeile. Praktisch, um eine Zeile in deinem Backend zu testen, bevor du es auf die ganze Tabelle loslässt.

ZPL aus deinem eigenen Code senden

Sobald du den String hast, kann dein Backend ihn an eine Zebra senden: über einen TCP-Socket (Port 9100 bei Netzwerkdruckern), über die localhost-API des Browser-Print-Hilfsprogramms oder über einen beliebigen Zebra-Druckserver.

Das einfachste Beispiel, ein ZD621 im Netzwerk unter 192.168.1.50:

# Python
import socket
zpl = "^XA^FO50,50^A0N,36,36^FDHello^FS^XZ"
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
s.connect(("192.168.1.50", 9100))
s.send(zpl.encode("utf-8"))
s.close()

Das ist schon das ganze Muster. In jeder Sprache: TCP-Socket zur IP des Druckers auf Port 9100 öffnen, die ZPL-Bytes schreiben, schließen. Der Drucker druckt, sobald er ^XZ sieht.

Die Kurzliste zum Überfliegen von ZPL

Wenn du ZPL liest, das jemand anderes erzeugt hat, ein früherer Entwickler oder ein geerbtes System, begegnen dir diese:

Alles andere ist eine Variante davon oder ein Spezialbefehl, etwa für RFID-Codierung, Statusabfragen oder die Druckerkonfiguration. Die offizielle ZPL-II-Referenz, ein kostenloses PDF von Zebra, enthält die ausführliche Fassung, falls du sie je brauchst.

Das Fazit

ZPL ist eine kleine, schlichte ASCII-Befehlssprache, die es seit den 1990ern gibt und die nicht so bald verschwinden wird.

Du musst es nicht schreiben. Der Editor kümmert sich um die Eigenheiten (DPI-Umrechnung, Schriftrasterung, Barcode-Codierung, Bitmap-Packen) und sendet einen sauberen ^XA … ^XZ-String an deinen Drucker.

Du musst kein ZPL schreiben, aber wenn du weißt, was im String steht, kannst du Fehler besser finden.

Es hilft auch, wenn du ein Backend anbindest oder wenn jemand fragt, was die Etikettensoftware eigentlich macht.