ZPL w praktyce: jak wysłać etykietę z ERP/WMS do drukarki Zebra

ZPL to język, w którym system ERP lub WMS „mówi” do drukarki Zebra: zamiast pliku graficznego wysyła krótki tekst z poleceniami, a drukarka sama układa z niego etykietę. Poniżej pokazujemy, jak według oficjalnego ZPL Programming Guide zbudować etykietę ZPL (Zebra), z kodem kreskowym, DataMatrix, QR i polskimi znakami, oraz jakimi drogami – portem 9100, sterownikiem, SDK albo z przeglądarki – dostarczyć ją do drukarki.

Struktura etykiety ZPL: ^XA … ^XZ

Każde polecenie ZPL zaczyna się od znaku prefiksu – domyślnie ^ dla poleceń formatu i ~ dla poleceń sterujących (tak podaje tabela ustawień konfiguracji ZD421/ZD621: COMMAND CHAR ^, CONTROL CHAR ~, separator parametrów ,). Format etykiety ma stałe ramy:

• ^XA – otwiera nowy format etykiety. Według ZPL Programming Guide poprawny kod ZPL II wymaga, by każdy format zaczynał się od ^XA i kończył poleceniem ^XZ.
• ^XZ – zamyka format; po nim drukarka drukuje etykietę.

Wszystko pomiędzy to pola: pozycja, czcionka lub symbolika kodu, dane i separator pola. Najprostszy przykład znajdziesz w dokumentacji Link-OS SDK: ^XA^FO20,20^A0N,25,25^FDThis is a ZPL test.^FS^XZ – drukuje napis w pobliżu górnej krawędzi etykiety.

Pola tekstowe: ^FO, ^A, ^FD, ^FS

• ^FOx,y (Field Origin) – ustawia lewy górny róg pola względem początku etykiety (^LH). Współrzędne podajesz w punktach (dots), w zakresie 0–32000, domyślnie 0. Za duża wartość może umieścić pole całkowicie poza etykietą.
• ^Afo,h,w (czcionka) – f to nazwa czcionki (A–Z, 0–9), o to orientacja (N – normalna, R – obrót o 90°, I – 180°, B – 270°), h i w to wysokość i szerokość w punktach. Ustawienie dotyczy tylko najbliższego pola ^FD. W ćwiczeniach ZPL II Zebra opisuje czcionkę ^A0 jako skalowalną – wysokość i szerokość wybierasz dowolnie.
• ^FD (Field Data) – dane, które mają się wydrukować.
• ^FS (Field Separator) – kończy pole.

Pozycje i rozmiary liczysz w punktach, więc zależą od rozdzielczości głowicy. ZPL Programming Guide przy długości etykiety (parametr SGD zpl.label_length, równoważny poleceniu ^LL) podaje przelicznik: długość w calach razy 203,2 dla głowicy 8 punktów/mm (203 dpi) albo 304,8 dla 12 punktów/mm (300 dpi). Etykieta o długości 50 mm na drukarce 203 dpi to więc ok. 400 punktów.

Kody kreskowe i 2D: ^BY, ^BC, ^BX, ^BQ

Który kod wybrać do jakiej informacji, opisujemy w artykule o rodzajach kodów kreskowych w firmie.

Polskie znaki: ^CI28 i ^FH

Domyślnie (po włączeniu zasilania) drukarka używa zestawu znaków ^CI0. Jeśli Twój ERP lub WMS wysyła tekst w UTF-8, umieść w etykiecie ^CI28 – według ZPL Programming Guide wartość 28 oznacza Unicode w kodowaniu UTF-8 (29 i 30 to UTF-16 Big- i Little-Endian). Wartości 28–30 wymagają firmware V60.14.x, V50.14.x lub nowszego.

