



                                                          R. Quattlebaum
                                                             j. woodyatt
                                                         Nest Labs, Inc.
                                                             May 1, 2017


                    Spinel Host-Controller Protocol
              draft-rquattle-spinel-unified-86157e99-dirty

Abstract

   This document describes a general management protocol for enabling a
   host device to communicate with and manage a Network Control
   Processor (NCP).

   While initially designed to support Thread-based NCPs, the NCP
   protocol has been designed with a layered approach that allows it to
   be easily adapted to other network technologies in the future.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   This document is not an Internet Standards Track specification; it is
   published for informational purposes.

   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.

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 publication of this document.
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.











Quattlebaum & woodyatt  Expires November 2, 2017                [Page 1]

                    Spinel Protocol (86157e99-dirty)            May 2017


Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   6
     1.1.  About this Draft  . . . . . . . . . . . . . . . . . . . .   6
       1.1.1.  Renumbering . . . . . . . . . . . . . . . . . . . . .   7
       1.1.2.  Spinel as Application API . . . . . . . . . . . . . .   7
       1.1.3.  Privileged Commands and Properties  . . . . . . . . .   8
     1.2.  Property Overview . . . . . . . . . . . . . . . . . . . .   9
       1.2.1.  Property Methods  . . . . . . . . . . . . . . . . . .   9
       1.2.2.  Property Types  . . . . . . . . . . . . . . . . . . .   9
   2.  Frame Format  . . . . . . . . . . . . . . . . . . . . . . . .  11
     2.1.  Header Format . . . . . . . . . . . . . . . . . . . . . .  11
       2.1.1.  FLG: Flag . . . . . . . . . . . . . . . . . . . . . .  11
       2.1.2.  NLI: Network Link Identifier  . . . . . . . . . . . .  12
       2.1.3.  TID: Transaction Identifier . . . . . . . . . . . . .  12
       2.1.4.  Command Identifier (CMD)  . . . . . . . . . . . . . .  12
       2.1.5.  Command Payload (Optional)  . . . . . . . . . . . . .  13
   3.  Data Packing  . . . . . . . . . . . . . . . . . . . . . . . .  13
     3.1.  Primitive Types . . . . . . . . . . . . . . . . . . . . .  13
     3.2.  Packed Unsigned Integer . . . . . . . . . . . . . . . . .  14
     3.3.  Data Blobs  . . . . . . . . . . . . . . . . . . . . . . .  15
     3.4.  Structured Data . . . . . . . . . . . . . . . . . . . . .  16
     3.5.  Arrays  . . . . . . . . . . . . . . . . . . . . . . . . .  16
   4.  Commands  . . . . . . . . . . . . . . . . . . . . . . . . . .  17
     4.1.  CMD 0: (Host->NCP) CMD_NOOP . . . . . . . . . . . . . . .  17
     4.2.  CMD 1: (Host->NCP) CMD_RESET  . . . . . . . . . . . . . .  17
     4.3.  CMD 2: (Host->NCP) CMD_PROP_VALUE_GET . . . . . . . . . .  17
     4.4.  CMD 3: (Host->NCP) CMD_PROP_VALUE_SET . . . . . . . . . .  18
     4.5.  CMD 4: (Host->NCP) CMD_PROP_VALUE_INSERT  . . . . . . . .  18
     4.6.  CMD 5: (Host->NCP) CMD_PROP_VALUE_REMOVE  . . . . . . . .  19
     4.7.  CMD 6: (NCP->Host) CMD_PROP_VALUE_IS  . . . . . . . . . .  20
     4.8.  CMD 7: (NCP->Host) CMD_PROP_VALUE_INSERTED  . . . . . . .  20
     4.9.  CMD 8: (NCP->Host) CMD_PROP_VALUE_REMOVED . . . . . . . .  21
     4.10. CMD 18: (Host->NCP) CMD_PEEK  . . . . . . . . . . . . . .  21
     4.11. CMD 19: (NCP->Host) CMD_PEEK_RET  . . . . . . . . . . . .  22
     4.12. CMD 20: (Host->NCP) CMD_POKE  . . . . . . . . . . . . . .  22
     4.13. CMD 21: (Host->NCP) CMD_PROP_VALUE_MULTI_GET  . . . . . .  22
     4.14. CMD 22: (Host->NCP) CMD_PROP_VALUE_MULTI_SET  . . . . . .  23
     4.15. CMD 23: (NCP->Host) CMD_PROP_VALUES_ARE . . . . . . . . .  24
   5.  Properties  . . . . . . . . . . . . . . . . . . . . . . . . .  24
     5.1.  Property Sections . . . . . . . . . . . . . . . . . . . .  25
     5.2.  Core Properties . . . . . . . . . . . . . . . . . . . . .  25
       5.2.1.  PROP 0: PROP_LAST_STATUS  . . . . . . . . . . . . . .  25
       5.2.2.  PROP 1: PROP_PROTOCOL_VERSION . . . . . . . . . . . .  26
       5.2.3.  PROP 2: PROP_NCP_VERSION  . . . . . . . . . . . . . .  27
       5.2.4.  PROP 3: PROP_INTERFACE_TYPE . . . . . . . . . . . . .  27
       5.2.5.  PROP 4: PROP_INTERFACE_VENDOR_ID  . . . . . . . . . .  28
       5.2.6.  PROP 5: PROP_CAPS . . . . . . . . . . . . . . . . . .  28



Quattlebaum & woodyatt  Expires November 2, 2017                [Page 2]

                    Spinel Protocol (86157e99-dirty)            May 2017


       5.2.7.  PROP 6: PROP_INTERFACE_COUNT  . . . . . . . . . . . .  29
       5.2.8.  PROP 7: PROP_POWER_STATE  . . . . . . . . . . . . . .  30
       5.2.9.  PROP 8: PROP_HWADDR . . . . . . . . . . . . . . . . .  30
       5.2.10. PROP 9: PROP_LOCK . . . . . . . . . . . . . . . . . .  31
     5.3.  Stream Properties . . . . . . . . . . . . . . . . . . . .  31
       5.3.1.  PROP 112: PROP_STREAM_DEBUG . . . . . . . . . . . . .  31
       5.3.2.  PROP 113: PROP_STREAM_RAW . . . . . . . . . . . . . .  32
       5.3.3.  PROP 114: PROP_STREAM_NET . . . . . . . . . . . . . .  33
       5.3.4.  PROP 114: PROP_STREAM_NET_INSECURE  . . . . . . . . .  34
     5.4.  PHY Properties  . . . . . . . . . . . . . . . . . . . . .  35
       5.4.1.  PROP 32: PROP_PHY_ENABLED . . . . . . . . . . . . . .  35
       5.4.2.  PROP 33: PROP_PHY_CHAN  . . . . . . . . . . . . . . .  35
       5.4.3.  PROP 34: PROP_PHY_CHAN_SUPPORTED  . . . . . . . . . .  35
       5.4.4.  PROP 35: PROP_PHY_FREQ  . . . . . . . . . . . . . . .  35
       5.4.5.  PROP 36: PROP_PHY_CCA_THRESHOLD . . . . . . . . . . .  35
       5.4.6.  PROP 37: PROP_PHY_TX_POWER  . . . . . . . . . . . . .  36
       5.4.7.  PROP 38: PROP_PHY_RSSI  . . . . . . . . . . . . . . .  36
     5.5.  MAC Properties  . . . . . . . . . . . . . . . . . . . . .  36
       5.5.1.  PROP 48: PROP_MAC_SCAN_STATE  . . . . . . . . . . . .  36
       5.5.2.  PROP 49: PROP_MAC_SCAN_MASK . . . . . . . . . . . . .  37
       5.5.3.  PROP 50: PROP_MAC_SCAN_PERIOD . . . . . . . . . . . .  37
       5.5.4.  PROP 51: PROP_MAC_SCAN_BEACON . . . . . . . . . . . .  37
       5.5.5.  PROP 52: PROP_MAC_15_4_LADDR  . . . . . . . . . . . .  38
       5.5.6.  PROP 53: PROP_MAC_15_4_SADDR  . . . . . . . . . . . .  38
       5.5.7.  PROP 54: PROP_MAC_15_4_PANID  . . . . . . . . . . . .  38
       5.5.8.  PROP 55: PROP_MAC_RAW_STREAM_ENABLED  . . . . . . . .  38
       5.5.9.  PROP 56: PROP_MAC_PROMISCUOUS_MODE  . . . . . . . . .  38
       5.5.10. PROP 4864: PROP_MAC_WHITELIST . . . . . . . . . . . .  39
       5.5.11. PROP 4865: PROP_MAC_WHITELIST_ENABLED . . . . . . . .  39
       5.5.12. PROP 4867: SPINEL_PROP_MAC_SRC_MATCH_ENABLED  . . . .  39
       5.5.13. PROP 4868: SPINEL_PROP_MAC_SRC_MATCH_SHORT_ADDRESSES   40
       5.5.14. PROP 4869:
               SPINEL_PROP_MAC_SRC_MATCH_EXTENDED_ADDRESSES  . . . .  40
     5.6.  NET Properties  . . . . . . . . . . . . . . . . . . . . .  40
       5.6.1.  PROP 64: PROP_NET_SAVED . . . . . . . . . . . . . . .  40
       5.6.2.  PROP 65: PROP_NET_IF_UP . . . . . . . . . . . . . . .  40
       5.6.3.  PROP 66: PROP_NET_STACK_UP  . . . . . . . . . . . . .  40
       5.6.4.  PROP 67: PROP_NET_ROLE  . . . . . . . . . . . . . . .  41
       5.6.5.  PROP 68: PROP_NET_NETWORK_NAME  . . . . . . . . . . .  41
       5.6.6.  PROP 69: PROP_NET_XPANID  . . . . . . . . . . . . . .  41
       5.6.7.  PROP 70: PROP_NET_MASTER_KEY  . . . . . . . . . . . .  41
       5.6.8.  PROP 71: PROP_NET_KEY_SEQUENCE_COUNTER  . . . . . . .  41
       5.6.9.  PROP 72: PROP_NET_PARTITION_ID  . . . . . . . . . . .  41
       5.6.10. PROP 73: PROP_NET_REQUIRE_JOIN_EXISTING . . . . . . .  41
       5.6.11. PROP 74: PROP_NET_KEY_SWITCH_GUARDTIME  . . . . . . .  42
       5.6.12. PROP 75: PROP_NET_PSKC  . . . . . . . . . . . . . . .  42
     5.7.  IPv6 Properties . . . . . . . . . . . . . . . . . . . . .  42
       5.7.1.  PROP 96: PROP_IPV6_LL_ADDR  . . . . . . . . . . . . .  42



