testing & QA

Writing your first Android Things driver

Android with a person outfit. I like to travel and I love my 2 dogs. Sometimes I also like noisy things, like mechanical keyboards.

Android Things is a lightweight version of the Android operating system that can be installed on IoT-focused devices. Android Things includes 'user drivers' functionality, enabling developers to easily control a wide range of peripherals (LEDs, switches, buttons, servo motors etc). Let’s take a look at what it takes to write a new peripherals driver for Android Things.


At the time of writing, Google hasn't announced what the requirements will be for a piece of hardware to run Android Things but the hardware documentation states that they're focusing on system on module (SoM) boards. While the only supported development boards for Android Things are the Raspberry Pi 3, the Intel Edison and the NXP Pico i.MX6UL, it would seem that almost any board will be able to run Android Things. The supported boards don't offer many sensors, LEDs and buttons to play with, but once an Android Things device is up and running you can easily plug in peripherals.

User drivers

One of the things that got me excited about working on an Android Things project was the idea of user drivers.

user drivers are managed by developers and can be reused across multiple apps

As shown in the above image, developers can use the Android Framework APIs directly and build their apps using user drivers. These are a thin layer that accesses and controls a peripheral piece of hardware from the Android Things app. This allows us to focus on what matters: writing an awesome app.

You can find a list of the available user drivers on Github. The cool thing about these drivers is that they're like any other Android library, meaning you can add one line to the project's build.gradle dependencies and the driver will be imported.

What happens if you want to use a peripheral that doesn't have an Android Things driver yet? You have 2 options:

  1. Pick a different peripheral and hope there's a driver for that.
  2. Go the DIY-way and write the driver yourself.

If you take the second option, you can contribute back to the open source community by sharing the driver to let anyone (including you) reuse that code in future projects. To do this you’ll need the peripheral documentation that the vendor provides 1.

Hardware Hacking

First of all you have to understand which communication protocol the peripheral uses. Android Things has support for the following types of communication:

the PWM protocol works by changing the pulse width to represent different values

Read the documentation from the peripheral vendor to find out what to use. If it uses one of the above methods then implementing a driver should be quite straight forward. Otherwise you'll have to implement whichever protocol it uses with GPIO ports.

Investigating the driver protocol

I bought this RGB LED strip with the code WS2801 printed on both chips. This is the datasheet for the WS2801, which I found by searching for ‘WS2801 datasheet’. In the PDF, the features list mentions that the chip uses PWM, but don’t let that fool you. On page five there’s a list of input and output pins and you can see the chip has a clock input (CKI), a data input (SDI), a power supply (VCC) and ground (GND), which are the pins that you can also find in the LED strip.

Investigating which protocol to use, the main indicator here is the number of pins needed. While power and ground are generic for most peripherals, the need for a clock and data input as separate pins indicates that you have to use either I2C or SPI (not PWM as that only uses one line).

Another indicator is the clock speed: the I2C standard is 400kHz (but can go up to ~3MHz), while the datasheet says the WS2801 accepts a maximum clock frequency of 25MHz.

The third and last indicator is the data format: on page 12 it shows that the only data the chip needs to operate is 3 bytes (red, green and blue values) and it will leave the rest of the data for the next chip (ie next LED of the strip). There is no mention of acknowledgement or 2-way communication. This leaves out I2C and UART from the list so you can use SPI.

A peripheral datasheet will also specify important values such as minimum and maximum voltages, maximum clock speed and whether the data is read on the leading or trailing clock edge.

Once you know which form of communication you have to use (SPI in the above example) you can start thinking about connecting and coding.

Connecting the peripheral to the developer board

It's time to find out which pins on the board need to be used in order to talk to the peripheral from the Android side. The easiest way is to find the pinout for your development board on the Android Things developer site. A pinout shows which pin can be used for each form of communication. Have a look at the Raspberry Pi 3 pinout for example:

In this case I used pin 2 (or 4) for power (VCC), pin 6 (or 9, 14, etc) for ground (GND), pin 23 for clock (CKI) and pin 19 for data (SDI). Note that there are two similar pins: 19 – MOSI, which stands for master out slave in and pin 21 – MISO or master in slave out. In this case I had to use MOSI because the master (Android Things device) will send out data and the slave (LED strip) will read it in.

One important thing to note is different boards have different output voltages and different peripherals need different voltages to operate, so be careful. The peripheral may not work and could burn out, so always check the specs before plugging a peripheral into a board and use a level converter if needed. For example, this article on Raspberry Pi 3 GPIO explains that pins can output either 0V(low) or 3.3V (high) and it also has two 5V pins. If the GPIO pins are configured as input then using any value higher than 3.3V will damage the board.

Software Hacking

At this point you should have a peripheral device plugged in to your Android Things board and you know the protocol you're going to use. So, it's time to start writing some code.

