INA228 电流 / 电压 / 功率监测模块
02526 黑板 · 03065 红板

/*
 * INA228 电流 / 电压 / 功率读取 —— ESP-IDF 裸寄存器示例
 *
 * 开发环境：VSCode + ESP-IDF v5.2 及以上（新版 I2C 驱动 driver/i2c_master.h）
 * 硬件    ：ESP32-S3 + INA228 模块（02526 黑板，采样电阻 R015 ≈ 0.015 Ω）
 * 接线    ：模块 VCC -> 3V3   GND -> GND   SDA -> GPIO8   SCL -> GPIO9
 *           VIN+ 接被测电源正极，VIN- 接负载正极（必须串联，见本页接线图）
 *
 * CMakeLists.txt：
 *   idf_component_register(SRCS "ina228_main.c" INCLUDE_DIRS "" REQUIRES driver)
 *
 * 说明：所有换算系数来自 TI 数据手册 SLYS021A。
 */
#include <stdio.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/i2c_master.h"
#include "esp_log.h"

static const char *TAG = "INA228";

#define I2C_PORT        I2C_NUM_0
#define PIN_SDA         8
#define PIN_SCL         9
#define INA228_ADDR     0x40      /* A1=A0=GND 时的地址；16 个地址范围 0x40~0x4F */

/* ---- 寄存器地址（手册 Table 7-3）---- */
#define REG_CONFIG          0x00
#define REG_ADC_CONFIG      0x01
#define REG_SHUNT_CAL       0x02
#define REG_VSHUNT          0x04  /* 24 位，高 20 位有效，有符号 */
#define REG_VBUS            0x05  /* 24 位，高 20 位有效，恒正   */
#define REG_DIETEMP         0x06  /* 16 位，有符号               */
#define REG_CURRENT         0x07  /* 24 位，高 20 位有效，有符号 */
#define REG_POWER           0x08  /* 24 位全有效，无符号，不移位 */
#define REG_MANUFACTURER_ID 0x3E  /* 应读回 0x5449 = "TI"        */
#define REG_DEVICE_ID       0x3F  /* 应读回 0x2281               */

/* ---- 改这两行就能适配别的板子 ---- */
#define R_SHUNT   0.015f   /* Ω，02526 黑板丝印 R015 */
#define I_MAX     10.0f    /* A，你打算测的最大电流   */

static i2c_master_dev_handle_t s_dev;
static float s_current_lsb;

static esp_err_t ina228_write16(uint8_t reg, uint16_t val)
{
    uint8_t buf[3] = { reg, (uint8_t)(val >> 8), (uint8_t)(val & 0xFF) };
    return i2c_master_transmit(s_dev, buf, sizeof(buf), 1000);
}

static esp_err_t ina228_read(uint8_t reg, uint8_t *buf, size_t len)
{
    return i2c_master_transmit_receive(s_dev, &reg, 1, buf, len, 1000);
}

static esp_err_t ina228_read16(uint8_t reg, uint16_t *out)
{
    uint8_t b[2];
    esp_err_t err = ina228_read(reg, b, 2);
    if (err == ESP_OK) *out = ((uint16_t)b[0] << 8) | b[1];
    return err;
}

/* 24 位寄存器：低 4 位是保留位，必须先右移 4 位，再按 20 位补码扩展符号。
   忘了移位读数会正好差 16 倍——这是自己写驱动最常踩的坑。 */
static esp_err_t ina228_read20_signed(uint8_t reg, int32_t *out)
{
    uint8_t b[3];
    esp_err_t err = ina228_read(reg, b, 3);
    if (err != ESP_OK) return err;

    int32_t raw = ((int32_t)b[0] << 16) | ((int32_t)b[1] << 8) | b[2];
    raw >>= 4;
    if (raw & 0x00080000) raw -= 0x00100000;   /* 20 位符号扩展 */
    *out = raw;
    return ESP_OK;
}

/* POWER 是 24 位全有效的无符号值，不移位 */
static esp_err_t ina228_read24_unsigned(uint8_t reg, uint32_t *out)
{
    uint8_t b[3];
    esp_err_t err = ina228_read(reg, b, 3);
    if (err != ESP_OK) return err;
    *out = ((uint32_t)b[0] << 16) | ((uint32_t)b[1] << 8) | b[2];
    return ESP_OK;
}