Quattlebaum & woodyatt  Expires November 2, 2017                [Page 3]

                    Spinel Protocol (86157e99-dirty)            May 2017


       5.7.2.  PROP 97: PROP_IPV6_ML_ADDR  . . . . . . . . . . . . .  42
       5.7.3.  PROP 98: PROP_IPV6_ML_PREFIX  . . . . . . . . . . . .  42
       5.7.4.  PROP 99: PROP_IPV6_ADDRESS_TABLE  . . . . . . . . . .  42
       5.7.5.  PROP 101: PROP_IPv6_ICMP_PING_OFFLOAD . . . . . . . .  43
     5.8.  Debug Properties  . . . . . . . . . . . . . . . . . . . .  43
       5.8.1.  PROP 16384: SPINEL_PROP_DEBUG_TEST_ASSERT . . . . . .  43
       5.8.2.  PROP 16385: SPINEL_PROP_DEBUG_NCP_LOG_LEVEL . . . . .  43
   6.  Status Codes  . . . . . . . . . . . . . . . . . . . . . . . .  44
   7.  Technology: Thread  . . . . . . . . . . . . . . . . . . . . .  45
     7.1.  Thread Capabilities . . . . . . . . . . . . . . . . . . .  45
     7.2.  Thread Properties . . . . . . . . . . . . . . . . . . . .  46
       7.2.1.  PROP 80: PROP_THREAD_LEADER_ADDR  . . . . . . . . . .  46
       7.2.2.  PROP 81: PROP_THREAD_PARENT . . . . . . . . . . . . .  46
       7.2.3.  PROP 82: PROP_THREAD_CHILD_TABLE  . . . . . . . . . .  46
       7.2.4.  PROP 83: PROP_THREAD_LEADER_RID . . . . . . . . . . .  46
       7.2.5.  PROP 84: PROP_THREAD_LEADER_WEIGHT  . . . . . . . . .  46
       7.2.6.  PROP 85: PROP_THREAD_LOCAL_LEADER_WEIGHT  . . . . . .  47
       7.2.7.  PROP 86: PROP_THREAD_NETWORK_DATA . . . . . . . . . .  47
       7.2.8.  PROP 87: PROP_THREAD_NETWORK_DATA_VERSION . . . . . .  47
       7.2.9.  PROP 88: PROP_THREAD_STABLE_NETWORK_DATA  . . . . . .  47
       7.2.10. PROP 89: PROP_THREAD_STABLE_NETWORK_DATA_VERSION  . .  47
       7.2.11. PROP 90: PROP_THREAD_ON_MESH_NETS . . . . . . . . . .  47
       7.2.12. PROP 91: PROP_THREAD_LOCAL_ROUTES . . . . . . . . . .  48
       7.2.13. PROP 92: PROP_THREAD_ASSISTING_PORTS  . . . . . . . .  48
       7.2.14. PROP 93: PROP_THREAD_ALLOW_LOCAL_NET_DATA_CHANGE  . .  48
       7.2.15. PROP 94: PROP_THREAD_MODE . . . . . . . . . . . . . .  48
       7.2.16. PROP 5376: PROP_THREAD_CHILD_TIMEOUT  . . . . . . . .  48
       7.2.17. PROP 5377: PROP_THREAD_RLOC16 . . . . . . . . . . . .  48
       7.2.18. PROP 5378: PROP_THREAD_ROUTER_UPGRADE_THRESHOLD . . .  49
       7.2.19. PROP 5379: PROP_THREAD_CONTEXT_REUSE_DELAY  . . . . .  49
       7.2.20. PROP 5380: PROP_THREAD_NETWORK_ID_TIMEOUT . . . . . .  49
       7.2.21. PROP 5381: PROP_THREAD_ACTIVE_ROUTER_IDS  . . . . . .  49
       7.2.22. PROP 5382: PROP_THREAD_RLOC16_DEBUG_PASSTHRU  . . . .  49
       7.2.23. PROP 5383: PROP_THREAD_ROUTER_ROLE_ENABLED  . . . . .  49
       7.2.24. PROP 5384: PROP_THREAD_ROUTER_DOWNGRADE_THRESHOLD . .  50
       7.2.25. PROP 5385: PROP_THREAD_ROUTER_SELECTION_JITTER  . . .  50
       7.2.26. PROP 5386: PROP_THREAD_PREFERRED_ROUTER_ID  . . . . .  50
       7.2.27. PROP 5387: PROP_THREAD_NEIGHBOR_TABLE . . . . . . . .  50
       7.2.28. PROP 5388: PROP_THREAD_CHILD_COUNT_MAX  . . . . . . .  50
       7.2.29. PROP 5389: PROP_THREAD_LEADER_NETWORK_DATA  . . . . .  51
       7.2.30. PROP 5390: PROP_THREAD_STABLE_LEADER_NETWORK_DATA . .  51
       7.2.31. PROP 5391: PROP_THREAD_JOINERS  . . . . . . . . . . .  51
       7.2.32. PROP 5392: PROP_THREAD_COMMISSIONER_ENABLED . . . . .  51
       7.2.33. PROP 5393: PROP_THREAD_BA_PROXY_ENABLED . . . . . . .  51
       7.2.34. PROP 5394: PROP_THREAD_BA_PROXY_STREAM  . . . . . . .  52
   8.  Feature: Network Save . . . . . . . . . . . . . . . . . . . .  52
     8.1.  Commands  . . . . . . . . . . . . . . . . . . . . . . . .  52
       8.1.1.  CMD 9: (Host->NCP) CMD_NET_SAVE . . . . . . . . . . .  52



Quattlebaum & woodyatt  Expires November 2, 2017                [Page 4]

                    Spinel Protocol (86157e99-dirty)            May 2017


       8.1.2.  CMD 10: (Host->NCP) CMD_NET_CLEAR . . . . . . . . . .  53
       8.1.3.  CMD 11: (Host->NCP) CMD_NET_RECALL  . . . . . . . . .  53
   9.  Feature: Host Buffer Offload  . . . . . . . . . . . . . . . .  54
     9.1.  Commands  . . . . . . . . . . . . . . . . . . . . . . . .  54
       9.1.1.  CMD 12: (NCP->Host) CMD_HBO_OFFLOAD . . . . . . . . .  54
       9.1.2.  CMD 13: (NCP->Host) CMD_HBO_RECLAIM . . . . . . . . .  54
       9.1.3.  CMD 14: (NCP->Host) CMD_HBO_DROP  . . . . . . . . . .  54
       9.1.4.  CMD 15: (Host->NCP) CMD_HBO_OFFLOADED . . . . . . . .  55
       9.1.5.  CMD 16: (Host->NCP) CMD_HBO_RECLAIMED . . . . . . . .  55
       9.1.6.  CMD 17: (Host->NCP) CMD_HBO_DROPPED . . . . . . . . .  55
     9.2.  Properties  . . . . . . . . . . . . . . . . . . . . . . .  55
       9.2.1.  PROP 10: PROP_HBO_MEM_MAX . . . . . . . . . . . . . .  55
       9.2.2.  PROP 11: PROP_HBO_BLOCK_MAX . . . . . . . . . . . . .  56
   10. Feature: Jam Detection  . . . . . . . . . . . . . . . . . . .  56
     10.1.  Properties . . . . . . . . . . . . . . . . . . . . . . .  56
       10.1.1.  PROP 4608: PROP_JAM_DETECT_ENABLE  . . . . . . . . .  56
       10.1.2.  PROP 4609: PROP_JAM_DETECTED . . . . . . . . . . . .  57
       10.1.3.  PROP 4610: PROP_JAM_DETECT_RSSI_THRESHOLD  . . . . .  57
       10.1.4.  PROP 4611: PROP_JAM_DETECT_WINDOW  . . . . . . . . .  57
       10.1.5.  PROP 4612: PROP_JAM_DETECT_BUSY  . . . . . . . . . .  58
       10.1.6.  PROP 4613: SPINEL_PROP_JAM_DETECT_HISTORY_BITMAP . .  58
   11. Feature: GPIO Access  . . . . . . . . . . . . . . . . . . . .  58
     11.1.  Properties . . . . . . . . . . . . . . . . . . . . . . .  59
       11.1.1.  PROP 4096: PROP_GPIO_CONFIG  . . . . . . . . . . . .  59
       11.1.2.  PROP 4098: PROP_GPIO_STATE . . . . . . . . . . . . .  60
       11.1.3.  PROP 4099: PROP_GPIO_STATE_SET . . . . . . . . . . .  60
       11.1.4.  PROP 4100: PROP_GPIO_STATE_CLEAR . . . . . . . . . .  61
   12. Feature: True Random Number Generation  . . . . . . . . . . .  61
     12.1.  Properties . . . . . . . . . . . . . . . . . . . . . . .  61
       12.1.1.  PROP 4101: PROP_TRNG_32  . . . . . . . . . . . . . .  61
       12.1.2.  PROP 4102: PROP_TRNG_128 . . . . . . . . . . . . . .  62
       12.1.3.  PROP 4103: PROP_TRNG_RAW_32  . . . . . . . . . . . .  62
   13. Security Considerations . . . . . . . . . . . . . . . . . . .  63
     13.1.  Raw Application Access . . . . . . . . . . . . . . . . .  63
     14.1.  URIs . . . . . . . . . . . . . . . . . . . . . . . . . .  63
   Appendix A.  Framing Protocol . . . . . . . . . . . . . . . . . .  63
     A.1.  UART Recommendations  . . . . . . . . . . . . . . . . . .  63
       A.1.1.  UART Bit Rate Detection . . . . . . . . . . . . . . .  64
       A.1.2.  HDLC-Lite . . . . . . . . . . . . . . . . . . . . . .  64
     A.2.  SPI Recommendations . . . . . . . . . . . . . . . . . . .  65
       A.2.1.  SPI Framing Protocol  . . . . . . . . . . . . . . . .  66
     A.3.  I^2C Recommendations  . . . . . . . . . . . . . . . . . .  68
     A.4.  Native USB Recommendations  . . . . . . . . . . . . . . .  68
   Appendix B.  Test Vectors . . . . . . . . . . . . . . . . . . . .  68
     B.1.  Test Vector: Packed Unsigned Integer  . . . . . . . . . .  68
     B.2.  Test Vector: Reset Command  . . . . . . . . . . . . . . .  68
     B.3.  Test Vector: Reset Notification . . . . . . . . . . . . .  69
     B.4.  Test Vector: Scan Beacon  . . . . . . . . . . . . . . . .  69



