Merge pull request #59 from nicholaswilde/add-percentage

Add Battery Percentage

config.h

@@ -10,8 +10,10 @@
 #define FIELD_NO_POWER 4        // field number of battery power
 
 #define SLEEP_TIME 15           // the time the Feather goes into a deep sleep (m)
-#define VOLTAGE_MAX 4.2         // max voltage of lipo battery (V)
-#define VOLTAGE_MIN 2.64        // min voltage of lipo battery (V)
+#define VOLTAGE_MAX 4072        // max voltage of lipo battery (V)
+#define VOLTAGE_MIN 3000        // min voltage of lipo battery (V)
+#define EXP_A 0.00348           // y = B * exp(A*x)
+#define EXP_B 0.000000686       // y = B * exp(A*x)
 
 // Pins
 #define BUTTON_A 15

docs/calibration.md

@@ -0,0 +1,88 @@
+# Calibration
+
+Instead of using a linear fit to calculate the battery percentage, the sketch
+uses the [coulomb counting method][1] by using the collection time interval and current
+passing to the battery. 
+
+## :chart_with_upwards_trend: Exponential Trendline
+
+The sketch uses an exponetial trendline for a voltage versus percentage to calculate the
+battyer percentage.
+
+The formula for the exponential trendline is as follows:
+
+$$
+B{\rm e}^{Ax}
+$$
+
+The coefficients of the trendline can be found from the equation of the exponential trendline
+on the chart.
+
+![](../assets/images/voltage-vs-percentage.png)
+
+In this instance, the following coefficients are found:
+
+$$
+y=6.86\mathrm{E}{-07}{\rm e}^{3.48\mathrm{E}{-03}x}
+$$
+
+$$
+B=0.000000686
+$$
+
+$$
+A=0.00348
+$$
+
+These coefficients can then be entered into the `config.h` file as `EXP_A` and `EXP_B`.
+
+!!! note
+    The coefficients supplied with the sketch were found using two 3000 mAh batteries.
+
+The maximum and minimum voltages can be found by from this data as well and transcribed
+to the `config.h` file in the `VOLTAGE_MAX` and `VOLTAGE_MIN` parameters.
+
+## :page_facing_up: Google Sheet
+
+The scatter plot is created by performing the following steps:
+
+- Collect data from when the batteries are fully depleted to fully charged.
+  This can be done either using a solar panel or wall wart.
+- Create a column that calculates the time in duration between readings in hours.
+- Create a column that multiplies the current by the time duration to get the
+  number of coulombs collected in that time interval.
+- Create another column that sums the amount of coulombs collected up to that period
+  in time.
+- Create another column that calculates the percentage by dividing the previous column
+  with the maximum number of coulombs collected.
+- Create a scatter plot that with the voltage on the X-Axis and percentage on the Y-Axis.
+- Add an exponential trendline with the equation in in the legend.
+- Transcribe the coefficients of the trendline to the `config.h` file in the `EXP_A` and
+  `EXP_B` parameters.
+
+!!! note
+    The data collection needs to start when the battery is fully depleted (cut off by the BMS)
+    in order to accurately calibrate the system.
+
+## :page_with_curl: Template
+
+WIP ([#57][2])
+
+## :raised_hand: Current Limitations
+
+- The Google Sheet assumes that the current over the collection period is constant.
+  Integration of the current versus time would be a better estimation of the amount
+  of energy collected.
+- The collection at the end of the charge can be a bit erratic and group around the same
+  same voltage. This was clipped in my original data.
+- The coefficients can only be found by the equation on the scatter plot chart. Have not
+  figured out a way to calculate the coefficients in a Sheet cell ([#58][3]).
+
+## :link: References
+
+- https://github.com/rlogiacco/BatterySense#remaining-capacity-approximation
+- https://batteryuniversity.com/article/bu-903-how-to-measure-state-of-charge
+
+[1]: https://batteryuniversity.com/article/bu-903-how-to-measure-state-of-charge
+[2]: https://github.com/nicholaswilde/solar-battery-charger/issues/57
+[3]: https://github.com/nicholaswilde/solar-battery-charger/issues/58

docs/configuration.md

@@ -310,6 +310,10 @@ Set `doSheets` in the `config.h` file to `true` to enable the uploading of value
     the email address specified in `CLIENT_EMAIL` in order to write to it using the Google Cloud
     Platform.
 
+## Battery Percentage
+
+See the [calibration page](./calibration.md) on how to calibrate the system.
+
 ## :robot: Task
 
 [go-task][10] may be used to automate some of the commands.

mkdocs.yml

@@ -17,6 +17,7 @@ nav:
   - About: about.md
   - Design: design.md
   - Configuration: configuration.md
+  - Calibration: calibration.md
   - Test:
       - adjusttime: test/adjusttime.md
       - animation: test/animation.md

solar-battery-charger.ino

@@ -83,7 +83,7 @@ void loop() {
   current = abs(current);
 
   int voltage = ina260.readBusVoltage();
-  int percentage;
+  int percentage = getPercentage(voltage);
   int power = ina260.readPower();
 
   if(!doDischarge && !doWake)executeRecharge(percentage, voltage, current, power);
@@ -281,6 +281,15 @@ int getWakeupPin(){
 
 /* ------------------------------- Functions ------------------------------- */
 
+int getPercentage(int voltage){
+  if (voltage <= VOLTAGE_MIN) {
+    return 0;
+	} else if (voltage >= VOLTAGE_MAX) {
+		return 100;
+  }
+  return (float)EXP_B * exp((float)EXP_A*voltage)*100;
+}
+
 bool checkButton() {
   static bool oldButton;
   bool but = !digitalRead(BUTTON_A);