R. Quattlebaum
Nest Labs
February 16, 2017

Spinel Host-Controller Protocol
draft-spinel-protocol-00deac5b1

Abstract

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

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

Status of This Document

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

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

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.


Table of Contents

1. Introduction

This Network Control Processor (NCP) protocol was designed to enable a host device to communicate with and manage a NCP while also achieving the following goals:

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

Renumbering would be undertaken in order to better organize the allocation of property IDs and capability IDs. One of the initial goals of this protocol was for it to be possible for a host or NCP to only implement properties with values less than 127 and for the NCP to still be usable---relegating all larger property values for extra features or other capabilities that aren't strictly necessary. This would allow simple implementations to avoid the need to implement support for PUIs (Section 3.2).

As time has gone by and the protocol has become more fleshed out, it has become clear that some of the initial allocations were inadequate and should be revisited if we want to try to achieve the original goal.

1.1.2. Spinel as Application API

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

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

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

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

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

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

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

1.1.3. Privileged Commands and Properties

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

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

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

1.2. Property Overview

Spinel is largely a property-based protocol, with a property defined for every attribute that needs to be set, changed, or known by the host. The inspiration of this approach was memory-mapped hardware registers for peripherals. The goal is to avoid, as much as possible, the use of large complicated structures and/or method argument lists. The reason for avoiding these is because they have a tendency to change, especially early in development. Adding or removing a property from a structure can render the entire protocol incompatible. By using properties, you simply change an additional property.

Almost all features and capabilities are implemented using properties. Most new features that are initially proposed as commands can be adapted to be property-based instead. Notable exceptions include "Host Buffer Offload" (Section 9) and "Network Save" (Section 8).

In Spinel, properties are keyed by an unsigned integer between 0 and 2,097,151 (See Section 3.2).

1.2.1. Property Methods

Properties may support one or more of the following methods:

Additionally, the NCP can send updates to the host (either synchronously or asynchronously) that inform the host about changes to specific properties:

1.2.2. Property Types

Conceptually, there are three different types of properties:

1.2.2.1. Single-Value Properties

Single-value properties are properties that have a simple representation of a single value. Examples would be:

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

1.2.2.2. Multiple-Value Properties

Multiple-Value Properties have more than one value associated with them. Examples would be:

The valid operations on these sorts of properties are VALUE_GET, VALUE_SET, VALUE_INSERT, and VALUE_REMOVE.

When the value is fetched using VALUE_GET, the returned value is the concatenation of all of the individual values in the list. If the length of the value for an individual item in the list is not defined by the type then each item returned in the list is prepended with a length (See Section 3.5). The order of the returned items, unless explicitly defined for that specific property, is undefined.

VALUE_SET provides a way to completely replace all previous values. Calling VALUE_SET with an empty value effectively instructs the NCP to clear the value of that property.

VALUE_INSERT and VALUE_REMOVE provide mechanisms for the insertion or removal of individual items by value. The payload for these commands is a plain single value.

1.2.2.3. Stream Properties

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

All such properties emit changes asynchronously using the VALUE_IS command, sent from the NCP to the host. For example, as IPv6 traffic is received by the NCP, the IPv6 packets are sent to the host by way of asynchronous VALUE_IS notifications.

Some of these properties also support the host send data back to the NCP. For example, this is how the host sends IPv6 traffic to the NCP.

These types of properties generally do not support VALUE_GET, as it is meaningless.

2. Frame Format

A frame is defined simply as the concatenation of

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

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.3. TID: Transaction Identifier

The least significant bits of the header represent the Transaction Identifier(TID). The TID is used for correlating responses to the commands which generated them.

When a command is sent from the host, any reply to that command sent by the NCP will use the same value for the TID. When the host receives a frame that matches the TID of the command it sent, it can easily recognize that frame as the actual response to that command.

The TID value of zero (0) is used for commands to which a correlated response is not expected or needed, such as for unsolicited update commands sent to the host from the NCP.

