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 //--------------------------------------------------------------------------------------------------
168 /**
169  * Type for handler called when a server disconnects.
170  */
171 //--------------------------------------------------------------------------------------------------
172 typedef void (*le_antenna_DisconnectHandler_t)(void *);
173 
174 //--------------------------------------------------------------------------------------------------
175 /**
176  *
177  * Connect the current client thread to the service providing this API. Block until the service is
178  * available.
179  *
180  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
181  * called before any other functions in this API. Normally, ConnectService is automatically called
182  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
183  *
184  * This function is created automatically.
185  */
186 //--------------------------------------------------------------------------------------------------
188 (
189  void
190 );
191 
192 //--------------------------------------------------------------------------------------------------
193 /**
194  *
195  * Try to connect the current client thread to the service providing this API. Return with an error
196  * if the service is not available.
197  *
198  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
199  * called before any other functions in this API. Normally, ConnectService is automatically called
200  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
201  *
202  * This function is created automatically.
203  *
204  * @return
205  * - LE_OK if the client connected successfully to the service.
206  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
207  * bound.
208  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
209  * - LE_COMM_ERROR if the Service Directory cannot be reached.
210  */
211 //--------------------------------------------------------------------------------------------------
213 (
214  void
215 );
216 
217 //--------------------------------------------------------------------------------------------------
218 /**
219  * Set handler called when server disconnection is detected.
220  *
221  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
222  * to continue without exiting, it should call longjmp() from inside the handler.
223  */
224 //--------------------------------------------------------------------------------------------------
226 (
227  le_antenna_DisconnectHandler_t disconnectHandler,
228  void *contextPtr
229 );
230 
231 //--------------------------------------------------------------------------------------------------
232 /**
233  *
234  * Disconnect the current client thread from the service providing this API.
235  *
236  * Normally, this function doesn't need to be called. After this function is called, there's no
237  * longer a connection to the service, and the functions in this API can't be used. For details, see
238  * @ref apiFilesC_client.
239  *
240  * This function is created automatically.
241  */
242 //--------------------------------------------------------------------------------------------------
244 (
245  void
246 );
247 
248 
249 //--------------------------------------------------------------------------------------------------
250 /**
251  * Reference type for an antenna diagnostic.
252  */
253 //--------------------------------------------------------------------------------------------------
254 
255 
256 //--------------------------------------------------------------------------------------------------
257 /**
258  * Antenna type.
259  */
260 //--------------------------------------------------------------------------------------------------
261 
262 
263 //--------------------------------------------------------------------------------------------------
264 /**
265  * Antenna status
266  */
267 //--------------------------------------------------------------------------------------------------
268 
269 
270 //--------------------------------------------------------------------------------------------------
271 /**
272  * Handler for antenna status.
273  *
274  */
275 //--------------------------------------------------------------------------------------------------
276 
277 
278 //--------------------------------------------------------------------------------------------------
279 /**
280  * Reference type used by Add/Remove functions for EVENT 'le_antenna_StatusEvent'
281  */
282 //--------------------------------------------------------------------------------------------------
283 
284 
285 //--------------------------------------------------------------------------------------------------
286 /**
287  * Requested the antenna monitoring.
288  *
289  * @return
290  * - Reference to the antenna object.
291  * - NULL on failure.
292  */
293 //--------------------------------------------------------------------------------------------------
294 le_antenna_ObjRef_t le_antenna_Request
295 (
296  le_antenna_Type_t antennaType
297  ///< [IN] antenna to be monitored
298 );
299 
300 //--------------------------------------------------------------------------------------------------
301 /**
302  * Get the antenna type.
303  *
304  * @return
305  * - LE_OK on success
306  * - LE_NOT_FOUND if the antenna reference is unknown
307  * - LE_BAD_PARAMETER if an invalid reference provided.
308  */
309 //--------------------------------------------------------------------------------------------------
311 (
312  le_antenna_ObjRef_t antennaRef,
313  ///< [IN] antenna reference
314  le_antenna_Type_t* antennaTypePtr
315  ///< [OUT] allocated antenna type
316 );
317 
318 //--------------------------------------------------------------------------------------------------
319 /**
320  * Set the ADC value used to detect a short circuit.
321  *
322  * @return
323  * - LE_OK on success
324  * - LE_NOT_FOUND if the antenna reference is unknown
325  * - LE_FAULT on other failure
326  */
327 //--------------------------------------------------------------------------------------------------
329 (
330  le_antenna_ObjRef_t antennaRef,
331  ///< [IN] antenna reference
332  uint32_t shortLimit
333  ///< [IN] ADC value used to detect a short circuit
334 );
335 
336 //--------------------------------------------------------------------------------------------------
337 /**
338  * Get the ADC value used to detect a short circuit.
339  *
340  * @return
341  * - LE_OK on success
342  * - LE_NOT_FOUND if the antenna reference is unknown
343  * - LE_FAULT on other failure
344  */
345 //--------------------------------------------------------------------------------------------------
347 (
348  le_antenna_ObjRef_t antennaRef,
349  ///< [IN] antenna reference
350  uint32_t* shortLimitPtr
351  ///< [OUT] ADC value used to detect a short circuit
352 );
353 
354 //--------------------------------------------------------------------------------------------------
355 /**
356  * Set the ADC value used to detect an open circuit.
357  *
358  * @return
359  * - LE_OK on success
360  * - LE_NOT_FOUND if the antenna reference is unknown
361  * - LE_FAULT on other failure
362  */
363 //--------------------------------------------------------------------------------------------------
365 (
366  le_antenna_ObjRef_t antennaRef,
367  ///< [IN] antenna reference
368  uint32_t openLimit
369  ///< [IN] ADC value used to detect an open circuit
370 );
371 
372 //--------------------------------------------------------------------------------------------------
373 /**
374  * Get the ADC value used to detect an open circuit.
375  *
376  * @return
377  * - LE_OK on success
378  * - LE_NOT_FOUND if the antenna reference is unknown
379  * - LE_FAULT on other failure
380  */
381 //--------------------------------------------------------------------------------------------------
383 (
384  le_antenna_ObjRef_t antennaRef,
385  ///< [IN] antenna reference
386  uint32_t* openLimitPtr
387  ///< [OUT] ADC value used to detect an open circuit
388 );
389 
390 //--------------------------------------------------------------------------------------------------
391 /**
392  * Add handler function for EVENT 'le_antenna_StatusEvent'
393  *
394  * This event provides information on antenna status for the given antennaRef.
395  *
396  */
397 //--------------------------------------------------------------------------------------------------
398 le_antenna_StatusEventHandlerRef_t le_antenna_AddStatusEventHandler
399 (
400  le_antenna_ObjRef_t antennaRef,
401  ///< [IN] antenna reference
402  le_antenna_StatusHandlerFunc_t handlerPtr,
403  ///< [IN]
404  void* contextPtr
405  ///< [IN]
406 );
407 
408 //--------------------------------------------------------------------------------------------------
409 /**
410  * Remove handler function for EVENT 'le_antenna_StatusEvent'
411  */
412 //--------------------------------------------------------------------------------------------------
414 (
415  le_antenna_StatusEventHandlerRef_t handlerRef
416  ///< [IN]
417 );
418 
419 //--------------------------------------------------------------------------------------------------
420 /**
421  * Get the antenna status.
422  *
423  * @return
424  * - LE_OK on success
425  * - LE_NOT_FOUND if the antenna reference is unknown
426  * - LE_UNSUPPORTED if the antenna detection is not supported
427  * - LE_FAULT on other failure
428  *
429  */
430 //--------------------------------------------------------------------------------------------------
432 (
433  le_antenna_ObjRef_t antennaRef,
434  ///< [IN] antenna reference
435  le_antenna_Status_t* statusPtr
436  ///< [OUT] antenna status
437 );
438 
439 //--------------------------------------------------------------------------------------------------
440 /**
441  * Set the external ADC used to monitor the requested antenna.
442  *
443  * @return
444  * - LE_OK on success
445  * - LE_NOT_FOUND if the antenna reference is unknown
446  * - LE_UNSUPPORTED request not supported
447  * - LE_FAULT on other failure
448  *
449  * @note The same external ADC may not be selected for both antennas at the same time.
450  */
451 //--------------------------------------------------------------------------------------------------
453 (
454  le_antenna_ObjRef_t antennaRef,
455  ///< [IN] antenna reference
456  int8_t adcId
457  ///< [IN] ADC index used to monitor the requested antenna
458 );
459 
460 //--------------------------------------------------------------------------------------------------
461 /**
462  * Get the external ADC used to monitor the requested antenna.
463  *
464  * @return
465  * - LE_OK on success
466  * - LE_NOT_FOUND if the antenna reference is unknown
467  * - LE_UNSUPPORTED request not supported
468  * - LE_FAULT on other failure
469  *
470  * @note If the returned ADC index is "-1", it means no external ADC are used to monitor
471  * the requested antenna.
472  */
473 //--------------------------------------------------------------------------------------------------
475 (
476  le_antenna_ObjRef_t antennaRef,
477  ///< [IN] antenna reference
478  int8_t* adcIdPtr
479  ///< [OUT] ADC index used to monitor the requested antenna
480 );
481 
482 #endif // LE_ANTENNA_INTERFACE_H_INCLUDE_GUARD
le_result_t le_antenna_TryConnectService(void)
le_result_t
Definition: le_basics.h:35
LE_FULL_API void le_antenna_SetServerDisconnectHandler(le_antenna_DisconnectHandler_t disconnectHandler, void *contextPtr)
void le_antenna_RemoveStatusEventHandler(le_antenna_StatusEventHandlerRef_t handlerRef)
void le_antenna_ConnectService(void)
le_result_t le_antenna_GetType(le_antenna_ObjRef_t antennaRef, le_antenna_Type_t *antennaTypePtr)
le_result_t le_antenna_GetExternalAdc(le_antenna_ObjRef_t antennaRef, int8_t *adcIdPtr)
le_result_t le_antenna_GetOpenLimit(le_antenna_ObjRef_t antennaRef, uint32_t *openLimitPtr)
le_result_t le_antenna_GetStatus(le_antenna_ObjRef_t antennaRef, le_antenna_Status_t *statusPtr)
le_antenna_ObjRef_t le_antenna_Request(le_antenna_Type_t antennaType)
le_result_t le_antenna_GetShortLimit(le_antenna_ObjRef_t antennaRef, uint32_t *shortLimitPtr)
void le_antenna_DisconnectService(void)
le_result_t le_antenna_SetOpenLimit(le_antenna_ObjRef_t antennaRef, uint32_t openLimit)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_result_t le_antenna_SetShortLimit(le_antenna_ObjRef_t antennaRef, uint32_t shortLimit)
le_result_t le_antenna_SetExternalAdc(le_antenna_ObjRef_t antennaRef, int8_t adcId)
void(* le_antenna_DisconnectHandler_t)(void *)
Definition: le_antenna_interface.h:172
le_antenna_StatusEventHandlerRef_t le_antenna_AddStatusEventHandler(le_antenna_ObjRef_t antennaRef, le_antenna_StatusHandlerFunc_t handlerPtr, void *contextPtr)