| OLD | NEW |
|---|
| (Empty) | |
| 1 <h1 class="page_title">Accessing Hardware Devices</h1> |
| 2 <div id="pageData-showTOC" class="pageData">true</div> |
| 3 <p> |
| 4 This doc shows you how packaged apps can connect to USB devices |
| 5 and read from and write to a user's serial ports. |
| 6 See also the reference docs for the |
| 7 <a href="experimental.usb.html">USB API</a> |
| 8 and the |
| 9 <a href="experimental.serial.html">Serial API</a>. |
| 10 The <a href="experimental.bluetooth.html">Bluetooth API</a> has just landed and |
| 11 we'll write more on this soon. |
| 12 We've included a link to an early sample below. |
| 13 </p> |
| 14 <p class="note"> |
| 15 <b>API Samples: </b> |
| 16 Want to play with the code? |
| 17 Check out the |
| 18 <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/serial">
serial</a>, |
| 19 <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/servo">s
ervo</a>, |
| 20 <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/usb">usb
</a>, |
| 21 and <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/blue
tooth-demo">bluetooth-demo</a> samples. |
| 22 </p> |
| 23 <h2 id="usb">Accessing USB devices</h2> |
| 24 <p> |
| 25 You can use the USB API to send messages to any connected device. |
| 26 </p> |
| 27 <h3>Manifest requirement</h3> |
| 28 <p> |
| 29 You must add the "usb" permission |
| 30 to the manifest file: |
| 31 </p> |
| 32 <pre> |
| 33 "permissions": [ |
| 34 "app.window", |
| 35 "experimental", |
| 36 "usb" |
| 37 ] |
| 38 </pre> |
| 39 <h3>Finding a device</h3> |
| 40 <p> |
| 41 Every device in a USB bus is identified |
| 42 by its vendor and product IDs. |
| 43 To find a device, |
| 44 use the <code>findDevice()</code> method |
| 45 which has four parameters: |
| 46 </p> |
| 47 <pre> |
| 48 chrome.experimental.usb.findDevice(vendorId, productId, eventCallbacks, onDevice
FoundCallback) |
| 49 </pre> |
| 50 <br> |
| 51 <table border="0"> |
| 52 <tr> |
| 53 <th scope="col"> Parameter (type) </th> |
| 54 <th scope="col"> Description </th> |
| 55 </tr> |
| 56 <tr> |
| 57 <td>vendorId (long)</td> |
| 58 <td>The vendor ID for your USB device (in Linux, use lsusb to find it).</td> |
| 59 </tr> |
| 60 <tr> |
| 61 <td>productId (long)</td> |
| 62 <td>The product ID for your USB device (in Linux, use lsusb to find it).</td
> |
| 63 </tr> |
| 64 <tr> |
| 65 <td>eventCallbacks(object)</td> |
| 66 <td>An object with a single key, "onEvent", |
| 67 to be called whenever an event occurs on the corresponding device. |
| 68 This will be the primary method of receiving information from the device. |
| 69 As the host-initiated USB protocol is complex, read on to learn more. |
| 70 </td> |
| 71 </tr> |
| 72 <tr> |
| 73 <td>onDevideFoundCallback()</td> |
| 74 <td>Called when the device is found. |
| 75 The callback's parameter is an object |
| 76 with three properties: <code>handle</code>, |
| 77 <code>vendorId</code>, |
| 78 <code>productId</code>; |
| 79 or <code>NULL</code>, |
| 80 if no device is found. |
| 81 Save this object |
| 82 as it's required to send messages to the device.</td> |
| 83 </tr> |
| 84 </table> |
| 85 <p> |
| 86 Example: |
| 87 </p> |
| 88 <pre> |
| 89 var onDeviceFound = function(device) { |
| 90 deviceObj=device; |
| 91 if (device) { |
| 92 console.log(“Device found: ”+device.handle); |
| 93 } else { |
| 94 console.log(“Device could not be found”); |
| 95 } |
| 96 }; |
| 97 var onUsbEvent = function(event) { |
| 98 console.log(“USB event!”); |
| 99 }; |
| 100 chrome.experimental.usb.findDevice(vendorId, productId, {"onEvent": onUsbEvent},
onDeviceFound); |
| 101 </pre> |
| 102 <h3>USB transfers and receiving data from a device</h3> |
| 103 <p> |
| 104 USB protocol defines four types of transfers: |
| 105 control, bulk, isochronous and interrupt. |
| 106 Theoretically they can all occur in both directions:<br> |
| 107 device-to-host and host-to-device. |
| 108 Host-to-device is initiated by your code and is described in the next sections. |
| 109 </p> |
| 110 <p> |
| 111 Device-to-host messages are handled by Chrome and delivered |
| 112 to the <code>onEvent()</code> callback |
| 113 defined in the <code>findDevice()</code> method. |
| 114 For each message from the device, |
| 115 the <code>onEvent</code> callback will receive |
| 116 an event object with the following properties: |
| 117 </p> |
| 118 <br> |
| 119 <table border="0"> |
| 120 <tr> |
| 121 <th scope="col"> Property </th> |
| 122 <th scope="col"> Description </th> |
| 123 </tr> |
| 124 <tr> |
| 125 <td>type (string)</td> |
| 126 <td>Currently always contains the string "transferResult".</td> |
| 127 </tr> |
| 128 <tr> |
| 129 <td>resultCode (integer)</td> |
| 130 <td>0 is success; other values indicate failure.</td> |
| 131 </tr> |
| 132 <tr> |
| 133 <td>data (integer array)</td> |
| 134 <td>Contains the data sent by the device. |
| 135 </td> |
| 136 </tr> |
| 137 </table> |
| 138 <p> |
| 139 Example: |
| 140 </p> |
| 141 <pre> |
| 142 var onUsbEvent = function(event) { |
| 143 if (event && event.resultCode===0 && event.data) { |
| 144 console.log(“got ”+event.data.length+" bytes"); |
| 145 } |
| 146 }; |
| 147 chrome.experimental.usb.findDevice( vendorId, productId, {"onEvent": onUsbEvent}
, onDeviceFound); |
| 148 </pre> |
| 149 <h3>Sending data - control transfers</h3> |
| 150 <p> |
| 151 Control transfers are generally used to send configuration |
| 152 or command parameters to a USB device. |
| 153 The method is simple and receives three parameters: |
| 154 </p> |
| 155 <pre> |
| 156 chrome.experimental.usb.controlTransfer(deviceObj, transferInfo, transferCallbac
k) |
| 157 </pre> |
| 158 <br> |
| 159 <table border="0"> |
| 160 <tr> |
| 161 <th scope="col"> Parameter (types)</th> |
| 162 <th scope="col"> Description </th> |
| 163 </tr> |
| 164 <tr> |
| 165 <td>deviceObj</td> |
| 166 <td>Object received from <code>findDevice()</code> callback.</td> |
| 167 </tr> |
| 168 <tr> |
| 169 <td>transferInfo</td> |
| 170 <td>Parameter object with values from the table below. |
| 171 Check your USB device protocol specification |
| 172 to know which values are supported.</td> |
| 173 </tr> |
| 174 <tr> |
| 175 <td>transferCallback()</td> |
| 176 <td>Invoked when the transfer has completed. |
| 177 Please note this only indicates that |
| 178 the transfer has been processed. |
| 179 The device's response, if any, will always be sent through |
| 180 the <code>onEvent()</code> callback set on <code>findDevice()</code>. |
| 181 </td> |
| 182 </tr> |
| 183 </table> |
| 184 <p> |
| 185 Values for <code>transferInfo</code> object: |
| 186 </p> |
| 187 <table border="0"> |
| 188 <tr> |
| 189 <th scope="col"> Value </th> |
| 190 <th scope="col"> Description </th> |
| 191 </tr> |
| 192 <tr> |
| 193 <td>requestType (string)</td> |
| 194 <td>"vendor", "standard", "class" or "reserved".</td> |
| 195 </tr> |
| 196 <tr> |
| 197 <td>recipient (string)</td> |
| 198 <td>"device", "interface", "endpoint" or "other".</td> |
| 199 </tr> |
| 200 <tr> |
| 201 <td>direction (string)</td> |
| 202 <td>in" or "out". |
| 203 IN direction is used to notify the device |
| 204 that it should send information to the host. |
| 205 All communication in a USB bus is host-initiated, |
| 206 so use an 'in' transfer to allow a device |
| 207 to send information back.</td> |
| 208 </tr> |
| 209 <tr> |
| 210 <td>request (integer)</td> |
| 211 <td>Defined by your device's protocol.</td> |
| 212 </tr> |
| 213 <tr> |
| 214 <td>value (integer)</td> |
| 215 <td>Defined by your device's protocol.</td> |
| 216 </tr> |
| 217 <tr> |
| 218 <td>index (integer)</td> |
| 219 <td>Defined by your device's protocol.</td> |
| 220 </tr> |
| 221 <tr> |
| 222 <td>length (integer)</td> |
| 223 <td>Only used when direction is "in". |
| 224 Notifies the device that this is the amount |
| 225 of data the host is expecting in response.</td> |
| 226 </tr> |
| 227 <tr> |
| 228 <td>data (integer array)</td> |
| 229 <td>Defined by your device's protocol, |
| 230 required when direction is "out". |
| 231 <b>WARNING: </b>in the near future, |
| 232 this parameter will likely change |
| 233 to <code>ArrayBuffer</code>.</td> |
| 234 </tr> |
| 235 </table> |
| 236 <p> |
| 237 Example: |
| 238 </p> |
| 239 <pre> |
| 240 var transferInfo = { |
| 241 "requestType": "vendor", |
| 242 "recipient": "device", |
| 243 "direction": "out", |
| 244 "request": 0x31, |
| 245 "value": 120, |
| 246 "index": 0, |
| 247 "data": [4, 8, 15, 16, 23, 42] |
| 248 }; |
| 249 chrome.experimental.usb.controlTransfer(deviceObj, transferInfo, optionalCallbac
k); |
| 250 </pre> |
| 251 <h3>Sending data - isochronous transfers</h3> |
| 252 <p> |
| 253 Isochronous transfers are commonly used for streams of data. |
| 254 Video and sound, for example, are good candidates for this transfer type. |
| 255 To send an isochronous transfer, use: |
| 256 </p> |
| 257 <pre> |
| 258 chrome.experimental.usb.isochronousTransfer(deviceObj, isochronousTransferInfo,
transferCallback) |
| 259 </pre> |
| 260 <br> |
| 261 <table border="0"> |
| 262 <tr> |
| 263 <th scope="col"> Parameter </th> |
| 264 <th scope="col"> Description </th> |
| 265 </tr> |
| 266 <tr> |
| 267 <td>deviceObj</td> |
| 268 <td>Object sent on <code>findDevice()</code> callback.</td> |
| 269 </tr> |
| 270 <tr> |
| 271 <td>isochronousTransferInfo</td> |
| 272 <td>Parameter object with the values in the table below.</td> |
| 273 </tr> |
| 274 <tr> |
| 275 <td>transferCallback()</td> |
| 276 <td>Invoked when the transfer has completed. |
| 277 Notice that this callback doesn't represent any response from the device. |
| 278 It's just to notify your code that the asynchronous transfer request |
| 279 has been processed and you can go ahead. |
| 280 The device's response, if any, will always be sent through |
| 281 the <code>onEvent()</code> callback set on <code>findDevice()</code>. |
| 282 </td> |
| 283 </tr> |
| 284 </table> |
| 285 <p> |
| 286 Values for <code>isochronousTransferInfo</code> object: |
| 287 </p> |
| 288 <table border="0"> |
| 289 <tr> |
| 290 <th scope="col"> Value </th> |
| 291 <th scope="col"> Description </th> |
| 292 </tr> |
| 293 <tr> |
| 294 <td>transferInfo (object)</td> |
| 295 <td>A parameter object with the following parameters:<br> |
| 296 <b>direction (string): </b>"in" or "out".<br> |
| 297 <b>endpoint (integer): </b>defined by your device's protocol.<br> |
| 298 <b>length (integer): </b>only used when direction is "in". |
| 299 Notifies the device that this is the amount |
| 300 of data the host is expecting in response<br> |
| 301 <b>data (integer array): </b>defined by your device's protocol; |
| 302 only used when direction is "out". |
| 303 </td> |
| 304 </tr> |
| 305 <tr> |
| 306 <td>packets (integer)</td> |
| 307 <td>Total number of packets expected in this transfer.</td> |
| 308 </tr> |
| 309 <tr> |
| 310 <td>packetLength (integer)</td> |
| 311 <td>Expected length of each packet in this transfer.</td> |
| 312 </tr> |
| 313 </table> |
| 314 <p> |
| 315 Example: |
| 316 </p> |
| 317 <pre> |
| 318 var transferInfo = { |
| 319 "direction": "in", |
| 320 "endpoint": 1, |
| 321 "length": 2560 |
| 322 }; |
| 323 var isoTransferInfo = { |
| 324 "transferInfo": transferInfo, |
| 325 "packets": 20, |
| 326 "packetLength": 128 |
| 327 }; |
| 328 chrome.experimental.usb.isochronousTransfer(deviceObj, isoTransferInfo, optional
Callback); |
| 329 </pre> |
| 330 <h3>Sending data - bulk transfers</h3> |
| 331 <p> |
| 332 Bulk transfer is a USB transfer type commonly used |
| 333 to transfer a large amount of data reliably. |
| 334 The method has three parameters: |
| 335 </p> |
| 336 <pre> |
| 337 chrome.experimental.usb.bulkTransfer(deviceObj, transferInfo, transferCallback) |
| 338 </pre> |
| 339 <br> |
| 340 <table border="0"> |
| 341 <tr> |
| 342 <th scope="col"> Parameter </th> |
| 343 <th scope="col"> Description </th> |
| 344 </tr> |
| 345 <tr> |
| 346 <td>deviceObj</td> |
| 347 <td>Object sent on <code>findDevice()</code> callback.</td> |
| 348 </tr> |
| 349 <tr> |
| 350 <td>transferInfo</td> |
| 351 <td>Parameter object with the values in the table below.</td> |
| 352 </tr> |
| 353 <tr> |
| 354 <td>transferCallback()</td> |
| 355 <td>Invoked when the transfer has completed. |
| 356 Notice that this callback doesn't represent any response from the device. |
| 357 It's just to notify your code that the asynchronous transfer request |
| 358 has been processed and you can go ahead. |
| 359 The device's response, if any, will always be sent through |
| 360 the <code>onEvent()</code> callback set on <code>findDevice()</code>. |
| 361 </td> |
| 362 </tr> |
| 363 </table> |
| 364 <p> |
| 365 Values for <code>transferInfo</code> object: |
| 366 </p> |
| 367 <table border="0"> |
| 368 <tr> |
| 369 <th scope="col"> Value </th> |
| 370 <th scope="col"> Description </th> |
| 371 </tr> |
| 372 <tr> |
| 373 <td>direction (string)</td> |
| 374 <td>"in" or "out".</td> |
| 375 </tr> |
| 376 <tr> |
| 377 <td>endpoint (integer)</td> |
| 378 <td>Defined by your device's protocol.</td> |
| 379 </tr> |
| 380 <tr> |
| 381 <td>length (integer)</td> |
| 382 <td>Only used when direction is "in". |
| 383 Notifies the device that this is the amount |
| 384 of data the host is expecting in response.</td> |
| 385 </tr> |
| 386 <tr> |
| 387 <td>data (integer array)</td> |
| 388 <td>Defined by your device's protocol; |
| 389 only used when direction is "out".</td> |
| 390 </tr> |
| 391 </table> |
| 392 <p> |
| 393 Example: |
| 394 </p> |
| 395 <pre> |
| 396 var transferInfo = { |
| 397 "direction": "out", |
| 398 "endpoint": 1, |
| 399 "data": [4, 8, 15, 16, 23, 42] |
| 400 }; |
| 401 </pre> |
| 402 <h3>Sending data - interrupt transfers</h3> |
| 403 <p> |
| 404 Interrupt transfers are used to send important notifications. |
| 405 Since all USB communication is initiated by the host, |
| 406 host code usually polls the device periodically, |
| 407 sending interrupt IN transfers that will make the device send data back |
| 408 if there is anything on the interrupt queue. |
| 409 The method has three parameters: |
| 410 </p> |
| 411 <pre> |
| 412 chrome.experimental.usb.interruptTransfer(deviceObj, transferInfo, transferCallb
ack) |
| 413 </pre> |
| 414 <br> |
| 415 <table border="0"> |
| 416 <tr> |
| 417 <th scope="col"> Parameter </th> |
| 418 <th scope="col"> Description </th> |
| 419 </tr> |
| 420 <tr> |
| 421 <td>deviceObj</td> |
| 422 <td>Object sent on <code>findDevice()</code> callback.</td> |
| 423 </tr> |
| 424 <tr> |
| 425 <td>transferInfo</td> |
| 426 <td>Parameter object with the values in the table below.</td> |
| 427 </tr> |
| 428 <tr> |
| 429 <td>transferCallback()</td> |
| 430 <td>Invoked when the transfer has completed. |
| 431 Notice that this callback doesn't represent any response from the device. |
| 432 It's just to notify your code that the asynchronous transfer request |
| 433 has been processed and you can go ahead. |
| 434 The device's response, if any, will always be sent through |
| 435 the <code>onEvent()</code> callback set on <code>findDevice()</code>. |
| 436 </td> |
| 437 </tr> |
| 438 </table> |
| 439 <p> |
| 440 Values for <code>transferInfo</code> object: |
| 441 </p> |
| 442 <table border="0"> |
| 443 <tr> |
| 444 <th scope="col"> Value </th> |
| 445 <th scope="col"> Description </th> |
| 446 </tr> |
| 447 <tr> |
| 448 <td>direction (string)</td> |
| 449 <td>"in" or "out".</td> |
| 450 </tr> |
| 451 <tr> |
| 452 <td>endpoint (integer)</td> |
| 453 <td>Defined by your device's protocol.</td> |
| 454 </tr> |
| 455 <tr> |
| 456 <td>length (integer)</td> |
| 457 <td>Only used when direction is "in". |
| 458 Notifies the device that this is the amount |
| 459 of data the host is expecting in response.</td> |
| 460 </tr> |
| 461 <tr> |
| 462 <td>data (integer array)</td> |
| 463 <td>Defined by your device's protocol; |
| 464 only used when direction is "out".</td> |
| 465 </tr> |
| 466 <p> |
| 467 Example: |
| 468 </p> |
| 469 <pre> |
| 470 var transferInfo = { |
| 471 "direction": "in", |
| 472 "endpoint": 1, |
| 473 "length": 2 |
| 474 }; |
| 475 chrome.experimental.usb.interruptTransfer(deviceObj, transferInfo, optionalCallb
ack); |
| 476 </pre> |
| 477 <h3>Caveats</h3> |
| 478 <p> |
| 479 On Linux, |
| 480 you must have specific permission to access USB devices. |
| 481 Create a file: <code>/etc/udev/rules.d/50-yourdevicename.rules</code>. |
| 482 Add the following content: |
| 483 </p> |
| 484 <pre> |
| 485 SUBSYSTEM=="usb", ATTR{idVendor}=="yourdevicevendor", MODE="0664", GROUP="plugde
v" |
| 486 </pre> |
| 487 <p> |
| 488 On MacOSX, |
| 489 devices which expose a HID profile cannot be managed |
| 490 using this low level API due to system restrictions. |
| 491 Currently there is no workaround. |
| 492 </p> |
| 493 <h2 id="serial">Accessing serial devices</h2> |
| 494 <p> |
| 495 You can use the serial API to read |
| 496 and write from a serial device. |
| 497 </p> |
| 498 <h3>Manifest requirement</h3> |
| 499 <p> |
| 500 The "serial" permission is not yet required; |
| 501 "experimental" is enough for now: |
| 502 </p> |
| 503 <pre> |
| 504 "permissions": ["experimental"] |
| 505 </pre> |
| 506 <h3>Listing available serial ports</h3> |
| 507 <p> |
| 508 To get a list of available serial ports, |
| 509 use the <code>getPorts()</code> method: |
| 510 </p> |
| 511 <pre> |
| 512 var onGetPorts = function(ports) { |
| 513 for (var i=0; i<ports.length; i++) { |
| 514 console.log(ports[i]); |
| 515 } |
| 516 } |
| 517 chrome.experimental.serial.getPorts(onGetPorts); |
| 518 </pre> |
| 519 <h3>Opening a serial device</h3> |
| 520 <p> |
| 521 Here's how to open a serial device: |
| 522 </p> |
| 523 <pre> |
| 524 var onOpen = function(connectionInfo) { |
| 525 // The serial device has been opened. Save its id to use later. |
| 526 var conId = connectionInfo.connectionId; |
| 527 // Do whatever you need to do with the opened device. |
| 528 } |
| 529 // Open the serial device /dev/ttyS01 |
| 530 chrome.experimental.serial.open("/dev/ttyS01", onOpen); |
| 531 </pre> |
| 532 <h3>Closing a serial device</h3> |
| 533 <p> |
| 534 Here's how to close a serial device: |
| 535 </p> |
| 536 <pre> |
| 537 var onClose = function(result) { |
| 538 console.log(“Serial port closed”); |
| 539 } |
| 540 chrome.experimental.serial.close(conId, onClose); |
| 541 </pre> |
| 542 <h3>Reading from a serial device</h3> |
| 543 <p> |
| 544 The serial API reads from the serial port and |
| 545 delivers the read bytes as an ArrayBuffer. |
| 546 There is no guarantee that all the available bytes will be read in one chunk |
| 547 (they are currently read one byte per time, but this might change in the future)
. |
| 548 The following procedure can accumulate read bytes until a new line is read, |
| 549 and then call a listener with the <code>ArrayBuffer</code> bytes converted to a
String: |
| 550 </p> |
| 551 <pre> |
| 552 var dataRead=''; |
| 553 var onCharRead=function(readInfo) { |
| 554 if (!connectionInfo) { |
| 555 return; |
| 556 } |
| 557 if (readInfo && readInfo.bytesRead>0 && readInfo.data) { |
| 558 var str=ab2str(readInfo.data); |
| 559 if (str[str.length-1]==='\n') { |
| 560 dataRead+=str.substring(0, str.length-1); |
| 561 onLineRead(dataRead); |
| 562 dataRead=""; |
| 563 } else { |
| 564 dataRead+=str; |
| 565 } |
| 566 } |
| 567 chrome.experimental.serial.read(connectionInfo.connectionId, onCharRead); |
| 568 } |
| 569 /* Convert an ArrayBuffer to a String, using UTF-8 as the encoding scheme. |
| 570 This is consistent with how Arduino sends characters by default */ |
| 571 var ab2str=function(buf) { |
| 572 return String.fromCharCode.apply(null, new Uint8Array(buf)); |
| 573 }; |
| 574 </pre> |
| 575 <h3>Writing to a serial device</h3> |
| 576 <p> |
| 577 The writing routine is simpler than the reading, |
| 578 since the writing can occur all at once. |
| 579 The only catch is that if your data protocol is String based, |
| 580 you have to convert your output string to an <code>ArrayBuffer</code> |
| 581 to compy with write's method signature. |
| 582 See the code below: |
| 583 </p> |
| 584 <pre> |
| 585 var writeSerial=function(str) { |
| 586 chrome.experimental.serial.write(connectionInfo.connectionId, str2ab(str), onW
rite); |
| 587 } |
| 588 var str2ab=function(str) { |
| 589 var buf=new ArrayBuffer(str.length); |
| 590 var bufView=new Uint8Array(buf); |
| 591 for (var i=0; i<str.length; i++) { |
| 592 bufView[i]=str.charCodeAt(i); |
| 593 } |
| 594 return buf; |
| 595 } |
| 596 </pre> |
| 597 <h3>Flushing a serial device buffer</h3> |
| 598 <p> |
| 599 You can flush your serial device buffer by issuing the flush command on the API: |
| 600 </p> |
| 601 <pre> |
| 602 var flushSerial=function(str) { |
| 603 chrome.experimental.serial.flush(connectionInfo.connectionId, onFlush); |
| 604 } |
| 605 </pre> |
| 606 <p class="backtotop"><a href="#top">Back to top</a></p> |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 10832042:
Extensions Docs Server: Doc conversion script (Closed)
Base URL: svn://svn.chromium.org/chrome/trunk/src