Permissions Web Serial et cycle de vie des ports

Web Serial permet de demander un port choisi par l’utilisateur, mais le sélecteur ne prouve ni connexion, ni confiance, ni propriété. BotBrowser peut vérifier les branches de permission et de repli de la page dans un contexte contrôlé ; il ne fournit pas de périphérique série physique, n’accorde pas la permission du système et ne prouve pas une E/S matérielle. Demandez après une action, ouvrez un port pris en charge, bornez les trames, annulez les flux à la déconnexion et gardez la tâche utilisable sans matériel.

TL;DR

• navigator.serial.requestPort({ filters: [{ usbVendorId: 0x2341 }] }) exige un contexte sécurisé et une activation utilisateur transitoire.
• Un SerialPort choisi est une capacité liée à l’origine ; il ne prouve pas qu’il est ouvert, connecté ou compatible.
• Ouvrez avec port.open({ baudRate: 115200 }) et validez chaque trame avant de modifier l’état.
• Les événements connect et disconnect sont des observations du navigateur ; annulez les readers, libérez les locks et fermez le port.
• Conservez granted, unsupported, invalid-frame ou disconnected, pas les numéros de série ni les buffers bruts.

Sommaire

• Demander au point d’utilisation
• Séparer permission et disponibilité
• Borner les flux
• Réconcilier connect et disconnect
• Minimiser les métadonnées et garder un repli
• Classer les résultats
• Capacité et limite de BotBrowser
• Conclusion pratique

Demander au point d’utilisation

Web Serial est limité aux contextes sécurisés et requestPort() doit suivre une action. La détection de navigator.serial n’ouvre pas le sélecteur. Une politique d’iframe, un navigateur administré, une plateforme non prise en charge ou le système peuvent refuser la demande.

async function connectSerial() {
  if (!window.isSecureContext || !navigator.serial) return showSerialState('unsupported');
  setSerialState('requesting');
  try {
    const port = await navigator.serial.requestPort({
      filters: [{ usbVendorId: 0x2341 }],
    });
    await openSelectedPort(port);
  } catch (error) {
    showSerialState(error.name === 'NotFoundError' ? 'cancelled' : 'denied');
  }
}

connectButton.addEventListener('click', connectSerial);

N’ouvrez pas un sélecteur au chargement et ne bouclez pas après annulation. Gardez le brouillon. Accès WebUSB : permissions, interfaces et vie privée sépare permission et disponibilité ; Permissions WebHID et limites de confidentialité applique cette frontière aux rapports ; Empreinte des permissions du navigateur rappelle qu’un état n’accorde pas l’accès et n’identifie personne.

Séparer permission et disponibilité

requestPort() renvoie le port choisi, pas un appareil prêt. open() peut réussir avec un mauvais baudRate, un framing incorrect ou un protocole absent. Traitez sélection, ouverture, lecture, écriture et fermeture comme états séparés et documentez baudRate, dataBits, stopBits, parity et flowControl acceptés.

navigator.serial.getPorts() ne constitue pas un inventaire complet. Une reconnexion doit être une action visible et revalider la configuration. La spécification Web Serial et MDN Web Serial API décrivent l’interface, sans promettre identité, localisation ou résultat physique.

Borner les flux

port.readable et port.writable sont asynchrones. Utilisez une taille maximale, un délimiteur ou une longueur, un checksum si le protocole en définit un et un délai pour les trames incomplètes.

const MAX_FRAME_BYTES = 128;

async function readSerialFrames(port) {
  const reader = port.readable.getReader();
  try {
    while (true) {
      const { value, done } = await reader.read();
      if (done) break;
      if (value.byteLength > MAX_FRAME_BYTES) {
        showSerialState('invalid-frame');
        continue;
      }
      acceptBoundedFrame(value);
    }
  } finally {
    reader.releaseLock();
  }
}

Ne journalisez pas chaque octet et n’envoyez pas une trame arbitraire à un interpréteur. Classez invalid-length, invalid-checksum ou timeout. Un writer.write() résolu prouve seulement que le navigateur a accepté les octets ; il ne prouve pas un effet matériel. Libérez le writer et annulez le reader avant close().

const serialOutcome = { state: 'fallback', rawIdentifiersRetained: false };
showSerialState(serialOutcome.state);

Réconcilier connect et disconnect

connect indique qu’un port est devenu visible ; disconnect indique qu’il a disparu. Aucun ne justifie une demande silencieuse ou n’explique la cause physique. À la déconnexion, invalidez la tâche, annulez le reader, libérez le writer, fermez le port au mieux, retirez les listeners, préservez les données et affichez un bouton de reconnexion. Ne renvoyez pas automatiquement la dernière commande.

Utilisez idle, requesting, selected, opening, opened, reading, invalid-frame, disconnected, cancelled et fallback. Une reconnexion répétée la configuration et le handshake, et ne traite pas serialNumber ou getInfo() comme une identité.

Minimiser les métadonnées et garder un repli

Séparez permission, session, consentement du protocole et téléversement. Une lecture locale n’autorise pas l’envoi serveur. Un journal peut garder unsupported, denied, cancelled, opened, invalid-frame, disconnected ou fallback, avec date et environnement ; évitez getInfo(), identifiants USB, buffers et historique durable. Gardez une saisie manuelle, un import, une valeur simulée ou une configuration statique.

Classer les résultats

Étape	Ce qu’elle établit	Action sûre
API absente, contexte non sûr ou politique	Web Serial ne démarre pas	Garder la tâche sans port
Sélecteur annulé ou permission refusée	Aucun accès utilisable	Préserver le brouillon
open() refusé	Session inutilisable	Afficher les réglages et fermer
Trame invalide	Protocole rejeté	Ignorer et classer l’erreur
disconnect	Retrait observé	Annuler, fermer, préserver et proposer un nouvel essai
Trame valide	Une valeur a été acceptée	Ne pas inférer d’effet physique

Capacité et limite de BotBrowser

BotBrowser peut vérifier le bouton, la détection, le résultat du sélecteur, la validation bornée, le nettoyage et le repli. La documentation des fonctionnalités avancées décrit ce contexte. BotBrowser ne fournit pas le périphérique, n’accorde pas la permission système, ne garantit pas un port et ne prouve pas un effet matériel. BotBrowser valide les états visibles de navigator.serial et le repli dans un contexte contrôlé ; il ne valide pas une opération électrique réelle.

{
  "api": "navigator.serial",
  "permission": "denied",
  "portState": "fallback",
  "framesAccepted": 0,
  "rawIdentifiersRetained": false,
  "physicalDevice": "not-asserted"
}

Sources

• Spécification Web Serial
• MDN : Web Serial API
• Fonctionnalités avancées BotBrowser

Conclusion pratique

Utilisez une action explicite, séparez permission, ouverture et flux, validez chaque trame et annulez les readers avant la fermeture. Gardez la tâche sans matériel et journalisez l’étape de l’échec plutôt que les métadonnées. Rejouez le fixture après une mise à jour ; un succès de page ne promet pas un comportement physique.