Quattlebaum & woodyatt  Expires November 2, 2017                [Page 5]

                    Spinel Protocol (86157e99-dirty)            May 2017


     B.5.  Test Vector: Inbound IPv6 Packet  . . . . . . . . . . . .  69
     B.6.  Test Vector: Outbound IPv6 Packet . . . . . . . . . . . .  70
     B.7.  Test Vector: Fetch list of on-mesh networks . . . . . . .  70
     B.8.  Test Vector: Returned list of on-mesh networks  . . . . .  70
     B.9.  Test Vector: Adding an on-mesh network  . . . . . . . . .  70
     B.10. Test Vector: Insertion notification of an on-mesh network  71
     B.11. Test Vector: Removing a local on-mesh network . . . . . .  71
     B.12. Test Vector: Removal notification of an on-mesh network .  72
   Appendix C.  Example Sessions . . . . . . . . . . . . . . . . . .  72
     C.1.  NCP Initialization  . . . . . . . . . . . . . . . . . . .  72
     C.2.  Attaching to a network  . . . . . . . . . . . . . . . . .  73
     C.3.  Successfully joining a pre-existing network . . . . . . .  73
     C.4.  Unsuccessfully joining a pre-existing network . . . . . .  74
     C.5.  Detaching from a network  . . . . . . . . . . . . . . . .  74
     C.6.  Attaching to a saved network  . . . . . . . . . . . . . .  75
     C.7.  NCP Software Reset  . . . . . . . . . . . . . . . . . . .  75
     C.8.  Adding an on-mesh prefix  . . . . . . . . . . . . . . . .  75
     C.9.  Entering low-power modes  . . . . . . . . . . . . . . . .  75
     C.10. Sniffing raw packets  . . . . . . . . . . . . . . . . . .  75
   Appendix D.  Glossary . . . . . . . . . . . . . . . . . . . . . .  76
   Appendix E.  Acknowledgments  . . . . . . . . . . . . . . . . . .  77
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  78

1.  Introduction

   This Network Control Processor (NCP) protocol was designed to enable
   a host device to communicate with and manage a NCP while also
   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




Quattlebaum & woodyatt  Expires November 2, 2017                [Page 6]

                    Spinel Protocol (86157e99-dirty)            May 2017


   haven't yet been fully specified, as well as some of the impetus for
   the current design.

1.1.1.  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.

   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.

1.1.2.  Spinel as Application API

   The current primary host driver implementation is wpantund [1].
   wpantund manages the NCP using the Spinel protocol and provides a
   management API for the application using D-Bus [2] IPC.

   However, some thought has been given to the idea of having a host
   driver daemon which uses Spinel directly as the management API.  You
   would have user-space daemon similar to wpantund which would
   communicate directly with the NCP.  Using Unix Domain Sockets,
   applications could connect to the daemon by opening a special socket
   file.  The protocol for that socket might be (for example) HDLC-Lite-



Quattlebaum & woodyatt  Expires November 2, 2017                [Page 7]

                    Spinel Protocol (86157e99-dirty)            May 2017


   encoded (Appendix A.1.2) spinel frames, as if the application were
   talking directly to the NCP.

   Applications aren't necessarily interested in everything that an NCP
   would normally send out unsolicited, so a mechanism for specifying
   which properties should be listened to would need to be defined.
   This mechanism would not be implemented by the NCP but would instead
   be implemented by the daemon to control which notification packets
   need to be directed where.

   In the event of transaction ID collisions, the daemon would
   transparently renumber spinel frames so as to not cause TID
   collisions.

   Since there can be more than one application that is using the API at
   a time, the "PROP_LOCK" property (Section 5.2.10) would be used to
   ensure exclusive access to the NCP by an application.  Only one
   process would be allowed to enable the lock at a time.

   Such a IPC mechanism would be desirable because it is, from a spinel
   perspective, future proof.  New features can be added and new
   properties assigned and the IPC protocol would not need to be
   extended to support them.  It is also simple and has no external
   dependencies other than unix domain sockets.

   Security is obviously paramount in a system like this, so a great
   deal of care should be taken to make sure that certain commands and
   properties cannot be executed or changed without the appropriate
   privileges.

1.1.3.  Privileged Commands and Properties

   The idea here is that some commands should be considered
   "privileged", and actively prevented from letting normal applications
   access them.  This is important if the IPC protocol between the
   application and the NCP is Spinel.

   Examples of such privileged commands would be debugging commands like
   "peek" or "poke", properties which control bootloader behavior, or
   changing factory-specified constants.  These commands should have
   some attribute about them that can be easily filtered to prevent
   applications from using issuing them directly to the NCP.

   This would likely be implemented as a part of the renumbering effort
   (Section 1.1.1).






Quattlebaum & woodyatt  Expires November 2, 2017                [Page 8]

                    Spinel Protocol (86157e99-dirty)            May 2017


1.2.  Property Overview

   Spinel is largely a property-based protocol, with a property defined
   for every attribute that needs to be set, changed, or known by the
   host.  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 change an additional
   property.

   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).

1.2.1.  Property Methods

   Properties may support one or more of the following methods:

   o  "VALUE_GET"
   o  "VALUE_SET"
   o  "VALUE_INSERT"
   o  "VALUE_REMOVE"

   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"
   o  "VALUE_INSERTED"
   o  "VALUE_REMOVED"

1.2.2.  Property Types

   Conceptually, there are three different types of properties:

   o  Single-value properties
   o  Multiple-value (Array) properties
   o  Stream properties





Quattlebaum & woodyatt  Expires November 2, 2017                [Page 9]

                    Spinel Protocol (86157e99-dirty)            May 2017


1.2.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 a unsigned 8-bit integer)
   o  Network name (Represented as a UTF-8 encoded string)
   o  802.15.4 PAN ID (Represented as a unsigned 16-bit integer)

   The valid operations on these sorts of properties are "GET" and
   "SET".

1.2.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.

1.2.2.3.  Stream Properties

   Stream properties are special properties representing streams of
   data.  Examples would be:

   o  Network packet stream (Section 5.3.3)
   o  Raw packet stream (Section 5.3.2)
   o  Debug message stream (Section 5.3.1)
   o  Network Beacon stream (Section 5.5.4)



Quattlebaum & woodyatt  Expires November 2, 2017               [Page 10]

                    Spinel Protocol (86157e99-dirty)            May 2017


   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.

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]

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.




Quattlebaum & woodyatt  Expires November 2, 2017               [Page 11]

                    Spinel Protocol (86157e99-dirty)            May 2017


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.

          +-----------------------+----------------------------+
          |       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    |
          +-----------------------+----------------------------+







Quattlebaum & woodyatt  Expires November 2, 2017               [Page 12]

                    Spinel Protocol (86157e99-dirty)            May 2017


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.

3.1.  Primitive Types












Quattlebaum & woodyatt  Expires November 2, 2017               [Page 13]

                    Spinel Protocol (86157e99-dirty)            May 2017


   +----------+----------------------+---------------------------------+
   |   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 [3], except that we limit the maximum value to the
   largest value that can be encoded into three bytes(2,097,151).





