Skip to main content
Biometric attendance terminals — fingerprint and face clocks on a factory wall — are the most reliable way to capture attendance for people who do not carry a work phone. They also cannot talk to a cloud service directly, which is why OnTime ships a small bridge.

​
The topology

Terminals speak raw TCP

An F500-class device opens a persistent TCP connection to a configured IP and port and streams null-terminated XML. It has no HTTPS, no certificates and no notion of a REST API.

The connector translates

A small stateless service you run on the same network. It terminates those TCP sessions and forwards each message to OnTime over HTTPS.

​
Why the connector exists

Three reasons, in order of importance:
  1. Terminals cannot speak HTTPS. There is no way to point one at a cloud endpoint.
  2. They need a listener on the local network. The device connects outward to an IP and port you configure on it — so something has to be listening there.
  3. It keeps no state. The connector holds nothing, has no queue and no database. Restarting it mid-session loses nothing, which is what lets it be deployed like any other service.

​
The no-data-loss contract

The device’s own flash memory is the retry queue, and the connector acks a punch only after OnTime has accepted it.This single rule is the whole reliability model. If OnTime is unreachable, the connector does not acknowledge the punch; the device sees no acknowledgement, keeps the record, and re-sends it. Nothing is lost to an outage, a deploy or a network blip.
The device re-sends any unacknowledged record roughly every 60 seconds and holds the rest of its queue behind it. Combined with OnTime’s deduplication, that produces at-least-once delivery with exactly-once storage — a punch cannot be missed, and cannot be counted twice.

​
Two things that are not obvious

A terminal identifies people by its own numeric user ID. Until that ID is linked to an OnTime employee, the punch is held rather than discarded. Creating the mapping replays everything parked.So “punches aren’t appearing” is almost never lost data. See Map terminal users.
The connector authenticates with a platform-level secret rather than an organization API key. Which organization a punch belongs to is resolved on the OnTime side, from the device’s serial number.Practically: you configure the connector once, and registering a device is what assigns it to your organization.

​
Setting up

1

Install the connector

On a machine that can reach both your terminals and the internet. See Install the connector.
2

Point the terminals at it

Set each device’s LogServer IP and port to the connector’s host.
3

Register the devices

They appear by serial once they first connect. See Register a terminal.
4

Map terminal users to employees

Otherwise every punch parks. See Map terminal users.
5

Verify without hardware

A fake-device script replays a realistic session. See Test with a fake device.

​
Where the connector runs

The connector is a Docker image that runs anywhere with a raw TCP port reachable from your terminals.It cannot run on Render, which OnTime otherwise deploys to — Render web services accept only public HTTP(S), and this needs a raw TCP listener. Run it on your own network, or on a host that supports raw TCP.