le_antenna_interface.h

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