Lire et écrire sur un port série

L'API Web Serial permet aux sites Web de communiquer avec des appareils sériels.

François Beaufort

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 soit via un port série sur le système de l'utilisateur, soit via des périphériques USB et Bluetooth amovibles qui émulent un port série.

En d'autres termes, l'API Web Serial fait le lien entre 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 complément à WebUSB, car les systèmes d'exploitation exigent que les applications communiquent avec certains ports série à l'aide de leur API série de niveau supérieur plutôt que de 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 sont conçus avec la technologie Web:

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

Dans certains cas, les sites Web communiquent avec l'appareil via une application d'agent que les utilisateurs ont installée manuellement. Dans d'autres cas, l'application est fournie dans une application empaquetée via un framework tel qu'Electron. Dans d'autres cas, l'utilisateur doit effectuer une étape supplémentaire, comme copier une application compilée sur l'appareil à l'aide d'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

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 asynchrone par conception. Cela empêche l'interface utilisateur du site Web de se bloquer 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 tactile ou un clic de souris, soit en choisir un parmi navigator.serial.getPorts() qui renvoie une liste des ports série auxquels le site Web a accès.

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 de faire correspondre n'importe quel appareil série connecté via USB à un fournisseur USB obligatoire (usbVendorId) et à des identifiants de 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();

L'appel de requestPort() invite l'utilisateur à sélectionner un appareil et renvoie un objet SerialPort. Une fois que vous disposez d'un objet SerialPort, l'appel de port.open() avec la vitesse de transmission souhaitée ouvre le port série. Le membre du dictionnaire baudRate spécifie la vitesse à laquelle les données sont envoyées sur une ligne de série. Elle est exprimée en unités de bits par seconde (bits/s). Consultez la documentation de votre appareil pour connaître la valeur correcte, car toutes les données que vous envoyez et recevez seront illisibles si cette valeur est spécifiée de manière incorrecte. Pour certains appareils USB et Bluetooth qui émulent un port série, cette valeur peut être définie 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 ont des valeurs par défaut pratiques.

• dataBits: nombre de bits de données par trame (7 ou 8).
• stopBits: nombre de bits de stop à la fin d'un frame (1 ou 2).
• parity: mode de parité ("none", "even" ou "odd").
• bufferSize: taille des tampons de lecture et d'écriture à créer (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 un ReadableStream et un WritableStream. Ils seront utilisés pour recevoir des données de l'appareil série et pour y envoyer des données. 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 un booléen done. Si done est défini sur "true", le port série a été fermé ou ne reçoit plus de données. L'appel de port.readable.getReader() crée un lecteur et verrouille readable. 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, comme un dépassement de mémoire tampon, des erreurs de cadrage ou des erreurs de parité. Ils sont générés en tant qu'exceptions et peuvent être détectés en ajoutant une autre boucle au-dessus de la précédente qui vérifie port.readable. En effet, tant que les erreurs ne sont pas fatales, un ReadableStream est créé automatiquement. Si une erreur fatale se produit, par exemple si l'appareil série est supprimé, 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 transmettre port.readable via un TextDecoderStream, comme illustré ci-dessous. Un TextDecoderStream est un flux de transformation qui récupère tous les segments 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 la manière dont la mémoire est allouée lorsque vous lisez à partir du flux à l'aide d'un lecteur "apportez votre propre tampon". 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 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 dans un port série

Pour envoyer des données à un appareil série, transmettez-les à port.writable.getWriter().write(). L'appel de releaseLock() sur port.writable.getWriter() est nécessaire pour que le port série soit fermé 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 illustré 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 leur rédacteur respectifs.

await port.close();

Toutefois, lors de la lecture continue de données à partir d'un appareil série à l'aide d'une boucle, port.readable est toujours verrouillé jusqu'à ce qu'une erreur se produise. Dans ce cas, l'appel de reader.cancel() oblige reader.read() à résoudre immédiatement avec { value: undefined, done: true }, ce qui permet à 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 complexe lorsque vous utilisez des flux de transformation. Appelez reader.cancel() comme précédemment. Appelez ensuite writer.close() et port.close(). Cette opération propage les erreurs à travers les flux de transformation vers le port série sous-jacent. Étant donné que la propagation des erreurs ne se produit pas 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'arrêt du flux. C'est pourquoi vous devez intercepter 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, cet appareil 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 des appareils et le contrôle de flux. Ces signaux sont définis comme des valeurs booléennes. Par exemple, certains appareils tels qu'Arduino entrent en mode de programmation si le signal DTR (Data Terminal Ready) est activé.

