Time Synchronization and Coordinate Transforms

Every data frame a device outputs carries a timestamp. After the SDK connects to a device, it synchronizes time automatically so device timestamps align with the host’s UTC clock. This page explains what the timestamp means, how synchronization works, and how to trigger a sync manually.

Data frame timestamps

Except for the paired tactile sensing glove frames on Wuji Hand, data frames share the same FrameHeader, in which timestamp_us is a 64-bit microsecond timestamp. For device-stamped frames (Wuji Hand 2, Wuji Glove), its meaning depends on whether time synchronization has completed:

After sync: timestamp_us is a UTC timestamp in microseconds (a Unix timestamp), directly aligned with the host clock
Before sync: timestamp_us is device uptime, the number of microseconds since power-on

Wuji Hand 2 and Wuji Glove have no real-time clock (RTC) and count from 0 at power-on. Time synchronization aligns this uptime counter to real UTC time.

When the timestamp is taken and how it propagates

When each product’s frames are stamped: Wuji Hand 2: the firmware stamps timestamp_us on feedback frames at send time. Wuji Glove: the firmware stamps each stream on the device side — not when the host receives the data:

EMF frames: when data acquisition for the sampling point completes
Tactile frames: when the full pressure-matrix scan completes
IMU frames: the firmware polls all IMUs on a fixed cycle — samples read in a cycle share that cycle’s start timestamp

Derived data computed from EMF frames (hand joint angles, skeleton, and fingertip poses) is not stamped separately: timestamp_us is taken from the source EMF frame, which lets you align derived results with their source data. Other header fields (frame_id, seq) are not guaranteed to match the source frame — see each product’s field reference. Wuji Hand: the SDK stamps timestamp_us on joint-state frames host-side (host UTC), so they don’t depend on device time sync. Paired tactile sensing glove frames carry no FrameHeader. Their timestamp_ms is a device-side millisecond timestamp passed through as-is — time sync never converts it to UTC, and it has no alignment guarantee with timestamp_us.

How synchronization works

The SDK uses client-side time setting: the device does not fetch time on its own. Instead, the SDK pushes the host clock to the device. The sync flow follows the NTP four-timestamp model — the SDK and device exchange a request/response pair and record four moments (request sent, device received, device replied, response received). From these, the SDK computes offset_us, the device clock’s offset relative to host UTC, and pushes it to the device. The device then derives:

device_time = uptime_us + offset_us

This is a PTP-like lightweight synchronization that does not rely on standard PTP hardware. Sync accuracy depends on the network round-trip time between the SDK and the device.

Periodic auto-sync requires recent firmware. Earlier firmware applies the offset only on the first sync after connecting. Subsequent periodic syncs do not refresh the device clock. Upgrade to the latest firmware for full time synchronization.

Automatic synchronization

After the SDK connects to a device, it maintains time synchronization automatically, and applications usually do not need to intervene:

First sync: a full sync runs immediately when connect() completes
Periodic sync: after connecting, a background sync runs every 30 seconds by default to counter device crystal drift

The background sync interval is configured through ConnectOptions.auto_time_sync_interval_ms:

Python
C

from wuji_sdk import ConnectOptions

# default 30 seconds
options = ConnectOptions()

# custom 10 seconds
options = ConnectOptions(auto_time_sync_interval_ms=10_000)

# disable background auto-sync
options = ConnectOptions(auto_time_sync_interval_ms=None)

// default 30 seconds
WujiConnectOptions options = wuji_connect_options_default();

// custom 10 seconds
options.auto_time_sync_interval_ms = 10000;

// disable background auto-sync
options.auto_time_sync_interval_enabled = false;

Value	Behavior
Not set	Default 30000 (30 seconds)
`None`	Disables background auto-sync
Integer (milliseconds)	Custom interval, must be ≥ 100

When a session closes, the sync state clears automatically and re-syncs on the next connection.

Manual synchronization

To force a sync at a moment of your choice (for example, before a long recording or a time-sensitive operation), call the device’s sync_time():

