chrome.usb

Descripción

Usa la API de chrome.usb para interactuar con dispositivos USB conectados. Esta API proporciona acceso a las operaciones USB desde el contexto de una app. Con esta API, las apps pueden funcionar como controladores de dispositivos de hardware. Para informar los errores que genera esta API, configura runtime.lastError y ejecuta la devolución de llamada normal de la función. En este caso, los parámetros regulares de la devolución de llamada no estarán definidos.

Permisos

usb

Tipos

ConfigDescriptor

Propiedades

  • activo

    boolean

    Chrome 47 y versiones posteriores

    ¿Esta es la configuración activa?

  • configurationValue

    número

    El número de configuración.

  • descripción

    cadena opcional

    Descripción de la configuración.

  • extra_data

    ArrayBuffer

    Datos de descriptor adicionales asociados con esta configuración.

  • interfaces

    InterfaceDescriptor[]

    Interfaces disponibles.

  • maxPower

    número

    La potencia máxima que necesita este dispositivo en miliamperios (mA).

  • remoteWakeup

    boolean

    El dispositivo admite el despertar remoto.

  • selfPowered

    boolean

    El dispositivo tiene alimentación propia.

ConnectionHandle

Propiedades

  • handle

    número

    Es un identificador opaco que representa esta conexión al dispositivo USB y todas las interfaces reclamadas asociadas y las transferencias pendientes. Se crea un identificador nuevo cada vez que se abre el dispositivo. El identificador de conexión es diferente de Device.device.

  • productId

    número

    Es el ID del producto.

  • vendorId

    número

    Es el ID del proveedor del dispositivo.

ControlTransferInfo

Propiedades

  • datos

    ArrayBuffer opcional

    Los datos que se transmitirán (obligatorio solo para las transferencias de salida).

  • dirección

    Dirección

    La dirección de transferencia ("in" o "out").

  • index

    número

    El campo wIndex; consulta Ibid.

  • longitud

    número opcional

    La cantidad máxima de bytes que se recibirán (obligatorio solo para las transferencias de entrada).

  • destinatario

    Destinatario

    El destino de la transferencia. El objetivo que proporciona index se debe reclamar si es "interface" o "endpoint".

  • request

    número

    El campo bRequest, consulta el artículo 9.3 de la Especificación del Bus Universal en Serie, revisión 1.1.

  • requestType

    RequestType

    Es el tipo de solicitud.

  • tiempo de espera agotado

    número opcional

    Chrome 43 y versiones posteriores

    Tiempo de espera de la solicitud (en milisegundos). El valor predeterminado 0 indica que no hay tiempo de espera.

  • valor

    número

    El campo wValue; consulta Ibid.

Device

Propiedades

  • dispositivo

    número

    Es un ID opaco para el dispositivo USB. Permanecerá sin cambios hasta que se desconecte el dispositivo.

  • manufacturerName

    string

    Chrome 46 y versiones posteriores

    Es la cadena de iManufacturer que lee del dispositivo, si está disponible.

  • productId

    número

    Es el ID del producto.

  • NombreProducto

    string

    Chrome 46 y versiones posteriores

    Es la cadena de iProduct que se lee del dispositivo, si está disponible.

  • serialNumber

    string

    Chrome 46 y versiones posteriores

    La cadena iSerialNumber que se lee del dispositivo, si está disponible

  • vendorId

    número

    Es el ID del proveedor del dispositivo.

  • versión

    número

    Chrome 51 y versiones posteriores

    La versión del dispositivo (campo bcdDevice)

DeviceFilter

Propiedades

  • interfaceClass

    número opcional

    Clase de interfaz USB, coincide con cualquier interfaz del dispositivo

  • interfaceProtocol

    número opcional

    Es el protocolo de interfaz USB, que se verifica solo si coincide la subclase de la interfaz.

  • interfaceSubclass

    número opcional

    Es la subclase de la interfaz USB, que se verifica solo si la clase de interfaz coincide.

  • productId

    número opcional

    Es el ID de producto del dispositivo, que se verifica solo si coincide el ID del proveedor.

  • vendorId

    número opcional

    Es el ID del proveedor del dispositivo.

DevicePromptOptions

Propiedades

  • filtros

    DeviceFilter[] opcional

    Filtra la lista de dispositivos que se presenta al usuario. Si se proporcionan varios filtros, se mostrarán los dispositivos que coincidan con cualquiera de ellos.

  • múltiples

    booleano opcional

    Permite que el usuario seleccione varios dispositivos.

Direction

