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 } batteryConfig_t;
  75
  76 PG_DECLARE(batteryConfig_t, batteryConfig);
  77
  78 typedef struct lowVoltageCutoff_s {
  79     bool enabled;
  80     uint8_t percentage;
  81     timeUs_t startTime;
  82 } lowVoltageCutoff_t;
  83
  84 typedef enum {
  85     BATTERY_OK = 0,
  86     BATTERY_WARNING,
  87     BATTERY_CRITICAL,
  88     BATTERY_NOT_PRESENT,
  89     BATTERY_INIT
  90 } batteryState_e;
  91
  92 void batteryInit(void);
  93 void batteryUpdateVoltage(timeUs_t currentTimeUs);
  94 void batteryUpdatePresence(void);
  95
  96 batteryState_e getBatteryState(void);
  97 batteryState_e getVoltageState(void);
  98 batteryState_e getConsumptionState(void);
  99 const  char * getBatteryStateString(void);
 100
 101 void batteryUpdateStates(timeUs_t currentTimeUs);
 102 void batteryUpdateAlarms(void);
 103
 104 struct rxConfig_s;
 105
 106 uint8_t calculateBatteryPercentageRemaining(void);
 107 bool isBatteryVoltageConfigured(void);
 108 uint16_t getBatteryVoltage(void);
 109 uint16_t getLegacyBatteryVoltage(void);
 110 uint16_t getBatteryVoltageLatest(void);
 111 uint8_t getBatteryCellCount(void);
 112 uint16_t getBatteryAverageCellVoltage(void);
 113 uint16_t getBatterySagCellVoltage(void);
 114
 115 bool isAmperageConfigured(void);
 116 int32_t getAmperage(void);
 117 int32_t getAmperageLatest(void);
 118 int32_t getMAhDrawn(void);
 119
 120 void batteryUpdateCurrentMeter(timeUs_t currentTimeUs);
 121
 122 const lowVoltageCutoff_t *getLowVoltageCutoff(void);