jeans/WLED
jeans/WLED
1
0
Fork 0
mirror of https://github.com/wled/WLED.git synced 2025-07-12 13:26:33 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #3968 from adamsthws/0_15_battery_usermod_readme

Browse Source 
Update Battery usermod documentation
This commit is contained in:
Blaž Kristan 2024-05-21 18:17:08 +02:00 committed by GitHub
commit 0bcdc9641d
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
5 changed files with 100 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
usermods/Battery/assets/battery_connection_schematic_esp32.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 129 KiB

BIN
usermods/Battery/assets/battery_connection_schematic_esp32_v2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 64 KiB

BIN
usermods/Battery/assets/installation_my_config_h.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 49 KiB

BIN
usermods/Battery/assets/installation_platformio_override_ini.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 54 KiB

155
usermods/Battery/readme.md
View File

@ -6,54 +6,79 @@
Enables battery level monitoring of your project. 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](#useful-links)). <p align="left">
<img width="700" src="assets/battery_info_screen.png">
If you have an ESP32 board, connect the positive side of the battery to ADC1 (GPIO32 - GPIO39)
<p align="center">
<img width="500" src="assets/battery_info_screen.png">
</p> </p>
<br>
## ⚙️ Features ## ⚙️ Features
- 💯 Displays current battery voltage - 💯 Displays current battery voltage
- 🚥 Displays battery level - 🚥 Displays battery level
- 🚫 Auto-off with configurable Threshold - 🚫 Auto-off with configurable threshold
- 🚨 Low power indicator with many configuration possibilities - 🚨 Low power indicator with many configuration possibilities
<br><br>
## 🎈 Installation ## 🎈 Installation
define `USERMOD_BATTERY` in `wled00/my_config.h` | **Option 1** | **Option 2** |
|--------------|--------------|
| In `wled00/my_config.h`<br>Add the line: `#define USERMOD_BATTERY`<br><br>[Example: my_config.h](assets/installation_my_config_h.png) | In `platformio_override.ini` (or `platformio.ini`)<br>Under: `build_flags =`, add the line: `-D USERMOD_BATTERY`<br><br>[Example: platformio_override.ini](assets/installation_platformio_override_ini.png) |
### Example wiring <br><br>
<p align="center"> ## 🔌 Example wiring
<img width="300" src="assets/battery_connection_schematic_01.png">
</p>
### Define Your Options - (see [Useful Links](#useful-links)).
<table style="width: 100%; table-layout: fixed;">
<tr>
<!-- Column for the first image -->
<td style="width: 50%; vertical-align: bottom;">
<img width="300" src="assets/battery_connection_schematic_01.png" style="display: block;">
<p><strong>ESP8266</strong><br>
With a 100k Ohm resistor, connect the positive<br>
side of the battery to pin `A0`.</p>
</td>
<!-- Column for the second image -->
<td style="width: 50%; vertical-align: bottom;">
<img width="250" src="assets/battery_connection_schematic_esp32.png" style="display: block;">
<p><strong>ESP32</strong> (+S2, S3, C3 etc...)<br>
Use a voltage divider (two resistors of equal value).<br>
Connect to ADC1 (GPIO32 - GPIO39). GPIO35 is Default.</p>
</td>
</tr>
</table>
<br><br>
## Define Your Options
| Name | Unit | Description | | Name | Unit | Description |
| ----------------------------------------------- | ----------- |-------------------------------------------------------------------------------------- | | ----------------------------------------------- | ----------- |-------------------------------------------------------------------------------------- |
| `USERMOD_BATTERY` | | define this (in `my_config.h`) to have this usermod included wled00\usermods_list.cpp | | `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_PIN` | | Defaults to A0 on ESP8266 and GPIO35 on ESP32 |
| `USERMOD_BATTERY_INITIAL_DELAY` | ms | delay before initial reading. defaults to 10 seconds to allow voltage stabilization | `USERMOD_BATTERY_MEASUREMENT_INTERVAL` | ms | Battery check interval. defaults to 30 seconds |
| `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}_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}_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}_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 | | `USERMOD_BATTERY_{TYPE}_CALIBRATION` | | Offset / calibration number, fine tune the measured voltage by the microcontroller |
| Auto-Off | --- | --- | | Auto-Off | --- | --- |
| `USERMOD_BATTERY_AUTO_OFF_ENABLED` | true/false | enables 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 | | `USERMOD_BATTERY_AUTO_OFF_THRESHOLD` | % (0-100) | When this threshold is reached master power turns off |
| Low-Power-Indicator | --- | --- | | Low-Power-Indicator | --- | --- |
| `USERMOD_BATTERY_LOW_POWER_INDICATOR_ENABLED` | true/false | enables low power indication | | `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_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_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 | | `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. All parameters can be configured at runtime via the Usermods settings page.
<br>
**NOTICE:** Each Battery type can be pre-configured individualy (in `my_config.h`) **NOTICE:** Each Battery type can be pre-configured individualy (in `my_config.h`)
| Name | Alias | `my_config.h` example | | Name | Alias | `my_config.h` example |
@ -61,66 +86,86 @@ All parameters can be configured at runtime via the Usermods settings page.
| Lithium Polymer | lipo (Li-Po) | `USERMOD_BATTERY_lipo_MIN_VOLTAGE` | | Lithium Polymer | lipo (Li-Po) | `USERMOD_BATTERY_lipo_MIN_VOLTAGE` |
| Lithium Ionen | lion (Li-Ion) | `USERMOD_BATTERY_lion_TOTAL_CAPACITY` | | Lithium Ionen | lion (Li-Ion) | `USERMOD_BATTERY_lion_TOTAL_CAPACITY` |
<br><br>
## 🔧 Calibration
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.
<br><br>
## ⚠️ Important ## ⚠️ Important
- Make sure you know your battery specifications! All batteries are **NOT** the same! Make sure you know your battery specifications! All batteries are **NOT** the same!
- Example:
| Your battery specification table | | Options you can define | Example:
| :-------------------------------- |:--------------- | :---------------------------- |
| Capacity | 3500mAh 12,5 Wh | | | Your battery specification table | | Options you can define |
| Minimum capacity | 3350mAh 11,9 Wh | | | --------------------------------- | --------------- | ----------------------------- |
| Capacity | 3500mAh 12.5Wh | |
| Minimum capacity | 3350mAh 11.9Wh | |
| Rated voltage | 3.6V - 3.7V | | | Rated voltage | 3.6V - 3.7V | |
| **Charging end voltage** | **4,2V ± 0,05** | `USERMOD_BATTERY_MAX_VOLTAGE` | | **Charging end voltage** | **4.2V ± 0.05** | `USERMOD_BATTERY_MAX_VOLTAGE` |
| **Discharge voltage** | **2,5V** | `USERMOD_BATTERY_MIN_VOLTAGE` | | **Discharge voltage** | **2.5V** | `USERMOD_BATTERY_MIN_VOLTAGE` |
| Max. discharge current (constant) | 10A (10000mA) | | | Max. discharge current (constant) | 10A (10000mA) | |
| max. charging current | 1.7A (1700mA) | | | max. charging current | 1.7A (1700mA) | |
| ... | ... | ... | | ... | ... | ... |
| .. | .. | .. | | .. | .. | .. |
Specification from: [Molicel INR18650-M35A, 3500mAh 10A Lithium-ion battery, 3.6V - 3.7V](https://www.akkuteile.de/lithium-ionen-akkus/18650/molicel/molicel-inr18650-m35a-3500mah-10a-lithium-ionen-akku-3-6v-3-7v_100833) Specification from: [Molicel INR18650-M35A, 3500mAh 10A Lithium-ion battery, 3.6V - 3.7V](https://www.akkuteile.de/lithium-ionen-akkus/18650/molicel/molicel-inr18650-m35a-3500mah-10a-lithium-ionen-akku-3-6v-3-7v_100833)
<br><br>
## 🌐 Useful Links ## 🌐 Useful Links
- https://lazyzero.de/elektronik/esp8266/wemos_d1_mini_a0/start - https://lazyzero.de/elektronik/esp8266/wemos_d1_mini_a0/start
- https://arduinodiy.wordpress.com/2016/12/25/monitoring-lipo-battery-voltage-with-wemos-d1-minibattery-shield-and-thingspeak/ - https://arduinodiy.wordpress.com/2016/12/25/monitoring-lipo-battery-voltage-with-wemos-d1-minibattery-shield-and-thingspeak/
<br><br>
## 📝 Change Log ## 📝 Change Log
2024-04-30 2024-05-11
- improved initial reading accuracy by delaying initial measurement to allow voltage to stabilize at power-on - Documentation updated
2024-04-30 2024-04-30
- integrate factory pattern to make it easier to add other / custom battery types - Integrate factory pattern to make it easier to add other / custom battery types
- update readme - Update readme
- Improved initial reading accuracy by delaying initial measurement to allow voltage to stabilize at power-on
2023-01-04 2023-01-04
- basic support for LiPo rechargeable batteries ( `-D USERMOD_BATTERY_USE_LIPO`) - Basic support for LiPo rechargeable batteries (`-D USERMOD_BATTERY_USE_LIPO`)
- improved support for esp32 (read calibrated voltage) - Improved support for ESP32 (read calibrated voltage)
- corrected config saving (measurement pin, and battery min/max were lost) - Corrected config saving (measurement pin, and battery min/max were lost)
- various bugfixes - Various bugfixes
2022-12-25 2022-12-25
- added "auto-off" feature - Added "auto-off" feature
- added "low-power-indication" feature - Added "low-power-indication" feature
- added "calibration/offset" field to configuration page - Added "calibration/offset" field to configuration page
- added getter and setter, so that user usermods could interact with this one - Added getter and setter, so that user usermods could interact with this one
- update readme (added new options, made it markdownlint compliant) - Update readme (added new options, made it markdownlint compliant)
2021-09-02 2021-09-02
- added "Battery voltage" to info - Added "Battery voltage" to info
- added circuit diagram to readme - Added circuit diagram to readme
- added MQTT support, sending battery voltage - Added MQTT support, sending battery voltage
- minor fixes - Minor fixes
2021-08-15 2021-08-15
- changed `USERMOD_BATTERY_MIN_VOLTAGE` to 2.6 volt as default for 18650 batteries - Changed `USERMOD_BATTERY_MIN_VOLTAGE` to 2.6 volt as default for 18650 batteries
- Updated readme, added specification table - Updated readme, added specification table
2021-08-10 2021-08-10