Low-Level C# SDK
v1.3.0
|
Welcome to the Weart Low-Level C# SDK documentation.
The SDK allows to connect to the Weart middleware and perform various actions with the TouchDIVER devices:
The minimum setup to use the weart SDK consists of:
The SDK can be downloaded as a zip file containing all the necessary files. To use it in your C# project, unzip it and move the files in a folder inside your project. Then, add the sdk files in your project. In Visual Studio, this can be done by including the sdk directory into the project (Right Click on Solution -> Add -> Existing Directory).
To start using the SDK in your project, start the Middleware application and connect a TouchDIVER device to it.
Import the main namespaces:
Create the WeArtClient and start the communication with the middleware:
As seen in the previous section, to start the middleware operations, call the Start() method.
To stop the middleware, call the Stop() method.
After starting the communication with the middleware, it's now possible to calibrate the TouchDIVER devices. The calibration allows to set the initial offsets of each thimble relative to the control unit position, in order to improve the finger tracking output.
The SDK client allows to add callbacks to monitor the calibration procedure status and result. For example, to start the calibration and print "Success" or "Failed":
The TouchDIVER allows to perform haptic feedback on the user's finger through its thimbles. Every thimble can apply a certain amount of pressure, temperature and vibration based on the processed object and texture.
A WeArtHapticObject is the basic object used to apply haptic feedback. To create one, use the following code:
The attirbutes handSideFlag and actuationPointFlag accept multiple values. The next example presents a single haptic object that, when applied a WeArtEffect, will affect both hands and all fingers.
The SDK contains a basic TouchEffect class to apply effects to the haptic device. The TouchEffect class contains the effects without any processing. For different use cases (e.g. values not directly set, but computed from other parameters), create a different effect class by implementing the IWeArtEffect interface.
Create the object on which the temperature, force and texture values will be applied:
It's possible to add a new effect to an haptic object, or to update an existing one.
In the example below, the effect created in the previous section is updated with a new temperature, force and texture. It is then added to the haptic object if not already present (if the effect is already applied to the thimble, it will update it automatically through the OnUpdate event).
If an effect is not needed anymore, it can be removed from the haptic object with the RemoveEffect method.
After starting the middleware and performing the device calibration, it's possible to receive tracking data related to the TouchDIVER thimbles.
To read these values, create and set a thimble tracker object for monitoring the closure/abduction value of a given finger:
Once this object is created, it will start receiving the tracking values. To access the closure and abduction values, simply use the getters provided by the thimble tracking object.
The closure value ranges from 0 (opened) to 1 (closed).
The abduction value ranges from 0 (finger near the hand's central axis) to 1 (finger far from the hand central axis).
It's possible to receive the raw data from the sensors on each thimble (and the control unit), in addition to the tracking data. Each sensor has:
To read these values, create a WeArtTrackingRawDataObject and add it to the client.
Once this object is added to the client, it will listen for raw data messages. To start receiving raw data from the middleware, call the WeArtClient.StartRawData() method. To stop receiving raw data, call the WeArtClient.StopRawData() method.
To get the sensors data, get the latest sample (SensorData) from the WeArtRawSensorsDataTrackingObject object. The sample contains the accelerometer, gyroscope and time of flight data, in addition to the timestamp of its sampling (generated by the middleware and represented as a DateTime value).
In addition to getting the latest sample by polling the tracking object, it's possible to add a callback called whenever a new sensor data sample is received from the TouchDIVER.
It's possible to receive the raw data from the sensors on each thimble (and the control unit), instead of the tracking data when this function is activated on the Middleware. Each sensor has:
To read these values, create a WeArtAnalogSensorRawDataObject object and add it to the client.
Once this object is added to the client, it will listen for raw data messages as soon the Middleware is on start.
To get the sensors data, get the latest sample (WeArtAnalogSensorData) from the AnalogSensorRawData object. The sample contains the accelerometer, gyroscope and time of flight data, in addition to the timestamp of its sampling (generated by the middleware and represented as milliseconds in unix epoch time).
The SDK allows to track and receives updates about the middleware and the connected devices status.
In particular, the information is available through a callback in the WeArtClient object
The middleware status callback will receive the MiddlewareStatusUpdate object, which includes:
The MiddlewareListener object allows to get the middleware status, which includes the latest status code sent by the middleware while performing its operations.
The current status codes (along with their description) are:
Status Code | Description | |
---|---|---|
0 | OK | Ok |
100 | START_GENERIC_ERROR | Can't start generic error: Stopping |
101 | CONNECT_THIMBLE | Unable to start, connect at least one thimble and retry |
102 | WRONG_THIMBLES | Unable to start, connect the right thimbles matched to the bracelet and retry |
103 | BATTERY_TOO_LOW | Battery is too low, cannot start |
104 | FIRMWARE_COMPATIBILITY | Can't start while the devices are connected to the power supply |
105 | SET_IMU_SAMPLE_RATE_ERROR | Error while setting IMU Sample Rate! Device Disconnected! |
106 | RUNNING_SENSOR_ON_MASK | Inconsistency on Analog Sensors raw data! Please try again or Restart your device/s! |
107 | RUNNING_DEVICE_CHARGING | Can't start while the devices are connected to the power supply |
200 | CONSECUTIVE_TRACKING_ERRORS | Too many consecutive running sensor errors, stopping session |
201 | DONGLE_DISCONNECT_RUNNING | BLE Dongle disconnected while running, stopping session |
202 | TD_DISCONNECT_RUNNING | TouchDIVER disconnected while running, stopping session |
203 | DONGLE_CONNECTION_ERROR | Error on Dongle during connection phase! |
300 | STOP_GENERIC_ERROR | Generic error occurred while stopping session |