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