linux-x86_64/lib/emulated_bluetooth_device.proto

// Copyright (C) 2022 The Android Open Source Project
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

// An EmulatedBluetoothService represents a bluetooth Gatt device.
// The android emulator will connect to this service to read/write and
// observe characteristics if the emulator establishes a connection
// to this device.
//
// You will need to implement this service and register the endpoint with
// the emulator to make this device discoverable.
syntax = "proto3";

option java_multiple_files = true;
option java_package = "com.android.emulator.bluetooth";

package android.emulation.bluetooth;
import "grpc_endpoint_description.proto";
import "google/protobuf/empty.proto";

// 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.
service GattDeviceService {
    // A remote client has requested to read a local characteristic.
    //
    // Return the current observed value.
    rpc OnCharacteristicReadRequest(CharacteristicValueRequest)
            returns (CharacteristicValueResponse);

    // A remote client has requested to write to a local characteristic.
    //
    // Return the current observed value.
    rpc OnCharacteristicWriteRequest(CharacteristicValueRequest)
            returns (CharacteristicValueResponse);

    // Listens for notifications from the emulated device, the device should
    // write to the stream with a response when a change has occurred.
    rpc OnCharacteristicObserveRequest(CharacteristicValueRequest)
            returns (stream CharacteristicValueResponse);

    // A remote device has been connected or disconnected.
    rpc OnConnectionStateChange(ConnectionStateChange)
            returns (google.protobuf.Empty);
}

// 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.
message CallbackIdentifier {
    string identity = 1;
}

// A Device Identifier is used to uniquely identify an emulated
// bluetooth device on the rootcanal mesh.
message DeviceIdentifier {
    // A string that uniquely identifies this device on the
    // rootcanal mesh.
    string address = 1;
}

message ConnectionStateChange {
    enum ConnectionState {
        CONNECTION_STATE_UNDEFINED = 0;
        // The profile is in disconnected state
        CONNECTION_STATE_DISCONNECTED = 1;
        // The profile is in connected state
        CONNECTION_STATE_CONNECTED = 2;
    }

    // The identity of the device is receiving the state change.
    CallbackIdentifier callback_device_id = 1;

    // The identity of the device that is changing state.
    DeviceIdentifier from_device = 2;

    // The current state of the device
    ConnectionState new_state = 3;
}

// 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.
message Uuid {
    oneof short_or_long {
        // The shortened bluetooth uuid, either 16/32 bit.
        uint32 id = 1;

        // The first 8 hex digits of the guid, if you are using
        // 128 bit guid.  These are the least significant bits.
        uint64 lsb = 2;
    }

    // The next 8 hex digits of the guid, ignored if the lsb value is not set.
    // These are the most significant bits.
    int64 msb = 3;
}

// Data exchanged to read/write bluetooth characteristics
message CharacteristicValueRequest {
    // 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.
    CallbackIdentifier callback_device_id = 1;

    // The identity of the device that is making this request.
    DeviceIdentifier from_device = 2;

    // 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.
    Uuid callback_id = 3;

    // The raw data in the request. The application developer will
    // need to parse the data and handle it properly.
    bytes data = 4;
}

// Data exchanged to read/write bluetooth characteristics
message CharacteristicValueResponse {
    enum GattStatus {
        GATT_STATUS_UNSPECIFIED = 0;
        // A GATT operation completed successfully
        GATT_STATUS_SUCCESS = 1;
        // A GATT operation failed
        GATT_STATUS_FAILURE = 2;
    }

    // The status of the request to be sent to the remote devices
    GattStatus status = 1;

    // The data of interest, this should contain the raw data according
    // to the bluetooth specification for the requested charactersic uuid.
    bytes data = 2;
}

