1. 代码开发工具用错,I2C 调试就只剩示波器可看
一块 HPM5E00EVK 开发板,一个 HT30 温湿度传感器,四根线接完上电,串口每秒刷一行 HT30 read data failed。这套代码开发工具我已经用了一段时间,第一反应是硬件问题,示波器夹上去却发现 SCL 上连一根毛都没有。折腾到后半夜才明白:SDK 已经把引脚复用、总线清除、主机初始化这些繁琐工作封装好了,我却还按裸机习惯直接改寄存器,顺序一乱,全盘皆输。
这篇写的就是怎么用 HPM SDK 把 I2C 主机和 HT30 从零读通:从认识 SDK 的目录,到写初始化和读写封装,再到接上传感器读温湿度、查状态寄存器,最后是几个我实际翻过车的点。手上有板子、想少走弯路的人可以跟着走一遍。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 代码开发工具链落地:先认清 SDK 里该改哪三个地方
拿到一套 SDK,最容易犯的错是从头到尾都在自己的应用文件里写寄存器。这样写出来的代码,换一块板子就废,换一版 SDK 就编译不过。HPM SDK 的设计是分得很清楚的:控制器操作在驱动里,时钟引脚延时的板级实现在板级文件里,器件协议在你的应用里。先把这三块的边界划出来,后面每一步都知道该改哪个文件。
2.1 驱动、板级、应用,各改各的
我一般按这个表来定位问题:
| 位置 | 你会碰到的符号 | 职责 | 改动频率 |
|---|---|---|---|
| SDK 驱动 | I2C_Type、i2c_config_t、i2c_init_master、i2c_master_read、i2c_master_write |
直接操作 I2C 控制器,处理起始位、地址位、ACK | 基本不改 |
| 板级实现 | board_init_i2c_clock、board_i2c_bus_clear、board_delay_ms、IOC_PAD_PC08 系列宏 |
时钟频率、引脚复用、上拉、毫秒延时 | 换板子必改 |
| 自己的应用 | ht30_* 系列函数、HT30_I2C_ADDR、命令宏 |
器件协议、数据换算、业务逻辑 | 自己维护 |
把这张表记住,调试时能省掉大量瞎猜。串口打出 failed to initialize i2c,问题几乎一定在板级那一行,不用去翻驱动源码;读回的数据 CRC 一直不对,那多半是应用层的命令帧或者等待时间有问题,跟控制器配置没关系。
2.2 引脚复用交给 IOC 的 FUNC_CTL,别手写寄存器
I2C 的引脚必须开漏加外部上拉,这一点大家都知道,但在这块板子上,它是由 PAD 控制寄存器里的几个位决定的。SDK 提供了现成的板级函数入口,我自己实现的时候是这么写的:
cpp复制void init_i2c_pins(I2C_Type *ptr)
{
if (ptr == HPM_I2C0) {
/* 把 PC08/PC09 的功能选择切到 I2C0 的 SCL/SDA */
HPM_IOC->PAD[IOC_PAD_PC08].FUNC_CTL = IOC_PC08_FUNC_CTL_I2C0_SCL | IOC_PAD_FUNC_CTL_LOOP_BACK_MASK;
HPM_IOC->PAD[IOC_PAD_PC09].FUNC_CTL = IOC_PC09_FUNC_CTL_I2C0_SDA | IOC_PAD_FUNC_CTL_LOOP_BACK_MASK;
/* 开漏输出 + 使能内部上拉 + 上拉选择 */
HPM_IOC->PAD[IOC_PAD_PC08].PAD_CTL = IOC_PAD_PAD_CTL_OD_SET(1) | IOC_PAD_PAD_CTL_PE_SET(1) | IOC_PAD_PAD_CTL_PS_SET(1);
HPM_IOC->PAD[IOC_PAD_PC09].PAD_CTL = IOC_PAD_PAD_CTL_OD_SET(1) | IOC_PAD_PAD_CTL_PE_SET(1) | IOC_PAD_PAD_CTL_PS_SET(1);
}
}
FUNC_CTL 那两行是在做引脚功能选择,把引脚从默认的 GPIO 状态切到 I2C0 的复用功能上。PAD_CTL 的三个位拆开看:OD_SET(1) 把引脚设为开漏,I2C 靠拉低来表达逻辑 0,推挽输出会跟从设备打架;PE_SET(1) 使能内部上拉,PS_SET(1) 选择上拉强度档位。很多板子在 SCL/SDA 上已经有 4.7k 外部上拉,内部上拉只是兜底,但这两个位不配,波形边沿会难看到让你怀疑人生。
上面这段里的 LOOP_BACK_MASK 需要单独说一句:它是引脚内部回环测试用的位,接真实器件的那一版我建议去掉,后面排查那一节会解释为什么。
2.3 从工程到第一行 printf
工程组织上,我做的最小验证是这样:新建应用文件,把 init_i2c_pins 和 board_init_i2c 放进去,main 里只留三行调用。
c复制#include "board.h"
#define TEST_I2C HPM_I2C0
int main(void)
{
board_init(); /* 板级基础初始化,调试串口在这里被配好 */
board_init_i2c(TEST_I2C); /* 内部失败会 printf 并停在 while(1) 里 */
printf("i2c bus ready\n");
while (1) {
/* 后面在这里加 HT30 的读取 */
}
}
board_init() 是 SDK 样例里的通用入口,负责把时钟树和调试串口拉起来;board_init_i2c(TEST_I2C) 就是我们自己写的那层板级封装,传进去的是控制器基地址指针,换成别的 I2C 实例就换这个宏。编译烧写之后,串口能稳定打出 i2c bus ready,说明时钟和引脚这两关已经过了。这一步看着不起眼,但它是整套代码开发工具链跑通的分水岭,后面所有调试都靠这一行 printf 输出日志。
如果这一步就卡住,不要急着改应用代码,先确认工程里有没有把板级文件一起编进去。缺文件时链接阶段通常会报未定义符号,但也有些构建配置会悄悄用一份空实现顶替,结果就是引脚压根没配。
3. 用 SDK 的 I2C API 写驱动:初始化顺序和两个读写函数
板的引脚配好之后,接下来是把 I2C 控制器本身启动起来。这一步顺序很关键:时钟没给、引脚没切、总线没清,直接调主机初始化,返回值可能还是成功,但发出去的数据没人应答。我见过不止一个项目在这卡了两天,最后发现是初始化顺序调换了。
3.1 四步初始化,一步都不能少
board_init_i2c 是我实际用的版本,四件事按固定顺序做:
cpp复制void board_init_i2c(I2C_Type *ptr)
{
i2c_config_t config;
hpm_stat_t stat;
uint32_t freq;
freq = board_init_i2c_clock(ptr); /* 1. 给控制器配置时钟,返回总线频率 */
init_i2c_pins(ptr); /* 2. 切引脚复用、开漏、上拉 */
board_i2c_bus_clear(ptr); /* 3. 清总线,处理从机把 SDA 拉死的情况 */
config.i2c_mode = i2c_mode_normal; /* 标准模式,不是快速模式 */
config.is_10bit_addressing = false;/* 用 7 位地址 */
stat = i2c_init_master(ptr, freq, &config);
if (stat != status_success) {
printf("failed to initialize i2c 0x%lx\n", (uint32_t) ptr);
while (1) {
}
}
}
第一步拿到的 freq 直接喂给 i2c_init_master,也就是说分频比是驱动根据实际时钟算的,你不需要自己填。第二步是上一节讲的引脚配置。第三步 board_i2c_bus_clear 值得展开:如果从设备在上一次通信中途掉电或复位,它可能一直把 SDA 拉在低电平,主机这时无论发什么都会认为总线忙。清总线的做法是发若干个时钟脉冲,让从机把剩余的位移完、释放总线,这是 I2C 协议里约定俗成的补救手段。
最后 i2c_init_master 拿到控制器指针、频率和配置结构体。i2c_mode_normal 对应标准速率,is_10bit_addressing = false 表示后面所有地址都按 7 位解释。失败时那句 printf 打印的是控制器基地址,方便你确认到底是哪个实例没起来;while(1) 在量产代码里当然要改成返回错误码,但在点亮阶段,让它停住比带着半配置的总线继续跑更安全。
3.2 读和写就两个函数,参数却各有讲究
初始化成功后,跟传感器打交道只剩两个接口:
c复制hpm_stat_t i2c_master_read(I2C_Type *ptr, const uint16_t device_address,
uint8_t *buf, const uint32_t size);
hpm_stat_t i2c_master_write(I2C_Type *ptr, const uint16_t device_address,
uint8_t *buf, const uint32_t size);
参数含义很直白:控制器指针、从机地址、缓冲区、字节数。返回统一是 hpm_stat_t,成功是 status_success。有两个地方容易踩:device_address 传的是 7 位地址,读写位由驱动内部拼,如果你照着某些手册把地址左移一位传进去,多数情况下会得到读失败或读回全 0xFF;写接口的 buf 没有加 const,但函数内部不会修改它,传常量数组时强转一下即可,不用为它单独拷一份。
地址这块再补一句:手头没有示波器的时候,最快的确认方式是先扫一遍地址。把 7 位地址从 0x08 到 0x77 逐个调 i2c_master_write 发一个字节,返回 status_success 的那个就是器件真实地址。这个方法不需要读数据,也不依赖 CRC,是排错时的第一把钥匙。
3.3 返回值只有 status_success 值得信任
我见过太多代码把读写函数的返回值直接丢掉,然后对着一个全零的结构体发愁。规则很简单:每一次 i2c_master_read 和 i2c_master_write 都要判返回值,判失败就打日志,日志里带上命令、地址和长度。
c复制if (status_success != i2c_master_write(TEST_I2C, HT30_I2C_ADDR, cmd_buf, 2)) {
printf("HT30 send command failed: 0x%04X\n", command);
return HT30_ERROR_MEASURE;
}
日志里那个 0x%04X 是命令字,出问题时一眼能看出卡在软复位还是测量命令上。这套日志习惯在只有串口可用的时候,价值不比调试器低,算是嵌入式调试里的黑匣子。另外注意延时用的是 board_delay_ms 而不是自己写的空循环,前者走的是板级时钟,换主频不用重算。
4. 接上 HT30:命令帧、CRC-8 和状态寄存器的完整闭环
总线通了,接下来全是器件协议的事。HT30 的交互模型是典型的“发命令—等转换—读结果”,中间有三处细节必须对上:命令字节序、转换等待时间、CRC 校验范围。任何一处错了,表现都差不多,要么读数全零,要么 CRC 报错,所以这三块我放在一起写。
4.1 16 位命令拆成大端两字节
HT30 的命令是 16 位的,线上传输是高字节在前:
cpp复制static ht30_error_t ht30_send_command(uint16_t command)
{
uint8_t cmd_buf[2];
cmd_buf[0] = (command >> 8) & 0xFF; /* 高字节先发 */
cmd_buf[1] = command & 0xFF; /* 低字节后发 */
if (status_success != i2c_master_write(TEST_I2C, HT30_I2C_ADDR, cmd_buf, 2)) {
printf("HT30 send command failed: 0x%04X\n", command);
return HT30_ERROR_MEASURE;
}
return HT30_OK;
}
这一层封装看着简单,价值在于把字节序固定在一个地方。如果哪天换一颗命令同样是 16 位、但字节序相反的器件,你只需要改这四行,不用去翻每个调用点。顺带说,command 用 uint16_t 接收,宏定义那边就别写成负数,否则右移会带符号扩展,高字节算出来是 0xFF。
4.2 先软复位,再谈测量
上电第一件事是软复位。传感器可能因为上次掉电时停在半途,内部状态机没归零,直接发测量命令会得到无效数据:
cpp复制ht30_error_t ht30_init(void)
{
printf("Initializing HT30 sensor...\n");
if (ht30_send_command(HT30_CMD_SOFT_RESET) != HT30_OK) {
printf("HT30 soft reset failed\n");
return HT30_ERROR_INIT;
}
board_delay_ms(10); /* 复位完成需要时间,10ms 是留了余量的值 */
printf("HT30 sensor initialized successfully\n");
return HT30_OK;
}
复位后的 10ms 延时不能省。我试过把延时去掉,读数时好时坏,加回来就稳定了——这类“玄学”问题十有八九是时序没等够。另外注意这个函数没有返回值检查之外的任何总线操作,也就是说软复位成功只能说明器件应答了,不代表数据一定对,真正的连通性验证要放到读状态寄存器那一步。
4.3 读六字节,两段 CRC 分别校验
高精度测量一次拿 6 个字节:温度高字节、温度低字节、温度 CRC、湿度高字节、湿度低字节、湿度 CRC。
cpp复制ht30_error_t ht30_read_temperature_humidity(ht30_data_t *data)
{
uint8_t rx_data[6];
uint16_t temp_raw, hum_raw;
if (ht30_send_command(HT30_CMD_MEASURE_HIGH) != HT30_OK) {
return HT30_ERROR_MEASURE;
}
board_delay_ms(20); /* 高精度测量典型 15ms,这里留到 20ms */
if (ht30_read_data(rx_data, 6) != HT30_OK) {
printf("HT30 read measurement data failed\n");
return HT30_ERROR_READ;
}
/* 温度两字节 + CRC;湿度两字节 + CRC,分别校验 */
if (ht30_calculate_crc(rx_data, 2) != rx_data[2]) {
printf("HT30 temperature CRC error\n");
return HT30_ERROR_CHECKSUM;
}
if (ht30_calculate_crc(&rx_data[3], 2) != rx_data[5]) {
printf("HT30 humidity CRC error\n");
return HT30_ERROR_CHECKSUM;
}
temp_raw = (rx_data[0] << 8) | rx_data[1];
data->temperature = -45.0f + 175.0f * ((float)temp_raw / 65535.0f);
hum_raw = (rx_data[3] << 8) | rx_data[4];
data->humidity = 100.0f * ((float)hum_raw / 65535.0f);
return HT30_OK;
}
注意 CRC 的校验范围是前两个字节,湿度那一段从 &rx_data[3] 开始算,不要图省事对 6 个字节一起算,那样永远对不上。等待时间取 20ms,是因为高精度档的典型转换时间是 15ms 左右,按典型值写会在温度低或者供电偏弱时偶发超时。
CRC 的实现是 CRC-8,多项式 0x31,初值 0xFF:
cpp复制static uint8_t ht30_calculate_crc(uint8_t *data, uint8_t len)
{
uint8_t crc = 0xFF;
uint8_t i, j;
for (i = 0; i < len; i++) {
crc ^= data[i];
for (j = 0; j < 8; j++) {
if (crc & 0x80) {
crc = (crc << 1) ^ 0x31; /* 最高位为 1 时异或多项式 */
} else {
crc = crc << 1;
}
}
}
return crc;
}
crc 声明成 uint8_t,左移时溢出位自然丢弃,这正是 CRC-8 想要的行为,不用额外掩码。这段代码是纯计算,不碰总线,所以可以单独拿出来用固定数据对拍,首字节和长度都对上就能确认实现没问题。
4.4 状态寄存器要按位看,不能按值等
状态寄存器是这颗器件最容易被忽略的部分,但它能告诉你复位有没有发生、命令有没有被处理、校验有没有出错:
cpp复制ht30_error_t ht30_read_status(uint8_t *status)
{
uint8_t rx_data[3];
if (ht30_send_command(HT30_CMD_STATUS) != HT30_OK) {
return HT30_ERROR_MEASURE;
}
board_delay_ms(10);
if (ht30_read_data(rx_data, 3) != HT30_OK) {
return HT30_ERROR_READ;
}
if (ht30_calculate_crc(rx_data, 2) != rx_data[2]) {
return HT30_ERROR_CHECKSUM;
}
*status = rx_data[1]; /* 第二个字节才是状态值 */
return HT30_OK;
}
状态值取的是 rx_data[1],不是 rx_data[0],这点在打印时很容易搞混。拿到状态字节之后,解析必须用位与,不能用等号:
cpp复制void ht30_print_data(ht30_data_t *data)
{
printf("Temperature: %.2f C\n", data->temperature);
printf("Humidity: %.2f %%RH\n", data->humidity);
printf("Status: 0x%02X", data->status);
if (data->status & 0x01) {
printf(" (Alert pending)");
} else if (data->status & 0x02) {
printf(" (Heater on)");
} else if (data->status & 0x10) {
printf(" (Reset detected)");
} else if (data->status & 0x20) {
printf(" (Command not processed)");
} else if (data->status & 0x40) {
printf(" (Write data checksum error)");
} else if (data->status & 0x80) {
printf(" (Write data error)");
}
printf("\n");
}
开头那句 status == 0x08 判“正常工作”的写法我不建议保留:0x08 这一位同时被解释成温度跟踪报警,两个含义撞在一起,用等号判断必然误报。状态位是掩码,每个位独立含义,正常状态就是各告警位都为 0,直接判 status & 0xFE 之类的组合更稳妥。还有一处:如果 ht30_read_temperature_humidity 内部没有给 data->status 赋值,打印出来的状态就是上一次残留的脏值,要么在读数据时顺手读一次状态,要么在结构体初始化时清零。
5. I2C 跑不通先看这五处:现象、原因和改法
这套链路我从头搭过不止一遍,下面五个问题每次都会遇到其中至少一个。它们的共同点是:现象看起来都像“硬件坏了”,实际原因全在代码配置里。
5.1 串口打出 failed to initialize i2c,然后卡死
现象:上电后串口只有一行 failed to initialize i2c 0x...,程序不再往下走。
原因:i2c_init_master 返回非成功,卡在了那个 while(1) 里。常见来源有两个:board_init_i2c_clock 没有针对这个控制器实例做时钟使能,或者 init_i2c_pins 里的引脚宏跟实际硬件接的不是同一组,控制器初始化时检测不到可用引脚。
解决:先在 init_i2c_pins 里加一行打印,确认 ptr == HPM_I2C0 这个判断真的进去了;再确认 board_init_i2c_clock 的返回值不为 0,为 0 说明时钟配置没生效,后面的分频全是错的。这两处都过了再去看引脚的 FUNC_CTL 宏是不是写成了别的实例。把 while(1) 改成返回错误码,至少能让后面的自检逻辑跑起来,不至于整机黑屏。
5.2 命令返回成功,读回的数据却是自己刚发的
现象:写命令返回 status_success,读数据也成功,但读回来的字节跟刚发出去的命令一模一样,接上真实传感器反而没反应。
原因:引脚 FUNC_CTL 里带了 IOC_PAD_FUNC_CTL_LOOP_BACK_MASK。这个位是给引脚做内部回环自测用的,置位后引脚在芯片内部自己接自己,外部器件根本收不到信号,你读到的是自己发出去的回声。
解决:接真实器件时把这几位去掉,FUNC_CTL 只保留功能选择那部分。这个位在单板自测阶段确实有用,可以确认控制器本身工作正常,但它和外部通信不能同时开。我一般会在板级文件里留一个宏开关,自测时打开,出货版本关掉。
5.3 温湿度能读,但 CRC 偶发报错
现象:大部分时候读数正常,隔几十次报一次 HT30 temperature CRC error 或 HT30 humidity CRC error,重试一次又好。
原因:一是测量等待时间按典型值给,20ms 改成 15ms 之后偶发率明显上升;二是 CRC 的校验范围写错,把 6 个字节一起算,那就会每次都错而不是偶发,这两种现象要区分开。
解决:确认等待时间不小于高精度档的典型转换时间并留余量;确认温度和湿度分别校验各自的前两字节;确认 CRC 初值是 0xFF、多项式是 0x31。如果偶发依旧,检查读 6 字节的那次操作有没有被别的事情打断——单线程轮询不容易出,一旦加了定时器中断或者任务调度,读事务被拆开就会拿到半截数据。
5.4 地址传了 8 位,读写全失败
现象:写命令直接返回失败,或者读回全 0xFF。
原因:把 7 位地址左移一位当成 8 位地址传了进去。SDK 这套接口收的是 7 位地址,读写位由驱动内部拼,多移一位等于把所有器件的地址都改了。
解决:统一按 7 位地址写宏定义,并在注释里标明这是 7 位。地址扫描法在这里特别有用:从 0x08 扫到 0x77,能应答的那个才是真实地址,比对着手册猜快得多。
5.5 状态寄存器误报“正常”,问题被掩盖
现象:数据偶尔明显不合理,但状态打印出来一切正常,排查方向被带偏。
原因:状态打印里用 status == 0x08 判正常工作,而 0x08 这一位本身又对应温度跟踪报警,两个判断打架;另外读取温湿度时没有同步更新 data->status,打印的是结构体里的残留值。
解决:所有状态位判断改成位与,正常状态用“告警位全为 0”来表达;状态值要么在每次读数据时一起刷新,要么结构体初始化时清零,别指望它自己变。状态寄存器是排查时序问题的第一手证据,“命令未被处理”这一位一旦置起来,基本就能确定是等待时间不够或者总线被占用。
6. 把这套驱动做成可复用组件:验证顺序和一个自检习惯
单个传感器跑通只是第一步,真正省时间的是把它整理成可以复用的形状,并且固化一套验证顺序。我现在的做法是:接口只暴露四个函数,上电流程固定成三步,任何一步不过就不往下走。
6.1 三层验证顺序,从底往上
第一步验总线:只做 i2c_master_write 发一个字节,看返回是不是 status_success,这一步不依赖器件协议。第二步验器件:发软复位、读状态寄存器,确认能拿到合法的状态字节。第三步才验数据:读温湿度、校验 CRC、看数值是否落在合理区间。三层里任何一层失败,都在那一层停下,不要带着上一层的疑问往下走,否则日志会互相干扰。
6.2 把接口收窄成四个函数
头文件里我只留这些声明,内部实现和宏全部藏进源文件:
c复制#ifndef HT30_H
#define HT30_H
#include <stdint.h>
typedef enum {
HT30_OK = 0,
HT30_ERROR_INIT,
HT30_ERROR_MEASURE,
HT30_ERROR_READ,
HT30_ERROR_CHECKSUM
} ht30_error_t;
typedef struct {
float temperature;
float humidity;
uint8_t status;
} ht30_data_t;
ht30_error_t ht30_init(void);
ht30_error_t ht30_read_temperature_humidity(ht30_data_t *data);
ht30_error_t ht30_read_status(uint8_t *status);
ht30_error_t ht30_check_connection(void);
#endif
ht30_check_connection 内部只调一次 ht30_read_status,专门用来自检,跟读数据的路径分开。返回错误码而不是布尔值,调用方才能区分是“没应答”还是“CRC 错”,日志里给出的信息量完全不同。命令宏、地址宏、CRC 函数都留在 .c 里,换器件时只改一个文件。
6.3 上电自检:状态寄存器加 CRC 计数
最后一个习惯:在初始化之后立刻读一次状态,把结果打进启动日志;同时在 CRC 校验失败的分支里加一个静态计数器,定期打印累计失败次数。温湿度这种慢变量,偶尔一次 CRC 错不影响业务,但失败率突然从千分之一涨到百分之一,往往意味着接线松动或者上拉电阻阻值不对。有了这个计数器,你不用盯着串口一行行看,扫一眼启动日志就知道链路稳不稳。
从那以后,我每接一个新的 I2C 器件,都强制先跑一遍地址扫描和状态寄存器自检,再谈读数据。这个习惯花不了五分钟,却能省掉一晚上的示波器。希望帮到你。
