fuchsia.bluetooth.sys

PROTOCOLS

ProcedureToken

Defined in fuchsia.bluetooth.sys/access.fidl

Represents an active procedure. The validity of a handle that supports this protocol is tied to the activity of the procedure that it is attached to. To elaborate:

1. Closing a token handle ends the procedure that it is attached to.
2. The system closes a token handle to communicate that a procedure was internally terminated.

Access

Defined in fuchsia.bluetooth.sys/access.fidl

Protocol that abstracts the operational modes and procedures defined in the Bluetooth Generic Access Profile (see Core Specification v5.1, Vol 3, Part C).

The procedures under this protocol apply to the system as a whole. The Bluetooth controller that plays an active role in these procedures can be managed using the HostWatcher protocol.

The procedures initiated by an Access protocol instance are terminated when the underlying channel is closed.

SetPairingDelegate

Assign a PairingDelegate to respond to drive pairing procedures. The delegate will be configured to use the provided I/O capabilities to determine the pairing method.

Only one PairingDelegate can be registered at a time. Closing a PairingDelegate aborts all on-going pairing procedures associated with a delegate and closes the PairingDelegate previously assigned for this Access instance.

• request input Bluetooth input capability
• request output Bluetooth output capability
• request delegate The client end of a PairingDelegate channel.

Request

Name	Type
input	InputCapability
output	OutputCapability
delegate	PairingDelegate

SetLocalName

Assign a local name for the Bluetooth system. This name will be visible to nearby peers when the system is in discoverable mode and during name discovery procedures.

• request name The complete local name to assign to the system.

Request

Name	Type
name	string

SetDeviceClass

Set the local device class that will be visible to nearby peers when the system is in discoverable mode.

• request device_class The device class to assign to the system.

Request

Name	Type
device_class	fuchsia.bluetooth/DeviceClass

MakeDiscoverable

Put the system into the "General Discoverable" mode on the BR/EDR transport. The active host will respond to general inquiry (by regularly entering the inquiry scan mode).

• request token ProcedureToken that will remain valid while a discoverable mode session is active. NOTE: The system may remain discoverable until all Access clients drop their tokens.

• error Reports Error.FAILED if inquiry mode cannot be entered.

Request

Name	Type
token	request<ProcedureToken>

Response

Name	Type
result	Access_MakeDiscoverable_Result

StartDiscovery

Start a general discovery procedure. All general discoverable BR/EDR, LE, and BR/EDR/LE devices will appear in the peer list, which can be observed by calling Access.WatchPeers.

• request token ProcedureToken that will remain valid while discovery is in progress. NOTE: The radio will continue performing discovery until all Access drop their tokens.

• error Reports Error.FAILED if discovery on either transport cannot be initiated.

Request

Name	Type
token	request<ProcedureToken>

Response

Name	Type
result	Access_StartDiscovery_Result

WatchPeers

Returns a list of all peers (connectable Bluetooth devices) known to the system. The first call results in a snapshot of all known peers to be sent immediately in the updated return paremeter. Subsequent calls receive a response only when one or more entries have been added, modified, or removed from the entries reported since the most recent call.

• response updated Peers that were added or updated since the last call to WatchPeers().
• response removed Ids of peers that were removed since the last call to WatchPeers().

Request

Name	Type

Response

Name	Type
updated	vector<Peer>
removed	vector<fuchsia.bluetooth/PeerId>

Connect

Initiate a connection to the peer with the given id. This method connects both BR/EDR and LE transports depending on the technologies that the peer is known to support.

• request id The id of the peer to connect.

• error Reports Error.FAILED if a connection to the peer cannot be initiated.
• error Reports Error.PEER_NOT_FOUND if id is not recognized.

Request

Name	Type
id	fuchsia.bluetooth/PeerId

Response

Name	Type
result	Access_Connect_Result

Disconnect

Disconnect all logical links to the peer with the given id. This includes LE and BR/EDR links that have been initiated using all Access and fuchsia.bluetooth.le protocol instances.

• request id The id of the peer to disconnect.

• error Reports Error.PEER_NOT_FOUND if id is not recognized.

Request

Name	Type
id	fuchsia.bluetooth/PeerId

Response

Name	Type
result	Access_Disconnect_Result

Forget

Removes all bonding information and disconnects any existing links with the peer with the given id.

• request id The id of the peer to forget.

• error Reports Error.PEER_NOT_FOUND if id is not recognized.

Request

Name	Type
id	fuchsia.bluetooth/PeerId

Response

Name	Type
result	Access_Forget_Result

Bootstrap

Defined in fuchsia.bluetooth.sys/bootstrap.fidl

