From c28e2ff07057a481be7eea8519c64f5d28ac3548 Mon Sep 17 00:00:00 2001 From: Abtin Keshavarzian Date: Mon, 8 May 2017 14:45:10 -0700 Subject: [PATCH] Spinel: Define properties for discover scan operation (#1703) This commit define new spinel properties related to Thread's discover scan operation. It also updates the spinel draft documentation. --- doc/spinel-protocol-src/spinel-prop-core.md | 3 ++ doc/spinel-protocol-src/spinel-prop-mac.md | 30 ++++++++++--- doc/spinel-protocol-src/spinel-tech-thread.md | 35 +++++++++++++++ src/ncp/spinel.c | 17 +++++++- src/ncp/spinel.h | 43 +++++++++++++++++++ 5 files changed, 120 insertions(+), 8 deletions(-) diff --git a/doc/spinel-protocol-src/spinel-prop-core.md b/doc/spinel-protocol-src/spinel-prop-core.md index c588d369e..9b9bb0591 100644 --- a/doc/spinel-protocol-src/spinel-prop-core.md +++ b/doc/spinel-protocol-src/spinel-prop-core.md @@ -149,9 +149,12 @@ Currently defined values are: * 49: `CAP_ROLE_SLEEPY` * 52: `CAP_NET_THREAD_1_0` * 512: `CAP_MAC_WHITELIST` + * 513: `CAP_MAC_RAW` + * 514: `CAP_OOB_STEERING_DATA` * 1024: `CAP_THREAD_COMMISSIONER` * 1025: `CAP_THREAD_BA_PROXY` + Additionally, future capability allocations SHALL be made from the following allocation plan: diff --git a/doc/spinel-protocol-src/spinel-prop-mac.md b/doc/spinel-protocol-src/spinel-prop-mac.md index b002a4040..536f4dc13 100644 --- a/doc/spinel-protocol-src/spinel-prop-mac.md +++ b/doc/spinel-protocol-src/spinel-prop-mac.md @@ -10,15 +10,20 @@ Possible Values: * 0: `SCAN_STATE_IDLE` * 1: `SCAN_STATE_BEACON` * 2: `SCAN_STATE_ENERGY` +* 3: `SCAN_STATE_DISCOVER` Set to `SCAN_STATE_BEACON` to start an active scan. Beacons will be emitted from `PROP_MAC_SCAN_BEACON`. Set to `SCAN_STATE_ENERGY` to start an energy scan. -Channel energy will be reported by alternating emissions -of `PROP_PHY_CHAN` and `PROP_PHY_RSSI`. +Channel energy result will be reported by emissions +of `PROP_MAC_ENERGY_SCAN_RESULT` (per channel). -Values switches to `SCAN_STATE_IDLE` when scan is complete. +Set to `SCAN_STATE_DISOVER` to start a Thread MLE discovery +scan operation. Discovery scan result will be emitted from +`PROP_MAC_SCAN_BEACON`. + +Value switches to `SCAN_STATE_IDLE` when scan is complete. ### PROP 49: PROP_MAC_SCAN_MASK {#prop-mac-scan-mask} * Type: Read-Write @@ -33,11 +38,11 @@ Values switches to `SCAN_STATE_IDLE` when scan is complete. ### PROP 51: PROP_MAC_SCAN_BEACON {#prop-mac-scan-beacon} * Type: Read-Only-Stream -* Packed-Encoding: `Ccdd` (or `Cct(ESSc)t(iCUd)`) +* Packed-Encoding: `Ccdd` (or `Cct(ESSc)t(iCUdd)`) -Octets: | 1 | 1 | 2 | *n* | 2 | *n* ---------|----|------|---------|----------|---------|---------- -Fields: | CH | RSSI | MAC_LEN | MAC_DATA | NET_LEN | NET_DATA +Octets: | 1 | 1 | 2 | *n* | 2 | *n* +--------|----|------|---------|----------|---------|---------- +Fields: | CH | RSSI | MAC_LEN | MAC_DATA | NET_LEN | NET_DATA Scan beacons have two embedded structures which contain information about the MAC layer and the NET layer. Their @@ -56,6 +61,7 @@ The format below is for an 802.15.4 MAC with Thread: * `C`: Flags * `U`: Network Name * `d`: XPANID + * `d`: Steering data Extra parameters may be added to each of the structures in the future, so care should be taken to read the length @@ -106,6 +112,16 @@ Id | Name | Description See (#prop-stream-raw). +### PROP 57: MAC_ENERGY_SCAN_RESULT {#prop-mac-scan-result} +* Type: Read-Only-Stream +* Packed-Encoding: `Cc` + +This property is emitted during energy scan operation +per scanned channel with following format: + +* `C`: Channel +* `c`: RSSI (in dBm) + ### PROP 4864: PROP_MAC_WHITELIST {#prop-mac-whitelist} * Type: Read-Write * Packed-Encoding: `A(T(Ec))` diff --git a/doc/spinel-protocol-src/spinel-tech-thread.md b/doc/spinel-protocol-src/spinel-tech-thread.md index a9e13c833..456b55606 100644 --- a/doc/spinel-protocol-src/spinel-tech-thread.md +++ b/doc/spinel-protocol-src/spinel-tech-thread.md @@ -287,5 +287,40 @@ CoAP requests/responses from the NCP's RLOC address. This allows the host driver to implement a Thread border agent. +### PROP 5395: PROP_THREAD_DISOVERY_SCAN_JOINER_FLAG {#prop-thread-discovery-scan-joiner-flag} +* Type: Read-Write +* Packed-Encoding:: `b` +This property specifies the value used in Thread MLE Discovery Request +TLV during discovery scan operation. Default value is `false`. + +### PROP 5396: PROP_THREAD_DISCOVERY_SCAN_ENABLE_FILTERING {#prop-thread-discovery-scan-enable-filtering} + +* Type: Read-Write +* Packed-Encoding:: `b` + +This property is used to enable/disable EUI64 filtering during discovery +scan operation. Default value is `false`. + +### PROP 5397: SPINEL_PROP_THREAD_DISCOVERY_SCAN_PANID (#prop-thread-discovery-scan-panid) + +* Type: Read-write +* Packed-Encoding:: `S` + +This property specifies the PANID used for filtering during discovery +scan operation. Default value is `0xffff` (broadcast PANID) which disables +PANID filtering. + +### PROP 5398: SPINEL_PROP_THREAD_STEERING_DATA {#prop-thread-steering-data} + +* Type: Write-Only +* Packed-Encoding: `E` +* Required capability: `SPINEL_CAP_OOB_STEERING_DATA` + +This property can be used to set the steering data for MLE Discovery +Response messages. + +* All zeros to clear the steering data (indicating no steering data). +* All 0xFFs to set the steering data (bloom filter) to accept/allow all. +* A specific EUI64 which is then added to steering data/bloom filter. diff --git a/src/ncp/spinel.c b/src/ncp/spinel.c index d39231b70..bb1c22cd6 100644 --- a/src/ncp/spinel.c +++ b/src/ncp/spinel.c @@ -1192,6 +1192,22 @@ spinel_prop_key_to_cstr(spinel_prop_key_t prop_key) ret = "PROP_THREAD_CONTEXT_REUSE_DELAY"; break; + case SPINEL_PROP_THREAD_DISCOVERY_SCAN_JOINER_FLAG: + ret = "SPINEL_PROP_THREAD_DISCOVERY_SCAN_JOINER_FLAG"; + break; + + case SPINEL_PROP_THREAD_DISCOVERY_SCAN_ENABLE_FILTERING: + ret = "SPINEL_PROP_THREAD_DISCOVERY_SCAN_ENABLE_FILTERING"; + break; + + case SPINEL_PROP_THREAD_DISCOVERY_SCAN_PANID: + ret = "SPINEL_PROP_THREAD_DISCOVERY_SCAN_PANID"; + break; + + case SPINEL_PROP_THREAD_STEERING_DATA: + ret = "SPINEL_PROP_THREAD_STEERING_DATA"; + break; + case SPINEL_PROP_MAC_WHITELIST: ret = "PROP_MAC_WHITELIST"; break; @@ -1208,7 +1224,6 @@ spinel_prop_key_to_cstr(spinel_prop_key_t prop_key) ret = "PROP_THREAD_CHILD_TIMEOUT"; break; - case SPINEL_PROP_NET_REQUIRE_JOIN_EXISTING: ret = "PROP_NET_REQUIRE_JOIN_EXISTING"; break; diff --git a/src/ncp/spinel.h b/src/ncp/spinel.h index ec873a648..b9d4a75a2 100644 --- a/src/ncp/spinel.h +++ b/src/ncp/spinel.h @@ -178,6 +178,7 @@ typedef enum SPINEL_SCAN_STATE_IDLE = 0, SPINEL_SCAN_STATE_BEACON = 1, SPINEL_SCAN_STATE_ENERGY = 2, + SPINEL_SCAN_STATE_DISCOVER = 3, } spinel_scan_state_t; typedef enum @@ -363,6 +364,7 @@ enum SPINEL_CAP_OPENTHREAD__BEGIN = 512, SPINEL_CAP_MAC_WHITELIST = (SPINEL_CAP_OPENTHREAD__BEGIN + 0), SPINEL_CAP_MAC_RAW = (SPINEL_CAP_OPENTHREAD__BEGIN + 1), + SPINEL_CAP_OOB_STEERING_DATA = (SPINEL_CAP_OPENTHREAD__BEGIN + 2), SPINEL_CAP_OPENTHREAD__END = 640, SPINEL_CAP_THREAD__BEGIN = 1024, @@ -851,6 +853,47 @@ typedef enum */ SPINEL_PROP_THREAD_BA_PROXY_STREAM = SPINEL_PROP_THREAD_EXT__BEGIN + 18, + /// Thread "joiner" flag used during discovery scan operation + /** Format `b` + * + * This property defines the Joiner Flag value in the Discovery Request TLV. + * + * Default value is `false`. + */ + SPINEL_PROP_THREAD_DISCOVERY_SCAN_JOINER_FLAG + = SPINEL_PROP_THREAD_EXT__BEGIN + 19, + + /// Enable EUI64 filtering for discovery scan operation. + /** Format `b` + * + * Default value is `false` + */ + SPINEL_PROP_THREAD_DISCOVERY_SCAN_ENABLE_FILTERING + = SPINEL_PROP_THREAD_EXT__BEGIN + 20, + + /// PANID used for Discovery scan operation (used for PANID filtering). + /** Format: `S` + * + * Default value is 0xffff (Broadcast PAN) to disable PANID filtering + * + */ + SPINEL_PROP_THREAD_DISCOVERY_SCAN_PANID + = SPINEL_PROP_THREAD_EXT__BEGIN + 21, + + /// Thread (out of band) steering data for MLE Discovery Response. + /** Format `E` - Write only + * + * Required capability: SPINEL_CAP_OOB_STEERING_DATA. + * + * Writing to this property allows to set/update the the MLE Discovery Response steering data out of band. + * + * - All zeros to clear the steering data (indicating that there is no steering data). + * - All 0xFFs to set steering data/bloom filter to accept/allow all. + * - A specific EUI64 which is then added to current steering data/bloom filter. + * + */ + SPINEL_PROP_THREAD_STEERING_DATA = SPINEL_PROP_THREAD_EXT__BEGIN + 22, + SPINEL_PROP_THREAD_EXT__END = 0x1600, SPINEL_PROP_IPV6__BEGIN = 0x60,