Bluetooth: метод requestDevice()

Метод Bluetooth.requestDevice() интерфейса Bluetooth возвращает Promise, который выполняется с объектом BluetoothDevice, соответствующим указанным параметрам. Если интерфейс выбора отсутствует, метод возвращает первый устройство, соответствующее критериям.

options Необязательный

Объект, задающий параметры выбора подходящего устройства. Доступные параметры:

filters Необязательный

Массив объектов фильтров, указывающих свойства устройств, которые будут соответствовать. Для соответствия объекту фильтра устройство должно соответствовать всем значениям фильтра: все его указанные services, name, namePrefix, и так далее.

Каждый фильтр состоит из массива объектов со следующими свойствами:

services Необязательный

Массив значений, указывающих Bluetooth GATT (Профиль общих атрибутов) сервисы, которые должно поддерживать Bluetooth-устройство. Каждое значение может быть допустимым именем из списка назначенных сервисов GATT, например, 'battery_service' или 'blood_pressure'. Также можно передать полное UUID сервиса, например, '0000180F-0000-1000-8000-00805f9b34fb' или короткий 16-битный (0x180F) или 32-битный псевдоним. Обратите внимание, что это те же значения, которые можно передать в BluetoothUUID.getService().

name Необязательный

Строка, содержащая точное имя устройства для сопоставления.

namePrefix Необязательный

Строка, содержащая префикс имени для сопоставления. Все устройства, у которых имя начинается с этой строки, будут сопоставлены.

manufacturerData Необязательный

Массив объектов, соответствующих данным производителя в рекламных пакетах Bluetooth Low Energy (BLE). Каждый объект фильтра имеет следующие свойства:

companyIdentifier

Обязательное число, идентифицирующее производителя устройства. Идентификаторы компаний перечислены в спецификации Bluetooth Назначенные номера, раздел 7. Например, чтобы сопоставить устройства, произведённые компанией "Digianswer A/S" с присвоенным шестнадцатеричным номером 0x000C, укажите 12.

dataPrefix Необязательный

Префикс данных. Буфер, содержащий значения для сопоставления с начальными значениями рекламных данных производителя.

mask Необязательный

Это позволяет сопоставлять байты внутри данных производителя, маскируя некоторые байты данных сервиса dataPrefix.

serviceData Необязательный

Массив объектов, соответствующих данным сервиса в рекламных пакетах Bluetooth Low Energy (BLE). Каждый объект фильтра имеет следующие свойства:

service

Имя сервиса GATT, UUID сервиса или UUID в 16-битном или 32-битном формате. Это принимает те же значения, что и элементы массива services.

dataPrefix Необязательный

Префикс данных. Буфер, содержащий значения для сопоставления с начальными значениями рекламных данных сервиса.

mask Необязательный

Это позволяет сопоставлять байты внутри данных сервиса, маскируя некоторые байты данных сервиса dataPrefix.

exclusionFilters Необязательный

Массив объектов фильтров, указывающих характеристики устройств, которые будут исключены из сопоставления. Свойства элементов массива такие же, как у filters.

optionalServices Необязательный

Массив идентификаторов необязательных сервисов.

Идентификаторы принимают те же значения, что и элементы массива services (название сервиса GATT, UUID сервиса или UUID в коротких 16-битном или 32-битном формате).

optionalManufacturerData Необязательный

Необязательный массив целочисленных кодов производителей. Принимает те же значения, что и companyIdentifier.

Данные не используются для фильтрации устройств, но рекламные объявления, соответствующие заданному набору, всё равно передаются в advertisementreceived событиях. Это полезно, потому что позволяет коду указать интерес к данным, полученным от Bluetooth-устройств, без ограничения фильтра, определяющего, какие устройства будут представлены пользователю в запросе разрешения.

acceptAllDevices Необязательный

Булево значение, указывающее, что запрашиваемый скрипт может принять все Bluetooth-устройства. По умолчанию false.

Этот параметр подходит, когда устройства не анонсировали достаточно информации для полезной фильтрации. Когда acceptAllDevices установлено в true вы должны опустить все filters и exclusionFilters, и вы должны установить optionalServices, чтобы иметь возможность использовать возвращенное устройство.

После выбора пользователем устройства для сопряжения в текущем происхождении, оно может получить доступ только к сервисам, чьи UUID были перечислены в списке сервисов в любом элементе filters.services или в optionalServices. Поэтому важно перечислить необходимые сервисы. В частности, при фильтрации только по name вы должны также указать необходимые сервисы в optionalServices.

Примечание: Хотя аргумент options технически необязательный, чтобы получить какие-либо результаты, вы должны либо задать значение для filters либо установить acceptAllDevices в true.

A Promise к объекту BluetoothDevice.

TypeError

Выбрасывается, если предоставленные options не имеют смысла. Например, если options.filters присутствует и options.acceptAllDevices равно true, options.filters отсутствует, а options.acceptAllDevices равно false, или options.filters равно [].

NotFoundError DOMException

Выбрасывается, если нет Bluetooth-устройства, соответствующего указанным параметрам.

SecurityError DOMException

Выбрасывается, если эта операция не разрешена в данном контексте из-за безопасности, например, если вызвана из небезопасного источника.

// Discovery options match any devices advertising:
// - The standard heart rate service.
// - Both 16-bit service IDs 0x1802 and 0x1803.
// - A proprietary 128-bit UUID service c48e6067-5295-48d3-8d5c-0395f61792b1.
// - Devices with name "ExampleName".
// - Devices with name starting with "Prefix".
//
// And enables access to the battery service if devices
// include it, even if devices do not advertise that service.
let options = {
  filters: [
    { services: ["heart_rate"] },
    { services: [0x1802, 0x1803] },
    { services: ["c48e6067-5295-48d3-8d5c-0395f61792b1"] },
    { name: "ExampleName" },
    { namePrefix: "Prefix" },
  ],
  optionalServices: ["battery_service"],
};

navigator.bluetooth
  .requestDevice(options)
  .then((device) => {
    console.log(`Name: ${device.name}`);
    // Do something with the device.
  })
  .catch((error) => console.error(`Something went wrong. ${error}`));

Подробные примеры приведены в спецификации, а также в Взаимодействие с Bluetooth-устройствами через JavaScript на developer.chrome.com.

• Общение с устройствами Bluetooth через JavaScript на developer.chrome.com.