Lettura e scrittura su una porta seriale

L'API Web Serial consente ai siti web di comunicare con i dispositivi seriali.

François Beaufort

Che cos'è l'API Web Serial?

Una porta seriale è un'interfaccia di comunicazione bidirezionale che consente di inviare e ricevere dati byte per byte.

L'API Web Serial consente ai siti web di leggere e scrivere su un dispositivo seriale con JavaScript. I dispositivi seriali sono collegati tramite una porta seriale sul sistema dell'utente o tramite dispositivi USB e Bluetooth rimovibili che emulano una porta seriale.

In altre parole, l'API Web Serial colma il divario tra il web e il mondo fisico consentendo ai siti web di comunicare con dispositivi seriali, come microcontrollori e stampanti 3D.

Questa API è anche un ottimo complemento di WebUSB, in quanto i sistemi operativi richiedono alle applicazioni di comunicare con alcune porte seriali utilizzando la relativa API seriale di livello superiore anziché l'API USB di basso livello.

Casi d'uso suggeriti

Nei settori dell'istruzione, degli hobby e dell'industria, gli utenti collegano dispositivi periferici ai computer. Questi dispositivi sono spesso controllati da microcontrollori con una connessione seriale utilizzata da software personalizzato. Alcuni software personalizzati per controllare questi dispositivi sono creati con la tecnologia web:

• Arduino Create
• Betaflight Configurator
• Espruino Web IDE
• Microsoft MakeCode

In alcuni casi, i siti web comunicano con il dispositivo tramite un'applicazione agente che gli utenti hanno installato manualmente. In altri casi, l'applicazione viene fornita in un'applicazione pacchettizzata tramite un framework come Electron. In altri casi, l'utente deve eseguire un passaggio aggiuntivo, ad esempio copiare un'applicazione compilata sul dispositivo tramite un'unità flash USB.

In tutti questi casi, l'esperienza utente verrà migliorata fornendo una comunicazione diretta tra il sito web e il dispositivo che sta controllando.

Stato attuale

Utilizzo dell'API Web Serial

Rilevamento delle funzionalità

Per verificare se l'API Web Serial è supportata, utilizza:

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

Apri una porta seriale

L'API Web Serial è asincrona per progettazione. In questo modo, l'interfaccia utente del sito web non viene bloccata durante l'attesa dell'input, il che è importante perché i dati seriali possono essere ricevuti in qualsiasi momento, richiedendo un modo per ascoltarli.

Per aprire una porta seriale, devi prima accedere a un oggetto SerialPort. A questo scopo, puoi chiedere all'utente di selezionare una singola porta seriale chiamando navigator.serial.requestPort() in risposta a un'attivazione dall'utente, ad esempio un tocco o un clic del mouse, oppure sceglierne una da navigator.serial.getPorts(), che restituisce un elenco di porte seriali a cui il sito web ha ricevuto l'accesso.

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 funzione navigator.serial.requestPort() accetta un oggetto letterale facoltativo che definisce i filtri. Questi vengono utilizzati per trovare la corrispondenza con qualsiasi dispositivo seriale collegato tramite USB con un fornitore USB obbligatorio (usbVendorId) e identificatori di prodotto USB facoltativi (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 chiamata a requestPort() chiede all'utente di selezionare un dispositivo e restituisce un oggetto SerialPort. Una volta ottenuto un oggetto SerialPort, la chiamata a port.open() con la velocità di trasmissione desiderata aprirà la porta seriale. Il membro del dizionario baudRate specifica la velocità di invio dei dati su una linea seriale. È espresso in unità di bit al secondo (bps). Controlla la documentazione del dispositivo per il valore corretto, poiché tutti i dati che invii e ricevi saranno incomprensibili se questo valore non è specificato correttamente. Per alcuni dispositivi USB e Bluetooth che emulano una porta seriale, questo valore può essere impostato in modo sicuro su qualsiasi valore, poiché viene ignorato dall'emulazione.

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

Puoi anche specificare una delle opzioni riportate di seguito quando apri una porta seriale. Queste opzioni sono facoltative e hanno valori predefiniti convenienti .

• dataBits: il numero di bit di dati per frame (7 o 8).
• stopBits: il numero di bit di stop alla fine di un frame (1 o 2).
• parity: la modalità di parità ("none", "even" o "odd").
• bufferSize: la dimensione dei buffer di lettura e scrittura da creare (deve essere inferiore a 16 MB).
• flowControl: la modalità di controllo del flusso ("none" o "hardware").

Leggi da una porta seriale

I flussi di input e output nell'API Web Serial vengono gestiti dall'API Streams.

Una volta stabilita la connessione alla porta seriale, le readable e writable proprietà dell'oggetto SerialPort restituiscono un ReadableStream e un WritableStream. Questi verranno utilizzati per ricevere dati dal dispositivo seriale e inviarli. Entrambi utilizzano istanze Uint8Array per il trasferimento dei dati.

Quando arrivano nuovi dati dal dispositivo seriale, port.readable.getReader().read() restituisce in modo asincrono due proprietà: value e un valore booleano done. Se done è true, la porta seriale è stata chiusa o non sono in arrivo altri dati. La chiamata a port.readable.getReader() crea un lettore e blocca readable su di esso. Mentre readable è bloccato, la porta seriale non può essere chiusa.

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

In alcune condizioni, ad esempio overflow del buffer, errori di framing o errori di parità, possono verificarsi alcuni errori di lettura della porta seriale non irreversibili. Questi vengono generati come eccezioni e possono essere intercettati aggiungendo un altro loop sopra quello precedente che controlla port.readable. Questo funziona perché, finché gli errori non sono irreversibili, viene creato automaticamente un nuovo ReadableStream. Se si verifica un errore irreversibile, ad esempio la rimozione del dispositivo seriale, port.readable diventa null.

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.
  }
}

