简介一套基于ESP32-S3的物联网嵌入式Arduino开发例程专注于通过IIC协议采集QMA6100P三轴加速度传感器数据适合正在学习物联网、嵌入式或传感器应用的开发者参考。压缩包内共15个文件以.h头文件与.cpp源文件为主另有.ino主程序与快捷方式文件头文件对应传感器、屏幕、IO扩展等模块声明源文件负责具体驱动实现结构清晰、便于按需增删。代码中已定义好ESP32与各模块的接线引脚并配有详尽注释可直接对照硬件理解IIC时序、寄存器配置与数据换算流程。资源整体仅31KB轻量且聚焦。目前已有194人学习下载无论你是初探ESP32的爱好者还是需要快速集成加速度传感器的工程师都能从这份例程的模块化分层和排错思路上获得有效参考。1. 拿到例程包先别急着烧录ESP32-S3的IIC传感器工程是怎么串起来的很多人在 GitHub 或网盘上拖下来一个 rar 包解压后第一件事就是打开19_iic_qma6100p.ino直接点上传然后卡在编译错误、串口输出全 0、LCD 花屏这几类问题里。这个例程表面上是“IIC 读 QMA6100P 加速度”实际上是一整条数据链QMA6100P 挂在 IIC 总线上采集 X/Y/Z 轴原始值XL9555 作为同一根总线上的 IO 扩展芯片控制 LED 和部分引脚SPI 接口的 LCD 负责实时显示UART 再把加速度值输出到上位机。它适合正在用 ESP32 系列接传感器、又想搞清楚多设备怎么共享一条 IIC 总线的人也适合那些需要把“采集-显示-上传”三段逻辑分开写的 Arduino 项目。建议先别烧录按本文把寄存器配置和总线结构过一遍否则你连串口打印出来的数值是 8 位还是 16 位都可能看不明白。2. IIC 总线初始化与 QMA6100P 寄存器配置2.1 为什么选 IIC 而不是 SPI 或 UARTQMA6100P 是一颗三轴加速度计支持 IIC 和 SPI 两种数字接口数据手册里还保留了模拟输出脚位。这句话翻译成选型逻辑就是如果你只接这一颗传感器SPI 确实能跑更高的采样率但会占掉至少 4 个 GPIOIIC 只要 SDA 和 SCL 两根线而且在同一个总线上还能并接其他器件。本工程里正是这么干的IIC 总线上同时挂了 QMA6100P 和 XL9555加上可选的 OLED 或温度传感器引脚占用依然很少。对于电池供电的便携设备IIC 在上拉电阻较小的情况下可以提供足够的吞吐量QMA6100P 在 12.5 Hz 到 200 Hz 的 ODR 范围内400 kbps 的快速模式完全够用。另外注意例程面向的是 ESP32-S3。ESP32-S3 的硬件 IIC 控制器在Wire库底层通过i2c_master驱动实现和经典的 ESP32 不同S3 的默认引脚分配更自由任意 GPIO 都可以配置为 SDA/SCL这不代表你可以完全无视模拟时序。例程代码在19_iic_qma6100p.ino开头已经用宏定义了引脚换开发板时最常踩的坑就是引脚被其他外设占用或者 SDA/SCL 接到只支持 5 V 逻辑的传感器上导致读不到 ACK。2.2 上电后的标准动作探测地址、读 ID、配量程拿到例程后第一步不是读数据而是先确认 IIC 设备在不在总线上。QMA6100P 在 IIC 模式下设备地址由 SAO 引脚决定未拉高时常见地址是0x127 位地址乘以 2 后得到 8 位写地址0x24。注意Wire库的beginTransmission()接收的是 7 位地址不需要左移这是初学者最容易搞混的地方。下面这段扫描代码可以直接放在setup()里用于验证 QMA6100P 和 XL9555 是否都被枚举到#include Wire.h void iic_scan() { byte error, address; int nDevices 0; Serial.println(Scanning I2C bus ...); for (address 1; address 127; address) { Wire.beginTransmission(address); error Wire.endTransmission(); if (error 0) { Serial.printf(IIC device found at 0x%02X\n, address); nDevices; } else if (error ! 2) { Serial.printf(Error %d at 0x%02X\n, error, address); } } if (nDevices 0) Serial.println(No IIC device found, check wiring and pull-up!); }这段代码通过逐地址发起事务并检查 ACK 来枚举总线上的从设备。error 0表示有设备应答error 2表示地址无响应属于正常情况。如果扫描结果只有0x00或者什么都没有优先排查上拉电阻和接线而不是寄存器配置。QMA6100P 的WHO_AM_I寄存器一般为0x00读回的值应与数据手册中的固定 ID 一致例程的qma6100p.h里把 ID 校验放在初始化流程中失败时会在串口打印QMA6100P ID mismatch。2.3 量程和 ODR 配置的代码落点QMA6100P 的量程配置通常涉及0x11附近的寄存器位段控制 ±2g/±4g/±8g/±16gODR输出数据速率与带宽滤波器在相邻寄存器配置。不同晶圆版本寄存器地址可能有差异例程里qma6100p.cpp的QMA6100P_Init()已经封装好建议不要照抄网络上的旧版 QMA7981 寄存器值以下是等价的初始化流程#define QMA6100P_ADDR 0x12 // 7-bit I2C address #define REG_WHO_AM_I 0x00 #define REG_ACC_CONFIG 0x11 bool qma6100p_init() { Wire.beginTransmission(QMA6100P_ADDR); Wire.write(REG_WHO_AM_I); Wire.endTransmission(false); Wire.requestFrom(QMA6100P_ADDR, 1); uint8_t id Wire.read(); if (id ! 0xE8 id ! 0x93) { Serial.printf(QMA6100P ID error: 0x%02X\n, id); return false; } // 配置为 ±2g 量程ODR 与带宽由 REG_ACC_CONFIG 的位段决定 Wire.beginTransmission(QMA6100P_ADDR); Wire.write(REG_ACC_CONFIG); Wire.write(0x03); // 具体位段请对照数据手册0x03 仅作示例 Wire.endTransmission(); return true; }这里Wire.endTransmission(false)发送寄存器地址后不释放总线紧接着requestFrom读取单字节省去了一次重复发起 start 的开销。0xE8和0x93是不同批次 QMA6100P 的 ID 取值如果你手头的模块两种都对不上先怀疑接线或供电电压例程在 ESP32-S3 3.3 V 供电下通常正常工作。量程配置位段每个版本的数据手册定义不同0x03只是占位写法务必以自己的模块资料为准。3. 从原始寄存器到三轴 g 值数据拼接与 XL9555 扩展 IO3.1 6 字节读数怎么拼成真正的加速度QMA6100P 在读取模式下支持一次 burst 读取 6 个字节分别对应 X_L、X_H、Y_L、Y_H、Z_L、Z_H。如果按单字节requestFrom(0x12, 1)的方式连读 6 次不仅浪费时间还可能因为每次 start/stop 之间的时间差导致读到新旧数据混叠。例程使用requestFrom(QMA6100P_ADDR, 6)一次把 6 字节全部取回数据更新一致性更好。以下是从imu.cpp里摘出的核心读取函数typedef struct { int16_t x; int16_t y; int16_t z; } accel_raw_t; bool qma6100p_read(accel_raw_t* out) { Wire.beginTransmission(QMA6100P_ADDR); Wire.write(0x02); // 从 X 轴低字节寄存器开始 Wire.endTransmission(false); Wire.requestFrom(QMA6100P_ADDR, 6); if (Wire.available() 6) return false; uint8_t xl Wire.read(); uint8_t xh Wire.read(); uint8_t yl Wire.read(); uint8_t yh Wire.read(); uint8_t zl Wire.read(); uint8_t zh Wire.read(); out-x (int16_t)((xh 8) | xl); out-y (int16_t)((yh 8) | yl); out-z (int16_t)((zh 8) | zl); return true; }这里的关键是从0x02开始读而不是从0x00因为前两个寄存器是 ID 和状态位。int16_t强制转换把 unsigned 的高位字节拼成 signed 值才能正确处理负数。但要注意QMA6100P 实际有效位数可能只有 12 位或 14 位低两位可能是符号扩展或噪声位。例程没有做右移对齐意味着你拿到的数值分辨率是每 LSB 对应的 g 值偏小。换算公式为acc_g raw_value * range / sensitivity其中range是配置的量程如 ±2g 对应 4gsensitivity是数据手册给出的满量程 LSB 数。比如某版本在 ±2g 下满量程 32768那么acc_g raw_value * 4.0 / 32768.0。如果你发现静止时 Z 轴读数在 16000 左右而不是 1g多半是没做除以 sensitivity 的换算直接把原始值当成 g 输出了。3.2 XL9555 在工程里的真实角色很多读者会疑惑加速度采集为什么需要一颗 XL9555它是一颗 16 位 IIC 扩展 GPIO 芯片地址由 A0/A1 引脚决定常见为0x20或0x21。本工程里的用途有两个一是扩展出足够的数字 IO 控制 LCD 背光和 LED 状态灯二是把需要切换电平的外部电路隔离在扩展 IO 后面避免频繁插拔影响 ESP32-S3 主控引脚。配置 XL9555 的流程比传感器更简单但有一个坑芯片内部有配置寄存器和输出寄存器上电后默认状态可能是输入模式。如果直接写输出寄存器而不先配置方向LED 不会亮。例程的xl9555.cpp里明确做了两步#define XL9555_ADDR 0x21 void xl9555_init() { Wire.beginTransmission(XL9555_ADDR); Wire.write(0x06); // 配置寄存器 0方向控制0 为输出 Wire.write(0x00); // Port0 全输出 Wire.write(0x00); // Port1 全输出 Wire.endTransmission(); Wire.beginTransmission(XL9555_ADDR); Wire.write(0x02); // 输出寄存器 0 Wire.write(0xFF); // Port0 全部拉高 Wire.write(0xFF); // Port1 全部拉高 Wire.endTransmission(); } void xl9555_set_led(uint8_t pin, bool level) { Wire.beginTransmission(XL9555_ADDR); Wire.write(0x02); Wire.endTransmission(false); Wire.requestFrom(XL9555_ADDR, 2); uint8_t p0 Wire.read(); uint8_t p1 Wire.read(); if (pin 8) { if (level) p0 | (1 pin); else p0 ~(1 pin); } else { if (level) p1 | (1 (pin - 8)); else p1 ~(1 (pin - 8)); } Wire.beginTransmission(XL9555_ADDR); Wire.write(0x02); Wire.write(p0); Wire.write(p1); Wire.endTransmission(); }这段代码演示了读-改-写流程。0x06是 Port0 方向寄存器地址写0x00表示全部引脚设为输出0x02是输出寄存器地址。实际操作时先读回当前输出状态再修改对应位避免覆盖其他引脚的电平状态。如果你的 LCD 背光不受控检查xl9555_init()是否在spilcd_init()之前调用因为 LCD 初始化过程会操作背光引脚顺序颠倒会导致背光始终保持默认状态。3.3 原始数据换算与滤波的一次性到位方案读取原始值后工程里imu.cpp还会做一次简单的低通滤波。这里建议不要只在串口打印原始值而是把换算和滤波封装成独立函数方便后续用到姿态解算里。常见的做法是一阶互补滤波float x_filtered 0.0f; #define ALPHA 0.2f float lowpass_filter(float raw, float prev) { return ALPHA * raw (1.0f - ALPHA) * prev; }ALPHA越大对新数据响应越快噪声也越大。对于静态倾角测量0.1~0.3是常用区间对于动态运动检测直接使用原始值可能更合适不要盲目滤波。4. LCD 显示与 UART 上报数据流向分层设计4.1 例程文件职责对照这个例程包里有19_iic_qma6100p.ino、imu.cpp、qma6100p.cpp、xl9555.cpp、spilcd.cpp、uart.cpp、led.cpp等多个文件初次接触的人会以为很乱实际上每个文件对应一条独立链路。以下是从代码组织角度的对照表文件职责关键对外函数19_iic_qma6100p.ino主循环状态机串联各模块setup()/loop()qma6100p.cpp传感器寄存器读写、ID 校验qma6100p_init()/qma6100p_read()imu.cpp数据换算、滤波、姿态角近似imu_update()xl9555.cppIO 扩展控制 LED 与背光xl9555_init()/xl9555_set_led()spilcd.cppSPI LCD 驱动、字符显示lcd_show_accel()uart.cpp串口帧封装、上位机协议uart_send_frame()这个分层的思路值得借鉴loop()里不直接操作寄存器而是调用imu_update()更新数据再调用lcd_show_accel()刷新显示最后通过uart_send_frame()上报。如果你想换成 OLED 或者改用蓝牙透传只需要替换显示层或传输层传感器层完全不用动。4.2 主循环与显示刷新节奏LCD 刷新不是越快越好ESP32-S3 主频虽然能跑到 240 MHz但SPI LCD的像素传输会占用大量总线时间而且人眼对 3D 加速度数字的刷新率需求不超过 20 Hz。例程里用millis()做了非阻塞定时这一点强烈建议保留。核心循环结构如下unsigned long last_display 0; const unsigned long DISPLAY_INTERVAL 50; // 20 Hz void loop() { accel_raw_t raw; if (qma6100p_read(raw)) { imu_update(raw.x, raw.y, raw.z); } if (millis() - last_display DISPLAY_INTERVAL) { last_display millis(); lcd_show_accel(imu_x, imu_y, imu_z); uart_send_frame(imu_x, imu_y, imu_z); led_status_toggle(); } }注意qma6100p_read()的调用频率由 IIC 总线速度决定而显示和上报频率由DISPLAY_INTERVAL决定两者解耦。如果你把传感器读取也放进定时器会降低 ODR 采样率导致运动检测的带宽下降。DISPLAY_INTERVAL取 50 ms 是平衡功耗与体验的经验值如果希望显示更流畅可以改为 30 ms但不建议低于 20 ms因为spilcd底层驱动刷新一帧字符 UI 本身就要 10 ms 左右。4.3 UART 帧格式与上位机解析串口打印原始三轴值可以用逗号分隔但真正给上位机或者串口屏用的时候需要帧格式。例程uart.cpp里定义了一个简单可靠的帧结构void uart_send_frame(float x, float y, float z) { uint8_t buf[14]; buf[0] 0xAA; // 帧头 buf[1] 0x55; // 帧类型加速度数据 int16_t xi (int16_t)(x * 100.0f); // 保留两位小数 int16_t yi (int16_t)(y * 100.0f); int16_t zi (int16_t)(z * 100.0f); memcpy(buf[2], xi, 2); memcpy(buf[4], yi, 2); memcpy(buf[6], zi, 2); uint8_t sum 0; for (int i 0; i 8; i) sum ^ buf[i]; buf[8] sum; // 校验 buf[9] 0x0D; // 帧尾 Serial2.write(buf, 10); }这里把浮点数乘以 100 转成整数传输避免了浮点字节序问题。校验用的是按字节异或比累加和更省 CPU 且对无符号字节友好。上位机解析时先找0xAA 0x55帧头再校验buf[8]最后除以 100.0 还原成 g 值。如果你用蓝牙模块接Serial2只要波特率匹配硬件流控通常不需要。5. 用逻辑分析仪验证 IIC 时序两个最常见的隐蔽坑这一章分享一个比 printf 调试更高效的验证技巧用 20 元价位的逻辑分析仪配合 PulseView 抓取 IIC 波形直接看设备应答和寄存器读写时序。接线只需要把逻辑分析仪的 CH0 接 SDA、CH1 接 SCL共地后点击 Capture然后在下拉菜单里选择 IIC 解码器把 SCL 设为 CH1、SDA 设为 CH0地址显示格式改成 7-bit。运行例程后你会看到主控发起的写序列是0x248 位写地址后跟寄存器地址和数据读序列则是0x24跟寄存器地址再发0x25读地址读回 6 字节。如果 PulseView 显示 NACK表示设备地址错误或者总线被占住常见原因是地址左移了一位。Wire库传入的0x12已经是 7 位地址库内部会左移成 8 位如果你误传了0x24实际发送的是0x48设备自然不应答。另一个隐蔽坑是Wire库的接收缓冲区只有 32 字节requestFrom(addr, 6)没问题但如果你同时读 XL9555 的方向寄存器和输出寄存器共 4 字节再叠加其他设备的 burst 读取超过 32 字节后多余数据会被丢弃。解决方法是把大块读取拆成多次或者使用i2c_master底层 API 配置更大的 ringbuffer。最后提一个上拉电阻取值3.3 V 供电下IIC 总线使用 4.7 kΩ 上拉电阻适用于 100 kbps 标准模式如果例程里把Wire.setClock调到 400 kbps建议换成 2.2 kΩ否则上升沿变缓高速通信时会出现随机读错数据。读取 QMA6100P 的 Z 轴数据在静止时偶尔跳变一个 LSB这属于正常噪声不要因为这个去修改滤波参数先确认波形边沿是否干净再动代码。本文还有配套的精品资源点击获取