Protocol used to initialize persistent core Bluetooth data. This protocol populates data that determine the identity of this device as perceived by other Bluetooth devices.

This protocol can be obtained only before the core Bluetooth host subsystem has generated its own identity. Once initial data is committed, this capability becomes unavailable and remains unavailable even if new Bluetooth adapters are attached.

Due to the privacy and bonding secrets involved, as well as the capability to make this device assume the Bluetooth identity of another device, this protocol should only be exposed to privileged components that can vouchsafe the origin of the data.

AddIdentities

Adds identities to be added to the unpopulated Bluetooth stack.

Repeated calls will append identities.

Request

Name	Type
identities	vector<Identity>

Commit

Writes all added bootstrapping data to the Bluetooth core stack. The server will close the channel regardless of success. Returns without error if successful and the stack will be considered initialized even if no bootstrapping data was written. Returns INVALID_HOST_IDENTITY if any host or bonded peer data is insufficient or inconsistent, with no effect (the client may retry by obtaining another protocol handle).

Request

Name	Type

Response

Name	Type
result	Bootstrap_Commit_Result

HostWatcher

Defined in fuchsia.bluetooth.sys/host_watcher.fidl

Protocol used to observe and manage the Bluetooth controllers on the system.

Watch

Obtain a list of all available Bluetooth controllers and their state. A response is sent only if this list has changed since the last time the client has sent this message.

Request

Name	Type

Response

Name	Type
hosts	vector<HostInfo>

SetActive

Designates the host with the given id as active. All Bluetooth procedures will be routed over this host. Any previously assigned active host will be disabled and all of its pending procedures will be terminated.

• error This can fail if a host with id was not found.

Request

Name	Type
id	fuchsia.bluetooth/Id

Response

Name	Type
result	HostWatcher_SetActive_Result

PairingDelegate

Defined in fuchsia.bluetooth.sys/pairing_delegate.fidl

OnPairingRequest

Called to initiate a pairing request. The delegate must respond with “true” or “false” to either accept or reject the pairing request. If the pairing method requires a passkey this is returned as well.

Any response from this method will be ignored if the OnPairingComplete event has already been sent for peer.

The displayed_passkey parameter should be displayed to the user if method equals PairingMethod.PASSKEY_DISPLAY or PairingMethod.PASSKEY_COMPARISON. Otherwise, this parameter has no meaning and should be ignored.

The entered_passkey parameter only has meaning if method equals PairingMethod.PASSKEY_ENTRY. It will be ignored otherwise.

Request

Name	Type
peer	Peer
method	PairingMethod
displayed_passkey	uint32

Response

Name	Type
accept	bool
entered_passkey	uint32

OnPairingComplete

Called if the pairing procedure for the device with the given ID is completed. This can be due to successful completion or an error (e.g. due to cancellation by the peer, a timeout, or disconnection) which is indicated by success.

Request

Name	Type
id	fuchsia.bluetooth/PeerId
success	bool

OnRemoteKeypress

Called to notify keypresses from the peer device during pairing using PairingMethod.PASSKEY_DISPLAY.

This event is used to provide key press events to the delegate for a responsive user experience as the user types the passkey on the peer device. This event will be called once for each key-press.

Request

Name	Type
id	fuchsia.bluetooth/PeerId
keypress	PairingKeypress

OnLocalKeypress

The delegate can send this event to notify the peer of local keypresses during pairing using PairingMethod.PASSKEY_ENTRY.

Response

Name	Type
id	fuchsia.bluetooth/PeerId
keypress	PairingKeypress

STRUCTS

Access_MakeDiscoverable_Response

generated

Name	Type	Description	Default

Access_StartDiscovery_Response

generated

Name	Type	Description	Default

Access_Connect_Response

generated

Name	Type	Description	Default

Access_Disconnect_Response

generated

Name	Type	Description	Default

Access_Forget_Response

generated

Name	Type	Description	Default

Bootstrap_Commit_Response

generated

Name	Type	Description	Default

HostWatcher_SetActive_Response

generated

Name	Type	Description	Default

SecurityProperties

Defined in fuchsia.bluetooth.sys/identity.fidl

Name	Type	Description	Default
authenticated	bool		No default
secure_connections	bool		No default
encryption_key_size	uint8		No default

Key

Defined in fuchsia.bluetooth.sys/identity.fidl

Represents a 128-bit secret key.

Name	Type	Description	Default
value	uint8[16]		No default

PeerKey

Defined in fuchsia.bluetooth.sys/identity.fidl

Represents a key that was received from a peer.

