INA228 high-precision power/energy/charge monitor driver. More...

#include <sfDevINA228.h>

Inheritance diagram for sfDevINA228:

Public Member Functions
	sfDevINA228 ()

sfTkError_t	calibrate (float shuntResOhms, float maxCurrentA)
	Calibrate the device for current and power measurements. More...

sfTkError_t	getShuntVoltage_mV (float &milliVolts)
	Read the shunt voltage in millivolts (24-bit VSHUNT, bits [23:4]). More...

sfTkError_t	getBusVoltage_V (float &volts)
	Read the bus voltage in Volts (24-bit VBUS, bits [23:4], 195.3125 uV/LSB). More...

sfTkError_t	getCurrent_A (float &amps)
	Read the calculated current in Amps (24-bit CURRENT, scaled by CURRENT_LSB). More...

sfTkError_t	getPower_W (float &watts)
	Read the calculated power in Watts (24-bit POWER, scaled by 3.2 * CURRENT_LSB). More...

sfTkError_t	getDieTemp_C (float &celsius)
	Read the die temperature in degrees Celsius (16-bit DIETEMP, 7.8125 m-deg-C/LSB). More...

sfTkError_t	getShuntVoltageRaw (int32_t &value)
	Read the raw 20-bit shunt voltage value (sign-extended). More...

sfTkError_t	getBusVoltageRaw (uint32_t &value)
	Read the raw 20-bit bus voltage value. More...

sfTkError_t	getCurrentRaw (int32_t &value)
	Read the raw 20-bit current value (sign-extended). More...

sfTkError_t	getPowerRaw (uint32_t &value)
	Read the raw 24-bit power value. More...

sfTkError_t	getEnergy_J (double &joules)
	Read the accumulated energy in Joules. More...

sfTkError_t	getCharge_C (double &coulombs)
	Read the accumulated charge in Coulombs. More...

Public Member Functions inherited from sfDevINA2XX
	sfDevINA2XX ()

sfTkError_t	begin (sfTkIBus *theBus=nullptr)
	Initialize the device driver with the given bus. More...

void	setCommunicationBus (sfTkIBus *theBus)
	Set the communication bus pointer. More...

sfTkError_t	getManufacturerID (uint16_t &id)
	Read the Manufacturer ID register (0x3E). More...

sfTkError_t	getDeviceID (uint16_t &id)
	Read the Device ID register (0x3F). More...

sfTkError_t	reset (void)
	Perform a full system reset via the RST bit in CONFIG. More...

sfTkError_t	resetAccumulators (void)
	Reset the energy and charge accumulators (INA228 RSTACC bit). More...

sfTkError_t	setADCRange (bool reducedRange)
	Set the ADC full-scale shunt range. More...

sfTkError_t	getADCRange (bool &reducedRange)
	Get the current ADC range setting. More...

sfTkError_t	setConversionDelay (uint8_t delay2ms)
	Set the initial conversion delay in 2ms steps. More...

sfTkError_t	getConversionDelay (uint8_t &delay2ms)
	Get the current conversion delay setting. More...

sfTkError_t	enableTempCompensation (bool enable)
	Enable or disable shunt temperature compensation. More...

sfTkError_t	getTempCompensation (bool &enabled)
	Get the temperature compensation enable state. More...

sfTkError_t	setADCMode (sfe_ina2xx_mode_t mode)
	Set the ADC operating mode. More...

sfTkError_t	getADCMode (sfe_ina2xx_mode_t &mode)
	Get the current ADC operating mode. More...

sfTkError_t	setBusVoltageConvTime (sfe_ina2xx_conv_time_t time)
	Set the bus voltage conversion time. More...

sfTkError_t	getBusVoltageConvTime (sfe_ina2xx_conv_time_t &time)
	Get the bus voltage conversion time. More...

sfTkError_t	setShuntVoltageConvTime (sfe_ina2xx_conv_time_t time)
	Set the shunt voltage conversion time. More...

