sdk/fidl/fuchsia.bluetooth.test/hci_emulator.fidl

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

using fuchsia.bluetooth as bt;
using fuchsia.bluetooth.bredr as bredr;

/// Error codes that can be generated for emulator-wide configurations.
type EmulatorError = strict enum {
    FAILED = 1;
    HCI_ALREADY_PUBLISHED = 2;
};

/// Error codes that are generated for functions that manipulate fake peers.
type EmulatorPeerError = strict enum {
    ADDRESS_REPEATED = 1;
    PARAMETERS_INVALID = 2;
    NOT_FOUND = 3;
};

// TODO(fxbug.dev/822): Add state structures for other LE and BR/EDR operations.
// TODO(armansito): Add ability to publish GATT services
// TODO(armansito): Add ability to publish SDP records
// TODO(armansito): Add ability to specify Bluetooth HCI version.

/// Pre-set HCI configurations.
type HciConfig = strict enum {
    /// Support both BR/EDR and LE in LMP features.
    DUAL_MODE = 1;

    /// Limits supported features and HCI commands to those that are required for LE only.
    LE_ONLY = 2;
};

/// The HCI ACL data flow-control parameters.
type AclBufferSettings = struct {
    /// ACL frame MTU in bytes.
    data_packet_length uint16;

    /// The maximum number of ACL frames that the controller can buffer.
    total_num_data_packets uint8;
};

/// Controller settings used by the emulator.
type EmulatorSettings = table {
    /// The `BD_ADDR` (BR/EDR) or LE Public Device Address. Defaults to "00:00:00:00:00:00".
    1: address bt.Address;

    /// Supported HCI command configuration. Defaults to "`DUAL_MODE`".
    2: hci_config HciConfig;

    /// True if the 5.0 extended advertising features are supported. Defaults to "false".
    3: extended_advertising bool;

    /// The ACL-U data buffer settings. Defaults to
    ///    data_packet_length: 1024
    ///    total_num_data_packets: 5
    /// IF `hci_config` is set to `DUAL_MODE`. Defaults to null otherwise.
    4: acl_buffer_settings AclBufferSettings;

    /// The LE-U ACL data buffer settings. Defaults to
    ///    data_packet_length: 251
    ///    total_num_data_packets: 5
    5: le_acl_buffer_settings AclBufferSettings;
};

type AdvertisingData = struct {
    data bytes:MAX_LEGACY_ADVERTISING_DATA_LENGTH;
};

/// Parameters used to emulate a peer's behavior over the Low Energy transport.
type LowEnergyPeerParameters = table {
    /// The LE identity address of the peer. This field is mandatory.
    1: address bt.Address;

    /// When present and true, the peer will send connectable advertisements and accept connection
    /// requests. The peer will ignore connection requests if not connectable.
    2: connectable bool;

    /// The advertising data contents. If not present, the advertising data sent by this peer will
    /// be empty.
    3: advertisement AdvertisingData;

    /// The scan response data contents. When present, the fake controller will generate scannable
    /// advertising packets and scan response events.
    4: scan_response AdvertisingData;
};

/// Maximum service records that can be advertised at once.
const MAX_PEER_SERVICES uint8 = 32;

/// Parameters used to emulate a peer's behavior over the BR/EDR transport.
type BredrPeerParameters = table {
    /// The BD_ADDR of the peer. This field is mandatory.
    1: address bt.Address;

    /// When present and true, the peer will accept connection requests. The peer will ignore
    /// connection requests if not connectable.
    2: connectable bool;

    /// The device class reported in the inquiry response for this peer during device discovery.
    3: device_class bt.DeviceClass;

    // The peer's services that will be discoverable via Service Discovery Protocol.
    4: service_definition vector<bredr.ServiceDefinition>:MAX_PEER_SERVICES;
};

type ConnectionState = strict enum {
    CONNECTED = 1;
    DISCONNECTED = 2;
};

/// Protocol used to drive the state of a fake peer device.
protocol Peer {
    /// Assign a HCI `status` for the controller to generate in response to connection requests.
    /// Applies to all successive HCI_Create_Connection and HCI_LE_Create_Connection commands. The
    /// procedure is acknowledged with an empty response.
    AssignConnectionStatus(struct {
        status HciError;
    }) -> ();

    /// Emulates a LE connection event. Does nothing if the peer is already connected. The
    /// `role` parameter determines the link layer connection role.
    EmulateLeConnectionComplete(struct {
        role bt.ConnectionRole;
    });

