Lire et écrire sur un port série

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

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 fournit aux sites Web un moyen de lire et d'écrire depuis 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 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 qu'avec l'API USB de bas niveau.

Cas d'utilisation suggérés

Dans les secteurs de l'éducation, des loisirs et de l'industrie, les utilisateurs connectent des périphériques à leurs ordinateurs. Ces appareils sont souvent contrôlés par des microcontrôleurs avec une connexion série utilisée par des logiciels personnalisés. Certains logiciels personnalisés permettant de contrôler ces appareils sont conçus avec la technologie Web :

• Arduino Create
• Betaflight Configurator
• Espruino Web IDE
• 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 packagée via un framework tel qu'Electron. Dans d'autres cas encore, l'utilisateur doit effectuer une étape supplémentaire, comme copier 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

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 lors de l'attente d'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 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 appui ou un clic de souris, ou 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() prend un littéral d'objet facultatif qui définit des filtres. Ceux-ci sont utilisés pour faire correspondre n'importe quel appareil série connecté via USB avec 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 le débit en bauds souhaité ouvre le port série. Le membre de dictionnaire baudRate spécifie la vitesse à laquelle les données sont envoyées sur une ligne série. Elle est exprimée en unités de bits par seconde (bps). Consultez la documentation de votre appareil pour connaître la valeur correcte, car toutes les données que vous envoyez et recevez seront incompréhensibles 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 frame (7 ou 8).
• stopBits : nombre de bits d'arrêt à la fin d'une frame (1 ou 2).
• parity : mode de parité (soit "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 readable et writable propriétés 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 lui en envoyer. 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 : la value et un booléen 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 tampon, des erreurs de trame ou des erreurs de parité. Elles 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 nouveau 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 canaliser port.readable via un TextDecoderStream, comme indiqué ci-dessous. Un TextDecoderStream est un flux de transformation qui récupère tous les blocs 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 "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 d'utilisation du tampon en dehors 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(). 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 canalisé 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 leur enregistreur 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'il rencontre une erreur. Dans ce cas, l'appel de reader.cancel() forcera reader.read() à se résoudre immédiatement avec { value: undefined, done: true }, ce qui permettra à 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 lorsque vous utilisez des flux de transformation. Appelez reader.cancel() comme précédemment. Appelez ensuite writer.close() et port.close(). Cela propage les erreurs via les flux de transformation vers le port série sous-jacent. Comme 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 du reader entraîne l'abandon du flux. C'est pourquoi vous devez intercepter et ignorer l'erreur résultante.

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

Après avoir établi la connexion au port série, 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 passent en mode programmation si le signal DTR (Data Terminal Ready) est activé.

La définition des signaux de sortie et l'obtention des 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 recevez pas nécessairement toutes les données en même temps. Elles peuvent être divisées de manière arbitraire. Pour en savoir plus, consultez les concepts de l'API Streams.

Pour résoudre ce problème, vous pouvez utiliser certains flux de transformation intégrés tels que TextDecoderStream ou créer votre propre flux de transformation, ce qui vous permet d'analyser le flux entrant et de renvoyer les données analysées. Le flux de transformation se situe 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. Imaginez une chaîne de montage : lorsqu'un widget arrive en bas de la chaîne, chaque étape de la chaîne le modifie, de sorte qu'une fois arrivé à sa destination finale, il s'agit d'un widget entièrement fonctionnel.

Par exemple, réfléchissez à la création d'une classe de flux de transformation qui consomme un flux et le divise 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. Elle peut mettre en file d'attente les données ou les enregistrer pour plus tard. La méthode flush() est appelée lorsque le flux est fermé, et elle gère toutes les données qui n'ont pas encore été traitées.

Pour utiliser la classe de flux de transformation, vous devez canaliser un flux entrant via 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'a été canalisé que via un TextDecoderStream. Nous devons donc appeler pipeThrough() pour le canaliser 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 afin de diviser les flux allant vers ou depuis 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 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 les utilisateurs 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 endroit.

Codelab

Dans l'atelier de programmation Google Developers, vous utiliserez l'API Web Serial pour interagir avec une carte micro:bit BBC 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.

Polyester

Sur Android, la prise en charge des ports série basés sur USB est possible à l'aide de l'API WebUSB et du polyester de l'API Serial. Ce polyester est limité au matériel et aux plates-formes où 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 la spécification ont conçu et implémenté l'API Web Serial en utilisant les principes de base 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. La possibilité d'utiliser cette API est principalement limité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 effectuer des étapes actives pour sélectionner un appareil série spécifique.

Pour comprendre les compromis en matière de sécurité, consultez les sections Sécurité et Confidentialité de l'explication 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

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 commentaires à un problème existant.

Signaler un problème lié à l'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.

Montrer votre soutien

Prévoyez-vous d'utiliser l'API Web Serial ? Votre soutien public 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

• Terminal série
• WebSerial
• Espruino Web IDE

Remerciements

Merci à Reilly Grant et Joe Medley pour leurs commentaires sur ce document.