esp-iot-solution INA236 功率监测组件实战I2C 电流电压测量从接线到源码级解析【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution本篇技术指南围绕 esp-iot-solution 仓库中components/sensors/power_monitor/ina236组件的官方文档展开完整覆盖 INA236 芯片的硬件接线、API 参数、可直接复制的使用代码并结合仓库源码深入解析其寄存器初始化、电压/电流换算公式与 ALERT 中断机制。读完后你可以独立完成 INA236 电流监测模块的接入、驱动配置与数据读取同时理解 1.6 mV/LSB 与 3970 A/LSB 等换算系数背后的实现逻辑。1. INA236 是什么16 位 I2C 数字电流监测芯片INA236 是一款带 I2C 接口的 16 位数字电流监测器其 I2C 接口兼容 1.2 V、1.8 V、3.3 V 和 5.0 V 等宽范围数字总线电压。芯片通过监测外部采样电阻sense resistor两端的压降来工作并上报三组关键数据电流Current由采样电阻上的压降VSHUNT换算得到总线电压Bus Voltage即 VBUS直接测量被监测支路的供电电压功率Power由电压与电流乘积推算。在 ESP32 系列 SoC 项目中该组件的典型应用场景是监测某个外设或负载支路的实时功耗例如电机、传感器板卡或 USB 负载的电流/电压采样。仓库中该组件的定位是通过 I2C 模块读取外部 I2C 传感器数据的示例组件——它依赖仓库内的 i2c_bus 组件而非裸的 ESP-IDFi2c驱动这也使整条数据链路保持在 esp-iot-solution 的统一总线抽象之下。重要提示继承自官方文档当前组件power_monitor将在 0.1.2 版本之后迁移至power_measure组件此后不再单独维护。详见 INA236 CHANGELOG 中 v0.1.2 条目This component has been migrated to power_measure and will no longer be maintained.。新项目建议直接使用 power_measure 组件其中已包含 INA236 驱动 与统一的 power_measure_ina236.h 接口。本文仍以旧组件为主线讲解其原理与接线对两个组件均适用。2. 硬件接线GPIO 分配与上拉电阻官方文档给出的接线约定非常简洁核心信息如下I2C 主机引脚分配GPIO21作为 I2C 主机的SDA数据信号GPIO13作为 I2C 主机的SCL时钟信号连线方式传感器 SDA 接 GPIO21传感器 SCL 接 GPIO13无需外部上拉电阻驱动会启用内部上拉。这里无需外部上拉正是 i2c_bus 组件的价值点在 测试应用 的配置中sda_pullup_en与scl_pullup_en均设为GPIO_PULLUP_ENABLE由 ESP-IDF GPIO 内部上拉完成总线偏置。实际硬件上INA236 需要正确配置 I2C 地址A2/A1/A0 引脚本组件默认使用地址0x41对应头文件中的宏 INA236_I2C_ADDRESS_DEFAULT。另外如果希望利用 ALERT 引脚做阈值告警需将芯片 ALERT 引脚引出到某个 GPIO见第 5 节的中断机制文档示例中alert_en false、alert_pin -1表示不启用告警。3. 组件引入与依赖关系组件元数据 idf_component.yml 声明了完整的依赖约束依赖项要求说明idf4.4.2最低 ESP-IDF 版本i2c_bus*override_path: ../../../i2c_bus强制使用仓库内的 i2c_bus 组件避免拉取外部同名版本当前版本0.1.2即已迁移至 power_measure 的版本仓库中组件自身的 CMakeLists.txt 也印证了这条依赖链idf_component_register(SRC_DIRS . INCLUDE_DIRS include PRIV_INCLUDE_DIRS priv_include REQUIRES i2c_bus)在独立项目中接入该组件有两种方式在项目的main/idf_component.yml中声明espressif/ina236组件管理器会自动解析i2c_bus依赖本地路径方式测试应用采用了EXTRA_COMPONENT_DIRS相对路径 test_apps/CMakeLists.txtset(EXTRA_COMPONENT_DIRS $ENV{IDF_PATH}/tools/unit-test-app/components ../../ina236)4. API 一览ina236_config_t 与五个核心函数对外接口全部定义在 ina236.h共 5 个 API 1 个配置结构体// 配置结构体ina236.h L36-L42 typedef struct { i2c_bus_handle_t bus; /*! I2C 总线句柄i2c_bus_create 的返回值 */ bool alert_en; /*! 是否启用 ALERT 中断回调 */ uint8_t dev_addr; /*! I2C 从机地址默认 INA236_I2C_ADDRESS_DEFAULT (0x41) */ uint8_t alert_pin; /*! ALERT 引脚的 GPIO 编号不启用时可填 -1 */ int236_alert_cb_t alert_cb; /*! ALERT 触发时的回调函数 */ } ina236_config_t;函数原型作用创建esp_err_t ina236_create(ina236_handle_t *handle, ina236_config_t *config)分配句柄、创建 I2C 从机设备、初始化寄存器参数为空返回ESP_ERR_INVALID_ARG内存不足返回ESP_ERR_NO_MEM删除esp_err_t ina236_delete(ina236_handle_t handle)释放 I2C 设备、移除 GPIO ISR、释放内存读电压esp_err_t ina236_get_voltage(ina236_handle_t handle, float *volt)输出总线电压单位伏特V读电流esp_err_t ina236_get_current(ina236_handle_t handle, float *curr)输出电流单位安培A清掩码esp_err_t ina236_clear_mask(ina236_handle_t handle)读取并清零 MASK 寄存器解除告警锁存状态告警回调签名为void (*int236_alert_cb_t)(void *arg)注意头文件中的类型名为int236_alert_cb_t。5. 三步上手官方示例代码逐行解析下面完整保留官方文档的示例并补充参数注释ina236_handle_t ina236 NULL; i2c_bus_handle_t i2c_bus NULL; //Step1: Init I2C bus i2c_config_t conf { .mode I2C_MODE_MASTER, .sda_io_num I2C_MASTER_SDA_IO, // GPIO21数据信号 .sda_pullup_en GPIO_PULLUP_ENABLE, // 内部上拉无需外部电阻 .scl_io_num I2C_MASTER_SCL_IO, // GPIO13时钟信号 .scl_pullup_en GPIO_PULLUP_ENABLE, .master.clk_speed I2C_MASTER_FREQ_HZ, // 测试应用中为 100 kHz }; i2c_bus i2c_bus_create(I2C_MASTER_NUM, conf); // I2C_MASTER_NUM I2C_NUM_0 //Step2: Init ina236 ina236_config_t ina236_cfg { .bus i2c_bus, .dev_addr INA236_I2C_ADDRESS_DEFAULT, // 0x41 .alert_en false, // 不启用 ALERT 中断 .alert_pin -1, // 无 ALERT 引脚 .alert_cb NULL, }; esp_err_t err ina236_create(ina236, ina236_cfg); //Step3: Get Voltage and Current float vloatge 0; // 原文档变量名拼写如此 float current 0; ina236_get_voltage(ina236, vloatge); ina236_get_current(ina236, current);对应的 GPIO 与总线宏定义来自 测试应用源码#define I2C_MASTER_SCL_IO 13 /*! gpio number for I2C master clock */ #define I2C_MASTER_SDA_IO 21 /*! gpio number for I2C master data */ #define I2C_MASTER_NUM I2C_NUM_0 /*! I2C port number for master dev */ #define I2C_MASTER_FREQ_HZ 100000 /*! I2C master clock frequency */运行配置见 sdkconfig.defaults240 MHz 主频、FreeRTOS 1 kHz 时基、关闭任务看门狗、USB-Serial-JTAG 控制台——这是一份可直接复用的最小 sdkconfig 基线。ALERT 中断机制源码级补充当alert_en true时ina236_create内部会为alert_pin配置下降沿 GPIO 中断并注册用户回调ina236.c#L97-L106if (ina236-alert_en) { gpio_config_t io_conf {}; io_conf.intr_type GPIO_INTR_NEGEDGE; // ALERT 拉低有效时触发 io_conf.mode GPIO_MODE_INPUT; io_conf.pin_bit_mask (1ULL ina236-alert_pin); io_conf.pull_up_en 1; err gpio_config(io_conf); gpio_install_isr_service(ESP_INTR_FLAG_DEFAULT); gpio_isr_handler_add(ina236-alert_pin, ina236-cb, NULL); }注意gpio_isr_handler_add注册的是裸 ISR 风格回调回调函数运行在中断上下文内部只做置标志等轻量操作。ina236_delete会成对地移除该中断处理ina236.c#L111-L120。6. 寄存器初始化与换算公式源码深度解析6.1 寄存器地址映射私有头文件 ina_236_reg.h 定义了完整的寄存器地址表寄存器地址说明INA236_REG_CFG0x00配置模式/转换时间/平均/复位INA236_REG_VSHUNT0x01采样电阻压降INA236_REG_VBUS0x02总线电压INA236_REG_POWER0x03功率INA236_REG_CURRENT0x04电流INA236_REG_CALIBRATION0x05校准系数INA236_REG_MASK0x06告警掩码INA236_REG_ALERT_LIM0x07告警限INA236_REG_MAF_ID0x3E制造商/修订标识INA236_REG_DEVID0x3F器件 ID6.2 初始化流程ina236_reg_initina236.c#L41-L63 中的初始化序列分四步器件 ID 校验读取DEVID寄存器与常量0xA080INA236_DEVICE_ID比对成功则打印 Check ina236 id OK写入校准系数calibration 10写入CALIBRATION寄存器配置 CFG 寄存器ina236_reg_cfg_t cfg { .bit.adcrange 0, // 量程0固定 16 V 满量程模式与 1.2/1.8/3.3/5 V 总线均兼容 .bit.avg 0, // 不做平均单次转换 .bit.mode 0x07, // 111VSHUNT 与 VBUS 连续转换模式 .bit.rst 0, .bit.vbusct 0x02, // VBUS 转换时间 0x02 档 .bit.vshct 0x02, // VSHUNT 转换时间 0x02 档 };从位域注释ina_236_reg.h#L26-L37可以看到mode111即shunt and bus voltage continuous意味着芯片以连续方式更新电流与电压寄存器主机可随时读取最新值设置 MASK 寄存器mask.bit.cnvr 1启用连续转换完成比较这是 ALERT 功能生效的前提。6.3 电压与电流的换算公式读数到物理量的转换是两个核心公式// ina236.c L122-L129电压 esp_err_t ina236_get_voltage(ina236_handle_t handle, float *volt) { uint16_t buffer 0; ina236_read_reg(ina236, INA236_REG_VBUS, buffer); *volt buffer * 0.0016f; // LSB 1.6 mV return ESP_OK; } // ina236.c L131-L138电流 esp_err_t ina236_get_current(ina236_handle_t handle, float *curr) { uint16_t buffer 0; ina236_read_reg(ina236, INA236_REG_VSHUNT, buffer); *curr (int16_t)buffer / 3970.0f; // 有符号3970 A/LSB 由校准系数推得 return ESP_OK; }两个细节值得注意电压 LSB 为 1.6 mVVBUS寄存器高 15 位 × 0.0016 即得伏特值vbus位域在 ina_236_reg.h#L43-L49 中正是 15 位电流按有符号数处理VSHUNT先强转为int16_t再除以 3970.0。这一点在 CHANGELOG 中有迹可循——v0.1.1 修复了 missing handling of negative current负电流处理缺失的缺陷说明该(int16_t)强转是保证反向电流负载向总线灌电流读数正确的关键。3970 A/LSB 的电流系数与初始化时写入的calibration 10及采样电阻取值共同决定修改采样电阻后需同步调整该系数。6.4 底层读写与多字节组装所有寄存器访问经由 i2c_bus 的字节级 API 完成ina236.c#L27-L39static esp_err_t ina236_read_reg(ina236_t *ina236, uint8_t reg, uint16_t *data) { uint8_t ina236_data[2] { 0 }; esp_err_t ret i2c_bus_read_bytes(ina236-i2c_dev, reg, 2, ina236_data[0]); *data ((ina236_data[0] 8 | ina236_data[1])); // 大端高字节在前 return ret; }INA236 的 16 位寄存器采用高字节先传输的 I2C 约定组装时先移入首字节即可。7. 测试应用可运行的验证工程test_apps 是一个基于 Unity 的标准 ESP-IDF 测试工程测试用例 ina236_test.c 的验证流程ina236_test_init按第 5 节代码创建 I2C 总线与 INA236 句柄ina236_test_get_data循环 2 次读取电压/电流并按Voltage: %.2f V, Current: %.2f mA\n打印每次间隔 1 sina236_test_deinit删除 ina236 与 i2c_bus 资源setUp/tearDown通过heap_caps_get_free_size(MALLOC_CAP_8BIT/32BIT)前后对比以TEST_MEMORY_LEAK_THRESHOLD (-460)为阈值检查内存泄漏——这也是 esp-iot-solution 组件测试的通用规范。该工程的 main/CMakeLists.txt 通过PRIV_REQUIRES unity ina236链接被测组件可直接idf.py -p /dev/ttyXXX flash monitor复现整套接线验证。8. 版本演进与迁移说明CHANGELOG 记录了完整演进v0.1.02024-05-23初始版本v0.1.12025-07-24修复负电流处理缺陷v0.1.22025-09-24组件迁移至power_measure本组件停止维护。迁移目标是仓库中的 power_measure 组件其目录结构包含drivers/ina236、drivers/bl0937、drivers/bl0942多颗电量监测芯片驱动以及统一的 power_measure.h / power_measure_interface.h 接口抽象和 独立测试应用。从源码结构看旧组件中每芯片一套句柄 五个 API的模式在新组件中被收敛到统一的 power_measure 接口之下后续维护、Bug 修复与新芯片支持都将在power_measure下进行。9. 小结项目要点芯片INA23616 位 I2C 电流监测兼容 1.2/1.8/3.3/5.0 V 总线默认地址0x41INA236_I2C_ADDRESS_DEFAULT接线SDA→GPIO21SCL→GPIO13GPIO 内部上拉即可无需外部电阻关键 APIina236_create/ina236_get_voltage/ina236_get_current/ina236_delete初始化行为校验 DEVID0xA080写 calibration10CFG 置于连续转换模式MASK 使能 cnvr换算公式电压 VBUS 寄存器 × 1.6 mV电流 (int16_t)VSHUNT ÷ 3970 A依赖ESP-IDF ≥ 4.4.2 仓库内i2c_bus组件状态v0.1.2 起迁移至power_measure新项目请使用新组件掌握以上内容后你可以直接按第 5 节代码搭建 INA236 电流监测链路并在需要告警、更高采样率或统一电量管理时平滑切换到power_measure组件。【免费下载链接】esp-iot-solutionEspressif IoT Library. IoT Device Drivers, Documentations and Solutions.项目地址: https://gitcode.com/GitHub_Trending/es/esp-iot-solution创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
