Timestamps & external time sync

Public numeric time values in the Glove SDK use milliseconds. Call sync_time() only when the application must align with an external system or make several Glove sources share one absolute time reference. A regular standalone Glove application can keep the default time reference.

Time units

Public numeric time values in Glove frames, runtime state, capture, calibration, and SDK-derived data are milliseconds. Do not read, store, subtract, or forward these fields as seconds.

Use timestamp_ms for external input. See GloveNodePose and ExternalGloveFrame for the complete field definitions and Data channels & read methods for the available sources and read paths.

Time reference

Default time reference

Without sync_time(), the SDK uses host Unix milliseconds. When an external frame omits timestamp_ms, that frame follows the current shared Glove time reference.

Keep the default behavior when the application reads one or more gloves on the same host and does not need alignment with another system.

External time reference

Pass the absolute Unix time in milliseconds from the external clock to qnbot::Glove::sync_time(). Synchronizing before start() is recommended:

qnbot::Sdk sdk(config);
auto glove = sdk.glove();

// reference_time_ms comes from PTP, ROS, or another external clock
// and must represent absolute Unix milliseconds.
glove.sync_time(reference_time_ms);
glove.start();

// Read data or start a runtime mode as required by the application.
glove.close();

The double argument must be finite and is not expressed in seconds or nanoseconds. See time_sync.cpp for a complete runnable example.

Resynchronizing while running

Call sync_time() again when the external clock is updated. Subsequent Glove frames without an explicit timestamp advance from the new reference without resetting subscriptions or lifecycle state.

glove.sync_time(updated_reference_time_ms);

Timestamps

SDK-generated timestamps

The SDK stamps physical Glove frames from the current shared Glove time reference. SDK-derived results, such as skeleton poses, retain the time of the corresponding input frame. Applications read these timestamps and do not need to supply them.

External input also receives an SDK-generated timestamp when both timestamp_ms and timestamp_sec are omitted. Without sync_time(), it comes from host Unix milliseconds. After synchronization, the SDK calculates it as the most recent synchronization value plus the elapsed time and keeps values generated by the shared clock increasing.

External-input timestamps

Only a qnbot::ExternalGloveFrame requires the application to decide whether to provide an explicit timestamp:

1. An explicit timestamp_ms takes precedence and is not overwritten by the shared time reference.
2. When only timestamp_sec is provided, the SDK retains compatibility with existing code by converting it as timestamp_ms = timestamp_sec * 1000.
3. When both fields are omitted, the SDK-generated timestamp described above is used.

Do not set both std::optional fields; supplying both values is an argument error. An explicit timestamp must be a finite millisecond value and strictly increasing for the same device. See External input for the complete configuration and frame constraints.