TL;DR — A push-protocol biometric terminal never accepts a connection. It polls the server, and a command can only leave on the reply to that poll. So the device’s poll interval is the floor on every remote operation: about 3 seconds on a ZK-protocol terminal once you tell it to poll that often, and minutes on a terminal that heartbeats every three minutes. Design around that floor rather than against it. Shorten the poll where the protocol lets you. Have a new request replace anything still queued, never stack behind it. Treat the face template arriving as the acknowledgement, because the enrol command often never gets one. Match unlabelled replies to the single command in flight. And never delete a user from a terminal that your system didn’t put there.

Key takeaways

  • With a polling device you don’t send commands, you leave them for collection. The poll interval is your latency floor and no server change gets under it.
  • Several commands in one poll run back to back on the device. For anything that waits on a person, like a face enrolment, that’s wrong. Send one, last in its batch.
  • An acknowledgement you might never receive can’t be the only signal of success. Find a side effect that proves the command worked.
  • An “abort” on your side doesn’t abort anything on the device. Tell the operator that plainly.
  • A sync that writes to a device without reading it first will erase data people enrolled at the device itself.

How a command reaches a terminal that only pulls

The terminals are the face and fingerprint readers at a canteen counter. A small agent on the site network receives their scans, as the offline-queue post describes. This post is the other direction: adding a user, pushing a photo, enrolling a face, deleting someone who left. The vendor’s desktop software can do all of that. The point of the agent was that nobody at the site should need it.

The catch is that these terminals never accept a connection. They are HTTP clients only:

  admin clicks "enrol face"
        │
        ▼
  agent queues ENROLL ──── waits ────┐
                                     │
  terminal ── GET  "any commands?" ──┤  (its own poll, on its own schedule)
  terminal ◀─ 200  "C:42:ENROLL…" ───┘
  terminal ── runs it, maybe minutes later, maybe never answers
  terminal ── POST "result for 42" ───▶ agent marks it done (if it comes)

  ▼  you can make the queue fast; you can't make the device ask sooner than it asks

On ZK-protocol terminals, the iclock/ADMS family, the poll is a GET to a getrequest endpoint, and the reply body carries the commands. On the FK-style protocol used by another vendor’s line, every heartbeat is the chance to hand over exactly one command. Either way, the device decides when you get to speak.

The latency floor, per device family

Device familyWhen it pollsWhat that means for a command
ZK protocol, our original handshakeEvery 10 sUp to 10 s before it even sees the command
ZK protocol, after the agent sends Delay=3Every 3 s (configured)A few seconds, the best case available
FK-style heartbeatRoughly every 3 minutesMinutes, and one command per heartbeat
A ZMM510 just after an enrolmentNot at all for about 65 s (observed)Everything queued waits out the window

The one lever is the poll interval, where the protocol exposes it. The ZK handshake reply includes a Delay= line that tells the terminal how often to poll. The agent rewrites it to 3 seconds, which takes effect from the terminal’s next handshake. On the FK side, there’s no equivalent I could rely on, so the design has to assume minutes.

With a 3-second poll, the numbers on real terminals were what a person at a counter can live with: a photo enrolment finished end to end in about 5 seconds, a terminal acknowledged an enrol command in 3.3 seconds, and lookups of an employee’s record took 3.4 to 6 seconds.

The 65 seconds after an enrolment

A ZMM510 (an eSSL-branded terminal that speaks the ZK protocol) does something no document I found mentions. After every face enrolment, it stops polling and answering for about 65 seconds. That happens whether the enrolment succeeded or not, and whether or not someone pressed Esc on the terminal to cancel it. The agent pads it to 70 seconds and doesn’t send that terminal anything until it’s over.

I’d call this observed, not documented. The pattern repeated on our bench and was verified on hardware again on 21 October. It may differ by firmware. What matters for design is that it exists at all: a device can go quiet as a consequence of your own command, and your timeouts have to know about it, or every command queued behind an enrolment looks like it failed.

The acknowledgement that never comes

The protocol has a result message for each command, labelled with the command’s ID. Two things go wrong with it in practice.

The enrol command often never gets a result. The ZMM510 frequently posts no result for an enrolment at all, and when it does, it can answer with an error code (-1003) even though the face was captured. The admin’s dialog sat open waiting for an answer that wasn’t coming.

The fix is to stop waiting for the acknowledgement and look for the proof. When a face is enrolled, the terminal uploads the new face template to the server, unprompted. That upload is the answer. The agent now marks an enrolment complete when the template for that user arrives, whatever the command result said or didn’t say.

// Illustrative.
function onTemplateUploaded(deviceId: string, userId: string) {
  const cmd = inFlight.find(c => c.deviceId === deviceId && c.kind === 'enroll' && c.userId === userId);
  if (cmd) complete(cmd, { via: 'template' });   // the side effect is the acknowledgement
}

Some firmware replies without the command ID. One FK-style terminal answered every command without echoing its ID. Unmatched, each reply would be ignored, and the command would be re-queued after a 90-second reply timeout, up to three attempts. The fix depends on a property of that protocol: an FK device only ever has one command in flight. So a result with no ID belongs to the one command currently out, and the agent matches it to that.

Both fixes are the same move. When the protocol’s acknowledgement is unreliable, find something else that can only be true if the command worked, and trust that instead.

Replace, don’t stack

The first version queued commands in order. Then three enrolment commands for the same terminal left in one poll reply, and the terminal ran them back to back: three face prompts in a row for one person standing at the counter.

The fixes:

  • An enrolment is always the last command in its poll, so nothing runs behind a prompt that is waiting on a person.
  • A new enrolment request replaces any that hasn’t reached the terminal yet. The older one is cancelled with a reason (“replaced by a newer enrolment”), not left in the queue.
  • A repeat click on the same enrolment follows the one already running instead of starting another.

