Welcome to Ziv Low’s INA226 documentation!

This library component provides an easier way to use the INA226 power monitor IC. This C++ library is written specifically for the ESP-IDF platform (at least ESP-IDF v5.2).

Take a look at the provided example code for inspiration on how to use this library.

Indices and tables

API

class INA226 : public INA226_Driver 

Represents an INA226 device for current and power monitoring.

This class provides an interface for interacting with the INA226 device over I2C communication. It allows initializing the I2C bus, writing to and reading from the device registers, and handling I2C-related errors.

Public Functions

INA226(const gpio_num_t sda_io_num = static_cast<gpio_num_t>(CONFIG_I2C_MASTER_SDA), const gpio_num_t scl_io_num = static_cast<gpio_num_t>(CONFIG_I2C_MASTER_SCL), const uint16_t address = CONFIG_INA226_I2C_ADDRESS, const uint32_t scl_frequency = CONFIG_I2C_MASTER_FREQUENCY, const i2c_port_num_t i2c_port_num = static_cast<i2c_port_num_t>(CONFIG_I2C_MASTER_PORT_NUM))

Initializes the I2C of ESP-IDF.

Parameters:

sda_io_num – [in] GPIO number of SDA pin. Defaults to GPIO 21 for ESP32.
scl_io_num – [in] GPIO number of SCL pin. Defaults to GPIO 22 for ESP32.
address – [in] I2C address of INA226. Defaults to 0x40.
scl_frequency – [in] Frequency of SCL pin. Defaults to 100000.
i2c_port_num – [in] I2C port number.

INA226(i2c_master_bus_handle_t i2c_bus_handle, const uint16_t address = CONFIG_INA226_I2C_ADDRESS, const uint32_t scl_frequency = CONFIG_I2C_MASTER_FREQUENCY)

Initializes the INA226 using an existing I2C handle.

Parameters:

i2c_bus_handle – [in] Existing I2C bus handle to use for this INA226.
address – [in] I2C address of INA226. Defaults to 0x40.
scl_frequency – [in] Frequency of SCL pin. Defaults to 100000.

class INA226_Driver

INA226 driver class for controlling and accessing the INA226 power monitor IC.

The INA226_Driver class provides a set of functions to initialize the INA226, read various measurements, and configure its operating modes, averaging modes, conversion times, and alert triggers.

This class is designed to be inherited and implemented by a specific I2C driver for the target platform. The I2C_Write and I2C_Read functions are abstract and need to be implemented by the derived class.

Note

The INA226 is a power monitor IC that can measure shunt voltage, bus voltage, current, and power. It also supports various operating modes, averaging modes, and conversion times.

Note

The INA226_Driver class uses the std::expected type to handle errors and return values. If an error occurs, a std::runtime_error is returned with an error message.

Note

The INA226_Driver class is not thread-safe and should be used in a single-threaded environment.

Subclassed by INA226

Getters

int32_t GetShuntVoltage_uV()

Get the Shunt Voltage in micro-Volts.

Returns:: int32_t

int32_t GetBusVoltage_mV()

Get the Bus Voltage in milli-Volts.

Returns:: int32_t

int32_t GetCurrent_uA()

Get the Current in micro-Amps.

Returns:: int32_t

int32_t GetPower_uW()

Get the Power in micro-Watts.

Returns:: int32_t

uint16_t GetConfig()

Get the configuration register value.

Returns:: uint16_t

uint16_t GetManufacturerID()

Get the manufacturer ID.

Returns:: uint16_t

uint16_t GetDieID()

Get the die ID.

Returns:: uint16_t

OperatingMode GetOperatingMode()

Get the operating mode.

Returns:: OperatingMode

AveragingMode GetAveragingMode()

Get the averaging mode.

Returns:: AveragingMode

ConversionTime GetBusVoltageConversionTime()

Get the bus voltage conversion time.

Returns:: ConversionTime

ConversionTime GetShuntVoltageConversionTime()

Get the shunt voltage conversion time.

Returns:: ConversionTime

uint16_t GetAlertTriggerMask()

Get the alert trigger mask.

Returns:: uint16_t

uint16_t GetAlertLimitValue()

Get the alert limit value.

Returns:: uint16_t

Setters

void Reset(): Reset the INA226.

void Calibrate(const uint32_t ShuntResistor_mOhm = 100, const uint32_t MaxCurrent_A = 1)

Calibrate the INA226.

Note

Max current is limited by the value of shunt resistor. 0.1ohm shunt can measure up to (2^15 -1)* 2.5µV / 0.1ohm = 819175µA (=0.819175A)

Note

https://github.com/esphome/issues/issues/2999#issuecomment-1038148627

Parameters:

ShuntResistor_mOhm – [in] Shunt resistor value in milli-Ohms. Defaults to 100mOhm.
MaxCurrent_A – [in] Maximum current in Amps. Defaults to 1A.

void SetConfig(const uint16_t Config)

Set the configuration register value.

Parameters:: Config – [in] The configuration register value.

void SetOperatingMode(OperatingMode Mode)

Set the operating mode.

Parameters:: Mode – [in] The operating mode.

void SetAveragingMode(AveragingMode Mode)

Set the averaging mode.

Parameters:: Mode – [in] The averaging mode.

void SetBusVoltageConversionTime(ConversionTime Time)

Set the bus voltage conversion time.

Parameters:: Time – [in] The bus voltage conversion time.

void SetShuntVoltageConversionTime(ConversionTime Time)

Set the shunt voltage conversion time.