• Zebra zaleca, by każdy skrypt ZPL zaczynał się od polecenia ^CI (albo znacznika BOM Unicode) – szczególnie gdy na jedną drukarkę trafiają etykiety z różnych systemów w różnych kodowaniach.
• Alternatywa to ^FH: wstawiasz w polu ^FD wartości szesnastkowe znaków poprzedzone wskaźnikiem (domyślnie _), np. bajty UTF-8. ^FH musi stać przed każdym ^FD, które z niego korzysta.
• Kodowanie to jedno, a czcionka – drugie. Instrukcja drukarek Zebra wyjaśnia, że ZPL obsługuje Unicode, a listę czcionek załadowanych w drukarce wyświetlisz poleceniem ^WD. Przed wdrożeniem wydrukuj etykietę testową z „ąćęłńóśźż” wybraną czcionką.

Przykładowa etykieta ZPL (Zebra) krok po kroku

Poniższa etykieta jest zbudowana wyłącznie z poleceń opisanych wyżej. Zakłada drukarkę 203 dpi i etykietę o długości 50 mm (^LL400 – zgodnie z przelicznikiem z ZPL Programming Guide).

^XA ^CI28 ^LL400 ^FO30,30^A0N,40,40^FDZażółć gęślą jaźń^FS ^FO30,90^A0N,30,30^FDIndeks: ABC12345^FS ^FO30,140^BY2^BCN,80,Y,N,N^FDABC12345^FS ^FO30,280^BXN,6,200^FDABC12345^FS ^FO150,270^BQN,2,4^FDQA,ABC12345^FS ^XZ

1. ^XA otwiera format, ^CI28 przełącza na UTF-8, ^LL400 ustawia długość etykiety (umieszczamy je na początku formatu, przed polami).
2. Dwa pola tekstowe czcionką 0 w orientacji normalnej.
3. Code 128 o wysokości 80 punktów, z linią tekstu pod kodem, moduł 2 punkty (^BY2).
4. Data Matrix ECC 200 z elementem 6 punktów.
5. QR model 2 z powiększeniem 4 i korekcją Q (QA, na początku danych).
6. ^XZ zamyka format.

W systemie ERP/WMS stałe elementy zostają w szablonie, a program podmienia tylko dane w polach ^FD (np. indeks, partię, numer zamówienia). Jeżeli etykieta ma trafiać do przesyłek kurierskich, zobacz też, jak drukować etykiety kurierskie 100×150 na drukarce Zebra z plików ZPL generowanych przez przewoźników.

Jak wysłać ZPL z ERP/WMS do drukarki

1. Bezpośrednio po sieci – port 9100

Drukarka Zebra z Ethernetem lub Wi-Fi nasłuchuje zleceń na porcie TCP ustawionym w parametrze SGD ip.port – według ZPL Programming Guide wartość domyślna to 9100 (dopuszczalne 1–65535 z wyłączeniem portów innych usług, np. 21, 23, 80, 515). Bieżącą wartość sprawdzisz poleceniem ! U1 getvar "ip.port". Ten sam port jest stałą DEFAULT_ZPL_TCP_PORT w Link-OS SDK (dla CPCL: 6101).

W praktyce serwer ERP/WMS otwiera połączenie TCP z adresem IP drukarki na porcie 9100 i wysyła tekst ZPL – bez sterownika i bez konwersji do grafiki. To najprostsza droga przy drukarkach sieciowych, np. Zebra ZD421 203 dpi USB/USB Host/BT/Ethernet (termiczna bezpośrednia) lub Zebra ZD421 203 dpi Ethernet BT USB Host (termotransferowa). Specyfikacja ZD421 wymienia w firmware ZPL II, EPL 2, XML, ZBI i PDF Direct. Różnice między modelami ZD230, ZD421 i ZD621 opisujemy w porównaniu drukarek biurkowych Zebra.

2. Przez sterownik ZDesigner (Windows)

Gdy aplikacja drukuje „na drukarkę Windows”, potrzebny jest sterownik. Według informacji o wydaniu sterownik ZDesigner w wersji 10 obsługuje drukarki z Link-OS i język ZPL, działa w Windows 10 i 11 oraz Windows Server 2019, 2022 i 2025; drukarki EPL i CPCL obsługuje sterownik w wersji 5.x. Przydatne zakładki opisane przez Zebra:

