Historia

Frank dbe8554724 code spell checking - part3 (usermods) if you can spell Fahrenheit, you can't spell Celsius. And vice versa :-)		2023-12-14 03:52:06 +01:00
..
assets	…
battery_defaults.h	…
readme.md	code spell checking - part3 (usermods)	2023-12-14 03:52:06 +01:00
usermod_v2_Battery.h	…

readme.md

Welcome to the battery usermod! 🔋

Enables battery level monitoring of your project.

For this to work, the positive side of the (18650) battery must be connected to pin A0 of the d1 mini/esp8266 with a 100k Ohm resistor (see Useful Links).

If you have an ESP32 board, connect the positive side of the battery to ADC1 (GPIO32 - GPIO39)

⚙️ Features

💯 Displays current battery voltage
🚥 Displays battery level
🚫 Auto-off with configurable Threshold
🚨 Low power indicator with many configuration possibilities

🎈 Installation

define USERMOD_BATTERY in wled00/my_config.h

Example wiring

Define Your Options

Name	Unit	Description
`USERMOD_BATTERY`		define this (in `my_config.h`) to have this usermod included wled00\usermods_list.cpp
`USERMOD_BATTERY_USE_LIPO`		define this (in `my_config.h`) if you use LiPo rechargeables (1S)
`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_MIN_VOLTAGE`	v	minimum battery voltage. default is 2.6 (18650 battery standard)
`USERMOD_BATTERY_MAX_VOLTAGE`	v	maximum battery voltage. default is 4.2 (18650 battery standard)
`USERMOD_BATTERY_TOTAL_CAPACITY`	mAh	the capacity of all cells in parallel summed up
`USERMOD_BATTERY_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.

⚠️ Important

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,5 Wh
Minimum capacity	3350mAh 11,9 Wh
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

🌐 Useful Links

📝 Change Log

2023-01-04

basic support for LiPo rechargeable batteries ( -D USERMOD_BATTERY_USE_LIPO)
improved support for esp32 (read calibrated voltage)
corrected config saving (measurement pin, and battery min/max were lost)
various bugfixes

2022-12-25

added "auto-off" feature
added "low-power-indication" feature
added "calibration/offset" field to configuration page
added getter and setter, so that user usermods could interact with this one
update readme (added new options, made it markdownlint compliant)

2021-09-02

added "Battery voltage" to info
added circuit diagram to readme
added MQTT support, sending battery voltage
minor fixes

2021-08-15

changed USERMOD_BATTERY_MIN_VOLTAGE to 2.6 volt as default for 18650 batteries
Updated readme, added specification table

2021-08-10

Created