Direction, Recipient, RequestType y TransferType se asignan a sus homónimos dentro de la especificación USB.

Enum

EndpointDescriptor

Propiedades

  • dirección

    número

    Dirección del extremo

  • dirección

    Dirección

    Dirección de transferencia.

  • extra_data

    ArrayBuffer

    Datos de descriptor adicionales asociados con este extremo.

  • maximumPacketSize

    número

    Tamaño máximo del paquete.

  • pollingInterval

    número opcional

    Intervalo de sondeo (solo interrupción e isócrono).

  • sincronización

    SynchronizationType opcional

    Modo de sincronización de la transferencia (solo modo isocrónico).

  • Tipo de transferencia.

  • uso

    UsageType opcional

    Sugerencia de uso del extremo.

EnumerateDevicesAndRequestAccessOptions

Propiedades

  • interfaceId

    número opcional

    El ID de interfaz para solicitar acceso. Solo está disponible en ChromeOS. No tiene ningún efecto en otras plataformas.

  • productId

    número

    Es el ID del producto.

  • vendorId

    número

    Es el ID del proveedor del dispositivo.

EnumerateDevicesOptions

Propiedades

  • filtros

    DeviceFilter[] opcional

    Se mostrará un dispositivo que coincida con cualquier filtro determinado. Si la lista de filtros está vacía, se mostrarán todos los dispositivos para los que la app tenga permiso.

  • productId

    número opcional

    Obsoleto

    Equivale a la configuración DeviceFilter.productId.

  • vendorId

    número opcional

    Obsoleto

    Equivale a la configuración DeviceFilter.vendorId.

GenericTransferInfo

Propiedades

  • datos

    ArrayBuffer opcional

    Los datos que se transmitirán (obligatorio solo para las transferencias de salida).

  • dirección

    Dirección

    La dirección de la transferencia ("in" o "out").

  • extremo

    número

    La dirección del extremo de destino. Se debe reclamar la interfaz que contiene este extremo.

  • longitud

    número opcional

    Es la cantidad máxima de bytes que se recibirán (solo se requiere para las transferencias de entrada).

  • tiempo de espera agotado

    número opcional

    Chrome 43 y versiones posteriores

    Tiempo de espera de la solicitud (en milisegundos). El valor predeterminado 0 indica que no hay tiempo de espera.

InterfaceDescriptor

Propiedades

  • alternateSetting

    número

    El número de configuración alternativo de la interfaz (el valor predeterminado es 0)

  • descripción

    cadena opcional

    Descripción de la interfaz.

  • extremos

    EndpointDescriptor[]

    Extremos disponibles.

  • extra_data

    ArrayBuffer

    Datos de descriptor adicionales asociados con esta interfaz.

  • interfaceClass

    número

    Es la clase de interfaz USB.

  • interfaceNumber

    número

    Es el número de interfaz.

  • interfaceProtocol

    número

    Protocolo de interfaz USB

  • interfaceSubclass

    número

    Es la subclase de la interfaz USB.

IsochronousTransferInfo

Propiedades

  • packetLength

    número

    La longitud de cada uno de los paquetes en esta transferencia.

  • paquetes

    número

    Es la cantidad total de paquetes en esta transferencia.

  • transferInfo

    GenericTransferInfo

    Parámetros de transferencia. La longitud de transferencia o el búfer de datos especificados en este bloque de parámetros se dividen a lo largo de los límites de packetLength para formar los paquetes individuales de la transferencia.

Recipient

Enum

"interface"

RequestType

Enum

SynchronizationType

En el caso de los modos isócrono y de interrupción, SynchronizationType y UsageType se asignan a sus homónimos dentro de la especificación USB.

Enum

"asynchronous"

"adaptativa"

"síncrona"

TransferResultInfo

Propiedades

  • datos

    ArrayBuffer opcional

    Los datos que muestra una transferencia de entrada. undefined para las transferencias de salida.

  • resultCode

    número opcional

    Un valor de 0 indica que la transferencia se realizó correctamente. Otros valores indican una falla.

TransferType

Enum

"control"

"interrupt"

UsageType

Enum

"data"

"explicitFeedback"

"notification"

Métodos

bulkTransfer()

Promesa 
chrome.usb.bulkTransfer(
  handle: ConnectionHandle,
  transferInfo: GenericTransferInfo,
  callback?: function,
)

Realiza una transferencia masiva en el dispositivo especificado.

Parámetros

Muestra

  • Promise<TransferResultInfo>

    Chrome 116 y versiones posteriores

    Las promesas solo se admiten para Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

claimInterface()

