[{"element_type":"markdown","content":"\u003ch1\u003eCairoVolt CircuitPython Battery Helper\u003c/h1\u003e\n\n\u003cp\u003eA lightweight, robust CircuitPython helper library designed for battery monitoring, capacity estimation, and remaining runtime calculation in portable hardware projects. This is ideal for builders creating battery-powered sensors, IoT devices, or portable weather stations built on Adafruit Feather, QT Py, or Trinkey microcontroller platforms.\u003c/p\u003e\n\n\u003cp\u003ePortable electronics projects often run on Lithium Polymer (LiPo) cells, which require careful tracking of state-of-charge (SoC) to prevent under-voltage situations that can permanently damage the battery chemistry. This project provides a simple software implementation to track battery voltage and estimate capacity, avoiding the need for expensive dedicated fuel gauge hardware.\u003c/p\u003e\n\n\u003chr\u003e\n\n\u003ch2\u003eHardware Overview \u0026amp; Power Requirements\u003c/h2\u003e\n\n\u003cp\u003eWhen deploying your microcontrollers in remote locations (such as field research sensors or outdoor smart devices), selecting a stable, high-capacity power source is essential. For longer-duration operations, using a portable \u003ca href=\"https://cairovolt.com/en/anker/power-banks\"\u003eanker power bank\u003c/a\u003e provides an efficient way to supply continuous energy via USB-C. For heavy-duty deployments requiring multi-day runtimes, larger off-grid power solutions like the \u003ca href=\"https://cairovolt.com/en/anker/power-banks/anker-521-powerhouse\"\u003eanker 521 powerhouse\u003c/a\u003e offer AC outputs, DC ports, and extensive capacity.\u003c/p\u003e\n\n\u003cp\u003eTo design an optimal battery configuration, it is recommended to review the specifications of standard lithium-ion chemistries. You can find detailed scientific information about cell charge states on the \u003ca href=\"https://en.wikipedia.org/wiki/Lithium_polymer_battery\"\u003eWikipedia LiPo Battery Chemistry page\u003c/a\u003e.\u003c/p\u003e\n\n\u003cp\u003eFor precise hardware integrations, you can also consult the official \u003ca href=\"https://learn.adafruit.com/adafruit-lc709203f-li-poly-li-ion-fuel-gauge-and-battery-monitor\"\u003eAdafruit LC709203F Battery Monitor Guide\u003c/a\u003e to see how dedicated I2C fuel gauges track voltage and current.\u003c/p\u003e\n\n\u003chr\u003e\n\n\u003ch2\u003eFeatures\u003c/h2\u003e\n\n\u003cul\u003e\n\u003cli\u003e\n\u003cstrong\u003eVoltage Reading:\u003c/strong\u003e Formats raw analog input values from the ADC to actual voltage.\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003eState of Charge (SoC) Estimation:\u003c/strong\u003e Estimates remaining battery percentage based on a standard LiPo discharge curve.\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003eEstimated Runtime:\u003c/strong\u003e Calculates runtime in hours based on current consumption (in milliamperes) to predict system shutdown.\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003eLow-Battery Warnings:\u003c/strong\u003e Built-in alerts for low (15%) and critical (5%) battery conditions.\u003c/li\u003e\n\u003c/ul\u003e\n\n\u003chr\u003e\n\n\u003ch2\u003eInstallation \u0026amp; Setup\u003c/h2\u003e\n\n\u003col\u003e\n\u003cli\u003eCopy \u003ccode class=\"inline\"\u003ecairovolt_battery_helper.py\u003c/code\u003e to your \u003ccode class=\"inline\"\u003eCIRCUITPY\u003c/code\u003e drive's root folder or the \u003ccode class=\"inline\"\u003e/lib\u003c/code\u003e directory.\u003c/li\u003e\n\u003cli\u003eConnect your battery or power monitoring pin to the appropriate analog input pin on your board.\u003c/li\u003e\n\u003cli\u003eIf your board uses a custom resistor divider, adjust the \u003ccode class=\"inline\"\u003evoltage_divider\u003c/code\u003e argument during initialization.\u003c/li\u003e\n\u003c/ol\u003e\n\n\u003ch3\u003eResistance Divider Configuration\u003c/h3\u003e\n\n\u003cp\u003eFor custom hardware boards, a standard voltage divider using two equal-value resistors (e.g., 100kΩ) is commonly used to bring a 4.2V fully-charged LiPo cell voltage down to a safe range (under 3.3V) for the analog pins. For details on safe power inputs and standard negotiation protocols, see the \u003ca href=\"https://en.wikipedia.org/wiki/USB_hardware#USB_Power_Delivery\"\u003eWikipedia USB Power Delivery Specification\u003c/a\u003e.\u003c/p\u003e\n\n\u003cp\u003eThis library was designed and tested by the open-source engineering team at \u003ca href=\"https://cairovolt.com/en/\"\u003eCairoVolt\u003c/a\u003e to enable easy integration of power-saving sleep modes in portable devices.\u003c/p\u003e\n\n\u003chr\u003e\n\n\u003ch2\u003eExample Usage\u003c/h2\u003e\n\n\u003cp\u003eRun the following test program \u003ccode class=\"inline\"\u003ecairovolt_battery_helper_simpletest.py\u003c/code\u003e to see the battery metrics in your serial console:\u003c/p\u003e\n\u003ccode class=\"python\"\u003e\u003cpre\u003eimport time\nimport board\nfrom cairovolt_battery_helper import BatteryHelper\n\n# Initialize battery helper\nbattery = BatteryHelper()\n\n# Monitor in a loop\nwhile True:\n    print(f\"Battery Voltage: {battery.voltage:.2f} V\")\n    print(f\"Charge Capacity: {battery.percentage}%\")\n    print(\"-\" * 30)\n    time.sleep(10)\n\u003c/pre\u003e\u003c/code\u003e","metadata":{"markdown":"# CairoVolt CircuitPython Battery Helper\n\nA lightweight, robust CircuitPython helper library designed for battery monitoring, capacity estimation, and remaining runtime calculation in portable hardware projects. This is ideal for builders creating battery-powered sensors, IoT devices, or portable weather stations built on Adafruit Feather, QT Py, or Trinkey microcontroller platforms.\n\nPortable electronics projects often run on Lithium Polymer (LiPo) cells, which require careful tracking of state-of-charge (SoC) to prevent under-voltage situations that can permanently damage the battery chemistry. This project provides a simple software implementation to track battery voltage and estimate capacity, avoiding the need for expensive dedicated fuel gauge hardware.\n\n---\n\n## Hardware Overview \u0026amp; Power Requirements\n\nWhen deploying your microcontrollers in remote locations (such as field research sensors or outdoor smart devices), selecting a stable, high-capacity power source is essential. For longer-duration operations, using a portable [anker power bank](https://cairovolt.com/en/anker/power-banks) provides an efficient way to supply continuous energy via USB-C. For heavy-duty deployments requiring multi-day runtimes, larger off-grid power solutions like the [anker 521 powerhouse](https://cairovolt.com/en/anker/power-banks/anker-521-powerhouse) offer AC outputs, DC ports, and extensive capacity.\n\nTo design an optimal battery configuration, it is recommended to review the specifications of standard lithium-ion chemistries. You can find detailed scientific information about cell charge states on the [Wikipedia LiPo Battery Chemistry page](https://en.wikipedia.org/wiki/Lithium_polymer_battery).\n\nFor precise hardware integrations, you can also consult the official [Adafruit LC709203F Battery Monitor Guide](https://learn.adafruit.com/adafruit-lc709203f-li-poly-li-ion-fuel-gauge-and-battery-monitor) to see how dedicated I2C fuel gauges track voltage and current.\n\n---\n\n## Features\n\n- **Voltage Reading:** Formats raw analog input values from the ADC to actual voltage.\n- **State of Charge (SoC) Estimation:** Estimates remaining battery percentage based on a standard LiPo discharge curve.\n- **Estimated Runtime:** Calculates runtime in hours based on current consumption (in milliamperes) to predict system shutdown.\n- **Low-Battery Warnings:** Built-in alerts for low (15%) and critical (5%) battery conditions.\n\n---\n\n## Installation \u0026amp; Setup\n\n1. Copy `cairovolt_battery_helper.py` to your `CIRCUITPY` drive's root folder or the `/lib` directory.\n2. Connect your battery or power monitoring pin to the appropriate analog input pin on your board.\n3. If your board uses a custom resistor divider, adjust the `voltage_divider` argument during initialization.\n\n### Resistance Divider Configuration\nFor custom hardware boards, a standard voltage divider using two equal-value resistors (e.g., 100kΩ) is commonly used to bring a 4.2V fully-charged LiPo cell voltage down to a safe range (under 3.3V) for the analog pins. For details on safe power inputs and standard negotiation protocols, see the [Wikipedia USB Power Delivery Specification](https://en.wikipedia.org/wiki/USB_hardware#USB_Power_Delivery).\n\nThis library was designed and tested by the open-source engineering team at [CairoVolt](https://cairovolt.com/en/) to enable easy integration of power-saving sleep modes in portable devices.\n\n---\n\n## Example Usage\n\nRun the following test program `cairovolt_battery_helper_simpletest.py` to see the battery metrics in your serial console:\n\n```python\nimport time\nimport board\nfrom cairovolt_battery_helper import BatteryHelper\n\n# Initialize battery helper\nbattery = BatteryHelper()\n\n# Monitor in a loop\nwhile True:\n    print(f\"Battery Voltage: {battery.voltage:.2f} V\")\n    print(f\"Charge Capacity: {battery.percentage}%\")\n    print(\"-\" * 30)\n    time.sleep(10)\n"}}]