imu.h

Generated from imu.h in platform-idf. Edit the header’s doxygen comments to change this page.

BSP IMU (ST LSM6DS3TR-C) interface.

Functions

`bsp_imu_init`

esp_err_t bsp_imu_init(void)

Initialize IMU.

This function initializes the LSM6DS3TR-C IMU sensor on the I2C bus. The I2C bus must be initialized first by calling bsp_i2c_init(). This function does NOT start the IMU task automatically.

Returns

ESP_OK on success
ESP_ERR_INVALID_STATE if I2C is not initialized
ESP_FAIL if IMU initialization failed

Declared in imu.h:95.

`bsp_imu_start_task`

esp_err_t bsp_imu_start_task(uint32_t update_rate_ms, uint32_t task_priority, uint32_t task_stack_size)

Start IMU task.

Starts a FreeRTOS task that reads the IMU in the background: on every gyro data-ready pulse (52 Hz) where BSP_HAS_IMU_INT2, otherwise every update_rate_ms. The data buffer is read with bsp_imu_get_data().

Parameters

update_rate_ms — Poll period without a data-ready line (default: 20 ms)
task_priority — Task priority (default: 5)
task_stack_size — Task stack size in bytes (default: 4096)

Returns

ESP_OK on success
ESP_ERR_INVALID_STATE if IMU not initialized or task already running
ESP_FAIL on task creation failure

Declared in imu.h:112.

`bsp_imu_stop_task`

esp_err_t bsp_imu_stop_task(void)

Stop IMU task.

Returns

ESP_OK on success
ESP_ERR_INVALID_STATE if task is not running

Declared in imu.h:121.

`bsp_imu_get_data`

esp_err_t bsp_imu_get_data(bsp_imu_data_t *data)

Get latest IMU data (thread-safe)

Returns the latest IMU data read by the background task. This function is thread-safe and can be called from any context.

Parameters

data — Pointer to structure to store IMU data

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if data is NULL
ESP_ERR_INVALID_STATE if IMU task is not running

Declared in imu.h:135.

`bsp_imu_read`

esp_err_t bsp_imu_read(bsp_imu_data_t *data)

Read IMU data directly (blocking)

This function directly reads data from the IMU sensor (blocking call). Use bsp_imu_get_data() instead if you are using the IMU task.

Parameters

data — Pointer to structure to store IMU data

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if data is NULL
ESP_FAIL if read failed

Declared in imu.h:149.

`bsp_imu_get_temperature`

esp_err_t bsp_imu_get_temperature(float *temp)

Get IMU temperature (thread-safe)

Parameters

temp — Pointer to store temperature value

Returns

ESP_OK on success
ESP_ERR_INVALID_ARG if temp is NULL
ESP_FAIL if read failed

Declared in imu.h:160.

`bsp_imu_is_task_running`

bool bsp_imu_is_task_running(void)

Check if IMU task is running.

Returns

true if task is running, false otherwise

Declared in imu.h:167.

`bsp_imu_get_stats`

void bsp_imu_get_stats(bsp_imu_stats_t *stats)

Counters of the IMU task (lock-free snapshot)

Parameters

stats — Filled with the current counters

Declared in imu.h:174.

`bsp_imu_mute_taps_for`

void bsp_imu_mute_taps_for(uint32_t ms)

Ignore knocks on the case for the next ms.

Pad hits also move the case. The pad input says when one happens; this drops the knocks before they are paired, so a real tap arriving afterwards never pairs with a pad hit.

Declared in imu.h:184.

`bsp_imu_get_events`

void bsp_imu_get_events(bsp_imu_event_counts_t *counts)

Event counters since boot (lock-free snapshot)

Declared in imu.h:189.

`bsp_imu_set_event_callback`

void bsp_imu_set_event_callback(bsp_imu_event_cb_t cb, void *ctx)

Runs in the IMU task: keep it short and never block on the I2C bus.

Declared in imu.h:196.

`bsp_imu_read_registers`

esp_err_t bsp_imu_read_registers(uint8_t first, uint8_t *out, size_t len)

Raw register read from the LSM6DS3TR-C, for diagnostics.

Reading a latched source register (0x1B..0x1D, 0x53) clears it.

Declared in imu.h:203.

`bsp_imu_write_register`

esp_err_t bsp_imu_write_register(uint8_t reg_addr, uint8_t value)

Raw register write to the LSM6DS3TR-C, for diagnostics.

Not persisted: the next reconfiguration (boot, recovery) writes the driver’s values back.

Declared in imu.h:211.

`bsp_imu_set_inactivity`

esp_err_t bsp_imu_set_inactivity(bool enable)

Let the part sleep its gyro after ~2.5 s without motion (default off)