Name	Type	Description	Default
security	SecurityProperties	The security properties of this link under which this key was received.	No default
data	Key	The contents of the key.	No default

Ltk

Defined in fuchsia.bluetooth.sys/identity.fidl

Represents a LE Long-Term peer key used for link encyrption. The |ediv| and |rand| fields are zero if distributed using LE Secure Connections pairing.

Name	Type	Description	Default
key	PeerKey		No default
ediv	uint16		No default
rand	uint64		No default

LeConnectionParameters

Defined in fuchsia.bluetooth.sys/identity.fidl

The preferred LE connection parameters of the peer.

Name	Type	Description	Default
connection_interval	uint16		No default
connection_latency	uint16		No default
supervision_timeout	uint16		No default

ENUMS

Error

Type: uint32

Defined in fuchsia.bluetooth.sys/access.fidl

Name	Value	Description
FAILED	1	Operation could not be performed.
PEER_NOT_FOUND	2	The peer designated for the operation was not found.

BootstrapError

Type: uint32

Defined in fuchsia.bluetooth.sys/bootstrap.fidl

Name	Value	Description
INVALID_HOST_IDENTITY	1
WRITE_FAILURE	2

InputCapability

Type: uint32

Defined in fuchsia.bluetooth.sys/pairing_delegate.fidl

Input and Output Capabilities for pairing exchanges. See Volume 3, Part C, Table 5.3 and 5.4

Name	Value	Description
NONE	1
CONFIRMATION	2
KEYBOARD	3

OutputCapability

Type: uint32

Defined in fuchsia.bluetooth.sys/pairing_delegate.fidl

Name	Value	Description
NONE	1
DISPLAY	2

PairingMethod

Type: uint32

Defined in fuchsia.bluetooth.sys/pairing_delegate.fidl

Different types required by the Security Manager for pairing methods. Bluetooth SIG has different requirements for different device capabilities.

Name	Value	Description
CONSENT	1	The user is asked to accept or reject pairing.
PASSKEY_DISPLAY	2	The user is shown a 6-digit numerical passkey which they must enter on the peer device.
PASSKEY_COMPARISON	3	The user is shown a 6-digit numerical passkey which will also shown on the peer device. The user must compare the passkeys and accept the pairing if the passkeys match.
PASSKEY_ENTRY	4	The user is asked to enter a 6-digit passkey.

PairingKeypress

Type: uint32

Defined in fuchsia.bluetooth.sys/pairing_delegate.fidl

Name	Value	Description
DIGIT_ENTERED	1	The user has entered a single digit.
DIGIT_ERASED	2	The user has erased a single digit.
PASSKEY_CLEARED	3	The user has cleared the entire passkey.
PASSKEY_ENTERED	4	The user has finished entering the passkey.

TechnologyType

Type: uint32

Defined in fuchsia.bluetooth.sys/peer.fidl

Name	Value	Description
LOW_ENERGY	1
CLASSIC	2
DUAL_MODE	3

TABLES

HostInfo

Defined in fuchsia.bluetooth.sys/host_watcher.fidl

Information about a Bluetooth controller and its associated host-subsystem state.

Ordinal	Name	Type	Description
1	id	fuchsia.bluetooth/Id	Uniquely identifies a host on the current system. This field is always present.
2	technology	TechnologyType	The Bluetooth technologies that are supported by this adapter. This field is always present.
3	address	fuchsia.bluetooth/Address	The identity address. This field is always present.
4	active	bool	Indicates whether or not this is the active host. The system has one active host which handles all Bluetooth procedures.
5	local_name	string	The local name of this host. This is the name that is visible to other devices when this host is in the discoverable mode.
6	discoverable	bool	Whether or not the local adapter is currently discoverable over BR/EDR and LE physical channels.
7	discovering	bool	Whether or not device discovery is currently being performed.

LeData

Defined in fuchsia.bluetooth.sys/identity.fidl

Ordinal	Name	Type	Description
1	address	fuchsia.bluetooth/Address	The identity address of the peer.
2	connection_parameters	LeConnectionParameters	The peer's preferred connection parameters, if known.
3	services	vector<fuchsia.bluetooth/Uuid>	Known GATT service UUIDs.
4	ltk	Ltk	The LE long-term key. Present if the link was encrypted.
5	irk	PeerKey	Identity Resolving RemoteKey used to generate and resolve random addresses.
6	csrk	PeerKey	Connection Signature Resolving RemoteKey used for data signing without encryption.

BredrData

Defined in fuchsia.bluetooth.sys/identity.fidl

