chrome.hid

Description

Use the chrome.hid API to interact with connected HID devices. This API provides access to HID operations from within the context of an app. Using this API, apps can function as drivers for hardware devices. Errors generated by this API are reported by setting runtime.lastError and executing the function's regular callback. The callback's regular parameters will be undefined in this case.

Permissions

hid

Types

DeviceFilter

Properties

  • productId

    number optional

    Device product ID, only checked only if the vendor ID matches.

  • usage

    number optional

    HID usage identifier, checked only if the HID usage page matches.

  • usagePage

    number optional

    HID usage page identifier.

  • vendorId

    number optional

    Device vendor ID.

GetDevicesOptions

Properties

  • filters

    DeviceFilter[] optional

    A device matching any given filter will be returned. An empty filter list will return all devices the app has permission for.

  • productId

    number optional

    Deprecated

    Equivalent to setting DeviceFilter.productId.

  • vendorId

    number optional

    Deprecated

    Equivalent to setting DeviceFilter.vendorId.

HidCollectionInfo

Properties

  • reportIds

    number[]

    Report IDs which belong to the collection and to its children.

  • usage

    number

    Page-defined usage identifier.

  • usagePage

    number

    HID usage page identifier.

HidConnectInfo

Properties

  • connectionId

    number

    The opaque ID used to identify this connection in all other functions.

HidDeviceInfo

Properties

  • collections

    HidCollectionInfo[]

    Top-level collections from this device's report descriptors.

  • deviceId

    number

    Opaque device ID.

  • maxFeatureReportSize

    number

    Top-level collection's maximum feature report size.

  • maxInputReportSize

    number

    Top-level collection's maximum input report size.

  • maxOutputReportSize

    number

    Top-level collection's maximum output report size.

  • productId

    number

    Product ID.

  • productName

    string

    Chrome 46+

    The product name read from the device, if available.

  • reportDescriptor

    ArrayBuffer

    Raw device report descriptor (not available on Windows).

  • serialNumber

    string

    Chrome 46+

    The serial number read from the device, if available.

  • vendorId

    number

    Vendor ID.

Methods

connect()

Promise 
chrome.hid.connect(
  deviceId: number,
  callback?: function,
)

Open a connection to an HID device for communication.

Parameters

Returns

  • Promise<HidConnectInfo>

    Chrome 117+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

disconnect()

Promise 
chrome.hid.disconnect(
  connectionId: number,
  callback?: function,
)

Disconnect from a device. Invoking operations on a device after calling this is safe but has no effect.

Parameters

  • connectionId

    number

    The connectionId returned by connect.

  • callback

    function optional

    The callback parameter looks like: 

    ()=>void

Returns

  • Promise<void>

    Chrome 117+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

getDevices()

Promise 
chrome.hid.getDevices(
  options: GetDevicesOptions,
  callback?: function,
)

Enumerate connected HID devices.

Parameters

Returns

  • Promise<HidDeviceInfo[]>

    Chrome 117+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

receive()

chrome.hid.receive(
  connectionId: number,
  callback: function,
)

Receive the next input report from the device.

Parameters

  • connectionId

    number

    The connectionId returned by connect.

  • callback

    function

    The callback parameter looks like: 

    (reportId: number,data: ArrayBuffer)=>void

    • reportId

      number

      The report ID or 0 if none.

    • data

      ArrayBuffer

      The report data, the report ID prefix (if present) is removed.

receiveFeatureReport()

Promise 
chrome.hid.receiveFeatureReport(
  connectionId: number,
  reportId: number,
  callback?: function,
)

Request a feature report from the device.

Parameters

  • connectionId

    number

    The connectionId returned by connect.

  • reportId

    number

    The report ID, or 0 if none.

  • callback

    function optional

    The callback parameter looks like: 

    (data: ArrayBuffer)=>void

    • data

      ArrayBuffer

      The report data, including a report ID prefix if one is sent by the device.

Returns

  • Promise<ArrayBuffer>

    Chrome 117+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

send()

Promise 
chrome.hid.send(
  connectionId: number,
  reportId: number,
  data: ArrayBuffer,
  callback?: function,
)

Send an output report to the device.

Note: Do not include a report ID prefix in data. It will be added if necessary.

Parameters

  • connectionId

    number

    The connectionId returned by connect.

  • reportId

    number

    The report ID to use, or 0 if none.

  • data

    ArrayBuffer

    The report data.

  • callback

    function optional

    The callback parameter looks like: 

    ()=>void

Returns

  • Promise<void>

    Chrome 117+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

sendFeatureReport()

Promise 
chrome.hid.sendFeatureReport(
  connectionId: number,
  reportId: number,
  data: ArrayBuffer,
  callback?: function,
)

Send a feature report to the device.

Note: Do not include a report ID prefix in data. It will be added if necessary.

Parameters

  • connectionId

    number

    The connectionId returned by connect.

  • reportId

    number

    The report ID to use, or 0 if none.

  • data

    ArrayBuffer

    The report data.

  • callback

    function optional

    The callback parameter looks like: 

    ()=>void

Returns

  • Promise<void>

    Chrome 117+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

Events

onDeviceAdded

chrome.hid.onDeviceAdded.addListener(
  callback: function,
)

Event generated when a device is added to the system. Events are only broadcast to apps and extensions that have permission to access the device. Permission may have been granted at install time or when the user accepted an optional permission (see permissions.request).

Parameters

onDeviceRemoved

chrome.hid.onDeviceRemoved.addListener(
  callback: function,
)

Event generated when a device is removed from the system. See onDeviceAdded for which events are delivered.

Parameters

  • callback

    function

    The callback parameter looks like: 

    (deviceId: number)=>void

    • deviceId

      number