Skinetic::SkineticSDK

Public Classes

	Name
struct	DeviceInfo Struct representing device information.
struct	EffectProperties Haptic Structure to describe how effect instances reproduce a pattern with variations.
struct	ExpAudioSettings Experimental - Struct containing settings for an audio connection.

Public Types

	Name
enum class	OutputType { E_AUTODETECT = 0, E_BLUETOOTH = 1, E_USB = 2, E_WIFI = 3} Type of connection to Skinetic.
enum class	DeviceType { E_UNKNOWN = ~0x0, E_SKINETICVEST = 0x01100101, E_HSDMK2 = 0x0122FFFF} Type of Skinetic device.
enum class	ConnectionState { E_RECONNECTING = 3, E_DISCONNECTING = 2, E_CONNECTING = 1, E_CONNECTED = 0, E_DISCONNECTED = -1} Connection state.
enum class	EffectState { E_PLAY = 2, E_MUTE = 1, E_INITIALIZED = 0, E_STOP = -1} Effect's state.
enum class	LogLevel { E_TRACE = 0, E_DEBUG = 1, E_INFO = 2, E_WARN = 3, E_ERR = 4} Log levels definitions.
enum class	ExpAudioPreset { E_CUSTOMDEVICE = 0, E_SKINETIC = 1, E_HSDMKI = 2, E_HSDMKII = 3, E_HSD0 = 4} Experimental - Preset of audio devices.

Public Functions

	Name
string	getSDKError(int error) Describe the error cause.
void	ConnectionClassCallback(ConnectionState status, int error, UInt32 serialNumber, IntPtr userData)
void	LogCallback(LogLevel level, string scope, string message)
String	GetDeviceSerialNumberAsString(UInt32 serialNumber) Convert Skinetic serial number to a formatted string.
int	SetLogCallback(LogCallbackDelegate callback)
void	InitInstance() Initialize the Skinetic device instance.
void	DeinitInstance() Deinitialize the Skinetic device instance.
int	ScanDevices(OutputType output) Initialize a scanning routine to find all available Skinetic device.
int	ScanStatus() Check the status of the asynchronous scanning routine.
List< DeviceInfo >	GetScannedDevices() This function returns a list of all DeviceInfo of each Skinetic devices found during the scan which match the specified output type.
int	Connect(OutputType output, System.UInt32 serialNumber) Initialize an asynchronous connection to a Skinetic device using the selected type of connection.
int	Disconnect() Disconnect the current Skinetic device.
ConnectionState	ConnectionStatus() Check the current status of the connection. The asynchronous connection routine is terminated on failure.
delegate void	ConnectionCallbackDelegate(ConnectionState state, int error, System.UInt32 serialNumber) Delegate of the connection callback.
delegate void	LogCallbackDelegate(LogLevel level, string scope, string message) Delegate of the log callback.
int	SetConnectionCallback(ConnectionCallbackDelegate callback) Set a callback function fired upon connection changes.
String	GetSDKVersion() Get SDK version as a string.
String	GetDeviceVersion() Get the connected device's version as a string.
System.UInt32	GetDeviceSerialNumber() Get the connected device's serial number.
String	GetDeviceSerialNumberAsString() Get the connected device's serial number as string.
DeviceType	GetDeviceType() Get the connected device's type.
int	GetGlobalIntensityBoost() Get the amount of effect's intensity boost.
int	SetGlobalIntensityBoost(int globalBoost) Set the amount of global intensity boost.
int	LoadPatternFromJSON(String json) Load a pattern from a valid json into a local haptic asset and return the corresponding patternID.
int	UnloadPattern(int patternID) Unload the pattern from of the corresponding patternID.
int	GetPatternIntensityBoost(int patternID) Get the pattern boost value which serves as a default value for the playing effect.
int	SetAccumulationWindowToPattern(int mainPatternID, int fallbackPatternID, float timeWindow, int maxAccumulation) Enable the effect accumulation strategy on a targeted pattern.
int	EraseAccumulationWindowToPattern(int mainPatternID) Disable the effect accumulation strategy on a specific pattern if any set.
int	PlayEffect(int patternID, EffectProperties effectProperties) Play an haptic effect based on a loaded pattern and return the effectID of this instance.
int	StopEffect(int effectID, float time) Stop the effect instance identified by its effectID.
EffectState	GetEffectState(int effectID) Get the current state of an effect.
int	PauseAll() Pause all haptic effect that are currently playing.
int	ResumeAll() Resume the paused haptic effects.
int	StopAll() Stop all playing haptic effect.
string[]	Exp_GetOutputDevicesNames() Get names of available audio output devices.
string[]	Exp_GetOutputDeviceAPIs(string outputName) Get available APIs for a given output device identified by name.
int	Exp_GetOutputDeviceInfo(string outputName, string apiName, ref int maxChannels, ref float defaultLowLatency, ref float defaultHighLatency) Get settings extremum values of the output device identified by name and API.
int[]	Exp_GetSupportedStandardSampleRates(string outputName, string apiName) Get all supported standard sample rates of the output device identified by name and API.
int	Exp_connectAudio(ExpAudioPreset audioPreset, ExpAudioSettings audioSettings) Initialize an asynchronous connection to an audio device using the provided settings.

