← All writing

Nov 15, 2026

Building Ferrite: Porting pyzk to Rust Without Dropping a Single Punch

Porting pyzk to Rust for a tailgating-detection system: async, typed, built so no ZKTeco punch is dropped, and the stress test that caught a real race.

Describe this image

Ferrite is a Rust library and command-line tool for ZKTeco biometric and access-control devices. Version 0.1.0-alpha.2 is now on crates.io as three crates: zkteco-proto, zkteco-client and zkctl. It covers what pyzk does, with one extra promise, no attendance punch gets silently dropped.

This post covers why I built it, what I learned from reading pyzk closely, how I tested a device library without owning a device.

A missed punch is a false alarm

Earlier this year I built a tailgating-detection platform for offices running ZKTeco devices. Tailgating is one person authenticating at a door and a second person walking through behind them. The platform matches door activity against badge and biometric punches. Activity with no matching punch is a possible tailgate.

pyzk got me connected to the devices quickly, and I'm grateful for it. But in this system a missed punch isn't a missing row in a report. It's a false alarm raised against a real employee.

Reading pyzk's source, I found places where punches could get lost. Live capture can drop events that arrive close together over TCP. And one impossible date in the device log fails the whole download. Devices really do record 30 February. That's tolerable for a monthly payroll export. It isn't tolerable for a security system.

Why Rust, and why not a straight port

Rust gave me what this system needed: typed records, errors you can't ignore, async I/O to watch many devices from one process, and a single binary to deploy.

I decided early not to translate pyzk line by line. pyzk is synchronous and keeps a lot of state in one class. Ferrite is split into three crates:

  • zkteco-proto: the protocol as pure functions over bytes. No sockets, so every encoder and decoder is unit-testable, and the same code can later run in a gateway or a passive traffic monitor.
  • zkteco-client: an async tokio client over TCP and UDP, built on zkteco-proto.
  • zkctl: a CLI for operators and scripts.

One more early decision was licensing. pyzk is GPL-2.0. Ferrite is MIT/Apache-2.0, so I treated ZKTeco's own 2006 protocol manual as the primary source and pyzk only as a reference for behaviour. The script that imports pyzk to generate test fixtures lives in its own GPL-licensed folder and never ships with the crates.

What reading pyzk taught me about the protocol

The ZK protocol is barely documented, so pyzk is the best record we have of how these devices really behave. Reading it closely turned up a few surprises:

  • The checksum has two off-by-one errors that cancel out. The result matches the standard ones'-complement checksum, with zero mismatches over 200,000 random packets. So Ferrite uses the standard algorithm and still matches pyzk byte for byte. At least one other port copied the quirk and had to add a "legacy checksum" mode for strict firmware.
  • Header fields get reused. In event packets, the session ID field holds the event type. In chunked TCP transfers it holds a sequence number. pyzk ignores both; Ferrite decodes them.
  • Real device data is messy. Besides impossible dates, different models report two incompatible 49-byte attendance layouts. Ferrite tells them apart per record.
  • UDP can corrupt data without any error. Large UDP reads carry no sequence number we know of. If two packets swap, the byte count still adds up and you get records that look valid but are wrong. Ferrite therefore reads over UDP one datagram per request, which makes reordering impossible, and prefers TCP whenever the device supports it.

Design principle: nothing gets dropped

Every design decision came back to one rule. When something goes wrong, Ferrite reports it and keeps the data. It never quietly throws a record away.

Where a punch can get lostWhat Ferrite does
A corrupt record in the device logSkips that record only, and returns it with its raw bytes and the reason
An event arriving in the middle of another replyQueues it and delivers it to the live stream
The connection dropsReconnects with backoff, then backfills punches made while disconnected from the device log
The process restartsSaves a watermark to a state file after each delivery and backfills from it on start
An event it can't decodeDelivers it as raw with its flags and payload
The same punch arrives twice (live and backfill)Gives every event a stable id, hashed from the device serial and the punch fields

