blob: 378cdb947ba8ac583de0413abf84b20b867b44af [file] [log] [blame]
// Copyright 2020 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.device;
using fuchsia.lowpan;
/// Describes the result from one channel of an energy scan.
type EnergyScanResult = table {
/// The channel index for this energy scan result.
1: channel_index fuchsia.lowpan.ChannelIndex;
/// The maximum RSSI detected on this channel.
2: max_rssi int32;
/// The minimum RSSI detected on this channel.
3: min_rssi int32;
};
/// Describes the parameters of an energy scan.
type EnergyScanParameters = table {
/// Subset of channels to scan.
///
/// If unspecified, all channels will be scanned.
1: channels vector<fuchsia.lowpan.ChannelIndex>:MAX_CHANNELS;
/// 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.
2: dwell_time_ms uint32;
};
/// Protocol for returning the results of an energy scan operation.
///
/// Closing the protocol will cancel the associated scan operation.
protocol EnergyScanResultStream {
/// Called to fetch the next set of energy scan results.
///
/// The last set will have zero items and the protocol will be closed.
Next() -> (struct {
results vector<EnergyScanResult>:MAX_STREAM_SET_SIZE;
});
};
/// Protocol for connecting to [`EnergyScan`] on a LoWPAN
/// interface.
@discoverable
protocol EnergyScanConnector {
/// 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.
Connect(resource struct {
name fuchsia.lowpan.InterfaceName;
server_end server_end:EnergyScan;
});
};
protocol EnergyScan {
/// 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.
StartEnergyScan(resource struct {
params EnergyScanParameters;
stream server_end:EnergyScanResultStream;
});
};