Accessing Hardware Devices

This doc shows you how packaged apps can connect to USB devices and read from and write to a user's serial ports. See also the reference docs for the USB API and the Serial API. The Bluetooth API is also available; we've include a link to a Bluetooth sample below.

API Samples: Want to play with the code? Check out the serial, servo, usb, and zephyr_hxm Bluetooth samples.

Accessing USB devices

You can use the USB API to send messages to connected devices using only JavaScript code. Some devices are not accessible through this API - see the Caveats section below for more details.

Manifest requirement

The USB API requires a special permission "usb" in the manifest file:

"permissions": [
  "usb"
]

Finding a device

Every device in a USB bus is identified by its vendor and product IDs. To find a device, use the findDevices() method which has two parameters:

chrome.usb.findDevices(FindDeviceOptions, callback)

Example:

var onDeviceFound = function(devices) {
  _this.devices=devices;
  if (devices) {
    if (devices.length > 0) {
      console.log("Device(s) found: "+devices.length);
    } else {
      console.log("Device could not be found");
    }
  } else {
    console.log("Did not request correct permissions");
  }
};

chrome.usb.findDevices({"vendorId": vendorId, "productId": productId}, onDeviceFound);

USB transfers and receiving data from a device

USB protocol defines four types of transfers: control, bulk, isochronous and interrupt. Theoretically they can occur in both directions:
device-to-host (inbound) and host-to-device (outbound).

However, due to the nature of the USB protocol, both inbound and outbound messages must be initiated by the host (your computer). For inbound (device-to-host) messages, the host, your JavaScript code, sends a message flagged as "inbound" to the device. The exact contents of the message depends on the device, but usually will have some identification of what you are requesting from it. The device then responds with the requested data. The device's response is handled by Chrome and delivered asynchronously to the callback you specified in the transfer method. An outbound (host-to-device) message is similar, but the response doesn't contain data returned from the device.

For each message from the device, the specified callback will receive an event object with the following properties:

Example:

var onTransferCallback = function(event) {
   if (event && event.resultCode === 0 && event.data) {
     console.log("got "+event.data.byteLength+" bytes");
   }
};

chrome.usb.bulkTransfer(device, transferInfo, onTransferCallback);

CONTROL transfers

Control transfers are generally used to send or receive configuration or command parameters to a USB device. The method is simple and receives three parameters:

chrome.usb.controlTransfer(deviceObj, transferInfo, transferCallback)

Values for transferInfo object:

Example:

var transferInfo = {
   "requestType": "vendor",
   "recipient": "device",
   "direction": "out",
   "request":  0x31,
   "value": 120,
   "index": 0,
   "data": new Uint8Array([4, 8, 15, 16, 23, 42]).buffer
 };
chrome.usb.controlTransfer(deviceObj, transferInfo, optionalCallback);

ISOCHRONOUS transfers

Isochronous transfers is the most complex type of USB transfers. They are commonly used for streams of data, like video and sound. To initiate an isochronous transfer (either inbound or outbound), you must use:

chrome.usb.isochronousTransfer(deviceObj, isochronousTransferInfo, transferCallback)

Values for isochronousTransferInfo object:

Example:

var transferInfo = {
   "direction": "in",
   "endpoint": 1,
   "length": 2560
 };
var isoTransferInfo = {
  "transferInfo": transferInfo,
  "packets": 20,
  "packetLength": 128
};
chrome.usb.isochronousTransfer(deviceObj, isoTransferInfo, optionalCallback);

Notes: One isochronous transfer will contain isoTransferInfo.packets packets of isoTransferInfo.packetLength bytes. If it is an inbound transfer (your code requested data from the device), the data field in the onUsbEvent will be an ArrayBuffer of size transferInfo.length. It is your duty to walk through this ArrayBuffer and extract the different packets, each starting at a multiple of isoTransferInfo.packetLength bytes. If you are expecting a stream of data from the device, remember that you will have to send one "inbound" transfer for each transfer you expect back. USB devices don't send transfers to the bus unless the host explicitly requests them through "inbound" transfers.

BULK transfers

Bulk transfer is an USB transfer type commonly used to transfer a large amount of data in a reliable way. The method has three parameters:

chrome.usb.bulkTransfer(deviceObj, transferInfo, transferCallback)

Values for transferInfo object:

Example:

var transferInfo = {
   "direction": "out",
   "endpoint": 1,
   "data": new Uint8Array([4, 8, 15, 16, 23, 42]).buffer
 };

INTERRUPT transfers

Interrupt transfers are used to send important notifications. Since all USB communication is initiated by the host, host code usually polls the device periodically, sending interrupt IN transfers that will make the device send data back if there is anything in the interrupt queue. The method has three parameters:

chrome.usb.interruptTransfer(deviceObj, transferInfo, transferCallback)

Values for transferInfo object:

Example:

var transferInfo = {
   "direction": "in", 
   "endpoint": 1,
   "length": 2
 };
chrome.usb.interruptTransfer(deviceObj, transferInfo, optionalCallback);

Caveats

On most Linux systems, USB devices are mapped with read-only permissions by default. To access it through this API, your user will need to have write access too. A simple solution is to set a udev rule. Create a file /etc/udev/rules.d/50-yourdevicename.rules with the following content:

SUBSYSTEM=="usb", ATTR{idVendor}=="[yourdevicevendor]", MODE="0664", GROUP="plugdev"

Then, just restart the udev daemon: service udev restart. You can check if the permissions are correctly set by:

• Find the bus and device numbers in lsusb
• ls -al /dev/bus/usb/[bus]/[device]. This file should be owned by group "plugdev" and have group write permissions.

Not all devices can be accessed through this API. In general, devices are not accessible either because the Operating System's kernel or a native driver holds them off from user space code. Some examples are devices with HID profiles on OSX systems and USB pen drives.

Accessing serial devices

You can use the serial API to read and write from a serial device.

Manifest requirement

You must add the "serial" permission to the manifest file:

"permissions": [
  "serial"
]

Listing available serial ports

To get a list of available serial ports, use the getPorts() method. Note: 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.

var onGetPorts = function(ports) {
  for (var i=0; i<ports.length; i++) {
    console.log(ports[i]);
  }
}
chrome.serial.getPorts(onGetPorts);

Opening a serial device

If you know the serial port name, you can open it for read and write using the open method:

chrome.serial.open(portName, options, openCallback)

A simple example:

var onOpen = 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.
}
// Open the serial port /dev/ttyS01
chrome.serial.open("/dev/ttyS01", {bitrate: 115200}, onOpen);

Closing a serial port

Closing a serial port is simple but very important. See the example below:

var onClose = function(result) {
 console.log("Serial port closed");
}
chrome.serial.close(connectionId, onClose);

Reading from a serial port

The serial API reads from the serial port and delivers the read bytes as an ArrayBuffer. There is no guarantee that all the requested bytes, even if available in the port, will be read in one chunk. The following example can accumulate read bytes, at most 128 at a time, until a new line is read, and then call a listener with the ArrayBuffer bytes converted to a String:

var dataRead='';

var onCharRead=function(readInfo) {
    if (!connectionInfo) {
      return;
    }
    if (readInfo && readInfo.bytesRead>0 && readInfo.data) {
      var str=ab2str(readInfo.data);
      if (str[readInfo.bytesRead-1]==='\n') {
        dataRead+=str.substring(0, readInfo.bytesRead-1);
        onLineRead(dataRead);
        dataRead="";
      } else {
        dataRead+=str;
      }
    }
    chrome.serial.read(connectionId, 128, onCharRead);
  }

/* Convert an ArrayBuffer to a String, using UTF-8 as the encoding scheme.
   This is consistent with how Arduino sends characters by default */
  var ab2str=function(buf) {
    return String.fromCharCode.apply(null, new Uint8Array(buf));
  };

Writing to a serial port

The writing routine is simpler than reading, since the writing can occur all at once. The only catch is that if your data protocol is String based, you have to convert your output string to an ArrayBuffer. See the code example below:

var writeSerial=function(str) {
  chrome.serial.write(connectionId, str2ab(str), onWrite);
}
// Convert string to ArrayBuffer
var str2ab=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;
}

Flushing a serial port buffer

You can flush your serial port buffer by issuing the flush command:

  chrome.serial.flush(connectionId, onFlush);

Back to top