sfTkError_t	getShuntVoltageConvTime (sfe_ina2xx_conv_time_t &time)
	Get the shunt voltage conversion time. More...

sfTkError_t	setTempConvTime (sfe_ina2xx_conv_time_t time)
	Set the temperature conversion time. More...

sfTkError_t	getTempConvTime (sfe_ina2xx_conv_time_t &time)
	Get the temperature conversion time. More...

sfTkError_t	setAveragingCount (sfe_ina2xx_avg_count_t count)
	Set the ADC averaging count. More...

sfTkError_t	getAveragingCount (sfe_ina2xx_avg_count_t &count)
	Get the current ADC averaging count. More...

sfTkError_t	setShuntCal (uint16_t calValue)
	Write a raw value to the SHUNT_CAL register. More...

sfTkError_t	getShuntCal (uint16_t &calValue)
	Read the current SHUNT_CAL register value. More...

sfTkError_t	setShuntTempCoefficient (uint16_t ppmPerDegC)
	Set the shunt temperature coefficient for temperature compensation. More...

sfTkError_t	getShuntTempCoefficient (uint16_t &ppmPerDegC)
	Get the shunt temperature coefficient. More...

sfTkError_t	getDiagnosticFlags (sfe_ina2xx_diag_alrt_reg_t &flags)
	Read the full DIAG_ALRT register. More...

sfTkError_t	setAlertLatch (bool latched)
	Enable or disable alert latching. More...

sfTkError_t	getAlertLatch (bool &latched)
	Get the alert latch setting. More...

sfTkError_t	setConversionReadyAlert (bool enable)
	Enable conversion ready flag on the ALERT pin. More...

sfTkError_t	getConversionReadyAlert (bool &enabled)
	Get the conversion ready alert enable state. More...

