Battery Monitor driver.
The Battery Monitor driver provides services related to measuring and reacting to the current supply voltage of the device, and changes to it.
The two main services provided are:
Unlike most drivers, there is only a single instance of the Battery Monitor driver that is always available once BatteryMonitor_init() is called. BatteryMonitor_init() should be called once before using other Battery Monitor driver APIs. Subsequent BatteryMonitor_init() calls will have no effect.
The driver can read the current supply voltage and return it. The resolution is device-specific (see device-specific Battery Monitor documentation), but the voltage will always be encoded as an unsigned integer in millivolts (mV).
The Battery Monitor driver can notify the application when the supply voltage crosses an application-defined threshold.
There are three default use cases for this:
There are three functions that register a notification for the application:
Multiple notifications may be registered. The different parts of the application and drivers that need to respond to a supply voltage change do not need to know of one another. Each notification must have its own BatteryMonitor_NotifyObj and must be registered individually.
Once the supply voltage crosses the smallest "high threshold" or largest "low threshold amongst the registered notifications, the driver will iterate over the entire list of registered notification and check which ones have triggered. Notifications that have triggered are removed from the list of registered notifications before their callback function is invoked.
If an application wishes to re-register a notification that just triggered and was unregistered, it may register it again from within the notification callback or another context.
It is possible to determine whether the high or low threshold triggered the notification callback as follows:
Registered notifications are unregistered in two ways:
Unregistered notifications may be registered again at any time.
Go to the source code of this file.
Data Structures | |
struct | BatteryMonitor_NotifyObj |
Battery Monitor notify object structure. More... | |
Macros | |
#define | BatteryMonitor_STATUS_RESERVED (-32) |
#define | BatteryMonitor_STATUS_SUCCESS (0) |
Successful status code. More... | |
#define | BatteryMonitor_STATUS_ERROR (-1) |
Generic error status code. More... | |
Typedefs | |
typedef void(* | BatteryMonitor_NotifyFxn) (uint16_t currentVoltage, uint16_t thresholdVoltage, uintptr_t clientArg, BatteryMonitor_NotifyObj *notifyObject) |
Function prototype for a notification callback. More... | |
Functions | |
void | BatteryMonitor_init (void) |
This function initializes the Battery Monitor driver. More... | |
uint16_t | BatteryMonitor_getVoltage (void) |
Gets the current supply voltage in millivolts. More... | |
int_fast16_t | BatteryMonitor_registerNotifyHigh (BatteryMonitor_NotifyObj *notifyObject, uint16_t thresholdHigh, BatteryMonitor_NotifyFxn notifyFxn, uintptr_t clientArg) |
Registers a notification with a high threshold. More... | |
int_fast16_t | BatteryMonitor_registerNotifyLow (BatteryMonitor_NotifyObj *notifyObject, uint16_t thresholdLow, BatteryMonitor_NotifyFxn notifyFxn, uintptr_t clientArg) |
Registers a notification with a low threshold. More... | |
int_fast16_t | BatteryMonitor_registerNotifyRange (BatteryMonitor_NotifyObj *notifyObject, uint16_t thresholdHigh, uint16_t thresholdLow, BatteryMonitor_NotifyFxn notifyFxn, uintptr_t clientArg) |
Registers a notification with both a high and low threshold. More... | |
int_fast16_t | BatteryMonitor_unregisterNotify (BatteryMonitor_NotifyObj *notifyObject) |
Unregisters a currently registered notification. More... | |
static uint16_t | BatteryMonitor_getThresholdHigh (BatteryMonitor_NotifyObj *notifyObject) |
Get the high threshold of a notification. More... | |
static uint16_t | BatteryMonitor_getThresholdLow (BatteryMonitor_NotifyObj *notifyObject) |
Get the low threshold of a notification. More... | |
static void | BatteryMonitor_getThresholdRange (BatteryMonitor_NotifyObj *notifyObject, uint16_t *thresholdHigh, uint16_t *thresholdLow) |
Get the high and low threshold of a notification. More... | |
static uintptr_t | BatteryMonitor_getClientArg (BatteryMonitor_NotifyObj *notifyObject) |
Get the application-provided clientArg of a notification. More... | |
static BatteryMonitor_NotifyFxn | BatteryMonitor_getNotifyFxn (BatteryMonitor_NotifyObj *notifyObject) |
Get the notifyFxn provided during registration. More... | |
#define BatteryMonitor_STATUS_RESERVED (-32) |
Common Battery Monitor status code reservation offset. Battery Monitor driver implementations should offset status codes with BatteryMonitor_STATUS_RESERVED growing negatively.
Example implementation specific status codes:
#define BatteryMonitor_STATUS_SUCCESS (0) |
Successful status code.
Functions return BatteryMonitor_STATUS_SUCCESS if the function was executed successfully.
#define BatteryMonitor_STATUS_ERROR (-1) |
Generic error status code.
Functions return BatteryMonitor_STATUS_ERROR if the function was not executed successfully.
typedef void(* BatteryMonitor_NotifyFxn) (uint16_t currentVoltage, uint16_t thresholdVoltage, uintptr_t clientArg, BatteryMonitor_NotifyObj *notifyObject) |
Function prototype for a notification callback.
[in] | currentVoltage | Current supply voltage in millivolts |
[in] | thresholdVoltage | Voltage threshold in millivolts that caused this notification callback. |
[in] | clientArg | Argument provided by the application during registration. |
[in/out] | notifyObject Pointer to notification object that was registered previously. This may be used to register the notification again with updated inputs from within the notification callback. |
void BatteryMonitor_init | ( | void | ) |
This function initializes the Battery Monitor driver.
This function initializes the internal state of the Battery Monitor driver. It must be called before calling any other Battery Monitor functions. Subsequent calls to this function have no effect.
uint16_t BatteryMonitor_getVoltage | ( | void | ) |
Gets the current supply voltage in millivolts.
int_fast16_t BatteryMonitor_registerNotifyHigh | ( | BatteryMonitor_NotifyObj * | notifyObject, |
uint16_t | thresholdHigh, | ||
BatteryMonitor_NotifyFxn | notifyFxn, | ||
uintptr_t | clientArg | ||
) |
Registers a notification with a high threshold.
This function registers a Battery Monitor notification with a high threshold. Once the supply voltage rises above thresholdHigh
, the notification is automatically unregistered and function notifyFxn
is called.
notifyObject | Structure to be initialized. After returning, it will contain the data necessary to issue a notification callback. The memory of the structure must persist while the notification is registered. | |
[in] | thresholdHigh | Threshold supply voltage in millivolts |
[in] | notifyFxn | Callback function that is called once the supply voltage rises above thresholdHigh . |
[in] | clientArg | Application-specified argument |
BatteryMonitor_STATUS_SUCCESS | The notification was successfully registered. |
BatteryMonitor_STATUS_ERROR | There was an error during registration. |
int_fast16_t BatteryMonitor_registerNotifyLow | ( | BatteryMonitor_NotifyObj * | notifyObject, |
uint16_t | thresholdLow, | ||
BatteryMonitor_NotifyFxn | notifyFxn, | ||
uintptr_t | clientArg | ||
) |
Registers a notification with a low threshold.
This function registers a Battery Monitor notification with a low threshold. Once the supply voltage falls below thresholdLow
, the notification is automatically unregistered and function notifyFxn
is called.
notifyObject | Structure to be initialized. After returning, it will contain the data necessary to issue a notification callback. The memory of the structure must persist while the notification is registered. | |
[in] | thresholdLow | Threshold supply voltage in millivolts |
[in] | notifyFxn | Callback function that is called once the supply voltage falls below thresholdLow . |
[in] | clientArg | Application-specified argument |
BatteryMonitor_STATUS_SUCCESS | The notification was successfully registered. |
BatteryMonitor_STATUS_ERROR | There was an error during registration. |
int_fast16_t BatteryMonitor_registerNotifyRange | ( | BatteryMonitor_NotifyObj * | notifyObject, |
uint16_t | thresholdHigh, | ||
uint16_t | thresholdLow, | ||
BatteryMonitor_NotifyFxn | notifyFxn, | ||
uintptr_t | clientArg | ||
) |
Registers a notification with both a high and low threshold.
This function registers a Battery Monitor notification with a high and low threshold. Once the supply voltage rises above thresholdHigh
or falls below thresholdLow
, the notification is automatically unregistered and function notifyFxn
is called.
notifyObject | Structure to be initialized. After returning, it will contain the data necessary to issue a notification callback. The memory of the structure must persist while the notification is registered. | |
[in] | thresholdHigh | High threshold supply voltage in millivolts |
[in] | thresholdLow | Low threshold supply voltage in millivolts |
[in] | notifyFxn | Callback function that is called once the supply voltage falls below thresholdLow , or rises above thresholdHigh . |
[in] | clientArg | Application-specified argument |
BatteryMonitor_STATUS_SUCCESS | The notification was successfully registered |
BatteryMonitor_STATUS_ERROR | There was an error during registration |
int_fast16_t BatteryMonitor_unregisterNotify | ( | BatteryMonitor_NotifyObj * | notifyObject | ) |
Unregisters a currently registered notification.
This function unregisters a currently registered notification.
notifyObject | Notification to unregister. |
BatteryMonitor_STATUS_SUCCESS | The notification was successfully unregistered. |
BatteryMonitor_STATUS_ERROR | There was an error during unregistration. |
notifyObject
with BatteryMonitor_registerNotifyHigh(), BatteryMonitor_registerNotifyLow(), or BatteryMonitor_registerNotifyRange()
|
inlinestatic |
Get the high threshold of a notification.
notifyObject
registered with BatteryMonitor_registerNotifyLow(). The high threshold value returned in that case will be a device-specific invalid voltage.notifyObject | Notification to get the high threshold of. |
notifyObject
with BatteryMonitor_registerNotifyHigh(), or BatteryMonitor_registerNotifyRange() References BatteryMonitor_NotifyObj::thresholdHigh.
|
inlinestatic |
Get the low threshold of a notification.
notifyObject
registered with BatteryMonitor_registerNotifyHigh(). The low threshold value returned in that case will be a device-specific invalid voltage.notifyObject | Notification to get the low threshold of. |
notifyObject
with BatteryMonitor_registerNotifyLow(), or BatteryMonitor_registerNotifyRange() References BatteryMonitor_NotifyObj::thresholdLow.
|
inlinestatic |
Get the high and low threshold of a notification.
notifyObject
registered with BatteryMonitor_registerNotifyLow() or BatteryMonitor_registerNotifyHigh(). The unconfigured threshold value returned in that case will be a device-specific invalid voltage.notifyObject | Notification to get the high and low threshold of. | |
[out] | thresholdHigh | High threshold value in millivolts written back by this function. |
[out] | thresholdLow | Low threshold value in millivolts written back by this function. |
notifyObject
with BatteryMonitor_registerNotifyRange() References BatteryMonitor_NotifyObj::thresholdHigh, and BatteryMonitor_NotifyObj::thresholdLow.
|
inlinestatic |
Get the application-provided clientArg of a notification.
notifyObject | Notification to get the clientArg of. |
notifyObject
with BatteryMonitor_registerNotifyHigh(), BatteryMonitor_registerNotifyLow(), or BatteryMonitor_registerNotifyRange() References BatteryMonitor_NotifyObj::clientArg.
|
inlinestatic |
Get the notifyFxn provided during registration.
notifyObject | Notification to get the notifyFxn of. |
notifyObject
with BatteryMonitor_registerNotifyHigh(), BatteryMonitor_registerNotifyLow(), or BatteryMonitor_registerNotifyRange() References BatteryMonitor_NotifyObj::notifyFxn.