DEV Community: Alex Radulovic

We Spent Days Fighting a Zebra Card Printer. So You Don't Have To.

Alex Radulovic — Thu, 26 Mar 2026 20:09:07 +0000

If you've ever tried to programmatically control a Zebra ZC350 card printer, you already know the pain. And if you haven't, let me save you some time: it's considerable. I want to save you the pain, even if you are a competitor.

Feed a card. Encode an NFC chip. Print a badge. Eject it. Sounds simple. It wasn't.

We built an open-source bridge called Dazzle because a client needed automated card issuance inside a larger workflow, and getting from "nice hardware" to "working software" was much harder than it should have been.

If you're going to have zebra problems, you might as well answer them with Dazzle. Bonus points if you get the reference.

At one point we spent hours staring at APDU responses that all came back 6900, trying to figure out whether we were talking to the card, the reader, the SAM, or something undocumented in between.

So we open-sourced the thing we wish we'd had on day one.

What Dazzle Does

Dazzle is a .NET 8 helper that runs as a child process and speaks JSON over stdin/stdout.

Your app, whether it's Node.js, Python, or anything else that can spawn a process and read lines, sends commands like:

feed
smartcard.connect
smartcard.transmit
eject

The helper talks to the Zebra printer and its internal smart-card encoder, then sends structured results back.

The goal is simple: keep the ugly vendor-specific parts out of your app code.

A typical flow looks like this:

const printer = new ZebraCardPrinter();
await printer.start();
await printer.connect("192.168.1.100");

await printer.feed();
const readers = await printer.getReaders();
await printer.smartcardConnect(readers.contactless);

const uid = await printer.smartcardTransmit("FFCA000000");
console.log("Card UID:", uid.response);

await printer.smartcardDisconnect();
await printer.eject();

The point is to make card issuance feel like normal application code.

Why We Built It

At PurpleOwl, we build custom business software for small and mid-sized companies. In this case, the project needed NFC-enabled ID card issuance as part of a larger operational workflow.

The Zebra ZC350 hardware is solid. The integration story was not.

What Made This Hard

Here are the problems that made us build Dazzle.

1. The SDK Isn't Distributed Like a Normal Dependency

There is no clean npm install or dotnet add package path for the Zebra Card SDK.

You download a large installer, dig through C:\Program Files\Zebra Technologies\ for DLLs, manually copy them into your project, and add references one by one.

Every new machine gets the same ritual. No normal dependency management. No clean reproducible setup.

2. USB Discovery Was Surprisingly Fragile

Finding a USB-connected printer should have been a solved problem.

Instead, the relevant class could live in a separate assembly that was not always loaded, and the property holding the USB address changed names across SDK versions:

SymbolicName
UsbSymbolicName
Address
DeviceId

We ended up using reflection to locate the type, invoke the discovery method, and probe multiple property names until one worked.

3. Connections Could Fail Without Looking Failed

The TCP connection to the printer can drop while still leaving you with an object that appears usable.

So IsConnected might look fine right up until the next SDK call hangs, throws from somewhere deep in the stack, or returns nonsense.

Dazzle wraps operations with reconnection logic because trusting the reported connection state turned out to be a mistake.

4. "Card Present" Did Not Mean "Card Ready"

After feeding a card into the encoder station, there is a delay before the PC/SC reader fully recognizes it.

During that window, the card can show up as present but unpowered. Connect too early and you get RemovedCard even though the card is physically there.

So Dazzle waits until the card is both present and powered before trying to connect.

The Cindy0 Problem

This one cost us the most time.

We connected to the printer's internal smart-card encoder over PC/SC, decoded the ATR's historical bytes to ASCII, and got:

Cindy0

Every APDU came back 6900.

Read UID? 6900.

Authenticate? 6900.

Write? 6900.

We assumed we were talking to the wrong slot, maybe the SAM instead of the contactless card, so we tried configuration changes, different share modes, transparent RF commands, IOCTLs, and a lot of other dead ends.

The real answer was stranger: Cindy0 is the Elatec TWN4 reader's virtual slot. It is not the card. It is a command channel that accepts the reader's "Simple Protocol" wrapped in APDUs.

So standard PC/SC card commands were failing because we were not actually talking to a card.

The actual contactless card appears on a different logical slot, but only after you use that command channel to search for a tag first.

That detail exists in the TWN4 PC/SC docs. It is not surfaced clearly in the Zebra integration story.

Five hours disappeared because a virtual slot was named Cindy0.

What Ships In The Repo

Dazzle includes:

ZebraCardHelper, the .NET helper that manages printer and encoder communication, APDUs, tunneling, and reconnection logic
zebra-card-printer.js, a Node.js wrapper that handles process lifecycle, JSON messaging, request/response correlation, and timeouts
PAINPOINTS.md, a write-up of the gotchas, race conditions, and undocumented behaviors we ran into

If you are doing anything with Zebra card printers and NFC encoding, that pain-points document alone may save you a lot of time.

Why JSON Over stdio

We used JSON over standard input/output because it is simple and portable. Each request has an id, and each response echoes it back.