    /// Emulate disconnection. Does nothing if the peer is not connected.
    EmulateDisconnectionComplete();

    /// Watch connection state changes using the
    /// [hanging get pattern](https://fuchsia.dev/fuchsia-src/concepts/api/fidl#delay-responses-using-hanging-gets).
    /// Notifies the most recent controller connection state if there has been a change since the
    /// last time this method was called.
    ///
    /// Multiple calls to this method can be outstanding at a given time. All calls will resolve in
    /// a response as soon as there is a change to the connection state.
    WatchConnectionStates() -> (struct {
        states vector<ConnectionState>:MAX;
    });
};

/// Protocol used to emulate a Bluetooth controller that supports the standard Bluetooth HCI.
@discoverable
protocol HciEmulator {
    /// Publish a bt-hci device using the provided `settings`. Each HciEmulator instance can only
    /// manage a single bt-hci device. Returns Emulator.`HCI_ALREADY_PUBLISHED` if the device has
    /// already been published.
    Publish(struct {
        settings EmulatorSettings;
    }) -> (struct {}) error EmulatorError;

    /// Inserts a new LE peer device to be emulated by this controller. Once registered, the state
    /// of the fake peer can be driven and observed using the `peer` handle.
    ///
    /// A reply will be sent to acknowledge the creation of the fake peer. If a peer cannot be
    /// initialized (e.g. due to a missing required field in `parameters` or for containing an
    /// address that is already emulated) the `peer` handle will be closed and an error reply will
    /// be sent.
    ///
    /// The peer will appear in advertising reports and respond to requests according to its
    /// configuration as long as the `peer` channel is open. The emulator stops emulating this peer
    /// when the channel gets closed, which makes it no longer discoverable and not respond to any
    /// requests.
    AddLowEnergyPeer(resource struct {
        parameters LowEnergyPeerParameters;
        peer server_end:Peer;
    }) -> (struct {}) error EmulatorPeerError;

    /// Inserts a new BR/EDR peer device to be emulated by this controller. Once registered, the state
    /// of the fake peer can be driven and observed using the `peer` handle.
    ///
    /// A reply will be sent to acknowledge the creation of the fake peer. If a peer cannot be
    /// initialized (e.g. due to a missing required field in `parameters` or for containing an
    /// address that is already emulated) the `peer` handle will be closed and an error reply will
    /// be sent.
    ///
    /// The peer will appear in inquiry results and respond to requests according to its
    /// configuration as long as the `peer` channel is open. The emulator stops emulating this peer
    /// when the channel gets closed, which makes it no longer discoverable and not respond to any
    /// requests.
    AddBredrPeer(resource struct {
        parameters BredrPeerParameters;
        peer server_end:Peer;
    }) -> (struct {}) error EmulatorPeerError;

    /// Returns the current controller parameter state. If the parameters have not changed since the
    /// last time this message was received, then this method does not return until there is a
    /// change.
    /// (see [hanging get pattern](https://fuchsia.dev/fuchsia-src/concepts/api/fidl#delay-responses-using-hanging-gets))
    WatchControllerParameters() -> (struct {
        parameters ControllerParameters;
    });

    /// Returns the most recent set of state transitions for the link layer LE scan procedure. This
    /// method returns when there has been a state change since the last invocation of this method
    /// by this client.
    ///
    /// Multiple calls to this method can be outstanding at a given time. All calls will resolve in
    /// a response as soon as there is a change to the scan state.
    /// (see [hanging get pattern](https://fuchsia.dev/fuchsia-src/concepts/api/fidl#delay-responses-using-hanging-gets))
    WatchLeScanStates() -> (struct {
        states vector<LeScanState>:MAX;
    });

    /// Returns the most recent set of state transitions for the link layer LE legacy advertising
    /// procedure. This method returns when there has been a state change since the last invocation
    /// of this method by this client.
    ///
    /// Only one call to this method can be outstanding at a given time. The
    /// [`fuchsia.bluetooth.test/HciEmulator`] channel will be closed if a call received when one is
    /// already pending.
    /// (see [hanging get pattern](https://fuchsia.dev/fuchsia-src/concepts/api/fidl#delay-responses-using-hanging-gets))
    WatchLegacyAdvertisingStates() -> (struct {
        states vector<LegacyAdvertisingState>:MAX;
    });
};