Intent to Ship: Web Serial API

386 views
Skip to first unread message

Reilly Grant

unread,
Dec 4, 2020, 8:16:03 PM12/4/20
to blink-dev

Contact emails

rei...@chromium.org


Explainer

https://github.com/WICG/serial/blob/gh-pages/EXPLAINER.md


Specification

https://wicg.github.io/serial/


API spec

Yes.


Design docs

https://web.dev/serial/


Summary

The Serial API provides an interface for connecting to serial devices, either through a serial port on the user’s system or removable USB and Bluetooth devices that emulate a serial port. This API has been requested by the hardware developer community, especially developers building educational tools, as a companion to the WebUSB API because operating systems require applications to communicate with USB-based serial ports using their higher-level serial API rather than the low-level USB API. It also supports non-USB serial ports.


We are requesting a gapless transition from Origin Trial to stable release for the API in order to prevent developers from having to deploy non-web versions of their applications to cover the gap. Throughout the trial we have asked developers to adapt to changes in the API, to which they have been very responsive. There will be one more such change made as part of shipping, which is the following:


As of Chrome 89 the SerialConnectionEvent interface has been removed. When a “connect” or “disconnect” event is fired the target is the SerialPort interface itself (it bubbles to navigator.serial) and so the port can be accessed as e.target instead of e.port.


Blink component

Blink>Serial


TAG review

https://github.com/w3ctag/design-reviews/issues/431


TAG review status

Pending


Link to origin trial feedback summary

https://docs.google.com/document/d/1vcjw-9q14Sr9v7ce3YR5gGzamykv_0Gbv4TDqGPdZCQ/edit


Risks


Interoperability and Compatibility


