Core objects & lifecycle | Qnbot Docs Center

Object hierarchy

Common objects are organized in the following hierarchy:

Sdk                              # Unified entry point of the SDK
└── Glove                        # Manages all configured gloves
    └── device() → GloveDevice  # Select a physical glove and its capabilities
        ├── capture_status()     # Query capture readiness
        ├── start_capture()      # Start capture
        ├── start_calibration()  # Start calibration using a completed capture
        ├── pose()               # Read the raw pose
        ├── imu()                # Read IMU data (experimental)
        ├── skeleton()           # Read OpenXR skeleton data
        │   ├── joint_angles()   # Read joint angles
        │   └── pose()           # Read skeleton node poses
        ├── output()             # Read dexterous hand output
        ├── calibration_status() # Check whether calibration is needed
        ├── capture_progress()   # Check capture progress
        ├── capture_control()    # Confirm, skip, retry, or cancel a capture
        ├── calibration_progress() # Check calibration progress
        ├── status()             # Check device connection status
        └── haptics()            # Control fingertip haptics

Sdk: the complete SDK object, used to start, stop, run, and inspect the health of the whole SDK uniformly.
Glove: the entry point for all configured gloves, used to manage gloves and select devices.
GloveDevice: represents one physical glove and provides 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.

Sdk, Subscription, and NextOperation<T> are all non-copyable. Sdk can be moved; Gloves, devices, data read entry points, and update results obtained before the move still belong to the same SDK, and the original object cannot continue to be used after the move.

Lifecycle

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

qnbot::SdkConfig config;
config.devices = {qnbot::GloveConfig{}};

qnbot::Sdk sdk(std::move(config));  // create: devices are discovered and verified, not started
auto glove = sdk.glove();           // the glove entry point

glove.start();                      // start: connect devices and open the required data streams
glove.run_forever();                // run: keep receiving data
glove.close();                      // close: release subscriptions and disconnect

Create: Sdk construction completes device discovery, identity verification and target resolution before returning, so devices can be selected and reads prepared right after.
Start: capability configuration and 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() and join() 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()` and `stop()`, with no separate `close()`

For the method tables and cross-object scope, see Lifecycle and scope in the API reference.