fuchsia.lowpan.device

PROTOCOLS

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.

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 fuchsia.lowpan/ProvisioningParams

Response

NameType

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

NameType

Response

NameType

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

NameType

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

NameType

Response

NameType
network_types vector<string>[16]

GetSupportedChannels

Returns a vector of information about the channels supported by this interface.

Request

NameType

Response

NameType
channels_info vector<fuchsia.lowpan/ChannelInfo>[100]

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

NameType

Response

NameType
device_combined_state DeviceState

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.

FormNetwork

Forms a new network with the given provisioning parameters.

Any unspecified fields that are required by the underlying device or network type will assigned with default values. If the credential is unspecified, a random one will be generated automatically.

This method will cause the device to leave any previously provisioned network.

Calling this method while the device is not active will implicitly make the device active.

Upon success, the device will be active and provisioned for the newly created network.

The progress of the operation can be monitored via the ProvisioningMonitor protocol instance. The operation may be cancelled by closing the ProvisioningMonitor.

Request

NameType
params fuchsia.lowpan/ProvisioningParams
progress request<ProvisioningMonitor>

JoinNetwork

Attempts to join a pre-existing nearby network with the given provisioning parameters.

Upon success, the device will be active and provisioned for the newly created network.

The progress of the operation can be monitored via the ProvisioningMonitor protocol instance. The operation may be cancelled by closing the ProvisioningMonitor.

Request

NameType
params fuchsia.lowpan/ProvisioningParams
progress request<ProvisioningMonitor>

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

NameType

Response

NameType
credential fuchsia.lowpan/Credential?

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 request<EnergyScanResultStream>

StartNetworkScan

Starts an active network scan operation.

This scan is used to identify other nearby networks in order 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.

A NetworkScanner instance could be used to expose coarse location information.

Request

NameType
params NetworkScanParameters
stream request<BeaconInfoStream>

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

NameType

Response

NameType
identity fuchsia.lowpan/Identity

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

NameType

Response

NameType
results vector<EnergyScanResult>[32]

BeaconInfoStream

Defined in fuchsia.lowpan.device/network_scanner.fidl

Protocol for returning the results of a network scan operation.

Closing the client end of an instance of this protocol will effectively cancel the scan operation.

Next

Called to fetch the next set of received beacons.

The last set will have zero items. Once all received beacons have been returned, this channel will close.

Request

NameType

Response

NameType
beacons vector<fuchsia.lowpan/BeaconInfo>[32]

ProvisioningMonitor

Defined in fuchsia.lowpan.device/provisioning_monitor.fidl

Reports the progress of a provisioning operation like Join or Form.

If there was a problem with the arguments passed to the originating function (Join/Form) then the channel will be closed with ZX_ERR_INVALID_ARGS.

WatchProgress

Call this method to receive an update on the provisioning progress.

When first called, this method will return immediately with the current status. On subsequent calls, it will block until the status changes.

If provisioning error is encountered, it is returned as a ProvisionError. See the documentation for ProvisionError details on error handling.

Once the method has either returned an identity or indicated a ProvisionError, the ProvisioningMonitor will close with ZX_OK.

Request

NameType

Response

NameType
result ProvisioningMonitor_WatchProgress_Result

Driver

Defined in fuchsia.lowpan.device/service.fidl

Protocol representing a LoWPAN driver instance.

GetProtocols

Request protocols to control this device. Unsupported protocols are closed.

Request

NameType
protocols Protocols

Lookup

Defined in fuchsia.lowpan.device/service.fidl

Protocol for discovering and resolving LoWPAN interfaces and their associated control protocol instances.

LookupDevice

Looks up the LoWPAN Device for the given interface name.

The name of the interface can be learned by calling GetDevices().

Request

NameType
name InterfaceName
protocols Protocols

Response

NameType
result Lookup_LookupDevice_Result

GetDevices

Returns the list of all registered LoWPAN device interface names.

Request

NameType

Response

NameType
device_names vector<string>[8]

WatchDevices

Observes when devices are added or removed.

The first call to this method returns immediately with a DeviceChanges struct containing only items in the added field with the names of all of the current devices. Subsequent calls will block until a device has been added or removed, at which point it will return with the added and/or removed fields filled out accordingly. The changes are reported since the time that the method returned.

If both the added and removed fields have names in the returned table, then the removed field MUST be processed BEFORE added field.

If a device was added and then removed in-between calls to this method, the device will be absent from both the added and removed lists.

If the same device name is listed on both the added and removed fields, then the client should assume that the original device was removed and a new device instance started in its place. However, while the client should be able to handle this condition, it should not depend on the server will always have this behavior.

Request

NameType

Response

NameType
device_changes DeviceChanges

Register

Defined in fuchsia.lowpan.device/service.fidl

Protocol for registering LoWPAN interfaces and their associated control protocols with the LoWPAN service.

RegisterDevice

Registers the given LoWPAN device with the LoWPAN Service using the given interface name.

Request

NameType
name InterfaceName
driver Driver

Response

NameType
result Register_RegisterDevice_Result

STRUCTS

ProvisioningMonitor_WatchProgress_Response

