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:
- shock: A sudden and big change in acceleration, in any direction.
- Shocks last for a short amount of time, typically less than 20ms.
- Shocks give rise of high accelerations, well above 16g.
As an example, dropping a package from 1m or higher causes one or more shocks on impact to the floor.
- shake: A slow repetitive movement, typically human induced, where subsequent accelerations are detected in opposite directions.
- Shakes last for a longer duration, where the full shake completes in a couple of seconds.
- Shakes constitute a few medium accelerations that can amount to 8g.
As an example: shaking a bottle to mix two fluids together.
- vibration: A fast repetitive movement, where small accelerations are detected over a longer period. In many cases vibration is unwanted. They can be caused by imbalances in rotating parts, by uneven friction, or by the meshing of gear teeth.
- Vibrations last for a long duration, in the order of 10+ seconds.
- Vibrations consist of a lot of small accelerations up to 4g.
As an example: driving over cobblestones
- tilt: A change in orientation. Tilting is measured by using the force of gravity. It detects changes in how the gravity pulls to the object. It cannot be used to detect when an object is spun around the axis orthogonal to the earth's surface.
As an example: a box is turned upside-down during transport.
- 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
◆ 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.
|
◆ 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 */ |
◆ ACCEL_SHOCK_DEFAULT_WAITTIME
#define ACCEL_SHOCK_DEFAULT_WAITTIME 100 /* ms */ |
◆ ACCEL_SHOCK_DEFAULT_RINGING_AMPLITUDE
#define ACCEL_SHOCK_DEFAULT_RINGING_AMPLITUDE 4000 /* milli-g */ |
◆ ACCEL_SHOCK_DEFAULT_RINGING_COUNT
#define ACCEL_SHOCK_DEFAULT_RINGING_COUNT 2 |
◆ ACCEL_SHOCK_DEFAULT_RINGING_DURATION
#define ACCEL_SHOCK_DEFAULT_RINGING_DURATION 900 /* ms */ |
◆ ACCEL_SHAKE_DEFAULT_AMPLITUDE
#define ACCEL_SHAKE_DEFAULT_AMPLITUDE 2500 /* milli-g */ |
◆ ACCEL_SHAKE_DEFAULT_COUNT
#define ACCEL_SHAKE_DEFAULT_COUNT 4 |
◆ ACCEL_SHAKE_DEFAULT_DURATION
#define ACCEL_SHAKE_DEFAULT_DURATION 1500 /* ms */ |
◆ ACCEL_VIBRATION_DEFAULT_AMPLITUDE
#define ACCEL_VIBRATION_DEFAULT_AMPLITUDE 1500 /* milli-g */ |
◆ ACCEL_VIBRATION_DEFAULT_FREQUENCY
#define ACCEL_VIBRATION_DEFAULT_FREQUENCY 20 /* Hz */ |
◆ ACCEL_VIBRATION_DEFAULT_DURATION
#define ACCEL_VIBRATION_DEFAULT_DURATION 4 /* s */ |
◆ ACCEL_TILT_DEFAULT_WAITTIME
#define ACCEL_TILT_DEFAULT_WAITTIME 1000 /* ms */ |
◆ 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.
|
◆ Accel_Cb()
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
-
pWorkspace | Points 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()
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
-
pShock | May be NULL . In that case, default values are set. Use this to forget and reset the parameters. |
pShake | May be NULL . In that case, default values are set. Use this to forget and reset the parameters. |
pVibration | May be NULL . In that case, default values are set. Use this to forget and reset the parameters. |
pTilt | May 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()
Retrieves a copy of the current known configuration.
- Parameters
-
pShock | May be NULL . |
pShake | May be NULL . |
pVibration | May be NULL . |
pTilt | May 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.