User API Module definitions More...

#include "hapticLib.h"

Macros
#define	HL_SYSTEM_FILE

Functions
haptor_desc *	hl_configure (uint32_t pwmFreq, uint8_t samplesDelay, uint8_t numHaptors)
	API exposed to the user to setup the system.
pattern_desc *	hl_initPattern (pattern_name patternName, user_param *userParams)
	API exposed to the user to initialize a new pattern.
pattern_desc *	hl_addHaptor (haptor_desc newHaptor, pattern_desc pattern)
	API exposed to the user to add an haptor to a pattern.
uint8_t	hl_startPattern (pattern_desc *pattern)
	API exposed to the user to send Haptic Feedback.
uint8_t	hl_stopPattern (pattern_desc *pattern)
	API exposed to the user to force pattern execution stop.

Variables
pattern_initiator	patternMap [MAX_HAPTORS]
	Pattern Generators Functions Map.
system_desc	SystemDesc
	Global variable to describe the haptic system.

Detailed Description

User API Module definitions

This file is part of the User API Module of HapticLib.

The code inside this module is meant to be platform independent.

The functions defined in hapticLib.c are the only ones the library user should need to call for his haptic applications.

Note:: The only exception is the Delay() function which now reside in the Platform Specific Module.

See also:: Please refer to the Architecture page for a complete overview of HapticLib structure.; Please refer to the Developer Guide for the internals of HapticLib's Modules interactions.

Author:: Leonardo Guardati

Version:: 0.7

Date:: 2012

Definition in file hapticLib.c.

Macro Definition Documentation

#define HL_SYSTEM_FILE

Definition at line 47 of file hapticLib.c.

Function Documentation

pattern_desc* hl_addHaptor	(	haptor_desc *	newHaptor,
		pattern_desc *	pattern
	)

API exposed to the user to add an haptor to a pattern.

The user needs to call hl_addHaptor() to let an already initialized pattern know which haptors to activate with its logic.

If the haptor is good (and free) and the pattern is good, hl_addHaptor() will link the pattern to the haptor and, vice-versa. If the pattern has already haptors linked to it, the newHaptor will be added to the list formed by all the haptors already attached to the pattern.

Parameters:

[out]	newHaptor	This is the pointer to the haptor to be added to the list of attached haptors of the pattern.
[out]	pattern	This is the pointer to a `pattern_desc` returned by a precedent hl_initPattern() call.

Returns:: pattern_desc * hl_addHaptor() returns the same pointer passed as argument by the caller.

Return values:

NULL	If the reference is NULL, an error has occurred.

Note:

Returning the pattern_desc * of the pattern, it is possible to nest the calling sequence that lead to a single haptor pattern activation.

                hl_startPattern( hl_addHaptor( &myHaptors[2], hl_initPattern(Test,NULL) ) );

Definition at line 280 of file hapticLib.c.

haptor_desc* hl_configure	(	uint32_t	pwmFreq,
		uint8_t	samplesDelay,
		uint8_t	numHaptors
	)

API exposed to the user to setup the system.

Here the global SystemDesc variable is initialized. Then all the system peripheral get configured based on the high level informations passed by the user.

Parameters:

[in]	pwmFreq	This is a `uint32_t` used to specify the Frequency of the haptors control PWM signals. Expressed in Hz.
[in]	samplesDelay	This is a `uint8_t` used to specify the delay (in ms) between successive haptors control PWM signals updates.

Note:: Please refer to the Platform Specific Module implementations of Timers and PWM generations to be sure of the meaning of these parameters.

Parameters:

[in] numHaptors This is a uint8_t to specify the actual number of haptors the application will use.

Note:: It is an important feature to be able to specify a minor number of devices to use instead of the hardware defined MAX_HAPTORS. Doing so, not only the code will be faster and the memory footprint smaller (todo), but also the resources that drive the unused haptors will be available to the application for other uses. (todo)

Returns:: haptor_desc * A reference to the array of the configured haptor is returned to the application.

Return values:

NULL	If the reference is NULL, an error has occurred.

