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