blob: 1db873eacd46a9f4e503f271d3fb9bfb1175d954 [file] [log] [blame]
Network Working Group R. Quattlebaum
Internet-Draft J. Woodyatt, Ed.
Intended status: Informational Nest Labs, Inc.
Expires: December 24, 2017 June 22, 2017
Spinel Host-Controller Protocol
draft-rquattle-spinel-unified-ab5628a5
Abstract
This document describes the Spinel protocol, which facilitates the
control and management of IPv6 network interfaces on devices where
general purpose application processors offload network functions at
their interfaces to network co-processors (NCP) connected by simple
communication links like serial data channels. While initially
developed to support Thread(R), Spinel's layered design allows it to
be easily adapted to other similar network technologies.
This document also describes various Spinel specializations,
including support for the Thread(R) low-power mesh network
technology.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on December 24, 2017.
Copyright Notice
Copyright (c) 2017 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 1]
Internet-Draft Spinel Protocol (Unified) June 2017
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
This document may not be modified, and derivative works of it may not
be created, and it may not be published except as an Internet-Draft.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 7
1.1. About this Draft . . . . . . . . . . . . . . . . . . . . 7
1.1.1. Scope . . . . . . . . . . . . . . . . . . . . . . . . 7
1.1.2. Renumbering . . . . . . . . . . . . . . . . . . . . . 7
2. Frame Format . . . . . . . . . . . . . . . . . . . . . . . . 8
2.1. Header Format . . . . . . . . . . . . . . . . . . . . . . 8
2.1.1. FLG: Flag . . . . . . . . . . . . . . . . . . . . . . 9
2.1.2. NLI: Network Link Identifier . . . . . . . . . . . . 9
2.1.3. TID: Transaction Identifier . . . . . . . . . . . . . 9
2.1.4. Command Identifier (CMD) . . . . . . . . . . . . . . 9
2.1.5. Command Payload (Optional) . . . . . . . . . . . . . 10
3. Data Packing . . . . . . . . . . . . . . . . . . . . . . . . 10
3.1. Primitive Types . . . . . . . . . . . . . . . . . . . . . 11
3.2. Packed Unsigned Integer . . . . . . . . . . . . . . . . . 11
3.3. Data Blobs . . . . . . . . . . . . . . . . . . . . . . . 12
3.4. Structured Data . . . . . . . . . . . . . . . . . . . . . 13
3.5. Arrays . . . . . . . . . . . . . . . . . . . . . . . . . 13
4. Commands . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.1. CMD 0: (Host->NCP) CMD_NOOP . . . . . . . . . . . . . . . 14
4.2. CMD 1: (Host->NCP) CMD_RESET . . . . . . . . . . . . . . 14
4.3. CMD 2: (Host->NCP) CMD_PROP_VALUE_GET . . . . . . . . . . 14
4.4. CMD 3: (Host->NCP) CMD_PROP_VALUE_SET . . . . . . . . . . 15
4.5. CMD 4: (Host->NCP) CMD_PROP_VALUE_INSERT . . . . . . . . 15
4.6. CMD 5: (Host->NCP) CMD_PROP_VALUE_REMOVE . . . . . . . . 16
4.7. CMD 6: (NCP->Host) CMD_PROP_VALUE_IS . . . . . . . . . . 17
4.8. CMD 7: (NCP->Host) CMD_PROP_VALUE_INSERTED . . . . . . . 17
4.9. CMD 8: (NCP->Host) CMD_PROP_VALUE_REMOVED . . . . . . . . 18
4.10. CMD 18: (Host->NCP) CMD_PEEK . . . . . . . . . . . . . . 18
4.11. CMD 19: (NCP->Host) CMD_PEEK_RET . . . . . . . . . . . . 19
4.12. CMD 20: (Host->NCP) CMD_POKE . . . . . . . . . . . . . . 19
4.13. CMD 21: (Host->NCP) CMD_PROP_VALUE_MULTI_GET . . . . . . 19
4.14. CMD 22: (Host->NCP) CMD_PROP_VALUE_MULTI_SET . . . . . . 20
4.15. CMD 23: (NCP->Host) CMD_PROP_VALUES_ARE . . . . . . . . . 21
5. Properties . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.1. Property Methods . . . . . . . . . . . . . . . . . . . . 22
5.2. Property Types . . . . . . . . . . . . . . . . . . . . . 22
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 2]
Internet-Draft Spinel Protocol (Unified) June 2017
5.2.1. Single-Value Properties . . . . . . . . . . . . . . . 22
5.2.2. Multiple-Value Properties . . . . . . . . . . . . . . 23
5.2.3. Stream Properties . . . . . . . . . . . . . . . . . . 23
5.3. Property Numbering . . . . . . . . . . . . . . . . . . . 24
5.4. Property Sections . . . . . . . . . . . . . . . . . . . . 24
5.5. Core Properties . . . . . . . . . . . . . . . . . . . . . 25
5.5.1. PROP 0: PROP_LAST_STATUS . . . . . . . . . . . . . . 25
5.5.2. PROP 1: PROP_PROTOCOL_VERSION . . . . . . . . . . . . 25
5.5.3. PROP 2: PROP_NCP_VERSION . . . . . . . . . . . . . . 26
5.5.4. PROP 3: PROP_INTERFACE_TYPE . . . . . . . . . . . . . 27
5.5.5. PROP 4: PROP_INTERFACE_VENDOR_ID . . . . . . . . . . 27
5.5.6. PROP 5: PROP_CAPS . . . . . . . . . . . . . . . . . . 27
5.5.7. PROP 6: PROP_INTERFACE_COUNT . . . . . . . . . . . . 29
5.5.8. PROP 7: PROP_POWER_STATE . . . . . . . . . . . . . . 29
5.5.9. PROP 8: PROP_HWADDR . . . . . . . . . . . . . . . . . 30
5.5.10. PROP 9: PROP_LOCK . . . . . . . . . . . . . . . . . . 30
5.5.11. PROP 10: PROP_HOST_POWER_STATE . . . . . . . . . . . 31
5.5.12. PROP 4104: PROP_UNSOL_UPDATE_FILTER . . . . . . . . . 32
5.5.13. PROP 4105: PROP_UNSOL_UPDATE_LIST . . . . . . . . . . 33
5.6. Stream Properties . . . . . . . . . . . . . . . . . . . . 33
5.6.1. PROP 112: PROP_STREAM_DEBUG . . . . . . . . . . . . . 33
5.6.2. PROP 113: PROP_STREAM_RAW . . . . . . . . . . . . . . 34
5.6.3. PROP 114: PROP_STREAM_NET . . . . . . . . . . . . . . 36
5.6.4. PROP 115: PROP_STREAM_NET_INSECURE . . . . . . . . . 37
5.7. PHY Properties . . . . . . . . . . . . . . . . . . . . . 37
5.7.1. PROP 32: PROP_PHY_ENABLED . . . . . . . . . . . . . . 37
5.7.2. PROP 33: PROP_PHY_CHAN . . . . . . . . . . . . . . . 37
5.7.3. PROP 34: PROP_PHY_CHAN_SUPPORTED . . . . . . . . . . 38
5.7.4. PROP 35: PROP_PHY_FREQ . . . . . . . . . . . . . . . 38
5.7.5. PROP 36: PROP_PHY_CCA_THRESHOLD . . . . . . . . . . . 38
5.7.6. PROP 37: PROP_PHY_TX_POWER . . . . . . . . . . . . . 38
5.7.7. PROP 38: PROP_PHY_RSSI . . . . . . . . . . . . . . . 38
5.7.8. PROP 39: PROP_PHY_RX_SENSITIVITY . . . . . . . . . . 39
5.8. MAC Properties . . . . . . . . . . . . . . . . . . . . . 39
5.8.1. PROP 48: PROP_MAC_SCAN_STATE . . . . . . . . . . . . 39
5.8.2. PROP 49: PROP_MAC_SCAN_MASK . . . . . . . . . . . . . 39
5.8.3. PROP 50: PROP_MAC_SCAN_PERIOD . . . . . . . . . . . . 39
5.8.4. PROP 51: PROP_MAC_SCAN_BEACON . . . . . . . . . . . . 40
5.8.5. PROP 52: PROP_MAC_15_4_LADDR . . . . . . . . . . . . 40
5.8.6. PROP 53: PROP_MAC_15_4_SADDR . . . . . . . . . . . . 41
5.8.7. PROP 54: PROP_MAC_15_4_PANID . . . . . . . . . . . . 41
5.8.8. PROP 55: PROP_MAC_RAW_STREAM_ENABLED . . . . . . . . 41
5.8.9. PROP 56: PROP_MAC_PROMISCUOUS_MODE . . . . . . . . . 41
5.8.10. PROP 57: PROP_MAC_ENERGY_SCAN_RESULT . . . . . . . . 42
5.8.11. PROP 4864: PROP_MAC_WHITELIST . . . . . . . . . . . . 42
5.8.12. PROP 4865: PROP_MAC_WHITELIST_ENABLED . . . . . . . . 42
5.8.13. PROP 4867: SPINEL_PROP_MAC_SRC_MATCH_ENABLED . . . . 42
5.8.14. PROP 4868: SPINEL_PROP_MAC_SRC_MATCH_SHORT_ADDRESSES 42
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 3]
Internet-Draft Spinel Protocol (Unified) June 2017
5.8.15. PROP 4869:
SPINEL_PROP_MAC_SRC_MATCH_EXTENDED_ADDRESSES . . . . 43
5.8.16. PROP 4870: PROP_MAC_BLACKLIST . . . . . . . . . . . . 43
5.8.17. PROP 4871: PROP_MAC_BLACKLIST_ENABLED . . . . . . . . 43
5.9. NET Properties . . . . . . . . . . . . . . . . . . . . . 43
5.9.1. PROP 64: PROP_NET_SAVED . . . . . . . . . . . . . . . 43
5.9.2. PROP 65: PROP_NET_IF_UP . . . . . . . . . . . . . . . 44
5.9.3. PROP 66: PROP_NET_STACK_UP . . . . . . . . . . . . . 44
5.9.4. PROP 67: PROP_NET_ROLE . . . . . . . . . . . . . . . 44
5.9.5. PROP 68: PROP_NET_NETWORK_NAME . . . . . . . . . . . 44
5.9.6. PROP 69: PROP_NET_XPANID . . . . . . . . . . . . . . 44
5.9.7. PROP 70: PROP_NET_MASTER_KEY . . . . . . . . . . . . 44
5.9.8. PROP 71: PROP_NET_KEY_SEQUENCE_COUNTER . . . . . . . 45
5.9.9. PROP 72: PROP_NET_PARTITION_ID . . . . . . . . . . . 45
5.9.10. PROP 73: PROP_NET_REQUIRE_JOIN_EXISTING . . . . . . . 45
5.9.11. PROP 74: PROP_NET_KEY_SWITCH_GUARDTIME . . . . . . . 45
5.9.12. PROP 75: PROP_NET_PSKC . . . . . . . . . . . . . . . 45
5.10. IPv6 Properties . . . . . . . . . . . . . . . . . . . . . 45
5.10.1. PROP 96: PROP_IPV6_LL_ADDR . . . . . . . . . . . . . 45
5.10.2. PROP 97: PROP_IPV6_ML_ADDR . . . . . . . . . . . . . 45
5.10.3. PROP 98: PROP_IPV6_ML_PREFIX . . . . . . . . . . . . 45
5.10.4. PROP 99: PROP_IPV6_ADDRESS_TABLE . . . . . . . . . . 46
5.10.5. PROP 101: PROP_IPv6_ICMP_PING_OFFLOAD . . . . . . . 46
5.11. Debug Properties . . . . . . . . . . . . . . . . . . . . 46
5.11.1. PROP 16384: PROP_DEBUG_TEST_ASSERT . . . . . . . . . 46
5.11.2. PROP 16385: PROP_DEBUG_NCP_LOG_LEVEL . . . . . . . . 46
6. Status Codes . . . . . . . . . . . . . . . . . . . . . . . . 47
7. Technology: Thread(R) . . . . . . . . . . . . . . . . . . . . 48
7.1. Capabilities . . . . . . . . . . . . . . . . . . . . . . 49
7.2. Properties . . . . . . . . . . . . . . . . . . . . . . . 49
7.2.1. PROP 80: PROP_THREAD_LEADER_ADDR . . . . . . . . . . 49
7.2.2. PROP 81: PROP_THREAD_PARENT . . . . . . . . . . . . . 49
7.2.3. PROP 82: PROP_THREAD_CHILD_TABLE . . . . . . . . . . 49
7.2.4. PROP 83: PROP_THREAD_LEADER_RID . . . . . . . . . . . 50
7.2.5. PROP 84: PROP_THREAD_LEADER_WEIGHT . . . . . . . . . 50
7.2.6. PROP 85: PROP_THREAD_LOCAL_LEADER_WEIGHT . . . . . . 50
7.2.7. PROP 86: PROP_THREAD_NETWORK_DATA . . . . . . . . . . 50
7.2.8. PROP 87: PROP_THREAD_NETWORK_DATA_VERSION . . . . . . 50
7.2.9. PROP 88: PROP_THREAD_STABLE_NETWORK_DATA . . . . . . 50
7.2.10. PROP 89: PROP_THREAD_STABLE_NETWORK_DATA_VERSION . . 50
7.2.11. PROP 90: PROP_THREAD_ON_MESH_NETS . . . . . . . . . . 51
7.2.12. PROP 91: PROP_THREAD_OFF_MESH_ROUTES . . . . . . . . 51
7.2.13. PROP 92: PROP_THREAD_ASSISTING_PORTS . . . . . . . . 51
7.2.14. PROP 93: PROP_THREAD_ALLOW_LOCAL_NET_DATA_CHANGE . . 51
7.2.15. PROP 94: PROP_THREAD_MODE . . . . . . . . . . . . . . 52
7.2.16. PROP 5376: PROP_THREAD_CHILD_TIMEOUT . . . . . . . . 52
7.2.17. PROP 5377: PROP_THREAD_RLOC16 . . . . . . . . . . . . 52
7.2.18. PROP 5378: PROP_THREAD_ROUTER_UPGRADE_THRESHOLD . . . 52
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 4]
Internet-Draft Spinel Protocol (Unified) June 2017
7.2.19. PROP 5379: PROP_THREAD_CONTEXT_REUSE_DELAY . . . . . 52
7.2.20. PROP 5380: PROP_THREAD_NETWORK_ID_TIMEOUT . . . . . . 52
7.2.21. PROP 5381: PROP_THREAD_ACTIVE_ROUTER_IDS . . . . . . 52
7.2.22. PROP 5382: PROP_THREAD_RLOC16_DEBUG_PASSTHRU . . . . 53
7.2.23. PROP 5383: PROP_THREAD_ROUTER_ROLE_ENABLED . . . . . 53
7.2.24. PROP 5384: PROP_THREAD_ROUTER_DOWNGRADE_THRESHOLD . . 53
7.2.25. PROP 5385: PROP_THREAD_ROUTER_SELECTION_JITTER . . . 53
7.2.26. PROP 5386: PROP_THREAD_PREFERRED_ROUTER_ID . . . . . 53
7.2.27. PROP 5387: PROP_THREAD_NEIGHBOR_TABLE . . . . . . . . 53
7.2.28. PROP 5388: PROP_THREAD_CHILD_COUNT_MAX . . . . . . . 54
7.2.29. PROP 5389: PROP_THREAD_LEADER_NETWORK_DATA . . . . . 54
7.2.30. PROP 5390: PROP_THREAD_STABLE_LEADER_NETWORK_DATA . . 54
7.2.31. PROP 5391: PROP_THREAD_JOINERS . . . . . . . . . . . 54
7.2.32. PROP 5392: PROP_THREAD_COMMISSIONER_ENABLED . . . . . 55
7.2.33. PROP 5393: PROP_THREAD_TMF_PROXY_ENABLED . . . . . . 55
7.2.34. PROP 5394: PROP_THREAD_TMF_PROXY_STREAM . . . . . . . 55
7.2.35. PROP 5395: PROP_THREAD_DISOVERY_SCAN_JOINER_FLAG . . 55
7.2.36. PROP 5396:
PROP_THREAD_DISCOVERY_SCAN_ENABLE_FILTERING . . . . . 56
7.2.37. PROP 5397: PROP_THREAD_DISCOVERY_SCAN_PANID . . . . . 56
7.2.38. PROP 5398: PROP_THREAD_STEERING_DATA . . . . . . . . 56
8. Feature: Network Save . . . . . . . . . . . . . . . . . . . . 56
8.1. Commands . . . . . . . . . . . . . . . . . . . . . . . . 57
8.1.1. CMD 9: (Host->NCP) CMD_NET_SAVE . . . . . . . . . . . 57
8.1.2. CMD 10: (Host->NCP) CMD_NET_CLEAR . . . . . . . . . . 57
8.1.3. CMD 11: (Host->NCP) CMD_NET_RECALL . . . . . . . . . 58
9. Feature: Host Buffer Offload . . . . . . . . . . . . . . . . 58
9.1. Commands . . . . . . . . . . . . . . . . . . . . . . . . 58
9.1.1. CMD 12: (NCP->Host) CMD_HBO_OFFLOAD . . . . . . . . . 58
9.1.2. CMD 13: (NCP->Host) CMD_HBO_RECLAIM . . . . . . . . . 59
9.1.3. CMD 14: (NCP->Host) CMD_HBO_DROP . . . . . . . . . . 59
9.1.4. CMD 15: (Host->NCP) CMD_HBO_OFFLOADED . . . . . . . . 59
9.1.5. CMD 16: (Host->NCP) CMD_HBO_RECLAIMED . . . . . . . . 59
9.1.6. CMD 17: (Host->NCP) CMD_HBO_DROPPED . . . . . . . . . 59
9.2. Properties . . . . . . . . . . . . . . . . . . . . . . . 59
9.2.1. PROP 10: PROP_HBO_MEM_MAX . . . . . . . . . . . . . . 59
9.2.2. PROP 11: PROP_HBO_BLOCK_MAX . . . . . . . . . . . . . 60
10. Feature: Jam Detection . . . . . . . . . . . . . . . . . . . 60
10.1. Properties . . . . . . . . . . . . . . . . . . . . . . . 60
10.1.1. PROP 4608: PROP_JAM_DETECT_ENABLE . . . . . . . . . 60
10.1.2. PROP 4609: PROP_JAM_DETECTED . . . . . . . . . . . . 61
10.1.3. PROP 4610: PROP_JAM_DETECT_RSSI_THRESHOLD . . . . . 61
10.1.4. PROP 4611: PROP_JAM_DETECT_WINDOW . . . . . . . . . 61
10.1.5. PROP 4612: PROP_JAM_DETECT_BUSY . . . . . . . . . . 62
10.1.6. PROP 4613: PROP_JAM_DETECT_HISTORY_BITMAP . . . . . 62
11. Feature: GPIO Access . . . . . . . . . . . . . . . . . . . . 62
11.1. Properties . . . . . . . . . . . . . . . . . . . . . . . 63
11.1.1. PROP 4096: PROP_GPIO_CONFIG . . . . . . . . . . . . 63
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 5]
Internet-Draft Spinel Protocol (Unified) June 2017
11.1.2. PROP 4098: PROP_GPIO_STATE . . . . . . . . . . . . . 64
11.1.3. PROP 4099: PROP_GPIO_STATE_SET . . . . . . . . . . . 64
11.1.4. PROP 4100: PROP_GPIO_STATE_CLEAR . . . . . . . . . . 65
12. Feature: True Random Number Generation . . . . . . . . . . . 65
12.1. Properties . . . . . . . . . . . . . . . . . . . . . . . 65
12.1.1. PROP 4101: PROP_TRNG_32 . . . . . . . . . . . . . . 65
12.1.2. PROP 4102: PROP_TRNG_128 . . . . . . . . . . . . . . 66
12.1.3. PROP 4103: PROP_TRNG_RAW_32 . . . . . . . . . . . . 66
13. Security Considerations . . . . . . . . . . . . . . . . . . . 67
13.1. Raw Application Access . . . . . . . . . . . . . . . . . 67
14.1. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Appendix A. Framing Protocol . . . . . . . . . . . . . . . . . . 67
A.1. UART Recommendations . . . . . . . . . . . . . . . . . . 67
A.1.1. UART Bit Rate Detection . . . . . . . . . . . . . . . 68
A.1.2. HDLC-Lite . . . . . . . . . . . . . . . . . . . . . . 68
A.2. SPI Recommendations . . . . . . . . . . . . . . . . . . . 69
A.2.1. SPI Framing Protocol . . . . . . . . . . . . . . . . 70
A.3. I^2C Recommendations . . . . . . . . . . . . . . . . . . 72
A.4. Native USB Recommendations . . . . . . . . . . . . . . . 72
Appendix B. Test Vectors . . . . . . . . . . . . . . . . . . . . 72
B.1. Test Vector: Packed Unsigned Integer . . . . . . . . . . 72
B.2. Test Vector: Reset Command . . . . . . . . . . . . . . . 72
B.3. Test Vector: Reset Notification . . . . . . . . . . . . . 73
B.4. Test Vector: Scan Beacon . . . . . . . . . . . . . . . . 73
B.5. Test Vector: Inbound IPv6 Packet . . . . . . . . . . . . 73
B.6. Test Vector: Outbound IPv6 Packet . . . . . . . . . . . . 74
B.7. Test Vector: Fetch list of on-mesh networks . . . . . . . 74
B.8. Test Vector: Returned list of on-mesh networks . . . . . 74
B.9. Test Vector: Adding an on-mesh network . . . . . . . . . 74
B.10. Test Vector: Insertion notification of an on-mesh network 75
B.11. Test Vector: Removing a local on-mesh network . . . . . . 75
B.12. Test Vector: Removal notification of an on-mesh network . 76
Appendix C. Example Sessions . . . . . . . . . . . . . . . . . . 76
C.1. NCP Initialization . . . . . . . . . . . . . . . . . . . 76
C.2. Attaching to a network . . . . . . . . . . . . . . . . . 77
C.3. Successfully joining a pre-existing network . . . . . . . 77
C.4. Unsuccessfully joining a pre-existing network . . . . . . 78
C.5. Detaching from a network . . . . . . . . . . . . . . . . 78
C.6. Attaching to a saved network . . . . . . . . . . . . . . 79
C.7. NCP Software Reset . . . . . . . . . . . . . . . . . . . 79
C.8. Adding an on-mesh prefix . . . . . . . . . . . . . . . . 79
C.9. Entering low-power modes . . . . . . . . . . . . . . . . 79
C.10. Sniffing raw packets . . . . . . . . . . . . . . . . . . 79
Appendix D. Glossary . . . . . . . . . . . . . . . . . . . . . . 80
Appendix E. Acknowledgments . . . . . . . . . . . . . . . . . . 81
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 82
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 6]
Internet-Draft Spinel Protocol (Unified) June 2017
1. Introduction
Spinel is a host-controller protocol designed to enable
interoperation over simple serial connections between general purpose
device operating systems (OS) and network co-processors (NCP) for the
purpose of controlling and managing their IPv6 network interfaces,
achieving the following goals:
o Adopt a layered approach to the protocol design, allowing future
support for other network protocols.
o Minimize the number of required commands/methods by providing a
rich, property-based API.
o Support NCPs capable of being connected to more than one network
at a time.
o Gracefully handle the addition of new features and capabilities
without necessarily breaking backward compatibility.
o Be as minimal and light-weight as possible without unnecessarily
sacrificing flexibility.
On top of this core framework, we define the properties and commands
to enable various features and network protocols.
1.1. About this Draft
This document is currently in a draft status and is changing often.
This section discusses some ideas for changes to the protocol that
haven't yet been fully specified, as well as some of the impetus for
the current design.
1.1.1. Scope
The eventual intent is to have two documents: A Spinel basis document
which discusses the network-technology-agnostic mechanisms and a
Thread(R) specialization document which describes all of the
Thread(R)-specific implementation details. Currently, this document
covers both.
1.1.2. Renumbering
Efforts are currently maintained to try to prevent overtly backward-
incompatible changes to the existing protocol, but if you are
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
be clearly marked and documented to make such a transition as easy as
possible.
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 7]
Internet-Draft Spinel Protocol (Unified) June 2017
To allow conclusive detection of protocol (in)compatibility between
the host and the NCP, the following commands and properties are
already considered to be "baked" and will not change:
o Command IDs zero through eight. (Reset, No-op, and Property-Value
Commands)
o Property IDs zero through two. (Last status, Protocol Version,
and NCP Version)
Renumbering would be undertaken in order to better organize the
allocation of property IDs and capability IDs. One of the initial
goals of this protocol was for it to be possible for a host or NCP to
only implement properties with values less than 127 and for the NCP
to still be usable---relegating all larger property values for extra
features or other capabilities that aren't strictly necessary. This
would allow simple implementations to avoid the need to implement
support for PUIs (Section 3.2).
As time has gone by and the protocol has become more fleshed out, it
has become clear that some of the initial allocations were inadequate
and should be revisited if we want to try to achieve the original
goal.
2. Frame Format
A frame is defined simply as the concatenation of
o A header byte
o A command (up to three bytes, see Section 3.2 for format)
o An optional command payload
+---------+--------+-----+-------------+
| Octets: | 1 | 1-3 | n |
+---------+--------+-----+-------------+
| Fields: | HEADER | CMD | CMD_PAYLOAD |
+---------+--------+-----+-------------+
2.1. Header Format
The header byte is broken down as follows:
0 1 2 3 4 5 6 7
+---+---+---+---+---+---+---+---+
| FLG | NLI | TID |
+---+---+---+---+---+---+---+---+
[CREF1]
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 8]
Internet-Draft Spinel Protocol (Unified) June 2017
2.1.1. FLG: Flag
The flag field of the header byte ("FLG") is always set to the value
two (or "10" in binary). Any frame received with these bits set to
any other value else MUST NOT be considered a Spinel frame.
This convention allows Spinel to be line compatible with BTLE HCI.
By defining the first two bit in this way we can disambiguate between
Spinel frames and HCI frames (which always start with either "0x01"
or "0x04") without any additional framing overhead.
2.1.2. NLI: Network Link Identifier
The Network Link Identifier (NLI) is a number between 0 and 3, which
is associated by the OS with one of up to four IPv6 zone indices
corresponding to conceptual IPv6 interfaces on the NCP. This allows
the protocol to support IPv6 nodes connecting simultaneously to more
than one IPv6 network link using a single NCP instance. The first
Network Link Identifier (0) MUST refer to a distinguished conceptual
interface provided by the NCP for its IPv6 link type. The other
three Network Link Identifiers (1, 2 and 3) MAY be dissociated from
any conceptual interface.
2.1.3. TID: Transaction Identifier
The least significant bits of the header represent the Transaction
Identifier(TID). The TID is used for correlating responses to the
commands which generated them.
When a command is sent from the host, any reply to that command sent
by the NCP will use the same value for the TID. When the host
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.
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.
2.1.4. Command Identifier (CMD)
The command identifier is a 21-bit unsigned integer encoded in up to
three bytes using the packed unsigned integer format described in
Section 3.2. This encoding allows for up to 2,097,152 individual
commands, with the first 127 commands represented as a single byte.
Command identifiers larger than 2,097,151 are explicitly forbidden.
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 9]
Internet-Draft Spinel Protocol (Unified) June 2017
+-----------------------+----------------------------+
| CID Range | Description |
+-----------------------+----------------------------+
| 0 - 63 | Reserved for core commands |
| 64 - 15,359 | _UNALLOCATED_ |
| 15,360 - 16,383 | Vendor-specific |
| 16,384 - 1,999,999 | _UNALLOCATED_ |
| 2,000,000 - 2,097,151 | Experimental use only |
+-----------------------+----------------------------+
2.1.5. Command Payload (Optional)
Depending on the semantics of the command in question, a payload MAY
be included in the frame. The exact composition and length of the
payload is defined by the command identifier.
3. Data Packing
Data serialization for properties is performed using a light-weight
data packing format which was loosely inspired by D-Bus. The format
of a serialization is defined by a specially formatted string.
This packing format is used for notational convenience. While this
string-based datatype format has been designed so that the strings
may be directly used by a structured data parser, such a thing is not
required to implement Spinel. Indeed, higly constrained applications
may find such a thing to be too heavyweight.
Goals:
o Be lightweight and favor direct representation of values.
o Use an easily readable and memorable format string.
o Support lists and structures.
o Allow properties to be appended to structures while maintaining
backward compatibility.
Each primitive datatype has an ASCII character associated with it.
Structures can be represented as strings of these characters. For
example:
o "C": A single unsigned byte.
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 concatenated IPv6 addresses
In each case, the data is represented exactly as described. For
example, an array of 10 IPv6 address is stored as 160 bytes.
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 10]
Internet-Draft Spinel Protocol (Unified) June 2017
3.1. Primitive Types
+----------+----------------------+---------------------------------+
| Char | Name | Description |
+----------+----------------------+---------------------------------+
| "." | DATATYPE_VOID | Empty data type. Used |
| | | internally. |
| "b" | DATATYPE_BOOL | Boolean value. Encoded in |
| | | 8-bits as either 0x00 or 0x01. |
| | | All other values are illegal. |
| "C" | DATATYPE_UINT8 | Unsigned 8-bit integer. |
| "c" | DATATYPE_INT8 | Signed 8-bit integer. |
| "S" | DATATYPE_UINT16 | Unsigned 16-bit integer. |
| "s" | DATATYPE_INT16 | Signed 16-bit integer. |
| "L" | DATATYPE_UINT32 | Unsigned 32-bit integer. |
| "l" | DATATYPE_INT32 | Signed 32-bit integer. |
| "i" | DATATYPE_UINT_PACKED | Packed Unsigned Integer. See |
| | | Section 3.2. |
| "6" | DATATYPE_IPv6ADDR | IPv6 Address. (Big-endian) |
| "E" | DATATYPE_EUI64 | EUI-64 Address. (Big-endian) |
| "e" | DATATYPE_EUI48 | EUI-48 Address. (Big-endian) |
| "D" | DATATYPE_DATA | Arbitrary data. See Section |
| | | 3.3. |
| "d" | DATATYPE_DATA_WLEN | Arbitrary data with prepended |
| | | length. See Section 3.3. |
| "U" | DATATYPE_UTF8 | Zero-terminated UTF8-encoded |
| | | string. |
| "t(...)" | DATATYPE_STRUCT | Structured datatype with |
| | | prepended length. See Section |
| | | 3.4. |
| "A(...)" | DATATYPE_ARRAY | Array of datatypes. Compound |
| | | type. See Section 3.5. |
+----------+----------------------+---------------------------------+
All multi-byte values are little-endian unless explicitly stated
otherwise.
3.2. Packed Unsigned Integer
For certain types of integers, such command or property identifiers,
usually have a value on the wire that is less than 127. However, in
order to not preclude the use of values larger than 255, we would
need to add an extra byte. Doing this would add an extra byte to the
majority of instances, which can add up in terms of bandwidth.
The packed unsigned integer format is based on the unsigned integer
format in EXI [1], except that we limit the maximum value to the
largest value that can be encoded into three bytes(2,097,151).
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 11]
Internet-Draft Spinel Protocol (Unified) June 2017
For all values less than 127, the packed form of the number is simply
a single byte which directly represents the number. For values
larger than 127, the following process is used to encode the value:
1. The unsigned integer is broken up into _n_ 7-bit chunks and
placed into _n_ octets, leaving the most significant bit of each
octet unused.
2. Order the octets from least-significant to most-significant.
(Little-endian)
3. Clear the most significant bit of the most significant octet.
Set the least significant bit on all other octets.
Where _n_ is the smallest number of 7-bit chunks you can use to
represent the given value.
Take the value 1337, for example:
1337 => 0x0539
=> [39 0A]
=> [B9 0A]
To decode the value, you collect the 7-bit chunks until you find an
octet with the most significant bit clear.
3.3. Data Blobs
There are two types for data blobs: "d" and "D".
o "d" has the length of the data (in bytes) prepended to the data
(with the length encoded as type "S"). The size of the length
field is not included in the length.
o "D" does not have a prepended length: the length of the data is
implied by the bytes remaining to be parsed. It is an error for
"D" to not be the last type in a type in a type signature.
This dichotomy allows for more efficient encoding by eliminating
redundency. If the rest of the buffer is a data blob, encoding the
length would be redundant because we already know how many bytes are
in the rest of the buffer.
In some cases we use "d" even if it is the last field in a type
signature. We do this to allow for us to be able to append
additional fields to the type signature if necessary in the future.
This is usually the case with embedded structs, like in the scan
results.
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
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 12]
Internet-Draft Spinel Protocol (Unified) June 2017
tell where the start and end of the data blob is: the start is 9
bytes from the start of the buffer, and its length is the length of
the buffer minus 9. (9 is the number of bytes taken up by a byte and
two longs)
The datatype signature "CLLDU" is illegal because we can't determine
where the last field (a zero-terminated UTF8 string) starts. But the
datatype "CLLdU" _is_ legal, because the parser can determine the
exact length of the data blob-- allowing it to know where the start
of the next field would be.
3.4. Structured Data
The structure data type ("t(...)") is a way of bundling together
several fields into a single structure. It can be thought of as a
"d" type except that instead of being opaque, the fields in the
content are known. This is useful for things like scan results where
you have substructures which are defined by different layers.
For example, consider the type signature "Lt(ES)t(6C)". In this
hypothetical case, the first struct is defined by the MAC layer, and
the second struct is defined by the PHY layer. Because of the use of
structures, we know exactly what part comes from that layer.
Additionally, we can add fields to each structure without introducing
backward compatability problems: Data encoded as "Lt(ESU)t(6C)"
(Notice the extra "U") will decode just fine as "Lt(ES)t(6C)".
Additionally, if we don't care about the MAC layer and only care
about the network layer, we could parse as "Lt()t(6C)".
Note that data encoded as "Lt(ES)t(6C)" will also parse as "Ldd",
with the structures from both layers now being opaque data blobs.
3.5. Arrays
An array is simply a concatenated set of _n_ data encodings. For
example, the type "A(6)" is simply a list of IPv6 addresses---one
after the other. The type "A(6E)" likewise a concatenation of IPv6-
address/EUI-64 pairs.
If an array contains many fields, the fields will often be surrounded
by a structure ("t(...)"). This effectively prepends each item in
the array with its length. This is useful for improving parsing
performance or to allow additional fields to be added in the future
in a backward compatible way. If there is a high certainty that
additional fields will never be added, the struct may be omitted
(saving two bytes per item).
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 13]
Internet-Draft Spinel Protocol (Unified) June 2017
This specification does not define a way to embed an array as a field
alongside other fields.
4. Commands
4.1. CMD 0: (Host->NCP) CMD_NOOP
+---------+--------+----------+
| Octets: | 1 | 1 |
+---------+--------+----------+
| Fields: | HEADER | CMD_NOOP |
+---------+--------+----------+
No-Operation command. Induces the NCP to send a success status back
to the host. This is primarily used for liveliness checks.
The command payload for this command SHOULD be empty. The receiver
MUST ignore any non-empty command payload.
There is no error condition for this command.
4.2. CMD 1: (Host->NCP) CMD_RESET
+---------+--------+-----------+
| Octets: | 1 | 1 |
+---------+--------+-----------+
| Fields: | HEADER | CMD_RESET |
+---------+--------+-----------+
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
indicating "PROP_LAST_STATUS" has been set to
"STATUS_RESET_SOFTWARE".
The command payload for this command SHOULD be empty. The receiver
MUST ignore any non-empty command payload.
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.
4.3. CMD 2: (Host->NCP) CMD_PROP_VALUE_GET
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 14]
Internet-Draft Spinel Protocol (Unified) June 2017
+---------+--------+--------------------+---------+
| Octets: | 1 | 1 | 1-3 |
+---------+--------+--------------------+---------+
| Fields: | HEADER | CMD_PROP_VALUE_GET | PROP_ID |
+---------+--------+--------------------+---------+
Get property value command. Causes the NCP to emit a
"CMD_PROP_VALUE_IS" command for the given property identifier.
The payload for this command is the property identifier encoded in
the packed unsigned integer format described in Section 3.2.
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.
4.4. CMD 3: (Host->NCP) CMD_PROP_VALUE_SET
+---------+--------+--------------------+---------+-------+
| Octets: | 1 | 1 | 1-3 | n |
+---------+--------+--------------------+---------+-------+
| Fields: | HEADER | CMD_PROP_VALUE_SET | PROP_ID | VALUE |
+---------+--------+--------------------+---------+-------+
Set property value command. Instructs the NCP to set the given
property to the specific given value, replacing any previous value.
The payload for this command is the property identifier encoded in
the packed unsigned integer format described in Section 3.2, followed
by the property value. The exact format of the property value is
defined by the property.
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.
4.5. CMD 4: (Host->NCP) CMD_PROP_VALUE_INSERT
+---------+--------+-----------------------+---------+-------+
| Octets: | 1 | 1 | 1-3 | n |
+---------+--------+-----------------------+---------+-------+
| Fields: | HEADER | CMD_PROP_VALUE_INSERT | PROP_ID | VALUE |
+---------+--------+-----------------------+---------+-------+
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
defined by the individual property being operated on.
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 15]
Internet-Draft Spinel Protocol (Unified) June 2017
The payload for this command is the property identifier encoded in
the packed unsigned integer format described in Section 3.2, followed
by the value to be inserted. The exact format of the value is
defined by the property.
If the type signature of the property specified by "PROP_ID" consists
of a single structure enclosed by an array ("A(t(...))"), then the
contents of "VALUE" MUST contain the contents of the structure
("...") rather than the serialization of the whole item ("t(...)").
Specifically, the length of the structure MUST NOT be prepended to
"VALUE". This helps to eliminate redundant data.
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.
4.6. CMD 5: (Host->NCP) CMD_PROP_VALUE_REMOVE
+---------+--------+-----------------------+---------+-------+
| Octets: | 1 | 1 | 1-3 | n |
+---------+--------+-----------------------+---------+-------+
| Fields: | HEADER | CMD_PROP_VALUE_REMOVE | PROP_ID | VALUE |
+---------+--------+-----------------------+---------+-------+
Remove value from property command. Instructs the NCP to remove the
given value from a list-oriented property, without affecting other
items in the list. The resulting order of items in the list is
defined by the individual property being operated on.
Note that this command operates _by value_, not by index!
The payload for this command is the property identifier encoded in
the packed unsigned integer format described in Section 3.2, followed
by the value to be removed. The exact format of the value is defined
by the property.
If the type signature of the property specified by "PROP_ID" consists
of a single structure enclosed by an array ("A(t(...))"), then the
contents of "VALUE" MUST contain the contents of the structure
("...") rather than the serialization of the whole item ("t(...)").
Specifically, the length of the structure MUST NOT be prepended to
"VALUE". This helps to eliminate redundant data.
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 & Woodyatt Expires December 24, 2017 [Page 16]
Internet-Draft Spinel Protocol (Unified) June 2017
4.7. CMD 6: (NCP->Host) CMD_PROP_VALUE_IS
+---------+--------+-------------------+---------+-------+
| Octets: | 1 | 1 | 1-3 | n |
+---------+--------+-------------------+---------+-------+
| Fields: | HEADER | CMD_PROP_VALUE_IS | PROP_ID | VALUE |
+---------+--------+-------------------+---------+-------+
Property value notification command. This command can be sent by the
NCP in response to a previous command from the host, or it can be
sent by the NCP in an unsolicited fashion to notify the host of
various state changes asynchronously.
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.
4.8. CMD 7: (NCP->Host) CMD_PROP_VALUE_INSERTED
+---------+--------+-------------------------+---------+-------+
| Octets: | 1 | 1 | 1-3 | n |
+---------+--------+-------------------------+---------+-------+
| Fields: | HEADER | CMD_PROP_VALUE_INSERTED | PROP_ID | VALUE |
+---------+--------+-------------------------+---------+-------+
Property value insertion notification command. This command can be
sent by the NCP in response to the "CMD_PROP_VALUE_INSERT" command,
or it can be sent by the NCP in an unsolicited fashion to notify the
host of various state changes asynchronously.
The payload for this command is the property identifier encoded in
the packed unsigned integer format described in Section 3.2, followed
by the value that was inserted into the given property.
If the type signature of the property specified by "PROP_ID" consists
of a single structure enclosed by an array ("A(t(...))"), then the
contents of "VALUE" MUST contain the contents of the structure
("...") rather than the serialization of the whole item ("t(...)").
Specifically, the length of the structure MUST NOT be prepended to
"VALUE". This helps to eliminate redundant data.
The resulting order of items in the list is defined by the given
property.
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 17]
Internet-Draft Spinel Protocol (Unified) June 2017
4.9. CMD 8: (NCP->Host) CMD_PROP_VALUE_REMOVED
+---------+--------+------------------------+---------+-------+
| Octets: | 1 | 1 | 1-3 | n |
+---------+--------+------------------------+---------+-------+
| Fields: | HEADER | CMD_PROP_VALUE_REMOVED | PROP_ID | VALUE |
+---------+--------+------------------------+---------+-------+
Property value removal notification command. This command can be
sent by the NCP in response to the "CMD_PROP_VALUE_REMOVE" command,
or it can be sent by the NCP in an unsolicited fashion to notify the
host of various state changes asynchronously.
Note that this command operates _by value_, not by index!
The payload for this command is the property identifier encoded in
the packed unsigned integer format described in Section 3.2, followed
by the value that was removed from the given property.
If the type signature of the property specified by "PROP_ID" consists
of a single structure enclosed by an array ("A(t(...))"), then the
contents of "VALUE" MUST contain the contents of the structure
("...") rather than the serialization of the whole item ("t(...)").
Specifically, the length of the structure MUST NOT be prepended to
"VALUE". This helps to eliminate redundant data.
The resulting order of items in the list is defined by the given
property.
4.10. CMD 18: (Host->NCP) CMD_PEEK
+---------+--------+----------+---------+-------+
| Octets: | 1 | 1 | 4 | 2 |
+---------+--------+----------+---------+-------+
| Fields: | HEADER | CMD_PEEK | ADDRESS | COUNT |
+---------+--------+----------+---------+-------+
This command allows the NCP to fetch values from the RAM of the NCP
for debugging purposes. Upon success, "CMD_PEEK_RET" is sent from
the NCP to the host. Upon failure, "PROP_LAST_STATUS" is emitted
with the appropriate error indication.
Due to the low-level nature of this command, certain error conditions
may induce the NCP to reset.
The NCP MAY prevent certain regions of memory from being accessed.
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 18]
Internet-Draft Spinel Protocol (Unified) June 2017
The implementation of this command has security implications. See
Section 13 for more information.
This command requires the capability "CAP_PEEK_POKE" to be present.
4.11. CMD 19: (NCP->Host) CMD_PEEK_RET
+---------+--------+--------------+---------+-------+-------+
| Octets: | 1 | 1 | 4 | 2 | n |
+---------+--------+--------------+---------+-------+-------+
| Fields: | HEADER | CMD_PEEK_RET | ADDRESS | COUNT | BYTES |
+---------+--------+--------------+---------+-------+-------+
This command contains the contents of memory that was requested by a
previous call to "CMD_PEEK".
This command requires the capability "CAP_PEEK_POKE" to be present.
4.12. CMD 20: (Host->NCP) CMD_POKE
+---------+--------+----------+---------+-------+-------+
| Octets: | 1 | 1 | 4 | 2 | n |
+---------+--------+----------+---------+-------+-------+
| Fields: | HEADER | CMD_POKE | ADDRESS | COUNT | BYTES |
+---------+--------+----------+---------+-------+-------+
This command writes the bytes to the specified memory address for
debugging purposes.
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 13 for more information.
This command requires the capability "CAP_PEEK_POKE" to be present.
4.13. CMD 21: (Host->NCP) CMD_PROP_VALUE_MULTI_GET
o Argument-Encoding: "A(i)"
o Required Capability: "CAP_CMD_MULTI"
Fetch the value of multiple properties in one command. Arguments are
an array of property IDs. If all properties are fetched
successfully, a "CMD_PROP_VALUES_ARE" command is sent back to the
host containing the propertyid and value of each fetched property.
The order of the results in "CMD_PROP_VALUES_ARE" match the order of
properties given in "CMD_PROP_VALUE_GET".
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 19]
Internet-Draft Spinel Protocol (Unified) June 2017
Errors fetching individual properties are reflected as indicating a
change to "PROP_LAST_STATUS" for that property's place.
Not all properties can be fetched using this method. As a general
rule of thumb, any property that blocks when getting will fail for
that individual property with "STATUS_INVALID_COMMAND_FOR_PROP".
4.14. CMD 22: (Host->NCP) CMD_PROP_VALUE_MULTI_SET
o Argument-Encoding: "A(iD)"
o Required Capability: "CAP_CMD_MULTI"
+---------+--------+--------------------------+---------------------+
| Octets: | 1 | 1 | n |
+---------+--------+--------------------------+---------------------+
| Fields: | HEADER | CMD_PROP_VALUE_MULTI_SET | Property/Value |
| | | | Pairs |
+---------+--------+--------------------------+---------------------+
With each property/value pair being:
+---------+--------+---------+------------+
| Octets: | 2 | 1-3 | n |
+---------+--------+---------+------------+
| Fields: | LENGTH | PROP_ID | PROP_VALUE |
+---------+--------+---------+------------+
This command sets the value of several properties at once in the
given order. The setting of properties stops at the first error,
ignoring any later properties.
The result of this command is generally "CMD_PROP_VALUES_ARE" unless
(for example) a parsing error has occured (in which case
"CMD_PROP_VALUE_IS" for "PROP_LAST_STATUS" would be the result). The
order of the results in "CMD_PROP_VALUES_ARE" match the order of
properties given in "CMD_PROP_VALUE_MULTI_SET".
Since the processing of properties to set stops at the first error,
the resulting "CMD_PROP_VALUES_ARE" can contain fewer items than the
requested number of properties to set.
Not all properties can be set using this method. As a general rule
of thumb, any property that blocks when setting will fail for that
individual property with "STATUS_INVALID_COMMAND_FOR_PROP".
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 20]
Internet-Draft Spinel Protocol (Unified) June 2017
4.15. CMD 23: (NCP->Host) CMD_PROP_VALUES_ARE
o Argument-Encoding: "A(iD)"
o Required Capability: "CAP_CMD_MULTI"
+---------+--------+---------------------+----------------------+
| Octets: | 1 | 1 | n |
+---------+--------+---------------------+----------------------+
| Fields: | HEADER | CMD_PROP_VALUES_ARE | Property/Value Pairs |
+---------+--------+---------------------+----------------------+
With each property/value pair being:
+---------+--------+---------+------------+
| Octets: | 2 | 1-3 | n |
+---------+--------+---------+------------+
| Fields: | LENGTH | PROP_ID | PROP_VALUE |
+---------+--------+---------+------------+
This command is emitted by the NCP as the response to both the
"CMD_PROP_VALUE_MULTI_GET" and "CMD_PROP_VALUE_MULTI_SET" commands.
It is roughly analogous to "CMD_PROP_VALUE_IS", except that it
contains more than one property.
This command SHOULD NOT be emitted asynchronously, or in response to
any command other than "CMD_PROP_VALUE_MULTI_GET" or
"CMD_PROP_VALUE_MULTI_SET".
The arguments are a list of structures containing the emitted
property and the associated value. These are presented in the same
order as given in the associated initiating command. In cases where
getting or setting a specific property resulted in an error, the
associated slot in this command will describe "PROP_LAST_STATUS".
5. Properties
Spinel is largely a property-based protocol, similar to
representational state transfer (REST), with a property defined for
every attribute that an OS needs to create, read, update or delete in
the function of an IPv6 interface. The inspiration of this approach
was memory-mapped hardware registers for peripherals. The goal is to
avoid, as much as possible, the use of large complicated structures
and/or method argument lists. The reason for avoiding these is
because they have a tendency to change, especially early in
development. Adding or removing a property from a structure can
render the entire protocol incompatible. By using properties, you
simply extend the protocol with an additional property.
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 21]
Internet-Draft Spinel Protocol (Unified) June 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).
In Spinel, properties are keyed by an unsigned integer between 0 and
2,097,151 (See Section 3.2).
5.1. Property Methods
Properties may support one or more of the following methods:
o "VALUE_GET" (Section 4.3)
o "VALUE_SET" (Section 4.4)
o "VALUE_INSERT" (Section 4.5)
o "VALUE_REMOVE" (Section 4.6)
Additionally, the NCP can send updates to the host (either
synchronously or asynchronously) that inform the host about changes
to specific properties:
o "VALUE_IS" (Section 4.7)
o "VALUE_INSERTED" (Section 4.8)
o "VALUE_REMOVED" (Section 4.9)
5.2. Property Types
Conceptually, there are three different types of properties:
o Single-value properties
o Multiple-value (Array) properties
o Stream properties
5.2.1. Single-Value Properties
Single-value properties are properties that have a simple
representation of a single value. Examples would be:
o Current radio channel (Represented as an unsigned 8-bit integer)
o Network name (Represented as a UTF-8 encoded string)
o 802.15.4 PAN ID (Represented as an unsigned 16-bit integer)
The valid operations on these sorts of properties are "GET" and
"SET".
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 22]
Internet-Draft Spinel Protocol (Unified) June 2017
5.2.2. Multiple-Value Properties
Multiple-Value Properties have more than one value associated with
them. Examples would be:
o List of channels supported by the radio hardware.
o List of IPv6 addresses assigned to the interface.
o List of capabilities supported by the NCP.
The valid operations on these sorts of properties are "VALUE_GET",
"VALUE_SET", "VALUE_INSERT", and "VALUE_REMOVE".
When the value is fetched using "VALUE_GET", the returned value is
the concatenation of all of the individual values in the list. If
the length of the value for an individual item in the list is not
defined by the type then each item returned in the list is prepended
with a length (See Section 3.5). The order of the returned items,
unless explicitly defined for that specific property, is undefined.
"VALUE_SET" provides a way to completely replace all previous values.
Calling "VALUE_SET" with an empty value effectively instructs the NCP
to clear the value of that property.
"VALUE_INSERT" and "VALUE_REMOVE" provide mechanisms for the
insertion or removal of individual items _by value_. The payload for
these commands is a plain single value.
5.2.3. Stream Properties
Stream properties are special properties representing streams of
data. Examples would be:
o Network packet stream (Section 5.6.3)
o Raw packet stream (Section 5.6.2)
o Debug message stream (Section 5.6.1)
o Network Beacon stream (Section 5.8.4)
All such properties emit changes asynchronously using the "VALUE_IS"
command, sent from the NCP to the host. For example, as IPv6 traffic
is received by the NCP, the IPv6 packets are sent to the host by way
of asynchronous "VALUE_IS" notifications.
Some of these properties also support the host send data back to the
NCP. For example, this is how the host sends IPv6 traffic to the
NCP.
These types of properties generally do not support "VALUE_GET", as it
is meaningless.
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 23]
Internet-Draft Spinel Protocol (Unified) June 2017
5.3. Property Numbering
While the majority of the properties that allow the configuration of
network connectivity are network protocol specific, there are several
properties that are required in all implementations.
Future property allocations SHALL be made from the following
allocation plan:
+-----------------------+-----------------------------------------+
| Property ID Range | Description |
+-----------------------+-----------------------------------------+
| 0 - 127 | Reserved for frequently-used properties |
| 128 - 15,359 | Unallocated |
| 15,360 - 16,383 | Vendor-specific |
| 16,384 - 1,999,999 | Unallocated |
| 2,000,000 - 2,097,151 | Experimental use only |
+-----------------------+-----------------------------------------+
For an explanation of the data format encoding shorthand used
throughout this document, see Section 3.
5.4. Property Sections
The currently assigned properties are broken up into several
sections, each with reserved ranges of property identifiers. These
ranges are:
+--------+------------------------------+---------------------+
| Name | Range (Inclusive) | Documentation |
+--------+------------------------------+---------------------+
| Core | 0x00 - 0x1F, 0x1000 - 0x11FF | Section 5.5 |
| PHY | 0x20 - 0x2F, 0x1200 - 0x12FF | Section 5.7 |
| MAC | 0x30 - 0x3F, 0x1300 - 0x13FF | Section 5.8 |
| NET | 0x40 - 0x4F, 0x1400 - 0x14FF | Section 5.9 |
| Tech | 0x50 - 0x5F, 0x1500 - 0x15FF | Technology-specific |
| IPv6 | 0x60 - 0x6F, 0x1600 - 0x16FF | Section 5.10 |
| Stream | 0x70 - 0x7F, 0x1700 - 0x17FF | Section 5.5 |
| Debug | 0x4000 - 0x4400 | Section 5.11 |
+--------+------------------------------+---------------------+
Note that some of the property sections have 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 frequently are generally allocated from the former range.
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 24]
Internet-Draft Spinel Protocol (Unified) June 2017
5.5. Core Properties
5.5.1. PROP 0: PROP_LAST_STATUS
o Type: Read-Only
o Encoding: "i"
+---------+-------------+
| Octets: | 1-3 |
+---------+-------------+
| Fields: | LAST_STATUS |
+---------+-------------+
Describes the status of the last operation. Encoded as a packed
unsigned integer.
This property is emitted often to indicate the result status of
pretty much any Host-to-NCP operation.
It is emitted automatically at NCP startup with a value indicating
the reset reason.
See Section 6 for the complete list of status codes.
5.5.2. PROP 1: PROP_PROTOCOL_VERSION
o Type: Read-Only
o Encoding: "ii"
+---------+---------------+---------------+
| Octets: | 1-3 | 1-3 |
+---------+---------------+---------------+
| Fields: | MAJOR_VERSION | MINOR_VERSION |
+---------+---------------+---------------+
Describes the protocol version information. This property contains
four fields, each encoded as a packed unsigned integer:
o Major Version Number
o Minor Version Number
This document describes major version 4, minor version 3 of this
protocol.
The host MUST only use this property from NLI 0. Behavior when used
from other NLIs is undefined.
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 25]
Internet-Draft Spinel Protocol (Unified) June 2017
5.5.2.1. Major Version Number
The major version number is used to identify large and incompatible
differences between protocol versions.
The host MUST enter a FAULT state if it does not explicitly support
the given major version number.
5.5.2.2. Minor Version Number
The minor version number is used to identify small but otherwise
compatible differences between protocol versions. A mismatch between
the advertised minor version number and the minor version that is
supported by the host SHOULD NOT be fatal to the operation of the
host.
5.5.3. PROP 2: PROP_NCP_VERSION
o Type: Read-Only
o Packed-Encoding: "U"
+---------+-------------------+
| Octets: | n |
+---------+-------------------+
| Fields: | NCP_VESION_STRING |
+---------+-------------------+
Contains a string which describes the firmware currently running on
the NCP. Encoded as a zero-terminated UTF-8 string.
The format of the string is not strictly defined, but it is intended
to present similarly to the "User-Agent" string from HTTP. The
RECOMMENDED format of the string is as follows:
STACK-NAME/STACK-VERSION[BUILD_INFO][; OTHER_INFO]; BUILD_DATE_AND_TIME
Examples:
o "OpenThread/1.0d26-25-gb684c7f; DEBUG; May 9 2016 18:22:04"
o "ConnectIP/2.0b125 s1 ALPHA; Sept 24 2015 20:49:19"
The host MUST only use this property from NLI 0. Behavior when used
from other NLIs is undefined.
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 26]
Internet-Draft Spinel Protocol (Unified) June 2017
5.5.4. PROP 3: PROP_INTERFACE_TYPE
o Type: Read-Only
o Encoding: "i"
+---------+----------------+
| Octets: | 1-3 |
+---------+----------------+
| Fields: | INTERFACE_TYPE |
+---------+----------------+
This integer identifies what the network protocol for this NCP.
Currently defined values are:
o 0: Bootloader
o 2: ZigBee IP(TM)
o 3: Thread(R)
The host MUST enter a FAULT state if it does not recognize the
protocol given by the NCP.
5.5.5. PROP 4: PROP_INTERFACE_VENDOR_ID
o Type: Read-Only
o Encoding: "i"
+---------+-----------+
| Octets: | 1-3 |
+---------+-----------+
| Fields: | VENDOR_ID |
+---------+-----------+
Vendor identifier.
5.5.6. PROP 5: PROP_CAPS
o Type: Read-Only
o Packed-Encoding: "A(i)"
+---------+-------+-------+-----+
| Octets: | 1-3 | 1-3 | ... |
+---------+-------+-------+-----+
| Fields: | CAP_1 | CAP_2 | ... |
+---------+-------+-------+-----+
Describes the supported capabilities of this NCP. Encoded as a list
of packed unsigned integers.
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 27]
Internet-Draft Spinel Protocol (Unified) June 2017
A capability is defined as a 21-bit integer that describes a subset
of functionality which is supported by the NCP.
Currently defined values are:
o 1: "CAP_LOCK"
o 2: "CAP_NET_SAVE"
o 3: "CAP_HBO": Host Buffer Offload. See Section 9.
o 4: "CAP_POWER_SAVE"
o 5: "CAP_COUNTERS"
o 6: "CAP_JAM_DETECT": Jamming detection. See Section 10
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 11: "CAP_CMD_MULTI": Support for "CMD_PROP_VALUE_MULTI_GET"
(Section 4.13), "CMD_PROP_VALUE_MULTI_SET" (Section 4.14, and
"CMD_PROP_VALUES_ARE" (Section 4.15).
o 12: "CAP_UNSOL_UPDATE_FILTER": Support for
"PROP_UNSOL_UPDATE_FILTER" (Section 5.5.12) and
"PROP_UNSOL_UPDATE_LIST" (Section 5.5.13).
o 16: "CAP_802_15_4_2003"
o 17: "CAP_802_15_4_2006"
o 18: "CAP_802_15_4_2011"
o 21: "CAP_802_15_4_PIB"
o 24: "CAP_802_15_4_2450MHZ_OQPSK"
o 25: "CAP_802_15_4_915MHZ_OQPSK"
o 26: "CAP_802_15_4_868MHZ_OQPSK"
o 27: "CAP_802_15_4_915MHZ_BPSK"
o 28: "CAP_802_15_4_868MHZ_BPSK"
o 29: "CAP_802_15_4_915MHZ_ASK"
o 30: "CAP_802_15_4_868MHZ_ASK"
o 48: "CAP_ROLE_ROUTER"
o 49: "CAP_ROLE_SLEEPY"
o 52: "CAP_NET_THREAD_1_0"
o 512: "CAP_MAC_WHITELIST"
o 513: "CAP_MAC_RAW"
o 514: "CAP_OOB_STEERING_DATA"
o 1024: "CAP_THREAD_COMMISSIONER"
o 1025: "CAP_THREAD_TMF_PROXY"
Additionally, future capability allocations SHALL be made from the
following allocation plan:
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 28]
Internet-Draft Spinel Protocol (Unified) June 2017
+-----------------------+--------------------------------+
| Capability Range | Description |
+-----------------------+--------------------------------+
| 0 - 127 | Reserved for core capabilities |
| 128 - 15,359 | _UNALLOCATED_ |
| 15,360 - 16,383 | Vendor-specific |
| 16,384 - 1,999,999 | _UNALLOCATED_ |
| 2,000,000 - 2,097,151 | Experimental use only |
+-----------------------+--------------------------------+
5.5.7. PROP 6: PROP_INTERFACE_COUNT
o Type: Read-Only
o Packed-Encoding: "C"
+---------+-------------------+
| Octets: | 1 |
+---------+-------------------+
| Fields: | "INTERFACE_COUNT" |
+---------+-------------------+
Describes the number of concurrent interfaces supported by this NCP.
Since the concurrent interface mechanism is still TBD, this value
MUST always be one.
This value is encoded as an unsigned 8-bit integer.
The host MUST only use this property from NLI 0. Behavior when used
from other NLIs is undefined.
5.5.8. PROP 7: PROP_POWER_STATE
o Type: Read-Write
o Packed-Encoding: "C"
+---------+-------------+
| Octets: | 1 |
+---------+-------------+
| Fields: | POWER_STATE |
+---------+-------------+
Describes the current power state of the NCP. By writing to this
property you can manage the lower state of the NCP. Enumeration is
encoded as a single unsigned byte.
Defined values are:
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 29]
Internet-Draft Spinel Protocol (Unified) June 2017
o 0: "POWER_STATE_OFFLINE": NCP is physically powered off.
(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.
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)
o 3: "POWER_STATE_LOW_POWER": NCP is responsive (and possibly
connected), but using less power. (e.g. "Sleepy" child node)
o 4: "POWER_STATE_ONLINE": NCP is fully powered. (e.g. "Parent"
node)
[CREF2]
5.5.9. PROP 8: PROP_HWADDR
o Type: Read-Only*
o Packed-Encoding: "E"
+---------+--------+
| Octets: | 8 |
+---------+--------+
| Fields: | HWADDR |
+---------+--------+
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.
5.5.10. PROP 9: PROP_LOCK
o Type: Read-Write
o Packed-Encoding: "b"
+---------+------+
| Octets: | 1 |
+---------+------+
| Fields: | LOCK |
+---------+------+
Property lock. Used for grouping changes to several properties to
take effect at once, or to temporarily prevent the automatic updating
of property values. When this property is set, the execution of the
NCP is effectively frozen until it is cleared.
This property is only supported if the "CAP_LOCK" capability is
present.
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 30]
Internet-Draft Spinel Protocol (Unified) June 2017
Unlike most other properties, setting this property to true when the
value of the property is already true MUST fail with a last status of
"STATUS_ALREADY".
5.5.11. PROP 10: PROP_HOST_POWER_STATE
o Type: Read-Write
o Packed-Encoding: "C"
o Default value: 4
+---------+--------------------+
| Octets: | 1 |
+---------+--------------------+
| Fields: | "HOST_POWER_STATE" |
+---------+--------------------+
Describes the current power state of the _host_. This property is
used by the host to inform the NCP when it has changed power states.
The NCP can then use this state to determine which properties need
asynchronous updates. Enumeration is encoded as a single unsigned
byte. These states are defined in similar terms to
"PROP_POWER_STATE" (Section 5.5.8).
Defined values are:
o 0: "HOST_POWER_STATE_OFFLINE": Host is physically powered off and
cannot be woken by the NCP. All asynchronous commands are
squelched.
o 1: "HOST_POWER_STATE_DEEP_SLEEP": The host is in a low power state
where it can be woken by the NCP but will potentially require more
than two seconds to become fully responsive. The NCP MUST avoid
sending unnecessary property updates, such as child table updates
or non-critical messages on the debug stream. If the NCP needs to
wake the host for traffic, the NCP MUST first take action to wake
the host. Once the NCP signals to the host that it should wake
up, the NCP MUST wait for some activity from the host (indicating
that it is fully awake) before sending frames.
o 2: *RESERVED*. This value MUST NOT be set by the host. If
received by the NCP, the NCP SHOULD consider this as a synonym of
"HOST_POWER_STATE_DEEP_SLEEP".
o 3: "HOST_POWER_STATE_LOW_POWER": The host is in a low power state
where it can be immediately woken by the NCP. The NCP SHOULD
avoid sending unnecessary property updates, such as child table
updates or non-critical messages on the debug stream.
o 4: "HOST_POWER_STATE_ONLINE": The host is awake and responsive.
No special filtering is performed by the NCP on asynchronous
updates.
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 31]
Internet-Draft Spinel Protocol (Unified) June 2017
o All other values are *RESERVED*. They MUST NOT be set by the host.
If received by the NCP, the NCP SHOULD consider the value as a
synonym of "HOST_POWER_STATE_LOW_POWER".
[CREF3]
After setting this power state, any further commands from the host to
the NCP will cause "HOST_POWER_STATE" to automatically revert to
"HOST_POWER_STATE_ONLINE".
When the host is entering a low-power state, it should wait for the
response from the NCP acknowledging the command (with
"CMD_VALUE_IS"). Once that acknowledgement is received the host may
enter the low-power state.
If the NCP has the "CAP_UNSOL_UPDATE_FILTER" capability, any
unsolicited property updates masked by "PROP_UNSOL_UPDATE_FILTER"
should be honored while the host indicates it is in a low-power
state. After resuming to the "HOST_POWER_STATE_ONLINE" state, the
value of "PROP_UNSOL_UPDATE_FILTER" MUST be unchanged from the value
assigned prior to the host indicating it was entering a low-power
state.
The host MUST only use this property from NLI 0. Behavior when used
from other NLIs is undefined.
5.5.12. PROP 4104: PROP_UNSOL_UPDATE_FILTER
o Required only if "CAP_UNSOL_UPDATE_FILTER" is set.
o Type: Read-Write
o Packed-Encoding: "A(I)"
o Default value: Empty.
Contains a list of properties which are _excluded_ from generating
unsolicited value updates. This property MUST be empty after reset.
In other words, the host may opt-out of unsolicited property updates
for a specific property by adding that property id to this list.
Hosts SHOULD NOT add properties to this list which are not present in
"PROP_UNSOL_UPDATE_LIST". If such properties are added, the NCP MUST
ignore the unsupported properties.
[CREF4]
Implementations of this property are only REQUIRED to support and use
the following commands:
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 32]
Internet-Draft Spinel Protocol (Unified) June 2017
o "CMD_PROP_VALUE_GET" (Section 4.3)
o "CMD_PROP_VALUE_SET" (Section 4.4)
o "CMD_PROP_VALUE_IS" (Section 4.7)
Implementations of this property MAY optionally support and use the
following commands:
o "CMD_PROP_VALUE_INSERT" (Section 4.5)
o "CMD_PROP_VALUE_REMOVE" (Section 4.6)
o "CMD_PROP_VALUE_INSERTED" (Section 4.8)
o "CMD_PROP_VALUE_REMOVED" (Section 4.9)
Host implementations which are aiming to maximize their compatability
across different firmwre implementations SHOULD NOT assume the
availability of the optional commands for this property.
The value of this property SHALL be independent for each NLI.
5.5.13. PROP 4105: PROP_UNSOL_UPDATE_LIST
o Required only if "CAP_UNSOL_UPDATE_FILTER" is set.
o Type: Read-Only
o Packed-Encoding: "A(I)"
Contains a list of properties which are capable of generating
unsolicited value updates. This list can be used when populating
"PROP_UNSOL_UPDATE_FILTER" to disable all unsolicited property
updates.
This property is intended to effectively behave as a constant for a
given NCP firmware.
Note that not all properties that support unsolicited updates need to
be listed here. Scan results, for example, are only generated due to
direct action on the part of the host, so those properties MUST NOT
not be included in this list.
The value of this property MAY be different across available NLIs.
5.6. Stream Properties
5.6.1. PROP 112: PROP_STREAM_DEBUG
o Type: Read-Only-Stream
o Packed-Encoding: "D"
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 33]
Internet-Draft Spinel Protocol (Unified) June 2017
+---------+-----------+
| Octets: | n |
+---------+-----------+
| Fields: | UTF8_DATA |
+---------+-----------+
This property is a streaming property, meaning that you cannot
explicitly fetch the value of this property. The stream provides
human-readable debugging output which may be displayed in the host
logs.
The location of newline characters is not assumed by the host: it is
the NCP's responsibility to insert newline characters where needed,
just like with any other text stream.
To receive the debugging stream, you wait for "CMD_PROP_VALUE_IS"
commands for this property from the NCP.
5.6.2. PROP 113: PROP_STREAM_RAW
o Type: Read-Write-Stream
o Packed-Encoding: "dD"
+---------+----------------+------------+----------------+
| Octets: | 2 | n | n |
+---------+----------------+------------+----------------+
| Fields: | FRAME_DATA_LEN | FRAME_DATA | FRAME_METADATA |
+---------+----------------+------------+----------------+
This stream provides the capability of sending and receiving raw
packets to and from the radio. The exact format of the frame
metadata and data is dependent on the MAC and PHY being used.
This property is a streaming property, meaning that you cannot
explicitly fetch the value of this property. To receive traffic, you
wait for "CMD_PROP_VALUE_IS" commands with this property id from the
NCP.
Implementations may OPTIONALLY support the ability to transmit
arbitrary raw packets. Support for this feature is indicated by the
presence of the "CAP_WRITABLE_RAW_STREAM" capability.
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,
with the stack being implemented on the host instead of the NCP.
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 34]
Internet-Draft Spinel Protocol (Unified) June 2017
5.6.2.1. Frame Metadata Format
Any data past the end of "FRAME_DATA_LEN" is considered metadata and
is OPTIONAL. Frame metadata MAY be empty or partially specified.
Partially specified metadata MUST be accepted. Default values are
used for all unspecified fields.
The same general format is used for "PROP_STREAM_RAW",
"PROP_STREAM_NET", and "PROP_STREAM_NET_INSECURE". It can be used
for frames sent from the NCP to the host as well as frames sent from
the host to the NCP.
The frame metadata field consists of the following fields:
+----------+-----------------------+------------+-----+---------+
| Field | Description | Type | Len | Default |
+----------+-----------------------+------------+-----+---------+
| MD_POWER | (dBm) RSSI/TX-Power | "c" int8 | 1 | -128 |
| MD_NOISE | (dBm) Noise floor | "c" int8 | 1 | -128 |
| MD_FLAG | Flags (defined below) | "S" uint16 | 2 | |
| MD_PHY | PHY-specific data | "d" data | >=2 | |
| MD_VEND | Vendor-specific data | "d" data | >=2 | |
+----------+-----------------------+------------+-----+---------+
The following fields are ignored by the NCP for packets sent to it
from the host:
o MD_NOISE
o MD_FLAG
When specifying "MD_POWER" for a packet to be transmitted, the actual
transmit power is never larger than the current value of
"PROP_PHY_TX_POWER" (Section 5.7.6). When left unspecified (or set
to the value -128), an appropriate transmit power will be chosen by
the NCP.
The bit values in "MD_FLAG" are defined as follows:
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 35]
Internet-Draft Spinel Protocol (Unified) June 2017
+---------+--------+------------------+-----------------------------+
| Bit | Mask | Name | Description if set |
+---------+--------+------------------+-----------------------------+
| 15 | 0x0001 | MD_FLAG_TX | Packet was transmitted, not |
| | | | received. |
| 13 | 0x0004 | MD_FLAG_BAD_FCS | Packet was received with |
| | | | bad FCS |
| 12 | 0x0008 | MD_FLAG_DUPE | Packet seems to be a |
| | | | duplicate |
| 0-11, | 0xFFF2 | MD_FLAG_RESERVED | Flags reserved for future |
| 14 | | | use. |
+---------+--------+------------------+-----------------------------+
The format of "MD_PHY" is specified by the PHY layer currently in
use, and may contain information such as the channel, LQI, antenna,
or other pertainent information.
5.6.3. PROP 114: PROP_STREAM_NET
o Type: Read-Write-Stream
o Packed-Encoding: "dD"
+---------+----------------+------------+----------------+
| Octets: | 2 | n | n |
+---------+----------------+------------+----------------+
| Fields: | FRAME_DATA_LEN | FRAME_DATA | FRAME_METADATA |
+---------+----------------+------------+----------------+
This stream provides the capability of sending and receiving data
packets to and from the currently attached network. The exact format
of the frame metadata and data is dependent on the network protocol
being used.
This property is a streaming property, meaning that you cannot
explicitly fetch the value of this property. To receive traffic, you
wait for "CMD_PROP_VALUE_IS" commands with this property id from the
NCP.
To send network packets, you call "CMD_PROP_VALUE_SET" on this
property with the value of the packet.
Any data past the end of "FRAME_DATA_LEN" is considered metadata, the
format of which is described in Section 5.6.2.1.
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 36]
Internet-Draft Spinel Protocol (Unified) June 2017
5.6.4. PROP 115: PROP_STREAM_NET_INSECURE
o Type: Read-Write-Stream
o Packed-Encoding: "dD"
+---------+----------------+------------+----------------+
| Octets: | 2 | n | n |
+---------+----------------+------------+----------------+
| Fields: | FRAME_DATA_LEN | FRAME_DATA | FRAME_METADATA |
+---------+----------------+------------+----------------+
This stream provides the capability of sending and receiving
unencrypted and unauthenticated data packets to and from nearby
devices for the purposes of device commissioning. The exact format
of the frame metadata and data is dependent on the network protocol
being used.
This property is a streaming property, meaning that you cannot
explicitly fetch the value of this property. To receive traffic, you
wait for "CMD_PROP_VALUE_IS" commands with this property id from the
NCP.
To send network packets, you call "CMD_PROP_VALUE_SET" on this
property with the value of the packet.
Any data past the end of "FRAME_DATA_LEN" is considered metadata, the
format of which is described in Section 5.6.2.1.
5.7. PHY Properties
5.7.1. PROP 32: PROP_PHY_ENABLED
o Type: Read-Write
o Packed-Encoding: "b" (bool8)
Set to 1 if the PHY is enabled, set to 0 otherwise. May be directly
enabled to bypass higher-level packet processing in order to
implement things like packet sniffers. This property can only be
written if the "SPINEL_CAP_MAC_RAW" capability is present.
5.7.2. PROP 33: PROP_PHY_CHAN
o Type: Read-Write
o Packed-Encoding: "C" (uint8)
Value is the current channel. Must be set to one of the values
contained in "PROP_PHY_CHAN_SUPPORTED".
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 37]
Internet-Draft Spinel Protocol (Unified) June 2017
5.7.3. PROP 34: PROP_PHY_CHAN_SUPPORTED
o Type: Read-Only
o Packed-Encoding: "A(C)" (array of uint8)
o Unit: List of channels
Value is a list of channel values that are supported by the hardware.
5.7.4. PROP 35: PROP_PHY_FREQ
o Type: Read-Only
o Packed-Encoding: "L" (uint32)
o Unit: Kilohertz
Value is the radio frequency (in kilohertz) of the current channel.
5.7.5. PROP 36: PROP_PHY_CCA_THRESHOLD
o Type: Read-Write
o Packed-Encoding: "c" (int8)
o Unit: dBm
Value is the CCA (clear-channel assessment) threshold. Set to -128
to disable.
When setting, the value will be rounded down to a value that is
supported by the underlying radio hardware.
5.7.6. PROP 37: PROP_PHY_TX_POWER
o Type: Read-Write
o Packed-Encoding: "c" (int8)
o Unit: dBm
Value is the transmit power of the radio.
When setting, the value will be rounded down to a value that is
supported by the underlying radio hardware.
5.7.7. PROP 38: PROP_PHY_RSSI
o Type: Read-Only
o Packed-Encoding: "c" (int8)
o Unit: dBm
Value is the current RSSI (Received signal strength indication) from
the radio. This value can be used in energy scans and for
determining the ambient noise floor for the operating environment.
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 38]
Internet-Draft Spinel Protocol (Unified) June 2017
5.7.8. PROP 39: PROP_PHY_RX_SENSITIVITY
o Type: Read-Only
o Packed-Encoding: "c" (int8)
o Unit: dBm
Value is the radio receive sensitivity. This value can be used as
lower bound noise floor for link metrics computation.
5.8. MAC Properties
5.8.1. PROP 48: PROP_MAC_SCAN_STATE
o Type: Read-Write
o Packed-Encoding: "C"
o Unit: Enumeration
Possible Values:
o 0: "SCAN_STATE_IDLE"
o 1: "SCAN_STATE_BEACON"
o 2: "SCAN_STATE_ENERGY"
o 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
result will be reported by emissions of "PROP_MAC_ENERGY_SCAN_RESULT"
(per channel).
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.
5.8.2. PROP 49: PROP_MAC_SCAN_MASK
o Type: Read-Write
o Packed-Encoding: "A(C)"
o Unit: List of channels to scan
5.8.3. PROP 50: PROP_MAC_SCAN_PERIOD
o Type: Read-Write
o Packed-Encoding: "S" (uint16)
o Unit: milliseconds per channel
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 39]
Internet-Draft Spinel Protocol (Unified) June 2017
5.8.4. PROP 51: PROP_MAC_SCAN_BEACON
o Type: Read-Only-Stream
o 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 |
+---------+----+------+---------+----------+---------+----------+
Scan beacons have two embedded structures which contain information
about the MAC layer and the NET layer. Their format depends on the
MAC and NET layer currently in use. The format below is for an
802.15.4 MAC with Thread:
o "C": Channel
o "c": RSSI of the beacon
o "t": MAC layer properties (802.15.4 layer shown below for
convenience)
* "E": Long address
* "S": Short address
* "S": PAN-ID
* "c": LQI
o NET layer properties (Standard net layer shown below for
convenience)
* "i": Protocol Number
* "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 that prepends each
structure.
5.8.5. PROP 52: PROP_MAC_15_4_LADDR
o Type: Read-Write
o Packed-Encoding: "E"
The 802.15.4 long address of this node.
This property is only present on NCPs which implement 802.15.4
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 40]
Internet-Draft Spinel Protocol (Unified) June 2017
5.8.6. PROP 53: PROP_MAC_15_4_SADDR
o Type: Read-Write
o Packed-Encoding: "S"
The 802.15.4 short address of this node.
This property is only present on NCPs which implement 802.15.4
5.8.7. PROP 54: PROP_MAC_15_4_PANID
o Type: Read-Write
o Packed-Encoding: "S"
The 802.15.4 PANID this node is associated with.
This property is only present on NCPs which implement 802.15.4
5.8.8. PROP 55: PROP_MAC_RAW_STREAM_ENABLED
o Type: Read-Write
o Packed-Encoding: "b"
Set to true to enable raw MAC frames to be emitted from
"PROP_STREAM_RAW". See Section 5.6.2.
5.8.9. PROP 56: PROP_MAC_PROMISCUOUS_MODE
o Type: Read-Write
o Packed-Encoding: "C"
Possible Values:
+----+--------------------------------+-----------------------------+
| Id | Name | Description |
+----+--------------------------------+-----------------------------+
| 0 | "MAC_PROMISCUOUS_MODE_OFF" | Normal MAC filtering is in |
| | | place. |
| 1 | "MAC_PROMISCUOUS_MODE_NETWORK" | All MAC packets matching |
| | | network are passed up the |
| | | stack. |
| 2 | "MAC_PROMISCUOUS_MODE_FULL" | All decoded MAC packets are |
| | | passed up the stack. |
+----+--------------------------------+-----------------------------+
See Section 5.6.2.
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 41]
Internet-Draft Spinel Protocol (Unified) June 2017
5.8.10. PROP 57: PROP_MAC_ENERGY_SCAN_RESULT
o Type: Read-Only-Stream
o Packed-Encoding: "Cc"
This property is emitted during energy scan operation per scanned
channel with following format:
o "C": Channel
o "c": RSSI (in dBm)
5.8.11. PROP 4864: PROP_MAC_WHITELIST
o Type: Read-Write
o Packed-Encoding: "A(T(Ec))"
o Required capability: "CAP_MAC_WHITELIST"
Structure Parameters:
o "E": EUI64 address of node
o "c": Optional RSSI-override value. The value 127 indicates that
the RSSI-override feature is not enabled for this address. If
this value is omitted when setting or inserting, it is assumed to
be 127. This parameter is ignored when removing.
5.8.12. PROP 4865: PROP_MAC_WHITELIST_ENABLED
o Type: Read-Write
o Packed-Encoding: "b"
o Required capability: "CAP_MAC_WHITELIST"
5.8.13. PROP 4867: SPINEL_PROP_MAC_SRC_MATCH_ENABLED
o Type: Write
o Packed-Encoding: "b"
Set to true to enable radio source matching or false to disable it.
This property is only available if the "SPINEL_CAP_MAC_RAW"
capability is present. The source match functionality is used by
radios when generating ACKs. The short and extended address lists
are used for settings the Frame Pending bit in the ACKs.
5.8.14. PROP 4868: SPINEL_PROP_MAC_SRC_MATCH_SHORT_ADDRESSES
o Type: Write
o Packed-Encoding: "A(S)"
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 42]
Internet-Draft Spinel Protocol (Unified) June 2017
Configures the list of short addresses used for source matching.
This property is only available if the "SPINEL_CAP_MAC_RAW"
capability is present.
Structure Parameters:
o "S": Short address for hardware generated ACKs
5.8.15. PROP 4869: SPINEL_PROP_MAC_SRC_MATCH_EXTENDED_ADDRESSES
o Type: Write
o Packed-Encoding: "A(E)"
Configures the list of extended addresses used for source matching.
This property is only available if the "SPINEL_CAP_MAC_RAW"
capability is present.
Structure Parameters:
o "E": EUI64 address for hardware generated ACKs
5.8.16. PROP 4870: PROP_MAC_BLACKLIST
o Type: Read-Write
o Packed-Encoding: "A(T(E))"
o Required capability: "CAP_MAC_WHITELIST"
Structure Parameters:
o "E": EUI64 address of node
5.8.17. PROP 4871: PROP_MAC_BLACKLIST_ENABLED
o Type: Read-Write
o Packed-Encoding: "b"
o Required capability: "CAP_MAC_WHITELIST"
5.9. NET Properties
5.9.1. PROP 64: PROP_NET_SAVED
o Type: Read-Only
o Packed-Encoding: "b"
Returns true if there is a network state stored/saved.
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 43]
Internet-Draft Spinel Protocol (Unified) June 2017
5.9.2. PROP 65: PROP_NET_IF_UP
o Type: Read-Write
o Packed-Encoding: "b"
Network interface up/down status. Non-zero (set to 1) indicates up,
zero indicates down.
5.9.3. PROP 66: PROP_NET_STACK_UP
o Type: Read-Write
o Packed-Encoding: "b"
o Unit: Enumeration
Thread stack operational status. Non-zero (set to 1) indicates up,
zero indicates down.
5.9.4. PROP 67: PROP_NET_ROLE
o Type: Read-Write
o Packed-Encoding: "C"
o Unit: Enumeration
Values:
o 0: "NET_ROLE_DETACHED"
o 1: "NET_ROLE_CHILD"
o 2: "NET_ROLE_ROUTER"
o 3: "NET_ROLE_LEADER"
5.9.5. PROP 68: PROP_NET_NETWORK_NAME
o Type: Read-Write
o Packed-Encoding: "U"
5.9.6. PROP 69: PROP_NET_XPANID
o Type: Read-Write
o Packed-Encoding: "D"
5.9.7. PROP 70: PROP_NET_MASTER_KEY
o Type: Read-Write
o Packed-Encoding: "D"
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 44]
Internet-Draft Spinel Protocol (Unified) June 2017
5.9.8. PROP 71: PROP_NET_KEY_SEQUENCE_COUNTER
o Type: Read-Write
o Packed-Encoding: "L"
5.9.9. PROP 72: PROP_NET_PARTITION_ID
o Type: Read-Write
o Packed-Encoding: "L"
The partition ID of the partition that this node is a member of.
5.9.10. PROP 73: PROP_NET_REQUIRE_JOIN_EXISTING
o Type: Read-Write
o Packed-Encoding: "b"
5.9.11. PROP 74: PROP_NET_KEY_SWITCH_GUARDTIME
o Type: Read-Write
o Packed-Encoding: "L"
5.9.12. PROP 75: PROP_NET_PSKC
o Type: Read-Write
o Packed-Encoding: "D"
5.10. IPv6 Properties
5.10.1. PROP 96: PROP_IPV6_LL_ADDR
o Type: Read-Only
o Packed-Encoding: "6"
IPv6 Address
5.10.2. PROP 97: PROP_IPV6_ML_ADDR
o Type: Read-Only
o Packed-Encoding: "6"
IPv6 Address + Prefix Length
5.10.3. PROP 98: PROP_IPV6_ML_PREFIX
o Type: Read-Write
o Packed-Encoding: "6C"
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 45]
Internet-Draft Spinel Protocol (Unified) June 2017
IPv6 Prefix + Prefix Length
5.10.4. PROP 99: PROP_IPV6_ADDRESS_TABLE
o Type: Read-Write
o Packed-Encoding: "A(t(6CLLC))"
Array of structures containing:
o "6": IPv6 Address
o "C": Network Prefix Length
o "L": Valid Lifetime
o "L": Preferred Lifetime
o "C": Flags
5.10.5. PROP 101: PROP_IPv6_ICMP_PING_OFFLOAD
o Type: Read-Write
o Packed-Encoding: "b"
Allow the NCP to directly respond to ICMP ping requests. If this is
turned on, ping request ICMP packets will not be passed to the host.
Default value is "false".
5.11. Debug Properties
5.11.1. PROP 16384: PROP_DEBUG_TEST_ASSERT
o Type: Read-Only
o Packed-Encoding: "b"
Reading this property will cause an assert on the NCP. This is
intended for testing the assert functionality of underlying platform/
NCP. Assert should ideally cause the NCP to reset, but if "assert"
is not supported or disabled boolean value of "false" is returned in
response.
5.11.2. PROP 16385: PROP_DEBUG_NCP_LOG_LEVEL
o Type: Read-Write
o Packed-Encoding: "C"
Provides access to the NCP log level. Currently defined values are
(which follows the RFC 5424):
o 0: Emergency (emerg).
o 1: Alert (alert).
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 46]
Internet-Draft Spinel Protocol (Unified) June 2017
o 2: Critical (crit).
o 3: Error (err).
o 4: Warning (warn).
o 5: Notice (notice).
o 6: Information (info).
o 7: Debug (debug).
If the NCP supports dynamic log level control, setting this property
changes the log level accordingly. Getting the value returns the
current log level. If the dynamic log level control is not
supported, setting this property returns a "PROP_LAST_STATUS" with
"STATUS_INVALID_COMMAND_FOR_PROP".
6. Status Codes
Status codes are sent from the NCP to the host via "PROP_LAST_STATUS"
using the "CMD_VALUE_IS" command to indicate the return status of a
previous command. As with any response, the TID field of the FLAG
byte is used to correlate the response with the request.
Note that most successfully executed commands do not indicate a last
status of "STATUS_OK". The usual way the NCP indicates a successful
command is to mirror the property change back to the host. For
example, if you do a "CMD_VALUE_SET" on "PROP_PHY_ENABLED", the NCP
would indicate success by responding with a "CMD_VALUE_IS" for
"PROP_PHY_ENABLED". If the command failed, "PROP_LAST_STATUS" would
be emitted instead.
See Section 5.5.1 for more information on "PROP_LAST_STATUS".
o 0: "STATUS_OK": Operation has completed successfully.
o 1: "STATUS_FAILURE": Operation has failed for some undefined
reason.
o 2: "STATUS_UNIMPLEMENTED": The given operation has not been
implemented.
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
current state of the device.
o 5: "STATUS_INVALID_COMMAND": The given command is not recognized.
o 6: "STATUS_INVALID_INTERFACE": The given Spinel interface is not
supported.
o 7: "STATUS_INTERNAL_ERROR": An internal runtime error has
occurred.
o 8: "STATUS_SECURITY_ERROR": A security or authentication error has
occurred.
o 9: "STATUS_PARSE_ERROR": An error has occurred while parsing the
command.
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 47]
Internet-Draft Spinel Protocol (Unified) June 2017
o 10: "STATUS_IN_PROGRESS": The operation is in progress and will be
completed asynchronously.
o 11: "STATUS_NOMEM": The operation has been prevented due to memory
pressure.
o 12: "STATUS_BUSY": The device is currently performing a mutually
exclusive operation.
o 13: "STATUS_PROP_NOT_FOUND": The given property is not recognized.
o 14: "STATUS_PACKET_DROPPED": The packet was dropped.
o 15: "STATUS_EMPTY": The result of the operation is empty.
o 16: "STATUS_CMD_TOO_BIG": The command was too large to fit in the
internal buffer.
o 17: "STATUS_NO_ACK": The packet was not acknowledged.
o 18: "STATUS_CCA_FAILURE": The packet was not sent due to a CCA
failure.
o 19: "STATUS_ALREADY": The operation is already in progress or the
property was already set to the given value.
o 20: "STATUS_ITEM_NOT_FOUND": The given item could not be found in
the property.
o 21: "STATUS_INVALID_COMMAND_FOR_PROP": The given command cannot be
performed on this property.
o 22-111: RESERVED
o 112-127: Reset Causes
* 112: "STATUS_RESET_POWER_ON"
* 113: "STATUS_RESET_EXTERNAL"
* 114: "STATUS_RESET_SOFTWARE"
* 115: "STATUS_RESET_FAULT"
* 116: "STATUS_RESET_CRASH"
* 117: "STATUS_RESET_ASSERT"
* 118: "STATUS_RESET_OTHER"
* 119: "STATUS_RESET_UNKNOWN"
* 120: "STATUS_RESET_WATCHDOG"
* 121-127: RESERVED-RESET-CODES
o 128 - 15,359: UNALLOCATED
o 15,360 - 16,383: Vendor-specific
o 16,384 - 1,999,999: UNALLOCATED
o 2,000,000 - 2,097,151: Experimental Use Only (MUST NEVER be used
in production!)
7. Technology: Thread(R)
This section describes all of the properties and semantics required
for managing a Thread(R) NCP.
Thread(R) NCPs have the following requirements:
o The property "PROP_INTERFACE_TYPE" must be 3.
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 48]
Internet-Draft Spinel Protocol (Unified) June 2017
o The non-optional properties in the following sections MUST be
implemented: CORE, PHY, MAC, NET, and IPV6.
All serious implementations of an NCP SHOULD also support the network
save feature (See Section 8).
7.1. Capabilities
The Thread(R) technology defines the following capabilities:
o "CAP_NET_THREAD_1_0" - Indicates that the NCP implements v1.0 of
the Thread(R) standard.
o "CAP_NET_THREAD_1_1" - Indicates that the NCP implements v1.1 of
the Thread(R) standard.
7.2. Properties
Properties for Thread(R) are allocated out of the "Tech" property
section (see Section 5.4).
7.2.1. PROP 80: PROP_THREAD_LEADER_ADDR
o Type: Read-Only
o Packed-Encoding: "6"
The IPv6 address of the leader. (Note: May change to long and short
address of leader)
7.2.2. PROP 81: PROP_THREAD_PARENT
o Type: Read-Only
o Packed-Encoding: "ES"
o LADDR, SADDR
The long address and short address of the parent of this node.
7.2.3. PROP 82: PROP_THREAD_CHILD_TABLE
o Type: Read-Only
o Packed-Encoding: "A(t(ES))"
Table containing the long and short addresses of all the children of
this node.
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 49]
Internet-Draft Spinel Protocol (Unified) June 2017
7.2.4. PROP 83: PROP_THREAD_LEADER_RID
o Type: Read-Only
o Packed-Encoding: "C"
The router-id of the current leader.
7.2.5. PROP 84: PROP_THREAD_LEADER_WEIGHT
o Type: Read-Only
o Packed-Encoding: "C"
The leader weight of the current leader.
7.2.6. PROP 85: PROP_THREAD_LOCAL_LEADER_WEIGHT
o Type: Read-Write
o Packed-Encoding: "C"
The leader weight for this node.
7.2.7. PROP 86: PROP_THREAD_NETWORK_DATA
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
o Packed-Encoding: "S"
7.2.9. PROP 88: PROP_THREAD_STABLE_NETWORK_DATA
o Type: Read-Only
o Packed-Encoding: "D"
The local stable network data.
7.2.10. PROP 89: PROP_THREAD_STABLE_NETWORK_DATA_VERSION
o Type: Read-Only
o Packed-Encoding: "S"
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 50]
Internet-Draft Spinel Protocol (Unified) June 2017
7.2.11. PROP 90: PROP_THREAD_ON_MESH_NETS
o Type: Read-Write
o Packed-Encoding: "A(t(6CbCb))"
Data per item is:
o "6": IPv6 Prefix
o "C": Prefix length in bits
o "b": Stable flag
o "C": TLV flags
o "b": "Is defined locally" flag. Set if this network was locally
defined. Assumed to be true for set, insert and replace. Clear
if the on mesh network was defined by another node.
7.2.12. PROP 91: PROP_THREAD_OFF_MESH_ROUTES
o Type: Read-Write
o Packed-Encoding: "A(t(6CbCbb))"
Data per item is:
o "6": Route Prefix
o "C": Prefix length in bits
o "b": Stable flag
o "C": Route preference flags
o "b": "Is defined locally" flag. Set if this route info was
locally defined as part of local network data. Assumed to be true
for set, insert and replace. Clear if the route is part of
partition's network data.
o "b": "Next hop is this device" flag. Set if the next hop for the
route is this device itself (i.e., route was added by this device)
This value is ignored when adding an external route. For any
added route the next hop is this device.
7.2.13. PROP 92: PROP_THREAD_ASSISTING_PORTS
o Type: Read-Write
o Packed-Encoding: "A(S)"
7.2.14. PROP 93: PROP_THREAD_ALLOW_LOCAL_NET_DATA_CHANGE
o Type: Read-Write
o Packed-Encoding: "b"
Set to true before changing local net data. Set to false when
finished. This allows changes to be aggregated into single events.
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 51]
Internet-Draft Spinel Protocol (Unified) June 2017
7.2.15. PROP 94: PROP_THREAD_MODE
o Type: Read-Write
o Packed-Encoding: "C"
This property contains the value of the mode TLV for this node. The
meaning of the bits in this bitfield are defined by section 4.5.2 of
the Thread(R) specification.
7.2.16. PROP 5376: PROP_THREAD_CHILD_TIMEOUT
o Type: Read-Write
o Packed-Encoding: "L"
Used when operating in the Child role.
7.2.17. PROP 5377: PROP_THREAD_RLOC16
o Type: Read-Write
o Packed-Encoding: "S"
7.2.18. PROP 5378: PROP_THREAD_ROUTER_UPGRADE_THRESHOLD
o Type: Read-Write
o Packed-Encoding: "C"
7.2.19. PROP 5379: PROP_THREAD_CONTEXT_REUSE_DELAY
o Type: Read-Write
o Packed-Encoding: "L"
7.2.20. PROP 5380: PROP_THREAD_NETWORK_ID_TIMEOUT
o Type: Read-Write
o Packed-Encoding: "C"
Allows you to get or set the Thread(R) "NETWORK_ID_TIMEOUT" constant,
as defined by the Thread(R) specification.
7.2.21. PROP 5381: PROP_THREAD_ACTIVE_ROUTER_IDS
o Type: Read-Write/Write-Only
o Packed-Encoding: "A(C)" (List of active thread router ids)
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 & Woodyatt Expires December 24, 2017 [Page 52]
Internet-Draft Spinel Protocol (Unified) June 2017
7.2.22. PROP 5382: PROP_THREAD_RLOC16_DEBUG_PASSTHRU
o Type: Read-Write
o Packed-Encoding: "b"
Allow the HOST to directly observe all IPv6 packets received by the
NCP, including ones sent to the RLOC16 address.
Default value is "false".
7.2.23. PROP 5383: PROP_THREAD_ROUTER_ROLE_ENABLED
o Type: Read-Write
o Packed-Encoding: "b"
Allow the HOST to indicate whether or not the router role is enabled.
If current role is a router, setting this property to "false" starts
a re-attach process as an end-device.
7.2.24. PROP 5384: PROP_THREAD_ROUTER_DOWNGRADE_THRESHOLD
o Type: Read-Write
o Packed-Encoding: "C"
7.2.25. PROP 5385: PROP_THREAD_ROUTER_SELECTION_JITTER
o Type: Read-Write
o Packed-Encoding: "C"
Specifies the self imposed random delay in seconds a REED waits
before registering to become an Active Router.
7.2.26. PROP 5386: PROP_THREAD_PREFERRED_ROUTER_ID
o Type: Write-Only
o Packed-Encoding: "C"
Specifies the preferred Router Id. Upon becoming a router/leader the
node attempts to use this Router Id. If the preferred Router Id is
not set or 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.
7.2.27. PROP 5387: PROP_THREAD_NEIGHBOR_TABLE
o Type: Read-Only
o Packed-Encoding: "A(t(ESLCcCbLL))"
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 53]
Internet-Draft Spinel Protocol (Unified) June 2017
Data per item is:
o "E": Extended/long address
o "S": RLOC16
o "L": Age
o "C": Link Quality In
o "c": Average RSS
o "C": Mode (bit-flags)
o "b": "true" if neighbor is a child, "false" otherwise.
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(R) 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.
7.2.31. PROP 5391: PROP_THREAD_JOINERS
o Type: Insert/Remove Only (optionally Read-Write)
o Packed-Encoding: "A(t(ULE))"
o Required capability: "CAP_THREAD_COMMISSIONER"
Data per item is:
o "U": PSKd
o "L": Timeout in seconds
o "E": Extended/long address (optional)
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 54]
Internet-Draft Spinel Protocol (Unified) June 2017
Passess Pre-Shared Key for the Device to the NCP in the commissioning
process. When the Extended address is ommited all Devices which
provided a valid PSKd are allowed to join the Thread(R) Network.
7.2.32. PROP 5392: PROP_THREAD_COMMISSIONER_ENABLED
o Type: Write only (optionally Read-Write)
o Packed-Encoding: "b"
o Required capability: "CAP_THREAD_COMMISSIONER"
Set to true to enable the native commissioner. It is mandatory
before adding the joiner to the network.
7.2.33. PROP 5393: PROP_THREAD_TMF_PROXY_ENABLED
o Type: Read-Write
o Packed-Encoding: "b"
o Required capability: "CAP_THREAD_TMF_PROXY"
Set to true to enable the TMF proxy.
7.2.34. PROP 5394: PROP_THREAD_TMF_PROXY_STREAM
o Type: Read-Write-Stream
o Packed-Encoding: "dSS"
o Required capability: "CAP_THREAD_TMF_PROXY"
Data per item is:
o "d": CoAP frame
o "S": source/destination RLOC/ALOC
o "S": source/destination port
+----------+--------+------+---------+------+
| Octects: | 2 | n | 2 | 2 |
+----------+--------+------+---------+------+
| Fields: | Length | CoAP | locator | port |
+----------+--------+------+---------+------+
This property allows the host to send and receive TMF messages from
the NCP's RLOC address and support Thread-specific border router
functions.
7.2.35. PROP 5395: PROP_THREAD_DISOVERY_SCAN_JOINER_FLAG
o Type: Read-Write
o Packed-Encoding:: "b"
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 55]
Internet-Draft Spinel Protocol (Unified) June 2017
This property specifies the value used in Thread(R) MLE Discovery
Request TLV during discovery scan operation. Default value is
"false".
7.2.36. PROP 5396: PROP_THREAD_DISCOVERY_SCAN_ENABLE_FILTERING
o Type: Read-Write
o Packed-Encoding:: "b"
This property is used to enable/disable EUI64 filtering during
discovery scan operation. Default value is "false".
7.2.37. PROP 5397: PROP_THREAD_DISCOVERY_SCAN_PANID
o Type: Read-write
o 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.
7.2.38. PROP 5398: PROP_THREAD_STEERING_DATA
o Type: Write-Only
o Packed-Encoding: "E"
o Required capability: "CAP_OOB_STEERING_DATA"
This property can be used to set the steering data for MLE Discovery
Response messages.
o All zeros to clear the steering data (indicating no steering
data).
o All 0xFFs to set the steering data (bloom filter) to accept/allow
all.
o A specific EUI64 which is then added to steering data/bloom
filter.
8. Feature: Network Save
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 & Woodyatt Expires December 24, 2017 [Page 56]
Internet-Draft Spinel Protocol (Unified) June 2017
8.1. Commands
8.1.1. CMD 9: (Host->NCP) CMD_NET_SAVE
+---------+--------+--------------+
| Octets: | 1 | 1 |
+---------+--------+--------------+
| Fields: | HEADER | CMD_NET_SAVE |
+---------+--------+--------------+
Save network state command. Saves any current network credentials
and state necessary to reconnect to the current network to non-
volatile memory.
This operation affects non-volatile memory only. The current network
information stored in volatile memory is unaffected.
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.
8.1.2. CMD 10: (Host->NCP) CMD_NET_CLEAR
+---------+--------+---------------+
| Octets: | 1 | 1 |
+---------+--------+---------------+
| Fields: | HEADER | CMD_NET_CLEAR |
+---------+--------+---------------+
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.
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 always available independent of the value of
"CAP_NET_SAVE" capability.
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 57]
Internet-Draft Spinel Protocol (Unified) June 2017
8.1.3. CMD 11: (Host->NCP) CMD_NET_RECALL
+---------+--------+----------------+
| Octets: | 1 | 1 |
+---------+--------+----------------+
| Fields: | HEADER | CMD_NET_RECALL |
+---------+--------+----------------+
Recall saved network state command. Recalls any previously saved
network credentials and state previously stored by "CMD_NET_SAVE"
from non-volatile memory.
This command will typically generated several unsolicited property
updates as the network state is loaded. At the conclusion of
loading, the authoritative 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.
9. Feature: Host Buffer Offload
The memory on an NCP may be much more limited than the memory on the
host processor. In such situations, it is sometimes useful for the
NCP to offload buffers to the host processor temporarily so that it
can perform other operations.
Host buffer offload is an optional NCP capability that, when present,
allows the NCP to store data buffers on the host processor that can
be recalled at a later time.
The presence of this feature can be detected by the host by checking
for the presence of the "CAP_HBO" capability in "PROP_CAPS".
9.1. Commands
9.1.1. CMD 12: (NCP->Host) CMD_HBO_OFFLOAD
o Argument-Encoding: "LscD"
* "OffloadId": 32-bit unique block identifier
* "Expiration": In seconds-from-now
* "Priority": Critical, High, Medium, Low
* "Data": Data to offload
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 58]
Internet-Draft Spinel Protocol (Unified) June 2017
9.1.2. CMD 13: (NCP->Host) CMD_HBO_RECLAIM
o Argument-Encoding: "Lb"
* "OffloadId": 32-bit unique block identifier
* "KeepAfterReclaim": If not set to true, the block will be
dropped by the host after it is sent to the NCP.
9.1.3. CMD 14: (NCP->Host) CMD_HBO_DROP
o Argument-Encoding: "L"
* "OffloadId": 32-bit unique block identifier
9.1.4. CMD 15: (Host->NCP) CMD_HBO_OFFLOADED
o Argument-Encoding: "Li"
* "OffloadId": 32-bit unique block identifier
* "Status": Status code for the result of the operation.
9.1.5. CMD 16: (Host->NCP) CMD_HBO_RECLAIMED
o Argument-Encoding: "LiD"
* "OffloadId": 32-bit unique block identifier
* "Status": Status code for the result of the operation.
* "Data": Data that was previously offloaded (if any)
9.1.6. CMD 17: (Host->NCP) CMD_HBO_DROPPED
o Argument-Encoding: "Li"
* "OffloadId": 32-bit unique block identifier
* "Status": Status code for the result of the operation.
9.2. Properties
9.2.1. PROP 10: PROP_HBO_MEM_MAX
o Type: Read-Write
o Packed-Encoding: "L"
+---------+--------------------+
| Octets: | 4 |
+---------+--------------------+
| Fields: | "PROP_HBO_MEM_MAX" |
+---------+--------------------+
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 59]
Internet-Draft Spinel Protocol (Unified) June 2017
Describes the number of bytes that may be offloaded from the NCP to
the host. Default value is zero, so this property must be set by the
host to a non-zero value before the NCP will begin offloading blocks.
This value is encoded as an unsigned 32-bit integer.
This property is only available if the "CAP_HBO" capability is
present in "PROP_CAPS".
9.2.2. PROP 11: PROP_HBO_BLOCK_MAX
o Type: Read-Write
o Packed-Encoding: "S"
+---------+----------------------+
| Octets: | 2 |
+---------+----------------------+
| Fields: | "PROP_HBO_BLOCK_MAX" |
+---------+----------------------+
Describes the number of blocks that may be offloaded from the NCP to
the host. Default value is 32. Setting this value to zero will
cause host block offload to be effectively disabled.
This value is encoded as an unsigned 16-bit integer.
This property is only available if the "CAP_HBO" capability is
present in "PROP_CAPS".
10. Feature: Jam Detection
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".
10.1. Properties
10.1.1. PROP 4608: PROP_JAM_DETECT_ENABLE
o Type: Read-Write
o Packed-Encoding: "b"
o Default Value: false
o REQUIRED for "CAP_JAM_DETECT"
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 60]
Internet-Draft Spinel Protocol (Unified) June 2017
+---------+--------------------------+
| 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".
10.1.2. PROP 4609: PROP_JAM_DETECTED
o Type: Read-Only
o Packed-Encoding: "b"
o 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".
10.1.3. PROP 4610: PROP_JAM_DETECT_RSSI_THRESHOLD
o Type: Read-Write
o Packed-Encoding: "c"
o Units: dBm
o Default Value: Implementation-specific
o 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.
10.1.4. PROP 4611: PROP_JAM_DETECT_WINDOW
o Type: Read-Write
o Packed-Encoding: "c"
o Units: Seconds (1-64)
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 61]
Internet-Draft Spinel Protocol (Unified) June 2017
o Default Value: Implementation-specific
o RECOMMENDED for "CAP_JAM_DETECT"
This parameter describes the window period for signal jamming
detection.
10.1.5. PROP 4612: PROP_JAM_DETECT_BUSY
o Type: Read-Write
o Packed-Encoding: "i"
o Units: Seconds (1-64)
o Default Value: Implementation-specific
o 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.
10.1.6. PROP 4613: PROP_JAM_DETECT_HISTORY_BITMAP
o Type: Read-Only
o Packed-Encoding: "LL"
o Default Value: Implementation-specific
o RECOMMENDED for "CAP_JAM_DETECT"
This value provides information about current state of jamming
detection module for monitoring/debugging purpose. It returns a
64-bit value where each bit corresponds to one second interval
starting with bit 0 for the most recent interval and bit 63 for the
oldest intervals (63 sec earlier). The bit is set to 1 if the
jamming detection module observed/detected high signal level during
the corresponding one second interval. The value is read-only and is
encoded as two "L" (uint32) values in little-endian format (first "L"
(uint32) value gives the lower bits corresponding to more recent
history).
11. Feature: GPIO Access
This feature allows the host to have control over some or all of the
GPIO pins on the NCP. The host can determine which GPIOs are
available by examining "PROP_GPIO_CONFIG", described below. This API
supports a maximum of 256 individual GPIO pins.
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 62]
Internet-Draft Spinel Protocol (Unified) June 2017
Support for this feature can be determined by the presence of
"CAP_GPIO".
11.1. Properties
11.1.1. PROP 4096: PROP_GPIO_CONFIG
o Argument-Encoding: "A(t(CCU))"
o Type: Read-write (Writable only using "CMD_PROP_VALUE_INSERT",
Section 4.5)
An array of structures which contain the following fields:
o "C": GPIO Number
o "C": GPIO Configuration Flags
o "U": Human-readable GPIO name
GPIOs which do not have a corresponding entry are not supported.
The configuration parameter contains the configuration flags for the
GPIO:
0 1 2 3 4 5 6 7
+---+---+---+---+---+---+---+---+
|DIR|PUP|PDN|TRIGGER| RESERVED |
+---+---+---+---+---+---+---+---+
|O/D|
+---+
o "DIR": Pin direction. Clear (0) for input, set (1) for output.
o "PUP": Pull-up enabled flag.
o "PDN"/"O/D": Flag meaning depends on pin direction:
* Input: Pull-down enabled.
* Output: Output is an open-drain.
o "TRIGGER": Enumeration describing how pin changes generate
asynchronous notification commands (TBD) from the NCP to the host.
* 0: Feature disabled for this pin
* 1: Trigger on falling edge
* 2: Trigger on rising edge
* 3: Trigger on level change
o "RESERVED": Bits reserved for future use. Always cleared to zero
and ignored when read.
As an optional feature, the configuration of individual pins may be
modified using the "CMD_PROP_VALUE_INSERT" command. Only the GPIO
number and flags fields MUST be present, the GPIO name (if present)
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 63]
Internet-Draft Spinel Protocol (Unified) June 2017
would be ignored. This command can only be used to modify the
configuration of GPIOs which are already exposed---it cannot be used
by the host to add addional GPIOs.
11.1.2. PROP 4098: PROP_GPIO_STATE
o Type: Read-Write
Contains a bit field identifying the state of the GPIOs. The length
of the data associated with these properties depends on the number of
GPIOs. If you have 10 GPIOs, you'd have two bytes. GPIOs are
numbered from most significant bit to least significant bit, so 0x80
is GPIO 0, 0x40 is GPIO 1, etc.
For GPIOs configured as inputs:
o "CMD_PROP_VAUE_GET": The value of the associated bit describes the
logic level read from the pin.
o "CMD_PROP_VALUE_SET": The value of the associated bit is ignored
for these pins.
For GPIOs configured as outputs:
o "CMD_PROP_VAUE_GET": The value of the associated bit is
implementation specific.
o "CMD_PROP_VALUE_SET": The value of the associated bit determines
the new logic level of the output. If this pin is configured as
an open-drain, setting the associated bit to 1 will cause the pin
to enter a Hi-Z state.
For GPIOs which are not specified in "PROP_GPIO_CONFIG":
o "CMD_PROP_VAUE_GET": The value of the associated bit is
implementation specific.
o "CMD_PROP_VALUE_SET": The value of the associated bit MUST be
ignored by the NCP.
When writing, unspecified bits are assumed to be zero.
11.1.3. PROP 4099: PROP_GPIO_STATE_SET
o Type: Write-only
Allows for the state of various output GPIOs to be set without
affecting other GPIO states. Contains a bit field identifying the
output GPIOs that should have their state set to 1.
Quattlebaum & Woodyatt Expires December 24, 2017 [Page 64]
Internet-Draft Spinel Protocol (Unified) June 2017
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.
11.1.4. PROP 4100: PROP_GPIO_STATE_CLEAR
o Type: Write-only
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.
12. Feature: True Random Number Generation
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 & Woodyatt Expires December 24, 2017 [Page 65]
Internet-Draft Spinel Protocol (Unified) June 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 & Woodyatt Expires December 24, 2017 [Page 66]
Internet-Draft Spinel Protocol (Unified) June 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
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.
14. References
14.1. URIs
[1] https://www.w3.org/TR/exi/#encodingUnsignedInteger
[2] http://reveng.sourceforge.net/crc-catalogue/16.htm#crc.cat.kermit
[3] https://github.com/miekg/mmark
[4] http://xml2rfc.ietf.org/