sdk/fidl/fuchsia.lowpan.test/device_test.fidl

// 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.test;

using fuchsia.lowpan;
using zx;

const uint32 MAX_NEIGHBORS = 1024;

protocol DeviceTest {
    /// Resets this network interface, returning
    /// all volatile state to default values. Any
    /// information stored in non-volatile memory
    /// is preserved. If the interface was attached
    /// to a network, this method will cause the
    /// interface to detach. In that case, once the
    /// interface has finished initialization the
    /// interface will attempt to reattach to the
    /// previous network.
    Reset() -> ();

    /// Returns the version string describing the firmware/stack
    /// version that is in use.
    GetNcpVersion() -> (string:256 version);

    /// Returns the current RSSI measured by the radio.
    GetCurrentRssi() -> (int32 rssi);

    /// Returns the factory-assigned static MAC address.
    GetFactoryMacAddress() -> (bytes:8 address);

    /// Returns the currently used MAC address, which can
    /// differ from the static factory-assigned MAC address.
    GetCurrentMacAddress() -> (bytes:8 address);

    /// Returns the current channel index for the radio.
    GetCurrentChannel() -> (fuchsia.lowpan.ChannelIndex channel_index);

    /// Returns the partition ID of the currently associated
    /// network partition.
    GetPartitionId() -> (uint32 pid);

    GetThreadRloc16() -> (uint16 rloc);

    GetThreadRouterId() -> (uint8 router_id);

    /// Updates the address filter settings.
    ///
    /// Responds once the filter settings have taken effect.
    ReplaceMacAddressFilterSettings(MacAddressFilterSettings settings) -> ();

    /// Returns the current address filter settings.
    GetMacAddressFilterSettings() -> (MacAddressFilterSettings settings);

    /// Returns a snapshot of the current neighbor table.
    GetNeighborTable() -> (vector<NeighborInfo>:MAX_NEIGHBORS neighbor_table);
};

/// LoWPAN MAC address
alias MacAddress = bytes:8;

/// An item in the MAC filter list.
table MacAddressFilterItem {
    /// The MAC address of the item. This field is required.
    1: MacAddress mac_address;

    /// Replacement RSSI value for packets received from this address.
    ///
    /// This field is ignored unless the mode is set to `MacAddressFilterMode::ALLOW`.
    ///
    /// This value is substituted for all received packets. This can affect
    /// what the mesh topology ultimately looks like.
    2: int8 rssi;
};

/// Maximum number of addresses that can be in the address filter list.
const uint16 MAX_FILTERED = 100;

table MacAddressFilterSettings {
    /// Address filter mode.
    ///
    /// This field is required. If this field is absent when passed to
    /// `ReplaceMacAddressFilterSettings`, the channel will be closed with
    /// the epitaph `ZX_ERR_INVALID_ARGUMENT`.
    1: MacAddressFilterMode mode;

    /// Addresses to be filtered.
    ///
    /// If this field is absent it is assumed to be empty.
    2: vector<MacAddressFilterItem>:MAX_FILTERED items;
};

/// Describes the address filtering mode of the interface.
enum MacAddressFilterMode : int32 {
    /// Address filtering is disabled. All packets that are
    /// received are processed normally.
    DISABLED = 0;

    /// Only packets that have addresses matching an address
    /// in the filter list will be allowed to be processed.
    /// All other packets are dropped as if they were never
    /// received.
    ///
    /// Additionally, if an RSSI value was associated
    /// with an item, that value will be substituted for internal
    /// routing considerations.
    ALLOW = 1;

    /// All packets from addresses in the filter list will be
    /// dropped.
    DENY = 2;
};

/// Neighbor Table Entry
///
/// See also: https://github.com/openthread/wpantund/blob/8db2a71c9597e08949dfc38d8c10f830e3de565c/third_party/openthread/src/ncp/spinel.h#L2356-L2373
table NeighborInfo {
    /// The MAC address of the neighbor.
    ///
    /// Note that this is the only field guaranteed to be present.
    1: MacAddress mac_address;

    /// 802.15.4 short address of neighbor.
    ///
    /// On Thread networks, this is also the RLOC16.
    2: uint16 short_address;

    /// The age of this entry in the neighbor table.
    ///
    /// Roughly (+/- 1sec) describes how long this device has been a neighbor.
    ///
    3: zx.duration age;

    /// True if this neighbor is considered a child and is thus
    /// entirely dependent on this device for routing.
    ///
    /// If absent, assumed to be false.
    4: bool is_child;

    /// The number of link (non-management) frames received from this neighbor.
    5: uint32 link_frame_count;

    /// The number of management (MLE, etc) frames received from this neighbor.
    6: uint32 mgmt_frame_count;

    /// RSSI of the most recent packet received from the neighbor.
    7: int32 last_rssi_in;

    /// Average/typical RSSI of packets received from the neighbor.
    8: int8 avg_rssi_in;

    /// LQI of the most recent packet received from the neighbor.
    ///
    /// Value is between 1 and 255, with 1 being the worst possible
    /// link quality (any worse and it would not have been decoded)
    /// and 255 being perfect reception. All values in between
    /// are a roughly linear (but not well defined) extrapolation
    /// between these two extremes.
    ///
    /// Zero values must not be encoded, but if encountered should be
    /// interpreted as if the LQI field were absent.
    ///
    /// In 802.15.4 networks, LQI is typically determined by the number of
    /// "chip errors" when decoding the packets.
    9: uint8 lqi_in;

    /// Thread Mode TLV. Only present on Thread networks.
    ///
    /// Defined by section 4.5.2 of the Thread 1.1.1 specification ("Mode TLV").
    10: uint8 thread_mode;
};