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


le_antenna_GetShortLimit
le_result_t le_antenna_GetShortLimit(le_antenna_ObjRef_t antennaRef, uint32_t *shortLimitPtr)


le_antenna_GetExternalAdc
le_result_t le_antenna_GetExternalAdc(le_antenna_ObjRef_t antennaRef, int8_t *adcIdPtr)


le_result_t
le_result_t
Definition: le_basics.h:46


le_antenna_Status_t
le_antenna_Status_t
Definition: le_antenna_common.h:60


le_antenna_GetStatus
le_result_t le_antenna_GetStatus(le_antenna_ObjRef_t antennaRef, le_antenna_Status_t *statusPtr)


le_antenna_DisconnectHandler_t
void(* le_antenna_DisconnectHandler_t)(void *)
Definition: le_antenna_interface.h:176


le_antenna_ObjRef_t
struct le_antenna_Obj * le_antenna_ObjRef_t
Definition: le_antenna_common.h:33


le_antenna_SetExternalAdc
le_result_t le_antenna_SetExternalAdc(le_antenna_ObjRef_t antennaRef, int8_t adcId)


le_antenna_common.h


le_antenna_SetShortLimit
le_result_t le_antenna_SetShortLimit(le_antenna_ObjRef_t antennaRef, uint32_t shortLimit)


le_antenna_StatusEventHandlerRef_t
struct le_antenna_StatusEventHandler * le_antenna_StatusEventHandlerRef_t
Definition: le_antenna_common.h:84


LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40


le_antenna_SetServerDisconnectHandler
LE_FULL_API void le_antenna_SetServerDisconnectHandler(le_antenna_DisconnectHandler_t disconnectHandler, void *contextPtr)


le_antenna_Request
le_antenna_ObjRef_t le_antenna_Request(le_antenna_Type_t antennaType)


le_antenna_AddStatusEventHandler
le_antenna_StatusEventHandlerRef_t le_antenna_AddStatusEventHandler(le_antenna_ObjRef_t antennaRef, le_antenna_StatusHandlerFunc_t handlerPtr, void *contextPtr)



le_antenna_TryConnectService
le_result_t le_antenna_TryConnectService(void)


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_StatusHandlerFunc_t
void(* le_antenna_StatusHandlerFunc_t)(le_antenna_ObjRef_t antennaRef, le_antenna_Status_t status, void *contextPtr)
Definition: le_antenna_common.h:94


le_antenna_Type_t
le_antenna_Type_t
Definition: le_antenna_common.h:41


le_antenna_ConnectService
void le_antenna_ConnectService(void)


le_antenna_GetOpenLimit
le_result_t le_antenna_GetOpenLimit(le_antenna_ObjRef_t antennaRef, uint32_t *openLimitPtr)


le_antenna_GetType
le_result_t le_antenna_GetType(le_antenna_ObjRef_t antennaRef, le_antenna_Type_t *antennaTypePtr)