Jam Detection

View source on GitHub

To provide a configurable mechanism for signal jamming detection on any OpenThread node, enable the Jam Detection feature.

This feature is useful for device certifications that require the ability to detect signal jamming on a specific channel. It can be configured to meet the requirements of each type of certification.

How it works

Jam Detection monitors the RSSI (received signal strength indicator) of a node during specified windows of time to determine whether the channel has been jammed.

When Jam Detection is enabled:

  1. The Jam Detection State is set to false.
  2. The node samples the RSSI multiple times over each one second interval.
  3. If the RSSI over that entire one second interval remains above the configured RSSI Threshold for every sample, that one second interval is considered jammed.
  4. If an aggregate number of jammed one second intervals is more than or equal to the aggregate number of configured Busy Period seconds within the preceding configured Detection Window seconds at any point in time, the Jam Detection State at that point in time is set to true.
  5. If an aggregate number of jammed one second intervals is less than the aggregate number of configured Busy Period seconds within the preceding configured Detection Window seconds at any point in time, the Jam Detection State at that point in time is set to false.

History Bitmap

In the OpenThread API, a bitmap of the preceding 63 seconds is available for retrieval. This bitmap indicates whether the RSSI crossed the configured RSSI Threshold at each of the preceding 63 seconds.

For example, you might retrieve the following bitmap:

0xC248068C416E7FF0

Converting to binary produces every instance the RSSI went above the configured RSSI Threshold during the preceding 63 seconds:

11000010 01001000 00000110 10001100 01000001 01101110 01111111 11110000

If the Detection Window is set to 16 seconds, and the Busy Period is set to 8 seconds, the Jam Detection State becomes true at 51 seconds, as that is the first instance where the RSSI Threshold was exceeded at least 8 entire seconds in the preceding 16 seconds. In this example, the Jam Detection State remains true for the next 13 seconds.

11000010 01001000 00000110 10001100 01000001 01101110 01111111 11110000
                                      [00001 01101110 011] = 8 in 16

This bitmap might be represented by the following graph, if -45 dBm was the configured RSSI Threshold:

OT Jam Detection

How to enable

This feature is disabled by default.

By define

To enable Jam Detection, define OPENTHREAD_CONFIG_JAM_DETECTION_ENABLE as 1 in the openthread/src/core/config/openthread-core-default-config.h file, prior to building OpenThread:

#ifndef OPENTHREAD_CONFIG_JAM_DETECTION_ENABLE
#define OPENTHREAD_CONFIG_JAM_DETECTION_ENABLE 1
#endif

By option

Alternatively, use the -DOT_JAM_DETECTION=ON build option when building OpenThread:

./script/build -DOT_JAM_DETECTION=ON

Parameters

Jam Detection parameters can only be configured through the OpenThread API or the Spinel protocol. Default values are applied if the feature is enabled without subsequent configuration.

Customize this feature using the following parameters:

Parameters
RSSI Threshold
Default value
0 dBm
Description
Specifies the threshold RSSI level in dBm above which to consider the channel jammed.
Detection Window
Default value
63 seconds
Description
Specifies the window in seconds in which to check for signal jamming. Range: 1-63.
Busy Period
Default value
63 seconds
Description
Specifies the number of aggregate seconds within the Detection Window in which the RSSI must be above the RSSI Threshold to trigger Jam Detection. Must be smaller than Detection Window. Range: 1-63.

API

OpenThread

Use the Jam Detection API to manage the Jam Detection feature directly in your OpenThread application. The OpenThread API provides the following functionality:

  • Start and stop the feature
  • View the Jam Detection State
  • Manage all parameters
  • Retrieve the current Jam Detection history bitmap
  • Register a callback function for when a jam is detected

Spinel

The Spinel protocol enables a host device to communicate directly with an NCP. This protocol exposes Jam Detection properties in openthread/src/lib/spinel/spinel.h that provide the following functionality:

  • Start and stop the feature
  • View the Jam Detection State
  • Manage all parameters
  • Retrieve the current Jam Detection history bitmap

CLI

OpenThread

There are no OpenThread CLI commands related to this feature.