i
Octets: | 1-3 |
---|---|
Fields: | LAST_STATUS |
Describes the status of the last operation. Encoded as a packed unsigned integer.
This property is emitted often to indicate the result status of pretty much any Host-to-NCP operation.
It is emitted automatically at NCP startup with a value indicating the reset reason.
See (#status-codes) for the complete list of status codes.
ii
Octets: | 1-3 | 1-3 |
---|---|---|
Fields: | MAJOR_VERSION | MINOR_VERSION |
Describes the protocol version information. This property contains four fields, each encoded as a packed unsigned integer:
This document describes major version 4, minor version 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.
U
Octets: | n |
---|---|
Fields: | NCP_VESION_STRING |
Contains a string which describes the firmware currently running on the NCP. Encoded as a zero-terminated UTF-8 string.
The format of the string is not strictly defined, but it is intended to present similarly to the “User-Agent” string from HTTP. The RECOMMENDED format of the string is as follows:
STACK-NAME/STACK-VERSION[BUILD_INFO][; OTHER_INFO]; BUILD_DATE_AND_TIME
Examples:
OpenThread/1.0d26-25-gb684c7f; DEBUG; May 9 2016 18:22:04
ConnectIP/2.0b125 s1 ALPHA; Sept 24 2015 20:49:19
The host MUST only use this property from NLI 0. Behavior when used from other NLIs is undefined.
i
Octets: | 1-3 |
---|---|
Fields: | INTERFACE_TYPE |
This integer identifies what the network protocol for this NCP. Currently defined values are:
The host MUST enter a FAULT state if it does not recognize the protocol given by the NCP.
i
Octets: | 1-3 |
---|---|
Fields: | VENDOR_ID |
Vendor identifier.
A(i)
Octets: | 1-3 | 1-3 | ... |
---|---|---|---|
Fields: | CAP_1 | CAP_2 | ... |
Describes the supported capabilities of this NCP. Encoded as a list of packed unsigned integers.
A capability is defined as a 21-bit integer that describes a subset of functionality which is supported by the NCP.
Currently defined values are:
CAP_LOCK
CAP_NET_SAVE
CAP_HBO
: Host Buffer Offload. See (#feature-host-buffer-offload).CAP_POWER_SAVE
CAP_COUNTERS
CAP_JAM_DETECT
: Jamming detection. See (#feature-jam-detect)CAP_PEEK_POKE
: PEEK/POKE debugging commands.CAP_WRITABLE_RAW_STREAM
: PROP_STREAM_RAW
is writable.CAP_GPIO
: Support for GPIO access. See (#feature-gpio-access).CAP_TRNG
: Support for true random number generation. See (#feature-trng).CAP_CMD_MULTI
: Support for CMD_PROP_VALUE_MULTI_GET
((#cmd-prop-value-multi-get)), CMD_PROP_VALUE_MULTI_SET
((#cmd-prop-value-multi-set), and CMD_PROP_VALUES_ARE
((#cmd-prop-values-are)).CAP_UNSOL_UPDATE_FILTER
: Support for PROP_UNSOL_UPDATE_FILTER
((#prop-unsol-update-filter)) and PROP_UNSOL_UPDATE_LIST
((#prop-unsol-update-list)).CAP_802_15_4_2003
CAP_802_15_4_2006
CAP_802_15_4_2011
CAP_802_15_4_PIB
CAP_802_15_4_2450MHZ_OQPSK
CAP_802_15_4_915MHZ_OQPSK
CAP_802_15_4_868MHZ_OQPSK
CAP_802_15_4_915MHZ_BPSK
CAP_802_15_4_868MHZ_BPSK
CAP_802_15_4_915MHZ_ASK
CAP_802_15_4_868MHZ_ASK
CAP_ROLE_ROUTER
CAP_ROLE_SLEEPY
CAP_NET_THREAD_1_0
CAP_MAC_WHITELIST
CAP_MAC_RAW
CAP_OOB_STEERING_DATA
CAP_THREAD_COMMISSIONER
CAP_THREAD_TMF_PROXY
Additionally, future capability allocations SHALL be made from the following allocation plan:
Capability Range | Description |
---|---|
0 - 127 | Reserved for core capabilities |
128 - 15,359 | UNALLOCATED |
15,360 - 16,383 | Vendor-specific |
16,384 - 1,999,999 | UNALLOCATED |
2,000,000 - 2,097,151 | Experimental use only |
C
Octets: | 1 |
---|---|
Fields: | INTERFACE_COUNT |
Describes the number of concurrent interfaces supported by this NCP. Since the concurrent interface mechanism is still TBD, this value MUST always be one.
This value is encoded as an unsigned 8-bit integer.
The host MUST only use this property from NLI 0. Behavior when used from other NLIs is undefined.
C
Octets: | 1 |
---|---|
Fields: | POWER_STATE |
Describes the current power state of the NCP. By writing to this property you can manage the lower state of the NCP. Enumeration is encoded as a single unsigned byte.
Defined values are:
POWER_STATE_OFFLINE
: NCP is physically powered off. (Enumerated for completeness sake, not expected on the wire)POWER_STATE_DEEP_SLEEP
: Almost everything on the NCP is shut down, but can still be resumed via a command or interrupt.POWER_STATE_STANDBY
: NCP is in the lowest power state that can still be awoken by an event from the radio (e.g. waiting for alarm)POWER_STATE_LOW_POWER
: NCP is responsive (and possibly connected), but using less power. (e.g. “Sleepy” child node)POWER_STATE_ONLINE
: NCP is fully powered. (e.g. “Parent” node)E
Octets: | 8 |
---|---|
Fields: | HWADDR |
The static EUI64 address of the device, used as a serial number. This value is read-only, but may be writable under certain vendor-defined circumstances.
b
Octets: | 1 |
---|---|
Fields: | LOCK |
Property lock. Used for grouping changes to several properties to take effect at once, or to temporarily prevent the automatic updating of property values. When this property is set, the execution of the NCP is effectively frozen until it is cleared.
This property is only supported if the CAP_LOCK
capability is present.
Unlike most other properties, setting this property to true when the value of the property is already true MUST fail with a last status of STATUS_ALREADY
.
C
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
((#prop-power-state)).
Defined values are:
HOST_POWER_STATE_OFFLINE
: Host is physically powered off and cannot be woken by the NCP. All asynchronous commands are squelched.HOST_POWER_STATE_DEEP_SLEEP
: The host is in a low power state where it can be woken by the NCP but will potentially require more than two seconds to become fully responsive. The NCP MUST avoid sending unnecessary property updates, such as child table updates or non-critical messages on the debug stream. If the NCP needs to wake the host for traffic, the NCP MUST first take action to wake the host. Once the NCP signals to the host that it should wake up, the NCP MUST wait for some activity from the host (indicating that it is fully awake) before sending frames.HOST_POWER_STATE_DEEP_SLEEP
.HOST_POWER_STATE_LOW_POWER
: The host is in a low power state where it can be immediately woken by the NCP. The NCP SHOULD avoid sending unnecessary property updates, such as child table updates or non-critical messages on the debug stream.HOST_POWER_STATE_ONLINE
: The host is awake and responsive. No special filtering is performed by the NCP on asynchronous updates.HOST_POWER_STATE_LOW_POWER
.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.
CAP_UNSOL_UPDATE_FILTER
is set.A(I)
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:
CMD_PROP_VALUE_GET
((#cmd-prop-value-get))CMD_PROP_VALUE_SET
((#cmd-prop-value-set))CMD_PROP_VALUE_IS
((#cmd-prop-value-is))Implementations of this property MAY optionally support and use the following commands:
CMD_PROP_VALUE_INSERT
((#cmd-prop-value-insert))CMD_PROP_VALUE_REMOVE
((#cmd-prop-value-remove))CMD_PROP_VALUE_INSERTED
((#cmd-prop-value-inserted))CMD_PROP_VALUE_REMOVED
((#cmd-prop-value-removed))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.
CAP_UNSOL_UPDATE_FILTER
is set.A(I)
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.
D
Octets: | n |
---|---|
Fields: | UTF8_DATA |
This property is a streaming property, meaning that you cannot explicitly fetch the value of this property. The stream provides human-readable debugging output which may be displayed in the host logs.
The location of newline characters is not assumed by the host: it is the NCP's responsibility to insert newline characters where needed, just like with any other text stream.
To receive the debugging stream, you wait for CMD_PROP_VALUE_IS
commands for this property from the NCP.
dD
Octets: | 2 | n | n |
---|---|---|---|
Fields: | FRAME_DATA_LEN | FRAME_DATA | FRAME_METADATA |
This stream provides the capability of sending and receiving raw packets to and from the radio. The exact format of the frame metadata and data is dependent on the MAC and PHY being used.
This property is a streaming property, meaning that you cannot explicitly fetch the value of this property. To receive traffic, you wait for CMD_PROP_VALUE_IS
commands with this property id from the NCP.
Implementations may OPTIONALLY support the ability to transmit arbitrary raw packets. Support for this feature is indicated by the presence of the CAP_WRITABLE_RAW_STREAM
capability.
If the capability CAP_WRITABLE_RAW_STREAM
is set, then packets written to this stream with CMD_PROP_VALUE_SET
will be sent out over the radio. This allows the caller to use the radio directly, with the stack being implemented on the host instead of the NCP.
Any data past the end of FRAME_DATA_LEN
is considered metadata and is OPTIONAL. Frame metadata MAY be empty or partially specified. Partially specified metadata MUST be accepted. Default values are used for all unspecified fields.
The same general format is used for PROP_STREAM_RAW
, PROP_STREAM_NET
, and PROP_STREAM_NET_INSECURE
. It can be used for frames sent from the NCP to the host as well as frames sent from the host to the NCP.
The frame metadata field consists of the following fields:
Field | Description | Type | Len | Default |
---|---|---|---|---|
MD_POWER | (dBm) RSSI/TX-Power | c int8 | 1 | -128 |
MD_NOISE | (dBm) Noise floor | c int8 | 1 | -128 |
MD_FLAG | Flags (defined below) | S uint16 | 2 | |
MD_PHY | PHY-specific data | d data | >=2 | |
MD_VEND | Vendor-specific data | d data | >=2 |
The following fields are ignored by the NCP for packets sent to it from the host:
When specifying MD_POWER
for a packet to be transmitted, the actual transmit power is never larger than the current value of PROP_PHY_TX_POWER
((#prop-phy-tx-power)). When left unspecified (or set to the value -128), an appropriate transmit power will be chosen by the NCP.
The bit values in MD_FLAG
are defined as follows:
Bit | Mask | Name | Description if set |
---|---|---|---|
15 | 0x0001 | MD_FLAG_TX | Packet was transmitted, not received. |
13 | 0x0004 | MD_FLAG_BAD_FCS | Packet was received with bad FCS |
12 | 0x0008 | MD_FLAG_DUPE | Packet seems to be a duplicate |
0-11, 14 | 0xFFF2 | MD_FLAG_RESERVED | Flags reserved for future use. |
The format of MD_PHY
is specified by the PHY layer currently in use, and may contain information such as the channel, LQI, antenna, or other pertainent information.
dD
Octets: | 2 | n | n |
---|---|---|---|
Fields: | FRAME_DATA_LEN | FRAME_DATA | FRAME_METADATA |
This stream provides the capability of sending and receiving data packets to and from the currently attached network. The exact format of the frame metadata and data is dependent on the network protocol being used.
This property is a streaming property, meaning that you cannot explicitly fetch the value of this property. To receive traffic, you wait for CMD_PROP_VALUE_IS
commands with this property id from the NCP.
To send network packets, you call CMD_PROP_VALUE_SET
on this property with the value of the packet.
Any data past the end of FRAME_DATA_LEN
is considered metadata, the format of which is described in (#frame-metadata-format).
dD
Octets: | 2 | n | n |
---|---|---|---|
Fields: | FRAME_DATA_LEN | FRAME_DATA | FRAME_METADATA |
This stream provides the capability of sending and receiving unencrypted and unauthenticated data packets to and from nearby devices for the purposes of device commissioning. The exact format of the frame metadata and data is dependent on the network protocol being used.
This property is a streaming property, meaning that you cannot explicitly fetch the value of this property. To receive traffic, you wait for CMD_PROP_VALUE_IS
commands with this property id from the NCP.
To send network packets, you call CMD_PROP_VALUE_SET
on this property with the value of the packet.
Any data past the end of FRAME_DATA_LEN
is considered metadata, the format of which is described in (#frame-metadata-format).