{"id":13612978,"url":"https://github.com/chrisb2/pyb_ina219","last_synced_at":"2025-03-21T00:31:41.872Z","repository":{"id":53262681,"uuid":"90507895","full_name":"chrisb2/pyb_ina219","owner":"chrisb2","description":"This library for MicroPython makes it easy to leverage the complex functionality of the Texas Instruments INA219 sensor to measure voltage, current and power.","archived":false,"fork":false,"pushed_at":"2023-08-05T23:36:47.000Z","size":47,"stargazers_count":59,"open_issues_count":3,"forks_count":19,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-17T19:21:22.594Z","etag":null,"topics":["esp32","esp8266","ina-219","micropython","pyboard"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chrisb2.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-05-07T04:06:20.000Z","updated_at":"2025-03-02T19:54:52.000Z","dependencies_parsed_at":"2024-10-28T09:24:58.826Z","dependency_job_id":null,"html_url":"https://github.com/chrisb2/pyb_ina219","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrisb2%2Fpyb_ina219","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrisb2%2Fpyb_ina219/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrisb2%2Fpyb_ina219/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrisb2%2Fpyb_ina219/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chrisb2","download_url":"https://codeload.github.com/chrisb2/pyb_ina219/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244717391,"owners_count":20498283,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["esp32","esp8266","ina-219","micropython","pyboard"],"created_at":"2024-08-01T20:00:37.510Z","updated_at":"2025-03-21T00:31:41.606Z","avatar_url":"https://github.com/chrisb2.png","language":"Python","funding_links":[],"categories":["Libraries","精选驱动库"],"sub_categories":["Sensors","传感器"],"readme":"# MicroPython Library for Voltage and Current Sensors Using the INA219\n\nThis MicroPython library for the [INA219](http://www.ti.com/lit/ds/symlink/ina219.pdf)\nvoltage, current and power monitor sensor from Texas Instruments. The intent of\nthe library is to make it easy to use the quite complex functionality of this\nsensor.\n\nThe functionality is currently under development and is based on my [INA219 library for the Raspberry Pi](https://github.com/chrisb2/pi_ina219).\n\nThe library currently only supports _continuous_ reads of voltage and\npower, but not _triggered_ reads.\n\nThe library supports the detection of _overflow_ in the current/power\ncalculations which results in meaningless values for these readings.\n\nThe low power mode of the INA219 is supported, so if only occasional\nreads are being made in a battery based system, current consumption can\nbe minimised.\n\nThe library has been tested with the [Adafruit INA219 Breakout](https://www.adafruit.com/products/904) and the [pyboard](https://store.micropython.org/#/store), as well as a [NodeMCU (esp8266 12e) clone](http://www.dx.com/p/esp8266-esp-12e-development-board-serial-wi-fi-module-for-nodemcu-441215). and a [Lolin32 Lite (esp32)](https://wiki.wemos.cc/products:lolin32:lolin32_lite). For specific instructions for the esp8266 and esp32, see sub-directories.\n\nIf you successfully use this library with an WiPy, etc, please let me know.\n\n## Usage\n\nIf you want to give it a try then copy _[ina219.py](https://raw.githubusercontent.com/chrisb2/pyb_ina219/master/ina219.py)_ and _[logging.py](https://raw.githubusercontent.com/micropython/micropython-lib/master/python-stdlib/logging/logging.py)_ onto the flash drive of your pyboard, connect the sensor to the I2C(1) or I2C(2) interfaces on the pyboard,\nthen from a REPL prompt execute:\n\n```python\nfrom ina219 import INA219\nfrom machine import I2C\n\nI2C_INTERFACE_NO = 2\nSHUNT_OHMS = 0.1  # Check value of shunt used with your INA219\n\nina = INA219(SHUNT_OHMS, I2C(I2C_INTERFACE_NO))\nina.configure()\nprint(\"Bus Voltage: %.3f V\" % ina.voltage())\nprint(\"Current: %.3f mA\" % ina.current())\nprint(\"Power: %.3f mW\" % ina.power())\n```\n\nAlternatively copy _[ina219.py](https://raw.githubusercontent.com/chrisb2/pyb_ina219/master/ina219.py)_, _[logging.py](https://raw.githubusercontent.com/micropython/micropython-lib/master/python-stdlib/logging/logging.py)_\nand _[example.py](https://raw.githubusercontent.com/chrisb2/pyb_ina219/master/example.py)_\nto the flash drive and from the REPL prompt execute:\n\n```python\nexecfile('example.py')\n```\n\nThe address of the sensor unless otherwise specified is the default\nof _0x40_.\n\nNote that the bus voltage is that on the load side of the shunt resister,\nif you want the voltage on the supply side then you should add the bus\nvoltage and shunt voltage together, or use the *supply_voltage()*\nfunction.\n\n### Simple - Auto Gain\n\nThis mode is great for getting started, as it will provide valid readings\nuntil the device current capability is exceeded for the value of the\nshunt resistor connected (3.2A for 0.1\u0026Omega; shunt resistor). It does this by\nautomatically adjusting the gain as required until the maximum is reached,\nwhen a _DeviceRangeError_ exception is thrown to avoid invalid readings being taken.\n\nThe downside of this approach is reduced current and power resolution.\n\n```python\nfrom ina219 import INA219\nfrom ina219 import DeviceRangeError\nfrom machine import I2C\n\nI2C_INTERFACE_NO = 2\nSHUNT_OHMS = 0.1  # Check value of shunt used with your INA219\n\nina = INA219(SHUNT_OHMS, I2C(I2C_INTERFACE_NO))\nina.configure()\n\nprint(\"Bus Voltage: %.3f V\" % ina.voltage())\ntry:\n    print(\"Bus Current: %.3f mA\" % ina.current())\n    print(\"Power: %.3f mW\" % ina.power())\n    print(\"Shunt voltage: %.3f mV\" % ina.shunt_voltage())\nexcept DeviceRangeError as e:\n    # Current out of device range with specified shunt resister\n    print e\n```\n\n### Advanced - Auto Gain, High Resolution\n\nIn this mode by understanding the maximum current expected in your system\nand specifying this in the script you can achieve the best possible current\nand power resolution. The library will calculate the best gain to achieve\nthe highest resolution based on the maximum expected current.\n\nIn this mode if the current exceeds the maximum specified, the gain will\nbe automatically increased, so a valid reading will still result, but at\na lower resolution.\n\nAs above when the maximum gain is reached, an exception is thrown to\navoid invalid readings being taken.\n\n```python\nfrom ina219 import INA219\nfrom ina219 import DeviceRangeError\nfrom machine import I2C\n\nI2C_INTERFACE_NO = 2\nSHUNT_OHMS = 0.1  # Check value of shunt used with your INA219\nMAX_EXPECTED_AMPS = 0.2\n\nina = INA219(SHUNT_OHMS, I2C(I2C_INTERFACE_NO), MAX_EXPECTED_AMPS)\nina.configure(ina.RANGE_16V)\n\nprint(\"Bus Voltage: %.3f V\" % ina.voltage())\ntry:\n    print(\"Bus Current: %.3f mA\" % ina.current())\n    print(\"Power: %.3f mW\" % ina.power())\n    print(\"Shunt voltage: %.3f mV\" % ina.shunt_voltage())\nexcept DeviceRangeError as e:\n    # Current out of device range with specified shunt resister\n    print e\n```\n\n### Advanced - Manual Gain, High Resolution\n\nIn this mode by understanding the maximum current expected in your system\nand specifying this and the gain in the script you can always achieve the\nbest possible current and power resolution, at the price of missing current\nand power values if a current overflow occurs.\n\n```python\nfrom ina219 import INA219\nfrom ina219 import DeviceRangeError\nfrom machine import I2C\n\nI2C_INTERFACE_NO = 2\nSHUNT_OHMS = 0.1  # Check value of shunt used with your INA219\nMAX_EXPECTED_AMPS = 0.2\n\nina = INA219(SHUNT_OHMS, I2C(I2C_INTERFACE_NO), MAX_EXPECTED_AMPS)\nina.configure(ina.RANGE_16V, ina.GAIN_1_40MV)\n\nprint(\"Bus Voltage: %.3f V\" % ina.voltage())\ntry:\n    print(\"Bus Current: %.3f mA\" % ina.current())\n    print(\"Power: %.3f mW\" % ina.power())\n    print(\"Shunt voltage: %.3f mV\" % ina.shunt_voltage())\nexcept DeviceRangeError as e:\n    print(\"Current overflow\")\n```\n\n### Sensor Address\n\nThe sensor address may be altered as follows:\n\n```python\nina = INA219(SHUNT_OHMS, I2C(2), MAX_EXPECTED_AMPS, address=0x41)\n```\n\n### Low Power Mode\n\nThe sensor may be put in low power mode between reads as follows:\n\n```python\nina.configure(ina.RANGE_16V)\nwhile True:\n    print(\"Voltage : %.3f V\" % ina.voltage())\n    ina.sleep()\n    time.sleep(60)\n    ina.wake()\n```\n\nNote that if you do not wake the device after sleeping, the value\nreturned from a read will be the previous value taken before sleeping.\n\n## Functions\n\n* `INA219()` constructs the class.\nThe arguments, are:\n    * shunt_ohms: The value of the shunt resistor in Ohms (mandatory).\n    * i2c: an instance of the I2C class from the _machine_ module, either\n           _I2C(1)_ or _I2C(2)_ (mandatory).\n    * max_expected_amps: The maximum expected current in Amps (optional).\n    * address: The I2C address of the INA219, defaults to *0x40* (optional).\n    * log_level: Set to _logging.INFO_ to see the detailed calibration\n    calculations and _logging.DEBUG_ to see register operations (optional).\n* `configure()` configures and calibrates how the INA219 will take measurements.\nThe arguments, which are all optional, are:\n    * voltage_range: The full scale voltage range, this is either 16V or 32V,\n    represented by one of the following constants (optional).\n        * RANGE_16V: Range zero to 16 volts\n        * RANGE_32V: Range zero to 32 volts (**default**). **Device only supports upto 26V.**\n    * gain: The gain, which controls the maximum range of the shunt voltage,\n        represented by one of the following constants (optional).\n        * GAIN_1_40MV: Maximum shunt voltage 40mV\n        * GAIN_2_80MV: Maximum shunt voltage 80mV\n        * GAIN_4_160MV: Maximum shunt voltage 160mV\n        * GAIN_8_320MV: Maximum shunt voltage 320mV\n        * GAIN_AUTO: Automatically calculate the gain (**default**)\n    * bus_adc: The bus ADC resolution (9, 10, 11, or 12-bit), or\n        set the number of samples used when averaging results, represented by\n        one of the following constants (optional).\n        * ADC_9BIT: 9 bit, conversion time 84us.\n        * ADC_10BIT: 10 bit, conversion time 148us.\n        * ADC_11BIT: 11 bit, conversion time 276us.\n        * ADC_12BIT: 12 bit, conversion time 532us (**default**).\n        * ADC_2SAMP: 2 samples at 12 bit, conversion time 1.06ms.\n        * ADC_4SAMP: 4 samples at 12 bit, conversion time 2.13ms.\n        * ADC_8SAMP: 8 samples at 12 bit, conversion time 4.26ms.\n        * ADC_16SAMP: 16 samples at 12 bit, conversion time 8.51ms\n        * ADC_32SAMP: 32 samples at 12 bit, conversion time 17.02ms.\n        * ADC_64SAMP: 64 samples at 12 bit, conversion time 34.05ms.\n        * ADC_128SAMP: 128 samples at 12 bit, conversion time 68.10ms.\n    * shunt_adc: The shunt ADC resolution (9, 10, 11, or 12-bit), or\n        set the number of samples used when averaging results, represented by\n        one of the following constants (optional).\n        * ADC_9BIT: 9 bit, conversion time 84us.\n        * ADC_10BIT: 10 bit, conversion time 148us.\n        * ADC_11BIT: 11 bit, conversion time 276us.\n        * ADC_12BIT: 12 bit, conversion time 532us (**default**).\n        * ADC_2SAMP: 2 samples at 12 bit, conversion time 1.06ms.\n        * ADC_4SAMP: 4 samples at 12 bit, conversion time 2.13ms.\n        * ADC_8SAMP: 8 samples at 12 bit, conversion time 4.26ms.\n        * ADC_16SAMP: 16 samples at 12 bit, conversion time 8.51ms\n        * ADC_32SAMP: 32 samples at 12 bit, conversion time 17.02ms.\n        * ADC_64SAMP: 64 samples at 12 bit, conversion time 34.05ms.\n        * ADC_128SAMP: 128 samples at 12 bit, conversion time 68.10ms.\n* `voltage()` Returns the bus voltage in volts (V).\n* `supply_voltage()` Returns the bus supply voltage in volts (V). This\n    is the sum of the bus voltage and shunt voltage. A _DeviceRangeError_\n    exception is thrown if current overflow occurs.\n* `current()` Returns the bus current in milliamps (mA).\n\tA _DeviceRangeError_ exception is thrown if current overflow occurs.\n* `power()` Returns the bus power consumption in milliwatts (mW).\n\tA _DeviceRangeError_ exception is thrown if current overflow occurs.\n* `shunt_voltage()` Returns the shunt voltage in millivolts (mV).\n\tA _DeviceRangeError_ exception is thrown if current overflow occurs.\n* `current_overflow()` Returns 'True' if an overflow has\n\toccured. Alternatively handle the _DeviceRangeError_ exception\n\tas shown in the examples above.\n* `sleep()` Put the INA219 into power down mode.\n* `wake()` Wake the INA219 from power down mode.\n* `reset()` Reset the INA219 to its default configuration.\n\n\n## Performance\n\nOn v1.1 pyboard reading a bus voltage in a loop, a read occurred approximately\nevery 270\u0026mu;s. Given that in _continuous_ mode a single 12-bit ADC\nconversion takes 532\u0026mu;s (p27 of the specification) each value returned\nby the _voltage()_ function will likely be the result of a new conversion.\n\nIf multiple ADC conversions are configured (e.g. ADC_2SAMP, takes 1060\u0026mu;s)\nthen the values returned by the _voltage()_ function will often be the result of\nthe same conversion and therefore identical.\n\n## Debugging\n\nAdd the following to the imports\n```Python\nimport logging\n```\nTo understand the calibration calculation results and automatic gain increases, informational output can be enabled with:\n\n```python\nina = INA219(SHUNT_OHMS, I2C(2), log_level=logging.INFO)\n```\n\nDetailed logging of device register operations can be enabled with:\n\n```python\nina = INA219(SHUNT_OHMS, I2C(2), log_level=logging.DEBUG)\n```\n\n## Coding Standard\n\nThis library adheres to the *PEP8* standard and follows the *idiomatic*\nstyle described in the book *Writing Idiomatic Python* by *Jeff Knupp*.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrisb2%2Fpyb_ina219","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchrisb2%2Fpyb_ina219","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrisb2%2Fpyb_ina219/lists"}