Package: pi-ina219
This Python library supports theINA219voltage,
current and power monitor sensor from Texas Instruments on both Python 2
and 3. The intent of the library is to make it easy to use the quite
complex functionality of this sensor.The library currently only supportscontinuousreads of voltage and
power, but nottriggeredreads.The library supports the detection ofoverflowin the current/power
calculations which results in meaningless values for these readings.The low power mode of the INA219 is supported, so if only occasional
reads are being made in a battery based system, current consumption can
be minimised.The library has been tested with theAdafruit INA219
Breakout.Installation and UpgradeThis library and its dependency (Adafruit GPIO
library) can be
installed from PyPI by executing:sudopip3installpi-ina219To upgrade from a previous version installed direct from Github execute:sudopip3uninstallpi-ina219sudopip3installpi-ina219The Adafruit library supports the I2C protocol on all versions of the
Raspberry Pi. Remember to enable the I2C bus under theAdvanced
Optionsofraspi-config.UsageThe address of the sensor unless otherwise specified is the default of0x40.Note that the bus voltage is that on the load side of the shunt
resistor, if you want the voltage on the supply side then you should add
the bus voltage and shunt voltage together, or use thesupply_voltage()function.I2C Bus numberIn most cases this will be determined automatically, however if this
fails you will see the exception:Could not determine default I2C bus for platformIn this case just set the bus number in the INA219 constructor, for
example:ina = INA219(SHUNT_OHMS, busnum=1)This is known to be required with Raspberry Pi 4 and the ‘Bullseye’
(October 2021) Raspberry Pi OS.Simple - Auto GainThis mode is great for getting started, as it will provide valid
readings until the device current capability is exceeded for the value
of the shunt resistor connected (3.2A for 0.1Ω shunt resistor). It does
this by automatically adjusting the gain as required until the maximum
is reached, when aDeviceRangeErrorexception is thrown to avoid
invalid readings being taken.The downside of this approach is reduced current and power resolution.#!/usr/bin/env pythonfromina219importINA219fromina219importDeviceRangeErrorSHUNT_OHMS=0.1defread():ina=INA219(SHUNT_OHMS)ina.configure()print("Bus Voltage:%.3fV"%ina.voltage())try:print("Bus Current:%.3fmA"%ina.current())print("Power:%.3fmW"%ina.power())print("Shunt voltage:%.3fmV"%ina.shunt_voltage())exceptDeviceRangeErrorase:# Current out of device range with specified shunt resistorprint(e)if__name__=="__main__":read()Advanced - Auto Gain, High ResolutionIn this mode by understanding the maximum current expected in your
system and specifying this in the script you can achieve the best
possible current and power resolution. The library will calculate the
best gain to achieve the highest resolution based on the maximum
expected current.In this mode if the current exceeds the maximum specified, the gain will
be automatically increased, so a valid reading will still result, but at
a lower resolution.As above when the maximum gain is reached, an exception is thrown to
avoid invalid readings being taken.#!/usr/bin/env pythonfromina219importINA219fromina219importDeviceRangeErrorSHUNT_OHMS=0.1MAX_EXPECTED_AMPS=0.2defread():ina=INA219(SHUNT_OHMS,MAX_EXPECTED_AMPS)ina.configure(ina.RANGE_16V)print("Bus Voltage:%.3fV"%ina.voltage())try:print("Bus Current:%.3fmA"%ina.current())print("Power:%.3fmW"%ina.power())print("Shunt voltage:%.3fmV"%ina.shunt_voltage())exceptDeviceRangeErrorase:# Current out of device range with specified shunt resistorprint(e)if__name__=="__main__":read()Advanced - Manual Gain, High ResolutionIn this mode by understanding the maximum current expected in your
system and specifying this and the gain in the script you can always
achieve the best possible current and power resolution, at the price of
missing current and power values if a current overflow occurs.#!/usr/bin/env pythonfromina219importINA219fromina219importDeviceRangeErrorSHUNT_OHMS=0.1MAX_EXPECTED_AMPS=0.2defread():ina=INA219(SHUNT_OHMS,MAX_EXPECTED_AMPS)ina.configure(ina.RANGE_16V,ina.GAIN_1_40MV)print("Bus Voltage:%.3fV"%ina.voltage())try:print("Bus Current:%.3fmA"%ina.current())print("Power:%.3fmW"%ina.power())print("Shunt voltage:%.3fmV"%ina.shunt_voltage())exceptDeviceRangeErrorase:print("Current overflow")if__name__=="__main__":read()Sensor AddressThe sensor address may be altered as follows:ina=INA219(SHUNT_OHMS,MAX_EXPECTED_AMPS,address=0x41)Low Power ModeThe sensor may be put in low power mode between reads as follows:ina.configure(ina.RANGE_16V)whileTrue:print("Voltage :%.3fV"%ina.voltage())ina.sleep()time.sleep(60)ina.wake()Note that if you do not wake the device after sleeping, the value
returned from a read will be the previous value taken before sleeping.FunctionsINA219()constructs the class. The arguments, are:shunt_ohms: The value of the shunt resistor in Ohms (mandatory).max_expected_amps: The maximum expected current in Amps
(optional).busnum: The I2C bus number for the device platform, defaults toauto detects 0 or 1 for Raspberry Pi or Beaglebone Black(optional).address: The I2C address of the INA219, defaults to0x40(optional).log_level: Set tologging.INFOto see the detailed calibration
calculations andlogging.DEBUGto see register operations
(optional).configure()configures and calibrates how the INA219 will take
measurements. The arguments, which are all optional, are:voltage_range: The full scale voltage range, this is either 16V or
32V, represented by one of the following constants (optional).RANGE_16V: Range zero to 16 voltsRANGE_32V: Range zero to 32 volts (default).Device only
supports up to 26V.gain: The gain, which controls the maximum range of the shunt
voltage, represented by one of the following constants (optional).GAIN_1_40MV: Maximum shunt voltage 40mVGAIN_2_80MV: Maximum shunt voltage 80mVGAIN_4_160MV: Maximum shunt voltage 160mVGAIN_8_320MV: Maximum shunt voltage 320mVGAIN_AUTO: Automatically calculate the gain (default)bus_adc: The bus ADC resolution (9, 10, 11, or 12-bit), or set the
number of samples used when averaging results, represented by one
of the following constants (optional).ADC_9BIT: 9 bit, conversion time 84us.ADC_10BIT: 10 bit, conversion time 148us.ADC_11BIT: 11 bit, conversion time 276us.ADC_12BIT: 12 bit, conversion time 532us (default).ADC_2SAMP: 2 samples at 12 bit, conversion time 1.06ms.ADC_4SAMP: 4 samples at 12 bit, conversion time 2.13ms.ADC_8SAMP: 8 samples at 12 bit, conversion time 4.26ms.ADC_16SAMP: 16 samples at 12 bit, conversion time 8.51msADC_32SAMP: 32 samples at 12 bit, conversion time 17.02ms.ADC_64SAMP: 64 samples at 12 bit, conversion time 34.05ms.ADC_128SAMP: 128 samples at 12 bit, conversion time 68.10ms.shunt_adc: The shunt ADC resolution (9, 10, 11, or 12-bit), or set
the number of samples used when averaging results, represented by
one of the following constants (optional).ADC_9BIT: 9 bit, conversion time 84us.ADC_10BIT: 10 bit, conversion time 148us.ADC_11BIT: 11 bit, conversion time 276us.ADC_12BIT: 12 bit, conversion time 532us (default).ADC_2SAMP: 2 samples at 12 bit, conversion time 1.06ms.ADC_4SAMP: 4 samples at 12 bit, conversion time 2.13ms.ADC_8SAMP: 8 samples at 12 bit, conversion time 4.26ms.ADC_16SAMP: 16 samples at 12 bit, conversion time 8.51msADC_32SAMP: 32 samples at 12 bit, conversion time 17.02ms.ADC_64SAMP: 64 samples at 12 bit, conversion time 34.05ms.ADC_128SAMP: 128 samples at 12 bit, conversion time 68.10ms.voltage()Returns the bus voltage in volts (V).supply_voltage()Returns the bus supply voltage in volts (V).
This is the sum of the bus voltage and shunt voltage. ADeviceRangeErrorexception is thrown if current overflow occurs.current()Returns the bus current in milliamps (mA). ADeviceRangeErrorexception is thrown if current overflow occurs.power()Returns the bus power consumption in milliwatts (mW). ADeviceRangeErrorexception is thrown if current overflow occurs.shunt_voltage()Returns the shunt voltage in millivolts (mV). ADeviceRangeErrorexception is thrown if current overflow occurs.current_overflow()Returns ‘True’ if an overflow has occured.
Alternatively handle theDeviceRangeErrorexception as shown in the
examples above.sleep()Put the INA219 into power down mode.wake()Wake the INA219 from power down mode.reset()Reset the INA219 to its default configuration.is_conversion_ready()check if conversion was done before reading
the next measurement results.PerformanceOn a Raspberry Pi 2 Model B running Raspbian Jesse and reading a 12-bit
voltage in a loop, a read occurred approximately every 10 milliseconds.On a Raspberry Pi 4 running Raspbian Buster a read occurred
approximately every 570 microseconds.DebuggingTo understand the calibration calculation results and automatic gain
increases, informational output can be enabled with:ina=INA219(SHUNT_OHMS,log_level=logging.INFO)Detailed logging of device register operations can be enabled with:ina=INA219(SHUNT_OHMS,log_level=logging.DEBUG)TestingInstall the library as described above, this will install all the
dependencies required for the unit tests, as well as the library itself.
Clone the library source from Github then execute the test suite from
the top level directory with:python3-munittestdiscover-stests-p'test_*.py'A single unit test class may be run as follows:python3-munittesttests.test_configuration.TestConfigurationCode coverage metrics may be generated and viewed with:coveragerun--branch--source=ina219-munittestdiscover-stests-p'test_*.py'coveragereport-mCoding StandardThis library adheres to thePEP8standard and follows theidiomaticstyle described in the bookWriting Idiomatic PythonbyJeff Knupp.