sdk/fidl/fuchsia.lowpan.experimental/device.fidl - fuchsia - Git at Google

 // Copyright 2022 The Fuchsia Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 library fuchsia.lowpan.experimental;

 using fuchsia.lowpan;
 using fuchsia.lowpan.device;

 type ChannelInfo = table {
     /// The index used by the interface to identify
     /// this channel.
     1: index fuchsia.lowpan.ChannelIndex;

     /// Human-readable identifier for channel.
     ///
     /// For most network types, this is just
     /// the string representation of the index.
     /// However, some network types might have
     /// non-integer ways of identifying specific
     /// channels. This field allows the application
     /// to display the name of the channel correctly
     /// under such circumstances.
     ///
     /// The allowed characters include:
     ///
     ///  * Dash (`-`), Underscore (`_`), Plus(`+`), Semicolon(`:`)
     ///  * Numbers (`0`-`9`)
     ///  * Letters (`a`-`z`, `A`-`Z`)
     2: id string:16;

     /// The maximum transmit power allowed on
     /// this channel, in dBm.
     3: max_transmit_power_dbm fuchsia.lowpan.PowerDbm;

     /// The center RF frequency of this channel, in Hz.
     ///
     /// For example, 802.15.4 has the following values:
     ///
     /// Channel | Center Frequency (Hz)
     /// --------|----------------------
     /// 11      | 2,405,000,000
     /// 12      | 2,410,000,000
     /// 13      | 2,415,000,000
     /// 14      | 2,420,000,000
     /// 15      | 2,425,000,000
     /// 16      | 2,430,000,000
     /// 17      | 2,435,000,000
     /// 18      | 2,440,000,000
     /// 19      | 2,445,000,000
     /// 20      | 2,450,000,000
     /// 21      | 2,455,000,000
     /// 22      | 2,460,000,000
     /// 23      | 2,465,000,000
     /// 24      | 2,470,000,000
     /// 25      | 2,475,000,000
     /// 26      | 2,480,000,000
     4: spectrum_center_frequency_hz uint64;

     /// The RF spectrum bandwidth used by this
     /// channel where the power level is expected to
     /// be higher than -20dBr, in Hz.
     ///
     /// For example, 802.15.4 channels 11 thru 26 would
     /// have the value 2,000,000 (2 MHz).
     5: spectrum_bandwidth_hz uint64;

     /// Indicates if this channel is masked by the
     /// current regulatory domain and is thus unable
     /// to be used.
     6: masked_by_regulatory_domain bool;
 };

 /// Protocol for connecting to [`Device`] on a LoWPAN
 /// interface.
 @discoverable
 protocol DeviceConnector {
     /// 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.
     Connect(resource struct {
         name fuchsia.lowpan.InterfaceName;
         server_end server_end:Device;
     });
 };

 /// LoWPAN Device Protocol, Experimental Methods.
 ///
 /// 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.
 protocol Device {
     /// Returns a vector of information about the
     /// channels supported by this interface.
     GetSupportedChannels() -> (struct {
         channels_info vector<ChannelInfo>:fuchsia.lowpan.device.MAX_CHANNELS;
     });
 };

 type BeaconInfo = table {
     /// The MAC address associated with this beacon.
     1: address fuchsia.lowpan.MacAddress;

     /// The identity of the network being advertised by
     /// this beacon.
     2: identity fuchsia.lowpan.device.Identity;

     /// RSSI of the beacon, measured in dBm.
     ///
     /// A value of -128 should be treated as if this
     /// field was absent.
     3: rssi fuchsia.lowpan.PowerDbm;

     /// Link Quality Index (LQI) of the beacon.
     ///
     /// * A value of 0 should be treated as if this
     ///   field was absent.
     /// * A value of 1 indicates the worst possible
     ///   quality where the decoded beacon is still valid.
     /// * A value of 255 indicates the best possible
     ///   quality that can be recognized by the radio
     ///   hardware.
     /// * Values 2-254 are intended to represent relative
     ///   quality levels evenly distributed between the
     ///   worst and best, with lower values always
     ///   indicating a worse quality than higher values.
     4: lqi uint8;
 };

 /// 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.
 protocol BeaconInfoStream {
     /// 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.
     Next() -> (struct {
         beacons vector<BeaconInfo>:fuchsia.lowpan.device.MAX_STREAM_SET_SIZE;
     });
 };

 /// Describes the parameters of a network scan.
 type NetworkScanParameters = table {
     /// Subset of channels to scan.
     ///
     /// If unspecified, all channels will be scanned.
     1: channels vector<fuchsia.lowpan.ChannelIndex>:fuchsia.lowpan.device.MAX_CHANNELS;

     /// 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.
     2: tx_power_dbm fuchsia.lowpan.PowerDbm;
 };


 /// Protocol for connecting to [`DeviceExtra`] on a LoWPAN
 /// interface.
 @discoverable
 protocol DeviceExtraConnector {
     /// 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.
     Connect(resource struct {
         name fuchsia.lowpan.InterfaceName;
         server_end server_end:DeviceExtra;
     });
 };

 /// LoWPAN Device "Extra" Protocol, Experimental Methods.
 ///
 /// 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.
 protocol DeviceExtra {
     // *****************************************************
     // ALL METHODS IN THIS CLASS DEAL WITH PII.
     // *****************************************************

     /// 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`.
     ///
     /// Calling this method will cause any current form, join, or
     /// commission operation to be canceled.
     FormNetwork(resource struct {
         params fuchsia.lowpan.device.ProvisioningParams;
         progress server_end:ProvisioningMonitor;
     });

     /// Attempts to join a pre-existing nearby network
     /// with the given provisioning parameters or joiner parameters.
     ///
     /// In-band commissioning is supported.
     ///
     /// 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`.
     ///
     /// Calling this method will cause any current form, join, or
     /// commission operation to be canceled.
     JoinNetwork(resource struct {
         params JoinParams;
         progress server_end:ProvisioningMonitor;
     });

     /// 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 [`BeaconInfoStream`] instance could be used to expose coarse
     /// location information.
     StartNetworkScan(resource struct {
         params NetworkScanParameters;
         stream server_end:BeaconInfoStream;
     });
 };
	// Copyright 2022 The Fuchsia Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style license that can be
	// found in the LICENSE file.
	library fuchsia.lowpan.experimental;

	using fuchsia.lowpan;
	using fuchsia.lowpan.device;

	type ChannelInfo = table {
	/// The index used by the interface to identify
	/// this channel.
	1: index fuchsia.lowpan.ChannelIndex;

	/// Human-readable identifier for channel.
	///
	/// For most network types, this is just
	/// the string representation of the index.
	/// However, some network types might have
	/// non-integer ways of identifying specific
	/// channels. This field allows the application
	/// to display the name of the channel correctly
	/// under such circumstances.
	///
	/// The allowed characters include:
	///
	/// * Dash (`-`), Underscore (`_`), Plus(`+`), Semicolon(`:`)
	/// * Numbers (`0`-`9`)
	/// * Letters (`a`-`z`, `A`-`Z`)
	2: id string:16;

	/// The maximum transmit power allowed on
	/// this channel, in dBm.
	3: max_transmit_power_dbm fuchsia.lowpan.PowerDbm;

	/// The center RF frequency of this channel, in Hz.
	///
	/// For example, 802.15.4 has the following values:
	///
	/// Channel \| Center Frequency (Hz)
	/// --------\|----------------------
	/// 11 \| 2,405,000,000
	/// 12 \| 2,410,000,000
	/// 13 \| 2,415,000,000
	/// 14 \| 2,420,000,000
	/// 15 \| 2,425,000,000
	/// 16 \| 2,430,000,000
	/// 17 \| 2,435,000,000
	/// 18 \| 2,440,000,000
	/// 19 \| 2,445,000,000
	/// 20 \| 2,450,000,000
	/// 21 \| 2,455,000,000
	/// 22 \| 2,460,000,000
	/// 23 \| 2,465,000,000
	/// 24 \| 2,470,000,000
	/// 25 \| 2,475,000,000
	/// 26 \| 2,480,000,000
	4: spectrum_center_frequency_hz uint64;

	/// The RF spectrum bandwidth used by this
	/// channel where the power level is expected to
	/// be higher than -20dBr, in Hz.
	///
	/// For example, 802.15.4 channels 11 thru 26 would
	/// have the value 2,000,000 (2 MHz).
	5: spectrum_bandwidth_hz uint64;

	/// Indicates if this channel is masked by the
	/// current regulatory domain and is thus unable
	/// to be used.
	6: masked_by_regulatory_domain bool;
	};

	/// Protocol for connecting to [`Device`] on a LoWPAN
	/// interface.
	@discoverable
	protocol DeviceConnector {
	/// 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.
	Connect(resource struct {
	name fuchsia.lowpan.InterfaceName;
	server_end server_end:Device;
	});
	};

	/// LoWPAN Device Protocol, Experimental Methods.
	///
	/// 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.
	protocol Device {
	/// Returns a vector of information about the
	/// channels supported by this interface.
	GetSupportedChannels() -> (struct {
	channels_info vector<ChannelInfo>:fuchsia.lowpan.device.MAX_CHANNELS;
	});
	};

	type BeaconInfo = table {
	/// The MAC address associated with this beacon.
	1: address fuchsia.lowpan.MacAddress;

	/// The identity of the network being advertised by
	/// this beacon.
	2: identity fuchsia.lowpan.device.Identity;

	/// RSSI of the beacon, measured in dBm.
	///
	/// A value of -128 should be treated as if this
	/// field was absent.
	3: rssi fuchsia.lowpan.PowerDbm;

	/// Link Quality Index (LQI) of the beacon.
	///
	/// * A value of 0 should be treated as if this
	/// field was absent.
	/// * A value of 1 indicates the worst possible
	/// quality where the decoded beacon is still valid.
	/// * A value of 255 indicates the best possible
	/// quality that can be recognized by the radio
	/// hardware.
	/// * Values 2-254 are intended to represent relative
	/// quality levels evenly distributed between the
	/// worst and best, with lower values always
	/// indicating a worse quality than higher values.
	4: lqi uint8;
	};

	/// 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.
	protocol BeaconInfoStream {
	/// 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.
	Next() -> (struct {
	beacons vector<BeaconInfo>:fuchsia.lowpan.device.MAX_STREAM_SET_SIZE;
	});
	};

	/// Describes the parameters of a network scan.
	type NetworkScanParameters = table {
	/// Subset of channels to scan.
	///
	/// If unspecified, all channels will be scanned.
	1: channels vector<fuchsia.lowpan.ChannelIndex>:fuchsia.lowpan.device.MAX_CHANNELS;

	/// 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.
	2: tx_power_dbm fuchsia.lowpan.PowerDbm;
	};


	/// Protocol for connecting to [`DeviceExtra`] on a LoWPAN
	/// interface.
	@discoverable
	protocol DeviceExtraConnector {
	/// 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.
	Connect(resource struct {
	name fuchsia.lowpan.InterfaceName;
	server_end server_end:DeviceExtra;
	});
	};

	/// LoWPAN Device "Extra" Protocol, Experimental Methods.
	///
	/// 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.
	protocol DeviceExtra {
	// *****************************************************
	// ALL METHODS IN THIS CLASS DEAL WITH PII.
	// *****************************************************

	/// 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`.
	///
	/// Calling this method will cause any current form, join, or
	/// commission operation to be canceled.
	FormNetwork(resource struct {
	params fuchsia.lowpan.device.ProvisioningParams;
	progress server_end:ProvisioningMonitor;
	});

	/// Attempts to join a pre-existing nearby network
	/// with the given provisioning parameters or joiner parameters.
	///
	/// In-band commissioning is supported.
	///
	/// 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`.
	///
	/// Calling this method will cause any current form, join, or
	/// commission operation to be canceled.
	JoinNetwork(resource struct {
	params JoinParams;
	progress server_end:ProvisioningMonitor;
	});

	/// 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 [`BeaconInfoStream`] instance could be used to expose coarse
	/// location information.
	StartNetworkScan(resource struct {
	params NetworkScanParameters;
	stream server_end:BeaconInfoStream;
	});
	};