blob: 3cc72b1a55f4b7142fb23b1a7ccd08aca78c4433 [file] [log] [blame]
// Copyright 2018 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.le;
using fuchsia.bluetooth as bt;
using fuchsia.bluetooth.gatt;
type CentralError = strict enum {
/// The request was aborted.
/// The request is already in progress.
/// The provided parameters are invalid.
/// Advertising could not be initiated due to a hardware or system error.
/// Filter parameters for use during a scan. A discovered peer only matches the
/// filter if it satisfies all of the present filter parameters.
type Filter = table {
/// Filter based on advertised service UUID.
1: service_uuid bt.Uuid;
/// Filter based on service data containing the given UUID.
2: service_data_uuid bt.Uuid;
/// Filter based on a manufacturer identifier present in the manufacturer
/// data. If this filter parameter is set, then the advertising payload must
/// contain manufacturer specific data with the provided company identifier
/// to satisfy this filter. Manufacturer identifiers can be found at
3: manufacturer_id uint16;
/// Filter based on whether or not a device is connectable. For example, a
/// client that is only interested in peripherals that it can connect to can
/// set this to true. Similarly a client can scan only for broadcasters by
/// setting this to false.
4: connectable bool;
/// Filter results based on a portion of the advertised device name.
/// Substring matches are allowed.
5: name bt.DeviceName;
/// Filter results based on the path loss of the radio wave. A device that
/// matches this filter must satisfy the following:
/// 1. Radio transmission power level and received signal strength must be
/// available for the path loss calculation;
/// 2. The calculated path loss value must be less than, or equal to,
/// `max_path_loss`.
/// NOTE: This field is calculated using the RSSI and TX Power information
/// obtained from advertising and scan response data during a scan procedure.
/// It should NOT be confused with information for an active connection
/// obtained using the "Path Loss Reporting" feature.
6: max_path_loss int8;
/// Parameters used during a scan.
type ScanOptions = table {
/// List of filters for use during a scan. A peripheral that satisfies any
/// of these filters will be reported. At least 1 filter must be specified.
/// While not recommended, clients that require that all peripherals be
/// reported can specify an empty filter.
1: filters vector<Filter>:MAX;
/// Represents an active scan procedure. This protocol remains valid for the
/// duration of a scan and can be used to obtain scan results. The client can
/// close the protocol to stop scanning. If a scan is stopped by the system, the
/// protocol will be closed with the epitaph `CANCELED` to communicate this to
/// the client.
closed protocol ScanResultWatcher {
/// Returns a list of all LE peers that satisfy the filters indicated in
/// `ScanOptions`. The first response(s) will return matching discovered
/// peers immediately. Subsequent calls receive a response only when peers
/// have been scanned or updated since the last call. If a second call to
/// `Watch` is erronously sent while one call is already pending, the scan
/// will be canceled and the protocol will be closed.
/// - response `updated` Peers that were added or updated since the last
/// call to Watch().
strict Watch() -> (struct {
updated vector<Peer>:MAX;
closed protocol Central {
/// Scans for nearby LE peripherals and broadcasters. If the scan cannot be
/// initiated, then `result_watcher` will be closed with an epitaph.
/// A Central client is allowed to have only one active scan at a time.
/// Accordingly, only one Scan request can be outstanding at a time.
/// Additional calls to Scan will fail.
/// The lifetime of the scan session is tied to the `result_watcher`
/// protocol provided. The scan will be stopped if the channel is closed.
/// Once a scan is started, the [`fuchsia.bluetooth.le/ScanResultWatcher`]
/// can be used to watch for scan results.
/// + request `options` Options used to configure the scan session.
/// + request `result_watcher` Protocol that remains valid for the duration
/// of this scan session.
/// - response An empty response will be sent to acknowledge the scan has
/// stopped.
/// The following epitaphs may be sent by the server on error:
/// * error `ALREADY_EXISTS`: A scan is already in progress. Each `Central`
/// protocol is only allowed 1 active scan.
/// * error `INVALID_ARGS`: Some of the scan `options` are invalid. See the
/// `ScanOptions` documentation.
/// * error `INTERNAL`: An internal error occurred and a scan could not be
/// started.
strict Scan(resource struct {
options ScanOptions;
result_watcher server_end:ScanResultWatcher;
}) -> ();
/// Connect to the peer with the given identifier.
/// The requested [`fuchsia.bluetooth.le/Connection`] represents the
/// client's interest on the LE connection to the peer. Closing the channel
/// removes interest, but may not result in disconnection if another client
/// holds a valid [`fuchsia.bluetooth.le/Connection`] to the same peer.
/// The [`fuchsia.bluetooth.le/Connection`] `handle` will be closed by the
/// system if the connection to the peer is lost or an error occurs.
/// The following epitaphs may be sent by the server on error:
/// + `INVALID_ARGS`: Some of the parameters are invalid.
/// + `ALREADY_BOUND`: A Connection to the peer already exists for this Central. The existing
/// Connection should be used.
/// + `NOT_CONNECTED`: A connection could not be established.
/// + `CONNECTION_RESET`: The peer disconnected.
/// + request `id` Identifier of the peer to initiate a connection to.
/// + request `options` Options used to configure the connection.
/// + request `handle` Handle that remains valid for the duration of this
/// connection.
strict Connect(resource struct {
id bt.PeerId;
options ConnectionOptions;
handle server_end:Connection;
/// Returns the list of peripherals that are known to the system from previous scan, connection,
/// and/or bonding procedures. The results can be filtered based on service UUIDs that are known to
/// be present on the peripheral.
/// This method only returns peripherals (i.e. connectable devices).
strict GetPeripherals(struct {
service_uuids vector<bt.UuidString>:<MAX, optional>;
}) -> (struct {
peripherals vector<RemoteDevice>:MAX;
/// **This method is not implemented by the Fuchsia core stack- TODO(**
/// Returns information about a single peripheral that is known to the system from previous scan,
/// connection, and/or bonding procedures based on its unique identifier. Returns null if
/// `identifier` is not recognized.
strict GetPeripheral(struct {
identifier bt.PeerIdString;
}) -> (struct {
peripheral box<RemoteDevice>;
/// Initiates a scan session for nearby peripherals and broadcasters. Discovered devices will be
/// reported via CentralDelegate.OnDeviceDiscovered(). If a scan session is already in progress,
/// `filter` will replace the existing session's filter.
/// If `filter` is null or empty (i.e. none of its fields has been populated) then the delegate
/// will be notified for all discoverable devices that are found. This is not recommended; clients
/// should generally filter results by at least one of `filter.service_uuids`,
/// `filter.service_data`, and/or `filter.manufacturer_identifier`.
@deprecated("Use Scan instead")
strict StartScan(struct {
filter box<ScanFilter>;
}) -> (struct {
status bt.Status;
/// Terminate a previously started scan session.
strict StopScan();
/// Creates a connection to the peripheral device with the given identifier.
/// Returns the status of the operation in `status`.
/// On success, `gatt_client` will be bound and can be used for GATT client
/// role procedures. On failure, `gatt_client` will be closed and `status` will
/// indicate an error.
@deprecated("Use Connect instead")
strict ConnectPeripheral(resource struct {
identifier bt.PeerIdString;
options ConnectionOptions;
gatt_client server_end:fuchsia.bluetooth.gatt.Client;
}) -> (struct {
status bt.Status;
/// Disconnects this Central's connection to the peripheral with the given identifier.
strict DisconnectPeripheral(struct {
identifier bt.PeerIdString;
}) -> (struct {
status bt.Status;
/// Called when the scan state changes, e.g. when a scan session terminates due to a call to
/// Central.StopScan() or another unexpected condition.
strict -> OnScanStateChanged(struct {
scanning bool;
/// Called for each peripheral/broadcaster that is discovered during a scan session. `rssi`
/// contains the received signal strength of the advertising packet that generated this event, if
/// available.
strict -> OnDeviceDiscovered(struct {
device RemoteDevice;
/// Called when this Central's connection to a peripheral with the given identifier is terminated.
strict -> OnPeripheralDisconnected(struct {
identifier bt.PeerIdString;