Web Serial API

The requestPort() method steps are:

1. Let promise be a new promise.
2. If this's relevant global object's associated Document is not allowed to use the policy-controlled feature named "serial", reject promise with a "SecurityError" DOMException and return promise.
3. If the relevant global object of this does not have transient activation, reject promise with a "SecurityError" DOMException and return promise.
4. If options["filters"] is present, then for each filter in options["filters"] run the following steps:
   1. If filter["bluetoothServiceClassId"] is present:
      1. If filter["usbVendorId"] is present, reject promise with a TypeError and return promise.
      2. If filter["usbProductId"] is present, reject promise with a TypeError and return promise.
   2. If filter["usbVendorId"] is not present, reject promise with a TypeError and return promise.
      Note

      This check implements the combined rule that a SerialPortFilter cannot be empty and if usbProductId is specified then usbVendorId must also be specified.
5. Run the following steps in parallel:
   1. Let allPorts be an empty list.
   2. For each Bluetooth device registered with the system:
      1. For each BluetoothServiceUUID uuid supported by the device:
         1. If uuid is not a blocked Bluetooth service class UUID:
            • If uuid is equal to the Serial Port Profile service class ID, or
            • options["allowedBluetoothServiceClassIds"] is present and contains uuid:
              1. Let port be a SerialPort representing the service on the Bluetooth device.
              2. Append port to allPorts.
   3. For each available non-Bluetooth serial port:
      1. Let port be a SerialPort representing the port.
      2. Append port to allPorts.
   4. Prompt the user to grant the site access to a serial port by presenting them with a list of ports in allPorts that match any filter in options["filters"] if present and allPorts otherwise.
   5. If the user does not choose a port, queue a global task on the relevant global object of this using the serial port task source to reject promise with a "NotFoundError" DOMException and abort these steps.
   6. Let port be a SerialPort representing the port chosen by the user.
   7. Queue a global task on the relevant global object of this using the serial port task source to resolve promise with port.
6. Return promise.

A serial port is available if it is a wired serial port and the port is physically connected to the system, or if it is a wireless serial port and the wireless device hosting the port is registered with the system.

WebIDLdictionary SerialPortRequestOptions {
  sequence<SerialPortFilter> filters;
  sequence<BluetoothServiceUUID> allowedBluetoothServiceClassIds;
};

WebIDLdictionary SerialPortFilter {
  unsigned short usbVendorId;
  unsigned short usbProductId;
  BluetoothServiceUUID bluetoothServiceClassId;
};

The getPorts() method steps are:

1. Let promise be a new promise.
2. If this's relevant global object's associated Document is not allowed to use the policy-controlled feature named "serial", reject promise with a "SecurityError" DOMException and return promise.
3. Run the following steps in parallel:
   1. Let availablePorts be the sequence of available serial ports which the user has allowed the site to access as the result of a previous call to requestPort().
   2. Let ports be the sequence of the SerialPorts representing the ports in availablePorts.
   3. Queue a global task on the relevant global object of this using the serial port task source to resolve promise with ports.
4. Return promise.

When a serial port that the user has allowed the site to access as the result of a previous call to requestPort() becomes logically connected, run the following steps:

1. Let port be a SerialPort representing the port.
2. Set port.[[connected]] to true.
3. Fire an event named connect at port with its bubbles attribute initialized to true.

A serial port is logically connected if it is a wired serial port and the port is physically connected to the system, or if it is a wireless serial port and the system has active connections to the wireless device (e.g. an open Bluetooth L2CAP channel).

When a serial port that the user has allowed the site to access as the result of a previous call to requestPort() is no longer logically connected, run the following steps:

1. Let port be a SerialPort representing the port.
2. Set port.[[connected]] to false.
3. Fire an event named disconnect at port with its bubbles attribute initialized to true.

1. Let info be an empty ordered map.
2. If the port is part of a USB device, perform the following steps:
   1. Set info["usbVendorId"] to the vendor ID of the device.
   2. Set info["usbProductId"] to the product ID of the device.
3. If the port is a service on a Bluetooth device, perform the following steps:
   1. Set info["bluetoothServiceClassId"] to the service class UUID of the Bluetooth service.
4. Return info.

WebIDLdictionary SerialPortInfo {
  unsigned short usbVendorId;
  unsigned short usbProductId;
  BluetoothServiceUUID bluetoothServiceClassId;
};

The open() method steps are:

1. Let promise be a new promise.
2. If this.[[state]] is not "closed", reject promise with an "InvalidStateError" DOMException and return promise.
3. If options["dataBits"] is not 7 or 8, reject promise with TypeError and return promise.
4. If options["stopBits"] is not 1 or 2, reject promise with TypeError and return promise.
5. If options["bufferSize"] is 0, reject promise with TypeError and return promise.
6. Optionally, if options["bufferSize"] is larger than the implementation is able to support, reject promise with a TypeError and return promise.
7. Set this.[[state]] to "opening".
8. Perform the following steps in parallel.
   1. Invoke the operating system to open the serial port using the connection parameters (or their defaults) specified in options.
   2. If this fails for any reason, queue a global task on the relevant global object of this using the serial port task source to reject promise with a "NetworkError" DOMException and abort these steps.
   3. Set this.[[state]] to "opened".
   4. Set this.[[bufferSize]] to options["bufferSize"].
   5. Queue a global task on the relevant global object of this using the serial port task source to resolve promise with undefined.
9. Return promise.

WebIDLdictionary SerialOptions {
  [EnforceRange] required unsigned long baudRate;
  [EnforceRange] octet dataBits = 8;
  [EnforceRange] octet stopBits = 1;
  ParityType parity = "none";
  [EnforceRange] unsigned long bufferSize = 255;
  FlowControlType flowControl = "none";
};

WebIDLenum ParityType {
  "none",
  "even",
  "odd"
};

WebIDLenum FlowControlType {
  "none",
  "hardware"
};

The connected getter steps are:

1. Return this.[[connected]].

The readable getter steps are:

1. If this.[[readable]] is not null, return this.[[readable]].
2. If this.[[state]] is not "opened", return null.
3. If this.[[readFatal]] is true, return null.
4. Let stream be a new ReadableStream.
5. Let pullAlgorithm be the following steps:
   1. Let desiredSize be the desired size to fill up to the high water mark for this.[[readable]].
   2. If this.[[readable]]'s current BYOB request view is non-null, then set desiredSize to this.[[readable]]'s current BYOB request view's byte length.
   3. Run the following steps in parallel:
      1. Invoke the operating system to read up to desiredSize bytes from the port, putting the result in the byte sequence bytes.
         Note

         this.[[state]] becoming "forgotten" must be treated as if the port was disconnected.
      2. Queue a global task on the relevant global object of this using the serial port task source to run the following steps:
         1. If no errors were encountered, then:
            1. If this.[[readable]]'s current BYOB request view is non-null, then write bytes into this.[[readable]]'s current BYOB request view, and set view to this.[[readable]]'s current BYOB request view.
            2. Otherwise, set view to the result of creating a Uint8Array from bytes in this's relevant Realm.
            3. Enqueue view into this.[[readable]].
         2. If a buffer overrun condition was encountered, invoke error on this.[[readable]] with a "BufferOverrunError" DOMException and invoke the steps to handle closing the readable stream.
         3. If a break condition was encountered, invoke error on this.[[readable]] with a "BreakError" DOMException and invoke the steps to handle closing the readable stream.
         4. If a framing error was encountered, invoke error on this.[[readable]] with a "FramingError" DOMException and invoke the steps to handle closing the readable stream.
         5. If a parity error was encountered, invoke error on this.[[readable]] with a "ParityError" DOMException and invoke the steps to handle closing the readable stream.
         6. If an operating system error was encountered, invoke error on this.[[readable]] with an "UnknownError" DOMException and invoke the steps to handle closing the readable stream.
         7. If the port was disconnected, run the following steps:
            1. Set this.[[readFatal]] to true,
            2. Invoke error on this.[[readable]] with a "NetworkError" DOMException.
            3. Invoke the steps to handle closing the readable stream.
   4. Return a promise resolved with undefined.
   Note

   The Promise returned by this algorithm is immediately resolved so that it does not block canceling the stream. [STREAMS] specifies that this algorithm will not be invoked again until a chunk is enqueued.

6. Let cancelAlgorithm be the following steps:
   1. Let promise be a new promise.
   2. Run the following steps in parallel.
      1. Invoke the operating system to discard the contents of all software and hardware receive buffers for the port.
      2. Queue a global task on the relevant global object of this using the serial port task source to run the following steps:
         1. Invoke the steps to handle closing the readable stream.
         2. Resolve promise with undefined.
   3. Return promise.
