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  * - LE_BAD_PARAMETER if an invalid reference provided.
346  */
347 //--------------------------------------------------------------------------------------------------
349 (
350  le_antenna_ObjRef_t antennaRef,
351  ///< [IN] antenna reference
352  le_antenna_Type_t* antennaTypePtr
353  ///< [OUT] allocated antenna type
354 );
355 
356 //--------------------------------------------------------------------------------------------------
357 /**
358  * Set the ADC value used to detect a short circuit.
359  *
360  * @return
361  * - LE_OK on success
362  * - LE_NOT_FOUND if the antenna reference is unknown
363  * - LE_FAULT on other failure
364  */
365 //--------------------------------------------------------------------------------------------------
367 (
368  le_antenna_ObjRef_t antennaRef,
369  ///< [IN] antenna reference
370  uint32_t shortLimit
371  ///< [IN] ADC value used to detect a short circuit
372 );
373 
374 //--------------------------------------------------------------------------------------------------
375 /**
376  * Get the ADC value used to detect a short circuit.
377  *
378  * @return
379  * - LE_OK on success
380  * - LE_NOT_FOUND if the antenna reference is unknown
381  * - LE_FAULT on other failure
382  */
383 //--------------------------------------------------------------------------------------------------
385 (
386  le_antenna_ObjRef_t antennaRef,
387  ///< [IN] antenna reference
388  uint32_t* shortLimitPtr
389  ///< [OUT] ADC value used to detect a short circuit
390 );
391 
392 //--------------------------------------------------------------------------------------------------
393 /**
394  * Set the ADC value used to detect an open circuit.
395  *
396  * @return
397  * - LE_OK on success
398  * - LE_NOT_FOUND if the antenna reference is unknown
399  * - LE_FAULT on other failure
400  */
401 //--------------------------------------------------------------------------------------------------
403 (
404  le_antenna_ObjRef_t antennaRef,
405  ///< [IN] antenna reference
406  uint32_t openLimit
407  ///< [IN] ADC value used to detect an open circuit
408 );
409 
410 //--------------------------------------------------------------------------------------------------
411 /**
412  * Get the ADC value used to detect an open circuit.
413  *
414  * @return
415  * - LE_OK on success
416  * - LE_NOT_FOUND if the antenna reference is unknown
417  * - LE_FAULT on other failure
418  */
419 //--------------------------------------------------------------------------------------------------
421 (
422  le_antenna_ObjRef_t antennaRef,
423  ///< [IN] antenna reference
424  uint32_t* openLimitPtr
425  ///< [OUT] ADC value used to detect an open circuit
426 );
427 
428 //--------------------------------------------------------------------------------------------------
429 /**
430  * Add handler function for EVENT 'le_antenna_StatusEvent'
431  *
432  * This event provides information on antenna status for the given antennaRef.
433  *
434  */
435 //--------------------------------------------------------------------------------------------------
437 (
438  le_antenna_ObjRef_t antennaRef,
439  ///< [IN] antenna reference
441  ///< [IN]
442  void* contextPtr
443  ///< [IN]
444 );
445 
446 //--------------------------------------------------------------------------------------------------
447 /**
448  * Remove handler function for EVENT 'le_antenna_StatusEvent'
449  */
450 //--------------------------------------------------------------------------------------------------
452 (
454  ///< [IN]
455 );
456 
457 //--------------------------------------------------------------------------------------------------
458 /**
459  * Get the antenna status.
460  *
461  * @return
462  * - LE_OK on success
463  * - LE_NOT_FOUND if the antenna reference is unknown
464  * - LE_UNSUPPORTED if the antenna detection is not supported
465  * - LE_FAULT on other failure
466  *
467  */
468 //--------------------------------------------------------------------------------------------------
470 (
471  le_antenna_ObjRef_t antennaRef,
472  ///< [IN] antenna reference
473  le_antenna_Status_t* statusPtr
474  ///< [OUT] antenna status
475 );
476 
477 //--------------------------------------------------------------------------------------------------
478 /**
479  * Set the external ADC used to monitor the requested antenna.
480  *
481  * @return
482  * - LE_OK on success
483  * - LE_NOT_FOUND if the antenna reference is unknown
484  * - LE_UNSUPPORTED request not supported
485  * - LE_FAULT on other failure
486  *
487  * @note The same external ADC may not be selected for both antennas at the same time.
488  */
489 //--------------------------------------------------------------------------------------------------
491 (
492  le_antenna_ObjRef_t antennaRef,
493  ///< [IN] antenna reference
494  int8_t adcId
495  ///< [IN] ADC index used to monitor the requested antenna
496 );
497 
498 //--------------------------------------------------------------------------------------------------
499 /**
500  * Get the external ADC used to monitor the requested antenna.
501  *
502  * @return
503  * - LE_OK on success
504  * - LE_NOT_FOUND if the antenna reference is unknown
505  * - LE_UNSUPPORTED request not supported
506  * - LE_FAULT on other failure
507  *
508  * @note If the returned ADC index is "-1", it means no external ADC are used to monitor
509  * the requested antenna.
510  */
511 //--------------------------------------------------------------------------------------------------
513 (
514  le_antenna_ObjRef_t antennaRef,
515  ///< [IN] antenna reference
516  int8_t* adcIdPtr
517  ///< [OUT] ADC index used to monitor the requested antenna
518 );
519 
520 #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
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
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_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)