Parameters:: Time – [in] The shunt voltage conversion time.

void SetAlertTriggerMask(AlertTriggerMask AlertTriggerMask)

Set the alert trigger mask.

Note

If multiple functions are enabled, the highest significant bit position Alert Function (D15-D11) takes priority and responds to the Alert Limit Register.

Parameters:: AlertTriggerMask – [in] The alert trigger mask.

void SetAlertLimitValue(uint16_t AlertLimitValue)

Set the alert limit value.

Parameters:: AlertLimitValue – [in] The alert limit value.

Public Types

enum class Const : uint16_t

Values:

enumerator BUS_VOLTAGE_LSB_uV

enumerator SHUNT_VOLTAGE_LSB_nV

enumerator POWER_LSB_FACTOR

enumerator CONFIG_RESET_VALUE

enum class Register : uint8_t

Values:

enumerator CONFIGURATION

enumerator SHUNT_VOLTAGE

enumerator BUS_VOLTAGE

enumerator POWER

enumerator CURRENT

enumerator CALIBRATION

enumerator MASK_ENABLE

enumerator ALERT_LIMIT

enumerator MANUFACTURER_ID

enumerator DIE_ID

enum class ConfigMask : uint16_t

Values:

enumerator OPERATING_MODE

enumerator SHUNT_VOLTAGE_CONVERSION_TIME

enumerator BUS_VOLTAGE_CONVERSION_TIME

enumerator AVERAGING_MODE

enumerator RESET

enum class ConfigOffset : uint8_t

Values:

enumerator OPERATING_MODE

enumerator SHUNT_VOLTAGE_CONVERSION_TIME

enumerator BUS_VOLTAGE_CONVERSION_TIME

enumerator AVERAGING_MODE

enumerator RESET

enum class OperatingMode : uint8_t

Operating modes of INA226.

Select continuous, triggered, or power-down mode of operation. Defaults to continuous shunt and bus measurement mode.

Values:

enumerator POWER_DOWN: Power-down mode.

enumerator SHUNT_VOLTAGE_TRIGGERED: Shunt voltage triggered mode.

enumerator BUS_VOLTAGE_TRIGGERED: Bus voltage triggered mode.

enumerator SHUNT_AND_BUS_TRIGGERED: Shunt and bus voltage triggered mode.

enumerator ADC_OFF: ADC off mode.

enumerator SHUNT_VOLTAGE_CONTINUOUS: Continuous shunt voltage measurement mode.

enumerator BUS_VOLTAGE_CONTINUOUS: Continuous bus voltage measurement mode.

enumerator SHUNT_AND_BUS_CONTINUOUS: Continuous shunt and bus voltage measurement mode.

enum class AveragingMode : uint8_t

Averaging modes of INA226.

Select the number of samples to be averaged. Defaults to 1 sample.

Values:

enumerator SAMPLE_1: 1 sample

enumerator SAMPLE_4: 4 samples

enumerator SAMPLE_16: 16 samples

enumerator SAMPLE_64: 64 samples

enumerator SAMPLE_128: 128 samples

enumerator SAMPLE_256: 256 samples

enumerator SAMPLE_512: 512 samples

enumerator SAMPLE_1024: 1024 samples

enum class ConversionTime : uint8_t

Conversion times of INA226.

Select the conversion time for shunt and bus voltage measurements. Defaults to 1100us (=1.1ms).

Values:

enumerator TIME_140_uS: 140 microseconds

enumerator TIME_204_uS: 204 microseconds

enumerator TIME_332_uS: 332 microseconds

enumerator TIME_588_uS: 588 microseconds

enumerator TIME_1100_uS: 1100 microseconds

enumerator TIME_2116_uS: 2116 microseconds

enumerator TIME_4156_uS: 4156 microseconds

enumerator TIME_8244_uS: 8244 microseconds

enum class AlertTriggerMask : uint16_t

Alert trigger masks of INA226.

Select the alert trigger masks. Defaults to all disabled (Transparent mode).

Values:

enumerator SHUNT_OVER_VOLTAGE: Shunt over-voltage trigger mask.

enumerator SHUNT_UNDER_VOLTAGE: Shunt under-voltage trigger mask.

enumerator BUS_OVER_VOLTAGE: Bus over-voltage trigger mask.

enumerator BUS_UNDER_VOLTAGE: Bus under-voltage trigger mask.

enumerator POWER_OVER_LIMIT: Power over-limit trigger mask.

enumerator CONVERSION_READY: Conversion ready trigger mask.

enumerator ALERT_FUNCTION_FLAG: Alert function flag trigger mask.

enumerator CONVERSION_READY_FLAG: Conversion ready flag trigger mask.

enumerator MATH_OVERFLOW_FLAG: Math overflow flag trigger mask.

enumerator ALERT_POLARITY: Alert polarity trigger mask.

enumerator ALERT_LATCH_ENABLE: Alert latch enable trigger mask.

enumerator ERROR: Error trigger mask.

Public Functions

std::expected<void, std::runtime_error> InitDriver(const uint32_t ShuntResistor_mOhm = CONFIG_INA226_SHUNT_RESISTOR_MILLIOHMS, const uint32_t MaxCurrent_A = CONFIG_INA226_MAX_CURRENT_AMPS)

Initializes the INA226 driver.

Parameters:

ShuntResistor_mOhm – [in] Shunt resistor value in milli-Ohms. Defaults to 100mOhm.
MaxCurrent_A – [in] Maximum current in Amps. Defaults to 1A.

Returns:

std::expected<void, std::runtime_error>