IMU Sensor Fusion Interface¶

Logicrom provides simple sensor fusion library to enable use of accelerometer and gyroscope sensor. This library can be very helpful in vehicle telematics to detect events like motion detect, harsh break, harsh acceleration etc.

API Reference¶

Header File¶

Source: include/hw/imu_sensor.h

#include <hw/imu_sensor.h>

Functions¶

int imu_init(struct imuconf_t *config, imu_eventcb_f callback)¶

Initialize IMU library.

Parameters

config – IMU configuration structure (imuconf_t), can be null for default configuration
callback – Event callback function, can be null if callback not required

Returns

return 0 on success, -1 on failure

int imu_add_sensor(const struct imu_sensor_t *sensor)¶

Add new sensor to sensor fusion library.

Parameters: sensor – Sensor definition structure imu_sensor_t
Returns: return sensor handle on success, negative value on failure (refer errno.h)

int imu_setconfig(struct imuconf_t *config)¶

Change/set IMU configuration.

Parameters: config – configuration structure, can be null to load default configuration
Returns: return 0 on success, -1 on failure

int imu_setevent_callback(imu_eventcb_f callback)¶

Change/Set event callback function.

Parameters: callback – callback function pointer, can be null to disable callbacks
Returns: return 0 on success, -1 on failure

int imu_get_accel(float *ax, float *ay, float *az)¶

Get current acceleration value in g.

Parameters

ax – acceleration value on x-axis
ay – acceleration value on y-axis
az – acceleration value on z-axis

Returns

return 0 on success, -1 on failure

int imu_get_linearaccel(float *ax, float *ay, float *az)¶

Get linear acceleration value without gravity component with real frame of reference. Values are in unit of g.

Parameters

ax – acceleration value on x-axis
ay – acceleration value on y-axis
az – acceleration value on z-axis

Returns

return 0 on success, -1 on failure

int imu_get_netaccel(float *force)¶

Get acceleration magnitude without gravity component with direction positivity value represents acceleration and negative value represent deceleration.

Parameters: force – Value of force magnitude in unit of g
Returns: return 0 on success, -1 on failure

int imu_get_gyro(float *gx, float *gy, float *gz)¶

Get current gyroscope reading in deg/s.

Parameters

gx – gyro value on x-axis
gy – gyro value on y-axis
gz – gyro value on z-axis

Returns

return 0 on success, -1 on failure

int imu_get_ypr(float *yaw, float *pitch, float *roll)¶

Get Euler angles: Yaw, Pitch and roll. When gyro sensor is not available, yaw value is always 0.

Parameters

yaw – Value of yaw angle in degree
pitch – value of pitch in degree
roll – value of roll in degree

Returns

return 0 on success, -1 on failure

int imu_is_ready(void)¶

Get IMU library status,.

Returns: return 1 when library is ready, else return 0

int imu_is_motionactive(void)¶

Get motion status.

Returns: returns 1 when motion active and 0 otherwise

int imu_calibrate_sensor(int handle)¶

This function initiates sensor calibration.

Parameters: handle – Sensor handle returned by imu_add_sensor()
Returns: return 0 on success, negative value on failure (refer errno.h)

int imu_calibrate_position(void)¶

This function sets zero position of sensor placement, used for detection of tilt, motion etc. Once set zero position is stored inside flash memory.

Returns: return 0 on success, -1 on failure

void imu_set_debuglevel(int level)¶

Set library debug level to print sensor values.

Level 0: No debug prints (default)

Level 1

: Prints acceleration and Euler angles in following format

IMU: samplerate, accx, accy, accz, acc magnitude, average acceleration, yaw, pitch, roll

Level 2

: Prints raw acceleration data and acceleration data in real frame of reference

in following format

IMU: samplerate, accx, accy, accz, acc_realx, acc_realy, acc_realz

Level 3

: Prints gryo data in degree/s

IMU: samplerate, gyrox, gyroy, gyroz

Level 4

: Print Quaternion value for teapot demo data in following format

IMU: samplerate, w, x, y, z

Parameters: level – debug level from 0 to 4

int imu_add_gpssensor(void)¶

Add GPS as sensor If system uses GPS then imu library can use gps to validate some events.

Returns: return sensor handle on success, negative value on failure (refer errno.h)

int imu_gps_motionassist(int enable)¶

Enable or disable imu assistance to GPS algorithm for trip start/stop detection.

Parameters: enable – 1 to enable, 0 to disable
Returns: return 0 on success, -1 on failure

Structures¶

struct imuconf_t¶

IMU configuration structure.

acceleration threshold values provided are in unit of g

e.g. a value of 0.5 is 0.5g = 9.8 x 0.5 = 4.9m/s2

when configuration is not provided, below are the default threshold values

    static_threshold = 0.01g
    motion_detect_threshold = 0.02g
    harsh_accel_threshold = 0.43g
    harsh_break_threshold = 0.55g
    harsh_turn_threshold = 0.47g
    tilt_angle = 45 degrees
    alpha_coff = 0.4
    sample_ms = 20ms

