From 5055ac5f97c2248e525144625bc813c172b37a84 Mon Sep 17 00:00:00 2001 From: Robert Quattlebaum Date: Mon, 30 Oct 2017 09:49:31 -0700 Subject: [PATCH] core: Updates to PHY, MAC, and NET property sections. Other changes include: * PROP_POWER_STATE is now always required, with CAP_POWER_STATE indicating if it can be written to. * PROP_MAC_SCAN_STATE: SCAN_STATE_DISCOVER is marked as deprecated. Will add new property for this. See #4 for more details. * Elaborated on purpose of PROP_MAC_DATA_POLL_PERIOD. --- core/detail-properties-core.md | 38 ++-- core/detail-properties-mac.md | 361 +++++++++++++++++++++++++-------- core/detail-properties-net.md | 36 +++- core/detail-properties-phy.md | 146 ++++++++++--- 4 files changed, 441 insertions(+), 140 deletions(-) diff --git a/core/detail-properties-core.md b/core/detail-properties-core.md index 343f3f2..9980231 100644 --- a/core/detail-properties-core.md +++ b/core/detail-properties-core.md @@ -4,7 +4,7 @@ * Type: Single-Value, Read-Only * Asynchronous Updates: Yes -* Required: Yes +* Required: **REQUIRED** * Post-Reset Value: Reset Reason Code Bytes: | 1-3 @@ -33,7 +33,7 @@ See (#status-codes) for the complete list of status codes. * Type: Single-Value, Constant * Asynchronous Updates: No -* Required: Yes +* Required: **REQUIRED** * Post-Reset Value: 4, 3 Bytes: | 1-3 | 1-3 @@ -67,7 +67,7 @@ be identical across all implemented NLIs. * Type: Single-Value, Constant * Asynchronous Updates: No -* Required: Yes +* Required: **REQUIRED** * Scope: Firmware * Post-Reset Value: Implementation-Specific @@ -119,7 +119,7 @@ identical across all implemented NLIs. * Type: Single-Value, Constant * Asynchronous Updates: No -* Required: Yes +* Required: **REQUIRED** * Post-Reset Value: Implementation-Specific Bytes: | 1-3 @@ -146,7 +146,7 @@ network protocol given by the NCP. * Type: Single-Value, Constant * Asynchronous Updates: No -* Required: Yes +* Required: **REQUIRED** * Post-Reset Value: Implementation-Specific Bytes: | 1-3 @@ -161,7 +161,7 @@ Fields: | `VENDOR_ID` * Type: Multiple-Value, Constant * Asynchronous Updates: No -* Required: Yes +* Required: **REQUIRED** * Post-Reset Value: Implementation-Specific Bytes: | 1-3 | 1-3 | ... @@ -176,7 +176,7 @@ packed unsigned integers. See (#capabilities) for a list of values. * Type: Single-Value, Constant * Asynchronous Updates: No -* Required: Yes +* Required: **REQUIRED** * Post-Reset Value: 1-4 Bytes: | 1 @@ -197,9 +197,11 @@ identical across all implemented NLIs. * Asynchronous Updates: Yes * Required: * Read: Yes - * Write: RECOMENDED + * Write: **RECOMENDED** * Post-Reset Value: `POWER_STATE_ONLINE` -* Related Capabilities: `CAP_POWER_STATE`(writable) +* Related Capabilities: + * `CAP_POWER_STATE`: Required when writable +* See Also: (#prop-mac-data-poll-period) Bytes: | 1 -------:|------------- @@ -246,7 +248,7 @@ Code | Name * Type: Single-Value, Read-Only * Asynchronous Updates: No * Post-Reset Value: Determined by Factory -* Required: Yes +* Required: **REQUIRED** Bytes: | 8 -------:|------------- @@ -260,7 +262,7 @@ The EUI-64 (TODO:CITE) format of the link-layer address of the device. * Type: Single-Value, Read-Write * Asynchronous Updates: No -* Required: No +* Required: **OPTIONAL** * Post-Reset Value: 0 * Required Capability: `CAP_LOCK` @@ -286,7 +288,7 @@ of `STATUS_ALREADY`. * Type: Single-Value, Read-Write * Asynchronous Updates: No -* Required: No +* Required: **OPTIONAL** * Post-Reset Value: `HOST_POWER_STATE_ONLINE` * Required Capability: `???` (TODO: Assign a capability) @@ -369,7 +371,7 @@ NLI is not zero are not specified. * Type: Multi-Value, Read-Write * Asynchronous Updates: No -* Required: No +* Required: **OPTIONAL** * Post-Reset Value: Empty * Scope: NCP * Required Capability: `CAP_UNSOL_UPDATE_FILTER` @@ -409,7 +411,7 @@ NCP **MUST** ignore the unsupported properties. * Type: Multi-Value, Constant * Asynchronous Updates: No -* Required: No +* Required: **OPTIONAL** * Post-Reset Value: Implementation Specific * Scope: Firmware * Required Capability: `CAP_UNSOL_UPDATE_FILTER` @@ -439,7 +441,7 @@ those properties **SHOULD NOT** not be included in this list. * Type: Character-Stream, Output-Only * Asynchronous Updates: Yes -* Required: No +* Required: **OPTIONAL** * Scope: NLI Bytes: | *n* @@ -466,7 +468,7 @@ first bytes of the next emission from this stream. * Type: Packet-Stream, Input/Output * Asynchronous Updates: Yes -* Required: No +* Required: **OPTIONAL** * Scope: NLI * Related Capabilities: * `CAP_WRITABLE_RAW_STREAM`: Can be written to if present. @@ -501,7 +503,7 @@ specified in the core protocol. * Type: Packet-Stream, Input/Output * Asynchronous Updates: Yes -* Required: Yes +* Required: **REQUIRED** * Scope: NLI Bytes: | 2 | *n* | *n* @@ -519,7 +521,7 @@ format of which is described in (#frame-metadata-format). * Type: Packet-Stream, Input/Output * Asynchronous Updates: Yes -* Required: Yes +* Required: **REQUIRED** * Scope: NLI Bytes: | 2 | *n* | *n* diff --git a/core/detail-properties-mac.md b/core/detail-properties-mac.md index 38fb250..fb12ed5 100644 --- a/core/detail-properties-mac.md +++ b/core/detail-properties-mac.md @@ -1,16 +1,27 @@ ## MAC Properties {#prop-mac} ### PROP 48: PROP_MAC_SCAN_STATE {#prop-mac-scan-state} -* Type: Read-Write -* Packed-Encoding: `C` +* Type: Single-Value, Read-Write +* Asynchronous Updates: Yes +* Required: **REQUIRED** * Unit: Enumeration +* Post-Reset Value: 0 (false) + +Bytes: | 1 +-------:|------------- +Format: | UINT8 +Fields: | `SCAN_STATE` + +TODO(RQ): This needs to be re-thought out. I don't like the whole discovery +thing being a separate scan state. Maybe we should add another property +for scanning only compatible networks. Possible Values: * 0: `SCAN_STATE_IDLE` * 1: `SCAN_STATE_BEACON` * 2: `SCAN_STATE_ENERGY` -* 3: `SCAN_STATE_DISCOVER` +* 3: `SCAN_STATE_DISCOVER` DEPRECATED Set to `SCAN_STATE_BEACON` to start an active scan. Beacons will be emitted from `PROP_MAC_SCAN_BEACON`. @@ -19,88 +30,162 @@ Set to `SCAN_STATE_ENERGY` to start an energy scan. Channel energy result will be reported by emissions of `PROP_MAC_ENERGY_SCAN_RESULT` (per channel). -Set to `SCAN_STATE_DISOVER` to start a Thread MLE discovery +DEPRECATED: Set to `SCAN_STATE_DISOVER` to start a Thread MLE discovery scan operation. Discovery scan result will be emitted from `PROP_MAC_SCAN_BEACON`. Value switches to `SCAN_STATE_IDLE` when scan is complete. ### PROP 49: PROP_MAC_SCAN_MASK {#prop-mac-scan-mask} -* Type: Read-Write -* Packed-Encoding: `A(C)` -* Unit: List of channels to scan +* Type: Multi-Value, Read-Write +* Asynchronous Updates: No +* Required: **REQUIRED** +* Unit: Channel Index +* Post-Reset Value: Same as PROP_PHY_CHAN_SUPPORTED + +Bytes: | 1 | 1 | ... +-------:|-------|-------|----- +Format: | UINT8 | UINT8 | ... +Fields: | `CHANNEL` | `CHANNEL` | ... + +This property contains the list of channels that will be scanned. ### PROP 50: PROP_MAC_SCAN_PERIOD {#prop-mac-scan-period} -* Type: Read-Write -* Packed-Encoding: `S` (uint16) + +* Type: Single-Value, Read-Write +* Asynchronous Updates: No +* Required: **OPTIONAL** * Unit: milliseconds per channel +* Post-Reset Value: Implementation-specific-default + +Bytes: | 1 +-------:|------------- +Format: | UINT16_LE +Fields: | `MSEC` ### PROP 51: PROP_MAC_SCAN_BEACON {#prop-mac-scan-beacon} -* Type: Read-Only-Stream + +* Type: Packet Stream, Output-Only +* Required: **REQUIRED** + * Packed-Encoding: `Ccdd` (or `Cct(ESSc)t(iCUdd)`) -Octets: | 1 | 1 | 2 | *n* | 2 | *n* +Bytes: | 1 | 1 | 2 | *n* | 2 | *n* --------|----|------|---------|----------|---------|---------- +Format: | UINT8 | INT8 | UINT16_LE | DATA | UINT16_LE | DATA Fields: | CH | RSSI | MAC_LEN | MAC_DATA | NET_LEN | NET_DATA Scan beacons have two embedded structures which contain information about the MAC layer and the NET layer. Their format depends on the MAC and NET layer currently in use. -The format below is for an 802.15.4 MAC with Thread: - -* `C`: Channel -* `c`: RSSI of the beacon -* `t`: MAC layer properties (802.15.4 layer shown below for convenience) - * `E`: Long address - * `S`: Short address - * `S`: PAN-ID - * `c`: LQI -* NET layer properties (Standard net layer shown below for convenience) - * `i`: Protocol Number - * `C`: Flags - * `U`: Network Name - * `d`: XPANID - * `d`: Steering data + +For example, in an 802.15.4 PHY, MAC_DATA would be formatted as follows: + +Bytes: | 8 | 2 | 2 | 1 +--------|----|------|---------|---------- +Format: | EUI-64 | UINT16_LE | UINT16_LE | UINT8 +Fields: | LONG_ADDR | SHORT_ADDR | PAN-ID | LQI + +For the standard network layer, the NET_DATA formatted as follows: + +Bytes: | 1-3 | 1 | *n* | 1 | 2 | *n* | 2| *n* +--------|----|------|----------------------------|------|---|------|---------- +Format: | PUI | UINT8 | UTF8 | ZT | UINT16_LE | DATA |UINT16_LE | DATA +Fields: | PROTO | FLAGS | NETWORK_NAME | 0x00 | XPANID_LEN| XPANID | STEERING_LEN | STEERING Extra parameters may be added to each of the structures in the future, so care should be taken to read the length that prepends each structure. +The RSSI is measured in dB. +The specific meaning of zero dB is implementation-specific, +but **MUST** be consistant with definitions of other properties +that express power. It is **RECOMMENDED** that zero dB +represent one milliwatt of power (0dBm), as measured from the +antenna connector. + ### PROP 52: PROP_MAC_15_4_LADDR {#prop-mac-15-4-laddr} -* Type: Read-Write -* Packed-Encoding: `E` + +* Type: Single-Value, Read-Write +* Asynchronous Updates: No +* Required: **ONLY** used with 802.15.4 MAC +* Post-Reset Value: Tehnology-dependent. **MAY** be `PROP_HWADDR` or be randomly generated. + +Bytes: | 8 +--------|---- +Format: | EUI-64 +Fields: | LADDR + +TODO(RQ): Break this out into an 802.15.4-specific section The 802.15.4 long address of this node. This property is only present on NCPs which implement 802.15.4 ### PROP 53: PROP_MAC_15_4_SADDR {#prop-mac-15-4-saddr} -* Type: Read-Write -* Packed-Encoding: `S` + +* Type: Single-Value, Read-Write +* Asynchronous Updates: No +* Required: **ONLY** when used with 802.15.4 MAC +* Post-Reset Value: 0xFFFF + +Bytes: | 2 +--------|---- +Format: | UINT16_LE +Fields: | SADDR + +TODO(RQ): Break this out into an 802.15.4-specific section The 802.15.4 short address of this node. This property is only present on NCPs which implement 802.15.4 ### PROP 54: PROP_MAC_15_4_PANID {#prop-mac-15-4-panid} -* Type: Read-Write -* Packed-Encoding: `S` + +* Type: Single-Value, Read-Write +* Asynchronous Updates: No +* Required: **ONLY** when used with 802.15.4 MAC +* Post-Reset Value: 0xFFFF ? + +Bytes: | 2 +--------|---- +Format: | UINT16_LE +Fields: | PANID + +TODO(RQ): Break this out into an 802.15.4-specific section The 802.15.4 PANID this node is associated with. This property is only present on NCPs which implement 802.15.4 ### PROP 55: PROP_MAC_RAW_STREAM_ENABLED {#prop-mac-raw-stream-enabled} -* Type: Read-Write -* Packed-Encoding: `b` + +* Type: Single-Value, Read-Write +* Asynchronous Updates: No +* Required: **RECOMMENDED** +* Post-Reset Value: 0 (false) + +Bytes: | 1 +--------|---- +Format: | BOOL +Fields: | RAW_STREAM_ENABLED Set to true to enable raw MAC frames to be emitted from `PROP_STREAM_RAW`. See (#prop-stream-raw). ### PROP 56: PROP_MAC_PROMISCUOUS_MODE {#prop-mac-promiscuous-mode} -* Type: Read-Write -* Packed-Encoding: `C` + +* Type: Single-Value, Read-Write +* Asynchronous Updates: No +* Required: **RECOMMENDED** +* Unit: Enumeration +* Post-Reset Value: `MAC_PROMISCUOUS_MODE_OFF` + +Bytes: | 1 +--------|---- +Format: | UINT8 +Fields: | MAC_PROMISCUOUS_MODE Possible Values: @@ -113,91 +198,189 @@ Id | Name | Description See (#prop-stream-raw). ### PROP 57: PROP_MAC_ENERGY_SCAN_RESULT {#prop-mac-escan-result} -* Type: Read-Only-Stream -* Packed-Encoding: `Cc` -This property is emitted during energy scan operation -per scanned channel with following format: +* Type: Packet Stream, Output-Only +* Required: **REQUIRED** + +Bytes: | 1 | 1 +--------|----|- +Format: | UINT8 | INT8 +Fields: | CHANNEL | RSSI + +This property is emitted during energy scan operation (SCAN_STATE_ENERGY) +once per scanned channel. + +The RSSI is measured in dB. +The specific meaning of zero dB is implementation-specific, +but **MUST** be consistant with definitions of other properties +that express power. It is **RECOMMENDED** that zero dB +represent one milliwatt of power (0dBm), as measured from the +antenna connector. -* `C`: Channel -* `c`: RSSI (in dBm) -### PROP 58: PROP_MAC_DATA_POLL_PERIOD {#prop-mac-data-poll-period -* Type: Read-Write -* Packed-Encoding: `L` +### PROP 58: PROP_MAC_DATA_POLL_PERIOD {#prop-mac-data-poll-period} + +* Type: Single-Value, Read-Write +* Asynchronous Updates: No +* Required: **OPTIONAL** +* Unit: milliseconds +* Post-Reset Value: 5000ms +* Required Capability: `CAP_POWER_SAVE` +* See Also: (#prop-power-state) + +Bytes: | 1 +--------|---- +Format: | UINT32_LE +Fields: | MAC_DATA_POLL_PERIOD The (user-specified) data poll (802.15.4 MAC Data Request) period -in milliseconds. Value zero means there is no user-specified -poll period, and the network stack determines the maximum period -based on the MLE Child Timeout. +in milliseconds. Value zero means the poll period will be calculated +by the stack to be the maximum interval acceptable by the parent. If the +maximum poll interval is longer than the maximum interval acceptable +by the parent, the later value is used instead. -If the value is non-zero, it specifies the maximum period between -data poll transmissions. Note that the network stack may send data -request transmissions more frequently when expecting a control-message -(e.g., when waiting for an MLE Child ID Response). +The value of this property is only used if `PROP_POWER_STATE` is set to +`POWER_STATE_LOW_POWER`. In all other states, the value of this property is +ignored. -This property is only present on NCPs which implement 802.15.4. +This property is only used on NCPs which support `POWER_STATE_LOW_POWER`. ### PROP 4864: PROP_MAC_WHITELIST {#prop-mac-whitelist} -* Type: Read-Write -* Packed-Encoding: `A(T(Ec))` -* Required capability: `CAP_MAC_WHITELIST` -Structure Parameters: +* Type: Multi-Value, Read-Write +* Asynchronous Updates: No +* Per-Item Length: No +* Required: **OPTIONAL** +* Post-Reset Value: empty +* Required Capability: `CAP_MAC_WHITELIST` +* See Also: (#prop-mac-whitelist-enabled) + +TODO(RQ): Consider moving this to the debug section. + +When whitelisting is enabled, this property prevents the device from being able +to communicate with devices which are not in this list. Also, if the +RSSI field is not 127, the given RSSI value will always be reported +instead of using the RSSI from the radio hardware. + +This property is intended to facilitate stack testing and debugging +and SHOULD NOT be used in production. + +Item Format: + +Bytes: | 8 | 1 +--------|----|----- +Format: | EUI-64-BE | UINT8 +Fields: | ADDR | RSSI + +ADDR +: EUI64 address of node -* `E`: EUI64 address of node -* `c`: Optional RSSI-override value. The value 127 indicates +RSSI +: Optional RSSI-override value. The value 127 indicates that the RSSI-override feature is not enabled for this address. If this value is omitted when setting or inserting, it is assumed to be 127. This parameter is - ignored when removing. + ignored when removing and may be omitted. ### PROP 4865: PROP_MAC_WHITELIST_ENABLED {#prop-mac-whitelist-enabled} -* Type: Read-Write -* Packed-Encoding: `b` + +* Type: Single-Value, Read-Write +* Asynchronous Updates: No +* Required: **OPTIONAL** +* Post-Reset Value: 0 (false) * Required capability: `CAP_MAC_WHITELIST` +* See Also: (#prop-mac-whitelist) + +Bytes: | 1 +-------:|------------- +Format: | BOOL +Fields: | `WHITELIST_ENABLED` + +TODO(RQ): Consider moving this to the debug section. + +Setting this to true **SHALL** cause `PROP_MAC_BLACKLIST_ENABLED` to be automatically +set to false. -### PROP 4867: SPINEL_PROP_MAC_SRC_MATCH_ENABLED {#prop-mac-src-match-enabled} -* Type: Write -* Packed-Encoding: `b` +### PROP 4867: PROP_MAC_SRC_MATCH_ENABLED {#prop-mac-src-match-enabled} -Set to true to enable radio source matching or false to disable it. This property -is only available if the `SPINEL_CAP_MAC_RAW` capability is present. The source match +* Type: Single-Value, Read-Write +* Asynchronous Updates: No +* Required: **OPTIONAL** +* Post-Reset Value: 0 (false) +* Required capability: `CAP_MAC_RAW`, TODO: 802.15.4 PHY CAP +* See Also: (#prop-mac-src-match-short-addresses), (#prop-mac-src-match-extended-addresses) + +Bytes: | 1 +-------:|------------- +Format: | BOOL +Fields: | `SRC_MATCH_ENABLED` + +Set to true to enable radio source matching or false to disable it. The source match functionality is used by radios when generating ACKs. The short and extended address lists are used for settings the Frame Pending bit in the ACKs. -### PROP 4868: SPINEL_PROP_MAC_SRC_MATCH_SHORT_ADDRESSES {#prop-mac-src-match-short-addresses} -* Type: Write -* Packed-Encoding: `A(S)` - -Configures the list of short addresses used for source matching. This property -is only available if the `SPINEL_CAP_MAC_RAW` capability is present. +### PROP 4868: PROP_MAC_SRC_MATCH_SHORT_ADDRESSES {#prop-mac-src-match-short-addresses} -Structure Parameters: +* Type: Multi-Value, Read-Write +* Asynchronous Updates: No +* Per-Item Length: No +* Required: **OPTIONAL** +* Post-Reset Value: empty +* Required Capability: `CAP_MAC_RAW`, TODO: 802.15.4 PHY CAP +* See Also: (#prop-mac-src-match-enabled) -* `S`: Short address for hardware generated ACKs +Configures the list of short addresses used for source matching. These +short address are used for hardware generated ACKs. -### PROP 4869: SPINEL_PROP_MAC_SRC_MATCH_EXTENDED_ADDRESSES {#prop-mac-src-match-extended-addresses} -* Type: Write -* Packed-Encoding: `A(E)` +Item Format: -Configures the list of extended addresses used for source matching. This property -is only available if the `SPINEL_CAP_MAC_RAW` capability is present. +Bytes: | 2 +--------|---- +Format: | UINT16_LE +Fields: | SADDR -Structure Parameters: +### PROP 4869: PROP_MAC_SRC_MATCH_EXTENDED_ADDRESSES {#prop-mac-src-match-extended-addresses} +* Type: Multi-Value, Read-Write +* Asynchronous Updates: No +* Per-Item Length: No +* Required: **OPTIONAL** +* Post-Reset Value: empty +* Required Capabilities: `CAP_MAC_RAW`, TODO: 802.15.4 PHY CAP +* See Also: (#prop-mac-src-match-enabled) -* `E`: EUI64 address for hardware generated ACKs +Configures the list of long addresses used for source matching. These +long address are used for hardware generated ACKs. ### PROP 4870: PROP_MAC_BLACKLIST {#prop-mac-blacklist} -* Type: Read-Write -* Packed-Encoding: `A(T(E))` -* Required capability: `CAP_MAC_WHITELIST` -Structure Parameters: +* Type: Multi-Value, Read-Write +* Asynchronous Updates: No +* Per-Item Length: No +* Required: **OPTIONAL** +* Post-Reset Value: empty +* Required Capability: `CAP_MAC_WHITELIST` +* See Also: (#prop-mac-blacklist-enabled) + +TODO(RQ): Consider moving this to the debug section. -* `E`: EUI64 address of node +When blacklisting is enabled, this property prevents the device from being able +to communicate with devices which are in this list. ### PROP 4871: PROP_MAC_BLACKLIST_ENABLED {#prop-mac-blacklist-enabled} -* Type: Read-Write -* Packed-Encoding: `b` + +* Type: Single-Value, Read-Write +* Asynchronous Updates: No +* Required: **OPTIONAL** +* Post-Reset Value: 0 (false) * Required capability: `CAP_MAC_WHITELIST` +* See Also: (#prop-mac-blacklist) + +TODO(RQ): Consider moving this to the debug section. + +Setting this to true **SHALL** cause `PROP_MAC_WHITELIST_ENABLED` to be automatically +set to false. + +Bytes: | 1 +-------:|------------- +Format: | BOOL +Fields: | `BLACKLIST_ENABLED` diff --git a/core/detail-properties-net.md b/core/detail-properties-net.md index 91b68ba..8639404 100644 --- a/core/detail-properties-net.md +++ b/core/detail-properties-net.md @@ -1,16 +1,40 @@ ## NET Properties {#prop-net} ### PROP 65: PROP_NET_IF_UP {#prop-net-if-up} -* Type: Read-Write -* Packed-Encoding: `b` + +* Type: Single-Value, Read-Write +* Asynchronous Updates: Yes +* Required: **REQUIRED** +* Post-Reset Value: 0 (false) + +Bytes: | 1 +-------:|------------- +Format: | BOOL +Fields: | `NET_IF_UP` Network interface up/down status. Non-zero (set to 1) indicates up, zero indicates down. +Setting this to false implies also setting `PROP_NET_STACK_UP` to false. + +#### Relationship with PROP_NET_STACK_UP + +EDITOR: the examples show that the order of operations to bring up a network interface is first set PROP_NET_IF_UP=TRUE, then PROP_NET_STACK_UP=TRUE. What does it mean when PROP_NET_IF_UP=TRUE and PROP_NET_STACK_UP=FALSE? Does the NLI matter in operations with the PROP_NET_STACK_UP property? + +RQ: PROP_NET_IF_UP=TRUE, PROP_NET_STACK_UP=FALSE is used for in-band commissioning. +It bring up link-local IPv6 capabilities on PROP_STREAM_NET_INSECURE. + ### PROP 66: PROP_NET_STACK_UP {#prop-net-stack-up} -* Type: Read-Write -* Packed-Encoding: `b` -* Unit: Enumeration + +* Type: Single-Value, Read-Write +* Asynchronous Updates: Yes +* Required: **REQUIRED** +* Post-Reset Value: 0 (false) + +Bytes: | 1 +-------:|------------- +Format: | BOOL +Fields: | `NET_STACK_UP` Network protocol stack operational status. Non-zero (set to 1) indicates up, zero indicates down. -EDITOR: the examples show that the order of operations to bring up a network interface is first set PROP_NET_IF_UP=TRUE, then PROP_NET_STACK_UP=TRUE. What does it mean when PROP_NET_IF_UP=TRUE and PROP_NET_STACK_UP=FALSE? Does the NLI matter in operations with the PROP_NET_STACK_UP property? +Setting this to true implies also setting `PROP_NET_IF_UP` to true. diff --git a/core/detail-properties-phy.md b/core/detail-properties-phy.md index 607e13c..c9120d4 100644 --- a/core/detail-properties-phy.md +++ b/core/detail-properties-phy.md @@ -1,8 +1,19 @@ ## PHY Properties {#prop-phy} ### PROP 32: PROP_PHY_ENABLED {#prop-phy-enabled} -* Type: Read-Write -* Packed-Encoding: `b` (bool8) + +* Type: Single-Value, Read-Write +* Asynchronous Updates: No +* Required: + * Read: Yes + * Write: No +* Post-Reset Value: 0 (false) +* Related Capabilities: SPINEL_CAP_MAC_RAW + +Bytes: | 1 +-------:|------------- +Format: | BOOL +Fields: | `PHY_ENABLED` Set to 1 if the PHY is enabled, set to 0 otherwise. May be directly enabled to bypass higher-level packet processing @@ -10,62 +21,143 @@ in order to implement things like packet sniffers. This property can only be written if the `SPINEL_CAP_MAC_RAW` capability is present. ### PROP 33: PROP_PHY_CHAN {#prop-phy-chan} -* Type: Read-Write -* Packed-Encoding: `C` (uint8) + +* Type: Single-Value, Read-Write +* Asynchronous Updates: No +* Required: **REQUIRED** +* Unit: Channel Index +* Post-Reset Value: Unspecified + +Bytes: | 1 +-------:|------------- +Format: | UINT8 +Fields: | `CHANNEL` Value is the current channel. Must be set to one of the values contained in `PROP_PHY_CHAN_SUPPORTED`. ### PROP 34: PROP_PHY_CHAN_SUPPORTED {#prop-phy-chan-supported} -* Type: Read-Only -* Packed-Encoding: `A(C)` (array of uint8) -* Unit: List of channels + +* Type: Multiple-Value, Constant +* Asynchronous Updates: No +* Required: **REQUIRED** +* Unit: Channel Index +* Post-Reset Value: Implementation Specific + +Bytes: | 1 | 1 | ... +-------:|-------|-------|----- +Format: | UINT8 | UINT8 | ... +Fields: | `CHANNEL` | `CHANNEL` | ... Value is a list of channel values that are supported by the -hardware. +NCP. ### PROP 35: PROP_PHY_FREQ {#prop-phy-freq} -* Type: Read-Only -* Packed-Encoding: `L` (uint32) -* Unit: Kilohertz + +* Type: Single-Value, Read-Only +* Asynchronous Updates: No +* Required: **REQUIRED** +* Unit: kHz +* Post-Reset Value: Unspecified + +Bytes: | 1 +-------:|------------- +Format: | UINT32_LE +Fields: | `FREQ` Value is the radio frequency (in kilohertz) of the current channel. ### PROP 36: PROP_PHY_CCA_THRESHOLD {#prop-phy-cca-threshold} -* Type: Read-Write -* Packed-Encoding: `c` (int8) -* Unit: dBm + +* Type: Single-Value, Read-Write +* Asynchronous Updates: No +* Required: **OPTIONAL** +* Unit: dB +* Post-Reset Value: Implementation-specific default + +Bytes: | 1 +-------:|------------- +Format: | INT8 +Fields: | `CCA_THRESHOLD` Value is the CCA (clear-channel assessment) threshold. Set to -128 to disable. -When setting, the value will be rounded down to a value +The specific meaning of zero dB is implementation-specific, +but **MUST** be consistant with definitions of other properties +that express power. It is **RECOMMENDED** that zero dB +represent one milliwatt of power (0dBm), as measured from the +antenna connector. + +When setting, the value **SHOULD** be rounded down to a value that is supported by the underlying radio hardware. ### PROP 37: PROP_PHY_TX_POWER {#prop-phy-tx-power} -* Type: Read-Write -* Packed-Encoding: `c` (int8) -* Unit: dBm -Value is the transmit power of the radio. +* Type: Single-Value, Read-Write +* Asynchronous Updates: No +* Required: **REQUIRED** +* Unit: dB +* Post-Reset Value: 0dB + +Bytes: | 1 +-------:|------------- +Format: | INT8 +Fields: | `TX_POWER` + +Value is the transmit power of the radio, measured in decibells. -When setting, the value will be rounded down to a value +The specific meaning of zero dB is implementation-specific, +but **MUST** be consistant with definitions of other properties +that express power. It is **RECOMMENDED** that zero dB +represent one milliwatt of power (0dBm), as measured from the +antenna connector. + +When setting, the value **SHOULD** be rounded down to a value that is supported by the underlying radio hardware. ### PROP 38: PROP_PHY_RSSI {#prop-phy-rssi} -* Type: Read-Only -* Packed-Encoding: `c` (int8) -* Unit: dBm -Value is the current RSSI (Received signal strength indication) +* Type: Single-Value, Read-Only +* Asynchronous Updates: No +* Required: **REQUIRED** +* Unit: dB +* Post-Reset Value: Unspecified + +Bytes: | 1 +-------:|------------- +Format: | INT8 +Fields: | `RSSI` + +Value is the current RSSI (Received Signal Strength Indication) from the radio. This value can be used in energy scans and for determining the ambient noise floor for the operating environment. +The specific meaning of zero dB is implementation-specific, +but **MUST** be consistant with definitions of other properties +that express power. It is **RECOMMENDED** that zero dB +represent one milliwatt of power (0dBm), as measured from the +antenna connector. + ### PROP 39: PROP_PHY_RX_SENSITIVITY {#prop-phy-rx-sensitivity} -* Type: Read-Only -* Packed-Encoding: `c` (int8) -* Unit: dBm + +* Type: Single-Value, Read-Only +* Asynchronous Updates: No +* Required: **OPTIONAL** +* Unit: dB +* Post-Reset Value: Unspecified + +Bytes: | 1 +-------:|------------- +Format: | INT8 +Fields: | `RX_SENSITIVITY` Value is the radio receive sensitivity. This value can be used as lower bound noise floor for link metrics computation. + +The specific meaning of zero dB is implementation-specific, +but **MUST** be consistant with definitions of other properties +that express power. It is **RECOMMENDED** that zero dB +represent one milliwatt of power (0dBm), as measured from the +antenna connector.