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 and wpantund properties, 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:

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, the Spinel protocol, or wpanctl, the wpantund command line tool for Network Co-Processor (NCP) management. 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.

wpantund

Use the wpanctl CLI to manage the Jam Detection feature for an OpenThread NCP configuration. wpantund retains all Jam Detection configuration upon NCP reset.

wpanctl provides access to the following wpantund properties:

Properties
JamDetection:Status	Format boolean Description Read only. Jam Detection State. Indicates if a signal jam is currently detected.
JamDetection:Enable	Format boolean Description Enable or disable the Jam Detection feature.
JamDetection:RssiThreshold	Format dBm Description Specifies the threshold RSSI level in dBm above which to consider the channel blocked.
JamDetection:Window	Format seconds Description Specifies the window in seconds in which to check for signal jamming. Range: 1-63.
JamDetection:BusyPeriod	Format seconds Description Specifies the number of aggregate seconds within JamDetection:Window in which the RSSI must be above JamDetection:RssiThreshold to trigger Jam Detection. Must be smaller than JamDetection:Window. Range: 1-63.
JamDetection:Debug:HistoryBitmap	Format 64-bit value Description Provides information about the Jam Detection State history for monitoring and debugging purposes.

For example, to get the Jam Detection State for an NCP:

sudo wpanctl getprop JamDetection:Status
JamDetection:Status = false

To set the Jam Detection RSSI Threshold to -45 dBm on an NCP:

sudo wpanctl setprop JamDetection:RssiThreshold -45
sudo wpanctl getprop JamDetection:RssiThreshold
JamDetection:RssiThreshold = -45

For more information on wpantund properties, see the wpantund GitHub repository.

Note: To learn more about managing an NCP using wpantund and wpanctl, see the Build a Thread Network Codelab.