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