Interface control document

1. Identification

2. Scope

This document defines the UDP datagram envelope the module accepts, the packet-type and data-identifier values it decodes, the byte order and per-identifier wire sizes it enforces, and the mapping from those identifiers to the fields and readings published to HEAT Capture.

The interface is receive-only. The module opens a listening socket and never sends anything to SmartEye: no subscription request, no handshake, no acknowledgement, no configuration. SmartEye must be configured independently to send its output to the workstation and port the module is listening on.

3. Interface inventory

4. IF-CMSMARTEYE-01 SmartEye output packet stream

4.1 Transport and addressing

Because the socket receive buffer holds roughly one maximum datagram, a burst that arrives while the receive thread is parsing or publishing can be discarded by the operating system before the module sees it. There is no counter or log for that loss.

4.2 Connection lifecycle

There is no connection. UDP is connectionless and the module is a passive listener, so there is no handshake, no keepalive, no disconnect detection and no reconnect logic.

StartCapture logs SmartEye Module starting capture on UDP port {Port}, constructs the receiver with the port value read at that moment, subscribes to its packet event, and starts the thread, which logs SmartEye UDP receiver listening on port {Port}. StartCapture is bounded by the SDK StartupTimeout of 5 seconds; the module does not override it. If the port is already in use the socket constructor throws inside StartCapture, the SDK logs SmartEye Module StartCapture failed. and the module does not start.

EndCapture logs “SmartEye Module ending capture”, unsubscribes the packet event, stops the receiver and disposes it. Stopping clears the running flag and closes the socket, which unblocks the pending Receive; the thread then logs “SmartEye UDP receiver stopped”. EndCapture does not wait for the thread to exit, and it does not clear the retained snapshot. See 5.6.

Silence is indistinguishable from absence. If SmartEye is not running, is not configured to send, or is sending to a different port, the module reports nothing: the listening log line appears exactly as it would with a healthy sender. See Troubleshooting.

4.3 Authentication

None. There is no credential, token, shared secret or source-address check. Any process that can send a UDP datagram to the bound port, on any interface of the workstation, can inject a packet that the module will accept as a measurement.

4.4 Packet envelope

All integers and all floating-point values are big-endian. The module decodes them with BinaryPrimitives.ReadUInt16BigEndian, ReadUInt32BigEndian and ReadDoubleBigEndian, so no host byte-order dependency exists.

A datagram is a 4-byte header followed by a sequence of length-prefixed entries:

Datagram
  +0  packetType   u16  big-endian, must equal 4
  +2  length       u16  big-endian, payload byte count following the header
  +4  payload      length bytes

Payload: zero or more entries, packed with no padding
  +0  dataId       u16  big-endian, see 4.5
  +2  dataLength   u16  big-endian, byte count of this entry's data
  +4  data         dataLength bytes

Envelope acceptance rules, in the order the parser applies them:

1. A datagram shorter than 4 bytes is rejected.
2. A packetType other than 4 is rejected. SmartEye’s other packet types are not decoded.
3. A datagram shorter than 4 + length is rejected.
4. Only the first length bytes after the header are treated as payload. Any bytes beyond that are ignored.
5. Entries are read until fewer than 4 bytes remain in the payload.

Rejection means the whole datagram is discarded and no event is raised. Nothing is logged for a discarded datagram at any log level.

Data element wire sizes are fixed: 1 byte for a boolean, 4 for an unsigned integer, 8 for a double-precision float, 24 for a three-component vector of doubles, 32 for a four-component vector of doubles. Vector components are packed in X, Y, Z order, and the quaternion in X, Y, Z, W order.

4.5 Data identifiers decoded

Each entry is matched on dataId together with an exact dataLength. Both must match for the value to be taken. “Destination” states where the value ends up: a published field or reading name, or the point at which it is dropped.

Frame information:

Head pose:

Gaze, raw and filtered. Where two identifiers feed one published field, the filtered value is used when present and the raw value only when the filtered one is absent in that packet:

Filtered and raw are selected per field, not per packet. A single published frame can carry a filtered combined direction and a raw left direction if that is what the packet contained. The values are never averaged or blended.

Eyelid and pupil:

Eyelid openness has no filtered identifier in this parser, so 0x0050 to 0x0055 are used as sent.

Analysis, status and occlusion:

