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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
180 (
181  void
182 );
183 
184 
185 //--------------------------------------------------------------------------------------------------
186 /**
187  * Platform input voltage event type.
188  */
189 //--------------------------------------------------------------------------------------------------
190 typedef enum
191 {
193  ///< High Critical input voltage threshold is reached.
195  ///< Normal input voltage threshold is reached.
197  ///< Warning input voltage threshold is reached.
199  ///< Critical input voltage threshold is reached.
200 }
202 
203 
204 //--------------------------------------------------------------------------------------------------
205 /**
206  * Platform power source type.
207  */
208 //--------------------------------------------------------------------------------------------------
209 typedef enum
210 {
212  ///< Platform is powered by an external source.
214  ///< Platform is powered by a battery.
215 }
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 //--------------------------------------------------------------------------------------------------
233 (
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 //--------------------------------------------------------------------------------------------------
249 (
251  ///< [IN]
252  void* contextPtr
253  ///< [IN]
254 );
255 
256 //--------------------------------------------------------------------------------------------------
257 /**
258  * Remove handler function for EVENT 'le_ips_ThresholdEvent'
259  */
260 //--------------------------------------------------------------------------------------------------
262 (
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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_ThresholdEventHandlerRef_t le_ips_AddThresholdEventHandler(le_ips_ThresholdEventHandlerFunc_t handlerPtr, void *contextPtr)
le_result_t le_ips_GetInputVoltage(uint32_t *inputVoltagePtr)
void le_ips_ConnectService(void)
le_result_t le_ips_GetPowerSource(le_ips_PowerSource_t *powerSourcePtr)
void le_ips_RemoveThresholdEventHandler(le_ips_ThresholdEventHandlerRef_t handlerRef)
le_ips_ThresholdStatus_t
Definition: le_ips_interface.h:190
le_result_t
Definition: le_basics.h:35
le_result_t le_ips_GetBatteryLevel(uint8_t *batteryLevelPtr)
struct le_ips_ThresholdEventHandler * le_ips_ThresholdEventHandlerRef_t
Definition: le_ips_interface.h:224
Normal input voltage threshold is reached.
Definition: le_ips_interface.h:194
void(* le_ips_ThresholdEventHandlerFunc_t)(le_ips_ThresholdStatus_t event, void *contextPtr)
Definition: le_ips_interface.h:233
void(* le_ips_DisconnectHandler_t)(void *)
Definition: le_ips_interface.h:108
Platform is powered by a battery.
Definition: le_ips_interface.h:213
Platform is powered by an external source.
Definition: le_ips_interface.h:211
Warning input voltage threshold is reached.
Definition: le_ips_interface.h:196
void le_ips_DisconnectService(void)
le_result_t le_ips_TryConnectService(void)
le_result_t le_ips_SetVoltageThresholds(uint16_t criticalVolt, uint16_t warningVolt, uint16_t normalVolt, uint16_t hiCriticalVolt)
High Critical input voltage threshold is reached.
Definition: le_ips_interface.h:192
le_result_t le_ips_SetBatteryLevel(uint8_t batteryLevel)
void le_ips_SetServerDisconnectHandler(le_ips_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_ips_PowerSource_t
Definition: le_ips_interface.h:209
Critical input voltage threshold is reached.
Definition: le_ips_interface.h:198
le_result_t le_ips_GetVoltageThresholds(uint16_t *criticalVoltPtr, uint16_t *warningVoltPtr, uint16_t *normalVoltPtr, uint16_t *hiCriticalVoltPtr)