• Stocks – definiowanie własnych rozmiarów etykiet,
• Custom Commands – polecenia (ZPL, EPL, CPCL lub SGD) wysyłane do drukarki przy każdym wydruku,
• Command Fonts – wysyłanie kodu drukarki bezpośrednio z dokumentu lub pliku ZebraDesigner.

Sterownik ma też funkcję passthrough (przekazywania kodu ZPL w treści dokumentu). Informacje o wydaniu ostrzegają, że znaki -, < i > w sekwencji początkowej mogą powodować problemy, i proponują zmianę sekwencji np. na STARTOFZPLSEQUENCE.

3. Link-OS Multiplatform SDK

Gdy piszesz własną aplikację, Zebra udostępnia Link-OS Multiplatform SDK z API dla Androida (Java), iOS (Objective-C), .NET MAUI 9 i 10 (Windows, Android, iOS), Javy na komputery PC oraz Javy dla serwerów WWW (połączenia Weblink przez WebSocket). W pakiecie są biblioteki, dokumentacja API i przykłady z kodem źródłowym. Klasa TcpConnection nawiązuje połączenie TCP z drukarką – tą samą drogą co port 9100. Dla aplikacji mobilnej na terminalu w magazynie warto sprawdzić, jak kolektor danych współpracuje z programem magazynowym.

4. Z przeglądarki – Zebra Browser Print

Dla systemów webowych (WMS w przeglądarce) Zebra oferuje Browser Print. Według przewodnika użytkownika (wersja 1.3) składa się z aplikacji działającej w tle na komputerze i biblioteki JavaScript (BrowserPrint.js), którą dołączasz do strony. Najważniejsze informacje z tego dokumentu:

• system: Windows 7 i 10 oraz macOS od 10.10; przeglądarki: Chrome 75+, Firefox 70+, Internet Explorer 11+, Edge 44+, Opera 65+, Safari 13+,
• wykrywa drukarki podłączone przez USB i sieć; drukuje „RAW” w ZPL II, a także obrazy PNG, JPG i BMP,
• nie załaduje firmware ani czcionek; limit przesyłu to 2 MB,
• nie uruchomi się, jeśli inny program na komputerze używa portów 9100 lub 9101,
• strony przykładowe muszą być serwowane z serwera WWW, a nie otwierane jako pliki lokalne.

Szablony w drukarce: ^DF, ^FN, ^XF

Zamiast wysyłać przy każdym wydruku cały układ etykiety, możesz zapisać szablon w drukarce, a potem przesyłać tylko dane:

• ^DFd:o.x – zapisuje format (wpisz bezpośrednio po ^XA). Urządzenie: R:, E:, B: lub A: (domyślnie R:), nazwa 1–16 znaków, rozszerzenie .ZPL.
• ^FN# – numer pola (0–9999); w szablonie zastępuje ^FD.
• ^XFd:o.x – przywołuje zapisany format; dokumentacja tego polecenia podaje nazwę 1–8 znaków, więc krótka nazwa zadziała w obu przypadkach.

Przykład z ćwiczeń ZPL II Zebra (skrócony). Zapis szablonu:

^XA ^DFR:SAMPLE.ZPL^FS ^FO30,40^ADN,36,20^FDShip to:^FS ^FO150,125^ADN,36,20^FN1^FS ^FO60,330^ADN,36,20^FN2^FS ^FO70,480^BY4^B3N,,200^FN4^FS ^XZ

Wydruk z danymi:

^XA ^XFR:SAMPLE.ZPL ^FN1^FDAcme Printing^FS ^FN2^FD14042^FS ^FN4^FD12345678^FS ^XZ

ZPL Programming Guide zaznacza, że zapisane formaty skracają czas transmisji, ale nie czas formatowania – szablon jest przechowywany jako tekst i drukarka i tak składa etykietę przy wydruku. Liczbę pól ogranicza pamięć drukarki; dokumentacja ^FN zaleca nie więcej niż 400 pól.

Testowanie i diagnostyka

