Quick Developer Guide

EPLServer listens on a single TCP port 48321 and accepts EPL commands in two ways:

• HTTP POST — Send a JSON payload to a REST endpoint. Best for application integration.
• Raw TCP socket — Open a socket and write EPL or JSON directly. Best for printer emulation and legacy tools.

You can check the port currently in use under the Settings web UI tab (eplserver --settings), or run eplserver --port from the command line.

1 — Sending EPL via HTTP (REST API)

EPLServer exposes two HTTP endpoints on the same port used by the web interface.

JSON Payload Reference

Send Content-Type: application/json with a body like the example below. All fields are optional and fall back to the values configured in the Settings web UI tab (eplserver --settings).

HTTP Examples

• Windows PowerShell — render to PNG and save to disk

  $epl = @" N q609 Q203,26 B26,26,0,UA0,2,2,152,B,"603679025109" A253,26,0,3,1,1,N,"SKU 6205518 MFG 6354" A253,56,0,3,1,1,N,"2XIST TROPICAL BEACH" A253,86,0,3,1,1,N,"STRIPE SQUARE CUT TRUNK" A253,116,0,3,1,1,N,"BRICK" A253,146,0,3,1,1,N,"X-LARGE" P1 "@ $body = @{ eplCommands = $epl dpi = 203 labelWidthInchUnit = 4 labelHeightInchUnit= 6 action = "writetofile" fileFormat = "PNG" fileFolder = "{Temp}/labels" } | ConvertTo-Json Invoke-RestMethod -Method Post ` -Uri "http://localhost:48321/render" ` -ContentType "application/json" ` -Body $body ` -OutFile "label.png"
• Windows PowerShell — receive raw bytes from /render

  $epl = @" N q609 Q203,26 B26,26,0,UA0,2,2,152,B,"603679025109" A253,26,0,3,1,1,N,"SKU 6205518 MFG 6354" A253,56,0,3,1,1,N,"2XIST TROPICAL BEACH" A253,86,0,3,1,1,N,"STRIPE SQUARE CUT TRUNK" A253,116,0,3,1,1,N,"BRICK" A253,146,0,3,1,1,N,"X-LARGE" P1 "@ $body = @{ eplCommands = $epl dpi = 203 labelWidthInchUnit = 4 labelHeightInchUnit= 6 fileFormat = "PNG" } | ConvertTo-Json Invoke-RestMethod -Method Post ` -Uri "http://localhost:48321/render" ` -ContentType "application/json" ` -Body $body ` -OutFile "label.png"
• macOS / Linux curl — render to PNG (binary output)

  curl -s -X POST "http://localhost:48321/render" \ -H "Content-Type: application/json" \ -d '{ "eplCommands": "N q609 Q203,26 B26,26,0,UA0,2,2,152,B,\"603679025109\" A253,26,0,3,1,1,N,\"SKU 6205518 MFG 6354\" A253,56,0,3,1,1,N,\"2XIST TROPICAL BEACH\" A253,86,0,3,1,1,N,\"STRIPE SQUARE CUT TRUNK\" A253,116,0,3,1,1,N,\"BRICK\" A253,146,0,3,1,1,N,\"X-LARGE\" P1", "dpi": 203, "labelWidthInchUnit": 4, "labelHeightInchUnit": 6, "fileFormat": "PNG" }' \ -o label.png
• macOS / Linux curl — render to PDF and save to a folder

  curl -s -X POST "http://localhost:48321/render" \ -H "Content-Type: application/json" \ -d '{ "eplCommands": "N q609 Q203,26 B26,26,0,UA0,2,2,152,B,\"603679025109\" A253,26,0,3,1,1,N,\"SKU 6205518 MFG 6354\" A253,56,0,3,1,1,N,\"2XIST TROPICAL BEACH\" A253,86,0,3,1,1,N,\"STRIPE SQUARE CUT TRUNK\" A253,116,0,3,1,1,N,\"BRICK\" A253,146,0,3,1,1,N,\"X-LARGE\" P1", "dpi": 203, "labelWidthInchUnit": 4, "labelHeightInchUnit": 6, "fileFormat": "PDF" }' \ -o label.pdf
