battery.h File Reference

Battery related functions. More...

#include "Arduino.h"

Go to the source code of this file.

Macros
#define	RAW_BATTERY_MULTIPLIER   0.0075196210
	The divider between real battery voltage and STM32 input is 8.2K-1k resistors So, the multiplier is 1/(1+8.2)=0.1087 Considering 0.1% precision resistances, multiplier is between 0,108502 and 0,108889 The reference is 3.348V (measured on 53 HW V3 boards) RawValue = (Vbat*0.1087)*1024/3.348 So, Vbat = RawValue * (3.348/(1024*0.1087)) More...
#define	RAW_VOLTAGE_MAINS   3643u
	Expected voltage in volts when power cord is plugged 27,4 V => 27,4 / RAW_BATTERY_MULTIPLIER. More...
#define	RAW_VOLTAGE_ON_BATTERY_HIGH   3590u
	RCM_SW_16 Expected voltage in volts when power cord is unplugged = 27 => 27 / RAW_BATTERY_MULTIPLIER. More...
#define	RAW_VOLTAGE_HYSTERESIS   12u
	Hysteresis is used to prevent fast switching when voltage is at the limit of 2 states analogRead(PIN) * RAW_BATTERY_MULTIPLIER = 0,1 => 0,1 / RAW_BATTERY_MULTIPLIER = 3. More...
#define	RAW_VOLTAGE_ON_BATTERY   3085u
	RCM_SW_11 = 23,2 => 23,2 / RAW_BATTERY_MULTIPLIER. More...
#define	RAW_VOLTAGE_ON_BATTERY_LOW   3005u
	RCM_SW_12 = 22,6 => 22,6 / RAW_BATTERY_MULTIPLIER. More...
#define	RAW_VOLTAGE_ON_BATTERY_NOT_STARTING_THRESHOLD   3191u
	Below this value, the machine wont start = 22 => 22 / RAW_BATTERY_MULTIPLIER. More...
#define	RAW_VOLTAGE_ON_BATTERY_STOP_THRESHOLD   2660u
	Below this value, the machine will stop immediately = 20 => 20 / RAW_BATTERY_MULTIPLIER. More...
#define	BATTERY_MAX_SAMPLES   20u
	Number of samples of the moving average. More...

Functions
void	initBattery ()
	Initialize battery abstraction. More...
void	batteryLoop (uint32_t p_cycleNumber)
	Handle battery events. More...
void	updateBatterySample ()
	Handle battery voltage calculation. More...
void	updateBatteryState (uint32_t p_cycleNumber)
	Updates battery states. More...
uint32_t	getBatteryLevel ()
	Returns battery level. More...
uint32_t	getBatteryLevelX10 ()
	Returns battery level x10 for better accuracy. More...
uint32_t	getBatteryLevelX100 ()
	Returns battery level x100 for better accuracy. More...
bool	isBatteryVeryLow ()
	Check if battery level is very low. More...
bool	isBatteryDeepDischarged ()
	Check if battery is deeply discharged. More...
bool	isMainsConnected ()
	Check if mains are connected. More...
bool	isMainsAvailable ()
	Check if the cable between power supply and expander input is connected. More...

Detailed Description

Battery related functions.

Author

Makers For Life

Copyright

Copyright (c) 2020 Makers For Life

Definition in file battery.h.

Macro Definition Documentation

BATTERY_MAX_SAMPLES

#define BATTERY_MAX_SAMPLES   20u

Number of samples of the moving average.

Definition at line 68 of file battery.h.

RAW_BATTERY_MULTIPLIER

#define RAW_BATTERY_MULTIPLIER   0.0075196210

The divider between real battery voltage and STM32 input is 8.2K-1k resistors So, the multiplier is 1/(1+8.2)=0.1087 Considering 0.1% precision resistances, multiplier is between 0,108502 and 0,108889 The reference is 3.348V (measured on 53 HW V3 boards) RawValue = (Vbat*0.1087)*1024/3.348 So, Vbat = RawValue * (3.348/(1024*0.1087))

1 bit = 3.348/(4096*0.1087) = 7.5mV

Definition at line 22 of file battery.h.

RAW_VOLTAGE_HYSTERESIS

#define RAW_VOLTAGE_HYSTERESIS   12u

Hysteresis is used to prevent fast switching when voltage is at the limit of 2 states analogRead(PIN) * RAW_BATTERY_MULTIPLIER = 0,1 => 0,1 / RAW_BATTERY_MULTIPLIER = 3.