Public Types Documentation

enum OutputType

Enumerator	Value	Description
E_AUTODETECT	0	Try all available type of connection.
E_BLUETOOTH	1	Bluetooth connection.
E_USB	2	USB connection.
E_WIFI	3	Wifi connection.

Type of connection to Skinetic.

E_AUTODETECT will try all available type of connection in the following order:

• Bluetooth
• USB
• WIFI

enum DeviceType

Enumerator	Value	Description
E_UNKNOWN	~0x0	Type is Unknown or undefined.
E_SKINETICVEST	0x01100101	Skinetic Vest.
E_HSDMK2	0x0122FFFF	HSD mk.II development kit.

Type of Skinetic device.

enum ConnectionState

Enumerator	Value	Description
E_RECONNECTING	3	Device connection was broken, trying to reconnect.
E_DISCONNECTING	2	Device is disconnecting, releasing all resources.
E_CONNECTING	1	Connection to the device is being established, connection routine is active.
E_CONNECTED	0	Device is connected.
E_DISCONNECTED	-1	Device is disconnected.

Connection state.

enum EffectState

Enumerator	Value	Description
E_PLAY	2	Effect is playing.
E_MUTE	1	Effect is muted.
E_INITIALIZED	0	Effect is initialized and should play as soon as possible.
E_STOP	-1	Effect is stopped.

Effect's state.

enum LogLevel

Enumerator	Value	Description
E_TRACE	0
E_DEBUG	1
E_INFO	2
E_WARN	3
E_ERR	4

Log levels definitions.

enum ExpAudioPreset

Enumerator	Value	Description
E_CUSTOMDEVICE	0	Audio stream with a custom configuration.
E_SKINETIC	1	Autoconfiguration of the audioStream for the Skinetic device.
E_HSDMKI	2	Autoconfiguration of the audioStream for the HSD mk.I device.
E_HSDMKII	3	Autoconfiguration of the audioStream for the HSD mk.II device.
E_HSD0	4	Autoconfiguration of the audioStream for the HSD 0 device.

Experimental - Preset of audio devices.

E_CUSTOMDEVICE is to be used for a custom configuration.

Public Functions Documentation

function getSDKError

static string getSDKError(
    int error
)

Describe the error cause.

Parameters:

• error value

Return: Error message.

function ConnectionClassCallback

static void ConnectionClassCallback(
    ConnectionState status,
    int error,
    UInt32 serialNumber,
    IntPtr userData
)

function LogCallback

static void LogCallback(
    LogLevel level,
    string scope,
    string message
)

function GetDeviceSerialNumberAsString

static String GetDeviceSerialNumberAsString(
    UInt32 serialNumber
)

Convert Skinetic serial number to a formatted string.

Parameters:

• serialNumber serial number to convert

Return: string representation of the serial number

function SetLogCallback

static int SetLogCallback(
    LogCallbackDelegate callback
)

function InitInstance

void InitInstance()

Initialize the Skinetic device instance.

function DeinitInstance

void DeinitInstance()

Deinitialize the Skinetic device instance.

function ScanDevices

int ScanDevices(
    OutputType output
)

Initialize a scanning routine to find all available Skinetic device.

Parameters:

• output

Return: 0 on success, an Error code on failure.

The state of the routine can be obtain from ScanStatus(). Once completed, the result can be accessed using GetScannedDevices().

function ScanStatus

int ScanStatus()

Check the status of the asynchronous scanning routine.

Return: the current status or an error on failure.

The method returns:

• '1' if the scan is ongoing.
• '0' if the scan is completed.
• a negative error code if the connection failed. The asynchronous scan routine is terminated on failure. Once the scan is completed, the result can be obtain by calling GetScannedDevices().

function GetScannedDevices

List< DeviceInfo > GetScannedDevices()

This function returns a list of all DeviceInfo of each Skinetic devices found during the scan which match the specified output type.

Return: a list of DeviceInfo, empty if no match or an error occurs.

function Connect

int Connect(
    OutputType output,
    System.UInt32 serialNumber
)

Initialize an asynchronous connection to a Skinetic device using the selected type of connection.

