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
  36 #define MAX_AUTO_DETECT_CELL_COUNT 8
  37
  38 #define GET_BATTERY_LPF_FREQUENCY(period) (1 / (period / 10.0f))
  39
  40 enum {
  41     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)
  42     AUTO_PROFILE_CELL_COUNT_CHANGE = -1, // Always switch to a profile with matching cell count if there is one
  43 };
  44
  45 typedef struct batteryConfig_s {
  46     // voltage
  47     uint16_t vbatmaxcellvoltage;            // maximum voltage per cell, used for auto-detecting battery voltage in 0.01V units, default is 430 (4.30V)
  48     uint16_t vbatmincellvoltage;            // minimum voltage per cell, this triggers battery critical alarm, in 0.01V units, default is 330 (3.30V)
  49     uint16_t vbatwarningcellvoltage;        // warning voltage per cell, this triggers battery warning alarm, in 0.01V units, default is 350 (3.50V)
  50     uint16_t vbatnotpresentcellvoltage;     // Between vbatmaxcellvoltage and 2*this is considered to be USB powered. Below this it is notpresent
  51     uint8_t lvcPercentage;                  // Percentage of throttle when lvc is triggered
  52     voltageMeterSource_e voltageMeterSource; // source of battery voltage meter used, either ADC or ESC
  53
  54     // current
  55     currentMeterSource_e currentMeterSource; // source of battery current meter used, either ADC, Virtual or ESC
  56     uint16_t batteryCapacity;               // mAh
  57
  58     // warnings / alerts
  59     bool useVBatAlerts;                     // Issue alerts based on VBat readings
  60     bool useConsumptionAlerts;              // Issue alerts based on total power consumption
  61     uint8_t consumptionWarningPercentage;   // Percentage of remaining capacity that should trigger a battery warning
  62     uint8_t vbathysteresis;                 // hysteresis for alarm, default 1 = 0.1V
  63
  64     uint16_t vbatfullcellvoltage;           // Cell voltage at which the battery is deemed to be "full" 0.01V units, default is 410 (4.1V)
  65
  66     uint8_t forceBatteryCellCount;          // Number of cells in battery, used for overwriting auto-detected cell count if someone has issues with it.
  67     uint8_t vbatDisplayLpfPeriod;           // Period of the cutoff frequency for the Vbat filter for display and startup (in 0.1 s)
  68     uint8_t ibatLpfPeriod;                  // Period of the cutoff frequency for the Ibat filter (in 0.1 s)
  69     uint8_t vbatDurationForWarning;         // Period voltage has to sustain before the battery state is set to BATTERY_WARNING (in 0.1 s)
  70     uint8_t vbatDurationForCritical;        // Period voltage has to sustain before the battery state is set to BATTERY_CRIT (in 0.1 s)
  71     uint8_t vbatSagLpfPeriod;               // Period of the cutoff frequency for the Vbat sag and PID compensation filter (in 0.1 s)
  72 } batteryConfig_t;
  73
  74 PG_DECLARE(batteryConfig_t, batteryConfig);
  75
  76 typedef struct lowVoltageCutoff_s {
  77     bool enabled;
  78     uint8_t percentage;
  79     timeUs_t startTime;
  80 } lowVoltageCutoff_t;
  81
  82 typedef enum {
  83     BATTERY_OK = 0,
  84     BATTERY_WARNING,
  85     BATTERY_CRITICAL,
  86     BATTERY_NOT_PRESENT,
  87     BATTERY_INIT
  88 } batteryState_e;
  89
  90 void batteryInit(void);
  91 void batteryUpdateVoltage(timeUs_t currentTimeUs);
  92 void batteryUpdatePresence(void);
  93
  94 batteryState_e getBatteryState(void);
  95 batteryState_e getVoltageState(void);
  96 batteryState_e getConsumptionState(void);
  97 const  char * getBatteryStateString(void);
  98
  99 void batteryUpdateStates(timeUs_t currentTimeUs);
 100 void batteryUpdateAlarms(void);
 101
 102 struct rxConfig_s;
 103
 104 float calculateVbatPidCompensation(void);
 105 uint8_t calculateBatteryPercentageRemaining(void);
 106 bool isBatteryVoltageConfigured(void);
 107 uint16_t getBatteryVoltage(void);
 108 uint16_t getLegacyBatteryVoltage(void);
 109 uint16_t getBatteryVoltageLatest(void);
 110 uint8_t getBatteryCellCount(void);
 111 uint16_t getBatteryAverageCellVoltage(void);
 112 uint16_t getBatterySagCellVoltage(void);
 113
 114 bool isAmperageConfigured(void);
 115 int32_t getAmperage(void);
 116 int32_t getAmperageLatest(void);
 117 int32_t getMAhDrawn(void);
 118
 119 void batteryUpdateCurrentMeter(timeUs_t currentTimeUs);
 120
 121 const lowVoltageCutoff_t *getLowVoltageCutoff(void);