Google is committed to advancing racial equity for Black communities. See how.

fuchsia.bluetooth.gatt2

PROTOCOLS

CharacteristicNotifier

Defined in fuchsia.bluetooth.gatt2/client.fidl

Listens to characteristic notifications & indications.

OnNotification

Called when a characteristic value notification or indication is received from the server.

  • request value the value of the updated characteristic.
  • response An empty response should be sent immediately as an acknowledgement that the notification was received (for flow control).

Request

NameType
value ReadValue

Response

NameType

Client

Defined in fuchsia.bluetooth.gatt2/client.fidl

ConnectToService

Connects the RemoteService with the given identifier.

service will be closed on error, with an epitaph that provides a reason.

  • error Returns a ZX_ERR_BAD_HANDLE if handle is invalid.
  • error Returns a ZX_ERR_CONNECTION_RESET if the service is removed.
  • error Returns a ZX_ERR_NOT_CONNECTED if the peer disconnects.

Request

NameType
handle Handle
service request<RemoteService>

WatchServices

Enumerates services found on the peer that this Client represents. Results can be restricted by specifying a list of UUIDs in uuids. On the initial request, a complete snapshot will be returned. Subsequent calls receive a response only when one or more services have been added, modified, or removed from the entries reported since the most recent call.

To further interact with services, clients must obtain a RemoteService protocol by calling ConnectToService().

  • request uuids the UUID allowlist. If empty, all services will be returned.
  • response updated the services that have been added or modified since WatchServices() was last called. The returned ServiceInfo tables will contain only basic information about each service and the characteristics and includes fields will be null.
  • response removed the handles of the services that have been removed since the last call to WatchServices().

Request

NameType
uuids vector<fuchsia.bluetooth/Uuid>

Response

NameType
updated vector<ServiceInfo>[65535]
removed vector<Handle>[65535]

RemoteService

Defined in fuchsia.bluetooth.gatt2/client.fidl

DiscoverCharacteristics

Returns the characteristics and characteristic descriptors that belong to this service.

Request

NameType

Response

NameType
characteristics vector<Characteristic>[32767]

ReadByType

Reads characteristics and descriptors with the given uuid.

This method is useful for reading values before discovery has completed, thereby reducing latency.

  • request uuid The UUID of the characteristics/descriptors to read.
  • response results The results of the read. May be empty if no matching values are read. If reading a value results in a permission error, the handle and error will be included.
  • error Returns INVALID_PARAMETERS if uuid refers to an internally reserved descriptor type (e.g. the Client Characteristic Configuration descriptor).
  • error Returns TOO_MANY_RESULTS if more results were read than can fit in a FIDL response. Consider reading characteristics/descriptors individually after performing discovery.
  • error Returns FAILURE if the server returns an error not specific to a single result.

Request

NameType
uuid fuchsia.bluetooth/Uuid

Response

NameType
result RemoteService_ReadByType_Result

ReadCharacteristic

Reads the value of a characteristic with the given handle.

  • request handle The characteristic handle to read.
  • request options Options that apply to the read.
  • response value The value of the characteristic.
  • error Returns INVALID_HANDLE if handle is invalid.
  • error Returns INVALID_PARAMETERS if options is invalid.
  • error Returns READ_NOT_PERMITTED or INSUFFICIENT_* if the server rejects the read request.
  • error Returns FAILURE if the server returns an error.

Request

NameType
handle Handle
options ReadOptions

Response

NameType
result RemoteService_ReadCharacteristic_Result

ReadDescriptor

Reads the value of the characteristic descriptor with handle and returns it in the reply.

  • request handle The descriptor handle to read.
  • request options Options that apply to the read.
  • response value The value of the descriptor.
  • error Returns INVALID_HANDLE if handle is invalid.
  • error Returns INVALID_PARAMETERS if options is invalid.
  • error Returns READ_NOT_PERMITTED or INSUFFICIENT_* if the server rejects the read request.
  • error Returns FAILURE if the server returns an error.

Request

NameType
handle Handle
options ReadOptions

Response

NameType
result RemoteService_ReadDescriptor_Result

RegisterCharacteristicNotifier

Subscribe to notifications & indications from the characteristic with the given handle.

Either notifications or indications will be enabled depending on characteristic properties. Indications will be preferred if they are supported. This operation fails if the characteristic does not have the "notify" or "indicate" property.