Quattlebaum & woodyatt  Expires November 2, 2017               [Page 14]

                    Spinel Protocol (86157e99-dirty)            May 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 November 2, 2017               [Page 15]

                    Spinel Protocol (86157e99-dirty)            May 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 November 2, 2017               [Page 16]

                    Spinel Protocol (86157e99-dirty)            May 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 November 2, 2017               [Page 17]

                    Spinel Protocol (86157e99-dirty)            May 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 November 2, 2017               [Page 18]

                    Spinel Protocol (86157e99-dirty)            May 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 November 2, 2017               [Page 19]

                    Spinel Protocol (86157e99-dirty)            May 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 November 2, 2017               [Page 20]

                    Spinel Protocol (86157e99-dirty)            May 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 November 2, 2017               [Page 21]

                    Spinel Protocol (86157e99-dirty)            May 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 November 2, 2017               [Page 22]

                    Spinel Protocol (86157e99-dirty)            May 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 November 2, 2017               [Page 23]

                    Spinel Protocol (86157e99-dirty)            May 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

   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:









Quattlebaum & woodyatt  Expires November 2, 2017               [Page 24]

                    Spinel Protocol (86157e99-dirty)            May 2017


    +-----------------------+-----------------------------------------+
    | 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.1.  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.2     |
      |  PHY   | 0x20 - 0x2F, 0x1200 - 0x12FF |     Section 5.4     |
      |  MAC   | 0x30 - 0x3F, 0x1300 - 0x13FF |     Section 5.5     |
      |  NET   | 0x40 - 0x4F, 0x1400 - 0x14FF |     Section 5.6     |
      |  Tech  | 0x50 - 0x5F, 0x1500 - 0x15FF | Technology-specific |
      |  IPv6  | 0x60 - 0x6F, 0x1600 - 0x16FF |     Section 5.7     |
      | Stream | 0x70 - 0x7F, 0x1700 - 0x17FF |     Section 5.2     |
      | Debug  |       0x4000 - 0x4400        |     Section 5.8     |
      +--------+------------------------------+---------------------+

   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.

5.2.  Core Properties

5.2.1.  PROP 0: PROP_LAST_STATUS

   o  Type: Read-Only
   o  Encoding: "i"








Quattlebaum & woodyatt  Expires November 2, 2017               [Page 25]

                    Spinel Protocol (86157e99-dirty)            May 2017


                         +---------+-------------+
                         | 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.2.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 1 of this
   protocol.

5.2.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.







Quattlebaum & woodyatt  Expires November 2, 2017               [Page 26]

                    Spinel Protocol (86157e99-dirty)            May 2017


5.2.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.2.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"

5.2.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



Quattlebaum & woodyatt  Expires November 2, 2017               [Page 27]

                    Spinel Protocol (86157e99-dirty)            May 2017


   o  2: ZigBeeIP
   o  3: Thread

   The host MUST enter a FAULT state if it does not recognize the
   protocol given by the NCP.

5.2.5.  PROP 4: PROP_INTERFACE_VENDOR_ID

   o  Type: Read-Only
   o  Encoding: "i"

                          +---------+-----------+
                          | Octets: |    1-3    |
                          +---------+-----------+
                          | Fields: | VENDOR_ID |
                          +---------+-----------+

   Vendor identifier.

5.2.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.

   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.




Quattlebaum & woodyatt  Expires November 2, 2017               [Page 28]

                    Spinel Protocol (86157e99-dirty)            May 2017


   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  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  1024: "CAP_THREAD_COMMISSIONER"
   o  1025: "CAP_THREAD_BA_PROXY"

   Additionally, future capability allocations SHALL be made from the
   following allocation plan:

        +-----------------------+--------------------------------+
        |    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.2.7.  PROP 6: PROP_INTERFACE_COUNT

   o  Type: Read-Only
   o  Packed-Encoding: "C"

                      +---------+-------------------+
                      | Octets: |         1         |
                      +---------+-------------------+
                      | Fields: | "INTERFACE_COUNT" |
                      +---------+-------------------+





Quattlebaum & woodyatt  Expires November 2, 2017               [Page 29]

                    Spinel Protocol (86157e99-dirty)            May 2017


   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.

5.2.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:

   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)

5.2.9.  PROP 8: PROP_HWADDR

   o  Type: Read-Only*
   o  Packed-Encoding: "E"

                           +---------+--------+
                           | Octets: |   8    |
                           +---------+--------+
                           | Fields: | HWADDR |
                           +---------+--------+






Quattlebaum & woodyatt  Expires November 2, 2017               [Page 30]

                    Spinel Protocol (86157e99-dirty)            May 2017


   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.2.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.

   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.3.  Stream Properties

5.3.1.  PROP 112: PROP_STREAM_DEBUG

   o  Type: Read-Only-Stream
   o  Packed-Encoding: "D"

                          +---------+-----------+
                          | 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.



Quattlebaum & woodyatt  Expires November 2, 2017               [Page 31]

                    Spinel Protocol (86157e99-dirty)            May 2017


   To receive the debugging stream, you wait for "CMD_PROP_VALUE_IS"
   commands for this property from the NCP.

5.3.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.

5.3.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:






Quattlebaum & woodyatt  Expires November 2, 2017               [Page 32]

                    Spinel Protocol (86157e99-dirty)            May 2017


     +----------+-----------------------+------------+-----+---------+
     | 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.4.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:

   +---------+--------+------------------+-----------------------------+
   |   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.3.3.  PROP 114: PROP_STREAM_NET

   o  Type: Read-Write-Stream
   o  Packed-Encoding: "dD"






Quattlebaum & woodyatt  Expires November 2, 2017               [Page 33]

                    Spinel Protocol (86157e99-dirty)            May 2017


        +---------+----------------+------------+----------------+
        | 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.3.2.1.

5.3.4.  PROP 114: 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.





Quattlebaum & woodyatt  Expires November 2, 2017               [Page 34]

                    Spinel Protocol (86157e99-dirty)            May 2017


   Any data past the end of "FRAME_DATA_LEN" is considered metadata, the
   format of which is described in Section 5.3.2.1.

5.4.  PHY Properties

5.4.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.4.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".

5.4.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.4.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.4.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.




Quattlebaum & woodyatt  Expires November 2, 2017               [Page 35]

                    Spinel Protocol (86157e99-dirty)            May 2017


   When setting, the value will be rounded down to a value that is
   supported by the underlying radio hardware.

5.4.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.4.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.

5.5.  MAC Properties

5.5.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"

   Set to "SCAN_STATE_BEACON" to start an active scan.  Beacons will be
   emitted from "PROP_MAC_SCAN_BEACON".

   Set to "SCAN_STATE_ENERGY" to start an energy scan.  Channel energy
   will be reported by alternating emissions of "PROP_PHY_CHAN" and
   "PROP_PHY_RSSI".

   Values switches to "SCAN_STATE_IDLE" when scan is complete.





Quattlebaum & woodyatt  Expires November 2, 2017               [Page 36]

                    Spinel Protocol (86157e99-dirty)            May 2017


5.5.2.  PROP 49: PROP_MAC_SCAN_MASK

   o  Type: Read-Write
   o  Packed-Encoding: "A(C)"
   o  Unit: List of channels to scan

5.5.3.  PROP 50: PROP_MAC_SCAN_PERIOD

   o  Type: Read-Write
   o  Packed-Encoding: "S" (uint16)
   o  Unit: milliseconds per channel

5.5.4.  PROP 51: PROP_MAC_SCAN_BEACON

   o  Type: Read-Only-Stream
   o  Packed-Encoding: "Ccdd" (or "Cct(ESSc)t(iCUd)")

     +---------+----+------+---------+----------+---------+----------+
     | 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

   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.



Quattlebaum & woodyatt  Expires November 2, 2017               [Page 37]

                    Spinel Protocol (86157e99-dirty)            May 2017


5.5.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

5.5.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.5.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.5.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.3.2.

5.5.9.  PROP 56: PROP_MAC_PROMISCUOUS_MODE

   o  Type: Read-Write
   o  Packed-Encoding: "C"

   Possible Values:










Quattlebaum & woodyatt  Expires November 2, 2017               [Page 38]

                    Spinel Protocol (86157e99-dirty)            May 2017


   +----+--------------------------------+-----------------------------+
   | 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.3.2.

5.5.10.  PROP 4864: PROP_MAC_WHITELIST

   o  Type: Read-Write
   o  Packed-Encoding: "A(T(Ec))"
   o  OPTIONAL

   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.5.11.  PROP 4865: PROP_MAC_WHITELIST_ENABLED

   o  Type: Read-Write
   o  Packed-Encoding: "b"

5.5.12.  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.








Quattlebaum & woodyatt  Expires November 2, 2017               [Page 39]

                    Spinel Protocol (86157e99-dirty)            May 2017


5.5.13.  PROP 4868: SPINEL_PROP_MAC_SRC_MATCH_SHORT_ADDRESSES

   o  Type: Write
   o  Packed-Encoding: "A(S)"

   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.5.14.  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.6.  NET Properties

5.6.1.  PROP 64: PROP_NET_SAVED

   o  Type: Read-Only
   o  Packed-Encoding: "b"

   Returns true if there is a network state stored/saved.

5.6.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.6.3.  PROP 66: PROP_NET_STACK_UP

   o  Type: Read-Write
   o  Packed-Encoding: "b"
   o  Unit: Enumeration