Parameters:

• output output type
• serialNumber serial number of the Skinetic device to connect to

Return: 0 on success, an error otherwise.

The state of the routine can be obtain from ConnectionStatus(). If the serial number is set to '0', the connection will be performed on the first found device.

function Disconnect

int Disconnect()

Disconnect the current Skinetic device.

Return: 0 on success, an error otherwise.

The disconnection is effective once all resources are released. The state of the routine can be obtain from ConnectionStatus().

function ConnectionStatus

ConnectionState ConnectionStatus()

Check the current status of the connection. The asynchronous connection routine is terminated on failure.

Return: the current status of the connection.

function ConnectionCallbackDelegate

delegate void ConnectionCallbackDelegate(
    ConnectionState state,
    int error,
    System.UInt32 serialNumber
)

Delegate of the connection callback.

Parameters:

• state status of the connection
• error of error occurring
• serialNumber serial number of the device firing the callback

Functions of type ski_ConnectionCallback are implemented by clients. The callback is fired at the end of the connection routine whether it succeeds or failed. It is also fired if a connection issue arise.

function LogCallbackDelegate

delegate void LogCallbackDelegate(
    LogLevel level,
    string scope,
    string message
)

Delegate of the log callback.

Parameters:

• level level of the log message
• scope string giving information about the SDK scope that send the log
• message string containing the log message

Functions of type ski_LogCallback are implemented by clients. The callback is fired for each logging entry.

function SetConnectionCallback

int SetConnectionCallback(
    ConnectionCallbackDelegate callback
)

Set a callback function fired upon connection changes.

Parameters:

• callback client's callback

Return: 0 on success, an Error code on failure.

Functions of type ski_ConnectionCallback are implemented by clients.

The callback is fired at the end of the connection routine whether it succeed or failed. It is also fired if a connection issue arise. The callback is not fired if none was passed to setConnectionCallback().

'userData' is a client supplied pointer which is passed back when the callback function is called.It could for example, contain a pointer to an class instance that will process the callback.

function GetSDKVersion

String GetSDKVersion()

Get SDK version as a string.

Return: The version string.

The format of the string is: major.minor.revision

function GetDeviceVersion

String GetDeviceVersion()

Get the connected device's version as a string.

Return: The version string if a Skinetic device is connected, an error message otherwise.

The format of the string is: major.minor.revision

function GetDeviceSerialNumber

System.UInt32 GetDeviceSerialNumber()

Get the connected device's serial number.

Return: The serial number of the connected Skinetic device if any, 0xFFFFFFFF otherwise.

function GetDeviceSerialNumberAsString

String GetDeviceSerialNumberAsString()

Get the connected device's serial number as string.

Return: The serial number as string of the connected Skinetic device if any, "noDeviceConnected" otherwise.

function GetDeviceType

DeviceType GetDeviceType()

Get the connected device's type.

Return: The type of the connected Skinetic device if it is connected, an ERROR message otherwise.

function GetGlobalIntensityBoost

int GetGlobalIntensityBoost()

Get the amount of effect's intensity boost.

Return: The percentage of effect's intensity boost, an ERROR otherwise.

The boost increase the overall intensity of all haptic effects. However, the higher the boost activation is, the more the haptic effects are degraded. The global boost is meant to be set by the user as an application setting.

function SetGlobalIntensityBoost

int SetGlobalIntensityBoost(
    int globalBoost
)

Set the amount of global intensity boost.

Parameters:

• globalBoost boostPercent percentage of the boost.

Return: 0 on success, an ERROR otherwise.

The boost increase the overall intensity of all haptic effects. However, the higher the boost activation is, the more the haptic effects are degraded. The global boost is meant to be set by the user as an application setting.

function LoadPatternFromJSON

int LoadPatternFromJSON(
    String json
)

Load a pattern from a valid json into a local haptic asset and return the corresponding patternID.

Parameters:

• json describing the pattern

Return: Positive patternID on success, an error otherwise.

The patternID is a positive index.

function UnloadPattern

int UnloadPattern(
    int patternID
)

Unload the pattern from of the corresponding patternID.

Parameters:

• patternID the patternID of the pattern to unload.

Return: 0 on success, an error otherwise.

function GetPatternIntensityBoost

int GetPatternIntensityBoost(
    int patternID
)

Get the pattern boost value which serves as a default value for the playing effect.

Parameters:

• patternID the ID of the targeted pattern.

Return: the pattern intensity boost of the pattern if it exists, 0 otherwise.

The value is ranged in [-100; 100]. If the pattern ID is invalid, zero is still returned.

function SetAccumulationWindowToPattern