A write request will be issued to configure the characteristic for notifications/indications if it contains a Client Characteristic Configuration descriptor. This method fails if an error occurs while writing to the descriptor.

On success, the notifier protocol can be used to be notified when the peer sends a notification or indication. Indications are automatically confirmed. When the protocol is dropped, the subscription may end if no other local client is receiving notifications.

  • request handle the characteristic handle.
  • request notifier the protocol used for notifications.
  • response An empty response will be sent immediately if registration succeeds.
  • error Returns a FAILURE if the characteristic does not support notifications or indications.
  • error Returns a INVALID_HANDLE if handle is invalid.
  • error Returns a WRITE_NOT_PERMITTED or INSUFFICIENT_*for a descriptor write error.

Request

NameType
handle Handle
notifier CharacteristicNotifier

Response

NameType
result RemoteService_RegisterCharacteristicNotifier_Result

WriteCharacteristic

Writes value to the characteristic with handle using the provided options.

It is not recommended to send additional writes while a write is already in progress (the server may receive simultaneous writes in any order).

  • request handle The characteristic to be written to.
  • request value The value to be written.
  • request options Options that apply to the write.
  • response An empty response will be sent when a success response is received from the server (or immediately if options.with_response is false)
  • error Returns INVALID_HANDLE if handle is invalid.
  • error Returns INVALID_PARAMETERS if options is invalid.
  • error Returns WRITE_NOT_PERMITTED or INSUFFICIENT_*if the server rejects the write request with a reason.
  • error Returns FAILURE if the server returns an error.

Request

NameType
handle Handle
value vector<uint8>[512]
options WriteOptions

Response

NameType
result RemoteService_WriteCharacteristic_Result

WriteDescriptor

Writes value to the characteristic descriptor with handle. It is not recommended to send additional writes while a write is already in progress (the server may receive simultaneous writes in any order).

  • request handle The descriptor handle to written to.
  • request value The value to be written.
  • request options Options that apply to the write.
  • response An empty response will be sent when a success response is received from the server (or immediately if options.with_response is false)
  • error Returns INVALID_HANDLE if handle is invalid or refers to an internally reserved descriptor type (e.g. the Client Characteristic Configuration descriptor).
  • error Returns INVALID_PARAMETERS if options is invalid.
  • error Returns WRITE_NOT_PERMITTED or INSUFFICIENT_* if the server rejects the write with a reason.
  • error Returns FAILURE if the server returns an error.

Request

NameType
handle Handle
value vector<uint8>[512]
options WriteOptions

Response

NameType
result RemoteService_WriteDescriptor_Result

STRUCTS

Handle

Defined in fuchsia.bluetooth.gatt2/types.fidl

NameTypeDescriptionDefault
value uint64 No default

RemoteService_ReadByType_Response

Defined in fuchsia.bluetooth.gatt2/client.fidl

NameTypeDescriptionDefault
results vector<ReadByTypeResult>[65535] No default

RemoteService_ReadCharacteristic_Response

Defined in fuchsia.bluetooth.gatt2/client.fidl

NameTypeDescriptionDefault
value ReadValue No default

RemoteService_ReadDescriptor_Response

Defined in fuchsia.bluetooth.gatt2/client.fidl

NameTypeDescriptionDefault
value ReadValue No default

RemoteService_RegisterCharacteristicNotifier_Response

Defined in fuchsia.bluetooth.gatt2/client.fidl

NameTypeDescriptionDefault

RemoteService_WriteCharacteristic_Response

Defined in fuchsia.bluetooth.gatt2/client.fidl

NameTypeDescriptionDefault

RemoteService_WriteDescriptor_Response

Defined in fuchsia.bluetooth.gatt2/client.fidl

NameTypeDescriptionDefault

ENUMS

Error

Type: uint32

Defined in fuchsia.bluetooth.gatt2/types.fidl

Errors that are returned by bluetooth.gatt2 methods.

NameValueDescription
FAILURE 1

A general error occurred that can not be classified as one of the more specific errors.

INVALID_RESPONSE 2

Indicates that the response received from the server was invalid.

TOO_MANY_RESULTS 3

Indicates that more results were read than can fit in a FIDL response. Consider reading attributes individually.

INSUFFICIENT_AUTHORIZATION 4

This attribute requires authorization, but the client is not authorized.

INSUFFICIENT_AUTHENTICATION 5

This attribute requires authentication, but the client is not authenticated.

