le_ips_interface.h

Go to the documentation of this file.
    1 /*
    2  * ====================== WARNING ======================
    3  *
    4  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
    5  * DO NOT MODIFY IN ANY WAY.
    6  *
    7  * ====================== WARNING ======================
    8  */
    9 
   10 /**
   11  * @page c_ips Input Power Supply Monitoring API
   12  *
   13  * @ref le_ips_interface.h "API Reference"
   14  *
   15  * <HR>
   16  *
   17  * The IPS API is used to get monitoring information related to the platform voltage input and set
   18  *  warning and critical thresholds.
   19  *
   20  * @section le_ips_binding IPC interfaces binding
   21  *
   22  * All the functions of this API are provided by the @b modemService.
   23  *
   24  * Here's a code sample binding to modem services:
   25  * @verbatim
   26    bindings:
   27    {
   28       clientExe.clientComponent.le_ips -> modemService.le_ips
   29    }
   30    @endverbatim
   31  *
   32  * @section Input Power Supply Monitoring
   33  *
   34  * This functionality allows to retrieve the Platform input voltage in [mV], so that the
   35  *  application can use the information to diagnose why the modem isn't fully functioning.
   36  *
   37  * le_ips_GetInputVoltage() API allows the application to retrieve the Platform voltage input.
   38  *
   39  * @section Platform Input voltage Thresholds
   40  *
   41  * @warning When a Critical event occurs, some platform may automatically switch off.
   42  *
   43  * @warning On some platforms, the thresholds parameters are persistent and a Platform reboot is
   44  *  required for thresholds change takes effect.
   45  *
   46  * Four Thresholds are set to decide the state:
   47  *  the critical, warning, the normal and the high critical Platform input voltage thresholds.
   48  *
   49  * if the Platform input voltage decreases below the:
   50  *  - "High Critical Threshold - 1 " but still higher than "Warning Threshold",
   51  * @c LE_IPS_VOLTAGE_NORMAL event occurs.
   52  *  - "Warning Threshold" but still higher than "Critical Threshold",
   53  * @c LE_IPS_VOLTAGE_WARNING event occurs.
   54  *  - "Critical Threshold", a @c LE_IPS_VOLTAGE_CRITICAL event occurs.
   55  *
   56  * if the Platform input voltage goes up and it reaches the :
   57  *  - "Normal threshold", a @c LE_IPS_VOLTAGE_NORMAL event occurs.
   58  *  - "High critical thresholds", a @c LE_IPS_HI_VOLTAGE_CRITICAL event occurs.
   59  *
   60  * @note The threshold values range is platform dependent.
   61  *
   62  * - le_ips_SetVoltageThresholds() API allows the application to set Platform input voltage
   63  *  thresholds.
   64  * - le_ips_GetVoltageThresholds() API allows the application to get Platform input voltage
   65  * thresholds.
   66  * - le_ips_AddThresholdEventHandler() API adds a handler to notify when the Platform input voltage
   67  *  threshold is reached.
   68  * - le_ips_RemoveThresholdEventHandler() API removes the Platform input voltage handler.
   69  * <HR>
   70  *
   71  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
   72  */
   73 /**
   74  * @file le_ips_interface.h
   75  *
   76  * Legato @ref c_ips include file.
   77  *
   78  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
   79  */
   80 
   81 #ifndef LE_IPS_INTERFACE_H_INCLUDE_GUARD
   82 #define LE_IPS_INTERFACE_H_INCLUDE_GUARD
   83 
   84 
   85 #include "legato.h"
   86 
   87 //--------------------------------------------------------------------------------------------------
   88 /**
   89  *
   90  * Connect the current client thread to the service providing this API. Block until the service is
   91  * available.
   92  *
   93  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
   94  * called before any other functions in this API.  Normally, ConnectService is automatically called
   95  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
   96  *
   97  * This function is created automatically.
   98  */
   99 //--------------------------------------------------------------------------------------------------
  100 void le_ips_ConnectService
  101 (
  102     void
  103 );
  104 
  105 //--------------------------------------------------------------------------------------------------
  106 /**
  107  *
  108  * Try to connect the current client thread to the service providing this API. Return with an error
  109  * if the service is not available.
  110  *
  111  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  112  * called before any other functions in this API.  Normally, ConnectService is automatically called
  113  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  114  *
  115  * This function is created automatically.
  116  *
  117  * @return
  118  *  - LE_OK if the client connected successfully to the service.
  119  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
  120  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  121  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  122  */
  123 //--------------------------------------------------------------------------------------------------
  124 le_result_t le_ips_TryConnectService
  125 (
  126     void
  127 );
  128 
  129 //--------------------------------------------------------------------------------------------------
  130 /**
  131  *
  132  * Disconnect the current client thread from the service providing this API.
  133  *
  134  * Normally, this function doesn't need to be called. After this function is called, there's no
  135  * longer a connection to the service, and the functions in this API can't be used. For details, see
  136  * @ref apiFilesC_client.
  137  *
  138  * This function is created automatically.
  139  */
  140 //--------------------------------------------------------------------------------------------------
  141 void le_ips_DisconnectService
  142 (
  143     void
  144 );
  145 
  146 
  147 //--------------------------------------------------------------------------------------------------
  148 /**
  149  * Platform input voltage event type.
  150  */
  151 //--------------------------------------------------------------------------------------------------
  152 typedef enum
  153 {
  154     LE_IPS_VOLTAGE_HI_CRITICAL = 0,
  155         ///< High Critical input voltage threshold is reached.
  156 
  157     LE_IPS_VOLTAGE_NORMAL = 1,
  158         ///< Normal input voltage threshold is reached.
  159 
  160     LE_IPS_VOLTAGE_WARNING = 2,
  161         ///< Warning input voltage threshold is reached.
  162 
  163     LE_IPS_VOLTAGE_CRITICAL = 3
  164         ///< Critical input voltage threshold is reached.
  165 }
  166 le_ips_ThresholdStatus_t;
  167 
  168 
  169 //--------------------------------------------------------------------------------------------------
  170 /**
  171  * Reference type used by Add/Remove functions for EVENT 'le_ips_ThresholdEvent'
  172  */
  173 //--------------------------------------------------------------------------------------------------
  174 typedef struct le_ips_ThresholdEventHandler* le_ips_ThresholdEventHandlerRef_t;
  175 
  176 
  177 //--------------------------------------------------------------------------------------------------
  178 /**
  179  * Handler for Platform input voltage event.
  180  *
  181  * @param event
  182  *        Input voltage threshold event reached.
  183  * @param contextPtr
  184  */
  185 //--------------------------------------------------------------------------------------------------
  186 typedef void (*le_ips_ThresholdEventHandlerFunc_t)
  187 (
  188     le_ips_ThresholdStatus_t event,
  189     void* contextPtr
  190 );
  191 
  192 //--------------------------------------------------------------------------------------------------
  193 /**
  194  * Add handler function for EVENT 'le_ips_ThresholdEvent'
  195  *
  196  * This event provides information on Threshold reached.
  197  */
  198 //--------------------------------------------------------------------------------------------------
  199 le_ips_ThresholdEventHandlerRef_t le_ips_AddThresholdEventHandler
  200 (
  201     le_ips_ThresholdEventHandlerFunc_t handlerPtr,
  202         ///< [IN]
  203 
  204     void* contextPtr
  205         ///< [IN]
  206 );
  207 
  208 //--------------------------------------------------------------------------------------------------
  209 /**
  210  * Remove handler function for EVENT 'le_ips_ThresholdEvent'
  211  */
  212 //--------------------------------------------------------------------------------------------------
  213 void le_ips_RemoveThresholdEventHandler
  214 (
  215     le_ips_ThresholdEventHandlerRef_t addHandlerRef
  216         ///< [IN]
  217 );
  218 
  219 //--------------------------------------------------------------------------------------------------
  220 /**
  221  * Get the Platform input voltage in [mV].
  222  *
  223  * @return
  224  *      - LE_OK            The function succeeded.
  225  *      - LE_FAULT         The function failed to get the value.
  226  */
  227 //--------------------------------------------------------------------------------------------------
  228 le_result_t le_ips_GetInputVoltage
  229 (
  230     uint32_t* inputVoltagePtr
  231         ///< [OUT] [OUT] The input voltage in [mV]
  232 );
  233 
  234 //--------------------------------------------------------------------------------------------------
  235 /**
  236  * Set the Platform warning and critical input voltage thresholds in [mV].
  237  *  When thresholds input voltage are reached, a input voltage event is triggered.
  238  *
  239  * @return
  240  *      - LE_OK            The function succeeded.
  241  *      - LE_BAD_PARAMETER The hiCriticalVolt threshold is equal or lower than the (normalVolt+1)
  242  *                           threshold.
  243  *                         The warningVolt threshold is equal to or higher than the normalVolt
  244  *                           threshold.
  245  *                         The warningVolt threshold is equal to or lower than the criticalVolt
  246  *                           threshold.
  247  *      - LE_FAULT         The function failed to set the thresholds.
  248  */
  249 //--------------------------------------------------------------------------------------------------
  250 le_result_t le_ips_SetVoltageThresholds
  251 (
  252     uint16_t criticalVolt,
  253         ///< [IN] [IN] The critical input voltage threshold in [mV].
  254 
  255     uint16_t warningVolt,
  256         ///< [IN] [IN] The warning input voltage threshold in [mV].
  257 
  258     uint16_t normalVolt,
  259         ///< [IN] [IN] The normal input voltage threshold in [mV].
  260 
  261     uint16_t hiCriticalVolt
  262         ///< [IN] [IN] The high critical input voltage threshold in [mV].
  263 );
  264 
  265 //--------------------------------------------------------------------------------------------------
  266 /**
  267  * Get the Platform warning and critical input voltage thresholds in [mV].
  268  *
  269  * @return
  270  *      - LE_OK            The function succeeded.
  271  *      - LE_FAULT         The function failed to get the thresholds.
  272  */
  273 //--------------------------------------------------------------------------------------------------
  274 le_result_t le_ips_GetVoltageThresholds
  275 (
  276     uint16_t* criticalVoltPtr,
  277         ///< [OUT] [OUT] The critical input voltage threshold in [mV].
  278 
  279     uint16_t* warningVoltPtr,
  280         ///< [OUT] [OUT] The warning input voltage threshold in [mV].
  281 
  282     uint16_t* normalVoltPtr,
  283         ///< [OUT] [OUT] The normal input voltage threshold in [mV].
  284 
  285     uint16_t* hiCriticalVoltPtr
  286         ///< [OUT] [IN] The high critical input voltage threshold in [mV].
  287 );
  288 
  289 
  290 #endif // LE_IPS_INTERFACE_H_INCLUDE_GUARD
  291 
