chrome.usb

Descripción

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

Permisos

usb

Disponibilidad

Solo en ChromeOS

Tipos

ConfigDescriptor

Propiedades

  • activo

    booleano

    Chrome 47 y versiones posteriores

    ¿Es esta la configuración activa?

  • configurationValue

    número

    Es el número de configuración.

  • descripción

    string opcional

    Es la descripción de la configuración.

  • extra_data

    ArrayBuffer

    Son los datos de descriptor adicionales asociados con esta configuración.

  • interfaces

    InterfaceDescriptor[]

    Son las interfaces disponibles.

  • maxPower

    número

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

  • remoteWakeup

    booleano

    El dispositivo admite la activación remota.

  • selfPowered

    booleano

    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 y transferencias pendientes asociadas. 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

    Son los datos que se transmitirán (solo se requieren para las transferencias de salida).

  • dirección

    Dirección

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

  • índice

    número

    El campo wIndex, consulta Ibid.

  • longitud

    number opcional

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

  • destinatario

    Destinatario

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

  • solicitud

    número

    Para el campo bRequest, consulta la Revisión 1.1 de la especificación del bus universal en serie § 9.3.

  • requestType

    RequestType

    Es el tipo de solicitud.

  • tiempo de espera agotado

    number 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. No cambia hasta que se desconecta el dispositivo.

  • manufacturerName

    string

    Chrome 46 y versiones posteriores

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

  • productId

    número

    Es el ID del producto.

  • NombreProducto

    string

    Chrome 46 y versiones posteriores

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

  • serialNumber

    string

    Chrome 46 y versiones posteriores

    Es 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 o versiones posteriores

    La versión del dispositivo (campo bcdDevice)

DeviceFilter

Propiedades

  • interfaceClass

    number opcional

    Clase de interfaz USB, coincide con cualquier interfaz del dispositivo.

  • interfaceProtocol

    number opcional

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

  • interfaceSubclass

    number opcional

    Subclase de interfaz USB, que se verifica solo si coincide con la clase de interfaz.

  • productId

    number opcional

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

  • vendorId

    number opcional

    ID de proveedor del dispositivo

DevicePromptOptions

Propiedades

  • filtros

    DeviceFilter[] opcional

    Filtrar la lista de dispositivos que se presentan 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 de USB.

Enum

"in"

"out"

EndpointDescriptor

Propiedades

  • dirección

    número

    Dirección del extremo.

  • dirección

    Dirección

    Dirección de transferencia.

  • extra_data

    ArrayBuffer

    Son los datos de descriptor adicionales asociados con este extremo.

  • maximumPacketSize

    número

    Tamaño máximo de los paquetes.

  • pollingInterval

    number opcional

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

  • sincronización

    SynchronizationType opcional

    Es el modo de sincronización de transferencia (solo isócrono).

  • Es el tipo de transferencia.

  • uso

    UsageType opcional

    Sugerencia de uso del extremo.

EnumerateDevicesAndRequestAccessOptions

Propiedades

  • interfaceId

    number opcional

    Es el ID de la interfaz a la que se solicitará acceso. Solo 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 devolverá un dispositivo que coincida con cualquier filtro determinado. Una lista de filtros vacía devolverá todos los dispositivos para los que la app tiene permiso.

  • productId

    number opcional

    Obsoleto

    Equivale a configurar DeviceFilter.productId.

  • vendorId

    number opcional

    Obsoleto

    Equivale a configurar DeviceFilter.vendorId.

GenericTransferInfo

