LSM6DS3 Driver

Overview

A comprehensive ESP-IDF driver for the STMicroelectronics LSM6DS3 6‑axis IMU sensor, featuring sensor fusion capabilities for computing absolute ground angles (roll and pitch). The driver is designed to be easy to integrate and use, providing both low-level sensor access and high-level orientation estimation functionality.

This driver includes comprehensive calibration support, angle zero reference management, and NVS persistence for maintaining settings across reboots. It is designed specifically for the ESP32-P4 platform and is used in EIP Ground Truth and FusionCoreEnIP projects.

Features

• Complete sensor support: Full implementation for LSM6DS3 accelerometer and gyroscope functionality
• Multiple interfaces: Support for both I2C and SPI communication protocols
• Advanced sensor fusion: Implementation of the Madgwick filter (quaternion-based) for high-accuracy orientation estimation
• Lightweight sensor fusion: Complementary filter implementation for applications requiring lower computational overhead
• Ground angle computation: Direct calculation of absolute ground angles (roll and pitch) relative to gravity, with 0-180° angle from vertical calculation
• Calibration support: Comprehensive calibration capabilities including automatic calibration routines, single-axis offset adjustment, and hardware offset registers
• NVS persistence: Non-volatile storage support for calibration data and angle zero references, ensuring settings persist across reboots
• Angle zero reference: Set and store reference angles for roll, pitch, and yaw, with GPIO input support for easy zero-setting
• Modular design: ESP-IDF component structure enabling straightforward integration into existing projects

Hardware Setup

The driver works with any LSM6DS3 breakout; the image above shows the Adafruit LSM6DS3TR-C breakout.

I2C Connection (Default)

Connect the LSM6DS3 to your ESP32-P4:

• VDD: 3.3V
• GND: GND
• SCL: GPIO 22 (configurable)
• SDA: GPIO 21 (configurable)
• SDO/SA0: GND (for address 0x6A) or VDD (for address 0x6B)

SPI Connection

For SPI mode, connect:

• CS: GPIO (configurable)
• SCL/SCLK: GPIO (configurable)
• SDA/SDI: GPIO (configurable)
• SDO: GPIO (configurable)

Sensor Fusion Algorithms

This implementation provides two distinct sensor fusion algorithms, each suited for different application requirements:

Madgwick Filter

The Madgwick filter offers superior accuracy at the cost of increased computational requirements. This implementation provides quaternion output that can be converted to Euler angles (roll, pitch, yaw), making it ideal for applications requiring precise orientation tracking.

Parameters:

• Beta parameter: Lower values (0.01-0.1) increase reliance on accelerometer data, while higher values favor gyroscope measurements
• Sample rate: Typically 104 Hz

Complementary Filter

The complementary filter provides a computationally efficient alternative, offering direct roll and pitch angle output. This implementation is well-suited for applications where processing resources are limited or where real-time performance is critical.

Parameters:

• Alpha parameter: Higher values (0.95-0.99) increase trust in gyroscope data, while lower values place greater emphasis on accelerometer readings
• Sample rate: Typically 104 Hz

Ground Angle from Vertical (0-180°)

The driver provides a function to calculate the absolute angle from vertical using roll and pitch:

• 0°: Device pointing straight up (Z-axis aligned with gravity)
• 90°: Device horizontal (Z-axis perpendicular to gravity)
• 180°: Device pointing straight down (Z-axis opposite to gravity)

The function uses the formula: acos(cos(roll) × cos(pitch)) to compute the angle from vertical.

Calibration Support

The driver provides comprehensive calibration capabilities to improve sensor accuracy:

Automatic Calibration (Recommended)

• Accelerometer calibration: Place the sensor on a flat, stable surface. The Z-axis offset accounts for gravity (1000 mg expected when stationary)
• Gyroscope calibration: Keep the sensor completely stationary during calibration. Any movement will affect the bias calculation
• Sample count: Use 50-200 samples for good accuracy. More samples provide better averaging but take longer

Manual Offset Setting

Manual offset adjustment is available for both accelerometer and gyroscope:

• Single-axis offset adjustment
• Hardware offset registers (accelerometer only)
• Retrieving calibration data
• Clearing calibration

NVS Persistence

Calibration data can be saved to and loaded from NVS (Non-Volatile Storage) to persist across reboots:

• Save calibration data to NVS
• Load calibration data from NVS
• Automatic application of offsets to all sensor readings once calibrated

Angle Zero Reference

The driver provides functionality to set reference angles (zero points) for roll, pitch, and yaw, allowing you to establish a custom reference orientation:

• Set angle zero references for roll, pitch, and yaw
• Apply zero references to angles
• Save/load angle zero references to NVS
• GPIO input support for easy zero-setting (example application uses GPIO 4, 5, 18)

Usage in Other Projects

This driver is used in the following projects:

• EIP Ground Truth: Used as a fallback sensor (MPU6050 is primary) for IMU-based ground-truth measurements
• FusionCoreEnIP: Integrated as part of the multi-sensor EtherNet/IP adapter platform

Important Considerations

• Yaw angle limitations: The LSM6DS3 is a 6DoF IMU without magnetometer capabilities. As such, yaw angle cannot be accurately determined without an external reference. Applications using the Madgwick filter should expect yaw drift over time.
• Ground angle measurement: Roll and pitch angles represent the absolute orientation relative to gravity, providing the essential information required for ground angle measurement applications.
• Calibration storage: Calibration offsets are stored in RAM by default and will be lost on power cycle. Use lsm6ds3_save_calibration_to_nvs() to persist calibration data. Hardware offset registers are also volatile and do not persist.
• Angle zero references: Zero references allow you to establish a custom reference frame. These are stored in RAM and should be saved to NVS for persistence.

Software Requirements

• ESP-IDF: Version 5.0 or later
• Target Platform: ESP32-P4
• NVS: Required for calibration and angle zero reference persistence

License

This project is licensed under the MIT License. Portions of this software incorporate code derived from STMicroelectronics' STMems_Standard_C_drivers, which are licensed under the BSD-3-Clause license.