Now let's look at how to implement the peripheral driver using SPI. A few days ago I submitted a PR to the drivers repository on Github, adding the driver for WS2801. These are the main things you need to include when writing a driver.

Android Things driver creation

Start by creating a standard gradle module and in the build.gradle add:

apply plugin: 'com.android.library'

android {  
    compileSdkVersion 24
    buildToolsVersion '24.0.3'

    defaultConfig {
        minSdkVersion 24
        targetSdkVersion 24
        // Other default stuff...
    }
}

dependencies {  
    provided 'com.google.android.things:androidthings:0.1-devpreview'
}

Remember, this is like any other Android library. You can use the com.android.library plugin and for Android Things you'll need to use at least API 24 as minimum SDK version. You should also specify com.google.android.things:android things as a provided dependency. This means you need it to be able to compile the app, but you don't want to distribute this dependency with the driver once it’s released.

Next you need to add one line to your AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"  
    package="com.xrigau.driver.ws2801">
    <application>
        <uses-library android:name="com.google.android.things" /> // THIS
    </application>
</manifest>  

Adding this line is the way to instruct the app to only run on Android Things devices rather than phones, tablets etc.

Now for the driver itself. Create a new class (I called it Ws2801.java) and write the driver code. The first thing you’ll need to do is open the SPI port so you can start sending data to it, and then close the port. Here are the main parts:

package com.xrigau.driver.ws2801;

import com.google.android.things.pio.PeripheralManagerService;  
import com.google.android.things.pio.SpiDevice;  
import java.io.IOException;

public class Ws2801 implements AutoCloseable {  
  // ...
  private final SpiDevice device;

  public static Ws2801 create(String spiBusPort) throws IOException {
    PeripheralManagerService pioService = new PeripheralManagerService();
    try {
      return new Ws2801(pioService.openSpiDevice(spiBusPort));
    } catch (IOException e) {
      throw new IOException("Unable to open SPI device in bus port " + spiBusPort, e);
    }
  }

  Ws2801(SpiDevice device) throws IOException {
    this.device = device;
    device.setFrequency(1000000); // 1MHz clock frequency
    device.setMode(SpiDevice.MODE0); // Mode 0 seems to work best for WS2801
    device.setBitsPerWord(8);
  }

  public void write(int[] colors) throws IOException {
    // … some computation
    Int[] colorsToSend = new int[]{Color.RED, Color.WHITE, Color.parseColor(“#0FACE0”)}; // As many as LEDs in the strip
    device.write(colorsToSend, colorsToSend.length);
  }

  @Override
  public void close() throws IOException {
    device.close(); // IMPORTANT: If you don’t close it then the resource can’t be opened again.
  }
}

Notice that first you need to create an instance of the PeripheralManagerService. This is used to get information of the different input/output (I/O) interfaces the development board has, as well as open buses or GPIO pins. In the example code above, I called the openSpiDevice(String spiBusName) method to open the SPI bus interface. Once you have a reference to the SpiDevice you can configure the bus and start sending it data.

Note: the code has been simplified, see the full source code on Github.

And that’s all you need.4 Now you can start using the driver.

it works!!1!!11!


So far we have looked at the different types of inputs and outputs Android Things boards support and how to identify which interface is needed to communicate with a peripheral. We’ve covered which pins to use for each different interface and how to implement a driver to control the peripheral using the Android Things SDK.

In my next blog post we’ll look at how to test the peripheral driver to improve your confidence when using or sharing your peripheral driver. If you’d like to discuss this post or give me any feedback on your own experiences for my next blog post please get in touch with me on Twitter or Google+.

Last but not least, I’d like to give thanks to Daniele Bonaldo, Luis Valle and especially to Paul Blundell for reviewing this post.


Read the second part of this blog post here: Testing your first Android Things driver


  1. When you want to use any peripheral for the first time always check the manufacturer’s website for the datasheet, usually a PDF file. It may also be in the product description on the seller’s website. If you can’t find it on either of those websites then search for the keywords you see written on the chips or the board.

  2. GPIO pins cannot be used as an output if they were previously enabled as an input with an edge trigger enabled since the last reboot.

  3. A slave can be seen as an individual component on your hardware peripheral, eg each sensor in a rack of sensors.

  4. In the existing drivers, there's a .driver-metadata file but it’s only used by the repo maintainers to automatically generate some documentation as explained in this StackOverflow question.

Enjoyed this article? There's more...

We send out a small, valuable newsletter with the best stories, app design & development resources every month.

No spam, no giving your data away, unsubscribe anytime.

About Novoda

We plan, design, and develop the world’s most desirable software products. Our team’s expertise helps brands like Sony, Motorola, Tesco, Channel4, BBC, and News Corp build fully customized Android devices or simply make their mobile experiences the best on the market. Since 2008, our full in-house teams work from London, Liverpool, Berlin, Barcelona, and NYC.

Let’s get in contact