Propiedades

  • datos

    ArrayBuffer opcional

    Son los datos que se transmitirán (solo se requieren para las transferencias de salida).

  • dirección

    Dirección

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

  • extremo

    número

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

  • longitud

    number opcional

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

  • tiempo de espera agotado

    number 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

    Es el número de configuración alternativa de la interfaz (el valor predeterminado es 0

  • descripción

    string opcional

    Es la descripción de la interfaz.

  • extremos

    EndpointDescriptor[]

    Son los extremos disponibles.

  • extra_data

    ArrayBuffer

    Son 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 la interfaz.

  • interfaceProtocol

    número

    Es el 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 de esta transferencia.

  • paquetes

    número

    Es la cantidad total de paquetes en esta transferencia.

  • transferInfo

    GenericTransferInfo

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

Recipient

Enum

"device"

"interface"

"endpoint"

"other"

RequestType

Enum

"standard"

"class"

"vendor"

"reserved"

SynchronizationType

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

Enum

"asynchronous"

"adaptive"

"synchronous"

TransferResultInfo

Propiedades

  • datos

    ArrayBuffer opcional

    Son los datos que devuelve una transferencia de entrada. undefined para las transferencias de salida.

  • resultCode

    number opcional

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

TransferType

Enum

"control"

"interrupt"

"isochronous"

"bulk"

UsageType

Enum

"data"

"feedback"

"explicitFeedback"

"periodic"

"notification"

Métodos

bulkTransfer()

Promise 
chrome.usb.bulkTransfer(
  handle: ConnectionHandle,
  transferInfo: GenericTransferInfo,
  callback?: function,
): Promise<TransferResultInfo>

Realiza una transferencia masiva en el dispositivo especificado.

Parámetros

Muestra

  • Chrome 116 y versiones posteriores

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

claimInterface()

Promise 
chrome.usb.claimInterface(
  handle: ConnectionHandle,
  interfaceNumber: number,
  callback?: function,
): Promise<void>

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

Se debe llamar a releaseInterface cuando ya no se necesite 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

  • Promise<void>

    Chrome 116 y versiones posteriores

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

closeDevice()

Promise 
chrome.usb.closeDevice(
  handle: ConnectionHandle,
  callback?: function,
): Promise<void>

Cierra un controlador de conexión. Invocar operaciones en un identificador después de que se cerró es una operación segura, pero no provoca que se realice ninguna acción.

Parámetros

Muestra

  • Promise<void>

    Chrome 116 y versiones posteriores

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

controlTransfer()

Promise 
chrome.usb.controlTransfer(
  handle: ConnectionHandle,
  transferInfo: ControlTransferInfo,
  callback?: function,
): Promise<TransferResultInfo>

Realiza una transferencia de control en el dispositivo especificado.

Las transferencias de control se refieren al dispositivo, una interfaz o 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 en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

findDevices()

Promise 
chrome.usb.findDevices(
  options: EnumerateDevicesAndRequestAccessOptions,
  callback?: function,
): Promise<ConnectionHandle[]>

Busca los dispositivos USB especificados por el proveedor, el producto y, de manera opcional, los IDs de 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 devolverá un identificador de conexión.

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

Parámetros

Muestra

  • Promise<ConnectionHandle[]>

    Chrome 116 y versiones posteriores

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

getConfiguration()

Promise 
chrome.usb.getConfiguration(
  handle: ConnectionHandle,
  callback?: function,
): Promise<ConfigDescriptor>

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

Parámetros

Muestra

  • Chrome 116 y versiones posteriores

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

getConfigurations()

Promise Chrome 47 y versiones posteriores 
chrome.usb.getConfigurations(
  device: Device,
  callback?: function,
): Promise<ConfigDescriptor[]>

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

Parámetros

Muestra

  • Promise<ConfigDescriptor[]>

    Chrome 116 y versiones posteriores

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

getDevices()

Promise 
chrome.usb.getDevices(
  options: EnumerateDevicesOptions,
  callback?: function,
): Promise<Device[]>

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

  • Promise<Device[]>

    Chrome 116 y versiones posteriores

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

getUserSelectedDevices()

Promise 
chrome.usb.getUserSelectedDevices(
  options: DevicePromptOptions,
  callback?: function,
): Promise<Device[]>

Presenta un selector de dispositivos al usuario y devuelve los Device seleccionados. Si el usuario cancela el selector, los dispositivos 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 la acción.

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 en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

interruptTransfer()

Promise 
chrome.usb.interruptTransfer(
  handle: ConnectionHandle,
  transferInfo: GenericTransferInfo,
  callback?: function,
): Promise<TransferResultInfo>

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

Parámetros

Muestra

  • Chrome 116 y versiones posteriores

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

isochronousTransfer()

Promise 
chrome.usb.isochronousTransfer(
  handle: ConnectionHandle,
  transferInfo: IsochronousTransferInfo,
  callback?: function,
): Promise<TransferResultInfo>

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

Parámetros

Muestra

  • Chrome 116 y versiones posteriores

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

listInterfaces()

Promise 
chrome.usb.listInterfaces(
  handle: ConnectionHandle,
  callback?: function,
): Promise<InterfaceDescriptor[]>

Enumera todas las interfaces de un dispositivo USB.

Parámetros

Muestra

  • Chrome 116 y versiones posteriores

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

openDevice()

Promise 
chrome.usb.openDevice(
  device: Device,
  callback?: function,
): Promise<ConnectionHandle>

Abre un dispositivo USB que devuelve getDevices.

Parámetros

Muestra

  • Chrome 116 y versiones posteriores

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

releaseInterface()

Promise 
chrome.usb.releaseInterface(
  handle: ConnectionHandle,
  interfaceNumber: number,
  callback?: function,
): Promise<void>

Libera una interfaz reclamada.

Parámetros

  • Una conexión abierta al dispositivo

  • interfaceNumber

    número

    Es la interfaz que se liberará.

  • callback

    función opcional

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

    () => void

Muestra

  • Promise<void>

    Chrome 116 y versiones posteriores

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

requestAccess()

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

Esta función era específica de ChromeOS y, si se llamaba en otras plataformas, fallaba. Esta operación ahora se realiza de forma implícita como parte de openDevice, y esta función devolverá true en todas las plataformas.

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

Parámetros

  • dispositivo

    Dispositivo

    El Device al que se solicitará acceso.

  • interfaceId

    número

    La interfaz particular solicitada.

  • callback

    función opcional

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

    (success: boolean) => void

    • éxito

      booleano

Muestra

  • Promise<boolean>

    Chrome 116 y versiones posteriores

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

resetDevice()

Promise 
chrome.usb.resetDevice(
  handle: ConnectionHandle,
  callback?: function,
): Promise<boolean>

Intenta restablecer el dispositivo USB. Si el restablecimiento falla, se cerrará el controlador de conexión proporcionado y el dispositivo USB aparecerá como 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

  • Es un controlador de conexión que se restablecerá.

  • callback

    función opcional

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

    (success: boolean) => void

    • éxito

      booleano

Muestra

  • Promise<boolean>

    Chrome 116 y versiones posteriores

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

setConfiguration()

Promise 
chrome.usb.setConfiguration(
  handle: ConnectionHandle,
  configurationValue: number,
  callback?: function,
): Promise<void>

Selecciona una configuración del dispositivo.

Esta función restablece el dispositivo de manera eficaz seleccionando uno de los parámetros de configuración disponibles. Solo son válidos los valores de configuración superiores a 0. Sin embargo, algunos dispositivos con errores tienen una configuración de trabajo 0, 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

  • Promise<void>

    Chrome 116 y versiones posteriores

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

setInterfaceAlternateSetting()

Promise 
chrome.usb.setInterfaceAlternateSetting(
  handle: ConnectionHandle,
  interfaceNumber: number,
  alternateSetting: number,
  callback?: function,
): Promise<void>

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

Parámetros

  • Es una conexión abierta al dispositivo en el que se reclamó esta interfaz.

  • interfaceNumber

    número

    Es la interfaz que se configurará.

  • alternateSetting

    número

    Es 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

  • Promise<void>

    Chrome 116 y versiones posteriores

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

Eventos

onDeviceAdded

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

Es el 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,
)

Es el evento que se genera cuando se quita un dispositivo del sistema. Consulta onDeviceAdded para saber qué eventos se entregan.

Parámetros

  • callback

    función

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

    (device: Device) => void