Skip to content

Commit dd465f8

Browse files
LK-SimonLK-Simon
committed
Initial Commit
1 parent 819cbcc commit dd465f8

File tree

12 files changed

+663
-0
lines changed

12 files changed

+663
-0
lines changed

‎README.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
[Latest Release - ![Release Version](https://img.shields.io/github/release/Flowduino/LithiumPowered.svg?style=plastic&logo=github)![Release Date](https://img.shields.io/github/release-date/Flowduino/LithiumPowered.svg?style=plastic&logo=github)](https://github.com/Flowduino/LithiumPowered/releases/latest/)
2+
3+
Need Help? [![Discord](https://img.shields.io/badge/Discuss-on%20Discord-7289d9?style=plastic&logo=discord)](https://discord.gg/jpwBy7VzaG) [![Instagram](https://img.shields.io/badge/Follow-on%20Instagram-c32aa3?style=plastic&logo=instagram)](https://instagram.com/Flowduino)
4+
5+
# LithiumPowered
6+
A (hopefully) Universal Library for Lithium-Powered Projects, designed to be available for both Arduino IDE and PlatformIO Projects.
7+
8+
This Library uses a Coulomb Counter (*such as the LTC4150 circuit*) to accurately keep track of the state of specifically Lithium Ion (*Li-Ion*) and Lithium Polymer (*Li-Po*) Batteries.
9+
10+
What makes this Library particularly beneficial is that it fully-encapsulates the code necessary to automatically and dynamically Calibrate the Battery Capacity (*in mAh*) while the Battery is Charging *and* Discharging. It also leverages persistent Storage on your MCU so that the Battery State is always remembered between power cycles (*switching your device off and on*)
11+
12+
## Cross-Platform
13+
LithiumPowered is designed to function identically for all MCUs* and all Lithium Battery Types & Capacities**.
14+
15+
>* *Must have suitable GPIO pins, support Interrupts (*ISR*), and provide some form of compatible persistent Storage (*e.g. EEPROM*).
16+
>* **You must configure your `Battery` instance by telling it the expected Capacity (*in mAh*) of your Lithium Cell(s)
17+
18+
## Easy Callbacks
19+
The operative Class, `Battery`, can be initialised with an Instance of your own custom decendant of `BatteryCallbacks`. Each method defined in `BatteryCallbacks` that you override in your decendant will be invokved as an *Event* reflecting the name of the respective overriden Method.
20+
21+
e.g.
22+
23+
```c++
24+
class MyBatteryCallbacks: public BatteryCallbacks {
25+
public:
26+
void onBatteryNowCharging() {
27+
Serial.println("Battery is now Charging!");
28+
}
29+
30+
void onBatteryNowDischarging() {
31+
Serial.println("Battery is no longer Charging!");
32+
}
33+
};
34+
```
35+
36+
## GPIO Settings
37+
The operative Class, `Battery`, can be initialised with an Instance of your own custom decendant of `BatteryGPIO`.
38+
Each method defined in `BatteryGPIO` that you override in your decendant will define an explicit GPIO Pin to be used for the corresponding Coloumb Pin represented by the name of the respective overriden Method.
39+
40+
e.g.
41+
42+
```c++
43+
class MyBatteryGPIO: public BatteryGPIO {
44+
uint8_t getPinInterrupt() { return 14; };
45+
};
46+
```
47+
48+
The above will tell our `Battery` instance to use GPIO Pin 14 for the main Coloumb Counter Interrupt pin, rather than the default defined in the Base Class, `BatteryGPIO`.
49+
50+
## Initialising Battery
51+
52+
```c++
53+
#include <LithiumPowered.h>
54+
55+
Battery myBattery();
56+
57+
void setup() {
58+
Serial.begin(115200);
59+
60+
myBattery.setCallbacks(new MyBatteryCallbacks()); // Use your Custom Callbacks
61+
myBattery.setGpio(new MyBatteryGPIO()); // Use your Custom GPIO Settings
62+
// We would now change any Properties of myBattery as required
63+
myBattery.setup(); // This will Initialise our Battery instance with the given Property values
64+
};
65+
66+
void loop() {
67+
myBattery.loop(); // We need to ensure we Loop our Battery Instance to update its State
68+
}
69+
```
70+
71+
With the above in place, we will now see lines appear in the Console Output each time we connect or disconnect (respectively) our Device to an external Power Supply.
72+
73+
**Note: If you are supplying power through the cable used to monitor Serial output, your Device will *always* be Charging!**

‎examples/BasicDemo/.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
.pio
2+
.vscode/.browse.c_cpp.db*
3+
.vscode/c_cpp_properties.json
4+
.vscode/launch.json
5+
.vscode/ipch

‎examples/BasicDemo/.vscode/extensions.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
// See http://go.microsoft.com/fwlink/?LinkId=827846
3+
// for the documentation about the extensions.json format
4+
"recommendations": [
5+
"platformio.platformio-ide"
6+
]
7+
}

‎examples/BasicDemo/lib/README‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
2+
This directory is intended for project specific (private) libraries.
3+
PlatformIO will compile them to static libraries and link into executable file.
4+
5+
The source code of each library should be placed in a an own separate directory
6+
("lib/your_library_name/[here are source files]").
7+
8+
For example, see a structure of the following two libraries `Foo` and `Bar`:
9+
10+
|--lib
11+
| |
12+
| |--Bar
13+
| | |--docs
14+
| | |--examples
15+
| | |--src
16+
| | |- Bar.c
17+
| | |- Bar.h
18+
| | |- library.json (optional, custom build options, etc) https://docs.platformio.org/page/librarymanager/config.html
19+
| |
20+
| |--Foo
21+
| | |- Foo.c
22+
| | |- Foo.h
23+
| |
24+
| |- README --> THIS FILE
25+
|
26+
|- platformio.ini
27+
|--src
28+
|- main.c
29+
30+
and a contents of `src/main.c`:
31+
```
32+
#include <Foo.h>
33+
#include <Bar.h>
34+
35+
int main (void)
36+
{
37+
...
38+
}
39+
40+
```
41+
42+
PlatformIO Library Dependency Finder will find automatically dependent
43+
libraries scanning project source files.
44+
45+
More information about PlatformIO Library Dependency Finder
46+
- https://docs.platformio.org/page/librarymanager/ldf.html

‎examples/BasicDemo/platformio.ini‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
[platformio]
2+
description = LithiumPowered - Basic Demo
3+
4+
[Common]
5+
monitor_speed = 115200
6+
framework = arduino
7+
lib_deps =
8+
lib_extra_dirs = ${PROJECT_DIR}../../src
9+
10+
[ESP32_Common]
11+
framework = ${Common.framework}
12+
platform = https://github.com/platformio/platform-espressif32.git
13+
board = esp32dev
14+
upload_port = /dev/cu.usbserial-6
15+
upload_speed = 921000
16+
monitor_port = /dev/cu.usbserial-6
17+
monitor_speed = ${Common.monitor_speed}
18+
lib_deps =
19+
${Common.lib_deps}
20+
lib_extra_dirs =
21+
${Common.lib_extra_dirs}
22+
23+
[env:ESP32_Release]
24+
framework = ${ESP32_Common.framework}
25+
platform = ${ESP32_Common.platform}
26+
board = ${ESP32_Common.board}
27+
upload_port = ${ESP32_Common.upload_port}
28+
upload_speed = ${ESP32_Common.upload_speed}
29+
monitor_port = ${ESP32_Common.monitor_port}
30+
monitor_speed = ${ESP32_Common.monitor_speed}
31+
lib_deps =
32+
${ESP32_Common.framework}
33+
lib_extra_dirs =
34+
${ESP32_Common.framework}
35+
build_type = release
36+
37+
[env:ESP32_Debug]
38+
framework = ${ESP32_Common.framework}
39+
platform = ${ESP32_Common.platform}
40+
board = ${ESP32_Common.board}
41+
upload_port = ${ESP32_Common.upload_port}
42+
upload_speed = ${ESP32_Common.upload_speed}
43+
monitor_port = ${ESP32_Common.monitor_port}
44+
monitor_speed = ${ESP32_Common.monitor_speed}
45+
lib_deps =
46+
${ESP32_Common.framework}
47+
lib_extra_dirs =
48+
${ESP32_Common.framework}
49+
build_type = debug
50+
debug_tool = esp-prog
51+
debug_init_break = tbreak setup

‎examples/BasicDemo/src/main.cpp‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
#include <Arduino.h>
2+
3+
#ifdef ESP32
4+
#include <Preferences.h> // CRITICAL FOR ESP32 DEVICES!
5+
#endif
6+
7+
#include <LithiumPowered.hpp>
8+
9+
#define BATTERY_RATED_CAPACITY 900.00 // Set this to the Rated Capacity of your Battery in mAh!
10+
11+
class MyBatteryCallbacks: public BatteryCallbacks {
12+
public:
13+
virtual void onBatteryNowCharging() {
14+
Serial.println("Battery is now Charging!");
15+
};
16+
17+
virtual void onBatteryNowDischarging() {
18+
Serial.println("Battery is no longer Charging!");
19+
};
20+
21+
virtual void onBatteryRemainingCapacityChanged() {
22+
Serial.print("Battery Update: ");
23+
Serial.print(Battery.getPercentage());
24+
Serial.print("% ");
25+
Serial.print(Battery.getCurrentCapacity());
26+
Serial.print("mAh remaining. ");
27+
Serial.print(Battery.getIsCharging() ? "Charging at +" : "Discharging at ");
28+
Serial.print(Battery.getChangeCapacityWithPolarity());
29+
Serial.print("mAh");
30+
if (Battery.getIsCharging()) {
31+
Serial.print(" - Time to full: ");
32+
Serial.print(Battery.getTimeToChargeInMinutes());
33+
}
34+
else {
35+
Serial.print(" - Time to empty: ");
36+
Serial.print(Battery.getTimeToDischargeInMinutes());
37+
}
38+
Serial.println(" min");
39+
};
40+
41+
virtual void onBatteryRecalibrated() {
42+
Serial.print("Maximum Battery Capacity has been Recalibrated!");
43+
};
44+
};
45+
46+
//#define USE_CUSTOM_GPIO // Uncomment this line if you need to use Custom GPIO Pins!
47+
48+
#ifdef USE_CUSTOM_GPIO
49+
class MyBatteryGPIO: public BatteryGPIO {
50+
public:
51+
// Override this to provide the GPIO Pin Number for the Coloumb Counter's Polarity Pin
52+
virtual uint8_t getPinPolarity() {
53+
return 4;
54+
}
55+
56+
// Override this to provide the GPIO Pin Number for the Coloumb Counter's Interrupt Pin
57+
virtual uint8_t getPinInterrupt() {
58+
return 35;
59+
}
60+
61+
// Override this to provide the GPIO Pin Number for the Coloumb Counter's High State Reference Pin
62+
virtual uint8_t getPinRefHigh() {
63+
return 23;
64+
}
65+
66+
// Override this to provide the GPIO Pin Number for the Coloumb Counter's Low State Reference Pin
67+
virtual uint8_t getPinRefLow() {
68+
return 5;
69+
}
70+
};
71+
#endif
72+
73+
void setup() {
74+
Serial.begin(115200); // Initialise Serial interface at 115200 Baud
75+
76+
#ifdef USE_CUSTOM_GPIO
77+
Battery.setGpio(new MyBatteryGPIO()); // We want to use specific GPIO Pins
78+
#endif
79+
Battery.setCallbacks(new MyBatteryCallbacks()); // Use our custom Callbacks for Battery Events
80+
Battery.setup(BATTERY_RATED_CAPACITY); // Initialise the LithiumPowered Battery System
81+
}
82+
83+
void loop() {
84+
Battery.loop(); // Required to perform State Updates for the LithiumPowered Battery System.
85+
}

‎examples/BasicDemo/test/README‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
2+
This directory is intended for PlatformIO Unit Testing and project tests.
3+
4+
Unit Testing is a software testing method by which individual units of
5+
source code, sets of one or more MCU program modules together with associated
6+
control data, usage procedures, and operating procedures, are tested to
7+
determine whether they are fit for use. Unit testing finds problems early
8+
in the development cycle.
9+
10+
More information about PlatformIO Unit Testing:
11+
- https://docs.platformio.org/page/plus/unit-testing.html

‎library.properties‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
name=Lithium-Powered
2+
version=0.0.1
3+
author=Flowduino
4+
maintainer=Flowduino <[email protected]>
5+
sentence=All-In-One Code Solution for Lithium Battery Management using the LTC4150 Coulomb Counter circuit.
6+
paragraph=This library provides you with an elegant and simple solution for managing Lithium Batteries on your Arduino and ESP devices.
7+
url=https://github.com/Flowduino/LithiumPowered
8+
category=Device Control
9+
architectures=*
10+
includes=LithiumPowered.hpp,LithiumStorage.hpp

‎platformio.ini‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
; PlatformIO Project Configuration File
2+
;
3+
; Build options: build flags, source filter
4+
; Upload options: custom upload port, speed and extra flags
5+
; Library options: dependencies, extra library storages
6+
; Advanced options: extra scripting
7+
;
8+
; Please visit documentation for the other options and examples
9+
; https://docs.platformio.org/page/projectconf.html
10+
11+
[platformio]
12+
src_dir = examples/BasicDemo/src
13+
lib_dir = src

‎src/LithiumPowered.cpp‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
#include <LithiumPowered.hpp>
2+
3+
LithiumBattery& LithiumBattery::getInstance() {
4+
static LithiumBattery battery;
5+
return battery;
6+
}
7+
8+
LithiumBattery &Battery = Battery.getInstance();
9+
10+
void ISR_Battery_ChargeChanged() {
11+
Battery._interruptChargeChanged();
12+
}
13+
14+
void ISR_Battery_PolarityChanged() {
15+
Battery._interruptPolarityChanged();
16+
}
17+
18+
void LithiumBattery::attachInterrupts() {
19+
attachInterrupt(digitalPinToInterrupt(Battery._pGpio->getPinInterrupt()), ISR_Battery_ChargeChanged, FALLING);
20+
attachInterrupt(digitalPinToInterrupt(Battery._pGpio->getPinPolarity()), ISR_Battery_PolarityChanged, CHANGE);
21+
}

0 commit comments

Comments
 (0)