@@ -3417,9 +3467,67 @@ STACK-NAME/STACK-VERSION[BUILD_INFO][; OTHER_INFO]; BUILD_DATE_AND_TIME
Allows for the state of various output GPIOs to be cleared without affecting other GPIO states. Contains a bit field identifying the output GPIOs that should have their state cleared to 0.
When writing, unspecified bits are assumed to be zero. The value of any bits for GPIOs which are not specified in PROP_GPIO_CONFIG MUST be ignored.
-
-
-Spinel MAY be used as an API boundary for allowing processes to configure the NCP. However, such a system MUST NOT give unprivileged processess the ability to send or receive arbitrary command frames to the NCP. Only the specific commands and properties that are required should be allowed to be passed, and then only after being checked for proper format.
+
+This feature allows the host to have access to any strong hardware random number generator that might be present on the NCP, for things like key generation or seeding PRNGs.
+Support for this feature can be determined by the presence of CAP_TRNG.
+Note well that implementing a cryptographically-strong software-based true random number generator (that is impervious to things like temperature changes, manufacturing differences across devices, or unexpected output correlations) is non-trivial without a well-designed, dedicated hardware random number generator. Implementors who have little or no experience in this area are encouraged to not advertise this capability.
+
+
+
+
+
+ - Argument-Encoding: L
+ - Type: Read-Only
+
+
+
+Fetching this property returns a strong random 32-bit integer that is suitable for use as a PRNG seed or for cryptographic use.
+While the exact mechanism behind the calculation of this value is implementation-specific, the implementation must satisfy the following requirements:
+
+
+
+ - Data representing at least 32 bits of fresh entropy (extracted from the primary entropy source) MUST be consumed by the calculation of each query.
+ - Each of the 32 bits returned MUST be free of bias and have no statistical correlation to any part of the raw data used for the calculation of any query.
+
+
+
+Support for this property is REQUIRED if CAP_TRNG is included in the device capabilities.
+
+
+
+
+ - Argument-Encoding: D
+ - Type: Read-Only
+
+
+
+Fetching this property returns 16 bytes of strong random data suitable for direct cryptographic use without further processing(For example, as an AES key).
+While the exact mechanism behind the calculation of this value is implementation-specific, the implementation must satisfy the following requirements:
+
+
+
+ - Data representing at least 128 bits of fresh entropy (extracted from the primary entropy source) MUST be consumed by the calculation of each query.
+ - Each of the 128 bits returned MUST be free of bias and have no statistical correlation to any part of the raw data used for the calculation of any query.
+
+
+
+Support for this property is REQUIRED if CAP_TRNG is included in the device capabilities.
+
+
+
+
+ - Argument-Encoding: D
+ - Type: Read-Only
+
+
+
+This property is primarily used to diagnose and debug the behavior of the entropy source used for strong random number generation.
+When queried, returns the raw output from the entropy source used to generate PROP_TRNG_32, prior to any reduction/whitening and/or mixing with prior state.
+The length of the returned buffer is implementation specific and should be expected to be non-deterministic.
+Support for this property is RECOMMENDED if CAP_TRNG is included in the device capabilities.
+
+
+Spinel MAY be used as an API boundary for allowing processes to configure the NCP. However, such a system MUST NOT give unprivileged processess the ability to send or receive arbitrary command frames to the NCP. Only the specific commands and properties that are required should be allowed to be passed, and then only after being checked for proper format.
Since this NCP protocol is defined independently of the physical transport or framing, any number of transports and framing protocols could be used successfully. However, in the interests of compatibility, this document provides some recommendations.
diff --git a/doc/draft-spinel-protocol.txt b/doc/draft-spinel-protocol.txt
index 5cc878e5b..65cb180d5 100644
--- a/doc/draft-spinel-protocol.txt
+++ b/doc/draft-spinel-protocol.txt
@@ -4,11 +4,11 @@
R. Quattlebaum
Nest Labs
- December 2, 2016
+ January 23, 2017
Spinel Host-Controller Protocol
- draft-spinel-protocol-3df876d
+ draft-spinel-protocol-d309a957-dirty
Abstract
@@ -53,9 +53,9 @@ Copyright Notice
-Quattlebaum Expires June 5, 2017 [Page 1]
+Quattlebaum Expires July 27, 2017 [Page 1]
- Spinel Protocol (3df876d) December 2016
+ Spinel Protocol (d309a957-dirty) January 2017
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
@@ -75,16 +75,16 @@ Table of Contents
1.2. Property Overview . . . . . . . . . . . . . . . . . . . . 8
1.2.1. Property Methods . . . . . . . . . . . . . . . . . . 9
1.2.2. Property Types . . . . . . . . . . . . . . . . . . . 9
- 2. Frame Format . . . . . . . . . . . . . . . . . . . . . . . . 10
+ 2. Frame Format . . . . . . . . . . . . . . . . . . . . . . . . 11
2.1. Header Format . . . . . . . . . . . . . . . . . . . . . . 11
2.1.1. FLG: Flag . . . . . . . . . . . . . . . . . . . . . . 11
2.1.2. IID: Interface Identifier . . . . . . . . . . . . . . 11
- 2.1.3. TID: Transaction Identifier . . . . . . . . . . . . . 11
+ 2.1.3. TID: Transaction Identifier . . . . . . . . . . . . . 12
2.1.4. Command Identifier (CMD) . . . . . . . . . . . . . . 12
2.1.5. Command Payload (Optional) . . . . . . . . . . . . . 12
3. Data Packing . . . . . . . . . . . . . . . . . . . . . . . . 12
3.1. Primitive Types . . . . . . . . . . . . . . . . . . . . . 13
- 3.2. Packed Unsigned Integer . . . . . . . . . . . . . . . . . 13
+ 3.2. Packed Unsigned Integer . . . . . . . . . . . . . . . . . 14
3.3. Data Blobs . . . . . . . . . . . . . . . . . . . . . . . 14
3.4. Structured Data . . . . . . . . . . . . . . . . . . . . . 15
3.5. Arrays . . . . . . . . . . . . . . . . . . . . . . . . . 16
@@ -93,14 +93,14 @@ Table of Contents
4.2. CMD 1: (Host->NCP) CMD_RESET . . . . . . . . . . . . . . 16
4.3. CMD 2: (Host->NCP) CMD_PROP_VALUE_GET . . . . . . . . . . 17
4.4. CMD 3: (Host->NCP) CMD_PROP_VALUE_SET . . . . . . . . . . 17
- 4.5. CMD 4: (Host->NCP) CMD_PROP_VALUE_INSERT . . . . . . . . 17
+ 4.5. CMD 4: (Host->NCP) CMD_PROP_VALUE_INSERT . . . . . . . . 18
4.6. CMD 5: (Host->NCP) CMD_PROP_VALUE_REMOVE . . . . . . . . 18
- 4.7. CMD 6: (NCP->Host) CMD_PROP_VALUE_IS . . . . . . . . . . 18
+ 4.7. CMD 6: (NCP->Host) CMD_PROP_VALUE_IS . . . . . . . . . . 19
4.8. CMD 7: (NCP->Host) CMD_PROP_VALUE_INSERTED . . . . . . . 19
4.9. CMD 8: (NCP->Host) CMD_PROP_VALUE_REMOVED . . . . . . . . 19
4.10. CMD 18: (Host->NCP) CMD_PEEK . . . . . . . . . . . . . . 20
4.11. CMD 19: (NCP->Host) CMD_PEEK_RET . . . . . . . . . . . . 20
- 4.12. CMD 20: (Host->NCP) CMD_POKE . . . . . . . . . . . . . . 20
+ 4.12. CMD 20: (Host->NCP) CMD_POKE . . . . . . . . . . . . . . 21
5. Properties . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.1. Property Sections . . . . . . . . . . . . . . . . . . . . 21
5.2. Core Properties . . . . . . . . . . . . . . . . . . . . . 22
@@ -109,53 +109,53 @@ Table of Contents
-Quattlebaum Expires June 5, 2017 [Page 2]
+Quattlebaum Expires July 27, 2017 [Page 2]
- Spinel Protocol (3df876d) December 2016
+ Spinel Protocol (d309a957-dirty) January 2017
5.2.3. PROP 2: PROP_NCP_VERSION . . . . . . . . . . . . . . 23
- 5.2.4. PROP 3: PROP_INTERFACE_TYPE . . . . . . . . . . . . . 23
+ 5.2.4. PROP 3: PROP_INTERFACE_TYPE . . . . . . . . . . . . . 24
5.2.5. PROP 4: PROP_INTERFACE_VENDOR_ID . . . . . . . . . . 24
5.2.6. PROP 5: PROP_CAPS . . . . . . . . . . . . . . . . . . 24
- 5.2.7. PROP 6: PROP_INTERFACE_COUNT . . . . . . . . . . . . 25
+ 5.2.7. PROP 6: PROP_INTERFACE_COUNT . . . . . . . . . . . . 26
5.2.8. PROP 7: PROP_POWER_STATE . . . . . . . . . . . . . . 26
- 5.2.9. PROP 8: PROP_HWADDR . . . . . . . . . . . . . . . . . 26
+ 5.2.9. PROP 8: PROP_HWADDR . . . . . . . . . . . . . . . . . 27
5.2.10. PROP 9: PROP_LOCK . . . . . . . . . . . . . . . . . . 27
- 5.3. Stream Properties . . . . . . . . . . . . . . . . . . . . 27
- 5.3.1. PROP 112: PROP_STREAM_DEBUG . . . . . . . . . . . . . 27
+ 5.3. Stream Properties . . . . . . . . . . . . . . . . . . . . 28
+ 5.3.1. PROP 112: PROP_STREAM_DEBUG . . . . . . . . . . . . . 28
5.3.2. PROP 113: PROP_STREAM_RAW . . . . . . . . . . . . . . 28
- 5.3.3. PROP 114: PROP_STREAM_NET . . . . . . . . . . . . . . 29
- 5.3.4. PROP 114: PROP_STREAM_NET_INSECURE . . . . . . . . . 30
+ 5.3.3. PROP 114: PROP_STREAM_NET . . . . . . . . . . . . . . 30
+ 5.3.4. PROP 114: PROP_STREAM_NET_INSECURE . . . . . . . . . 31
5.4. PHY Properties . . . . . . . . . . . . . . . . . . . . . 31
5.4.1. PROP 32: PROP_PHY_ENABLED . . . . . . . . . . . . . . 31
5.4.2. PROP 33: PROP_PHY_CHAN . . . . . . . . . . . . . . . 31
- 5.4.3. PROP 34: PROP_PHY_CHAN_SUPPORTED . . . . . . . . . . 31
- 5.4.4. PROP 35: PROP_PHY_FREQ . . . . . . . . . . . . . . . 31
- 5.4.5. PROP 36: PROP_PHY_CCA_THRESHOLD . . . . . . . . . . . 31
+ 5.4.3. PROP 34: PROP_PHY_CHAN_SUPPORTED . . . . . . . . . . 32
+ 5.4.4. PROP 35: PROP_PHY_FREQ . . . . . . . . . . . . . . . 32
+ 5.4.5. PROP 36: PROP_PHY_CCA_THRESHOLD . . . . . . . . . . . 32
5.4.6. PROP 37: PROP_PHY_TX_POWER . . . . . . . . . . . . . 32
5.4.7. PROP 38: PROP_PHY_RSSI . . . . . . . . . . . . . . . 32
- 5.5. MAC Properties . . . . . . . . . . . . . . . . . . . . . 32
- 5.5.1. PROP 48: PROP_MAC_SCAN_STATE . . . . . . . . . . . . 32
+ 5.5. MAC Properties . . . . . . . . . . . . . . . . . . . . . 33
+ 5.5.1. PROP 48: PROP_MAC_SCAN_STATE . . . . . . . . . . . . 33
5.5.2. PROP 49: PROP_MAC_SCAN_MASK . . . . . . . . . . . . . 33
5.5.3. PROP 50: PROP_MAC_SCAN_PERIOD . . . . . . . . . . . . 33
5.5.4. PROP 51: PROP_MAC_SCAN_BEACON . . . . . . . . . . . . 33
5.5.5. PROP 52: PROP_MAC_15_4_LADDR . . . . . . . . . . . . 34
5.5.6. PROP 53: PROP_MAC_15_4_SADDR . . . . . . . . . . . . 34
5.5.7. PROP 54: PROP_MAC_15_4_PANID . . . . . . . . . . . . 34
- 5.5.8. PROP 55: PROP_MAC_RAW_STREAM_ENABLED . . . . . . . . 34
- 5.5.9. PROP 56: PROP_MAC_PROMISCUOUS_MODE . . . . . . . . . 34
+ 5.5.8. PROP 55: PROP_MAC_RAW_STREAM_ENABLED . . . . . . . . 35
+ 5.5.9. PROP 56: PROP_MAC_PROMISCUOUS_MODE . . . . . . . . . 35
5.5.10. PROP 4864: PROP_MAC_WHITELIST . . . . . . . . . . . . 35
5.5.11. PROP 4865: PROP_MAC_WHITELIST_ENABLED . . . . . . . . 35
- 5.6. NET Properties . . . . . . . . . . . . . . . . . . . . . 35
- 5.6.1. PROP 64: PROP_NET_SAVED . . . . . . . . . . . . . . . 35
- 5.6.2. PROP 65: PROP_NET_IF_UP . . . . . . . . . . . . . . . 35
+ 5.6. NET Properties . . . . . . . . . . . . . . . . . . . . . 36
+ 5.6.1. PROP 64: PROP_NET_SAVED . . . . . . . . . . . . . . . 36
+ 5.6.2. PROP 65: PROP_NET_IF_UP . . . . . . . . . . . . . . . 36
5.6.3. PROP 66: PROP_NET_STACK_UP . . . . . . . . . . . . . 36
5.6.4. PROP 67: PROP_NET_ROLE . . . . . . . . . . . . . . . 36
5.6.5. PROP 68: PROP_NET_NETWORK_NAME . . . . . . . . . . . 36
- 5.6.6. PROP 69: PROP_NET_XPANID . . . . . . . . . . . . . . 36
- 5.6.7. PROP 70: PROP_NET_MASTER_KEY . . . . . . . . . . . . 36
- 5.6.8. PROP 71: PROP_NET_KEY_SEQUENCE_COUNTER . . . . . . . 36
+ 5.6.6. PROP 69: PROP_NET_XPANID . . . . . . . . . . . . . . 37
+ 5.6.7. PROP 70: PROP_NET_MASTER_KEY . . . . . . . . . . . . 37
+ 5.6.8. PROP 71: PROP_NET_KEY_SEQUENCE_COUNTER . . . . . . . 37
5.6.9. PROP 72: PROP_NET_PARTITION_ID . . . . . . . . . . . 37
5.6.10. PROP 73: PROP_NET_KEY_SWITCH_GUARDTIME . . . . . . . 37
5.7. IPv6 Properties . . . . . . . . . . . . . . . . . . . . . 37
@@ -165,128 +165,136 @@ Quattlebaum Expires June 5, 2017 [Page 2]
-Quattlebaum Expires June 5, 2017 [Page 3]
+Quattlebaum Expires July 27, 2017 [Page 3]
- Spinel Protocol (3df876d) December 2016
+ Spinel Protocol (d309a957-dirty) January 2017
- 5.7.4. PROP 99: PROP_IPV6_ADDRESS_TABLE . . . . . . . . . . 37
+ 5.7.4. PROP 99: PROP_IPV6_ADDRESS_TABLE . . . . . . . . . . 38
5.7.5. PROP 101: PROP_IPv6_ICMP_PING_OFFLOAD . . . . . . . . 38
6. Status Codes . . . . . . . . . . . . . . . . . . . . . . . . 38
- 7. Technology: Thread . . . . . . . . . . . . . . . . . . . . . 39
+ 7. Technology: Thread . . . . . . . . . . . . . . . . . . . . . 40
7.1. Thread Capabilities . . . . . . . . . . . . . . . . . . . 40
7.2. Thread Properties . . . . . . . . . . . . . . . . . . . . 40
7.2.1. PROP 80: PROP_THREAD_LEADER_ADDR . . . . . . . . . . 40
7.2.2. PROP 81: PROP_THREAD_PARENT . . . . . . . . . . . . . 40
- 7.2.3. PROP 82: PROP_THREAD_CHILD_TABLE . . . . . . . . . . 40
- 7.2.4. PROP 83: PROP_THREAD_LEADER_RID . . . . . . . . . . . 40
+ 7.2.3. PROP 82: PROP_THREAD_CHILD_TABLE . . . . . . . . . . 41
+ 7.2.4. PROP 83: PROP_THREAD_LEADER_RID . . . . . . . . . . . 41
7.2.5. PROP 84: PROP_THREAD_LEADER_WEIGHT . . . . . . . . . 41
7.2.6. PROP 85: PROP_THREAD_LOCAL_LEADER_WEIGHT . . . . . . 41
7.2.7. PROP 86: PROP_THREAD_NETWORK_DATA . . . . . . . . . . 41
7.2.8. PROP 87: PROP_THREAD_NETWORK_DATA_VERSION . . . . . . 41
7.2.9. PROP 88: PROP_THREAD_STABLE_NETWORK_DATA . . . . . . 41
- 7.2.10. PROP 89: PROP_THREAD_STABLE_NETWORK_DATA_VERSION . . 41
- 7.2.11. PROP 90: PROP_THREAD_ON_MESH_NETS . . . . . . . . . . 41
+ 7.2.10. PROP 89: PROP_THREAD_STABLE_NETWORK_DATA_VERSION . . 42
+ 7.2.11. PROP 90: PROP_THREAD_ON_MESH_NETS . . . . . . . . . . 42
7.2.12. PROP 91: PROP_THREAD_LOCAL_ROUTES . . . . . . . . . . 42
7.2.13. PROP 92: PROP_THREAD_ASSISTING_PORTS . . . . . . . . 42
7.2.14. PROP 93: PROP_THREAD_ALLOW_LOCAL_NET_DATA_CHANGE . . 42
- 7.2.15. PROP 94: PROP_THREAD_MODE . . . . . . . . . . . . . . 42
- 7.2.16. PROP 5376: PROP_THREAD_CHILD_TIMEOUT . . . . . . . . 42
- 7.2.17. PROP 5377: PROP_THREAD_RLOC16 . . . . . . . . . . . . 42
+ 7.2.15. PROP 94: PROP_THREAD_MODE . . . . . . . . . . . . . . 43
+ 7.2.16. PROP 5376: PROP_THREAD_CHILD_TIMEOUT . . . . . . . . 43
+ 7.2.17. PROP 5377: PROP_THREAD_RLOC16 . . . . . . . . . . . . 43
7.2.18. PROP 5378: PROP_THREAD_ROUTER_UPGRADE_THRESHOLD . . . 43
7.2.19. PROP 5379: PROP_THREAD_CONTEXT_REUSE_DELAY . . . . . 43
7.2.20. PROP 5380: PROP_THREAD_NETWORK_ID_TIMEOUT . . . . . . 43
7.2.21. PROP 5381: PROP_THREAD_ACTIVE_ROUTER_IDS . . . . . . 43
- 7.2.22. PROP 5382: PROP_THREAD_RLOC16_DEBUG_PASSTHRU . . . . 43
- 7.2.23. PROP 5383: SPINEL_PROP_THREAD_ROUTER_ROLE_ENABLED . . 43
+ 7.2.22. PROP 5382: PROP_THREAD_RLOC16_DEBUG_PASSTHRU . . . . 44
+ 7.2.23. PROP 5383: PROP_THREAD_ROUTER_ROLE_ENABLED . . . . . 44
7.2.24. PROP 5384: PROP_THREAD_ROUTER_DOWNGRADE_THRESHOLD . . 44
7.2.25. PROP 5385: PROP_THREAD_ROUTER_SELECTION_JITTER . . . 44
7.2.26. PROP 5386: PROP_THREAD_PREFERRED_ROUTER_ID . . . . . 44
- 7.2.27. PROP 5387: SPINEL_PROP_THREAD_NEIGHBOR_TABLE . . . . 44
- 8. Feature: Network Save . . . . . . . . . . . . . . . . . . . . 44
- 8.1. Commands . . . . . . . . . . . . . . . . . . . . . . . . 45
- 8.1.1. CMD 9: (Host->NCP) CMD_NET_SAVE . . . . . . . . . . . 45
- 8.1.2. CMD 10: (Host->NCP) CMD_NET_CLEAR . . . . . . . . . . 45
- 8.1.3. CMD 11: (Host->NCP) CMD_NET_RECALL . . . . . . . . . 46
- 9. Feature: Host Buffer Offload . . . . . . . . . . . . . . . . 46
- 9.1. Commands . . . . . . . . . . . . . . . . . . . . . . . . 46
- 9.1.1. CMD 12: (NCP->Host) CMD_HBO_OFFLOAD . . . . . . . . . 46
- 9.1.2. CMD 13: (NCP->Host) CMD_HBO_RECLAIM . . . . . . . . . 47
- 9.1.3. CMD 14: (NCP->Host) CMD_HBO_DROP . . . . . . . . . . 47
- 9.1.4. CMD 15: (Host->NCP) CMD_HBO_OFFLOADED . . . . . . . . 47
- 9.1.5. CMD 16: (Host->NCP) CMD_HBO_RECLAIMED . . . . . . . . 47
- 9.1.6. CMD 17: (Host->NCP) CMD_HBO_DROPPED . . . . . . . . . 47
- 9.2. Properties . . . . . . . . . . . . . . . . . . . . . . . 47
- 9.2.1. PROP 10: PROP_HBO_MEM_MAX . . . . . . . . . . . . . . 47
+ 7.2.27. PROP 5387: PROP_THREAD_NEIGHBOR_TABLE . . . . . . . . 44
+ 7.2.28. PROP 5388: PROP_THREAD_CHILD_COUNT_MAX . . . . . . . 45
+ 7.2.29. PROP 5389: PROP_THREAD_LEADER_NETWORK_DATA . . . . . 45
+ 7.2.30. PROP 5390: PROP_THREAD_STABLE_LEADER_NETWORK_DATA . . 45
+ 8. Feature: Network Save . . . . . . . . . . . . . . . . . . . . 45
+ 8.1. Commands . . . . . . . . . . . . . . . . . . . . . . . . 46
+ 8.1.1. CMD 9: (Host->NCP) CMD_NET_SAVE . . . . . . . . . . . 46
+ 8.1.2. CMD 10: (Host->NCP) CMD_NET_CLEAR . . . . . . . . . . 46
+ 8.1.3. CMD 11: (Host->NCP) CMD_NET_RECALL . . . . . . . . . 47
+ 9. Feature: Host Buffer Offload . . . . . . . . . . . . . . . . 47
+ 9.1. Commands . . . . . . . . . . . . . . . . . . . . . . . . 47
+ 9.1.1. CMD 12: (NCP->Host) CMD_HBO_OFFLOAD . . . . . . . . . 47
+ 9.1.2. CMD 13: (NCP->Host) CMD_HBO_RECLAIM . . . . . . . . . 48
+ 9.1.3. CMD 14: (NCP->Host) CMD_HBO_DROP . . . . . . . . . . 48
+ 9.1.4. CMD 15: (Host->NCP) CMD_HBO_OFFLOADED . . . . . . . . 48
+ 9.1.5. CMD 16: (Host->NCP) CMD_HBO_RECLAIMED . . . . . . . . 48
-Quattlebaum Expires June 5, 2017 [Page 4]
+Quattlebaum Expires July 27, 2017 [Page 4]
- Spinel Protocol (3df876d) December 2016
+ Spinel Protocol (d309a957-dirty) January 2017
- 9.2.2. PROP 11: PROP_HBO_BLOCK_MAX . . . . . . . . . . . . . 48
- 10. Feature: Jam Detection . . . . . . . . . . . . . . . . . . . 48
- 10.1. Properties . . . . . . . . . . . . . . . . . . . . . . . 48
- 10.1.1. PROP 4608: PROP_JAM_DETECT_ENABLE . . . . . . . . . 48
- 10.1.2. PROP 4609: PROP_JAM_DETECTED . . . . . . . . . . . . 49
- 10.1.3. PROP 4610: PROP_JAM_DETECT_RSSI_THRESHOLD . . . . . 49
- 10.1.4. PROP 4611: PROP_JAM_DETECT_WINDOW . . . . . . . . . 49
- 10.1.5. PROP 4612: PROP_JAM_DETECT_BUSY . . . . . . . . . . 50
- 10.1.6. PROP 4613: SPINEL_PROP_JAM_DETECT_HISTORY_BITMAP . . 50
- 11. Feature: GPIO Access . . . . . . . . . . . . . . . . . . . . 50
- 11.1. Properties . . . . . . . . . . . . . . . . . . . . . . . 51
- 11.1.1. PROP 4096: PROP_GPIO_CONFIG . . . . . . . . . . . . 51
- 11.1.2. PROP 4098: PROP_GPIO_STATE . . . . . . . . . . . . . 52
- 11.1.3. PROP 4099: PROP_GPIO_STATE_SET . . . . . . . . . . . 52
- 11.1.4. PROP 4100: PROP_GPIO_STATE_CLEAR . . . . . . . . . . 53
- 12. Security Considerations . . . . . . . . . . . . . . . . . . . 53
- 12.1. Raw Application Access . . . . . . . . . . . . . . . . . 53
- 13.1. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 53
- Appendix A. Framing Protocol . . . . . . . . . . . . . . . . . . 53
- A.1. UART Recommendations . . . . . . . . . . . . . . . . . . 54
- A.1.1. UART Bit Rate Detection . . . . . . . . . . . . . . . 54
- A.1.2. HDLC-Lite . . . . . . . . . . . . . . . . . . . . . . 55
- A.2. SPI Recommendations . . . . . . . . . . . . . . . . . . . 56
- A.2.1. SPI Framing Protocol . . . . . . . . . . . . . . . . 56
- A.3. I^2C Recommendations . . . . . . . . . . . . . . . . . . 58
- A.4. Native USB Recommendations . . . . . . . . . . . . . . . 58
- Appendix B. Test Vectors . . . . . . . . . . . . . . . . . . . . 58
- B.1. Test Vector: Packed Unsigned Integer . . . . . . . . . . 58
- B.2. Test Vector: Reset Command . . . . . . . . . . . . . . . 59
- B.3. Test Vector: Reset Notification . . . . . . . . . . . . . 59
- B.4. Test Vector: Scan Beacon . . . . . . . . . . . . . . . . 59
- B.5. Test Vector: Inbound IPv6 Packet . . . . . . . . . . . . 60
- B.6. Test Vector: Outbound IPv6 Packet . . . . . . . . . . . . 60
- B.7. Test Vector: Fetch list of on-mesh networks . . . . . . . 60
- B.8. Test Vector: Returned list of on-mesh networks . . . . . 60
- B.9. Test Vector: Adding an on-mesh network . . . . . . . . . 61
- B.10. Test Vector: Insertion notification of an on-mesh network 61
- B.11. Test Vector: Removing a local on-mesh network . . . . . . 62
- B.12. Test Vector: Removal notification of an on-mesh network . 62
- Appendix C. Example Sessions . . . . . . . . . . . . . . . . . . 62
- C.1. NCP Initialization . . . . . . . . . . . . . . . . . . . 62
- C.2. Attaching to a network . . . . . . . . . . . . . . . . . 63
- C.3. Successfully joining a pre-existing network . . . . . . . 64
- C.4. Unsuccessfully joining a pre-existing network . . . . . . 64
- C.5. Detaching from a network . . . . . . . . . . . . . . . . 65
- C.6. Attaching to a saved network . . . . . . . . . . . . . . 65
- C.7. NCP Software Reset . . . . . . . . . . . . . . . . . . . 65
- C.8. Adding an on-mesh prefix . . . . . . . . . . . . . . . . 65
+ 9.1.6. CMD 17: (Host->NCP) CMD_HBO_DROPPED . . . . . . . . . 48
+ 9.2. Properties . . . . . . . . . . . . . . . . . . . . . . . 48
+ 9.2.1. PROP 10: PROP_HBO_MEM_MAX . . . . . . . . . . . . . . 48
+ 9.2.2. PROP 11: PROP_HBO_BLOCK_MAX . . . . . . . . . . . . . 49
+ 10. Feature: Jam Detection . . . . . . . . . . . . . . . . . . . 49
+ 10.1. Properties . . . . . . . . . . . . . . . . . . . . . . . 49
+ 10.1.1. PROP 4608: PROP_JAM_DETECT_ENABLE . . . . . . . . . 49
+ 10.1.2. PROP 4609: PROP_JAM_DETECTED . . . . . . . . . . . . 50
+ 10.1.3. PROP 4610: PROP_JAM_DETECT_RSSI_THRESHOLD . . . . . 50
+ 10.1.4. PROP 4611: PROP_JAM_DETECT_WINDOW . . . . . . . . . 50
+ 10.1.5. PROP 4612: PROP_JAM_DETECT_BUSY . . . . . . . . . . 51
+ 10.1.6. PROP 4613: SPINEL_PROP_JAM_DETECT_HISTORY_BITMAP . . 51
+ 11. Feature: GPIO Access . . . . . . . . . . . . . . . . . . . . 51
+ 11.1. Properties . . . . . . . . . . . . . . . . . . . . . . . 52
+ 11.1.1. PROP 4096: PROP_GPIO_CONFIG . . . . . . . . . . . . 52
+ 11.1.2. PROP 4098: PROP_GPIO_STATE . . . . . . . . . . . . . 53
+ 11.1.3. PROP 4099: PROP_GPIO_STATE_SET . . . . . . . . . . . 53
+ 11.1.4. PROP 4100: PROP_GPIO_STATE_CLEAR . . . . . . . . . . 54
+ 12. Feature: True Random Number Generation . . . . . . . . . . . 54
+ 12.1. Properties . . . . . . . . . . . . . . . . . . . . . . . 54
+ 12.1.1. PROP 4101: PROP_TRNG_32 . . . . . . . . . . . . . . 54
+ 12.1.2. PROP 4102: PROP_TRNG_128 . . . . . . . . . . . . . . 55
+ 12.1.3. PROP 4103: PROP_TRNG_RAW_32 . . . . . . . . . . . . 55
+ 13. Security Considerations . . . . . . . . . . . . . . . . . . . 56
+ 13.1. Raw Application Access . . . . . . . . . . . . . . . . . 56
+ 14.1. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 56
+ Appendix A. Framing Protocol . . . . . . . . . . . . . . . . . . 56
+ A.1. UART Recommendations . . . . . . . . . . . . . . . . . . 56
+ A.1.1. UART Bit Rate Detection . . . . . . . . . . . . . . . 57
+ A.1.2. HDLC-Lite . . . . . . . . . . . . . . . . . . . . . . 57
+ A.2. SPI Recommendations . . . . . . . . . . . . . . . . . . . 58
+ A.2.1. SPI Framing Protocol . . . . . . . . . . . . . . . . 59
+ A.3. I^2C Recommendations . . . . . . . . . . . . . . . . . . 61
+ A.4. Native USB Recommendations . . . . . . . . . . . . . . . 61
+ Appendix B. Test Vectors . . . . . . . . . . . . . . . . . . . . 61
+ B.1. Test Vector: Packed Unsigned Integer . . . . . . . . . . 61
+ B.2. Test Vector: Reset Command . . . . . . . . . . . . . . . 61
+ B.3. Test Vector: Reset Notification . . . . . . . . . . . . . 62
+ B.4. Test Vector: Scan Beacon . . . . . . . . . . . . . . . . 62
+ B.5. Test Vector: Inbound IPv6 Packet . . . . . . . . . . . . 62
+ B.6. Test Vector: Outbound IPv6 Packet . . . . . . . . . . . . 63
+ B.7. Test Vector: Fetch list of on-mesh networks . . . . . . . 63
+ B.8. Test Vector: Returned list of on-mesh networks . . . . . 63
+ B.9. Test Vector: Adding an on-mesh network . . . . . . . . . 63
+ B.10. Test Vector: Insertion notification of an on-mesh network 64
+ B.11. Test Vector: Removing a local on-mesh network . . . . . . 64
+ B.12. Test Vector: Removal notification of an on-mesh network . 65
+ Appendix C. Example Sessions . . . . . . . . . . . . . . . . . . 65
-Quattlebaum Expires June 5, 2017 [Page 5]
+Quattlebaum Expires July 27, 2017 [Page 5]
- Spinel Protocol (3df876d) December 2016
+ Spinel Protocol (d309a957-dirty) January 2017
- C.9. Entering low-power modes . . . . . . . . . . . . . . . . 66
- C.10. Sniffing raw packets . . . . . . . . . . . . . . . . . . 66
- Appendix D. Acknowledgments . . . . . . . . . . . . . . . . . . 67
- Appendix E. Glossary . . . . . . . . . . . . . . . . . . . . . . 67
- Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 68
+ C.1. NCP Initialization . . . . . . . . . . . . . . . . . . . 65
+ C.2. Attaching to a network . . . . . . . . . . . . . . . . . 66
+ C.3. Successfully joining a pre-existing network . . . . . . . 66
+ C.4. Unsuccessfully joining a pre-existing network . . . . . . 67
+ C.5. Detaching from a network . . . . . . . . . . . . . . . . 67
+ C.6. Attaching to a saved network . . . . . . . . . . . . . . 68
+ C.7. NCP Software Reset . . . . . . . . . . . . . . . . . . . 68
+ C.8. Adding an on-mesh prefix . . . . . . . . . . . . . . . . 68
+ C.9. Entering low-power modes . . . . . . . . . . . . . . . . 68
+ C.10. Sniffing raw packets . . . . . . . . . . . . . . . . . . 68
+ Appendix D. Acknowledgments . . . . . . . . . . . . . . . . . . 69
+ Appendix E. Glossary . . . . . . . . . . . . . . . . . . . . . . 70
+ Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 71
1. Introduction
@@ -322,6 +330,14 @@ Quattlebaum Expires June 5, 2017 [Page 5]
implementing Spinel in your own products you should expect there to
be at least one large renumbering event and major version number
change before the standard is considered "baked". All changes will
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 6]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
be clearly marked and documented to make such a transition as easy as
possible.
@@ -329,15 +345,6 @@ Quattlebaum Expires June 5, 2017 [Page 5]
the host and the NCP, the following commands and properties are
already considered to be "baked" and will not change:
-
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 6]
-
- Spinel Protocol (3df876d) December 2016
-
-
o Command IDs zero through eight. (Reset, No-op, and Property-Value
Commands)
o Property IDs zero through two. (Last status, Protocol Version,
@@ -379,21 +386,20 @@ Quattlebaum Expires June 5, 2017 [Page 6]
be implemented by the daemon to control which notification packets
need to be directed where.
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 7]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
In the event of transaction ID collisions, the daemon would
transparently renumber spinel frames so as to not cause TID
collisions.
Since there can be more than one application that is using the API at
a time, the "PROP_LOCK" property (Section 5.2.10) would be used to
-
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 7]
-
- Spinel Protocol (3df876d) December 2016
-
-
ensure exclusive access to the NCP by an application. Only one
process would be allowed to enable the lock at a time.
@@ -437,19 +443,19 @@ Quattlebaum Expires June 5, 2017 [Page 7]
incompatible. By using properties, you simply change an additional
property.
+
+
+Quattlebaum Expires July 27, 2017 [Page 8]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
Almost all features and capabilities are implemented using
properties. Most new features that are initially proposed as
commands can be adapted to be property-based instead. Notable
exceptions include "Host Buffer Offload" (Section 9) and "Network
Save" (Section 8).
-
-
-Quattlebaum Expires June 5, 2017 [Page 8]
-
- Spinel Protocol (3df876d) December 2016
-
-
In Spinel, properties are keyed by an unsigned integer between 0 and
2,097,151 (See Section 3.2).
@@ -490,6 +496,16 @@ Quattlebaum Expires June 5, 2017 [Page 8]
The valid operations on these sorts of properties are "GET" and
"SET".
+
+
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 9]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
1.2.2.2. Multiple-Value Properties
Multiple-Value Properties have more than one value associated with
@@ -499,13 +515,6 @@ Quattlebaum Expires June 5, 2017 [Page 8]
o List of IPv6 addresses assigned to the interface.
o List of capabilities supported by the NCP.
-
-
-Quattlebaum Expires June 5, 2017 [Page 9]
-
- Spinel Protocol (3df876d) December 2016
-
-
The valid operations on these sorts of properties are "VALUE_GET",
"VALUE_SET", "VALUE_INSERT", and "VALUE_REMOVE".
@@ -546,6 +555,13 @@ Quattlebaum Expires June 5, 2017 [Page 9]
These types of properties generally do not support "VALUE_GET", as it
is meaningless.
+
+
+Quattlebaum Expires July 27, 2017 [Page 10]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
2. Frame Format
A frame is defined simply as the concatenation of
@@ -554,14 +570,6 @@ Quattlebaum Expires June 5, 2017 [Page 9]
o A command (up to three bytes, see Section 3.2 for format)
o An optional command payload
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 10]
-
- Spinel Protocol (3df876d) December 2016
-
-
+---------+--------+-----+-------------+
| Octets: | 1 | 1-3 | n |
+---------+--------+-----+-------------+
@@ -598,6 +606,18 @@ Quattlebaum Expires June 5, 2017 [Page 10]
The first subinterface (0) is considered the primary subinterface and
MUST be supported. Support for all other subinterfaces is OPTIONAL.
+
+
+
+
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 11]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
2.1.3. TID: Transaction Identifier
The least significant bits of the header represent the Transaction
@@ -609,15 +629,6 @@ Quattlebaum Expires June 5, 2017 [Page 10]
receives a frame that matches the TID of the command it sent, it can
easily recognize that frame as the actual response to that command.
-
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 11]
-
- Spinel Protocol (3df876d) December 2016
-
-
The TID value of zero (0) is used for commands to which a correlated
response is not expected or needed, such as for unsolicited update
commands sent to the host from the NCP.
@@ -655,6 +666,14 @@ Quattlebaum Expires June 5, 2017 [Page 11]
Goals:
o Be lightweight and favor direct representation of values.
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 12]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
o Use an easily readable and memorable format string.
o Support lists and structures.
o Allow properties to be appended to structures while maintaining
@@ -665,15 +684,6 @@ Quattlebaum Expires June 5, 2017 [Page 11]
example:
o "C": A single unsigned byte.
-
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 12]
-
- Spinel Protocol (3df876d) December 2016
-
-
o "C6U": A single unsigned byte, followed by a 128-bit IPv6 address,
followed by a zero-terminated UTF8 string.
o "A(6)": An array of IPv6 addresses
@@ -713,6 +723,13 @@ Quattlebaum Expires June 5, 2017 [Page 12]
All multi-byte values are little-endian unless explicitly stated
otherwise.
+
+
+Quattlebaum Expires July 27, 2017 [Page 13]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
3.2. Packed Unsigned Integer
For certain types of integers, such command or property identifiers,
@@ -721,15 +738,6 @@ Quattlebaum Expires June 5, 2017 [Page 12]
need to add an extra byte. Doing this would add an extra byte to the
vast majority of instances, which can add up in terms of bandwidth.
-
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 13]
-
- Spinel Protocol (3df876d) December 2016
-
-
The packed unsigned integer format is based on the unsigned integer
format in EXI [3], except that we limit the maximum value to the
largest value that can be encoded into three bytes(2,097,151).
@@ -770,6 +778,14 @@ Quattlebaum Expires June 5, 2017 [Page 13]
size of the buffer, and the length of the data is simply the rest of
the size of the buffer.
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 14]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
For example, let's say we have a buffer that is encoded with the
datatype signature of "CLLD". In this case, it is pretty easy to
tell where the start and end of the data blob is: the start is 9
@@ -777,15 +793,6 @@ Quattlebaum Expires June 5, 2017 [Page 13]
the buffer minus 9. (9 is the number of bytes taken up by a byte and
two longs)
-
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 14]
-
- Spinel Protocol (3df876d) December 2016
-
-
However, things are a little different with "CLDL". Since our data
blob is no longer the last item in the signature, the length must be
prepended.
@@ -826,6 +833,15 @@ Quattlebaum Expires June 5, 2017 [Page 14]
type (like flags), we break our backward compatibility if we add
another member and use "A(6cC)". To allow for data to be added
without breaking backward compatibility, we use the structured data
+
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 15]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
type from the start: "A(T(6c))". Then when we add a new member to
the structure ("A(T(6cC))"), we don't break backward compatibility.
@@ -835,13 +851,6 @@ Quattlebaum Expires June 5, 2017 [Page 14]
When a length is prepended, the length is encoded as a little-endian
unsigned 16-bit integer.
-
-
-Quattlebaum Expires June 5, 2017 [Page 15]
-
- Spinel Protocol (3df876d) December 2016
-
-
3.5. Arrays
An array is simply a concatenated set of _n_ data encodings. For
@@ -882,6 +891,13 @@ Quattlebaum Expires June 5, 2017 [Page 15]
| Fields: | HEADER | CMD_RESET |
+---------+--------+-----------+
+
+
+Quattlebaum Expires July 27, 2017 [Page 16]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
Reset NCP command. Causes the NCP to perform a software reset. Due
to the nature of this command, the TID is ignored. The host should
instead wait for a "CMD_PROP_VALUE_IS" command from the NCP
@@ -891,13 +907,6 @@ Quattlebaum Expires June 5, 2017 [Page 15]
The command payload for this command SHOULD be empty. The receiver
MUST ignore any non-empty command payload.
-
-
-Quattlebaum Expires June 5, 2017 [Page 16]
-
- Spinel Protocol (3df876d) December 2016
-
-
If an error occurs, the value of "PROP_LAST_STATUS" will be emitted
instead with the value set to the generated status code for the
error.
@@ -936,6 +945,15 @@ Quattlebaum Expires June 5, 2017 [Page 16]
by the property value. The exact format of the property value is
defined by the property.
+
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 17]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
If an error occurs, the value of "PROP_LAST_STATUS" will be emitted
with the value set to the generated status code for the error.
@@ -947,13 +965,6 @@ Quattlebaum Expires June 5, 2017 [Page 16]
| Fields: | HEADER | CMD_PROP_VALUE_INSERT | PROP_ID | VALUE |
+---------+--------+-----------------------+---------+-------+
-
-
-Quattlebaum Expires June 5, 2017 [Page 17]
-
- Spinel Protocol (3df876d) December 2016
-
-
Insert value into property command. Instructs the NCP to insert the
given value into a list-oriented property, without removing other
items in the list. The resulting order of items in the list is
@@ -990,6 +1001,15 @@ Quattlebaum Expires June 5, 2017 [Page 17]
If an error occurs, the value of "PROP_LAST_STATUS" will be emitted
with the value set to the generated status code for the error.
+
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 18]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
4.7. CMD 6: (NCP->Host) CMD_PROP_VALUE_IS
+---------+--------+-------------------+---------+-------+
@@ -1003,13 +1023,6 @@ Quattlebaum Expires June 5, 2017 [Page 17]
sent by the NCP in an unsolicited fashion to notify the host of
various state changes asynchronously.
-
-
-Quattlebaum Expires June 5, 2017 [Page 18]
-
- Spinel Protocol (3df876d) December 2016
-
-
The payload for this command is the property identifier encoded in
the packed unsigned integer format described in Section 3.2, followed
by the current value of the given property.
@@ -1044,6 +1057,15 @@ Quattlebaum Expires June 5, 2017 [Page 18]
Property value removal notification command. This command can be
sent by the NCP in response to the "CMD_PROP_VALUE_REMOVE" command,
+
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 19]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
or it can be sent by the NCP in an unsolicited fashion to notify the
host of various state changes asynchronously.
@@ -1056,16 +1078,6 @@ Quattlebaum Expires June 5, 2017 [Page 18]
The resulting order of items in the list is defined by the given
property.
-
-
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 19]
-
- Spinel Protocol (3df876d) December 2016
-
-
4.10. CMD 18: (Host->NCP) CMD_PEEK
+---------+--------+----------+---------+-------+
@@ -1085,7 +1097,7 @@ Quattlebaum Expires June 5, 2017 [Page 19]
The NCP MAY prevent certain regions of memory from being accessed.
The implementation of this command has security implications. See
- Section 12 for more information.
+ Section 13 for more information.
This command requires the capability "CAP_PEEK_POKE" to be present.
@@ -1102,6 +1114,14 @@ Quattlebaum Expires June 5, 2017 [Page 19]
This command requires the capability "CAP_PEEK_POKE" to be present.
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 20]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
4.12. CMD 20: (Host->NCP) CMD_POKE
+---------+--------+----------+---------+-------+-------+
@@ -1113,20 +1133,11 @@ Quattlebaum Expires June 5, 2017 [Page 19]
This command writes the bytes to the specified memory address for
debugging purposes.
-
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 20]
-
- Spinel Protocol (3df876d) December 2016
-
-
Due to the low-level nature of this command, certain error conditions
may induce the NCP to reset.
The implementation of this command has security implications. See
- Section 12 for more information.
+ Section 13 for more information.
This command requires the capability "CAP_PEEK_POKE" to be present.
@@ -1158,6 +1169,15 @@ Quattlebaum Expires June 5, 2017 [Page 20]
sections, each with reserved ranges of property identifiers. These
ranges are:
+
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 21]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
+--------+------------------------------+---------------------+
| Name | Range (Inclusive) | Documentation |
+--------+------------------------------+---------------------+
@@ -1170,14 +1190,6 @@ Quattlebaum Expires June 5, 2017 [Page 20]
| Stream | 0x70 - 0x7F, 0x1700 - 0x17FF | Section 5.2 |
+--------+------------------------------+---------------------+
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 21]
-
- Spinel Protocol (3df876d) December 2016
-
-
Note that each property section has two reserved ranges: a primary
range (which is encoded as a single byte) and an extended range
(which is encoded as two bytes). properties which are used more
@@ -1212,6 +1224,16 @@ Quattlebaum Expires June 5, 2017 [Page 21]
o Type: Read-Only
o Encoding: "ii"
+
+
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 22]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
+---------+---------------+---------------+
| Octets: | 1-3 | 1-3 |
+---------+---------------+---------------+
@@ -1227,13 +1249,6 @@ Quattlebaum Expires June 5, 2017 [Page 21]
This document describes major version 4, minor version 1 of this
protocol.
-
-
-Quattlebaum Expires June 5, 2017 [Page 22]
-
- Spinel Protocol (3df876d) December 2016
-
-
5.2.2.1. Major Version Number
The major version number is used to identify large and incompatible
@@ -1268,6 +1283,13 @@ Quattlebaum Expires June 5, 2017 [Page 22]
to present similarly to the "User-Agent" string from HTTP. The
RECOMMENDED format of the string is as follows:
+
+
+Quattlebaum Expires July 27, 2017 [Page 23]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
STACK-NAME/STACK-VERSION[BUILD_INFO][; OTHER_INFO]; BUILD_DATE_AND_TIME
Examples:
@@ -1280,16 +1302,6 @@ Quattlebaum Expires June 5, 2017 [Page 22]
o Type: Read-Only
o Encoding: "i"
-
-
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 23]
-
- Spinel Protocol (3df876d) December 2016
-
-
+---------+----------------+
| Octets: | 1-3 |
+---------+----------------+
@@ -1324,6 +1336,16 @@ Quattlebaum Expires June 5, 2017 [Page 23]
o Type: Read-Only
o Packed-Encoding: "A(i)"
+
+
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 24]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
+---------+-------+-------+-----+
| Octets: | 1-3 | 1-3 | ... |
+---------+-------+-------+-----+
@@ -1338,14 +1360,6 @@ Quattlebaum Expires June 5, 2017 [Page 23]
Currently defined values are:
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 24]
-
- Spinel Protocol (3df876d) December 2016
-
-
o 1: "CAP_LOCK"
o 2: "CAP_NET_SAVE"
o 3: "CAP_HBO": Host Buffer Offload. See Section 9.
@@ -1355,6 +1369,8 @@ Quattlebaum Expires June 5, 2017 [Page 24]
o 7: "CAP_PEEK_POKE": PEEK/POKE debugging commands.
o 8: "CAP_WRITABLE_RAW_STREAM": "PROP_STREAM_RAW" is writable.
o 9: "CAP_GPIO": Support for GPIO access. See Section 11.
+ o 10: "CAP_TRNG": Support for true random number generation. See
+ Section 12.
o 16: "CAP_802_15_4_2003"
o 17: "CAP_802_15_4_2006"
o 18: "CAP_802_15_4_2011"
@@ -1374,6 +1390,18 @@ Quattlebaum Expires June 5, 2017 [Page 24]
Additionally, future capability allocations SHALL be made from the
following allocation plan:
+
+
+
+
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 25]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
+-----------------------+--------------------------------+
| Capability Range | Description |
+-----------------------+--------------------------------+
@@ -1395,13 +1423,6 @@ Quattlebaum Expires June 5, 2017 [Page 24]
| Fields: | "INTERFACE_COUNT" |
+---------+-------------------+
-
-
-Quattlebaum Expires June 5, 2017 [Page 25]
-
- Spinel Protocol (3df876d) December 2016
-
-
Describes the number of concurrent interfaces supported by this NCP.
Since the concurrent interface mechanism is still TBD, this value
MUST always be one.
@@ -1429,6 +1450,14 @@ Quattlebaum Expires June 5, 2017 [Page 25]
(Enumerated for completeness sake, not expected on the wire)
o 1: "POWER_STATE_DEEP_SLEEP": Almost everything on the NCP is shut
down, but can still be resumed via a command or interrupt.
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 26]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
o 2: "POWER_STATE_STANDBY": NCP is in the lowest power state that
can still be awoken by an event from the radio (e.g. waiting for
alarm)
@@ -1448,16 +1477,6 @@ Quattlebaum Expires June 5, 2017 [Page 25]
| Fields: | HWADDR |
+---------+--------+
-
-
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 26]
-
- Spinel Protocol (3df876d) December 2016
-
-
The static EUI64 address of the device, used as a serial number.
This value is read-only, but may be writable under certain vendor-
defined circumstances.
@@ -1485,6 +1504,16 @@ Quattlebaum Expires June 5, 2017 [Page 26]
value of the property is already true MUST fail with a last status of
"STATUS_ALREADY".
+
+
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 27]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
5.3. Stream Properties
5.3.1. PROP 112: PROP_STREAM_DEBUG
@@ -1507,13 +1536,6 @@ Quattlebaum Expires June 5, 2017 [Page 26]
the NCP's responsibility to insert newline characters where needed,
just like with any other text stream.
-
-
-Quattlebaum Expires June 5, 2017 [Page 27]
-
- Spinel Protocol (3df876d) December 2016
-
-
To receive the debugging stream, you wait for "CMD_PROP_VALUE_IS"
commands for this property from the NCP.
@@ -1541,6 +1563,13 @@ Quattlebaum Expires June 5, 2017 [Page 27]
arbitrary raw packets. Support for this feature is indicated by the
presence of the "CAP_WRITABLE_RAW_STREAM" capability.
+
+
+Quattlebaum Expires July 27, 2017 [Page 28]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
If the capability "CAP_WRITABLE_RAW_STREAM" is set, then packets
written to this stream with "CMD_PROP_VALUE_SET" will be sent out
over the radio. This allows the caller to use the radio directly,
@@ -1560,16 +1589,6 @@ Quattlebaum Expires June 5, 2017 [Page 27]
The frame metadata field consists of the following fields:
-
-
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 28]
-
- Spinel Protocol (3df876d) December 2016
-
-
+----------+-----------------------+------------+-----+---------+
| Field | Description | Type | Len | Default |
+----------+-----------------------+------------+-----+---------+
@@ -1594,6 +1613,19 @@ Quattlebaum Expires June 5, 2017 [Page 28]
The bit values in "MD_FLAG" are defined as follows:
+
+
+
+
+
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 29]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
+---------+--------+------------------+-----------------------------+
| Bit | Mask | Name | Description if set |
+---------+--------+------------------+-----------------------------+
@@ -1616,16 +1648,6 @@ Quattlebaum Expires June 5, 2017 [Page 28]
o Type: Read-Write-Stream
o Packed-Encoding: "DD"
-
-
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 29]
-
- Spinel Protocol (3df876d) December 2016
-
-
+---------+----------------+------------+----------------+
| Octets: | 2 | n | n |
+---------+----------------+------------+----------------+
@@ -1648,6 +1670,18 @@ Quattlebaum Expires June 5, 2017 [Page 29]
Any data past the end of "FRAME_DATA_LEN" is considered metadata, the
format of which is described in Section 5.3.2.1.
+
+
+
+
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 30]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
5.3.4. PROP 114: PROP_STREAM_NET_INSECURE
o Type: Read-Write-Stream
@@ -1673,15 +1707,6 @@ Quattlebaum Expires June 5, 2017 [Page 29]
To send network packets, you call "CMD_PROP_VALUE_SET" on this
property with the value of the packet.
-
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 30]
-
- Spinel Protocol (3df876d) December 2016
-
-
Any data past the end of "FRAME_DATA_LEN" is considered metadata, the
format of which is described in Section 5.3.2.1.
@@ -1704,6 +1729,15 @@ Quattlebaum Expires June 5, 2017 [Page 30]
Value is the current channel. Must be set to one of the values
contained in "PROP_PHY_CHAN_SUPPORTED".
+
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 31]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
5.4.3. PROP 34: PROP_PHY_CHAN_SUPPORTED
o Type: Read-Only
@@ -1729,15 +1763,6 @@ Quattlebaum Expires June 5, 2017 [Page 30]
Value is the CCA (clear-channel assessment) threshold. Set to -128
to disable.
-
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 31]
-
- Spinel Protocol (3df876d) December 2016
-
-
When setting, the value will be rounded down to a value that is
supported by the underlying radio hardware.
@@ -1762,6 +1787,13 @@ Quattlebaum Expires June 5, 2017 [Page 31]
the radio. This value can be used in energy scans and for
determining the ambient noise floor for the operating environment.
+
+
+Quattlebaum Expires July 27, 2017 [Page 32]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
5.5. MAC Properties
5.5.1. PROP 48: PROP_MAC_SCAN_STATE
@@ -1785,15 +1817,6 @@ Quattlebaum Expires June 5, 2017 [Page 31]
Values switches to "SCAN_STATE_IDLE" when scan is complete.
-
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 32]
-
- Spinel Protocol (3df876d) December 2016
-
-
5.5.2. PROP 49: PROP_MAC_SCAN_MASK
o Type: Read-Write
@@ -1819,6 +1842,14 @@ Quattlebaum Expires June 5, 2017 [Page 32]
Scan beacons have two embedded structures which contain information
about the MAC layer and the NET layer. Their format depends on the
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 33]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
MAC and NET layer currently in use. The format below is for an
802.15.4 MAC with Thread:
@@ -1841,15 +1872,6 @@ Quattlebaum Expires June 5, 2017 [Page 32]
future, so care should be taken to read the length that prepends each
structure.
-
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 33]
-
- Spinel Protocol (3df876d) December 2016
-
-
5.5.5. PROP 52: PROP_MAC_15_4_LADDR
o Type: Read-Write
@@ -1877,6 +1899,13 @@ Quattlebaum Expires June 5, 2017 [Page 33]
This property is only present on NCPs which implement 802.15.4
+
+
+Quattlebaum Expires July 27, 2017 [Page 34]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
5.5.8. PROP 55: PROP_MAC_RAW_STREAM_ENABLED
o Type: Read-Write
@@ -1892,20 +1921,6 @@ Quattlebaum Expires June 5, 2017 [Page 33]
Possible Values:
-
-
-
-
-
-
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 34]
-
- Spinel Protocol (3df876d) December 2016
-
-
+----+--------------------------------+-----------------------------+
| Id | Name | Description |
+----+--------------------------------+-----------------------------+
@@ -1939,6 +1954,14 @@ Quattlebaum Expires June 5, 2017 [Page 34]
o Type: Read-Write
o Packed-Encoding: "b"
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 35]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
5.6. NET Properties
5.6.1. PROP 64: PROP_NET_SAVED
@@ -1954,14 +1977,6 @@ Quattlebaum Expires June 5, 2017 [Page 34]
o Type: Read-Write
o Packed-Encoding: "b"
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 35]
-
- Spinel Protocol (3df876d) December 2016
-
-
Network interface up/down status. Non-zero (set to 1) indicates up,
zero indicates down.
@@ -1992,6 +2007,17 @@ Quattlebaum Expires June 5, 2017 [Page 35]
o Type: Read-Write
o Packed-Encoding: "U"
+
+
+
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 36]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
5.6.6. PROP 69: PROP_NET_XPANID
o Type: Read-Write
@@ -2007,17 +2033,6 @@ Quattlebaum Expires June 5, 2017 [Page 35]
o Type: Read-Write
o Packed-Encoding: "L"
-
-
-
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 36]
-
- Spinel Protocol (3df876d) December 2016
-
-
5.6.9. PROP 72: PROP_NET_PARTITION_ID
o Type: Read-Write
@@ -2051,6 +2066,14 @@ Quattlebaum Expires June 5, 2017 [Page 36]
o Type: Read-Write
o Packed-Encoding: "6C"
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 37]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
IPv6 Prefix + Prefix Length
5.7.4. PROP 99: PROP_IPV6_ADDRESS_TABLE
@@ -2066,14 +2089,6 @@ Quattlebaum Expires June 5, 2017 [Page 36]
o "L": Preferred Lifetime
o "C": Flags
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 37]
-
- Spinel Protocol (3df876d) December 2016
-
-
5.7.5. PROP 101: PROP_IPv6_ICMP_PING_OFFLOAD
o Type: Read-Write
@@ -2106,6 +2121,15 @@ Quattlebaum Expires June 5, 2017 [Page 37]
reason.
o 2: "STATUS_UNIMPLEMENTED": The given operation has not been
implemented.
+
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 38]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
o 3: "STATUS_INVALID_ARGUMENT": An argument to the given operation
is invalid.
o 4: "STATUS_INVALID_STATE" : The given operation is invalid for the
@@ -2121,15 +2145,6 @@ Quattlebaum Expires June 5, 2017 [Page 37]
command.
o 10: "STATUS_IN_PROGRESS": The operation is in progress and will be
completed asynchronously.
-
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 38]
-
- Spinel Protocol (3df876d) December 2016
-
-
o 11: "STATUS_NOMEM": The operation has been prevented due to memory
pressure.
o 12: "STATUS_BUSY": The device is currently performing a mutually
@@ -2162,6 +2177,15 @@ Quattlebaum Expires June 5, 2017 [Page 38]
o 128 - 15,359: UNALLOCATED
o 15,360 - 16,383: Vendor-specific
o 16,384 - 1,999,999: UNALLOCATED
+
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 39]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
o 2,000,000 - 2,097,151: Experimental Use Only (MUST NEVER be used
in production!)
@@ -2179,13 +2203,6 @@ Quattlebaum Expires June 5, 2017 [Page 38]
All serious implementations of an NCP SHOULD also support the network
save feature (See Section 8).
-
-
-Quattlebaum Expires June 5, 2017 [Page 39]
-
- Spinel Protocol (3df876d) December 2016
-
-
7.1. Thread Capabilities
The Thread technology defines the following capabilities:
@@ -2216,6 +2233,15 @@ Quattlebaum Expires June 5, 2017 [Page 39]
The long address and short address of the parent of this node.
+
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 40]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
7.2.3. PROP 82: PROP_THREAD_CHILD_TABLE
o Type: Read-Only
@@ -2231,17 +2257,6 @@ Quattlebaum Expires June 5, 2017 [Page 39]
The router-id of the current leader.
-
-
-
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 40]
-
- Spinel Protocol (3df876d) December 2016
-
-
7.2.5. PROP 84: PROP_THREAD_LEADER_WEIGHT
o Type: Read-Only
@@ -2261,6 +2276,8 @@ Quattlebaum Expires June 5, 2017 [Page 40]
o Type: Read-Only
o Packed-Encoding: "D"
+ The local network data.
+
7.2.8. PROP 87: PROP_THREAD_NETWORK_DATA_VERSION
o Type: Read-Only
@@ -2271,6 +2288,16 @@ Quattlebaum Expires June 5, 2017 [Page 40]
o Type: Read-Only
o Packed-Encoding: "D"
+ The local stable network data.
+
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 41]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
7.2.10. PROP 89: PROP_THREAD_STABLE_NETWORK_DATA_VERSION
o Type: Read-Only
@@ -2291,13 +2318,6 @@ Quattlebaum Expires June 5, 2017 [Page 40]
defined. Assumed to be true for set, insert and replace. Clear
if the on mesh network was defined by another node.
-
-
-Quattlebaum Expires June 5, 2017 [Page 41]
-
- Spinel Protocol (3df876d) December 2016
-
-
7.2.12. PROP 91: PROP_THREAD_LOCAL_ROUTES
o Type: Read-Write
@@ -2323,6 +2343,17 @@ Quattlebaum Expires June 5, 2017 [Page 41]
Set to true before changing local net data. Set to false when
finished. This allows changes to be aggregated into single events.
+
+
+
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 42]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
7.2.15. PROP 94: PROP_THREAD_MODE
o Type: Read-Write
@@ -2344,16 +2375,6 @@ Quattlebaum Expires June 5, 2017 [Page 41]
o Type: Read-Write
o Packed-Encoding: "S"
-
-
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 42]
-
- Spinel Protocol (3df876d) December 2016
-
-
7.2.18. PROP 5378: PROP_THREAD_ROUTER_UPGRADE_THRESHOLD
o Type: Read-Write
@@ -2380,6 +2401,15 @@ Quattlebaum Expires June 5, 2017 [Page 42]
Note that some implementations may not support "CMD_GET_VALUE" router
ids, but may support "CMD_REMOVE_VALUE" when the node is a leader.
+
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 43]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
7.2.22. PROP 5382: PROP_THREAD_RLOC16_DEBUG_PASSTHRU
o Type: Read-Write
@@ -2390,7 +2420,7 @@ Quattlebaum Expires June 5, 2017 [Page 42]
Default value is "false".
-7.2.23. PROP 5383: SPINEL_PROP_THREAD_ROUTER_ROLE_ENABLED
+7.2.23. PROP 5383: PROP_THREAD_ROUTER_ROLE_ENABLED
o Type: Read-Write
o Packed-Encoding: "b"
@@ -2399,17 +2429,6 @@ Quattlebaum Expires June 5, 2017 [Page 42]
If current role is a router, setting this property to "false" starts
a re-attach process as an end-device.
-
-
-
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 43]
-
- Spinel Protocol (3df876d) December 2016
-
-
7.2.24. PROP 5384: PROP_THREAD_ROUTER_DOWNGRADE_THRESHOLD
o Type: Read-Write
@@ -2434,11 +2453,19 @@ Quattlebaum Expires June 5, 2017 [Page 43]
picked. This property can be set only when the device role is either
detached or disabled.
-7.2.27. PROP 5387: SPINEL_PROP_THREAD_NEIGHBOR_TABLE
+7.2.27. PROP 5387: PROP_THREAD_NEIGHBOR_TABLE
o Type: Read-Only
o Packed-Encoding: "A(T(ESLCcCbLL))"
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 44]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
Data per item is:
o "E": Extended/long address
@@ -2451,24 +2478,50 @@ Quattlebaum Expires June 5, 2017 [Page 43]
o "L": Link Frame Counter
o "L": MLE Frame Counter
+7.2.28. PROP 5388: PROP_THREAD_CHILD_COUNT_MAX
+
+ o Type: Read-Write
+ o Packed-Encoding: "C"
+
+ Specifies the maximum number of children currently allowed. This
+ parameter can only be set when Thread protocol operation has been
+ stopped.
+
+7.2.29. PROP 5389: PROP_THREAD_LEADER_NETWORK_DATA
+
+ o Type: Read-Only
+ o Packed-Encoding: "D"
+
+ The leader network data.
+
+7.2.30. PROP 5390: PROP_THREAD_STABLE_LEADER_NETWORK_DATA
+
+ o Type: Read-Only
+ o Packed-Encoding: "D"
+
+ The stable leader network data.
+
8. Feature: Network Save
- The network save feature is an optional NCP capability that, when
- present, allows the host to save and recall network credentials and
- state to and from nonvolatile storage.
+ The network save/recall feature is an optional NCP capability that,
+ when present, allows the host to save and recall network credentials
+ and state to and from nonvolatile storage.
+
+ The presence of the save/recall feature can be detected by checking
+ for the presence of the "CAP_NET_SAVE" capability in "PROP_CAPS".
+
+ Network clear feature allows host to erase all network credentials
+ and state from non-volatile memory.
-Quattlebaum Expires June 5, 2017 [Page 44]
+Quattlebaum Expires July 27, 2017 [Page 45]
- Spinel Protocol (3df876d) December 2016
+ Spinel Protocol (d309a957-dirty) January 2017
- The presence of this feature can be detected by checking for the
- presence of the "CAP_NET_SAVE" capability in "PROP_CAPS".
-
8.1. Commands
8.1.1. CMD 9: (Host->NCP) CMD_NET_SAVE
@@ -2500,9 +2553,10 @@ Quattlebaum Expires June 5, 2017 [Page 44]
| Fields: | HEADER | CMD_NET_CLEAR |
+---------+--------+---------------+
- Clear saved network state command. Clears any previously saved
- network credentials and state previously stored by "CMD_NET_SAVE"
- from non-volatile memory.
+ Clear saved network settings command. Erases all network credentials
+ and state from non-volatile memory. The erased settings include any
+ data saved automatically by the network stack firmware and/or data
+ saved by "CMD_NET_SAVE" operation.
This operation affects non-volatile memory only. The current network
information stored in volatile memory is unaffected.
@@ -2510,16 +2564,18 @@ Quattlebaum Expires June 5, 2017 [Page 44]
The response to this command is always a "CMD_PROP_VALUE_IS" for
"PROP_LAST_STATUS", indicating the result of the operation.
- This command is only available if the "CAP_NET_SAVE" capability is
- set.
+ This command is always available independent of the value of
+ "CAP_NET_SAVE" capability.
-Quattlebaum Expires June 5, 2017 [Page 45]
+
+
+Quattlebaum Expires July 27, 2017 [Page 46]
- Spinel Protocol (3df876d) December 2016
+ Spinel Protocol (d309a957-dirty) January 2017
8.1.3. CMD 11: (Host->NCP) CMD_NET_RECALL
@@ -2573,9 +2629,9 @@ Quattlebaum Expires June 5, 2017 [Page 45]
-Quattlebaum Expires June 5, 2017 [Page 46]
+Quattlebaum Expires July 27, 2017 [Page 47]
- Spinel Protocol (3df876d) December 2016
+ Spinel Protocol (d309a957-dirty) January 2017
9.1.2. CMD 13: (NCP->Host) CMD_HBO_RECLAIM
@@ -2629,9 +2685,9 @@ Quattlebaum Expires June 5, 2017 [Page 46]
-Quattlebaum Expires June 5, 2017 [Page 47]
+Quattlebaum Expires July 27, 2017 [Page 48]
- Spinel Protocol (3df876d) December 2016
+ Spinel Protocol (d309a957-dirty) January 2017
Describes the number of bytes that may be offloaded from the NCP to
@@ -2685,9 +2741,9 @@ Quattlebaum Expires June 5, 2017 [Page 47]
-Quattlebaum Expires June 5, 2017 [Page 48]
+Quattlebaum Expires July 27, 2017 [Page 49]
- Spinel Protocol (3df876d) December 2016
+ Spinel Protocol (d309a957-dirty) January 2017
+---------+--------------------------+
@@ -2741,9 +2797,9 @@ Quattlebaum Expires June 5, 2017 [Page 48]
-Quattlebaum Expires June 5, 2017 [Page 49]
+Quattlebaum Expires July 27, 2017 [Page 50]
- Spinel Protocol (3df876d) December 2016
+ Spinel Protocol (d309a957-dirty) January 2017
o Default Value: Implementation-specific
@@ -2797,9 +2853,9 @@ Quattlebaum Expires June 5, 2017 [Page 49]
-Quattlebaum Expires June 5, 2017 [Page 50]
+Quattlebaum Expires July 27, 2017 [Page 51]
- Spinel Protocol (3df876d) December 2016
+ Spinel Protocol (d309a957-dirty) January 2017
Support for this feature can be determined by the presence of
@@ -2853,9 +2909,9 @@ Quattlebaum Expires June 5, 2017 [Page 50]
-Quattlebaum Expires June 5, 2017 [Page 51]
+Quattlebaum Expires July 27, 2017 [Page 52]
- Spinel Protocol (3df876d) December 2016
+ Spinel Protocol (d309a957-dirty) January 2017
would be ignored. This command can only be used to modify the
@@ -2909,9 +2965,9 @@ Quattlebaum Expires June 5, 2017 [Page 51]
-Quattlebaum Expires June 5, 2017 [Page 52]
+Quattlebaum Expires July 27, 2017 [Page 53]
- Spinel Protocol (3df876d) December 2016
+ Spinel Protocol (d309a957-dirty) January 2017
When writing, unspecified bits are assumed to be zero. The value of
@@ -2930,9 +2986,108 @@ Quattlebaum Expires June 5, 2017 [Page 52]
any bits for GPIOs which are not specified in "PROP_GPIO_CONFIG" MUST
be ignored.
-12. Security Considerations
+12. Feature: True Random Number Generation
-12.1. Raw Application Access
+ This feature allows the host to have access to any strong hardware
+ random number generator that might be present on the NCP, for things
+ like key generation or seeding PRNGs.
+
+ Support for this feature can be determined by the presence of
+ "CAP_TRNG".
+
+ Note well that implementing a cryptographically-strong software-based
+ true random number generator (that is impervious to things like
+ temperature changes, manufacturing differences across devices, or
+ unexpected output correlations) is non-trivial without a well-
+ designed, dedicated hardware random number generator. Implementors
+ who have little or no experience in this area are encouraged to not
+ advertise this capability.
+
+12.1. Properties
+
+12.1.1. PROP 4101: PROP_TRNG_32
+
+ o Argument-Encoding: "L"
+ o Type: Read-Only
+
+ Fetching this property returns a strong random 32-bit integer that is
+ suitable for use as a PRNG seed or for cryptographic use.
+
+ While the exact mechanism behind the calculation of this value is
+ implementation-specific, the implementation must satisfy the
+ following requirements:
+
+
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 54]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
+ o Data representing at least 32 bits of fresh entropy (extracted
+ from the primary entropy source) MUST be consumed by the
+ calculation of each query.
+ o Each of the 32 bits returned MUST be free of bias and have no
+ statistical correlation to any part of the raw data used for the
+ calculation of any query.
+
+ Support for this property is REQUIRED if "CAP_TRNG" is included in
+ the device capabilities.
+
+12.1.2. PROP 4102: PROP_TRNG_128
+
+ o Argument-Encoding: "D"
+ o Type: Read-Only
+
+ Fetching this property returns 16 bytes of strong random data
+ suitable for direct cryptographic use without further processing(For
+ example, as an AES key).
+
+ While the exact mechanism behind the calculation of this value is
+ implementation-specific, the implementation must satisfy the
+ following requirements:
+
+ o Data representing at least 128 bits of fresh entropy (extracted
+ from the primary entropy source) MUST be consumed by the
+ calculation of each query.
+ o Each of the 128 bits returned MUST be free of bias and have no
+ statistical correlation to any part of the raw data used for the
+ calculation of any query.
+
+ Support for this property is REQUIRED if "CAP_TRNG" is included in
+ the device capabilities.
+
+12.1.3. PROP 4103: PROP_TRNG_RAW_32
+
+ o Argument-Encoding: "D"
+ o Type: Read-Only
+
+ This property is primarily used to diagnose and debug the behavior of
+ the entropy source used for strong random number generation.
+
+ When queried, returns the raw output from the entropy source used to
+ generate "PROP_TRNG_32", prior to any reduction/whitening and/or
+ mixing with prior state.
+
+ The length of the returned buffer is implementation specific and
+ should be expected to be non-deterministic.
+
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 55]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
+ Support for this property is RECOMMENDED if "CAP_TRNG" is included in
+ the device capabilities.
+
+13. Security Considerations
+
+13.1. Raw Application Access
Spinel MAY be used as an API boundary for allowing processes to
configure the NCP. However, such a system MUST NOT give unprivileged
@@ -2941,9 +3096,9 @@ Quattlebaum Expires June 5, 2017 [Page 52]
should be allowed to be passed, and then only after being checked for
proper format.
-13. References
+14. References
-13.1. URIs
+14.1. URIs
[1] http://wpantund.org/
@@ -2961,15 +3116,6 @@ Appendix A. Framing Protocol
Since this NCP protocol is defined independently of the physical
transport or framing, any number of transports and framing protocols
-
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 53]
-
- Spinel Protocol (3df876d) December 2016
-
-
could be used successfully. However, in the interests of
compatibility, this document provides some recommendations.
@@ -2984,6 +3130,14 @@ A.1. UART Recommendations
o Parity: None
o Flow Control: Hardware
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 56]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
These values may be adjusted depending on the individual needs of the
application or product, but some sort of flow control MUST be used.
Hardware flow control is preferred over software flow control. In
@@ -3018,14 +3172,6 @@ A.1.1. UART Bit Rate Detection
In order to limit the time spent hunting for the appropriate bitrate,
we RECOMMEND that only the following bitrates be checked:
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 54]
-
- Spinel Protocol (3df876d) December 2016
-
-
o 115200
o 230400
o 1000000 (1Mbit)
@@ -3041,6 +3187,13 @@ A.1.2. HDLC-Lite
of HDLC are omitted. This protocol was chosen because it works well
with software flow control and is widely implemented.
+
+
+Quattlebaum Expires July 27, 2017 [Page 57]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
To transmit a frame with HDLC-lite, the 16-bit CRC must first be
appended to the frame. The CRC function is defined to be CRC-16/
CCITT, otherwise known as the KERMIT CRC [4].
@@ -3075,13 +3228,6 @@ A.1.2. HDLC-Lite
a framing error. Consecutive flag octets MAY be used as a way to
wake up a sleeping NCP.
-
-
-Quattlebaum Expires June 5, 2017 [Page 55]
-
- Spinel Protocol (3df876d) December 2016
-
-
When first establishing a connection to the NCP, it is customary to
send one or more flag octets to ensure that any previously received
data is discarded.
@@ -3097,6 +3243,13 @@ A.2. SPI Recommendations
o "I̅N̅T̅": (NCP-to-Host) Host Interrupt
o "R̅E̅S̅": (Host-to-NCP) NCP Hardware Reset
+
+
+Quattlebaum Expires July 27, 2017 [Page 58]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
The "I̅N̅T̅" signal is used by the NCP to indicate to
the host that the NCP has frames pending to send to it. When
asserted, the host SHOULD initiate a SPI transaction in a timely
@@ -3130,14 +3283,6 @@ A.2.1. SPI Framing Protocol
other device must not send any data. (Little endian)
o "DATA_LEN": The fourth and fifth bytes indicate the size of the
pending data frame to be sent to the other device. If this value
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 56]
-
- Spinel Protocol (3df876d) December 2016
-
-
is equal-to or less-than the number of bytes that the other device
is willing to receive, then the data of the frame is immediately
after the header. (Little Endian)
@@ -3151,6 +3296,16 @@ Quattlebaum Expires June 5, 2017 [Page 56]
o "RST": This bit is set when that device has been reset since the
last time "C̅S̅" was asserted.
+
+
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 59]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
o "CRC": This bit is set when that device supports writing a 16-bit
CRC at the end of the data. The CRC length is NOT included in
DATA_LEN.
@@ -3185,15 +3340,6 @@ Quattlebaum Expires June 5, 2017 [Page 56]
should consider the transaction to have failed and try again after 10
milliseconds, retrying up to 200 times. After unsuccessfully trying
200 times in a row, the master MAY take appropriate remedial action
-
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 57]
-
- Spinel Protocol (3df876d) December 2016
-
-
(like a NCP hardware reset, or indicating a communication failure to
a user interface).
@@ -3208,6 +3354,14 @@ Quattlebaum Expires June 5, 2017 [Page 57]
the frame. If not enough bytes were clocked out for the CRC to be
read, then the frame must be ignored. If enough bytes were clocked
out to perform a CRC check, but the CRC check fails, then the frame
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 60]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
must be rejected and the "CRC_FAIL" bit on the next frame (and ONLY
the next frame) MUST be set.
@@ -3242,14 +3396,6 @@ B.1. Test Vector: Packed Unsigned Integer
| 2,097,151 | "FF FF 7F" |
+---------------+-----------------------+
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 58]
-
- Spinel Protocol (3df876d) December 2016
-
-
[CREF4]
B.2. Test Vector: Reset Command
@@ -3262,6 +3408,16 @@ B.2. Test Vector: Reset Command
80 01
+
+
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 61]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
B.3. Test Vector: Reset Notification
o IID: 0
@@ -3298,14 +3454,6 @@ B.4. Test Vector: Scan Beacon
+ Network Name: "spinel"
+ XPANID: "DE AD 00 BE EF 00 CA FE"
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 59]
-
- Spinel Protocol (3df876d) December 2016
-
-
Frame:
80 07 33 0F C4 0D 00 B6 40 D4 8C E9 38 F9 52 FF FF D2 04 00
@@ -3318,6 +3466,14 @@ B.5. Test Vector: Inbound IPv6 Packet
[CREF5]
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 62]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
B.6. Test Vector: Outbound IPv6 Packet
CMD_VALUE_SET(PROP_STREAM_NET)
@@ -3352,16 +3508,6 @@ B.8. Test Vector: Returned list of on-mesh networks
Frame:
-
-
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 60]
-
- Spinel Protocol (3df876d) December 2016
-
-
84 06 5A 13 00 20 01 0D B8 00 01 00 00 00 00 00 00 00 00 00
00 40 01 ?? 13 00 20 01 0D B8 00 02 00 00 00 00 00 00 00 00
00 00 40 00 ??
@@ -3374,6 +3520,16 @@ B.9. Test Vector: Adding an on-mesh network
o PROP: 90 ("PROP_THREAD_ON_MESH_NETS")
o VALUE: Structure, encoded as "6CbCb"
+
+
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 63]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
+--------------+---------------+-------------+-------------+
| IPv6 Prefix | Prefix Length | Stable Flag | Other Flags |
+--------------+---------------+-------------+-------------+
@@ -3408,16 +3564,6 @@ B.10. Test Vector: Insertion notification of an on-mesh network
[CREF8]
-
-
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 61]
-
- Spinel Protocol (3df876d) December 2016
-
-
B.11. Test Vector: Removing a local on-mesh network
o IID: 0
@@ -3430,6 +3576,16 @@ B.11. Test Vector: Removing a local on-mesh network
86 05 5A 20 01 0D B8 00 03 00 00 00 00 00 00 00 00 00 00
+
+
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 64]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
B.12. Test Vector: Removal notification of an on-mesh network
o IID: 0
@@ -3466,14 +3622,6 @@ C.1. NCP Initialization
If the host supports using vendor-specific commands, the vendor
should be verified before using them:
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 62]
-
- Spinel Protocol (3df876d) December 2016
-
-
o CMD_VALUE_GET:PROP_VENDOR_ID
o CMD_VALUE_IS:PROP_VENDOR_ID
@@ -3486,6 +3634,14 @@ Quattlebaum Expires June 5, 2017 [Page 62]
If the NCP supports CAP_NET_SAVE, then we go ahead and recall the
network:
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 65]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
o CMD_NET_RECALL
C.2. Attaching to a network
@@ -3522,14 +3678,6 @@ C.2. Attaching to a network
o CMD_VALUE_SET:PROP_NET_STACK_UP:TRUE
o CMD_VALUE_IS:PROP_NET_STACK_UP:TRUE
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 63]
-
- Spinel Protocol (3df876d) December 2016
-
-
Some asynchronous events from the NCP:
o CMD_VALUE_IS:PROP_NET_ROLE
@@ -3540,6 +3688,16 @@ C.3. Successfully joining a pre-existing network
[CREF11]
+
+
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 66]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
This example session is identical to the above session up to the
point where we set PROP_NET_IF_UP to true. From there, the behavior
changes.
@@ -3578,14 +3736,6 @@ C.4. Unsuccessfully joining a pre-existing network
Some asynchronous events from the NCP:
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 64]
-
- Spinel Protocol (3df876d) December 2016
-
-
o CMD_VALUE_IS:PROP_LAST_STATUS:STATUS_JOIN_NO_PEERS
o CMD_VALUE_IS:PROP_NET_STACK_UP:FALSE
@@ -3593,6 +3743,17 @@ C.5. Detaching from a network
TBD
+
+
+
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 67]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
C.6. Attaching to a saved network
[CREF12]
@@ -3630,18 +3791,6 @@ C.8. Adding an on-mesh prefix
TBD
-
-
-
-
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 65]
-
- Spinel Protocol (3df876d) December 2016
-
-
C.9. Entering low-power modes
TBD
@@ -3654,6 +3803,13 @@ C.10. Sniffing raw packets
Optionally set the channel:
+
+
+Quattlebaum Expires July 27, 2017 [Page 68]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
o CMD_VALUE_SET:PROP_PHY_CHAN:x
o CMD_VALUE_IS:PROP_PHY_CHAN
@@ -3687,17 +3843,6 @@ C.10. Sniffing raw packets
so that you can avoid receiving packets from other networks or that
are destined for other nodes.
-
-
-
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 66]
-
- Spinel Protocol (3df876d) December 2016
-
-
Appendix D. Acknowledgments
Special thanks to Abtin Keshavarzian, Martin Turon, Arjuna
@@ -3709,6 +3854,18 @@ Appendix D. Acknowledgments
This document was prepared using mmark [5] by (Miek Gieben) and
xml2rfc (version 2) [6].
+
+
+
+
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 69]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
Appendix E. Glossary
[CREF16]
@@ -3745,15 +3902,6 @@ Editorial Comments
0 | 1 | 2 | 3 | 4 | 5 | 6 |
7 | |---|---|---|---|---|---|---|---| | FLG || IID || TID ||||
-
-
-
-
-Quattlebaum Expires June 5, 2017 [Page 67]
-
- Spinel Protocol (3df876d) December 2016
-
-
[CREF2] RQ: It may make sense to have a look at what Bluetooth HCI is
doing for native I^2C framing and go with that.
@@ -3766,6 +3914,14 @@ Quattlebaum Expires June 5, 2017 [Page 67]
[CREF6] RQ: FIXME: This test vector is incomplete.
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 70]
+
+ Spinel Protocol (d309a957-dirty) January 2017
+
+
[CREF7] RQ: FIXME: This test vector is incomplete.
[CREF8] RQ: FIXME: This test vector is incomplete.
@@ -3805,4 +3961,16 @@ Author's Address
-Quattlebaum Expires June 5, 2017 [Page 68]
+
+
+
+
+
+
+
+
+
+
+
+
+Quattlebaum Expires July 27, 2017 [Page 71]
diff --git a/doc/spinel-protocol-src/spinel-tech-thread.md b/doc/spinel-protocol-src/spinel-tech-thread.md
index 931f5763c..38d561790 100644
--- a/doc/spinel-protocol-src/spinel-tech-thread.md
+++ b/doc/spinel-protocol-src/spinel-tech-thread.md
@@ -66,6 +66,8 @@ The leader weight for this node.
* Type: Read-Only
* Packed-Encoding: `D`
+The local network data.
+
### PROP 87: PROP_THREAD_NETWORK_DATA_VERSION
* Type: Read-Only
* Packed-Encoding: `S`
@@ -74,6 +76,8 @@ The leader weight for this node.
* Type: Read-Only
* Packed-Encoding: `D`
+The local stable network data.
+
### PROP 89: PROP_THREAD_STABLE_NETWORK_DATA_VERSION
* Type: Read-Only
* Packed-Encoding: `S`
@@ -165,7 +169,7 @@ including ones sent to the RLOC16 address.
Default value is `false`.
-### PROP 5383: SPINEL_PROP_THREAD_ROUTER_ROLE_ENABLED
+### PROP 5383: PROP_THREAD_ROUTER_ROLE_ENABLED
* Type: Read-Write
* Packed-Encoding: `b`
@@ -194,7 +198,7 @@ if it can not be used, a randomly generated router id is picked. This
property can be set only when the device role is either detached or
disabled.
-### PROP 5387: SPINEL_PROP_THREAD_NEIGHBOR_TABLE
+### PROP 5387: PROP_THREAD_NEIGHBOR_TABLE
* Type: Read-Only
* Packed-Encoding: `A(T(ESLCcCbLL))`
@@ -209,3 +213,23 @@ Data per item is:
* `b`: `true` if neighbor is a child, `false` otherwise.
* `L`: Link Frame Counter
* `L`: MLE Frame Counter
+
+### PROP 5388: PROP_THREAD_CHILD_COUNT_MAX
+* Type: Read-Write
+* Packed-Encoding: `C`
+
+Specifies the maximum number of children currently allowed.
+This parameter can only be set when Thread protocol operation
+has been stopped.
+
+### PROP 5389: PROP_THREAD_LEADER_NETWORK_DATA
+* Type: Read-Only
+* Packed-Encoding: `D`
+
+The leader network data.
+
+### PROP 5390: PROP_THREAD_STABLE_LEADER_NETWORK_DATA
+* Type: Read-Only
+* Packed-Encoding: `D`
+
+The stable leader network data.