NHS31xx SW API
accel: Accelerometer sensor module

Detailed Description

The accelerometer sensor module abstracts away an external accelerometer, and provides a high level API focusing on event reporting of a specific type. The external accelerometer is to be connected with the NSH31xx IC via the HW IC block.

Four events can be detected, which are loosely defined as:

Note
The module allows to change the type of the external accelerometer without affecting its API or functionality. The current supported external accelerometer sensors can be selected as a diversity setting. Given a type, some events may not be available. Also, not all events can be monitored for at the same time. See the diversity setting documentation for more details.
Warning
This module assumes it is the only block accessing the external accelerometer. Any other access through other unrelated code, both during, before or after the use of this module, may result in unpredictable behavior.
Operation
The module provides little information, if at all, about the actual x, y and z acceleration data points that lead up to the reporting of the event. A typical flow is: #- to configure the acceleration sensor. Depending on the type of event that is to be detected, a different configuration is applied. #- The accelerometer report threshold excesses via an interrupt line, which will wake up the ARM should the NHS31xx be in sleep, deep sleep or deep power down mode. #- Again depending on the type of events to be detected, a different algorithm is used by the accel module to conclude whether the interrupts generated by the acceleration sensor constitute a genuine event. #- Each event is reported via the callback function Accel_Cb. It is defined weakly, allowing the application to override it, even when they are compiled in a different library. Only the end conclusion of the algorithm is reported; interrupt information and acceleration data points are lost to the application.

Physically, the shock, shake and vibration events are all variations on sudden changes in acceleration measurements; whereas tilting is about checking the gravity in a stable environment. The latter is a type of orientation, while The first three events are all types of motion, each requiring a different configuration of the same accelerometer. For this reason, it is only possible to detect either shock, shake or vibration; possibly combined with tilting.

Detecting shocks
Shocks are detected in a two-step process:
  • First a large shock is monitored for.
  • After the large shock, multiple smaller shocks are expected, in a so called 'ringing' effect.
This leads to the following parameters:
  • amplitude: the minimal amplitude of the large shocks, and of the smaller shocks thereafter.
  • duration: the expected duration of the ringing effect.
  • count: combined with duration, indicates the rate at which the ringing effect is quenched.
These can be configured here using ACCEL_SHOCK_PARAMS_T.

Detecting shakes
A typical shake motion is unidirectional and involves a number of consecutive side to side shake movements of the device. Two interrupts will be generated by the chip on a single shake (one for going from one side to the other, and one for coming back). The interrupts will report opposite polarities such as X+/X- or Y-/Y+, etc. We can decide on the shake event by counting opposite interrupts for a specified period.
Including the acceleration threshold fixed, this gives three configurable parameters:
  • duration: how long the user is expected to shake the product.
  • count: a minimum number of back=and-forth movements that are to be detected.
  • amplitude: the minimal amplitude of each swing (shake) before it is counted.
These can be configured here using ACCEL_SHAKE_PARAMS_T.

Detecting vibration
Vibration is detected using a very simple algorithm, focusing on three components:
  • amplitude: an operating machine is typically already vibrating. Only when the vibrations are amplifying, a notification should be generated.
  • frequency: a low vibration frequency is usually not a concern. Higher frequencies exceeding the target amplitude, exert more force on the guarded product or machine and indicate an imminent failure or devaluation of the product's quality.
  • duration: typically, short bursts of vibration are not a concern. Only when vibration lasts for a long duration, a notification should be generated.
These can be configured here using ACCEL_VIBRATION_PARAMS_T.

Detecting tilting
Tilting is fully determined by the accelerometer. Tilting will be reported when the stable absolute position of the accelerometer changes more than 45°, with a hysteresis angle of 15°.
  • Fixed values are used for both types of angles.
  • waitTime: the time after which a position is considered stable. Changes in angle shorter than this time are not reported.
Configurable parameters are presented as ACCEL_TILT_PARAMS_T.
Diversity
This module supports diversity, such as the choice between the supported accelerometer sensors. Some code space can be saved by stripping unused modes during pre-processing. Check Diversity settings for all diversity parameters.
Note
Accelerometer sensors have measurement scale range limits: usually they're capable of measuring acceleration up to 8g or 16g. This means a shock - which easily can produce very short bursts of 50g and higher - cannot be tracked very accurately: the higher acceleration values will be clipped.
^ ^
g| X g|
| XX |
| X XX |
| X XX |
16+------XX------X------------------------- 16+------XXXXXXXXX------------------------
| XX XX | XX XX
| XX X XX | XX X XX
| XX XX X time | XX XX X time
0+----------------------------------------> 0+--------------------------------------->
| XX XX | XX XX
| XX XX | XX XX
| XX XX | XX XX
-16+----------------------XX---X------------ -16+----------------------XXXXXX-----------
| XX X |
| XX |
| Actual acceleration X | Measured acceleration

