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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
142 (
143  void
144 );
145 
146 
147 //--------------------------------------------------------------------------------------------------
148 /**
149  * Platform input voltage event type.
150  */
151 //--------------------------------------------------------------------------------------------------
152 typedef enum
153 {
155  ///< High Critical input voltage threshold is reached.
156 
158  ///< Normal input voltage threshold is reached.
159 
161  ///< Warning input voltage threshold is reached.
162 
164  ///< Critical input voltage threshold is reached.
165 }
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 //--------------------------------------------------------------------------------------------------
187 (
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 //--------------------------------------------------------------------------------------------------
200 (
202  ///< [IN]
203 
204  void* contextPtr
205  ///< [IN]
206 );
207 
208 //--------------------------------------------------------------------------------------------------
209 /**
210  * Remove handler function for EVENT 'le_ips_ThresholdEvent'
211  */
212 //--------------------------------------------------------------------------------------------------
214 (
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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_ThresholdEventHandlerRef_t le_ips_AddThresholdEventHandler(le_ips_ThresholdEventHandlerFunc_t handlerPtr, void *contextPtr)
void le_ips_RemoveThresholdEventHandler(le_ips_ThresholdEventHandlerRef_t addHandlerRef)
le_result_t le_ips_GetInputVoltage(uint32_t *inputVoltagePtr)
void le_ips_ConnectService(void)
le_ips_ThresholdStatus_t
Definition: le_ips_interface.h:152
le_result_t
Definition: le_basics.h:35
struct le_ips_ThresholdEventHandler * le_ips_ThresholdEventHandlerRef_t
Definition: le_ips_interface.h:174
Normal input voltage threshold is reached.
Definition: le_ips_interface.h:157
Warning input voltage threshold is reached.
Definition: le_ips_interface.h:160
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:154
Critical input voltage threshold is reached.
Definition: le_ips_interface.h:163
void(* le_ips_ThresholdEventHandlerFunc_t)(le_ips_ThresholdStatus_t event, void *contextPtr)
Definition: le_ips_interface.h:187
le_result_t le_ips_GetVoltageThresholds(uint16_t *criticalVoltPtr, uint16_t *warningVoltPtr, uint16_t *normalVoltPtr, uint16_t *hiCriticalVoltPtr)