Definition at line 41 of file battery.h.

RAW_VOLTAGE_MAINS

#define RAW_VOLTAGE_MAINS   3643u

Expected voltage in volts when power cord is plugged 27,4 V => 27,4 / RAW_BATTERY_MULTIPLIER.

Definition at line 28 of file battery.h.

RAW_VOLTAGE_ON_BATTERY

#define RAW_VOLTAGE_ON_BATTERY   3085u

RCM_SW_11 = 23,2 => 23,2 / RAW_BATTERY_MULTIPLIER.

Definition at line 47 of file battery.h.

RAW_VOLTAGE_ON_BATTERY_HIGH

#define RAW_VOLTAGE_ON_BATTERY_HIGH   3590u

RCM_SW_16 Expected voltage in volts when power cord is unplugged = 27 => 27 / RAW_BATTERY_MULTIPLIER.

Definition at line 35 of file battery.h.

RAW_VOLTAGE_ON_BATTERY_LOW

#define RAW_VOLTAGE_ON_BATTERY_LOW   3005u

RCM_SW_12 = 22,6 => 22,6 / RAW_BATTERY_MULTIPLIER.

Definition at line 53 of file battery.h.

RAW_VOLTAGE_ON_BATTERY_NOT_STARTING_THRESHOLD

#define RAW_VOLTAGE_ON_BATTERY_NOT_STARTING_THRESHOLD   3191u

Below this value, the machine wont start = 22 => 22 / RAW_BATTERY_MULTIPLIER.

Definition at line 59 of file battery.h.

RAW_VOLTAGE_ON_BATTERY_STOP_THRESHOLD

#define RAW_VOLTAGE_ON_BATTERY_STOP_THRESHOLD   2660u

Below this value, the machine will stop immediately = 20 => 20 / RAW_BATTERY_MULTIPLIER.

Definition at line 65 of file battery.h.

Function Documentation

batteryLoop()

void batteryLoop

(

uint32_t

p_cycleNumber

)

Handle battery events.

Parameters

p_cycleNumber

Number of cycles since boot

Warning

It must be called in the program loop

Definition at line 117 of file battery.cpp.

                                         {
    updateBatterySample();
    updateBatteryState(p_cycleNumber);
}

getBatteryLevel()

uint32_t getBatteryLevel

(

)

Returns battery level.

Returns

Battery level in volts

Definition at line 123 of file battery.cpp.

{ return rawBatteryMeanVoltage * RAW_BATTERY_MULTIPLIER; }

getBatteryLevelX10()

uint32_t getBatteryLevelX10

(

)

Returns battery level x10 for better accuracy.

Returns

Battery level in volts x10

Definition at line 126 of file battery.cpp.

{ return rawBatteryMeanVoltage * (10.0 * RAW_BATTERY_MULTIPLIER); }

getBatteryLevelX100()

uint32_t getBatteryLevelX100

(

)

Returns battery level x100 for better accuracy.

Returns

Battery level in volts x100

Definition at line 129 of file battery.cpp.

{ return rawBatteryMeanVoltage * (100.0 * RAW_BATTERY_MULTIPLIER); }

initBattery()

void initBattery

(

)

Initialize battery abstraction.

Warning

It must be called once to be able to check battery level

Definition at line 33 of file battery.cpp.

                   {
    // hardware v3 expander is connected to AC ON relay. that remains an optionnal wiring.
    pinMode(PIN_IN_MAINS_CONNECTED, INPUT_PULLUP);
    pinMode(PIN_IN_CONNECTION_TO_SUPPLY_OK, INPUT_PULLUP);
    analogReadResolution(ADC_RESOLUTION_MAKAIR);
 
    for (uint8_t i = 0; i < BATTERY_MAX_SAMPLES; i++) {
        rawBatterySample[i] = 0;
    }
 
    // Running this in setup avoids triggering alarms at startup
    for (uint8_t i = 0; i < BATTERY_MAX_SAMPLES; i++) {
        updateBatterySample();
    }
}

isBatteryDeepDischarged()

bool isBatteryDeepDischarged

(

)

Check if battery is deeply discharged.

Definition at line 136 of file battery.cpp.

                               {
    return rawBatteryMeanVoltage < RAW_VOLTAGE_ON_BATTERY_STOP_THRESHOLD;
}

isBatteryVeryLow()

bool isBatteryVeryLow

(

)

Check if battery level is very low.