2.1.4. Command Identifier (CMD)

The command identifier is a 21-bit unsigned integer encoded in up to three bytes using the packed unsigned integer format described in Section 3.2. This encoding allows for up to 2,097,152 individual commands, with the first 127 commands represented as a single byte. Command identifiers larger than 2,097,151 are explicitly forbidden.

CID Range Description
0 - 63 Reserved for core commands
64 - 15,359 UNALLOCATED
15,360 - 16,383 Vendor-specific
16,384 - 1,999,999 UNALLOCATED
2,000,000 - 2,097,151 Experimental use only

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.

Goals:

Each primitive datatype has an ASCII character associated with it. Structures can be represented as strings of these characters. For example:

In each case, the data is represented exactly as described. For example, an array of 10 IPv6 address is stored as 160 bytes.

3.1. Primitive Types

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.
U DATATYPE_UTF8 Zero-terminated UTF8-encoded string.
T DATATYPE_STRUCT Structured datatype. Compound type. 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 vast 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, except that we limit the maximum value to the largest value that can be encoded into three bytes(2,097,151).

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

Data blobs are special datatypes in that the data that they contain does not inherently define the size of the data. This means that if the length of the data blob isn't implied, then the length of the blob must be prepended as a packed unsigned integer.

The length of a data blob is implied only when it is the last datatype in a given buffer. This works because we already know the size of the buffer, and the length of the data is simply the rest of the size of the buffer.

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)

However, things are a little different with CLDL. Since our data blob is no longer the last item in the signature, the length must be prepended.

If you are a little confused, keep reading. This theme comes up in a a few different ways in the following sections.

When a length is prepended, the length is encoded as a little-endian unsigned 16-bit integer.

3.4. Structured Data

The structured data type is a way of bundling together a bunch of data into a single data structure. This may at first seem useless. What is the difference between T(Cii) and just Cii? The answer is, in that particular case, nothing: they are stored in exactly the same way.

However, one case where the structure datatype makes a difference is when you compare T(Cii)L to CiiL: they end up being represented entirely differently. This is because the structured data type follows the exact same semantics as the data blob type: if it isn't the last datatype in a signature, it must be prepended with a length. This is useful because it allows for new datatypes to be appended to the structure's signature while remaining backward parsing compatibility.

More explicitly, if you take data that was encoded with T(Cii6)L, you can still decode it as T(Cii)L.

Let's take, for example, the property PROP_IPv6_ADDR_TABLE. Conceptually it is just a list of IPv6 addresses, so we can encode it as A(6c). However, if we ever want to associate more data with the type (like flags), we break our backward compatibility if we add another member and use A(6cC). To allow for data to be added without breaking backward compatibility, we use the structured data type from the start: A(T(6c)). Then when we add a new member to the structure (A(T(6cC))), we don't break backward compatibility.

It's also worth noting that T(Cii)L also parses as DL. You could then take the resultant data blob and parse it as Cii.

When a length is prepended, the length is encoded as a little-endian unsigned 16-bit integer.

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.

Just like the data blob type and the structured data type, the length of the entire array must be prepended unless the array is the last type in a given signature. Thus, A(C) (An array of unsigned bytes) encodes identically to D.

When a length is prepended, the length is encoded as a little-endian unsigned 16-bit integer.

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

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.

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

The resulting order of items in the list is defined by the given property.

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.

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.

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

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.

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

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

4.15. CMD 23: (NCP->Host) CMD_PROP_VALUES_ARE

Octets: 1 1 n
Fields: HEADER CMD_PROP_VALUES_ARE Property/Value Pairs

With each property/value pair being:

Octets: 2 1-3 n
Fields: LENGTH PROP_ID PROP_VALUE

This command is emitted by the NCP as the response to both the CMD_PROP_VALUE_MULTI_GET and CMD_PROP_VALUE_MULTI_SET commands. It is roughly analogous to CMD_PROP_VALUE_IS, except that it contains more than one property.

