The Serial API provides a way for websites to read and write from a serial device through script. Such an API would bridge the web and the physical world, by allowing documents to communicate with devices such as microcontrollers, 3D printers, and other serial devices.
This is a work in progress. All [contributions](https://github.com/whatwg/serial) welcome.
## Usage example This example shows how to find the first "Arduino" device and set it up for use.
//Request the list of ports from the user
SerialPort.requestPorts().then(ports => {

  //Pick the first matching port
  var serial,
      kind = "Arduino",
      key = "manufacturer",
      //find the Arduinos!
      arduinos = ports.filter(port => port.get(key).search(kind) > -1);

  if (arduinos.length) {
     serial = new SerialPort(arduinos[0].path);
     serial.in.read(readData)
  }

  function readData(){
    while(let data = yield serial.read()) {
      console.log(data);
    }
  }
})
.catch(console.error);
## Dependencies The `ReadableStream` and `WritableStream` interfaces are defined in [[!STREAMS]]. The `Promise` and `DOMException` interfaces are defined in [[!DOM]]. ## SerialPort interface
[constructor(DOMString path, optional SerialOptions options)]
interface SerialPort {
  static Promise<SerialPortInfo[]> requestPorts();
  readonly attribute ReadableStream in;
  readonly attribute WritableStream out;
  SerialPortInfo getInfo();
};
### Constructing `SerialPort` objects When the constructor of the `SerialPort` interface is invoked, the user agent MUST run the following steps: 1. ...To be written... 1. Profit! 1. Return serial port. ### `requestPorts()` method The `requestPorts()` method requests access to the serial ports of the system (see security considerations). When the `requestPorts()` method is invoked, the user agent MUST perform the following steps: 1. Let promise be a new `Promise` object and resolver its associated resolver. 1. Return `promise` and run the remaining steps asynchronously. 1. Let ports be an empty `Array` object [[!ECMASCRIPT]]. 1. Request access to serial ports (see security considerations): 1. If the access request is rejected: 1. Let error be a new `DOMException` whose name is `[AbortError](http://dom.spec.whatwg.org/#aborterror)`. 1. Run resolver's internal reject algorithm with error as value and terminate this algorithm. 1. Otherwise, for each port for which access was granted: 1. Let info be the result of running the steps for getting metadata of a serial port. 1. Append info to ports. 1. Run resolver's internal fulfill algorithm with ports as value. ### `getInfo()` method The `getInfo()` method provides a means to get metadata corresponding to a `SerialPort` object. When the `getInfo()` method is invoked, the user agent MUST perform the steps for getting metadata of a serial port. ## `SerialPortInfo` interface
interface SerialPortInfo{
  maplike<DOMString, DOMString?>;
};
## Serial port metadata The value of certain attributes is dependent on the method that the system used to establish the serial port (e.g., USB), and so might not always be available. ### Recommended serial port metadata When available, it is RECOMMENDED that user agents populate a `SerialPortInfo` object with the following information. If the value of piece of metadata is unavailable(e.g., if the manufacturer is unknown), then it is RECOMMNEDED that that metadata be excluded from the `SerialPortInfo`. For interoperability, user agents SHOULD use the values provided in they "Key" column of the table of recommended metadata.
Table of recommended metadata
Name Key Description
Product ID `productId`
Serial Number `serialNumber`
Manufacturer `manufacturer`
Location ID `locationId`
Vendor ID `vendorId`
Vendor `vendor`
Product ID `productId`
Product `product`
### Getting serial port metadata The steps for getting metadata of a serial port for a serial port are as follows. The steps always return an instance of `SerialPortInfo`, which contains the related metadata. 1. Let info be an object that implements the `SerialPortInfo` interface. 1. Let path be a `DOMString` that represents the path of the serial port. 1. Invoke info's `set()` method using the string `"path"` as the key, and path as the value. 1. For each additional metadata item known about the serial port, perform the following sub-steps. Please see the table of recommended metadata for a list of recommended metadata items that SHOULD be included. 1. Let key be a `DOMString` for the commonly used name for this key. 1. Let value be a `DOMString` for the commonly used name for this key, or `null` otherwise. 1. Invoke info's `set()` method using the string "path" as the key, and path as the value. 1. Return info. ## `SerialOptions` dictionary
  dictionary SerialOptions {
    long baudrate = 9600;
    octet databits = 8;
    octet stopbits = 1;
    ParityType parity = "none";
    long buffersize = 255;
    boolean rtscts = false;
    boolean xon = false;
    boolean xoff = false;
    boolean xany = false;
  };
baudrate member
One of 115200, 57600, 38400, 19200, 9600, 4800, 2400, 1800, 1200, 600, 300, 200, 150, 134, 110, 75, or 50.
databits member
One of 8, 7, 6, or 5.
stopbits member
One of 1 or 2.
parity member'
The parity type.
buffersize member
rtscts member
xon member
xoff member
xany member
## `ParityType` enum
enum ParityType {
  "none",
  "even",
  "mark",
  "odd",
  "space"
};
none
even
mark
odd
space
## Security considerations This section defines the Security considerations for the Serial API. It is RECOMMENDED that an user interface be presented to the user to allow them to select the serial ports that the page can access. Such an interface would allow an end user to select zero ore more serial ports on the device - or to reject the request to access any ports. A user agent SHOULD allow the user to select from all serial ports available on the machine, and be shown an indicator for serial ports that are currently busy, either as a result of prior calls to `requestPorts()` or are in use by the system. It is also RECOMMENDED that user agents provide users with a means for the end- user to view which independently of any access request, and be given the ability to revoke individual or complete access to serial ports at any time either at the user agent level or per [origin](http://www.whatwg.org/specs/web-apps/current-work/#origin-0) [[!HTML]].
## Use cases and requirements ### Hardware disconnection Some devices allow users to manually reset the connection between the user agent and the physical device (e.g., by pushing a button). One example device is the Arduino. Another example is the user abruptly disconnecting one device from another, thus severing the communication channel. As such, it is a requirement that the API gracefully handle abrupt disconnection caused by a reset or other event. When such disconnections occur, the API must make it possible for the developer to be notified of such disconnections. When possible, the API should provide details about the disconnection (e.g., reason, time, etc.). ### Baud rates Traditionally, serial devices have operated at [baud rates](http://en.wikipedia.org/wiki/Baud) of between 50 and 115,200 bps. However, modern USB serial devices are able to operate at significantly higher baud rates than legacy hardware. For example, the [bioloid servos](http://support.robotis.com/en/techsupport_eng.htm#product/dynamixel/ax_series/dxl_ax_actuator.htm) operate at 1 Mbit (1,000,000 bps). Other USB-to-serial chips are able to operate at 3 MBit (3,000,000bps). Additionally, other serial devices have standardized baud rates that are not in the commonly accepted value for baud rates. For example, [MIDI](http://en.wikipedia.org/wiki/MIDI) uses a baud rate of 31,250 bps, while a [DMX512 controller](http://en.wikipedia.org/wiki/DMX512) transmits data at 250kbps. As such, it is a requirement that the Serial API does not limit the baud rates to a traditional range. Instead, the API must allow a developer to specify any rate so long as the value is an unsigned number. If there is a baud rate that is common for a large range of hardware that will make use of this API, the API should provide a default baud rate value. Given the above requirement, it is possible to create software to wrap the Serial API to restrict the possible baud rates used for communicating with some particular hardware. For example, a JavaScript library that communicates with a MIDI device could automatically set the baud rate to 31,250 bps without needing to bother the developer to specify the value.
## Acknowledgements ... coming soon...