Modules

 Diversity settings
 

Data Structures

struct  ACCEL_SHOCK_PARAMS_T
 
struct  ACCEL_SHAKE_PARAMS_T
 
struct  ACCEL_VIBRATION_PARAMS_T
 
struct  ACCEL_TILT_PARAMS_T
 

Macros

#define ACCEL_WORKSPACE_SIZE   22
 
#define ACCEL_SHOCK_DEFAULT_AMPLITUDE   12000 /* milli-g */
 
#define ACCEL_SHOCK_DEFAULT_WAITTIME   100 /* ms */
 
#define ACCEL_SHOCK_DEFAULT_RINGING_AMPLITUDE   4000 /* milli-g */
 
#define ACCEL_SHOCK_DEFAULT_RINGING_COUNT   2
 
#define ACCEL_SHOCK_DEFAULT_RINGING_DURATION   900 /* ms */
 
#define ACCEL_SHAKE_DEFAULT_AMPLITUDE   2500 /* milli-g */
 
#define ACCEL_SHAKE_DEFAULT_COUNT   4
 
#define ACCEL_SHAKE_DEFAULT_DURATION   1500 /* ms */
 
#define ACCEL_VIBRATION_DEFAULT_AMPLITUDE   1500 /* milli-g */
 
#define ACCEL_VIBRATION_DEFAULT_FREQUENCY   20 /* Hz */
 
#define ACCEL_VIBRATION_DEFAULT_DURATION   4 /* s */
 
#define ACCEL_TILT_DEFAULT_WAITTIME   1000 /* ms */
 

Enumerations

enum  ACCEL_MODE_T {
  ACCEL_MODE_NONE = 0,
  ACCEL_MODE_SHOCK = 0x01,
  ACCEL_MODE_SHAKE = 0x02,
  ACCEL_MODE_VIBRATION = 0x04,
  ACCEL_MODE_TILT = 0x08,
  ACCEL_MODE_COUNT = 4,
  ACCEL_MODE_ALL = 0x0F
}
 
enum  ACCEL_STATE_T {
  ACCEL_STATE_BEGIN,
  ACCEL_STATE_FALSE,
  ACCEL_STATE_END
}
 

Functions

WEAK void Accel_Cb (ACCEL_MODE_T mode, ACCEL_STATE_T state)
 
void Accel_Init (void *pWorkspace)
 
void Accel_DeInit (void)
 
void Accel_SetParams (const ACCEL_SHOCK_PARAMS_T *pShock, const ACCEL_SHAKE_PARAMS_T *pShake, const ACCEL_VIBRATION_PARAMS_T *pVibration, const ACCEL_TILT_PARAMS_T *pTilt)
 
void Accel_GetParams (ACCEL_SHOCK_PARAMS_T *pShock, ACCEL_SHAKE_PARAMS_T *pShake, ACCEL_VIBRATION_PARAMS_T *pVibration, ACCEL_TILT_PARAMS_T *pTilt)
 
int Accel_Start (int mode)
 
int Accel_Stop (int mode)
 
bool Accel_Check (void)
 

Data Structure Documentation

◆ ACCEL_SHOCK_PARAMS_T

struct ACCEL_SHOCK_PARAMS_T

Defines the parameter values that characterize a shock.

Data Fields
uint16_t amplitude

Define the minimal threshold value to watch for. This threshold is applied to each axis: X, Y and Z. When an acceleration is detected which is - in absolute value - above this threshold value, the NHS31xx IC is notified and it is checked whether this constitutes a valid shock. The number listed must be an absolute positive number, expressed in milli-g.

uint16_t waitTime

Define the time to wait after detecting an initial shock. All acceleration events after detecting the initial shock are ignored for this duration. After this time has passed, the 'ringing' effect is looked for. The number listed must be an absolute positive number, expressed in milli-seconds.

uint16_t ringingAmplitude

When a shock occurs, after the first peak, a number of smaller shocks are expected, in a so-called 'ringing' effect. Define here the minimal threshold value above which ringing is detected. The number listed must be an absolute positive number less than amplitude, expressed in milli-g.