Definition at line 132 of file battery.cpp.

                        {
    return rawBatteryMeanVoltage < RAW_VOLTAGE_ON_BATTERY_NOT_STARTING_THRESHOLD;
}

isMainsAvailable()

bool isMainsAvailable

(

)

Check if the cable between power supply and expander input is connected.

Definition at line 144 of file battery.cpp.

{ return mainsConnectedAvailable; }

isMainsConnected()

bool isMainsConnected

(

)

Check if mains are connected.

Definition at line 141 of file battery.cpp.

{ return (!isRunningOnBattery); }

updateBatterySample()

void updateBatterySample

(

)

Handle battery voltage calculation.

Definition at line 49 of file battery.cpp.

                           {
    uint16_t rawVout = analogRead(PIN_BATTERY);
 
    // Assign sample from Vout
    rawBatterySample[batteryCurrentSample] = rawVout;
 
    // Increment sample
    batteryCurrentSample++;
 
    // If we reached max samples
    if (batteryCurrentSample >= BATTERY_MAX_SAMPLES) {
        batteryCurrentSample = 0;
    }
 
    batteryTotalSamples = 0;
    for (uint8_t i = 0; i < BATTERY_MAX_SAMPLES; i++) {
        batteryTotalSamples += rawBatterySample[i];
    }
    // Updates mean voltage
    rawBatteryMeanVoltage = (batteryTotalSamples / BATTERY_MAX_SAMPLES);
}

updateBatteryState()

void updateBatteryState

(

uint32_t

p_cycleNumber

)

Updates battery states.

Parameters

p_cycleNumber

Number of cycle since start

Definition at line 71 of file battery.cpp.

                                                {
    // The connector includes a small wire between gnd and PIN_IN_CONNECTION_TO_SUPPLY_OK.
    // If this is not detected, there may be a end of line connection problem,
    // and there is a fallback to Vbat value
    mainsConnectedAvailable = (LOW == digitalRead(PIN_IN_CONNECTION_TO_SUPPLY_OK));
    mainsConnected = (LOW == digitalRead(PIN_IN_MAINS_CONNECTED));
 
    if ((mainsConnectedAvailable && !mainsConnected)
        || (!mainsConnectedAvailable
            && (rawBatteryMeanVoltage < (RAW_VOLTAGE_ON_BATTERY_HIGH - RAW_VOLTAGE_HYSTERESIS)))) {
        alarmController.detectedAlarm(RCM_SW_16, p_cycleNumber,
                                      (RAW_VOLTAGE_ON_BATTERY_HIGH - RAW_VOLTAGE_HYSTERESIS),
                                      rawBatteryMeanVoltage);
        isRunningOnBattery = true;
    } else if ((mainsConnectedAvailable && mainsConnected)
               || (!mainsConnectedAvailable
                   && (rawBatteryMeanVoltage > RAW_VOLTAGE_ON_BATTERY_HIGH))) {
        alarmController.notDetectedAlarm(RCM_SW_16);
        isRunningOnBattery = false;
    } else {
        // This is an hysteresis, so do nothing here
    }
 
    if (!mainsConnected
        && (rawBatteryMeanVoltage < (RAW_VOLTAGE_ON_BATTERY - RAW_VOLTAGE_HYSTERESIS))) {
        alarmController.detectedAlarm(RCM_SW_11, p_cycleNumber,
                                      (RAW_VOLTAGE_ON_BATTERY - RAW_VOLTAGE_HYSTERESIS),
                                      rawBatteryMeanVoltage);
    } else if (mainsConnected || (rawBatteryMeanVoltage > RAW_VOLTAGE_ON_BATTERY)) {
        alarmController.notDetectedAlarm(RCM_SW_11);
    } else {
        // This is an hysteresis, so do nothing here
    }
 
    if (!mainsConnected
        && (rawBatteryMeanVoltage < (RAW_VOLTAGE_ON_BATTERY_LOW - RAW_VOLTAGE_HYSTERESIS))) {
        alarmController.detectedAlarm(RCM_SW_12, p_cycleNumber,
                                      (RAW_VOLTAGE_ON_BATTERY_LOW - RAW_VOLTAGE_HYSTERESIS),
                                      rawBatteryMeanVoltage);
    } else if (mainsConnected || (rawBatteryMeanVoltage > RAW_VOLTAGE_ON_BATTERY_LOW)) {
        alarmController.notDetectedAlarm(RCM_SW_12);
    } else {
        // This is an hysteresis, so do nothing here
    }
}