Serial: метод requestPort()

Метод Serial.requestPort() интерфейса Serial предоставляет пользователю диалоговое окно, в котором он может выбрать последовательное устройство для подключения. Он возвращает Promise, который разрешается экземпляром SerialPort, представляющим выбранное пользователем устройство.

При первом посещении сайта у него не будет разрешения на доступ к последовательным устройствам. Сначала сайт должен вызвать requestPort(), чтобы запросить у пользователя разрешение на управление этим устройством.

Этот метод должен вызываться с помощью временного активации. Пользователь должен взаимодействовать со страницей или элементом пользовательского интерфейса для работы этой функции.

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

Объект со следующими свойствами:

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

Список объектов, содержащих идентификаторы поставщика, продукта или класса Bluetooth-службы, используемые для фильтрации типов устройств, доступных пользователю для запроса подключения. Если фильтры не указаны, пользователю будет представлен список всех доступных устройств для выбора. Фильтры могут содержать следующие значения:

bluetoothServiceClassId Необязательно

Беззнаковое целое число или строка, представляющая идентификатор класса Bluetooth-службы. Это может быть псевдоним UUID 16 или 32 бит, любой допустимый UUID или допустимое имя из ключей назначенных служб GATT.

usbVendorId Необязательно

Беззнаковое короткое целое число, определяющее поставщика USB-устройств. USB Implementors Forum присваивает идентификаторы определённым поставщикам.

usbProductId Необязательно

Беззнаковое короткое целое число, определяющее USB-устройство. Каждый поставщик присваивает идентификаторы своим продуктам.

allowedBluetoothServiceClassIds Необязательно

Список беззнаковых целых чисел и/или строк, представляющих идентификаторы классов Bluetooth-служб. Порты Bluetooth с пользовательскими идентификаторами класса службы исключаются из списка портов, представленных пользователю, если идентификатор класса службы не включен в этот список. Это справедливо как при фильтрации списка, так и без неё.

A Promise, который разрешается экземпляром SerialPort.

SecurityError DOMException

Возвращаемый Promise отклоняется с этой ошибкой в следующих ситуациях:

• Политика разрешений serial блокирует использование этой функции.
• Запрос разрешения пользователя был отклонен.

NotFoundError DOMException

Возвращаемый Promise отклоняется с этим исключением, если пользователь не выбирает порт при запросе.

Этот пример использует requestPort() для запроса выбора устройства при нажатии <button>. Он не включает фильтр, поэтому список выбора будет содержать все доступные устройства:

<button id="connect">Connect</button>

const connectBtn = document.getElementById("connect");
connectBtn.addEventListener("click", () => {
  try {
    const port = await navigator.serial.requestPort();
    // Connect to port or add it to the list of available ports
  } catch (e) {
    // The user didn't select a device
  }
});

В этом случае фильтр передается в requestPort() с идентификатором поставщика USB, чтобы ограничить отображаемые устройства только USB-устройствами определённого производителя.

connectBtn.addEventListener("click", () => {
  const usbVendorId = 0xabcd;
  try {
    const port = await navigator.serial.requestPort({ filters: [{ usbVendorId }] });
    // Connect to port or add it to the list of available ports
  } catch (e) {
    // The user didn't select a device
  }
});

Хотя большинство устройств поддерживают SPP-связь через стандартный профиль Bluetooth Classic Serial Port, некоторые используют пользовательские службы связи по радиочастоте (RFCOMM). У таких устройств есть идентификатор класса службы, который не входит в стандартный диапазон UUID Bluetooth.

Для доступа к этим пользовательским службам на основе RFCOMM необходимо передать список allowedBluetoothServiceClassIds в requestPort().

const myBluetoothServiceUuid = "01234567-89ab-cdef-0123-456789abcdef";

// Prompt user to select any serial port
// Access to the custom Bluetooth RFCOMM service above will be allowed
const port = await navigator.serial.requestPort({
  allowedBluetoothServiceClassIds: [myBluetoothServiceUuid],
});

Можно также использовать ключ фильтра bluetoothServiceClassId при вызове requestPort(), чтобы отобразить список отфильтрованных последовательных портов Bluetooth, идентифицированных по идентификаторам класса службы:

const myBluetoothServiceUuid = "01234567-89ab-cdef-0123-456789abcdef";

// Prompt the user to select Bluetooth serial ports with
// the custom Bluetooth RFCOMM service above.
const port = await navigator.serial.requestPort({
  allowedBluetoothServiceClassIds: [myBluetoothServiceUuid],
  filters: [{ bluetoothServiceClassId: myBluetoothServiceUuid }],
});