uint8_t ringingCount

When a shock occurs, after the first peak, a number of smaller shocks are expected, in a so-called 'ringing' effect. Define here the minimal number of smaller shocks to detect. The number listed must be an absolute positive number less than 10.

uint16_t ringingDuration

Define the total duration to look for the 'ringing' effect. This time window starts when waitTime expires. At least ringingShockCount smaller shocks are expected in this time window. The number listed must be equal to or larger than waitTime, expressed in milli-seconds.

◆ ACCEL_SHAKE_PARAMS_T

struct ACCEL_SHAKE_PARAMS_T

Defines the parameter values that characterize a shake.

Data Fields
uint16_t amplitude

Define the minimal threshold value to watch for. This threshold is applied to each axis: X, Y and Z. When accelerations are detected which are - in absolute value - less than this value, the NHS31xx IC is not involved: the data is immediately discarded by the accelerometer. The number listed must be an absolute positive number, expressed in milli-g.

uint8_t count

Define the minimal number of back-and-forth movements to detect before classifying the motion as a shake. The number listed must be an absolute positive number.

uint16_t duration

Define the maximal duration in which the shake must be completed before it is reported. When the product is shaked the sufficient number of times after a longer duration, it is considered as a 'short-lived heavy vibration' kind of motion, and not a - typically human-induced - shake. The number listed must be an absolute positive number, expressed in milliseconds.

◆ ACCEL_VIBRATION_PARAMS_T

struct ACCEL_VIBRATION_PARAMS_T

Defines the parameter values that characterize a vibration.

Data Fields
uint16_t amplitude

Define the minimal threshold value to watch for. This threshold is applied to each axis: X, Y and Z. When accelerations are detected which are - in absolute value - less than this value, the NHS31xx IC is not involved: the data is immediately discarded by the accelerometer. The number listed must be an absolute positive number, expressed in milli-g.

uint8_t frequency

Define the minimal frequency before a vibration is to be reported. The accelerometer is sampling continually, at a rate suitable to catch the vibration to monitor for. The samples are filtered per the given threshold value amplitude. The filtered samples occur at a rate which increases when the vibration intensifies. The value given here sets the minimum frequency in which the application is interested. The number listed must be an absolute positive number, expressed in Hertz.

uint16_t duration

Define the minimal duration of the vibration before it is reported. When the product or machine, which the NHS31xx solution is monitoring, is manipulated, short-lived vibrations can occur. These do not necessarily indicate a defect. The number listed here sets a duration: only when the filtered accelerations are sampled at a high-enough rate for a long enough time, the application is notified. The number listed must be an absolute positive number, expressed in seconds.

◆ ACCEL_TILT_PARAMS_T

struct ACCEL_TILT_PARAMS_T

Defines the parameter values that characterize a tilt.

Data Fields
uint16_t waitTime

Define the time to wait after detecting an orientation change. Only when the orientation change is stable for this amount of time, it is reported as an event. The number listed must be an absolute positive number, expressed in milli-seconds.

Note
The maximum possible wait time is dependent on the sampling rate of the accelerometer. When the chosen wait time cannot be met, it is set to the maximum value it can wait.

Macro Definition Documentation

◆ ACCEL_WORKSPACE_SIZE

#define ACCEL_WORKSPACE_SIZE   22

Size of the workspace in use by this module. Defines the size of the array to pass along when calling Accel_Init.

◆ ACCEL_SHOCK_DEFAULT_AMPLITUDE

#define ACCEL_SHOCK_DEFAULT_AMPLITUDE   12000 /* milli-g */

Default value for ACCEL_SHOCK_PARAMS_T.amplitude when custom values are not given.

◆ ACCEL_SHOCK_DEFAULT_WAITTIME

#define ACCEL_SHOCK_DEFAULT_WAITTIME   100 /* ms */

Default value for ACCEL_SHOCK_PARAMS_T.waitTime when custom values are not given.

◆ ACCEL_SHOCK_DEFAULT_RINGING_AMPLITUDE

#define ACCEL_SHOCK_DEFAULT_RINGING_AMPLITUDE   4000 /* milli-g */

Default value for ACCEL_SHOCK_PARAMS_T.ringingAmplitude when custom values are not given.

◆ ACCEL_SHOCK_DEFAULT_RINGING_COUNT

#define ACCEL_SHOCK_DEFAULT_RINGING_COUNT   2

Default value for ACCEL_SHOCK_PARAMS_T.ringingCount when custom values are not given.

