GloveConfig

• side: Required for external input
• side: an explicit value must match the device or the input frame
• connection: The serial port is used for a physical glove
• connection: external is used for per-frame external input
• name: When provided, it must be a non-empty name and unique among enabled devices
• name: with multiple devices, explicitly naming them is recommended
• enabled: When False, it does not connect, does not start, cannot be selected, and cannot serve as a target source

SerialConnection

• auto_discover: Choose exactly one of this, port, and serial_number
• auto_discover: the discovery result must be unique and pass identity validation
• port: Specifies the serial port
• port: the configured identity can be used only when GloveConfig.side is also provided, the port is recognized as a supported wired directly connected glove, and the old firmware does not support id
• serial_number: Discovers by USB serial number, always requires a valid device identity, and cannot use the old firmware fallback
• baudrate: must be an integer between 1 and 4294967295 when provided

ExternalConnection

ExternalConnection has no configuration fields, but requires GloveConfig.side.

TargetConfig

• type: An explicit value narrows and validates the candidates
• type: the currently public values are HAND and ARM
• name: Caller-defined output instance name
• name: it must not be duplicated for the same target ID, and the reserved name skeleton cannot be used as an ordinary target name
• side: An explicit value must be compatible with the source and the algorithm capabilities
• source: Zero candidates or multiple candidates both cause SDK creation to fail
• algorithms: Executed in configuration order
• algorithms: an empty sequence means the input is passed through directly

DeviceSelector

• type: Must be a non-empty device type
• type: gloves use "glove"
• name: Matches the device name in the configuration
• side: Matches the physical side of the device
• side: the combined conditions must uniquely select one enabled source

TargetAlgorithm

• id: Must be a non-empty algorithm package ID, and the corresponding package must already be installed and be compatible with the current platform and SDK

AlgorithmsConfig

• calibration: Controls whether to recalculate the calibration
• capture: Controls the interaction mode, the wearer identifier, and whether an existing capture is reused

CaptureConfig

• interaction: AUTO_TERMINAL suits a foreground terminal
• interaction: GUI, remote, or no-TTY hosts use EXTERNAL and handle Capture control
• force: When True, ignores reusable raw frames and samples again
• force: it is not continuous capture and does not sample again on every update
• operator_id: Must be a non-empty string
• operator_id: serves as the wearer identifier, used to separately look up and save captures and calibration records for different wearers

CalibrationConfig

• force: When True, recalculates the calibration using the currently available capture without forcing a new sample
• force: after it succeeds the same SDK reuses the new result on stop or reconnect; the next SDK created with force=True still set recalculates again

DebugConfig

• modules: Optional: TRANSPORT, DEVICE, CAPTURE, CALIBRATION, RETARGETING, OUTPUT
• detail: Can only be SUMMARY or FULL
• detail: FULL records more runtime data and produces a larger log volume
• sample_rate: When provided, it must be a positive uint32
• sample_rate: a value of N means one record out of every N, and important events are not dropped

SdkConfig and Sdk(...)

• devices: Each item must be a public device configuration
• devices: enabled device names and the final source must be unique
• targets: Each target must resolve to an enabled source
• targets: creation fails on duplication, ambiguity, or incompatibility
• debug: When provided, enables Debug logs for that SDK instance
• algorithms: Controls Capture and Calibration behavior and is not responsible for installing algorithm packages

Application data directory

When QNBOT_HOME is not set, the SDK uses ~/.qnbot as the application data root directory.

Set that environment variable to use a different directory. Calibration records are stored in <QNBOT_HOME>/glove/calibrations, and Debug logs in <QNBOT_HOME>/logs.

• Timing: it must be set before creating the Sdk
• Consistency: the CLI and the SDK should use the same value, otherwise the SDK may not find the algorithm packages the CLI installed

Terminal output and interaction

With nothing configured, the built-in terminal enables level colors only in an interactive TTY: the Error label is bold red, the Warning label is yellow, the Info label uses the terminal's default foreground color, and Success key results use green. Only level labels and key results are colored; the whole message is not colorized. Debug logs and diagnostic JSON never contain ANSI colors.

NO_COLOR keeps messages plain text; QNBOT_INTERACTIVE_CONSOLE=1 tells the SDK that the current console can receive user input; PYCHARM_HOSTED=1 is set by JetBrains and makes the JetBrains Python Run/Debug Console input-capable even when it uses a pipe.

• Coloring scope: only level labels and key results are colored, never the whole message
• Non-TTY: redirected output, pipes and other non-TTY environments behave the same as setting NO_COLOR
• Setting only TERM: does not make the SDK treat the console as input-capable
• Interaction mode: these variables do not change the configured interaction mode; taking over the interaction still requires CaptureConfig.interaction to be EXTERNAL, see Capture