// 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;
    });
};