INSUFFICIENT_ENCRYPTION_KEY_SIZE 6

This attribute requires a connection encrypted by a larger encryption key.

INSUFFICIENT_ENCRYPTION 7

This attribute requires encryption, but the connection is not encrypted.

READ_NOT_PERMITTED 8

This attribute is not readable.

WRITE_NOT_PERMITTED 9

This attribute is not writable.

INVALID_PARAMETERS 10

One or more of the parameters are invalid. See the parameter documentation.

INVALID_HANDLE 11

The attribute indicated by the handle is invalid. It may have been removed.

TABLES

AttributePermissions

Defined in fuchsia.bluetooth.gatt2/types.fidl

Specifies the access permissions for a specific attribute value.

OrdinalNameTypeDescription
1 read SecurityRequirements

Specifies whether or not an attribute has the read permission. If null, then the attribute value cannot be read. Otherwise, it can be read only if the permissions specified in the SecurityRequirements table are satisfied.

2 write SecurityRequirements

Specifies whether or not an attribute has the write permission. If null, then the attribute value cannot be written. Otherwise, it be written only if the permissions specified in the SecurityRequirements table are satisfied.

3 update SecurityRequirements

Specifies the security requirements for a client to subscribe to notifications or indications on a characteristic. A characteristic's support for notifications or indiciations is specified using the NOTIFY and INDICATE characteristic properties. If a local characteristic has one of these properties then this field can not be null. Otherwise, this field must be left as null.

This field is ignored for Descriptors.

Characteristic

Defined in fuchsia.bluetooth.gatt2/types.fidl

Represents a local or remote GATT characteristic.

OrdinalNameTypeDescription
1 handle Handle

Uniquely identifies this characteristic within a service. For local characteristics, the specified handle must be unique across all characteristic and descriptor handles in this service.

Always present. For local characteristics, this value is mandatory.

2 type fuchsia.bluetooth/Uuid

The UUID that identifies the type of this characteristic. Always present. Mandatory for local characteristics.

3 properties uint32

The characteristic properties bitfield. See CharacteristicPropertyBits above for possible values. Always present. Mandatory for local characteristics.

4 permissions AttributePermissions

The attribute permissions of this characteristic. For remote characteristics, this value will be null until the permissions are discovered via read and write requests.

For local characteristics, this value is mandatory.

5 descriptors vector<Descriptor>[65532]

The descriptors of this characteristic. Present only if non-empty. Optional for local characteristics.

Descriptor

Defined in fuchsia.bluetooth.gatt2/types.fidl

Represents a local or remote GATT characteristic descriptor.

OrdinalNameTypeDescription
1 handle Handle

Uniquely identifies this descriptor within a service. For local descriptors, the specified handle must be unique across all characteristic and descriptor handles in this service.

Always present. For local descriptors, this value is mandatory.

2 type fuchsia.bluetooth/Uuid

The UUID that identifies the type of this descriptor. Always present. For local descriptors, this value is mandatory.

3 permissions AttributePermissions

The attribute permissions of this descriptor. For remote descriptors, this value will be null until the permissions are discovered via read and write requests.

For local descriptors, this value is mandatory.

ReadByTypeResult

Defined in fuchsia.bluetooth.gatt2/client.fidl

A result returned by RemoteService.ReadByType.

OrdinalNameTypeDescription
1 handle Handle

Characteristic or descriptor handle.

2 value ReadValue

The value of the characteristic or descriptor, if it was read successfully.

3 error Error

Reason the value could not be read, if reading it resulted in an error.

ReadOptions

Defined in fuchsia.bluetooth.gatt2/types.fidl

Represents the supported options to read a characteristic or descriptor value from a server.

OrdinalNameTypeDescription
1 offset uint16

The byte to start the read at. Must be less than the length of the value. Optional. Default: 0

2 max_bytes uint16

The maximum number of bytes to read. Optional. Default: MAX_VALUE_LENGTH

3 read_complete_value bool

If true, read the complete value of the characteristic/descriptor. This may require many messages, and therefore cause high latency.

If false, read only the portion of the value that fits into a single message (at least 22 bytes). This will be low latency, and is useful for situations where a truncated value is acceptable. Possible truncation is indicated by the maybe_truncated parameter in the response. max_bytes will be ignored.

Optional. Default: true

ReadValue

Defined in fuchsia.bluetooth.gatt2/client.fidl

