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