spinel: Updated documentation for signal jamming detection (#929)

This commit outlines new Spinel properties for implementing a
signal jamming detection feature into an NCP.

doc/spinel-protocol-src/draft-spinel-protocol.md.in

@@ -336,6 +336,8 @@ by (Miek Gieben) and [xml2rfc (version 2)](http://xml2rfc.ietf.org/).
 
 {{spinel-feature-host-buffer-offload.md}}
 
+{{spinel-feature-jam-detect.md}}
+
 {{spinel-tech-thread.md}}
 
 {{spinel-test-vectors.md}}

doc/spinel-protocol-src/spinel-feature-jam-detect.md

@@ -0,0 +1,83 @@
+# Feature: Jam Detection {#feature-jam-detect}
+
+Jamming detection is a feature that allows the NCP to report when it
+detects high levels of interference that are characteristic of intentional
+signal jamming.
+
+The presence of this feature can be detected by checking for the
+presence of the `CAP_JAM_DETECT` (value 6) capability in `PROP_CAPS`.
+
+## Properties
+
+### PROP 4608: PROP_JAM_DETECT_ENABLE {#prop-jam-detect-enable}
+
+* Type: Read-Write
+* Packed-Encoding: `b`
+* Default Value: false
+* REQUIRED for `CAP_JAM_DETECT`
+
+Octets: |       1
+--------|-----------------
+Fields: | `PROP_JAM_DETECT_ENABLE`
+
+Indicates if jamming detection is enabled or disabled. Set to true
+to enable jamming detection.
+
+This property is only available if the `CAP_JAM_DETECT`
+capability is present in `PROP_CAPS`.
+
+### PROP 4609: PROP_JAM_DETECTED {#prop-jam-detected}
+
+* Type: Read-Only
+* Packed-Encoding: `b`
+* REQUIRED for `CAP_JAM_DETECT`
+
+Octets: |       1
+--------|-----------------
+Fields: | `PROP_JAM_DETECTED`
+
+Set to true if radio jamming is detected. Set to false otherwise.
+
+When jamming detection is enabled, changes to the value of this
+property are emitted asynchronously via `CMD_PROP_VALUE_IS`.
+
+This property is only available if the `CAP_JAM_DETECT`
+capability is present in `PROP_CAPS`.
+
+### PROP 4610: PROP_JAM_DETECT_RSSI_THRESHOLD
+
+* Type: Read-Write
+* Packed-Encoding: `c`
+* Units: dBm
+* Default Value: Implementation-specific
+* RECOMMENDED for `CAP_JAM_DETECT`
+
+This parameter describes the threshold RSSI level (measured in
+dBm) above which the jamming detection will consider the
+channel blocked.
+
+### PROP 4611: PROP_JAM_DETECT_WINDOW
+
+* Type: Read-Write
+* Packed-Encoding: `c`
+* Units: Seconds (1-64)
+* Default Value: Implementation-specific
+* RECOMMENDED for `CAP_JAM_DETECT`
+
+This parameter describes the window period for signal jamming
+detection.
+
+### PROP 4612: PROP_JAM_DETECT_BUSY
+
+* Type: Read-Write
+* Packed-Encoding: `i`
+* Units: Seconds (1-64)
+* Default Value: Implementation-specific
+* RECOMMENDED for `CAP_JAM_DETECT`
+
+This parameter describes the number of aggregate seconds within
+the detection window where the RSSI must be above
+`PROP_JAM_DETECT_RSSI_THRESHOLD` to trigger detection.
+
+The behavior of the jamming detection feature when `PROP_JAM_DETECT_BUSY`
+is larger than `PROP_JAM_DETECT_WINDOW` is undefined.

doc/spinel-protocol-src/spinel-prop-core.md

@@ -127,6 +127,8 @@ Currently defined values are:
  * 2: `CAP_NET_SAVE`
  * 3: `CAP_HBO`: Host Buffer Offload. See (#feature-host-buffer-offload).
  * 4: `CAP_POWER_SAVE`
+ * 5: `CAP_COUNTERS`
+ * 6: `CAP_JAM_DETECT`: Jamming detection. See (#feature-jam-detect)
  * 16: `CAP_802_15_4_2003`
  * 17: `CAP_802_15_4_2006`
  * 18: `CAP_802_15_4_2011`