le_antenna_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_antenna Antenna Monitoring
14  *
15  * @ref le_antenna_interface.h "API Reference"
16  *
17  * <HR>
18  *
19  * This file contains reference definitions for the antenna diagnostic APIs.
20  *
21  * @section le_antenna_binding IPC interfaces binding
22  *
23  * All functions of this API are provided by the @b modemService.
24  *
25  * Here's a code sample binding to modem services:
26  * @verbatim
27  bindings:
28  {
29  clientExe.clientComponent.le_antenna -> modemService.le_antenna
30  }
31  @endverbatim
32  *
33  * @section le_antenna_cell_antenna Cellular or Diversity antenna
34  *
35  * @subsection le_antenna_cell_antenna_diag Diagnostics principle
36  *
37  * Diagnostic functionality detects antenna presence and/or defective
38  * antennas.
39  *
40  * Antenna diagnostics are based on the following principles:
41  *
42  * A small DC current passes through the coaxial cable to the antenna. A resistive bridge is
43  * used to provide different voltage depending on the antenna state.
44  *
45  * @note Only antennas with a resistor between the radiating element and ground are supported.
46  *
47  * These are the diagnostic states:
48  * - open circuit: there's no antenna but RF open circuit
49  * - closed circuit: antenna is present
50  * - short circuit: with or without antenna, short circuit for RF path.
51  *
52  * @subsection le_antenna_cell_thres_subsection Thresholds
53  *
54  * Configurable thresholds are compared to the ADC (Analog to Digital Converter) reading from the
55  * antenna diagnostic voltage to determine the antenna state.
56  *
57  * Short and Open threshold limits determine the antenna's state:
58  *
59  * <b>Short Threshold Limit</b>
60  * - short circuit: unknown state
61  * - close circuit: presence of antenna
62  *
63  * A short event is reported for the Cellular or Diversity antenna if the ADC value is lower than
64  * the corresponding short limit.
65  *
66  * <b>Open Threshold Limit</b>
67  * - open circuit: no antenna
68  *
69  * An open event is reported for the Cellular or Diversity antenna
70  * if the ADC value is higher than the corresponding open limit.
71  *
72  * @note The open threshold is always HIGHER than the short threshold.
73  *
74  * @section le_antenna_gnss GNSS antenna
75  *
76  * @warning Be sure check the supported antenna diagnostic limit for your specific platform.
77  *
78  * @subpage platformConstraintsAntenna Platform Constraints
79  *
80  * @subsection le_antenna_gnss_diag Diagnostics principle
81  *
82  * This functionality detects (or not) the presence of an antenna or a defective
83  * antenna.
84  *
85  * Antenna diagnostics measure the current consumption for a GNSS active
86  * antenna, and provides current protection circuitry to protect the active
87  * antenna's power supply.
88  *
89  * These are the diagnostic states:
90  * - short circuit: with or without antenna, short circuit for RF path.
91  * - open circuit: there is no antenna.
92  * - closed circuit: presence of antenna.
93  * - over current : with or without antenna, short circuit for RF path and current
94  * hardware protection circuitry has tripped.
95  *
96  * @subsection le_antenna_gnss_thresh Thresholds
97  *
98  * GNSS configurable thresholds are compared to the ADC reading from the
99  * antenna diagnostic hardware design to measure the current to determine the antenna state.
100  *
101  * These are the status values reported for a GNSS antenna:
102  * - SHORT_CIRCUIT: ADC value > short limit, but over current HW not tripped.
103  * - CLOSE_CIRCUIT: short limit >= ADC value >= open limit.
104  * - OPEN_CIRCUIT: ADC value < open limit.
105  * - OVER_CURRENT: antenna is shorted and current HW protection circuitry has tripped.
106  *
107  * @note The open threshold is always LOWER than the short threshold.
108  *
109  * @section le_antenna_gnss_diag_adc_selection Antenna diagnostic ADC selection
110  *
111  * @warning Ensure to check the supported antenna diagnosis for your specific platform.
112  *
113  * By default, antenna diagnostics use an internal ADC to read the voltage from the
114  * integrated antenna diagnostic circuit, if any.
115  *
116  * An antenna design using an external antenna diagnostic circuit can still take
117  * advantage of the antenna monitoring service. Using the function le_antenna_SetExternalAdc(),
118  * the module can monitor one of the external ADC’s to read the voltage from an
119  * external antenna diagnosis circuit, rather than the internal ADC.
120  * le_antenna_GetExternalAdc() function reads the external ADC used to monitor
121  * the requested antenna.
122  *
123  * @section API_desc API description
124  *
125  * le_antenna_Request() API allows the application to monitor the requested antenna.
126  *
127  * le_antenna_GetType() API retrieves the antenna type from an antenna reference.
128  *
129  * le_antenna_SetShortLimit() API sets the ADC value used to detect a short circuit.
130  *
131  * le_antenna_GetShortLimit() API gets the ADC value used to detect a short circuit.
132  *
133  * le_antenna_SetOpenLimit() API sets the ADC value used to detect an open circuit.
134  *
135  * le_antenna_GetOpenLimit() API gets the ADC value used to detect an open circuit.
136  *
137  * le_antenna_AddStatusEventHandler() API adds a handler to be notified when the requested antenna
138  * status changed.
139  *
140  * le_antenna_RemoveStatusEventHandler() removes the antenna status handler.
141  *
142  * le_antenna_GetStatus() API gets the current antenna status.
143  *
144  * le_antenna_SetExternalAdc() API sets the external ADC used to monitor the requested antenna.
145  *
146  * le_antenna_GetExternalAdc() API gets the external ADC used to monitor the requested antenna.
147  *
148  *
149  * Copyright (C) Sierra Wireless Inc.
150  */
151 /**
152  * @file le_antenna_interface.h
153  *
154  * Legato @ref c_antenna include file.
155  *
156  * Copyright (C) Sierra Wireless Inc.
157  */
158 
159 #ifndef LE_ANTENNA_INTERFACE_H_INCLUDE_GUARD
160 #define LE_ANTENNA_INTERFACE_H_INCLUDE_GUARD
161 
162 
163 #include "legato.h"
164 
165 // Internal includes for this interface
166 #include "le_antenna_common.h"
167 /** @addtogroup le_antenna le_antenna API Reference
168  * @{
169  * @file le_antenna_common.h
170  * @file le_antenna_interface.h **/
171 //--------------------------------------------------------------------------------------------------
172 /**
173  * Type for handler called when a server disconnects.
174  */
175 //--------------------------------------------------------------------------------------------------
176 typedef void (*le_antenna_DisconnectHandler_t)(void *);
177 
178 //--------------------------------------------------------------------------------------------------
179 /**
180  *
181  * Connect the current client thread to the service providing this API. Block until the service is
182  * available.
183  *
184  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
185  * called before any other functions in this API. Normally, ConnectService is automatically called
186  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
187  *
188  * This function is created automatically.
189  */
190 //--------------------------------------------------------------------------------------------------
192 (
193  void
194 );
195 
196 //--------------------------------------------------------------------------------------------------
197 /**
198  *
199  * Try to connect the current client thread to the service providing this API. Return with an error
200  * if the service is not available.
201  *
202  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
203  * called before any other functions in this API. Normally, ConnectService is automatically called
204  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
205  *
206  * This function is created automatically.
207  *
208  * @return
209  * - LE_OK if the client connected successfully to the service.
210  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
211  * bound.
212  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
213  * - LE_COMM_ERROR if the Service Directory cannot be reached.
214  */
215 //--------------------------------------------------------------------------------------------------
217 (
218  void
219 );
220 
221 //--------------------------------------------------------------------------------------------------
222 /**
223  * Set handler called when server disconnection is detected.
224  *
225  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
226  * to continue without exiting, it should call longjmp() from inside the handler.
227  */
228 //--------------------------------------------------------------------------------------------------
230 (
231  le_antenna_DisconnectHandler_t disconnectHandler,
232  void *contextPtr
233 );
234 
235 //--------------------------------------------------------------------------------------------------
236 /**
237  *
238  * Disconnect the current client thread from the service providing this API.
239  *
240  * Normally, this function doesn't need to be called. After this function is called, there's no
241  * longer a connection to the service, and the functions in this API can't be used. For details, see
242  * @ref apiFilesC_client.
243  *
244  * This function is created automatically.
245  */
246 //--------------------------------------------------------------------------------------------------
248 (
249  void
250 );
251 
252 
253 //--------------------------------------------------------------------------------------------------
254 /**
255  * Reference type for an antenna diagnostic.
256  */
257 //--------------------------------------------------------------------------------------------------
258 
259 
260 //--------------------------------------------------------------------------------------------------
261 /**
262  * Antenna type.
263  */
264 //--------------------------------------------------------------------------------------------------
265 
266 
267 //--------------------------------------------------------------------------------------------------
268 /**
269  * Antenna status
270  */
271 //--------------------------------------------------------------------------------------------------
272 
273 
274 //--------------------------------------------------------------------------------------------------
275 /**
276  * Handler for antenna status.
277  *
278  */
279 //--------------------------------------------------------------------------------------------------
280 
281 
282 //--------------------------------------------------------------------------------------------------
283 /**
284  * Reference type used by Add/Remove functions for EVENT 'le_antenna_StatusEvent'
285  */
286 //--------------------------------------------------------------------------------------------------
287 
288 
289 //--------------------------------------------------------------------------------------------------
290 /**
291  * Requested the antenna monitoring.
292  *
293  * @return
294  * - Reference to the antenna object.
295  * - NULL on failure.
296  */
297 //--------------------------------------------------------------------------------------------------
299 (
300  le_antenna_Type_t antennaType
301  ///< [IN] antenna to be monitored
302 );
303 
304 //--------------------------------------------------------------------------------------------------
305 /**
306  * Get the antenna type.
307  *
308  * @return
309  * - LE_OK on success
310  * - LE_NOT_FOUND if the antenna reference is unknown
311  * - LE_BAD_PARAMETER if an invalid reference provided.
312  */
313 //--------------------------------------------------------------------------------------------------
315 (
316  le_antenna_ObjRef_t antennaRef,
317  ///< [IN] antenna reference
318  le_antenna_Type_t* antennaTypePtr
319  ///< [OUT] allocated antenna type
320 );
321 
322 //--------------------------------------------------------------------------------------------------
323 /**
324  * Set the ADC value used to detect a short circuit.
325  *
326  * @return
327  * - LE_OK on success
328  * - LE_NOT_FOUND if the antenna reference is unknown
329  * - LE_FAULT on other failure
330  */
331 //--------------------------------------------------------------------------------------------------
333 (
334  le_antenna_ObjRef_t antennaRef,
335  ///< [IN] antenna reference
336  uint32_t shortLimit
337  ///< [IN] ADC value used to detect a short circuit
338 );
339 
340 //--------------------------------------------------------------------------------------------------
341 /**
342  * Get the ADC value used to detect a short circuit.
343  *
344  * @return
345  * - LE_OK on success
346  * - LE_NOT_FOUND if the antenna reference is unknown
347  * - LE_FAULT on other failure
348  */
349 //--------------------------------------------------------------------------------------------------
351 (
352  le_antenna_ObjRef_t antennaRef,
353  ///< [IN] antenna reference
354  uint32_t* shortLimitPtr
355  ///< [OUT] ADC value used to detect a short circuit
356 );
357 
358 //--------------------------------------------------------------------------------------------------
359 /**
360  * Set the ADC value used to detect an open circuit.
361  *
362  * @return
363  * - LE_OK on success
364  * - LE_NOT_FOUND if the antenna reference is unknown
365  * - LE_FAULT on other failure
366  */
367 //--------------------------------------------------------------------------------------------------
369 (
370  le_antenna_ObjRef_t antennaRef,
371  ///< [IN] antenna reference
372  uint32_t openLimit
373  ///< [IN] ADC value used to detect an open circuit
374 );
375 
376 //--------------------------------------------------------------------------------------------------
377 /**
378  * Get the ADC value used to detect an open circuit.
379  *
380  * @return
381  * - LE_OK on success
382  * - LE_NOT_FOUND if the antenna reference is unknown
383  * - LE_FAULT on other failure
384  */
385 //--------------------------------------------------------------------------------------------------
387 (
388  le_antenna_ObjRef_t antennaRef,
389  ///< [IN] antenna reference
390  uint32_t* openLimitPtr
391  ///< [OUT] ADC value used to detect an open circuit
392 );
393 
394 //--------------------------------------------------------------------------------------------------
395 /**
396  * Add handler function for EVENT 'le_antenna_StatusEvent'
397  *
398  * This event provides information on antenna status for the given antennaRef.
399  *
400  */
401 //--------------------------------------------------------------------------------------------------
403 (
404  le_antenna_ObjRef_t antennaRef,
405  ///< [IN] antenna reference
407  ///< [IN]
408  void* contextPtr
409  ///< [IN]
410 );
411 
412 //--------------------------------------------------------------------------------------------------
413 /**
414  * Remove handler function for EVENT 'le_antenna_StatusEvent'
415  */
416 //--------------------------------------------------------------------------------------------------
418 (
420  ///< [IN]
421 );
422 
423 //--------------------------------------------------------------------------------------------------
424 /**
425  * Get the antenna status.
426  *
427  * @return
428  * - LE_OK on success
429  * - LE_NOT_FOUND if the antenna reference is unknown
430  * - LE_UNSUPPORTED if the antenna detection is not supported
431  * - LE_FAULT on other failure
432  *
433  */
434 //--------------------------------------------------------------------------------------------------
436 (
437  le_antenna_ObjRef_t antennaRef,
438  ///< [IN] antenna reference
439  le_antenna_Status_t* statusPtr
440  ///< [OUT] antenna status
441 );
442 
443 //--------------------------------------------------------------------------------------------------
444 /**
445  * Set the external ADC used to monitor the requested antenna.
446  *
447  * @return
448  * - LE_OK on success
449  * - LE_NOT_FOUND if the antenna reference is unknown
450  * - LE_UNSUPPORTED request not supported
451  * - LE_FAULT on other failure
452  *
453  * @note The same external ADC may not be selected for both antennas at the same time.
454  */
455 //--------------------------------------------------------------------------------------------------
457 (
458  le_antenna_ObjRef_t antennaRef,
459  ///< [IN] antenna reference
460  int8_t adcId
461  ///< [IN] ADC index used to monitor the requested antenna
462 );
463 
464 //--------------------------------------------------------------------------------------------------
465 /**
466  * Get the external ADC used to monitor the requested antenna.
467  *
468  * @return
469  * - LE_OK on success
470  * - LE_NOT_FOUND if the antenna reference is unknown
471  * - LE_UNSUPPORTED request not supported
472  * - LE_FAULT on other failure
473  *
474  * @note If the returned ADC index is "-1", it means no external ADC are used to monitor
475  * the requested antenna.
476  */
477 //--------------------------------------------------------------------------------------------------
479 (
480  le_antenna_ObjRef_t antennaRef,
481  ///< [IN] antenna reference
482  int8_t* adcIdPtr
483  ///< [OUT] ADC index used to monitor the requested antenna
484 );
485 
486 /** @} **/
487 
488 #endif // LE_ANTENNA_INTERFACE_H_INCLUDE_GUARD
void le_antenna_RemoveStatusEventHandler(le_antenna_StatusEventHandlerRef_t handlerRef)
le_result_t le_antenna_GetShortLimit(le_antenna_ObjRef_t antennaRef, uint32_t *shortLimitPtr)
le_result_t le_antenna_GetExternalAdc(le_antenna_ObjRef_t antennaRef, int8_t *adcIdPtr)
le_result_t
Definition: le_basics.h:46
le_antenna_Status_t
Definition: le_antenna_common.h:60
le_result_t le_antenna_GetStatus(le_antenna_ObjRef_t antennaRef, le_antenna_Status_t *statusPtr)
void(* le_antenna_DisconnectHandler_t)(void *)
Definition: le_antenna_interface.h:176
struct le_antenna_Obj * le_antenna_ObjRef_t
Definition: le_antenna_common.h:33
le_result_t le_antenna_SetExternalAdc(le_antenna_ObjRef_t antennaRef, int8_t adcId)
le_result_t le_antenna_SetShortLimit(le_antenna_ObjRef_t antennaRef, uint32_t shortLimit)
struct le_antenna_StatusEventHandler * le_antenna_StatusEventHandlerRef_t
Definition: le_antenna_common.h:84
#define LE_FULL_API
Definition: le_apiFeatures.h:40
LE_FULL_API void le_antenna_SetServerDisconnectHandler(le_antenna_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_antenna_ObjRef_t le_antenna_Request(le_antenna_Type_t antennaType)
le_antenna_StatusEventHandlerRef_t le_antenna_AddStatusEventHandler(le_antenna_ObjRef_t antennaRef, le_antenna_StatusHandlerFunc_t handlerPtr, void *contextPtr)
le_result_t le_antenna_TryConnectService(void)
void le_antenna_DisconnectService(void)
le_result_t le_antenna_SetOpenLimit(le_antenna_ObjRef_t antennaRef, uint32_t openLimit)
void(* le_antenna_StatusHandlerFunc_t)(le_antenna_ObjRef_t antennaRef, le_antenna_Status_t status, void *contextPtr)
Definition: le_antenna_common.h:94
le_antenna_Type_t
Definition: le_antenna_common.h:41
void le_antenna_ConnectService(void)
le_result_t le_antenna_GetOpenLimit(le_antenna_ObjRef_t antennaRef, uint32_t *openLimitPtr)
le_result_t le_antenna_GetType(le_antenna_ObjRef_t antennaRef, le_antenna_Type_t *antennaTypePtr)