mirror of
https://github.com/espressif/openthread.git
synced 2026-09-08 02:00:12 +00:00
Spinel Changes (#1777)
* spinel: Updates in preparation for IETF submission. * spinel: Use revision number instead of hash * spinel: James is the editor
This commit is contained in:
Robert Quattlebaum
committed by
Jonathan Hui
Jonathan Hui
parent
a0ff24d0ac
commit
64544d0cee
@@ -39,7 +39,7 @@ RM_F ?= rm -f
|
||||
MKDIR_P ?= mkdir -p
|
||||
|
||||
SOURCE_DATE := $(shell (TZ=UTC git log -n 1 --date=iso-strict-local --pretty=format:%ad 2> /dev/null || date -u +"%Y-%m-%dT%H:%M:%SZ" ) | sed 's/+00:00$$/Z/')
|
||||
SOURCE_VERSION := $(shell git describe --dirty --always --match "--PoIsOn--" 2> /dev/null)
|
||||
SOURCE_VERSION ?= $(shell git describe --dirty --always --match "--PoIsOn--" 2> /dev/null)
|
||||
|
||||
# -------------
|
||||
|
||||
@@ -61,6 +61,7 @@ $(XML2RFC_CACHE_DIR):
|
||||
|
||||
%.xml: %.md
|
||||
$(MMARK) -xml2 -page $< $@
|
||||
$(SED) -i "" -e 's/fullname="James Woodyatt"/fullname="James Woodyatt" role="editor"/' $@
|
||||
|
||||
%.html: %.xml $(XML2RFC_CACHE_DIR)
|
||||
$(XML2RFC) --html $<
|
||||
@@ -70,8 +71,29 @@ $(XML2RFC_CACHE_DIR):
|
||||
|
||||
# -------------
|
||||
|
||||
draft-spinel-protocol-bis.xml: \
|
||||
draft-spinel-protocol-bis.md \
|
||||
draft-rquattle-spinel-basis.xml: \
|
||||
draft-rquattle-spinel-basis.md \
|
||||
spinel-commands.md \
|
||||
spinel-data-packing.md \
|
||||
spinel-example-sessions.md \
|
||||
spinel-feature-host-buffer-offload.md \
|
||||
spinel-feature-network-save.md \
|
||||
spinel-frame-format.md \
|
||||
spinel-framing.md \
|
||||
spinel-prop-core.md \
|
||||
spinel-prop-debug.md \
|
||||
spinel-prop-ipv6.md \
|
||||
spinel-prop-mac.md \
|
||||
spinel-prop-net.md \
|
||||
spinel-prop-phy.md \
|
||||
spinel-prop.md \
|
||||
spinel-status-codes.md \
|
||||
spinel-tech-thread.md \
|
||||
spinel-test-vectors.md \
|
||||
$(NULL)
|
||||
|
||||
draft-rquattle-spinel-unified.xml: \
|
||||
draft-rquattle-spinel-unified.md \
|
||||
spinel-commands.md \
|
||||
spinel-data-packing.md \
|
||||
spinel-example-sessions.md \
|
||||
|
||||
@@ -9,7 +9,6 @@
|
||||
|
||||
[pi]
|
||||
editing = "yes"
|
||||
private = "OpenThread"
|
||||
compact = "yes"
|
||||
subcompact = "yes"
|
||||
comments = "yes"
|
||||
@@ -50,23 +49,13 @@
|
||||
|
||||
.# Abstract
|
||||
|
||||
This document specifies the basis of the Spinel protocol, which facilitates the control and management of IPv6 network interfaces in nodes 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. Spinel was initially designed for use with Thread network co-processors, but its basis is general purpose and intended to be easily adapted to other types of IPv6 network interface.
|
||||
|
||||
.# Status of This Memo
|
||||
|
||||
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
|
||||
|
||||
.# Copyright Notice
|
||||
|
||||
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 specifies the basis of 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. Spinel was initially designed for use with Thread network co-processors, but its basis is general purpose and intended to be easily adapted to other types of IPv6 network interface.
|
||||
|
||||
{mainmatter}
|
||||
|
||||
# Introduction #
|
||||
|
||||
Spinel is designed to enable the 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:
|
||||
Spinel is a host-controller protocol designed to enable interoperation over simple serial connections between general purpose device operating systems (OS) and network co-processors (NCP) for the purpose of controlling and managing their IPv6 network interfaces, achieving the following goals:
|
||||
|
||||
* Adopt a layered approach to the protocol design, allowing future support for other types of IPv6 link.
|
||||
* Minimize the number of required commands/methods by supporting a rich, property-based programming interface.
|
||||
@@ -77,78 +66,6 @@ Spinel is designed to enable the interoperation over simple serial connections b
|
||||
|
||||
On top of this core framework, properties and commands enable various common features of IPv6. In related and forthcoming documents, the Spinel protocol is extended to support NCP implementations for specific IPv6 link types, e.g. Thread.
|
||||
|
||||
## Property Overview ##
|
||||
|
||||
Spinel is largely a property-based protocol, similar to representational state transfer (REST), with a property defined for every attribute that an OS needs to create, read, update or delete in the function of an IPv6 interface. 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 extend the protocol with 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" ((#feature-host-buffer-offload)) and "Network Save" ((#feature-network-save)).
|
||||
|
||||
In Spinel, properties are keyed by an unsigned integer between 0 and 2,097,151 (See (#packed-unsigned-integer)).
|
||||
|
||||
### Property Methods ###
|
||||
|
||||
Properties may support one or more of the following methods:
|
||||
|
||||
* `VALUE_GET`
|
||||
* `VALUE_SET`
|
||||
* `VALUE_INSERT`
|
||||
* `VALUE_REMOVE`
|
||||
|
||||
Additionally, the NCP can send updates to the host (either synchronously or asynchronously) that inform the host about changes to specific properties:
|
||||
|
||||
* `VALUE_IS`
|
||||
* `VALUE_INSERTED`
|
||||
* `VALUE_REMOVED`
|
||||
|
||||
### Property Types ###
|
||||
|
||||
Conceptually, there are three different types of properties:
|
||||
|
||||
* Single-value properties
|
||||
* Multiple-value (Array) properties
|
||||
* Stream properties
|
||||
|
||||
#### Single-Value Properties ####
|
||||
|
||||
Single-value properties are properties that have a simple representation of a single value. Examples would be:
|
||||
|
||||
* Current radio channel (Represented as a unsigned 8-bit integer)
|
||||
* Network name (Represented as a UTF-8 encoded string)
|
||||
* 802\.15.4 PAN ID (Represented as a unsigned 16-bit integer)
|
||||
|
||||
The valid operations on these sorts of properties are `GET` and `SET`.
|
||||
|
||||
#### Multiple-Value Properties ####
|
||||
|
||||
Multiple-Value Properties have more than one value associated with them. Examples would be:
|
||||
|
||||
* List of channels supported by the radio hardware.
|
||||
* List of IPv6 addresses assigned to the interface.
|
||||
* List of capabilities supported by the NCP.
|
||||
|
||||
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 (#arrays)). 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 ####
|
||||
|
||||
Stream properties are special properties representing streams of data. Examples would be:
|
||||
|
||||
* Network packet stream ((#prop-stream-net))
|
||||
* Raw packet stream ((#prop-stream-raw))
|
||||
* Debug message stream ((#prop-stream-debug))
|
||||
* Network Beacon stream ((#prop-mac-scan-beacon))
|
||||
|
||||
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.
|
||||
|
||||
{{spinel-frame-format.md}}
|
||||
|
||||
{{spinel-data-packing.md}}
|
||||
@@ -185,6 +102,8 @@ These types of properties generally do not support `VALUE_GET`, as it is meaning
|
||||
|
||||
# Acknowledgments #
|
||||
|
||||
Thread is a registered trademark of The Thread Group, Inc.
|
||||
|
||||
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](https://github.com/miekg/mmark) by (Miek Gieben) and [xml2rfc (version 2)](http://xml2rfc.ietf.org/).
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
%%%
|
||||
title = "Spinel Host-Controller Protocol"
|
||||
abbrev = "Spinel Protocol (@SOURCE_VERSION@)"
|
||||
abbrev = "Spinel Protocol (Unified)"
|
||||
category = "info"
|
||||
docName = "draft-rquattle-spinel-unified-@SOURCE_VERSION@"
|
||||
ipr = "noDerivativesTrust200902"
|
||||
@@ -10,7 +10,6 @@
|
||||
|
||||
[pi]
|
||||
editing = "yes"
|
||||
private = "OpenThread"
|
||||
compact = "yes"
|
||||
subcompact = "yes"
|
||||
comments = "yes"
|
||||
@@ -33,9 +32,9 @@
|
||||
|
||||
[[author]]
|
||||
role = "editor"
|
||||
initials = "j.h."
|
||||
surname = "woodyatt"
|
||||
fullname = "james woodyatt"
|
||||
initials = "J.H."
|
||||
surname = "Woodyatt"
|
||||
fullname = "James Woodyatt"
|
||||
organization = "Nest Labs, Inc."
|
||||
|
||||
[author.address]
|
||||
@@ -51,42 +50,22 @@
|
||||
|
||||
.# Abstract
|
||||
|
||||
This document describes a general management protocol for enabling a host
|
||||
device to communicate with and manage a Network Control Processor (NCP).
|
||||
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.
|
||||
|
||||
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 also describes various Spinel specializations, including support
|
||||
for the Thread(R) low-power mesh network technology.
|
||||
|
||||
.# Status of This Memo
|
||||
|
||||
This Internet-Draft is submitted in full conformance with the provisions
|
||||
of BCP 78 and BCP 79.
|
||||
|
||||
This document is not an Internet Standards Track specification; it is
|
||||
published for informational purposes.
|
||||
|
||||
This document may not be modified, and derivative works of it may not be
|
||||
created, and it may not be published except as an Internet-Draft.
|
||||
|
||||
.# Copyright Notice
|
||||
|
||||
Copyright (c) 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.
|
||||
|
||||
{mainmatter}
|
||||
|
||||
# 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:
|
||||
Spinel is a host-controller protocol designed to enable interoperation over simple serial connections between general purpose device operating systems (OS) and network co-processors (NCP) for the purpose of controlling and managing their IPv6 network interfaces, achieving the following goals:
|
||||
|
||||
* Adopt a layered approach to the protocol design, allowing future
|
||||
support for other network protocols.
|
||||
@@ -109,6 +88,13 @@ This section discusses some ideas for changes to the protocol that
|
||||
haven't yet been fully specified, as well as some of the impetus for
|
||||
the current design.
|
||||
|
||||
### Scope ###
|
||||
|
||||
The eventual intent is to have two documents: A Spinel basis document
|
||||
which discusses the network-technology-agnostic mechanisms and a
|
||||
Thread(R) specialization document which describes all of the Thread(R)-specific
|
||||
implementation details. Currently, this document covers both.
|
||||
|
||||
### Renumbering ###
|
||||
|
||||
Efforts are currently maintained to try to prevent overtly
|
||||
@@ -141,169 +127,6 @@ has become clear that some of the initial allocations were inadequate
|
||||
and should be revisited if we want to try to achieve the original
|
||||
goal.
|
||||
|
||||
### Spinel as Application API ###
|
||||
|
||||
The current primary host driver implementation is
|
||||
[wpantund](http://wpantund.org/). wpantund manages the NCP using the
|
||||
Spinel protocol and provides a management API for the application using
|
||||
[D-Bus](https://www.freedesktop.org/wiki/Software/dbus/) 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 ((#hdlc-lite)) 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 ((#prop-lock)) 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.
|
||||
|
||||
### 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
|
||||
((#renumbering)).
|
||||
|
||||
## 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" ((#feature-host-buffer-offload)) and "Network Save"
|
||||
((#feature-network-save)).
|
||||
|
||||
In Spinel, properties are keyed by an unsigned integer between 0 and
|
||||
2,097,151 (See (#packed-unsigned-integer)).
|
||||
|
||||
### Property Methods ###
|
||||
|
||||
Properties may support one or more of the following methods:
|
||||
|
||||
* `VALUE_GET`
|
||||
* `VALUE_SET`
|
||||
* `VALUE_INSERT`
|
||||
* `VALUE_REMOVE`
|
||||
|
||||
Additionally, the NCP can send updates to the host (either
|
||||
synchronously or asynchronously) that inform the host about changes to
|
||||
specific properties:
|
||||
|
||||
* `VALUE_IS`
|
||||
* `VALUE_INSERTED`
|
||||
* `VALUE_REMOVED`
|
||||
|
||||
### Property Types ###
|
||||
|
||||
Conceptually, there are three different types of properties:
|
||||
|
||||
* Single-value properties
|
||||
* Multiple-value (Array) properties
|
||||
* Stream properties
|
||||
|
||||
#### Single-Value Properties ####
|
||||
|
||||
Single-value properties are properties that have a simple
|
||||
representation of a single value. Examples would be:
|
||||
|
||||
* Current radio channel (Represented as a unsigned 8-bit integer)
|
||||
* Network name (Represented as a UTF-8 encoded string)
|
||||
* 802\.15.4 PAN ID (Represented as a unsigned 16-bit integer)
|
||||
|
||||
The valid operations on these sorts of properties are `GET` and `SET`.
|
||||
|
||||
#### Multiple-Value Properties ####
|
||||
|
||||
Multiple-Value Properties have more than one value associated with
|
||||
them. Examples would be:
|
||||
|
||||
* List of channels supported by the radio hardware.
|
||||
* List of IPv6 addresses assigned to the interface.
|
||||
* List of capabilities supported by the NCP.
|
||||
|
||||
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 (#arrays)). 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 ####
|
||||
|
||||
Stream properties are special properties representing streams of data.
|
||||
Examples would be:
|
||||
|
||||
* Network packet stream ((#prop-stream-net))
|
||||
* Raw packet stream ((#prop-stream-raw))
|
||||
* Debug message stream ((#prop-stream-debug))
|
||||
* Network Beacon stream ((#prop-mac-scan-beacon))
|
||||
|
||||
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.
|
||||
|
||||
{{spinel-frame-format.md}}
|
||||
|
||||
@@ -341,6 +164,8 @@ is meaningless.
|
||||
|
||||
# Acknowledgments #
|
||||
|
||||
Thread is a registered trademark of The Thread Group, Inc.
|
||||
|
||||
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.
|
||||
|
||||
@@ -2,23 +2,24 @@
|
||||
|
||||
<!-- RQ -- Alphabetize before finalization. -->
|
||||
|
||||
FCS
|
||||
: Final Checksum. Bytes added to the end of a packet to help determine if the packet was received without corruption.
|
||||
|
||||
NCP
|
||||
: Network Control Processor.
|
||||
|
||||
OS
|
||||
: Operating System, i.e. the IPv6 node using Spinel to control and manage one or more of its IPv6 network interfaces.
|
||||
|
||||
TID
|
||||
: Transaction Identifier. May be a value between zero and fifteen. See (#tid-transaction-identifier) for more information.
|
||||
|
||||
NLI
|
||||
: Network Link Identifier. May be a value between zero and three. See (#nli-network-link-identifier) 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 (#packed-unsigned-integer) for more information.
|
||||
|
||||
FCS
|
||||
: Final Checksum. Bytes added to the end of a packet to help determine if the packet was received without corruption.
|
||||
OS
|
||||
: Operating System, i.e. the IPv6 node using Spinel to control and manage one or more of its IPv6 network interfaces.
|
||||
|
||||
PHY
|
||||
: Physical layer. Refers to characteristics and parameters related to the physical implementation and operation of a networking medium.
|
||||
|
||||
PUI
|
||||
: Packed Unsigned Integer. A way to serialize an unsigned integer using one, two, or three bytes. Used throughout the Spinel protocol. See (#packed-unsigned-integer) for more information.
|
||||
|
||||
TID
|
||||
: Transaction Identifier. May be a value between zero and fifteen. See (#tid-transaction-identifier) for more information.
|
||||
|
||||
|
||||
@@ -82,7 +82,7 @@ the detection window where the RSSI must be above
|
||||
The behavior of the jamming detection feature when `PROP_JAM_DETECT_BUSY`
|
||||
is larger than `PROP_JAM_DETECT_WINDOW` is undefined.
|
||||
|
||||
### PROP 4613: SPINEL_PROP_JAM_DETECT_HISTORY_BITMAP
|
||||
### PROP 4613: PROP_JAM_DETECT_HISTORY_BITMAP
|
||||
|
||||
* Type: Read-Only
|
||||
* Packed-Encoding: `LL`
|
||||
|
||||
@@ -89,8 +89,8 @@ This integer identifies what the network protocol for this NCP.
|
||||
Currently defined values are:
|
||||
|
||||
* 0: Bootloader
|
||||
* 2: ZigBeeIP
|
||||
* 3: Thread
|
||||
* 2: ZigBee IP(TM)
|
||||
* 3: Thread(R)
|
||||
|
||||
The host MUST enter a FAULT state if it does not recognize the
|
||||
protocol given by the NCP.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
## Debug Properties {#prop-debug}
|
||||
|
||||
### PROP 16384: SPINEL_PROP_DEBUG_TEST_ASSERT {#prop-debug-test-assert}
|
||||
### PROP 16384: PROP_DEBUG_TEST_ASSERT {#prop-debug-test-assert}
|
||||
* Type: Read-Only
|
||||
* Packed-Encoding: `b`
|
||||
|
||||
@@ -10,7 +10,7 @@ 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.
|
||||
|
||||
### PROP 16385: SPINEL_PROP_DEBUG_NCP_LOG_LEVEL {#prop-debug-ncp-log-level}
|
||||
### PROP 16385: PROP_DEBUG_NCP_LOG_LEVEL {#prop-debug-ncp-log-level}
|
||||
* Type: Read-Write
|
||||
* Packed-Encoding: `C`
|
||||
|
||||
@@ -26,8 +26,7 @@ the RFC 5424):
|
||||
* 6: Information (info).
|
||||
* 7: Debug (debug).
|
||||
|
||||
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`.
|
||||
|
||||
@@ -112,7 +112,7 @@ Id | Name | Description
|
||||
|
||||
See (#prop-stream-raw).
|
||||
|
||||
### PROP 57: MAC_ENERGY_SCAN_RESULT {#prop-mac-scan-result}
|
||||
### PROP 57: PROP_MAC_ENERGY_SCAN_RESULT {#prop-mac-escan-result}
|
||||
* Type: Read-Only-Stream
|
||||
* Packed-Encoding: `Cc`
|
||||
|
||||
|
||||
@@ -0,0 +1,69 @@
|
||||
Spinel is largely a property-based protocol, similar to representational state transfer (REST), with a property defined for every attribute that an OS needs to create, read, update or delete in the function of an IPv6 interface. 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 extend the protocol with 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" ((#feature-host-buffer-offload)) and "Network Save" ((#feature-network-save)).
|
||||
|
||||
In Spinel, properties are keyed by an unsigned integer between 0 and 2,097,151 (See (#packed-unsigned-integer)).
|
||||
|
||||
## Property Methods ###
|
||||
|
||||
Properties may support one or more of the following methods:
|
||||
|
||||
* `VALUE_GET` ((#prop-value-get))
|
||||
* `VALUE_SET` ((#prop-value-set))
|
||||
* `VALUE_INSERT` ((#prop-value-insert))
|
||||
* `VALUE_REMOVE` ((#prop-value-remove))
|
||||
|
||||
Additionally, the NCP can send updates to the host (either synchronously or asynchronously) that inform the host about changes to specific properties:
|
||||
|
||||
* `VALUE_IS` ((#prop-value-is))
|
||||
* `VALUE_INSERTED` ((#prop-value-inserted))
|
||||
* `VALUE_REMOVED` ((#prop-value-removed))
|
||||
|
||||
## Property Types ###
|
||||
|
||||
Conceptually, there are three different types of properties:
|
||||
|
||||
* Single-value properties
|
||||
* Multiple-value (Array) properties
|
||||
* Stream properties
|
||||
|
||||
### Single-Value Properties ####
|
||||
|
||||
Single-value properties are properties that have a simple representation of a single value. Examples would be:
|
||||
|
||||
* Current radio channel (Represented as an unsigned 8-bit integer)
|
||||
* Network name (Represented as a UTF-8 encoded string)
|
||||
* 802\.15.4 PAN ID (Represented as an unsigned 16-bit integer)
|
||||
|
||||
The valid operations on these sorts of properties are `GET` and `SET`.
|
||||
|
||||
### Multiple-Value Properties ####
|
||||
|
||||
Multiple-Value Properties have more than one value associated with them. Examples would be:
|
||||
|
||||
* List of channels supported by the radio hardware.
|
||||
* List of IPv6 addresses assigned to the interface.
|
||||
* List of capabilities supported by the NCP.
|
||||
|
||||
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 (#arrays)). 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 ####
|
||||
|
||||
Stream properties are special properties representing streams of data. Examples would be:
|
||||
|
||||
* Network packet stream ((#prop-stream-net))
|
||||
* Raw packet stream ((#prop-stream-raw))
|
||||
* Debug message stream ((#prop-stream-debug))
|
||||
* Network Beacon stream ((#prop-mac-scan-beacon))
|
||||
|
||||
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.
|
||||
@@ -1,5 +1,9 @@
|
||||
# Properties
|
||||
|
||||
{{spinel-prop-overview.md}}
|
||||
|
||||
## Property Numbering
|
||||
|
||||
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.
|
||||
|
||||
@@ -2,8 +2,8 @@
|
||||
|
||||
## 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
|
||||
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.
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
# Technology: Thread
|
||||
# Technology: Thread(R) {#tech-thread}
|
||||
|
||||
This section describes all of the properties and semantics required
|
||||
for managing a Thread NCP.
|
||||
for managing a Thread(R) NCP.
|
||||
|
||||
Thread NCPs have the following requirements:
|
||||
Thread(R) NCPs have the following requirements:
|
||||
|
||||
* The property `PROP_INTERFACE_TYPE` must be 3.
|
||||
* The non-optional properties in the following sections **MUST** be
|
||||
@@ -12,16 +12,16 @@ Thread NCPs have the following requirements:
|
||||
All serious implementations of an NCP **SHOULD** also support the network
|
||||
save feature (See (#feature-network-save)).
|
||||
|
||||
## Thread Capabilities
|
||||
## Capabilities {#thread-caps}
|
||||
|
||||
The Thread technology defines the following capabilities:
|
||||
The Thread(R) technology defines the following capabilities:
|
||||
|
||||
* `CAP_NET_THREAD_1_0` - Indicates that the NCP implements v1.0 of the Thread standard.
|
||||
* `CAP_NET_THREAD_1_1` - Indicates that the NCP implements v1.1 of the Thread standard.
|
||||
* `CAP_NET_THREAD_1_0` - Indicates that the NCP implements v1.0 of the Thread(R) standard.
|
||||
* `CAP_NET_THREAD_1_1` - Indicates that the NCP implements v1.1 of the Thread(R) standard.
|
||||
|
||||
## Thread Properties
|
||||
## Properties {#thread-properties}
|
||||
|
||||
Properties for Thread are allocated out of the `Tech` property
|
||||
Properties for Thread(R) are allocated out of the `Tech` property
|
||||
section (see (#property-sections)).
|
||||
|
||||
### PROP 80: PROP_THREAD_LEADER_ADDR
|
||||
@@ -91,7 +91,7 @@ Data per item is:
|
||||
* `6`: IPv6 Prefix
|
||||
* `C`: Prefix length, in bits
|
||||
* `b`: Stable flag
|
||||
* `C`: Thread flags
|
||||
* `C`: TLV flags
|
||||
* `b`: "Is defined locally" flag. Set if this network was locally
|
||||
defined. Assumed to be true for set, insert and replace. Clear if
|
||||
the on mesh network was defined by another node.
|
||||
@@ -124,7 +124,7 @@ This allows changes to be aggregated into single events.
|
||||
|
||||
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
|
||||
bitfield are defined by section 4.5.2 of the Thread(R)
|
||||
specification.
|
||||
|
||||
### PROP 5376: PROP_THREAD_CHILD_TIMEOUT
|
||||
@@ -149,8 +149,8 @@ Used when operating in the Child role.
|
||||
* Type: Read-Write
|
||||
* Packed-Encoding: `C`
|
||||
|
||||
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.
|
||||
|
||||
### PROP 5381: PROP_THREAD_ACTIVE_ROUTER_IDS
|
||||
* Type: Read-Write/Write-Only
|
||||
@@ -219,7 +219,7 @@ Data per item is:
|
||||
* Packed-Encoding: `C`
|
||||
|
||||
Specifies the maximum number of children currently allowed.
|
||||
This parameter can only be set when Thread protocol operation
|
||||
This parameter can only be set when Thread(R) protocol operation
|
||||
has been stopped.
|
||||
|
||||
### PROP 5389: PROP_THREAD_LEADER_NETWORK_DATA
|
||||
@@ -248,7 +248,7 @@ Data per item is:
|
||||
|
||||
Passess Pre-Shared Key for the Device to the NCP in the commissioning process.
|
||||
When the Extended address is ommited all Devices which provided a valid PSKd
|
||||
are allowed to join the Thread Network.
|
||||
are allowed to join the Thread(R) Network.
|
||||
|
||||
### PROP 5392: PROP_THREAD_COMMISSIONER_ENABLED {#prop-thread-commissioner-enabled}
|
||||
|
||||
@@ -284,7 +284,7 @@ Fields: | Length | CoAP | locator | port
|
||||
|
||||
This property allows the host to send and receive border-agent-related
|
||||
CoAP requests/responses from the NCP's RLOC address. This allows the
|
||||
host driver to implement a Thread border agent.
|
||||
host driver to implement a Thread(R) border agent.
|
||||
|
||||
|
||||
### PROP 5395: PROP_THREAD_DISOVERY_SCAN_JOINER_FLAG {#prop-thread-discovery-scan-joiner-flag}
|
||||
@@ -292,7 +292,7 @@ host driver to implement a Thread border agent.
|
||||
* Type: Read-Write
|
||||
* Packed-Encoding:: `b`
|
||||
|
||||
This property specifies the value used in Thread MLE Discovery Request
|
||||
This property specifies the value used in Thread(R) MLE Discovery Request
|
||||
TLV during discovery scan operation. Default value is `false`.
|
||||
|
||||
### PROP 5396: PROP_THREAD_DISCOVERY_SCAN_ENABLE_FILTERING {#prop-thread-discovery-scan-enable-filtering}
|
||||
@@ -303,7 +303,7 @@ 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`.
|
||||
|
||||
### PROP 5397: SPINEL_PROP_THREAD_DISCOVERY_SCAN_PANID (#prop-thread-discovery-scan-panid)
|
||||
### PROP 5397: PROP_THREAD_DISCOVERY_SCAN_PANID {#prop-thread-discovery-scan-panid}
|
||||
|
||||
* Type: Read-write
|
||||
* Packed-Encoding:: `S`
|
||||
@@ -312,11 +312,11 @@ This property specifies the PANID used for filtering during discovery
|
||||
scan operation. Default value is `0xffff` (broadcast PANID) which disables
|
||||
PANID filtering.
|
||||
|
||||
### PROP 5398: SPINEL_PROP_THREAD_STEERING_DATA {#prop-thread-steering-data}
|
||||
### PROP 5398: PROP_THREAD_STEERING_DATA {#prop-thread-steering-data}
|
||||
|
||||
* Type: Write-Only
|
||||
* Packed-Encoding: `E`
|
||||
* Required capability: `SPINEL_CAP_OOB_STEERING_DATA`
|
||||
* Required capability: `CAP_OOB_STEERING_DATA`
|
||||
|
||||
This property can be used to set the steering data for MLE Discovery
|
||||
Response messages.
|
||||
|
||||
Reference in New Issue
Block a user