# DivingStationProtocol (v1)
# Supported Software
- DivingStation v1.5.6 or later
# How to Use
DivingStationProtocol uses OSC (Open Sound Control) for communication. Select the OSC library that suits your desired language or environment.
First, ensure that DivingStation is running and that the device is connected.
Next, connect to DivingStation. Send the following connection request protocol to DivingStation (Port number: 25790).
- Example: If the client's receiving port number is 25788
/DS/HC/Connect 25788
(/DS/HC/Connect represents the OSC address, and 25788 represents the argument.)
Upon successful connection, various data will be transmitted from DivingStation to port 25788.
When ending the communication, a disconnect request protocol will be sent.
/DS/HC/Disconnect 25788
If the disconnection is successful, data reception from DivingStation will stop.
From SDK version 1.1.0 for Unity onwards, it is implemented using the DivingStationProtocol. Please refer to this when implementing.
# Configuration
Each protocol included in DivingStationProtocol consists of a combination of OSC addresses and arguments.
The type of protocol is identified by the address.
Arguments are pairs of values of type float, int, or string. Fields starting with is_ take values of 0 (=False) or 1 (=True), representing boolean values.
# List of Protocols (Receiver Side)
# Device Information
This protocol retrieves information about all hand-tracking devices connected to DivingStation.
# Address
/DS/HC/Device
# Arguments
int version, (string id, int is_main, int device_type, string name, int color, float ping, int is_left_connected, int left_battery, float left_ping, int is_right_connected, int right_battery, float right_ping)*
* indicates that the previous set can repeat 0 or more times.
The argument length is 1 + 12n (where n is the number of connected devices).
Description of Arguments
| Argument Name | Type | Description |
|---|---|---|
| version | int | Protocol version (=1) |
| id | string | Device ID |
| is_main | int | Whether it is the main device |
| device_type | int | Type of device |
| name | string | Device name |
| color | int | Device LED color |
| ping | float | Communication delay with the dongle |
| is_left_connected | int | Whether the left-hand device is connected |
| left_battery | int | Left-hand device battery level |
| left_ping | float | Communication delay with the left-hand device |
| is_right_connected | int | Whether the right-hand device is connected |
| right_battery | int | Right-hand device battery level |
| right_ping | float | Communication delay with the right-hand device |
The main device refers to the device used in systems like SteamVR.
The values of device_type and corresponding device types are as follows:
| device_type | Device Type |
|---|---|
| 0 | ContactGlove |
| 1 | ContactSheet |
| 2 | ContactGlove2 |
The values of color and corresponding colors are as follows:
| color | Color |
|---|---|
| 0 | Magenta |
| 1 | Red |
| 2 | Orange |
| 3 | Yellow |
| 4 | Green |
| 5 | Cyan |
| 6 | Blue |
| 7 | Achromatic |
# Finger Bending and Tilt Values
This protocol retrieves the bending and tilt values of the fingers of the hand-tracking device.
# Address
/DS/HC/Hand
# Arguments
int version, string id, int is_left, float thumb_cmc, float thumb_mcp, float thumb_ip, float thumb_tilt, float index_mcp, float index_pip, float index_dip, float index_tilt, ...
The argument length is 23.
Description of Arguments
| Argument Name | Type | Description |
|---|---|---|
| version | int | Protocol version (=1) |
| id | string | Device ID |
| is_left | int | Whether it is the left hand or right hand |
| thumb_cmc | float | Bending value of the thumb's CMC joint |
| thumb_mcp | float | Bending value of the thumb's MCP joint |
| thumb_ip | float | Bending value of the thumb's IP joint |
| thumb_tilt | float | Tilt of the thumb |
| {finger_name}_mcp | float | Bending value of {finger_name}'s MCP joint |
| {finger_name}_pip | float | Bending value of {finger_name}'s PIP joint |
| {finger_name}_dip | float | Bending value of {finger_name}'s DIP joint |
| {finger_name}_tilt | float | Tilt of {finger_name} |
The joints are arranged in the order MCP, PIP, DIP from the base to the tip of the finger (for the thumb, CMC, MCP, IP).
The fingers are arranged in the order: thumb (thumb), index (index), middle (middle), ring (ring), little (little).
The bending values range from 0.0 to 1.0, where 0.0 represents the straight state, and 1.0 represents the bent state. Tilt is represented as the angle from the default state of 0°.
# Quaternion of Each Joint
This protocol retrieves the quaternion of each joint of the hand-tracking device.
# Address
/DS/HC/HandQuat
# Arguments
int version, string id, int is_left, float thumb_cmc_w, float thumb_cmc_x, float thumb_cmc_y, float thumb_cmc_z, ..., float index_mcp_w, ...
The argument length is 63.
Description of Arguments
| Argument Name | Type | Description |
|---|---|---|
| version | int | Protocol version (=1) |
| id | string | Device ID |
| is_left | int | Whether it is the left hand or right hand |
| {finger_name}_{joint_name}_w | float | Quaternion w component of {finger_name}'s {joint_name} |
| {finger_name}_{joint_name}_x | float | Quaternion x component of {finger_name}'s {joint_name} |
| {finger_name}_{joint_name}_y | float | Quaternion y component of {finger_name}'s {joint_name} |
| {finger_name}_{joint_name}_z | float | Quaternion z component of {finger_name}'s {joint_name} |
The fingers are arranged in the order: thumb (thumb), index (index), middle (middle), ring (ring), little (little).
The joints are ordered as follows: for the thumb, cmc (base), mcp (center), ip (tip); for the other fingers, mcp (base), pip (center), dip (tip).
# Wrist Rotation
This protocol retrieves the wrist rotation of the hand-tracking device.
# Address
/DS/HC/Wrist
# Arguments
int version, string id, int is_left, float w, float x, float y, float z
The argument length is 7.
Description of Arguments
| Argument Name | Type | Description |
|---|---|---|
| version | int | Protocol version (=1) |
| id | string | Device ID |
| is_left | int | Whether it is the left hand or right hand |
| w | float | Quaternion w component |
| x | float | Quaternion x component |
| y | float | Quaternion y component |
| z | float | Quaternion z component |
# Controller Input
This protocol retrieves the input information of the controller.
# Address
/DS/HC/Controller
# Arguments
int version, string id, int is_left, int a, int b, int sys, int trigger_button, int joystick_button, int trackpad_button, float trigger, float grip_value, float grip_force, float joystick_x, float joystick_y, float trackpad_x, float trackpad_y
The argument length is 16.
Description of Arguments
| Argument Name | Type | Description |
|---|---|---|
| version | int | Protocol version (=1) |
| id | string | Device ID |
| is_left | int | Whether it is the left hand or right hand |
| a | int | State of the A button |
| b | int | State of the B button |
| sys | int | State of the system button |
| trigger_button | int | State of the trigger button |
| joystick_button | int | State of the joystick button |
| trackpad_button | int | State of the trackpad touch |
| trigger | float | Value of the trigger |
| grip_value | float | Value of the grip |
| grip_force | float | Strength of the grip |
| joystick_x | float | X-axis value of the joystick |
| joystick_y | float | Y-axis value of the joystick |
| trackpad_x | float | X-axis value of the trackpad |
| trackpad_y | float | Y-axis value of the trackpad |
The values for button press states are as follows:
| Value | Description |
|---|---|
| 0 | Button not pressed |
| 1 | Button touched |
| 2 | Button pressed |
# List of Protocols (Sender Side)
# Connection Request
This protocol sends a request to connect to DivingStation.
About Ports
The client’s receiving port number can be freely set using this protocol.
Please note that the DivingStation’s receiving port (25790) cannot be changed.
# Address
/DS/HC/Connect
# Arguments
int port_recv
The argument length is 1.
Description of Arguments
| Argument Name | Type | Description |
|---|---|---|
| port_recv | int | Receiving port number |
# Disconnection Request
This protocol sends a request to disconnect from DivingStation.
# Address
/DS/HC/Disconnect
# Arguments
int port_recv
The argument length is 1.
Description of Arguments
| Argument Name | Type | Description |
|---|---|---|
| port_recv | int | Receiving port number |
# Vibration
This protocol generates vibration for devices with a vibration module.
# Address
/DS/HC/{id}/Haptics/Body
Specify the device ID in {id}. The device ID can be obtained through the device information protocol.
# Arguments
int version, int is_left, float frequency, float amplitude, float duration
The argument length is 5.
Description of Arguments
| Argument Name | Type | Description |
|---|---|---|
| version | int | Protocol version (=1) |
| is_left | int | Whether it is the left hand or right hand |
| frequency | float | Vibration frequency |
| amplitude | float | Vibration amplitude |
| duration | float | Duration of vibration (in seconds) |
amplitude is specified in the range 0.0 to 1.0.