Leer y escribir en un puerto en serie

La API de Web Serial permite que los sitios web se comuniquen con dispositivos en serie.

François Beaufort

¿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 a los sitios web una forma de leer y escribir desde un dispositivo en serie con JavaScript. Los dispositivos en serie se conectan a través de un puerto en serie en el sistema del usuario o a través de dispositivos USB y Bluetooth extraíbles que emulan un puerto en serie.

En otras palabras, la API de Web Serial une la Web y el mundo físico, ya que permite que los sitios web se comuniquen con dispositivos en serie, como microcontroladores e impresoras 3D.

Esta API también es un excelente complemento para WebUSB, ya que los sistemas operativos requieren que las aplicaciones se comuniquen con algunos puertos en serie usando su API en serie de nivel superior en lugar de la API de USB de nivel inferior.

Casos de uso sugeridos

En los sectores educativo, industrial y de aficionados, los usuarios conectan dispositivos periféricos a sus computadoras. Estos dispositivos suelen controlarse con microcontroladores con una conexión en serie que usa software personalizado. Algunos software personalizados para controlar estos dispositivos se compilan con tecnología web:

• Arduino Create
• Configurador de Betaflight
• IDE web de Espruino
• Microsoft MakeCode

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. En otros casos, el usuario debe realizar un paso adicional, como copiar una aplicación compilada en el dispositivo a través de una unidad flash USB.

En todos estos casos, la experiencia del usuario mejorará si se proporciona comunicación directa entre el sitio web y el dispositivo que controla.

Estado actual

Usa la API de Web Serial

Detección de funciones

Para verificar si se admite la API de Web Serial, usa lo siguiente:

if ("serial" in navigator) {
  // The Web Serial API is supported.
}

Abre un puerto en serie

La API de Web Serial es asíncrona por diseño. Esto evita que la IU del sitio web se bloquee cuando espera la entrada, lo que es importante porque los datos en serie se pueden recibir en cualquier momento, lo que requiere una forma de escucharlos.

Para abrir un puerto en serie, primero accede a un objeto SerialPort. Para ello, puedes solicitar al usuario que seleccione un solo puerto en serie llamando a navigator.serial.requestPort() en respuesta a un gesto del usuario, como un toque o un clic del mouse, o elegir uno de navigator.serial.getPorts(), que muestra una lista de puertos en serie a los que se le otorgó acceso al 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. Se usan para hacer coincidir cualquier dispositivo en serie conectado a través de USB con un proveedor de USB obligatorio (usbVendorId) y los identificadores de producto USB opcionales (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();

Si llamas a requestPort(), se le solicita al usuario que seleccione un dispositivo y se muestra un objeto SerialPort. Una vez que tengas un objeto SerialPort, si llamas a port.open() con la velocidad de transmisión deseada, se abrirá el puerto en serie. El miembro del diccionario baudRate especifica la velocidad con la que 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 incomprensibles 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 opciones que se muestran a continuación cuando abres un puerto en serie. Estas opciones son opcionales y tienen valores predeterminados convenientes.

• dataBits: Es la cantidad de bits de datos por fotograma (7 u 8).
• stopBits: Es la cantidad de bits de detención al final de un fotograma (1 o 2).
• parity: Es el modo de paridad (ya sea "none", "even" o "odd").
• bufferSize: Es el tamaño de los búferes de lectura y escritura que se deben crear (debe ser inferior a 16 MB).
• flowControl: Es el modo de control de flujo (ya sea "none" o "hardware").

Lee desde un puerto en serie

Los flujos de entrada y salida en la API de Web Serial se controlan con la API de Streams.

Una vez que se establece la conexión del puerto en serie, las readable y writable propiedades del objeto SerialPort muestran un ReadableStream y un WritableStream. Se usarán para recibir datos del dispositivo en serie y enviarlos a él. Ambos 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: el value y un booleano done. Si done es verdadero, se cerró el puerto en serie o no hay más datos. Si llamas a port.readable.getReader(), se crea un lector y se bloquea readable a él. Mientras readable esté bloqueado, no se podrá cerrar el puerto en serie.

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);
}

En algunas condiciones, pueden ocurrir algunos errores de lectura del puerto en serie no fatales, como desbordamiento de búfer, errores de encuadre o errores de paridad. Se arrojan como excepciones y se pueden detectar agregando otro bucle sobre el anterior que verifica port.readable. Esto funciona porque, mientras los errores no sean fatales, se creará automáticamente un nuevo ReadableStream. Si se produce un error fatal, como la eliminación del dispositivo en serie, port.readable se convierte en 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, puedes canalizar port.readable a través de un TextDecoderStream, como se muestra a continuación. Un TextDecoderStream es un flujo de transformación que toma todos los fragmentos de 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 desde el flujo con un lector "Bring Your Own Buffer". Llama a port.readable.getReader({ mode: "byob" }) para obtener la interfaz ReadableStreamBYOBReader y proporciona 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 reutilizar 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 de 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 datos a port.writable.getWriter().write(). Es necesario 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");

Cierra 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 lector y escritor respectivos.

await port.close();

