| Members | Descriptions |
|---|---|
class Battery |
This class provides a detailed insight into the battery's health and usage. |
class Board |
Represents a board with power management capabilities. |
class Charger |
Class for controlling charging parameters and monitoring charging status. |
class MAX1726Driver |
Driver class for the MAX1726 Fuel Gauge IC. |
struct BatteryCharacteristics |
This struct contains the characteristics of the battery. |
This class provides a detailed insight into the battery's health and usage.
| Members | Descriptions |
|---|---|
Battery |
Initializes the battery object with default values for capacity (0mAh) and empty voltage (3.3V). |
Battery |
Initializes the battery object with the given battery characteristics. |
begin |
Initializes the battery communication and configuration. |
isConnected |
Checks if a battery is connected to the system. |
voltage |
Reads the current voltage of the battery. Voltage is usually between 3.0V and 4.2V. |
averageVoltage |
Reads an average of voltage readings of the battery. |
minimumVoltage |
Returns the minimum voltage value measured since the last device reset. At power-up the minimum voltage value is set to FFh (the maximum). |
maximumVoltage |
Returns the maximum voltage value measured since the last device reset. At power-up the maximum voltage value is set to 00h (the minimum). |
resetMaximumMinimumVoltage |
Resets the minimum and maximum voltage values. |
current |
Reads the current flowing from the battery at the moment. Negative values indicate that the battery is charging, positive values indicate that the battery is discharging. When no battery is connected, the value is -1. |
averageCurrent |
Reads an average of current readings of the battery. |
minimumCurrent |
Reads the minimum current values measured since the last device reset. Note: The resolution of the minimum current value is 160mA so the value is rounded to the nearest 160mA. |
maximumCurrent |
Reads the maximum current values measured since the last device reset. Note: The resolution of the minimum current value is 160mA so the value is rounded to the nearest 160mA. |
resetMaximumMinimumCurrent |
Resets the minimum and maximum current values. |
power |
Reads the current power of the battery in milliwatts (mW). This value is calculated based on the current and voltage of the battery. |
averagePower |
Reads an average of power readings of the battery in milliwatts (mW). This value is calculated based on the current and voltage of the battery. |
internalTemperature |
Reads the current temperature of the internal die of the battery gauge chip. |
averageInternalTemperature |
Reads an average of internal temperature readings of the battery. Note: If the battery temperature was read before, this function will change the configuration to read the internal temperature. You will have to await a couple of temperature readings before getting a meaningful average temperature. |
percentage |
Reads the battery's state of charge (SOC). This value is based on both the voltage and the current of the battery as well as compensation for the battery's age and temperature and discharge rate. |
remainingCapacity |
Reads the remaining capacity of the battery. In combination with current(), this value can be used to estimate the remaining time until the battery is empty. |
fullCapacity |
Returns the full capacity of the battery. For this to work, the capacity of the battery must be set when initializing the battery object. |
isEmpty |
Checks if the battery is empty. Returns false once the cell voltage rises above the recovery threshold. |
timeToEmpty |
Calculates the estimated time until the battery is empty. |
timeToFull |
Calculates the estimated time until the battery is fully charged. The value is determined by learning from the experience of prior charge cycles. |
Battery()Initializes the battery object with default values for capacity (0mAh) and empty voltage (3.3V).
Battery( BatteryCharacteristics batteryCharacteristics)Initializes the battery object with the given battery characteristics.
batteryCharacteristicsThe characteristics of the battery.
bool begin(bool enforceReload)Initializes the battery communication and configuration.
enforceReloadIf set to true, the battery gauge config will be reloaded.
True if the initialization was successful, false otherwise.
boolean isConnected()Checks if a battery is connected to the system.
True if a battery is connected, false otherwise
float voltage()Reads the current voltage of the battery. Voltage is usually between 3.0V and 4.2V.
The current voltage in volts (V).
float averageVoltage()Reads an average of voltage readings of the battery.
The average voltage in volts (V).
float minimumVoltage()Returns the minimum voltage value measured since the last device reset. At power-up the minimum voltage value is set to FFh (the maximum).
The minimum voltage value in volts (V).
float maximumVoltage()Returns the maximum voltage value measured since the last device reset. At power-up the maximum voltage value is set to 00h (the minimum).
The maximum voltage value in volts (V).
bool resetMaximumMinimumVoltage()Resets the minimum and maximum voltage values.
True if the minimum and maximum voltage values were successfully reset, false otherwise.
int16_t current()Reads the current flowing from the battery at the moment. Negative values indicate that the battery is charging, positive values indicate that the battery is discharging. When no battery is connected, the value is -1.
The current flowing from the battery in milli amperes (mA).
int16_t averageCurrent()Reads an average of current readings of the battery.
The average current in milli amperes (mA).
int16_t minimumCurrent()Reads the minimum current values measured since the last device reset. Note: The resolution of the minimum current value is 160mA so the value is rounded to the nearest 160mA.
The minimum current values in milli amperes (mA).
int16_t maximumCurrent()Reads the maximum current values measured since the last device reset. Note: The resolution of the minimum current value is 160mA so the value is rounded to the nearest 160mA.
The maximum current values in milli amperes (mA).
bool resetMaximumMinimumCurrent()Resets the minimum and maximum current values.
True if the minimum and maximum current values were successfully reset, false otherwise.
int16_t power()Reads the current power of the battery in milliwatts (mW). This value is calculated based on the current and voltage of the battery.
The current power in milliwatts (mW).
int16_t averagePower()Reads an average of power readings of the battery in milliwatts (mW). This value is calculated based on the current and voltage of the battery.
The average power in milliwatts (mW).
uint8_t internalTemperature()Reads the current temperature of the internal die of the battery gauge chip.
The current temperature in degrees Celsius.
uint8_t averageInternalTemperature()Reads an average of internal temperature readings of the battery. Note: If the battery temperature was read before, this function will change the configuration to read the internal temperature. You will have to await a couple of temperature readings before getting a meaningful average temperature.
The average temperature in degrees Celsius.
uint8_t percentage()Reads the battery's state of charge (SOC). This value is based on both the voltage and the current of the battery as well as compensation for the battery's age and temperature and discharge rate.
The state of charge as a percentage (Range: 0% - 100%).
uint16_t remainingCapacity()Reads the remaining capacity of the battery. In combination with current(), this value can be used to estimate the remaining time until the battery is empty.
The remaining capacity in milliampere-hours (mAh).
uint16_t fullCapacity()Returns the full capacity of the battery. For this to work, the capacity of the battery must be set when initializing the battery object.
The full capacity of the battery.
bool isEmpty()Checks if the battery is empty. Returns false once the cell voltage rises above the recovery threshold.
true if the battery is empty, false otherwise.
int32_t timeToEmpty()Calculates the estimated time until the battery is empty.
The estimated time until the battery is empty, in seconds. If the battery is charging, the function returns -1.
int32_t timeToFull()Calculates the estimated time until the battery is fully charged. The value is determined by learning from the experience of prior charge cycles.
The estimated time until the battery is fully charged in seconds. If the battery is discharging, the function returns -1.
Represents a board with power management capabilities.
The Board class provides methods to check the power source, enable/disable power rails, set voltage levels, enable/disable wakeup from pins or RTC, put the device into sleep mode for a specified duration, and control peripherals' power.
Supported boards: Arduino Portenta H7, Arduino Portenta C33, Arduino Nicla Vision.
| Members | Descriptions |
|---|---|
Board |
Construct a new Board object. |
~Board |
Destroy the Board object. |
begin |
Initializes the board by initiating the PMIC. |
isUSBPowered |
Check if the board is powered through USB. |
isBatteryPowered |
Check if the board is powered by the battery. |
setExternalPowerEnabled |
Enables/disables the voltage on the external power rail. This lane powers the pin labeled 3V3 on the board. |
setExternalVoltage |
Set the voltage for the external power rail. This lane powers the pin labeled 3V3 on the board. |
setCameraPowerEnabled |
Enables/disables the camera's power rail on boards with a built-in camera. |
enableWakeupFromPin |
Enables wakeup from pin GPIO0 on Portenta H7. The pin is only accessible via high-density connectors. |
enableSleepWhenIdle |
Enables sleep mode when the board is idle. |
enableWakeupFromPin |
Enables wake-up of the device from a specified pin (A0, A1, A2, A3, A4, A5, D4, D7 ) on Arduino Portenta C33. |
enableWakeupFromRTC |
Enables wake-up of the device from the RTC. This function allows to use a custom RTC instance to put the device in sleep mode. |
enableWakeupFromRTC |
Enables wake-up of the device from the RTC. |
enableWakeupFromRTC |
Enables wake-up of the device from the RTC. |
sleepUntilWakeupEvent |
Put the device into sleep mode until a wakeup event occurs This sleep mode is ideal for applications requiring periodic wake-ups or brief intervals of inactivity and reduces consumption to a range between 6mA and 18mA depending on the state of the peripherals. This sleep mode resumes the operation from the last operation without resetting the board. A wakeup event can be an interrupt on a pin or the RTC, depending on what you set with enableWakeupFromPin() and enableWakeupFromRTC(). |
standByUntilWakeupEvent |
Put the device into standby mode until a wakeup event occurs. For scenarios demanding drastic power conservation, the standby Mode significantly reduces the board's power usage to micro amperes range depending on the state of the peripherals. This mode restarts the board on wake-up, effectively running the setup() function again. A wakeup event can be an interrupt on a pin or the RTC, depending on what you set with enableWakeupFromPin() and enableWakeupFromRTC(). |
setAllPeripheralsPower |
Toggle the peripherals' power on Portenta C33 (ADC, RGB LED, Secure Element, Wifi and Bluetooth). |
setCommunicationPeripheralsPower |
Toggles the communication peripherials' power on Portenta C33 (Wifi, Bluetooth and Secure Element) |
setAnalogDigitalConverterPower |
Toggles the power of the analog digital converter on Portenta C33. This is not available on the Portenta H7. |
setReferenceVoltage |
Set the reference voltage. This value is used by the ADC to convert analog values to digital values. This can be particularly useful to increase the accuracy of the ADC when working with low voltages. |
shutDownFuelGauge |
Shuts down the fuel gauge to reduce power consumption. The IC returns to active mode on any edge of any communication line. If the IC is power-cycled or the software RESET command is sent the IC returns to active mode of operation. |
Board()Construct a new Board object.
~Board()Destroy the Board object.
bool begin()Initializes the board by initiating the PMIC.
true if the board initialization is successful, false otherwise.
bool isUSBPowered()Check if the board is powered through USB.
True if powered through USB, false otherwise.
bool isBatteryPowered()Check if the board is powered by the battery.
True if powered by the battery, false otherwise.
void setExternalPowerEnabled(bool on)Enables/disables the voltage on the external power rail. This lane powers the pin labeled 3V3 on the board.
onTrue to enable this power rail, false to disable it.
bool setExternalVoltage(float voltage)Set the voltage for the external power rail. This lane powers the pin labeled 3V3 on the board.
voltagefloat value of the voltage value to set. Value has to be one of the following (1.10, 1.20, 1.35, 1.50, 1.80, 2.50, 3.00, 3.30)
True the voltage was set successfully, false otherwise.
void setCameraPowerEnabled(bool enabled)Enables/disables the camera's power rail on boards with a built-in camera.
enabledTrue to turn on the camera, false to turn it off.
void enableWakeupFromPin()Enables wakeup from pin GPIO0 on Portenta H7. The pin is only accessible via high-density connectors.
void enableSleepWhenIdle()Enables sleep mode when the board is idle.
void enableWakeupFromPin(uint8_t pin, PinStatus direction)Enables wake-up of the device from a specified pin (A0, A1, A2, A3, A4, A5, D4, D7 ) on Arduino Portenta C33.
-
pinThe pin number used for waking up the device. -
directionThe direction of the interrupt that will wake up the device. (RISING, FALLING)
bool enableWakeupFromRTC(uint32_t hours, uint32_t minutes, uint32_t seconds, void(*)() callbackFunction, RTClock * rtc)Enables wake-up of the device from the RTC. This function allows to use a custom RTC instance to put the device in sleep mode.
-
hoursThe number of hours to sleep. -
minutesThe number of minutes to sleep. -
secondsThe number of seconds to sleep. -
callbackFunctionThe function to call when the device wakes up. If no callback function is provided, the device will wake up without calling any function. -
rtcThe RTC instance to use for the sleep function. If no RTC instance is provided, the default RTC instance is used.
True if successful, false otherwise.
bool enableWakeupFromRTC(uint32_t hours, uint32_t minutes, uint32_t seconds, RTClock * rtc)Enables wake-up of the device from the RTC.
-
hoursThe number of hours to sleep. -
minutesThe number of minutes to sleep. -
secondsThe number of seconds to sleep. -
rtcThe RTC instance to use for the sleep function. Default is the shared RTC instance.
True if successful, false otherwise.
bool enableWakeupFromRTC(uint32_t hours, uint32_t minutes, uint32_t seconds)Enables wake-up of the device from the RTC.
-
hoursThe number of hours to sleep. -
minutesThe number of minutes to sleep. -
secondsThe number of seconds to sleep.
True if successful, false otherwise.
void sleepUntilWakeupEvent()Put the device into sleep mode until a wakeup event occurs This sleep mode is ideal for applications requiring periodic wake-ups or brief intervals of inactivity and reduces consumption to a range between 6mA and 18mA depending on the state of the peripherals. This sleep mode resumes the operation from the last operation without resetting the board. A wakeup event can be an interrupt on a pin or the RTC, depending on what you set with enableWakeupFromPin() and enableWakeupFromRTC().
void standByUntilWakeupEvent()Put the device into standby mode until a wakeup event occurs. For scenarios demanding drastic power conservation, the standby Mode significantly reduces the board's power usage to micro amperes range depending on the state of the peripherals. This mode restarts the board on wake-up, effectively running the setup() function again. A wakeup event can be an interrupt on a pin or the RTC, depending on what you set with enableWakeupFromPin() and enableWakeupFromRTC().
void setAllPeripheralsPower(bool on)Toggle the peripherals' power on Portenta C33 (ADC, RGB LED, Secure Element, Wifi and Bluetooth).
onTrue to turn on the power, false to turn it off.
void setCommunicationPeripheralsPower(bool on)Toggles the communication peripherials' power on Portenta C33 (Wifi, Bluetooth and Secure Element)
onTrue to turn on the power, false to turn it off.
void setAnalogDigitalConverterPower(bool on)Toggles the power of the analog digital converter on Portenta C33. This is not available on the Portenta H7.
onTrue to turn on the power, false to turn it off.
bool setReferenceVoltage(float voltage)Set the reference voltage. This value is used by the ADC to convert analog values to digital values. This can be particularly useful to increase the accuracy of the ADC when working with low voltages.
voltageReference voltage value in volts. It can be anything between 1.80V and 3.30V in steps of 0.10V. Any value outside this range or with different steps will not be accepted by the library.
True if the voltage was set successfully, false otherwise.
void shutDownFuelGauge()Shuts down the fuel gauge to reduce power consumption. The IC returns to active mode on any edge of any communication line. If the IC is power-cycled or the software RESET command is sent the IC returns to active mode of operation.
Class for controlling charging parameters and monitoring charging status.
| Members | Descriptions |
|---|---|
Charger |
Constructs a new Charger object. |
begin |
Initializes the charger by initiating the PMIC. |
setChargeCurrent |
Set the charging current. The default charging current is set to 100mA. |
getChargeCurrent |
Get the charge current in milli amperes (mA). |
setChargeVoltage |
Set the charging voltage in volts (V). The current charging voltage is set to 4.2V by default. |
getChargeVoltage |
Get the charge voltage in volts (V). |
setEndOfChargeCurrent |
Set the end-of-charge current. The charger IC determines when to terminate the charge cycle based on the current going into the battery dropping below the given threshold during the constant voltage phase. At this point, the battery is considered fully charged and charging is completed. If charge termination is disabled, the charge current will naturally decay to 0mA, but this is rarely done in practice. This is because the amount of charge going into the battery exponentially decreases during CV charging, and it would take a significantly longer time to recharge the battery with a very little increase in capacity. |
getEndOfChargeCurrent |
Get the end of charge current. |
setInputCurrentLimit |
The input current limit (ILIM) safeguards the device by preventing overcurrent, ensuring the charging current is within safe levels for the battery, and adapting to the maximum current the power source can provide, allowing you to charge and use the system at the same time. The default input current limit is set to 1.5A. |
getInputCurrentLimit |
Get the input current limit. It is a safeguard to prevent overcurrent when charging respectively to the maximum current the power source can provide. |
getState |
Get the current charging status. |
isEnabled |
Checks if the charger and thus charging is enabled. By default, the charger is enabled. |
setEnabled |
Sets the enabled state of the charger. When enabling it uses the default settings or the last saved parameters, depending on what was set previously. |
Charger()Constructs a new Charger object.
bool begin()Initializes the charger by initiating the PMIC.
true if the charger initialization is successful, false otherwise.
bool setChargeCurrent(uint16_t current)Set the charging current. The default charging current is set to 100mA.
currentCharging current in milli amperes (mA). Supported values: 100, 150, 200, 250, 300, 350, 400, 450, 500, 550, 600, 650, 700, 750, 800, 850, 900, 950, 1000
True if successful, false if an invalid value was provided or if the PMIC communication failed.
uint16_t getChargeCurrent()Get the charge current in milli amperes (mA).
The charge current in float.
bool setChargeVoltage(float voltage)Set the charging voltage in volts (V). The current charging voltage is set to 4.2V by default.
voltageCharging voltage in volts (V). Supported values: 3.50, 3.52, 3.54, 3.56, 3.58, 3.60, 3.62, 3.64, 3.66, 3.68, 3.70, 3.72, 3.74, 3.76, 3.78, 3.80, 3.82, 3.84, 3.86, 3.88, 3.90, 3.92, 3.94, 3.96, 3.98, 4.00, 4.02, 4.04, 4.06, 4.08, 4.10, 4.12, 4.14, 4.16, 4.18, 4.20, 4.22, 4.24, 4.26, 4.28, 4.30, 4.32, 4.34, 4.36, 4.38, 4.40, 4.42, 4.44
True if successful, false if an invalid value was provided or if the PMIC communication failed.
float getChargeVoltage()Get the charge voltage in volts (V).
The charge voltage as a float value.
bool setEndOfChargeCurrent(uint16_t current)Set the end-of-charge current. The charger IC determines when to terminate the charge cycle based on the current going into the battery dropping below the given threshold during the constant voltage phase. At this point, the battery is considered fully charged and charging is completed. If charge termination is disabled, the charge current will naturally decay to 0mA, but this is rarely done in practice. This is because the amount of charge going into the battery exponentially decreases during CV charging, and it would take a significantly longer time to recharge the battery with a very little increase in capacity.
currentEnd-of-charge current in milli amperes (mA). The default end-of-charge current is set to 50 mA. Supported values: 5, 10, 20, 30, 50
True if successful, false if an invalid value was provided or if the PMIC communication failed.
uint16_t getEndOfChargeCurrent()Get the end of charge current.
This function returns the current value at which the charging process is considered complete. Charging is terminated when the supplied current drops below the pre-programmed end of charge level.
The end of charge current.
bool setInputCurrentLimit(uint16_t current)The input current limit (ILIM) safeguards the device by preventing overcurrent, ensuring the charging current is within safe levels for the battery, and adapting to the maximum current the power source can provide, allowing you to charge and use the system at the same time. The default input current limit is set to 1.5A.
currentMaximum input current in milli amperes (mA). Supported values: 10, 15, 20, 25, 30, 35, 40, 45, 50, 100, 150, 200, 300, 400, 500, 600, 700, 800, 900, 1000, 1500
True if successful, false if an invalid value was provided or if the PMIC communication failed.
uint16_t getInputCurrentLimit()Get the input current limit. It is a safeguard to prevent overcurrent when charging respectively to the maximum current the power source can provide.
The input current limit in milli amperes (mA).
ChargingState getState()Get the current charging status.
Charging status enum value (ChargingState). The possible states are:
-
none: Provided by the registers, not used in this API.
-
preCharge: First stage of the charging process, prepares battery for the charging process.
-
fastChargeConstantCurrent: Second phase of the charging process where the battery is charging in constant current mode until it reaches the voltage where the it's considered fully charged. (4.2V)
-
fastChargeConstantVoltage: Third phase of the charging process where the battery is kept at the fully charged voltage and current is slowly decreased to the end of charge current.
-
endOfCharge: If the battery is still connected, the charger will ensure it's kept at 4.2V by topping up the voltage to avoid self discharge.
-
done: Battery is fully charged
-
timerFaultError: The timer that is monitoring the charge status has encountered an error.
-
thermistorSuspendError: Charging was suspended due to overheating
-
chargerDisabled: Charger is disabled
-
batteryOvervoltageError: Charging was suspended due to an overvoltage fault
-
chargerBypassed: The charger is bypassed completely and the USB voltage is powering the board
bool isEnabled()Checks if the charger and thus charging is enabled. By default, the charger is enabled.
true if the charger is enabled, false otherwise.
bool setEnabled(bool enabled)Sets the enabled state of the charger. When enabling it uses the default settings or the last saved parameters, depending on what was set previously.
enabledThe desired enabled state of the charger.
true if the enabled state was successfully set, false otherwise.
Driver class for the MAX1726 Fuel Gauge IC.
| Members | Descriptions |
|---|---|
chargingComplete |
Checks if the battery charging is complete. |
setOperationMode |
Sets the operation mode of the Fuel Gauge. |
MAX1726Driver |
Constructs a new MAX1726Driver object. |
~MAX1726Driver |
bool chargingComplete()Checks if the battery charging is complete.
Checks if the charging process is complete.
true if the charging process is complete, false otherwise.
true if the charging is complete, false otherwise.
bool setOperationMode(FuelGaugeOperationMode mode)Sets the operation mode of the Fuel Gauge.
modeThe operation mode to set. Possible values are: hibernate, shutdown, active.
True if the operation mode was set successfully, false otherwise.
MAX1726Driver(TwoWire * wire, uint8_t i2cAddress)Constructs a new MAX1726Driver object.
-
wirePointer to the TwoWire object for I2C communication. -
i2cAddressThe I2C address of the MAX1726 device. The default value is 0x36.
~MAX1726Driver()This struct contains the characteristics of the battery.
| Members | Descriptions |
|---|---|
capacity |
The battery's capacity in milliampere-hours (mAh). |
emptyVoltage |
The voltage in volts (V) at which the battery is considered empty. If you don't know this value you can use the minimumVoltage() function to find out while you let the battery completely discharge. |
chargeVoltage |
The voltage in volts (V) at which the battery is being charged. |
endOfChargeCurrent |
The current in milli amperes (mA) that is used to keep the battery charged at the end of the charging process. |
ntcResistor |
The NTC resistor value used in the battery pack (10K or 100K Ohm). |
recoveryVoltage |
Sets the voltage level for clearing empty detection. Once the cell voltage rises above this point, empty voltage detection is re-enabled. |
int capacityThe battery's capacity in milliampere-hours (mAh).
float emptyVoltageThe voltage in volts (V) at which the battery is considered empty. If you don't know this value you can use the minimumVoltage() function to find out while you let the battery completely discharge.
float chargeVoltageThe voltage in volts (V) at which the battery is being charged.
int endOfChargeCurrentThe current in milli amperes (mA) that is used to keep the battery charged at the end of the charging process.
NTCResistor ntcResistorThe NTC resistor value used in the battery pack (10K or 100K Ohm).
float recoveryVoltageSets the voltage level for clearing empty detection. Once the cell voltage rises above this point, empty voltage detection is re-enabled.