Quattlebaum & woodyatt  Expires November 2, 2017               [Page 40]

                    Spinel Protocol (86157e99-dirty)            May 2017


   Thread stack operational status.  Non-zero (set to 1) indicates up,
   zero indicates down.

5.6.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.6.5.  PROP 68: PROP_NET_NETWORK_NAME

   o  Type: Read-Write
   o  Packed-Encoding: "U"

5.6.6.  PROP 69: PROP_NET_XPANID

   o  Type: Read-Write
   o  Packed-Encoding: "D"

5.6.7.  PROP 70: PROP_NET_MASTER_KEY

   o  Type: Read-Write
   o  Packed-Encoding: "D"

5.6.8.  PROP 71: PROP_NET_KEY_SEQUENCE_COUNTER

   o  Type: Read-Write
   o  Packed-Encoding: "L"

5.6.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.6.10.  PROP 73: PROP_NET_REQUIRE_JOIN_EXISTING

   o  Type: Read-Write
   o  Packed-Encoding: "b"




Quattlebaum & woodyatt  Expires November 2, 2017               [Page 41]

                    Spinel Protocol (86157e99-dirty)            May 2017


5.6.11.  PROP 74: PROP_NET_KEY_SWITCH_GUARDTIME

   o  Type: Read-Write
   o  Packed-Encoding: "L"

5.6.12.  PROP 75: PROP_NET_PSKC

   o  Type: Read-Write
   o  Packed-Encoding: "D"

5.7.  IPv6 Properties

5.7.1.  PROP 96: PROP_IPV6_LL_ADDR

   o  Type: Read-Only
   o  Packed-Encoding: "6"

   IPv6 Address

5.7.2.  PROP 97: PROP_IPV6_ML_ADDR

   o  Type: Read-Only
   o  Packed-Encoding: "6"

   IPv6 Address + Prefix Length

5.7.3.  PROP 98: PROP_IPV6_ML_PREFIX

   o  Type: Read-Write
   o  Packed-Encoding: "6C"

   IPv6 Prefix + Prefix Length

5.7.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






Quattlebaum & woodyatt  Expires November 2, 2017               [Page 42]

                    Spinel Protocol (86157e99-dirty)            May 2017


5.7.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.8.  Debug Properties

5.8.1.  PROP 16384: SPINEL_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.8.2.  PROP 16385: SPINEL_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).
   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 LAST_STATUS with
   SPINEL_STATUS_INVALID_COMMAND_FOR_PROP status.






Quattlebaum & woodyatt  Expires November 2, 2017               [Page 43]

                    Spinel Protocol (86157e99-dirty)            May 2017


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.2.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.
   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.




Quattlebaum & woodyatt  Expires November 2, 2017               [Page 44]

                    Spinel Protocol (86157e99-dirty)            May 2017


   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

   This section describes all of the properties and semantics required
   for managing a Thread NCP.

   Thread NCPs have the following requirements:

   o  The property "PROP_INTERFACE_TYPE" must be 3.
   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.  Thread Capabilities

   The Thread technology defines the following capabilities:

   o  "CAP_NET_THREAD_1_0" - Indicates that the NCP implements v1.0 of
      the Thread standard.




Quattlebaum & woodyatt  Expires November 2, 2017               [Page 45]

                    Spinel Protocol (86157e99-dirty)            May 2017


   o  "CAP_NET_THREAD_1_1" - Indicates that the NCP implements v1.1 of
      the Thread standard.

7.2.  Thread Properties

   Properties for Thread are allocated out of the "Tech" property
   section (see Section 5.1).

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.

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.






Quattlebaum & woodyatt  Expires November 2, 2017               [Page 46]

                    Spinel Protocol (86157e99-dirty)            May 2017


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"

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": Thread 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.






Quattlebaum & woodyatt  Expires November 2, 2017               [Page 47]

                    Spinel Protocol (86157e99-dirty)            May 2017


7.2.12.  PROP 91: PROP_THREAD_LOCAL_ROUTES

   o  Type: Read-Write
   o  Packed-Encoding: "A(t(6CbC))"

   Data per item is:

   o  "6": IPv6 Prefix
   o  "C": Prefix length, in bits
   o  "b": Stable flag
   o  "C": Other flags

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.

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 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"






Quattlebaum & woodyatt  Expires November 2, 2017               [Page 48]

                    Spinel Protocol (86157e99-dirty)            May 2017


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 "NETWORK_ID_TIMEOUT" constant, as
   defined by the Thread 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.

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.







Quattlebaum & woodyatt  Expires November 2, 2017               [Page 49]

                    Spinel Protocol (86157e99-dirty)            May 2017


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))"

   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"






Quattlebaum & woodyatt  Expires November 2, 2017               [Page 50]

                    Spinel Protocol (86157e99-dirty)            May 2017


   Specifies the maximum number of children currently allowed.  This
   parameter can only be set when Thread protocol operation has been
   stopped.

7.2.29.  PROP 5389: PROP_THREAD_LEADER_NETWORK_DATA

   o  Type: Read-Only
   o  Packed-Encoding: "D"

   The leader network data.

7.2.30.  PROP 5390: PROP_THREAD_STABLE_LEADER_NETWORK_DATA

   o  Type: Read-Only
   o  Packed-Encoding: "D"

   The stable leader network data.

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)

   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 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_BA_PROXY_ENABLED

   o  Type: Read-Write
   o  Packed-Encoding: "b"
   o  Required capability: "CAP_THREAD_BA_PROXY"



Quattlebaum & woodyatt  Expires November 2, 2017               [Page 51]

                    Spinel Protocol (86157e99-dirty)            May 2017


   Set to true to enable the border agent proxy.

7.2.34.  PROP 5394: PROP_THREAD_BA_PROXY_STREAM

   o  Type: Read-Write-Stream
   o  Packed-Encoding: "dSS"
   o  Required capability: "CAP_THREAD_BA_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 border-agent-
   related CoAP requests/responses from the NCP's RLOC address.  This
   allows the host driver to implement a Thread border agent.

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.

8.1.  Commands

8.1.1.  CMD 9: (Host->NCP) CMD_NET_SAVE

                    +---------+--------+--------------+
                    | Octets: |   1    |      1       |
                    +---------+--------+--------------+
                    | Fields: | HEADER | CMD_NET_SAVE |
                    +---------+--------+--------------+






Quattlebaum & woodyatt  Expires November 2, 2017               [Page 52]

                    Spinel Protocol (86157e99-dirty)            May 2017


   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.

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.





Quattlebaum & woodyatt  Expires November 2, 2017               [Page 53]

                    Spinel Protocol (86157e99-dirty)            May 2017


   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

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




Quattlebaum & woodyatt  Expires November 2, 2017               [Page 54]

                    Spinel Protocol (86157e99-dirty)            May 2017


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" |
                     +---------+--------------------+

   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".








Quattlebaum & woodyatt  Expires November 2, 2017               [Page 55]

                    Spinel Protocol (86157e99-dirty)            May 2017


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"

                  +---------+--------------------------+
                  | Octets: |            1             |
                  +---------+--------------------------+
                  | Fields: | "PROP_JAM_DETECT_ENABLE" |
                  +---------+--------------------------+

   Indicates if jamming detection is enabled or disabled.  Set to true
   to enable jamming detection.





Quattlebaum & woodyatt  Expires November 2, 2017               [Page 56]

                    Spinel Protocol (86157e99-dirty)            May 2017


   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)
   o  Default Value: Implementation-specific
   o  RECOMMENDED for "CAP_JAM_DETECT"

   This parameter describes the window period for signal jamming
   detection.







Quattlebaum & woodyatt  Expires November 2, 2017               [Page 57]

                    Spinel Protocol (86157e99-dirty)            May 2017


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: SPINEL_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.

   Support for this feature can be determined by the presence of
   "CAP_GPIO".








Quattlebaum & woodyatt  Expires November 2, 2017               [Page 58]

                    Spinel Protocol (86157e99-dirty)            May 2017


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)
   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.



Quattlebaum & woodyatt  Expires November 2, 2017               [Page 59]

                    Spinel Protocol (86157e99-dirty)            May 2017


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.

   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.





Quattlebaum & woodyatt  Expires November 2, 2017               [Page 60]

                    Spinel Protocol (86157e99-dirty)            May 2017


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:

   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.





Quattlebaum & woodyatt  Expires November 2, 2017               [Page 61]

                    Spinel Protocol (86157e99-dirty)            May 2017


   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.

   Support for this property is RECOMMENDED if "CAP_TRNG" is included in
   the device capabilities.




Quattlebaum & woodyatt  Expires November 2, 2017               [Page 62]

                    Spinel Protocol (86157e99-dirty)            May 2017


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] http://wpantund.org/

   [2] https://www.freedesktop.org/wiki/Software/dbus/

   [3] https://www.w3.org/TR/exi/#encodingUnsignedInteger

   [4] http://reveng.sourceforge.net/crc-catalogue/16.htm#crc.cat.kermit

   [5] https://github.com/miekg/mmark

   [6] http://xml2rfc.ietf.org/

Appendix A.  Framing Protocol

   Since this NCP protocol is defined independently of the physical
   transport or framing, any number of transports and framing protocols
   could be used successfully.  However, in the interests of
   compatibility, this document provides some recommendations.