sfTkError_t	setSlowAlert (bool enable)
	Enable alert comparison on averaged (vs. More...

sfTkError_t	getSlowAlert (bool &enabled)
	Get the slow alert enable state. More...

sfTkError_t	setAlertPolarity (bool activeHigh)
	Set the ALERT pin polarity. More...

sfTkError_t	getAlertPolarity (bool &activeHigh)
	Get the ALERT pin polarity setting. More...

sfTkError_t	isEnergyOverflow (bool &overflow)
	Check if the energy register has overflowed (INA228 only). More...

sfTkError_t	isChargeOverflow (bool &overflow)
	Check if the charge register has overflowed (INA228 only). More...

sfTkError_t	isMathOverflow (bool &overflow)
	Check if a math overflow has occurred in current/power calculations. More...

sfTkError_t	isTempOverLimit (bool &overLimit)
	Check if the temperature over-limit flag is set. More...

sfTkError_t	isShuntOverVoltage (bool &overVoltage)
	Check if the shunt overvoltage flag is set. More...

sfTkError_t	isShuntUnderVoltage (bool &underVoltage)
	Check if the shunt undervoltage flag is set. More...

sfTkError_t	isBusOverVoltage (bool &overVoltage)
	Check if the bus overvoltage flag is set. More...

sfTkError_t	isBusUnderVoltage (bool &underVoltage)
	Check if the bus undervoltage flag is set. More...

sfTkError_t	isPowerOverLimit (bool &overLimit)
	Check if the power over-limit flag is set. More...

sfTkError_t	isConversionReady (bool &ready)
	Check if a conversion has completed. More...

sfTkError_t	isMemoryValid (bool &valid)
	Check the memory checksum status. More...

sfTkError_t	setShuntOverVoltageThreshold (int16_t threshold)
	Set the shunt overvoltage threshold. More...

sfTkError_t	getShuntOverVoltageThreshold (int16_t &threshold)
	Get the shunt overvoltage threshold. More...

sfTkError_t	setShuntUnderVoltageThreshold (int16_t threshold)
	Set the shunt undervoltage threshold. More...

sfTkError_t	getShuntUnderVoltageThreshold (int16_t &threshold)
	Get the shunt undervoltage threshold. More...

sfTkError_t	setBusOverVoltageThreshold (uint16_t threshold)
	Set the bus overvoltage threshold. More...

sfTkError_t	getBusOverVoltageThreshold (uint16_t &threshold)
	Get the bus overvoltage threshold. More...

sfTkError_t	setBusUnderVoltageThreshold (uint16_t threshold)
	Set the bus undervoltage threshold. More...

sfTkError_t	getBusUnderVoltageThreshold (uint16_t &threshold)
	Get the bus undervoltage threshold. More...

sfTkError_t	setTempLimitThreshold (int16_t threshold)
	Set the temperature over-limit threshold. More...

sfTkError_t	getTempLimitThreshold (int16_t &threshold)
	Get the temperature over-limit threshold. More...

sfTkError_t	setPowerLimitThreshold (uint16_t threshold)
	Set the power over-limit threshold. More...

sfTkError_t	getPowerLimitThreshold (uint16_t &threshold)
	Get the power over-limit threshold. More...

Static Protected Attributes
static constexpr float	kCalScale = 13107.2e6f
	Calibration scale constant. More...

static constexpr float	kShuntLSBDefault = 312.5e-9f
	Shunt LSB in volts (ADCRANGE = 0). More...

static constexpr float	kShuntLSBReduced = 78.125e-9f
	Shunt LSB in volts (ADCRANGE = 1). More...

static constexpr float	kBusLSB = 195.3125e-6f
	Bus voltage LSB in volts. More...

static constexpr float	kTempLSB = 7.8125e-3f
	Die temperature LSB in deg-C. More...

static constexpr float	kCurrentFullScale = 524288.0f
	2^19, positive half of the 20-bit ADC. More...

static constexpr float	kPowerLSBScale = 3.2f
	Power LSB = 3.2 x CURRENT_LSB. More...

static constexpr uint8_t	kDieTempShift = 0
	DIETEMP is a full 16-bit value. More...

static constexpr double	kEnergyLSBScale = 16.0 * 3.2
	Energy LSB = 16 x 3.2 x CURRENT_LSB. More...

Static Protected Attributes inherited from sfDevINA2XX
static const uint8_t	kI2CAddress = 0x40
	Default 7-bit I2C address for the SparkFun Qwiic Power Monitor board. More...

static const uint8_t	kRegConfig = 0x00
	Configuration register (16-bit, R/W) More...

static const uint8_t	kRegAdcConfig = 0x01
	ADC Configuration register (16-bit, R/W) More...

static const uint8_t	kRegShuntCal = 0x02
	Shunt Calibration register (16-bit, R/W) More...

static const uint8_t	kRegShuntTempCo = 0x03
	Shunt Temperature Coefficient (16-bit, R/W) More...

static const uint8_t	kRegVShunt = 0x04
	Shunt Voltage Measurement (24/16-bit, R) More...

static const uint8_t	kRegVBus = 0x05
	Bus Voltage Measurement (24/16-bit, R) More...

static const uint8_t	kRegDieTemp = 0x06
	Die Temperature Measurement (16-bit, R) More...

static const uint8_t	kRegCurrent = 0x07
	Current Result (24/16-bit, R) More...

static const uint8_t	kRegPower = 0x08
	Power Result (24-bit, R) More...

static const uint8_t	kRegEnergy = 0x09
	Energy Result (40-bit, R) – INA228 only. More...

static const uint8_t	kRegCharge = 0x0A
	Charge Result (40-bit, R) – INA228 only. More...

static const uint8_t	kRegDiagAlrt = 0x0B
	Diagnostic Flags and Alert (16-bit, R/W) More...

static const uint8_t	kRegSOVL = 0x0C
	Shunt Overvoltage Threshold (16-bit, R/W) More...

static const uint8_t	kRegSUVL = 0x0D
	Shunt Undervoltage Threshold (16-bit, R/W) More...

static const uint8_t	kRegBOVL = 0x0E
	Bus Overvoltage Threshold (16-bit, R/W) More...

static const uint8_t	kRegBUVL = 0x0F
	Bus Undervoltage Threshold (16-bit, R/W) More...

static const uint8_t	kRegTempLimit = 0x10
	Temperature Over-Limit Threshold (16-bit, R/W) More...

static const uint8_t	kRegPowerLimit = 0x11
	Power Over-Limit Threshold (16-bit, R/W) More...

static const uint8_t	kRegManufacturerID = 0x3E
	Manufacturer ID (16-bit, R) – reads 0x5449 ("TI") More...

static const uint8_t	kRegDeviceID = 0x3F
	Device ID (16-bit, R) More...

static const uint16_t	kShuntCalMask = 0x7FFF
	SHUNT_CAL valid bits [14:0] (bit 15 reserved) More...

static const uint16_t	kBusThresholdMask = 0x7FFF
	BOVL/BUVL valid bits [14:0] (bit 15 reserved) More...

static const uint16_t	kShuntTempCoMask = 0x3FFF
	TEMPCO field mask, bits [13:0]. More...

static const uint16_t	kINA228DeviceIDValue = 0x2280
	INA228 device ID (upper 12 bits) More...

static const uint16_t	kINA237DeviceIDValue = 0x2370
	INA237 device ID (upper 12 bits) More...

static const uint16_t	kINA238DeviceIDValue = 0x2380
	INA238 device ID (register-compatible with INA237) More...

static const uint16_t	kDeviceIDMask = 0xFFF0
	Mask for device ID (ignore revision) More...

static const uint16_t	kManufacturerIDValue = 0x5449
	"TI" in ASCII More...

Additional Inherited Members
Protected Member Functions inherited from sfDevINA2XX
sfTkError_t	readRegister24 (uint8_t reg, uint32_t &value)
	Read 3 bytes (24-bit) from a register into a uint32_t. More...

sfTkError_t	readRegister40 (uint8_t reg, uint64_t &value)
	Read 5 bytes (40-bit) from a register into a uint64_t. More...

sfTkError_t	calibrateImpl (float shuntResOhms, float maxCurrentA, float calScale, float currentFullScale)
	Shared calibration math; only the two scale constants differ per device. More...

sfTkError_t	powerToWatts (float &watts, float powerLSBScale)
	Shared POWER -> watts conversion. `powerLSBScale` is 3.2 (INA228) or 0.2 (INA237). More...

sfTkError_t	dieTemperatureToCelsius (float &celsius, uint8_t shift, float tempLSB)
	Shared DIETEMP -> Celsius conversion. More...

sfTkError_t	readPowerRaw (uint32_t &value)
	Shared raw POWER read (24-bit, unsigned) — identical on both devices. More...

template<typename T , bool Wide>
sfTkError_t	readSignedMeasurementRaw (uint8_t reg, T &value)
	Shared raw read for a signed measurement register (shunt voltage, current). More...

template<typename T , bool Wide>
sfTkError_t	readUnsignedMeasurementRaw (uint8_t reg, T &value)
	Shared raw read for an unsigned measurement register (bus voltage). More...

template<typename T , bool Wide>
sfTkError_t	shuntVoltageToMilliVolts (float &milliVolts, float lsbDefault, float lsbReduced)
	Shared VSHUNT -> millivolts conversion (reads raw, then scales by the range LSB). More...

template<typename T , bool Wide>
sfTkError_t	busVoltageToVolts (float &volts, float busLSB)
	Shared VBUS -> volts conversion. More...

template<typename T , bool Wide>
sfTkError_t	currentToAmps (float &amps)
	Shared CURRENT -> amps conversion (scales by the calibrated CURRENT_LSB). More...

Protected Attributes inherited from sfDevINA2XX
sfTkIBus *	_theBus
	Pointer to the communication bus device. More...

float	_currentLSB
	Current measurement LSB in Amps, set during calibration. More...

bool	_adcRange
	Cached ADC range: false = +/-163.84mV, true = +/-40.96mV. More...

float	_shuntRes
	Shunt resistance in Ohms, stored during calibration. More...

Detailed Description

INA228 high-precision power/energy/charge monitor driver.

Inherits shared configuration from sfDevINA2XX and forwards each measurement to the matching shared helper (templated on the INA228's 24-bit register width), adding the INA228-only 40-bit energy and charge accumulation.

Constructor & Destructor Documentation

◆ sfDevINA228()

sfDevINA228::sfDevINA228 ( )

inline

Member Function Documentation

◆ calibrate()

sfTkError_t sfDevINA228::calibrate	(	float	shuntResOhms,
		float	maxCurrentA
	)

inline

Calibrate the device for current and power measurements.

Computes CURRENT_LSB from maxCurrent and the 20-bit ADC range (2^19), then calculates SHUNT_CAL = 13107.2e6 * CURRENT_LSB * Rshunt (x4 if ADCRANGE=1).

Parameters

shuntResOhms	Shunt resistance in Ohms (e.g., 0.015 for 15 mOhm).
maxCurrentA	Maximum expected current in Amps.

Returns: ::ksfTkErrOk on success, ::ksfTkErrFail for invalid arguments, or an error code on communication failure.

◆ getBusVoltage_V()

sfTkError_t sfDevINA228::getBusVoltage_V ( float & volts )

inline

Read the bus voltage in Volts (24-bit VBUS, bits [23:4], 195.3125 uV/LSB).

Parameters

volts Output reference that receives the bus voltage in V.

Returns: ::ksfTkErrOk on success, or an error code on failure.

◆ getBusVoltageRaw()

sfTkError_t sfDevINA228::getBusVoltageRaw ( uint32_t & value )

inline

Read the raw 20-bit bus voltage value.

Parameters

value Output reference that receives the unsigned 20-bit value.

Returns: ::ksfTkErrOk on success, or an error code on failure.

◆ getCharge_C()

sfTkError_t sfDevINA228::getCharge_C ( double & coulombs )

Read the accumulated charge in Coulombs.

Reads the 40-bit CHARGE register (two's complement) and scales by CURRENT_LSB.

Note: calibrate() must be called before this method returns meaningful values.

Parameters

coulombs Output reference that receives the charge in Coulombs.

Returns: ::ksfTkErrOk on success, or an error code on failure.

◆ getCurrent_A()

sfTkError_t sfDevINA228::getCurrent_A ( float & amps )

inline

Read the calculated current in Amps (24-bit CURRENT, scaled by CURRENT_LSB).

Note: calibrate() must be called before this method returns meaningful values.

Parameters

amps	Output reference that receives the current in A.

Returns: ::ksfTkErrOk on success, or an error code on failure.

◆ getCurrentRaw()

sfTkError_t sfDevINA228::getCurrentRaw ( int32_t & value )

inline

Read the raw 20-bit current value (sign-extended).

Parameters

value Output reference that receives the signed 20-bit value.

Returns: ::ksfTkErrOk on success, or an error code on failure.

◆ getDieTemp_C()

sfTkError_t sfDevINA228::getDieTemp_C ( float & celsius )

inline

Read the die temperature in degrees Celsius (16-bit DIETEMP, 7.8125 m-deg-C/LSB).

Parameters

celsius Output reference that receives the temperature in deg-C.

Returns: ::ksfTkErrOk on success, or an error code on failure.

◆ getEnergy_J()

sfTkError_t sfDevINA228::getEnergy_J ( double & joules )

Read the accumulated energy in Joules.

Reads the 40-bit ENERGY register (unsigned) and scales by 16 * 3.2 * CURRENT_LSB.

Note: calibrate() must be called before this method returns meaningful values.

Parameters

joules Output reference that receives the energy in Joules.

Returns: ::ksfTkErrOk on success, or an error code on failure.

◆ getPower_W()

sfTkError_t sfDevINA228::getPower_W ( float & watts )

inline

Read the calculated power in Watts (24-bit POWER, scaled by 3.2 * CURRENT_LSB).

Note: calibrate() must be called before this method returns meaningful values.

Parameters

watts Output reference that receives the power in W.

Returns: ::ksfTkErrOk on success, or an error code on failure.

◆ getPowerRaw()

sfTkError_t sfDevINA228::getPowerRaw ( uint32_t & value )

inline

Read the raw 24-bit power value.

Parameters

value Output reference that receives the unsigned 24-bit value.

Returns: ::ksfTkErrOk on success, or an error code on failure.

◆ getShuntVoltage_mV()

sfTkError_t sfDevINA228::getShuntVoltage_mV ( float & milliVolts )

inline

Read the shunt voltage in millivolts (24-bit VSHUNT, bits [23:4]).

Scales by 312.5 nV/LSB (ADCRANGE=0) or 78.125 nV/LSB (ADCRANGE=1).

Parameters

milliVolts Output reference that receives the shunt voltage in mV.

Returns: ::ksfTkErrOk on success, or an error code on failure.

◆ getShuntVoltageRaw()

sfTkError_t sfDevINA228::getShuntVoltageRaw ( int32_t & value )

inline

Read the raw 20-bit shunt voltage value (sign-extended).

Parameters

value Output reference that receives the signed 20-bit value.

Returns: ::ksfTkErrOk on success, or an error code on failure.

Member Data Documentation

◆ kBusLSB

constexpr float sfDevINA228::kBusLSB = 195.3125e-6f

staticconstexprprotected

Bus voltage LSB in volts.

◆ kCalScale

constexpr float sfDevINA228::kCalScale = 13107.2e6f

staticconstexprprotected

Calibration scale constant.

◆ kCurrentFullScale

constexpr float sfDevINA228::kCurrentFullScale = 524288.0f

staticconstexprprotected

2^19, positive half of the 20-bit ADC.

◆ kDieTempShift

constexpr uint8_t sfDevINA228::kDieTempShift = 0

staticconstexprprotected

DIETEMP is a full 16-bit value.

◆ kEnergyLSBScale

constexpr double sfDevINA228::kEnergyLSBScale = 16.0 * 3.2

staticconstexprprotected

Energy LSB = 16 x 3.2 x CURRENT_LSB.

◆ kPowerLSBScale

constexpr float sfDevINA228::kPowerLSBScale = 3.2f

staticconstexprprotected

Power LSB = 3.2 x CURRENT_LSB.

◆ kShuntLSBDefault

constexpr float sfDevINA228::kShuntLSBDefault = 312.5e-9f

staticconstexprprotected

Shunt LSB in volts (ADCRANGE = 0).

◆ kShuntLSBReduced

constexpr float sfDevINA228::kShuntLSBReduced = 78.125e-9f

staticconstexprprotected

Shunt LSB in volts (ADCRANGE = 1).

◆ kTempLSB

constexpr float sfDevINA228::kTempLSB = 7.8125e-3f

staticconstexprprotected

Die temperature LSB in deg-C.

The documentation for this class was generated from the following files:

src/sfTk/sfDevINA228.h
src/sfTk/sfDevINA228.cpp

Public Member Functions

Static Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ sfDevINA228()

Member Function Documentation

◆ calibrate()

◆ getBusVoltage_V()

◆ getBusVoltageRaw()

◆ getCharge_C()

◆ getCurrent_A()

◆ getCurrentRaw()

◆ getDieTemp_C()

◆ getEnergy_J()

◆ getPower_W()

◆ getPowerRaw()

◆ getShuntVoltage_mV()

◆ getShuntVoltageRaw()

Member Data Documentation

◆ kBusLSB

◆ kCalScale

◆ kCurrentFullScale

◆ kDieTempShift

◆ kEnergyLSBScale

◆ kPowerLSBScale

◆ kShuntLSBDefault

◆ kShuntLSBReduced

◆ kTempLSB