Gecko: Negative (https://mozilla.github.io/standards-positions/#webserial)


WebKit: Negative (https://webkit.org/tracking-prevention/)


Web developers: Strongly positive (https://discourse.wicg.io/t/serial-api-moving-from-web-of-sensors-cg-to-web-incubator-cg/2940)


Debuggability

Developers are able to debug script using this feature using the existing DevTools console and debugger. For debugging device communication issues it is often convenient to use the tee() method provided by the ReadableStream to split the streams going to or from the device and print them to the console for inspection.


Is this feature fully tested by web-platform-tests?

Partially. WebIDL conformance and Permissions Policy tests are already upstreamed. More extensive Web Platform Tests have been prototyped in the Chromium wpt_internal directory and should be exportable to upstream Web Platform Tests by leveraging the work that Robert Ma has done on standardizing how we implement Mojo-based test-only APIs. This will be completed ASAP.


Tracking bug

https://crbug.com/884928


Launch bug

https://crbug.com/967863


Sample links

https://googlechromelabs.github.io/serial-terminal


Link to entry on the Chrome Platform Status

https://chromestatus.com/feature/6577673212002304


Links to previous Intent discussions

Intent to prototype: https://groups.google.com/a/chromium.org/d/msg/blink-dev/GcqEnSW5yHs/r7G3iMmDCQAJ

Intent to experiment #1:

https://groups.google.com/a/chromium.org/g/blink-dev/c/AiGJihoCbl4/m/OmA24108DwAJ

Intent to experiment #2:

https://groups.google.com/a/chromium.org/g/blink-dev/c/P5uKC_HTStw/m/VjYdUfg-BQAJ

Intent to experiment #3: https://groups.google.com/a/chromium.org/g/blink-dev/c/NGgprfPEbG0/m/nhNCiN0ZBgAJ


This intent message was generated by Chrome Platform Status and edited by hand.

Reilly Grant | Software Engineer | rei...@chromium.org | Google Chrome

Domenic Denicola

unread,
Dec 7, 2020, 11:27:57 AM12/7/20
to blink-dev, Reilly Grant

I've been acting as a Chromium specification mentor for this API, and am very happy with the quality of the resulting specification:

  • It's appropriately detailed and algorithmic, with every method and property specified through concrete steps. Reilly has paid close attention to commonly-missed spec issues like task queuing, error handling, or detailing which document or global object is involved in policy checks.

  • It integrates with and builds on Streams very well, using well-defined extension points and giving a detailed account of how an implementation should bridge from the OS-level serial port interfaces to the web-exposed streams APIs.

  • Although I am not a domain expert in serial communication, from what I can tell a lot of care seems to have gone into the API design, in terms of making it easy to use and integrating well with web platform primitives like promises and streams. The spec contains detailed examples showing how easy situations are relatively easy, and more complicated situations are no more complex than they need to be. A small example of this is issue #87.

  • It contains detailed security and privacy considerations sections which discuss the nuanced tradeoffs involved, with more details in the security and privacy questionnaire answers. (I've suggested moving a bit of useful information from the questionnaire answers into the spec's privacy considerations section.)

The only remaining issue that came up during review is that there's currently an underspecified storage mechanism backing "the sequence of available serial ports on the system which the user has allowed the site to access as the result of a previous call to requestPort()." I have confidence that Reilly will address this in the near future, and don't consider it an impediment to this API's ship-readiness.  

melkysand38776

unread,
Dec 7, 2020, 2:15:03 PM12/7/20
to Domenic Denicola, blink-dev, Reilly Grant




Dikirim dari Galaxy saya


-------- Pesan asli --------
Dari: Domenic Denicola <dom...@chromium.org>
Tanggal: 07/12/20 23:27 (GMT+07:00)
Ke: blink-dev <blin...@chromium.org>
Cc: Reilly Grant <rei...@chromium.org>
Subjek: [blink-dev] Re: Intent to Ship: Web Serial API

--
You received this message because you are subscribed to the Google Groups "blink-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.
To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/bd3c407b-7c5a-415f-a752-74272eced571n%40chromium.org.

Fergal Daly

unread,
Dec 9, 2020, 4:32:19 AM12/9/20
to blink-dev, Reilly Grant, bfcache-dev
[+bfcache-dev]

Hi Reilly,

how does WebSerial interact with Chrome's BFCache? Can we make it so that a page that has an open serial connection can safely be put into BFCache and will work when it comes out without breaking user expectations (that they had navigated away from the page)? If not, we need to ensure that pages using WebSerial do not go into BFCache when it would be a problem.

We have put together a doc that hopefully provides enough information for feature teams to figure this out. Could you take a look and figure out what issues there may be? It's a new doc so feedback on the doc itself is also appreciated. 

The simplest course of action is to blocklist all pages that use WebSerial but ideally we can ensure that they work well together. Thanks,

F

Reilly Grant

unread,
Dec 9, 2020, 2:24:07 PM12/9/20
to blink-dev
Web Platform Tests for this API have now been upstreamed. Results for automated tests at https://wpt.fyi/results/serial should be available soon. The manual tests can be run on https://wpt.live/serial/ if you have a serial device you can wire up in a loopback configuration.

Reilly Grant | Software Engineer | rei...@chromium.org | Google Chrome

Reilly Grant

unread,
Dec 9, 2020, 5:08:03 PM12/9/20
to Fergal Daly, blink-dev, bfcache-dev
I've met with the BFCache team to figure out how to support BFCache with WebUSB, and supporting it with Web Serial will have similar challenges. I've filed https://github.com/WICG/serial/issues/109 to track defining the integration points so that we can avoid continuing to blocklist all pages that are using Web Serial as we currently do.

Reilly Grant | Software Engineer | rei...@chromium.org | Google Chrome

Fergal Daly

unread,
Dec 10, 2020, 11:34:51 PM12/10/20
to Reilly Grant, blink-dev, bfcache-dev
Thanks!

F

yo...@yoav.ws

unread,
Dec 17, 2020, 2:23:35 PM12/17/20
to blink-dev, Fergal Daly, blink-dev, bfcache-dev, rei...@chromium.org

LGTM1

This seems like an important addition to the web platform, that enables unique use-cases that were previously reserved to native apps, with their associated deployment pain. Thanks for working on this!!

Mike West

unread,
Dec 17, 2020, 3:00:33 PM12/17/20
to blink-dev, yo...@yoav.ws, Fergal Daly, blink-dev, bfcache-dev, Reilly Grant
LGTM2.

Similar to the WebHID API, I'm happy with the work the team has done to address security and privacy concerns. The interaction model has proven effective, there's a good story around user-facing indicators, and we have the ability to cut off access to devices when that proves to be particularly dangerous. The implementation puts the user in control, and I'm excited to see it launch.

With regard to the gapless OT, there's good evidence of developer feedback, and equally good evidence that the API has changed in response. Given that we have confidence in the shape of the API, it seems reasonable to me to move it directly from OT to stable without enforcing a gap in availability. So, that bit specifically LGTM.

-mike

Chris Harrelson

unread,
Dec 17, 2020, 3:21:58 PM12/17/20
to Mike West, blink-dev, yo...@yoav.ws, Fergal Daly, bfcache-dev, Reilly Grant
LGTM3

--
You received this message because you are subscribed to the Google Groups "blink-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.

Reilly Grant

unread,
Dec 17, 2020, 5:32:43 PM12/17/20
to Mike West, blink-dev, yo...@yoav.ws, Fergal Daly, bfcache-dev
On Thu, Dec 17, 2020 at 12:00 PM Mike West <mk...@chromium.org> wrote:
LGTM2.

Similar to the WebHID API, I'm happy with the work the team has done to address security and privacy concerns. The interaction model has proven effective, there's a good story around user-facing indicators, and we have the ability to cut off access to devices when that proves to be particularly dangerous. The implementation puts the user in control, and I'm excited to see it launch.

A nuance from the "Security considerations" section of the specification that may have been missed in your analysis is that while we can implement a block list for USB serial devices in particular because of the out-of-band identifiers that USB provides there is no solution for generally blocking access to any serial device (such as one connected via a generic adapter) as the serial protocol itself does not provide a means to identify the connected device.

Mike West

unread,
Dec 18, 2020, 1:50:32 AM12/18/20
to Reilly Grant, blink-dev, yo...@yoav.ws, Fergal Daly, bfcache-dev
Thanks, Reilly! I framed this comment poorly, and I appreciate the clarification.

I meant to convey my understanding is that serial-over-{USB,Bluetooth} runs any available vendor and product IDs through the same blocklist as WebUSB and Web Bluetooth, giving us some ability to mitigate risk for identifiable devices. Is that accurate?

In cases where these identifiers are either generic or unavailable (in the case of "actual" serial ports soldered to a board), we're relying on direct user control via the chooser-based UX as the primary mitigation.

-mike

Reilly Grant

unread,
Jan 7, 2021, 9:43:37 PMJan 7
to Mike West, blink-dev, yo...@yoav.ws, Fergal Daly, bfcache-dev
On Thu, Dec 17, 2020 at 10:50 PM Mike West <mk...@chromium.org> wrote:
Thanks, Reilly! I framed this comment poorly, and I appreciate the clarification.

I meant to convey my understanding is that serial-over-{USB,Bluetooth} runs any available vendor and product IDs through the same blocklist as WebUSB and Web Bluetooth, giving us some ability to mitigate risk for identifiable devices. Is that accurate?

In crrev.com/c/2613792 I have implemented a Web Serial-specific blocklist which currently only supports matching against USB devices but is extensible to Bluetooth and other device types. There are platform limitations preventing us from recognizing useful properties of Bluetooth devices at the moment. This is something we can work on going forward and will likely be unblocked by work to improve support for Bluetooth serial devices in crbug.com/1043300.

Reilly Grant

unread,
Jan 8, 2021, 5:45:00 PMJan 8
to Chris Harrelson, Mike West, blink-dev, yo...@yoav.ws, Fergal Daly, bfcache-dev
Do API OWNERS approve the requested gapless transition from Origin Trial to stable?

Reilly Grant | Software Engineer | rei...@chromium.org | Google Chrome

Chris Harrelson

unread,
Jan 8, 2021, 5:58:21 PMJan 8
to Reilly Grant, Mike West, blink-dev, yo...@yoav.ws, Fergal Daly, bfcache-dev
Yes, gapless LGTM, per what Mike said.

Reilly Grant

unread,
Jan 13, 2021, 9:40:09 PMJan 13
to Chris Harrelson, Mike West, blink-dev, yo...@yoav.ws, Fergal Daly, bfcache-dev
Thanks. Over the holidays I forgot that he'd already approved it.

Reilly Grant | Software Engineer | rei...@chromium.org | Google Chrome

Reply all
Reply to author
Forward
0 new messages