A.1.  UART Recommendations

   The recommended default UART settings are:

   o  Bit rate: 115200
   o  Start bits: 1
   o  Data bits: 8
   o  Stop bits: 1
   o  Parity: None
   o  Flow Control: Hardware

   These values may be adjusted depending on the individual needs of the
   application or product, but some sort of flow control MUST be used.
   Hardware flow control is preferred over software flow control.  In



Quattlebaum & woodyatt  Expires November 2, 2017               [Page 63]

                    Spinel Protocol (86157e99-dirty)            May 2017


   the absence of hardware flow control, software flow control (XON/
   XOFF) MUST be used instead.

   We also *RECOMMEND* an Arduino-style hardware reset, where the DTR
   signal is coupled to the "R&#773;E&#773;S&#773;" pin through a
   0.01[micro]F capacitor.  This causes the NCP to automatically reset
   whenever the serial port is opened.  At the very least we *RECOMMEND*
   dedicating one of your host pins to controlling the
   "R&#773;E&#773;S&#773;" pin on the NCP, so that you can easily
   perform a hardware reset if necessary.

A.1.1.  UART Bit Rate Detection

   When using a UART, the issue of an appropriate bit rate must be
   considered.  A bitrate of 115200 bits per second has become a defacto
   standard baud rate for many serial peripherals.  This rate, however,
   is slower than the theoretical maximum bitrate of the 802.15.4 2.4GHz
   PHY (250kbit).  In most circumstances this mismatch is not
   significant because the overall bitrate will be much lower than
   either of these rates, but there are circumstances where a faster
   UART bitrate is desirable.  Thus, this document proposes a simple
   bitrate detection scheme that can be employed by the host to detect
   when the attached NCP is initially running at a higher bitrate.

   The algorithm is to send successive NOOP commands to the NCP at
   increasing bitrates.  When a valid "CMD_LAST_STATUS" response has
   been received, we have identified the correct bitrate.

   In order to limit the time spent hunting for the appropriate bitrate,
   we RECOMMEND that only the following bitrates be checked:

   o  115200
   o  230400
   o  1000000 (1Mbit)

   The bitrate MAY also be changed programmatically by adjusting
   "PROP_UART_BITRATE", if implemented.

A.1.2.  HDLC-Lite

   _HDLC-Lite_ is the recommended framing protocol for transmitting
   Spinel frames over a UART.  HDLC-Lite consists of only the framing,
   escaping, and CRC parts of the larger HDLC protocol---all other parts
   of HDLC are omitted.  This protocol was chosen because it works well
   with software flow control and is widely implemented.






Quattlebaum & woodyatt  Expires November 2, 2017               [Page 64]

                    Spinel Protocol (86157e99-dirty)            May 2017


   To transmit a frame with HDLC-lite, the 16-bit CRC must first be
   appended to the frame.  The CRC function is defined to be CRC-16/
   CCITT, otherwise known as the KERMIT CRC [4].

   Individual frames are terminated with a frame delimiter octet called
   the 'flag' octet ("0x7E").

   The following octets values are considered _special_ and should be
   escaped when present in data frames:

                 +-------------+------------------------+
                 | Octet Value |      Description       |
                 +-------------+------------------------+
                 |     0x7E    | Frame Delimiter (Flag) |
                 |     0x7D    |      Escape Byte       |
                 |     0x11    |          XON           |
                 |     0x13    |          XOFF          |
                 |     0xF8    |    Vendor-Specific     |
                 +-------------+------------------------+

   When present in a data frame, these octet values are escaped by
   prepending the escape octet ("0x7D") and XORing the value with
   "0x20".

   When receiving a frame, the CRC must be verified after the frame is
   unescaped.  If the CRC value does not match what is calculated for
   the frame data, the frame MUST be discarded.  The implementation MAY
   indicate the failure to higher levels to handle as they see fit, but
   MUST NOT attempt to process the deceived frame.

   Consecutive flag octets are entirely legal and MUST NOT be treated as
   a framing error.  Consecutive flag octets MAY be used as a way to
   wake up a sleeping NCP.

   When first establishing a connection to the NCP, it is customary to
   send one or more flag octets to ensure that any previously received
   data is discarded.

A.2.  SPI Recommendations

   We RECOMMEND the use of the following standard SPI signals:

   o  "C&#773;S&#773;": (Host-to-NCP) Chip Select
   o  "CLK": (Host-to-NCP) Clock
   o  "MOSI": Master-Output/Slave-Input
   o  "MISO": Master-Input/Slave-Output
   o  "I&#773;N&#773;T&#773;": (NCP-to-Host) Host Interrupt
   o  "R&#773;E&#773;S&#773;": (Host-to-NCP) NCP Hardware Reset



Quattlebaum & woodyatt  Expires November 2, 2017               [Page 65]

                    Spinel Protocol (86157e99-dirty)            May 2017


   The "I&#773;N&#773;T&#773;" signal is used by the NCP to indicate to
   the host that the NCP has frames pending to send to it.  When
   asserted, the host SHOULD initiate a SPI transaction in a timely
   manner.

   We RECOMMEND the following SPI properties:

   o  "C&#773;S&#773;" is active low.
   o  "CLK" is active high.
   o  "CLK" speed is larger than 500 kHz.
   o  Data is valid on leading edge of "CLK".
   o  Data is sent in multiples of 8-bits (octets).
   o  Octets are sent most-significant bit first.

   This recommended configuration may be adjusted depending on the
   individual needs of the application or product.

A.2.1.  SPI Framing Protocol

   Each SPI frame starts with a 5-byte frame header:

                  +---------+-----+----------+----------+
                  | Octets: |  1  |    2     |    2     |
                  +---------+-----+----------+----------+
                  | Fields: | HDR | RECV_LEN | DATA_LEN |
                  +---------+-----+----------+----------+

   o  "HDR": The first byte is the header byte (defined below)
   o  "RECV_LEN": The second and third bytes indicate the largest frame
      size that that device is ready to receive.  If zero, then the
      other device must not send any data.  (Little endian)
   o  "DATA_LEN": The fourth and fifth bytes indicate the size of the
      pending data frame to be sent to the other device.  If this value
      is equal-to or less-than the number of bytes that the other device
      is willing to receive, then the data of the frame is immediately
      after the header.  (Little Endian)

   The "HDR" byte is defined as:

                       0   1   2   3   4   5   6   7
                     +---+---+---+---+---+---+---+---+
                     |RST|CRC|CCF|  RESERVED |PATTERN|
                     +---+---+---+---+---+---+---+---+

   o  "RST": This bit is set when that device has been reset since the
      last time "C&#773;S&#773;" was asserted.





Quattlebaum & woodyatt  Expires November 2, 2017               [Page 66]

                    Spinel Protocol (86157e99-dirty)            May 2017


   o  "CRC": This bit is set when that device supports writing a 16-bit
      CRC at the end of the data.  The CRC length is NOT included in
      DATA_LEN.
   o  "CCF": "CRC Check Failure".  Set if the CRC check on the last
      received frame failed, cleared to zero otherwise.  This bit is
      only used if both sides support CRC.
   o  "RESERVED": These bits are all reserved for future used.  They
      MUST be cleared to zero and MUST be ignored if set.
   o  "PATTERN": These bits are set to a fixed value to help distinguish
      valid SPI frames from garbage (by explicitly making "0xFF" and
      "0x00" invalid values).  Bit 6 MUST be set to be one and bit 7
      MUST be cleared (0).  A frame received that has any other values
      for these bits MUST be dropped.

   Prior to a sending or receiving a frame, the master MAY send a
   5-octet frame with zeros for both the max receive frame size and the
   the contained frame length.  This will induce the slave device to
   indicate the length of the frame it wants to send (if any) and
   indicate the largest frame it is capable of receiving at the moment.
   This allows the master to calculate the size of the next transaction.
   Alternatively, if the master has a frame to send it can just go ahead
   and send a frame of that length and determine if the frame was
   accepted by checking that the "RECV_LEN" from the slave frame is
   larger than the frame the master just tried to send.  If the
   "RECV_LEN" is smaller then the frame wasn't accepted and will need to
   be transmitted again.

   This protocol can be used either unidirectionally or bidirectionally,
   determined by the behavior of the master and the slave.

   If the the master notices "PATTERN" is not set correctly, the master
   should consider the transaction to have failed and try again after 10
   milliseconds, retrying up to 200 times.  After unsuccessfully trying
   200 times in a row, the master MAY take appropriate remedial action
   (like a NCP hardware reset, or indicating a communication failure to
   a user interface).

   At the end of the data of a frame is an optional 16-bit CRC, support
   for which is indicated by the "CRC" bit of the "HDR" byte being set.
   If these bits are set for both the master and slave frames, then CRC
   checking is enabled on both sides, effectively requiring that frame
   sizes be two bytes longer than would be otherwise required.  The CRC
   is calculated using the same mechanism used for the CRC calculation
   in HDLC-Lite (See Appendix A.1.2).  When both of the "CRC" bits are
   set, both sides must verify that the "CRC" is valid before accepting
   the frame.  If not enough bytes were clocked out for the CRC to be
   read, then the frame must be ignored.  If enough bytes were clocked
   out to perform a CRC check, but the CRC check fails, then the frame



Quattlebaum & woodyatt  Expires November 2, 2017               [Page 67]

                    Spinel Protocol (86157e99-dirty)            May 2017


   must be rejected and the "CRC_FAIL" bit on the next frame (and ONLY
   the next frame) MUST be set.

