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  * In case the device is powered by an external battery monitored by an application, this
   47  * application can set the battery level with the le_ips_SetBatteryLevel() API. This value will
   48  * then be used when the battery level is requested through the le_ips_GetBatteryLevel() API.
   49  *
   50  * @note The value set by le_ips_SetBatteryLevel() will be reported by le_ips_GetBatteryLevel()
   51  * until Legato is restarted.
   52  *
   53  * @section le_ips_voltageThresholds Platform input voltage thresholds
   54  *
   55  * @warning When a critical event occurs, some platform may automatically switch off.
   56  *
   57  * @warning On some platforms, the thresholds parameters are persistent and a platform reboot is
   58  * required for thresholds change takes effect.
   59  *
   60  * Four thresholds are set to decide the state: the @e critical, @e warning, @e normal and
   61  * <em>high critical</em> platform input voltage thresholds.
   62  *
   63  * if the platform input voltage decreases below the:
   64  *  - "High critical threshold - 1 " but still higher than "Warning threshold",
   65  * @c LE_IPS_VOLTAGE_NORMAL event occurs.
   66  *  - "Warning threshold" but still higher than "Critical threshold",
   67  * @c LE_IPS_VOLTAGE_WARNING event occurs.
   68  *  - "Critical threshold", a @c LE_IPS_VOLTAGE_CRITICAL event occurs.
   69  *
   70  * if the platform input voltage goes up and it reaches the:
   71  *  - "Normal threshold", a @c LE_IPS_VOLTAGE_NORMAL event occurs.
   72  *  - "High critical thresholds", a @c LE_IPS_HI_VOLTAGE_CRITICAL event occurs.
   73  *
   74  * @note The threshold values range is platform dependent.
   75  *
   76  * - le_ips_SetVoltageThresholds() API allows the application to set platform input voltage
   77  *  thresholds.
   78  * - le_ips_GetVoltageThresholds() API allows the application to get platform input voltage
   79  * thresholds.
   80  * - le_ips_AddThresholdEventHandler() API adds a handler to notify when the platform input voltage
   81  *  threshold is reached.
   82  * - le_ips_RemoveThresholdEventHandler() API removes the platform input voltage handler.
   83  *
   84  * <HR>
   85  *
   86  * Copyright (C) Sierra Wireless Inc.
   87  */
   88 /**
   89  * @file le_ips_interface.h
   90  *
   91  * Legato @ref c_ips include file.
   92  *
   93  * Copyright (C) Sierra Wireless Inc.
   94  */
   95 
   96 #ifndef LE_IPS_INTERFACE_H_INCLUDE_GUARD
   97 #define LE_IPS_INTERFACE_H_INCLUDE_GUARD
   98 
   99 
  100 #include "legato.h"
  101 
  102 
  103 //--------------------------------------------------------------------------------------------------
  104 /**
  105  * Type for handler called when a server disconnects.
  106  */
  107 //--------------------------------------------------------------------------------------------------
  108 typedef void (*le_ips_DisconnectHandler_t)(void *);
  109 
  110 //--------------------------------------------------------------------------------------------------
  111 /**
  112  *
  113  * Connect the current client thread to the service providing this API. Block until the service is
  114  * available.
  115  *
  116  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  117  * called before any other functions in this API.  Normally, ConnectService is automatically called
  118  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  119  *
  120  * This function is created automatically.
  121  */
  122 //--------------------------------------------------------------------------------------------------
  123 void le_ips_ConnectService
  124 (
  125     void
  126 );
  127 
  128 //--------------------------------------------------------------------------------------------------
  129 /**
  130  *
  131  * Try to connect the current client thread to the service providing this API. Return with an error
  132  * if the service is not available.
  133  *
  134  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  135  * called before any other functions in this API.  Normally, ConnectService is automatically called
  136  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  137  *
  138  * This function is created automatically.
  139  *
  140  * @return
  141  *  - LE_OK if the client connected successfully to the service.
  142  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  143  *    bound.
  144  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  145  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  146  */
  147 //--------------------------------------------------------------------------------------------------
  148 le_result_t le_ips_TryConnectService
  149 (
  150     void
  151 );
  152 
  153 //--------------------------------------------------------------------------------------------------
  154 /**
  155  * Set handler called when server disconnection is detected.
  156  *
  157  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  158  * to continue without exiting, it should call longjmp() from inside the handler.
  159  */
  160 //--------------------------------------------------------------------------------------------------
  161 void le_ips_SetServerDisconnectHandler
  162 (
  163     le_ips_DisconnectHandler_t disconnectHandler,
  164     void *contextPtr
  165 );
  166 
  167 //--------------------------------------------------------------------------------------------------
  168 /**
  169  *
  170  * Disconnect the current client thread from the service providing this API.
  171  *
  172  * Normally, this function doesn't need to be called. After this function is called, there's no
  173  * longer a connection to the service, and the functions in this API can't be used. For details, see
  174  * @ref apiFilesC_client.
  175  *
  176  * This function is created automatically.
  177  */
  178 //--------------------------------------------------------------------------------------------------
  179 void le_ips_DisconnectService
  180 (
  181     void
  182 );
  183 
  184 
  185 //--------------------------------------------------------------------------------------------------
  186 /**
  187  * Platform input voltage event type.
  188  */
  189 //--------------------------------------------------------------------------------------------------
  190 typedef enum
  191 {
  192     LE_IPS_VOLTAGE_HI_CRITICAL = 0,
  193         ///< High Critical input voltage threshold is reached.
  194     LE_IPS_VOLTAGE_NORMAL = 1,
  195         ///< Normal input voltage threshold is reached.
  196     LE_IPS_VOLTAGE_WARNING = 2,
  197         ///< Warning input voltage threshold is reached.
  198     LE_IPS_VOLTAGE_CRITICAL = 3
  199         ///< Critical input voltage threshold is reached.
  200 }
  201 le_ips_ThresholdStatus_t;
  202 
  203 
  204 //--------------------------------------------------------------------------------------------------
  205 /**
  206  * Platform power source type.
  207  */
  208 //--------------------------------------------------------------------------------------------------
  209 typedef enum
  210 {
  211     LE_IPS_POWER_SOURCE_EXTERNAL = 0,
  212         ///< Platform is powered by an external source.
  213     LE_IPS_POWER_SOURCE_BATTERY = 1
  214         ///< Platform is powered by a battery.
  215 }
  216 le_ips_PowerSource_t;
  217 
  218 
  219 //--------------------------------------------------------------------------------------------------
  220 /**
  221  * Reference type used by Add/Remove functions for EVENT 'le_ips_ThresholdEvent'
  222  */
  223 //--------------------------------------------------------------------------------------------------
  224 typedef struct le_ips_ThresholdEventHandler* le_ips_ThresholdEventHandlerRef_t;
  225 
  226 
  227 //--------------------------------------------------------------------------------------------------
  228 /**
  229  * Handler for Platform input voltage event.
  230  */
  231 //--------------------------------------------------------------------------------------------------
  232 typedef void (*le_ips_ThresholdEventHandlerFunc_t)
  233 (
  234     le_ips_ThresholdStatus_t event,
  235         ///< Input voltage threshold event reached.
  236     void* contextPtr
  237         ///<
  238 );
  239 
  240 //--------------------------------------------------------------------------------------------------
  241 /**
  242  * Add handler function for EVENT 'le_ips_ThresholdEvent'
  243  *
  244  * This event provides information on Threshold reached.
  245  *
  246  */
  247 //--------------------------------------------------------------------------------------------------
  248 le_ips_ThresholdEventHandlerRef_t le_ips_AddThresholdEventHandler
  249 (
  250     le_ips_ThresholdEventHandlerFunc_t handlerPtr,
  251         ///< [IN]
  252     void* contextPtr
  253         ///< [IN]
  254 );
  255 
  256 //--------------------------------------------------------------------------------------------------
  257 /**
  258  * Remove handler function for EVENT 'le_ips_ThresholdEvent'
  259  */
  260 //--------------------------------------------------------------------------------------------------
  261 void le_ips_RemoveThresholdEventHandler
  262 (
  263     le_ips_ThresholdEventHandlerRef_t handlerRef
  264         ///< [IN]
  265 );
  266 
  267 //--------------------------------------------------------------------------------------------------
  268 /**
  269  * Get the Platform input voltage in [mV].
  270  *
  271  * @return
  272  *      - LE_OK            The function succeeded.
  273  *      - LE_FAULT         The function failed to get the value.
  274  *
  275  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
  276  *       function will not return.
  277  */
  278 //--------------------------------------------------------------------------------------------------
  279 le_result_t le_ips_GetInputVoltage
  280 (
  281     uint32_t* inputVoltagePtr
  282         ///< [OUT] [OUT] The input voltage in [mV]
  283 );
  284 
  285 //--------------------------------------------------------------------------------------------------
  286 /**
  287  * Set the Platform warning and critical input voltage thresholds in [mV].
  288  *  When thresholds input voltage are reached, a input voltage event is triggered.
  289  *
  290  * @return
  291  *      - LE_OK            The function succeeded.
  292  *      - LE_BAD_PARAMETER The hiCriticalVolt threshold is equal or lower than the (normalVolt+1)
  293  *                           threshold.
  294  *                         The warningVolt threshold is equal to or higher than the normalVolt
  295  *                           threshold.
  296  *                         The warningVolt threshold is equal to or lower than the criticalVolt
  297  *                           threshold.
  298  *      - LE_FAULT         The function failed to set the thresholds.
  299  */
  300 //--------------------------------------------------------------------------------------------------
  301 le_result_t le_ips_SetVoltageThresholds
  302 (
  303     uint16_t criticalVolt,
  304         ///< [IN] [IN] The critical input voltage threshold in [mV].
  305     uint16_t warningVolt,
  306         ///< [IN] [IN] The warning input voltage threshold in [mV].
  307     uint16_t normalVolt,
  308         ///< [IN] [IN] The normal input voltage threshold in [mV].
  309     uint16_t hiCriticalVolt
  310         ///< [IN] [IN] The high critical input voltage threshold in [mV].
  311 );
  312 
  313 //--------------------------------------------------------------------------------------------------
  314 /**
  315  * Get the Platform warning and critical input voltage thresholds in [mV].
  316  *
  317  * @return
  318  *      - LE_OK            The function succeeded.
  319  *      - LE_FAULT         The function failed to get the thresholds.
  320  *
  321  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
  322  *       function will not return.
  323  */
  324 //--------------------------------------------------------------------------------------------------
  325 le_result_t le_ips_GetVoltageThresholds
  326 (
  327     uint16_t* criticalVoltPtr,
  328         ///< [OUT] [OUT] The critical input voltage threshold in [mV].
  329     uint16_t* warningVoltPtr,
  330         ///< [OUT] [OUT] The warning input voltage threshold in [mV].
  331     uint16_t* normalVoltPtr,
  332         ///< [OUT] [OUT] The normal input voltage threshold in [mV].
  333     uint16_t* hiCriticalVoltPtr
  334         ///< [OUT] [IN] The high critical input voltage threshold in [mV].
  335 );
  336 
  337 //--------------------------------------------------------------------------------------------------
  338 /**
  339  * Get the Platform power source.
  340  *
  341  * @return
  342  *      - LE_OK            The function succeeded.
  343  *      - LE_FAULT         The function failed to get the value.
  344  *
  345  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
  346  *       function will not return.
  347  */
  348 //--------------------------------------------------------------------------------------------------
  349 le_result_t le_ips_GetPowerSource
  350 (
  351     le_ips_PowerSource_t* powerSourcePtr
  352         ///< [OUT] [OUT] The power source.
  353 );
  354 
  355 //--------------------------------------------------------------------------------------------------
  356 /**
  357  * Get the Platform battery level in percent:
  358  *  - 0: battery is exhausted or platform does not have a battery connected
  359  *  - 1 to 100: percentage of battery capacity remaining
  360  *
  361  * @return
  362  *      - LE_OK            The function succeeded.
  363  *      - LE_FAULT         The function failed to get the value.
  364  *
  365  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
  366  *       function will not return.
  367  */
  368 //--------------------------------------------------------------------------------------------------
  369 le_result_t le_ips_GetBatteryLevel
  370 (
  371     uint8_t* batteryLevelPtr
  372         ///< [OUT] [OUT] The battery level in percent.
  373 );
  374 
  375 //--------------------------------------------------------------------------------------------------
  376 /**
  377  * Set the Platform battery level in percent.
  378  * This is useful when an external battery is used and its level is provided by the application
  379  * monitoring it.
  380  *
  381  * @note The battery level set through this API will be the value reported by
  382  * le_ips_GetBatteryLevel() until Legato is restarted.
  383  *
  384  * @return
  385  *      - LE_OK            The function succeeded.
  386  *      - LE_BAD_PARAMETER Incorrect battery level provided.
  387  */
  388 //--------------------------------------------------------------------------------------------------
  389 le_result_t le_ips_SetBatteryLevel
  390 (
  391     uint8_t batteryLevel
  392         ///< [IN] [IN] The battery level in percent.
  393 );
  394 
  395 #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:190


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


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


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


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


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


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


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


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


le_ips_SetBatteryLevel
le_result_t le_ips_SetBatteryLevel(uint8_t batteryLevel)


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


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


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