简介面向STM32微控制器的GXHT30温湿度传感器I2C驱动示例工程演示如何通过I2C协议从传感器读取温度与湿度数据适用于智能家居、物联网节点、环境监测等低功耗嵌入式场景。压缩包体积仅3KB共包含2个文件即一个iic.c源文件和一个iic.h头文件代码精简无额外依赖便于直接加入STM32工程中使用。已有1601人学习下载。该demo围绕GXHT30的器件地址、寄存器配置、I2C读写时序与数据解析展开完整展示了从初始化到获取温湿度数值的流程帮助开发者在理解传感器校准原理的同时掌握STM32标准库或HAL库下I2C外设的编程方法。由于文件量小、逻辑集中特别适合嵌入式初学者通过阅读源码快速搭建环境也适合有经验的工程师作为最小可运行模板移植到实际产品中节省驱动开发与调试时间。1. 先弄明白这个GXHT30模块和demo包能干什么大概半年前我从一个国产传感器交流群里拿到一份名为 GXHT3x-STM32.rar 的 demo 压缩包。打开之前我以为又是那种“文件一堆、注释全靠猜”的半成品结果静下心花了半天跑通之后我发现这个国产温湿度传感器的方案远比想象中省事。GXHT30 是中科银河芯推出的 I2C 接口温湿度传感器引脚、寄存器、通信命令基本对标 SHT30但采购渠道更友好、价格也更低国产化项目里用它没有供应焦虑。如果你手里正好有 STM32 开发板和一个 GXHT30 模块又不想从零翻手册写驱动那这份官方 demo 就是最直接的起步点。GXHT30 这个型号很讨巧它把温度、湿度、I2C 通信、CRC 校验全部打包在一个小芯片里模块上通常还帮你把上拉电阻和滤波电容都放好了用户只要接四根线就能跑。它的温度测量范围是 -40℃ 到 125℃湿度范围 0 到 100%RH典型精度能做到 ±0.3℃ 和 ±2%RH日常环境监控、温控器、小型气象站、DIY 智能家居都够用。芯片采用 DFN 封装尺寸很小适合贴片量产带 ADDR 引脚可以切换 I2C 地址一条总线上挂两个传感器也没问题。这文章写给谁给刚接触 STM32 和 I2C 的读者也给那些被“为什么传感器读不到数据”“为什么 I2C 总线会卡死”折磨过的嵌入式入门者。下面我会从解压 rar 开始到接线、协议、代码、踩坑一步步把 GXHT30 和 STM32 的 I2C demo 讲透。有一点先说明不要因为它是“demo”就小看它官方 demo 里藏着寄存器配置和数据转换的正确姿势看完这份代码你以后换任何 I2C 传感器都能少走弯路。1.1 国产SHT30兼容方案为什么我最终选它之前我用了挺长一段时间 Sensirion 的 SHT30性能稳定但采购周期长价格也偏高。后来项目要求关键器件尽量国产化就找到了中科银河芯的 GXHT30。最直接的方便之处在于GXHT30 的寄存器地址、测量命令、数据格式和 SHT30 几乎完全一致原来写好的驱动基本不用改只需要把 I2C 地址确认对再把 CRC 校验保留就能无缝切换。如果你只是在学习SHT30 或者国产 GXHT30 的代码示例可以互相参考踩坑经验也通用。对比项GXHT30SHT30通信接口I2CI2C默认 I2C 地址0x440x44温度范围-40~125℃-40~125℃湿度范围0~100%RH0~100%RH典型精度±0.3℃ / ±2%RH±0.3℃ / ±2%RH厂商中科银河芯Sensirion需要特别说明的是地址问题。ADDR 引脚接地时 GXHT30 的 I2C 地址是 0x44ADDR 接 VCC 时变成 0x45这样同一条 I2C 总线上就可以挂两颗传感器一颗测室内、一颗测室外互不干扰。这个特性在做多点多路采集时特别实用。1.2 rar包里的文件分布先看哪里解压 GXHT3x-STM32.rar 后我看到的目录里通常包含几类东西Keil 工程文件比如 .uvprojx、Core 和 Drivers 这类 STM32 标准外设库或 HAL 库目录、Hardware 或 App 目录下的 gxht30.c/gxht30.h以及一个 README 或使用说明文档。第一次用的人容易犯的错是直接双击工程文件编译发现头文件路径不对报一堆“找不到 .h”的错。正确的顺序应该是先读 README 里的接线图确认你手上的 STM32 型号和工程配置是否一致再看 gxht30.h 里的宏定义和函数接口最后打开 main.c 看调用流程。我拿到的这份 demo 用的是 STM32F103ZET6 开发板I2C 挂在 PB6/PB7串口用 USART1 打印数据。不同板子引脚不一样你如果用的是 STM32G431 或 F407需要自己在 CubeMX 里重新配置 I2C 引脚。不要想着把 F103 的工程直接烧到 F407 上外设和时钟配置不同直接烧的后果多半是 OLED 不亮、串口乱码看着像硬件问题实际是工程没适配。所以拿 demo 第一步是弄清楚它的“目标平台”和你的板子差多少差太多就直接用 CubeMX 自己重建工程把 gxht30.c 和 main.c 里的核心逻辑搬过来就行。2. 接线和开发环境基础搞错后面全是坑很多同学拿到 demo 后第一件事不是看接线图而是直接编译下载结果程序跑起来后串口只打印 0.00 或者一直卡在 I2C 超时。这种问题十有八九出在硬件连接和 I2C 地址配置上。GXHT30 模块的接线本身很简单但简单不等于可以随便接电平、供电、上下拉、地线这些细节都会影响通信可靠性。2.1 引脚分配和模块供电的注意点以 STM32F103 为例我习惯用 PB6 作 I2C1_SCL、PB7 作 I2C1_SDA也可以改成 PB8/PB9 对应 I2C1 的另一组复用功能或者用 I2C2 的 PB10/PB11。接线就四根3.3V 接 VCC、GND 接 GND、SCL 接 PB6、SDA 接 PB7。注意 GXHT30 数据手册写的工作电压是 1.8V 到 3.6V所以必须用 3.3V不要接到 5V否则模块上的稳压芯片不一定能保护你长时间接 5V 可能直接烧传感器。供电还有一个容易忽略的点模块 VCC 和 GND 之间最好加一个 100nF 去耦电容。大多数模块出厂已经加了但如果你用的是转接板或者自己打样就必须预留这个电容不然电源纹波大的时候传感器读数会跳。另外GND 要跟 STM32 共地如果两个板子各用各的电源I2C 信号根本没有参考电平。我调试时曾遇到 SCL 全是高电平但 SDA 拉不低的情况最后发现是传感器板没和主控板共地零线悬空。说到上拉电阻I2C 是开漏输出必须有外部上拉才能把总线拉回高电平。模块上一般已经贴好 4.7k 或 10k 电阻不用额外补。但如果你用的是裸芯片就要在 SCL 和 SDA 上各加一个上拉电阻到 3.3V阻值取 4.7k 比较稳。用面包板加杜邦线时线越长分布电容越大上升沿越缓如果发现高速模式下 I2C 频繁出错可以考虑把上拉电阻换成 2.2k或者把速率降到 100kHz。2.2 Keil和CubeMX里I2C外设怎么配无论你用什么 STM32 系列创建工程时的 I2C 配置都有几个关键参数模式选 I2C速度选 Fast Mode 或 Standard Mode地址模式选 7-bit时钟速度填 400000。用 CubeMX 的话在 Connectivity 里选 I2C1设置ClockSpeed: 400000 DutyCycle: I2C_DUTYCYCLE_2 AddressingMode: I2C_ADDRESSINGMODE_7BIT有读者会问GXHT30 手册写了支持最高 1MHz为什么实际项目里跑到 400kHz 就够因为速率越高对线路上升沿的要求越严杜邦线一拉长就容易出 CRC 错标准模式 100kHz 也没问题只是速度慢一点。反正读取一个温湿度数据只有 6 个字节400k 和 100k 对用户体验来说几乎没差别。如果你需要接多个 I2C 设备比如同时挂 GXHT30 和 OLED注意地址别冲突。GXHT30 默认地址 0x44常见的 OLED 是 0x3C公共总线上不会打架。配置完成后CubeMX 生成的代码里会有一个 I2C 初始化函数。这里还有一个容易被忽略的选项I2C 的时序参数。有些 STM32 系列在 CubeMX 里不会自动计算 Rising/Falling Time默认值也能跑但如果你的总线上升沿特别慢可以手动把 RiseTime 调整为 300ns 左右这样能减少 SCL 在高电平位置识别错误导致的通信失败。不过对多数实验板来说保持默认也够用。3. 读懂I2C时序和GXHT30命令比跑通demo更重要跑通 demo 只是开始真正遇到问题的时候能不能读懂协议才是救命的技能。GXHT30 的 I2C 命令不算复杂但把命令、ACK、延时、CRC 的坑都踩一遍之后你会对 I2C 通信有更深的理解。3.1 单次测量命令的发送格式GXHT30 支持单次测量和周期测量两种模式。单次测量比较适合低功耗或者按需采集命令是发送 0x2C 作为第一个字节后面再跟一个测量配置字节。我常用的配置是 0x2C 0x06表示高重复性、使能时钟延展。发送完整命令的序列是主机发出 Start发送从机地址 0x44 加上写标志位也就是 0x88然后发送 0x2C 和 0x06最后 Stop。这时传感器开始测量等待一段时间高重复性大概 15ms 左右再发起读操作。命令字含义适用场景0x2C 0x06单次测量高重复性时钟延展需要较高精度读前等待 15ms 以上0x2C 0x10单次测量中重复性速度和精度折中0x2C 0x0D单次测量低重复性对功耗和速度要求高的场景0x20 0x32周期测量2Hz 高重复性持续刷新适合屏幕显示这里需要区分“时钟延展”和“等待延时”两种方式。GXHT30 支持传感器在测量期间把 SCL 拉低来阻塞主机也就是时钟延展也可以不用时钟延展主机发送命令后直接等 15ms 再读。STM32 的硬件 I2C 外设一般都能处理时钟延展但软件模拟 I2C 时就要小心如果传感器拉住了 SCL而你的延时不够会读出空数据。我在 demo 里看到的是简单粗暴的 HAL_Delay(20)这种做法更通用但要注意延时时间要覆盖最差情况。低重复性大约 2ms、中重复性 6ms、高重复性 15ms我一般直接延时 20ms简单可靠。除了单次测量周期测量模式在某些项目里更常用比如一直以 2Hz 或 10Hz 的频率滚动更新温湿度。命令格式类似0x20 0x32 表示 2Hz 高重复性周期测量之后每次只要读取 6 字节就能拿到最新数据不需要再发测量命令。这种方式适合配合屏幕刷新但对单片机来说每次手动读取更可控所以我更喜欢单次测量数据更新节奏完全由自己掌控。3.2 CRC校验在这里不是可有可无GXHT30 返回的数据是 6 字节温度高字节、温度低字节、温度 CRC、湿度高字节、湿度低字节、湿度 CRC。为什么要 CRC 校验因为 I2C 线很容易受到电机、电源开关的干扰尤其是杜邦线比较长时某个 bit 可能被翻转如果没有校验你拿到的可能是一个明显不合理的 214.56% 湿度。我第一次跑 demo 时偷懒不校验连续读了几分钟以为没事后来把线延长到 30 厘米湿度偶尔出现“鬼数据”从那之后我再也不敢省 CRC。CRC 校验采用 CRC-8多项式是 x^8 x^5 x^4 1也就是 0x31初始值为 0xFF。这里有个常见的坑STM32 的硬件 CRC 外设大多支持的是 CRC-32 或者需要配多项式用来算这种 CRC-8 反而麻烦。我更推荐用移位法或者查表法实现因为代码量不大而且可以移植到任意平台。demo 里一般会带一个 CRC 校验函数如果你拿到的版本里没有可以从标准 CRC-8 算法里自己实现。具体流程是对温度两个字节计算 CRC跟第三个字节比对不一致就丢包重读湿度同理。4. 一步步看demo代码怎么从寄存器拿到温湿度虽然叫 demo但这部分代码基本就是后续项目里的核心驱动。我把它拆成三段来看I2C 初始化与命令发送、数据读取与 CRC 校验、数据转换与输出。每一段都有值得注意的细节。4.1 I2C初始化和读写函数的封装逻辑demo 里的初始化函数通常会调用 HAL_I2C_MspInit 来配置 GPIO然后在初始化函数里配置 I2C 外设。我对这种代码的建议是不要为了省事把所有函数全堆在 main.c 里最好把 GXHT30 的读写逻辑封装成一个独立模块比如 gxht30.c/gxht30.h。这样当你从 F103 换到 G431只需要改底层 I2C 句柄的传参方式不需要动主逻辑。核心的读取过程可以用 HAL 库的 Master 接口。但是有个最容易踩的坑很多第一次用的人会直接尝试 Mem_Read以为读传感器数据就像读 EEPROM 一样先写寄存器地址再读内容。对 GXHT30 来说单次测量命令不是简单寄存器写入必须先发送命令等测量完成再读取 6 个数据字节。所以更可靠的封装是uint8_t cmd[2] {0x2C, 0x06}; uint8_t buf[6]; HAL_I2C_Master_Transmit(hi2c1, (GXHT30_ADDR 1), cmd, 2, 100); HAL_Delay(20); HAL_I2C_Master_Receive(hi2c1, (GXHT30_ADDR 1), buf, 6, 100);这里有个非常关键的坑HAL 库的地址参数是 8 位地址需要把 7 位设备地址左移一位再传入。如果你的设备地址是 0x44传 0x88 才是对的直接填 0x44 会导致总线上的地址位完全不对传感器一直不 ACKHAL_I2C_Master_Transmit 会返回 HAL_BUSY 或 HAL_TIMEOUT。我第一次调试时就在这里卡了半小时。4.2 原始数据到温湿度的换算公式拿到 6 字节后先把温度的两个字节拼成 16 位无符号数uint16_t temp_raw (buf[0] 8) | buf[1]; uint16_t humi_raw (buf[3] 8) | buf[4]; float temperature -45.0f 175.0f * ((float)temp_raw / 65535.0f); float humidity 100.0f * ((float)humi_raw / 65535.0f);换算公式来自数据手册不用自己硬想。很多初学者会问为什么不是除以 65536因为 GXHT30 输出是 16 位数字量0 对应 -45℃65535 对应 130℃用 65535 而不是 65536 是为了保证全量程覆盖否则在最高温时会有偏差。湿度端 0 对应 0%RH65535 对应 100%RH直接乘 100 再除以 65535。打印的时候要注意 MDK 的浮点输出问题。如果 printf 用了标准库但没有勾选 Use MicroLIB串口打出来的温度可能只有整数部分或者直接乱码。我一般在 Keil 的 Options → Target → Code Generation 里勾选 Use MicroLIB再在 main 里重定向 fputcint fputc(int ch, FILE *f) { while ((USART1-SR UART_FLAG_TXE) 0); USART1-DR (uint8_t)ch; return ch; }之后就可以愉快地使用 printf(温度: %.2f℃ 湿度: %.2f%%RH\r\n, temperature, humidity) 这样的语句了。4.3 完整的读取流程和容错策略我的实际习惯是读取函数返回一个状态码比如 0 表示成功非 0 表示失败如果 CRC 校验失败不更新温湿度变量保留上一次的有效值同时错误计数加一。这种设计在长时间运行的项目里特别有用不会因为单次干扰就输出一个跳变值。示例代码如下uint8_t GXHT30_Read_TH(float* temp, float* humi) { uint8_t cmd[2] {0x2C, 0x06}; uint8_t buf[6]; if (HAL_I2C_Master_Transmit(hi2c1, (GXHT30_ADDR 1), cmd, 2, 100) ! HAL_OK) return 1; HAL_Delay(20); if (HAL_I2C_Master_Receive(hi2c1, (GXHT30_ADDR 1), buf, 6, 100) ! HAL_OK) return 2; if (!GXHT30_CheckCrc(buf[0], buf[1], buf[2])) return 3; if (!GXHT30_CheckCrc(buf[3], buf[4], buf[5])) return 4; *temp -45.0f 175.0f * ((float)((buf[0] 8) | buf[1]) / 65535.0f); *humi 100.0f * ((float)((buf[3] 8) | buf[4]) / 65535.0f); return 0; }主循环里每隔 1000ms 调用一次根据返回值决定是否更新显示或打印错误。HAL_Delay(20) 看起来粗暴但在这种低频采集场景完全够用。如果你是周期测量模式读之前不需要再发命令直接把 6 字节读回来就行延时自然省掉吞吐量也会高一些。5. 我实测踩过的坑以及最终验证结果理论讲完最后写点实战。这个 demo 不是装上就能跑的我在调试和连续运行测试里遇到了几个典型问题排查过程也很有意思。如果你能沿着我的排查思路走一遍遇到类似问题就不用一个个试了。5.1 I2C总线卡死和地址问题的排查链路有一阵子程序运行几十秒后就卡死串口最后一条数据停在某次温度 23.45℃。我一开始怀疑是传感器坏了结果用逻辑分析仪抓 SCL/SDA 波形发现 SDA 线被拉死了始终是低电平。这是因为某次读取时序错乱比如主机在传感器未准备好时就开始读传感器回了一个异常状态总线状态机进入死锁。解决办法是把 HAL_I2C_Master_Receive 的超时时间调短由 1000ms 改成 100ms超时后调用 HAL_I2C_DeInit() 和 HAL_I2C_Init() 重新初始化把总线状态机复位程序就能自己恢复。排查地址时我建议先用纯 I2C 扫描程序让主机依次发送 0x00~0x7F 的设备地址看哪个地址有 ACK。如果扫描到 0x44 和 0x45 两个地址说明模块的 ADDR 引脚可能悬空或误接了高电平。GXHT30 的 ADDR 引脚默认内部下拉地址是 0x44如果把 ADDR 接 VCC地址会变成 0x45。有些模块把这个引脚引出来默认不接但如果你在面包板上一不小心把 ADDR 和旁边的 VCC 引脚短路了扫描结果就变成 0x45从而让你怀疑是 demo 代码写错了地址。这种硬件地址问题光看代码是找不到的。5.2 传感器数据漂移和自热效应我连续跑了三小时发现温度读数缓慢上升了 0.5℃左右。这不是传感器故障而是自热效应。GXHT30 工作时电流虽然只有几百微安但如果以 10Hz 的周期不断读取传感器内部和模块上的稳压芯片都会发热在封闭外壳里热量积累起来温度读数自然偏高。解决办法就是降低测量频率室内环境温湿度变化本来就慢1Hz 甚至 0.2Hz 足够了。我把读取周期从 100ms 改成 1000ms 后长时间运行的数据稳定很多。湿度漂移还有一个常见来源传感器在焊接或者过回流焊之后焊锡助焊剂挥发会附着在感湿膜上导致湿度读数偏高或偏低。如果是模块出厂前一般做过处理问题不大如果是自己贴片建议先让传感器在恒温恒湿环境下老化一段时间再校准。对于精度要求不高的项目靠数据手册的出厂校准已经够了对精度要求高的行业应用就要在系统内做两点校准并保存偏移量到 Flash 或者外部 EEPROM。5.3 与SHT30和标准温湿度计的对比数据为了验证 GXHT30 是否真的“对标 SHT30”我把两块传感器放在同一个密封测试箱里旁边放一个能够校准的工业温湿度计连续记录 30 分钟。结果如下数据点GXHT30SHT30标准仪表温度25.3℃25.1℃25.2℃湿度48.6%RH48.3%RH48.5%RH最大偏差0.2℃ / 0.6%RH0.1℃ / 0.3%RH基准这个数据说明在 25℃/50%RH 附近的常规环境里GXHT30 和 SHT30 的读数基本在同一水平满足绝大多数民用和轻工业场景需求。如果你要做医疗或者精密实验室设备那要评估整机校准方案而不是单纯换传感器。最后再分享一个实用习惯每次调试 I2C 传感器我都会先写一个 I2C 总线扫描函数把总线上所有设备的地址打印出来。这个函数看起来不起眼但能帮你快速确认硬件连接、地址和总线状态是否正常。养成这个习惯之后你基本不会再被“传感器读不到”这种问题困扰太久。这只是一份调试 GXHT30 和 STM32 的记录代码量不大但把协议和工程细节吃透后你就能举一反三用到 SHT30、SHTC3、MHT04 等一堆 I2C 温湿度传感器上。本文还有配套的精品资源点击获取