Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# BluetoothEmulation

This domain allows configuring virtual Bluetooth devices to test the web-bluetooth API.

This CDP domain is experimental.

- Types

- Commands

- Events

## Types

Generally, you do not need to instantiate CDP types yourself. Instead, the API creates objects for you as return values from commands, and then you can use those objects as arguments to other commands.

class CentralState(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

  Indicates the various states of Central.

  ABSENT = 'absent'
  POWERED_OFF = 'powered-off'
  POWERED_ON = 'powered-on'

class GATTOperationType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

  Indicates the various types of GATT event.

  CONNECTION = 'connection'
  DISCOVERY = 'discovery'

class CharacteristicWriteType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

  Indicates the various types of characteristic write.

  WRITE_DEFAULT_DEPRECATED = 'write-default-deprecated'
  WRITE_WITH_RESPONSE = 'write-with-response'
  WRITE_WITHOUT_RESPONSE = 'write-without-response'

class CharacteristicOperationType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

  Indicates the various types of characteristic operation.

  READ = 'read'
  WRITE = 'write'
  SUBSCRIBE_TO_NOTIFICATIONS = 'subscribe-to-notifications'
  UNSUBSCRIBE_FROM_NOTIFICATIONS = 'unsubscribe-from-notifications'

class DescriptorOperationType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

  Indicates the various types of descriptor operation.

  READ = 'read'
  WRITE = 'write'

class ManufacturerData(key, data)

  Stores the manufacturer data

  key: `int`

    Company identifier https://bitbucket.org/bluetooth-SIG/public/src/main/assigned_numbers/company_identifiers/company_identifiers.yaml https://usb.org/developers

  data: `str`

    Manufacturer-specific data (Encoded as a base64 string when passed over JSON)

class ScanRecord(name=None, uuids=None, appearance=None, tx_power=None, manufacturer_data=None)

  Stores the byte data of the advertisement packet sent by a Bluetooth device.

  name: `Optional`[`str`] = None
  uuids: `Optional`[`List`[`str`]] = None
  appearance: `Optional`[`int`] = None

    Stores the external appearance description of the device.

  tx_power: `Optional`[`int`] = None

    Stores the transmission power of a broadcasting device.

  manufacturer_data: `Optional`[`List`[`ManufacturerData`]] = None

    Key is the company identifier and the value is an array of bytes of manufacturer specific data.

class ScanEntry(device_address, rssi, scan_record)

  Stores the advertisement packet information that is sent by a Bluetooth device.

  device_address: `str`
  rssi: `int`
  scan_record: `ScanRecord`

class CharacteristicProperties(broadcast=None, read=None, write_without_response=None, write=None, notify=None, indicate=None, authenticated_signed_writes=None, extended_properties=None)

  Describes the properties of a characteristic. This follows Bluetooth Core Specification BT 4.2 Vol 3 Part G 3.3.1. Characteristic Properties.

  broadcast: `Optional`[`bool`] = None
  read: `Optional`[`bool`] = None
  write_without_response: `Optional`[`bool`] = None
  write: `Optional`[`bool`] = None
  notify: `Optional`[`bool`] = None
  indicate: `Optional`[`bool`] = None
  authenticated_signed_writes: `Optional`[`bool`] = None
  extended_properties: `Optional`[`bool`] = None

## Commands

Each command is a generator function. The return type `Generator[x, y, z]` indicates that the generator yields arguments of type `x`, it must be resumed with an argument of type `y`, and it returns type `z`. In this library, types `x` and `y` are the same for all commands, and `z` is the return type you should pay attention to. For more information, see Getting Started: Commands.

add_characteristic(service_id, characteristic_uuid, properties)

  Adds a characteristic with `characteristicUuid` and `properties` to the service represented by `serviceId`.

  Parameters:

    - service_id (`str`) –

    - characteristic_uuid (`str`) –

    - properties (`CharacteristicProperties`) –

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `str`]

  Returns:

    An identifier that uniquely represents this characteristic.

add_descriptor(characteristic_id, descriptor_uuid)

  Adds a descriptor with `descriptorUuid` to the characteristic respresented by `characteristicId`.

  Parameters:

    - characteristic_id (`str`) –

    - descriptor_uuid (`str`) –

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `str`]

  Returns:

    An identifier that uniquely represents this descriptor.