While still the accel drops to 12.5 Hz, where taps are not recognised, and pitch/roll/gyro stop updating until motion over the wake-up threshold. The platform turns it on when the screen goes dark (LIGHT sleep) and off again on wake, so a board in use keeps every tap.

Declared in imu.h:221.

`bsp_imu_set_thresholds`

esp_err_t bsp_imu_set_thresholds(uint8_t tap_ths, uint8_t wake_ths)

Set the tap and wake-up thresholds (at 2 g full scale)

The wake-up threshold has to stay above the tap threshold or the part stops reporting taps (they share the slope comparator). While the part is still it uses a fixed low wake-up threshold instead, so motion wakes it.

Parameters

tap_ths — 0..31, 1 LSB = 62.5 mg (default 3 = 187 mg)
wake_ths — 0..63, 1 LSB = 31.25 mg (default 8 = 250 mg)

Declared in imu.h:233.

`bsp_imu_deinit`

esp_err_t bsp_imu_deinit(void)

Deinitialize IMU.

Stops the IMU task if running and deinitializes the sensor.

Returns

ESP_OK on success
ESP_FAIL on error

Declared in imu.h:244.

`bsp_imu_set_kalman_params`

esp_err_t bsp_imu_set_kalman_params(float q_angle, float q_bias, float r_measure)

Tune Kalman filter parameters (angle + bias) for responsiveness.

Parameters

q_angle — Process noise variance for the angle state
q_bias — Process noise variance for the gyro bias state
r_measure — Measurement noise variance for accelerometer angle

Returns

ESP_OK on success

Declared in imu.h:254.

`bsp_imu_set_update_rate`

esp_err_t bsp_imu_set_update_rate(uint32_t update_rate_ms)

Change the IMU task’s poll period (used only without a data-ready line)

Parameters

update_rate_ms — New poll period in milliseconds (min 1ms)

Returns

ESP_OK on success

Declared in imu.h:262.

Types

`bsp_imu_data_t`

IMU data structure.

Field	Type	Description
`accel_x`	`float`	Acceleration X-axis (g)
`accel_y`	`float`	Acceleration Y-axis (g)
`accel_z`	`float`	Acceleration Z-axis (g)
`gyro_x`	`float`	Gyroscope X-axis (dps)
`gyro_y`	`float`	Gyroscope Y-axis (dps)
`gyro_z`	`float`	Gyroscope Z-axis (dps)
`temp`	`float`	Temperature (°C)
`fused_pitch`	`float`	Fused pitch angle (degrees) - Kalman output.
`fused_roll`	`float`	Fused roll angle (degrees) - Kalman output.

Declared in imu.h:24.

`bsp_imu_stats_t`

How the IMU task is being driven, for diagnostics.

Field	Type	Description
`drdy_line`	`bool`	reads are triggered by the gyro data-ready pulse on INT2
`drdy_pulses`	`uint32_t`	data-ready pulses seen by the ISR
`samples`	`uint32_t`	new gyro samples fused
`read_failures`	`uint32_t`	I2C reads that failed.
`tap_mutes`	`uint32_t`	times something asked for taps to be ignored
`taps_muted`	`uint32_t`	knocks dropped because they fell in a muted window
`tap_mute_ms_left`	`int32_t`	what is left of the current mute, 0 when listening

Declared in imu.h:39.

`bsp_imu_event_t`

Events the LSM6DS3TR-C recognises itself (bitmask)

Value	Value	Description
`BSP_IMU_EVENT_SINGLE_TAP`	`1u << 0`
`BSP_IMU_EVENT_DOUBLE_TAP`	`1u << 1`
`BSP_IMU_EVENT_FREE_FALL`	`1u << 2`
`BSP_IMU_EVENT_WAKE_UP`	`1u << 3`	motion over the wake-up threshold
`BSP_IMU_EVENT_ORIENTATION`	`1u << 4`	6D orientation changed
`BSP_IMU_EVENT_STILL`	`1u << 5`	no motion for ~10 s: gyro asleep until a wake-up

Declared in imu.h:52.

`bsp_imu_event_counts_t`

Counters of recognised events since boot.

Field	Type	Description
`single_tap`	`uint32_t`
`double_tap`	`uint32_t`
`free_fall`	`uint32_t`
`wake_up`	`uint32_t`
`orientation`	`uint32_t`
`still_periods`	`uint32_t`	times the part went still and slept its gyro
`still`	`bool`	the part is in its still (gyro asleep) state now
`orientation_6d`	`uint8_t`	D6D_SRC axes: bit5 ZH, 4 ZL, 3 YH, 2 YL, 1 XH, 0 XL.

Declared in imu.h:64.

`bsp_imu_event_cb_t`

typedef void(* bsp_imu_event_cb_t)(uint32_t events, uint8_t orientation_6d, void *ctx)

Called from the IMU task when the part reports events.

Declared in imu.h:81.