{ "id": 1, "cmd": "connect", "ip": "192.168.1.100" }
{ "id": 1, "ok": true, "data": { "connected": true } }

{ "id": 2, "cmd": "feed" }
{ "id": 2, "ok": true, "data": { "fed": true } }

{ "id": 3, "cmd": "smartcard.transmit", "apdu": "FFCA000000" }
{ "id": 3, "ok": true, "data": { "response": "04a23b1a9070809000" } }

That keeps the integration language-agnostic. Node.js, Python, Go, or anything else that can spawn a child process and read lines can use it.

Who This Is For

If you're building a system that issues NFC-encoded cards, employee badges, access cards, membership cards, or anything similar on Zebra ZC350 hardware, this project is for you.

It is also for the developer who is already deep in the Zebra SDK and wondering whether the weirdness is their fault.

It probably is not.

Why We Open-Sourced It

We're a five-person shop. We build custom ERP, CRM, and PSA systems. We built Dazzle because a client needed it, and we released it because it felt wasteful to let every future developer rediscover the same problems from scratch.

The hardware is solid. The integration layer does not need to be this punishing.

If Dazzle saves someone else from losing half a day to Cindy0, publishing it was worth it.

I added userId and transactionId to every console.log without refactoring

Alex Radulovic — Wed, 21 Jan 2026 19:44:03 +0000

Almost every JavaScript server starts the same way.

You add a few console.log() calls so you can see what's happening. You deploy. Everything works.

For a while, this is completely fine.

The problem is that this version of "fine" only exists while your system is still small.

As soon as you have multiple users, concurrent requests, and background jobs, logging quietly stops being helpful. Nothing breaks—but nothing is understandable anymore.

What Logging Looks Like Right Before It Fails You

A single user action might:

create or update several records
trigger validations
enqueue background work
call external APIs
finish seconds or minutes later

All of that generates logs. Now multiply by hundreds of users doing the same thing at the same time.

A log like this:

console.log('updating contact', contactId);

Is fine—until you see it 10,000 times a day and have no idea which one matters.

The Conversation Every Team Has (and Then Avoids)

Eventually someone says: "We should really fix logging."

What that usually means is:

passing user IDs everywhere
threading request IDs through layers
replacing console.log() with a custom logger
touching hundreds of files

For small teams, that's not a small task. It's a refactor with no visible feature payoff, so it gets kicked down the road.

We've done that ourselves.

So instead of designing a "proper" logging framework, we imposed a hard constraint:

If adopting this requires rewriting the app, we won't use it.

The Entire Setup (Yes, Really)

At your application entry point:

import { replaceConsole, loggerMiddleware } from '@purpleowl-io/tracepack';

replaceConsole();

Then, after your auth middleware and before your routes:

app.use(loggerMiddleware());

That's it. Two lines.

You don't change your existing logs. You don't update call sites. You don't teach the team a new API.

What Your Logs Look Like After

Before:

contact created

After:

{
  "ts": "2025-01-15T10:23:01.000Z",
  "level": "info",
  "userId": "alex_123",
  "txId": "abc-789",
  "msg": "contact created"
}

Same code. Different outcome.

Now when you have this deeper in your codebase:

function updateContact(data) {
  console.log('updating contact', data.id);
}

The output automatically becomes:

{
  "level": "info",
  "userId": "alex_123",
  "txId": "abc-789",
  "msg": "updating contact",
  "args": [12345]
}

You didn't pass a user ID. You didn't pass a transaction ID. The context followed the execution for you.

Why This Works Without Being Fragile

Under the hood, this uses Node's AsyncLocalStorage to attach context to the execution path, not to individual function calls.

That context survives:

await
promises
database drivers
network calls
timers
background work

Once a request starts, everything it touches can log with the same identity—even if the work fans out across multiple async layers.

Adding Business Context

Sometimes user + transaction isn't enough.

import { log } from '@purpleowl-io/tracepack';

log.addContext({ orderId: req.body.id });

From that point forward, every log in that async chain includes orderId.

Background Jobs and Scripts

For non-HTTP code, you can explicitly establish context:

import { withContext } from '@purpleowl-io/tracepack';

await withContext(
  { userId: 'system', txId: 'nightly-job-001' },
  async () => {
    console.log('starting batch');
    await processBatch();
    console.log('batch complete');
  }
);

Those logs still look exactly like request logs—structured, searchable, and correlated.

Filtering With jq

All output is clean JSON, one log entry per line:

# Filter by transaction
node app.js | jq 'select(.txId == "abc-789")'

# Filter by user
node app.js | jq 'select(.userId == "alex_123")'

# Errors only
node app.js | jq 'select(.level == "error")'

Get It

npm i @purpleowl-io/tracepack

npm: https://www.npmjs.com/package/@purpleowl-io/tracepack
GitHub: https://github.com/purpleowl-io/tracepack

We built this because we were tired of reading logs that couldn't answer the questions we actually had.

If your system is still small enough that logs are readable by default, great. Enjoy it while it lasts.

If you've crossed the line where concurrency has turned debugging into guesswork, this is a small change that pays off every single time something breaks.

Happy to answer questions about the implementation or tradeoffs.