add_service(address, service_uuid)

  Adds a service with `serviceUuid` to the peripheral with `address`.

  Parameters:

    - address (`str`) –

    - service_uuid (`str`) –

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `str`]

  Returns:

    An identifier that uniquely represents this service.

disable()

  Disable the BluetoothEmulation domain.

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

enable(state, le_supported)

  Enable the BluetoothEmulation domain.

  Parameters:

    - state (`CentralState`) – State of the simulated central.

    - le_supported (`bool`) – If the simulated central supports low-energy.

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

remove_characteristic(characteristic_id)

  Removes the characteristic respresented by `characteristicId` from the simulated central.

  Parameters:

    characteristic_id (`str`) –

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

remove_descriptor(descriptor_id)

  Removes the descriptor with `descriptorId` from the simulated central.

  Parameters:

    descriptor_id (`str`) –

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

remove_service(service_id)

  Removes the service respresented by `serviceId` from the simulated central.

  Parameters:

    service_id (`str`) –

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

set_simulated_central_state(state)

  Set the state of the simulated central.

  Parameters:

    state (`CentralState`) – State of the simulated central.

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

simulate_advertisement(entry)

  Simulates an advertisement packet described in `entry` being received by the central.

  Parameters:

    entry (`ScanEntry`) –

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

simulate_characteristic_operation_response(characteristic_id, type_, code, data=None)

  Simulates the response from the characteristic with `characteristicId` for a characteristic operation of `type`. The `code` value follows the Error Codes from Bluetooth Core Specification Vol 3 Part F 3.4.1.1 Error Response. The `data` is expected to exist when simulating a successful read operation response.

  Parameters:

    - characteristic_id (`str`) –

    - type –

    - code (`int`) –

    - data (`Optional`[`str`]) – (Optional)

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

simulate_descriptor_operation_response(descriptor_id, type_, code, data=None)

  Simulates the response from the descriptor with `descriptorId` for a descriptor operation of `type`. The `code` value follows the Error Codes from Bluetooth Core Specification Vol 3 Part F 3.4.1.1 Error Response. The `data` is expected to exist when simulating a successful read operation response.

  Parameters:

    - descriptor_id (`str`) –

    - type –

    - code (`int`) –

    - data (`Optional`[`str`]) – (Optional)

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

simulate_gatt_disconnection(address)

  Simulates a GATT disconnection from the peripheral with `address`.

  Parameters:

    address (`str`) –

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

simulate_gatt_operation_response(address, type_, code)

  Simulates the response code from the peripheral with `address` for a GATT operation of `type`. The `code` value follows the HCI Error Codes from Bluetooth Core Specification Vol 2 Part D 1.3 List Of Error Codes.

  Parameters:

    - address (`str`) –

    - type –

    - code (`int`) –

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

simulate_preconnected_peripheral(address, name, manufacturer_data, known_service_uuids)

  Simulates a peripheral with `address`, `name` and `knownServiceUuids` that has already been connected to the system.

  Parameters:

    - address (`str`) –

    - name (`str`) –

    - manufacturer_data (`List`[`ManufacturerData`]) –

    - known_service_uuids (`List`[`str`]) –

  Return type:

    `Generator`[`Dict`[`str`, `Any`], `Dict`[`str`, `Any`], `None`]

## Events

Generally, you do not need to instantiate CDP events yourself. Instead, the API creates events for you and then you use the event’s attributes.

class GattOperationReceived(address, type_)

  Event for when a GATT operation of `type` to the peripheral with `address` happened.

  address: `str`
  type_: `GATTOperationType`

class CharacteristicOperationReceived(characteristic_id, type_, data, write_type)

  Event for when a characteristic operation of `type` to the characteristic respresented by `characteristicId` happened. `data` and `writeType` is expected to exist when `type` is write.

  characteristic_id: `str`
  type_: `CharacteristicOperationType`
  data: `Optional`[`str`]
  write_type: `Optional`[`CharacteristicWriteType`]

class DescriptorOperationReceived(descriptor_id, type_, data)

  Event for when a descriptor operation of `type` to the descriptor respresented by `descriptorId` happened. `data` is expected to exist when `type` is write.

  descriptor_id: `str`
  type_: `DescriptorOperationType`
  data: `Optional`[`str`]