Device Access

    The can be used to communicate with bluetooth devices. In order to use this API in Electron, developers will need to handle the select-bluetooth-device event on the webContents associated with the device request.

    Additionally, can be used to handle pairing to bluetooth devices on Windows or Linux when additional validation such as a pin is needed.

    This example demonstrates an Electron application that automatically selects the first available bluetooth device when the button is clicked.

    Open in Fiddle

    • main.js
    • preload.js
    • index.html
    • renderer.js
    1. const { contextBridge, ipcRenderer } = require('electron')
    3. contextBridge.exposeInMainWorld('electronAPI', {
    4.   bluetoothPairingRequest: (callback) => ipcRenderer.on('bluetooth-pairing-request', callback),
    5.   bluetoothPairingResponse: (response) => ipcRenderer.send('bluetooth-pairing-response', response)
    6. })
    1. <!DOCTYPE html>
    2. <html>
    3.   <head>
    4.     <meta charset="UTF-8">
    5.     <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
    6.     <title>Web Bluetooth API</title>
    7.   </head>
    8.   <body>
    9.     <h1>Web Bluetooth API</h1>
    11.     <button id="clickme">Test Bluetooth</button>
    13.     <p>Currently selected bluetooth device: <strong id="device-name""></strong></p>
    15.     <script src="./renderer.js"></script>
    16.   </body>
    17. </html>
    1. async function testIt() {
    2.   const device = await navigator.bluetooth.requestDevice({
    3.     acceptAllDevices: true
    4.   })
    5.   document.getElementById('device-name').innerHTML = device.name || `ID: ${device.id}`
    6. }
    8. document.getElementById('clickme').addEventListener('click',testIt)
    10. window.electronAPI.bluetoothPairingRequest((event, details) => {
    11.   const response = {}
    13.   switch (details.pairingKind) {
    14.     case 'confirm': {
    15.       response.confirmed = confirm(`Do you want to connect to device ${details.deviceId}?`)
    16.       break
    17.     }
    18.     case 'confirmPin': {
    19.       response.confirmed = confirm(`Does the pin ${details.pin} match the pin displayed on device ${details.deviceId}?`)
    20.       break
    21.     }
    22.     case 'providePin': {
    23.       const pin = prompt(`Please provide a pin for ${details.deviceId}.`)
    24.       if (pin) {
    25.         response.pin = pin
    26.         response.confirmed = true
    27.       } else {
    28.         response.confirmed = false
    29.       }
    30.     }
    31.   }
    33.   window.electronAPI.bluetoothPairingResponse(response)
    34. })
    • The select-hid-device event on the Session can be used to select a HID device when a call to navigator.hid.requestDevice is made. Additionally the and hid-device-removed events on the Session can be used to handle devices being plugged in or unplugged when handling the select-hid-device event. Note: These events only fire until the callback from select-hid-device is called. They are not intended to be used as a generic hid device listener.
    • can be used to provide default permissioning to devices without first calling for permission to devices via navigator.hid.requestDevice. Additionally, the default behavior of Electron is to store granted device permission through the lifetime of the corresponding WebContents. If longer term storage is needed, a developer can store granted device permissions (eg when handling the select-hid-device event) and then read from that storage with setDevicePermissionHandler.
    • ses.setPermissionCheckHandler(handler) can be used to disable HID access for specific origins.

    By default Electron employs the same blocklist used by Chromium. If you wish to override this behavior, you can do so by setting the disable-hid-blocklist flag:

    This example demonstrates an Electron application that automatically selects HID devices through ses.setDevicePermissionHandler(handler) and through when the Test WebHID button is clicked.

    docs/fiddles/features/web-hid (23.0.0)

    • main.js
    • index.html
    • renderer.js
    1. const {app, BrowserWindow} = require('electron')
    2. const path = require('path')
    4. function createWindow () {
    5.   const mainWindow = new BrowserWindow({
    6.     width: 800,
    7.     height: 600
    8.   })
    10.   mainWindow.webContents.session.on('select-hid-device', (event, details, callback) => {
    11.     //Add events to handle devices being added or removed before the callback on
    12.     //`select-hid-device` is called.
    13.     mainWindow.webContents.session.on('hid-device-added', (event, device) => {    
    14.       console.log('hid-device-added FIRED WITH', device)
    15.       //Optionally update details.deviceList
    16.     })
    18.     mainWindow.webContents.session.on('hid-device-removed', (event, device) => {    
    19.       console.log('hid-device-removed FIRED WITH', device)
    20.       //Optionally update details.deviceList
    21.     })
    23.     event.preventDefault()
    24.     if (details.deviceList && details.deviceList.length > 0) {
    25.       callback(details.deviceList[0].deviceId)
    26.     }
    27.   })
    29.   mainWindow.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
    30.     if (permission === 'hid' && details.securityOrigin === 'file:///') {
    31.       return true
    32.   })
    34.   mainWindow.webContents.session.setDevicePermissionHandler((details) => {
    35.     if (details.deviceType === 'hid' && details.origin === 'file://') {
    36.       return true
    37.     }
    40.   mainWindow.loadFile('index.html')
    41. }
    43. app.whenReady().then(() => {
    44.   createWindow()
    46.   app.on('activate', function () {
    47.     if (BrowserWindow.getAllWindows().length === 0) createWindow()
    48.   })
    49. })
    51. app.on('window-all-closed', function () {
    52.   if (process.platform !== 'darwin') app.quit()
    53. })
    1. <!DOCTYPE html>
    2. <html>
    3.   <head>
    4.     <meta charset="UTF-8">
    5.     <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
    6.     <title>WebHID API</title>
    7.   </head>
    8.   <body>
    9.     <h1>WebHID API</h1>
    11.     <button id="clickme">Test WebHID</button>
    13.     <h3>HID devices automatically granted access via <i>setDevicePermissionHandler</i></h3>
    14.     <div id="granted-devices"></div>
    16.     <h3>HID devices automatically granted access via <i>select-hid-device</i></h3>
    17.     <div id="granted-devices2"></div>
    19.     <script src="./renderer.js"></script>
    20.   </body>
    21. </html>
    1. async function testIt() {
    2.   const grantedDevices = await navigator.hid.getDevices()
    3.   let grantedDeviceList = ''
    4.   grantedDevices.forEach(device => {
    5.     grantedDeviceList += `<hr>${device.productName}</hr>`
    6.   })
    7.   document.getElementById('granted-devices').innerHTML = grantedDeviceList
    8.   const grantedDevices2 = await navigator.hid.requestDevice({
    9.     filters: []
    10.   })
    12.   grantedDeviceList = ''
    13.    grantedDevices2.forEach(device => {
    14.     grantedDeviceList += `<hr>${device.productName}</hr>`
    15.   })
    16.   document.getElementById('granted-devices2').innerHTML = grantedDeviceList
    17. }
    19. document.getElementById('clickme').addEventListener('click',testIt)

    The can be used to access serial devices that are connected via serial port, USB, or Bluetooth. In order to use this API in Electron, developers will need to handle the select-serial-port event on the Session associated with the serial port request.

    • The and serial-port-removed events on the Session can be used to handle devices being plugged in or unplugged when handling the select-serial-port event. Note: These events only fire until the callback from select-serial-port is called. They are not intended to be used as a generic serial port listener.
    • can be used to provide default permissioning to devices without first calling for permission to devices via navigator.serial.requestPort. Additionally, the default behavior of Electron is to store granted device permission through the lifetime of the corresponding WebContents. If longer term storage is needed, a developer can store granted device permissions (eg when handling the select-serial-port event) and then read from that storage with setDevicePermissionHandler.
    • ses.setPermissionCheckHandler(handler) can be used to disable serial access for specific origins.

    This example demonstrates an Electron application that automatically selects serial devices through ses.setDevicePermissionHandler(handler) as well as demonstrating selecting the first available Arduino Uno serial device (if connected) through when the Test Web Serial button is clicked.

    docs/fiddles/features/web-serial (23.0.0)

    • main.js
    • index.html
    • renderer.js
    1. <!DOCTYPE html>
    2. <html>
    3.   <head>
    4.     <meta charset="UTF-8">
    5.     <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
    6.     <title>Web Serial API</title>
    7.   <body>
    8.     <h1>Web Serial API</h1>
    10.     <button id="clickme">Test Web Serial API</button>
    12.     <p>Matching Arduino Uno device: <strong id="device-name""></strong></p>
    14.     <script src="./renderer.js"></script>
    15.   </body>
    16. </html>
    1. async function testIt() {
    2.   const filters = [
    3.     { usbVendorId: 0x2341, usbProductId: 0x0043 },
    4.     { usbVendorId: 0x2341, usbProductId: 0x0001 }
    5.   ];
    6.   try {
    7.     const port = await navigator.serial.requestPort({filters});
    8.     const portInfo = port.getInfo();
    9.     document.getElementById('device-name').innerHTML = `vendorId: ${portInfo.usbVendorId} | productId: ${portInfo.usbProductId} `
    10.   } catch (ex) {
    11.     if (ex.name === 'NotFoundError') {
    12.       document.getElementById('device-name').innerHTML = 'Device NOT found'
    13.     } else {
    14.       document.getElementById('device-name').innerHTML = ex
    15.     }
    16.   }
    17. }
    19. document.getElementById('clickme').addEventListener('click',testIt)

    The can be used to access USB devices. Electron provides several APIs for working with the WebUSB API:

    • The select-usb-device event on the Session can be used to select a USB device when a call to navigator.usb.requestDevice is made. Additionally the and usb-device-removed events on the Session can be used to handle devices being plugged in or unplugged when handling the select-usb-device event. Note: These two events only fire until the callback from select-usb-device is called. They are not intended to be used as a generic usb device listener.
    • The can be used to respond when device.forget() is called on a USB device.
    • can be used to provide default permissioning to devices without first calling for permission to devices via navigator.usb.requestDevice. Additionally, the default behavior of Electron is to store granted device permission through the lifetime of the corresponding WebContents. If longer term storage is needed, a developer can store granted device permissions (eg when handling the select-usb-device event) and then read from that storage with setDevicePermissionHandler.
    • ses.setPermissionCheckHandler(handler) can be used to disable USB access for specific origins.

    This example demonstrates an Electron application that automatically selects USB devices (if they are attached) through ses.setDevicePermissionHandler(handler) and through when the Test WebUSB button is clicked.

    • index.html
    • renderer.js
    2. const e = require('express')
    3. const path = require('path')
    5. function createWindow () {
    6.   const mainWindow = new BrowserWindow({
    7.     width: 800,
    8.     height: 600
    9.   })
    11.   let grantedDeviceThroughPermHandler
    13.   mainWindow.webContents.session.on('select-usb-device', (event, details, callback) => {
    14.     //Add events to handle devices being added or removed before the callback on
    15.     //`select-usb-device` is called.
    16.     mainWindow.webContents.session.on('usb-device-added', (event, device) => {    
    17.       console.log('usb-device-added FIRED WITH', device)
    18.       //Optionally update details.deviceList
    19.     })
    21.     mainWindow.webContents.session.on('usb-device-removed', (event, device) => {
    22.       console.log('usb-device-removed FIRED WITH', device)
    23.       //Optionally update details.deviceList
    24.     })
    26.     event.preventDefault()
    27.     if (details.deviceList && details.deviceList.length > 0) {
    28.       const deviceToReturn  = details.deviceList.find((device) => {
    29.         if (!grantedDeviceThroughPermHandler || (device.deviceId != grantedDeviceThroughPermHandler.deviceId)) {
    30.           return true
    31.         }
    32.       })
    33.       if (deviceToReturn) {
    34.         callback(deviceToReturn.deviceId)        
    35.       } else {
    36.         callback()
    37.       }
    38.     }
    39.   })
    41.   mainWindow.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
    42.     if (permission === 'usb' && details.securityOrigin === 'file:///') {
    43.       return true
    44.     }
    45.   })
    48.   mainWindow.webContents.session.setDevicePermissionHandler((details) => {
    49.     if (details.deviceType === 'usb' && details.origin === 'file://') {
    50.       if (!grantedDeviceThroughPermHandler) {        
    51.         grantedDeviceThroughPermHandler = details.device
    52.         return true
    53.       } else {
    54.         return false
    55.       }
    56.     }
    57.   })
    59.   mainWindow.loadFile('index.html')
    60. }
    62. app.whenReady().then(() => {
    63.   createWindow()
    65.   app.on('activate', function () {
    66.     if (BrowserWindow.getAllWindows().length === 0) createWindow()
    67.   })
    68. })
    70. app.on('window-all-closed', function () {
    71.   if (process.platform !== 'darwin') app.quit()
    72. })
    1. function getDeviceDetails(device) {
    2.   return grantedDevice.productName || `Unknown device ${grantedDevice.deviceId}`
    3. }
    5. async function testIt() {
    6.   const noDevicesFoundMsg = 'No devices found'
    7.   const grantedDevices = await navigator.usb.getDevices()
    8.   let grantedDeviceList = ''
    9.   if (grantedDevices.length > 0) {    
    10.     grantedDevices.forEach(device => {
    11.       grantedDeviceList += `<hr>${getDeviceDetails(device)}</hr>`
    12.     })    
    13.   } else {
    14.     grantedDeviceList = noDevicesFoundMsg
    15.   }
    16.   document.getElementById('granted-devices').innerHTML = grantedDeviceList
    18.   grantedDeviceList = ''
    19.   try {
    20.     const grantedDevice = await navigator.usb.requestDevice({
    21.       filters: []
    22.     })
    23.     grantedDeviceList += `<hr>${getDeviceDetails(device)}</hr>`
    25.   } catch (ex) {
    26.     if (ex.name === 'NotFoundError') {
    27.       grantedDeviceList = noDevicesFoundMsg
    28.     }
    29.   }
    30.   document.getElementById('granted-devices2').innerHTML = grantedDeviceList
    31. }