Occlusion is published as a bare boolean while its quality score is discarded, so a consumer cannot tell a confident occlusion from a low-confidence guess.

Drowsiness, emotion and activity, all published as named readings on BiometricSensorComponent:

Profile identity, decoded and then dropped when the packet is copied to the retained snapshot:

Identifiers named in the module’s identifier table but not decoded by the parser at this revision, so they are skipped as if unknown: eyeglasses status 0x00c1, per-eye blink closing and opening mid-time, amplitude and speed 0x00e0 to 0x00eb, left and right eyelid state 0x0390 and 0x0391, keypoints found 0x0510, camera-drift heading, pitch and roll 0x0512 to 0x0514.

4.6 Sample validity handling

There is no sample-validity concept beyond structural checks. Concretely:

• Presence is per identifier, per packet. Any identifier SmartEye omits leaves the corresponding value unset for that packet.
• An entry whose dataLength does not exactly equal the expected size for its identifier is skipped. It is treated identically to an unknown identifier: no value is taken, nothing is logged.
• Quality values are carried through as numbers. The module never thresholds, gates or rejects a measurement based on its quality value, on the tracking-state code 0x00c0, or on the occlusion flags. A gaze direction with a quality of zero is published exactly like one with a quality of one.
• Value ranges are not validated. A decoded double is cast to float for publication with no range or finiteness check, so a non-finite or out-of-range value from the sender is published as such.
• A packet is accepted whole or not at all at the envelope level, but partially at the entry level: see the truncated-entry row in 4.7.

4.7 Error behaviour

No condition in this table produces a retry, a counter, or a state change visible to HEAT Capture. A malformed or hostile stream degrades silently.

4.8 Timing and cadence

The module imposes no rate on the sender. The publication cadence depends on SendAtNativeRate:

On the native-rate path the frame build and the publish run inside the receive loop, between two Receive calls, so publication cost is back-pressure on datagram reception rather than on the capture loop.

Neither path uses the SmartEye frame number 0x0001 or timestamp 0x0003 for ordering or de-duplication. On the native-rate path a duplicate or out-of-order datagram is published as a new frame.

5. IF-CMSMARTEYE-02 Frame publication and data model reference

5.1 Entity

All four components are attached unconditionally, whether or not the snapshot contained anything for them. An empty SpatialComponent or a BiometricSensorComponent with no readings is still present in the frame.

5.2 Head pose

SpatialComponent.pose is emitted only when head position 0x0010 was present. Orientation is resolved in this order:

1. The quaternion 0x001d, used directly.
2. Otherwise the Rodrigues vector 0x0012, converted to a unit quaternion by the module. A vector whose magnitude is below 1e-10 yields the identity quaternion.
3. Otherwise the identity quaternion (0, 0, 0, 1).

Case 3 means a frame can carry an authoritative-looking neutral head orientation that reflects only the absence of rotation data. There is no published flag distinguishing it from a measured neutral pose.

5.3 Fields never populated

GazeComponent.IPD, GazeComponent.gaze_point and GazeComponent.gaze_screen_point are never set by this module: no SmartEye identifier is mapped to them. PupillometryDataComponent.other_pupil_data is never populated; the drowsiness, emotion and activity values go to BiometricSensorComponent instead. SpatialComponent fields other than pose are never set.

No EntityEvent is ever published. Saccade 0x003d and fixation 0x003e are decoded and retained but are not turned into events or published fields.

5.4 Absence semantics per field type

Whether a consumer can distinguish “SmartEye did not send this” from “SmartEye sent zero” depends on the proto field type, not on anything the module does:

5.5 Publication before a current packet

The retained snapshot is created empty when the module instance is constructed, is not cleared by StartCapture, and is not cleared by EndCapture. On the fixed-rate path a frame is built from it on every cycle regardless. This is audit finding SE-01, and it is a property of this revision, not of the SmartEye protocol.

Two consequences follow. First, before any packet arrives, the seed snapshot has every field unset and the module publishes this:

A consumer therefore cannot distinguish “no SmartEye data yet” from a real measurement of fully closed eyelids and zero pupil diameter with no blink.

Second, and more consequential, the snapshot outlives a capture session. Because the module instance is initialised once and reused across starts and stops, the last packet of one session remains in the snapshot and is published as the first frames of the next session, timestamped with the new session’s capture time. An earlier subject’s gaze, pupil, head-pose, drowsiness and emotion values can be attributed to a new subject.

