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)).
Properties may support one or more of the following methods:
VALUE_GET
((#cmd-prop-value-get))VALUE_SET
((#cmd-prop-value-set))VALUE_INSERT
((#cmd-prop-value-insert))VALUE_REMOVE
((#cmd-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
((#cmd-prop-value-is))VALUE_INSERTED
((#cmd-prop-value-inserted))VALUE_REMOVED
((#cmd-prop-value-removed))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 (#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 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.