static void ina228_init(void)
{
    i2c_master_bus_config_t bus_cfg = {
        .clk_source                   = I2C_CLK_SRC_DEFAULT,
        .i2c_port                     = I2C_PORT,
        .scl_io_num                   = PIN_SCL,
        .sda_io_num                   = PIN_SDA,
        .glitch_ignore_cnt            = 7,
        .flags.enable_internal_pullup = true,
    };
    i2c_master_bus_handle_t bus = NULL;
    ESP_ERROR_CHECK(i2c_new_master_bus(&bus_cfg, &bus));

    i2c_device_config_t dev_cfg = {
        .dev_addr_length = I2C_ADDR_BIT_LEN_7,
        .device_address  = INA228_ADDR,
        .scl_speed_hz    = 400000,
    };
    ESP_ERROR_CHECK(i2c_master_bus_add_device(bus, &dev_cfg, &s_dev));

    /* 第一步永远是验身份：读不到这两个值，后面都白搭 */
    uint16_t id = 0;
    ESP_ERROR_CHECK(ina228_read16(REG_MANUFACTURER_ID, &id));
    ESP_LOGI(TAG, "MANUFACTURER_ID = 0x%04X (应为 0x5449)", id);
    ESP_ERROR_CHECK(ina228_read16(REG_DEVICE_ID, &id));
    ESP_LOGI(TAG, "DEVICE_ID       = 0x%04X (应为 0x2281)", id);

    /* ADC_CONFIG = 0xFB6A
       MODE=Fh 连续测量分流+总线+温度；三个转换时间都取 5h(1052us)；AVG=2h(平均16次)
       复位默认是 0xFB68（AVG=1 次），这里改成 16 次平均把读数稳住 */
    ESP_ERROR_CHECK(ina228_write16(REG_ADC_CONFIG, 0xFB6A));

    /* 校准（手册 Equation 2/3）：
       CURRENT_LSB = I_MAX / 2^19
       SHUNT_CAL   = 13107.2e6 * CURRENT_LSB * R_SHUNT
       注意：若把 CONFIG 的 ADCRANGE 置 1（±40.96mV 档），SHUNT_CAL 要再乘 4 */
    s_current_lsb = I_MAX / 524288.0f;
    uint16_t shunt_cal = (uint16_t)(13107.2e6f * s_current_lsb * R_SHUNT + 0.5f);
    ESP_ERROR_CHECK(ina228_write16(REG_SHUNT_CAL, shunt_cal));
    ESP_LOGI(TAG, "CURRENT_LSB = %.3f uA, SHUNT_CAL = %u (0x%04X)",
             s_current_lsb * 1e6f, shunt_cal, shunt_cal);
}

void app_main(void)
{
    ina228_init();

    while (1) {
        int32_t  vbus_raw = 0, vsh_raw = 0, cur_raw = 0;
        uint32_t pwr_raw  = 0;
        uint16_t temp_raw = 0;

        ESP_ERROR_CHECK(ina228_read20_signed(REG_VBUS,    &vbus_raw));
        ESP_ERROR_CHECK(ina228_read20_signed(REG_VSHUNT,  &vsh_raw));
        ESP_ERROR_CHECK(ina228_read20_signed(REG_CURRENT, &cur_raw));
        ESP_ERROR_CHECK(ina228_read24_unsigned(REG_POWER, &pwr_raw));
        ESP_ERROR_CHECK(ina228_read16(REG_DIETEMP,        &temp_raw));

        float vbus    = vbus_raw * 195.3125e-6f;          /* 195.3125 uV/LSB  */
        float vshunt  = vsh_raw  * 312.5e-9f;             /* 312.5 nV/LSB     */
        float current = cur_raw  * s_current_lsb;         /* A                */
        float power   = 3.2f * s_current_lsb * pwr_raw;   /* W，手册 Eq.5     */
        float die_c   = (int16_t)temp_raw * 7.8125e-3f;   /* 7.8125 m°C/LSB   */

        ESP_LOGI(TAG, "Bus=%.4f V  Shunt=%.3f mV  I=%.4f A  P=%.4f W  Tdie=%.2f C",
                 vbus, vshunt * 1000.0f, current, power, die_c);

        vTaskDelay(pdMS_TO_TICKS(500));
    }
}

/*
 * INA228 基础读取示例（Arduino）
 * 库：RobTillaart/INA228（库管理器搜 "INA228"）
 * 硬件：INA228 模块，采样电阻 0.015 Ω（02526 黑板 R015）
 * 接线：VCC->3V3/5V  GND->GND  SDA->A4(UNO)/GPIO21(ESP32)  SCL->A5(UNO)/GPIO22(ESP32)
 *       VIN+ 接电源正极，VIN- 接负载正极（串联！）
 */
#include "Wire.h"
#include "INA228.h"

INA228 INA(0x40);          // A1=A0=GND 时地址是 0x40

void setup()
{
  Serial.begin(115200);
  Wire.begin();            // ESP32 想指定引脚：Wire.begin(21, 22);

  if (!INA.begin())
  {
    Serial.println("找不到 INA228。请检查：");
    Serial.println("  1) VCC/GND/SDA/SCL 四根线");
    Serial.println("  2) 先跑 I2C Scanner 确认实际地址（可能不是 0x40）");
    while (1) delay(1000);
  }

  // 关键一步：告诉库你要测多大电流、板上电阻多少欧
  // 不设这个，电流和功率读数全是错的
  INA.setMaxCurrentShunt(10, 0.015);

  Serial.println("INA228 就绪");
}

void loop()
{
  Serial.print("总线电压 ");
  Serial.print(INA.getBusVoltage(), 4);
  Serial.print(" V   电流 ");
  Serial.print(INA.getCurrent(), 4);
  Serial.print(" A   功率 ");
  Serial.print(INA.getPower(), 4);
  Serial.print(" W   芯片温度 ");
  Serial.print(INA.getTemperature(), 2);
  Serial.println(" C");

  delay(500);
}