[![](https://openthread.io/static/images/icon-github.svg)View source on GitHub](https://github.com/openthread/ot-docs/tree/main/site/en/guides/build/features/jam-detection.md) 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](https://openthread.io/guides/build/features/jam-detection#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](https://openthread.io/guides/build/features/jam-detection#busy_period) seconds within the preceding configured [Detection Window](https://openthread.io/guides/build/features/jam-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](https://openthread.io/guides/build/features/jam-detection#busy_period) seconds within the preceding configured [Detection Window](https://openthread.io/guides/build/features/jam-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](https://openthread.io/guides/build/features/jam-detection#openthread), 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](https://openthread.io/guides/images/ot-jam-detection-graph.png)](https://openthread.io/guides/images/ot-jam-detection-graph_2x.png) ## 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`](https://github.com/openthread/openthread/tree/main/src/core/config/openthread-core-default-config.h) file, prior to [building OpenThread](https://openthread.io/guides/build/index.md): #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](https://openthread.io/guides/build/index.md): ./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](https://openthread.io/reference/group/api-jam-detection) 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`](https://github.com/openthread/openthread/tree/main/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.