简介面向STM32开发者的三轴加速度计驱动源码包目标是解决嵌入式项目中LIS3DH传感器快速接入和实时数据读取难题适合具备基础单片机经验、正在做I2C或SPI接口传感器移植的工程师与高年级学生。源码基于HAL库和标准CMSIS编写核心驱动文件封装了初始化、寄存器配置、XYZ三轴加速度读取、中断设置、低功耗模式控制等常用功能配套的示例主函数演示了从外设初始化到数据输出的完整流程说明文档则重点讲解硬件I2C与SPI选择、关键寄存器配置逻辑以及典型应用注意事项适配F1、F4、H7等主流系列无需第三方中间件可直接拷贝到Keil或STM32CubeIDE工程中使用。压缩包共3个文件以工程配置、HTML说明和gitignore版本管理文件为主整体仅3KB结构简洁便于逐文件查阅。当前已有33人学习下载这份源码将寄存器操作与HAL封装结合可作为传感器驱动开发的规范模板尤其对低功耗场景和中断唤醒的设计有直接参考价值。 最近在做便携式跌倒检测项目核心需求是从三轴加速度计上稳定读取数据。我选了ST的LIS3DH配合STM32F103来驱动前后折腾了一周把驱动源码包含例程与头文件整理好了。这期间踩了不少坑也把寄存器的配置逻辑摸透了。如果你也在用STM32平台驱动LIS3DH或者正在为选型发愁这篇文章应该能帮你节省不少时间。我会从硬件连接、寄存器配置、源码实现到实测数据把整套驱动方案完整过一遍。1. 方案选型与整体设计思路1.1 为什么选LIS3DH选传感器这事我的原则是先看应用场景再定型号。这次项目要做跌倒检测需要采集三轴加速度来计算姿态角和判断运动状态对传感器的要求是低功耗、小尺寸、支持中断唤醒、能接I2C或SPI。市面上一圈对比下来LIS3DH的综合竞争力比较强。LIS3DH是ST公司出的一颗三轴加速度计量程有±2g/±4g/±8g/±16g四档可选输出速率从1Hz到5kHz可配。它最突出的两点是功耗极低正常模式最低2µA左右低功耗模式下更夸张以及内置FIFO缓冲区和两个独立中断引脚。对于电池供电的可穿戴设备这种特性很关键主控可以长时间休眠靠传感器中断来唤醒能大幅拉低整机功耗。对比同级别的ADXL345和MMA8452QLIS3DH在噪声水平上略占优而且它的中断配置更灵活——支持方向检测、单击/双击识别、自由落体检测这些在运动场景里都是硬需求。价格方面批量采购大约2~3元一颗性价比也不错。所以我最终确定用LIS3DH并把驱动源码包设计成可复用的模块方便以后换芯片平台时快速迁移。1.2 通信接口选择与硬件连接LIS3DH支持I2C和SPI两种通信协议我都测过说下我的取舍。I2C接线简单只要两根线SCL、SDA不占用额外的片选引脚非常适合资源紧张的STM32小封装型号。SPI的吞吐量更高但在加速度计这种低频数据场景里优势不明显反而要多接一根CS片选线。所以我主推I2C接口源码包也默认用I2C实测SPI的配置代码在驱动里保留了一份需要的话可以参考修改。I2C接口有一个细节要特别注意LIS3DH的7位I2C地址由SDO/SA0引脚的电位决定。SDO接地时地址是0x18接VDD时地址是0x19。我在主板上把SDO直接接地所以驱动里默认地址是0x18。如果你的硬件不是这个接法记得改LIS3DH_I2C_ADDR这个宏。硬件接线表如下以STM32F103C8T6为例传感器引脚STM32引脚说明VDD3.3V电源正极必须加100nF去耦电容GNDGND共地SCLPB6I2C1时钟线外部上拉4.7kΩ至3.3VSDAPB7I2C1数据线外部上拉4.7kΩ至3.3VSDO/SA0GND设置I2C从机地址为0x18CSVDD拉高选择I2C模式拉低则进入SPI模式INT1PB8中断输出1可选接注意CS引脚的电平决定了通信模式。CS拉高时芯片工作于I2C模式CS拉低则进入SPI模式。很多人第一次调试时芯片无响应多半是CS引脚悬空或拉错了电平。2. 驱动源码包结构与寄存器详解2.1 源码包文件组成这套驱动源码包的目录结构如下lis3dh_driver/ ├── inc/ │ ├── lis3dh.h // 寄存器宏定义、数据结构、函数声明 │ └── stm32f1xx_hal_conf.h // 如果工程没有可忽略 ├── src/ │ ├── lis3dh.c // I2C读写封装、初始化、数据读取、中断配置 │ └── main.c // 例程轮询读取并打印三轴加速度 └── README.md // 引脚连接说明与快速上手指引考虑到大部分STM32用户用的是标准外设库或者HAL库我把底层的I2C读写单独抽出来只在lis3dh.c里做了两个静态函数LIS3DH_WriteReg和LIS3DH_ReadReg里面调用了HAL库的HAL_I2C_Mem_Write和HAL_I2C_Mem_Read。换到标准库或者LL库时只需要改这两个函数内部实现上层的寄存器配置代码完全不用动。2.2 关键寄存器与配置要点LIS3DH的寄存器不算多但每个都用得上。我挑几个核心的来讲这些是驱动初始化时必须处理的WHO_AM_I0x0F芯片ID寄存器固定值0x33。每次初始化先读它确认I2C通信正常、芯片在位。如果读到的不是0x33说明要么接线错误要么地址配置不对。这个步骤强烈建议保留能省掉后面排查的一大堆麻烦。CTRL_REG10x20控制寄存器控制输出数据速率ODR和使能X、Y、Z三轴。低4位是ODR配置把bit[7:4]设置成0111就是400Hz。我的跌倒检测场景要求较高采样率所以设了400Hz如果做静态倾角测量100Hz甚至50Hz就够了功耗更低。在实际项目中采样率不是越高越好。采样率越高功耗越大数据噪声处理也更麻烦。建议静态倾角用50Hz手势识别用100Hz跌倒检测用400Hz超过400Hz的场景极少。CTRL_REG40x23量程和自测控制。bit[4:3]用于设置量程00代表±2g01代表±4g10代表±8g11代表±16g。量程设置会影响后续数据换算比例。默认我设成±2g精度最高因为跌倒检测的加速度不会超过这个范围。如果你做的是冲击检测再考虑±8g或±16g。STATUS_REG0x27状态寄存器bit[3]是ZYXDA位表示三轴新数据是否准备好。轮询方式读取数据前务必先查这个标志位否则可能读到旧数据。OUT_X_L / OUT_X_H / OUT_Y_L / OUT_Y_H / OUT_Z_L / OUT_Z_H0x28~0x2D三轴加速度数据寄存器每个轴占两个字节小端模式。读取时保证连续性最好用I2C连续读功能一次性把这6个字节读回来避免分次读取时数据被新样本覆盖。2.3 量程、采样率与数据精度的权衡在写初始化代码之前必须搞清楚量程和精度的关系。LIS3DH输出的原始数据是16位有符号整数高有效位在左协议下bit[7:0]代表高8位实际有效精度取决于量程。以±2g量程为例满量程是4g-2g到2g16位ADC正好对应65536个码值所以灵敏度为灵敏度 4g / 65536 ≈ 0.061mg/LSB如果切换到±16g模式灵敏度变为灵敏度 32g / 65536 ≈ 0.488mg/LSB很明显±2g模式的精度更高这也是我默认使用±2g的原因。对应关系可以整理成一张表量程满量程范围灵敏度mg/LSB适用场景±2g-2g ~ 2g0.061倾角测量、姿态检测±4g-4g ~ 4g0.122通用运动检测±8g-8g ~ 8g0.244手势识别、中等冲击±16g-16g ~ 16g0.488高冲击、碰撞检测这组数据是驱动源码包换算逻辑的依据。实际代码里我把量程参数作为枚举传入初始化函数数据读取时根据当前量程自动换算成真正的重力加速度值单位g。3. 驱动代码实现与核心逻辑3.1 头文件lis3dh.h的设计头文件是整个驱动源码包的“门面”既要保证类型清晰又要让使用方一眼看懂怎么用。我按功能划分了三块内容寄存器宏定义、枚举类型、API函数声明。寄存器宏定义这块直接对照芯片手册抄录常用地址做好注释#ifndef __LIS3DH_H #define __LIS3DH_H #ifdef __cplusplus extern C { #endif #include stm32f1xx_hal.h #include stdint.h /* 设备I2C地址SDO接地为0x18接VDD为0x19 */ #define LIS3DH_I2C_ADDR 0x18 #define LIS3DH_WHO_AM_I 0x33 /* 寄存器地址定义 */ #define LIS3DH_REG_WHO_AM_I 0x0F #define LIS3DH_REG_CTRL_REG1 0x20 #define LIS3DH_REG_CTRL_REG2 0x21 #define LIS3DH_REG_CTRL_REG3 0x22 #define LIS3DH_REG_CTRL_REG4 0x23 #define LIS3DH_REG_CTRL_REG5 0x24 #define LIS3DH_REG_CTRL_REG6 0x25 #define LIS3DH_REG_STATUS_REG 0x27 #define LIS3DH_REG_OUT_X_L 0x28 #define LIS3DH_REG_OUT_X_H 0x29 #define LIS3DH_REG_OUT_Y_L 0x2A #define LIS3DH_REG_OUT_Y_H 0x2B #define LIS3DH_REG_OUT_Z_L 0x2C #define LIS3DH_REG_OUT_Z_H 0x2D /* 量程配置宏 */ #define LIS3DH_RANGE_2G 0x00 #define LIS3DH_RANGE_4G 0x01 #define LIS3DH_RANGE_8G 0x02 #define LIS3DH_RANGE_16G 0x03 /* 输出数据速率配置宏 */ #define LIS3DH_ODR_1HZ 0x01 #define LIS3DH_ODR_10HZ 0x02 #define LIS3DH_ODR_25HZ 0x03 #define LIS3DH_ODR_50HZ 0x04 #define LIS3DH_ODR_100HZ 0x05 #define LIS3DH_ODR_200HZ 0x06 #define LIS3DH_ODR_400HZ 0x07 /* 三轴数据结构体 */ typedef struct { int16_t x_raw; int16_t y_raw; int16_t z_raw; float x_g; float y_g; float z_g; } lis3dh_data_t; /* API函数声明 */ uint8_t LIS3DH_Init(I2C_HandleTypeDef *hi2c, uint8_t range, uint8_t odr); uint8_t LIS3DH_ReadAccel(I2C_HandleTypeDef *hi2c, lis3dh_data_t *data); uint8_t LIS3DH_SetRange(I2C_HandleTypeDef *hi2c, uint8_t range); uint8_t LIS3DH_SetODR(I2C_HandleTypeDef *hi2c, uint8_t odr); float LIS3DH_ConvertRawToG(int16_t raw, uint8_t range); #endif这里我特意把原始ADC值和换算后的g值放在同一个结构体里方便调试时同时观察两者。实测中从原始值反推寄存器配置是否正确非常有用比如静止时Z轴原始值应该接近32768乘以静止重力占比而不只是一个抽象的浮点数。3.2 I2C读写底层实现驱动源码包中I2C读写是所有功能的基础必须保证稳定。我采用HAL库的HAL_I2C_Mem_Read和HAL_I2C_Mem_Write这两个函数的参数分别是指定I2C句柄、设备地址、寄存器地址、寄存器地址长度、数据缓冲区和数据长度。有一个细节I2C地址是8位左移格式还是7位格式容易搞混。HAL库里HAL_I2C_Mem_Read的第一个地址参数要求的是8位地址即7位地址左移一位最低位为读写标志例如7位地址0x18要写成0x18 1。我在代码里已经处理了这在用标准库或直接操作寄存器时非常容易出错很多新手在这里卡很久。static HAL_StatusTypeDef LIS3DH_WriteReg(I2C_HandleTypeDef *hi2c, uint8_t reg, uint8_t value) { return HAL_I2C_Mem_Write(hi2c, LIS3DH_I2C_ADDR 1, reg, I2C_MEMSIZE_8BIT, value, 1, 100); } static HAL_StatusTypeDef LIS3DH_ReadRegs(I2C_HandleTypeDef *hi2c, uint8_t reg, uint8_t *buf, uint8_t len) { return HAL_I2C_Mem_Read(hi2c, LIS3DH_I2C_ADDR 1, reg, I2C_MEMSIZE_8BIT, buf, len, 100); }超时时间我设为100ms在400kHz I2C速率下读写一次几字节的数据完全够用。如果你在低功耗场景中用的是慢速I2C可以适当调大超时值。3.3 数据读取与转换算法数据读取的核心是保证6个字节连续读出避免读到新旧交叉的数据。LIS3DH的OUT_X_L地址是0x28我直接从该地址连续读取6字节让芯片内部自动把三轴数据按顺序输出。读取结果存储到结构体时注意小端字节序——低字节在前高字节在后这点和大多数STM32小板的内存序一致但如果你的平台是大端模式需要交换高低字节。转换算法也不复杂float LIS3DH_ConvertRawToG(int16_t raw, uint8_t range) { float sensitivity; switch (range) { case LIS3DH_RANGE_2G: sensitivity 0.061f; break; case LIS3DH_RANGE_4G: sensitivity 0.122f; break; case LIS3DH_RANGE_8G: sensitivity 0.244f; break; case LIS3DH_RANGE_16G: sensitivity 0.488f; break; default: sensitivity 0.061f; break; } return (float)raw * sensitivity / 1000.0f; }为什么要除以1000因为灵敏度的单位是mg/LSB而我们要转换为g。以±2g为例原始值32768代表大约2g乘以0.061再除以1000得到1.999g合理。整体的数据读取函数如下uint8_t LIS3DH_ReadAccel(I2C_HandleTypeDef *hi2c, lis3dh_data_t *data) { uint8_t buf[6]; uint8_t status; if (LIS3DH_ReadRegs(hi2c, LIS3DH_REG_STATUS_REG, status, 1) ! HAL_OK) return 1; if (!(status 0x08)) // ZYXDA bit return 2; // 数据尚未准备好 if (LIS3DH_ReadRegs(hi2c, LIS3DH_REG_OUT_X_L, buf, 6) ! HAL_OK) return 1; >uint8_t LIS3DH_Init(I2C_HandleTypeDef *hi2c, uint8_t range, uint8_t odr) { uint8_t id; if (LIS3DH_ReadRegs(hi2c, LIS3DH_REG_WHO_AM_I, id, 1) ! HAL_OK) return 1; if (id ! LIS3DH_WHO_AM_I) return 2; _current_range range; // 配置CTRL_REG4设置量程开启高分辨率模式(bit71) uint8_t ctrl4 0x80 | ((range 0x03) 4); if (LIS3DH_WriteReg(hi2c, LIS3DH_REG_CTRL_REG4, ctrl4) ! HAL_OK) return 1; // 配置CTRL_REG1设置ODR和使能三轴(bit01 X, bit11 Y, bit21 Z) uint8_t ctrl1 ((odr 0x0F) 4) | 0x07; if (LIS3DH_WriteReg(hi2c, LIS3DH_REG_CTRL_REG1, ctrl1) ! HAL_OK) return 1; return 0; }CTRL_REG4的bit7置1启用高分辨率模式。这个模式下ADC输出是12位有效数据左对齐到16位相当于把有效精度提高静态场景的噪声表现会好一些。代价是输出速率会减半如果你需要400Hz的速率建议不要开高分辨率模式。4.2 轮询读取例程主循环里最简单的读取方式就是轮询适合快速验证硬件和驱动。例程代码如下int main(void) { HAL_Init(); SystemClock_Config(); MX_I2C1_Init(); if (LIS3DH_Init(hi2c1, LIS3DH_RANGE_2G, LIS3DH_ODR_100HZ) ! 0) { printf(LIS3DH init failed\n); while (1); } printf(LIS3DH init ok\n); lis3dh_data_t accel; while (1) { if (LIS3DH_ReadAccel(hi2c1, accel) 0) { printf(X: %6.3f g Y: %6.3f g Z: %6.3f g\n, accel.x_g, accel.y_g, accel.z_g); } HAL_Delay(10); // 100Hz读取间隔 } }串口重定向用的是printf记得在工程里实现fputc或_write不然printf输出不到串口。我在测试板上用USART1的115200波特率输出一次三轴数据大约40字节在100Hz下完全不会溢出。4.3 实测数据与结果分析把板子平放在桌面上理论上静止时Z轴应该接近1gX和Y接近0g。实测输出如下X: 0.012 g Y: -0.008 g Z: 0.996 g X: 0.010 g Y: -0.009 g Z: 0.998 g X: 0.013 g Y: -0.007 g Z: 0.997 g X: 0.011 g Y: -0.009 g Z: 0.998 gZ轴稳定在0.996~0.998g和标准重力加速度1g非常接近误差约0.2%~0.4%。X轴和Y轴有约10mg左右的偏置这主要来自芯片焊接应力和PCB板面的轻微不平整。对于一般的姿态估计场景这个偏置可以忽略但如果做高精度倾角仪建议在系统上电后做一次零点校准把静止时的偏置记录下来。随后我用手快速翻转板子可以看到Z轴的数值瞬间跳到-1g左右X轴和Y轴也有对应变化。响应速度符合100Hz的设置未出现数据明显滞后或丢帧的情况。整体验证通过驱动源码包可以直接用于后续项目。5. 常见问题与排查技巧实录5.1 I2C通信失败的排查读写I2C时总线无响应是最常见的故障。我总结了几个排查方向第一种情况是地址不对。确认SDO引脚电平是否和代码里的地址匹配。我经常遇到SDO悬空的情况导致芯片地址不稳定读取WHO_AM_I时有时有响应有时没有。解决方案是硬件上把SDO直接接到确定的电平。第二种情况是上拉电阻缺失。I2C总线的SCL和SDA必须外部上拉内部上拉通常太弱。实测中如果省掉4.7kΩ上拉电阻通信距离稍微一长、或者接示波器探头后就容易失败。建议每个I2C引脚都配上4.7kΩ上拉到VDD。第三种情况是CS引脚电平不对。CS悬空或者被干扰拉低芯片就进入SPI模式I2C自然不通。检查CS是否牢固接VDD。5.2 数据跳变与滤波处理如果读取的数据出现明显的跳变毛刺可能是电源纹波造成的。LIS3DH对供电质量比较敏感VDD和VDD_IO的旁路电容一定要靠近芯片引脚放置至少加一个0.1µF陶瓷电容推荐再并联一个1µF电容。另外一个原因是I2C读取时序不连续读到新旧交错的数据。这时要检查是否每次都先查了新数据标志位是否用了连续读。如果分多次单字节读取芯片在两次读取之间可能更新了寄存器导致一个轴的两次读数来自不同的采样点。我在源码包里统一采用连续读6字节的方式问题就消失了。如果滤波后仍有小幅波动可以在应用层加一个简单的滑动平均滤波。例如对每轴保存最近8个采样点每次取平均值。这个操作在姿态检测中的效果非常明显能有效降低高频噪声。5.3 低功耗模式与唤醒配置项目要求设备大部分时间处于休眠状态只在运动时唤醒。LIS3DH的中断功能在这时候很有用。具体做法是配置CTRL_REG3和CTRL_REG6把中断1引脚映射到唤醒事件再设置CTRL_REG5的低功耗模式位。运动检测时芯片自身检测到加速度变化超过阈值就在INT1引脚上产生一个高电平脉冲STM32从停机模式唤醒。这里最大的坑是寄存器配置顺序。必须先配置中断使能再进入低功耗模式顺序反了会导致中断不触发。另外中断信号类型电平触发还是边沿触发要和STM32的EXTI配置匹配我在例程中用的是上升沿触发。从我实测的情况来看LIS3DH在低功耗1Hz采样率下整套系统待机电流只有大约10µA这个功耗水平对于电池供电的设备完全可接受。如果后续再加一颗LIS3DH的内部FIFO功能还能进一步减少主控的唤醒次数这是驱动源码包后续可以扩展的方向之一。这套驱动源码包我现在已经在两个项目里复用了一次是小体积的跌倒检测手环一次是门磁震动监测模块都稳定运行。代码结构上只要把底层I2C读写函数换成对应平台的接口就能快速迁移到其他单片机。如果你在移植过程中遇到什么问题欢迎留言交流。本文还有配套的精品资源点击获取