Ordinal	Name	Type	Description
1	address	fuchsia.bluetooth/Address	The public device address of the peer.
2	role_preference	fuchsia.bluetooth/ConnectionRole	The peer's preferred piconet role. This is determined by role switch procedures. Paging and connecting from a peer does not automatically set this flag. If absent, the peer has not expressed a preference.
3	services	vector<fuchsia.bluetooth/Uuid>	Known service UUIDs obtained from EIR data or SDP.
4	link_key	PeerKey	The semi-permanent BR/EDR key. Present if link was paired with Secure Simple Pairing or stronger.

BondingData

Defined in fuchsia.bluetooth.sys/identity.fidl

Represents the bonding data for a single peer.

Ordinal	Name	Type	Description
1	identifier	fuchsia.bluetooth/PeerId	The identifier that uniquely identifies this peer.
2	local_address	fuchsia.bluetooth/Address	The local Bluetooth identity address that this bond is associated with.
3	name	string	The name of the peer, if known.
4	le	LeData	Bonding data that is present when this peer is paired on the LE transport.
5	bredr	BredrData	Bonding data that is present when this peer is paired on the BR/EDR transport.

HostData

Defined in fuchsia.bluetooth.sys/identity.fidl

Represents persistent local host data.

Ordinal	Name	Type	Description
1	irk	LocalKey	The local Identity Resolving Key used by a bt-host device to generate Resolvable Private Addresses when privacy is enabled. May be absent for hosts that do not use LE privacy, or that only use Non-Resolvable Private Addresses. NOTE: This key is distributed to LE peers during pairing procedures. The client must take care to assign an IRK that consistent with the local bt-host identity.

Identity

Defined in fuchsia.bluetooth.sys/identity.fidl

Represents the persistent configuration of a single host-subsystem instance. This is used for identity presentation (inquiry, inquiry response, and advertisement) and for bonding secrets recall (encrypting link data to peers associated with this identity).

Each BR/EDR BD_ADDR and Low Energy public identity address used to bond should have its own Identity instance containing corresponding peers.

Each Identity instance that supports LE privacy should have an Identity Resolving Key (IRK) that is consistent with that distributed to its bonded peers.

Ordinal	Name	Type	Description
1	host	HostData
2	bonds	vector<BondingData>	All bonds that use a public identity address must contain the same local address.

Peer

Defined in fuchsia.bluetooth.sys/peer.fidl

Represents a remote BR/EDR, LE, or dual-mode BR/EDR/LE peer.

Ordinal	Name	Type	Description
1	id	fuchsia.bluetooth/PeerId	Uniquely identifies this peer on the current system. This field is always present.
2	address	fuchsia.bluetooth/Address	Bluetooth device address that identifies this peer. Clients should display this field to the user when |name| is not available. This field is always present. NOTE: Clients should use the identifier field to keep track of peers instead of their address.
3	technology	TechnologyType	The Bluetooth technologies that are supported by this peer. This field is always present.
4	connected	bool	Whether or not a BR/EDR and/or LE connection exists to this peer. This field is always present.
5	bonded	bool	Whether or not this peer is bonded. This field is always present.
6	name	string	The name of the peer, if known.
7	appearance	fuchsia.bluetooth/Appearance	The LE appearance property. Present if this peer supports LE and the appearance information was obtained over advertising and/or GATT.
8	device_class	fuchsia.bluetooth/DeviceClass	The class of device for this device, if known.
9	rssi	int8	The most recently obtained advertising signal strength for this peer. Present if known.
10	tx_power	int8	The most recently obtained transmission power for this peer. Present if known.
11	services	vector<fuchsia.bluetooth/Uuid>	The list of service UUIDs known to be available on this peer.

UNIONS

Access_MakeDiscoverable_Result

generated

Name	Type	Description
response	Access_MakeDiscoverable_Response
err	Error

Access_StartDiscovery_Result

generated

Name	Type	Description
response	Access_StartDiscovery_Response
err	Error

Access_Connect_Result

generated

Name	Type	Description
response	Access_Connect_Response
err	Error

Access_Disconnect_Result

generated

Name	Type	Description
response	Access_Disconnect_Response
err	Error

Access_Forget_Result

generated

Name	Type	Description
response	Access_Forget_Response
err	Error

Bootstrap_Commit_Result

generated

Name	Type	Description
response	Bootstrap_Commit_Response
err	BootstrapError

HostWatcher_SetActive_Result

generated

Name	Type	Description
response	HostWatcher_SetActive_Response
err	zx/status

TYPE ALIASES

Name	Value	Description
LocalKey	fuchsia.bluetooth.sys/Key	Represents a locally generated key that is distributed across one or more bonds.