Add Serial API Content (#2700)

* Add Serial interface and its members. * Add SerialPort interface and its members. * Tidy up of existing pages * Update files/en-us/web/api/serial/index.html Co-authored-by: Ruth John <Rumyra@users.noreply.github.com> * Update files/en-us/web/api/serialport/open/index.html Co-authored-by: Ruth John <Rumyra@users.noreply.github.com> * Update files/en-us/web/api/serialport/writable/index.html Co-authored-by: Ruth John <Rumyra@users.noreply.github.com> * Update files/en-us/web/api/serialport/ondisconnect/index.html Co-authored-by: Ruth John <Rumyra@users.noreply.github.com> * Update files/en-us/web/api/serialport/onconnect/index.html Co-authored-by: Ruth John <Rumyra@users.noreply.github.com> * Update files/en-us/web/api/serialport/onconnect/index.html Co-authored-by: Ruth John <Rumyra@users.noreply.github.com> * Update files/en-us/web/api/serial/requestport/index.html Co-authored-by: Ruth John <Rumyra@users.noreply.github.com> * Update files/en-us/web/api/serial/onconnect/index.html Co-authored-by: Ruth John <Rumyra@users.noreply.github.com> * Update files/en-us/web/api/serial/requestport/index.html Co-authored-by: Ruth John <Rumyra@users.noreply.github.com> * Update files/en-us/web/api/serialport/index.html Co-authored-by: Ruth John <Rumyra@users.noreply.github.com> * Update files/en-us/web/api/serialport/onconnect/index.html Co-authored-by: Ruth John <Rumyra@users.noreply.github.com> * Update files/en-us/web/api/serial/index.html Co-authored-by: Ruth John <Rumyra@users.noreply.github.com> Co-authored-by: Rachel Andrew <me@rachelandrew.co.uk> Co-authored-by: Rachel Andrew <rachel.andrew@edgeofmyseat.com> Co-authored-by: Ruth John <Rumyra@users.noreply.github.com>
mdn · Mar 3, 2021 · bbce399 · bbce399
1 parent 5de2470
commit bbce399
Show file tree

Hide file tree

Showing 15 changed files with 973 additions and 0 deletions.
diff --git a/files/en-us/web/api/serial/getports/index.html b/files/en-us/web/api/serial/getports/index.html
@@ -0,0 +1,59 @@
+---
+title: Serial.getPorts()
+slug: Web/API/Serial/getPorts
+tags:
+  - API
+  - Method
+  - Reference
+  - Serial.getPorts
+  - Serial
+---
+<div>{{securecontext_header}}{{DefaultAPISidebar("Serial API")}}</div>
+
+<p class="summary">The <strong><code>getPorts()</code></strong> method of the {{domxref("Serial")}} interface returns a {{jsxref("Promise")}} that resolves with an array of {{domxref("SerialPort")}} objects representing serial ports connected to the host which the origin has permission to access. </p>
+
+<h2 id="Syntax">Syntax</h2>
+
+<pre class="syntaxbox notranslate">var <var>promise</var> = <var>Serial</var>.getPorts();</pre>
+
+<h3 id="Returns">Return value</h3>
+
+<p>A {{jsxref("Promise")}} that resolves with an array of {{domxref("SerialPort")}} objects.</p>
+
+<h3 id="Exceptions">Exceptions</h3>
+
+<dl>
+  <dt>{{domxref("DOMException")}} <code>"SecurityError"</code></dt>
+  <dd>The returned <code>Promise</code> rejects with this error if a <a href="/en-US/docs/Web/HTTP/Feature_Policy">Feature Policy</a> restricts use of this API or a permission to use it has not granted via a user gesture.</dd>
+</dl>
+
+<h2 id="Examples">Examples</h2>
+
+<p>The following example uses <code>getPorts()</code> to initialize a list of available ports.</p>
+
+<pre class="brush: js notranslate">navigator.serial.getPorts().then((ports) => {
+  // Initialize the list of available ports with `ports` on page load.
+});</pre>
+
+<h2 id="Specifications">Specifications</h2>
+
+<table class="standard-table">
+ <tbody>
+  <tr>
+   <th scope="col">Specification</th>
+   <th scope="col">Status</th>
+   <th scope="col">Comment</th>
+  </tr>
+  <tr>
+   <td>{{SpecName('Web Serial API','#dom-serial-getports','Serial.getPorts()')}}</td>
+   <td>{{Spec2('Web Serial API')}}</td>
+   <td>Initial definition.</td>
+  </tr>
+ </tbody>
+</table>
+
+<h2 id="Browser_compatibility">Browser compatibility</h2>
+
+<div class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</div>
+
+<p>{{Compat("api.Serial.getPorts")}}</p>
diff --git a/files/en-us/web/api/serial/index.html b/files/en-us/web/api/serial/index.html
@@ -0,0 +1,91 @@
+---
+title: Serial
+slug: Web/API/Serial
+tags:
+  - API
+  - Interface
+  - Reference
+  - Serial
+---
+<div>{{securecontext_header}}{{DefaultAPISidebar("Serial API")}}</div>
+
+<h2 id="Description">Description</h2>
+
+<p>The <code>Serial</code> interface of the {{domxref("Web_Serial_API", "Web Serial API")}} provides attributes and methods for finding and connecting to serial ports from a web page.</p>
+
+
+<h2 id="Event_handlers">Event Handlers</h2>
+
+<dl>
+  <dt>{{domxref("Serial.onconnect")}}</dt>
+  <dd>An event handler called when a port has been connected to the device.</dd>
+  <dt>{{domxref("Serial.ondisconnect")}}</dt>
+  <dd>An event handler called when a port has been disconnected from the device.</dd>
+</dl>
+
+<h2 id="Methods">Methods</h2>
+
+<dl>
+  <dt>{{domxref("Serial.requestPort()")}}</dt>
+  <dd>
+    <p>Returns a {{jsxref("Promise")}} that resolves with an instance of {{domxref("SerialPort")}} representing the device chosen by the user or rejects if no device was selected.</p>
+    <p>This method must be called with user activation.</p>
+  </dd>
+  <dt>{{domxref("Serial.getPorts()")}}</dt>
+  <dd>
+    Returns a {{jsxref("Promise")}} that resolves with an array of  {{domxref("SerialPort")}} objects representing serial ports connected to
+    the host which the origin has permission to access.
+  </dd>
+</dl>
+
+<h2 id="Examples">Examples</h2>
+
+<p>The following example shows how a site can check for available ports and allow the user to grant it permission to access additional ports.</p>
+
+<p>On load event listeners are added for the <code>connect</code> and <code>disconnect</code> events so that the site can react when a device is connected or disconnected from the system. The {{domxref("Serial.getPorts()","getPorts()")}} method is then called to see which ports are connected that the site already has access to.</p>
+
+<p>If the site doesn't have access to any connected ports it has to wait until it has user activation to proceed. In this example we use a {{domxref("Element.click_event", "click")}} event handler on a button for this task. A filter is passed to {{domxref("Serial.requestPort()","requestPort()")}} with a USB vendor ID in order to limit the set of devices shown to the user to only USB devices built by a particular manufacturer.</p>
+
+<pre class="brush: js">navigator.serial.addEventListener('connect', (e) => {
+  // Connect to `e.target` or add it to a list of available ports.
+});
+
+navigator.serial.addEventListener('disconnect', (e) => {
+  // Remove `e.target` from the list of available ports.
+});
+
+navigator.serial.getPorts().then((ports) => {
+  // Initialize the list of available ports with `ports` on page load.
+});
+
+button.addEventListener('click', () => {
+  const usbVendorId = ...;
+  navigator.serial.requestPort({ filters: [{ usbVendorId }]}).then((port) => {
+    // Connect to `port` or add it to the list of available ports.
+  }).catch((e) => {
+    // The user didn't select a port.
+  });
+});</pre>
+
+<h2 id="Specifications">Specifications</h2>
+
+<table class="standard-table">
+ <tbody>
+  <tr>
+   <th scope="col">Specification</th>
+   <th scope="col">Status</th>
+   <th scope="col">Comment</th>
+  </tr>
+  <tr>
+   <td>{{SpecName('Web Serial API','#serial-interface','Serial')}}</td>
+   <td>{{Spec2('Web Serial API')}}</td>
+   <td>Initial definition.</td>
+  </tr>
+ </tbody>
+</table>
+
+<h2 id="Browser_compatibility">Browser compatibility</h2>
+
+<div class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</div>
+
+<p>{{Compat("api.Serial")}}</p>
diff --git a/files/en-us/web/api/serial/onconnect/index.html b/files/en-us/web/api/serial/onconnect/index.html
@@ -0,0 +1,51 @@
+---
+title: Serial.onconnect
+slug: Web/API/Serial/onconnect
+tags:
+  - API
+  - Property
+  - Reference
+  - Serial.onconnect
+  - Serial
+---
+<div>{{securecontext_header}}{{DefaultAPISidebar("Serial API")}}</div>
+
+<p class="summary">The <strong><code>onconnect</code></strong> {{domxref("EventHandler")}} of the {{domxref("Serial")}} interface is called when a port has been connected from a device. This method receives an {{domxref("Event")}} object. The target of this event is the {{domxref("SerialPort")}} interface that has been disconnected.
+
+<p>This event is only fired for ports associated with removable devices such as those connected via USB. The user must grant the origin permission to access this device during a call to {{domxref("Serial.requestPort()","requestPort()")}} before this event will be fired.</p>
+
+<h2 id="Syntax">Syntax</h2>
+
+<pre class="syntaxbox">Serial.onconnect = <var>function(event)</var>;
+Serial.addEventListener('connect', <var>function(event)</var>);</pre>
+
+<h2>Example</h2>
+
+<p>The following example shows an event listener for the <code>connect</code> event,. This allows the site to react when a port is connected.</p>
+
+<pre class="brush: js">navigator.serial.addEventListener('connect', (e) => {
+  // Connect to `e.target` or add it to a list of available ports.
+});</pre>
+
+<h2 id="Specifications">Specifications</h2>
+
+<table class="standard-table">
+ <tbody>
+  <tr>
+   <th scope="col">Specification</th>
+   <th scope="col">Status</th>
+   <th scope="col">Comment</th>
+  </tr>
+  <tr>
+   <td>{{SpecName('Web Serial API','#dom-serial-onconnect','Serial.onconnect')}}</td>
+   <td>{{Spec2('Web Serial API')}}</td>
+   <td>Initial definition.</td>
+  </tr>
+ </tbody>
+</table>
+
+<h2 id="Browser_compatibility">Browser compatibility</h2>
+
+<div class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</div>
+
+<p>{{Compat("api.Serial.onconnect")}}</p>
diff --git a/files/en-us/web/api/serial/ondisconnect/index.html b/files/en-us/web/api/serial/ondisconnect/index.html
@@ -0,0 +1,51 @@
+---
+title: Serial.ondisconnect
+slug: Web/API/Serial/ondisconnect
+tags:
+  - API
+  - Property
+  - Reference
+  - Serial.ondisconnect
+  - Serial
+---
+<div>{{securecontext_header}}{{DefaultAPISidebar("Serial API")}}</div>
+
+<p class="summary">The <strong><code>ondisconnect</code></strong> EventHandler of the {{domxref("Serial")}} interface is called when the port has been disconnected from the device. This method receives an {{domxref("Event")}} object. The target of this event is the {{domxref("SerialPort")}} interface that has been disconnected.</p>
+
+<p>This event is only fired for ports associated with removable devices such as those connected via USB. The user must grant the origin permission to access this device during a call to {{domxref("Serial.requestPort()", "requestPort()")}} before this event will be fired.</p>
+
+<h2 id="Syntax">Syntax</h2>
+
+<pre class="syntaxbox">Serial.ondisconnect = <var>function(event)</var>;
+Serial.addEventListener('disconnect', <var>function(event)</var>);</pre>
+
+<h2>Example</h2>
+
+<p>The following example shows an event listener for the <code>disconnect</code> event,. This allows the site to react when a port is disconnected.</p>
+
+<pre class="brush: js">navigator.serial.addEventListener('disconnect', (e) => {
+  // Remove `e.target` from the list of available ports.
+});</pre>
+
+<h2 id="Specifications">Specifications</h2>
+
+<table class="standard-table">
+ <tbody>
+  <tr>
+   <th scope="col">Specification</th>
+   <th scope="col">Status</th>
+   <th scope="col">Comment</th>
+  </tr>
+  <tr>
+   <td>{{SpecName('Web Serial API','#dom-serial-ondisconnect','Serial.ondisconnect')}}</td>
+   <td>{{Spec2('Web Serial API')}}</td>
+   <td>Initial definition.</td>
+  </tr>
+ </tbody>
+</table>
+
+<h2 id="Browser_compatibility">Browser compatibility</h2>
+
+<div class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</div>
+
+<p>{{Compat("api.Serial.ondisconnect")}}</p>
diff --git a/files/en-us/web/api/serial/requestport/index.html b/files/en-us/web/api/serial/requestport/index.html
@@ -0,0 +1,83 @@
+---
+title: Serial.requestPort()
+slug: Web/API/Serial/requestPort
+tags:
+  - API
+  - Method
+  - Reference
+  - requestPort
+  - Serial
+---
+<div>{{securecontext_header}}{{DefaultAPISidebar("Serial API")}}</div>
+
+<p class="summary">The <strong><code>Serial.requestPort()</code></strong> method of the {{domxref("Serial")}} interface returns a {{jsxref("Promise")}} that resolves with an instance of {{domxref("SerialPort")}} representing the device chosen by the user or rejects if no device was selected.</p>
+
+<h2 id="Syntax">Syntax</h2>
+
+<pre class="syntaxbox notranslate">var <var>promise</var> = Serial.requestPort([<var>options</var>]);</pre>
+
+<h3 id="Parameters">Parameters</h3>
+
+<dl>
+  <dt>options</dt>
+  <dd>
+    <dl>
+      <dt><code>filters</code></dt>
+      <dd>A list of objects containing vendor and product IDs used to search for attached devices. The <a href="https://www.usb.org/">USB Implementors Forum</a> assigns IDs to specific companies. Each company assigns IDS to it's products. Filters contain the following values:
+        <ul>
+          <li><code>usbVendorId</code>: An unsigned short integer that identifies a USB device vendor. </li>
+          <li><code>usbProductId</code>: An unsigned short integer that identiffies a USB device.</li>
+        </ul>
+      </dd>
+    </dl>
+  </dd>
+</dl>
+
+<h3 id="Returns">Return value</h3>
+
+<p>A {{jsxref("Promise")}} that resolves with an instance of {{domxref("SerialPort")}}.</p>
+
+<h3 id="Exceptions">Exceptions</h3>
+
+<dl>
+  <dt>{{domxref("DOMException")}} <code>"SecurityError"</code></dt>
+  <dd>The returned <code>Promise</code> rejects with this error if a <a href="/en-US/docs/Web/HTTP/Feature_Policy">Feature Policy</a> restricts use of this API or a permission to use it has not granted via a user gesture.</dd>
+  <dt>{{domxref("DOMException")}} <code>"AbortError"</code></dt>
+  <dd>The returned <code>Promise</code> rejects with this if the user does not select a port when prompted.</dd>
+</dl>
+
+<h2 id="Examples">Examples</h2>
+
+<p>The following example shows a filter being passed to <code>requestPort()</code> with a USB vendor ID in order to limit the set of devices shown to the user to only USB devices built by a particular manufacturer. If this filter was omitted the user would be able to select any available port.</p>
+
+<pre class="brush: js">button.addEventListener('click', () => {
+  const usbVendorId = ...;
+  navigator.serial.requestPort({ filters: [{ usbVendorId }]}).then((port) => {
+    // Connect to `port` or add it to the list of available ports.
+  }).catch((e) => {
+    // The user didn't select a port.
+  });
+});</pre>
+
+<h2 id="Specifications">Specifications</h2>
+
+<table class="standard-table">
+ <tbody>
+  <tr>
+   <th scope="col">Specification</th>
+   <th scope="col">Status</th>
+   <th scope="col">Comment</th>
+  </tr>
+  <tr>
+   <td>{{SpecName('Web Serial API','#dom-serial-requestport','Serial.requestPort()')}}</td>
+   <td>{{Spec2('Web Serial API')}}</td>
+   <td>Initial definition.</td>
+  </tr>
+ </tbody>
+</table>
+
+<h2 id="Browser_compatibility">Browser compatibility</h2>
+
+<div class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</div>
+
+<p>{{Compat("api.Serial.requestPort")}}</p>
diff --git a/files/en-us/web/api/serialport/close/index.html b/files/en-us/web/api/serialport/close/index.html
@@ -0,0 +1,48 @@
+---
+title: SerialPort.close()
+slug: Web/API/SerialPort/close
+tags:
+  - API
+  - Method
+  - Reference
+  - close
+  - SerialPort
+---
+<div>{{securecontext_header}}{{DefaultAPISidebar("Serial API")}}</div>
+
+<p class="summary">The <strong><code>SerialPort.close()</code></strong> method of the {{domxref("SerialPort")}} interface returns a {{jsxref("Promise")}} that resolves when the port closes.</p>
+
+<h2 id="Syntax">Syntax</h2>
+
+<pre class="syntaxbox notranslate">var <var>promise</var> = <var>SerialPort</var>.close();</pre>
+
+<h3 id="Parameters">Parameters</h3>
+
+<p>None.</p>
+
+<h3 id="Returns">Return value</h3>
+
+<p>A {{jsxref("Promise")}}.</p>
+
+<h2 id="Specifications">Specifications</h2>
+
+<table class="standard-table">
+ <tbody>
+  <tr>
+   <th scope="col">Specification</th>
+   <th scope="col">Status</th>
+   <th scope="col">Comment</th>
+  </tr>
+  <tr>
+   <td>{{SpecName('Web Serial API','#dom-serialport-close','SerialPort.close()')}}</td>
+   <td>{{Spec2('Web Serial API')}}</td>
+   <td>Initial definition.</td>
+  </tr>
+ </tbody>
+</table>
+
+<h2 id="Browser_compatibility">Browser compatibility</h2>
+
+<div class="hidden">The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> and send us a pull request.</div>
+
+<p>{{Compat("api.SerialPort.close()")}}</p>