| <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/serial/adkjs#readme">adkjs</a>, |
| <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/serial/ledtoggle#readme">ledtoggle</a> and the |
| <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/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<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 (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 (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 && 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<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> |