usermods/Battery/readme.md
Enables battery level monitoring of your project.
<p align="left"> </p>In platformio_override.ini (or platformio.ini)
Under: custom_usermods =, add the line: Battery
Example: platformio_override.ini |
<p><strong>ESP8266</strong>
With a 100k Ohm resistor, connect the positive
side of the battery to pin `A0`.</p>
<p><strong>ESP32</strong> (+S2, S3, C3 etc...)
Use a voltage divider (two resistors of equal value).
Connect to ADC1 (GPIO32 - GPIO39). GPIO35 is Default.</p>
| Name | Unit | Description |
|---|---|---|
USERMOD_BATTERY | Define this (in my_config.h) to have this usermod included wled00\usermods_list.cpp | |
USERMOD_BATTERY_MEASUREMENT_PIN | Defaults to A0 on ESP8266 and GPIO35 on ESP32 | |
USERMOD_BATTERY_MEASUREMENT_INTERVAL | ms | Battery check interval. defaults to 30 seconds |
USERMOD_BATTERY_INITIAL_DELAY | ms | Delay before initial reading. defaults to 10 seconds to allow voltage stabilization |
USERMOD_BATTERY_{TYPE}_MIN_VOLTAGE | v | Minimum battery voltage. default is 2.6 (18650 battery standard) |
USERMOD_BATTERY_{TYPE}_MAX_VOLTAGE | v | Maximum battery voltage. default is 4.2 (18650 battery standard) |
USERMOD_BATTERY_{TYPE}_TOTAL_CAPACITY | mAh | The capacity of all cells in parallel summed up |
USERMOD_BATTERY_{TYPE}_CALIBRATION | Offset / calibration number, fine tune the measured voltage by the microcontroller | |
| Auto-Off | --- | --- |
USERMOD_BATTERY_AUTO_OFF_ENABLED | true/false | Enables auto-off |
USERMOD_BATTERY_AUTO_OFF_THRESHOLD | % (0-100) | When this threshold is reached master power turns off |
| Low-Power-Indicator | --- | --- |
USERMOD_BATTERY_LOW_POWER_INDICATOR_ENABLED | true/false | Enables low power indication |
USERMOD_BATTERY_LOW_POWER_INDICATOR_PRESET | preset id | When low power is detected then use this preset to indicate low power |
USERMOD_BATTERY_LOW_POWER_INDICATOR_THRESHOLD | % (0-100) | When this threshold is reached low power gets indicated |
USERMOD_BATTERY_LOW_POWER_INDICATOR_DURATION | seconds | For this long the configured preset is played |
All parameters can be configured at runtime via the Usermods settings page.
NOTICE: Each Battery type can be pre-configured individualy (in my_config.h)
| Name | Alias | my_config.h example |
|---|---|---|
| Lithium Polymer | lipo (Li-Po) | USERMOD_BATTERY_lipo_MIN_VOLTAGE |
| Lithium Ionen | lion (Li-Ion) | USERMOD_BATTERY_lion_TOTAL_CAPACITY |
The calibration number is a value that is added to the final computed voltage after it has been scaled by the voltage multiplier.
It fine-tunes the voltage reading so that it more closely matches the actual battery voltage, compensating for inaccuracies inherent in the voltage divider resistors or the ESP's ADC measurements.
Set calibration either in the Usermods settings page or at compile time in my_config.h or platformio_override.ini.
It can be either a positive or negative number.
Make sure you know your battery specifications! All batteries are NOT the same!
Example:
| Your battery specification table | Options you can define | |
|---|---|---|
| Capacity | 3500mAh 12.5Wh | |
| Minimum capacity | 3350mAh 11.9Wh | |
| Rated voltage | 3.6V - 3.7V | |
| Charging end voltage | 4.2V ± 0.05 | USERMOD_BATTERY_MAX_VOLTAGE |
| Discharge voltage | 2.5V | USERMOD_BATTERY_MIN_VOLTAGE |
| Max. discharge current (constant) | 10A (10000mA) | |
| max. charging current | 1.7A (1700mA) | |
| ... | ... | ... |
| .. | .. | .. |
Specification from: Molicel INR18650-M35A, 3500mAh 10A Lithium-ion battery, 3.6V - 3.7V
2024-08-19
2024-05-11
2024-04-30
2023-01-04
-D USERMOD_BATTERY_USE_LIPO)2022-12-25
2021-09-02
2021-08-15
USERMOD_BATTERY_MIN_VOLTAGE to 2.6 volt as default for 18650 batteries2021-08-10