Core objects & lifecycle | Qnbot Docs Center

Object hierarchy

The commonly used objects of the Python SDK are organized in the following hierarchy:

Sdk                              # unified entry point of the SDK
└── Glove                        # manages all configured gloves
    └── device() → GloveDevice  # selects a physical glove and its capabilities
        ├── pose()               # reads the raw pose
        ├── imu()                # reads IMU data (experimental feature)
        ├── skeleton()           # reads OpenXR skeleton data
        │   ├── joint_angles()   # reads joint angles
        │   └── pose()           # reads skeleton node pose
        ├── output()             # reads dexterous hand output
        ├── calibration_status() # checks whether calibration is needed
        ├── capture_status()     # queries capture readiness
        ├── start_capture()      # starts capture
        ├── start_calibration()  # starts calibration using a completed capture
        ├── capture_progress()   # checks capture progress
        ├── capture_control()    # confirms, skips, retries, or cancels capture
        ├── calibration_progress() # checks calibration progress
        ├── status()             # checks the device connection status
        └── haptics()            # controls fingertip vibration

Sdk: the complete SDK object, used to uniformly start, stop, run, and check health status.
Glove: the operation entry point for all configured gloves, used to manage gloves and select devices.
GloveDevice: represents a physical glove, providing single-device control and data reading.

Object relationships: Glove is not the same as one glove. One Glove can manage multiple GloveDevice; one GloveDevice can also drive multiple dexterous hands or simulation targets through multiple targets.

Lifecycle

Sdk manages every configured device and capability; when you only use glove capabilities, sdk.glove() is the single entry point:

from qnbot_sdk import Sdk
from qnbot_sdk.glove import GloveConfig

sdk = Sdk(devices=(GloveConfig(),))  # create: devices can be selected, nothing is connected yet
glove = sdk.glove()                  # the glove entry point; use device() for a single device

glove.start()                        # start: connect devices and open the required data streams
try:
    glove.run_forever()              # run: keep receiving data
except KeyboardInterrupt:
    pass
finally:
    glove.close()                    # close: release subscriptions

Create: after Sdk(...) returns, devices can be selected and reads prepared.
Start: capability configuration and callback subscriptions happen before start(); start() connects the devices and opens the required data streams.
Run: for what the SDK publishes and how to read it, see Data channels & read methods; for the three ways to advance the SDK's scheduling, see Runtime modes.
Stop and close: stop() stops running and disconnects, close() releases subscriptions; background mode calls request_stop() first.

Sdk, Glove and GloveDevice each have their own lifecycle methods:

Object	Scope
`Sdk`	The whole SDK: every configured device and capability
`Glove`	Glove capabilities only
`GloveDevice`	A single device: `start()`, `stop()`, `health()` and `close()`

Per-device close() releases that device scope, which cannot be restarted afterward; glove.close() releases all glove resources. For signatures, see the GloveDevice method table.