Spinel Host-Controller Protocol
- draft-rquattle-spinel-unified-86157e99-dirty
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.
-This document describes the Spinel protocol, which facilitates the control and management of IPv6 network interfaces on devices where general purpose application processors offload network functions at their interfaces to network co-processors (NCP) connected by simple communication links like serial data channels. While initially developed to support Thread(R), Spinel's layered design allows it to be easily adapted to other similar network technologies.
+This document also describes various Spinel specializations, including support for the Thread(R) low-power mesh network technology.
+This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
-This document is not an Internet Standards Track specification; it is published for informational purposes.
-This document may not be modified, and derivative works of it may not be created, and it may not be published except as an Internet-Draft.
-This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
+Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.
+Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
+This Internet-Draft will expire on December 24, 2017.
+Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved.
-This document is subject to BCP 78 and the IETF Trust’s Legal Provisions Relating to IETF Documents (<http://trustee.ietf.org/license-info>) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document.
+Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved.
+This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
+This document may not be modified, and derivative works of it may not be created, and it may not be published except as an Internet-Draft.
@@ -650,12 +665,8 @@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:
+Spinel is a host-controller protocol designed to enable interoperation over simple serial connections between general purpose device operating systems (OS) and network co-processors (NCP) for the purpose of controlling and managing their IPv6 network interfaces, achieving the following goals:
On top of this core framework, we define the properties and commands to enable various features and network protocols.
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.
-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:
+The eventual intent is to have two documents: A Spinel basis document which discusses the network-technology-agnostic mechanisms and a Thread(R) specialization document which describes all of the Thread(R)-specific implementation details. Currently, this document covers both.
+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.
-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.
-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).
-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).
-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:
- - --
Conceptually, there are three different types of 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.
-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.
-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.
+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.
A frame is defined simply as the concatenation of
@@ -1324,7 +1249,7 @@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.
-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.
-For an explanation of the data format encoding shorthand used throughout this document, see Section 3.
-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.
+The currently assigned properties are broken up into several sections, each with reserved ranges of property identifiers. These ranges are:
| Core | 0x00 - 0x1F, 0x1000 - 0x11FF | - Section 5.2 + Section 5.5 |
| PHY | 0x20 - 0x2F, 0x1200 - 0x12FF | - Section 5.4 + Section 5.7 |
| MAC | 0x30 - 0x3F, 0x1300 - 0x13FF | - Section 5.5 + Section 5.8 |
| NET | 0x40 - 0x4F, 0x1400 - 0x14FF | - Section 5.6 + Section 5.9 |
| IPv6 | 0x60 - 0x6F, 0x1600 - 0x16FF | - Section 5.7 + Section 5.10 |
| Stream | 0x70 - 0x7F, 0x1700 - 0x17FF | - Section 5.2 + Section 5.5 |
| Debug | 0x4000 - 0x4400 | - Section 5.8 + Section 5.11 |
Note that some of the property sections have two reserved ranges: a primary range (which is encoded as a single byte) and an extended range (which is encoded as two bytes). properties which are used more frequently are generally allocated from the former range.
-Note that some of the property sections have two reserved ranges: a primary range (which is encoded as a single byte) and an extended range (which is encoded as two bytes). properties which are used more frequently are generally allocated from the former range.
+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.
-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.
+Describes the protocol version information. This property contains four fields, each encoded as a packed unsigned integer:
+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.
-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.
-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.
-This document describes major version 4, minor version 3 of this protocol.
+The host MUST only use this property from NLI 0. Behavior when used from other NLIs is undefined.
+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.
+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.
+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:
+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:
+Examples:
-
The host MUST only use this property from NLI 0. Behavior when used from other NLIs is undefined.
+This integer identifies what the network protocol for this NCP. Currently defined values are:
+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.
-The host MUST enter a FAULT state if it does not recognize the protocol given by the NCP.
+Vendor identifier.
-Vendor identifier.
+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:
+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:
+Additionally, future capability allocations SHALL be made from the following allocation plan:
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.
-Describes the number of concurrent interfaces supported by this NCP. Since the concurrent interface mechanism is still TBD, this value MUST always be one.
+This value is encoded as an unsigned 8-bit integer.
+The host MUST only use this property from NLI 0. Behavior when used from other NLIs is undefined.
+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:
+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:
-
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.
-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.
+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.
-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.
++
| Octets: | +1 | +
|---|---|
| Fields: | ++ HOST_POWER_STATE + | +
Describes the current power state of the host. This property is used by the host to inform the NCP when it has changed power states. The NCP can then use this state to determine which properties need asynchronous updates. Enumeration is encoded as a single unsigned byte. These states are defined in similar terms to PROP_POWER_STATE (Section 5.5.8).
+Defined values are:
+ + ++ +
After setting this power state, any further commands from the host to the NCP will cause HOST_POWER_STATE to automatically revert to HOST_POWER_STATE_ONLINE.
+When the host is entering a low-power state, it should wait for the response from the NCP acknowledging the command (with CMD_VALUE_IS). Once that acknowledgement is received the host may enter the low-power state.
+If the NCP has the CAP_UNSOL_UPDATE_FILTER capability, any unsolicited property updates masked by PROP_UNSOL_UPDATE_FILTER should be honored while the host indicates it is in a low-power state. After resuming to the HOST_POWER_STATE_ONLINE state, the value of PROP_UNSOL_UPDATE_FILTER MUST be unchanged from the value assigned prior to the host indicating it was entering a low-power state.
+The host MUST only use this property from NLI 0. Behavior when used from other NLIs is undefined.
++
Contains a list of properties which are excluded from generating unsolicited value updates. This property MUST be empty after reset.
+In other words, the host may opt-out of unsolicited property updates for a specific property by adding that property id to this list.
+Hosts SHOULD NOT add properties to this list which are not present in PROP_UNSOL_UPDATE_LIST. If such properties are added, the NCP MUST ignore the unsupported properties.
+ +Implementations of this property are only REQUIRED to support and use the following commands:
+ + ++
Implementations of this property MAY optionally support and use the following commands:
+ + ++
Host implementations which are aiming to maximize their compatability across different firmwre implementations SHOULD NOT assume the availability of the optional commands for this property.
+The value of this property SHALL be independent for each NLI.
++
Contains a list of properties which are capable of generating unsolicited value updates. This list can be used when populating PROP_UNSOL_UPDATE_FILTER to disable all unsolicited property updates.
+This property is intended to effectively behave as a constant for a given NCP firmware.
+Note that not all properties that support unsolicited updates need to be listed here. Scan results, for example, are only generated due to direct action on the part of the host, so those properties MUST NOT not be included in this list.
+The value of this property MAY be different across available NLIs.
+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.
-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.
+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.
-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:
+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.
+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:
The following fields are ignored by the NCP for packets sent to it from the host:
+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:
+When specifying MD_POWER for a packet to be transmitted, the actual transmit power is never larger than the current value of PROP_PHY_TX_POWER (Section 5.7.6). When left unspecified (or set to the value -128), an appropriate transmit power will be chosen by the NCP.
+The bit values in MD_FLAG are defined as follows:
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.
-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.
+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.
-This stream provides the capability of sending and receiving data packets to and from the currently attached network. The exact format of the frame metadata and data is dependent on the network protocol being used.
+This property is a streaming property, meaning that you cannot explicitly fetch the value of this property. To receive traffic, you wait for CMD_PROP_VALUE_IS commands with this property id from the NCP.
+To send network packets, you call CMD_PROP_VALUE_SET on this property with the value of the packet.
+Any data past the end of FRAME_DATA_LEN is considered metadata, the format of which is described in Section 5.6.2.1.
+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.
-This stream provides the capability of sending and receiving unencrypted and unauthenticated data packets to and from nearby devices for the purposes of device commissioning. The exact format of the frame metadata and data is dependent on the network protocol being used.
+This property is a streaming property, meaning that you cannot explicitly fetch the value of this property. To receive traffic, you wait for CMD_PROP_VALUE_IS commands with this property id from the NCP.
+To send network packets, you call CMD_PROP_VALUE_SET on this property with the value of the packet.
+Any data past the end of FRAME_DATA_LEN is considered metadata, the format of which is described in Section 5.6.2.1.
+-
Set to 1 if the PHY is enabled, set to 0 otherwise. May be directly enabled to bypass higher-level packet processing in order to implement things like packet sniffers. This property can only be written if the SPINEL_CAP_MAC_RAW capability is present.
-Set to 1 if the PHY is enabled, set to 0 otherwise. May be directly enabled to bypass higher-level packet processing in order to implement things like packet sniffers. This property can only be written if the SPINEL_CAP_MAC_RAW capability is present.
+-
Value is the current channel. Must be set to one of the values contained in PROP_PHY_CHAN_SUPPORTED.
-Value is the current channel. Must be set to one of the values contained in PROP_PHY_CHAN_SUPPORTED.
+-
Value is a list of channel values that are supported by the hardware.
-Value is a list of channel values that are supported by the hardware.
+-
Value is the radio frequency (in kilohertz) of the current channel.
-Value is the radio frequency (in kilohertz) of the current channel.
+-
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.
-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.
+-
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.
-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.
+-
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.
-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.
++
Value is the radio receive sensitivity. This value can be used as lower bound noise floor for link metrics computation.
+-
Possible Values:
+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.
-Set to SCAN_STATE_BEACON to start an active scan. Beacons will be emitted from PROP_MAC_SCAN_BEACON.
+Set to SCAN_STATE_ENERGY to start an energy scan. Channel energy result will be reported by emissions of PROP_MAC_ENERGY_SCAN_RESULT (per channel).
+Set to SCAN_STATE_DISOVER to start a Thread MLE discovery scan operation. Discovery scan result will be emitted from PROP_MAC_SCAN_BEACON.
+Value switches to SCAN_STATE_IDLE when scan is complete.
+-
-
@@ -2540,19 +2667,19 @@ STACK-NAME/STACK-VERSION[BUILD_INFO][; OTHER_INFO]; BUILD_DATE_AND_TIME -
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:
+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.
-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.
+-
The 802.15.4 long address of this node.
-This property is only present on NCPs which implement 802.15.4
-The 802.15.4 long address of this node.
+This property is only present on NCPs which implement 802.15.4
+-
The 802.15.4 short address of this node.
-This property is only present on NCPs which implement 802.15.4
-The 802.15.4 short address of this node.
+This property is only present on NCPs which implement 802.15.4
+-
The 802.15.4 PANID this node is associated with.
-This property is only present on NCPs which implement 802.15.4
-The 802.15.4 PANID this node is associated with.
+This property is only present on NCPs which implement 802.15.4
+-
Set to true to enable raw MAC frames to be emitted from PROP_STREAM_RAW. See Section 5.3.2.
-Set to true to enable raw MAC frames to be emitted from PROP_STREAM_RAW. See Section 5.6.2.
+-
Possible Values:
+Possible Values:
See Section 5.3.2.
-See Section 5.6.2.
++
This property is emitted during energy scan operation per scanned channel with following format:
+ + ++
-
Structure Parameters:
+Structure Parameters:
-
-
-
Set to true to enable radio source matching or false to disable it. This property is only available if the SPINEL_CAP_MAC_RAW capability is present. The source match functionality is used by radios when generating ACKs. The short and extended address lists are used for settings the Frame Pending bit in the ACKs.
-Set to true to enable radio source matching or false to disable it. This property is only available if the SPINEL_CAP_MAC_RAW capability is present. The source match functionality is used by radios when generating ACKs. The short and extended address lists are used for settings the Frame Pending bit in the ACKs.
+-
Configures the list of short addresses used for source matching. This property is only available if the SPINEL_CAP_MAC_RAW capability is present.
-Structure Parameters:
+Configures the list of short addresses used for source matching. This property is only available if the SPINEL_CAP_MAC_RAW capability is present.
+Structure Parameters:
-
-
Configures the list of extended addresses used for source matching. This property is only available if the SPINEL_CAP_MAC_RAW capability is present.
-Structure Parameters:
+Configures the list of extended addresses used for source matching. This property is only available if the SPINEL_CAP_MAC_RAW capability is present.
+Structure Parameters:
-
+
Structure Parameters:
+ + ++
+
-
Returns true if there is a network state stored/saved.
-Returns true if there is a network state stored/saved.
+-
Network interface up/down status. Non-zero (set to 1) indicates up, zero indicates down.
-Network interface up/down status. Non-zero (set to 1) indicates up, zero indicates down.
+-
Thread stack operational status. Non-zero (set to 1) indicates up, zero indicates down.
-Thread stack operational status. Non-zero (set to 1) indicates up, zero indicates down.
+-
Values:
+Values:
-
-
-
-
-
-
The partition ID of the partition that this node is a member of.
-The partition ID of the partition that this node is a member of.
+-
-
-
-
IPv6 Address
-IPv6 Address
+-
IPv6 Address + Prefix Length
-IPv6 Address + Prefix Length
+-
IPv6 Prefix + Prefix Length
-IPv6 Prefix + Prefix Length
+-
Array of structures containing:
+Array of structures containing:
-
-
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.
-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.
+-
Reading this property will cause an assert on the NCP. This is intended for testing the assert functionality of underlying platform/NCP. Assert should ideally cause the NCP to reset, but if assert is not supported or disabled boolean value of false is returned in response.
-Reading this property will cause an assert on the NCP. This is intended for testing the assert functionality of underlying platform/NCP. Assert should ideally cause the NCP to reset, but if assert is not supported or disabled boolean value of false is returned in response.
+-
Provides access to the NCP log level. Currently defined values are (which follows the RFC 5424):
+Provides access to the NCP log level. Currently defined values are (which follows the RFC 5424):
-
If the NCP supports dynamic log level control, setting this property changes the log level accordingly. Getting the value returns the current log level. If the dynamic log level control is not supported, setting this property returns a LAST_STATUS with SPINEL_STATUS_INVALID_COMMAND_FOR_PROP status.
+If the NCP supports dynamic log level control, setting this property changes the log level accordingly. Getting the value returns the current log level. If the dynamic log level control is not supported, setting this property returns a PROP_LAST_STATUS with STATUS_INVALID_COMMAND_FOR_PROP.
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.
+See Section 5.5.1 for more information on PROP_LAST_STATUS.
-
This section describes all of the properties and semantics required for managing a Thread NCP.
-Thread NCPs have the following requirements:
+This section describes all of the properties and semantics required for managing a Thread(R) NCP.
+Thread(R) NCPs have the following requirements:
All serious implementations of an NCP SHOULD also support the network save feature (See Section 8).
-The Thread technology defines the following capabilities:
+The Thread(R) technology defines the following capabilities:
-
Properties for Thread are allocated out of the Tech property section (see Section 5.1).
+Properties for Thread(R) are allocated out of the Tech property section (see Section 5.4).
-
@@ -3132,10 +3306,12 @@ STACK-NAME/STACK-VERSION[BUILD_INFO][; OTHER_INFO]; BUILD_DATE_AND_TIME
@@ -3167,7 +3343,7 @@ STACK-NAME/STACK-VERSION[BUILD_INFO][; OTHER_INFO]; BUILD_DATE_AND_TIME
-
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.
+This property contains the value of the mode TLV for this node. The meaning of the bits in this bitfield are defined by section 4.5.2 of the Thread(R) specification.
-
Allows you to get or set the Thread NETWORK_ID_TIMEOUT constant, as defined by the Thread specification.
+Allows you to get or set the Thread(R) NETWORK_ID_TIMEOUT constant, as defined by the Thread(R) specification.
-
Specifies the maximum number of children currently allowed. This parameter can only be set when Thread protocol operation has been stopped.
+Specifies the maximum number of children currently allowed. This parameter can only be set when Thread(R) protocol operation has been stopped.
-
Passess Pre-Shared Key for the Device to the NCP in the commissioning process. When the Extended address is ommited all Devices which provided a valid PSKd are allowed to join the Thread Network.
+Passess Pre-Shared Key for the Device to the NCP in the commissioning process. When the Extended address is ommited all Devices which provided a valid PSKd are allowed to join the Thread(R) Network.
This property allows the host to send and receive TMF messages from the NCP's RLOC address and support Thread-specific border router functions.
++
This property specifies the value used in Thread(R) MLE Discovery Request TLV during discovery scan operation. Default value is false.
++
This property is used to enable/disable EUI64 filtering during discovery scan operation. Default value is false.
++
This property specifies the PANID used for filtering during discovery scan operation. Default value is 0xffff (broadcast PANID) which disables PANID filtering.
++
This property can be used to set the steering data for MLE Discovery Response messages.
+ + +
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.
@@ -3693,7 +3919,7 @@ STACK-NAME/STACK-VERSION[BUILD_INFO][; OTHER_INFO]; BUILD_DATE_AND_TIME
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.
-@@ -4022,12 +4248,12 @@ STACK-NAME/STACK-VERSION[BUILD_INFO][; OTHER_INFO]; BUILD_DATE_AND_TIME
TBD
- [CREF2]RQ: It may make sense to have a look at what Bluetooth HCI is doing for native I²C framing and go with that. + [CREF5]RQ: It may make sense to have a look at what Bluetooth HCI is doing for native I²C framing and go with that.
TBD
- [CREF3]RQ: It may make sense to have a look at what Bluetooth HCI is doing for native USB framing and go with that. + [CREF6]RQ: It may make sense to have a look at what Bluetooth HCI is doing for native USB framing and go with that.
- [CREF4]RQ: The PUI test-vector encodings need to be verified. + [CREF7]RQ: The PUI test-vector encodings need to be verified.
CMD_VALUE_IS(PROP_STREAM_NET)
- [CREF5]RQ: FIXME: This test vector is incomplete. + [CREF8]RQ: FIXME: This test vector is incomplete.
CMD_VALUE_SET(PROP_STREAM_NET)
- [CREF6]RQ: FIXME: This test vector is incomplete. + [CREF9]RQ: FIXME: This test vector is incomplete.
- [CREF7]RQ: FIXME: This test vector is incomplete. + [CREF10]RQ: FIXME: This test vector is incomplete.
- [CREF8]RQ: FIXME: This test vector is incomplete. + [CREF11]RQ: FIXME: This test vector is incomplete.
- [CREF9]RQ: FIXME: This example session is incomplete. + [CREF12]RQ: FIXME: This example session is incomplete.
Check the protocol version to see if it is supported:
@@ -4387,7 +4613,7 @@ FE
- [CREF10]RQ: FIXME: This example session is incomplete. + [CREF13]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:
@@ -4441,7 +4667,7 @@ FE
- [CREF11]RQ: FIXME: This example session is incomplete. + [CREF14]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.
@@ -4511,7 +4737,7 @@ FETBD
- [CREF12]RQ: FIXME: This example session is incomplete. + [CREF15]RQ: FIXME: This example session is incomplete.
Recall the saved network if you haven't already done so:
@@ -4551,7 +4777,7 @@ FE
- [CREF13]RQ: FIXME: This example session is incomplete. + [CREF16]RQ: FIXME: This example session is incomplete.
@@ -4568,7 +4794,7 @@ FETBD
- [CREF14]RQ: FIXME: This example session is incomplete. + [CREF17]RQ: FIXME: This example session is incomplete.
This assumes that the NCP has been initialized.
Optionally set the channel:
@@ -4620,31 +4846,32 @@ FEThis 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.
- [CREF15]RQ: Alphabetize before finalization. + [CREF18]RQ: Alphabetize before finalization.
Special thanks to Nick Banks, Jonathan Hui, Abtin Keshavarzian, Piotr Szkotak, Arjuna Sivasithambaresan and Martin Turon for their substantial contributions and feedback related to this document.
-This document was prepared using mmark by (Miek Gieben) and xml2rfc (version 2).
+Thread is a registered trademark of The Thread Group, Inc.
+Special thanks to Nick Banks, Jonathan Hui, Abtin Keshavarzian, Yakun Xu, Piotr Szkotak, Arjuna Sivasithambaresan and Martin Turon for their substantial contributions and feedback related to this document.
+This document was prepared using mmark by (Miek Gieben) and xml2rfc (version 2).