le_ips_AddThresholdEventHandler
le_ips_ThresholdEventHandlerRef_t le_ips_AddThresholdEventHandler(le_ips_ThresholdEventHandlerFunc_t handlerPtr, void *contextPtr)


le_ips_RemoveThresholdEventHandler
void le_ips_RemoveThresholdEventHandler(le_ips_ThresholdEventHandlerRef_t addHandlerRef)


le_ips_GetInputVoltage
le_result_t le_ips_GetInputVoltage(uint32_t *inputVoltagePtr)


le_ips_ConnectService
void le_ips_ConnectService(void)


le_ips_ThresholdStatus_t
le_ips_ThresholdStatus_t
Definition: le_ips_interface.h:152


le_result_t
le_result_t
Definition: le_basics.h:35


le_ips_ThresholdEventHandlerRef_t
struct le_ips_ThresholdEventHandler * le_ips_ThresholdEventHandlerRef_t
Definition: le_ips_interface.h:174


LE_IPS_VOLTAGE_NORMAL
Normal input voltage threshold is reached. 
Definition: le_ips_interface.h:157


LE_IPS_VOLTAGE_WARNING
Warning input voltage threshold is reached. 
Definition: le_ips_interface.h:160


le_ips_DisconnectService
void le_ips_DisconnectService(void)


le_ips_TryConnectService
le_result_t le_ips_TryConnectService(void)


le_ips_SetVoltageThresholds
le_result_t le_ips_SetVoltageThresholds(uint16_t criticalVolt, uint16_t warningVolt, uint16_t normalVolt, uint16_t hiCriticalVolt)



LE_IPS_VOLTAGE_HI_CRITICAL
High Critical input voltage threshold is reached. 
Definition: le_ips_interface.h:154


LE_IPS_VOLTAGE_CRITICAL
Critical input voltage threshold is reached. 
Definition: le_ips_interface.h:163


le_ips_ThresholdEventHandlerFunc_t
void(* le_ips_ThresholdEventHandlerFunc_t)(le_ips_ThresholdStatus_t event, void *contextPtr)
Definition: le_ips_interface.h:187


le_ips_GetVoltageThresholds
le_result_t le_ips_GetVoltageThresholds(uint16_t *criticalVoltPtr, uint16_t *warningVoltPtr, uint16_t *normalVoltPtr, uint16_t *hiCriticalVoltPtr)