HapticLib  0.7
Haptic Feedback Library for embedded systems
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Functions | Variables
impact.c File Reference

Impact Pattern generator function definition More...

#include "hapticLib.h"

Go to the source code of this file.

Functions

uint8_t impactContinuator (pattern_desc *pattern)
 Pattern generator continuator
uint8_t impactPatternGenerator (pattern_desc *pattern)
 Pattern generator initiator

Variables

const uint16_t rubberImpactPattern [256]
 Hardcoded, Haptic Feedback Pattern of impact on Rubber surface.
const uint16_t woodImpactPattern [256]
 Hardcoded, Haptic Feedback Pattern of impact on Wood surface.
const uint16_t aluminumImpactPattern [256]
 Hardcoded, Haptic Feedback Pattern of impact on Aluminum surface.

Detailed Description

Impact Pattern generator function definition

Introduction

This is the Impact Pattern Generator function that describe an impact on surface sensation.
Users can choose from three different surface materials and three hit velocity magnitude.

Note:
Refer to hl_startPattern documentation to learn how parameters are passed through modules.
This pattern now supports HapticLib's multi-haptor feature.

Theory

Impact Pattern is based on theoretical research published on paper

and also used in other researches such as the one published on paper

in which authors propose a mathematics model that describe vibrations in impact on various surface materials.

Original model proposed was sinusoidal one:

$Q(t) = A(v) \cdot e^{(-B \cdot t)} \cdot \sin(2 \cdot \pi \cdot f \cdot t)$

where:

  • $v$ is the impact velocity
  • $A(v)$ is the amplitude factor
  • $B$ is the decay rate of the sinusoid
  • $f$ is the frequency of the sinusoid
  • $t$ is the time

the amplitude factor $A(v)$ depends on impact velocity in a quasi-linear way, so the model can be simplified in

$Q(t) = A \cdot v \cdot e^{(-B \cdot t)} \cdot \sin(2 \cdot \pi \cdot f \cdot t)$

To use this formula as Haptic Pattern Samples Generator some other manipulations are necessary:

