From c6e597556e0111180350987adad5508484c07b89 Mon Sep 17 00:00:00 2001 From: james woodyatt Date: Tue, 2 May 2017 12:19:46 -0700 Subject: [PATCH] [Spinel protocol spec] Update the Copyright Notice. (#1690) * [Spinel protocol spec] Update the Copyright Notice. To prepare for submission of draft-rquattle-spinel-unified to IETF as an Internet Draft, the Status of This Memo and Copyright Notice sections are updated to be in full conformance with BCP 78, BCP 79 and the IETF Trust's Legal Provisions. * Update the doc/Makefile.am with new filenames. --- doc/Makefile.am | 4 +- ...tml => draft-rquattle-spinel-unified.html} | 311 +++-- ....txt => draft-rquattle-spinel-unified.txt} | 1032 +++++++++-------- .../draft-rquattle-spinel-basis.md.in | 46 +- .../draft-rquattle-spinel-unified.md.in | 96 +- 5 files changed, 869 insertions(+), 620 deletions(-) rename doc/{draft-spinel-protocol.html => draft-rquattle-spinel-unified.html} (95%) rename doc/{draft-spinel-protocol.txt => draft-rquattle-spinel-unified.txt} (88%) diff --git a/doc/Makefile.am b/doc/Makefile.am index 9a1768a00..3272f6407 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -34,8 +34,8 @@ EXTRA_DIST = \ $(srcdir)/images/Open-Thread-Logo-200x42.png \ $(srcdir)/images/openthread_contrib.png \ $(srcdir)/images/openthread_logo.png \ - draft-spinel-protocol.txt \ - draft-spinel-protocol.html \ + draft-rquattle-spinel-unified.html \ + draft-rquattle-spinel-unified.txt \ $(NULL) # diff --git a/doc/draft-spinel-protocol.html b/doc/draft-rquattle-spinel-unified.html similarity index 95% rename from doc/draft-spinel-protocol.html rename to doc/draft-rquattle-spinel-unified.html index 83426ae26..53b98f2ab 100644 --- a/doc/draft-spinel-protocol.html +++ b/doc/draft-rquattle-spinel-unified.html @@ -385,7 +385,7 @@ - + @@ -462,7 +462,9 @@ - + + + @@ -471,6 +473,7 @@ + @@ -505,6 +508,10 @@ + + + + @@ -574,17 +581,17 @@ - - + + - + - - - + + + @@ -601,11 +608,15 @@ - Nest Labs + j. woodyatt - March 20, 2017 + Nest Labs, Inc. + + + + May 1, 2017 @@ -613,7 +624,7 @@

Spinel Host-Controller Protocol
- draft-spinel-protocol-6d981f72

+ draft-rquattle-spinel-unified-86157e99-dirty

Abstract @@ -621,27 +632,16 @@

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

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

- Status of This Document + Status of This Memo

-

This document is a work in progress and subject to change.

+

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

+

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

+

This document may not be modified, and derivative works of it may not be created, and it may not be published except as an Internet-Draft.

Copyright Notice

-

Copyright (c) 2016, Nest Labs, Inc. All rights reserved.

-

- [CREF1]RQ: We may want to consider a license more appropriate for documentation. -

-

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

-

- -

    -
  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
    2. -
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
    3. -
  3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
    4. -
- -

-

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

+

Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved.

+

This document is subject to BCP 78 and the IETF Trust’s Legal Provisions Relating to IETF Documents (<http://trustee.ietf.org/license-info>) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document.

@@ -659,7 +659,7 @@
  • 2. Frame Format
  • 6. Status Codes
  • 7. Technology: Thread
  • 8. Feature: Network Save
  • Appendix D. Glossary
    • +
  • Appendix E. Acknowledgments
    • +
  • Authors' Addresses
    • @@ -1023,17 +1030,17 @@ 
       0   1   2   3   4   5   6   7
 +---+---+---+---+---+---+---+---+
-|  FLG  |  IID  |      TID      |
+|  FLG  |  NLI  |      TID      |
 +---+---+---+---+---+---+---+---+

    - [CREF2]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 || IID || TID |||| + [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 ||||

    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. IID: Interface Identifier

    -

    The Interface Identifier (IID) is a number between 0 and 3 which identifies which subinterface the frame is intended for. This allows the protocol to support connecting to more than one network at once. The first subinterface (0) is considered the primary subinterface and MUST be supported. Support for all other subinterfaces is OPTIONAL.

    +

    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.

    @@ -1267,7 +1274,7 @@

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

    +

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

    @@ -2005,6 +2012,8 @@ STACK-NAME/STACK-VERSION[BUILD_INFO][; OTHER_INFO]; BUILD_DATE_AND_TIME
  • 49: CAP_ROLE_SLEEPY
  • 52: CAP_NET_THREAD_1_0
  • 512: CAP_MAC_WHITELIST
    • +
  • 1024: CAP_THREAD_COMMISSIONER
    • +
  • 1025: CAP_THREAD_BA_PROXY

    • @@ -2802,7 +2811,16 @@ STACK-NAME/STACK-VERSION[BUILD_INFO][; OTHER_INFO]; BUILD_DATE_AND_TIME

    The partition ID of the partition that this node is a member of.

    -

    5.6.10. PROP 73: PROP_NET_KEY_SWITCH_GUARDTIME

    +

    5.6.10. PROP 73: PROP_NET_REQUIRE_JOIN_EXISTING

    +

    + +

    + +

    +

    5.6.11. PROP 74: PROP_NET_KEY_SWITCH_GUARDTIME

    +

    +

    5.6.12. PROP 75: PROP_NET_PSKC

    +

    + +

    +

    5.7. IPv6 Properties

    5.7.1. PROP 96: PROP_IPV6_LL_ADDR

    @@ -2885,6 +2912,31 @@ STACK-NAME/STACK-VERSION[BUILD_INFO][; OTHER_INFO]; BUILD_DATE_AND_TIME

    Reading this property will cause an assert on the NCP. This is intended for testing the assert functionality of underlying platform/NCP. Assert should ideally cause the NCP to reset, but if assert is not supported or disabled boolean value of false is returned in response.

    +

    5.8.2. PROP 16385: SPINEL_PROP_DEBUG_NCP_LOG_LEVEL

    +

    + +

    + +

    +

    Provides access to the NCP log level. Currently defined values are (which follows the RFC 5424):

    +

    + +

    + +

    +

    If the NCP supports dynamic log level control, setting this property changes the log level accordingly. Getting the value returns the current log level. If the dynamic log level control is not supported, setting this property returns a LAST_STATUS with SPINEL_STATUS_INVALID_COMMAND_FOR_PROP status.

    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.

    @@ -3278,6 +3330,90 @@ STACK-NAME/STACK-VERSION[BUILD_INFO][; OTHER_INFO]; BUILD_DATE_AND_TIME

    The stable leader network data.

    +

    7.2.31. PROP 5391: PROP_THREAD_JOINERS

    +

    + +

    + +

    +

    Data per item is:

    +

    + +

    + +

    +

    Passess Pre-Shared Key for the Device to the NCP in the commissioning process. When the Extended address is ommited all Devices which provided a valid PSKd are allowed to join the Thread Network.

    +

    7.2.32. PROP 5392: PROP_THREAD_COMMISSIONER_ENABLED

    +

    + +

    + +

    +

    Set to true to enable the native commissioner. It is mandatory before adding the joiner to the network.

    +

    7.2.33. PROP 5393: PROP_THREAD_BA_PROXY_ENABLED

    +

    + +

    + +

    +

    Set to true to enable the border agent proxy.

    +

    7.2.34. PROP 5394: PROP_THREAD_BA_PROXY_STREAM

    +

    + +

    + +

    +

    Data per item is:

    +

    + +

    + +

    + + + + + + + + + + + + + + + + + + + +
    Octects:2n22
    Fields:LengthCoAPlocatorport
    +

    This property allows the host to send and receive border-agent-related CoAP requests/responses from the NCP's RLOC address. This allows the host driver to implement a Thread border agent.

    8. Feature: Network Save

    The network save/recall feature is an optional NCP capability that, when present, allows the host to save and recall network credentials and state to and from nonvolatile storage.

    The presence of the save/recall feature can be detected by checking for the presence of the CAP_NET_SAVE capability in PROP_CAPS.

    @@ -3886,12 +4022,12 @@ STACK-NAME/STACK-VERSION[BUILD_INFO][; OTHER_INFO]; BUILD_DATE_AND_TIME

    A.3. I²C Recommendations

    TBD

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

    A.4. Native USB Recommendations

    TBD

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

    Appendix B. Test Vectors

    B.1. Test Vector: Packed Unsigned Integer

    @@ -3966,13 +4102,13 @@ STACK-NAME/STACK-VERSION[BUILD_INFO][; OTHER_INFO]; BUILD_DATE_AND_TIME

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

    B.2. Test Vector: Reset Command

    @@ -3986,7 +4122,7 @@ STACK-NAME/STACK-VERSION[BUILD_INFO][; OTHER_INFO]; BUILD_DATE_AND_TIME