Hardware Ingestion & Payload Normalization

The TitanGrid core operates as a universal data translation middleware layer for biometric edge hardware. Because the ecosystem integrates with proprietary devices from different manufacturers, the ingestion tier is designed to abstract away varying networking protocols and data types.

To prevent vendor lock-in, TitanGrid utilizes a Data Normalization Pipeline. Regardless of the manufacturer's payload format, the pipeline intercepts the chaotic incoming byte stream and mutates it into a strict, predictable JSON dictionary before committing it to the immutable database log.

Here is exactly how raw streams from all three integrated hardware partners are conceptually transformed into standardized TitanGrid payloads.

1. ZKTeco (ADMS Protocol)

ZKTeco devices do not use modern JSON. Instead, they communicate via HTTP polling, pushing raw, Tab-Separated Values (TSV) in a text stream via the cdata endpoint.

The Normalization Process

To transform this raw string into a usable payload, the system executes these conceptual steps:

• Tokenization: The ingestion engine splits the raw string using the tab delimiter character to isolate the values.
• Positional Index Mapping: Since there are no keys, values are extracted strictly by their position (e.g., Index 1 is always the Employee ID).
• Timezone Injection: ZKTeco devices transmit "naive" datetime strings missing timezone data. The pipeline explicitly appends the local server timezone offset before normalizing the string to absolute UTC.
• State Translation: Proprietary operational integers (such as 15) are mapped to standard system strings (e.g., "face").

1	1042	2026-06-07 08:14:00	1	15

{
  "device_serial": "ZKT-NODE-1",
  "employee_code": "1042",
  "timestamp": "2026-06-07T06:14:00Z",
  "verification_type": "face"
}

2. Hikvision (ISUP 5.0)

Hikvision terminals communicate using the native ISUP 5.0 (EHome) protocol, pushing structured, deeply nested JSON objects over TCP connection lines whenever a verification event triggers.

The Normalization Process

To digest Hikvision’s native format, the system applies the following normalization rules:

• Object Hierarchy Flattening: The pipeline extracts data buried deep inside the root AccessControllerEvent object, eliminating unnecessary parent object nesting.
• Key Alias Normalization: Proprietary string parameters are translated to fit the TitanGrid core standard. The key employeeNoString is normalized to employee_code.
• Offset Resolution: Hikvision passes the explicit regional offset (e.g., +02:00). The pipeline converts this calculation to absolute UTC time to prevent midnight-crossing ledger calculation bugs.

{
  "AccessControllerEvent": {
    "employeeNoString": "EMP-9042",
    "serialNo": "DS-K1T671M-12345",
    "time": "2026-06-07T08:14:00+02:00",
    "currentVerifyMode": "fingerprintOrFace"
  }
}

{
  "device_serial": "DS-K1T671M-12345",
  "employee_code": "EMP-9042",
  "timestamp": "2026-06-07T06:14:00Z",
  "verification_type": "fingerprintOrFace"
}

3. Suprema (BioStar 2)

Suprema deployment networks communicate cloud-to-cloud. Instead of interacting with single endpoints, Suprema pushes real-time JSON webhooks wrapped in batch event arrays.

The Normalization Process

The Suprema adapter uses specific data-casting mutations to process these entries safely:

• Array Destructuring: Webhook batches compress logs into arrays. The pipeline extracts the individual transaction items from the Log list.
• Epoch Datetime Conversion: Suprema represents transaction times using an integer Unix Epoch format (e.g., 1717740840). The pipeline mathematically converts this elapsed-seconds integer into a standard ISO-8601 UTC timestamp.
• Strict Schema Type-Casting: Suprema handles user IDs as system integers. Because TitanGrid supports alphanumeric enterprise personnel codes (e.g., EMP-9042), the normalization engine explicitly casts these integers to standard string structures.

{
  "Event": {
    "Log": [
      {
        "UserID": 9042,
        "DeviceID": 5432198,
        "EventTime": 1717740840,
        "EventType": 4096
      }
    ]
  }
}

{
  "device_serial": "SUP-5432198",
  "employee_code": "9042",
  "timestamp": "2026-06-07T06:14:00Z",
  "verification_type": "biometric"
}

Architectural Summary

By forcing all terminal integrations to distill their raw data down to these matching, flat target structures, the core calculations module remains completely isolated from hardware manufacturer mechanics. Whether a worker scans a face on a ZKTeco pod, swipes a card on a Hikvision pillar, or triggers a Suprema sensor, the background scheduling engine reads the exact same data signature.