Sin embargo, cuando se leen datos de forma continua desde un dispositivo en serie con un bucle, port.readable siempre estará bloqueado hasta que encuentre un error. En este caso, si llamas a reader.cancel(), se forzará a reader.read() a resolver de inmediato con { value: undefined, done: true } y, por lo tanto, se 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 flujos de transformación. Llama a reader.cancel() como antes. Luego, llama a writer.close() y port.close(). Esto propaga errores a través de los flujos de transformación al puerto en serie subyacente. Como la propagación de errores no ocurre de inmediato, debes usar las promesas readableStreamClosed y writableStreamClosed creadas anteriormente para detectar cuándo se desbloquearon port.readable y port.writable. Si cancelas el reader, se anulará el flujo; por eso, debes detectar y omitir 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();

Escucha la conexión y la desconexión

Si un dispositivo USB proporciona un puerto en serie, ese dispositivo se puede conectar o desconectar del sistema. Cuando se le otorga permiso al sitio web 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.
});

Controla los indicadores

Después de establecer la conexión del puerto en serie, puedes consultar y configurar de forma explícita los indicadores expuestos por el puerto en serie para la detección de dispositivos 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 el indicador Data Terminal Ready (DTR).

Para configurar los indicadores de salida y obtener los indicadores de entrada, se hace respectivamente llamando a port.setSignals() y port.getSignals(). Consulta los ejemplos de uso a continuación.

// 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 flujos

Cuando recibes datos del dispositivo en serie, no necesariamente obtendrás todos los datos a la vez. Es posible que se dividan de forma arbitraria. Para obtener más información, consulta los conceptos de la API de Streams .

Para solucionar este problema, puedes usar algunos flujos de transformación integrados, como TextDecoderStream, o crear tu propio flujo de transformación que te permita analizar el flujo entrante y mostrar datos analizados. El flujo de transformación se encuentra entre el dispositivo en serie y el bucle de lectura que consume el flujo. Puede aplicar una transformación arbitraria antes de que se consuman los datos. Piensa en ello como una línea de ensamblaje: a medida que un widget baja por la línea, cada paso de la línea lo modifica, de modo que, cuando llega a su destino final, es un widget completamente funcional.

Por ejemplo, considera cómo crear una clase de flujo de transformación que consuma un flujo y lo divida en función de los saltos de línea. Se llama a su método transform() cada vez que el flujo recibe datos nuevos. Puede poner en cola los datos o guardarlos para más adelante. Se llama al método flush() cuando se cierra el flujo y controla los datos que aún no se procesaron.

Para usar la clase de flujo de transformación, debes canalizar un flujo entrante a través de ella. En el tercer ejemplo de código en Leer desde un puerto en serie, el flujo 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 los flujos que van hacia o desde el dispositivo en serie. Los dos flujos creados se pueden consumir de forma independiente, lo que te permite imprimir uno 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.

Revoca el acceso a un puerto en serie

El sitio web puede limpiar los permisos para acceder a un puerto en serie que ya no le interesa conservar llamando a forget() en la instancia SerialPort. Por ejemplo, para 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 mala experiencia del usuario.

// Voluntarily revoke access to this serial port.
await port.forget();

Como 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

Depurar 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 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 para mostrar imágenes en su matriz LED de 5x5.

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, la compatibilidad con puertos en serie basados en USB es posible con la API de WebUSB y el polyfill de la API de Serial. Este polyfill se limita al hardware y las plataformas en las que se puede acceder al dispositivo a través de la API de WebUSB, ya que no fue reclamado por un controlador de dispositivo integrado.

Seguridad y privacidad

Los autores de la especificación diseñaron e implementaron la API de Web Serial con los principios básicos definidos en Controlar el acceso a funciones potentes de la plataforma web, incluidos el control del usuario, la transparencia y la ergonomía. La capacidad de usar esta API se limita principalmente a un modelo de permisos que otorga acceso a un solo dispositivo en serie a la vez. En respuesta a una solicitud del usuario, este debe tomar medidas activas para seleccionar un dispositivo en serie en particular.

Para comprender las compensaciones de seguridad, consulta las secciones de seguridad y privacidad del Explicador 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 en la API que no funciona como se espera? ¿O faltan métodos o propiedades que necesitas para implementar tu idea?

Informa un problema de especificación en el repositorio de GitHub de la API de Web Serial o agrega tus opiniones a un problema existente.

Informa un problema con la implementación

¿Encontraste un error en la implementación de Chrome? ¿O la implementación es diferente de la especificación?

Informa un error en https://new.crbug.com. Asegúrate de incluir la mayor cantidad de detalles posible, proporcionar instrucciones sencillas para reproducir el error y configurar Components en Blink>Serial.

Expresar apoyo

¿Planeas usar la API de Web Serial? Tu apoyo público ayuda al equipo de Chrome a priorizar funciones y muestra a otros proveedores de navegadores lo fundamental que es admitirlas.

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

• Terminal en serie
• WebSerial
• IDE web de Espruino

Agradecimientos

Gracias a Reilly Grant y Joe Medley por sus revisiones de este documento.