Generic Pattern generator function definition [TEMPLATE] More...

#include "hapticLib.h"

Macros
#define	HL_DEBUG
	Generator function Debugging Capabilities.

Functions
uint8_t	genericContinuator (pattern_desc *pattern)
	Pattern generator continuator
uint8_t	genericPatternGenerator (pattern_desc *pattern)
	Pattern generator initiator

Detailed Description

Generic Pattern generator function definition [TEMPLATE]

[TEMPLATE]

This is a template file; copy and rename it as starting point for the implementation of a new Pattern Generator.

Follow the structure of this example pattern (code and documentation formats) while implementing a new pattern generator.

The initiator and the continuator need to be implemented and documented. First read the documentation and the code of both and the implement your own pattern code and document it.

Note:

Remember to use the associated header file too. For the template is:

generic.c: Documentation, initiator and continuator.
generic.h: Pattern specific definitions, user and status parameters definitions

For your pattern they become:

mypattern.c: Documentation, initiator and continuator.
mypattern.h: Pattern specific definitions, user and status parameters definitions

[TEMPLATE]

Implementation code of the Generic Pattern.

Introduction

Description with main features only mentioned.

Theory

Reference to theoretical documentation on which the pattern is based.

Link to optional tools used on pattern development.

Description of main results.

Optional Parameters

Detailed description of parameters needed and structure defined to contain them.

Parameters values ranges MUST be explained here.

Usage Examples

Put some code snippets to illustrate how to use the pattern.

Debugging Details

Explain (if any) the behavior of optional debugging features present inside the generator.

Additional Notes

Add some optional notes.

Authors:: Leonardo Guardati; Silvio Vallorani

Version:: v0.7

Date:: 2012

Definition in file generic.c.

Macro Definition Documentation

#define HL_DEBUG

Generator function Debugging Capabilities.

The HapticLib Debugging Features are available on the pattern generator function too.

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

The code must have conditional inclusion of debugging code.

         ...
         #ifdef HL_DEBUG
                 ...
                 send_string("Debug Message...\n\r\0");
                 ...
         #endif
         ...

Warning:: Unconditionally use of debugging code will result in compiling errors when linking the release version of the object files (compiled without -DHL_DEBUG passed to the compiler).

Definition at line 129 of file generic.c.

Function Documentation

uint8_t genericContinuator ( pattern_desc * pattern )

Pattern generator continuator

This function is called back from the patternScheduler() every SystemDesc.samples_delay ms.

At every call, this continuator will decide what to do.

For a simple and static pattern, the action could be to simply point to the next element of an array of samples, or to generate it on the fly through a certain formula.

For more complex scenarios, this pattern continuator callback should be able to deliver a good degree of flexibility.

Warning:: The continuator MUST implement an exit strategy to decide when the pattern is finished an remove itself from the scheduling patterns. If this is not done right, the pattern will never free the haptor(s) for the other patterns to use it(them) again.

Parameters:

[out] pattern A pattern_desc* holding the reference to the running pattern instance to work with. Through this reference, the continuator can extract the user and status parameters in order to execute the haptic pattern.

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

Return values:

0	Success
1	Error

Definition at line 170 of file generic.c.

uint8_t genericPatternGenerator ( pattern_desc * pattern )

Pattern generator initiator

This function is called by the User API Module of HapticLib, when the library user calls hl_startPattern().

The first task for the pattern generator initiator is to validate the user provided inputs, this cannot be done anywhere else.

The pattern initiator then sets up all the status parameters.

If the pattern accept user parameters, the status setting can be based on the user provided parameters.

The last duty of this function is to put the pattern continuator up for scheduling ( setting pattern->continuator =&genericContinuator;), so the next time patternScheduler() will check for active patterns, it will find this pattern.

Warning:: If the initiator doesn't set the continuator up for scheduling, the pattern will never start, and for HapticLib, the haptor is free to receive other patterns.