fuchsia.lowpan.device

Added: 7

PROTOCOLS

Counters

Defined in fuchsia.lowpan.device/counters.fidl

Get

Returns a snapshot of the counters without resetting the counters.

Request

<EMPTY>

Response

NameType
counters AllCounters

Reset

Resets all of the counters to zero returning the counter values immediately prior.

Request

<EMPTY>

Response

NameType
counters AllCounters

CountersConnector

Defined in fuchsia.lowpan.device/counters.fidl

Protocol for connecting to Counters on a LoWPAN interface.

Connect

Connects to the DeviceCounters protocol on the named LoWPAN interface.

The name of the interface can be learned by calling [`fuchsia.lowpan/Lookup.GetDevices].

If there is an error in processing this request the given channel is closed and an epitaph code used to describe the reason for the failure:

  • ZX_ERR_INVALID_ARGUMENT: The given interface name was not formatted correctly or otherwise invalid.
  • ZX_ERR_NOT_FOUND: No interface was found with the given name.
  • ZX_ERR_NOT_SUPPORTED: The interface exists but does not support this protocol.

Request

NameType
name fuchsia.lowpan/InterfaceName
server_end server_end:Counters

Device

Defined in fuchsia.lowpan.device/device.fidl

LoWPAN Device Protocol.

This protocol provides clients with a way to control and monitor the device.

Note that aspects of the device that deal with PII must be monitored and controlled via the DeviceExtra protocol.

GetSupportedNetworkTypes

Returns the types of networks supported by this interface.

LoWPAN devices typically only support a single network type, but some devices may support more than one. Up to MAX_NETWORK_TYPES network types may be returned.

Request

<EMPTY>

Response

NameType
network_types vector<NetworkType>:16

LeaveNetwork

Bring down the network interface and forget all non-volatile details about the current network.

Upon completion, all non-volatile and transient state about the current network is cleared and the interface will be offline.

Specifically, calling this method will cause the following observable effects:

  • DeviceState.connectivity_state will transition to State::OFFLINE, assuming it wasn't in that state already.
  • DeviceExtra::WatchIdentity will emit an empty Identity, assuming it wasn't already empty.

If the interface was not previously provisioned, calling this method does nothing.

Request

<EMPTY>

Response

<EMPTY>

ProvisionNetwork

Provision the interface for the network described by identity and credential. This is similar to JoinNetwork, except that (assuming the identity and credential are valid) it will (assuming all preconditions are met) always succeed, even if there are no peers nearby.

The following fields of ProvisioningParams MUST be specified:

  • identity.raw_name
  • identity.xpanid
  • identity.panid
  • identity.channel_index
  • credential

If any of the required fields are unspecified, the channel will be closed with the epitaph ZX_ERR_INVALID_ARGUMENT.

Additionally, if the identity.net_type field is present and does not match a network type supported by this device, the channel will also be closed with the epitaph ZX_ERR_NOT_SUPPORTED.

This method returns once the device has been reconfigured successfully. The resulting change in state can be monitored via WatchDeviceState(). Any error that prevents the operation from completing successfully will result in the protocol being closed.

Request

NameType
params ProvisioningParams

Response

<EMPTY>

SetActive

Activate ("bring-up") or deactivate ("shut-down") the network interface.

Note that simply setting this to true does not mean that the network interface will necessarily become online and usable, see the connectivity_state field of the DeviceState table for more information.

This method returns once the operation has completed successfully. The resulting change in state can be monitored via WatchDeviceState(). Any error that prevents the operation from completing successfully will result in the protocol being closed.

Request

NameType
active bool

Response

<EMPTY>

WatchDeviceState

Observes changes to the DeviceState.

First call always returns a snapshot of the current state. Subsequent calls will block until the state has changed and returns the delta against the device's internal state.

Changes are not queued. The returned value always represents the latest and most accurate state values, even if several changes had happened in-between calls.

Request

<EMPTY>

Response

NameType
device_combined_state DeviceState

DeviceConnector

Defined in fuchsia.lowpan.device/device.fidl

Protocol for connecting to Device on a LoWPAN interface.

Connect

Connects to the Device protocol on the named LoWPAN interface.

The name of the interface can be learned by calling fuchsia.lowpan/Lookup.GetDevices().

If there is an error in processing this request the given channel is closed and an epitaph code used to describe the reason for the failure:

  • ZX_ERR_INVALID_ARGUMENT: The given interface name was not formatted correctly or otherwise invalid.
  • ZX_ERR_NOT_FOUND: No interface was found with the given name.
  • ZX_ERR_NOT_SUPPORTED: The interface exists but does not support this protocol.

Request

NameType
name fuchsia.lowpan/InterfaceName
server_end server_end:Device

DeviceExtra

Defined in fuchsia.lowpan.device/device.fidl

LoWPAN Device "Extra" Protocol.

This protocol provides clients with a way to control and monitor aspects of the LoWPAN device that can, either directly or indirectly, leak PII or cryptographic keys.

GetCredential

Fetches the current credential.

The returned credential will have originated from a previous call to ProvisionNetwork, JoinNetwork, or FormNetwork. If the device is not provisioned (for example, by calling LeaveNetwork()) then this method returns nothing.

Request

<EMPTY>

Response

NameType
credential Credential?

GetCurrentMacAddress

Returns the current MAC address being used for this device, which may differ from the static factory-assigned MAC address.

This address is generally static, but may change when the device is re-associated to a different network or a factory reset is performed.

Added: 9

Request

<EMPTY>

Response

NameType
address fuchsia.lowpan/MacAddress

WatchIdentity

Observes changes to the current network identity.

First call always returns a snapshot of the current identity. Subsequent calls will block until the identity has changed, upon which the entire updated identity is returned.

If there is no identity currently associated with the device, then the returned identity will be empty.

Changes are not queued. The returned identity always represents the latest and most accurate value, even if several changes had happened in-between calls.

Note that the changes are NOT incremental: whenever there is a change, the entire current LoWPAN identity is returned.

The value of the identity can be changed by any of the following calls:

  • Device.ProvisionNetwork()
  • Device.LeaveNetwork()
  • DeviceExtra.JoinNetwork()
  • DeviceExtra.FormNetwork()

Request

<EMPTY>

Response

NameType
identity Identity

DeviceExtraConnector

Defined in fuchsia.lowpan.device/device.fidl

Protocol for connecting to DeviceExtra on a LoWPAN interface.

Connect

Connects to the DeviceExtra protocol on the named LoWPAN interface.

The name of the interface can be learned by calling fuchsia.lowpan/Lookup.GetDevices.

If there is an error in processing this request the given channel is closed and an epitaph code used to describe the reason for the failure:

  • ZX_ERR_INVALID_ARGUMENT: The given interface name was not formatted correctly or otherwise invalid.
  • ZX_ERR_NOT_FOUND: No interface was found with the given name.
  • ZX_ERR_NOT_SUPPORTED: The interface exists but does not support this protocol.

Request

NameType
name fuchsia.lowpan/InterfaceName
server_end server_end:DeviceExtra

EnergyScan

Defined in fuchsia.lowpan.device/energy_scanner.fidl

StartEnergyScan

Starts an energy scan operation.

This can be used for surveying the spectrum to identify channels that should be avoided.

The scan operation may be cancelled by closing the stream protocol.

If a scan is started while another scan is in progress, the previous scan is allowed to complete before the new scan executes and starts returning results.

All scans should be expected to completely occupy the LoWPAN device while it is in progress, preventing other operations from completing until the scan has completed. Additionally, all network packets should be expected to be dropped while a scan is in progress.

Performing energy scans could be used to profile the spectrum energy for a location and thus be used to determine or refine coarse location information.

Request

NameType
params EnergyScanParameters
stream server_end:EnergyScanResultStream

EnergyScanConnector

Defined in fuchsia.lowpan.device/energy_scanner.fidl

Protocol for connecting to EnergyScan on a LoWPAN interface.

Connect

Connects to the EnergyScan protocol on the named LoWPAN interface.

The name of the interface can be learned by calling fuchsia.lowpan/Lookup.GetDevices.

If there is an error in processing this request the given channel is closed and an epitaph code used to describe the reason for the failure:

  • ZX_ERR_INVALID_ARGUMENT: The given interface name was not formatted correctly or otherwise invalid.
  • ZX_ERR_NOT_FOUND: No interface was found with the given name.
  • ZX_ERR_NOT_SUPPORTED: The interface exists but does not support this protocol.

Request

NameType
name fuchsia.lowpan/InterfaceName
server_end server_end:EnergyScan

EnergyScanResultStream

Defined in fuchsia.lowpan.device/energy_scanner.fidl

Protocol for returning the results of an energy scan operation.

Closing the protocol will cancel the associated scan operation.

Next

Called to fetch the next set of energy scan results.

The last set will have zero items and the protocol will be closed.

Request

<EMPTY>

Response

NameType
results vector<EnergyScanResult>:32

STRUCTS

ProvisioningParams

Defined in fuchsia.lowpan.device/provisioning_params.fidl

FieldTypeDescriptionDefault
identity Identity

The identity of the network.

 No default
credential Credential?

The credential used to authenticate to the network.

 No default

ENUMS

ConnectivityState flexible

Type: int32

Defined in fuchsia.lowpan.device/device.fidl

LoWPAN Connectivity State

This enum describes the level of connectivity being provided by a device.

NameValueDescription
1

Inactive state.

In this state the device is unprovisioned and administratively disabled (inactive).

This state can always be explicitly entered by calling Leave followed by SetActive(false).
2

Ready state.

In this state the device is provisioned for a network, but is administratively disabled (inactive).

This state can be directly entered with the following actions based on the current connectivity state:

  • INACTIVE: by calling ProvisionNetwork(...).
  • ATTACHING, ATTACHED, ISOLATED, COMMISSIONING: by calling SetActive(false).
3

Offline state.

In this state the device is administratively enabled (active) but is not provisioned and thus has no network to attach to.

This state can be directly entered with the following actions based on the current connectivity state:

  • INACTIVE: by calling SetActive(true).
  • ATTACHING, ATTACHED, ISOLATED, COMMISSIONING: by calling Leave().
4

Attaching state.

In this state the device is administratively enabled (active) and either provisioned for a network or shortly about to become provisioned for a network.

The interface enters this state when it starts the process of trying to find other nodes so that it can attach to any pre-existing network fragment, or when it is in the process of calculating the optimal values for unspecified parameters when forming a new network.

This state can be directly entered with the following actions based on the current connectivity state:

  • READY: by calling SetActive(true)
  • OFFLINE, ATTACHING, ATTACHED, ISOLATED, COMMISSIONING: by calling ProvisionNetwork(...), FormNetwork(...), or JoinNetwork(...)
5

Attached state.

In this state the device is both administratively enabled (active) and provisioned for a network. The device is an active participant on the network and can communicate with peers.

This state usually implies that peers are available, but that may not actually be the case due to current network conditions or privacy-protecting measures.

This state cannot generally be entered directly, rather the device will enter this state automatically from the ATTACHING or ISOLATED states once connectivity has been (re)established.
6

Isolated state.

In this state the device is both administratively enabled (active) and provisioned for a network. However, the device has no connectivity because there are no peers in range on the provisioned network.

Once peer devices on the same network come into range the connectivity state will eventually switch back to ATTACHED, indicating restored connectivity with at least one peer.

This state cannot generally be entered directly, rather the device may enter this state automatically from the ATTACHING or ATTACHED states.
7

Commissioning state.

Currently unused, but will later be used to support in-band commissioning. It is usually appropriate to consider this as a synonym for the ATTACHING state except that the device remains unprovisioned.

Role flexible

Type: int32

Defined in fuchsia.lowpan.device/device.fidl

LoWPAN Role Type.

This type describes the role a device can assume on a network.

NameValueDescription
1

Detached role. The interface is not currently participating on the network, either because it cannot find a parent
2

End-device role. End devices do not route traffic on behalf of other nodes.
3

Router role. Routers help route traffic around the mesh network.

Note that this role is independent of the device being a "border router".

Not all network types support this role.
4

Sleepy End-Device role.

End devices with this role are nominally asleep, waking up periodically to check in with their parent to see if there are packets destined for them. Such devices are capable of extraordinarily low power consumption, but packet latency can be on the order of dozens of seconds(depending on how the node is configured). Not all network types support this role.

Not all network types support this role.
5

Sleepy-router role.

Routers with this role are nominally asleep, waking up periodically to check in with other routers and their children.

Not all network types support this role.
6

Leader role.

On Thread networks, for each partition/fragment one router is designated as the "leader", which means that it is considered authoritative for all network data. In most cases this role can be considered as a synonym to Role::ROUTER.

Not all network types support this role.
7

Coordinator role.

Not all network types support this role.

TABLES

AllCounters

Defined in fuchsia.lowpan.device/counters.fidl

Describes all counters.

May be empty if no counters are supported.

OrdinalFieldTypeDescription
mac_tx MacCounters

MAC Counters for TX
mac_rx MacCounters

MAC Counters for RX
coex_tx CoexCounters

Coex Counters for TX
coex_rx CoexCounters

Coex Counters for RX
coex_saturated bool

Coex stats may be incorrect due to internal counter overflow.

Reset the counters to clear this flag.
ip_tx IpCounters

IP Counters for TX.

Added: 8
ip_rx IpCounters

IP Counters for RX.

Added: 8

CoexCounters

Defined in fuchsia.lowpan.device/counters.fidl

Counters associated with RF Coexistance.

Some counters are only valid for RX or TX. See this for more info.

OrdinalFieldTypeDescription
requests uint64

The number of requests
grant_immediate uint64

The number of requests while grant was active
grant_wait uint64

The number of requests while grant was inactive
grant_wait_activated uint64

The number of requests while grant was inactive that were ultimately granted
grant_wait_timeout uint64

The number of requests while grant was inactive that timed out
grant_deactivated_during_request uint64

The number of requests that were in progress when grant was deactivated
delayed_grant uint64

The number of requests that were not granted within 50µs
avg_delay_request_to_grant_usec uint32

The average time in µsec from request to grant
grant_none uint64

The number of requests that completed without receiving grant.

Receive only.

DeviceState

Defined in fuchsia.lowpan.device/device.fidl

Combined State for LoWPAN Devices

Contains the various properties of a LoWPAN device that define its current operational state.

You will get a snapshot of the current state upon the first invocation of WatchDeviceState(), after which future invocations of that method will return deltas.

OrdinalFieldTypeDescription
connectivity_state ConnectivityState

LoWPAN Connectivity State

This field describes the current level of connectivity being provided by this device.
role Role

LoWPAN Role

This field describes the current role this device is taking on the current network.

EnergyScanParameters

Defined in fuchsia.lowpan.device/energy_scanner.fidl

Describes the parameters of an energy scan.

OrdinalFieldTypeDescription
channels vector<fuchsia.lowpan/ChannelIndex>:200

Subset of channels to scan.

If unspecified, all channels will be scanned.
dwell_time_ms uint32

Desired dwell time per-channel for the energy scan, measured in milliseconds.

Note that firmware limitations may prevent the exact dwell time from being used. In such cases an approximation will be used.

Implementations must be able to support dwell times of at least 5000ms (5 seconds). The exact supported dwell-time range is device/driver dependent.

Setting a value outside of the supported range of values for this device will result in the value being clamped to the closest valid value, so setting a value of zero will always request the smallest energy scan duration the device is capable of.

If unspecified, a dwell time of approximately 500ms will be used.

EnergyScanResult

Defined in fuchsia.lowpan.device/energy_scanner.fidl

Describes the result from one channel of an energy scan.

OrdinalFieldTypeDescription
channel_index fuchsia.lowpan/ChannelIndex

The channel index for this energy scan result.
max_rssi int32

The maximum RSSI detected on this channel.
min_rssi int32

The minimum RSSI detected on this channel.

Identity

Defined in fuchsia.lowpan.device/device.fidl

OrdinalFieldTypeDescription
raw_name vector<uint8>:63

The raw bytes for the network name. This is typically a StringPrep'd UTF8 encoding.

Note that extra care must be taken when displaying this value to users, since there are many ways to make visually similar UTF8 strings that have differing bytecode representations.
net_type NetworkType

String identifying the type of network.

Well-known protocol ids are associated with specific string values (like "org.threadgroup.std.thread" or "org.zigbee.std.zigbee-ip"). For unknown protocol ids, the string will map to something like fuchsia.lowpan.net_type.802.15.4.pid.XX, where XX is the value of the protocol id from a 802.14.5 beacon. This field is optional when joining, forming, or provisioning.
channel fuchsia.lowpan/ChannelIndex

Channel Index.
panid uint16

PANID for 802.14.5-based networks (or the equivalent).
mesh_local_prefix fuchsia.net/Ipv6AddressWithPrefix

IPv6 Mesh-local prefix.

This parameter allows you to determine the mesh-local IPv6 prefix for the current network, or to specify one when provisioning the interface for a network or forming a new network.

The prefix length is always 64 bits, so only the upper 64 bits of the value are used: the least significant bits must be ignored when read and zero when set.

This field is ignored when supplied to JoinNetwork().
xpanid array<uint8, 8>

Extended PANID.

Added: 11

IpCounters

Defined in fuchsia.lowpan.device/counters.fidl

Counters associated with the IP layer.

Added: 8

OrdinalFieldTypeDescription
success uint32

The number of IPv6 packets successfully transmitted/received.
failure uint32

The number of IPv6 packets failed to transmit/receive.

MacCounters

Defined in fuchsia.lowpan.device/counters.fidl

Counters associated with the MAC layer.

Some counters are only valid for RX or TX.

OrdinalFieldTypeDescription
total uint32

The total number of frames
unicast uint32

The total number of unicast frames
broadcast uint32

The total number of broadcast frames
ack_requested uint32

The number of frames with ack request
acked uint32

The number of frames that were acked
no_ack_requested uint32

The number of frames without ack request
data uint32

The number of data frames
data_poll uint32

The number of data poll frames
beacon uint32

The number of beacon frames
beacon_request uint32

The number of beacon request frames
other uint32

The number of other types of frames
address_filtered uint32

The number of frames filtered by address filter (allowlist or denylist).
retries uint32

The number of retransmission attempts. TX only.
direct_max_retry_expiry uint32

The number of expired retransmission retries for direct message. TX only.
indirect_max_retry_expiry uint32

The number of expired retransmission retries for indirect message TX only.
dest_addr_filtered uint32

The number of received frames filtered by destination check. RX only.
duplicated uint32

The number of received duplicated frames. RX only.
err_no_frame uint32

The number of received frames with no or malformed content. RX only.
err_unknown_neighbor uint32

The number of received frames from unknown neighbor. RX only.
err_invalid_src_addr uint32

The number of received frames whose source address is invalid. RX only.
err_sec uint32

The number of received frames with security error. RX only.
err_fcs uint32

The number of received frames with FCS error. RX only.
err_cca uint32

The number of CCA failures. TX only.
err_abort uint32

The number of frame transmission failures due to abort error. TX only.
err_busy_channel uint32

The number of frames that were dropped due to a busy channel. TX only.
err_other uint32

The number of frames that encountered some other error.

UNIONS

Credential flexible

Defined in fuchsia.lowpan.device/device.fidl

Describes a LoWPAN credential.

Currently only supports a symmetric network key, but may be extended in the future to support other types of credentials, such as passwords, PAKE secrets, or a reference to a certificate/private-key pair.

OrdinalVariantTypeDescription
network_key vector<uint8>:32

Describes a symmetric key credential.

The size of the symmetric key is defined by the underlying network technology. For Thread this is a 16-byte value.

Note that this value is not a password.

CONSTANTS

NameValueTypeDescription
MAX_CHANNELS 200 uint16

Maximum number of channels that can be returned by Device.GetSupportedChannels.

Value was chosen arbitrarily to be large enough to accommodate any reasonable future use case.
MAX_NETWORK_TYPES 16 uint16

Maximum number of distinct network types that a LoWPAN device can support.

The choice of 16 is an arbitrary upper bound. Most devices will only support one, and maybe one day a device might support two. Sixteen was chosen because it's large enough to account for any failure of imagination, yet small enough to not cause system stability issues.
MAX_NET_TYPE_LEN 64 uint16

Maximum length of a network type string.

Chosen arbitrarily to be large enough to accommodate any reasonable future net types.
MAX_STREAM_SET_SIZE 32 uint16

The maximum number of items that can be returned at one time by a scan stream.
NET_TYPE_RAW_6LOWPAN fuchsia.lowpan.net_type.6lowpan String
NET_TYPE_THREAD_1_X org.threadgroup.std.thread.1 String
NET_TYPE_UNKNOWN_802_15_4_PID fuchsia.lowpan.net_type.802.15.4.pid String
NET_TYPE_ZIGBEE_IP_1_X org.zigbee.std.zigbee-ip.1 String

ALIASES

NameValueDescription
NetworkType string[MAX_NET_TYPE_LEN]

String describing a network type.