Promesa 
chrome.usb.claimInterface(
  handle: ConnectionHandle,
  interfaceNumber: number,
  callback?: function,
)

Reclama una interfaz en un dispositivo USB. Antes de que los datos se puedan transferir a una interfaz o a extremos asociados, se debe reclamar la interfaz. Solo un identificador de conexión puede reclamar una interfaz en un momento determinado. Si ya se reclamó la interfaz, la llamada fallará.

Se debe llamar a releaseInterface cuando ya no se necesita la interfaz.

Parámetros

  • Una conexión abierta al dispositivo.

  • interfaceNumber

    número

    Es la interfaz que se reclamará.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promesa<void>

    Chrome 116 y versiones posteriores

    Las promesas solo se admiten para Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

closeDevice()

Promesa 
chrome.usb.closeDevice(
  handle: ConnectionHandle,
  callback?: function,
)

Cierra un controlador de conexión. Invocar operaciones en un controlador después de que se cerró es una operación segura, pero no implica que se tomen medidas.

Parámetros

Muestra

  • Promesa<void>

    Chrome 116 y versiones posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

controlTransfer()

Promesa 
chrome.usb.controlTransfer(
  handle: ConnectionHandle,
  transferInfo: ControlTransferInfo,
  callback?: function,
)

Realiza una transferencia de controles en el dispositivo especificado.

Las transferencias de control se refieren al dispositivo, a una interfaz o a un extremo. Las transferencias a una interfaz o un extremo requieren que se reclame la interfaz.

Parámetros

Muestra

  • Chrome 116 y versiones posteriores

    Las promesas solo se admiten para Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

findDevices()

Promesa 
chrome.usb.findDevices(
  options: EnumerateDevicesAndRequestAccessOptions,
  callback?: function,
)

Busca dispositivos USB especificados por los IDs de proveedor, producto y, de manera opcional, interfaz, y, si los permisos lo permiten, los abre para su uso.

Si se rechaza la solicitud de acceso o no se puede abrir el dispositivo, no se creará ni se mostrará el controlador de conexión.

Llamar a este método equivale a llamar a getDevices seguido de openDevice para cada dispositivo.

Parámetros

Muestra

  • Promise&lt;ConnectionHandle[]&gt;

    Chrome 116 y versiones posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

getConfiguration()

Promesa 
chrome.usb.getConfiguration(
  handle: ConnectionHandle,
  callback?: function,
)

Obtiene el descriptor de configuración de la configuración seleccionada actualmente.

Parámetros

Muestra

  • Chrome 116 y versiones posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

getConfigurations()

Promesa Chrome 47 y versiones posteriores 
chrome.usb.getConfigurations(
  device: Device,
  callback?: function,
)

Devuelve el conjunto completo de descriptores de configuración del dispositivo.

Parámetros

Muestra

  • Promise&lt;ConfigDescriptor[]&gt;

    Chrome 116 y versiones posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

getDevices()

Promesa 
chrome.usb.getDevices(
  options: EnumerateDevicesOptions,
  callback?: function,
)

Enumera los dispositivos USB conectados.

Parámetros

  • Son las propiedades que se buscarán en los dispositivos de destino.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (devices: Device[]) => void

Muestra

  • Promesa<Dispositivo[]>

    Chrome 116 y versiones posteriores

    Las promesas solo se admiten para Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

getUserSelectedDevices()

Promesa 
chrome.usb.getUserSelectedDevices(
  options: DevicePromptOptions,
  callback?: function,
)

Presenta un selector de dispositivos al usuario y muestra los Device seleccionados. Si el usuario cancela, los dispositivos del selector estarán vacíos. Se requiere un gesto del usuario para que se muestre el diálogo. Sin un gesto del usuario, la devolución de llamada se ejecutará como si el usuario hubiera cancelado.

Parámetros

  • Configuración del cuadro de diálogo del selector de dispositivos.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (devices: Device[]) => void

Muestra

  • Promise<Device[]>

    Chrome 116 y versiones posteriores

    Las promesas solo se admiten para Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

interruptTransfer()

Promesa 
chrome.usb.interruptTransfer(
  handle: ConnectionHandle,
  transferInfo: GenericTransferInfo,
  callback?: function,
)

Realiza una transferencia de interrupción en el dispositivo especificado.

Parámetros

Muestra

  • Chrome 116 y versiones posteriores

    Las promesas solo se admiten para Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

isochronousTransfer()

Promesa 
chrome.usb.isochronousTransfer(
  handle: ConnectionHandle,
  transferInfo: IsochronousTransferInfo,
  callback?: function,
)