This is the shape of every command that is safe to send twice but wrong to send twice at once. Re-sending an enrolment later is fine. Two of them in the same poll is a person staring at a second prompt.

What “abort” can and can’t do

I added an Abort button on 29 September, because a dialog that can wait for minutes needs a way out. What it does is narrower than the word suggests:

  • A command still in the queue is dropped. It never reaches the terminal.
  • A command the terminal already has is marked “aborted by admin”, and the agent stops waiting. Nothing is sent to the device, because there is no command for “stop what I told you”. The terminal keeps its prompt open until it times out, about a minute, and Esc on the terminal didn’t end it sooner on a ZMM510.

So the UI says exactly that: “Aborted. The terminal keeps its prompt open for up to a minute. If someone still completes it, the face is saved on the user.” A button that claims more than it can do teaches operators to stop trusting every other message on the screen.

Never delete what you didn’t put there

These terminals arrive at a site with users already on them, enrolled at the device with fingerprints and faces. The agent has to coexist with those. Two rules, both enforced in code and covered by tests:

  • Read before writing. Before the agent writes a user to a terminal it hasn’t looked at, it reads the terminal’s user list and that user’s record first, so an existing user’s biometrics are kept rather than overwritten blind.
  • Only delete what the agent created. A sync deletes only users the agent itself pushed to that terminal. Anyone else on the device is left alone, even if they’re missing from the server’s list.

The second rule costs something: a stale user enrolled by hand stays until someone removes them by hand. That’s the right side to err on. An extra user is a tidy-up. A deleted one means someone re-enrolling their fingerprints at the counter.

One more lesson from the design phase belongs here. The first design assumed the FK-style hardware. The terminals actually installed at the first site spoke the ZK protocol. User management, card numbers, face-template push and import were verified on that real hardware on 23 September. The FK driver still hasn’t been verified on real hardware, and it says so.

Decision table

ProblemOptionWhat I choseWhy
Command latencyFaster server / shorter poll / honest UIShorter poll where possible, honest UI everywhereThe server isn’t the bottleneck; the poll is
Duplicate requestsStack in order / replace queuedReplace queued, enrolment last in its pollStacking ran three prompts back to back
Missing acknowledgementsWait longer / retry / trust a side effectTemplate upload completes an enrolmentWaiting longer doesn’t produce an answer that never comes
Unlabelled repliesIgnore and retry / match to in-flightMatch to the single in-flight commandFK devices have one command out at a time
Users not created by the agentMirror the server exactly / leave aloneLeave alone, read before writeDeleting enrolled biometrics can’t be undone remotely
AbortPretend to cancel / stop waiting and say soStop waiting and say soThe protocol has no cancel

What actually broke

  • Three enrolment prompts in a row, from stacked commands in one poll reply.
  • Dialogs that never closed, because they waited for an enrolment result the terminal didn’t send, or sent as an error after succeeding.
  • Unmatched replies from firmware that doesn’t echo the command ID, which would have made every command on that terminal time out and retry.
  • A design built for the wrong hardware, until the real terminals were on a bench.

FAQ

How do I add a user to a biometric device remotely? For push-protocol terminals, you don’t connect to the device. You queue the command on the server the device polls, and hand it over in the reply to the device’s next poll. ZK-protocol devices poll a getrequest endpoint; FK-style devices take one command per heartbeat. No vendor desktop software is needed if you implement the protocol yourself.

Why do commands to my ZKTeco device take so long? Because the device only collects commands when it polls, and the poll interval is set in the handshake. Ours started at 10 seconds. Sending Delay=3 in the handshake reply makes the device poll every 3 seconds from its next handshake. Some other device families heartbeat every few minutes, and there’s no way to make a command arrive sooner than that.

Why doesn’t my terminal respond after a face enrolment? Some terminals go quiet after an enrolment. On a ZMM510 we observed about 65 seconds of no polls and no replies after every enrolment, successful or not, even when Esc was pressed. Hold commands for that terminal until the window passes, or they’ll look like failures.

What if the device never acknowledges the enrol command? Look for proof instead. When a face is enrolled, the terminal uploads the new face template. Treat that upload as completion, whatever the command result says. We saw terminals return an error code for enrolments that had actually succeeded.

Can I cancel a command after the device has received it? Not on these protocols. You can drop commands still in your queue and stop waiting for one that’s been sent, but the device will finish or time out on its own. Tell the operator that, rather than showing “cancelled”.

How do I avoid deleting users that were enrolled at the device? Keep a record of which users your system pushed to each device, and only ever delete those. Before writing a user to a device you haven’t read, read its user list first, so you don’t overwrite fingerprints or faces enrolled at the terminal.

What I’d still improve

  • Verify the FK-style driver on real hardware. It’s tested against captured traffic, which isn’t the same thing.
  • Show the operator the device’s expected wait up front, per terminal, based on its poll interval, instead of a spinner.
  • Measure the post-enrolment quiet window across firmware versions before relying on 65 seconds anywhere else.
  • Re-measure the 3-second poll under production load. The timings here are from test sessions.

The one idea to take away

When the device decides when you may speak, design every command to be safe to say twice and wrong to say twice at once.

You can’t make the device listen sooner, and you can’t be sure it heard. What you control is what’s waiting when it does ask: one command, the latest one, that does no harm if it arrives again, and a way to tell it worked that doesn’t depend on the device saying so.


I write about backend reliability, Postgres and edge systems from work on food-tech and healthcare platforms. More on what I build and how I work, on how the same agent keeps scans safe through outages, and on claiming a job safely when several workers want it. If you integrate a polling device, write down its poll interval before you write a timeout.