Detailed Description

Battery Monitor driver.

Overview

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:

Getting the current supply voltage
Providing notification callbacks when the supply voltage changes

Usage

Initialisation

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.

Getting the Current Supply Voltage

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).

Notifications

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:

High threshold. The application will receive a notification callback when currentVoltage >= thresholdHigh.
Low threshold. The application will receive a notification callback when currentVoltage <= thresholdLow.
Range threshold. The application will receive a notification callback when currentVoltage >= thresholdHigh || currentVoltage <= thresholdLow. This setup addresses use cases where a notification is required when the supply voltage changes by a certain amount regardless of whether it is up or down.

Registering Notifications

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.

Notification Callbacks

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:

currentVoltage <= thresholdVoltage: Low threshold triggered
currentVoltage >= thresholdVoltage: High threshold triggered This information is only reasonably useful when registering a notification with both a high and low threshold using BatteryMonitor_registerNotifyRange(). Even then, the expected basic use case only cares about the current voltage and adding an offset to it when registering the notification again.

Unregistering Notifications

Registered notifications are unregistered in two ways:

Automatically when a notification triggers
By calling BatteryMonitor_unregisterNotify()

Unregistered notifications may be registered again at any time.

Synopsis

#include <ti/drivers/BatteryMonitor.h>
#define WINDOW_DELTA_MILLIVOLT 300
BatteryMonitor_init();
currentVoltage = BatteryMonitor_getVoltage();
result = BatteryMonitor_registerNotifyRange(&notifyObject,
                                            currentVoltage + WINDOW_DELTA_MILLIVOLT,
                                            currentVoltage - WINDOW_DELTA_MILLIVOLT,
                                            myNotifyFxn,
                                            clientArg);

Examples

Register a High Threshold Notification

// The notification will trigger when the supply voltage reaches 3.5V
#define THRESHOLD_CUTOFF_MILLIVOLT 3500
#include <ti/drivers/BatteryMonitor.h>
void thresholdNotifyFxn(uint16_t currentVoltage,
                        uint16_t thresholdVoltage,
                        uintptr_t clientArg,
                        BatteryMonitor_NotifyObj *notifyObject) {
   // Post a semaphore, set a flag, or otherwise act upon the voltage change.
}
...
// Initialize the Battery Monitor driver and register a notification.
BatteryMonitor_init();
int_fast16_t status = BatteryMonitor_registerNotifyHigh(notifyObject,
                                                        THRESHOLD_CUTOFF_MILLIVOLT,
                                                        thresholdNotifyFxn,
                                                        NULL);
if (status != BatteryMonitor_STATUS_SUCCESS) {
    // Handle error
}

Register a Range Threshold Notification and re-register in Callback

#define THRESHOLD_DELTA_MILLIVOLT 300
#include <ti/drivers/BatteryMonitor.h>
void deltaNotificationFxn(uint16_t currentVoltage,
                          uint16_t thresholdVoltage,
                          uintptr_t clientArg,
                          BatteryMonitor_NotifyObj *notifyObject) {
    int_fast16_t status;
    status = BatteryMonitor_registerNotifyRange(notifyObject,
                                        currentVoltage + THRESHOLD_DELTA_MILLIVOLT,
                                        currentVoltage - THRESHOLD_DELTA_MILLIVOLT,
                                        deltaNotificationFxn,
                                        clientArg);
    if (status != BatteryMonitor_STATUS_SUCCESS) {
        while(1);
    }
}
 ...
// Initialize the Battery Monitor driver and register a notification.
BatteryMonitor_init();
BatteryMonitor_NotifyObj rangeNotifyObject;
uint16_t currentVoltage = BatteryMonitor_getVoltage();
int_fast16_t status = BatteryMonitor_registerNotifyRange(6rangeNotifyObject,
                                                      currentVoltage + THRESHOLD_DELTA_MILLIVOLT,
                                                      currentVoltage - THRESHOLD_DELTA_MILLIVOLT,
                                                      deltaNotificationFxn,
                                                      (uintptr_t)NULL);

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <ti/drivers/utils/List.h>

Include dependency graph for BatteryMonitor.h:

This graph shows which files directly or indirectly include this file:

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...

Macro Definition Documentation

§ BatteryMonitor_STATUS_RESERVED

#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 BatteryMonitorXYZ_STATUS_ERROR0    BatteryMonitor_STATUS_RESERVED - 0
#define BatteryMonitorXYZ_STATUS_ERROR1    BatteryMonitor_STATUS_RESERVED - 1
#define BatteryMonitorXYZ_STATUS_ERROR2    BatteryMonitor_STATUS_RESERVED - 2

§ BatteryMonitor_STATUS_SUCCESS

#define BatteryMonitor_STATUS_SUCCESS (0)

Successful status code.

Functions return BatteryMonitor_STATUS_SUCCESS if the function was executed successfully.

§ BatteryMonitor_STATUS_ERROR

#define BatteryMonitor_STATUS_ERROR (-1)

Generic error status code.

Functions return BatteryMonitor_STATUS_ERROR if the function was not executed successfully.

Typedef Documentation

§ BatteryMonitor_NotifyFxn

typedef void(* BatteryMonitor_NotifyFxn) (uint16_t currentVoltage, uint16_t thresholdVoltage, uintptr_t clientArg, BatteryMonitor_NotifyObj *notifyObject)

Function prototype for a notification callback.

Parameters

