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