◆ ACCEL_SHOCK_DEFAULT_RINGING_DURATION

#define ACCEL_SHOCK_DEFAULT_RINGING_DURATION   900 /* ms */

Default value for ACCEL_SHOCK_PARAMS_T.ringingDuration when custom values are not given.

◆ ACCEL_SHAKE_DEFAULT_AMPLITUDE

#define ACCEL_SHAKE_DEFAULT_AMPLITUDE   2500 /* milli-g */

Default value for ACCEL_SHAKE_PARAMS_T.amplitude when custom values are not given.

◆ ACCEL_SHAKE_DEFAULT_COUNT

#define ACCEL_SHAKE_DEFAULT_COUNT   4

Default value for ACCEL_SHAKE_PARAMS_T.count when custom values are not given.

◆ ACCEL_SHAKE_DEFAULT_DURATION

#define ACCEL_SHAKE_DEFAULT_DURATION   1500 /* ms */

Default value for ACCEL_SHAKE_PARAMS_T.duration when custom values are not given.

◆ ACCEL_VIBRATION_DEFAULT_AMPLITUDE

#define ACCEL_VIBRATION_DEFAULT_AMPLITUDE   1500 /* milli-g */

Default value for ACCEL_VIBRATION_PARAMS_T.amplitude when custom values are not given.

◆ ACCEL_VIBRATION_DEFAULT_FREQUENCY

#define ACCEL_VIBRATION_DEFAULT_FREQUENCY   20 /* Hz */

Default value for ACCEL_VIBRATION_PARAMS_T.frequency when custom values are not given.

◆ ACCEL_VIBRATION_DEFAULT_DURATION

#define ACCEL_VIBRATION_DEFAULT_DURATION   4 /* s */

Default value for ACCEL_VIBRATION_PARAMS_T.duration when custom values are not given.

◆ ACCEL_TILT_DEFAULT_WAITTIME

#define ACCEL_TILT_DEFAULT_WAITTIME   1000 /* ms */

Default value for ACCEL_TILT_PARAMS_T.waitTime when custom values are not given.

Enumeration Type Documentation

◆ ACCEL_MODE_T

The different modes which can be enabled. Each mode enables the detection of a specific type of acceleration.

Note
Not all modes can be enabled at a time. The allowed combinations are restricted by the implementation and the choice of acceleration sensor.
Enumerator
ACCEL_MODE_NONE 

No detection.

ACCEL_MODE_SHOCK 

Detect shocks. See accelShock_anchor

ACCEL_MODE_SHAKE 

Detect human shake movements. See accelShake_anchor

ACCEL_MODE_VIBRATION 

Detect vibration. See accelVibration_anchor

ACCEL_MODE_TILT 

Detect tilting. See saccelTilt_anchor

ACCEL_MODE_COUNT 

Number of modes. Not to be used as a possible mode. Use this in for loops or to define array sizes.

ACCEL_MODE_ALL 

Convenience value to target all acceleration modes at once.

◆ ACCEL_STATE_T

Lists the different states that the algorithm detection of a mode is in, as reported via Accel_Cb.

Enumerator
ACCEL_STATE_BEGIN 

A first interrupt has been received that could lead to a valid detection of a mode.

Warning
Deinitializing the acceleration module through Accel_DeInit, or going to the Deep power down or Power-off mode, will prevent further analysis, and the detection will not be completed.
ACCEL_STATE_FALSE 

The algorithm as implemented by the acceleration module has finished the detection sequence of a mode, and has concluded it was a false positive. The mode was not detected at this time.

Note
Deinitializing the acceleration module through Accel_DeInit, and thereafter going to the Deep power down or Power-off mode, can now take place, and will not will prevent future detections.
ACCEL_STATE_END 

The algorithm as implemented by the acceleration module has finished a valid detection of a mode. The mode was just now successfully detected.

Note
Deinitializing the acceleration module through Accel_DeInit, and thereafter going to the Deep power down or Power-off mode, can now take place, and will not will prevent future detections.

Function Documentation

◆ Accel_Cb()

WEAK void Accel_Cb ( ACCEL_MODE_T  mode,
ACCEL_STATE_T  state 
)

Weak declaration of the acceleration callback function. Override this in your application to capture all algorithm state changes of the enabled modes.

Parameters
mode: Reports the mode whose algorithm was triggered.
state: Reports what the current state is of the current algorithm running for the given mode.
Warning
The application must redefine this to receive updates about the mode detection process.

