package android.emulation.bluetooth
Get desktop application:
View/edit binary Protocol Buffers messages
An Emulated Bluetooth Service exposes a method to register an emulated bluetooth device.
Registers an emulated bluetooth device. The emulator will reach out to the emulated device to read/write and subscribe to properties. The following gRPC error codes can be returned: - FAILED_PRECONDITION (code 9): - root canal is not available on this device - unable to reach the endpoint for the GattDevice - INTERNAL (code 13) if there was an internal emulator failure. The device will not be discoverable in case of an error.
optional endpoint = 1
The endpoint where the emulated device can be found. This endpoint should provide an implementation of the GattDeviceService and must be reachable through the provided description.
optional advertisement = 2
How this device will be advertised.
optional profile = 3
The bluetooth profile that is made available.
message
emulated_bluetooth.proto:44optional callback_device_id = 1
The identity of the registered device. The emulator will provide this when executing a request for a CharacteristicValueRequest
You can provide your own GattDevice by implementing this service and registering it with the android emulator. The device will appear as a real bluetooth device, and you will receive callbacks when the bluetooth system wants to read, write or observe a characteristic.
rpc OnCharacteristicObserveRequest (, stream )
emulated_bluetooth_device.proto:52Listens for notifications from the emulated device, the device should write to the stream with a response when a change has occurred.
A remote client has requested to read a local characteristic. Return the current observed value.
A remote client has requested to write to a local characteristic. Return the current observed value.
A remote device has been connected or disconnected.
optional callback_device_id = 1
The identity of the device is receiving the state change.
optional from_device = 2
The identity of the device that is changing state.
ConnectionStateChange.ConnectionState new_state = 3
The current state of the device
The advertisement definition, this will be used to advertise the bluetooth device to android emulator. Every device that is registered will be discoverable by the emulator.
Used in:
string device_name = 1
The name of the device as an UTF-8 string. This is how the device will show up when android scans for devices. Only the first 29 bytes will show up on an in initial scan.
Advertisement.ConnectionMode connection_mode = 2
Whether the advertisement type should be connectable or non-connectable.
Advertisement.DiscoveryMode discovery_mode = 3
Used in:
CONNECTION_MODE_UNSPECIFIED = 0
None specified, defaults to undirected
CONNECTION_MODE_NON_CONNECTABLE = 1
Non-connectable, as per section 3.C.9.3.2
CONNECTION_MODE_DIRECTED = 2
Directed-connectable, as per section 3.C.9.3.3
CONNECTION_MODE_UNDIRECTED = 3
Undirected-connectable, as per section 3.C.9.3.4
Used in:
DISCOVERY_MODE_UNSPECIFIED = 0
None specified, defaults to general discoverable
DISCOVERY_MODE_NON_DISCOVERABLE = 1
Non-discoverable, as per section 3.C.9.2.2).
DISCOVERY_MODE_LIMITED = 2
Limited-discoverable, as per section 3.C.9.2.3).
DISCOVERY_MODE_GENERAL = 3
General-discoverable, as per section 3.C.9.2.4).
A callback identifier is used by the service to identify who should handle the any of the requests above. This is only relevant if you have a single endpoint that emulates multiple devices.
Used in: , ,
string identity = 1
Data exchanged to read/write bluetooth characteristics
Used as request type in: GattDeviceService.OnCharacteristicObserveRequest, GattDeviceService.OnCharacteristicReadRequest, GattDeviceService.OnCharacteristicWriteRequest
optional callback_device_id = 1
The identity of the device we are making this request to. The gRPC service for the emulated device must route the request to the actual device that emulates this identity. This is needed if you wish to emulate multipe devices on a single gRPC endpoint.
optional from_device = 2
The identity of the device that is making this request.
optional callback_id = 3
The specific callback id for which this request is. This is the callback_id used to register the given characteristic. If the value was not set it will be the uuid of the characteristic.
bytes data = 4
The raw data in the request. The application developer will need to parse the data and handle it properly.
Data exchanged to read/write bluetooth characteristics
Used as response type in: GattDeviceService.OnCharacteristicObserveRequest, GattDeviceService.OnCharacteristicReadRequest, GattDeviceService.OnCharacteristicWriteRequest
CharacteristicValueResponse.GattStatus status = 1
The status of the request to be sent to the remote devices
bytes data = 2
The data of interest, this should contain the raw data according to the bluetooth specification for the requested charactersic uuid.
Used in:
GATT_STATUS_UNSPECIFIED = 0
GATT_STATUS_SUCCESS = 1
A GATT operation completed successfully
GATT_STATUS_FAILURE = 2
A GATT operation failed
Used in:
CONNECTION_STATE_UNDEFINED = 0
CONNECTION_STATE_DISCONNECTED = 1
The profile is in disconnected state
CONNECTION_STATE_CONNECTED = 2
The profile is in connected state
A Device Identifier is used to uniquely identify an emulated bluetooth device on the rootcanal mesh.
Used in: ,
string address = 1
A string that uniquely identifies this device on the rootcanal mesh.
The Characteristic Properties bit field determines how the Characteristic Value can be used, or how the characteristic descriptors can be accessed.
Used in:
optional uuid = 1
The UUID identifying this characteristic, for a list of UUIDS: https://www.bluetooth.com/specifications/assigned-numbers/ Or (the much easier to use) XML definitions: https://github.com/sputnikdev/bluetooth-gatt-parser/tree/master/src/main/resources/gatt/characteristic For example the uuid=0x2A19 indicates the "The current charge level of a battery."
uint32 properties = 2
Contains a mask of the properties described in the properties enum. Property definitions are *ONLY* required during device registration.
uint32 permissions = 3
Contains a mask of the permissions described in the permissions enum. Permission definitions are *ONLY* required during device registration.
optional callback_id = 4
The callback_id that will be set whenever a bluetooth request comes in for this characteristic. Defaults to the value in uuid (field 1) if it is not set. You will only need to set this if the same uuid is defined multiple defines in your service, and can be used to disambiguate which characterisic is requested.
An attribute has a set of permission values associated with it. The permissions associated with an attribute specifies that it may be read and/or written. The permissions associated with the attribute specifies the security level required for read and/or write access, as well as notification and/or indication. The permissions of a given attribute are defined by a higher layer specification, and are not discoverable using the Attribute protocol.
PERMISSION_UNSPECIFIED = 0
PERMISSION_READ = 1
Characteristic read permission
PERMISSION_READ_ENCRYPTED = 2
Characteristic permission: Allow encrypted read operations
PERMISSION_READ_ENCRYPTED_MITM = 4
Characteristic permission: Allow reading with person-in-the-middle protection
PERMISSION_WRITE = 16
Characteristic write permission
PERMISSION_WRITE_ENCRYPTED = 32
Characteristic permission: Allow encrypted writes
PERMISSION_WRITE_ENCRYPTED_MITM = 64
Characteristic permission: Allow encrypted writes with person-in-the-middle protection
PERMISSION_WRITE_SIGNED = 128
Characteristic permission: Allow signed write operations
PERMISSION_WRITE_SIGNED_MITM = 256
Characteristic permission: Allow signed write operations with person-in-the-middle protection
Properties Value Description.
PROPERTY_UNSPECIFIED = 0
PROPERTY_BROADCAST = 1
If set, permits broadcasts of the Characteristic Value using Server Characteristic Configuration Descriptor. If set, the Server Characteristic Configuration Descriptor shall exist.
PROPERTY_READ = 2
If set, permits reads of the Characteristic Value using procedures defined in Section 4.8
PROPERTY_WRITE_NO_RESPONSE = 4
If set, permit writes of the Characteristic Value without response using procedures defined in Section 4.9.1.
PROPERTY_WRITE = 8
If set, permits writes of the Characteristic Value with response using procedures defined in Section 4.9.3 or Section 4.9.4.
PROPERTY_NOTIFY = 16
If set, permits notifications of a Characteristic Value without acknowledgment using the procedure defined in Section 4.10. If set, the Client Characteristic Configuration Descriptor shall exist.
PROPERTY_INDICATE = 32
If set, permits indications of a Characteristic Value with acknowledgment using the procedure defined in Section 4.11. If set, the Client Characteristic Configuration Descriptor shall exist.
PROPERTY_SIGNED_WRITE = 64
If set, permits signed writes to the Characteristic Value using the procedure defined in Section 4.9.2.
PROPERTY_EXTENDED_PROPS = 128
If set, additional characteristic properties are defined in the Characteristic Extended Properties Descriptor defined in Section 3.3.3.1. If set, the Characteristic Extended Properties Descriptor
A Gatt profile consists of a series of services that are offered to clients. Gatt profiles are well defined in the spec. You can find more information about the various profiles in the official specifications: https://www.bluetooth.com/specifications/specs/ A concrete example is the Heart Rate Monitor: https://www.bluetooth.com/specifications/specs/heart-rate-service-1-0/
Used in:
repeated services = 1
A Gatt service definition.
Used in:
optional uuid = 1
The uuid of this service. This can be a: 16, 32 or 128 bit uuid. This is usually a well defined UUID from the bluetooth specification. For example 0x180D indicates a heart rate monitor. See https://www.bluetooth.com/specifications/assigned-numbers/service-discovery/ for a list of well known uuid's.
GattService.ServiceType service_type = 2
repeated characteristics = 3
Used in:
SERVICE_TYPE_UNSPECIFIED = 0
SERVICE_TYPE_PRIMARY = 1
Primary service
SERVICE_TYPE_SECONDARY = 2
Secondary service (included by primary services)
A UUID is a universally unique identifier that is guaranteed to be unique across all space and all time. UUIDs can be independently created in a distributed fashion. No central registry of assigned UUIDs is required. A UUID is a 128-bit value. To reduce the burden of storing and transferring 128-bit UUID values, a range of UUID values has been pre-allocated for assignment to often-used, registered purposes. The first UUID in this pre-allocated range is known as the Bluetooth Base UUID and has the value 00000000-0000-1000-8000- 00805F9B34FB, from Assigned Numbers. UUID values in the pre-allocated range have aliases that are represented as 16-bit or 32-bit values. These aliases are often called 16-bit and 32-bit UUIDs, but each actually represents a 128-bit UUID value. The full 128-bit value of a 16-bit or 32-bit UUID may be computed by a simple arithmetic operation: 128_bit_value = 16_bit_value * 2^96 + Bluetooth_Base_UUID 128_bit_value = 32_bit_value * 2^96 + Bluetooth_Base_UUID A 16-bit UUID may be converted to 32-bit UUID format by zero-extending the 16-bit value to 32-bits. An equivalent method is to add the 16-bit UUID value to a zero-valued 32-bit UUID. Note: Two 16-bit UUIDs may be compared directly, as may two 32-bit UUIDs or two 128-bit UUIDs. If two UUIDs of differing sizes are to be compared, the shorter UUID must be converted to the longer UUID format before comparison.
Used in: , ,
oneof short_or_long
uint32 id = 1
The shortened bluetooth uuid, either 16/32 bit.
uint64 lsb = 2
The first 8 hex digits of the guid, if you are using 128 bit guid. These are the least significant bits.
int64 msb = 3
The next 8 hex digits of the guid, ignored if the lsb value is not set. These are the most significant bits.