CairoVolt CircuitPython Battery Helper

A 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.

Portable 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.

Hardware Overview & Power Requirements

When 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 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 offer AC outputs, DC ports, and extensive capacity.

To 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.

For precise hardware integrations, you can also consult the official Adafruit LC709203F Battery Monitor Guide to see how dedicated I2C fuel gauges track voltage and current.

Features

• Voltage Reading: Formats raw analog input values from the ADC to actual voltage.
• State of Charge (SoC) Estimation: Estimates remaining battery percentage based on a standard LiPo discharge curve.
• Estimated Runtime: Calculates runtime in hours based on current consumption (in milliamperes) to predict system shutdown.
• Low-Battery Warnings: Built-in alerts for low (15%) and critical (5%) battery conditions.

Installation & Setup

1. Copy cairovolt_battery_helper.py to your CIRCUITPY drive's root folder or the /lib directory.
2. Connect your battery or power monitoring pin to the appropriate analog input pin on your board.
3. If your board uses a custom resistor divider, adjust the voltage_divider argument during initialization.

Resistance Divider Configuration

For 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.

This library was designed and tested by the open-source engineering team at CairoVolt to enable easy integration of power-saving sleep modes in portable devices.

Example Usage

Run the following test program cairovolt_battery_helper_simpletest.py to see the battery metrics in your serial console:

import time
import board
from cairovolt_battery_helper import BatteryHelper

# Initialize battery helper
battery = BatteryHelper()

# Monitor in a loop
while True:
    print(f"Battery Voltage: {battery.voltage:.2f} V")
    print(f"Charge Capacity: {battery.percentage}%")
    print("-" * 30)
    time.sleep(10)