Every event also carries two timestamps, the device's clock and the host's receive time, because device clocks drift and tailgating checks compare devices.

The honest guarantee is at-least-once delivery after a crash, so consumers deduplicate on id. Exactly-once holds across a clean stop.

Testing a device library without a device

I built all of Ferrite without a ZKTeco device on my desk, so the tests had to stand in for one:

  • Golden fixtures from pyzk itself. A script runs pyzk against a fake device and records the exact bytes it produces. Ferrite matches them byte for byte in 14 areas, and CI fails if they ever drift.
  • Mutation checks. I deliberately broke the checksum, the comm key and a field offset, one at a time. Each break failed its test, which shows the tests actually catch errors.
  • Property tests. Encode/decode round trips, plus a check that every decoder finishes on arbitrary input instead of hanging or panicking.
  • A mock device that misbehaves on purpose. It splits and merges TCP frames, drops replies, sends bad checksums and short streams, pushes events in the middle of replies, and closes connections without warning.

That's 302 tests, run on stable Rust and the minimum supported version, 1.88.

One test, which merges two devices across a reconnect, failed about once in a hundred runs. It would have been easy to blame load on the test machine and move on. Instead I had the agent write a stress harness: loop the scenario under CPU load and, on failure, dump a single timeline with the test's steps, the client's debug log and the mock device's request trace.

It failed on run three, and the timeline showed a real bug. After a reconnect, the client asks the device how many records it holds, then reads the attendance table, and works out the record size from those two numbers. A punch landing between the two reads, which is exactly when people walk through a door, made them disagree. The backfill failed, and the punches made while disconnected were lost until the next drop.

The fix re-checks the count after reading, retries if the log changed, and remembers the record layout once it's known, so a busy door can't trigger the race again. If the log keeps changing on every read, it returns an error instead of guessing. A new mock fault now reproduces it deterministically, with no timing involved. Flaky tests deserve a harness, not a shrug.

Building it with an AI agent

I built Ferrite with an AI coding agent, in six phases. Each phase ended with the agent stopping for my review: the protocol write-up, the protocol crate, the TCP client, UDP, live capture, then the CLI and docs.

The agent did the research I'd never have had time for. It tested the checksum theory over 200,000 packets, went through pyzk's issue history for real device quirks, and wrote a 27-item table of protocol pitfalls before writing any code.

My reviews mattered most where the agent's sensible-looking defaults would have broken my one rule:

  • Acknowledging and skipping events that arrived mid-reply. In a tailgating system, that creates false alarms.
  • Accepting replies with mismatched IDs, which risks answering the wrong question.
  • Basing event IDs on the device's profile name instead of its serial number. Renaming a profile would have broken deduplication.

The split that worked was where the agent brought speed and breadth, and I decided what the system must never do. Writing those rules down at the start made every review faster.

Try it, and help me test it

Ferrite is alpha, and it hasn't been tested on physical devices yet. Install the CLI:

cargo install zkctl --version 0.1.0-alpha.2

No device? The repository includes a demo device that serves fictional punches and drops its connection every so often, so you can watch reconnects and backfill. Clone the repo, start two demo devices, and stream from both (the README has the full walkthrough):

cargo run -p zkteco-client --example demo_device -- --port 14370 --name front
cargo run -p zkteco-client --example demo_device -- --port 14371 --name lobby
zkctl live -d front -d lobby --reconnect --backfill

If you have a ZKTeco device, the most useful thing you can do is run:

zkctl diagnose --probe-live 30

It's read-only, the client refuses any command outside a fixed allowlist before anything is sent. It also scrubs names, IDs, card numbers, serials and MACs from its report. Punch in a couple of times during the 30-second window, then open a GitHub issue with the report. Each report adds a row to the compatibility table and answers questions no fixture can.

Next, once hardware results settle the open questions, comes a long-running gateway service that feeds my tailgating platform.