diff --git a/doc/spinel-protocol-src/spinel-commands.md b/doc/spinel-protocol-src/spinel-commands.md index a6477d85f..0c6bae004 100644 --- a/doc/spinel-protocol-src/spinel-commands.md +++ b/doc/spinel-protocol-src/spinel-commands.md @@ -35,7 +35,7 @@ instead with the value set to the generated status code for the error. -## CMD 2: (Host->NCP) CMD_PROP_VALUE_GET {#prop-value-get} +## CMD 2: (Host->NCP) CMD_PROP_VALUE_GET {#cmd-prop-value-get} Octets: | 1 | 1 | 1-3 --------|--------|--------------------|--------- @@ -52,7 +52,7 @@ instead with the value set to the generated status code for the error. -## CMD 3: (Host->NCP) CMD_PROP_VALUE_SET {#prop-value-set} +## CMD 3: (Host->NCP) CMD_PROP_VALUE_SET {#cmd-prop-value-set} Octets: | 1 | 1 | 1-3 | *n* --------|--------|--------------------|---------|------------ @@ -71,7 +71,7 @@ with the value set to the generated status code for the error. -## CMD 4: (Host->NCP) CMD_PROP_VALUE_INSERT {#prop-value-insert} +## CMD 4: (Host->NCP) CMD_PROP_VALUE_INSERT {#cmd-prop-value-insert} Octets: | 1 | 1 | 1-3 | *n* --------|--------|-----------------------|---------|------------ @@ -99,7 +99,7 @@ with the value set to the generated status code for the error. -## CMD 5: (Host->NCP) CMD_PROP_VALUE_REMOVE {#prop-value-remove} +## CMD 5: (Host->NCP) CMD_PROP_VALUE_REMOVE {#cmd-prop-value-remove} Octets: | 1 | 1 | 1-3 | *n* --------|--------|-----------------------|---------|------------ @@ -128,7 +128,7 @@ If an error occurs, the value of `PROP_LAST_STATUS` will be emitted with the value set to the generated status code for the error. -## CMD 6: (NCP->Host) CMD_PROP_VALUE_IS {#prop-value-is} +## CMD 6: (NCP->Host) CMD_PROP_VALUE_IS {#cmd-prop-value-is} Octets: | 1 | 1 | 1-3 | *n* --------|--------|-------------------|---------|------------ @@ -145,7 +145,7 @@ the current value of the given property. -## CMD 7: (NCP->Host) CMD_PROP_VALUE_INSERTED {#prop-value-inserted} +## CMD 7: (NCP->Host) CMD_PROP_VALUE_INSERTED {#cmd-prop-value-inserted} Octets: | 1 | 1 | 1-3 | *n* --------|--------|-------------------------|---------|------------ @@ -170,7 +170,7 @@ helps to eliminate redundant data. The resulting order of items in the list is defined by the given property. -## CMD 8: (NCP->Host) CMD_PROP_VALUE_REMOVED {#prop-value-removed} +## CMD 8: (NCP->Host) CMD_PROP_VALUE_REMOVED {#cmd-prop-value-removed} Octets: | 1 | 1 | 1-3 | *n* --------|--------|------------------------|---------|------------ @@ -247,7 +247,7 @@ See (#security-considerations) for more information. This command requires the capability `CAP_PEEK_POKE` to be present. -## CMD 21: (Host->NCP) CMD_PROP_VALUE_MULTI_GET {#prop-value-multi-get} +## CMD 21: (Host->NCP) CMD_PROP_VALUE_MULTI_GET {#cmd-prop-value-multi-get} * Argument-Encoding: `A(i)` * Required Capability: `CAP_CMD_MULTI` @@ -266,7 +266,7 @@ Not all properties can be fetched using this method. As a general rule of thumb, any property that blocks when getting will fail for that individual property with `STATUS_INVALID_COMMAND_FOR_PROP`. -## CMD 22: (Host->NCP) CMD_PROP_VALUE_MULTI_SET {#prop-value-multi-set} +## CMD 22: (Host->NCP) CMD_PROP_VALUE_MULTI_SET {#cmd-prop-value-multi-set} * Argument-Encoding: `A(iD)` * Required Capability: `CAP_CMD_MULTI` @@ -299,7 +299,7 @@ Not all properties can be set using this method. As a general rule of thumb, any property that blocks when setting will fail for that individual property with `STATUS_INVALID_COMMAND_FOR_PROP`. -## CMD 23: (NCP->Host) CMD_PROP_VALUES_ARE {#prop-values-are} +## CMD 23: (NCP->Host) CMD_PROP_VALUES_ARE {#cmd-prop-values-are} * Argument-Encoding: `A(iD)` * Required Capability: `CAP_CMD_MULTI` diff --git a/doc/spinel-protocol-src/spinel-feature-gpio.md b/doc/spinel-protocol-src/spinel-feature-gpio.md index 07c9baafc..f43f57862 100644 --- a/doc/spinel-protocol-src/spinel-feature-gpio.md +++ b/doc/spinel-protocol-src/spinel-feature-gpio.md @@ -13,7 +13,7 @@ Support for this feature can be determined by the presence of `CAP_GPIO`. * Argument-Encoding: `A(t(CCU))` * Type: Read-write (Writable only using `CMD_PROP_VALUE_INSERT`, - (#prop-value-insert)) + (#cmd-prop-value-insert)) An array of structures which contain the following fields: diff --git a/doc/spinel-protocol-src/spinel-prop-core.md b/doc/spinel-protocol-src/spinel-prop-core.md index 8f62d9aa2..918fa2502 100644 --- a/doc/spinel-protocol-src/spinel-prop-core.md +++ b/doc/spinel-protocol-src/spinel-prop-core.md @@ -35,7 +35,10 @@ four fields, each encoded as a packed unsigned integer: * Major Version Number * Minor Version Number -This document describes major version 4, minor version 1 of this protocol. +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. #### Major Version Number @@ -76,6 +79,9 @@ 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. + ### PROP 3: PROP_INTERFACE_TYPE {#prop-interface-type} * Type: Read-Only @@ -133,7 +139,8 @@ Currently defined values are: * 8: `CAP_WRITABLE_RAW_STREAM`: `PROP_STREAM_RAW` is writable. * 9: `CAP_GPIO`: Support for GPIO access. See (#feature-gpio-access). * 10: `CAP_TRNG`: Support for true random number generation. See (#feature-trng). - * 11: `CAP_CMD_MULTI`: Support for `CMD_PROP_VALUE_MULTI_GET` ((#prop-value-multi-get)), `CMD_PROP_VALUE_MULTI_SET` ((#prop-value-multi-set), and `CMD_PROP_VALUES_ARE` ((#prop-values-are)). + * 11: `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)). + * 12: `CAP_UNSOL_UPDATE_FILTER`: Support for `PROP_UNSOL_UPDATE_FILTER` ((#prop-unsol-update-filter)) and `PROP_UNSOL_UPDATE_LIST` ((#prop-unsol-update-list)). * 16: `CAP_802_15_4_2003` * 17: `CAP_802_15_4_2006` * 18: `CAP_802_15_4_2011` @@ -182,6 +189,9 @@ 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. + ### PROP 7: PROP_POWER_STATE {#prop-power-state} * Type: Read-Write @@ -307,6 +317,91 @@ 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. + +### PROP 4104: PROP_UNSOL_UPDATE_FILTER {#prop-unsol-update-filter} + +* Required only if `CAP_UNSOL_UPDATE_FILTER` is set. +* Type: Read-Write +* Packed-Encoding: `A(I)` +* Default value: Empty. + +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. + +### PROP 4105: PROP_UNSOL_UPDATE_LIST {#prop-unsol-update-list} + +* Required only if `CAP_UNSOL_UPDATE_FILTER` is set. +* Type: Read-Only +* Packed-Encoding: `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. + ## Stream Properties {#prop-stream} ### PROP 112: PROP_STREAM_DEBUG {#prop-stream-debug} @@ -423,7 +518,7 @@ 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). -### PROP 114: PROP_STREAM_NET_INSECURE {#prop-stream-net-insecure} +### PROP 115: PROP_STREAM_NET_INSECURE {#prop-stream-net-insecure} * Type: Read-Write-Stream * Packed-Encoding: `dD` diff --git a/doc/spinel-protocol-src/spinel-prop-overview.md b/doc/spinel-protocol-src/spinel-prop-overview.md index d82e0bcde..b277a7426 100644 --- a/doc/spinel-protocol-src/spinel-prop-overview.md +++ b/doc/spinel-protocol-src/spinel-prop-overview.md @@ -8,16 +8,16 @@ In Spinel, properties are keyed by an unsigned integer between 0 and 2,097,151 ( 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)) +* `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` ((#prop-value-is)) -* `VALUE_INSERTED` ((#prop-value-inserted)) -* `VALUE_REMOVED` ((#prop-value-removed)) +* `VALUE_IS` ((#cmd-prop-value-is)) +* `VALUE_INSERTED` ((#cmd-prop-value-inserted)) +* `VALUE_REMOVED` ((#cmd-prop-value-removed)) ## Property Types ###