• macOS / Linux curl — forward rendered output to a webhook

  curl -s -X POST http://localhost:48321/render \ -H "Content-Type: application/json" \ -d '{ "eplCommands": "N q609 Q203,26 B26,26,0,UA0,2,2,152,B,\"603679025109\" A253,26,0,3,1,1,N,\"SKU 6205518 MFG 6354\" A253,56,0,3,1,1,N,\"2XIST TROPICAL BEACH\" A253,86,0,3,1,1,N,\"STRIPE SQUARE CUT TRUNK\" A253,116,0,3,1,1,N,\"BRICK\" A253,146,0,3,1,1,N,\"X-LARGE\" P1", "fileFormat": "PNG", "action": "forward", "forwardTo": "https://my.server.com/label-webhook" }'

2 — Sending EPL via Raw TCP Socket

EPLServer listens on the same port for raw TCP connections. You can write either:

• Plain EPL commands (e.g. ^XA...^XZ) — the server uses the settings from the Settings web UI tab (eplserver --settings).
• A complete JSON payload — the server parses it and applies any overrides before rendering.

This mode is compatible with any tool or language that can open a TCP socket: Zebra printers, legacy applications, scripts, etc.

Raw Socket Examples

• Windows PowerShell — send raw EPL over TCP

  $epl = @" N q609 Q203,26 B26,26,0,UA0,2,2,152,B,"603679025109" A253,26,0,3,1,1,N,"SKU 6205518 MFG 6354" A253,56,0,3,1,1,N,"2XIST TROPICAL BEACH" A253,86,0,3,1,1,N,"STRIPE SQUARE CUT TRUNK" A253,116,0,3,1,1,N,"BRICK" A253,146,0,3,1,1,N,"X-LARGE" P1 "@ $port = 48321 $enc = [System.Text.Encoding]::GetEncoding(850) $client = New-Object System.Net.Sockets.TcpClient("127.0.0.1", $port) $stream = $client.GetStream() $bytes = $enc.GetBytes($epl) $stream.Write($bytes, 0, $bytes.Length) $stream.Flush() $stream.Close() $client.Close()
• Windows PowerShell — send JSON payload over TCP

  $epl = @" N q609 Q203,26 B26,26,0,UA0,2,2,152,B,"603679025109" A253,26,0,3,1,1,N,"SKU 6205518 MFG 6354" A253,56,0,3,1,1,N,"2XIST TROPICAL BEACH" A253,86,0,3,1,1,N,"STRIPE SQUARE CUT TRUNK" A253,116,0,3,1,1,N,"BRICK" A253,146,0,3,1,1,N,"X-LARGE" P1 "@ $json = @{ eplCommands = $epl dpi = 203 labelWidthInchUnit = 4 labelHeightInchUnit= 6 fileFormat = "PDF" action = "writetofile" fileFolder = "{Temp}/labels" } | ConvertTo-Json -Compress $port = 48321 $enc = [System.Text.Encoding]::UTF8 $client = New-Object System.Net.Sockets.TcpClient("127.0.0.1", $port) $stream = $client.GetStream() $bytes = $enc.GetBytes($json) $stream.Write($bytes, 0, $bytes.Length) $stream.Flush() $stream.Close() $client.Close()
• macOS / Linux nc (netcat) — send raw EPL

  #!/bin/bash PORT="48321" nc -w 2 127.0.0.1 "$PORT" << 'EOF' N q609 Q203,26 B26,26,0,UA0,2,2,152,B,"603679025109" A253,26,0,3,1,1,N,"SKU 6205518 MFG 6354" A253,56,0,3,1,1,N,"2XIST TROPICAL BEACH" A253,86,0,3,1,1,N,"STRIPE SQUARE CUT TRUNK" A253,116,0,3,1,1,N,"BRICK" A253,146,0,3,1,1,N,"X-LARGE" P1 EOF
• macOS / Linux nc (netcat) — send a JSON payload from a file

  # Create payload.json first, then: nc 127.0.0.1 48321 < payload.json
• Linux bash /dev/tcp — no extra tools needed

  #!/bin/bash PORT="48321" EPL=$'N\r\nq609\r\nQ203,26\r\nB26,26,0,UA0,2,2,152,B,"603679025109"\r\nA253,26,0,3,1,1,N,"SKU 6205518 MFG 6354"\r\nA253,56,0,3,1,1,N,"2XIST TROPICAL BEACH"\r\nA253,86,0,3,1,1,N,"STRIPE SQUARE CUT TRUNK"\r\nA253,116,0,3,1,1,N,"BRICK"\r\nA253,146,0,3,1,1,N,"X-LARGE"\r\nP1\r\n' exec 3>"/dev/tcp/127.0.0.1/$PORT" printf "%s" "$EPL" >&3 exec 3>&-

