Migration

Upgrading from 1.3.0 to 1.4.0

The primary required migration in 1.4.0 is the unified time unit. An existing standalone Glove application does not need to become a composite or call sync_time() unless it uses an external time source, consumes numeric time fields, or is adopting Exo + Glove hardware.

Update Core and Glove together

Install qnbot-sdk-glove 1.4.0 and let pip resolve the matching Core dependency. Do not let a packaged application continue carrying the 1.3.0 native library:

python -m pip install --upgrade "qnbot-sdk-glove==1.4.0"

If the application bundles wheels, native libraries, or a virtual environment, remove the old artifacts before rebuilding and deploying it.

Change public numeric time values to milliseconds

Glove frames, runtime state, capture, calibration, and derived data use milliseconds in 1.4.0. New output exposes timestamp_ms only. Update code that reads, stores, subtracts, or forwards a time value as seconds.

Use timestamp_ms for a new external frame:

frame = ExternalGloveFrame(
    thumb=thumb,
    index=index,
    middle=middle,
    ring=ring,
    pinky=pinky,
    timestamp_ms=1_700_000_000_123.0,
)

The legacy timestamp_sec remains an explicit compatibility input and is converted as timestamp_ms = timestamp_sec * 1000. The SDK does not infer a unit from the numeric magnitude. Do not provide both fields: supplying timestamp_ms and timestamp_sec together is an argument error.

Set an external time reference when needed

Call the public Glove.sync_time() entry point when every Glove source needs one external absolute time reference. The argument is absolute Unix milliseconds, not seconds or nanoseconds:

import time

sdk = Sdk(devices=(GloveConfig(),))
glove = sdk.glove()
glove.sync_time(time.time() * 1_000.0)
glove.start()

sync_time() may be called again while running. Subsequent Glove frames without an explicit time advance from the new reference without resetting subscriptions or lifecycle state. An explicit timestamp_ms takes precedence. Without synchronization, the SDK uses host Unix milliseconds. The call changes the Glove domain only and does not modify Exo time.

Adopt an Exo + Glove composite only when needed

Composite support is additive and does not change an existing GloveConfig. For shared-serial hardware, use CompositeExoGloveConfig and obtain sdk.glove() and sdk.exo() from the same Sdk. See Glove + Exo composite solution for the full configuration and capability boundaries.

Migration checklist

• Install matching Core and Glove 1.4.0 packages and remove bundled 1.3.0 native libraries
• Convert second-valued output handling and downstream protocols to milliseconds and timestamp_ms
• If retaining timestamp_sec input temporarily, ensure timestamp_ms is not supplied with it
• Pass absolute Unix milliseconds to glove.sync_time() when an external time source is required
• Use CompositeExoGloveConfig only for composite hardware
• Re-test capture records, time alignment, reconnect recovery, and shutdown on real hardware

Upgrading from 1.2.x to 1.3.0

This section lists only what must change when upgrading the Glove SDK from 1.2.0 to 1.3.0. SerialConnection, background running, and the meaning of the algorithm package package_id are unchanged, so they are not part of this incompatible change set.

The capture entry points move from Glove to GloveDevice

In 1.2.0 the application called the capture entry points on Glove and passed the device selection along with the request:

capture = glove.start_capture(
    package_ids=["qnbot-dexhand"],
    operator_id="operator-001",
    source=None,
    side=Side.LEFT,
    force=False,
)

Here source selects the device by name and side selects it by hand; when source is empty, side decides.

In 1.3.0, select the target device first and then run the capture:

device = glove.device(side=Side.LEFT)

capture = device.start_capture(
    package_ids=["qnbot-dexhand"],
    operator_id="operator-001",
    force=False,
)

The device can also be selected by name:

device = glove.device("my-glove")

Device selection is now separate from the capture request: the application picks the GloveDevice explicitly first.

capture_status() moves to GloveDevice

1.2.0:

readiness = glove.capture_status(
    package_ids=["qnbot-dexhand"],
    operator_id="operator-001",
    source=None,
    side=Side.LEFT,
)

1.3.0:

device = glove.device(side=Side.LEFT)

readiness = device.capture_status(
    package_ids=["qnbot-dexhand"],
    operator_id="operator-001",
)

start_calibration() moves to GloveDevice

1.2.0:

calibration = glove.start_calibration(
    completed_capture_session=capture,
    targets=targets,
)

1.3.0:

calibration = device.start_calibration(
    completed_capture_session=capture,
    targets=targets,
)

The capture session and the calibration session are managed by the same GloveDevice:

device = glove.device(side=Side.LEFT)

capture = device.start_capture(
    package_ids=["qnbot-dexhand"],
    operator_id="operator-001",
)

calibration = device.start_calibration(
    completed_capture_session=capture,
    targets=targets,
)

CalibrationInteractionMode is renamed

The 1.2.0 CalibrationInteractionMode is renamed to CaptureInteractionMode in 1.3.0, with the same values (AUTO_TERMINAL, EXTERNAL):

from qnbot_sdk import CaptureInteractionMode

Project code, configuration mappings, and custom wrappers that use the old enum name must all be updated.

Capture interaction configuration moves from CalibrationConfig to CaptureConfig

1.3.0 separates capture-stage configuration from calibration-stage configuration: interaction and operator_id belong to the capture stage and have moved from CalibrationConfig to CaptureConfig, leaving only force on CalibrationConfig.

If a 1.2.0 project wrote those two fields on CalibrationConfig:

algorithms = AlgorithmsConfig(
    calibration=CalibrationConfig(
        interaction=CalibrationInteractionMode.EXTERNAL,
        operator_id="operator-001",
        force=False,
    ),
)

1.3.0 requires:

algorithms = AlgorithmsConfig(
    capture=CaptureConfig(
        interaction=CaptureInteractionMode.EXTERNAL,
        operator_id="operator-001",
    ),
    calibration=CalibrationConfig(force=False),
)

The meaning and ownership of the two force flags are unchanged; see CaptureConfig and CalibrationConfig for the field definitions.

Migration checklist

• Change glove.start_capture() to device.start_capture()
• Change glove.capture_status() to device.capture_status()
• Change glove.start_calibration() to device.start_calibration()
• Change CalibrationInteractionMode to CaptureInteractionMode
• Move interaction and operator_id from CalibrationConfig to CaptureConfig
• Make sure capture and calibration use the same GloveDevice

Upgrading from 1.1.x to 1.2.0

The following lists only the incompatible changes that require modifying existing code or rebuilding when upgrading. For complete new features, fixes, and version changes, see the Python SDK changelog.