A.3.  I^2C Recommendations

   TBD

   [CREF2]

A.4.  Native USB Recommendations

   TBD

   [CREF3]

Appendix B.  Test Vectors

B.1.  Test Vector: Packed Unsigned Integer

                 +---------------+-----------------------+
                 | Decimal Value | Packet Octet Encoding |
                 +---------------+-----------------------+
                 |             0 | "00"                  |
                 |             1 | "01"                  |
                 |           127 | "7F"                  |
                 |           128 | "80 01"               |
                 |           129 | "81 01"               |
                 |         1,337 | "B9 0A"               |
                 |        16,383 | "FF 7F"               |
                 |        16,384 | "80 80 01"            |
                 |        16,385 | "81 80 01"            |
                 |     2,097,151 | "FF FF 7F"            |
                 +---------------+-----------------------+

   [CREF4]

B.2.  Test Vector: Reset Command

   o  NLI: 0
   o  TID: 0
   o  CMD: 1 ("CMD_RESET")

   Frame:

                                   80 01






Quattlebaum & woodyatt  Expires November 2, 2017               [Page 68]

                    Spinel Protocol (86157e99-dirty)            May 2017


B.3.  Test Vector: Reset Notification

   o  NLI: 0
   o  TID: 0
   o  CMD: 6 ("CMD_VALUE_IS")
   o  PROP: 0 ("PROP_LAST_STATUS")
   o  VALUE: 114 ("STATUS_RESET_SOFTWARE")

   Frame:

                                80 06 00 72

B.4.  Test Vector: Scan Beacon

   o  NLI: 0
   o  TID: 0
   o  CMD: 7 ("CMD_VALUE_INSERTED")
   o  PROP: 51 ("PROP_MAC_SCAN_BEACON")
   o  VALUE: Structure, encoded as "Cct(ESSc)t(iCUd)"

      *  CHAN: 15
      *  RSSI: -60dBm
      *  MAC_DATA: (0D 00 B6 40 D4 8C E9 38 F9 52 FF FF D2 04 00)

         +  Long address: B6:40:D4:8C:E9:38:F9:52
         +  Short address: 0xFFFF
         +  PAN-ID: 0x04D2
         +  LQI: 0
      *  NET_DATA: (13 00 03 20 73 70 69 6E 65 6C 00 08 00 DE AD 00 BE
         EF 00 CA FE)

         +  Protocol Number: 3
         +  Flags: 0x20
         +  Network Name: "spinel"
         +  XPANID: "DE AD 00 BE EF 00 CA FE"

   Frame:

        80 07 33 0F C4 0D 00 B6 40 D4 8C E9 38 F9 52 FF FF D2 04 00
        13 00 03 20 73 70 69 6E 65 6C 00 08 00 DE AD 00 BE EF 00 CA
        FE

B.5.  Test Vector: Inbound IPv6 Packet

   CMD_VALUE_IS(PROP_STREAM_NET)

   [CREF5]




Quattlebaum & woodyatt  Expires November 2, 2017               [Page 69]

                    Spinel Protocol (86157e99-dirty)            May 2017


B.6.  Test Vector: Outbound IPv6 Packet

   CMD_VALUE_SET(PROP_STREAM_NET)

   [CREF6]

B.7.  Test Vector: Fetch list of on-mesh networks

   o  NLI: 0
   o  TID: 4
   o  CMD: 2 ("CMD_VALUE_GET")
   o  PROP: 90 ("PROP_THREAD_ON_MESH_NETS")

   Frame:

                                 84 02 5A

B.8.  Test Vector: Returned list of on-mesh networks

   o  NLI: 0
   o  TID: 4
   o  CMD: 6 ("CMD_VALUE_IS")
   o  PROP: 90 ("PROP_THREAD_ON_MESH_NETS")
   o  VALUE: Array of structures, encoded as "A(t(6CbC))"

       +--------------+---------------+-------------+-------------+
       | IPv6 Prefix  | Prefix Length | Stable Flag | Other Flags |
       +--------------+---------------+-------------+-------------+
       | 2001:DB8:1:: |       64      |     True    |      ??     |
       | 2001:DB8:2:: |       64      |    False    |      ??     |
       +--------------+---------------+-------------+-------------+

   Frame:

        84 06 5A 13 00 20 01 0D B8 00 01 00 00 00 00 00 00 00 00 00
        00 40 01 ?? 13 00 20 01 0D B8 00 02 00 00 00 00 00 00 00 00
        00 00 40 00 ??

B.9.  Test Vector: Adding an on-mesh network

   o  NLI: 0
   o  TID: 5
   o  CMD: 4 ("CMD_VALUE_INSERT")
   o  PROP: 90 ("PROP_THREAD_ON_MESH_NETS")
   o  VALUE: Structure, encoded as "6CbCb"






Quattlebaum & woodyatt  Expires November 2, 2017               [Page 70]

                    Spinel Protocol (86157e99-dirty)            May 2017


       +--------------+---------------+-------------+-------------+
       | IPv6 Prefix  | Prefix Length | Stable Flag | Other Flags |
       +--------------+---------------+-------------+-------------+
       | 2001:DB8:3:: |       64      |     True    |      ??     |
       +--------------+---------------+-------------+-------------+

   Frame:

        85 03 5A 20 01 0D B8 00 03 00 00 00 00 00 00 00 00 00 00 40
        01 ?? 01

   [CREF7]

B.10.  Test Vector: Insertion notification of an on-mesh network

   o  NLI: 0
   o  TID: 5
   o  CMD: 7 ("CMD_VALUE_INSERTED")
   o  PROP: 90 ("PROP_THREAD_ON_MESH_NETS")
   o  VALUE: Structure, encoded as "6CbCb"

       +--------------+---------------+-------------+-------------+
       | IPv6 Prefix  | Prefix Length | Stable Flag | Other Flags |
       +--------------+---------------+-------------+-------------+
       | 2001:DB8:3:: |       64      |     True    |      ??     |
       +--------------+---------------+-------------+-------------+

   Frame:

        85 07 5A 20 01 0D B8 00 03 00 00 00 00 00 00 00 00 00 00 40
        01 ?? 01

   [CREF8]

B.11.  Test Vector: Removing a local on-mesh network

   o  NLI: 0
   o  TID: 6
   o  CMD: 5 ("CMD_VALUE_REMOVE")
   o  PROP: 90 ("PROP_THREAD_ON_MESH_NETS")
   o  VALUE: IPv6 Prefix "2001:DB8:3::"

   Frame:

         86 05 5A 20 01 0D B8 00 03 00 00 00 00 00 00 00 00 00 00






Quattlebaum & woodyatt  Expires November 2, 2017               [Page 71]

                    Spinel Protocol (86157e99-dirty)            May 2017


B.12.  Test Vector: Removal notification of an on-mesh network

   o  NLI: 0
   o  TID: 6
   o  CMD: 8 ("CMD_VALUE_REMOVED")
   o  PROP: 90 ("PROP_THREAD_ON_MESH_NETS")
   o  VALUE: IPv6 Prefix "2001:DB8:3::"

   Frame:

         86 08 5A 20 01 0D B8 00 03 00 00 00 00 00 00 00 00 00 00

Appendix C.  Example Sessions

C.1.  NCP Initialization

   [CREF9]

   Check the protocol version to see if it is supported:

   o  CMD_VALUE_GET:PROP_PROTOCOL_VERSION
   o  CMD_VALUE_IS:PROP_PROTOCOL_VERSION

   Check the NCP version to see if a firmware update may be necessary:

   o  CMD_VALUE_GET:PROP_NCP_VERSION
   o  CMD_VALUE_IS:PROP_NCP_VERSION

   Check interface type to make sure that it is what we expect:

   o  CMD_VALUE_GET:PROP_INTERFACE_TYPE
   o  CMD_VALUE_IS:PROP_INTERFACE_TYPE

   If the host supports using vendor-specific commands, the vendor
   should be verified before using them:

   o  CMD_VALUE_GET:PROP_VENDOR_ID
   o  CMD_VALUE_IS:PROP_VENDOR_ID

   Fetch the capability list so that we know what features this NCP
   supports:

   o  CMD_VALUE_GET:PROP_CAPS
   o  CMD_VALUE_IS:PROP_CAPS

   If the NCP supports CAP_NET_SAVE, then we go ahead and recall the
   network:




Quattlebaum & woodyatt  Expires November 2, 2017               [Page 72]

                    Spinel Protocol (86157e99-dirty)            May 2017


   o  CMD_NET_RECALL