3a — Windows Virtual Printer Setup

On Windows you can configure EPLServer as a Standard TCP/IP printer port. Any application that prints to this virtual printer will have its EPL stream captured and processed by EPLServer automatically.

1. Open Devices and Printers:
   • Windows 11 / 10 Right-click Start → Settings → Bluetooth & devices → Printers & scanners
   • Windows 8 / 7 Start → Control Panel → Hardware and Sound → Devices and Printers
2. Click Add a printer → The printer that I want isn't listed.
3. Select Add a local printer or network printer with manual settings → Next.
4. Select Create a new port, choose Standard TCP/IP Port → Next.
5. Enter:
   • Host Name or IP Address: 127.0.0.1
   • Port Name: any name you like, e.g. EPLServer_local
   • Uncheck Query the printer and automatically select the driver to use
6. When prompted for a driver, choose any Generic / Text Only driver.
7. After the port is created, open its Properties → Ports tab → select the port → Configure Port and set the Port Number to match the value returned by EPLServer.exe --port.
8. Click Finish. The new printer will now forward all print jobs to EPLServer.

3b — Linux: CUPS Virtual Printer Setup

On Linux you can add EPLServer as a raw CUPS printer. Any application that prints to it will have its EPL stream sent directly to EPLServer over a socket connection.

Option A — Command line (recommended)

Run the following as a user with lpadmin privileges (or prefix with sudo):

# Add the printer — replace 48321 with the port shown by eplserver --port
            lpadmin -p EPLServer \
                    -E \
                    -v socket://127.0.0.1:48321 \
                    -m raw \
                    -D "EPLServer virtual EPL printer" \
                    -L "localhost"

            # Set it as the system default (optional)
            lpoptions -d EPLServer

The -m raw flag tells CUPS to forward the print data unmodified — no driver translation occurs, so EPL commands reach EPLServer exactly as sent by the application.

Option B — CUPS web interface

1. Open http://localhost:631 in a browser.
2. Go to Administration Add Printer.
3. Select AppSocket/HP JetDirect and click Continue.
4. Set the connection URI to:

   socket://127.0.0.1:48321

5. Give it a name (e.g. EPLServer), click Continue.
6. Under Make choose Raw, under Model choose Raw Queue (en).
7. Click Add Printer. Done.

3c — macOS: Printers & Scanners Setup

macOS uses CUPS under the hood, so the same raw socket approach works. You can add EPLServer either through the Printers & Scanners System Settings panel or from the Terminal.

Option A — Terminal (fastest)

# Replace 48321 with the port shown by eplserver --port
            lpadmin -p EPLServer \
                    -E \
                    -v socket://127.0.0.1:48321 \
                    -m raw \
                    -D "EPLServer virtual EPL printer"

            # Set as default printer (optional)
            lpoptions -d EPLServer

Option B — System Settings GUI

1. Open System Settings (macOS Ventura 13+) or System Preferences (macOS Monterey 12 and earlier) Printers & Scanners.
2. Click the (Add Printer) button.
3. In the Add Printer dialog, click the IP tab ( globe icon).
4. Fill in the fields:
   • Address: 127.0.0.1
   • Protocol: HP Jetdirect - Socket
   • Queue: leave blank
   • Name: EPLServer (or any name you like)
   • Use / Driver: select Generic PostScript Printer or AirPrint — then immediately change it to Select Software… Generic Generic PostScript Printer. The driver is irrelevant because CUPS will use the raw queue.
5. Click Add. The printer appears in the list.
6. Important: right-click (or Control-click) the new printer in the list and choose Show Printers in Finder to verify the queue name, then match it to the port configured in EPLServer which can be obtained through eplserver --port.

4 — Command-Line Interface (CLI)

Run eplserver from a terminal with the following flags:

EPL Commands Support

EPLServer rendering engine supports most of the EPL formatting and control commands. The following table lists the supported commands. Not listed or unsupported commands will be skipped in the parsing stage.