SkineticSDK

This class is used as the main API interface.

#include <Skinetic.h>

Public Functions

	Name
std::string	serialNumberToString(uint32_t serialNumber) Convert Skinetic serial number to a formatted string.
std::string	getSDKVersion() Get SDK version as a string.
int	setLogCallback(ski_log_callback_t callback) Set the logging callback function. It should be set before initialisation of the SDK.
	SkineticSDK(const char * logFileName ="") Instantiate a new Skinetic SDK.
	~SkineticSDK() SkineticSDK destructor.
ExperimentalSkineticSDK	ExperimentalAPI() Get the handle to the experimental API of this Skinetic instance.
int	scanDevices(ski_output_t outputType) Initialize a scanning routine to find all available Skinetic device.
int	scanStatus() Check the status of the asynchronous scanning routine.
ski_device_info_t *	getFirstScannedDevice() Get linked list of all the Skinetic devices found during the scan which match the specified output type.
int	connect(ski_output_t outputType, uint32_t serialNumber) Initialize an asynchronous connection to a Skinetic device using the selected type of connection.
int	disconnect() Disconnect the current Skinetic device.
ski_connection_state_t	connectionStatus() Check the current status of the connection.
int	setConnectionCallback(ski_ConnectionCallback callback, void userData) Set a callback function fired upon connection changes.
uint32_t	getSkineticSerialNumber() Get the connected device's serial number.
std::string	getSkineticSerialNumberAsString() Get the connected device's serial number as string.
std::string	getSkineticVersion() Get the connected device's version as a string.
ski_device_type_t	getSkineticType() Get the connected device's type.
int	getGlobalIntensityBoost() Get the amount of global intensity boost.
int	setGlobalIntensityBoost(int globalBoost) Set the amount of global intensity boost.
int	loadPatternFromJSON(const char * 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 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, ski_effect_properties_t effectProperties =ski_effect_properties_t()) 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.
ski_effect_state_t	effectState(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.

Friends

	Name
class	ExperimentalSkineticSDK

Public Functions Documentation

function serialNumberToString

static  std::string serialNumberToString(
    uint32_t serialNumber
)

Convert Skinetic serial number to a formatted string.

Parameters:

• serialNumber Serial number to convert.

Return: String representation of the serial number.

function getSDKVersion

static  std::string getSDKVersion()

Get SDK version as a string.

Return: the version string.

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

function setLogCallback

static  int setLogCallback(
    ski_log_callback_t callback
)

Set the logging callback function. It should be set before initialisation of the SDK.

This callback will be called every time log message is produced by the SDK.

The callback function takes the following arguments:

• ski_log_level_t level: the level of the log message
• const char* scope: string giving information about the SDK scope that send the log
• const char* msg: string containing the log message Set the callback to nullptr to disable logging. callbackthe callback function.

0 on success, an Error otherwise.

function SkineticSDK

explicit  SkineticSDK(
    const char * logFileName =""
)

Instantiate a new Skinetic SDK.

Parameters:

• logFileName Name of the file to log in. Leave blank to use the default SkineticSDK.log file. File path can be absolute or relative to the directory containing the library.

function ~SkineticSDK

 ~SkineticSDK()

SkineticSDK destructor.

function ExperimentalAPI

 ExperimentalSkineticSDK ExperimentalAPI()

Get the handle to the experimental API of this Skinetic instance.

Return: a handle to the experimental API.

function scanDevices

 int scanDevices(
    ski_output_t outputType
)

Initialize a scanning routine to find all available Skinetic device.

Parameters:

• outputType type of connection to introspect.

Return: 0 on success, an Error otherwise.

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

function scanStatus

 int scanStatus()

Check the status of the asynchronous scanning routine.

The method returns:

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

function getFirstScannedDevice

 ski_device_info_t * getFirstScannedDevice()

Get linked list of all the Skinetic devices found during the scan which match the specified output type.

Return: a pointer to the first structure in the linked list, nullptr otherwise.

The ski_device_info_t.next field of the structure points to the next found device if any. It is equal to nullptr when the last device is reached.

The returned pointer should neither be modified nor memorized but have to be used immediately to retrieve the devices list. Its life span is only guarantied until scanDevices() is called again.

function connect

 int connect(
    ski_output_t outputType,
    uint32_t serialNumber
)

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

Parameters:

• outputType type of connection
• 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

 ski_connection_state_t connectionStatus()

Check the current status of the connection.

Return: the current status of the connection.

The asynchronous connection routine is terminated on failure.

function setConnectionCallback

 int setConnectionCallback(
    ski_ConnectionCallback * callback,
    void * userData
)

Set a callback function fired upon connection changes.

Parameters:

• callback client's callback.
• userData client's supplied pointer.

Return: 0 on success, an Error otherwise.

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 getSkineticSerialNumber

 uint32_t getSkineticSerialNumber()

Get the connected device's serial number.

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

function getSkineticSerialNumberAsString

 std::string getSkineticSerialNumberAsString()

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 getSkineticVersion

 std::string getSkineticVersion()

Get the connected device's version as a string.

Return: the version string if a Skinetic device is connected, "noDeviceConnected" otherwise.

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

function getSkineticType

 ski_device_type_t getSkineticType()

Get the connected device's type.

Return: the type of the connected Skinetic device if it is connected, ski_device_type_t::eUnknown otherwise.

function getGlobalIntensityBoost

 int getGlobalIntensityBoost()

Get the amount of global intensity boost.

Return: the global intensity boost 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 setGlobalIntensityBoost

 int setGlobalIntensityBoost(
    int globalBoost
)

Set the amount of global intensity boost.

Parameters:

• globalBoost global boost value.

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(
    const char * 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 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 in [0; infinity[ 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,
    ski_effect_properties_t effectProperties =ski_effect_properties_t()
)

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. Transformation and boolean operations are not applicable to actuator-based patterns.

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 fadeout to prevent abrupt transition. If "time" is set to 0, no fadeout is applied and the effect is stopped as soon as possible. Once an effect is stopped, its instance is destroyed and its effectID invalidated.

function effectState

 ski_effect_state_t effectState(
    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 ski_effect_state_t::eStop 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.

Friends

friend ExperimentalSkineticSDK

friend class ExperimentalSkineticSDK(
    ExperimentalSkineticSDK 
);

---

Updated on 2024-06-05 at 16:05:52 +0000