Do not treat an early fixed-rate frame as evidence of a live tracker. Correlate with a changing value, or run the module on its default native-rate path, where a frame is only built from an immediately received packet. Native rate does not fix SE-01; it avoids the code path on which SE-01 manifests.

6. Units and conventions

The authority for coordinate-system handedness, origin, axis directions and units is SmartEye’s own documentation. The module does not define them and does not assert them.

7. Configuration affecting the interface

There is no setting for the listening interface, for a sender allow-list, for which identifier groups to publish, or for a quality threshold. Emotion and drowsiness readings cannot be turned off independently of gaze.

See Manage capture modules for the generic settings and the Module SDK ICD for the lifecycle contract.

8. Compatibility and versioning

There is no version negotiation and no version field in the envelope. Compatibility rests on three assumptions: that the sender uses packet type 4, that identifier numbers keep their meaning, and that each identifier keeps its wire size.

A SmartEye release that changes an identifier’s wire size causes that field to be dropped silently, because the size guard fails and the entry is treated as unknown. A release that reassigns an identifier number to a different quantity causes that quantity to be published under the old field or reading name, with no diagnostic. A release that adds identifiers is tolerated: unknown identifiers are skipped and the rest of the packet still parses.

The identifier subset listed as undecoded at the end of 4.5 is a property of this revision. Enabling those outputs in SmartEye does not make them appear in HEAT Capture.

9. Security considerations

The listening socket is unauthenticated and accepts datagrams from any source address on any interface of the workstation, so any host that can route a UDP packet to the bound port can inject a measurement, and any local process can do the same. Nothing in the module distinguishes an injected packet from a genuine one. Restrict the port at the host firewall to the address of the machine running SmartEye.

The stream itself is unencrypted. Any device on the path can read it, and the module cannot detect tampering.

The payload is personal data. Gaze direction and origin, eye position, pupil diameter, eyelid openness, blink, head pose, glasses and face-mask detection, drowsiness level, facial-emotion estimates and a speaking flag are all measurements of an identifiable person’s body and inferred internal state. The profile identifier SmartEye can send is decoded, though this revision discards it before publication. Gaze and pupil data support inferences beyond the stated purpose of a session, including attention, cognitive load and, in combination with the emotion readings, affective state. Treat captured SmartEye sessions accordingly: restrict who can read them, apply the deployment’s retention limits, and obtain the consent the deployment’s jurisdiction requires before recording. There is no setting that reduces the published set, so consent must cover everything in 4.5.

10. Conformance

1. Configure SmartEye to send its output to the workstation’s address on the configured port. Start a capture session and confirm the log records “SmartEye Module starting capture on UDP port 5003” and “SmartEye UDP receiver listening on port 5003”.
2. Confirm one entity named SmartEye_Data appears in the captured data, carrying all four components.
3. With a subject tracked, confirm gaze_direction and pupil_diameter change across successive frames.
4. Confirm the filtered-over-raw preference. Disable SmartEye’s filtered gaze output and confirm gaze_direction still populates from the raw identifier 0x0021.
5. Confirm the byte order end to end by checking that a published pupil diameter is a plausible millimetre-scale number rather than a value of extreme magnitude, which is what a byte-order mismatch would produce.
6. Verify packet-type filtering. Confirm that enabling another SmartEye packet type produces no additional data and no log entry.
7. Verify SE-01 on the fixed-rate path. Set SendAtNativeRate to false, start a session with SmartEye stopped, and confirm the frames carry the seed values in 5.5, in particular pupil_diameter of 0 and blink of false with no pose.
8. Verify the cross-session case. With SendAtNativeRate set to false, run a session with a tracked subject, stop it, stop SmartEye, then start a second session and confirm whether the first frames repeat the previous subject’s last measurement. Until SE-01 is fixed, discard the frames preceding the first packet of each session.
9. Stop SmartEye mid-session and confirm the module logs nothing and publishes no error. On the native-rate path, confirm frame publication stops.
10. Confirm the entity id is not relied on across restarts: restart HEAT Capture and confirm the id for SmartEye_Data differs while the name does not.

11. Revision history

HEAT Capture team. Last updated 2 October 2026.