Public Members

float static_threshold¶: acceleration value below which sensor is considered static

float motion_detect_threshold¶: acceleration greater than or equal to this generates motion active event

float harsh_accel_threshold¶: acceleration threshold for harsh acceleration

float harsh_break_threshold¶: deceleration threshold for harsh breaking event

float harsh_turn_threshold¶: acceleration threshold while turning

float tilt_angle¶: Tilt threshold angle in degree

float alpha_coff¶: Alpha coefficient, currently not used

int sample_ms¶: Data sample rate in miliseconds. lower the better, 20ms is optimal.

struct imu_sensor_t¶

IMU Sensor structure.

This structure defines the sensor interface used by sensor fusion library.

Public Members

int capability¶: Sensor capability: SENSOR_CAP_ACCEL, SENSOR_CAP_GYRO, SENSOR_CAP_MAG

int (*init)(void)¶

Sensor initialization callback.

Return: return 0 for success and non zero for error

int (*read)(int type, float *x, float *y, float *z)¶

Read sensor data callback.

When sensor type is Accelerometer, x, y, and z respresents acceleration in x, y and z axis respectively in m/s2

When sensor type is Gyroscope, x, y, and z respresents rotation around x, y and z axis respectively in degree/s.

Param type: Sensor type imusentype_e
Param x: Sensor value in x axis
Param y: sensor value in y axis
Param z: sensor value in z axis
Return: return 0 for success and non zero for error

int (*read_raw)(int type, int32_t *x, int32_t *y, int32_t *z)¶

Read sensor raw data.

This callback is made during calibration process and expect sensor raw data to calculate offset values.

For accelerometer, raw data should remove any gravity component from it. e.g. If sensor is placed flat, gravity is along z axis; hence it is expected that z is raw data of sensor without gravity.

Param type: Sensor type imusentype_e
Param x: raw value of sensor’s x-axis
Param y: raw value of sensor’s y-axis
Param z: raw value of sensor’s z-axis
Return: return 0 for success and non zero for error

int (*get_offset)(int type, int32_t *off_x, int32_t *off_y, int32_t *off_z)¶

Read sensor offset values.

This callback is called from calibration routine to get offset values for specified sensor type.

Param type: Sensor type imusentype_e
Param x: sensor’s x-axis offset
Param y: sensor’s y-axis offset
Param z: sensor’s z-axis offset
Return: return 0 for success and non zero for error

int (*set_offset)(int type, int32_t off_x, int32_t off_y, int32_t off_z)¶

Set sensor current offset values.

This callback is called from calibration routine to set currently measured offset values for specified sensor type.

Param type: Sensor type imusentype_e
Param x: sensor’s x-axis offset
Param y: sensor’s y-axis offset
Param z: sensor’s z-axis offset
Return: return 0 for success and non zero for error

int (*calib_status)(int status)¶

Calibration status callback.

This callback is called before start of calibration process with status as SENSOR_CAL_START to prepare sensor for calibration. This means setting highest data sample rate.

Once calibration is finished, this callback is again called with status as SENSOR_CAL_END to notify calibration finish. Settings of sensor can be reverted to normal data sampling rate.

Param status: Calibration status
Return: return 0 for success and non zero for error

Macros¶

SENSOR_CAP_ACCEL¶: Sensor has accelerometer

SENSOR_CAP_GYRO¶: Sensor has Gyroscope

SENSOR_CAP_MAG¶: Sensor has Magnetometer

Note

Not implemented yet

SENSOR_CAL_START¶

Calibration start event

On this event sensor can be prepared for calibration with fast data rate for reading

SENSOR_CAL_END¶

Calibration end event

After this event the offset values can be saved to flash or any storage media

Type Definitions¶

typedef void (*imu_eventcb_f)(int event)¶

IMU event callback function type.

Param event: current event imuevent_e

Enumerations¶

enum imusentype_e¶

Sensor type for callbacks.

Values:

enumerator SEN_TYPE_ACCEL¶: Accelerometer

enumerator SEN_TYPE_GYRO¶: Gyroscope

enumerator SEN_TYPE_MAG¶: Magnetometer

enum imuevent_e¶

Events generated by sensor fusion library based on configured thresholds.

Values:

enumerator IMU_EVENT_MOTION_ACTIVE¶: Motion detected event

enumerator IMU_EVENT_MOTION_INACTIVE¶: Motion inactive event

enumerator IMU_EVENT_TILT_ACTIVE¶: Tilt detect event

enumerator IMU_EVENT_TILT_INACTIVE¶: Tilt inactive event, sensor returned to normal position

enumerator IMU_EVENT_HARSH_ACCEL¶: Harsh acceleration event

enumerator IMU_EVENT_HARSH_BREAK¶: Harsh breaking event

enumerator IMU_EVENT_HARSH_TURN¶: Harsh turning event