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