int SetAccumulationWindowToPattern(
    int mainPatternID,
    int fallbackPatternID,
    float timeWindow,
    int maxAccumulation
)

Enable the effect accumulation strategy on a targeted pattern.

Parameters:

• mainPatternID the patternID of the main pattern.
• fallbackPatternID the patternID of the fallback pattern
• timeWindow the time window during which the accumulation should happen.
• maxAccumulation max number of extra accumulated effect instances.

Return: 0 on success, an ERROR otherwise.

Whenever an effect is triggered on the main pattern, the fallback one is used instead, if the main is already playing. More details can be found the additional documentation. For the maxAccumulation, setting to 0 removes the limit.

If a new call to this function is done for a specific pattern, the previous association is overridden.

function EraseAccumulationWindowToPattern

int EraseAccumulationWindowToPattern(
    int mainPatternID
)

Disable the effect accumulation strategy on a specific pattern if any set.

Parameters:

• mainPatternID the patternID of the main pattern.

Return: 0 on success, an ERROR otherwise.

function PlayEffect

int PlayEffect(
    int patternID,
    EffectProperties effectProperties
)

Play an haptic effect based on a loaded pattern and return the effectID of this instance.

Parameters:

• patternID pattern used by the effect instance.
• effectProperties struct to specialized the effect.

Return: Positive effectID on success, an error otherwise.

The instance index is positive. Each call to playEffect() using the same patternID generates a new haptic effect instance totally uncorrelated to the previous ones. The instance is destroyed once it stops playing.

The haptic effect instance reproduces the pattern with variations describes in the structure ski_effect_properties_t.More information on these parameters and how to used them can be found in the structure's description.

If the pattern is unloaded, the haptic effect is not interrupted.

function StopEffect

int StopEffect(
    int effectID,
    float time
)

Stop the effect instance identified by its effectID.

Parameters:

• effectID index identifying the effect.
• time duration of the fadeout in second.

Return: 0 on success, an error otherwise.

The effect is stop in "time" seconds with a fade out to prevent abrupt transition. If time is set to 0, no fadeout are applied and the effect is stopped as soon as possible. Once an effect is stopped, it is instance is destroyed and its effectID invalidated.

function GetEffectState

EffectState GetEffectState(
    int effectID
)

Get the current state of an effect.

Parameters:

• effectID index identifying the effect.

Return: the current state of the effect.

If the effectID is invalid, the 'stop' state will be return.

function PauseAll

int PauseAll()

Pause all haptic effect that are currently playing.

Return: 0 on success, an error otherwise.

function ResumeAll

int ResumeAll()

Resume the paused haptic effects.

Return: 0 on success, an error otherwise.

function StopAll

int StopAll()

Stop all playing haptic effect.

Return: 0 on success, an error otherwise.

function Exp_GetOutputDevicesNames

static string[] Exp_GetOutputDevicesNames()

Get names of available audio output devices.

Return: array of device names

If no device is available, the array will contain "noDevice". This allows to select which device to use if initializing the context with eCustomDevice.

function Exp_GetOutputDeviceAPIs

static string[] Exp_GetOutputDeviceAPIs(
    string outputName
)

Get available APIs for a given output device identified by name.

Parameters:

• outputName name of the output

Return: array of api names

If no API is available, the array will contain "noAPI".

function Exp_GetOutputDeviceInfo

static int Exp_GetOutputDeviceInfo(
    string outputName,
    string apiName,
    ref int maxChannels,
    ref float defaultLowLatency,
    ref float defaultHighLatency
)

Get settings extremum values of the output device identified by name and API.

Parameters:

• outputName name of the output
• apiName name of the API
• maxChannels max number of channel
• defaultLowLatency minimum latency of the output device
• defaultHighLatency maximum latency of the output device

Return: 0 if the values have been set successfully, an Error otherwise

function Exp_GetSupportedStandardSampleRates

static int[] Exp_GetSupportedStandardSampleRates(
    string outputName,
    string apiName
)

Get all supported standard sample rates of the output device identified by name and API.

Parameters:

• outputName name of the output
• apiName name of the API

Return: array of available frame rates

If the outputName or the API are not valid, the array is filled with all standard sample rates.

function Exp_connectAudio

int Exp_connectAudio(
    ExpAudioPreset audioPreset,
    ExpAudioSettings audioSettings
)

Initialize an asynchronous connection to an audio device using the provided settings.

Parameters:

• audioPreset preset of audio device.
• audioSettings stream settings

Return: 0 on success, an error otherwise.

If audioPreset is set to anything else other than ExpAudioPreset::E_CUSTOMDEVICE, the provided settings are ignored and the ones corresponding to the preset are used instead.

---

Updated on 2024-05-23 at 10:02:49 +0000