Battery 18650 Stats

Library to keeps easy to obtain 18650 (battery) charge level in Arduino environment.

This lib was made on top of Pangodream 18650CL

Compatibility

This Lib theoretically compatible with any ESP that has ACP pins and a 18650 Battery. It's tested with:

• LILYGO-T-Energy (T18)

Usage

Import and setup

To use this Lib, you need to import and setup:

#include <Battery18650Stats.h>

// #define ADC_PIN 35 
// #define CONVERSION_FACTOR 1.7 
// #define READS 5 

Battery18650Stats battery();
// Battery18650Stats battery(ADC_PIN);
// Battery18650Stats battery(ADC_PIN, CONVERSION_FACTOR);
// Battery18650Stats battery(ADC_PIN, CONVERSION_FACTOR, READS);

Constructor parameters:

Battery18650Stats(<adc_pin>, <conversion_factor>, <reads>);

• adc_pin (optional): The ADC Pin that lib will read (analogRead) to calculate charge level. Can be obtained at device datasheet. Default Value: 35;
• conversion_factor (optional): Value used to convert ADC pin reading in real battery voltage. This value can be obtained through comparisons between code result and a voltmeter result. Default Value: 1.702;
• reads (optional): Quantity of reads to get an average of pin readings. Its used due pin reading instabilities. Default Value: 20;

Methods

After the installation and instantiation, we are able to obtain the charge level and current battery voltage.

Method double getBatteryVolts()

Returns the current battery voltage.

Method int getBatteryChargeLevel(bool useConversionTable = false)

Returns the current battery charge level.

• Parameter bool useConversionTable: Indicates if the internal charge level will be obtained using the internal predefined conversion table instead the formula (default). Default value: false

Attention! Using predefined conversion table will consume more RAM than using the formula.

Usage example

#include <Battery18650Stats.h>

Battery18650Stats battery(35);

void setup() {
  Serial.begin(115200);
  Serial.print("Volts: ");
  Serial.println(battery.getBatteryVolts());
	
  Serial.print("Charge level: ");
  Serial.println(battery.getBatteryChargeLevel());
  
  Serial.print("Charge level (using the reference table): ");
  Serial.println(battery.getBatteryChargeLevel(true));
}

void loop {
  //
}

Troubleshoot and Finding Conversion Factor

Sometimes the result of getBatteryChargeLevel and getBatteryVolts may not represents the real state of the battery.

There are two main problems that could be happening:

• Your code is using the wrong ADC port or
• Your code is using the wrong conversion factor.

Finding the right ADC port

You can find the ADC ports in the device datasheet. The port can change according to the hardware you are using.

Finding the right conversion factor

To find the right conversion factor you will need a voltmeter.

Steps:

1. Measure the voltage of the battery with the voltmeter
2. Print the voltage obtained by the lib through getBatteryVolts method

If the measurements (library and voltmeter) match, the conversion factor is right. If they are different, you will need to increment or decrement the conversion factor until the measurements match.

Tested devices

This is the tested parameters and calibrations for given devices

Device	ADC Pin	Conversion Factor
LILYGO-T-Energy (T18)	35	1.702

License

The MIT License (MIT). Please see License File for more information.