• Podgląd przed wydrukiem. Labelary to zewnętrzny serwis (nie jest częścią dokumentacji Zebra), który na swojej stronie opisuje „Online ZPL Viewer” do edycji i podglądu etykiet ZPL – z wyborem gęstości druku 6, 8, 12 lub 24 punktów/mm i rozmiaru etykiety. Ma też API, które zamienia ZPL na PNG lub PDF; plan darmowy to według cennika m.in. 5000 zapytań dziennie i 50 etykiet na zapytanie, bez gwarancji braku przechowywania danych (Zero Data Retention: „No”). Nie wysyłaj tam danych wrażliwych.
• Tryb diagnostyki komunikacji. W ZT411/ZT421 włączysz go z menu TOOLS albo przytrzymując PAUSE + FEED przez 2 sekundy w stanie gotowości – drukarka drukuje wtedy wartości szesnastkowe wszystkich odebranych danych. Zobaczysz, co faktycznie wysyła Twój system.
• Dane dochodzą, ale nic się nie drukuje? Instrukcja ZD421/ZD621 wskazuje trzy przyczyny: znaki prefiksu i separatora w drukarce inne niż w formacie, niezgodne ustawienia komunikacji po stronie komputera albo błąd w samym formacie etykiety. Pozostałe przypadki opisujemy w artykule Drukarka Zebra nie drukuje lub pomija etykiety.

Przy wyborze drukarki do integracji z ERP/WMS zacznij od przewodnika po drukarkach etykiet dla firmy, a modele znajdziesz w kategoriach drukarki etykiet biurkowe, drukarki etykiet przemysłowe i drukarki etykiet do magazynu. Przy dużych wolumenach druku sprawdzi się drukarka przemysłowa, np. Zebra ZT411 203 dpi Ethernet RS232 Bluetooth – karta produktu wymienia emulacje ZPL, ZPL II i EPL. Biurkowa alternatywa z Ethernetem do druku termotransferowego to Zebra ZD621t 203 dpi, termotransferowa, Ethernet, BLE.

Integrujesz druk etykiet z ERP lub WMS i potrzebujesz dobrać drukarki, przygotować je do pracy albo uzyskać cenę projektową na większą liczbę urządzeń? Skontaktuj się z nami – zajmujemy się doborem sprzętu, konfiguracją i integracją z systemami magazynowymi i ERP.

Źródła

• Zebra – ZPL Programming Guide: ^XA
• Zebra – ZPL Programming Guide: ^FO
• Zebra – ZPL Programming Guide: ^A (Scalable/Bitmapped Font)
• Zebra – ZPL Programming Guide: ^BY
• Zebra – ZPL Programming Guide: ^BC (Code 128)
• Zebra – ZPL Programming Guide: ^BX (Data Matrix)
• Zebra – ZPL Programming Guide: ^BQ (QR Code)
• Zebra – ZPL Programming Guide: ^CI
• Zebra – ZPL Programming Guide: ^FH
• Zebra – ZPL Programming Guide: ^LL
• Zebra – ZPL Programming Guide: SGD zpl.label_length
• Zebra – ZPL Programming Guide: ^DF
• Zebra – ZPL Programming Guide: ^XF
• Zebra – ZPL Programming Guide: ^FN
• Zebra – ZPL Programming Guide: SGD ip.port
• Zebra – ZPL II Exercises (PDF)
• Zebra – ZD421/ZD621 User Guide: Configuration Setting to Command Cross-reference
• Zebra – ZD421/ZD621 User Guide: Label Job Sent, Data Transfers, But No Print
• Zebra – ZD411t User Guide: Printer Fonts
• Zebra – ZT411/ZT421 User Guide: Calibration and Diagnostic Tools
• Zebra – Link-OS Multiplatform SDK
• Zebra – Link-OS SDK: TcpConnection
• Zebra – Link-OS SDK: Constant Field Values
• Zebra – Browser Print User Guide v1.3 (PDF)
• Zebra – ZDesigner Windows Driver Release Notes v10.6.26.28275
• Zebra Support – ZDesigner Driver Additional Tabs Descriptions
• Zebra – ZD421 Spec Sheet
• Labelary – Online ZPL Viewer
• Labelary – ZPL Web Service (API)