chrome.usb

Descripción

Usa la API de chrome.usb para interactuar con 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 registran 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

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

    cadena opcional

    Es la descripción de la configuración.

  • extra_data

    ArrayBuffer

    Son datos adicionales del descriptor asociados a esta configuración.

  • interfaces

    InterfaceDescriptor[]

    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 su propia fuente de alimentación.

ConnectionHandle

Propiedades

  • handle

    número

    Es un identificador opaco que representa esta conexión con el dispositivo USB y todas las interfaces reclamadas asociadas y las transferencias pendientes. Se crea un nuevo identificador 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 son obligatorios para las transferencias de salida).

  • dirección

    Dirección

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

  • índice

    número

    El campo wIndex, consulta Ibid.

  • longitud

    número opcional

    Cantidad máxima de bytes que se pueden recibir (solo se requiere para las transferencias de entrada).

  • destinatario

    Destinatario

    Es el destino de la transferencia. El objetivo proporcionado por index se debe reclamar si es "interface" o "endpoint".

  • solicitud

    número

    El campo bRequest, consulta Universal Serial Bus Specification Revision 1.1 § 9.3.

  • 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. Permanece sin cambios 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.

  • version

    número

    Chrome 51 y versiones posteriores

    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

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

  • interfaceSubclass

    número opcional

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

  • productId

    número opcional

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

  • vendorId

    número opcional

    ID del proveedor del dispositivo.

DevicePromptOptions

Propiedades

  • filtros

    DeviceFilter[] opcional

    Filtra la lista de dispositivos que se le 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

    Es la dirección del extremo.

  • dirección

    Dirección

    Es la dirección de la transferencia.

  • extra_data

    ArrayBuffer

    Son datos adicionales del descriptor asociados con este extremo.

  • maximumPacketSize

    número

    Es el tamaño máximo del paquete.

  • pollingInterval

    número opcional

    Intervalo de sondeo (solo para interrupciones y datos isócronos).

  • sincronización

    SynchronizationType opcional

    Modo de sincronización de transferencia (solo isócrono).

  • Tipo de transferencia.

  • uso

    UsageType opcional

    Es una sugerencia de uso del extremo.

EnumerateDevicesAndRequestAccessOptions

Propiedades

  • interfaceId

    número opcional

    Es el ID de la interfaz a la que se solicita 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

    número opcional

    Obsoleto

    Equivale a configurar DeviceFilter.productId.

  • vendorId

    número opcional

    Obsoleto

    Equivale a configurar DeviceFilter.vendorId.

GenericTransferInfo

Propiedades

  • datos

    ArrayBuffer opcional

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

  • dirección

    Dirección

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

  • extremo

    número

    Es la dirección del extremo de destino. La interfaz que contiene este extremo debe reclamarse.

  • longitud

    número opcional

    Cantidad máxima de bytes que se pueden recibir (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

    Número de ajuste alternativo de la interfaz (el valor predeterminado es 0)

  • descripción

    cadena opcional

    Es la descripción de la interfaz.

  • extremos

    EndpointDescriptor[]

    Son los extremos disponibles.

  • extra_data

    ArrayBuffer

    Son datos de descriptores 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 la interfaz USB.

  • interfaceSubclass

    número

    Subclase de la interfaz USB.

IsochronousTransferInfo

Propiedades

  • packetLength

    número

    Es 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

    Son los 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

"device"

"interface"

"endpoint"

"other"

RequestType

Enum

"standard"

"class"

"vendor"

"reserved"

SynchronizationType

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

Enum

"asynchronous"

"adaptive"

"síncrono"

TransferResultInfo

Propiedades

  • datos

    ArrayBuffer opcional

    Son los datos que devuelve una transferencia de entrada. undefined para 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"

"isochronous"

"bulk"

UsageType

Enum

"data"

"feedback"

"explicitFeedback"

"periodic"

"notification"

Métodos

bulkTransfer()

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

Realiza una transferencia masiva en el dispositivo especificado.

Parámetros

Muestra

  • Promesa de TransferResultInfo

    Chrome 116 y versiones posteriores

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

claimInterface()

Promesa 
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 los extremos asociados, se debe reclamar la interfaz. Solo un identificador de conexión puede reclamar una interfaz en un momento dado. Si la interfaz ya se reclamó, 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()

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

Cierra un identificador 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()

Promesa 
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, a una interfaz o a un extremo. Las transferencias a una interfaz o un extremo requieren que se reclame la interfaz.

Parámetros

Muestra

  • Promesa de TransferResultInfo

    Chrome 116 y versiones posteriores

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

findDevices()

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

Busca dispositivos USB especificados por los IDs de proveedor, producto y (opcionalmente) 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 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()

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

Obtiene el descriptor de configuración para 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()

Promesa 
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 objetivo.

  • 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()

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

Presenta un selector de dispositivos al usuario y devuelve los Devices 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

  • Es la 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()

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

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

Parámetros

Muestra

  • Promesa de TransferResultInfo

    Chrome 116 y versiones posteriores

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

isochronousTransfer()

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

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

Parámetros

Muestra

  • Promesa de TransferResultInfo

    Chrome 116 y versiones posteriores

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

listInterfaces()

Promesa 
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()

Promesa 
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()

Promesa 
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 llamarla en otras plataformas generaría un error. 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 desde el agente de permisos a un dispositivo reclamado por ChromeOS si no se reclamó la interfaz determinada en el dispositivo.

Parámetros

  • dispositivo

    Dispositivo

    Es el Device al que se solicita acceso.

  • interfaceId

    número

    Es la interfaz específica que se solicitó.

  • callback

    función opcional

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

    (success: boolean) => void

    • correcto

      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()

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

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

Parámetros

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

  • callback

    función opcional

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

    (success: boolean) => void

    • correcto

      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()

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

Selecciona la configuración de un dispositivo.

Esta función restablece el dispositivo de manera eficaz seleccionando una de las configuraciones disponibles del dispositivo. Sin embargo, solo son válidos los valores de configuración mayores que 0, pero 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

  • 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()

Promesa 
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 previamente.

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 configurará.

  • 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,
)

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