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

• include/hw/imu_sensor.h

Functions

int imu_init(struct imuconf_t *config, imu_eventcb_f callback)

Initialize IMU library.

Return

return 0 on success, -1 on failure

Parameters

• config: IMU configuration structure (imuconf_t), can be null for default configuration

• callback: Event callback function, can be null if callback not required

int imu_add_sensor(const struct imu_sensor_t *sensor)

Add new sensor to sensor fusion library.

Return

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

Parameters

• sensor: Sensor definition structure imu_sensor_t

int imu_setconfig(struct imuconf_t *config)

Change/set IMU configuration.

Return

return 0 on success, -1 on failure

Parameters

• config: configuration structure, can be null to load default configuration

int imu_setevent_callback(imu_eventcb_f callback)

Change/Set event callback function.

Return

return 0 on success, -1 on failure

Parameters

• callback: callback function pointer, can be null to disable callbacks

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

Get current acceleration value in g.

Return

return 0 on success, -1 on failure

Parameters

• ax: acceleration value on x-axis

• ay: acceleration value on y-axis

• az: acceleration value on z-axis

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.

Return

return 0 on success, -1 on failure

Parameters

• ax: acceleration value on x-axis

• ay: acceleration value on y-axis

• az: acceleration value on z-axis

int imu_get_netaccel(float *force)

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

Return

return 0 on success, -1 on failure

Parameters

• force: Value of force magnitude in unit of g

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

Get current gyroscope reading in deg/s.

Return

return 0 on success, -1 on failure

Parameters

• gx: gyro value on x-axis

• gy: gyro value on y-axis

• gz: gyro value on z-axis

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.

Return

return 0 on success, -1 on failure

Parameters

• yaw: Value of yaw angle in degree

• pitch: value of pitch in degree

• roll: value of roll in degree

int imu_is_ready(void)

Get IMU library status,.

Return

return 1 when library is ready, else return 0

int imu_is_motionactive(void)

Get motion status.

Return

returns 1 when motion active and 0 otherwise

int imu_calibrate_sensor(int handle)

This function initiates sensor calibration.

Return

return 0 on success, negative value on failure (refer errno.h)

Parameters

• handle: Sensor handle returned by imu_add_sensor()

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.

Return

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.

Return

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.

Return

return 0 on success, -1 on failure

Parameters

• enable: 1 to enable, 0 to disable

Structures

struct imuconf_t

IMU configuration structure.

accleration 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

deacceleration 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 cofficient, 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

See

SENSOR_CAP_ACCEL

See

SENSOR_CAP_GYRO

See

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.

Return

return 0 for success and non zero for error

Parameters

• type: Sensor type imusentype_e

• x: Sensor value in x axis

• y: sensor value in y axis

• z: sensor value in z axis

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.

Return

return 0 for success and non zero for error

Parameters

• type: Sensor type imusentype_e

• x: raw value of sensor’s x-axis

• y: raw value of sensor’s y-axis

• z: raw value of sensor’s z-axis

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.

Return

return 0 for success and non zero for error

Parameters

• type: Sensor type imusentype_e

• x: sensor’s x-axis offset

• y: sensor’s y-axis offset

• z: sensor’s z-axis offset

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.

Return

return 0 for success and non zero for error

Parameters

• type: Sensor type imusentype_e

• x: sensor’s x-axis offset

• y: sensor’s y-axis offset

• z: sensor’s z-axis offset

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.

Return

return 0 for success and non zero for error

Parameters

• status: Calibration status

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.

Parameters

• 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 = 1

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