Se il dispositivo seriale invia testo, puoi inviare port.readable tramite un TextDecoderStream, come mostrato di seguito. Un TextDecoderStream è un flusso di trasformazione che acquisisce tutti i blocchi Uint8Array e li converte in stringhe.

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

Puoi controllare l'allocazione della memoria quando leggi dal flusso utilizzando un lettore "Bring Your Own Buffer". Chiama port.readable.getReader({ mode: "byob" }) per ottenere l'interfaccia ReadableStreamBYOBReader e fornisci il tuo ArrayBuffer quando chiami read(). Tieni presente che l'API Web Serial supporta questa funzionalità in Chrome 106 o versioni successive.

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

Ecco un esempio di come riutilizzare il buffer da 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`.
}

Ecco un altro esempio di come leggere una quantità specifica di dati da una porta seriale:

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

Scrivi su una porta seriale

Per inviare dati a un dispositivo seriale, passa i dati a port.writable.getWriter().write(). Per chiudere la porta seriale in un secondo momento, è necessario chiamare releaseLock() su port.writable.getWriter().

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

Invia testo al dispositivo tramite un TextEncoderStream inviato a port.writable, come mostrato di seguito.

const textEncoder = new TextEncoderStream();
const writableStreamClosed = textEncoder.readable.pipeTo(port.writable);

const writer = textEncoder.writable.getWriter();

await writer.write("hello");

Chiudi una porta seriale

port.close() chiude la porta seriale se i membri readable e writable sono sbloccati, il che significa che è stato chiamato releaseLock() per il rispettivo lettore e scrittore.

await port.close();

Tuttavia, quando si leggono continuamente i dati da un dispositivo seriale utilizzando un loop, port.readable rimarrà sempre bloccato finché non si verifica un errore. In questo caso, la chiamata a reader.cancel() forzerà la risoluzione immediata di reader.read() con { value: undefined, done: true } e quindi consentirà al loop di chiamare 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;
});

La chiusura di una porta seriale è più complicata quando si utilizzano flussi di trasformazione. Chiama reader.cancel() come prima. Poi chiama writer.close() e port.close(). In questo modo, gli errori vengono propagati attraverso i flussi di trasformazione alla porta seriale sottostante. Poiché la propagazione degli errori non avviene immediatamente, devi utilizzare le promesse readableStreamClosed e writableStreamClosed create in precedenza per rilevare quando port.readable e port.writable sono stati sbloccati. L'annullamento del reader causa l'interruzione del flusso; per questo motivo devi intercettare e ignorare l'errore risultante.

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

Ascolta la connessione e la disconnessione

Se una porta seriale viene fornita da un dispositivo USB, questo dispositivo può essere collegato o scollegato dal sistema. Quando al sito web è stata concessa l'autorizzazione ad accedere a una porta seriale, deve monitorare gli eventi connect e 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.
});

Gestisci i segnali

Dopo aver stabilito la connessione alla porta seriale, puoi eseguire query e impostare in modo esplicito i segnali esposti dalla porta seriale per il rilevamento del dispositivo e il controllo del flusso. Questi segnali sono definiti come valori booleani. Ad esempio, alcuni dispositivi come Arduino entrano in modalità di programmazione se il segnale Data Terminal Ready (DTR) viene attivato/disattivato.

L'impostazione dei segnali di output e l'ottenimento dei segnali di input vengono eseguiti rispettivamente chiamando port.setSignals() e port.getSignals(). Vedi esempi di utilizzo di seguito.

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

Trasforma i flussi

Quando ricevi dati dal dispositivo seriale, non riceverai necessariamente tutti i dati contemporaneamente. Potrebbe essere suddiviso in blocchi arbitrari. Per maggiori informazioni, consulta i concetti dell'API Streams.

Per risolvere questo problema, puoi utilizzare alcuni flussi di trasformazione integrati, come TextDecoderStream, o creare il tuo flusso di trasformazione che ti consenta di analizzare il flusso in entrata e restituire i dati analizzati. Il flusso di trasformazione si trova tra il dispositivo seriale e il loop di lettura che utilizza il flusso. Può applicare una trasformazione arbitraria prima che i dati vengano utilizzati. Immagina una catena di montaggio: quando un widget scende lungo la linea, ogni passaggio della linea lo modifica, in modo che quando arriva alla destinazione finale sia un widget completamente funzionante.

Ad esempio, considera come creare una classe di flusso di trasformazione che utilizza un flusso e lo suddivide in blocchi in base agli interruzioni di riga. Il metodo transform() viene chiamato ogni volta che il flusso riceve nuovi dati. Può mettere in coda i dati o salvarli per un secondo momento. Il metodo flush() viene chiamato quando il flusso viene chiuso e gestisce tutti i dati che non sono ancora stati elaborati.

Per utilizzare la classe di flusso di trasformazione, devi inviare un flusso in entrata tramite questa classe. Nel terzo esempio di codice in Leggi da una porta seriale, il flusso di input originale è stato inviato solo tramite un TextDecoderStream, quindi dobbiamo chiamare pipeThrough() per inviarlo tramite il nostro nuovo 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();

Per eseguire il debug dei problemi di comunicazione del dispositivo seriale, utilizza il metodo tee() di port.readable per dividere i flussi in entrata o in uscita dal dispositivo seriale. I due flussi creati possono essere utilizzati in modo indipendente e questo ti consente di stamparne uno nella console per l'ispezione.

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 l'accesso a una porta seriale

Il sito web può ripulire le autorizzazioni per accedere a una porta seriale che non è più interessato a conservare chiamando forget() sull'istanza SerialPort. Ad esempio, per un'applicazione web didattica utilizzata su un computer condiviso con molti dispositivi, un numero elevato di autorizzazioni generate dagli utenti crea un'esperienza utente scadente.

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

Poiché forget() è disponibile in Chrome 103 o versioni successive, verifica se questa funzionalità è supportata con quanto segue:

if ("serial" in navigator && "forget" in SerialPort.prototype) {
  // forget() is supported.
}

Suggerimenti per gli sviluppatori

Il debug dell'API Web Serial in Chrome è semplice con la pagina interna about://device-log, in cui puoi visualizzare tutti gli eventi relativi ai dispositivi seriali in un unico posto.

Codelab

Nel codelab per sviluppatori di Google, utilizzerai l'API Web Serial per interagire con una scheda micro:bit BBC per mostrare le immagini sulla matrice LED 5x5.

Supporto browser

L'API Web Serial è disponibile su tutte le piattaforme desktop (ChromeOS, Linux, macOS e Windows) in Chrome 89.

Polyfill

Su Android, il supporto per le porte seriali basate su USB è possibile utilizzando l'API WebUSB e il polyfill dell'API Serial. Questo polyfill è limitato all'hardware e alle piattaforme in cui il dispositivo è accessibile tramite l'API WebUSB perché non è stato richiesto da un driver di dispositivo integrato.

Sicurezza e privacy

Gli autori delle specifiche hanno progettato e implementato l'API Web Serial utilizzando i principi fondamentali definiti in Controllo dell'accesso alle funzionalità avanzate della piattaforma web, tra cui controllo dell'utente, trasparenza ed ergonomia. La possibilità di utilizzare questa API è principalmente limitata da un modello di autorizzazione che concede l'accesso a un solo dispositivo seriale alla volta. In risposta a una richiesta dell'utente, l'utente deve eseguire passaggi attivi per selezionare un dispositivo seriale specifico.

Per comprendere i compromessi di sicurezza, consulta le sezioni relative alla sicurezza e alla privacy della spiegazione dell'API Web Serial.

Feedback

Il team di Chrome vorrebbe conoscere le tue opinioni ed esperienze con l'API Web Serial.

Parlaci della progettazione dell'API

C'è qualcosa nell'API che non funziona come previsto? Oppure mancano metodi o proprietà di cui hai bisogno per implementare la tua idea?

Segnala un problema relativo alle specifiche nel repository GitHub dell'API Web Serial o aggiungi le tue opinioni a un problema esistente.

Segnala un problema relativo all'implementazione

Hai trovato un bug nell'implementazione di Chrome? Oppure l'implementazione è diversa dalle specifiche?

Segnala un bug all'indirizzo https://new.crbug.com. Assicurati di includere il maggior numero di dettagli possibile, fornisci istruzioni semplici per riprodurre il bug e imposta Components su Blink>Serial.

Mostra il tuo sostegno

Stai pensando di utilizzare l'API Web Serial? Il tuo supporto pubblico aiuta il team di Chrome a dare la priorità alle funzionalità e mostra ad altri fornitori di browser quanto sia fondamentale supportarle.

Invia un tweet a @ChromiumDev utilizzando l'hashtag #SerialAPI e comunicaci dove e come lo utilizzi.

Link utili

• Specifiche
• Bug di monitoraggio
• Voce di ChromeStatus.com
• Componente Blink: Blink>Serial

Demo

• Terminale seriale
• WebSerial
• Espruino Web IDE

Ringraziamenti

Grazie a Reilly Grant e Joe Medley per le loro recensioni di questo documento.