L'API Web Serial consente ai siti web di comunicare con i dispositivi seriali.
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 simulano 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 è inoltre un'ottima compagna di WebUSB, in quanto i sistemi operativi richiedono alle applicazioni di comunicare con alcune porte seriali mediante l'API seriale di livello superiore anziché l'API USB di basso livello.
Casi d'uso suggeriti
Nei settori didattico, hobbistico e industriale, gli utenti collegano dispositivi periferici ai computer. Questi dispositivi sono spesso controllati da microcontrollori tramite una connessione seriale utilizzata da software personalizzato. Alcuni software personalizzati per controllare questi dispositivi sono realizzati con tecnologia web:
In alcuni casi, i siti web comunicano con il dispositivo tramite un'applicazione agente installata manualmente dagli utenti. In altri casi, l'applicazione viene fornita in un'applicazione pacchettizzata tramite un framework come Electron. In altri, l'utente deve eseguire un passaggio aggiuntivo, come copiare un'applicazione compilata sul dispositivo tramite un'unità flash USB.
In tutti questi casi, l'esperienza utente verrà migliorata grazie alla comunicazione diretta tra il sito web e il dispositivo che controlla.
Stato attuale
| Passaggio | Stato |
|---|---|
| 1. Creare un'animazione esplicativa | Completato |
| 2. Creare una bozza iniziale della specifica | Completato |
| 3. Raccogli feedback e esegui l'iterazione sul design | Completato |
| 4. Prova dell'origine | Completato |
| 5. Avvia | Completato |
Utilizzo dell'API Web Serial
Rilevamento di funzionalità
Per verificare se l'API Web Serial è supportata, utilizza:
if ("serial" in navigator) {
// The Web Serial API is supported.
}
Aprire una porta seriale
L'API Web Serial è asincrona per progettazione. In questo modo, l'interfaccia utente del sito web non si blocca quando attende l'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 gesto dell'utente, come il tocco o il clic del mouse, oppure sceglierne una da navigator.serial.getPorts(), che restituisce un elenco di porte seriali a cui è stato concesso l'accesso al sito 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 funzione navigator.serial.requestPort() prende un valore letterale oggetto
facoltativo che definisce i filtri. Questi vengono utilizzati per associare qualsiasi dispositivo seriale connesso tramite USB a un fornitore USB obbligatorio (usbVendorId) e a 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() richiede all'utente di selezionare un dispositivo e restituisce un oggetto SerialPort. Una volta creato un oggetto SerialPort, la chiamata a port.open()
con la velocità in baud desiderata aprirà la porta seriale. Il membro del dizionario baudRate
specifica la velocità di invio dei dati su una linea seriale. Viene espressa in unità di bit al secondo (bps). Controlla la documentazione del dispositivo per trovare il valore corretto, poiché tutti i dati inviati e ricevuti saranno incomprensibili se il valore è specificato in modo errato. Per alcuni dispositivi USB e Bluetooth che simulano una porta seriale, questo valore può essere impostato in tutta sicurezza 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 });
Quando apri una porta seriale, puoi anche specificare una delle opzioni riportate di seguito. Queste opzioni sono facoltative e hanno valori predefiniti pratici.
dataBits: il numero di bit di dati per frame (7 o 8).stopBits: il numero di stop bit alla fine di un frame (1 o 2).parity: la modalità di parità ("none","even"o"odd").bufferSize: le dimensioni dei buffer di lettura e scrittura che devono essere creati (devono essere inferiori a 16 MB).flowControl: la modalità di controllo del flusso ("none"o"hardware").
Leggere da una porta seriale
Gli stream di input e di output nell'API Web Serial sono gestiti dall'API Streams.
Una volta stabilita la connessione alla porta seriale, le proprietà readable e writable
dell'oggetto SerialPort restituiscono un ReadableStream e un
WritableStream. Verranno utilizzati per ricevere e inviare dati al
dispositivo seriale. Entrambi utilizzano istanze Uint8Array per il trasferimento dei dati.
Quando arrivano nuovi dati dal dispositivo seriale, port.readable.getReader().read()
restituisce due proprietà in modo asincrono: value e un valore booleano done. Se done è true, la porta seriale è stata chiusa o non ci sono più dati in entrata. La chiamata a port.readable.getReader() crea un lettore e blocca readable su di esso. Quando 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);
}
Alcuni errori di lettura non irreversibili delle porte seriali possono verificarsi in determinate condizioni, ad esempio overflow del buffer, errori di inquadratura o errori di parità. Vengono lanciate come eccezioni e possono essere rilevate aggiungendo un altro ciclo sopra quello precedente che controlla port.readable. Questo funziona perché, a condizione che gli errori non siano fatali, viene creato automaticamente un nuovo ReadableStream. Se si verifica un errore fatale, ad esempio se il dispositivo seriale viene rimosso, port.readable diventa nullo.
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 a un
TextDecoderStream come mostrato di seguito. Un TextDecoderStream è un flusso di trasformazione
che prende 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 la modalità di allocazione della memoria quando leggi dallo stream utilizzando un lettore "Porta il tuo 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 di 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);
Scrivere in una porta seriale
Per inviare dati a un dispositivo seriale, passali a
port.writable.getWriter().write(). La chiamata a releaseLock() su
port.writable.getWriter() è necessaria per la chiusura successiva della porta seriale.
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 il testo al dispositivo tramite un TextEncoderStream piped to 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");
Chiudere una porta seriale
port.close() chiude la porta seriale se i relativi membri readable e writable
sono sbloccati, il che significa che releaseLock() è stato chiamato per i rispettivi
lettore e scrittore.
await port.close();
Tuttavia, quando leggi continuamente i dati da un dispositivo seriale utilizzando un loop,port.readable rimarrà sempre bloccato finché non viene rilevato un errore. In questo
caso, la chiamata a reader.cancel() costringerà reader.read() a risolversi
immediatamente con { value: undefined, done: true }, consentendo così 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 gli stream di trasformazione. Chiama reader.cancel() come prima.
Quindi chiama writer.close() e port.close(). In questo modo, gli errori vengono propagati tramite gli stream 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 di reader comporta l'interruzione dello stream, motivo per cui 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 connessione e disconnessione
Se una porta seriale è fornita da un dispositivo USB, il dispositivo potrebbe essere collegato o scollegato dal sistema. Quando al sito web è stata concessa l'autorizzazione per 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.
});
Gestire gli indicatori
Dopo aver stabilito la connessione alla porta seriale, puoi eseguire query e impostare esplicitamente gli indicatori esposti dalla porta seriale per il rilevamento dei dispositivi e il controllo del flusso. Questi indicatori sono definiti come valori booleani. Ad esempio, alcuni dispositivi come Arduino entrano in modalità di programmazione se il segnale DTR (Data Terminal Ready) viene attivato/disattivato.
L'impostazione dei segnali di output e la ricezione dei segnali di input vengono eseguiti rispettivamente
chiamando port.setSignals() e port.getSignals(). Di seguito sono riportati alcuni esempi di utilizzo.
// 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}`);
Trasformare gli stream
Quando ricevi i dati dal dispositivo seriale, non necessariamente li ricevi tutti contemporaneamente. Potrebbe essere suddiviso in blocchi in modo arbitrario. Per ulteriori informazioni, consulta i concetti dell'API Streams.
Per risolvere il problema, puoi utilizzare alcuni stream di trasformazione integrati come
TextDecoderStream oppure creare il tuo stream di trasformazione che ti consenta di
analizzare lo stream in entrata e restituire i dati analizzati. Lo stream di trasformazione si trova tra il dispositivo seriale e il loop di lettura che lo utilizza. Può
applicare una trasformazione arbitraria prima che i dati vengano utilizzati. Pensala come a una catena di montaggio: quando un widget arriva in fondo alla 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 stream di trasformazione che consumi uno stream e lo suddivida in base ai ritorni a capo. Il relativo metodo transform() viene chiamato ogni volta che lo stream riceve nuovi dati. Può mettere in coda i dati o salvarli per utilizzarli in un secondo momento. Il metodo flush() viene chiamato quando lo stream viene chiuso e gestisce i dati che non sono stati ancora elaborati.
Per utilizzare la classe del flusso di trasformazione, devi reindirizzare un flusso in entrata attraverso
la classe di flusso di trasformazione. Nel terzo esempio di codice in Read from a serial port (Lettura da una porta seriale),
il flusso di input originale era trasmesso solo attraverso una rete TextDecoderStream, quindi
dobbiamo chiamare pipeThrough() per trasmetterlo attraverso 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 suddividere gli stream inviati o ricevuti dal dispositivo seriale. I due stream creati possono essere utilizzati in modo indipendente e questo ti consente di stamparne uno nella console per ispezionarlo.
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.
Revocare l'accesso a una porta seriale
Il sito web può eliminare le autorizzazioni per accedere a una porta seriale che non ha più interesse 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 accumulate crea un'esperienza utente negativa.
// 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
Eseguire il debug dell'API Web Serial in Chrome è semplice grazie alla pagina interna about://device-log, in cui puoi visualizzare tutti gli eventi relativi ai dispositivi seriali in un'unica posizione.
Codelab
Nel codelab di Google Developer, utilizzerai l'API Web Serial per interagire con una scheda BBC micro:bit per mostrare le immagini sulla sua 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 delle 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 rivendicato 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 nella sezione Controllare l'accesso a funzionalità avanzate della piattaforma web, tra cui controllo degli utenti, trasparenza ed ergonomia. La possibilità di utilizzare questa API è limitata principalmente 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 determinato dispositivo seriale.
Per comprendere i compromessi in termini di sicurezza, consulta le sezioni sulla sicurezza e sulla privacy della spiegazione dell'API Web Serial.
Feedback
Il team di Chrome vorrebbe conoscere le tue opinioni ed esperienze con l'API Web Serial.
Fornisci informazioni sul design dell'API
C'è qualcosa nell'API che non funziona come previsto? Oppure mancano metodi o proprietà che ti servono per implementare la tua idea?
Invia una segnalazione relativa alle specifiche nel repository GitHub dell'API Web Serial o aggiungi il tuo contributo a un problema esistente.
Segnalare un problema con l'implementazione
Hai trovato un bug nell'implementazione di Chrome? Oppure l'implementazione è diversa dalla specifica?
Segnala un bug all'indirizzo https://new.crbug.com. Assicurati di includere il maggior numero possibile di dettagli, fornisci istruzioni semplici per riprodurre il bug e imposta l'opzione Componenti su Blink>Serial. Glitch è ideale per condividere riproduzioni rapide e semplici.
Mostrare il proprio sostegno
Intendi 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 all'indirizzo @ChromiumDev utilizzando l'hashtag
#SerialAPI
e facci sapere dove e come lo utilizzi.
Link utili
- Specifiche
- Bug di monitoraggio
- Voce di ChromeStatus.com
- Componente lampeggiante:
Blink>Serial
Demo
Ringraziamenti
Grazie a Reilly Grant e Joe Medley per le loro recensioni su questo articolo. Foto della fabbrica di aeroplani di Birmingham Museums Trust su Unsplash.