This command SHOULD NOT be emitted asynchronously, or in response to any command other than CMD_PROP_VALUE_MULTI_GET or CMD_PROP_VALUE_MULTI_SET.

The arguments are a list of structures containing the emitted property and the associated value. These are presented in the same order as given in the associated initiating command. In cases where getting or setting a specific property resulted in an error, the associated slot in this command will describe PROP_LAST_STATUS.

5. Properties

While the majority of the properties that allow the configuration of network connectivity are network protocol specific, there are several properties that are required in all implementations.

Future property allocations SHALL be made from the following allocation plan:

Property ID Range Description
0 - 127 Reserved for frequently-used properties
128 - 15,359 Unallocated
15,360 - 16,383 Vendor-specific
16,384 - 1,999,999 Unallocated
2,000,000 - 2,097,151 Experimental use only

For an explanation of the data format encoding shorthand used throughout this document, see Section 3.

5.1. Property Sections

The currently assigned properties are broken up into several sections, each with reserved ranges of property identifiers. These ranges are:

Name Range (Inclusive) Documentation
Core 0x00 - 0x1F, 0x1000 - 0x11FF Section 5.2
PHY 0x20 - 0x2F, 0x1200 - 0x12FF Section 5.4
MAC 0x30 - 0x3F, 0x1300 - 0x13FF Section 5.5
NET 0x40 - 0x4F, 0x1400 - 0x14FF Section 5.6
Tech 0x50 - 0x5F, 0x1500 - 0x15FF Technology-specific
IPv6 0x60 - 0x6F, 0x1600 - 0x16FF Section 5.7
Stream 0x70 - 0x7F, 0x1700 - 0x17FF Section 5.2

Note that each property section has two reserved ranges: a primary range (which is encoded as a single byte) and an extended range (which is encoded as two bytes). properties which are used more frequently are generally allocated from the former range.

5.2. Core Properties

5.2.1. PROP 0: PROP_LAST_STATUS

Octets: 1-3
Fields: LAST_STATUS

Describes the status of the last operation. Encoded as a packed unsigned integer.

This property is emitted often to indicate the result status of pretty much any Host-to-NCP operation.

It is emitted automatically at NCP startup with a value indicating the reset reason.

See Section 6 for the complete list of status codes.

5.2.2. PROP 1: PROP_PROTOCOL_VERSION

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:

This document describes major version 4, minor version 1 of this protocol.

5.2.2.1. Major Version Number

The major version number is used to identify large and incompatible differences between protocol versions.

The host MUST enter a FAULT state if it does not explicitly support the given major version number.

5.2.2.2. Minor Version Number

The minor version number is used to identify small but otherwise compatible differences between protocol versions. A mismatch between the advertised minor version number and the minor version that is supported by the host SHOULD NOT be fatal to the operation of the host.

5.2.3. PROP 2: PROP_NCP_VERSION

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:

5.2.4. PROP 3: PROP_INTERFACE_TYPE

Octets: 1-3
Fields: INTERFACE_TYPE

This integer identifies what the network protocol for this NCP. Currently defined values are:

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

5.2.5. PROP 4: PROP_INTERFACE_VENDOR_ID

Octets: 1-3
Fields: VENDOR_ID

Vendor identifier.

5.2.6. PROP 5: PROP_CAPS

Octets: 1-3 1-3 ...
Fields: CAP_1 CAP_2 ...

Describes the supported capabilities of this NCP. Encoded as a list of packed unsigned integers.

A capability is defined as a 21-bit integer that describes a subset of functionality which is supported by the NCP.

Currently defined values are:

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

Capability Range Description
0 - 127 Reserved for core capabilities
128 - 15,359 UNALLOCATED
15,360 - 16,383 Vendor-specific
16,384 - 1,999,999 UNALLOCATED
2,000,000 - 2,097,151 Experimental use only

5.2.7. PROP 6: PROP_INTERFACE_COUNT

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.

5.2.8. PROP 7: PROP_POWER_STATE

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:

5.2.9. PROP 8: PROP_HWADDR

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.2.10. PROP 9: PROP_LOCK

Octets: 1
Fields: LOCK

Property lock. Used for grouping changes to several properties to take effect at once, or to temporarily prevent the automatic updating of property values. When this property is set, the execution of the NCP is effectively frozen until it is cleared.

This property is only supported if the CAP_LOCK capability is present.

Unlike most other properties, setting this property to true when the value of the property is already true MUST fail with a last status of STATUS_ALREADY.

5.3. Stream Properties

5.3.1. PROP 112: PROP_STREAM_DEBUG

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.3.2. PROP 113: PROP_STREAM_RAW

Octets: 2 n n
Fields: FRAME_DATA_LEN FRAME_DATA FRAME_METADATA

This stream provides the capability of sending and receiving raw packets to and from the radio. The exact format of the frame metadata and data is dependent on the MAC and PHY being used.

This property is a streaming property, meaning that you cannot explicitly fetch the value of this property. To receive traffic, you wait for CMD_PROP_VALUE_IS commands with this property id from the NCP.

Implementations may OPTIONALLY support the ability to transmit arbitrary raw packets. Support for this feature is indicated by the presence of the CAP_WRITABLE_RAW_STREAM capability.

If the capability CAP_WRITABLE_RAW_STREAM is set, then packets written to this stream with CMD_PROP_VALUE_SET will be sent out over the radio. This allows the caller to use the radio directly, with the stack being implemented on the host instead of the NCP.

5.3.2.1. Frame Metadata Format

Any data past the end of FRAME_DATA_LEN is considered metadata and is OPTIONAL. Frame metadata MAY be empty or partially specified. Partially specified metadata MUST be accepted. Default values are used for all unspecified fields.

The same general format is used for PROP_STREAM_RAW, PROP_STREAM_NET, and PROP_STREAM_NET_INSECURE. It can be used for frames sent from the NCP to the host as well as frames sent from the host to the NCP.

The frame metadata field consists of the following fields:

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:

When specifying MD_POWER for a packet to be transmitted, the actual transmit power is never larger than the current value of PROP_PHY_TX_POWER (Section 5.4.6). When left unspecified (or set to the value -128), an appropriate transmit power will be chosen by the NCP.

The bit values in MD_FLAG are defined as follows:

Bit Mask Name Description if set
15 0x0001 MD_FLAG_TX Packet was transmitted, not received.
13 0x0004 MD_FLAG_BAD_FCS Packet was received with bad FCS
12 0x0008 MD_FLAG_DUPE Packet seems to be a duplicate
0-11, 14 0xFFF2 MD_FLAG_RESERVED Flags reserved for future use.

The format of MD_PHY is specified by the PHY layer currently in use, and may contain information such as the channel, LQI, antenna, or other pertainent information.

5.3.3. PROP 114: PROP_STREAM_NET

Octets: 2 n n
Fields: FRAME_DATA_LEN FRAME_DATA FRAME_METADATA

This stream provides the capability of sending and receiving data packets to and from the currently attached network. The exact format of the frame metadata and data is dependent on the network protocol being used.

This property is a streaming property, meaning that you cannot explicitly fetch the value of this property. To receive traffic, you wait for CMD_PROP_VALUE_IS commands with this property id from the NCP.

To send network packets, you call CMD_PROP_VALUE_SET on this property with the value of the packet.

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

5.3.4. PROP 114: PROP_STREAM_NET_INSECURE

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

5.4. PHY Properties

5.4.1. PROP 32: PROP_PHY_ENABLED

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.

5.4.2. PROP 33: PROP_PHY_CHAN

Value is the current channel. Must be set to one of the values contained in PROP_PHY_CHAN_SUPPORTED.

5.4.3. PROP 34: PROP_PHY_CHAN_SUPPORTED

Value is a list of channel values that are supported by the hardware.

5.4.4. PROP 35: PROP_PHY_FREQ

Value is the radio frequency (in kilohertz) of the current channel.

5.4.5. PROP 36: PROP_PHY_CCA_THRESHOLD

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.4.6. PROP 37: PROP_PHY_TX_POWER

Value is the transmit power of the radio.

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

5.4.7. PROP 38: PROP_PHY_RSSI

Value is the current RSSI (Received signal strength indication) from the radio. This value can be used in energy scans and for determining the ambient noise floor for the operating environment.

5.5. MAC Properties

5.5.1. PROP 48: PROP_MAC_SCAN_STATE

Possible Values:

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

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

Values switches to SCAN_STATE_IDLE when scan is complete.

5.5.2. PROP 49: PROP_MAC_SCAN_MASK

5.5.3. PROP 50: PROP_MAC_SCAN_PERIOD

5.5.4. PROP 51: PROP_MAC_SCAN_BEACON

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:

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.5.5. PROP 52: PROP_MAC_15_4_LADDR

The 802.15.4 long address of this node.

This property is only present on NCPs which implement 802.15.4

5.5.6. PROP 53: PROP_MAC_15_4_SADDR

The 802.15.4 short address of this node.

This property is only present on NCPs which implement 802.15.4

5.5.7. PROP 54: PROP_MAC_15_4_PANID

The 802.15.4 PANID this node is associated with.

This property is only present on NCPs which implement 802.15.4

5.5.8. PROP 55: PROP_MAC_RAW_STREAM_ENABLED

Set to true to enable raw MAC frames to be emitted from PROP_STREAM_RAW. See Section 5.3.2.

5.5.9. PROP 56: PROP_MAC_PROMISCUOUS_MODE

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

5.5.10. PROP 4864: PROP_MAC_WHITELIST

Structure Parameters:

5.5.11. PROP 4865: PROP_MAC_WHITELIST_ENABLED

5.6. NET Properties

5.6.1. PROP 64: PROP_NET_SAVED

Returns true if there is a network state stored that can be restored with a call to CMD_NET_RECALL.

5.6.2. PROP 65: PROP_NET_IF_UP

Network interface up/down status. Non-zero (set to 1) indicates up, zero indicates down.

5.6.3. PROP 66: PROP_NET_STACK_UP

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

5.6.4. PROP 67: PROP_NET_ROLE

Values:

5.6.5. PROP 68: PROP_NET_NETWORK_NAME

5.6.6. PROP 69: PROP_NET_XPANID

5.6.7. PROP 70: PROP_NET_MASTER_KEY

5.6.8. PROP 71: PROP_NET_KEY_SEQUENCE_COUNTER

5.6.9. PROP 72: PROP_NET_PARTITION_ID

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

5.6.10. PROP 73: PROP_NET_KEY_SWITCH_GUARDTIME

5.7. IPv6 Properties

5.7.1. PROP 96: PROP_IPV6_LL_ADDR

IPv6 Address

5.7.2. PROP 97: PROP_IPV6_ML_ADDR

IPv6 Address + Prefix Length

5.7.3. PROP 98: PROP_IPV6_ML_PREFIX

IPv6 Prefix + Prefix Length

5.7.4. PROP 99: PROP_IPV6_ADDRESS_TABLE

Array of structures containing:

5.7.5. PROP 101: PROP_IPv6_ICMP_PING_OFFLOAD

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.

6. Status Codes

Status codes are sent from the NCP to the host via PROP_LAST_STATUS using the CMD_VALUE_IS command to indicate the return status of a previous command. As with any response, the TID field of the FLAG byte is used to correlate the response with the request.

Note that most successfully executed commands do not indicate a last status of STATUS_OK. The usual way the NCP indicates a successful command is to mirror the property change back to the host. For example, if you do a CMD_VALUE_SET on PROP_PHY_ENABLED, the NCP would indicate success by responding with a CMD_VALUE_IS for PROP_PHY_ENABLED. If the command failed, PROP_LAST_STATUS would be emitted instead.

See Section 5.2.1 for more information on PROP_LAST_STATUS.

7. Technology: Thread

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

Thread NCPs have the following requirements:

All serious implementations of an NCP SHOULD also support the network save feature (See Section 8).

7.1. Thread Capabilities

The Thread technology defines the following capabilities:

7.2. Thread Properties

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

7.2.1. PROP 80: PROP_THREAD_LEADER_ADDR

The IPv6 address of the leader. (Note: May change to long and short address of leader)

7.2.2. PROP 81: PROP_THREAD_PARENT

The long address and short address of the parent of this node.

7.2.3. PROP 82: PROP_THREAD_CHILD_TABLE

Table containing the long and short addresses of all the children of this node.

7.2.4. PROP 83: PROP_THREAD_LEADER_RID

The router-id of the current leader.

7.2.5. PROP 84: PROP_THREAD_LEADER_WEIGHT

The leader weight of the current leader.

7.2.6. PROP 85: PROP_THREAD_LOCAL_LEADER_WEIGHT

The leader weight for this node.

7.2.7. PROP 86: PROP_THREAD_NETWORK_DATA

The local network data.

7.2.8. PROP 87: PROP_THREAD_NETWORK_DATA_VERSION

7.2.9. PROP 88: PROP_THREAD_STABLE_NETWORK_DATA

The local stable network data.

7.2.10. PROP 89: PROP_THREAD_STABLE_NETWORK_DATA_VERSION

7.2.11. PROP 90: PROP_THREAD_ON_MESH_NETS

Data per item is:

7.2.12. PROP 91: PROP_THREAD_LOCAL_ROUTES

Data per item is:

7.2.13. PROP 92: PROP_THREAD_ASSISTING_PORTS

7.2.14. PROP 93: PROP_THREAD_ALLOW_LOCAL_NET_DATA_CHANGE

Set to true before changing local net data. Set to false when finished. This allows changes to be aggregated into single events.

7.2.15. PROP 94: PROP_THREAD_MODE

This property contains the value of the mode TLV for this node. The meaning of the bits in this bitfield are defined by section 4.5.2 of the Thread specification.

7.2.16. PROP 5376: PROP_THREAD_CHILD_TIMEOUT

Used when operating in the Child role.

7.2.17. PROP 5377: PROP_THREAD_RLOC16

7.2.18. PROP 5378: PROP_THREAD_ROUTER_UPGRADE_THRESHOLD

7.2.19. PROP 5379: PROP_THREAD_CONTEXT_REUSE_DELAY

7.2.20. PROP 5380: PROP_THREAD_NETWORK_ID_TIMEOUT

Allows you to get or set the Thread NETWORK_ID_TIMEOUT constant, as defined by the Thread specification.

7.2.21. PROP 5381: PROP_THREAD_ACTIVE_ROUTER_IDS

Note that some implementations may not support CMD_GET_VALUE router ids, but may support CMD_REMOVE_VALUE when the node is a leader.

7.2.22. PROP 5382: PROP_THREAD_RLOC16_DEBUG_PASSTHRU

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

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

7.2.25. PROP 5385: PROP_THREAD_ROUTER_SELECTION_JITTER

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

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

Data per item is:

7.2.28. PROP 5388: PROP_THREAD_CHILD_COUNT_MAX

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

7.2.29. PROP 5389: PROP_THREAD_LEADER_NETWORK_DATA

The leader network data.

7.2.30. PROP 5390: PROP_THREAD_STABLE_LEADER_NETWORK_DATA

The stable leader network data.

8. Feature: Network Save

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

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

Network clear feature allows host to erase all network credentials and state from non-volatile memory.

8.1. Commands

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

Octets: 1 1
Fields: HEADER CMD_NET_SAVE

Save network state command. Saves any current network credentials and state necessary to reconnect to the current network to non-volatile memory.

This operation affects non-volatile memory only. The current network information stored in volatile memory is unaffected.

The response to this command is always a CMD_PROP_VALUE_IS for PROP_LAST_STATUS, indicating the result of the operation.

This command is only available if the CAP_NET_SAVE capability is set.

8.1.2. CMD 10: (Host->NCP) CMD_NET_CLEAR

Octets: 1 1
Fields: HEADER CMD_NET_CLEAR

Clear saved network settings command. Erases all network credentials and state from non-volatile memory. The erased settings include any data saved automatically by the network stack firmware and/or data saved by CMD_NET_SAVE operation.

This operation affects non-volatile memory only. The current network information stored in volatile memory is unaffected.

The response to this command is always a CMD_PROP_VALUE_IS for PROP_LAST_STATUS, indicating the result of the operation.

This command is always available independent of the value of CAP_NET_SAVE capability.

8.1.3. CMD 11: (Host->NCP) CMD_NET_RECALL

Octets: 1 1
Fields: HEADER CMD_NET_RECALL

Recall saved network state command. Recalls any previously saved network credentials and state previously stored by CMD_NET_SAVE from non-volatile memory.

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

9.1.2. CMD 13: (NCP->Host) CMD_HBO_RECLAIM

9.1.3. CMD 14: (NCP->Host) CMD_HBO_DROP

9.1.4. CMD 15: (Host->NCP) CMD_HBO_OFFLOADED

9.1.5. CMD 16: (Host->NCP) CMD_HBO_RECLAIMED

9.1.6. CMD 17: (Host->NCP) CMD_HBO_DROPPED

9.2. Properties

9.2.1. PROP 10: PROP_HBO_MEM_MAX

Octets: 4
Fields: PROP_HBO_MEM_MAX

Describes the number of bytes that may be offloaded from the NCP to the host. Default value is zero, so this property must be set by the host to a non-zero value before the NCP will begin offloading blocks.

This value is encoded as an unsigned 32-bit integer.

This property is only available if the CAP_HBO capability is present in PROP_CAPS.

9.2.2. PROP 11: PROP_HBO_BLOCK_MAX

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

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

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

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

This parameter describes the window period for signal jamming detection.

10.1.5. PROP 4612: PROP_JAM_DETECT_BUSY

This parameter describes the number of aggregate seconds within the detection window where the RSSI must be above PROP_JAM_DETECT_RSSI_THRESHOLD to trigger detection.

The behavior of the jamming detection feature when PROP_JAM_DETECT_BUSY is larger than PROP_JAM_DETECT_WINDOW is undefined.

10.1.6. PROP 4613: SPINEL_PROP_JAM_DETECT_HISTORY_BITMAP

This value provides information about current state of jamming detection module for monitoring/debugging purpose. It returns a 64-bit value where each bit corresponds to one second interval starting with bit 0 for the most recent interval and bit 63 for the oldest intervals (63 sec earlier). The bit is set to 1 if the jamming detection module observed/detected high signal level during the corresponding one second interval. The value is read-only and is encoded as two L (uint32) values in little-endian format (first L (uint32) value gives the lower bits corresponding to more recent history).

11. Feature: GPIO Access

This feature allows the host to have control over some or all of the GPIO pins on the NCP. The host can determine which GPIOs are available by examining PROP_GPIO_CONFIG, described below. This API supports a maximum of 256 individual GPIO pins.

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

11.1. Properties

11.1.1. PROP 4096: PROP_GPIO_CONFIG

An array of structures which contain the following fields:

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

As an optional feature, the configuration of individual pins may be modified using the CMD_PROP_VALUE_INSERT command. Only the GPIO number and flags fields MUST be present, the GPIO name (if present) would be ignored. This command can only be used to modify the configuration of GPIOs which are already exposed---it cannot be used by the host to add addional GPIOs.

11.1.2. PROP 4098: PROP_GPIO_STATE

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:

For GPIOs configured as outputs:

For GPIOs which are not specified in PROP_GPIO_CONFIG:

When writing, unspecified bits are assumed to be zero.

11.1.3. PROP 4099: PROP_GPIO_STATE_SET

Allows for the state of various output GPIOs to be set without affecting other GPIO states. Contains a bit field identifying the output GPIOs that should have their state set to 1.

When writing, unspecified bits are assumed to be zero. The value of any bits for GPIOs which are not specified in PROP_GPIO_CONFIG MUST be ignored.

11.1.4. PROP 4100: PROP_GPIO_STATE_CLEAR

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

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:

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

12.1.2. PROP 4102: PROP_TRNG_128

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:

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

12.1.3. PROP 4103: PROP_TRNG_RAW_32

This property is primarily used to diagnose and debug the behavior of the entropy source used for strong random number generation.

When queried, returns the raw output from the entropy source used to generate PROP_TRNG_32, prior to any reduction/whitening and/or mixing with prior state.

The length of the returned buffer is implementation specific and should be expected to be non-deterministic.

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

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.

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:

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

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.

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.

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:

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:

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

The HDR byte is defined as:

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

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 must be rejected and the CRC_FAIL bit on the next frame (and ONLY the next frame) MUST be set.

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.

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.

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

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

B.2. Test Vector: Reset Command

Frame:

80 01

B.3. Test Vector: Reset Notification

Frame:

80 06 00 72

B.4. Test Vector: Scan Beacon

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)

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

B.6. Test Vector: Outbound IPv6 Packet

CMD_VALUE_SET(PROP_STREAM_NET)

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

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

Frame:

84 02 5A

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

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

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

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

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

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

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

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

Frame:

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

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

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

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

Check the protocol version to see if it is supported:

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

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

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

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

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

C.2. Attaching to a network

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

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

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

Bring the network interface up:

Bring the routing stack up:

Some asynchronous events from the NCP:

C.3. Successfully joining a pre-existing network

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

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.

Bring the routing stack up:

Some asynchronous events from the NCP:

Now let's save the network settings to NVRAM:

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.

Bring the routing stack up:

Some asynchronous events from the NCP:

C.5. Detaching from a network

TBD

C.6. Attaching to a saved network

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

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

Bring the network interface up:

Bring the routing stack up:

Some asynchronous events from the NCP:

C.7. NCP Software Reset

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

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

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

This assumes that the NCP has been initialized.

Optionally set the channel:

Set the filter mode:

Enable the raw stream:

Enable the PHY directly:

Now we will get raw 802.15.4 packets asynchronously on 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. Acknowledgments

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

[CREF16]RQ: If I have missed anyone who has contributed to this document, please let me know ASAP.

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

Appendix E. Glossary

[CREF17]RQ: Alphabetize before finalization.

NCP

Acronym for Network Control Processor.
Host

Computer or Micro-controller which controls the NCP.
TID

Transaction Identifier. May be a value between zero and fifteen. See Section 2.1.3 for more information.
IID

Interface Identifier. May be a value between zero and three. See Section 2.1.2 for more information.
PUI

Packed Unsigned Integer. A way to serialize an unsigned integer using one, two, or three bytes. Used throughout the Spinel protocol. See Section 3.2 for more information.
FCS

Final Checksum. Bytes added to the end of a packet to help determine if the packet was received without corruption.
PHY

Physical layer. Refers to characteristics and parameters related to the physical implementation and operation of a networking medium.

Author's Address

Robert S. Quattlebaum Nest Labs 3400 Hillview Ave. Palo Alto, California 94304 USA EMail: rquattle@nestlabs.com