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_lib_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 set to NULL to disable events

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_initconfig(struct imuconf_t *config)

Init config structure with default values.

Parameters:

config – structure pointer to initialize

Returns:

return 0 on success, -1 on failure

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_getconfig(struct imuconf_t *config)

Get current IMU configuration.

Parameters:

config – pointer to configuration structure to be filled

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.

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_is_tiltactive(void)

Get Tilt 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_get_debuglevel(void)

Get current debug level.

Returns:

debug level

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

void imu_set_testmode(int enable)

Enable library test mode.

In test mode, GPS sensor (if enabled) will be disabled and events will be generated without any external dependency to test IMU library.

Parameters:

enable – 1 to enable, 0 to disable

int imu_get_testmode(void)

Get test mode status.

Returns:

returns 0 if disabled, 1 if enabled

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.02g
    motion_detect_threshold = 0.05g
    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 SENSOR_TYPE_ACCEL

Accelerometer

enumerator SENSOR_TYPE_GYRO

Gyroscope

enumerator SENSOR_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