message GattCharacteristic {
    // The Characteristic Properties bit field determines how the Characteristic
    // Value can be used, or how the characteristic descriptors can be accessed.

    // Properties Value Description.
    enum Properties {
        PROPERTY_UNSPECIFIED = 0;

        // If set, permits broadcasts of the Characteristic
        // Value using Server Characteristic Configuration Descriptor. If set,
        // the Server Characteristic Configuration Descriptor shall exist.
        PROPERTY_BROADCAST = 0x01;

        // If set, permits reads of the Characteristic Value using procedures
        // defined in Section 4.8
        PROPERTY_READ = 0x02;

        // If set, permit writes of the Characteristic Value without response
        // using procedures defined in Section 4.9.1.
        PROPERTY_WRITE_NO_RESPONSE = 0x04;

        // If set, permits writes of the Characteristic Value with response
        // using procedures defined in Section 4.9.3 or Section 4.9.4.
        PROPERTY_WRITE = 0x08;

        // 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_NOTIFY = 0x10;

        // 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_INDICATE = 0x20;

        // If set, permits signed writes to the Characteristic Value using the
        // procedure defined in Section 4.9.2.
        PROPERTY_SIGNED_WRITE = 0x40;

        // 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
        PROPERTY_EXTENDED_PROPS = 0x80;
    }

    // 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.
    enum Permissions {
        PERMISSION_UNSPECIFIED = 0;

        //  Characteristic read permission
        PERMISSION_READ = 0x01;

        // Characteristic permission: Allow encrypted read operations
        PERMISSION_READ_ENCRYPTED = 0x02;

        // Characteristic permission: Allow reading with person-in-the-middle
        // protection
        PERMISSION_READ_ENCRYPTED_MITM = 0x04;

        // Characteristic write permission
        PERMISSION_WRITE = 0x10;

        // Characteristic permission: Allow encrypted writes
        PERMISSION_WRITE_ENCRYPTED = 0x20;

        // Characteristic permission: Allow encrypted writes with
        // person-in-the-middle protection
        PERMISSION_WRITE_ENCRYPTED_MITM = 0x40;

        // Characteristic permission: Allow signed write operations
        PERMISSION_WRITE_SIGNED = 0x80;

        // Characteristic permission: Allow signed write operations with
        // person-in-the-middle protection
        PERMISSION_WRITE_SIGNED_MITM = 0x100;
    }

    // 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."
    Uuid uuid = 1;

    // Contains a mask of the properties described in the properties enum.
    // Property definitions are *ONLY* required during device registration.
    uint32 properties = 2;

    // Contains a mask of the permissions described in the permissions enum.
    // Permission definitions are *ONLY* required during device registration.
    uint32 permissions = 3;

    // 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.
    Uuid callback_id = 4;
}

// A Gatt service definition.
message GattService {
    enum ServiceType {
        SERVICE_TYPE_UNSPECIFIED = 0;

        // Primary service
        SERVICE_TYPE_PRIMARY = 0x01;

        // Secondary service (included by primary services)
        SERVICE_TYPE_SECONDARY = 0x02;
    }

    // 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.
    Uuid uuid = 1;
    ServiceType service_type = 2;
    repeated GattCharacteristic characteristics = 3;
}

// 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/
message GattProfile {
    repeated GattService services = 1;
}

// 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.
message Advertisement {
    // 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.
    string device_name = 1;

    enum ConnectionMode {
        // None specified, defaults to undirected
        CONNECTION_MODE_UNSPECIFIED = 0;
        // Non-connectable, as per section 3.C.9.3.2
        CONNECTION_MODE_NON_CONNECTABLE = 1;
        // Directed-connectable, as per section 3.C.9.3.3
        CONNECTION_MODE_DIRECTED = 2;
        // Undirected-connectable, as per section 3.C.9.3.4
        CONNECTION_MODE_UNDIRECTED = 3;
    }

    //  Whether the advertisement type should be connectable or non-connectable.
    ConnectionMode connection_mode = 2;

    enum DiscoveryMode {
        // None specified, defaults to general discoverable
        DISCOVERY_MODE_UNSPECIFIED = 0;
        // Non-discoverable, as per section 3.C.9.2.2).
        DISCOVERY_MODE_NON_DISCOVERABLE = 1;
        // Limited-discoverable, as per section 3.C.9.2.3).
        DISCOVERY_MODE_LIMITED = 2;
        // General-discoverable, as per section 3.C.9.2.4).
        DISCOVERY_MODE_GENERAL = 3;
    }

    DiscoveryMode discovery_mode = 3;
}

message GattDevice {
    // 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.
    android.emulation.remote.Endpoint endpoint = 1;

    // How this device will be advertised.
    Advertisement advertisement = 2;

    // The bluetooth profile that is made available.
    GattProfile profile = 3;
}