src/main/sensors/battery.h

   1 /*
   2  * This file is part of Cleanflight and Betaflight.
   3  *
   4  * Cleanflight and Betaflight are free software. You can redistribute
   5  * this software and/or modify this software under the terms of the
   6  * GNU General Public License as published by the Free Software
   7  * Foundation, either version 3 of the License, or (at your option)
   8  * any later version.
   9  *
  10  * Cleanflight and Betaflight are distributed in the hope that they
  11  * will be useful, but WITHOUT ANY WARRANTY; without even the implied
  12  * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  13  * See the GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this software.
  17  *
  18  * If not, see <http://www.gnu.org/licenses/>.
  19  */
  20
  21 #pragma once
  22
  23 #include "pg/pg.h"
  24
  25 #include "common/filter.h"
  26 #include "common/time.h"
  27 #include "sensors/current.h"
  28 #include "sensors/voltage.h"
  29
  30 //TODO: Make the 'cell full' voltage user adjustble
  31 #define CELL_VOLTAGE_FULL_CV 420
  32
  33 #define VBAT_CELL_VOTAGE_RANGE_MIN 100
  34 #define VBAT_CELL_VOTAGE_RANGE_MAX 500
  35 #define VBAT_CELL_VOLTAGE_DEFAULT_MIN 330
  36 #define VBAT_CELL_VOLTAGE_DEFAULT_MAX 430
  37
  38 #define MAX_AUTO_DETECT_CELL_COUNT 8
  39
  40 #define GET_BATTERY_LPF_FREQUENCY(period) (1 / (period / 10.0f))
  41
  42 enum {
  43     AUTO_PROFILE_CELL_COUNT_STAY = 0, // Stay on this profile irrespective of the detected cell count. Use this profile if no other profile matches (default, i.e. auto profile switching is off)
  44     AUTO_PROFILE_CELL_COUNT_CHANGE = -1, // Always switch to a profile with matching cell count if there is one
  45 };
  46
  47 typedef struct batteryConfig_s {
  48     // voltage
  49     uint16_t vbatmaxcellvoltage;            // maximum voltage per cell, used for auto-detecting battery voltage in 0.01V units, default is 430 (4.30V)
  50     uint16_t vbatmincellvoltage;            // minimum voltage per cell, this triggers battery critical alarm, in 0.01V units, default is 330 (3.30V)
  51     uint16_t vbatwarningcellvoltage;        // warning voltage per cell, this triggers battery warning alarm, in 0.01V units, default is 350 (3.50V)
  52     uint16_t vbatnotpresentcellvoltage;     // Between vbatmaxcellvoltage and 2*this is considered to be USB powered. Below this it is notpresent
  53     uint8_t lvcPercentage;                  // Percentage of throttle when lvc is triggered
  54     voltageMeterSource_e voltageMeterSource; // source of battery voltage meter used, either ADC or ESC
  55
  56     // current
  57     currentMeterSource_e currentMeterSource; // source of battery current meter used, either ADC, Virtual or ESC
  58     uint16_t batteryCapacity;               // mAh
  59
  60     // warnings / alerts
  61     bool useVBatAlerts;                     // Issue alerts based on VBat readings
  62     bool useConsumptionAlerts;              // Issue alerts based on total power consumption
  63     uint8_t consumptionWarningPercentage;   // Percentage of remaining capacity that should trigger a battery warning
  64     uint8_t vbathysteresis;                 // hysteresis for alarm in 0.01V units, default 1 = 0.01V
  65
  66     uint16_t vbatfullcellvoltage;           // Cell voltage at which the battery is deemed to be "full" 0.01V units, default is 410 (4.1V)
  67
  68     uint8_t forceBatteryCellCount;          // Number of cells in battery, used for overwriting auto-detected cell count if someone has issues with it.
  69     uint8_t vbatDisplayLpfPeriod;           // Period of the cutoff frequency for the Vbat filter for display and startup (in 0.1 s)
  70     uint8_t ibatLpfPeriod;                  // Period of the cutoff frequency for the Ibat filter (in 0.1 s)
  71     uint8_t vbatDurationForWarning;         // Period voltage has to sustain before the battery state is set to BATTERY_WARNING (in 0.1 s)
  72     uint8_t vbatDurationForCritical;        // Period voltage has to sustain before the battery state is set to BATTERY_CRIT (in 0.1 s)
  73     uint8_t vbatSagLpfPeriod;               // Period of the cutoff frequency for the Vbat sag and PID compensation filter (in 0.1 s)
  74
  75 #ifdef USE_BATTERY_CONTINUE
  76     bool isBatteryContinueEnabled;
  77 #endif
  78 } batteryConfig_t;
  79
  80 PG_DECLARE(batteryConfig_t, batteryConfig);
  81
  82 typedef struct lowVoltageCutoff_s {
  83     bool enabled;
  84     uint8_t percentage;
  85     timeUs_t startTime;
  86 } lowVoltageCutoff_t;
  87
  88 typedef enum {
  89     BATTERY_OK = 0,
  90     BATTERY_WARNING,
  91     BATTERY_CRITICAL,
  92     BATTERY_NOT_PRESENT,
  93     BATTERY_INIT
  94 } batteryState_e;
  95
  96 void batteryInit(void);
  97 void batteryUpdateVoltage(timeUs_t currentTimeUs);
  98 void batteryUpdatePresence(void);
  99
 100 batteryState_e getBatteryState(void);
 101 batteryState_e getVoltageState(void);
 102 batteryState_e getConsumptionState(void);
 103 const  char * getBatteryStateString(void);
 104
 105 void batteryUpdateStates(timeUs_t currentTimeUs);
 106 void batteryUpdateAlarms(void);
 107
 108 struct rxConfig_s;
 109
 110 uint8_t calculateBatteryPercentageRemaining(void);
 111 bool isBatteryVoltageConfigured(void);
 112 uint16_t getBatteryVoltage(void);
 113 uint16_t getLegacyBatteryVoltage(void);
 114 uint16_t getBatteryVoltageLatest(void);
 115 uint8_t getBatteryCellCount(void);
 116 uint16_t getBatteryAverageCellVoltage(void);
 117 uint16_t getBatterySagCellVoltage(void);
 118
 119 bool isAmperageConfigured(void);
 120 int32_t getAmperage(void);
 121 int32_t getAmperageLatest(void);
 122 int32_t getMAhDrawn(void);
 123 float getWhDrawn(void);
 124 #ifdef USE_BATTERY_CONTINUE
 125 bool hasUsedMAh(void);
 126 void setMAhDrawn(uint32_t mAhDrawn);
 127 #endif
 128
 129 void batteryUpdateCurrentMeter(timeUs_t currentTimeUs);
 130
 131 const lowVoltageCutoff_t *getLowVoltageCutoff(void);