The getPorts() 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.
var promise = Serial.getPorts();+ +
A {{jsxref("Promise")}} that resolves with an array of {{domxref("SerialPort")}} objects.
+ +"SecurityError"Promise rejects with this error if a Feature Policy restricts use of this API or a permission to use it has not granted via a user gesture.The following example uses getPorts() to initialize a list of available ports.
navigator.serial.getPorts().then((ports) => {
+ // Initialize the list of available ports with `ports` on page load.
+});
+
+| Specification | +Status | +Comment | +
|---|---|---|
| {{SpecName('Web Serial API','#dom-serial-getports','Serial.getPorts()')}} | +{{Spec2('Web Serial API')}} | +Initial definition. | +
{{Compat("api.Serial.getPorts")}}
diff --git a/files/en-us/web/api/serial/index.html b/files/en-us/web/api/serial/index.html new file mode 100644 index 000000000000000..90ed5af9a5b6ff8 --- /dev/null +++ b/files/en-us/web/api/serial/index.html @@ -0,0 +1,91 @@ +--- +title: Serial +slug: Web/API/Serial +tags: + - API + - Interface + - Reference + - Serial +--- +The Serial 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.
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.
+This method must be called with user activation.
+The following example shows how a site can check for available ports and allow the user to grant it permission to access additional ports.
+ +On load event listeners are added for the connect and disconnect 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.
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.
+ +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.
+ });
+});
+
+| Specification | +Status | +Comment | +
|---|---|---|
| {{SpecName('Web Serial API','#serial-interface','Serial')}} | +{{Spec2('Web Serial API')}} | +Initial definition. | +
{{Compat("api.Serial")}}
diff --git a/files/en-us/web/api/serial/onconnect/index.html b/files/en-us/web/api/serial/onconnect/index.html new file mode 100644 index 000000000000000..819c833a0471218 --- /dev/null +++ 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 +--- +The onconnect {{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.
+
+
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.
+ +Serial.onconnect = function(event);
+Serial.addEventListener('connect', function(event));
+
+The following example shows an event listener for the connect event,. This allows the site to react when a port is connected.
navigator.serial.addEventListener('connect', (e) => {
+ // Connect to `e.target` or add it to a list of available ports.
+});
+
+| Specification | +Status | +Comment | +
|---|---|---|
| {{SpecName('Web Serial API','#dom-serial-onconnect','Serial.onconnect')}} | +{{Spec2('Web Serial API')}} | +Initial definition. | +
{{Compat("api.Serial.onconnect")}}
diff --git a/files/en-us/web/api/serial/ondisconnect/index.html b/files/en-us/web/api/serial/ondisconnect/index.html new file mode 100644 index 000000000000000..aa1b6eb449485c8 --- /dev/null +++ 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 +--- +The ondisconnect 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.
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.
+ +Serial.ondisconnect = function(event);
+Serial.addEventListener('disconnect', function(event));
+
+The following example shows an event listener for the disconnect event,. This allows the site to react when a port is disconnected.
navigator.serial.addEventListener('disconnect', (e) => {
+ // Remove `e.target` from the list of available ports.
+});
+
+| Specification | +Status | +Comment | +
|---|---|---|
| {{SpecName('Web Serial API','#dom-serial-ondisconnect','Serial.ondisconnect')}} | +{{Spec2('Web Serial API')}} | +Initial definition. | +
{{Compat("api.Serial.ondisconnect")}}
diff --git a/files/en-us/web/api/serial/requestport/index.html b/files/en-us/web/api/serial/requestport/index.html new file mode 100644 index 000000000000000..a59d82257db1148 --- /dev/null +++ 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 +--- +The Serial.requestPort() 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.
var promise = Serial.requestPort([options]);+ +
filtersusbVendorId: An unsigned short integer that identifies a USB device vendor. usbProductId: An unsigned short integer that identiffies a USB device.A {{jsxref("Promise")}} that resolves with an instance of {{domxref("SerialPort")}}.
+ +"SecurityError"Promise rejects with this error if a Feature Policy restricts use of this API or a permission to use it has not granted via a user gesture."AbortError"Promise rejects with this if the user does not select a port when prompted.The following example shows a filter being passed to 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. If this filter was omitted the user would be able to select any available port.
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.
+ });
+});
+
+| Specification | +Status | +Comment | +
|---|---|---|
| {{SpecName('Web Serial API','#dom-serial-requestport','Serial.requestPort()')}} | +{{Spec2('Web Serial API')}} | +Initial definition. | +
{{Compat("api.Serial.requestPort")}}
diff --git a/files/en-us/web/api/serialport/close/index.html b/files/en-us/web/api/serialport/close/index.html new file mode 100644 index 000000000000000..06e0fab1787d3ef --- /dev/null +++ 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 +--- +The SerialPort.close() method of the {{domxref("SerialPort")}} interface returns a {{jsxref("Promise")}} that resolves when the port closes.
var promise = SerialPort.close();+ +
None.
+ +A {{jsxref("Promise")}}.
+ +| Specification | +Status | +Comment | +
|---|---|---|
| {{SpecName('Web Serial API','#dom-serialport-close','SerialPort.close()')}} | +{{Spec2('Web Serial API')}} | +Initial definition. | +
{{Compat("api.SerialPort.close()")}}
diff --git a/files/en-us/web/api/serialport/getinfo/index.html b/files/en-us/web/api/serialport/getinfo/index.html new file mode 100644 index 000000000000000..d3a5244a2f48143 --- /dev/null +++ b/files/en-us/web/api/serialport/getinfo/index.html @@ -0,0 +1,55 @@ +--- +title: SerialPort.getInfo() +slug: Web/API/SerialPort/getInfo +tags: + - API + - Method + - Reference + - getInfo() + - SerialPort +--- +The SerialPort.getInfo() method of the {{domxref("SerialPort")}} interface returns a {{jsxref("Promise")}} that resolves with an object containing properties of the port.
var promise = SerialPort.getInfo();+ +
None.
+ +An object containing the following values.
+ +usbVendorIdundefined.usbProductIdundefined.| Specification | +Status | +Comment | +
|---|---|---|
| {{SpecName('Web Serial API','#dom-serialport-getinfo','SerialPort.getInfo()')}} | +{{Spec2('Web Serial API')}} | +Initial definition. | +
{{Compat("api.SerialPort.getInfo")}}
diff --git a/files/en-us/web/api/serialport/getsignals/index.html b/files/en-us/web/api/serialport/getsignals/index.html new file mode 100644 index 000000000000000..802b0759ead6323 --- /dev/null +++ b/files/en-us/web/api/serialport/getsignals/index.html @@ -0,0 +1,68 @@ +--- +title: SerialPort.getSignals() +slug: Web/API/SerialPort/getSignals +tags: + - API + - Method + - Reference + - getSignals() + - SerialPort +--- +The SerialPort.getSignals() method of the {{domxref("SerialPort")}} interface returns a {{jsxref("Promise")}} that resolves with an object containing the current state of the port's control signals.
var promise = SerialPort.getSignals();+ +
None.
+ +Returns a {{jsxref("Promise")}} that resolves with an object containing the following members:
+ +clearToSenddataCarrierDetectdataSetReadyringIndicator"InvalidStateError"NetworkError| Specification | +Status | +Comment | +
|---|---|---|
| {{SpecName('Web Serial API','#dom-serialport-getsignals','SerialPort.getSignals()')}} | +{{Spec2('Web Serial API')}} | +Initial definition. | +
{{Compat("api.SerialPort.getSignals")}}
diff --git a/files/en-us/web/api/serialport/index.html b/files/en-us/web/api/serialport/index.html new file mode 100644 index 000000000000000..4d4e2353bd72e2d --- /dev/null +++ b/files/en-us/web/api/serialport/index.html @@ -0,0 +1,115 @@ +--- +title: SerialPort +slug: Web/API/SerialPort +tags: + - API + - Interface + - Reference + - SerialPort +--- +The SerialPort interface of the {{domxref("Web_Serial_API", "Web Serial API")}} provides access to a serial port on the host device.
Instances of this interface may be obtained by calling methods of the {{domxref("Serial")}} interface, therefore it has no constructor of its own. + +
Before communicating on a serial port it must be opened. Opening the port allows the site to specify the necessary parameters that control how data is transmitted and received. Developers should check the documentation for the device they are connecting to for the appropriate parameters.
+ +await port.open({ baudRate: /* pick your baud rate */ });
+
+Once the Promise returned by open() resolves the readable and writable attributes can be accessed to get the {{domxref("ReadableStream")}} and {{domxref("WritableStream")}} instances for receiving data from and sending data to the connected device.
The following example shows how to read data from a port. The outer loop handles non-fatal errors, creating a new reader until a fatal error is encountered and readable becomes null.
while (port.readable) {
+ const reader = port.readable.getReader();
+ try {
+ while (true) {
+ const { value, done } = await reader.read();
+ if (done) {
+ // |reader| has been canceled.
+ break;
+ }
+ // Do something with |value|...
+ }
+ } catch (error) {
+ // Handle |error|...
+ } finally {
+ reader.releaseLock();
+ }
+}
+
+The following example shows how to write a string to a port. A {{domxref("TextEncoder")}} converts the string to a Uint8Array before transmission.
const encoder = new TextEncoder();
+const writer = port.writable.getWriter();
+await writer.write(encoder.encode("PING"));
+writer.releaseLock();
+
+| Specification | +Status | +Comment | +
|---|---|---|
| {{SpecName('Web Serial API','#dom-serialport','SerialPort')}} | +{{Spec2('Web Serial API')}} | +Initial definition. | +
{{Compat("api.SerialPort")}}
diff --git a/files/en-us/web/api/serialport/onconnect/index.html b/files/en-us/web/api/serialport/onconnect/index.html new file mode 100644 index 000000000000000..fe45a4b3d5676f1 --- /dev/null +++ b/files/en-us/web/api/serialport/onconnect/index.html @@ -0,0 +1,42 @@ +--- +title: SerialPort.onconnect +slug: Web/API/SerialPort/onconnect +tags: + - API + - Property + - Reference + - onconnect + - SerialPort +--- +The onconnect event handler of the {{domxref("SerialPort")}} interface is called when the port has disconnected from the device. This method receives an {{domxref("Event")}} object. This event is only fired for ports associated with removable devices such as those connected via USB. This event bubbles to the instance of {{domxref("Serial")}} that returned this interface..
SerialPort.onconnect = function(event);
+SerialPort.addEventListener('connect', function(event));
+
+| Specification | +Status | +Comment | +
|---|---|---|
| {{SpecName('Web Serial API','#dom-serialport-onconnect','SerialPort.onconnect')}} | +{{Spec2('Web Serial API')}} | +Initial definition. | +
{{Compat("api.SerialPort.onconnect")}}
diff --git a/files/en-us/web/api/serialport/ondisconnect/index.html b/files/en-us/web/api/serialport/ondisconnect/index.html new file mode 100644 index 000000000000000..c9f9bc0cac080e5 --- /dev/null +++ b/files/en-us/web/api/serialport/ondisconnect/index.html @@ -0,0 +1,41 @@ +--- +title: SerialPort.ondisconnect +slug: Web/API/SerialPort/ondisconnect +tags: + - API + - Property + - Reference + - ondisconnect + - SerialPort +--- +The ondisconnect event handler of the {{domxref("SerialPort")}} interface is called when the port has disconnected from the device. This method receives an {{domxref("Event")}} object. This event is only fired for ports associated with removable devices such as those connected via USB. This event bubbles to the instance of {{domxref("Serial")}} that returned this interface.
+
+
SerialPort.ondisconnect = function(event);
+SerialPort.addEventListener('disconnect', function(event));
+
+| Specification | +Status | +Comment | +
|---|---|---|
| {{SpecName('Web Serial API','#dom-serialport-ondisconnect','SerialPort.ondisconnect')}} | +{{Spec2('Web Serial API')}} | +Initial definition. | +
{{Compat("api.SerialPort.ondisconnect")}}
diff --git a/files/en-us/web/api/serialport/open/index.html b/files/en-us/web/api/serialport/open/index.html new file mode 100644 index 000000000000000..b4f05ea1502bb82 --- /dev/null +++ b/files/en-us/web/api/serialport/open/index.html @@ -0,0 +1,81 @@ +--- +title: SerialPort.open() +slug: Web/API/SerialPort/open +tags: + - API + - Method + - Reference + - open + - SerialPort +--- +The open() method of the {{domxref("SerialPort")}} interface returns a {{jsxref("Promise")}} that resolves when the port is opened. By default the port is opened with 8 data bits, 1 stop bit and no parity checking. The baudRate parameter is required.
var promise = SerialPort.open(options);+ +
optionsbaudRatebufferSize{{optional_inline}}dataBits{{optional_inline}}flowControl{{optional_inline}}"none" or "hardware". The default value is "none:.parity{{optional_inline}}"none", "even", or "odd". The default value is "none".stopBits{{optional_inline}}A {{jsxref("Promise")}}.
+ +"InvalidStateError"NetworkErrorBefore communicating on a serial port it must be opened. Opening the port allows the site to specify the necessary parameters that control how data is transmitted and received. Developers should check the documentation for the device they are connecting to for the appropriate parameters.
+ +await port.open({ baudRate: /* pick your baud rate */ });
+
+| Specification | +Status | +Comment | +
|---|---|---|
| {{SpecName('Web Serial API','#dom-serialport-open','SerialPort.open()')}} | +{{Spec2('Web Serial API')}} | +Initial definition. | +
{{Compat("api.SerialPort.open")}}
diff --git a/files/en-us/web/api/serialport/readable/index.html b/files/en-us/web/api/serialport/readable/index.html new file mode 100644 index 000000000000000..5d107d928196aaf --- /dev/null +++ b/files/en-us/web/api/serialport/readable/index.html @@ -0,0 +1,65 @@ +--- +title: SerialPort.readable +slug: Web/API/SerialPort/readable +tags: + - API + - Property + - Reference + - readable + - SerialPort +--- +The readable read-only property of the {{domxref("SerialPort")}} interface returns a {{domxref("ReadableStream")}} for receiving data from the device connected to the port. Chunks read from this stream are instances of {{jsxref("Uint8Array")}}. This property is non-null as long as the port is open and has not encountered a fatal error.
var readableStream = SerialPort.readable;+ +
A {{domxref("ReadableStream")}}.
+ +The following example shows how to read data from a port. The outer loop handles non-fatal errors, creating a new reader until a fatal error is encountered and readable becomes null.
while (port.readable) {
+ const reader = port.readable.getReader();
+ try {
+ while (true) {
+ const { value, done } = await reader.read();
+ if (done) {
+ // |reader| has been canceled.
+ break;
+ }
+ // Do something with |value|...
+ }
+ } catch (error) {
+ // Handle |error|...
+ } finally {
+ reader.releaseLock();
+ }
+}
+
+| Specification | +Status | +Comment | +
|---|---|---|
| {{SpecName('Web Serial API','#dom-serialport-readable','SerialPort.readable')}} | +{{Spec2('Web Serial API')}} | +Initial definition. | +
{{Compat("api.SerialPort.readable")}}
diff --git a/files/en-us/web/api/serialport/setsignals/index.html b/files/en-us/web/api/serialport/setsignals/index.html new file mode 100644 index 000000000000000..5816eead7615238 --- /dev/null +++ b/files/en-us/web/api/serialport/setsignals/index.html @@ -0,0 +1,71 @@ +--- +title: SerialPort.setSignals() +slug: Web/API/SerialPort/setSignals +tags: + - API + - Method + - Reference + - setSignals + - SerialPort +--- +The setSignals() method of the {{domxref("SerialPort")}} interface sets control signals on the port and returns a {{jsxref("Promise")}} that resolves when they are set.
var promise = SerialPort.setSignals(options);+ +
options{{optional_inline}}clearToSenddataCarrierDetectdataSetReadyringIndicatorA {{jsxref("Promise")}}.
+ +"InvalidStateError"NetworkError| Specification | +Status | +Comment | +
|---|---|---|
| {{SpecName('Web Serial API','#dom-serialport-setsignals','SerialPort.setSignals()')}} | +{{Spec2('Web Serial API')}} | +Initial definition. | +
{{Compat("api.SerialPort.setSignals")}}
diff --git a/files/en-us/web/api/serialport/writable/index.html b/files/en-us/web/api/serialport/writable/index.html new file mode 100644 index 000000000000000..78ce5ba466e0301 --- /dev/null +++ b/files/en-us/web/api/serialport/writable/index.html @@ -0,0 +1,52 @@ +--- +title: SerialPort.writable +slug: Web/API/SerialPort/writable +tags: + - API + - Property + - Reference + - writable + - SerialPort +--- +The writable read-only property of the {{domxref("SerialPort")}} interface returns a {{domxref("WritableStream")}} for sending data to the device connected to the port. Chunks written to this stream must be instances of {{domxref("BufferSource")}} (for example, an {{jsxref("ArrayBuffer")}} or {{domxref("ArrayBufferView")}} such as {{jsxref("Uint8Array")}}). This property is non-null as long as the port is open and has not encountered a fatal error.
var writableStream = SerialPort.writable;+ +
A {{domxref("WritableStream")}}
+ +The following example shows how to write a string to a port. A {{domxref("TextEncoder")}} converts the string to a Uint8Array before transmission.
const encoder = new TextEncoder();
+const writer = port.writable.getWriter();
+await writer.write(encoder.encode("PING"));
+writer.releaseLock();
+
+| Specification | +Status | +Comment | +
|---|---|---|
| {{SpecName('Web Serial API','#dom-serialport-writable','SerialPort.writable')}} | +{{Spec2('Web Serial API')}} | +Initial definition. | +
{{Compat("api.SerialPort.writable")}}