Python
C

result = glove.sync_time()
print(f"Offset: {result.offset_us} us")
print(f"Round trip: {result.round_trip_us} us")
print(f"Synced at: {result.synced_at_us} us")

WujiTimeSyncResult tsr = {0};
if (wuji_glove_sync_time(glove, &tsr) == WUJI_STATUS_OK) {
    printf("Offset: %lld us\n", (long long)tsr.offset_us);
    printf("Round trip: %lld us\n", (long long)tsr.round_trip_us);
    printf("Synced at: %llu us\n", (unsigned long long)tsr.synced_at_us);
}

The call triggers a full sync and pushes the offset to the device. Python returns a TimeSyncResult, and C fills a WujiTimeSyncResult:

Field	Type	Description
`offset_us`	`int`	Device clock offset. `device_time = uptime_us + offset_us`
`round_trip_us`	`int`	Network round-trip time of this sync (microseconds), measured with a monotonic clock. Smaller is more accurate
`synced_at_us`	`int`	Host UTC timestamp (microseconds) when this sync completed

Both calls block and are serialized with the SDK’s background sync task. On failure, C leaves *out untouched and records the reason in wuji_last_error().

The SDK already runs a built-in 30-second background auto-sync, so most use cases do not need to call sync_time() manually. Manual calls are useful in two cases: forcing an immediate sync before a time-sensitive operation, or inspecting the quality of the latest sync through the returned round_trip_us.

Timestamp monotonicity

Device-stamped timestamp_us (Wuji Hand 2, Wuji Glove) is strictly monotonically increasing across all sync scenarios. Even when the host clock steps backward or a periodic sync computes a reverse offset, the device smooths the correction so the timestamp never jumps backward. Each frame’s timestamp_us is greater than the previous one, so the field can be used directly for ordering frames and computing sample intervals. Wuji Hand joint-state frames carry host-side timestamps that follow the host clock, outside this guarantee.

Sync accuracy

Sync accuracy is determined mainly by the network round-trip time between the SDK and the device. TimeSyncResult.round_trip_us reflects this metric. The smaller the round-trip time, the more accurate the offset estimate. Over a direct wired Ethernet connection, round-trip time is typically on the order of a few hundred microseconds. The periodic background sync continuously corrects device crystal drift, keeping the device clock aligned with host UTC even over long runs.

Interface List

Operation	Python	C
Configure the background sync interval	`ConnectOptions(auto_time_sync_interval_ms=...)`	`auto_time_sync_interval_ms` and `auto_time_sync_interval_enabled` on `WujiConnectOptions`
Disable background auto-sync	`ConnectOptions(auto_time_sync_interval_ms=None)`	Set `auto_time_sync_interval_enabled` to `false`
Trigger a full sync manually	`glove.sync_time()`	`wuji_glove_sync_time()`
Read the sync result	`offset_us`, `round_trip_us`, and `synced_at_us` on `TimeSyncResult`	The same three fields on `WujiTimeSyncResult`
Read a frame timestamp	`frame.header.timestamp_us`	`frame->header.timestamp_us`

C uses a boolean field where Python uses None: passing None disables background sync in Python, while C sets auto_time_sync_interval_enabled to false. WujiTimeSyncResult is plain old data with no heap fields, so nothing needs releasing.

Overview

Hardware

Software

More

Time Synchronization and Coordinate Transforms

Data frame timestamps

When the timestamp is taken and how it propagates

How synchronization works

Automatic synchronization

Manual synchronization

Timestamp monotonicity

Sync accuracy

Interface List

​Data frame timestamps

​When the timestamp is taken and how it propagates

​How synchronization works

​Automatic synchronization

​Manual synchronization

​Timestamp monotonicity

​Sync accuracy

​Interface List

Data frame timestamps

When the timestamp is taken and how it propagates

How synchronization works

Automatic synchronization

Manual synchronization

Timestamp monotonicity

Sync accuracy

Interface List