[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.

Function Documentation

§ BatteryMonitor_init()

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.

§ BatteryMonitor_getVoltage()

uint16_t BatteryMonitor_getVoltage ( void )

Gets the current supply voltage in millivolts.

Returns: Current supply voltage in millivolts

§ BatteryMonitor_registerNotifyHigh()

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.

Parameters

	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

Return values

BatteryMonitor_STATUS_SUCCESS	The notification was successfully registered.
BatteryMonitor_STATUS_ERROR	There was an error during registration.

Precondition: BatteryMonitor_init() called

§ BatteryMonitor_registerNotifyLow()

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.

Parameters

	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

Return values

BatteryMonitor_STATUS_SUCCESS	The notification was successfully registered.
BatteryMonitor_STATUS_ERROR	There was an error during registration.

Precondition: BatteryMonitor_init() called

§ BatteryMonitor_registerNotifyRange()

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.

Parameters

	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

Return values

BatteryMonitor_STATUS_SUCCESS	The notification was successfully registered
BatteryMonitor_STATUS_ERROR	There was an error during registration

Precondition: BatteryMonitor_init() called

§ BatteryMonitor_unregisterNotify()

int_fast16_t BatteryMonitor_unregisterNotify ( BatteryMonitor_NotifyObj * notifyObject )

Unregisters a currently registered notification.

This function unregisters a currently registered notification.

Parameters

notifyObject Notification to unregister.

Return values

BatteryMonitor_STATUS_SUCCESS	The notification was successfully unregistered.
BatteryMonitor_STATUS_ERROR	There was an error during unregistration.

Precondition: Register notifyObject with BatteryMonitor_registerNotifyHigh(), BatteryMonitor_registerNotifyLow(), or BatteryMonitor_registerNotifyRange()

§ BatteryMonitor_getThresholdHigh()

static uint16_t BatteryMonitor_getThresholdHigh ( BatteryMonitor_NotifyObj * notifyObject )

inlinestatic

Get the high threshold of a notification.

Warning: This function should not be called on a notifyObject registered with BatteryMonitor_registerNotifyLow(). The high threshold value returned in that case will be a device-specific invalid voltage.

Parameters

notifyObject Notification to get the high threshold of.

Returns: High threshold in millivolts.

Precondition: Register notifyObject with BatteryMonitor_registerNotifyHigh(), or BatteryMonitor_registerNotifyRange()

References BatteryMonitor_NotifyObj::thresholdHigh.

§ BatteryMonitor_getThresholdLow()

static uint16_t BatteryMonitor_getThresholdLow ( BatteryMonitor_NotifyObj * notifyObject )

inlinestatic

Get the low threshold of a notification.

Warning: This function should not be called on a notifyObject registered with BatteryMonitor_registerNotifyHigh(). The low threshold value returned in that case will be a device-specific invalid voltage.

Parameters

notifyObject Notification to get the low threshold of.

Returns: Low threshold in millivolts.

Precondition: Register notifyObject with BatteryMonitor_registerNotifyLow(), or BatteryMonitor_registerNotifyRange()

References BatteryMonitor_NotifyObj::thresholdLow.

§ BatteryMonitor_getThresholdRange()

static void BatteryMonitor_getThresholdRange	(	BatteryMonitor_NotifyObj *	notifyObject,
		uint16_t *	thresholdHigh,
		uint16_t *	thresholdLow
	)

inlinestatic

Get the high and low threshold of a notification.

Warning: This function should not be called on a notifyObject registered with BatteryMonitor_registerNotifyLow() or BatteryMonitor_registerNotifyHigh(). The unconfigured threshold value returned in that case will be a device-specific invalid voltage.

Parameters

	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.

Precondition: Register notifyObject with BatteryMonitor_registerNotifyRange()

References BatteryMonitor_NotifyObj::thresholdHigh, and BatteryMonitor_NotifyObj::thresholdLow.

§ BatteryMonitor_getClientArg()

static uintptr_t BatteryMonitor_getClientArg ( BatteryMonitor_NotifyObj * notifyObject )

inlinestatic

Get the application-provided clientArg of a notification.

Parameters

notifyObject Notification to get the clientArg of.

Returns: The clientArg provided during registration.

Precondition: Register notifyObject with BatteryMonitor_registerNotifyHigh(), BatteryMonitor_registerNotifyLow(), or BatteryMonitor_registerNotifyRange()

References BatteryMonitor_NotifyObj::clientArg.

§ BatteryMonitor_getNotifyFxn()

static BatteryMonitor_NotifyFxn BatteryMonitor_getNotifyFxn ( BatteryMonitor_NotifyObj * notifyObject )

inlinestatic

Get the notifyFxn provided during registration.

Parameters

notifyObject Notification to get the notifyFxn of.

Returns: The notifyFxn provided during registration

Precondition: Register notifyObject with BatteryMonitor_registerNotifyHigh(), BatteryMonitor_registerNotifyLow(), or BatteryMonitor_registerNotifyRange()

References BatteryMonitor_NotifyObj::notifyFxn.

Detailed Description

Overview

Usage

Initialisation

Getting the Current Supply Voltage

Notifications

Registering Notifications

Notification Callbacks

Unregistering Notifications

Synopsis

Examples

Register a High Threshold Notification

Register a Range Threshold Notification and re-register in Callback

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

§ BatteryMonitor_STATUS_RESERVED

§ BatteryMonitor_STATUS_SUCCESS

§ BatteryMonitor_STATUS_ERROR

Typedef Documentation

§ BatteryMonitor_NotifyFxn

Function Documentation

§ BatteryMonitor_init()

§ BatteryMonitor_getVoltage()

§ BatteryMonitor_registerNotifyHigh()

§ BatteryMonitor_registerNotifyLow()

§ BatteryMonitor_registerNotifyRange()

§ BatteryMonitor_unregisterNotify()

§ BatteryMonitor_getThresholdHigh()

§ BatteryMonitor_getThresholdLow()

§ BatteryMonitor_getThresholdRange()

§ BatteryMonitor_getClientArg()

§ BatteryMonitor_getNotifyFxn()