Spinel Host-Controller Protocol
- draft-spinel-protocol-05367497d
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.
-The length of the data associated with these properties depends on the number of GPIOs. If you have 10 GPIOs, you'd have two bytes. You determine the number of GPIOs available by examining PROP_GPIO_AVAILABLE, described below. This API isn't intended to support every possible GPIO state, it is intended for basic reading and writing.
+This feature allows the host to have control over some or all of the GPIO pins on the NCP. The host can determine which GPIOs are available by examining PROP_GPIO_CONFIG, described below. This API supports a maximum of 256 individual GPIO pins.
+Support for this feature can be determined by the presence of CAP_GPIO.
-
Contains a bit field identifying which GPIOs are supported. Cleared bits are not supported. Set bits are supported.
-An array of structures which contain the following fields:
-
Contains a bit field identifying which GPIOs are configured as outputs. Cleared bits are inputs. Set bits are outputs.
-GPIOs which do not have a corresponding entry are not supported.
+The configuration parameter contains the configuration flags for the GPIO:
++ 0 1 2 3 4 5 6 7 ++---+---+---+---+---+---+---+---+ +|DIR|PUP|PDN|TRIGGER| RESERVED | ++---+---+---+---+---+---+---+---+ + |O/D| + +---+ ++ + +
+
As an optional feature, the configuration of individual pins may be modified using the CMD_PROP_VALUE_INSERT command. Only the GPIO number and flags fields MUST be present, the GPIO name (if present) would be ignored. This command can only be used to modify the configuration of GPIOs which are already exposed---it cannot be used by the host to add addional GPIOs.
+-
Contains a bit field identifying the state of the GPIOs. For GPIOs configured as inputs, this is the read logic level. For GPIOs configured as outputs, this is the logic level of the output.
-Contains a bit field identifying the state of the GPIOs. The length of the data associated with these properties depends on the number of GPIOs. If you have 10 GPIOs, you'd have two bytes. GPIOs are numbered from most significant bit to least significant bit, so 0x80 is GPIO 0, 0x40 is GPIO 1, etc.
+For GPIOs configured as inputs:
+ + ++
For GPIOs configured as outputs:
+ + ++
For GPIOs which are not specified in PROP_GPIO_CONFIG:
+ + ++
When writing, unspecified bits are assumed to be zero.
+-
Allows for the state of various output GPIOs to be set without affecting other GPIO states. Contains a bit field identifying the output GPIOs that should have their state set to 1.
-Allows for the state of various output GPIOs to be set without affecting other GPIO states. Contains a bit field identifying the output GPIOs that should have their state set to 1.
+When writing, unspecified bits are assumed to be zero. The value of any bits for GPIOs which are not specified in PROP_GPIO_CONFIG MUST be ignored.
+-
Allows for the state of various output GPIOs to be cleared without affecting other GPIO states. Contains a bit field identifying the output GPIOs that should have their state cleared to 0.
+Allows for the state of various output GPIOs to be cleared without affecting other GPIO states. Contains a bit field identifying the output GPIOs that should have their state cleared to 0.
+When writing, unspecified bits are assumed to be zero. The value of any bits for GPIOs which are not specified in PROP_GPIO_CONFIG MUST be ignored.
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.
diff --git a/doc/draft-spinel-protocol.txt b/doc/draft-spinel-protocol.txt index 19599767f..18f14a4aa 100644 --- a/doc/draft-spinel-protocol.txt +++ b/doc/draft-spinel-protocol.txt @@ -4,11 +4,11 @@ R. Quattlebaum Nest Labs - November 28, 2016 + November 30, 2016 Spinel Host-Controller Protocol - draft-spinel-protocol-05367497d + draft-spinel-protocol-29f5b2c82 Abstract @@ -53,9 +53,9 @@ Copyright Notice -Quattlebaum Expires June 1, 2017 [Page 1] +Quattlebaum Expires June 3, 2017 [Page 1] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS @@ -109,9 +109,9 @@ Table of Contents -Quattlebaum Expires June 1, 2017 [Page 2] +Quattlebaum Expires June 3, 2017 [Page 2] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 5.2.3. PROP 2: PROP_NCP_VERSION . . . . . . . . . . . . . . 23 @@ -165,9 +165,9 @@ Quattlebaum Expires June 1, 2017 [Page 2] -Quattlebaum Expires June 1, 2017 [Page 3] +Quattlebaum Expires June 3, 2017 [Page 3] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 5.7.4. PROP 99: PROP_IPV6_ADDRESS_TABLE . . . . . . . . . . 37 @@ -221,9 +221,9 @@ Quattlebaum Expires June 1, 2017 [Page 3] -Quattlebaum Expires June 1, 2017 [Page 4] +Quattlebaum Expires June 3, 2017 [Page 4] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 9.2.2. PROP 11: PROP_HBO_BLOCK_MAX . . . . . . . . . . . . . 48 @@ -234,59 +234,58 @@ Quattlebaum Expires June 1, 2017 [Page 4] 10.1.3. PROP 4610: PROP_JAM_DETECT_RSSI_THRESHOLD . . . . . 49 10.1.4. PROP 4611: PROP_JAM_DETECT_WINDOW . . . . . . . . . 49 10.1.5. PROP 4612: PROP_JAM_DETECT_BUSY . . . . . . . . . . 50 - 11. Feature: Basic GPIO Access . . . . . . . . . . . . . . . . . 50 + 11. Feature: GPIO Access . . . . . . . . . . . . . . . . . . . . 50 11.1. Properties . . . . . . . . . . . . . . . . . . . . . . . 50 - 11.1.1. PROP 4096: PROP_GPIO_AVAILABLE . . . . . . . . . . . 50 - 11.1.2. PROP 4097: PROP_GPIO_DIRECTION . . . . . . . . . . . 50 - 11.1.3. PROP 4098: PROP_GPIO_STATE . . . . . . . . . . . . . 51 - 11.1.4. PROP 4099: PROP_GPIO_STATE_SET . . . . . . . . . . . 51 - 11.1.5. PROP 4100: PROP_GPIO_STATE_CLEAR . . . . . . . . . . 51 - 12. Security Considerations . . . . . . . . . . . . . . . . . . . 51 - 12.1. Raw Application Access . . . . . . . . . . . . . . . . . 51 - 13.1. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 51 - Appendix A. Framing Protocol . . . . . . . . . . . . . . . . . . 52 - A.1. UART Recommendations . . . . . . . . . . . . . . . . . . 52 - A.1.1. UART Bit Rate Detection . . . . . . . . . . . . . . . 52 - A.1.2. HDLC-Lite . . . . . . . . . . . . . . . . . . . . . . 53 - A.2. SPI Recommendations . . . . . . . . . . . . . . . . . . . 54 - A.2.1. SPI Framing Protocol . . . . . . . . . . . . . . . . 54 - A.3. I^2C Recommendations . . . . . . . . . . . . . . . . . . 56 - A.4. Native USB Recommendations . . . . . . . . . . . . . . . 56 - Appendix B. Test Vectors . . . . . . . . . . . . . . . . . . . . 56 - B.1. Test Vector: Packed Unsigned Integer . . . . . . . . . . 56 - B.2. Test Vector: Reset Command . . . . . . . . . . . . . . . 57 - B.3. Test Vector: Reset Notification . . . . . . . . . . . . . 57 - B.4. Test Vector: Scan Beacon . . . . . . . . . . . . . . . . 57 - B.5. Test Vector: Inbound IPv6 Packet . . . . . . . . . . . . 58 - B.6. Test Vector: Outbound IPv6 Packet . . . . . . . . . . . . 58 - B.7. Test Vector: Fetch list of on-mesh networks . . . . . . . 58 - B.8. Test Vector: Returned list of on-mesh networks . . . . . 59 - B.9. Test Vector: Adding an on-mesh network . . . . . . . . . 59 - B.10. Test Vector: Insertion notification of an on-mesh network 59 - B.11. Test Vector: Removing a local on-mesh network . . . . . . 60 - B.12. Test Vector: Removal notification of an on-mesh network . 60 - Appendix C. Example Sessions . . . . . . . . . . . . . . . . . . 60 - C.1. NCP Initialization . . . . . . . . . . . . . . . . . . . 60 - C.2. Attaching to a network . . . . . . . . . . . . . . . . . 61 - C.3. Successfully joining a pre-existing network . . . . . . . 62 - C.4. Unsuccessfully joining a pre-existing network . . . . . . 63 - C.5. Detaching from a network . . . . . . . . . . . . . . . . 63 - C.6. Attaching to a saved network . . . . . . . . . . . . . . 63 - C.7. NCP Software Reset . . . . . . . . . . . . . . . . . . . 64 - C.8. Adding an on-mesh prefix . . . . . . . . . . . . . . . . 64 + 11.1.1. PROP 4096: PROP_GPIO_CONFIG . . . . . . . . . . . . 50 + 11.1.2. PROP 4098: PROP_GPIO_STATE . . . . . . . . . . . . . 51 + 11.1.3. PROP 4099: PROP_GPIO_STATE_SET . . . . . . . . . . . 52 + 11.1.4. PROP 4100: PROP_GPIO_STATE_CLEAR . . . . . . . . . . 52 + 12. Security Considerations . . . . . . . . . . . . . . . . . . . 53 + 12.1. Raw Application Access . . . . . . . . . . . . . . . . . 53 + 13.1. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 53 + Appendix A. Framing Protocol . . . . . . . . . . . . . . . . . . 53 + A.1. UART Recommendations . . . . . . . . . . . . . . . . . . 53 + A.1.1. UART Bit Rate Detection . . . . . . . . . . . . . . . 54 + A.1.2. HDLC-Lite . . . . . . . . . . . . . . . . . . . . . . 54 + A.2. SPI Recommendations . . . . . . . . . . . . . . . . . . . 55 + A.2.1. SPI Framing Protocol . . . . . . . . . . . . . . . . 56 + A.3. I^2C Recommendations . . . . . . . . . . . . . . . . . . 58 + A.4. Native USB Recommendations . . . . . . . . . . . . . . . 58 + Appendix B. Test Vectors . . . . . . . . . . . . . . . . . . . . 58 + B.1. Test Vector: Packed Unsigned Integer . . . . . . . . . . 58 + B.2. Test Vector: Reset Command . . . . . . . . . . . . . . . 58 + B.3. Test Vector: Reset Notification . . . . . . . . . . . . . 59 + B.4. Test Vector: Scan Beacon . . . . . . . . . . . . . . . . 59 + B.5. Test Vector: Inbound IPv6 Packet . . . . . . . . . . . . 59 + B.6. Test Vector: Outbound IPv6 Packet . . . . . . . . . . . . 60 + B.7. Test Vector: Fetch list of on-mesh networks . . . . . . . 60 + B.8. Test Vector: Returned list of on-mesh networks . . . . . 60 + B.9. Test Vector: Adding an on-mesh network . . . . . . . . . 60 + B.10. Test Vector: Insertion notification of an on-mesh network 61 + B.11. Test Vector: Removing a local on-mesh network . . . . . . 61 + B.12. Test Vector: Removal notification of an on-mesh network . 62 + Appendix C. Example Sessions . . . . . . . . . . . . . . . . . . 62 + C.1. NCP Initialization . . . . . . . . . . . . . . . . . . . 62 + C.2. Attaching to a network . . . . . . . . . . . . . . . . . 63 + C.3. Successfully joining a pre-existing network . . . . . . . 63 + C.4. Unsuccessfully joining a pre-existing network . . . . . . 64 + C.5. Detaching from a network . . . . . . . . . . . . . . . . 64 + C.6. Attaching to a saved network . . . . . . . . . . . . . . 65 + C.7. NCP Software Reset . . . . . . . . . . . . . . . . . . . 65 + C.8. Adding an on-mesh prefix . . . . . . . . . . . . . . . . 65 + C.9. Entering low-power modes . . . . . . . . . . . . . . . . 65 -Quattlebaum Expires June 1, 2017 [Page 5] +Quattlebaum Expires June 3, 2017 [Page 5] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 - C.9. Entering low-power modes . . . . . . . . . . . . . . . . 64 - C.10. Sniffing raw packets . . . . . . . . . . . . . . . . . . 64 - Appendix D. Acknowledgments . . . . . . . . . . . . . . . . . . 65 - Appendix E. Glossary . . . . . . . . . . . . . . . . . . . . . . 65 - Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 66 + C.10. Sniffing raw packets . . . . . . . . . . . . . . . . . . 65 + Appendix D. Acknowledgments . . . . . . . . . . . . . . . . . . 66 + Appendix E. Glossary . . . . . . . . . . . . . . . . . . . . . . 67 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 68 1. Introduction @@ -329,17 +328,16 @@ Quattlebaum Expires June 1, 2017 [Page 5] the host and the NCP, the following commands and properties are already considered to be "baked" and will not change: - - - - -Quattlebaum Expires June 1, 2017 [Page 6] - - Spinel Protocol (05367497d) November 2016 - - o Command IDs zero through eight. (Reset, No-op, and Property-Value Commands) + + + +Quattlebaum Expires June 3, 2017 [Page 6] + + Spinel Protocol (29f5b2c82) November 2016 + + o Property IDs zero through two. (Last status, Protocol Version, and NCP Version) @@ -385,18 +383,17 @@ Quattlebaum Expires June 1, 2017 [Page 6] 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 - - - - -Quattlebaum Expires June 1, 2017 [Page 7] - - Spinel Protocol (05367497d) November 2016 - - ensure exclusive access to the NCP by an application. Only one process would be allowed to enable the lock at a time. + + + +Quattlebaum Expires June 3, 2017 [Page 7] + + Spinel Protocol (29f5b2c82) November 2016 + + 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 @@ -443,16 +440,16 @@ Quattlebaum Expires June 1, 2017 [Page 7] exceptions include "Host Buffer Offload" (Section 9) and "Network Save" (Section 8). - - -Quattlebaum Expires June 1, 2017 [Page 8] - - Spinel Protocol (05367497d) November 2016 - - In Spinel, properties are keyed by an unsigned integer between 0 and 2,097,151 (See Section 3.2). + + +Quattlebaum Expires June 3, 2017 [Page 8] + + Spinel Protocol (29f5b2c82) November 2016 + + 1.2.1. Property Methods Properties may support one or more of the following methods: @@ -499,16 +496,16 @@ Quattlebaum Expires June 1, 2017 [Page 8] o List of IPv6 addresses assigned to the interface. o List of capabilities supported by the NCP. - - -Quattlebaum Expires June 1, 2017 [Page 9] - - Spinel Protocol (05367497d) November 2016 - - The valid operations on these sorts of properties are "VALUE_GET", "VALUE_SET", "VALUE_INSERT", and "VALUE_REMOVE". + + +Quattlebaum Expires June 3, 2017 [Page 9] + + Spinel Protocol (29f5b2c82) November 2016 + + 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 @@ -557,9 +554,12 @@ Quattlebaum Expires June 1, 2017 [Page 9] -Quattlebaum Expires June 1, 2017 [Page 10] + + + +Quattlebaum Expires June 3, 2017 [Page 10] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 +---------+--------+-----+-------------+ @@ -613,9 +613,9 @@ Quattlebaum Expires June 1, 2017 [Page 10] -Quattlebaum Expires June 1, 2017 [Page 11] +Quattlebaum Expires June 3, 2017 [Page 11] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 The TID value of zero (0) is used for commands to which a correlated @@ -669,9 +669,9 @@ Quattlebaum Expires June 1, 2017 [Page 11] -Quattlebaum Expires June 1, 2017 [Page 12] +Quattlebaum Expires June 3, 2017 [Page 12] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 o "C6U": A single unsigned byte, followed by a 128-bit IPv6 address, @@ -725,9 +725,9 @@ Quattlebaum Expires June 1, 2017 [Page 12] -Quattlebaum Expires June 1, 2017 [Page 13] +Quattlebaum Expires June 3, 2017 [Page 13] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 The packed unsigned integer format is based on the unsigned integer @@ -781,9 +781,9 @@ Quattlebaum Expires June 1, 2017 [Page 13] -Quattlebaum Expires June 1, 2017 [Page 14] +Quattlebaum Expires June 3, 2017 [Page 14] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 However, things are a little different with "CLDL". Since our data @@ -837,9 +837,9 @@ Quattlebaum Expires June 1, 2017 [Page 14] -Quattlebaum Expires June 1, 2017 [Page 15] +Quattlebaum Expires June 3, 2017 [Page 15] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 3.5. Arrays @@ -893,9 +893,9 @@ Quattlebaum Expires June 1, 2017 [Page 15] -Quattlebaum Expires June 1, 2017 [Page 16] +Quattlebaum Expires June 3, 2017 [Page 16] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 If an error occurs, the value of "PROP_LAST_STATUS" will be emitted @@ -949,9 +949,9 @@ Quattlebaum Expires June 1, 2017 [Page 16] -Quattlebaum Expires June 1, 2017 [Page 17] +Quattlebaum Expires June 3, 2017 [Page 17] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 Insert value into property command. Instructs the NCP to insert the @@ -1005,9 +1005,9 @@ Quattlebaum Expires June 1, 2017 [Page 17] -Quattlebaum Expires June 1, 2017 [Page 18] +Quattlebaum Expires June 3, 2017 [Page 18] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 The payload for this command is the property identifier encoded in @@ -1061,9 +1061,9 @@ Quattlebaum Expires June 1, 2017 [Page 18] -Quattlebaum Expires June 1, 2017 [Page 19] +Quattlebaum Expires June 3, 2017 [Page 19] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 4.10. CMD 18: (Host->NCP) CMD_PEEK @@ -1117,9 +1117,9 @@ Quattlebaum Expires June 1, 2017 [Page 19] -Quattlebaum Expires June 1, 2017 [Page 20] +Quattlebaum Expires June 3, 2017 [Page 20] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 Due to the low-level nature of this command, certain error conditions @@ -1173,9 +1173,9 @@ Quattlebaum Expires June 1, 2017 [Page 20] -Quattlebaum Expires June 1, 2017 [Page 21] +Quattlebaum Expires June 3, 2017 [Page 21] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 Note that each property section has two reserved ranges: a primary @@ -1229,9 +1229,9 @@ Quattlebaum Expires June 1, 2017 [Page 21] -Quattlebaum Expires June 1, 2017 [Page 22] +Quattlebaum Expires June 3, 2017 [Page 22] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 5.2.2.1. Major Version Number @@ -1285,9 +1285,9 @@ Quattlebaum Expires June 1, 2017 [Page 22] -Quattlebaum Expires June 1, 2017 [Page 23] +Quattlebaum Expires June 3, 2017 [Page 23] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 +---------+----------------+ @@ -1341,9 +1341,9 @@ Quattlebaum Expires June 1, 2017 [Page 23] -Quattlebaum Expires June 1, 2017 [Page 24] +Quattlebaum Expires June 3, 2017 [Page 24] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 o 1: "CAP_LOCK" @@ -1354,6 +1354,7 @@ Quattlebaum Expires June 1, 2017 [Page 24] o 6: "CAP_JAM_DETECT": Jamming detection. See Section 10 o 7: "CAP_PEEK_POKE": PEEK/POKE debugging commands. o 8: "CAP_WRITABLE_RAW_STREAM": "PROP_STREAM_RAW" is writable. + o 9: "CAP_GPIO": Support for GPIO access. See Section 11. o 16: "CAP_802_15_4_2003" o 17: "CAP_802_15_4_2006" o 18: "CAP_802_15_4_2011" @@ -1396,10 +1397,9 @@ Quattlebaum Expires June 1, 2017 [Page 24] - -Quattlebaum Expires June 1, 2017 [Page 25] +Quattlebaum Expires June 3, 2017 [Page 25] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 Describes the number of concurrent interfaces supported by this NCP. @@ -1453,9 +1453,9 @@ Quattlebaum Expires June 1, 2017 [Page 25] -Quattlebaum Expires June 1, 2017 [Page 26] +Quattlebaum Expires June 3, 2017 [Page 26] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 The static EUI64 address of the device, used as a serial number. @@ -1509,9 +1509,9 @@ Quattlebaum Expires June 1, 2017 [Page 26] -Quattlebaum Expires June 1, 2017 [Page 27] +Quattlebaum Expires June 3, 2017 [Page 27] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 To receive the debugging stream, you wait for "CMD_PROP_VALUE_IS" @@ -1565,9 +1565,9 @@ Quattlebaum Expires June 1, 2017 [Page 27] -Quattlebaum Expires June 1, 2017 [Page 28] +Quattlebaum Expires June 3, 2017 [Page 28] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 +----------+-----------------------+------------+-----+---------+ @@ -1621,9 +1621,9 @@ Quattlebaum Expires June 1, 2017 [Page 28] -Quattlebaum Expires June 1, 2017 [Page 29] +Quattlebaum Expires June 3, 2017 [Page 29] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 +---------+----------------+------------+----------------+ @@ -1677,9 +1677,9 @@ Quattlebaum Expires June 1, 2017 [Page 29] -Quattlebaum Expires June 1, 2017 [Page 30] +Quattlebaum Expires June 3, 2017 [Page 30] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 Any data past the end of "FRAME_DATA_LEN" is considered metadata, the @@ -1733,9 +1733,9 @@ Quattlebaum Expires June 1, 2017 [Page 30] -Quattlebaum Expires June 1, 2017 [Page 31] +Quattlebaum Expires June 3, 2017 [Page 31] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 When setting, the value will be rounded down to a value that is @@ -1789,9 +1789,9 @@ Quattlebaum Expires June 1, 2017 [Page 31] -Quattlebaum Expires June 1, 2017 [Page 32] +Quattlebaum Expires June 3, 2017 [Page 32] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 5.5.2. PROP 49: PROP_MAC_SCAN_MASK @@ -1845,9 +1845,9 @@ Quattlebaum Expires June 1, 2017 [Page 32] -Quattlebaum Expires June 1, 2017 [Page 33] +Quattlebaum Expires June 3, 2017 [Page 33] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 5.5.5. PROP 52: PROP_MAC_15_4_LADDR @@ -1901,9 +1901,9 @@ Quattlebaum Expires June 1, 2017 [Page 33] -Quattlebaum Expires June 1, 2017 [Page 34] +Quattlebaum Expires June 3, 2017 [Page 34] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 +----+--------------------------------+-----------------------------+ @@ -1957,9 +1957,9 @@ Quattlebaum Expires June 1, 2017 [Page 34] -Quattlebaum Expires June 1, 2017 [Page 35] +Quattlebaum Expires June 3, 2017 [Page 35] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 Network interface up/down status. Non-zero (set to 1) indicates up, @@ -2013,9 +2013,9 @@ Quattlebaum Expires June 1, 2017 [Page 35] -Quattlebaum Expires June 1, 2017 [Page 36] +Quattlebaum Expires June 3, 2017 [Page 36] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 5.6.9. PROP 72: PROP_NET_PARTITION_ID @@ -2069,9 +2069,9 @@ Quattlebaum Expires June 1, 2017 [Page 36] -Quattlebaum Expires June 1, 2017 [Page 37] +Quattlebaum Expires June 3, 2017 [Page 37] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 5.7.5. PROP 101: PROP_IPv6_ICMP_PING_OFFLOAD @@ -2125,9 +2125,9 @@ Quattlebaum Expires June 1, 2017 [Page 37] -Quattlebaum Expires June 1, 2017 [Page 38] +Quattlebaum Expires June 3, 2017 [Page 38] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 o 11: "STATUS_NOMEM": The operation has been prevented due to memory @@ -2181,9 +2181,9 @@ Quattlebaum Expires June 1, 2017 [Page 38] -Quattlebaum Expires June 1, 2017 [Page 39] +Quattlebaum Expires June 3, 2017 [Page 39] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 7.1. Thread Capabilities @@ -2237,9 +2237,9 @@ Quattlebaum Expires June 1, 2017 [Page 39] -Quattlebaum Expires June 1, 2017 [Page 40] +Quattlebaum Expires June 3, 2017 [Page 40] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 7.2.5. PROP 84: PROP_THREAD_LEADER_WEIGHT @@ -2293,9 +2293,9 @@ Quattlebaum Expires June 1, 2017 [Page 40] -Quattlebaum Expires June 1, 2017 [Page 41] +Quattlebaum Expires June 3, 2017 [Page 41] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 7.2.12. PROP 91: PROP_THREAD_LOCAL_ROUTES @@ -2349,9 +2349,9 @@ Quattlebaum Expires June 1, 2017 [Page 41] -Quattlebaum Expires June 1, 2017 [Page 42] +Quattlebaum Expires June 3, 2017 [Page 42] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 7.2.18. PROP 5378: PROP_THREAD_ROUTER_UPGRADE_THRESHOLD @@ -2405,9 +2405,9 @@ Quattlebaum Expires June 1, 2017 [Page 42] -Quattlebaum Expires June 1, 2017 [Page 43] +Quattlebaum Expires June 3, 2017 [Page 43] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 7.2.24. PROP 5384: PROP_THREAD_ROUTER_DOWNGRADE_THRESHOLD @@ -2461,9 +2461,9 @@ Quattlebaum Expires June 1, 2017 [Page 43] -Quattlebaum Expires June 1, 2017 [Page 44] +Quattlebaum Expires June 3, 2017 [Page 44] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 The presence of this feature can be detected by checking for the @@ -2517,9 +2517,9 @@ Quattlebaum Expires June 1, 2017 [Page 44] -Quattlebaum Expires June 1, 2017 [Page 45] +Quattlebaum Expires June 3, 2017 [Page 45] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 8.1.3. CMD 11: (Host->NCP) CMD_NET_RECALL @@ -2573,9 +2573,9 @@ Quattlebaum Expires June 1, 2017 [Page 45] -Quattlebaum Expires June 1, 2017 [Page 46] +Quattlebaum Expires June 3, 2017 [Page 46] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 9.1.2. CMD 13: (NCP->Host) CMD_HBO_RECLAIM @@ -2629,9 +2629,9 @@ Quattlebaum Expires June 1, 2017 [Page 46] -Quattlebaum Expires June 1, 2017 [Page 47] +Quattlebaum Expires June 3, 2017 [Page 47] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 Describes the number of bytes that may be offloaded from the NCP to @@ -2685,9 +2685,9 @@ Quattlebaum Expires June 1, 2017 [Page 47] -Quattlebaum Expires June 1, 2017 [Page 48] +Quattlebaum Expires June 3, 2017 [Page 48] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 +---------+--------------------------+ @@ -2741,9 +2741,9 @@ Quattlebaum Expires June 1, 2017 [Page 48] -Quattlebaum Expires June 1, 2017 [Page 49] +Quattlebaum Expires June 3, 2017 [Page 49] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 o Default Value: Implementation-specific @@ -2768,49 +2768,118 @@ Quattlebaum Expires June 1, 2017 [Page 49] "PROP_JAM_DETECT_BUSY" is larger than "PROP_JAM_DETECT_WINDOW" is undefined. -11. Feature: Basic GPIO Access +11. Feature: GPIO Access - The length of the data associated with these properties depends on - the number of GPIOs. If you have 10 GPIOs, you'd have two bytes. - You determine the number of GPIOs available by examining - PROP_GPIO_AVAILABLE, described below. This API isn't intended to - support every possible GPIO state, it is intended for basic reading - and writing. + This feature allows the host to have control over some or all of the + GPIO pins on the NCP. The host can determine which GPIOs are + available by examining "PROP_GPIO_CONFIG", described below. This API + supports a maximum of 256 individual GPIO pins. + + Support for this feature can be determined by the presence of + "CAP_GPIO". 11.1. Properties -11.1.1. PROP 4096: PROP_GPIO_AVAILABLE +11.1.1. PROP 4096: PROP_GPIO_CONFIG - o Type: Read-only + o Argument-Encoding: "A(CCU)" + o Type: Read-write (Writable only using "CMD_PROP_VALUE_INSERT", + Section 4.5) - Contains a bit field identifying which GPIOs are supported. Cleared - bits are not supported. Set bits are supported. + An array of structures which contain the following fields: -11.1.2. PROP 4097: PROP_GPIO_DIRECTION + o "C": GPIO Number + o "C": GPIO Configuration Flags + o "U": Human-readable GPIO name - o Type: Read-only (Optionally read/write) - - Contains a bit field identifying which GPIOs are configured as - outputs. Cleared bits are inputs. Set bits are outputs. + GPIOs which do not have a corresponding entry are not supported. - -Quattlebaum Expires June 1, 2017 [Page 50] +Quattlebaum Expires June 3, 2017 [Page 50] - Spinel Protocol (05367497d) November 2016 + Spinel Protocol (29f5b2c82) November 2016 -11.1.3. PROP 4098: PROP_GPIO_STATE + The configuration parameter contains the configuration flags for the + GPIO: + + 0 1 2 3 4 5 6 7 + +---+---+---+---+---+---+---+---+ + |DIR|PUP|PDN|TRIGGER| RESERVED | + +---+---+---+---+---+---+---+---+ + |O/D| + +---+ + + o "DIR": Pin direction. Clear (0) for input, set (1) for output. + o "PUP": Pull-up enabled flag. + o "PDN"/"O/D": Flag meaning depends on pin direction: + + * Input: Pull-down enabled. + * Output: Output is an open-drain. + o "TRIGGER": Enumeration describing how pin changes generate + asynchronous notification commands (TBD) from the NCP to the host. + + * 0: Feature disabled for this pin + * 1: Trigger on falling edge + * 2: Trigger on rising edge + * 3: Trigger on level change + o "RESERVED": Bits reserved for future use. Always cleared to zero + and ignored when read. + + As an optional feature, the configuration of individual pins may be + modified using the "CMD_PROP_VALUE_INSERT" command. Only the GPIO + number and flags fields MUST be present, the GPIO name (if present) + would be ignored. This command can only be used to modify the + configuration of GPIOs which are already exposed---it cannot be used + by the host to add addional GPIOs. + +11.1.2. PROP 4098: PROP_GPIO_STATE o Type: Read-Write - Contains a bit field identifying the state of the GPIOs. For GPIOs - configured as inputs, this is the read logic level. For GPIOs - configured as outputs, this is the logic level of the output. + Contains a bit field identifying the state of the GPIOs. The length + of the data associated with these properties depends on the number of + GPIOs. If you have 10 GPIOs, you'd have two bytes. GPIOs are + numbered from most significant bit to least significant bit, so 0x80 + is GPIO 0, 0x40 is GPIO 1, etc. -11.1.4. PROP 4099: PROP_GPIO_STATE_SET + For GPIOs configured as inputs: + + o "CMD_PROP_VAUE_GET": The value of the associated bit describes the + logic level read from the pin. + + + + +Quattlebaum Expires June 3, 2017 [Page 51] + + Spinel Protocol (29f5b2c82) November 2016 + + + o "CMD_PROP_VALUE_SET": The value of the associated bit is ignored + for these pins. + + For GPIOs configured as outputs: + + o "CMD_PROP_VAUE_GET": The value of the associated bit is + implementation specific. + o "CMD_PROP_VALUE_SET": The value of the associated bit determines + the new logic level of the output. If this pin is configured as + an open-drain, setting the associated bit to 1 will cause the pin + to enter a Hi-Z state. + + For GPIOs which are not specified in "PROP_GPIO_CONFIG": + + o "CMD_PROP_VAUE_GET": The value of the associated bit is + implementation specific. + o "CMD_PROP_VALUE_SET": The value of the associated bit MUST be + ignored by the NCP. + + When writing, unspecified bits are assumed to be zero. + +11.1.3. PROP 4099: PROP_GPIO_STATE_SET o Type: Write-only @@ -2818,7 +2887,11 @@ Quattlebaum Expires June 1, 2017 [Page 50] affecting other GPIO states. Contains a bit field identifying the output GPIOs that should have their state set to 1. -11.1.5. PROP 4100: PROP_GPIO_STATE_CLEAR + When writing, unspecified bits are assumed to be zero. The value of + any bits for GPIOs which are not specified in "PROP_GPIO_CONFIG" MUST + be ignored. + +11.1.4. PROP 4100: PROP_GPIO_STATE_CLEAR o Type: Write-only @@ -2826,6 +2899,21 @@ Quattlebaum Expires June 1, 2017 [Page 50] affecting other GPIO states. Contains a bit field identifying the output GPIOs that should have their state cleared to 0. + When writing, unspecified bits are assumed to be zero. The value of + any bits for GPIOs which are not specified in "PROP_GPIO_CONFIG" MUST + be ignored. + + + + + + + +Quattlebaum Expires June 3, 2017 [Page 52] + + Spinel Protocol (29f5b2c82) November 2016 + + 12. Security Considerations 12.1. Raw Application Access @@ -2851,13 +2939,6 @@ Quattlebaum Expires June 1, 2017 [Page 50] [5] https://github.com/miekg/mmark - - -Quattlebaum Expires June 1, 2017 [Page 51] - - Spinel Protocol (05367497d) November 2016 - - [6] http://xml2rfc.ietf.org/ Appendix A. Framing Protocol @@ -2881,6 +2962,14 @@ A.1. UART Recommendations These values may be adjusted depending on the individual needs of the application or product, but some sort of flow control MUST be used. Hardware flow control is preferred over software flow control. In + + + +Quattlebaum Expires June 3, 2017 [Page 53] + + Spinel Protocol (29f5b2c82) November 2016 + + the absence of hardware flow control, software flow control (XON/ XOFF) MUST be used instead. @@ -2905,15 +2994,6 @@ A.1.1. UART Bit Rate Detection bitrate detection scheme that can be employed by the host to detect when the attached NCP is initially running at a higher bitrate. - - - - -Quattlebaum Expires June 1, 2017 [Page 52] - - Spinel Protocol (05367497d) November 2016 - - The algorithm is to send successive NOOP commands to the NCP at increasing bitrates. When a valid "CMD_LAST_STATUS" response has been received, we have identified the correct bitrate. @@ -2936,6 +3016,16 @@ A.1.2. HDLC-Lite of HDLC are omitted. This protocol was chosen because it works well with software flow control and is widely implemented. + + + + + +Quattlebaum Expires June 3, 2017 [Page 54] + + Spinel Protocol (29f5b2c82) November 2016 + + To transmit a frame with HDLC-lite, the 16-bit CRC must first be appended to the frame. The CRC function is defined to be CRC-16/ CCITT, otherwise known as the KERMIT CRC [4]. @@ -2962,14 +3052,6 @@ A.1.2. HDLC-Lite When receiving a frame, the CRC must be verified after the frame is unescaped. If the CRC value does not match what is calculated for - - - -Quattlebaum Expires June 1, 2017 [Page 53] - - Spinel Protocol (05367497d) November 2016 - - the frame data, the frame MUST be discarded. The implementation MAY indicate the failure to higher levels to handle as they see fit, but MUST NOT attempt to process the deceived frame. @@ -2993,6 +3075,13 @@ A.2. SPI Recommendations o "I̅N̅T̅": (NCP-to-Host) Host Interrupt o "R̅E̅S̅": (Host-to-NCP) NCP Hardware Reset + + +Quattlebaum Expires June 3, 2017 [Page 55] + + Spinel Protocol (29f5b2c82) November 2016 + + The "I̅N̅T̅" signal is used by the NCP to indicate to the host that the NCP has frames pending to send to it. When asserted, the host SHOULD initiate a SPI transaction in a timely @@ -3014,18 +3103,6 @@ A.2.1. SPI Framing Protocol Each SPI frame starts with a 5-byte frame header: - - - - - - - -Quattlebaum Expires June 1, 2017 [Page 54] - - Spinel Protocol (05367497d) November 2016 - - +---------+-----+----------+----------+ | Octets: | 1 | 2 | 2 | +---------+-----+----------+----------+ @@ -3051,6 +3128,16 @@ Quattlebaum Expires June 1, 2017 [Page 54] o "RST": This bit is set when that device has been reset since the last time "C̅S̅" was asserted. + + + + + +Quattlebaum Expires June 3, 2017 [Page 56] + + Spinel Protocol (29f5b2c82) November 2016 + + o "CRC": This bit is set when that device supports writing a 16-bit CRC at the end of the data. The CRC length is NOT included in DATA_LEN. @@ -3074,14 +3161,6 @@ Quattlebaum Expires June 1, 2017 [Page 54] Alternatively, if the master has a frame to send it can just go ahead and send a frame of that length and determine if the frame was accepted by checking that the "RECV_LEN" from the slave frame is - - - -Quattlebaum Expires June 1, 2017 [Page 55] - - Spinel Protocol (05367497d) November 2016 - - larger than the frame the master just tried to send. If the "RECV_LEN" is smaller then the frame wasn't accepted and will need to be transmitted again. @@ -3107,6 +3186,14 @@ Quattlebaum Expires June 1, 2017 [Page 55] the frame. If not enough bytes were clocked out for the CRC to be read, then the frame must be ignored. If enough bytes were clocked out to perform a CRC check, but the CRC check fails, then the frame + + + +Quattlebaum Expires June 3, 2017 [Page 57] + + Spinel Protocol (29f5b2c82) November 2016 + + must be rejected and the "CRC_FAIL" bit on the next frame (and ONLY the next frame) MUST be set. @@ -3126,18 +3213,6 @@ Appendix B. Test Vectors B.1. Test Vector: Packed Unsigned Integer - - - - - - - -Quattlebaum Expires June 1, 2017 [Page 56] - - Spinel Protocol (05367497d) November 2016 - - +---------------+-----------------------+ | Decimal Value | Packet Octet Encoding | +---------------+-----------------------+ @@ -3165,6 +3240,16 @@ B.2. Test Vector: Reset Command 80 01 + + + + + +Quattlebaum Expires June 3, 2017 [Page 58] + + Spinel Protocol (29f5b2c82) November 2016 + + B.3. Test Vector: Reset Notification o IID: 0 @@ -3186,14 +3271,6 @@ B.4. Test Vector: Scan Beacon o VALUE: Structure, encoded as "CcT(ESSc.)T(iCUD.)." * CHAN: 15 - - - -Quattlebaum Expires June 1, 2017 [Page 57] - - Spinel Protocol (05367497d) November 2016 - - * RSSI: -60dBm * MAC_DATA: (0D 00 B6 40 D4 8C E9 38 F9 52 FF FF D2 04 00) @@ -3221,6 +3298,14 @@ B.5. Test Vector: Inbound IPv6 Packet [CREF5] + + + +Quattlebaum Expires June 3, 2017 [Page 59] + + Spinel Protocol (29f5b2c82) November 2016 + + B.6. Test Vector: Outbound IPv6 Packet CMD_VALUE_SET(PROP_STREAM_NET) @@ -3238,18 +3323,6 @@ B.7. Test Vector: Fetch list of on-mesh networks 84 02 5A - - - - - - - -Quattlebaum Expires June 1, 2017 [Page 58] - - Spinel Protocol (05367497d) November 2016 - - B.8. Test Vector: Returned list of on-mesh networks o IID: 0 @@ -3279,6 +3352,16 @@ B.9. Test Vector: Adding an on-mesh network o PROP: 90 ("PROP_THREAD_ON_MESH_NETS") o VALUE: Structure, encoded as "6CbCb" + + + + + +Quattlebaum Expires June 3, 2017 [Page 60] + + Spinel Protocol (29f5b2c82) November 2016 + + +--------------+---------------+-------------+-------------+ | IPv6 Prefix | Prefix Length | Stable Flag | Other Flags | +--------------+---------------+-------------+-------------+ @@ -3298,14 +3381,6 @@ B.10. Test Vector: Insertion notification of an on-mesh network o TID: 5 o CMD: 7 ("CMD_VALUE_INSERTED") o PROP: 90 ("PROP_THREAD_ON_MESH_NETS") - - - -Quattlebaum Expires June 1, 2017 [Page 59] - - Spinel Protocol (05367497d) November 2016 - - o VALUE: Structure, encoded as "6CbCb" +--------------+---------------+-------------+-------------+ @@ -3333,6 +3408,16 @@ B.11. Test Vector: Removing a local on-mesh network 86 05 5A 20 01 0D B8 00 03 00 00 00 00 00 00 00 00 00 00 + + + + + +Quattlebaum Expires June 3, 2017 [Page 61] + + Spinel Protocol (29f5b2c82) November 2016 + + B.12. Test Vector: Removal notification of an on-mesh network o IID: 0 @@ -3354,14 +3439,6 @@ C.1. NCP Initialization Check the protocol version to see if it is supported: o CMD_VALUE_GET:PROP_PROTOCOL_VERSION - - - -Quattlebaum Expires June 1, 2017 [Page 60] - - Spinel Protocol (05367497d) November 2016 - - o CMD_VALUE_IS:PROP_PROTOCOL_VERSION Check the NCP version to see if a firmware update may be necessary: @@ -3389,6 +3466,14 @@ Quattlebaum Expires June 1, 2017 [Page 60] If the NCP supports CAP_NET_SAVE, then we go ahead and recall the network: + + + +Quattlebaum Expires June 3, 2017 [Page 62] + + Spinel Protocol (29f5b2c82) November 2016 + + o CMD_NET_RECALL C.2. Attaching to a network @@ -3410,14 +3495,6 @@ C.2. Attaching to a network o CMD_VALUE_IS:PROP_NET_NETWORK_NAME o CMD_VALUE_SET:PROP_NET_MASTER_KEY o CMD_VALUE_IS:PROP_NET_MASTER_KEY - - - -Quattlebaum Expires June 1, 2017 [Page 61] - - Spinel Protocol (05367497d) November 2016 - - o CMD_VALUE_SET:PROP_NET_KEY_SEQUENCE_COUNTER o CMD_VALUE_IS:PROP_NET_KEY_SEQUENCE_COUNTER o CMD_VALUE_SET:PROP_NET_KEY_SWITCH_GUARDTIME @@ -3443,6 +3520,16 @@ C.3. Successfully joining a pre-existing network [CREF11] + + + + + +Quattlebaum Expires June 3, 2017 [Page 63] + + Spinel Protocol (29f5b2c82) November 2016 + + 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. @@ -3465,15 +3552,6 @@ C.3. Successfully joining a pre-existing network o CMD_NET_SAVE - - - - -Quattlebaum Expires June 1, 2017 [Page 62] - - Spinel Protocol (05367497d) November 2016 - - C.4. Unsuccessfully joining a pre-existing network This example session is identical to the above session up to the @@ -3497,6 +3575,17 @@ C.5. Detaching from a network TBD + + + + + + +Quattlebaum Expires June 3, 2017 [Page 64] + + Spinel Protocol (29f5b2c82) November 2016 + + C.6. Attaching to a saved network [CREF12] @@ -3521,15 +3610,6 @@ C.6. Attaching to a saved network o CMD_VALUE_IS:PROP_NET_PARTITION_ID o CMD_VALUE_IS:PROP_THREAD_ON_MESH_NETS - - - - -Quattlebaum Expires June 1, 2017 [Page 63] - - Spinel Protocol (05367497d) November 2016 - - C.7. NCP Software Reset [CREF13] @@ -3555,6 +3635,13 @@ C.10. Sniffing raw packets Optionally set the channel: + + +Quattlebaum Expires June 3, 2017 [Page 65] + + Spinel Protocol (29f5b2c82) November 2016 + + o CMD_VALUE_SET:PROP_PHY_CHAN:x o CMD_VALUE_IS:PROP_PHY_CHAN @@ -3578,14 +3665,6 @@ C.10. Sniffing raw packets Now we will get raw 802.15.4 packets asynchronously on PROP_STREAM_RAW: - - - -Quattlebaum Expires June 1, 2017 [Page 64] - - Spinel Protocol (05367497d) November 2016 - - o CMD_VALUE_IS:PROP_STREAM_RAW:... o CMD_VALUE_IS:PROP_STREAM_RAW:... o CMD_VALUE_IS:PROP_STREAM_RAW:... @@ -3607,6 +3686,18 @@ Appendix D. Acknowledgments This document was prepared using mmark [5] by (Miek Gieben) and xml2rfc (version 2) [6]. + + + + + + + +Quattlebaum Expires June 3, 2017 [Page 66] + + Spinel Protocol (29f5b2c82) November 2016 + + Appendix E. Glossary [CREF16] @@ -3633,15 +3724,6 @@ Appendix E. Glossary to the physical implementation and operation of a networking medium. - - - - -Quattlebaum Expires June 1, 2017 [Page 65] - - Spinel Protocol (05367497d) November 2016 - - Editorial Comments [CREF1] RQ: We may want to consider a license more appropriate for @@ -3664,6 +3746,14 @@ Editorial Comments [CREF6] RQ: FIXME: This test vector is incomplete. + + + +Quattlebaum Expires June 3, 2017 [Page 67] + + Spinel Protocol (29f5b2c82) November 2016 + + [CREF7] RQ: FIXME: This test vector is incomplete. [CREF8] RQ: FIXME: This test vector is incomplete. @@ -3687,17 +3777,6 @@ Editorial Comments Author's Address - - - - - - -Quattlebaum Expires June 1, 2017 [Page 66] - - Spinel Protocol (05367497d) November 2016 - - Robert S. Quattlebaum Nest Labs 3400 Hillview Ave. @@ -3726,27 +3805,4 @@ Quattlebaum Expires June 1, 2017 [Page 66] - - - - - - - - - - - - - - - - - - - - - - - -Quattlebaum Expires June 1, 2017 [Page 67] +Quattlebaum Expires June 3, 2017 [Page 68] diff --git a/doc/spinel-protocol-src/spinel-feature-gpio.md b/doc/spinel-protocol-src/spinel-feature-gpio.md index fc39d49a0..7fef29e9a 100644 --- a/doc/spinel-protocol-src/spinel-feature-gpio.md +++ b/doc/spinel-protocol-src/spinel-feature-gpio.md @@ -1,47 +1,114 @@ -# Feature: Basic GPIO Access +# Feature: GPIO Access {#feature-gpio-access} -The length of the data associated with these properties depends on the -number of GPIOs. If you have 10 GPIOs, you'd have two bytes. You determine -the number of GPIOs available by examining PROP_GPIO_AVAILABLE, described -below. This API isn't intended to support every possible GPIO state, it is -intended for basic reading and writing. +This feature allows the host to have control over some or all of the +GPIO pins on the NCP. The host can determine which GPIOs are available +by examining `PROP_GPIO_CONFIG`, described below. This API supports a +maximum of 256 individual GPIO pins. -## Properties +Support for this feature can be determined by the presence of `CAP_GPIO`. -### PROP 4096: PROP_GPIO_AVAILABLE +## Properties ## -* Type: Read-only +### PROP 4096: PROP\_GPIO\_CONFIG ### -Contains a bit field identifying which GPIOs are supported. Cleared bits -are not supported. Set bits are supported. +* Argument-Encoding: `A(CCU)` +* Type: Read-write (Writable only using `CMD_PROP_VALUE_INSERT`, + (#prop-value-insert)) -### PROP 4097: PROP_GPIO_DIRECTION +An array of structures which contain the following fields: -* Type: Read-only (Optionally read/write) +* `C`: GPIO Number +* `C`: GPIO Configuration Flags +* `U`: Human-readable GPIO name -Contains a bit field identifying which GPIOs are configured as outputs. -Cleared bits are inputs. Set bits are outputs. +GPIOs which do not have a corresponding entry are not supported. -### PROP 4098: PROP_GPIO_STATE +The configuration parameter contains the configuration flags for the +GPIO: -* Type: Read-Write + 0 1 2 3 4 5 6 7 + +---+---+---+---+---+---+---+---+ + |DIR|PUP|PDN|TRIGGER| RESERVED | + +---+---+---+---+---+---+---+---+ + |O/D| + +---+ -Contains a bit field identifying the state of the GPIOs. For GPIOs -configured as inputs, this is the read logic level. For GPIOs configured -as outputs, this is the logic level of the output. +* `DIR`: Pin direction. Clear (0) for input, set (1) for output. +* `PUP`: Pull-up enabled flag. +* `PDN`/`O/D`: Flag meaning depends on pin direction: + * Input: Pull-down enabled. + * Output: Output is an open-drain. +* `TRIGGER`: Enumeration describing how pin changes generate + asynchronous notification commands (TBD) from the NCP to the host. + * 0: Feature disabled for this pin + * 1: Trigger on falling edge + * 2: Trigger on rising edge + * 3: Trigger on level change +* `RESERVED`: Bits reserved for future use. Always cleared to zero + and ignored when read. -### PROP 4099: PROP_GPIO_STATE_SET +As an optional feature, the configuration of individual pins may be +modified using the `CMD_PROP_VALUE_INSERT` command. Only the GPIO +number and flags fields MUST be present, the GPIO name (if present) +would be ignored. This command can only be used to modify the +configuration of GPIOs which are already exposed---it cannot be used +by the host to add addional GPIOs. -* Type: Write-only +### PROP 4098: PROP\_GPIO\_STATE ### -Allows for the state of various output GPIOs to be set without affecting -other GPIO states. Contains a bit field identifying the output GPIOs that -should have their state set to 1. +* Type: Read-Write -### PROP 4100: PROP_GPIO_STATE_CLEAR +Contains a bit field identifying the state of the GPIOs. The length of +the data associated with these properties depends on the number of +GPIOs. If you have 10 GPIOs, you'd have two bytes. GPIOs are numbered +from most significant bit to least significant bit, so 0x80 is GPIO 0, +0x40 is GPIO 1, etc. -* Type: Write-only +For GPIOs configured as inputs: -Allows for the state of various output GPIOs to be cleared without affecting -other GPIO states. Contains a bit field identifying the output GPIOs that -should have their state cleared to 0. +* `CMD_PROP_VAUE_GET`: The value of the associated bit describes the + logic level read from the pin. +* `CMD_PROP_VALUE_SET`: The value of the associated bit is ignored + for these pins. + +For GPIOs configured as outputs: + +* `CMD_PROP_VAUE_GET`: The value of the associated bit is + implementation specific. +* `CMD_PROP_VALUE_SET`: The value of the associated bit determines + the new logic level of the output. If this pin is configured as an + open-drain, setting the associated bit to 1 will cause the pin to + enter a Hi-Z state. + +For GPIOs which are not specified in `PROP_GPIO_CONFIG`: + +* `CMD_PROP_VAUE_GET`: The value of the associated bit is + implementation specific. +* `CMD_PROP_VALUE_SET`: The value of the associated bit MUST be + ignored by the NCP. + +When writing, unspecified bits are assumed to be zero. + +### PROP 4099: PROP\_GPIO\_STATE\_SET ### + +* Type: Write-only + +Allows for the state of various output GPIOs to be set without +affecting other GPIO states. Contains a bit field identifying the +output GPIOs that should have their state set to 1. + +When writing, unspecified bits are assumed to be zero. The value of +any bits for GPIOs which are not specified in `PROP_GPIO_CONFIG` MUST +be ignored. + +### PROP 4100: PROP\_GPIO\_STATE\_CLEAR ### + +* Type: Write-only + +Allows for the state of various output GPIOs to be cleared without +affecting other GPIO states. Contains a bit field identifying the +output GPIOs that should have their state cleared to 0. + +When writing, unspecified bits are assumed to be zero. The value of +any bits for GPIOs which are not specified in `PROP_GPIO_CONFIG` MUST +be ignored. diff --git a/doc/spinel-protocol-src/spinel-prop-core.md b/doc/spinel-protocol-src/spinel-prop-core.md index 6533e9548..7662d7c68 100644 --- a/doc/spinel-protocol-src/spinel-prop-core.md +++ b/doc/spinel-protocol-src/spinel-prop-core.md @@ -131,6 +131,7 @@ Currently defined values are: * 6: `CAP_JAM_DETECT`: Jamming detection. See (#feature-jam-detect) * 7: `CAP_PEEK_POKE`: PEEK/POKE debugging commands. * 8: `CAP_WRITABLE_RAW_STREAM`: `PROP_STREAM_RAW` is writable. + * 9: `CAP_GPIO`: Support for GPIO access. See (#feature-gpio-access). * 16: `CAP_802_15_4_2003` * 17: `CAP_802_15_4_2006` * 18: `CAP_802_15_4_2011` diff --git a/src/ncp/spinel.c b/src/ncp/spinel.c index 21ecce0a0..6f7e8a1c6 100644 --- a/src/ncp/spinel.c +++ b/src/ncp/spinel.c @@ -1209,6 +1209,22 @@ spinel_prop_key_to_cstr(spinel_prop_key_t prop_key) ret = "PROP_JAM_DETECT_WINDOW"; break; + case SPINEL_PROP_GPIO_CONFIG: + ret = "PROP_GPIO_CONFIG"; + break; + + case SPINEL_PROP_GPIO_STATE: + ret = "PROP_GPIO_STATE"; + break; + + case SPINEL_PROP_GPIO_STATE_SET: + ret = "PROP_GPIO_STATE_SET"; + break; + + case SPINEL_PROP_GPIO_STATE_CLEAR: + ret = "PROP_GPIO_STATE_CLEAR"; + break; + default: break; } diff --git a/src/ncp/spinel.h b/src/ncp/spinel.h index c1d37a948..b636ae9e2 100644 --- a/src/ncp/spinel.h +++ b/src/ncp/spinel.h @@ -73,6 +73,10 @@ #define SPINEL_FRAME_MAX_SIZE 1300 +/// Macro for generating bit masks using bit index from the spec +#define SPINEL_BIT_MASK(bit_index,field_bit_count) \ + ( (1 << ((field_bit_count) - 1)) >> (bit_index)) + // ---------------------------------------------------------------------------- __BEGIN_DECLS @@ -195,6 +199,19 @@ enum { SPINEL_NET_FLAG_PREFERENCE_MASK = (3 << SPINEL_NET_FLAG_PREFERENCE_OFFSET), }; +enum { + SPINEL_GPIO_FLAG_DIR_INPUT = 0, + SPINEL_GPIO_FLAG_DIR_OUTPUT = SPINEL_BIT_MASK(0, 8), + SPINEL_GPIO_FLAG_PULL_UP = SPINEL_BIT_MASK(1, 8), + SPINEL_GPIO_FLAG_PULL_DOWN = SPINEL_BIT_MASK(2, 8), + SPINEL_GPIO_FLAG_OPEN_DRAIN = SPINEL_BIT_MASK(2, 8), + SPINEL_GPIO_FLAG_TRIGGER_NONE = 0, + SPINEL_GPIO_FLAG_TRIGGER_RISING = SPINEL_BIT_MASK(3, 8), + SPINEL_GPIO_FLAG_TRIGGER_FALLING = SPINEL_BIT_MASK(4, 8), + SPINEL_GPIO_FLAG_TRIGGER_ANY = SPINEL_GPIO_FLAG_TRIGGER_RISING + | SPINEL_GPIO_FLAG_TRIGGER_FALLING, +}; + enum { SPINEL_PROTOCOL_TYPE_BOOTLOADER = 0, @@ -292,6 +309,7 @@ enum SPINEL_CAP_PEEK_POKE = 7, SPINEL_CAP_WRITABLE_RAW_STREAM = 8, + SPINEL_CAP_GPIO = 9, SPINEL_CAP_802_15_4__BEGIN = 16, SPINEL_CAP_802_15_4_2003 = (SPINEL_CAP_802_15_4__BEGIN + 0), @@ -350,31 +368,85 @@ typedef enum SPINEL_PROP_BASE_EXT__BEGIN = 0x1000, - /// Available GPIO Bitmask - /** Format: `D` - * Type: Read-Only + /// GPIO Configuration + /** Format: `A(CCU)` + * Type: Read-Only (Optionally Read-write using `CMD_PROP_VALUE_INSERT`) * - * Contains a bit field identifying which GPIOs are supported. Cleared bits - * are not supported. Set bits are supported. - */ - SPINEL_PROP_GPIO_AVAILABLE = SPINEL_PROP_BASE_EXT__BEGIN + 0, - - /// GPIO Direction Bitmask - /** Format: `D` - * Type: Read-only (Optionally read/write) + * An array of structures which contain the following fields: * - * Contains a bit field identifying which GPIOs are configured as outputs. - * Cleared bits are inputs. Set bits are outputs. + * * `C`: GPIO Number + * * `C`: GPIO Configuration Flags + * * `U`: Human-readable GPIO name + * + * GPIOs which do not have a corresponding entry are not supported. + * + * The configuration parameter contains the configuration flags for the + * GPIO: + * + * 0 1 2 3 4 5 6 7 + * +---+---+---+---+---+---+---+---+ + * |DIR|PUP|PDN|TRIGGER| RESERVED | + * +---+---+---+---+---+---+---+---+ + * |O/D| + * +---+ + * + * * `DIR`: Pin direction. Clear (0) for input, set (1) for output. + * * `PUP`: Pull-up enabled flag. + * * `PDN`/`O/D`: Flag meaning depends on pin direction: + * * Input: Pull-down enabled. + * * Output: Output is an open-drain. + * * `TRIGGER`: Enumeration describing how pin changes generate + * asynchronous notification commands (TBD) from the NCP to the host. + * * 0: Feature disabled for this pin + * * 1: Trigger on falling edge + * * 2: Trigger on rising edge + * * 3: Trigger on level change + * * `RESERVED`: Bits reserved for future use. Always cleared to zero + * and ignored when read. + * + * As an optional feature, the configuration of individual pins may be + * modified using the `CMD_PROP_VALUE_INSERT` command. Only the GPIO + * number and flags fields MUST be present, the GPIO name (if present) + * would be ignored. This command can only be used to modify the + * configuration of GPIOs which are already exposed---it cannot be used + * by the host to add addional GPIOs. */ - SPINEL_PROP_GPIO_DIRECTION = SPINEL_PROP_BASE_EXT__BEGIN + 1, + SPINEL_PROP_GPIO_CONFIG = SPINEL_PROP_BASE_EXT__BEGIN + 0, /// GPIO State Bitmask /** Format: `D` * Type: Read-Write * - * Contains a bit field identifying the state of the GPIOs. For GPIOs - * configured as inputs, this is the read logic level. For GPIOs configured - * as outputs, this is the logic level of the output. + * Contains a bit field identifying the state of the GPIOs. The length of + * the data associated with these properties depends on the number of + * GPIOs. If you have 10 GPIOs, you'd have two bytes. GPIOs are numbered + * from most significant bit to least significant bit, so 0x80 is GPIO 0, + * 0x40 is GPIO 1, etc. + * + * For GPIOs configured as inputs: + * + * * `CMD_PROP_VAUE_GET`: The value of the associated bit describes the + * logic level read from the pin. + * * `CMD_PROP_VALUE_SET`: The value of the associated bit is ignored + * for these pins. + * + * For GPIOs configured as outputs: + * + * * `CMD_PROP_VAUE_GET`: The value of the associated bit is + * implementation specific. + * * `CMD_PROP_VALUE_SET`: The value of the associated bit determines + * the new logic level of the output. If this pin is configured as an + * open-drain, setting the associated bit to 1 will cause the pin to + * enter a Hi-Z state. + * + * For GPIOs which are not specified in `PROP_GPIO_CONFIG`: + * + * * `CMD_PROP_VAUE_GET`: The value of the associated bit is + * implementation specific. + * * `CMD_PROP_VALUE_SET`: The value of the associated bit MUST be + * ignored by the NCP. + * + * When writing, unspecified bits are assumed to be zero. */ SPINEL_PROP_GPIO_STATE = SPINEL_PROP_BASE_EXT__BEGIN + 2, @@ -385,6 +457,10 @@ typedef enum * Allows for the state of various output GPIOs to be set without affecting * other GPIO states. Contains a bit field identifying the output GPIOs that * should have their state set to 1. + * + * When writing, unspecified bits are assumed to be zero. The value of + * any bits for GPIOs which are not specified in `PROP_GPIO_CONFIG` MUST + * be ignored. */ SPINEL_PROP_GPIO_STATE_SET = SPINEL_PROP_BASE_EXT__BEGIN + 3, @@ -395,6 +471,10 @@ typedef enum * Allows for the state of various output GPIOs to be cleared without affecting * other GPIO states. Contains a bit field identifying the output GPIOs that * should have their state cleared to 0. + * + * When writing, unspecified bits are assumed to be zero. The value of + * any bits for GPIOs which are not specified in `PROP_GPIO_CONFIG` MUST + * be ignored. */ SPINEL_PROP_GPIO_STATE_CLEAR = SPINEL_PROP_BASE_EXT__BEGIN + 4,