sdk/fidl/fuchsia.bluetooth.test/hci_emulator.fidl - fuchsia - Git at Google

 // 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.
 enum EmulatorError {
     FAILED = 1;
     HCI_ALREADY_PUBLISHED = 2;
 };

 /// Error codes that are generated for functions that manipulate fake peers.
 enum EmulatorPeerError {
     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.
 enum HciConfig {
     /// 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.
 struct AclBufferSettings {
     /// ACL frame MTU in bytes.
     uint16 data_packet_length;

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

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

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

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

     /// 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: AclBufferSettings acl_buffer_settings;

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

 struct AdvertisingData {
     bytes:MAX_LEGACY_ADVERTISING_DATA_LENGTH data;
 };

 /// Parameters used to emulate a peer's behavior over the Low Energy transport.
 table LowEnergyPeerParameters {
     /// The LE identity address of the peer. This field is mandatory.
     1: bt.Address 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: bool connectable;

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

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

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

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

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

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

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

 enum ConnectionState {
     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(HciError status) -> ();

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

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

     /// Watch connection state changes using the
     /// [hanging get pattern](/docs/development/api/fidl.md#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() -> (vector<ConnectionState> states);
 };

 /// 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(EmulatorSettings settings) -> () 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(LowEnergyPeerParameters parameters, request<Peer> peer) -> () 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(BredrPeerParameters parameters, request<Peer> peer) -> () 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](//docs/development/api/fidl.md#delay-responses-using-hanging-gets))
     WatchControllerParameters() -> (ControllerParameters parameters);

     /// 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](//docs/development/api/fidl.md#delay-responses-using-hanging-gets))
     WatchLeScanStates() -> (vector<LeScanState> states);

     /// 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](//docs/development/api/fidl.md#delay-responses-using-hanging-gets))
     WatchLegacyAdvertisingStates() -> (vector<LegacyAdvertisingState> states);
 };
	// 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.
	enum EmulatorError {
	FAILED = 1;
	HCI_ALREADY_PUBLISHED = 2;
	};

	/// Error codes that are generated for functions that manipulate fake peers.
	enum EmulatorPeerError {
	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.
	enum HciConfig {
	/// 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.
	struct AclBufferSettings {
	/// ACL frame MTU in bytes.
	uint16 data_packet_length;

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

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

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

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

	/// 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: AclBufferSettings acl_buffer_settings;

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

	struct AdvertisingData {
	bytes:MAX_LEGACY_ADVERTISING_DATA_LENGTH data;
	};

	/// Parameters used to emulate a peer's behavior over the Low Energy transport.
	table LowEnergyPeerParameters {
	/// The LE identity address of the peer. This field is mandatory.
	1: bt.Address 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: bool connectable;

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

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

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

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

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

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

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

	enum ConnectionState {
	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(HciError status) -> ();

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

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

	/// Watch connection state changes using the
	/// [hanging get pattern](/docs/development/api/fidl.md#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() -> (vector<ConnectionState> states);
	};

	/// 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(EmulatorSettings settings) -> () 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(LowEnergyPeerParameters parameters, request<Peer> peer) -> () 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(BredrPeerParameters parameters, request<Peer> peer) -> () 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](//docs/development/api/fidl.md#delay-responses-using-hanging-gets))
	WatchControllerParameters() -> (ControllerParameters parameters);

	/// 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](//docs/development/api/fidl.md#delay-responses-using-hanging-gets))
	WatchLeScanStates() -> (vector<LeScanState> states);

	/// 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](//docs/development/api/fidl.md#delay-responses-using-hanging-gets))
	WatchLegacyAdvertisingStates() -> (vector<LegacyAdvertisingState> states);
	};