7. Set up with byte reading support stream with pullAlgorithm set to pullAlgorithm, cancelAlgorithm set to cancelAlgorithm, and highWaterMark set to this.[[bufferSize]].
8. Set this.[[readable]] to stream.
9. Return stream.

1. Set this.[[readable]] to null.
2. If this.[[writable]] is null and this.[[pendingClosePromise]] is not null, resolve this.[[pendingClosePromise]] with undefined.

The writable getter steps are:

1. If this.[[writable]] is not null, return this.[[writable]].
2. If this.[[state]] is not "opened", return null.
3. If this.[[writeFatal]] is true, return null.
4. Let stream be a new WritableStream.
5. Let signal be stream's signal.
6. Let writeAlgorithm be the following steps, given chunk:
   1. Let promise be a new promise.
   2. Assert: signal is not aborted.
   3. If chunk cannot be converted to an IDL value of type BufferSource, reject promise with a TypeError and return promise. Otherwise, save the result of the conversion in source.
   4. Get a copy of the buffer source source and save the result in bytes.
   5. In parallel, run the following steps:
      1. Invoke the operating system to write bytes to the port. Alternately, store the chunk for future coalescing.
         Note

         The operating system may return from this operation once bytes has been queued for transmission rather than after it has been transmitted.
         Note

         this.[[state]] becoming "forgotten" must be treated as if the port was disconnected.
      2. Queue a global task on the relevant global object of this using the serial port task source to run the following steps:
         1. If the chunk was successfully written, or was stored for future coalescing, resolve promise with undefined.
            Note

            [STREAMS] specifies that writeAlgorithm will only be invoked after the Promise returned by a previous invocation of this algorithm has resolved. For efficiency an implementation is allowed to resolve this Promise early in order to coalesce multiple chunks waiting in the WritableStream's internal queue into a single request to the operating system.
         2. If an operating system error was encountered, reject promise with an "UnknownError" DOMException.
         3. If the port was disconnected, run the following steps:
            1. Set this.[[writeFatal]] to true.
            2. Reject promise with a "NetworkError" DOMException.
            3. Invoke the steps to handle closing the writable stream.
         4. If signal is aborted, reject promise with signal's abort reason.
   6. Return promise.
7. Let abortAlgorithm be the following steps:
   1. Let promise be a new promise.
   2. Run the following steps in parallel.
      1. Invoke the operating system to discard the contents of all software and hardware transmit buffers for the port.
      2. Queue a global task on the relevant global object of this using the serial port task source to run the following steps:
         1. Invoke the steps to handle closing the writable stream.
         2. Resolve promise with undefined.
   3. Return promise.
8. Let closeAlgorithm be the following steps:
   1. Let promise be a new promise.
   2. Run the following steps in parallel.
      1. Invoke the operating system to flush the contents of all software and hardware transmit buffers for the port.
      2. Queue a global task on the relevant global object of this using the serial port task source to run the following steps:
         1. Invoke the steps to handle closing the writable stream.
         2. If signal is aborted, reject promise with signal's abort reason.
         3. Otherwise, resolve promise with undefined.
   3. Return promise.
9. Set up stream with writeAlgorithm set to writeAlgorithm, abortAlgorithm set to abortAlgorithm, closeAlgorithm set to closeAlgorithm, highWaterMark set to this.[[bufferSize]], and sizeAlgorithm set to a byte-counting size algorithm.
10. Add the following abort steps to signal:
    1. Cause any invocation of the operating system to write to the port to return as soon as possible no matter how much data has been written.
11. Set this.[[writable]] to stream.
12. Return stream.

1. Set this.[[writable]] to null.
2. If this.[[readable]] is null and this.[[pendingClosePromise]] is not null, resolve this.[[pendingClosePromise]] with undefined.

The setSignals() method steps are:

1. Let promise be a new promise.
2. If this.[[state]] is not "opened", reject promise with an "InvalidStateError" DOMException and return promise.
3. If all of the specified members of signals are not present reject promise with TypeError and return promise.
4. Perform the following steps in parallel:
   Note

   Ideally the changes specified in signals would be applied atomically however this is not supported by either the POSIX or Windows APIs user agents will use to implement these steps. Therefore the ordering given below is likely to be relied upon by applications.
   1. If signals["dataTerminalReady"] is present, invoke the operating system to either assert (if true) or deassert (if false) the "data terminal ready" or "DTR" signal on the serial port.
   2. If signals["requestToSend"] is present, invoke the operating system to either assert (if true) or deassert (if false) the "request to send" or "RTS" signal on the serial port.
   3. If signals["break"] is present, invoke the operating system to either assert (if true) or deassert (if false) the "break" signal on the serial port.
      Note

      The "break" signal is typically implemented as an in-band signal by holding the transmit line at the "mark" voltage and thus prevents data transmission for as long as it remains asserted.
   4. If the operating system fails to change the state of any of these signals for any reason, queue a global task on the relevant global object of this using the serial port task source to reject promise with a "NetworkError" DOMException.
   5. Queue a global task on the relevant global object of this using the serial port task source to resolve promise with undefined.
5. Return promise.

WebIDLdictionary SerialOutputSignals {
  boolean dataTerminalReady;
  boolean requestToSend;
  boolean break;
};

1. Let promise be a new promise.
2. If this.[[state]] is not "opened", reject promise with an "InvalidStateError" DOMException and return promise.
3. Perform the following steps in parallel:
   1. Query the operating system for the status of the control signals that may be asserted by the device connected to the serial port.
   2. If the operating system fails to determine the status of these signals for any reason, queue a global task on the relevant global object of this using the serial port task source to reject promise with a "NetworkError" DOMException and abort these steps.
   3. Let dataCarrierDetect be true if the "data carrier detect" or "DCD" signal has been asserted by the device, and false otherwise.
   4. Let clearToSend be true if the "clear to send" or "CTS" signal has been asserted by the device, and false otherwise.
   5. Let ringIndicator be true if the "ring indicator" or "RI" signal has been asserted by the device, and false otherwise.
   6. Let dataSetReady be true if the "data set ready" or "DSR" signal has been asserted by the device, and false otherwise.
   7. Let signals be the ordered map «[ "dataCarrierDetect" → dataCarrierDetect, "clearToSend" → clearToSend, "ringIndicator" → ringIndicator, "dataSetReady" → dataSetReady ]».
   8. Queue a global task on the relevant global object of this using the serial port task source to resolve promise with signals.
4. Return promise.

WebIDLdictionary SerialInputSignals {
  required boolean dataCarrierDetect;
  required boolean clearToSend;
  required boolean ringIndicator;
  required boolean dataSetReady;
};

The close() method steps are:

1. Let promise be a new promise.
2. If this.[[state]] is not "opened", reject promise with an "InvalidStateError" DOMException and return promise.
3. Let cancelPromise be the result of invoking cancel on this.[[readable]] or a promise resolved with undefined if this.[[readable]] is null.
4. Let abortPromise be the result of invoking abort on this.[[writable]] or a promise resolved with undefined if this.[[writable]] is null.
5. Let pendingClosePromise be a new promise.
6. If this.[[readable]] and this.[[writable]] are null, resolve pendingClosePromise with undefined.
7. Set this.[[pendingClosePromise]] to pendingClosePromise.
8. Let combinedPromise be the result of getting a promise to wait for all with «cancelPromise, abortPromise, pendingClosePromise».
9. Set this.[[state]] to "closing".
10. React to combinedPromise.
    • If combinedPromise was fulfilled, then:
      1. Run the following steps in parallel:
         1. Invoke the operating system to close the serial port and release any associated resources.
         2. Set this.[[state]] to "closed".
         3. Set this.[[readFatal]] and this.[[writeFatal]] to false.
         4. Set this.[[pendingClosePromise]] to null.
         5. Queue a global task on the relevant global object of this using the serial port task source to resolve promise with undefined.
    • If combinedPromise was rejected with reason r, then:
      1. Set this.[[pendingClosePromise]] to null.
      2. Queue a global task on the relevant global object of this using the serial port task source to reject promise with r.
11. Return promise.

The forget() method steps are:

1. If the user agent can't perform this action (e.g. permission was granted by administrator policy), return a promise resolved with undefined.
2. Run the following steps in parallel:
   1. Set this.[[state]] to "forgetting".
   2. Remove this from the sequence of serial ports on the system which the user has allowed the site to access as the result of a previous call to requestPort().
   3. Set this.[[state]] to "forgotten".
   4. Queue a global task on the relevant global object of this using the serial port task source to resolve promise with undefined.
3. Return promise.

This specification defines a feature that controls whether the methods exposed by the serial attribute on the Navigator object may be used.

The feature name for this feature is "serial"`.

The default allowlist for this feature is 'self'.