Le paramétrage des signaux de sortie et l'obtention des signaux d'entrée sont effectués respectivement 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 n'obtenez pas nécessairement toutes les données en même temps. Il peut être fragmenté de manière arbitraire. Pour en savoir plus, consultez la section Concepts de l'API Streams.

Pour y remédier, 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 trouve entre l'appareil série et la boucle de lecture qui consomme le flux. 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 s'achève sur la ligne, chaque étape de la ligne le modifie. Le temps qu'il atteigne sa destination finale, il devient donc un widget entièrement fonctionnel.

Par exemple, réfléchissez à la façon de créer une classe de flux de transformation qui consomme un flux et le découpe en fonction des sauts de ligne. Sa méthode transform() est appelée chaque fois que de nouvelles données sont reçues par le flux. Il peut soit mettre les données en file d'attente, soit les enregistrer pour plus tard. La méthode flush() est appelée lorsque le flux est fermé et gère toutes les données qui n'ont pas encore été traitées.

Pour utiliser la classe de flux de transformation, vous devez y transmettre un flux entrant. Dans le troisième exemple de code sous Lire à partir d'un port série, le flux d'entrée d'origine n'a été redirigé que via un TextDecoderStream. Nous devons donc appeler pipeThrough() pour le rediriger 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 allant vers ou provenant de l'appareil série. Les deux flux créés peuvent être consommés indépendamment, ce qui vous permet d'en imprimer un dans la console pour l'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, un grand nombre d'autorisations générées par l'utilisateur accumulées crée une mauvaise expérience utilisateur.

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

Comme forget() est disponible dans Chrome 103 ou version ultérieure, vérifiez si cette fonctionnalité 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 grâce à la page interne about://device-log, où vous pouvez voir tous les événements liés aux appareils série en un seul et même endroit.

Atelier de programmation

Dans l'atelier de programmation Google Developer, vous allez utiliser l'API Web Serial pour interagir avec une carte BBC micro:bit afin d'afficher des images sur sa matrice de 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 basés sur USB est possible à l'aide de l'API WebUSB et du 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 de spécifications ont conçu et mis en œuvre l'API Web Serial selon les principes fondamentaux définis dans la section 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, l'utilisateur doit prendre des mesures actives pour sélectionner un appareil série particulier.

Pour comprendre les compromis de sécurité, consultez les sections Sécurité et Confidentialité de la présentation de l'API Web Serial.

Commentaires

L'équipe Chrome aimerait connaître votre avis et votre expérience avec l'API Web Serial.

Parlez-nous de la conception de l'API

L'API ne fonctionne-t-elle pas comme prévu ? Ou manque-t-il des méthodes ou des propriétés dont vous avez besoin pour implémenter votre idée ?

Signalez un problème de spécification dans le dépôt GitHub de l'API Web Serial ou ajoutez vos commentaires à un problème existant.

Signaler un problème d'implémentation

Avez-vous trouvé un bug dans l'implémentation de Chrome ? Ou l'implémentation est-elle différente de la spécification ?

Signalez un bug sur https://new.crbug.com. Veillez à inclure autant de détails que possible, à fournir des instructions simples pour reproduire le bug et à définir Components sur Blink>Serial. Glitch est idéal pour partager des reproductions rapides et faciles.

Montrez votre 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 en utilisant le hashtag #SerialAPI et indiquez-nous où et comment vous l'utilisez.

Liens utiles

• Spécification
• Bug de suivi
• Enregistrement sur ChromeStatus.com
• Composant clignotement : Blink>Serial

Démonstrations

• Terminal série
• WebSerial
• IDE Web Espruino

Remerciements

Merci à Reilly Grant et Joe Medley pour leurs commentaires sur cet article. Photo d'usine d'avions par le Birmingham Museums Trust sur Unsplash.