Realiza una transferencia isócrona en el dispositivo específico.

Parámetros

Muestra

  • Chrome 116 y versiones posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

listInterfaces()

Promesa 
chrome.usb.listInterfaces(
  handle: ConnectionHandle,
  callback?: function,
)

Muestra una lista de todas las interfaces de un dispositivo USB.

Parámetros

Muestra

  • Chrome 116 y versiones posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

openDevice()

Promesa 
chrome.usb.openDevice(
  device: Device,
  callback?: function,
)

Abre un dispositivo USB que devolvió getDevices.

Parámetros

Muestra

  • Promise&lt;ConnectionHandle&gt;

    Chrome 116 y versiones posteriores

    Las promesas solo se admiten para Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

releaseInterface()

Promesa 
chrome.usb.releaseInterface(
  handle: ConnectionHandle,
  interfaceNumber: number,
  callback?: function,
)

Libera una interfaz reclamada.

Parámetros

  • Una conexión abierta al dispositivo.

  • interfaceNumber

    número

    La interfaz que se lanzará.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promesa<void>

    Chrome 116 y versiones posteriores

    Las promesas solo se admiten para Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

requestAccess()

Promise Obsoleto
chrome.usb.requestAccess(
  device: Device,
  interfaceId: number,
  callback?: function,
)

Esta función era específica de ChromeOS y no se podía llamar desde otras plataformas. Ahora, esta operación se realiza de forma implícita como parte de openDevice, y esta función mostrará true en todas las plataformas.

Solicita acceso del agente de permisos a un dispositivo reclamado por ChromeOS si no se reclama la interfaz determinada en el dispositivo.

Parámetros

  • dispositivo

    Dispositivo

    El Device al que deseas solicitar acceso.

  • interfaceId

    número

    Es la interfaz particular solicitada.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (success: boolean) => void

    • correcto

      boolean

Muestra

  • Promise<boolean>

    Chrome 116 y versiones posteriores

    Las promesas solo se admiten para Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

resetDevice()

Promesa 
chrome.usb.resetDevice(
  handle: ConnectionHandle,
  callback?: function,
)

Intenta restablecer el dispositivo USB. Si el restablecimiento falla, se cerrará el identificador de conexión determinado y el dispositivo USB parecerá estar desconectado y, luego, se volverá a conectar. En este caso, se debe volver a llamar a getDevices o findDevices para adquirir el dispositivo.

Parámetros

  • Un controlador de conexión para restablecer.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (success: boolean) => void

    • correcto

      boolean

Muestra

  • Promise<boolean>

    Chrome 116 y versiones posteriores

    Las promesas solo se admiten para Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

setConfiguration()

Promesa 
chrome.usb.setConfiguration(
  handle: ConnectionHandle,
  configurationValue: number,
  callback?: function,
)

Selecciona una configuración del dispositivo.

Esta función restablece de manera efectiva el dispositivo seleccionando una de las configuraciones disponibles. Solo son válidos los valores de configuración superiores a 0. Sin embargo, algunos dispositivos con errores tienen una configuración 0 que funciona, por lo que se permite este valor.

Parámetros

  • Una conexión abierta al dispositivo

  • configurationValue

    número

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promesa<void>

    Chrome 116 y versiones posteriores

    Las promesas solo se admiten para Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

setInterfaceAlternateSetting()

Promesa 
chrome.usb.setInterfaceAlternateSetting(
  handle: ConnectionHandle,
  interfaceNumber: number,
  alternateSetting: number,
  callback?: function,
)

Selecciona un parámetro de configuración alternativo en una interfaz reclamada anteriormente.

Parámetros

  • Una conexión abierta con el dispositivo en el que se reclamó esta interfaz.

  • interfaceNumber

    número

    La interfaz que se configurará.

  • alternateSetting

    número

    El parámetro de configuración alternativo que se debe establecer.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promesa<void>

    Chrome 116 y versiones posteriores

    Las promesas solo se admiten para Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

Eventos

onDeviceAdded

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

Es un evento que se genera cuando se agrega un dispositivo al sistema. Los eventos solo se transmiten a las apps y extensiones que tienen permiso para acceder al dispositivo. Es posible que se haya otorgado el permiso en el momento de la instalación, cuando el usuario aceptó un permiso opcional (consulta permissions.request) o a través de getUserSelectedDevices.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    (device: Device) => void

onDeviceRemoved

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

Evento generado cuando se quita un dispositivo del sistema. Consulta onDeviceAdded para ver qué eventos se publican.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    (device: Device) => void