This file contains prototype definitions for the antenna diagnosis APIs.

IPC interfaces binding

All the functions of this API are provided by the modemService.

Here's a code sample binding to modem services:

  bindings:
  {
     clientExe.clientComponent.le_antenna -> modemService.le_antenna
  }

Cellular or Diversity antenna

Diagnostics principle

This functionality allows to detect or not the presence of an antenna or to detect a defective antenna.

Antenna diagnosis is based on the following principle :

A very small D.C. current goes through the coaxial cable to the antenna. A resistive bridge is realized to provide different voltages depending on the antenna state.

It is mandatory to use a specific antenna. The antenna used have to be built with a resistor between radiating element and ground.

The states to diagnose are listed here:

Antenna in open circuit: there is no antenna but RF open circuit
Antenna in close circuit: presence of antenna
Antenna in short circuit: with or without antenna, short circuit for RF path.

Thresholds

Configurable thresholds are compared to the ADC (Analog to Digital Converter) reading from the antenna diagnostic voltage to determine in which state the RF (Radio Frequency) is.

Two thresholds are set to decide the state:

                          short limit                   open limit
  ---- short circuit ----|---- close circuit ----|---- open circuit ----
         unknown state      |   presence of antenna  |        no antenna

A short event is reported for the Cellular or Diversity antenna if the ADC value is lower than the corresponding short limit. An open event is reported for the Cellular or Diversity antenna if the ADC value is higher than the corresponding open limit.

Note: The open threshold is always HIGHER than the short threshold.

GNSS antenna

Warning: Ensure to check the supported antenna diagnosis for your specific platform.

Diagnostics principle

This functionality allows to detect or not the presence of an antenna or to detect a defective antenna.

The antenna diagnosis is based on the measurement of the current consumption for a GNSS active antenna. Moreover a current hardware protection circuitry is able to protect the power supply of that active antenna.

The states to diagnose are listed here:

Antenna in short circuit: with or without antenna, short circuit for RF path.
Antenna in open circuit: there is no antenna but RF open circuit.
Antenna in close circuit: presence of antenna.
Antenna in over current : with or without antenna, short circuit for RF path and current hardware protection circuitry has tripped.

Thresholds

Configurable thresholds are compared to the ADC (Analog to Digital Converter) reading from the antenna diagnostic hardware design measuring the current to determine in which state the antenna is.

The following status are reported for the GNSS antenna if the ADC value is:

SHORT_CIRCUIT: ADC value > short limit, but over current HW not tripped.
CLOSE_CIRCUIT: short limit >= ADC value >= open limit.
OPEN_CIRCUIT: ADC value < open limit.
OVER_CURRENT: antenna is shorted and current HW protection circuitry has tripped.

Note: The open threshold is always LOWER than the short threshold.

Antenna diagnostic ADC selection

Warning: Ensure to check the supported antenna diagnosis for your specific platform.

By default, the antenna diagnostics use an internal ADC for reading the voltage from the integrated antenna diagnosis circuit if any.

An antenna design that makes use of an external antenna diagnosis circuit can still take advantage of the antenna monitoring service. Using the function le_antenna_SetExternalAdc(), the module can be instructed to monitor one of the external ADC’s to read the voltage from an external antenna diagnosis circuit rather than the internal ADC. Moreover, the le_antenna_GetExternalAdc() function reads the external ADC used to monitor the requested antenna.

API description

le_antenna_Request() API allows the application to monitor the requested antenna.

le_antenna_GetType() API retrieves the antenna type from an antenna reference.

le_antenna_SetShortLimit() API sets the ADC value used to detect a short circuit.

le_antenna_GetShortLimit() API gets the ADC value used to detect a short circuit.

le_antenna_SetOpenLimit() API sets the ADC value used to detect an open circuit.

le_antenna_GetOpenLimit() API gets the ADC value used to detect an open circuit.

le_antenna_AddStatusEventHandler() API adds a handler to be notified when the requested antenna status changed.

le_antenna_RemoveStatusEventHandler() removes the antenna status handler.

le_antenna_GetStatus() API gets the current antenna status.

le_antenna_SetExternalAdc() API sets the external ADC used to monitor the requested antenna.

le_antenna_GetExternalAdc() API gets the external ADC used to monitor the requested antenna.

Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.