Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
INA219 library for MicroPython
"""MicroPython library for the INA219 sensor.
This library supports the INA219 sensor from Texas Instruments with
MicroPython using the I2C bus.
"""
import logging
import utime
from math import trunc
from micropython import const
class INA219:
"""Provides all the functionality to interact with the INA219 sensor."""
RANGE_16V = const(0) # Range 0-16 volts
RANGE_32V = const(1) # Range 0-32 volts
GAIN_1_40MV = const(0) # Maximum shunt voltage 40mV
GAIN_2_80MV = const(1) # Maximum shunt voltage 80mV
GAIN_4_160MV = const(2) # Maximum shunt voltage 160mV
GAIN_8_320MV = const(3) # Maximum shunt voltage 320mV
GAIN_AUTO = const(-1) # Determine gain automatically
ADC_9BIT = const(0) # 9-bit conversion time 84us.
ADC_10BIT = const(1) # 10-bit conversion time 148us.
ADC_11BIT = const(2) # 11-bit conversion time 2766us.
ADC_12BIT = const(3) # 12-bit conversion time 532us.
ADC_2SAMP = const(9) # 2 samples at 12-bit, conversion time 1.06ms.
ADC_4SAMP = const(10) # 4 samples at 12-bit, conversion time 2.13ms.
ADC_8SAMP = const(11) # 8 samples at 12-bit, conversion time 4.26ms.
ADC_16SAMP = const(12) # 16 samples at 12-bit,conversion time 8.51ms
ADC_32SAMP = const(13) # 32 samples at 12-bit, conversion time 17.02ms.
ADC_64SAMP = const(14) # 64 samples at 12-bit, conversion time 34.05ms.
ADC_128SAMP = const(15) # 128 samples at 12-bit, conversion time 68.10ms.
__ADC_CONVERSION = {
ADC_9BIT: "9-bit",
ADC_10BIT: "10-bit",
ADC_11BIT: "11-bit",
ADC_12BIT: "12-bit",
ADC_2SAMP: "12-bit, 2 samples",
ADC_4SAMP: "12-bit, 4 samples",
ADC_8SAMP: "12-bit, 8 samples",
ADC_16SAMP: "12-bit, 16 samples",
ADC_32SAMP: "12-bit, 32 samples",
ADC_64SAMP: "12-bit, 64 samples",
ADC_128SAMP: "12-bit, 128 samples"
}
__ADDRESS = 0x40
__REG_CONFIG = 0x00
__REG_SHUNTVOLTAGE = 0x01
__REG_BUSVOLTAGE = 0x02
__REG_POWER = 0x03
__REG_CURRENT = 0x04
__REG_CALIBRATION = 0x05
__RST = 15
__BRNG = 13
__PG1 = 12
__PG0 = 11
__BADC4 = 10
__BADC3 = 9
__BADC2 = 8
__BADC1 = 7
__SADC4 = 6
__SADC3 = 5
__SADC2 = 4
__SADC1 = 3
__MODE3 = 2
__MODE2 = 1
__MODE1 = 0
__OVF = 1
__CNVR = 2
__BUS_RANGE = [16, 32]
__GAIN_VOLTS = [0.04, 0.08, 0.16, 0.32]
__CONT_SH_BUS = 7
__AMP_ERR_MSG = ('Expected current %.3fA is greater '
'than max possible current %.3fA')
__RNG_ERR_MSG = ('Expected amps %.2fA, out of range, use a lower '
'value shunt resistor')
__VOLT_ERR_MSG = ('Invalid voltage range, must be one of: '
'RANGE_16V, RANGE_32V')
__LOG_FORMAT = '%(asctime)s - %(levelname)s - INA219 %(message)s'
__LOG_MSG_1 = ('shunt ohms: %.3f, bus max volts: %d, '
'shunt volts max: %.2f%s, '
'bus ADC: %s, shunt ADC: %s')
__LOG_MSG_2 = ('calibrate called with: bus max volts: %dV, '
'max shunt volts: %.2fV%s')
__LOG_MSG_3 = ('Current overflow detected - '
'attempting to increase gain')
__SHUNT_MILLIVOLTS_LSB = 0.01 # 10uV
__BUS_MILLIVOLTS_LSB = 4 # 4mV
__CALIBRATION_FACTOR = 0.04096
# Max value supported value (65534 decimal) of the calibration register
# (D0 bit is always zero, p31 of spec)
__MAX_CALIBRATION_VALUE = 0xFFFE
# In the spec (p17) the current LSB factor for the minimum LSB is
# documented as 32767, but a larger value (100.1% of 32767) is used
# to guarantee that current overflow can always be detected.
__CURRENT_LSB_FACTOR = 32800
def __init__(self, shunt_ohms, i2c, max_expected_amps=None,
address=__ADDRESS, log_level=logging.ERROR):
"""Construct the class.
At a minimum pass in the resistance of the shunt resistor and I2C
interface to which the sensor is connected.
Arguments:
shunt_ohms -- value of shunt resistor in Ohms (mandatory).
i2c -- an instance of the I2C class from the *machine* module, either
I2C(1) or I2C(2) (mandatory).
max_expected_amps -- the maximum expected current in Amps (optional).
address -- the I2C address of the INA219, defaults to
*0x40* (optional).
log_level -- set to logging.DEBUG to see detailed calibration
calculations (optional).
"""
logging.basicConfig(level=log_level)
self._log = logging.getLogger("ina219")
self._i2c = i2c
self._address = address
self._shunt_ohms = shunt_ohms
self._max_expected_amps = max_expected_amps
self._min_device_current_lsb = self._calculate_min_current_lsb()
self._gain = None
self._auto_gain_enabled = False
def configure(self, voltage_range=RANGE_32V, gain=GAIN_AUTO,
bus_adc=ADC_12BIT, shunt_adc=ADC_12BIT):
"""Configure and calibrate how the INA219 will take measurements.
Arguments:
voltage_range -- The full scale voltage range, this is either 16V
or 32V represented by one of the following constants;
RANGE_16V, RANGE_32V (default).
gain -- The gain which controls the maximum range of the shunt
voltage represented by one of the following constants;
GAIN_1_40MV, GAIN_2_80MV, GAIN_4_160MV,
GAIN_8_320MV, GAIN_AUTO (default).
bus_adc -- The bus ADC resolution (9, 10, 11, or 12-bit) or
set the number of samples used when averaging results
represent by one of the following constants; ADC_9BIT,
ADC_10BIT, ADC_11BIT, ADC_12BIT (default),
ADC_2SAMP, ADC_4SAMP, ADC_8SAMP, ADC_16SAMP,
ADC_32SAMP, ADC_64SAMP, ADC_128SAMP
shunt_adc -- The shunt ADC resolution (9, 10, 11, or 12-bit) or
set the number of samples used when averaging results
represent by one of the following constants; ADC_9BIT,
ADC_10BIT, ADC_11BIT, ADC_12BIT (default),
ADC_2SAMP, ADC_4SAMP, ADC_8SAMP, ADC_16SAMP,
ADC_32SAMP, ADC_64SAMP, ADC_128SAMP
"""
self.__validate_voltage_range(voltage_range)
self._voltage_range = voltage_range
if self._max_expected_amps is not None:
if gain == self.GAIN_AUTO:
self._auto_gain_enabled = True
self._gain = self._determine_gain(self._max_expected_amps)
else:
self._gain = gain
else:
if gain != self.GAIN_AUTO:
self._gain = gain
else:
self._auto_gain_enabled = True
self._gain = self.GAIN_1_40MV
self._log.info('gain set to %.2fV', self.__GAIN_VOLTS[self._gain])
self._log.debug(
self.__LOG_MSG_1,
self._shunt_ohms, self.__BUS_RANGE[voltage_range],
self.__GAIN_VOLTS[self._gain],
self.__max_expected_amps_to_string(self._max_expected_amps),
self.__ADC_CONVERSION[bus_adc], self.__ADC_CONVERSION[shunt_adc])
self._calibrate(
self.__BUS_RANGE[voltage_range], self.__GAIN_VOLTS[self._gain],
self._max_expected_amps)
self._configure(voltage_range, self._gain, bus_adc, shunt_adc)
def voltage(self):
"""Return the bus voltage in volts."""
value = self._voltage_register()
return float(value) * self.__BUS_MILLIVOLTS_LSB / 1000
def supply_voltage(self):
"""Return the bus supply voltage in volts.
This is the sum of the bus voltage and shunt voltage. A
DeviceRangeError exception is thrown if current overflow occurs.
"""
return self.voltage() + (float(self.shunt_voltage()) / 1000)
def current(self):
"""Return the bus current in milliamps.
A DeviceRangeError exception is thrown if current overflow occurs.
"""
self._handle_current_overflow()
return self._current_register() * self._current_lsb * 1000
def power(self):
"""Return the bus power consumption in milliwatts.
A DeviceRangeError exception is thrown if current overflow occurs.
"""
self._handle_current_overflow()
return self._power_register() * self._power_lsb * 1000
def shunt_voltage(self):
"""Return the shunt voltage in millivolts.
A DeviceRangeError exception is thrown if current overflow occurs.
"""
self._handle_current_overflow()
return self._shunt_voltage_register() * self.__SHUNT_MILLIVOLTS_LSB
def sleep(self):
"""Put the INA219 into power down mode."""
configuration = self._read_configuration()
self._configuration_register(configuration & 0xFFF8)
def wake(self):
"""Wake the INA219 from power down mode."""
configuration = self._read_configuration()
self._configuration_register(configuration | 0x0007)
# 40us delay to recover from powerdown (p14 of spec)
utime.sleep_us(40)
def current_overflow(self):
"""Return true if the sensor has detect current overflow.
In this case the current and power values are invalid.
"""
return self._has_current_overflow()
def reset(self):
"""Reset the INA219 to its default configuration."""
self._configuration_register(1 << self.__RST)
def _handle_current_overflow(self):
if self._auto_gain_enabled:
while self._has_current_overflow():
self._increase_gain()
else:
if self._has_current_overflow():
raise DeviceRangeError(self.__GAIN_VOLTS[self._gain])
def _determine_gain(self, max_expected_amps):
shunt_v = max_expected_amps * self._shunt_ohms
if shunt_v > self.__GAIN_VOLTS[3]:
raise ValueError(self.__RNG_ERR_MSG % max_expected_amps)
gain = min(v for v in self.__GAIN_VOLTS if v > shunt_v)
return self.__GAIN_VOLTS.index(gain)
def _increase_gain(self):
self._log.info(self.__LOG_MSG_3)
gain = self._read_gain()
if gain < len(self.__GAIN_VOLTS) - 1:
gain = gain + 1
self._calibrate(self.__BUS_RANGE[self._voltage_range],
self.__GAIN_VOLTS[gain])
self._configure_gain(gain)
# 1ms delay required for new configuration to take effect,
# otherwise invalid current/power readings can occur.
utime.sleep_ms(1)
else:
self._log.info('Device limit reach, gain cannot be increased')
raise DeviceRangeError(self.__GAIN_VOLTS[gain], True)
def _configure(self, voltage_range, gain, bus_adc, shunt_adc):
configuration = (
voltage_range << self.__BRNG | gain << self.__PG0 |
bus_adc << self.__BADC1 | shunt_adc << self.__SADC1 |
self.__CONT_SH_BUS)
self._configuration_register(configuration)
def _calibrate(self, bus_volts_max, shunt_volts_max,
max_expected_amps=None):
self._log.info(self.__LOG_MSG_2,
bus_volts_max, shunt_volts_max,
self.__max_expected_amps_to_string(max_expected_amps))
max_possible_amps = shunt_volts_max / self._shunt_ohms
self._log.info("max possible current: %.3fA", max_possible_amps)
self._current_lsb = \
self._determine_current_lsb(max_expected_amps, max_possible_amps)
self._log.info("current LSB: %.3e A/bit", self._current_lsb)
self._power_lsb = self._current_lsb * 20
self._log.info("power LSB: %.3e W/bit", self._power_lsb)
max_current = self._current_lsb * 32767
self._log.info("max current before overflow: %.4fA", max_current)
max_shunt_voltage = max_current * self._shunt_ohms
self._log.info("max shunt voltage before overflow: %.4fmV",
max_shunt_voltage * 1000)
calibration = trunc(self.__CALIBRATION_FACTOR /
(self._current_lsb * self._shunt_ohms))
self._log.info("calibration: 0x%04x (%d)", calibration, calibration)
self._calibration_register(calibration)
def _determine_current_lsb(self, max_expected_amps, max_possible_amps):
if max_expected_amps is not None:
if max_expected_amps > round(max_possible_amps, 3):
raise ValueError(self.__AMP_ERR_MSG %
(max_expected_amps, max_possible_amps))
self._log.info("max expected current: %.3fA", max_expected_amps)
if max_expected_amps < max_possible_amps:
current_lsb = max_expected_amps / self.__CURRENT_LSB_FACTOR
else:
current_lsb = max_possible_amps / self.__CURRENT_LSB_FACTOR
else:
current_lsb = max_possible_amps / self.__CURRENT_LSB_FACTOR
if current_lsb < self._min_device_current_lsb:
current_lsb = self._min_device_current_lsb
return current_lsb
def _configuration_register(self, register_value):
self._log.debug("configuration: 0x%04x", register_value)
self.__write_register(self.__REG_CONFIG, register_value)
def _read_configuration(self):
return self.__read_register(self.__REG_CONFIG)
def _calculate_min_current_lsb(self):
return self.__CALIBRATION_FACTOR / \
(self._shunt_ohms * self.__MAX_CALIBRATION_VALUE)
def _read_gain(self):
configuration = self._read_configuration()
gain = (configuration & 0x1800) >> self.__PG0
self._log.info("gain is currently: %.2fV", self.__GAIN_VOLTS[gain])
return gain
def _configure_gain(self, gain):
configuration = self._read_configuration()
configuration = configuration & 0xE7FF
self._configuration_register(configuration | (gain << self.__PG0))
self._gain = gain
self._log.info("gain set to: %.2fV" % self.__GAIN_VOLTS[gain])
def _calibration_register(self, register_value):
self._log.debug("calibration: 0x%04x" % register_value)
self.__write_register(self.__REG_CALIBRATION, register_value)
def _has_current_overflow(self):
ovf = self._read_voltage_register() & self.__OVF
return (ovf == 1)
def _voltage_register(self):
register_value = self._read_voltage_register()
return register_value >> 3
def _read_voltage_register(self):
return self.__read_register(self.__REG_BUSVOLTAGE)
def _current_register(self):
return self.__read_register(self.__REG_CURRENT, True)
def _shunt_voltage_register(self):
return self.__read_register(self.__REG_SHUNTVOLTAGE, True)
def _power_register(self):
return self.__read_register(self.__REG_POWER)
def __validate_voltage_range(self, voltage_range):
if voltage_range > len(self.__BUS_RANGE) - 1:
raise ValueError(self.__VOLT_ERR_MSG)
def __write_register(self, register, register_value):
self.__log_register_operation("write", register, register_value)
register_bytes = self.__to_bytes(register_value)
self._i2c.writeto_mem(self._address, register, register_bytes)
def __to_bytes(self, register_value):
return bytearray([(register_value >> 8) & 0xFF, register_value & 0xFF])
def __read_register(self, register, negative_value_supported=False):
register_bytes = self._i2c.readfrom_mem(self._address, register, 2)
register_value = int.from_bytes(register_bytes, 'big')
if negative_value_supported:
# Two's compliment
if register_value > 32767:
register_value -= 65536
self.__log_register_operation("read", register, register_value)
return register_value
def __log_register_operation(self, msg, register, value):
# performance optimisation
if logging._level == logging.DEBUG:
binary = '{0:#018b}'.format(value)
self._log.debug("%s register 0x%02x: 0x%04x %s",
msg, register, value, binary)
def __max_expected_amps_to_string(self, max_expected_amps):
if max_expected_amps is None:
return ''
else:
return ', max expected amps: %.3fA' % max_expected_amps
class DeviceRangeError(Exception):
"""This exception is throw to prevent invalid readings.
Invalid readings occur When the current is greater than allowed given
calibration of the device.
"""
__DEV_RNG_ERR = ('Current out of range (overflow), '
'for gain %.2fV')
def __init__(self, gain_volts, device_max=False):
"""Construct the class."""
msg = self.__DEV_RNG_ERR % gain_volts
if device_max:
msg = msg + ', device limit reached'
super(DeviceRangeError, self).__init__(msg)
self.gain_volts = gain_volts
self.device_limit_reached = device_max
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.