le_antenna_interface.h

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