User API Module header More...

#include <stdint.h>
#include <stdlib.h>
#include "hl_patterns.h"
#include "hl_STM32VLDISCOVERY.h"

Data Structures
struct	haptor_desc
	Single haptor descriptor. More...

Macros
#define	HL_DEBUG
	Define this symbol to enable the Debugging Features.
#define	STM32VLDISCOVERY
	This symbol define what platform we are building for.

Typedefs
typedef struct haptor_desc	haptor_desc
	Single haptor descriptor.

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

Detailed Description

User API Module header

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

This is the only file to be included by a project to use HapticLib.

This file is the entry point for the HapticLib user.

All the High Level API the user should use, are listed here.

Note:

Please make sure the right symbols are set when invoking the compiler. (check the Makefile to be sure).

For example, using the STM32VLDISCOVERY platform these symbols are needed:

-DSTM32VLDISCOVERY (required by HapticLib Platform Specific Module)
-DSTM32F10X_MD_VL (required by STM StdPeriph)
-DUSE_STDPERIPH_DRIVER (required by STM StdPeriph)

Author:: Leonardo Guardati

Version:: 0.7

Date:: 2012

Definition in file hapticLib.h.

Macro Definition Documentation

#define HL_DEBUG

Define this symbol to enable the Debugging Features.

The Debugging features offered by the library are:

The HapticLib Debugging Features are enabled based on the presence of the symbol HL_DEBUG .

To define the symbol do either:

explicitly #define HL_DEBUG inside a module.
add -DHL_DEBUG to the compiler command line during compilation.

Warning:

Always make calls to debugging code inside conditionally included blocks.

                        ...
                        #ifdef HL_DEBUG
                                ...
                                send_int( 1234567 );
                                ...
                                send_string("Correct usage.\n\r\0");
                                ...
                        #endif
                        ...

Definition at line 1873 of file hapticLib.h.

#define STM32VLDISCOVERY

This symbol define what platform we are building for.

This symbol is needed by the Platform Specific Module to select the right low level code implementations.

Note:: You MUST define this symbol using the compiler command line.

Definition at line 1887 of file hapticLib.h.

Typedef Documentation

typedef struct haptor_desc haptor_desc

Single haptor descriptor.

HapticLib keep track of all the haptors configured in the system using one haptor_desc struct for each of them.

To know what kind of informations holds, please refer to its data structure haptor_desc.

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.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation