BatteryMonitor.h

Go to the documentation of this file.

/*
 * Copyright (c) 2022-2023, Texas Instruments Incorporated
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * *  Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
/*!****************************************************************************
 *  @file       BatteryMonitor.h
 *
 *  @brief      Battery Monitor driver
 *
 *  @anchor ti_drivers_BatteryMonitor_Overview
 *  # 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
 *
 *  @anchor ti_drivers_BatteryMonitor_Usage
 *  # 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:
 *      - #BatteryMonitor_registerNotifyHigh()
 *      - #BatteryMonitor_registerNotifyLow()
 *      - #BatteryMonitor_registerNotifyRange()
 *
 *  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.
 *
 *  @anchor ti_drivers_BatteryMonitor_Synopsis
 *  # Synopsis #
 *  @anchor ti_drivers_BatteryMonitor_Synopsis_Code
 *  @code
 *  #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);
 *  @endcode
 *
 *  @anchor ti_drivers_BatteryMonitor_Examples
 *  # Examples #
 *
 *  ## Register a High Threshold Notification #
 *
 *  @code
 *
 *  // 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
 *  }
 *
 *  @endcode
 *
 *  ## Register a Range Threshold Notification and re-register in Callback #
 *
 *  @code
 *
 *  #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);
 *  @endcode
 */

#ifndef ti_drivers_BatteryMonitor__include
#define ti_drivers_BatteryMonitor__include

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

#include <ti/drivers/utils/List.h>

#ifdef __cplusplus
extern "C" {
#endif

#define BatteryMonitor_STATUS_RESERVED (-32)

#define BatteryMonitor_STATUS_SUCCESS (0)

#define BatteryMonitor_STATUS_ERROR (-1)

/* @cond NODOC
 *
 * Type declaration for the notification object made separately from the
 * struct definition because of the circular dependency between
 * #BatteryMonitor_NotifyFxn() and #BatteryMonitor_NotifyObj.
 */
typedef struct BatteryMonitor_NotifyObj BatteryMonitor_NotifyObj;
/* @endcond */

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

struct BatteryMonitor_NotifyObj
{
    List_Elem link;                     
    BatteryMonitor_NotifyFxn notifyFxn; 
    uint16_t thresholdHigh;             
    uint16_t thresholdLow;              
    uintptr_t clientArg;                
    bool isRegistered;                  
};

void BatteryMonitor_init(void);

uint16_t BatteryMonitor_getVoltage(void);

int_fast16_t BatteryMonitor_registerNotifyHigh(BatteryMonitor_NotifyObj *notifyObject,
                                               uint16_t thresholdHigh,
                                               BatteryMonitor_NotifyFxn notifyFxn,
                                               uintptr_t clientArg);

int_fast16_t BatteryMonitor_registerNotifyLow(BatteryMonitor_NotifyObj *notifyObject,
                                              uint16_t thresholdLow,
                                              BatteryMonitor_NotifyFxn notifyFxn,
                                              uintptr_t clientArg);

int_fast16_t BatteryMonitor_registerNotifyRange(BatteryMonitor_NotifyObj *notifyObject,
                                                uint16_t thresholdHigh,
                                                uint16_t thresholdLow,
                                                BatteryMonitor_NotifyFxn notifyFxn,
                                                uintptr_t clientArg);

int_fast16_t BatteryMonitor_unregisterNotify(BatteryMonitor_NotifyObj *notifyObject);

static inline uint16_t BatteryMonitor_getThresholdHigh(BatteryMonitor_NotifyObj *notifyObject)
{
    return notifyObject->thresholdHigh;
}

static inline uint16_t BatteryMonitor_getThresholdLow(BatteryMonitor_NotifyObj *notifyObject)
{
    return notifyObject->thresholdLow;
}

static inline void BatteryMonitor_getThresholdRange(BatteryMonitor_NotifyObj *notifyObject,
                                                    uint16_t *thresholdHigh,
                                                    uint16_t *thresholdLow)
{
    *thresholdHigh = notifyObject->thresholdHigh;
    *thresholdLow  = notifyObject->thresholdLow;
}

static inline uintptr_t BatteryMonitor_getClientArg(BatteryMonitor_NotifyObj *notifyObject)
{
    return notifyObject->clientArg;
}

static inline BatteryMonitor_NotifyFxn BatteryMonitor_getNotifyFxn(BatteryMonitor_NotifyObj *notifyObject)
{
    return notifyObject->notifyFxn;
}

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_BatteryMonitor__include */