openthread/doc/spinel-protocol-src/draft-rquattle-spinel-unified.md.in

%%%
    title           = "Spinel Host-Controller Protocol"
    abbrev          = "Spinel Protocol (Unified)"
    category        = "info"
    docName         = "draft-rquattle-spinel-unified-@SOURCE_VERSION@"
    ipr             = "noDerivativesTrust200902"
    keyword         = ["Spinel", "IPv6", "NCP"]
    date            = @SOURCE_DATE@
    submissionType  = "independent"
    
    [pi]
    editing         = "yes"
    compact         = "yes"
    subcompact      = "yes"
    comments        = "yes"
    
    [[author]]
    initials        = "R."
    surname         = "Quattlebaum"
    fullname        = "Robert S. Quattlebaum"
    organization    = "Nest Labs, Inc."
    
        [author.address]
        email       = "[email protected]"
        
        [author.address.postal]
        street      = "3400 Hillview Ave."
        city        = "Palo Alto"
        region      = "California"
        code        = "94304"
        country     = "USA"
    
    [[author]]
    role            = "editor"
    initials        = "J.H."
    surname         = "Woodyatt"
    fullname        = "James Woodyatt"
    organization    = "Nest Labs, Inc."
    
        [author.address]
        email       = "[email protected]"
        
        [author.address.postal]
        street      = "3400 Hillview Ave."
        city        = "Palo Alto"
        region      = "California"
        code        = "94304"
        country     = "USA"
%%%

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


{mainmatter}

# 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:

*   Adopt a layered approach to the protocol design, allowing future
    support for other network protocols.
*   Minimize the number of required commands/methods by providing a
    rich, property-based API.
*   Support NCPs capable of being connected to more than one network
    at a time.
*   Gracefully handle the addition of new features and capabilities
    without necessarily breaking backward compatibility.
*   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.

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

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

### Renumbering ###

Efforts are currently maintained to try to prevent overtly
backward-incompatible changes to the existing protocol, but if you are
implementing Spinel in your own products you should expect there to be
at least one large renumbering event and major version number change
before the standard is considered "baked". All changes will be clearly
marked and documented to make such a transition as easy as possible.

To allow conclusive detection of protocol (in)compatibility between
the host and the NCP, the following commands and properties are
already considered to be "baked" and will not change:

*   Command IDs zero through eight. (Reset, No-op, and Property-Value
    Commands)
*   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 ((#packed-unsigned-integer)).

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.


{{spinel-frame-format.md}}

{{spinel-data-packing.md}}

{{spinel-commands.md}}

{{spinel-prop.md}}

{{spinel-status-codes.md}}

{{spinel-tech-thread.md}}

{{spinel-feature-network-save.md}}

{{spinel-feature-host-buffer-offload.md}}

{{spinel-feature-jam-detect.md}}

{{spinel-feature-gpio.md}}

{{spinel-feature-trng.md}}

{{spinel-security-considerations.md}}

{backmatter}

{{spinel-framing.md}}

{{spinel-test-vectors.md}}

{{spinel-example-sessions.md}}

{{spinel-basis-glossary.md}}

# 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](https://github.com/miekg/mmark)
by (Miek Gieben) and [xml2rfc (version 2)](http://xml2rfc.ietf.org/).