Antenna Monitoring

API Reference

This file contains reference definitions for the antenna diagnostic APIs.

IPC interfaces binding

All 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

Diagnostic functionality detects antenna presence and/or defective antennas.

Antenna diagnostics are based on the following principles:

A small DC current passes through the coaxial cable to the antenna. A resistive bridge is used to provide different voltage depending on the antenna state.

Note
Only antennas with a resistor between the radiating element and ground are supported.

These are the diagnostic states:

  • open circuit: there's no antenna but RF open circuit
  • closed circuit: antenna is present
  • 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 the antenna state.

Short and Open threshold limits determine the antenna's state:

Short Threshold Limit

  • short circuit: unknown state
  • close circuit: presence of antenna

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

Open Threshold Limit

  • open circuit: no antenna

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
Be sure check the supported antenna diagnostic limit for your specific platform.

Platform Constraints Platform Constraints

Diagnostics principle

This functionality detects (or not) the presence of an antenna or a defective antenna.

Antenna diagnostics measure the current consumption for a GNSS active antenna, and provides current protection circuitry to protect the active antenna's power supply.

These are the diagnostic states:

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

Thresholds

GNSS configurable thresholds are compared to the ADC reading from the antenna diagnostic hardware design to measure the current to determine the antenna state.

These are the status values reported for a GNSS antenna:

  • 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, antenna diagnostics use an internal ADC to read the voltage from the integrated antenna diagnostic circuit, if any.

An antenna design using an external antenna diagnostic circuit can still take advantage of the antenna monitoring service. Using the function le_antenna_SetExternalAdc(), the module can monitor one of the external ADC’s to read the voltage from an external antenna diagnosis circuit, rather than the internal ADC. 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.