le_ips_interface.h

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


le_ips_GetInputVoltage
le_result_t le_ips_GetInputVoltage(uint32_t *inputVoltagePtr)


le_ips_ConnectService
void le_ips_ConnectService(void)


le_ips_GetPowerSource
le_result_t le_ips_GetPowerSource(le_ips_PowerSource_t *powerSourcePtr)


le_ips_RemoveThresholdEventHandler
void le_ips_RemoveThresholdEventHandler(le_ips_ThresholdEventHandlerRef_t handlerRef)


le_ips_ThresholdStatus_t
le_ips_ThresholdStatus_t
Definition: le_ips_interface.h:183


le_result_t
le_result_t
Definition: le_basics.h:35


le_ips_GetBatteryLevel
le_result_t le_ips_GetBatteryLevel(uint8_t *batteryLevelPtr)


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


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


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


le_ips_DisconnectHandler_t
void(* le_ips_DisconnectHandler_t)(void *)
Definition: le_ips_interface.h:101


LE_IPS_POWER_SOURCE_BATTERY
Platform is powered by a battery. 
Definition: le_ips_interface.h:206


LE_IPS_POWER_SOURCE_EXTERNAL
Platform is powered by an external source. 
Definition: le_ips_interface.h:204


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


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:185


le_ips_SetServerDisconnectHandler
void le_ips_SetServerDisconnectHandler(le_ips_DisconnectHandler_t disconnectHandler, void *contextPtr)


le_ips_PowerSource_t
le_ips_PowerSource_t
Definition: le_ips_interface.h:202


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


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