Serial Devices

This document describes how to use the serial API to read and write from serial devices. Chrome Apps can also connect to USB and Bluetooth devices.

Samples: For examples that illustrate how Chrome Apps can connect to hardware devices through a serial port, see the adkjs, ledtoggle and the servo samples.

Manifest requirement

You must add the "serial" permission to the manifest file:

"permissions": [
  "serial"
]

Listing available serial ports

To get a list of paths associated with available serial ports, use the serial.getDevices method. Note: not all serial ports are available. The API uses heuristics to only expose serial devices that are expected to be safe.

var onGetDevices = function(ports) {
  for (var i=0; i<ports.length; i++) {
    console.log(ports[i].path);
  }
}
chrome.serial.getDevices(onGetDevices);

Connecting to a serial device

If you know the path associated with the serial port, you can connect to it using the serial.connect method:

chrome.serial.connect(path, options, callback)

Parameter	Description
path (string)	If the path associated with your device's port is unknown, you can use the serial.getDevices method.
options (object)	Parameter object with several configuration values. See details at serial.ConnectionOptions
callback	Invoked when the port has been successfully opened. The callback will be called with one parameter, connectionInfo, that has several important values. See details at serial.ConnectionInfo.

A simple example:

var onConnect = function(connectionInfo) {
   // The serial port has been opened. Save its id to use later.
  _this.connectionId = connectionInfo.connectionId;
  // Do whatever you need to do with the opened port.
}
// Connect to the serial port /dev/ttyS01
chrome.serial.connect("/dev/ttyS01", {bitrate: 115200}, onConnect);

Disconnect from a serial port

When an app terminates, connections to serial ports that are not persistent are automatically closed by the platform. However, if you want to disconnect while your app is still running, you can use the serial.disconnect method:

var onDisconnect = function(result) {
  if (result) {
    console.log("Disconnected from the serial port");
  } else {
    console.log("Disconnect failed");
  }
}
chrome.serial.disconnect(connectionId, onDisconnect);

Reading from a serial port

The serial API reads from the serial port and delivers the read bytes as an ArrayBuffer to event listeners. Every port that your application is connected to will generate read events to all listeners added through chrome.serial.onReceive.addListener(onReceiveCallback). If you are connected to more than one port at the same time, you may find the corresponding connectionId of an incoming read event in the callback parameter of serial.onReceive.

The following example can accumulate read bytes until a new line is read, converting the received ArrayBuffer to String and calling a method when a newline is found as the last character received:

var stringReceived = '';

var onReceiveCallback = function(info) {
    if (info.connectionId == expectedConnectionId && info.data) {
      var str = convertArrayBufferToString(info.data);
      if (str.charAt(str.length-1) === '\n') {
        stringReceived += str.substring(0, str.length-1);
        onLineReceived(stringReceived);
        stringReceived = '';
      } else {
        stringReceived += str;
      }
    }
  };

chrome.serial.onReceive.addListener(onReceiveCallback);

// [...] not shown here: connect to the serial port

Sending data to a serial port

Sending data is simpler than reading. The only catch is that if your data protocol is String based, you have to convert your output string to an ArrayBuffer. See the code example below:

var writeSerial=function(str) {
  chrome.serial.send(connectionId, convertStringToArrayBuffer(str), onSend);
}
// Convert string to ArrayBuffer
var convertStringToArrayBuffer=function(str) {
  var buf=new ArrayBuffer(str.length);
  var bufView=new Uint8Array(buf);
  for (var i=0; i<str.length; i++) {
    bufView[i]=str.charCodeAt(i);
  }
  return buf;
}

Flushing a serial port buffer

You can flush your serial port buffer by issuing the flush command:

  chrome.serial.flush(connectionId, onFlush);

More

The Serial API has several other features. You can, for example, set a connection to persistent, so it can receive data even when your app is not running, or you can update connection parameters on the fly, like bitrate, timeouts, control signals, and many others with the serial.update method. See the full reference of the serial API for more information.