L'API Web Serial permet aux sites Web de communiquer avec les appareils série.
Qu'est-ce que l'API Web Serial ?
Un port série est une interface de communication bidirectionnelle qui permet d'envoyer et de recevoir des données octet par octet.
L'API Web Serial permet aux sites Web de lire et d'écrire sur un appareil série avec JavaScript. Les appareils série sont connectés via un port série sur le système de l'utilisateur ou via des appareils USB et Bluetooth amovibles qui émulent un port série.
En d'autres termes, l'API Web Serial relie le Web et le monde physique en permettant aux sites Web de communiquer avec des appareils série, tels que des microcontrôleurs et des imprimantes 3D.
Cette API est également un excellent compagnon de WebUSB, car les systèmes d'exploitation nécessitent que les applications communiquent avec certains ports série à l'aide de leur API série de niveau supérieur plutôt qu'avec l'API USB de bas niveau.
Cas d'utilisation suggérés
Dans les secteurs éducatif, amateur et industriel, les utilisateurs connectent des périphériques à leurs ordinateurs. Ces appareils sont souvent contrôlés par des microcontrôleurs via une connexion série utilisée par un logiciel personnalisé. Certains logiciels personnalisés permettant de contrôler ces appareils reposent sur une technologie Web:
Dans certains cas, les sites Web communiquent avec l'appareil via une application agent que les utilisateurs ont installée manuellement. Dans d'autres, l'application est fournie dans un package via un framework tel qu'Electron. Dans d'autres, l'utilisateur doit effectuer une étape supplémentaire, telle que la copie d'une application compilée sur l'appareil via une clé USB.
Dans tous ces cas, l'expérience utilisateur sera améliorée en fournissant une communication directe entre le site Web et l'appareil qu'il contrôle.
État actuel
| Step | État |
|---|---|
| 1. Créer une vidéo explicative | Fin |
| 2. Créer un brouillon initial de la spécification | Fin |
| 3. Recueillir des commentaires et itérer sur la conception | Fin |
| 4. Phase d'évaluation | Fin |
| 5. Lancement | Fin |
Utiliser l'API Web Serial
Détection de fonctionnalités
Pour vérifier si l'API Web Serial est compatible, utilisez:
if ("serial" in navigator) {
// The Web Serial API is supported.
}
Ouvrir un port série
L'API Web Serial est de conception asynchrone. Cela évite que l'interface utilisateur du site Web ne se bloque lorsqu'elle attend une entrée, ce qui est important car les données série peuvent être reçues à tout moment, ce qui nécessite un moyen de les écouter.
Pour ouvrir un port série, accédez d'abord à un objet SerialPort. Pour ce faire, vous pouvez soit inviter l'utilisateur à sélectionner un seul port série en appelant navigator.serial.requestPort() en réponse à un geste de l'utilisateur, tel qu'un geste ou un clic de souris, soit en choisir un dans navigator.serial.getPorts(), qui renvoie une liste des ports série auxquels le site Web a été autorisé à accéder.
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 fonction navigator.serial.requestPort() utilise un littéral d'objet facultatif qui définit des filtres. Ils permettent d'associer tout appareil série connecté via USB à un fournisseur USB obligatoire (usbVendorId) et à des identifiants produit USB facultatifs (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();
Appeler requestPort() invite l'utilisateur à sélectionner un appareil et renvoie un objet SerialPort. Une fois que vous disposez d'un objet SerialPort, appeler port.open() avec le débit en bauds souhaité ouvrira le port série. Le membre du dictionnaire baudRate spécifie la vitesse d'envoi des données sur une ligne série. Elle est exprimée en unités de bits par seconde (bit/s). Consultez la documentation de votre appareil pour connaître la valeur correcte, car toutes les données que vous envoyez et recevez seront vides de sens si elles sont spécifiées de manière incorrecte. Pour certains appareils USB et Bluetooth qui émulent un port série, cette valeur peut être définie en toute sécurité sur n'importe quelle valeur, car elle est ignorée par l'émulation.
// 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 });
Vous pouvez également spécifier l'une des options ci-dessous lors de l'ouverture d'un port série. Ces options sont facultatives et disposent de valeurs par défaut pratiques.
dataBits: nombre de bits de données par trame (7 ou 8).stopBits: nombre de bits d'arrêt à la fin d'une trame (1 ou 2).parity: mode de parité ("none","even"ou"odd").bufferSize: taille des tampons de lecture et d'écriture à créer (elle doit être inférieure à 16 Mo).flowControl: mode de contrôle de flux ("none"ou"hardware").
Lire à partir d'un port série
Les flux d'entrée et de sortie de l'API Web Serial sont gérés par l'API Streams.
Une fois la connexion au port série établie, les propriétés readable et writable de l'objet SerialPort renvoient ReadableStream et WritableStream. Ceux-ci seront utilisés pour recevoir des données et en envoyer à l'appareil série. Les deux utilisent des instances Uint8Array pour le transfert de données.
Lorsque de nouvelles données arrivent de l'appareil série, port.readable.getReader().read() renvoie deux propriétés de manière asynchrone: value et une valeur booléenne done. Si done est défini sur "true", le port série a été fermé ou il n'y a plus de données entrantes. L'appel de port.readable.getReader() crée un lecteur et verrouille readable sur celui-ci. Lorsque readable est verrouillé, le port série ne peut pas être fermé.
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);
}
Certaines erreurs de lecture de port série non fatales peuvent se produire dans certaines conditions, telles qu'un dépassement de mémoire tampon, des erreurs de cadrage ou des erreurs de parité. Celles-ci sont générées en tant qu'exceptions et peuvent être interceptées en ajoutant une autre boucle au-dessus de la précédente qui vérifie port.readable. Cela fonctionne, car tant que les erreurs ne sont pas fatales, un ReadableStream est créé automatiquement. Si une erreur fatale se produit, telle que la suppression de l'appareil série, port.readable devient nul.
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 l'appareil série renvoie du texte, vous pouvez rediriger port.readable via un TextDecoderStream, comme indiqué ci-dessous. Un TextDecoderStream est un flux de transformation qui récupère tous les fragments Uint8Array et les convertit en chaînes.
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);
}
Vous pouvez contrôler l'allocation de la mémoire lorsque vous lisez le flux à l'aide d'un lecteur "Bring Your Own Buffer". Appelez port.readable.getReader({ mode: "byob" }) pour obtenir l'interface ReadableStreamBYOBReader et fournissez votre propre ArrayBuffer lorsque vous appelez read(). Notez que l'API Web Serial est compatible avec cette fonctionnalité dans Chrome 106 ou version ultérieure.
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()...
}
}
Voici un exemple de réutilisation du tampon hors 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`.
}
Voici un autre exemple de lecture d'une quantité spécifique de données à partir d'un port série:
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);
Écrire sur un port série
Pour envoyer des données à un appareil série, transmettez-les à port.writable.getWriter().write(). Vous devez appeler releaseLock() sur port.writable.getWriter() pour fermer le port série ultérieurement.
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();
Envoyez du texte à l'appareil via un TextEncoderStream redirigé vers port.writable, comme indiqué ci-dessous.
const textEncoder = new TextEncoderStream();
const writableStreamClosed = textEncoder.readable.pipeTo(port.writable);
const writer = textEncoder.writable.getWriter();
await writer.write("hello");
Fermer un port série
port.close() ferme le port série si ses membres readable et writable sont déverrouillés, ce qui signifie que releaseLock() a été appelé pour leur lecteur et rédacteur respectifs.
await port.close();
Toutefois, lors de la lecture en continu des données d'un appareil série à l'aide d'une boucle, port.readable est toujours verrouillé jusqu'à ce qu'il rencontre une erreur. Dans ce cas, l'appel de reader.cancel() force reader.read() à se résoudre immédiatement avec { value: undefined, done: true }, permettant ainsi à la boucle d'appeler 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 fermeture d'un port série est plus compliquée lors de l'utilisation de flux de transformation. Appelez reader.cancel() comme précédemment.
Appelez ensuite writer.close() et port.close(). Cette opération propage les erreurs via les flux de transformation vers le port série sous-jacent. Comme la propagation des erreurs n'a pas lieu immédiatement, vous devez utiliser les promesses readableStreamClosed et writableStreamClosed créées précédemment pour détecter quand port.readable et port.writable ont été déverrouillés. L'annulation de reader entraîne l'abandon du flux. C'est pourquoi vous devez détecter et ignorer l'erreur qui en résulte.
// 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();
Écouter la connexion et la déconnexion
Si un port série est fourni par un appareil USB, celui-ci peut être connecté ou déconnecté du système. Lorsque le site Web a été autorisé à accéder à un port série, il doit surveiller les événements connect et 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.
});
Gérer les signaux
Une fois la connexion au port série établie, vous pouvez interroger et définir explicitement les signaux exposés par le port série pour la détection d'appareils et le contrôle de flux. Ces signaux sont définis comme des valeurs booléennes. Par exemple, certains appareils tels qu'Arduino passent en mode programmation si le signal DTR (Data Terminal Ready) est activé.
La définition de signaux de sortie et l'obtention de signaux d'entrée sont respectivement effectuées en appelant port.setSignals() et port.getSignals(). Consultez les exemples d'utilisation ci-dessous.
// 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}`);
Transformer des flux
Lorsque vous recevez des données de l'appareil série, vous ne les recevez pas nécessairement en même temps. Il peut être fragmenté de manière arbitraire. Pour en savoir plus, consultez la page Concepts de l'API Streams.
Pour résoudre ce problème, vous pouvez utiliser des flux de transformation intégrés tels que TextDecoderStream ou créer votre propre flux de transformation qui vous permet d'analyser le flux entrant et de renvoyer des données analysées. Le flux de transformation se situe entre l'appareil série et la boucle de lecture qui le consomme. Il peut appliquer une transformation arbitraire avant que les données ne soient consommées. Considérez cela comme une chaîne d'assemblage: lorsqu'un widget arrive sur la ligne, chaque étape le modifie, de sorte qu'une fois qu'il atteint sa destination finale, il est pleinement opérationnel.
Par exemple, réfléchissez à la création d'une classe de flux de transformation qui consomme un flux et le fragmente en fonction des sauts de ligne. Sa méthode transform() est appelée à chaque fois que le flux reçoit de nouvelles données. Il peut mettre les données en file d'attente ou les enregistrer pour plus tard. La méthode flush() est appelée lorsque le flux est fermé et traite toutes les données qui n'ont pas encore été traitées.
Pour utiliser la classe de flux de transformation, vous devez diriger un flux entrant par le biais de celle-ci. Dans le troisième exemple de code sous Lire à partir d'un port série, le flux d'entrée d'origine n'était acheminé que via un TextDecoderStream. Nous devons donc appeler pipeThrough() pour le transférer via notre nouveau 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();
Pour déboguer les problèmes de communication des appareils série, utilisez la méthode tee() de port.readable pour diviser les flux à destination ou en provenance de l'appareil série. Les deux flux créés peuvent être utilisés indépendamment, ce qui vous permet d'en imprimer un sur la console pour inspection.
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.
Révoquer l'accès à un port série
Le site Web peut nettoyer les autorisations d'accès à un port série qu'il ne souhaite plus conserver en appelant forget() sur l'instance SerialPort. Par exemple, pour une application Web éducative utilisée sur un ordinateur partagé avec de nombreux appareils, l'accumulation d'autorisations générées par l'utilisateur nuit à l'expérience utilisateur.
// Voluntarily revoke access to this serial port.
await port.forget();
forget() étant disponible dans Chrome 103 ou version ultérieure, vérifiez si elle est compatible avec les éléments suivants:
if ("serial" in navigator && "forget" in SerialPort.prototype) {
// forget() is supported.
}
Conseils pour les développeurs
Le débogage de l'API Web Serial dans Chrome est facile à l'aide de la page interne about://device-log, où vous pouvez voir tous les événements liés aux appareils sériels au même endroit.
Atelier de programmation
Dans l'atelier de programmation Google Developers, vous utiliserez l'API Web Serial pour interagir avec une carte BBC micro:bit afin d'afficher des images sur sa matrice LED 5x5.
Prise en charge des navigateurs
L'API Web Serial est disponible sur toutes les plates-formes de bureau (ChromeOS, Linux, macOS et Windows) dans Chrome 89.
Polyfill
Sur Android, la prise en charge des ports série USB est possible en utilisant l'API WebUSB et le polyfill de l'API Serial. Ce polyfill est limité au matériel et aux plates-formes sur lesquels l'appareil est accessible via l'API WebUSB, car il n'a pas été revendiqué par un pilote d'appareil intégré.
Sécurité et confidentialité
Les auteurs des spécifications ont conçu et mis en œuvre l'API Web Serial en suivant les principes fondamentaux définis dans Contrôler l'accès aux fonctionnalités puissantes de la plate-forme Web, y compris le contrôle utilisateur, la transparence et l'ergonomie. L'utilisation de cette API est principalement contrôlée par un modèle d'autorisation qui n'accorde l'accès qu'à un seul appareil série à la fois. En réponse à une invite utilisateur, celui-ci doit prendre des mesures actives pour sélectionner un appareil série particulier.
Pour comprendre les compromis en matière de sécurité, consultez les sections sur la sécurité et la confidentialité du document explicatif sur l'API Web Serial.
Commentaires
L'équipe Chrome aimerait connaître votre avis et vos expériences concernant l'API Web Serial.
Décrivez-nous la conception de l'API.
Y a-t-il quelque chose dans l'API qui ne fonctionne pas comme prévu ? Ou y a-t-il des méthodes ou des propriétés manquantes dont vous avez besoin pour mettre en œuvre votre idée ?
Signalez un problème de spécification dans le dépôt GitHub de l'API Web Serial ou ajoutez vos réflexions à un problème existant.
Signaler un problème d'implémentation
Avez-vous détecté un bug dans l'implémentation de Chrome ? Ou l'implémentation est-elle différente des spécifications ?
Signalez un bug à l'adresse https://new.crbug.com. Veillez à inclure autant de détails que possible, à fournir des instructions simples pour reproduire le bug et à définir l'option Composants sur Blink>Serial. Glitch est idéal pour partager des reproductions rapides et faciles.
Afficher le soutien
Comptez-vous utiliser l'API Web Serial ? Votre assistance publique aide l'équipe Chrome à hiérarchiser les fonctionnalités et montre aux autres fournisseurs de navigateurs à quel point il est essentiel de les prendre en charge.
Envoyez un tweet à @ChromiumDev avec le hashtag #SerialAPI, et indiquez-nous où et comment vous l'utilisez.
Liens utiles
- Spécification
- Bug de suivi
- Entrée ChromeStatus.com
- Composant Blink:
Blink>Serial
Démonstrations
Remerciements
Merci à Reilly Grant et à Joe Medley d'avoir donné leur avis sur cet article. Photo de l'usine d'un avion du Birmingham Museums Trust publiée sur Unsplash.