Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

ZPL Simulator

A small, offline Windows printer simulator. Applications submit raw ZPL to a Windows printer named ZPL Simulator. A background Windows service renders the labels and prints them to Microsoft Print to PDF, saving a uniquely named PDF automatically.

No browser, web server, cloud rendering, Python, Java, or paid API. C# / .NET 10, the built-in Windows TCP/IP print port and Generic / Text Only driver, and BinaryKits.Zpl.Viewer for rendering. The default installer includes the .NET runtime, so end users do not need to install development tools. Runs at boot even when nobody is logged in.

Install

Requires Windows 10/11 x64, the Windows Print Spooler, and administrator rights for installation. Building from source also requires the .NET 10 SDK and internet access to restore NuGet packages. The default packaged app includes its runtime and runs offline.

A fresh clone or GitHub source ZIP does not contain artifacts/. That directory is generated by the build and excluded from Git. Use one of the following installation paths.

Build and install from source

Clone this repository or download and extract its source ZIP. Open PowerShell in the repository root—the directory containing this README and scripts—then run:

dotnet --version  # Confirm the .NET 10 SDK is installed
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\Build.ps1
.\artifacts\ZplSimulator\Install.cmd

Wait for the build to finish successfully before running the installer. Accept the Windows elevation prompt. The build creates:

Output Purpose
artifacts\ZplSimulator\ Complete installer folder, including Install.cmd and the app payload.
artifacts\ZplSimulator-win-x64.zip The same folder packaged for distribution to other Windows PCs.

Do not run installer\Install.ps1 directly from a fresh clone: it is installer source and has no compiled app payload beside it.

Install a prebuilt package

If a maintainer has published a release, download ZplSimulator-Setup.exe or ZplSimulator-win-x64.zip from that release's assets. GitHub's automatically generated Source code ZIP is not an installer.

  • Setup.exe: Run it and accept Windows elevation.
  • Installer ZIP: Extract the entire ZIP, then double-click Install.cmd inside the extracted folder. Keep the folder for repair/uninstall.

Builds are also configured in this repository's Actions → Build Windows installer workflow. A successful run uploads an artifact named ZplSimulator-windows-x64, containing Setup.exe and the installer ZIP. If you download that artifact, extract its outer ZIP first, then use either installer inside. The workflow does not automatically publish GitHub Releases. If no prebuilt package is available, build from source as described above.

After installation, confirm ZPL Simulator appears in Windows Printers & scanners.

The installer enables the Microsoft PDF printing feature if the default target is missing. If Windows requires a restart or still has no PDF queue, enable/install Microsoft Print to PDF in Windows and rerun the installer. It never replaces the default Windows printer.

Both installers use the same installation script. Building Setup.exe is optional; see Build options and verification.

Try a label

After installation, open PowerShell in either the repository root or the extracted installer folder:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\Send-Zpl.ps1 -Path .\samples\test-label.zpl
explorer C:\ProgramData\ZplSimulator\Output

If you installed with Setup.exe and have no source checkout, these same sample files are installed in C:\Program Files\ZplSimulator; run the commands from that folder. If you changed the simulated printer's name, add -PrinterName 'Your printer name' to the sender command.

Your application must send ZPL as RAW printer data, using WritePrinter or its equivalent. Printing a text file from Notepad, a Windows test page, Word, or a browser does not send raw ZPL. This is a ZPL printer emulator, not a driver that converts ordinary documents into labels. A label application can use its Zebra/ZPL output mode and send those bytes to the simulator queue. The included sender demonstrates the Windows RAW spooler path.

Programs can also send bytes directly to 127.0.0.1:19100. Close the connection after each job; multiple complete ^XA ... ^XZ labels in one connection produce multiple pages in one PDF. Connections idle for 30 seconds are rejected and their partial data retained. The listener is local-only; no firewall opening is required.

Configure

After installation, edit C:\ProgramData\ZplSimulator\config.json as administrator. The installer copies the packaged defaults there on first installation and preserves existing configuration on subsequent runs. Editing installer\config.json in the source tree only changes defaults for future builds and new installations.

{
  "PrinterName": "ZPL Simulator",
  "TargetPrinter": "Microsoft Print to PDF",
  "Port": 19100,
  "OutputDirectory": "C:\\ProgramData\\ZplSimulator\\Output",
  "PrintToFile": true,
  "PaperMode": "PrinterDefault",
  "DotsPerMillimeter": 8,
  "LabelWidthMm": 101.6,
  "LabelHeightMm": 152.4,
  "MaxJobBytes": 16777216,
  "MaxPages": 100,
  "RejectUnknownCommands": false
}
Setting Behavior
PrinterName Name of the simulated Windows queue. Rerun Install.cmd after changing it.
TargetPrinter Exact installed Windows destination name. Reloaded for each job. Must differ from the input queue.
PrintToFile true for Microsoft Print to PDF. Set false for a physical printer. Other PDF drivers must support unattended GDI output-file printing.
OutputDirectory Absolute local output folder. The service runs as LocalSystem and needs write access; mapped user drives are unavailable.
PaperMode PrinterDefault centers each label on the target's default paper and scales down only if needed. Label requests exact label-sized paper and fails if the driver substitutes another size. Microsoft PDF custom-size support varies; default-paper mode works without installing custom forms.
DotsPerMillimeter 6, 8, 12, or 24. Usually 8 for a nominal 203 dpi Zebra, 12 for 300 dpi.
LabelWidthMm, LabelHeightMm Default canvas when ZPL omits ^PW / ^LL. Explicit dimensions are dots divided by density.
Port Local RAW TCP port. Rerun installer after changing.
RejectUnknownCommands false logs unsupported commands; true rejects the job. Rendering mistakes still cause failure in either mode.