Defined in fuchsia.lowpan.device/provisioning_monitor.fidl

NameTypeDescriptionDefault
progress ProvisioningProgress No default

Lookup_LookupDevice_Response

Defined in fuchsia.lowpan.device/service.fidl

NameTypeDescriptionDefault

Register_RegisterDevice_Response

Defined in fuchsia.lowpan.device/service.fidl

NameTypeDescriptionDefault

DeviceChanges

Defined in fuchsia.lowpan.device/service.fidl

Struct describing changes to the devices being managed by the LoWPAN service.

NameTypeDescriptionDefault
removed vector<string>[8] No default
added vector<string>[8] No default

ENUMS

ProvisionError

Type: int32

Defined in fuchsia.lowpan.device/provisioning_monitor.fidl

LoWPAN Provisioning Error

Returned by ProvisioningMonitor.WatchProgress().

NameValueDescription
CREDENTIAL_REJECTED 1

Provisioning did not successfully complete because the credential was rejected. For example, the key was incorrect.

This may be interpreted as an argument error.

NETWORK_NOT_FOUND 2

Provisioning did not successfully complete because the no peers on the requested network are in range.

NETWORK_ALREADY_EXISTS 3

Forming a new network did not successfully complete because the a peer with the requested network identity is in range.

ServiceError

Type: int32

Defined in fuchsia.lowpan.device/service.fidl

NameValueDescription
INVALID_ARGUMENT 1

One of the arguments to this method was invalid.

This error is only returned if none of the other error codes would be a better description.

DEVICE_NOT_FOUND 2

A device with this interface name has not been registered.

DEVICE_ALREADY_EXISTS 3

A device with this interface name has already been registered.

INVALID_INTERFACE_NAME 4

The given interface name was invalid.

See the documentation for InterfaceName for more details.

TOO_MANY_DEVICES 5

Too many LoWPAN devices have already been registered.

TABLES

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.

OrdinalNameTypeDescription
1 connectivity_state fuchsia.lowpan/ConnectivityState

LoWPAN Connectivity State

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

2 role fuchsia.lowpan/Role

LoWPAN Role

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

EnergyScanResult

Defined in fuchsia.lowpan.device/energy_scanner.fidl

Describes the result from one channel of an energy scan.

OrdinalNameTypeDescription
1 channel_index ChannelIndex
2 max_rssi int32

The maximum RSSI detected on this channel.

3 min_rssi int32

The minimum RSSI detected on this channel.

EnergyScanParameters

Defined in fuchsia.lowpan.device/energy_scanner.fidl

Describes the parameters of an energy scan.

OrdinalNameTypeDescription
1 channels vector<uint16>[100]

Subset of channels to scan.

If unspecified, all channels will be scanned.

2 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.

NetworkScanParameters

Defined in fuchsia.lowpan.device/network_scanner.fidl

Describes the parameters of a network scan.

OrdinalNameTypeDescription
1 channels vector<uint16>[100]

Subset of channels to scan.

If unspecified, all channels will be scanned.

2 tx_power_dbm int32

Transmit power (in dBm to the antenna) for transmitting beacon requests.

Note that hardware limitations may cause the actual used transmit power to differ from what is specified. In that case the used transmit power will always be the highest available transmit power that is less than the specified transmit power. If the desired transmit power is lower than the lowest transmit power supported by the hardware, then that will be used instead.

Protocols

Defined in fuchsia.lowpan.device/service.fidl

Table of protocol requests that is passed into Lookup.Lookup() and Driver.GetProtocols().

OrdinalNameTypeDescription
1 device request<Device>
2 device_extra request<DeviceExtra>
3 device_test request<fuchsia.lowpan.test/DeviceTest>

UNIONS

ProvisioningMonitor_WatchProgress_Result

Defined in fuchsia.lowpan.device/provisioning_monitor.fidl

NameTypeDescription
response ProvisioningMonitor_WatchProgress_Response
err ProvisionError

ProvisioningProgress

Defined in fuchsia.lowpan.device/provisioning_monitor.fidl

Indicates the current status of the form/join operation.

Returned by ProvisioningMonitor.WatchProgress().

NameTypeDescription
progress float32

Approximate percent complete indication for a user interface.

identity fuchsia.lowpan/Identity

The final Identity when the operation has completed successfully.

Lookup_LookupDevice_Result

Defined in fuchsia.lowpan.device/service.fidl

NameTypeDescription
response Lookup_LookupDevice_Response
err ServiceError

Register_RegisterDevice_Result

Defined in fuchsia.lowpan.device/service.fidl

NameTypeDescription
response Register_RegisterDevice_Response
err ServiceError

CONSTANTS

NameValueTypeDescription
MAX_STREAM_SET_SIZE 32 uint16

The maximum number of items that can be returned at one time by a scan stream.

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_LOWPAN_DEVICES 8 uint32

TYPE ALIASES

NameValueDescription
ChannelIndex uint16

Type for describing a channel index.

InterfaceName string

Type describing the name of the network interface.

Interface names must satisfy the following regular expression:

 ^[a-z_][-_.+0-9a-z]{1,31}$