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  *      - LE_BAD_PARAMETER if an invalid reference provided.
  346  */
  347 //--------------------------------------------------------------------------------------------------
  348 le_result_t le_antenna_GetType
  349 (
  350     le_antenna_ObjRef_t antennaRef,
  351         ///< [IN] antenna reference
  352     le_antenna_Type_t* antennaTypePtr
  353         ///< [OUT] allocated antenna type
  354 );
  355 
  356 //--------------------------------------------------------------------------------------------------
  357 /**
  358  * Set the ADC value used to detect a short circuit.
  359  *
  360  * @return
  361  *      - LE_OK on success
  362  *      - LE_NOT_FOUND if the antenna reference is unknown
  363  *      - LE_FAULT on other failure
  364  */
  365 //--------------------------------------------------------------------------------------------------
  366 le_result_t le_antenna_SetShortLimit
  367 (
  368     le_antenna_ObjRef_t antennaRef,
  369         ///< [IN] antenna reference
  370     uint32_t shortLimit
  371         ///< [IN] ADC value used to detect a short circuit
  372 );
  373 
  374 //--------------------------------------------------------------------------------------------------
  375 /**
  376  * Get the ADC value used to detect a short circuit.
  377  *
  378  * @return
  379  *      - LE_OK on success
  380  *      - LE_NOT_FOUND if the antenna reference is unknown
  381  *      - LE_FAULT on other failure
  382  */
  383 //--------------------------------------------------------------------------------------------------
  384 le_result_t le_antenna_GetShortLimit
  385 (
  386     le_antenna_ObjRef_t antennaRef,
  387         ///< [IN] antenna reference
  388     uint32_t* shortLimitPtr
  389         ///< [OUT] ADC value used to detect a short circuit
  390 );
  391 
  392 //--------------------------------------------------------------------------------------------------
  393 /**
  394  * Set the ADC value used to detect an open circuit.
  395  *
  396  * @return
  397  *      - LE_OK on success
  398  *      - LE_NOT_FOUND if the antenna reference is unknown
  399  *      - LE_FAULT on other failure
  400  */
  401 //--------------------------------------------------------------------------------------------------
  402 le_result_t le_antenna_SetOpenLimit
  403 (
  404     le_antenna_ObjRef_t antennaRef,
  405         ///< [IN] antenna reference
  406     uint32_t openLimit
  407         ///< [IN] ADC value used to detect an open circuit
  408 );
  409 
  410 //--------------------------------------------------------------------------------------------------
  411 /**
  412  * Get the ADC value used to detect an open circuit.
  413  *
  414  * @return
  415  *      - LE_OK on success
  416  *      - LE_NOT_FOUND if the antenna reference is unknown
  417  *      - LE_FAULT on other failure
  418  */
  419 //--------------------------------------------------------------------------------------------------
  420 le_result_t le_antenna_GetOpenLimit
  421 (
  422     le_antenna_ObjRef_t antennaRef,
  423         ///< [IN] antenna reference
  424     uint32_t* openLimitPtr
  425         ///< [OUT] ADC value used to detect an open circuit
  426 );
  427 
  428 //--------------------------------------------------------------------------------------------------
  429 /**
  430  * Add handler function for EVENT 'le_antenna_StatusEvent'
  431  *
  432  * This event provides information on antenna status for the given antennaRef.
  433  *
  434  */
  435 //--------------------------------------------------------------------------------------------------
  436 le_antenna_StatusEventHandlerRef_t le_antenna_AddStatusEventHandler
  437 (
  438     le_antenna_ObjRef_t antennaRef,
  439         ///< [IN] antenna reference
  440     le_antenna_StatusHandlerFunc_t handlerPtr,
  441         ///< [IN]
  442     void* contextPtr
  443         ///< [IN]
  444 );
  445 
  446 //--------------------------------------------------------------------------------------------------
  447 /**
  448  * Remove handler function for EVENT 'le_antenna_StatusEvent'
  449  */
  450 //--------------------------------------------------------------------------------------------------
  451 void le_antenna_RemoveStatusEventHandler
  452 (
  453     le_antenna_StatusEventHandlerRef_t handlerRef
  454         ///< [IN]
  455 );
  456 
  457 //--------------------------------------------------------------------------------------------------
  458 /**
  459  * Get the antenna status.
  460  *
  461  * @return
  462  *      - LE_OK on success
  463  *      - LE_NOT_FOUND if the antenna reference is unknown
  464  *      - LE_UNSUPPORTED if the antenna detection is not supported
  465  *      - LE_FAULT on other failure
  466  *
  467  */
  468 //--------------------------------------------------------------------------------------------------
  469 le_result_t le_antenna_GetStatus
  470 (
  471     le_antenna_ObjRef_t antennaRef,
  472         ///< [IN] antenna reference
  473     le_antenna_Status_t* statusPtr
  474         ///< [OUT] antenna status
  475 );
  476 
  477 //--------------------------------------------------------------------------------------------------
  478 /**
  479  * Set the external ADC used to monitor the requested antenna.
  480  *
  481  * @return
  482  *      - LE_OK on success
  483  *      - LE_NOT_FOUND if the antenna reference is unknown
  484  *      - LE_UNSUPPORTED request not supported
  485  *      - LE_FAULT on other failure
  486  *
  487  * @note The same external ADC may not be selected for both antennas at the same time.
  488  */
  489 //--------------------------------------------------------------------------------------------------
  490 le_result_t le_antenna_SetExternalAdc
  491 (
  492     le_antenna_ObjRef_t antennaRef,
  493         ///< [IN] antenna reference
  494     int8_t adcId
  495         ///< [IN] ADC index used to monitor the requested antenna
  496 );
  497 
  498 //--------------------------------------------------------------------------------------------------
  499 /**
  500  * Get the external ADC used to monitor the requested antenna.
  501  *
  502  * @return
  503  *      - LE_OK on success
  504  *      - LE_NOT_FOUND if the antenna reference is unknown
  505  *      - LE_UNSUPPORTED request not supported
  506  *      - LE_FAULT on other failure
  507  *
  508  * @note If the returned ADC index is "-1", it means no external ADC are used to monitor
  509  * the requested antenna.
  510  */
  511 //--------------------------------------------------------------------------------------------------
  512 le_result_t le_antenna_GetExternalAdc
  513 (
  514     le_antenna_ObjRef_t antennaRef,
  515         ///< [IN] antenna reference
  516     int8_t* adcIdPtr
  517         ///< [OUT] ADC index used to monitor the requested antenna
  518 );
  519 
  520 #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_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_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_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)