Google Assistant support for IKEA TRÅDFRI lights

Update (2018-04-21): IKEA has rolled out official support for Google Assistant, so if you just want your lights to work with Google Home, you don't need any of this. If you're interested in the technical side, you may still find this post useful.

Earlier this year I got some IKEA smart lights from their TRÅDFRI line. They can be controlled by a remote and also through a smartphone app, if you have IKEA's gateway. Around the same time I also got a Google Home and naturally I wanted them all to work together. IKEA is planning to add official support for Google Assistant very soon, but in the meantime I rolled out my own. So while all this may be obsolete soon, I still wanted to publish it in the hope that it might be useful for someone (perhaps for adding Assistant support to some other smart lighting system without official support). Below I try to provide a step-by-step description of how I got it to work, but if you just want to see the code, here it is.

Let's get started. We're going to need a computer on the same network as the IKEA gateway (or it must be able to reach it though some clever routing). I used a Raspberry Pi, but any computer running Linux will do. This computer needs to have its 443 port accessible from the Internet, so if it's behind a router, you need to configure port forwarding. We're also going to need a domain name that will point to our Linux box and a proper SSL/TLS certificate for that domain. I'm not going to go into details about these, but you can easily get a certificate for free at Let's Encrypt. Below I'm using home.example.com as the domain name, obviously you should change it to your actual domain wherever it appears.

The general architecture of the solution is as follows. We're going to create a Smart Home App on Actions on Google and deploy it in testing mode. Then when we talk to the Google Assistant (on Google Home or a phone or a smartwatch), Google's cloud magic will make a call to our server, asking what lights are available or telling it to turn a certain light on or off. Then our app will talk to the IKEA gateway, which in turn talks to the light bulbs themselves. Using the Actions SDK instead of IFTTT means we will get to use more natural language commands without defining each phrase manually.

Google's documentation likes to give all the examples in node.js, but the app can by anything as long as it speaks the proper API over HTTP. I wrote mine in Python using Django and deployed it using nginx and uwsgi, but any other way of deploying a Django app would also work.

Let's get the code (below I assume we're running as the pi user, change to your actual user and group if they're different):
sudo mkdir /var/www/home.example.com
sudo chown pi:pi /var/www/home.example.com
cd /var/www/home.example.com/
git clone https://github.com/jfedor2/ikea-tradfri-google-assistant.git .
One more thing we're going to need is the coap-client tool, compiled with DTLS (encryption) support. It's what we're going to use to talk to the IKEA gateway. I'm going to borrow the instructions for compiling it from here:
sudo apt-get install build-essential autoconf automake libtool
git clone --recursive https://github.com/obgm/libcoap.git
cd libcoap
git checkout dtls
git submodule update --init --recursive
./configure --disable-documentation --disable-shared
sudo make install
Once we have the coap-client tool installed, there's a one-time step that we need to perform to set up an identity that we'll use to authenticate to the IKEA gateway (in other words, a login and password). For that we will need to know the gateway's IP address on the local network and the security code that's printed on the bottom of the gateway. Also we need to come up with an identity (username) that we'll use. This can be anything, e.g. "foobar". With those in hand we run the following command (substituting the appropriate values):
coap-client -m post -u Client_identity -k 'security code' -e '{"9090":"chosen username"}' "coaps://IP address of your IKEA gateway:5684/15011/9063"
The gateway should reply with a pre-shared key that we'll use for authentication. Write that down somewhere.