Todo:: Add input validation on pwm_freq and samples_delay passed parameters.

Definition at line 109 of file hapticLib.c.

pattern_desc* hl_initPattern	(	pattern_name	patternName,
		user_param *	userParams
	)

API exposed to the user to initialize a new pattern.

Calling hl_initPattern(), the system will check for available resources and then create the new pattern descriptor returning its reference to the application who called.

The pattern repository offer a wide selection of haptic feedback patterns.

The user must read the documentation of the patterns she wants to use, in order to know if and what kind of user parameters the pattern needs.

Parameters:

[in]	patternName	This is an integer value (encoded with the pattern_name enumeration) used to select the desired pattern.
[out]	userParams	This is a pointer to the user_param structure the application must allocate to store the parameters needed by the pattern.

Note:: user_param is a union type definition. With this type the compiler can enforce type checking at compile time to ensure a valid argument is passed. (earlier version of HapticLib used a void * to pass the user parameters).

Returns:: pattern_desc * A pointer to the pattern descriptor is returned to the application. The application will use this descriptor to make successive operations related to this pattern (like, adding haptors to it, starting it, stopping it).

Return values:

NULL	If the reference is NULL, an error has occurred.

Definition at line 209 of file hapticLib.c.

uint8_t hl_startPattern ( pattern_desc * pattern )

API exposed to the user to send Haptic Feedback.

hl_startPattern() is used to activate an already initialized pattern with a set of haptors attached to it.

After some validation checks on the pattern passed (it must be ready to be activated), hl_startPattern() will call the pattern's initiator code.

See also:: To learn about how a pattern generator works, please read the Developer Page.

hl_startPattern() uses the patternMap array to be able to call the right initiator.

Note:: You cannot use the same pattern descriptor to activate the pattern simultaneously on different haptors.
If the pattern is multi haptor, you have to call addHaptor() for each haptor to add to the same pattern.
If the pattern is single-haptor, and you want multiple instances running simultaneously, you need to initialize a new pattern instance for each haptor, call the addHaptor() with the single haptor to attach and then you can startPattern() on all the patterns together.

Parameters:

[out] pattern This is the pointer to a pattern_desc * returned by a precedent hl_initPattern() call. This pattern_desc should not be already running. If you want many instances of the same pattern, you need to follow all the steps to initialize it.

Returns:: uint8_t The result is returned to indicate success or error.

Return values:

0	Success
1	Error

Definition at line 364 of file hapticLib.c.

uint8_t hl_stopPattern ( pattern_desc * pattern )

API exposed to the user to force pattern execution stop.

Normally, a well designed pattern will finish its job and then free its instances (the pattern itself and all the haptors used) to be eventually configured later.

There are cases however, when you cannot wait for the pattern to stop.
For example, imagine a continuous pattern that will run until the user feel the feedback, in this case, the pattern must be stopped by the application code (the condition cannot be coded inside the pattern) calling hl_stopPattern() with the right pattern descriptor.

Parameters:

[out] pattern This is the pattern descriptor reference of a running pattern.

Returns:: uint8_t The result is returned to indicate success or error.

Return values:

0	Success
1	Error

Definition at line 412 of file hapticLib.c.

Variable Documentation

pattern_initiator patternMap[MAX_HAPTORS]

Pattern Generators Functions Map.

This array contains the addresses of all the pattern generator initiator functions.

The index of the array locate the specific pattern using one of the Pattern Generator Functions Index Names defined in the pattern_name enumeration type definition. (e.g. Test, Impact)

Definition at line 79 of file hl_patterns.c.

system_desc SystemDesc

Global variable to describe the haptic system.

The Library uses this global variable to describe the system and to keep track of the haptic devices' status and active patterns' progress at any time.

Note:: The library user doesn't need to access this variable.

The SystemDesc variable holds a lot of informations, and its members allow the system to access almost all the informations needed.

See also:: Please refer to the Developer Guide page for details.

Definition at line 70 of file hapticLib.c.

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

Function Documentation

Variable Documentation