src/chrome/common/extensions/docs/templates/articles/app_serial.html

   1 <h1>Serial Devices</h1>
   2
   3 <p>
   4 </p>
   5
   6 <p>
   7 This document describes how to use the <a href="serial.html">serial API</a> to read
   8 and write from serial devices. Chrome Apps can also connect to
   9 <a href="usb.html">USB</a> and <a href="bluetooth.html">Bluetooth</a> devices.
  10 </p>
  11
  12 <p class="note">
  13 <b>Samples:</b> For examples that illustrate how Chrome Apps can connect to hardware devices, see the
  14 <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/serial">serial</a>,
  15 <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/servo">servo</a>,
  16 <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/usb">usb</a>, and
  17 <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/zephyr_hxm">zephyr_hxm
  18 Bluetooth</a> samples.
  19 </p>
  20
  21 <h2 id="requirement">Manifest requirement</h2>
  22
  23 <p>
  24 You must add the "serial" permission to the manifest file:
  25 </p>
  26 <pre data-filename="manifest.json">
  27 "permissions": [
  28   "serial"
  29 ]
  30 </pre>
  31
  32 <h2 id="listing">Listing available serial ports</h2>
  33
  34 <p>
  35 To get a list of available serial ports,
  36 use the <code>getPorts()</code> method. <b>Note:</b> not all serial ports are available. The API uses a heuristic based on the name of the port to only expose serial devices that are expected to be safe.
  37 </p>
  38
  39 <pre>
  40 var onGetPorts = function(ports) {
  41   for (var i=0; i&lt;ports.length; i++) {
  42     console.log(ports[i]);
  43   }
  44 }
  45 chrome.serial.getPorts(onGetPorts);
  46 </pre>
  47
  48 <h2 id="opening">Opening a serial device</h2>
  49
  50 <p>
  51 If you know the serial port name, you can open it for read and write using the <code>open</code> method:
  52 </p>
  53
  54 <pre>
  55 chrome.serial.open(portName, options, openCallback)
  56 </pre>
  57
  58 <table border="0">
  59   <tr>
  60     <th scope="col"> Parameter </th>
  61     <th scope="col"> Description </th>
  62   </tr>
  63   <tr>
  64     <td>portName&nbsp;(string)</td>
  65     <td>If your device's port name is unknown, you can use the <code>getPorts</code> method.</td>
  66   </tr>
  67   <tr>
  68     <td>options&nbsp;(object)</td>
  69     <td>Parameter object with one single value: <code>bitrate</code>, an integer specifying the desired bitrate used to communicate with the serial port.</td>
  70   </tr>
  71   <tr>
  72     <td>openCallback</td>
  73     <td>Invoked when the port has been successfully opened. The callback will be called with one parameter, <code>openInfo</code>, that has one attribute, <code>connectionId</code>. Save this id, because you will need it to actually communicate with the port.
  74     </td>
  75   </tr>
  76 </table>
  77
  78 <p>A simple example:</p>
  79
  80 <pre>
  81 var onOpen = function(connectionInfo) {
  82    // The serial port has been opened. Save its id to use later.
  83   _this.connectionId = connectionInfo.connectionId;
  84   // Do whatever you need to do with the opened port.
  85 }
  86 // Open the serial port /dev/ttyS01
  87 chrome.serial.open("/dev/ttyS01", {bitrate: 115200}, onOpen);
  88 </pre>
  89
  90 <h2 id="closing">Closing a serial port</h2>
  91
  92 <p>
  93 Closing a serial port is simple but very important. See the example below:
  94 </p>
  95
  96 <pre>
  97 var onClose = function(result) {
  98  console.log("Serial port closed");
  99 }
 100 chrome.serial.close(connectionId, onClose);
 101 </pre>
 102
 103 <h2 id="reading">Reading from a serial port</h2>
 104
 105 <p>
 106 The serial API reads from the serial port and
 107 delivers the read bytes as an ArrayBuffer.
 108 There is no guarantee that all the requested bytes, even if available in the port, will be read in one chunk.
 109 The following example can accumulate read bytes, at most 128 at a time, until a new line is read,
 110 and then call a listener with the <code>ArrayBuffer</code> bytes converted to a String:
 111 </p>
 112
 113 <pre>
 114 var dataRead='';
 115
 116 var onCharRead=function(readInfo) {
 117     if (!connectionInfo) {
 118       return;
 119     }
 120     if (readInfo &amp;&amp; readInfo.bytesRead>0 &amp;&amp; readInfo.data) {
 121       var str=ab2str(readInfo.data);
 122       if (str[readInfo.bytesRead-1]==='\n') {
 123         dataRead+=str.substring(0, readInfo.bytesRead-1);
 124         onLineRead(dataRead);
 125         dataRead="";
 126       } else {
 127         dataRead+=str;
 128       }
 129     }
 130     chrome.serial.read(connectionId, 128, onCharRead);
 131   }
 132
 133 /* Convert an ArrayBuffer to a String, using UTF-8 as the encoding scheme.
 134    This is consistent with how Arduino sends characters by default */
 135   var ab2str=function(buf) {
 136     return String.fromCharCode.apply(null, new Uint8Array(buf));
 137   };
 138 </pre>
 139
 140 <h2 id="writing">Writing to a serial port</h2>
 141
 142 <p>
 143 The writing routine is simpler than reading,
 144 since the writing can occur all at once.
 145 The only catch is that if your data protocol is String based,
 146 you have to convert your output string to an <code>ArrayBuffer</code>.
 147 See the code example below:
 148 </p>
 149
 150 <pre>
 151 var writeSerial=function(str) {
 152   chrome.serial.write(connectionId, str2ab(str), onWrite);
 153 }
 154 // Convert string to ArrayBuffer
 155 var str2ab=function(str) {
 156   var buf=new ArrayBuffer(str.length);
 157   var bufView=new Uint8Array(buf);
 158   for (var i=0; i&lt;str.length; i++) {
 159     bufView[i]=str.charCodeAt(i);
 160   }
 161   return buf;
 162 }
 163 </pre>
 164
 165 <h2 id="flushing">Flushing a serial port buffer</h2>
 166
 167 <p>
 168 You can flush your serial port buffer by issuing the flush command:
 169 </p>
 170
 171 <pre>
 172   chrome.serial.flush(connectionId, onFlush);
 173 </pre>