Target, output, and rendering settings reload between jobs. Queue-name/port changes require running Install.cmd again from your built/extracted installer folder, or from C:\Program Files\ZplSimulator for a Setup.exe installation. Existing config is preserved. Clear pending Windows jobs before renaming the input queue. Avoid routing the target to another queue that points back to this simulator.

Compatibility

The renderer covers common ZPL II text, fields, rotation, boxes/lines, Code 128 and other common barcodes, QR codes, and supported ASCII/compressed graphics. ^PW, ^LL, multiple labels and the basic ^PQ quantity are handled by this app. Text input supports default CP850 or UTF-8 when the job uses ^CI28; use one encoding per job.

It does not render every possible ZPL format. The rendering engine is an approximation of Zebra firmware. Changed command delimiters, binary graphic downloads, downloaded fonts, stored/recalled formats, serialization, and persistent printer memory across jobs are unsupported. Supply expanded, self-contained labels. Graphics downloaded in the same job can be recalled. Additional ^PQ options are logged but not simulated. Other unsupported commands are logged or rejected according to RejectUnknownCommands; font metrics and device-specific behavior can differ. Check representative labels before relying on barcode geometry or physical dimensions.

Each label is rasterized at the configured printer density before being sent to Windows; PDF text is not searchable. Physical printers may have unprintable margins. A job is limited to 16 MiB and 100 pages by default; each label is capped at 25 megapixels. The simulator does not implement Zebra status-query protocols, EPL, CPCL, ESC/POS, PDF input, or arbitrary Windows document printing.

Renderer documentation and supported elements: BinaryKits.Zpl. Windows integration uses GDI printing and a standard TCP/IP printer port.

Troubleshooting / uninstall

  • Logs: C:\ProgramData\ZplSimulator\service.log (rotates at 5 MB).
  • Failed inputs and reasons: C:\ProgramData\ZplSimulator\Failed.
  • Accepted jobs waiting to render: C:\ProgramData\ZplSimulator\Pending.
  • Manage service: Get-Service ZplSimulator / Restart-Service ZplSimulator in elevated PowerShell.
  • Inspect both the simulated and destination queues if a PDF does not appear. Windows completing the RAW input job means the service received it; it does not guarantee the destination printed it.
  • Jobs interrupted during receiving or printing are kept for manual inspection rather than automatically reprinted. A failed job may already have reached the destination, so check it before resending with Send-Zpl.ps1.
  • Successful raw inputs are deleted; PDFs remain until you delete them. Failed jobs also remain until you remove them.
  • No listener? Check invalid JSON, port conflicts, or missing runtime/native DLLs. For console diagnostics, stop the service first and run & 'C:\Program Files\ZplSimulator\app\ZplSimulator.exe' --console in elevated PowerShell.
  • Double-click Uninstall.cmd in your built/extracted installer folder, or use Windows Installed apps / Apps & features if installed with Setup.exe. Config, PDFs, and failed jobs are preserved; the simulator queue, port, service, and app are removed. The shared Generic driver and Microsoft PDF feature remain installed.

Build options and verification

Run these commands from the repository root on Windows with the .NET 10 SDK. To also build a conventional Setup.exe, install Inno Setup 6, then run:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\Build.ps1 -SetupExe

This creates artifacts\ZplSimulator-Setup.exe as well as the installer folder and ZIP. The basic build in the installation instructions does not require Inno Setup.

For the smallest distribution on PCs that already have the .NET 10 x64 runtime, add -FrameworkDependent to either build command. Do not trim this application: the rendering library uses reflection.

Renderer checks (Linux or Windows with the .NET 10 SDK, from the repository root; no prior app build or printer installation required):

dotnet run --project tests/RendererChecks.csproj -- samples/test-label.zpl artifacts/preview

Preview without printing on Windows, after building the app:

.\artifacts\ZplSimulator\app\ZplSimulator.exe --render .\samples\test-label.zpl .\artifacts\preview .\installer\config.json

To test PDF printing without installing the simulator, use --print in place of --render in the preview command. This creates a PDF in the given output folder through the configured Windows PDF printer.

Test the complete Windows queue → service → PDF path after installing the simulator, from the repository root or extracted installer folder:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\SmokeTest-Windows.ps1

This check requires the running service and the default Microsoft Print to PDF destination. It submits the sample and checks the resulting PDF header; inspect the PDF to verify the label's appearance. Renderer tests alone do not verify service installation or Windows printing.

Licensed under the MIT License. Third-party packages retain their respective licenses; see THIRD-PARTY-NOTICES.md.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages