From 654f953fdaf34e457bee61eb674908141d0a5f8e Mon Sep 17 00:00:00 2001 From: Robert Quattlebaum Date: Wed, 14 Sep 2016 12:00:40 -0700 Subject: [PATCH] Spinel Protocol Documentation Updates (#581) Elaborated on introduction section. Added explanation of how properties are intended to work. Minor fixes to test vectors. Move glossary to the end of the document. Fixed several spelling errors. Also added placeholder section for security considerations. --- doc/draft-spinel-protocol.html | 1026 +++++++----- doc/draft-spinel-protocol.txt | 1454 ++++++++++------- doc/spinel-protocol-src/Makefile | 92 ++ .../draft-spinel-protocol.md.in | 287 +++- .../spinel-example-sessions.md | 2 +- doc/spinel-protocol-src/spinel-framing.md | 4 +- doc/spinel-protocol-src/spinel-prop-mac.md | 2 +- .../spinel-security-considerations.md | 3 + .../spinel-status-codes.md | 6 +- doc/spinel-protocol-src/spinel-tech-thread.md | 4 +- .../spinel-test-vectors.md | 10 +- 11 files changed, 1815 insertions(+), 1075 deletions(-) create mode 100644 doc/spinel-protocol-src/Makefile create mode 100644 doc/spinel-protocol-src/spinel-security-considerations.md diff --git a/doc/draft-spinel-protocol.html b/doc/draft-spinel-protocol.html index 5edc25391..82d0c9004 100644 --- a/doc/draft-spinel-protocol.html +++ b/doc/draft-spinel-protocol.html @@ -375,84 +375,92 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -526,6 +534,7 @@ + @@ -533,8 +542,8 @@ - - + + @@ -555,7 +564,7 @@ - September 9, 2016 + September 10, 2016 @@ -563,7 +572,7 @@

Spinel Host-Controller Protocol
- draft-spinel-protocol-94724cf

+ draft-spinel-protocol-4d55c14

Abstract @@ -599,84 +608,92 @@ @@ -769,30 +787,133 @@

On top of this core framework, we define the properties and commands to enable various features and network protocols.

-

2. Definitions

+

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:

-

-
NCP
-

Acryonym 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 3.1.3 for more information.
-
IID
-

Interface Identifier. May be a value between zero and three. See Section 3.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 4.2 for more information.
-
+

-

3. Frame Format

-

A frame is defined simply as the concatenation of

+

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.1) 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" (Appendix C) and "Network Save" (Appendix B).

+

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

@@ -815,8 +936,8 @@ -

3.1. Header Format

-

The header byte is broken down as follows:

+

2.1. Header Format

+

The header byte is broken down as follows: 

   0   1   2   3   4   5   6   7
 +---+---+---+---+---+---+---+---+
@@ -826,17 +947,17 @@
 

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

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

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

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

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

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

 
@@ -871,11 +992,11 @@
     

   
     

   
 

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

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

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

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

-
4.1. Primitive Types

+
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

 
@@ -968,7 +1089,7 @@
         i
-      
+      
-      
+      
-      
+      
-      
+      

   
     

       
       DATATYPE_UINT_PACKEDPacked Unsigned Integer. See Section 4.2.Packed Unsigned Integer. See Section 3.2.
     

     

       
@@ -996,7 +1117,7 @@
         D
       
       DATATYPE_DATAArbitrary Data. See Section 4.3.Arbitrary Data. See Section 3.3.
     

     

       
@@ -1010,22 +1131,22 @@
         T
       
       DATATYPE_STRUCTStructured datatype. Compound type. See Section 4.4.Structured datatype. Compound type. See Section 3.4.
     

     

       
         A
       
       DATATYPE_ARRAYArray of datatypes. Compound type. See Section 4.5.Array of datatypes. Compound type. See Section 3.5.
     

   
 

-
All multi-byte values are little-endian unless explicitly stated otherwise.  

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

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

 

 
 
    
@@ -1035,39 +1156,39 @@
 

 
 
 

-
Where n is the smallest number of 7-bit chunks you can use to represent the given value.  

-
Take the value 1337, for example: 

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

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

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

 

 
 

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

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

-
5. Commands

-
5.1. CMD 0: (Host->NCP) CMD_NOOP

+
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

 
@@ -1084,10 +1205,10 @@
     

   
     

   
 

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

-
5.2. CMD 1: (Host->NCP) CMD_RESET

+
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

 
@@ -1104,10 +1225,10 @@
     

   
     

   
 

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

-
5.3. CMD 2: (Host->NCP) CMD_PROP_VALUE_GET

+
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

 
@@ -1126,10 +1247,10 @@
     

   
     

   
 

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

-
5.4. CMD 3: (Host->NCP) CMD_PROP_VALUE_SET

+
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

 
@@ -1150,10 +1271,10 @@
     

   
     

   
 

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

-
5.5. CMD 4: (Host->NCP) CMD_PROP_VALUE_INSERT

+
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

 
@@ -1174,10 +1295,10 @@
     

   
     

   
 

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

-
5.6. CMD 5: (Host->NCP) CMD_PROP_VALUE_REMOVE

+
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

 
@@ -1198,11 +1319,11 @@
     

   
     

   
 

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

-
5.7. CMD 6: (NCP->Host) CMD_PROP_VALUE_IS

+
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

 
@@ -1223,9 +1344,9 @@
     

   
     

   
 

-
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 4.2, followed by the current value of the given property.  

-
5.8. CMD 7: (NCP->Host) CMD_PROP_VALUE_INSERTED

+
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

 
@@ -1246,10 +1367,10 @@
     

   
     

   
 

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

-
5.9. CMD 8: (NCP->Host) CMD_PROP_VALUE_REMOVED

+
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

 
@@ -1270,13 +1391,13 @@
     

   
     

   
 

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

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

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

 
@@ -1307,9 +1428,9 @@
     

   
     

   
 

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

-
6.1. Property Sections

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

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

 
@@ -1323,28 +1444,28 @@
       
@@ -1356,21 +1477,21 @@
       

   
     
Core
       0x00 - 0x1F, 0x1000 - 0x11FF
       
-        Section 6.2
+        Section 5.2
       
     

     

       PHY
       0x20 - 0x2F, 0x1200 - 0x12FF
       
-        Section 6.3
+        Section 5.3
       
     

     

       MAC
       0x30 - 0x3F, 0x1300 - 0x13FF
       
-        Section 6.4
+        Section 5.4
       
     

     

       NET
       0x40 - 0x4F, 0x1400 - 0x14FF
       
-        Section 6.5
+        Section 5.5
       
     

     
IPv6
       0x60 - 0x6F, 0x1600 - 0x16FF
       
-        Section 6.6
+        Section 5.6
       
     

     

       Stream
       0x70 - 0x7F, 0x1700 - 0x17FF
       
-        Section 6.2
+        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.  

-
6.2. Core Properties

-
6.2.1. PROP 0: PROP_LAST_STATUS

+
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