C.2.  Attaching to a network

   [CREF10]

   We make the assumption that the NCP is not currently associated with
   a network.

   Set the network properties, if they were not already set:

   o  CMD_VALUE_SET:PROP_PHY_CHAN
   o  CMD_VALUE_IS:PROP_PHY_CHAN
   o  CMD_VALUE_SET:PROP_NET_XPANID
   o  CMD_VALUE_IS:PROP_NET_XPANID
   o  CMD_VALUE_SET:PROP_MAC_15_4_PANID
   o  CMD_VALUE_IS:PROP_MAC_15_4_PANID
   o  CMD_VALUE_SET:PROP_NET_NETWORK_NAME
   o  CMD_VALUE_IS:PROP_NET_NETWORK_NAME
   o  CMD_VALUE_SET:PROP_NET_MASTER_KEY
   o  CMD_VALUE_IS:PROP_NET_MASTER_KEY
   o  CMD_VALUE_SET:PROP_NET_KEY_SEQUENCE_COUNTER
   o  CMD_VALUE_IS:PROP_NET_KEY_SEQUENCE_COUNTER
   o  CMD_VALUE_SET:PROP_NET_KEY_SWITCH_GUARDTIME
   o  CMD_VALUE_IS:PROP_NET_KEY_SWITCH_GUARDTIME

   Bring the network interface up:

   o  CMD_VALUE_SET:PROP_NET_IF_UP:TRUE
   o  CMD_VALUE_IS:PROP_NET_IF_UP:TRUE

   Bring the routing stack up:

   o  CMD_VALUE_SET:PROP_NET_STACK_UP:TRUE
   o  CMD_VALUE_IS:PROP_NET_STACK_UP:TRUE

   Some asynchronous events from the NCP:

   o  CMD_VALUE_IS:PROP_NET_ROLE
   o  CMD_VALUE_IS:PROP_NET_PARTITION_ID
   o  CMD_VALUE_IS:PROP_THREAD_ON_MESH_NETS

C.3.  Successfully joining a pre-existing network

   [CREF11]






Quattlebaum & woodyatt  Expires November 2, 2017               [Page 73]

                    Spinel Protocol (86157e99-dirty)            May 2017


   This example session is identical to the above session up to the
   point where we set PROP_NET_IF_UP to true.  From there, the behavior
   changes.

   o  CMD_VALUE_SET:PROP_NET_REQUIRE_JOIN_EXISTING:TRUE
   o  CMD_VALUE_IS:PROP_NET_REQUIRE_JOIN_EXISTING:TRUE

   Bring the routing stack up:

   o  CMD_VALUE_SET:PROP_NET_STACK_UP:TRUE
   o  CMD_VALUE_IS:PROP_NET_STACK_UP:TRUE

   Some asynchronous events from the NCP:

   o  CMD_VALUE_IS:PROP_NET_ROLE
   o  CMD_VALUE_IS:PROP_NET_PARTITION_ID
   o  CMD_VALUE_IS:PROP_THREAD_ON_MESH_NETS

   Now let's save the network settings to NVRAM:

   o  CMD_NET_SAVE

C.4.  Unsuccessfully joining a pre-existing network

   This example session is identical to the above session up to the
   point where we set PROP_NET_IF_UP to true.  From there, the behavior
   changes.

   o  CMD_VALUE_SET:PROP_NET_REQUIRE_JOIN_EXISTING:TRUE
   o  CMD_VALUE_IS:PROP_NET_REQUIRE_JOIN_EXISTING:TRUE

   Bring the routing stack up:

   o  CMD_VALUE_SET:PROP_NET_STACK_UP:TRUE
   o  CMD_VALUE_IS:PROP_NET_STACK_UP:TRUE

   Some asynchronous events from the NCP:

   o  CMD_VALUE_IS:PROP_LAST_STATUS:STATUS_JOIN_NO_PEERS
   o  CMD_VALUE_IS:PROP_NET_STACK_UP:FALSE

C.5.  Detaching from a network

   TBD







Quattlebaum & woodyatt  Expires November 2, 2017               [Page 74]

                    Spinel Protocol (86157e99-dirty)            May 2017


C.6.  Attaching to a saved network

   [CREF12]

   Recall the saved network if you haven't already done so:

   o  CMD_NET_RECALL

   Bring the network interface up:

   o  CMD_VALUE_SET:PROP_NET_IF_UP:TRUE
   o  CMD_VALUE_IS:PROP_NET_IF_UP:TRUE

   Bring the routing stack up:

   o  CMD_VALUE_SET:PROP_NET_STACK_UP:TRUE
   o  CMD_VALUE_IS:PROP_NET_STACK_UP:TRUE

   Some asynchronous events from the NCP:

   o  CMD_VALUE_IS:PROP_NET_ROLE
   o  CMD_VALUE_IS:PROP_NET_PARTITION_ID
   o  CMD_VALUE_IS:PROP_THREAD_ON_MESH_NETS

C.7.  NCP Software Reset

   [CREF13]

   o  CMD_RESET
   o  CMD_VALUE_IS:PROP_LAST_STATUS:STATUS_RESET_SOFTWARE

   Then jump to Appendix C.1.

C.8.  Adding an on-mesh prefix

   TBD

C.9.  Entering low-power modes

   TBD

C.10.  Sniffing raw packets

   [CREF14]

   This assumes that the NCP has been initialized.

   Optionally set the channel:



Quattlebaum & woodyatt  Expires November 2, 2017               [Page 75]

                    Spinel Protocol (86157e99-dirty)            May 2017


   o  CMD_VALUE_SET:PROP_PHY_CHAN:x
   o  CMD_VALUE_IS:PROP_PHY_CHAN

   Set the filter mode:

   o  CMD_VALUE_SET:PROP_MAC_PROMISCUOUS_MODE:MAC_PROMISCUOUS_MODE_MONIT
      OR
   o  CMD_VALUE_IS:PROP_MAC_PROMISCUOUS_MODE:MAC_PROMISCUOUS_MODE_MONITO
      R

   Enable the raw stream:

   o  CMD_VALUE_SET:PROP_MAC_RAW_STREAM_ENABLED:TRUE
   o  CMD_VALUE_IS:PROP_MAC_RAW_STREAM_ENABLED:TRUE

   Enable the PHY directly:

   o  CMD_VALUE_SET:PROP_PHY_ENABLED:TRUE
   o  CMD_VALUE_IS:PROP_PHY_ENABLED:TRUE

   Now we will get raw 802.15.4 packets asynchronously on
   PROP_STREAM_RAW:

   o  CMD_VALUE_IS:PROP_STREAM_RAW:...
   o  CMD_VALUE_IS:PROP_STREAM_RAW:...
   o  CMD_VALUE_IS:PROP_STREAM_RAW:...

   This mode may be entered even when associated with a network.  In
   that case, you should set "PROP_MAC_PROMISCUOUS_MODE" to
   "MAC_PROMISCUOUS_MODE_PROMISCUOUS" or "MAC_PROMISCUOUS_MODE_NORMAL",
   so that you can avoid receiving packets from other networks or that
   are destined for other nodes.

Appendix D.  Glossary

   [CREF15]

   NCP
      Network Control Processor.
   OS
      Operating System, i.e. the IPv6 node using Spinel to control and
      manage one or more of its IPv6 network interfaces.
   TID
      Transaction Identifier.  May be a value between zero and fifteen.
      See Section 2.1.3 for more information.
   NLI
      Network Link Identifier.  May be a value between zero and three.
      See Section 2.1.2 for more information.



Quattlebaum & woodyatt  Expires November 2, 2017               [Page 76]

                    Spinel Protocol (86157e99-dirty)            May 2017


   PUI
      Packed Unsigned Integer.  A way to serialize an unsigned integer
      using one, two, or three bytes.  Used throughout the Spinel
      protocol.  See Section 3.2 for more information.
   FCS
      Final Checksum.  Bytes added to the end of a packet to help
      determine if the packet was received without corruption.
   PHY
      Physical layer.  Refers to characteristics and parameters related
      to the physical implementation and operation of a networking
      medium.

Appendix E.  Acknowledgments

   Special thanks to Nick Banks, Jonathan Hui, Abtin Keshavarzian, Piotr
   Szkotak, Arjuna Sivasithambaresan and Martin Turon for their
   substantial contributions and feedback related to this document.

   This document was prepared using mmark [5] by (Miek Gieben) and
   xml2rfc (version 2) [6].

Editorial Comments

[CREF1] RQ: Eventually, when https://github.com/miekg/mmark/issues/95 is
        addressed, the above table should be swapped out with this: |
        0 | 1 | 2 | 3 | 4 | 5 | 6 |
        7 | |---|---|---|---|---|---|---|---| | FLG || NLI || TID ||||

[CREF2] RQ: It may make sense to have a look at what Bluetooth HCI is
        doing for native I^2C framing and go with that.

[CREF3] RQ: It may make sense to have a look at what Bluetooth HCI is
        doing for native USB framing and go with that.

[CREF4] RQ: The PUI test-vector encodings need to be verified.

[CREF5] RQ: FIXME: This test vector is incomplete.

[CREF6] RQ: FIXME: This test vector is incomplete.

[CREF7] RQ: FIXME: This test vector is incomplete.

[CREF8] RQ: FIXME: This test vector is incomplete.

[CREF9] RQ: FIXME: This example session is incomplete.

[CREF10] RQ: FIXME: This example session is incomplete.




Quattlebaum & woodyatt  Expires November 2, 2017               [Page 77]

                    Spinel Protocol (86157e99-dirty)            May 2017


[CREF11] RQ: FIXME: This example session is incomplete.

[CREF12] RQ: FIXME: This example session is incomplete.

[CREF13] RQ: FIXME: This example session is incomplete.

[CREF14] RQ: FIXME: This example session is incomplete.

[CREF15] RQ: Alphabetize before finalization.

Authors' Addresses

   Robert S. Quattlebaum
   Nest Labs, Inc.
   3400 Hillview Ave.
   Palo Alto, California  94304
   USA

   Email: rquattle@nestlabs.com


   james woodyatt
   Nest Labs, Inc.
   3400 Hillview Ave.
   Palo Alto, California  94304
   USA

   Email: jhw@nestlabs.com























Quattlebaum & woodyatt  Expires November 2, 2017               [Page 78]