Wrapper around a possible truncated value recieved from the server.

OrdinalNameTypeDescription
1 handle Handle

Characteristic or descriptor handle. Always present.

2 value vector<uint8>[512]

The value of the characteristic or descriptor. Always present.

3 maybe_truncated bool

True if value might be truncated (the buffer was completely filled by the server). ReadCharacteristic or ReadDescriptor should be used to read the complete value. Always present.

SecurityRequirements

Defined in fuchsia.bluetooth.gatt2/types.fidl

Represents encryption, authentication, and authorization permissions that can be assigned to a specific access permission.

OrdinalNameTypeDescription
1 encryption_required bool

If true, the physical link must be encrypted to access this attribute.

2 authentication_required bool

If true, the physical link must be authenticated to access this attribute.

3 authorization_required bool

If true, the client needs to be authorized before accessing this attribute.

ServiceInfo

Defined in fuchsia.bluetooth.gatt2/types.fidl

Represents a local or remote GATT service.

OrdinalNameTypeDescription
1 handle Handle

Uniquely identifies this GATT service. Always present if this represents a remote service. Ignored if present for local services.

2 primary bool

Indicates whether this is a primary or secondary service. Always present for remote services. Optional for local services Default: true

3 type fuchsia.bluetooth/Uuid

The UUID that identifies the type of this service. Always present for remote services. Required for local services.

4 characteristics vector<Characteristic>[32767]

The characteristics of this service. Always present for remote services. Required for local services.

5 includes vector<Handle>[65535]

Handles of other services that are included by this service. Only present for remote services if non-empty. Optional for local services.

WriteOptions

Defined in fuchsia.bluetooth.gatt2/types.fidl

Represents the supported options to write a characteristic value to a server.

OrdinalNameTypeDescription
1 with_response bool

If true, wait for acknowledgement from the peer before returning.

If false, delivery will not be confirmed before returning. Writing without a response is only supported for short characteristics with the WRITE_WITHOUT_RESPONSE property. If the written value can't fit into a single message, a FAILURE error will be returned. To ensure that the value fits, it must be at most 20 bytes. offset must be 0.

Optional. Default: true

2 offset uint16

Request a write starting at the byte indicated. Optional. Default: 0

UNIONS

RemoteService_ReadByType_Result

Defined in fuchsia.bluetooth.gatt2/client.fidl

NameTypeDescription
response RemoteService_ReadByType_Response
err Error

RemoteService_ReadCharacteristic_Result

Defined in fuchsia.bluetooth.gatt2/client.fidl

NameTypeDescription
response RemoteService_ReadCharacteristic_Response
err Error

RemoteService_ReadDescriptor_Result

Defined in fuchsia.bluetooth.gatt2/client.fidl

NameTypeDescription
response RemoteService_ReadDescriptor_Response
err Error

RemoteService_RegisterCharacteristicNotifier_Result

Defined in fuchsia.bluetooth.gatt2/client.fidl

NameTypeDescription
response RemoteService_RegisterCharacteristicNotifier_Response
err Error

RemoteService_WriteCharacteristic_Result

Defined in fuchsia.bluetooth.gatt2/client.fidl

NameTypeDescription
response RemoteService_WriteCharacteristic_Response
err Error

RemoteService_WriteDescriptor_Result

Defined in fuchsia.bluetooth.gatt2/client.fidl

NameTypeDescription
response RemoteService_WriteDescriptor_Response
err Error

BITS

CharacteristicPropertyBits

Type: uint16

Defined in fuchsia.bluetooth.gatt2/types.fidl

Possible values for the characteristic properties bitfield. These specify the GATT procedures that are allowed for a particular characteristic.

NameValueDescription
BROADCAST 1
READ 2
WRITE_WITHOUT_RESPONSE 4
WRITE 8
NOTIFY 16
INDICATE 32
AUTHENTICATED_SIGNED_WRITES 64
RELIABLE_WRITE 256
WRITABLE_AUXILIARIES 512

CONSTANTS

NameValueTypeDescription
MAX_ATTRIBUTE_COUNT 65535 uint16
MAX_CHARACTERISTIC_COUNT 32767 uint16
MAX_DESCRIPTOR_COUNT 65532 uint16
MAX_SERVICE_COUNT MAX_ATTRIBUTE_COUNT uint16
MAX_VALUE_LENGTH 512 uint16