简介面向物联网嵌入式开发者的ESP32 Arduino例程包以IIC协议采集QMA6100P三轴加速度值为核心演示从传感器驱动到串口输出的完整流程适合正在学习ESP32或需要快速移植加速度传感器的开发者参考。压缩包共15个文件其中包含7个.h头文件、6个.cpp源文件、1个.ino主程序文件及1个.url说明链接分别对应引脚与功能声明、底层驱动实现和Arduino入口逻辑代码中已定义接线方式并附有注释便于对照硬件排查。整套例程在ESP32-S3上验证运行若使用其他型号可根据情况调整引脚配置。资源包体积仅31KB轻量易用已有194人学习。通过阅读该例程开发者可以掌握IIC总线时序、传感器寄存器配置及数据解析方法并能基于现有代码快速扩展至其他QMA系列或类似三轴加速度传感器项目。1. 从手环拆机件到 ESP32 例程QMA6100P 为什么值得用 IIC 去读QMA6100P 这颗三轴加速度计早年常出现在手环、计步器和手机副板里近几年大量流到模块市场成了物联网嵌入式项目里替代 MMA8452、ADXL345 的常见选择。它支持 IIC 与 SPI 两种接口但在 ESP32 开发里绝大多数方案会选 IIC——两根线、地址固定、能和其他传感器挂在同一条总线上这对引脚本来就不宽裕的 ESP32 来说性价比更高。标题里的“例程 19”指的是一套按序号组织的 Arduino 例程包中的第 19 个核心任务是初始化芯片、配置量程再周期性读出 X/Y/Z 三轴加速度。这篇文章按我平时调这类传感器的顺序展开先把硬件接法和总线机制讲清楚再给出能直接编译的驱动代码然后是应用层处理最后是调试手段。适合手里有 ESP32 开发板和 QMA6100P 模块、想半小时内跑通数据并看懂每个参数含义的人。2. ESP32 的 IIC 引脚映射与 QMA6100P 硬件接线2.1 QMA6100P 这颗传感器是什么IIC 地址、量程与上电时序QMA6100P 是国产歌尔微电子推出的一颗电容式三轴加速度计量程可选 ±2g、±4g、±8g、±16g片内带 14 位 ADC输出数据寄存器为 16 位左对齐格式。它和很多老款传感器最大的差异在于WHO_AM_I 寄存器、量程配置寄存器、数据寄存器的地址定义有自己的风格且不同批次的数据手册对同一个寄存器的默认值描述存在差异所以驱动代码里必须写“读回校验”这一步而不是照抄网上的初始化序列就完事。IIC 地址方面QMA6100P 的 7 位地址由 SAO/SDO 引脚决定拉低时是 0x13拉高时是 0x12大多数模块上默认拉低。上电后芯片需要一段稳定时间典型值是 1020ms之后的第一个操作应当是读 WHO_AM_I 寄存器而不是直接配置量程否则芯片可能还没准备好写入被丢弃。这一点在 Arduino 例程里经常被忽略导致初始化看起来成功但数据全是 0。2.2 为什么 ESP32 上接 IIC 不用挑引脚Wire.begin 的自由映射用过 Arduino Uno 的人都知道硬件 IIC 必须用 A4/A5 引脚但在 ESP32 上这个约束不存在。ESP32 的 I2C 外设由 GPIO 矩阵控制任意支持输入输出的引脚都可以被映射为 SDA 或 SCL这在 Arduino 环境里由Wire.begin(sda, scl, frequency)完成。#include Wire.h #define IIC_SDA 21 #define IIC_SCL 22 #define IIC_FREQ 400000 void setup() { Wire.begin(IIC_SDA, IIC_SCL, IIC_FREQ); }这段代码把 GPIO21 映射为 SDA、GPIO22 映射为 SCL总线频率设为 400kHz也就是常说的 Fast Mode。Wire.begin的前两个参数是引脚号第三个是频率不传时默认 100kHz。需要说明的是GPIO21/22 是 ESP32 经典款的默认推荐引脚但不是固定死的如果你的板子把某些引脚连了 LED、按键或模数转换器改成任意两个空闲 GPIO 即可。ESP32-S3、ESP32-C3 同样适用这套写法只是默认推荐引脚不同。频率建议先 400kHz如果总线上有其他器件对时序敏感再降回 100kHz。2.3 最小硬件清单与接线表驱动 QMA6100P 不需要外围元件模块上通常已经焊好上拉电阻和去耦电容直接飞线就能工作。接线如下ESP32 引脚QMA6100P 模块说明3V3VCC必须 3.3V禁止接 5VGNDGND共地GPIO21SDA数据线模块内含上拉电阻GPIO22SCL时钟线模块内含上拉电阻不接SAO/SDO默认拉低地址为 0x13注意 QMA6100P 的工作电压范围是 1.71V 到 3.6V接 5V 会直接损坏芯片。有些模块会额外引出 INT 中断引脚本文例程不用它悬空即可。3. QMA6100P 寄存器地图与 Arduino 驱动代码实现3.1 例程必备的寄存器地图WHO_AM_I、量程寄存器与数据寄存器写驱动前先建立寄存器地图。QMA6100P 的寄存器是 8 位地址、8 位数据IIC 时序为标准的两阶段操作先写寄存器地址再读或写数据。与例程直接相关的寄存器如下寄存器地址名称读写属性用途0x00WHO_AM_I只读芯片 ID用于确认 IIC 通信正常0x0FACC_RANGE读写bit[1:0] 配置量程0x01~0x06ACC_X_L/H、ACC_Y_L/H、ACC_Z_L/H只读三轴加速度原始值16 位左对齐0x11ODR/带宽读写输出数据率例程保持默认数据寄存器从 0x01 开始连续排列一次 IIC 连读 6 个字节即可取回全部三轴数据这比读一次发一次地址高效得多。量程寄存器 0x0F 的位定义在不同厂商文档里略有出入常见约定是 bit[1:0] 为 00 时对应 ±2g01 对应 ±4g10 对应 ±8g11 对应 ±16g。正因存在这种不确定性初始化代码里应当把写入的值再读出来比对并打印到串口。3.2 初始化流程读 ID、配置量程、回读校验完整的初始化函数需要做三件事确认设备在线、写入量程配置、回读验证。下面的代码可以直接放进 .ino 文件顶部。#include Wire.h #define QMA6100P_I2C_ADDR 0x13 #define REG_WHO_AM_I 0x00 #define REG_ACC_RANGE 0x0F bool qma6100pInit() { // 第一步读 WHO_AM_I确认芯片在总线上应答 Wire.beginTransmission(QMA6100P_I2C_ADDR); Wire.write(REG_WHO_AM_I); Wire.endTransmission(false); Wire.requestFrom((uint8_t)QMA6100P_I2C_ADDR, (uint8_t)1); uint8_t chipId Wire.read(); if (chipId 0x00 || chipId 0xFF) { Serial.printf(QMA6100P not found, ID0x%02X\n, chipId); return false; } Serial.printf(QMA6100P ID0x%02X\n, chipId); // 第二步配置量程为 ±2g写入 0x00 Wire.beginTransmission(QMA6100P_I2C_ADDR); Wire.write(REG_ACC_RANGE); Wire.write(0x00); Wire.endTransmission(); // 第三步回读量程寄存器验证写入是否生效 Wire.beginTransmission(QMA6100P_I2C_ADDR); Wire.write(REG_ACC_RANGE); Wire.endTransmission(false); Wire.requestFrom((uint8_t)QMA6100P_I2C_ADDR, (uint8_t)1); uint8_t rangeReg Wire.read(); Serial.printf(ACC_RANGE0x%02X\n, rangeReg); return true; }这段代码有几个值得注意的细节。endTransmission(false)表示当前传输结束后不发送停止条件而是紧接一个重复起始条件这样在读取前不会释放总线时序更紧凑也避免其他 IIC 设备插入竞争。Wire.requestFrom的第一个参数被强转为uint8_t是为了消除 Arduino 环境里requestFrom(int, int)与requestFrom(uint8_t, uint8_t)的重载歧义这是 ESP32 编译时报错的高频原因。回读校验不是为了走形式——如果读到 0xFF说明 SDA 线没接好或芯片未上电如果读到 0x00说明芯片处于复位或休眠状态。3.3 连续读取 6 字节与 14 位数据换算数据读取函数是例程的核心。QMA6100P 的每个轴占用两个 8 位寄存器低字节在前高字节在后14 位有效数据左对齐存放在 16 位中所以拼接后需要右移 2 位才能得到真正的 14 位有符号数。bool qma6100pRead(float ax, float ay, float az) { Wire.beginTransmission(QMA6100P_I2C_ADDR); Wire.write(0x01); // X 轴低字节寄存器地址 Wire.endTransmission(false); Wire.requestFrom((uint8_t)QMA6100P_I2C_ADDR, (uint8_t)6); uint8_t buf[6]; for (int i 0; i 6; i) { buf[i] Wire.read(); } // 拼接每个轴的原始值 int16_t rawX (int16_t)((uint16_t)((buf[1] 8) | buf[0])); int16_t rawY (int16_t)((uint16_t)((buf[3] 8) | buf[2])); int16_t rawZ (int16_t)((uint16_t)((buf[5] 8) | buf[4])); // 右移 2 位得到 14 位右对齐的有符号数 rawX 2; rawY 2; rawZ 2; // 量程 ±2g 时灵敏度为 8192 LSB/g ax rawX / 8192.0f; ay rawY / 8192.0f; az rawZ / 8192.0f; return true; }换算公式的物理意义是±2g 的量程范围对应 14 位 ADC 的全量程即从 -2g 到 2g 映射到 -8192 到 8191所以 1g 的重力加速度对应 8192 LSB。如果把量程改成 ±4g灵敏度就变成 4096 LSB/g换算除数要同步修改。拼接时先用uint16_t强制转换是为了避免buf[1] 8在int类型下的符号扩展问题然后再转int16_t确保负数在之后的右移操作中执行算术移位而不是逻辑移位。这一行如果不加处理Z 轴在翻转时会跳变出非常大的值排查起来很隐蔽。4. 把加速度值用起来串口格式、OLED 显示与倾角计算4.1 输出数据的取舍原始值、物理值与应用值三段式打印数据读回来后串口打印格式直接影响调试效率。常见做法是分三段输出先打印拼接后的原始 int16 值再打印以 g 为单位的物理值最后打印用于姿态识别的角度值。这样既能核对传感器原始输出是否在合理区间又能直接验证换算公式是否正确。void loop() { float ax, ay, az; if (qma6100pRead(ax, ay, az)) { Serial.printf(X%7.3f g Y%7.3f g Z%7.3f g\n, ax, ay, az); } delay(100); }串口监视器选择 115200 波特率。将板子平放桌面上时理论上 Z 轴读数应接近 1.0gX/Y 轴接近 0g把板子竖起来对应轴会落到 ±1g。如果平放时 Z 轴读出 0.5g 或者其他比例值基本可以断定量程配置回读校验没通过或者 LSB 灵敏度除错了。4.2 0.91 寸 OLED 侧 SSD1306 的接入与显示在便携式物联网嵌入式场景里串口不够直观通常会让加速度值显示在 0.91 寸 OLED 上。这块屏用的是 SSD1306 驱动IIC 地址常见 0x3C和 QMA6100P 的 0x13 互不冲突正好验证一总线上挂多设备的能力。#include SSD1306Wire.h SSD1306Wire display(0x3C, IIC_SDA, IIC_SCL); void oledShowAccel(float ax, float ay, float az) { display.clear(); display.drawString(0, 0, X: String(ax, 3) g); display.drawString(0, 16, Y: String(ay, 3) g); display.drawString(0, 32, Z: String(az, 3) g); display.display(); }初始化时先display.init()再display.clear()。注意 0.91 寸 OLED 的 IIC 总线频率如果超过 400kHz部分屏幕会出现雪花点或花屏所以总线上同时挂 QMA6100P 和 OLED 时建议把 IIC 频率保持在 400kHz 以内。还有一点SSD1306 的地址引脚可以通过焊接电阻在 0x3C 和 0x3D 之间切换如果扫描发现地址变了优先查这个而不是查代码。4.3 静态倾角识别atan2 在低功耗监测里的边界三轴加速度最直接的应用是计算静态倾角。在设备静止或缓慢运动时重力矢量在三个轴上的投影唯一确定了俯仰角和横滚角公式如下float pitch atan2(-ax, sqrt(ay * ay az * az)) * 57.29578f; float roll atan2(ay, az) * 57.29578f;atan2返回值是弧度乘以 57.29578 后转为角度。pitch 的 X 轴向上为正roll 的定义取决于传感器安装方向不同模块布局会有符号差异以实际翻转测试为准。这段代码只适合静态或准静态场景一旦设备在运动线性加速度和角速度会混入重力分量倾角会出现明显漂移。此时需要用加速度计加陀螺仪的融合算法这是 MPU6050 方案常做的事QMA6100P 没有内置姿态解算单元不建议在强振动场景直接使用静态公式。若例程后续要接入 OTA 升级驱动函数务必按 init、read、calibrate 拆成独立模块避免把总线逻辑堆在 loop 里导致升级期间传感器阻塞。5. 调试三板斧IIC 地址扫描、全 0 全 FF 排查与 wokwi 时序验证5.1 先做 I2CScanner确认 0x13 在总线上驱动代码跑不通时第一步永远是扫描总线而不是反复检查换算公式。下面是一段通用扫描代码void scanI2C() { Serial.println(Scanning...); for (uint8_t addr 1; addr 127; addr) { Wire.beginTransmission(addr); uint8_t err Wire.endTransmission(); if (err 0) { Serial.printf(Found device at 0x%02X\n, addr); } } }在一个干净的 ESP32 Arduino 工程里这段代码比任何驱动都先跑。正常情况你会看到两个地址0x13QMA6100P和 0x3COLED。如果只看到 0x3C 而没有 0x13检查 QMA6100P 的 VCC 和 SDA 接线如果所有地址都扫不到优先怀疑 SCL 没接对或者总线上拉电阻失效。如果扫出来的是 0x12说明模块上的 SAO 引脚被拉高了把代码里的地址宏改掉即可。5.2 回到例程目录本身.rar 解包后的工程组织与烧录标题给的是 .rar 压缩包解压后你会得到一个以例程序号命名的目录。Arduino IDE 要求 .ino 文件必须与所在文件夹同名所以如果解压出来的文件夹名和 .ino 文件名不一致需要手动统一后再打开否则 IDE 会报“Invalid .ino file”或者编译时找不到主文件。例程包里的多个 .ino 文件属于同一工程时IDE 按页签组织只有和文件夹同名的那个是主文件其他 .ino 会被视为附加代码页。烧录时选好开发板型号ESP32 Dev Module和串口号按住 BOOT 键再点烧录这是 ESP32 最常用的手动烧录流程。注意解压路径不要带中文和空格ESP32 的编译工具链对路径里的中文支持不好这是 Windows 上最常见的诡异报错来源。5.3 wokwi 仿真与逻辑分析仪下的 IIC 协议时序图在真实硬件还没到货时wokwi 仿真平台可以帮你验证 IIC 时序。wokwi 的器件库里没有 QMA6100P但可以用一个通用的 I2C 外设扩展模拟从机响应或者直接用内置的逻辑分析仪观察 SCL/SDA 波形。更贴近真实调试的做法是把逻辑分析仪的通道 0 接 SCL、通道 1 接 SDA抓一段初始化时序正常情况下应当看到起始条件SCL 高电平时 SDA 由高跳低、设备地址 0x13 加写位即 0x26、寄存器地址、重复起始条件然后是从机应答和连续 6 字节数据。如果波形里从机在地址阶段没有拉低 SDA 应答即出现 NACK问题一定出在地址或硬件地址引脚上而不是寄存器配置错误。拿到波形后对照时序图逐段看是排查这类问题最有效的手段。本文还有配套的精品资源点击获取