La API de Web Serial permite que los sitios web se comuniquen con dispositivos en serie.
¿Qué es la API de Web Serial?
Un puerto en serie es una interfaz de comunicación bidireccional que permite enviar y recibir datos byte por byte.
La API de Web Serial proporciona una forma para que los sitios web lean y escriban en un dispositivo en serie con JavaScript. Los dispositivos en serie se conectan a través de un puerto en serie del sistema del usuario o mediante dispositivos USB y Bluetooth extraíbles que emulan un puerto en serie.
En otras palabras, la API de Web Serial conecta el mundo físico con la Web y permite que los sitios web se comuniquen con dispositivos en serie, como impresoras 3D y microcontroladores.
Esta API también es un gran complemento para WebUSB, ya que los sistemas operativos requieren que las aplicaciones se comuniquen con algunos puertos en serie mediante su API en serie de nivel superior en lugar de la API de USB de bajo nivel.
Casos de uso sugeridos
En los sectores educativo, industrial y de aficionados, los usuarios conectan dispositivos periféricos a sus computadoras. Estos dispositivos suelen ser controlados por microcontroladores a través de una conexión en serie que utiliza un software personalizado. Algunos software personalizados para controlar estos dispositivos se compilan con tecnología web:
En algunos casos, los sitios web se comunican con el dispositivo a través de una aplicación de agente que los usuarios instalaron de forma manual. En otros, la aplicación se entrega en una aplicación empaquetada a través de un framework como Electron. Y en otros, el usuario debe realizar un paso adicional, como copiar una aplicación compilada en el dispositivo a través de una unidad de memoria flash USB.
En todos estos casos, la experiencia del usuario mejorará si se proporciona una comunicación directa entre el sitio web y el dispositivo que controla.
Estado actual
| Step | Estado |
|---|---|
| 1. Crear explicación | Completo |
| 2. Crea el borrador inicial de la especificación | Completo |
| 3. Recopila comentarios e itera en el diseño | Completo |
| 4. Prueba de origen | Completo |
| 5. Lanzamiento | Completo |
Usa la API de Web Serial
Detección de funciones
Para verificar si la API de Web Serial es compatible, usa lo siguiente:
if ("serial" in navigator) {
// The Web Serial API is supported.
}
Cómo abrir un puerto en serie
La API de Web Serial tiene un diseño asíncrono. Esto evita que la IU del sitio web se bloquee cuando se espera la entrada, lo cual es importante porque los datos en serie se pueden recibir en cualquier momento y se requiere una forma de escucharlos.
Para abrir un puerto en serie, primero accede a un objeto SerialPort. Para ello, puedes pedirle al usuario que seleccione un solo puerto en serie llamando a navigator.serial.requestPort() en respuesta a un gesto del usuario, como tocar o hacer clic con el mouse, o elegir uno de navigator.serial.getPorts(), que muestra una lista de puertos en serie a los que tiene acceso el sitio web.
document.querySelector('button').addEventListener('click', async () => {
// Prompt user to select any serial port.
const port = await navigator.serial.requestPort();
});
// Get all serial ports the user has previously granted the website access to.
const ports = await navigator.serial.getPorts();
La función navigator.serial.requestPort() toma un literal de objeto opcional que define filtros. Estos se usan para vincular cualquier dispositivo en serie conectado a través de USB con un proveedor USB obligatorio (usbVendorId) e identificadores opcionales de productos USB (usbProductId).
// Filter on devices with the Arduino Uno USB Vendor/Product IDs.
const filters = [
{ usbVendorId: 0x2341, usbProductId: 0x0043 },
{ usbVendorId: 0x2341, usbProductId: 0x0001 }
];
// Prompt user to select an Arduino Uno device.
const port = await navigator.serial.requestPort({ filters });
const { usbProductId, usbVendorId } = port.getInfo();
La llamada a requestPort() le solicita al usuario que seleccione un dispositivo y devuelve un objeto SerialPort. Una vez que tengas un objeto SerialPort, si llamas a port.open() con la tasa de baudios deseada, se abrirá el puerto en serie. El miembro del diccionario baudRate especifica qué tan rápido se envían los datos a través de una línea en serie. Se expresa en unidades de bits por segundo (bps). Consulta la documentación de tu dispositivo para obtener el valor correcto, ya que todos los datos que envíes y recibas serán incoherentes si se especifica de forma incorrecta. Para algunos dispositivos USB y Bluetooth que emulan un puerto en serie, este valor se puede establecer de forma segura en cualquier valor, ya que la emulación lo ignora.
// Prompt user to select any serial port.
const port = await navigator.serial.requestPort();
// Wait for the serial port to open.
await port.open({ baudRate: 9600 });
También puedes especificar cualquiera de las siguientes opciones cuando abres un puerto en serie. Estas opciones son opcionales y tienen valores predeterminados convenientes.
dataBits: Es la cantidad de bits de datos por trama (7 u 8).stopBits: Es la cantidad de bits de parada al final de una trama (1 o 2).parity: Es el modo de paridad ("none","even"o"odd").bufferSize: El tamaño de los búferes de lectura y escritura que se deben crear (debe ser menor que 16 MB).flowControl: Es el modo de control de flujo ("none"o"hardware").
Leer desde un puerto en serie
La API de Streams controla las transmisiones de entrada y salida en la API de Web Serial.
Después de establecer la conexión del puerto en serie, las propiedades readable y writable del objeto SerialPort muestran un ReadableStream y un WritableStream. Se usarán para recibir datos del dispositivo en serie y enviarlos al
dispositivo en serie. Ambas usan instancias de Uint8Array para la transferencia de datos.
Cuando llegan datos nuevos del dispositivo en serie, port.readable.getReader().read() muestra dos propiedades de forma asíncrona: value y un valor booleano done. Si done es verdadero, el puerto en serie se cerró o no hay más datos entrando. Llamar a port.readable.getReader() crea un lector y bloquea readable en él. Mientras readable esté bloqueado, el puerto en serie no se puede cerrar.
const reader = port.readable.getReader();
// Listen to data coming from the serial device.
while (true) {
const { value, done } = await reader.read();
if (done) {
// Allow the serial port to be closed later.
reader.releaseLock();
break;
}
// value is a Uint8Array.
console.log(value);
}
Algunos errores recuperables de lectura del puerto en serie pueden ocurrir en algunas condiciones, como el desbordamiento del búfer, los errores de encuadre o los errores de paridad. Estas se arrojan como
excepciones y se pueden detectar si agregas otro bucle sobre el anterior
que verifique port.readable. Esto funciona porque, siempre que los errores sean recuperables, se creará automáticamente un ReadableStream nuevo. Si se produce un error irrecuperable, por ejemplo, si se quita el dispositivo en serie, port.readable será nulo.
while (port.readable) {
const reader = port.readable.getReader();
try {
while (true) {
const { value, done } = await reader.read();
if (done) {
// Allow the serial port to be closed later.
reader.releaseLock();
break;
}
if (value) {
console.log(value);
}
}
} catch (error) {
// TODO: Handle non-fatal read error.
}
}
Si el dispositivo en serie envía texto de vuelta, puedes canalizar port.readable a través de un TextDecoderStream como se muestra a continuación. Un TextDecoderStream es un flujo de transformaciones que toma todos los fragmentos Uint8Array y los convierte en cadenas.
const textDecoder = new TextDecoderStream();
const readableStreamClosed = port.readable.pipeTo(textDecoder.writable);
const reader = textDecoder.readable.getReader();
// Listen to data coming from the serial device.
while (true) {
const { value, done } = await reader.read();
if (done) {
// Allow the serial port to be closed later.
reader.releaseLock();
break;
}
// value is a string.
console.log(value);
}
Puedes controlar cómo se asigna la memoria cuando lees de la transmisión mediante un lector del tipo "Bring Your Own Buffer". Llama a port.readable.getReader({ mode: "byob" }) para obtener la interfaz ReadableStreamBYOBReader y proporcionar tu propio ArrayBuffer cuando llames a read(). Ten en cuenta que la API de Web Serial admite esta función en Chrome 106 o versiones posteriores.
try {
const reader = port.readable.getReader({ mode: "byob" });
// Call reader.read() to read data into a buffer...
} catch (error) {
if (error instanceof TypeError) {
// BYOB readers are not supported.
// Fallback to port.readable.getReader()...
}
}
Este es un ejemplo de cómo volver a usar el búfer de value.buffer:
const bufferSize = 1024; // 1kB
let buffer = new ArrayBuffer(bufferSize);
// Set `bufferSize` on open() to at least the size of the buffer.
await port.open({ baudRate: 9600, bufferSize });
const reader = port.readable.getReader({ mode: "byob" });
while (true) {
const { value, done } = await reader.read(new Uint8Array(buffer));
if (done) {
break;
}
buffer = value.buffer;
// Handle `value`.
}
Este es otro ejemplo de cómo leer una cantidad específica de datos desde un puerto en serie:
async function readInto(reader, buffer) {
let offset = 0;
while (offset < buffer.byteLength) {
const { value, done } = await reader.read(
new Uint8Array(buffer, offset)
);
if (done) {
break;
}
buffer = value.buffer;
offset += value.byteLength;
}
return buffer;
}
const reader = port.readable.getReader({ mode: "byob" });
let buffer = new ArrayBuffer(512);
// Read the first 512 bytes.
buffer = await readInto(reader, buffer);
// Then read the next 512 bytes.
buffer = await readInto(reader, buffer);
Escribe en un puerto en serie
Para enviar datos a un dispositivo en serie, pasa los datos a port.writable.getWriter().write(). Se requiere llamar a releaseLock() en port.writable.getWriter() para que el puerto en serie se cierre más tarde.
const writer = port.writable.getWriter();
const data = new Uint8Array([104, 101, 108, 108, 111]); // hello
await writer.write(data);
// Allow the serial port to be closed later.
writer.releaseLock();
Envía texto al dispositivo a través de un TextEncoderStream canalizado a port.writable, como se muestra a continuación.
const textEncoder = new TextEncoderStream();
const writableStreamClosed = textEncoder.readable.pipeTo(port.writable);
const writer = textEncoder.writable.getWriter();
await writer.write("hello");
Cómo cerrar un puerto en serie
port.close() cierra el puerto en serie si sus miembros readable y writable están desbloqueados, lo que significa que se llamó a releaseLock() para su respectivo lector y escritor.
await port.close();
Sin embargo, cuando se leen datos de forma continua desde un dispositivo en serie mediante un bucle, port.readable siempre estará bloqueado hasta que encuentre un error. En este caso, llamar a reader.cancel() forzará a reader.read() a resolverse de inmediato con { value: undefined, done: true } y, por lo tanto, permitir que el bucle llame a reader.releaseLock().
// Without transform streams.
let keepReading = true;
let reader;
async function readUntilClosed() {
while (port.readable && keepReading) {
reader = port.readable.getReader();
try {
while (true) {
const { value, done } = await reader.read();
if (done) {
// reader.cancel() has been called.
break;
}
// value is a Uint8Array.
console.log(value);
}
} catch (error) {
// Handle error...
} finally {
// Allow the serial port to be closed later.
reader.releaseLock();
}
}
await port.close();
}
const closedPromise = readUntilClosed();
document.querySelector('button').addEventListener('click', async () => {
// User clicked a button to close the serial port.
keepReading = false;
// Force reader.read() to resolve immediately and subsequently
// call reader.releaseLock() in the loop example above.
reader.cancel();
await closedPromise;
});
Cerrar un puerto en serie es más complicado cuando se usan transmisiones de transformación. Llama a reader.cancel() como antes.
Luego, llama a writer.close() y port.close(). Esto propaga los errores a través de las transmisiones de transformación al puerto en serie subyacente. Debido a que la propagación de errores no ocurre de inmediato, debes usar las promesas readableStreamClosed y writableStreamClosed que creaste antes para detectar cuándo se desbloquearon port.readable y port.writable. La cancelación de reader provoca que se anule la transmisión. Por este motivo, debes identificar y, además, ignorar el error resultante.
// With transform streams.
const textDecoder = new TextDecoderStream();
const readableStreamClosed = port.readable.pipeTo(textDecoder.writable);
const reader = textDecoder.readable.getReader();
// Listen to data coming from the serial device.
while (true) {
const { value, done } = await reader.read();
if (done) {
reader.releaseLock();
break;
}
// value is a string.
console.log(value);
}
const textEncoder = new TextEncoderStream();
const writableStreamClosed = textEncoder.readable.pipeTo(port.writable);
reader.cancel();
await readableStreamClosed.catch(() => { /* Ignore the error */ });
writer.close();
await writableStreamClosed;
await port.close();
Detectar conexión y desconexión
Si un dispositivo USB proporciona un puerto en serie, este puede conectarse o desconectarse del sistema. Cuando el sitio web tiene permiso para acceder a un puerto en serie, debe supervisar los eventos connect y disconnect.
navigator.serial.addEventListener("connect", (event) => {
// TODO: Automatically open event.target or warn user a port is available.
});
navigator.serial.addEventListener("disconnect", (event) => {
// TODO: Remove |event.target| from the UI.
// If the serial port was opened, a stream error would be observed as well.
});
Cómo controlar las señales
Después de establecer la conexión del puerto en serie, puedes consultar y configurar de forma explícita las señales que expone el puerto en serie para la detección del dispositivo y el control de flujo. Estos indicadores se definen como valores booleanos. Por ejemplo, algunos dispositivos, como Arduino, ingresarán a un modo de programación si se activa o desactiva la señal de terminal de datos lista (DTR).
La configuración de los indicadores de salida y la obtención de los indicadores de entrada se realizan respectivamente con una llamada a port.setSignals() y port.getSignals(). Consulta los siguientes ejemplos de uso.
// Turn off Serial Break signal.
await port.setSignals({ break: false });
// Turn on Data Terminal Ready (DTR) signal.
await port.setSignals({ dataTerminalReady: true });
// Turn off Request To Send (RTS) signal.
await port.setSignals({ requestToSend: false });
const signals = await port.getSignals();
console.log(`Clear To Send: ${signals.clearToSend}`);
console.log(`Data Carrier Detect: ${signals.dataCarrierDetect}`);
console.log(`Data Set Ready: ${signals.dataSetReady}`);
console.log(`Ring Indicator: ${signals.ringIndicator}`);
Transformación de transmisiones
Cuando recibas datos del dispositivo en serie, no necesariamente obtendrás todos los datos de una sola vez. Es posible que se fragmente de manera arbitraria. Para obtener más información, consulta Conceptos de la API de Streams.
Para solucionarlo, puedes usar algunas transmisiones de transformaciones integradas, como TextDecoderStream, o crear tu propia transmisión de transformaciones que te permita analizar la transmisión entrante y mostrar los datos analizados. La transmisión de transformación se encuentra entre el dispositivo en serie y el bucle de lectura que consume la transmisión. Puede aplicar una transformación arbitraria antes de que se consuman los datos. Considéralo una línea de ensamble: a medida que un widget baja en la línea, cada paso de la línea modifica el widget, de modo que, cuando llega a su destino final, es un widget completamente funcional.
Por ejemplo, considera cómo crear una clase de transmisión de transformación que consuma una transmisión y la fragmente en función de saltos de línea. Cada vez que la transmisión recibe datos nuevos, se llama a su método transform(). Puede poner los datos en cola o
guardarlos para más tarde. Se llama al método flush() cuando se cierra la transmisión, y este controla cualquier dato que aún no se haya procesado.
Para usar la clase de transmisión de transformación, debes canalizar una transmisión entrante a través de ella. En el tercer ejemplo de código en Leer desde un puerto en serie, la transmisión de entrada original solo se canalizó a través de un TextDecoderStream, por lo que debemos llamar a pipeThrough() para canalizarlo a través de nuestro nuevo LineBreakTransformer.
class LineBreakTransformer {
constructor() {
// A container for holding stream data until a new line.
this.chunks = "";
}
transform(chunk, controller) {
// Append new chunks to existing chunks.
this.chunks += chunk;
// For each line breaks in chunks, send the parsed lines out.
const lines = this.chunks.split("\r\n");
this.chunks = lines.pop();
lines.forEach((line) => controller.enqueue(line));
}
flush(controller) {
// When the stream is closed, flush any remaining chunks out.
controller.enqueue(this.chunks);
}
}
const textDecoder = new TextDecoderStream();
const readableStreamClosed = port.readable.pipeTo(textDecoder.writable);
const reader = textDecoder.readable
.pipeThrough(new TransformStream(new LineBreakTransformer()))
.getReader();
Para depurar problemas de comunicación de dispositivos en serie, usa el método tee() de port.readable para dividir las transmisiones que van hacia o desde el dispositivo en serie. Las dos transmisiones creadas se pueden consumir de forma independiente y esto te permite imprimir una en la consola para su inspección.
const [appReadable, devReadable] = port.readable.tee();
// You may want to update UI with incoming data from appReadable
// and log incoming data in JS console for inspection from devReadable.
Revocar el acceso a un puerto en serie
El sitio web puede liberar permisos para acceder a un puerto en serie que ya no está interesado en conservar llamando a forget() en la instancia SerialPort. Por ejemplo, en el caso de una aplicación web educativa que se usa en una computadora compartida con muchos dispositivos, una gran cantidad de permisos acumulados generados por el usuario crea una experiencia del usuario deficiente.
// Voluntarily revoke access to this serial port.
await port.forget();
Dado que forget() está disponible en Chrome 103 o versiones posteriores, verifica si esta función es compatible con lo siguiente:
if ("serial" in navigator && "forget" in SerialPort.prototype) {
// forget() is supported.
}
Sugerencias para desarrolladores
La depuración de la API de Web Serial en Chrome es fácil con la página interna, about://device-log, en la que puedes ver todos los eventos relacionados con los dispositivos en serie en un solo lugar.
Codelab
En el codelab de Google Developers, usarás la API de Web Serial para interactuar con una placa micro:bit de BBC y mostrar imágenes en su matriz LED de 5 × 5.
Navegadores compatibles
La API de Web Serial está disponible en todas las plataformas de escritorio (ChromeOS, Linux, macOS y Windows) en Chrome 89.
Polyfill
En Android, es posible admitir puertos en serie basados en USB a través de la API de WebUSB y el polyfill de la API de Serial. Este polyfill se limita al hardware y las plataformas en los que se puede acceder al dispositivo a través de la API de WebUSB, ya que no lo reclamó ningún controlador integrado.
Seguridad y privacidad
Los autores de las especificaciones diseñaron e implementaron la API de Web Serial mediante los principios básicos definidos en Cómo controlar el acceso a funciones potentes de la plataforma web, incluidos el control de usuario, la transparencia y la ergonomía. La capacidad de usar esta API está restringida principalmente por un modelo de permisos que otorga acceso a un solo dispositivo en serie a la vez. En respuesta a la solicitud de un usuario, este debe realizar pasos activos para seleccionar un dispositivo en serie determinado.
Para comprender las compensaciones de seguridad, consulta las secciones seguridad y privacidad de la explicación de la API de Web Serial.
Comentarios
Al equipo de Chrome le encantaría conocer tus opiniones y experiencias con la API de Web Serial.
Cuéntanos sobre el diseño de la API
¿Hay algo acerca de la API que no funciona como se espera? ¿O faltan métodos o propiedades que necesitas para implementar tu idea?
Informa sobre un problema de especificaciones en el repositorio de GitHub de la API de Web Serial o agrega lo que piensas a un problema existente.
Informar un problema con la implementación
¿Encontraste un error en la implementación de Chrome? ¿La implementación es diferente de las especificaciones?
Informa un error en https://new.crbug.com. Asegúrate de incluir todos los detalles que puedas, proporciona instrucciones simples para reproducir el error y configura los componentes como Blink>Serial. Glitch funciona muy bien para compartir repros rápidos y fáciles.
Muestra tu apoyo
¿Planeas usar la API de Web Serial? Tu apoyo público ayuda al equipo de Chrome a priorizar funciones y les muestra a otros proveedores de navegadores la importancia de brindar compatibilidad.
Envía un tweet a @ChromiumDev con el hashtag #SerialAPI y cuéntanos dónde y cómo lo usas.
Vínculos útiles
- Especificación
- Error de seguimiento
- Entrada de ChromeStatus.com
- Componente de Blink:
Blink>Serial
Demostraciones
Agradecimientos
Agradecemos a Reilly Grant y Joe Medley por sus opiniones sobre este artículo. Foto de la fábrica de aviones de Birmingham Museums Trust, en Unsplash.