◆ Accel_Init()

void Accel_Init ( void *  pWorkspace)

Initialization function. Initializes file scoped variables.

Precondition
Must be the first function called in this module.
Parameters
pWorkspacePoints to a contiguous array of ACCEL_WORKSPACE_SIZE bytes free to be used by the validation process. Any change to this value is assumed to be stored in EEPROM before going to Deep Power Down mode and given back unaltered in a next call to this function. This allows the validation process to keep track of its own internal state.
Precondition
All calls to this function must provide the same workspace.
The very first call to this function must provide a zero-initialized workspace.
Warning
pWorkspace may not be NULL.
Note
The HW I2C bus is not used during this call.

◆ Accel_DeInit()

void Accel_DeInit ( void  )

De-Init function.

Warning
This call can still change the contents pointed to by pWorkspace (see Accel_Init). This must be the last function called in this module.
Note
The HW I2C bus is not used during this call.

◆ Accel_SetParams()

void Accel_SetParams ( const ACCEL_SHOCK_PARAMS_T pShock,
const ACCEL_SHAKE_PARAMS_T pShake,
const ACCEL_VIBRATION_PARAMS_T pVibration,
const ACCEL_TILT_PARAMS_T pTilt 
)

Initialization function, continued. Initializes detection parameters.

Precondition
If called at all, must be the second function called in this module, after Accel_Init, before Accel_Start.
Parameters
pShockMay be NULL. In that case, default values are set. Use this to forget and reset the parameters.
pShakeMay be NULL. In that case, default values are set. Use this to forget and reset the parameters.
pVibrationMay be NULL. In that case, default values are set. Use this to forget and reset the parameters.
pTiltMay be NULL. In that case, default values are set. Use this to forget and reset the parameters.
Postcondition
New parameters are stored and will be used for all subsequent acceleration modes, including new detection sessions that are started after a power-off.
Note
The HW I2C bus is not used during this call.

◆ Accel_GetParams()

void Accel_GetParams ( ACCEL_SHOCK_PARAMS_T pShock,
ACCEL_SHAKE_PARAMS_T pShake,
ACCEL_VIBRATION_PARAMS_T pVibration,
ACCEL_TILT_PARAMS_T pTilt 
)

Retrieves a copy of the current known configuration.

Parameters
pShockMay be NULL.
pShakeMay be NULL.
pVibrationMay be NULL.
pTiltMay be NULL.
Note
The HW I2C bus is not used during this call.

◆ Accel_Start()

int Accel_Start ( int  mode)

Enables the detection of a mode. The modes given are merged with the already enabled modes. Modes that are already enabled and also given here remain untouched.

Parameters
mode: bitmask. An OR'd combination of enumeration values ACCEL_MODE_T, which must be detected.
Returns
All modes that are currently enabled.
For all enabled modes, the findings will be reported through Accel_Cb
Precondition
Accel_Init and Accel_Start must have been called beforehand.
The acceleration chip must be powered.
Note
Not all modes can be enabled at a time. The allowed combinations are restricted by the implementation and the choice of acceleration sensor.
Precondition
The I2C driver is not in use: Chip_I2C_Init has not yet been called, or Chip_I2C_DeInit was the last call to this driver.
Postcondition
The I2C driver is no longer in use by the acceleration module.

◆ Accel_Stop()

int Accel_Stop ( int  mode)

Disables the detection of a mode. Modes that already disabled remain disabled.

Parameters
mode: bitmask. An OR'd combination of enumeration values ACCEL_MODE_T, which no longer need to be detected.
Precondition
The acceleration chip must be powered.
Returns
All modes that remain enabled.
For all modes that are still enabled, the findings will continue to be reported through Accel_Cb
Precondition
The I2C driver is not in use: Chip_I2C_Init has not yet been called, or Chip_I2C_DeInit was the last call to this driver.
Postcondition
The I2C driver is no longer in use by the acceleration module.

◆ Accel_Check()

bool Accel_Check ( void  )

The external accelerometer typically pulls/toggles a pin, provoking an interrupt. The application can use that as a trigger to call this function, which queries the accelerometer and checks the enables modes.

Returns
True if the accelerometer had something to report, false otherwise.
Note
This call requires the use of the I2C HW
Precondition
The I2C driver is not in use: Chip_I2C_Init has not yet been called, or Chip_I2C_DeInit was the last call to this driver.
Postcondition
The I2C driver is no longer in use by the acceleration module.