com.actronika.skineticsdk.SkineticSDK

This class is used as the main API interface for Android project. More...

Public Classes

	Name
enum	CONNECTION_STATE Connection state.
enum	DEVICE_TYPE Type of Skinetic device.
enum	EFFECT_STATE Effect's state.
enum	ERROR Error codes returned by the functions of the library.
enum	OUTPUT_TYPE Type of connection to Skinetic.

Public Functions

	Name
String	serialNumberToString(long serialNumber) Convert Skinetic serial number to a formatted string.
int	setLogCallback(long callback) Set the logging C-like callback function.
	SkineticSDK(@NonNull Context context, @NonNull Activity activity) Constructor of the Skinetic instance.
void	close() Call this method to free the resources.
int	scanDevices(OUTPUT_TYPE outputType) Initialize a scanning routine to find all available Skinetic device.
int	scanStatus() Check the status of the asynchronous scanning routine.
ArrayList< DeviceInfo >	getScannedDevices() Get list of all the Skinetic devices found during the scan which match the specified output type.
int	connect(OUTPUT_TYPE output, long serialNumber) Initialize an asynchronous connection to a Skinetic device using the selected type of connection.
int	disconnect() Disconnect the current Skinetic device.
CONNECTION_STATE	connectionStatus() Check the current status of the connection.
int	setConnectionCallback(long callback, long userData) This function is for setting a C like callback, in case client is interfacing with language other than Java which can provide C like function pointer.
String	getSDKVersion() Get SDK version as a string.
String	getDeviceVersion() Get the connected device's version as a string.
long	getDeviceSerialNumber() Get the connected device's serial number.
String	getDeviceSerialNumberAsString() Get the connected device's serial number as String.
DEVICE_TYPE	getDeviceType() 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(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.
EFFECT_STATE	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.

Detailed Description

public class com.actronika.skineticsdk.SkineticSDK;

This class is used as the main API interface for Android project.

When adding the Skinetic SDK to your project, make sure that your gradle configuration follows these prerequisites:

• Add to gradle.build in the dependencies:
  • implementation 'androidx.appcompat:appcompat:1.5.0'
• Add to gradle.properties
  • android.useAndroidX=true
  • android.enableJetifier=true

Public Functions Documentation

function serialNumberToString

public static String serialNumberToString(
    long serialNumber
)

Convert Skinetic serial number to a formatted string.

Parameters:

• serialNumber Serial number to convert.

Return: String representation of the serial number.

function setLogCallback

public static int setLogCallback(
    long callback
)

Set the logging C-like 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

public SkineticSDK(
    @NonNull Context context,
    @NonNull Activity activity
)

Constructor of the Skinetic instance.

The Skinetic instance need to have access to a valid context and activity of your application for the communication protocol to work properly.

function close

public void close()

Call this method to free the resources.

function scanDevices

public int scanDevices(
    OUTPUT_TYPE outputType
)

Initialize a scanning routine to find all available Skinetic device.

Parameters:

• outputType type of connection to introspect.

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

public 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 connection failed. The asynchronous scan routine is terminated on failure. Once the scan is completed, the result can be obtain by calling getScannedDevices(). the current status or an error on failure.

function getScannedDevices

public ArrayList< DeviceInfo > getScannedDevices()

Get list of all the 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

public int connect(
    OUTPUT_TYPE output,
    long serialNumber
)

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

Parameters:

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

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

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

public 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

public CONNECTION_STATE 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

public int setConnectionCallback(
    long callback,
    long userData
)

This function is for setting a C like callback, in case client is interfacing with language other than Java which can provide C like function pointer.

Parameters:

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

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

The expected prototype of the callback is: void ski_ConnectionCallback(ski_connection_state_t newStatus, ski_error_t error, uint32_t serialNumber, void *userData) See the C/C++ documentation for further details.

Set a callback function fired upon connection changes. 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

public String getSDKVersion()

Get SDK version as a string.

Return: the version string.

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

function getDeviceVersion

public String getDeviceVersion()

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 getDeviceSerialNumber

public long getDeviceSerialNumber()

Get the connected device's serial number.

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

function getDeviceSerialNumberAsString

public String getDeviceSerialNumberAsString()

Get the connected device's serial number as String.

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

function getDeviceType

public DEVICE_TYPE getDeviceType()

Get the connected device's type.

Return: the type of the connected Skinetic device if it is connected, DEVICE_TYE.E_UNKNOWN otherwise.

function getGlobalIntensityBoost

public 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.

function setGlobalIntensityBoost

public 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.

function loadPatternFromJSON

public 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

public 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

public 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

public 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

public 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

public 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 EffectProperties object to specialized the effect.

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

public 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 are 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

public EFFECT_STATE 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 'stop' state will be return.

function pauseAll

public int pauseAll()

Pause all haptic effect that are currently playing.

Return: 0 on success, an ERROR otherwise.

function resumeAll

public int resumeAll()

Resume the paused haptic effects.

Return: 0 on success, an ERROR otherwise.

function stopAll

public int stopAll()

Stop all playing haptic effect.

Return: 0 on success, an ERROR otherwise.

---

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