blob: 5e7dd60bb9057347dfb769ae4667e2f1e579759d [file] [log] [blame]
// 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;
});
};