$PS(t) = |A| \cdot v \cdot [ 2 \cdot e^{(-B \cdot t)} \cdot (1 + \sin(2 \cdot \pi \cdot f \cdot t) ]$

This approach ensures non negative samples and avoid discontinuities.

Samples are also scaled to remain in $(1/3) \cdot PWM\_LEVELS$ range for the slow pattern implementation; the normal and fast patterns are then runtime generated taking the slow pattern samples multiplied by the velocity parameter.

$PS(t) = PS(t) \cdot SCALE\_FACTOR \cdot ({PWM\_LEVELS}/{3})$

Note:
Refer to SCILAB script impact.sce to learn how samples were generated.

Graphics of vibration patterns obtained using this formula are reported in figure:

impactPatterns.png
Impact Pattern Graphics

Optional Parameters

Impact Pattern Generator needs two optional parameters: velocity and material, that can be

  • velocity:
    • Slow
    • Normal
    • Fast
  • material:
    • Rubber
    • Wood
    • Aluminum

Users must define a structure of impactPatternParameters type to pass these parameters.

Usage Examples

This is a sample code snippets that show how impact pattern must be sent:

       ...
       haptor_desc *myHaptor = hl_configure(24000000,15,1);

       impactPatternParameters params;

       params.velocity = Fast;
       params.material = Wood;

       pattern_desc *myImpactPattern = hl_initPattern(Impact, &params);

       hl_addHaptor(myHaptor,myImpactPattern);

       hl_startPattern(myImapctPattern);
       ...

Debugging Details

If HL_DEBUG is defined some useful informations are send to USART.
In particular will be send:

  • impact velocity magnitude used
  • surface material selected
  • first and last 10 samples of the pattern

Additional Notes

No additional notes.

Authors:
Leonardo Guardati
Silvio Vallorani
Version:
v0.7
Date:
2012

Definition in file impact.c.

Function Documentation

uint8_t impactContinuator ( 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 point to the next element of the right array of samples.

When reached the last sample the pattern is finished an remove itself from the scheduling patterns.

Definition at line 272 of file impact.c.

uint8_t impactPatternGenerator ( 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.

This 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 =&impactContinuator;), 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.
Parameters:
[out]patternA 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:
0Success
1Error

Definition at line 431 of file impact.c.

Variable Documentation

const uint16_t aluminumImpactPattern[256]
Initial value:
{
11711, 18304, 21647, 20434, 15299, 8439, 2627, 41, 1417, 5832,
11188, 15131, 16034, 13609, 8947, 3986, 673, 165, 2408, 6234,
9903, 11848, 11302, 8563, 4809, 1560, 40, 696, 3063, 6008,
8234, 8819, 7567, 5045, 2304, 423, 66, 1236, 3315, 5355,
6481, 6247, 4790, 2738, 923, 34, 340, 1606, 3224, 4478,
4848, 4205, 2842, 1329, 264, 25, 633, 1761, 2894, 3543,
3452, 2678, 1556, 545, 27, 164, 841, 1728, 2434, 2664,
2335, 1600, 766, 163, 8, 323, 934, 1562, 1936, 1906,
1496, 884, 320, 20, 79, 439, 926, 1322, 1463, 1296,
900, 440, 100, 2, 164, 495, 843, 1057, 1052, 835,
501, 188, 14, 37, 229, 495, 718, 803, 719, 506,
253, 61, 0, 83, 262, 454, 577, 580, 466, 284,
110, 10, 17, 119, 265, 389, 440, 398, 284, 145,
37, 0, 42, 138, 245, 315, 320, 259, 161, 64,
6, 8, 62, 141, 211, 241, 221, 159, 83, 22,
0, 21, 73, 132, 171, 176, 144, 91, 37, 4,
3, 32, 75, 114, 132, 122, 89, 47, 13, 0,
10, 38, 71, 93, 97, 80, 51, 21, 3, 1,
16, 40, 62, 72, 67, 50, 27, 8, 0, 5,
20, 38, 51, 53, 44, 29, 12, 1, 0, 8,
21, 33, 39, 37, 28, 15, 4, 0, 2, 10,
20, 27, 29, 24, 16, 7, 1, 0, 4, 11,
18, 21, 20, 15, 8, 2, 0, 1, 5, 11,
15, 16, 13, 9, 4, 0, 0, 2, 6, 9,
11, 11, 8, 5, 1, 0, 0, 2, 5, 8,
8, 7, 5, 2, 0, 0 }

Hardcoded, Haptic Feedback Pattern of impact on Aluminum surface.

The aluminumImpactPattern describe a vibration in response to impact on Aluminum. (256 samples)

Defined as const to store it in flash memory.

Note:
Refer to SCILAB script impact.sce to learn how samples was generated.

Definition at line 231 of file impact.c.

const uint16_t rubberImpactPattern[256]
Initial value:
{
9369, 9779, 10165, 10527, 10861, 11167, 11445, 11692, 11909, 12095,
12249, 12372, 12463, 12524, 12553, 12552, 12521, 12462, 12374, 12259,
12118, 11953, 11763, 11552, 11319, 11067, 10798, 10511, 10210, 9896,
9569, 9233, 8887, 8535, 8177, 7815, 7450, 7084, 6719, 6354,
5993, 5635, 5283, 4937, 4598, 4267, 3946, 3634, 3333, 3043,
2765, 2500, 2247, 2008, 1782, 1570, 1372, 1188, 1018, 862,
720, 592, 477, 375, 287, 211, 148, 97, 57, 28,
9, 0, 1, 10, 28, 53, 85, 124, 168, 217,
271, 329, 390, 455, 521, 589, 658, 727, 797, 867,
935, 1003, 1069, 1133, 1195, 1254, 1310, 1363, 1413, 1459,
1501, 1540, 1574, 1605, 1631, 1653, 1670, 1684, 1693, 1698,
1699, 1696, 1688, 1677, 1663, 1644, 1623, 1598, 1570, 1539,
1506, 1470, 1432, 1391, 1349, 1305, 1260, 1214, 1166, 1118,
1069, 1020, 970, 921, 871, 822, 774, 726, 679, 633,
588, 544, 501, 460, 421, 383, 346, 312, 279, 248,
219, 191, 166, 143, 121, 101, 84, 68, 53, 41,
30, 22, 14, 8, 4, 1, 0, 0, 1, 3,
6, 10, 15, 21, 27, 34, 42, 50, 59, 68,
77, 86, 96, 105, 115, 124, 133, 142, 151, 159,
167, 175, 182, 189, 196, 201, 207, 212, 216, 219,
223, 225, 227, 228, 229, 229, 229, 228, 227, 225,
223, 220, 217, 213, 209, 204, 200, 195, 189, 184,
178, 172, 165, 159, 152, 146, 139, 132, 126, 119,
112, 106, 99, 93, 87, 81, 75, 69, 63, 58,
53, 48, 43, 38, 34, 30, 26, 23, 20, 17,
14, 11, 9, 7, 6, 0 }

Hardcoded, Haptic Feedback Pattern of impact on Rubber surface.

The rubberImpactPattern describe a vibration in response to impact on Rubber. (256 samples)

Defined as const to store it in flash memory.

Note:
Refer to SCILAB script impact.sce to learn how samples was generated.

Definition at line 152 of file impact.c.

const uint16_t woodImpactPattern[256]
Initial value:
{
5855, 6936, 7894, 8683, 9269, 9626, 9745, 9624, 9278, 8728,
8006, 7149, 6200, 5204, 4205, 3245, 2364, 1593, 958, 479,
163, 14, 24, 181, 465, 851, 1312, 1818, 2338, 2844,
3309, 3709, 4026, 4246, 4361, 4368, 4269, 4073, 3791, 3438,
3033, 2595, 2145, 1701, 1283, 906, 585, 329, 145, 35,
0, 33, 129, 278, 468, 685, 917, 1149, 1370, 1568,
1732, 1857, 1936, 1967, 1949, 1885, 1780, 1639, 1469, 1280,
1079, 877, 682, 501, 342, 210, 108, 40, 5, 2,
30, 84, 159, 251, 352, 457, 560, 655, 738, 804,
852, 878, 883, 866, 829, 774, 705, 624, 536, 446,
356, 270, 193, 126, 73, 33, 9, 0, 5, 22,
51, 88, 131, 178, 225, 270, 311, 345, 371, 389,
396, 394, 383, 362, 335, 301, 264, 223, 182, 143,
106, 73, 45, 24, 9, 1, 0, 5, 15, 29,
47, 68, 89, 110, 129, 146, 160, 170, 176, 178,
175, 168, 158, 144, 128, 110, 92, 74, 57, 41,
27, 16, 7, 2, 0, 0, 3, 9, 16, 25,
34, 44, 53, 61, 68, 74, 78, 80, 79, 77,
73, 68, 61, 54, 46, 38, 30, 22, 15, 9,
5, 2, 0, 0, 0, 2, 5, 9, 13, 17,
21, 25, 29, 32, 34, 35, 36, 35, 34, 32,
29, 26, 22, 19, 15, 12, 8, 5, 3, 1,
0, 0, 0, 0, 1, 3, 4, 6, 8, 10,
12, 13, 14, 15, 16, 16, 15, 15, 14, 12,
11, 9, 7, 6, 4, 3, 2, 1, 0, 0,
0, 0, 0, 1, 1, 0 }

Hardcoded, Haptic Feedback Pattern of impact on Wood surface.

The woodImpactPattern describe a vibration in response to impact on Wood. (256 samples)

Defined as const to store it in flash memory.

Note:
Refer to SCILAB script impact.sce to learn how samples was generated.

Definition at line 191 of file impact.c.