Jam Detection

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:

OT Jam Detection

How to enable

This feature is disabled by default.

To enable Jam Detection, use the --enable-jam-detection configure option flag prior to building OpenThread:

./configure --enable-jam-detection
make

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 /src/ncp/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.