Merge Chromium + Blink git repositories

[chromium-blink-merge.git] / chrome / common / extensions / docs / templates / articles / app_serial.html

<h1>Serial Devices</h1>

<p>
</p>

<p>
This document describes how to use the <a href="serial">serial API</a> to read
and write from serial devices. Chrome Apps can also connect to
<a href="app_usb">USB</a> and <a href="app_bluetooth">Bluetooth</a> devices.
</p>

<p class="note">
<b>Samples:</b> For examples that illustrate how Chrome Apps can connect to hardware devices through a serial port, see the
<a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/samples/serial/adkjs#readme">adkjs</a>,
<a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/samples/serial/ledtoggle#readme">ledtoggle</a> and the
<a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/samples/servo#readme">servo</a> samples.
</p>

<h2 id="requirement">Manifest requirement</h2>

<p>
You must add the "serial" permission to the manifest file:
</p>
<pre data-filename="manifest.json">
"permissions": [
  "serial"
]
</pre>

<h2 id="listing">Listing available serial ports</h2>

<p>
To get a list of paths associated with available serial ports,
use the <code>$(ref:serial.getDevices)</code> method. <b>Note:</b> not all serial ports are available. The API uses heuristics to only expose serial devices that are expected to be safe.
</p>

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

<h2 id="opening">Connecting to a serial device</h2>

<p>
If you know the path associated with the serial port, you can connect to it using the <code>$(ref:serial.connect)</code> method:
</p>

<pre>
chrome.serial.connect(path, options, callback)
</pre>

<table border="0">
  <tr>
    <th scope="col"> Parameter </th>
    <th scope="col"> Description </th>
  </tr>
  <tr>
    <td>path&nbsp;(string)</td>
    <td>If the path associated with your device's port is unknown, you can use the <code>$(ref:serial.getDevices)</code> method.</td>
  </tr>
  <tr>
    <td>options&nbsp;(object)</td>
    <td>Parameter object with several configuration values. See details at $(ref:serial.ConnectionOptions)</td>
  </tr>
  <tr>
    <td>callback</td>
    <td>Invoked when the port has been successfully opened. The callback will be called with one parameter, <code>connectionInfo</code>, that has several important values. See details at $(ref:serial.ConnectionInfo).
    </td>
  </tr>
</table>

<p>A simple example:</p>

<pre>
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);
</pre>

<h2 id="disconnect">Disconnect from a serial port</h2>

<p>
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 $(ref:serial.disconnect) method:
</p>

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

<h2 id="reading">Reading from a serial port</h2>

<p>
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
<code>chrome.serial.onReceive.addListener(onReceiveCallback)</code>. If you are connected to more than one port at the
same time, you may find the corresponding <code>connectionId</code> of an incoming read event in the callback parameter
of $(ref:serial.onReceive).
</p>
<p>
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:
</p>

<pre>
var stringReceived = '';

var onReceiveCallback = function(info) {
    if (info.connectionId == expectedConnectionId &amp;&amp; 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

</pre>

<h2 id="writing">Sending data to a serial port</h2>

<p>
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 <code>ArrayBuffer</code>.
See the code example below:
</p>

<pre>
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&lt;str.length; i++) {
    bufView[i]=str.charCodeAt(i);
  }
  return buf;
}
</pre>

<h2 id="flushing">Flushing a serial port buffer</h2>

<p>
You can flush your serial port buffer by issuing the flush command:
</p>

<pre>
  chrome.serial.flush(connectionId, onFlush);
</pre>

<h2 id="More">More</h2>

<p>
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 $(ref:serial.update) method. See the full reference of the $(ref:serial) API for more information.
</p>