Let's get back to our app and actually make it work. First, let's create a Python virtual environment for the app so that we can install the necessary modules locally:
cd /var/www/home.example.com/
virtualenv .virtualenv
. .virtualenv/bin/activate
pip install -r requirements.txt
Then we need to edit the Django settings file. You can either edit /var/www/home.example.com/tradfri/settings.py or leave that file unchanged and create a new file, /var/www/home.example.com/tradfri/local_settings.py, with just the settings that need changing locally. (That way it's easier to keep settings.py under version control.) You need to provide the following settings:
SECRET_KEY = 'insert a long string of random characters here that you will keep private'
ALLOWED_HOSTS = ['home.example.com']
COAP_CLIENT = '/usr/local/bin/coap-client' # or wherever you installed it
IKEA_IDENTITY = 'the username we chose above'
IKEA_PRE_SHARED_KEY = 'the pre-shared key that the gateway provided'
GATEWAY_ADDRESS = 'IP address of your IKEA gateway'
Depending on your local network configuration, it may also be useful to add the local IP address of your Linux computer to ALLOWED_HOSTS (if you're using port forwarding on the router, accessing the server through the proper domain name might not work from inside the network):
ALLOWED_HOSTS = ['home.example.com', '192.168.0.x']
Then, create the necessary tables in the database (run the following commands in the Python virtual environment created above - run the activate command before if you haven't already in this shell):
./manage.py migrate
And let's create a user that we will use for OAuth2 account linking:
./manage.py createsuperuser
Choose whatever username and password you want and remember them.

In the extras directory, I provided example configuration files for nginx and uwsgi, home.example.com.conf and home.example.com.ini. Edit them with your specific settings and put them in /etc/nginx/sites-enabled/ and /etc/uwsgi/apps-enabled/, respectively.

After updating the configuration files, restart uwsgi and nginx (install them first if necessary):
sudo apt-get install nginx uwsgi-plugin-python
sudo service uwsgi restart
sudo service nginx restart
Whenever you change something in the Django app, you need to restart uwsgi.

In the extras directory there's also an actions.json file, that we will use to tell Google where to look for our app. But first we need to create a project for it.

Go to the Actions on Google console. Click "Add/import project", choose a name and click "create project". In the "Add actions to your app" section, click on "Actions SDK". It will give you an example command that looks something like this:
gactions update --action_package PACKAGE_NAME --project smartlights-abc12
smartlights-abc12 is your project ID, which you will need in a moment.

Update the /var/www/home.example.com/extras/action.json file with your actual domain name, download the gactions command-line tool and run it, substituting the actual project ID of course (you may have to provide a path to the tool if it's not in your PATH):
gactions test --action_package /var/www/home.example.com/extras/action.json --project smartlights-abc12
This will put your app in testing mode and make it accessible in the Google Home app on your phone (you have to be using the same Google account). Google says an app only works in testing mode for 3 days, but I found that in reality it works indefinitely.

In the Google Actions console you probably also need to provide some text and graphics for your app. It doesn't matter what you put there (no-one else is going to see it).

Now all that is left is to set up OAuth2 for account linking. We need to configure it on both our app and the Actions on Google console. Go to https://home.example.com/oauth2/applications/ or http://192.168.0.x/oauth2/applications/ (substituting the correct address of course). Log in using the user and password you created with createsuperuser. Click "New Application". Put some name in (I used "google"), note the client ID and client secret (you're going to need them in a moment), choose "client type": "confidential", "authorization grant type": "authorization code" and put https://oauth-redirect.googleusercontent.com/r/smartlights-abc12 in "redirect uris" (substituting your project ID from above). Click "Save". Now go to the Actions on Google console and in your project go to "Account linking". Choose "Authorization code" under "Grant type" as before. Under "Client information", paste the client ID and client secret that you saw in our app's web interface a moment ago. Then put https://home.example.com/oauth2/authorize/ under "Authorization URL" and https://home.example.com/oauth2/token/ under "Token URL". Click "save".

We're almost done. Open the Google Home app on your phone. Open the hamburger menu and tap "Home control". Tap the plus icon in the bottom right corner. This should give you a long list of devices that are officially supported by the Google Assistant, but also our humble app should be there on the very top, with its name prefixed with "[test]". Tapping it should take you to a login form on our app. Login with the user and password you created with createsuperuser a few minutes ago and on the next screen confirm that you want to give Google access. (You may have to disable wifi on your phone and use the cellular network connection for this step if https://home.example.com/ doesn't work from inside your local network.)

Boom, that's it. You should get a list of your IKEA lights and be able to control them with Google Assistant.

Update (2017-12-04): With version 1.2.42 of the IKEA gateway firmware, the authentication scheme changed. The code and this post have been updated accordingly.


External notification light for your phone

Among other interesting things, Android 4.3 introduced a proper way of accessing notifications from an app. I used this API to make an external notification light for my phone:

It uses Adafruit's Trinket, a Bluetooth serial board from dx.com to talk to the phone and it's powered via USB. Here's a diagram of the connections:

The Arduino sketch that's running on the Trinket is very simple, it listens on the serial line that's connected to the Bluetooth board and turns the LED on and off depending on what character is received. You can see the sketch here. On Android side, the code is also pretty simple, there's an intent filter in the manifest to register a listener that gets called whenever a notification is posted or dismissed. In the listener we check what notifications are active and if they requested the notification light to be turned on (your phone might not even have a notification light, but the information is still there). Then we connect to the Trinket via Bluetooth and tell it to turn the LED on or off. You can see the code here. There is no UI and the Bluetooth address is hardwired.

There is no special permission in the manifest to let the app access notifications, instead you grant access via a checkbox in the security section of your phone's settings:

As usual, there's room for improvement. For example if the phone fails to connect to the device via Bluetooth (because it's out of range or powered off), it should probably try again in some time. Also, we could have an RGB LED and send color and timing information, instead of just on/off state, to better replicate the behavior of the notification light.


Morse code Bluetooth keyboard

My previous attempt at a Morse code keyboard worked over USB and used a copper coin as a capacitive sensor. Since then I've acquired a real telegraph key and Adafruit's Bluefruit EZ-Key board. With that and a Trinket I made a Morse code Bluetooth keyboard. It works with any computer that has Bluetooth (also phones and tablets).

Here's what it looks like in action (as usual please excuse my lack of Morse code skills):

Here's the Arduino sketch that's running on the Trinket. As before there's a buzzer for feedback and the transmission speed is fixed.

If you're into Morse code, I continue to recommend my Android application that listens to Morse code using your smartphone's microphone and translates it to text.

Here's a diagram of the connections:


Bluetooth mouse from a Wii nunchuck

I never had a Nintendo Wii, but I got a nunchuck controller to play with. It has a joystick, two buttons, an accelerometer for orientation sensing and the third-party ones are dirt cheap. It turns out that it's really easy to talk to them from an Arduino too, because they speak I2C and as you would expect the protocol is well documented on the Internet. I used Adafruit's Trinket, Bluefruit EZ-Key and a 100 mAh lipo battery to turn the nunchuck into a Bluetooth mouse:

Here's a diagram of the connections, pin 1 on the Trinket goes to the RX pin on the Bluefruit and pins 0 and 2 are used for the I2C communication with the nunchuck:

On the software side, I used the WiiChuck class I found here, but I modified it to use the TinyWireM library for I2C. It is equivalent to the standard Arduino Wire library, but it runs on ATtiny chips like the one used by the Trinket. I also used this SendOnlySoftwareSerial library. Here's my sketch and the modified WiiChuck library.

I haven't found any clever use for the accelerometer inside the nunchuck yet, perhaps it could somehow be used for scrolling.

Bluetooth emergency mute button

Some time ago I made an emergency mute button that connected over USB. Now with Adafruit's Bluefruit EZ-Key I made a wireless version that works over Bluetooth. Look, no wires:

In addition to the Bluefruit board, I used a Trinket and a 100 mAh lipo battery. It all fit nicely inside the button:

Here's a diagram of the connections:

There's no on/off switch and to charge the battery I have to disassemble the whole thing, but hey, nobody's perfect. Here's the Arduino sketch that's running on the Trinket, it simply sends the "mute" key code when it detects a change in the state of the button. I'm using this SendOnlySoftwareSerial library, because I'm only sending data to the Bluefruit board.

(You will notice that it still suffers from the synchronization problem that the USB version had - if you mute audio on your computer some other way than using the button, then pressing the button will actually unmute audio. It's because the button is stateful, but has no way of finding out what the actual state of audio on the computer is and there are no separate key codes for muting and unmuting.)


DIY presentation clicker

I think it is very cool that with a board like the Arduino it is easy to make your own USB input devices that speak the regular HID protocol and therefore work with any modern computer (and even some phones and tablets) without any additional software or drivers. For example I made this emergency mute button that I still think is a very practical device. But making Bluetooth input devices used to be somewhat harder, until Adafruit released their Bluefruit EZ-Key. Its purpose is making it easy to create devices that work as Bluetooth keyboards and mice. And in the simplest cases, it doesn't even require a separate microcontroller. I got one and to test it I made this presentation clicker:

It has two buttons that are connected directly to Bluefruit's pins 2 and 3 that correspond to left/right arrow keys by default:

And then it's enough to provide power (I used a coin cell battery) and pair it with your computer. The form factor is reasonable so I could even imagine using it in real life:

Bluetooth thermometer

Some time ago I measured the temperature inside my fridge with a Raspberry Pi and a TMP36 sensor. That was cool, but obviously you don't need an entire computer running Linux just to report temperature. So I made a wireless thermometer using Adafruit's Trinket, a DHT22 temperature/humidity sensor and a cheap Bluetooth serial module from dx.com. Here's what it looks like:

And here's a diagram:

The connections are pretty straightforward, I used three AA batteries for power, which was fine for the 3.3V Trinket and the Bluetooth module. I connected the DHT22 sensor to the regulated 3.3V output on the Trinket. I only connected the RX pin on the Bluetooth module, because I was only going to be sending data. The DHT22 sensor also has one data pin and there's a 10K pull up resistor between the data pin and VCC.

As far as software goes, I used this library to talk to the DHT22 sensor, because the one from Adafruit that I used previously with a real Arduino didn't want to work on a Trinket for some reason. I also used this SendOnlySoftwareSerial library because I was only sending data and with the regular SoftwareSerial library the sketch wouldn't fit in Trinket's limited memory. You can the sketch I used here, it's a simple modification of the example sketch that comes with the DHT22 library.

To read the temperature from this thermometer, you need a device (phone, tablet, computer) with Bluetooth and a terminal application. It prints the temperature and humidity every two seconds: