API Reference
ContactGlove SDK v2 is a C++ library for interacting with ContactGlove devices.
Setup and integration
See the SDK guide for supported operating systems, CPU architectures, runtime and build requirements, distribution installation, CMake/C/Rust integration, and troubleshooting.
Examples
Connecting to and disconnecting from DivingStation
Use ConnectToHost to connect to DivingStation.
The connection information passed to ConnectToHost consists of a host name, IP address, DivingStation receive port, and SDK receive port. The host name is an arbitrary label used to distinguish hosts. The IP address is assigned to the computer running DivingStation. The DivingStation receive port accepts OSC requests from the SDK. It is normally 25791, but it can be changed in DivingStation; use the corresponding value when it is changed. The SDK receive port accepts data streams from DivingStation.
Use Disconnect to disconnect from DivingStation.
#include <chrono>
#include <iostream>
#include <thread>
#include "contactglove/ContactGloveSDKv2.hpp"
int main() {
ContactGloveSDKv2::SDK sdk;
// Set the connection information.
ContactGloveSDKv2::Host host{"localhost", "127.0.0.1", 25791, 25788};
// Connect to DivingStation.
sdk.ConnectToHost(host);
// Perform application-specific work.
// Disconnect from DivingStation.
sdk.Disconnect(host);
return(0);
}Querying data
The following functions retrieve information associated with a glove. Each returns the value available when the function is called.
| Available value | Function |
|---|---|
| Glove information | GetDataForGlove |
| Whether a glove supports haptics | DoesGloveSupportHaptics |
| Opening and bending angles for each finger joint | GetErgonomicsDataForGlove |
| Position and rotation of each finger joint | GetSkeletonDataForGlove |
| Raw sensor position and rotation | GetRawSensorTransformsForGlove |
| Input from the controller attached to the glove | GetControllerDataForGlove |
| IDs of all connected gloves | GetIdsOfAvailableGloves |
| Number of connected gloves | GetNumberofAvailableGloves |
Glove data arrives asynchronously. A successful ConnectToHost call starts the local session; it does not confirm approval or data reception. Use a glove ID received from DivingStation when querying data. When multiple gloves are present, select the intended device using its ID or properties such as isLeft.
The bundled share/ContactGloveSDKv2/examples/basic_usage.cpp demonstrates callbacks and polling with DivingStation on the same PC (127.0.0.1). It polls the first ID received and disconnects after approximately five seconds.
For LAN connections that require approval, keep the same session alive while waiting for approval and data. Calling Disconnect can discard pending or granted approval; a successful connection request does not confirm approval.
Receiving updates automatically
Register callback functions to receive automatic updates when glove-related values change. Callbacks run on the SDK receiver thread and may query cached data. An exception thrown by one callback is contained; the remaining callbacks and records are still delivered. Do not connect, disconnect, or destroy this SDK from a callback. Schedule connection management on another thread instead. Disconnect waits for active callbacks to finish. Finish callbacks that access the SDK before starting its destruction.
| Update that triggers the callback | Function |
|---|---|
| Glove information | RegisterCallbackForGloveDataStream |
| Opening and bending angles for each finger joint | RegisterCallbackForErgonomicsStream |
| Position and rotation of each finger joint | RegisterCallbackForSkeletonStream |
| Raw sensor position and rotation | RegisterCallbackForRawSensorTransformsStream |
| Input from the controller attached to the glove | RegisterCallbackForControllerDataStream |
See the bundled share/ContactGloveSDKv2/examples/basic_usage.cpp for a complete callback and polling example and its five-second lifetime.
C ABI and Rust bindings
include/contactglove/ContactGloveSDKv2C.h is the ContactGlove SDK v2 C++/C/Rust FFI header. It can be used directly from C with no additional header. The C ABI v2 exposes opaque handles, fixed-width numeric types, UTF-8 string views, caller-provided buffers, and subscription tokens.
Although most C ABI data structures correspond to the C++ types documented here, their lifetime and memory contracts differ. For polling results that include strings, the caller provides a buffer in cg_string_buffer_t. Even when CG_RESULT_BUFFER_TOO_SMALL is returned, length receives the required character count. Allocate sufficient storage and retry the same function. Memory returned by the SDK does not need to be freed.
Manage stream subscriptions with cg_sdk_subscribe_* and cg_sdk_unsubscribe. A callback view is valid only during the callback invocation. After cg_sdk_unsubscribe succeeds, its callback is not running. Disconnecting, destroying the SDK, or unsubscribing from within a callback is unsupported.
The v2 updates expose device field is_external_power_present and the invalid value battery_percentage=-1, tracking_state for ergonomics and skeleton data, profile_uuid for retargeted skeleton data, HandSkeletonRaw, and retarget profile information request and response messages. The Rust bindings expose the same query and callback surface. The numeric C ABI and Rust color fields use the DeviceColor values for the device display-color setting. Their numeric tracking_state fields use TrackingState values and the same display/diagnostic-only restriction for IkFailed and NotAttempted. While connected, the SDK resends Connect every 30 seconds and reuses the same send socket for Connect, Disconnect, and haptics requests.
The official Rust workspace is included in rust/ in distributions. contactglove-sdk-v2-sys provides the C ABI layer, while contactglove-sdk-v2 provides owned types and RAII subscriptions.
Defined types and functions
The following types and functions are defined by this SDK.
Classes
| Name | Description |
|---|---|
SDK | Main class of the ContactGlove SDK. |
GloveData | Structure holding glove device information. |
Host | Structure describing a DivingStation host. |
Vec3 | Three-dimensional vector. |
Quaternion | Quaternion representing rotation. |
Transform | Transform combining position and rotation. |
ControllerData | Structure holding controller input states. |
ErgonomicsData | Structure holding finger opening and bending angle data. |
SkeletonData | Structure holding hand skeleton data (joint positions and rotations). |
RawSkeletonData | Hand skeleton data before retargeting. |
RetargetProfileInfo | Response containing retarget profile information. |
RawSensorTransformsData | Structure holding raw sensor transform data for one hand. |
Enumerations
| Name | Description |
|---|---|
DeviceFamilyType | Enumeration of device families. |
DeviceColor | Enumeration of device display-color settings. |
DeviceConnectedState | Enumeration of device connection states. |
TrackingState | Tracking state of IK-derived data. |
SDKReturnCode | Return codes used by SDK functions. |
ButtonStatus | Enumeration of button states. |
ErgonomicsDataType | Enumeration identifying the joint represented by each ergonomics data element. |
SkeletonDataType | Enumeration identifying the joint represented by each skeleton data element. |
DeviceFamilyType
enum DeviceFamilyTypeEnumeration of device families.
ContactGlove3 is the primary target.
| Value | Description |
|---|---|
ContactGlove | ContactGlove. |
ContactSheet | ContactSheet. |
ContactGlove2 | ContactGlove2. |
ContactGlove3 | ContactGlove3. |
DeviceColor
enum DeviceColorEnumeration of device display-color settings.
Migrating the display-color type name
DeviceColor is the public display-color type. Replace references such as LedColor::Green with DeviceColor::Green and rebuild. LedColor remains a C++ compatibility alias of DeviceColor, so existing source still compiles. Prefer DeviceColor in new code. The GloveData.color member name and numeric color values stay the same. The C ABI version remains 2. The C ABI and Rust integer color fields and the OSC wire format are unchanged.
| Value | Description |
|---|---|
Magenta | Magenta. |
Red | Red. |
Orange | Orange. |
Yellow | Yellow. |
Green | Green. |
Cyan | Cyan. |
Blue | Blue. |
Achromatic | Achromatic. |
DeviceConnectedState
enum DeviceConnectedStateEnumeration of device connection states.
| Value | Description |
|---|---|
Unknown | State unknown. |
Connected | Connected. |
Unconnected | Not connected. |
Pairing | Connection attempt in progress. |
TrackingState
enum TrackingStateTracking state of IK-derived data.
NotAttempted means the required IK pass was not performed. This includes earlier processing failures or missing input, and cases where pose calculation was deemed unnecessary, such as update-interval control reusing an existing pose. It does not itself indicate an IK failure.
IkFailed and NotAttempted values may be used for display and diagnostics, but must not be used for control, velocity estimation or interpolation. Only Tracked values are valid for those uses.
SkeletonData reports retarget IK; RawSkeletonData and ErgonomicsData report source skeleton IK. Their states can differ at the same time. For retarget IK, NotAttempted also includes a decision that pose calculation was unnecessary.
| Value | Description |
|---|---|
Tracked | Valid result from the current IK pass. |
IkFailed | IK was attempted but failed. |
NotAttempted | IK was not performed, including intentional update-interval skips. |
SDKReturnCode
enum SDKReturnCodeReturn codes used by SDK functions.
Indicates the result of a function call or the kind of error.
| Value | Description |
|---|---|
Success | Operation completed successfully. |
SdkNotAvailable | The SDK or requested feature is unavailable. |
NotConnected | Not connected to DivingStation. |
InvalidID | The specified ID does not exist. |
InvalidArgument | An argument is outside its valid range. |
ButtonStatus
enum ButtonStatusEnumeration of button states.
| Value | Description |
|---|---|
Unpressed | Not pressed. |
Touching | Touch sensor detected contact. |
Pressed | Pressed. |
ErgonomicsDataType
enum ErgonomicsDataTypeEnumeration identifying the joint represented by each ergonomics data element.
Left-hand values are 0 through 19 and right-hand values are 20 through 39, but ErgonomicsData::data always holds only one hand (20 elements). To use a value as an index into ErgonomicsData::data, use static_cast<uint32_t>(type) % ERGONOMICS_DATA_COUNT. Values are in degrees.
Naming convention: (Left|Right){finger name}{joint name}{motion type}.
| Value | Description |
|---|---|
LeftThumbCMCFlex | Left thumb CMC joint flexion angle. |
LeftThumbMCPFlex | Left thumb MCP joint flexion angle. |
LeftThumbIPFlex | Left thumb IP joint flexion angle. |
LeftThumbMCPTilt | Left thumb MCP joint tilt angle. |
LeftIndexMCPFlex | Left index finger MCP joint flexion angle. |
LeftIndexPIPFlex | Left index finger PIP joint flexion angle. |
LeftIndexDIPFlex | Left index finger DIP joint flexion angle. |
LeftIndexMCPTilt | Left index finger MCP joint tilt angle. |
LeftMiddleMCPFlex | Left middle finger MCP joint flexion angle. |
LeftMiddlePIPFlex | Left middle finger PIP joint flexion angle. |
LeftMiddleDIPFlex | Left middle finger DIP joint flexion angle. |
LeftMiddleMCPTilt | Left middle finger MCP joint tilt angle. |
LeftRingMCPFlex | Left ring finger MCP joint flexion angle. |
LeftRingPIPFlex | Left ring finger PIP joint flexion angle. |
LeftRingDIPFlex | Left ring finger DIP joint flexion angle. |
LeftRingMCPTilt | Left ring finger MCP joint tilt angle. |
LeftLittleMCPFlex | Left little finger MCP joint flexion angle. |
LeftLittlePIPFlex | Left little finger PIP joint flexion angle. |
LeftLittleDIPFlex | Left little finger DIP joint flexion angle. |
LeftLittleMCPTilt | Left little finger MCP joint tilt angle. |
RightThumbCMCFlex | Right thumb CMC joint flexion angle. |
RightThumbMCPFlex | Right thumb MCP joint flexion angle. |
RightThumbIPFlex | Right thumb IP joint flexion angle. |
RightThumbMCPTilt | Right thumb MCP joint tilt angle. |
RightIndexMCPFlex | Right index finger MCP joint flexion angle. |
RightIndexPIPFlex | Right index finger PIP joint flexion angle. |
RightIndexDIPFlex | Right index finger DIP joint flexion angle. |
RightIndexMCPTilt | Right index finger MCP joint tilt angle. |
RightMiddleMCPFlex | Right middle finger MCP joint flexion angle. |
RightMiddlePIPFlex | Right middle finger PIP joint flexion angle. |
RightMiddleDIPFlex | Right middle finger DIP joint flexion angle. |
RightMiddleMCPTilt | Right middle finger MCP joint tilt angle. |
RightRingMCPFlex | Right ring finger MCP joint flexion angle. |
RightRingPIPFlex | Right ring finger PIP joint flexion angle. |
RightRingDIPFlex | Right ring finger DIP joint flexion angle. |
RightRingMCPTilt | Right ring finger MCP joint tilt angle. |
RightLittleMCPFlex | Right little finger MCP joint flexion angle. |
RightLittlePIPFlex | Right little finger PIP joint flexion angle. |
RightLittleDIPFlex | Right little finger DIP joint flexion angle. |
RightLittleMCPTilt | Right little finger MCP joint tilt angle. |
SkeletonDataType
enum SkeletonDataTypeEnumeration identifying the joint represented by each skeleton data element.
Use this enum to index SkeletonData::transforms. It maps to SKELETON_NODE_COUNT elements for one hand.
Naming convention: Skeleton{finger}{joint name} or Skeleton{finger}Tip.
| Value | Description |
|---|---|
SkeletonWrist | Wrist. |
SkeletonThumbCMC | Thumb CMC joint. |
SkeletonThumbMCP | Thumb MCP joint. |
SkeletonThumbIP | Thumb IP joint. |
SkeletonThumbTip | Thumb tip. |
SkeletonIndexCMC | Index finger CMC joint. |
SkeletonIndexMCP | Index finger MCP joint. |
SkeletonIndexPIP | Index finger PIP joint. |
SkeletonIndexDIP | Index finger DIP joint. |
SkeletonIndexTip | Index finger tip. |
SkeletonMiddleCMC | Middle finger CMC joint. |
SkeletonMiddleMCP | Middle finger MCP joint. |
SkeletonMiddlePIP | Middle finger PIP joint. |
SkeletonMiddleDIP | Middle finger DIP joint. |
SkeletonMiddleTip | Middle finger tip. |
SkeletonRingCMC | Ring finger CMC joint. |
SkeletonRingMCP | Ring finger MCP joint. |
SkeletonRingPIP | Ring finger PIP joint. |
SkeletonRingDIP | Ring finger DIP joint. |
SkeletonRingTip | Ring finger tip. |
SkeletonLittleCMC | Little finger CMC joint. |
SkeletonLittleMCP | Little finger MCP joint. |
SkeletonLittlePIP | Little finger PIP joint. |
SkeletonLittleDIP | Little finger DIP joint. |
SkeletonLittleTip | Little finger tip. |
Typedefs
| Return | Name | Description |
|---|---|---|
uint64_t | Timestamp | Integer type representing Unix time in milliseconds. |
std::string | GloveId | Identifier of a glove device. |
DeviceColor | LedColor | Compatibility alias for DeviceColor. Prefer DeviceColor in new code. |
std::function< void(const GloveData &)> | GloveDataStreamCallback_t | Callback function type invoked when glove data is updated. |
std::function< void(const ControllerData &)> | ControllerDataStreamCallback_t | Callback function type invoked when controller data is updated. |
std::function< void(const ErgonomicsData &)> | ErgonomicsStreamCallback_t | Callback function type invoked when ergonomics data is updated. |
std::function< void(const SkeletonData &)> | SkeletonStreamCallback_t | Callback function type invoked when skeleton data is updated. |
std::function< void(const RawSkeletonData &)> | RawSkeletonStreamCallback_t | |
std::function< void(const RawSensorTransformsData &)> | RawSensorTransformsStreamCallback_t | Callback function type invoked when raw sensor transform data is updated. |
std::function< void(const RetargetProfileInfo &)> | RetargetProfileInfoCallback_t |
Timestamp
uint64_t Timestamp()Integer type representing Unix time in milliseconds.
GloveId
std::string GloveId()Identifier of a glove device.
LedColor
DeviceColor LedColor()Compatibility alias for DeviceColor. Prefer DeviceColor in new code.
GloveDataStreamCallback_t
std::function< void(const GloveData &)> GloveDataStreamCallback_t()Callback function type invoked when glove data is updated.
ControllerDataStreamCallback_t
std::function< void(const ControllerData &)> ControllerDataStreamCallback_t()Callback function type invoked when controller data is updated.
ErgonomicsStreamCallback_t
std::function< void(const ErgonomicsData &)> ErgonomicsStreamCallback_t()Callback function type invoked when ergonomics data is updated.
SkeletonStreamCallback_t
std::function< void(const SkeletonData &)> SkeletonStreamCallback_t()Callback function type invoked when skeleton data is updated.
RawSkeletonStreamCallback_t
std::function< void(const RawSkeletonData &)> RawSkeletonStreamCallback_t()RawSensorTransformsStreamCallback_t
std::function< void(const RawSensorTransformsData &)> RawSensorTransformsStreamCallback_t()Callback function type invoked when raw sensor transform data is updated.
RetargetProfileInfoCallback_t
std::function< void(const RetargetProfileInfo &)> RetargetProfileInfoCallback_t()Variables
| Return | Name | Description |
|---|---|---|
uint32_t | ERGONOMICS_DATA_COUNT | Number of ergonomics data elements per hand (five fingers times four joints). |
uint32_t | SKELETON_NODE_COUNT | Number of skeleton nodes per hand (wrist, four thumb nodes, and five nodes for each of four fingers). |
uint32_t | SKELETON_DATA_COUNT | Number of skeleton transforms per hand. |
uint32_t | RAW_SENSOR_TRANSFORM_COUNT | Number of raw sensor transforms per hand. |
ERGONOMICS_DATA_COUNT
uint32_t ERGONOMICS_DATA_COUNT = 20Number of ergonomics data elements per hand (five fingers times four joints).
SKELETON_NODE_COUNT
uint32_t SKELETON_NODE_COUNT = 25Number of skeleton nodes per hand (wrist, four thumb nodes, and five nodes for each of four fingers).
SKELETON_DATA_COUNT
uint32_t SKELETON_DATA_COUNT = SKELETON_NODE_COUNTNumber of skeleton transforms per hand.
RAW_SENSOR_TRANSFORM_COUNT
uint32_t RAW_SENSOR_TRANSFORM_COUNT = 5Number of raw sensor transforms per hand.
SDK
#include <contactglove/ContactGloveSDKv2.hpp>Main class of the ContactGlove SDK.
Public Methods
| Return | Name | Description |
|---|---|---|
SDK | ||
SDK | Deleted constructor. | |
SDKReturnCode | ConnectToHost | Connect to DivingStation and start data streams. |
SDKReturnCode | Disconnect | Disconnect from DivingStation. |
SDKReturnCode | DoesGloveSupportHaptics const | Query whether a glove supports haptics. |
SDKReturnCode | GetDataForGlove const | Retrieve glove information by glove ID. |
SDKReturnCode | GetControllerDataForGlove const | Retrieve controller input data by glove ID. |
SDKReturnCode | GetErgonomicsDataForGlove const | Retrieve finger opening and bending angle data by glove ID. |
SDKReturnCode | GetSkeletonDataForGlove const | Retrieve joint position and rotation data by glove ID. |
SDKReturnCode | GetRawSkeletonDataForGlove const | Retrieve pre-retarget hand skeleton data by glove ID. |
SDKReturnCode | GetRawSensorTransformsForGlove const | Retrieve raw sensor transform data by glove ID. |
SDKReturnCode | GetIdsOfAvailableGloves const | Retrieve IDs of all currently recognized gloves. |
SDKReturnCode | GetNumberofAvailableGloves const | Retrieve the total number of currently recognized gloves. |
SDKReturnCode | VibrateGlove | Vibrate a glove. |
SDKReturnCode | RequestRetargetProfileInfo | Send a request for retarget profile information. |
SDKReturnCode | RegisterCallbackForGloveDataStream | Register a callback invoked when glove information is updated. |
SDKReturnCode | RegisterCallbackForControllerDataStream | Register a callback invoked when controller data is updated. |
SDKReturnCode | RegisterCallbackForErgonomicsStream | Register a callback invoked when ergonomics data is updated. |
SDKReturnCode | RegisterCallbackForSkeletonStream | Register a callback invoked when skeleton data is updated. |
SDKReturnCode | RegisterCallbackForRawSkeletonStream | |
SDKReturnCode | RegisterCallbackForRawSensorTransformsStream | Register a callback invoked when raw sensor transform data is updated. |
SDKReturnCode | RegisterCallbackForRetargetProfileInfoStream |
SDK
SDK()SDK
SDK(const SDK &) = deleteDeleted constructor.
ConnectToHost
SDKReturnCode ConnectToHost(const Host & p_Host)Connect to DivingStation and start data streams.
Calling again with the same endpoint and ports resends Connect using the existing socket, including its OS-selected source port when sendPort is 0. Use this for automatic retries while awaiting LAN approval or recovering from lost data. Success means the request was started; it does not confirm LAN approval. Disconnect explicitly ends the session and can revoke approval.
Parameters
p_HostHost information for the target DivingStation instance.
Returns
SDKReturnCode::Success — Connection started successfully.
Returns
SDKReturnCode::SdkNotAvailable — Failed to open a socket.
Returns
SDKReturnCode::InvalidArgument — p_Host.sendPort is greater than 65535.
Returns
SDKReturnCode::InvalidArgument — The receive port is already in use by a connection with a different IP address, destination port, or send port.
Disconnect
SDKReturnCode Disconnect(const Host & p_Host)Disconnect from DivingStation.
Parameters
p_HostHost information to disconnect. It must match the value passed toConnectToHost().
Returns
SDKReturnCode::Success — Disconnected successfully.
Returns
SDKReturnCode::NotConnected — No connection exists for the specified port.
DoesGloveSupportHaptics
const
SDKReturnCode DoesGloveSupportHaptics(const std::string & id, bool * p_IsHaptics) constQuery whether a glove supports haptics.
Parameters
-
idID of the glove to query. -
p_IsHapticsOutput location for whether haptics are supported; must not be null.
Returns
SDKReturnCode::Success — Value retrieved successfully.
Returns
SDKReturnCode::InvalidID — The specified glove does not exist.
GetDataForGlove
const
SDKReturnCode GetDataForGlove(const std::string & id, GloveData * p_GloveData) constRetrieve glove information by glove ID.
Parameters
-
idID of the glove to retrieve. -
p_GloveDataOutput location for the retrieved data; must not be null.
Returns
SDKReturnCode::Success — Data retrieved successfully.
Returns
SDKReturnCode::InvalidID — The specified glove does not exist.
GetControllerDataForGlove
const
SDKReturnCode GetControllerDataForGlove(const std::string & id, ControllerData * p_Controller) constRetrieve controller input data by glove ID.
Parameters
-
idID of the glove to retrieve. -
p_ControllerOutput location for the retrieved data; must not be null.
Returns
SDKReturnCode::Success — Data retrieved successfully.
Returns
SDKReturnCode::InvalidID — No data exists for the specified ID, or p_Controller is null.
GetErgonomicsDataForGlove
const
SDKReturnCode GetErgonomicsDataForGlove(const std::string & id, ErgonomicsData * p_ErgonomicsData) constRetrieve finger opening and bending angle data by glove ID.
Parameters
-
idID of the glove to retrieve. -
p_ErgonomicsDataOutput location for the retrieved data; must not be null.
Returns
SDKReturnCode::Success — Data retrieved successfully.
Returns
SDKReturnCode::InvalidID — No data exists for the specified ID, or p_ErgonomicsData is null.
GetSkeletonDataForGlove
const
SDKReturnCode GetSkeletonDataForGlove(const std::string & id, SkeletonData * p_SkeletonData) constRetrieve joint position and rotation data by glove ID.
Parameters
-
idID of the glove to retrieve. -
p_SkeletonDataOutput location for the retrieved data; must not be null.
Returns
SDKReturnCode::Success — Data retrieved successfully.
Returns
SDKReturnCode::InvalidID — No data exists for the specified ID, or p_SkeletonData is null.
GetRawSkeletonDataForGlove
const
SDKReturnCode GetRawSkeletonDataForGlove(const std::string & id, RawSkeletonData * p_RawSkeletonData) constRetrieve pre-retarget hand skeleton data by glove ID.
GetRawSensorTransformsForGlove
const
SDKReturnCode GetRawSensorTransformsForGlove(const std::string & id, RawSensorTransformsData * p_RawSensorTransforms) constRetrieve raw sensor transform data by glove ID.
Parameters
-
idID of the glove to retrieve. -
p_RawSensorTransformsOutput location for the retrieved data; must not be null.
Returns
SDKReturnCode::Success — Data retrieved successfully.
Returns
SDKReturnCode::InvalidID — No data exists for the specified ID, or p_RawSensorTransforms is null.
GetIdsOfAvailableGloves
const
SDKReturnCode GetIdsOfAvailableGloves(GloveId * p_IdsOfAvailableGloves, uint32_t p_NumberOfIdsThatFitInArray) constRetrieve IDs of all currently recognized gloves.
When the output array is too small, only the first p_NumberOfIdsThatFitInArray IDs are written. Query the total count in advance with GetNumberofAvailableGloves().
Parameters
-
p_IdsOfAvailableGlovesPointer to the first element of the output ID array; must not be null. -
p_NumberOfIdsThatFitInArrayCapacity of the output array in elements.
Returns
SDKReturnCode::Success — Data retrieved successfully.
Returns
SDKReturnCode::InvalidID — p_IdsOfAvailableGloves is null.
GetNumberofAvailableGloves
const
SDKReturnCode GetNumberofAvailableGloves(uint32_t * n) constRetrieve the total number of currently recognized gloves.
Parameters
nOutput location for the count; must not be null.
Returns
SDKReturnCode::Success — Data retrieved successfully.
Returns
SDKReturnCode::InvalidID — n is null.
VibrateGlove
SDKReturnCode VibrateGlove(const std::string & id, float frequency, float amplitude, float duration)Vibrate a glove.
Parameters
-
idID of the glove to vibrate. -
frequencyVibration frequency in Hz (100.0 to 500.0). -
amplitudeVibration amplitude (0.0 to 1.0). -
durationVibration duration in seconds (0.001 to 1.0).
Returns
SDKReturnCode::Success — Request sent successfully.
Returns
SDKReturnCode::InvalidID — The specified glove does not exist.
Returns
SDKReturnCode::InvalidArgument — An argument is outside its valid range.
RequestRetargetProfileInfo
SDKReturnCode RequestRetargetProfileInfo(const std::string & profileUuid, int32_t requestId)Send a request for retarget profile information.
RegisterCallbackForGloveDataStream
SDKReturnCode RegisterCallbackForGloveDataStream(GloveDataStreamCallback_t p_Callback)Register a callback invoked when glove information is updated.
The callback receives a GloveData argument.
Parameters
p_CallbackCallback function to register.
Returns
SDKReturnCode::Success — Registered successfully.
RegisterCallbackForControllerDataStream
SDKReturnCode RegisterCallbackForControllerDataStream(ControllerDataStreamCallback_t p_Callback)Register a callback invoked when controller data is updated.
Parameters
p_CallbackCallback function to register.
Returns
SDKReturnCode::Success — Registered successfully.
RegisterCallbackForErgonomicsStream
SDKReturnCode RegisterCallbackForErgonomicsStream(ErgonomicsStreamCallback_t p_Callback)Register a callback invoked when ergonomics data is updated.
Parameters
p_CallbackCallback function to register.
Returns
SDKReturnCode::Success — Registered successfully.
RegisterCallbackForSkeletonStream
SDKReturnCode RegisterCallbackForSkeletonStream(SkeletonStreamCallback_t p_Callback)Register a callback invoked when skeleton data is updated.
Parameters
p_CallbackCallback function to register.
Returns
SDKReturnCode::Success — Registered successfully.
RegisterCallbackForRawSkeletonStream
SDKReturnCode RegisterCallbackForRawSkeletonStream(RawSkeletonStreamCallback_t p_Callback)RegisterCallbackForRawSensorTransformsStream
SDKReturnCode RegisterCallbackForRawSensorTransformsStream(RawSensorTransformsStreamCallback_t p_Callback)Register a callback invoked when raw sensor transform data is updated.
Parameters
p_CallbackCallback function to register.
Returns
SDKReturnCode::Success — Registered successfully.
RegisterCallbackForRetargetProfileInfoStream
SDKReturnCode RegisterCallbackForRetargetProfileInfoStream(RetargetProfileInfoCallback_t p_Callback)GloveData
#include <contactglove/ContactGloveSDKv2.hpp>Structure holding glove device information.
Corresponds to data received at OSC address /DS2/HC/Device.
Public Attributes
| Return | Name | Description |
|---|---|---|
std::string | id | Device ID. |
std::string | pairId | ID of the paired glove; empty when no pair exists. |
int32_t | batteryPercentage | Battery percentage [0 - 100]; -1 when invalid. |
bool | isHaptics | Whether haptics are supported. |
bool | isLeft | Whether this is a left-hand glove. |
DeviceFamilyType | familyType | Device family. |
DeviceColor | color | Device display-color setting. |
DeviceConnectedState | connectedState | Connection state. |
std::string | name | Device name. |
bool | isExternalPowerPresent | Whether external power is detected. |
id
std::string idDevice ID.
pairId
std::string pairIdID of the paired glove; empty when no pair exists.
batteryPercentage
int32_t batteryPercentage = -1Battery percentage [0 - 100]; -1 when invalid.
isHaptics
bool isHaptics = falseWhether haptics are supported.
isLeft
bool isLeft = falseWhether this is a left-hand glove.
familyType
DeviceFamilyType familyType = DeviceFamilyType::ContactGloveDevice family.
color
DeviceColor color = DeviceColor::AchromaticDevice display-color setting.
connectedState
DeviceConnectedState connectedState = DeviceConnectedState::UnknownConnection state.
name
std::string nameDevice name.
isExternalPowerPresent
bool isExternalPowerPresent = falseWhether external power is detected.
Host
#include <contactglove/ContactGloveSDKv2.hpp>Structure describing a DivingStation host.
Pass this structure to ConnectToHost() and Disconnect(). port is the OSC receive port on DivingStation. receivePort is the OSC receive port on the SDK. sendPort is the OSC send port on the SDK; when it is 0, the operating system selects an available port.
Public Attributes
| Return | Name | Description |
|---|---|---|
std::string | hostName | Arbitrary label used to distinguish hosts, for example "localhost". |
std::string | ipAddress | IP address, for example "127.0.0.1". |
uint32_t | port | OSC receive port on DivingStation. |
uint32_t | receivePort | OSC receive port on the SDK. |
uint32_t | sendPort | OSC send port on the SDK; 0 lets the OS select a port. |
hostName
std::string hostNameArbitrary label used to distinguish hosts, for example "localhost".
ipAddress
std::string ipAddressIP address, for example "127.0.0.1".
port
uint32_t port = 25791OSC receive port on DivingStation.
receivePort
uint32_t receivePort = 25788OSC receive port on the SDK.
sendPort
uint32_t sendPort = 0OSC send port on the SDK; 0 lets the OS select a port.
Vec3
#include <contactglove/ContactGloveSDKv2.hpp>Three-dimensional vector.
Public Attributes
x
float x = 0.0fX component.
y
float y = 0.0fY component.
z
float z = 0.0fZ component.
Quaternion
#include <contactglove/ContactGloveSDKv2.hpp>Quaternion representing rotation.
Public Attributes
w
float w = 1.0fScalar component.
x
float x = 0.0fX component.
y
float y = 0.0fY component.
z
float z = 0.0fZ component.
Transform
#include <contactglove/ContactGloveSDKv2.hpp>Transform combining position and rotation.
Used as each element of SkeletonData::transforms.
Public Attributes
position
Vec3 positionPosition.
rotation
Quaternion rotationRotation.
ControllerData
#include <contactglove/ContactGloveSDKv2.hpp>Structure holding controller input states.
Public Attributes
| Return | Name | Description |
|---|---|---|
std::string | id | Glove ID. |
bool | isLeft | Whether this is the left hand. |
ButtonStatus | aButton | A button state. |
ButtonStatus | bButton | B button state. |
ButtonStatus | sysButton | System button state. |
ButtonStatus | triggerButton | Trigger button state. |
ButtonStatus | joystickButton | Joystick button state. |
ButtonStatus | trackpadButton | Trackpad touch state. |
float | trigger | Trigger value (0.0 to 1.0). |
float | gripValue | Grip value (0.0 to 1.0). |
float | gripForce | Grip force (0.0 to 1.0). |
float | joystickX | Joystick X-axis value (-1.0 to 1.0). |
float | joystickY | Joystick Y-axis value (-1.0 to 1.0). |
float | trackpadX | Trackpad X-axis value (-1.0 to 1.0). |
float | trackpadY | Trackpad Y-axis value (-1.0 to 1.0). |
id
std::string idGlove ID.
isLeft
bool isLeft = falseWhether this is the left hand.
aButton
ButtonStatus aButton = ButtonStatus::UnpressedA button state.
bButton
ButtonStatus bButton = ButtonStatus::UnpressedB button state.
sysButton
ButtonStatus sysButton = ButtonStatus::UnpressedSystem button state.
triggerButton
ButtonStatus triggerButton = ButtonStatus::UnpressedTrigger button state.
joystickButton
ButtonStatus joystickButton = ButtonStatus::UnpressedJoystick button state.
trackpadButton
ButtonStatus trackpadButton = ButtonStatus::UnpressedTrackpad touch state.
trigger
float trigger = 0.0fTrigger value (0.0 to 1.0).
gripValue
float gripValue = 0.0fGrip value (0.0 to 1.0).
gripForce
float gripForce = 0.0fGrip force (0.0 to 1.0).
joystickX
float joystickX = 0.0fJoystick X-axis value (-1.0 to 1.0).
joystickY
float joystickY = 0.0fJoystick Y-axis value (-1.0 to 1.0).
trackpadX
float trackpadX = 0.0fTrackpad X-axis value (-1.0 to 1.0).
trackpadY
float trackpadY = 0.0fTrackpad Y-axis value (-1.0 to 1.0).
ErgonomicsData
#include <contactglove/ContactGloveSDKv2.hpp>Structure holding finger opening and bending angle data.
data has ERGONOMICS_DATA_COUNT elements for one hand. Values are in degrees. See ErgonomicsDataType for the meaning of each index.
Public Attributes
| Return | Name | Description |
|---|---|---|
std::string | id | Glove ID. |
bool | isLeft | Whether this is the left hand. |
Timestamp | generatedAt | Frame generation time (Unix time in milliseconds). |
TrackingState | trackingState | Tracking state of IK-derived data. |
std::array< float, ERGONOMICS_DATA_COUNT > | data | Opening and bending angle values per joint (20 elements for one hand, in degrees). |
id
std::string idGlove ID.
isLeft
bool isLeft = falseWhether this is the left hand.
generatedAt
Timestamp generatedAt = 0Frame generation time (Unix time in milliseconds).
trackingState
TrackingState trackingState = TrackingState::TrackedTracking state of IK-derived data.
data
std::array< float, ERGONOMICS_DATA_COUNT > data {}Opening and bending angle values per joint (20 elements for one hand, in degrees).
SkeletonData
#include <contactglove/ContactGloveSDKv2.hpp>Structure holding hand skeleton data (joint positions and rotations).
transforms has SKELETON_DATA_COUNT elements for one hand. See SkeletonDataType for the meaning of each index. Positions are in meters in a right-handed hand-model coordinate system rooted at the wrist. +X points from the fingertips toward the wrist, +Y from the palm toward the back of the hand, and +Z from little finger to thumb on the right hand and from thumb to little finger on the left hand. Rotations are local quaternions relative to the parent joint; wrist and fingertip rotations are identity placeholders, not measured rotations. These conventions apply to skeleton transforms; raw sensor rotations instead represent orientations in hand-model space.
Public Attributes
| Return | Name | Description |
|---|---|---|
std::string | id | Glove ID. |
std::string | profileUuid | Stable UUID of the retarget profile. |
bool | isLeft | Whether this is the left hand. |
Timestamp | generatedAt | Frame generation time (Unix time in milliseconds). |
TrackingState | trackingState | Tracking state of retarget IK. |
std::array< Transform, SKELETON_DATA_COUNT > | transforms | Position and rotation per node (25 elements). |
id
std::string idGlove ID.
profileUuid
std::string profileUuidStable UUID of the retarget profile.
isLeft
bool isLeft = falseWhether this is the left hand.
generatedAt
Timestamp generatedAt = 0Frame generation time (Unix time in milliseconds).
trackingState
TrackingState trackingState = TrackingState::TrackedTracking state of retarget IK.
transforms
std::array< Transform, SKELETON_DATA_COUNT > transforms {}Position and rotation per node (25 elements).
RawSkeletonData
#include <contactglove/ContactGloveSDKv2.hpp>Hand skeleton data before retargeting.
Public Attributes
| Return | Name | Description |
|---|---|---|
std::string | id | |
bool | isLeft | |
Timestamp | generatedAt | |
TrackingState | trackingState | |
std::array< Transform, SKELETON_DATA_COUNT > | transforms |
id
std::string idisLeft
bool isLeft = falsegeneratedAt
Timestamp generatedAt = 0trackingState
TrackingState trackingState = TrackingState::Trackedtransforms
std::array< Transform, SKELETON_DATA_COUNT > transforms {}RetargetProfileInfo
#include <contactglove/ContactGloveSDKv2.hpp>Response containing retarget profile information.
Public Attributes
| Return | Name | Description |
|---|---|---|
int32_t | requestId | |
std::string | profileUuid | |
int32_t | status | |
std::string | name | |
std::string | description |
requestId
int32_t requestId = 0profileUuid
std::string profileUuidstatus
int32_t status = 0name
std::string namedescription
std::string descriptionRawSensorTransformsData
#include <contactglove/ContactGloveSDKv2.hpp>Structure holding raw sensor transform data for one hand.
Corresponds to data received at OSC address /DS2/HC/RawSensorTransforms. Each transform is expressed in the same right-handed model-rooted space as /DS2/HC/HandSkeleton. Its position is the sensor center relative to the wrist, and its rotation is the orientation from the sensor local frame to model-rooted space. transforms contains RAW_SENSOR_TRANSFORM_COUNT elements in thumb, index, middle, ring, and little finger order.
Public Attributes
| Return | Name | Description |
|---|---|---|
std::string | id | Glove ID. |
bool | isLeft | Whether this is the left hand. |
Timestamp | generatedAt | Frame generation time (Unix time in milliseconds). |
std::array< Transform, RAW_SENSOR_TRANSFORM_COUNT > | transforms | Position and rotation per sensor (five elements for one hand). |
id
std::string idGlove ID.
isLeft
bool isLeft = falseWhether this is the left hand.
generatedAt
Timestamp generatedAt = 0Frame generation time (Unix time in milliseconds).
transforms
std::array< Transform, RAW_SENSOR_TRANSFORM_COUNT > transforms {}Position and rotation per sensor (five elements for one hand).
Generated by Moxygen