IKEA TRÅDFRI Library

While working on a desktop client for the IKEA TRÅDFRI system, I first wrote a library to access the devices. That library can also be used in other PHP applications.

Below you'll find the documentation of the library. Source code can be found at https://bitbucket.org/garrcomm/tradfri-php-library.

How to use

First, initiate a TRÅDFRI client. It's best to store the client data and re-use that, since the gateway doesn't like many clients in memory.

<?php
$ip = '192.168.2.170';
$securityCode = 'f00b4r';

// Initiate a TRÅDFRI client
$tradfri = new \Garrcomm\Tradfri\Service\Tradfri($ip, '/usr/local/bin/coap-client');

// First time; fetch a client ID and pre-shared key
$clientData = $tradfri->authenticate($securityCode);

When we have the client data, we can continue like this:

$ip = '192.168.2.170';

// Initiate a TRÅDFRI client
$tradfri = new \Garrcomm\Tradfri\Service\Tradfri($ip, '/usr/local/bin/coap-client');

// Log in using known credentials
$tradfri->setClientIdentity($clientData['clientIdentity'], $clientData['privateSharedKey']);

// Turn on all plugs that are currently off
foreach($tradfri->listDevices() as $device) {
    if ($device instanceof \Garrcomm\Tradfri\Model\TradfriPlug && !$device->isOn()) {
        $device->turnOn();
    }
}

A device can be any class extending BaseTradfriDevice. Each device can have its own capabilities. There are several ways to see which capabilities a device has:

// instanceof check
if ($device instanceof \Garrcomm\Tradfri\Model\TradfriLight) {
    // I'm a lamp, so you can display me with a lamp icon.
}

// method_exists check
if (method_exists($device, 'turnOn')) {
    // I'm either a plug, or a lamp, or maybe something else? But you can turn me on!
}
if (method_exists($device, 'setBrightness')) {
    // I'm very likely some kind of a lamp. You can brighten me up!
}

To see more usages, check out the code in https://bitbucket.org/garrcomm/tradfri-web-application

coap-client dependency

For PHP, we don't have many dependencies. Just PHP 7.3+ and ext-json (which is installed in PHP by default). But we do need a coap-client binary. There are several approaches.

In my Web application example, a docker container is included that already has this binary. You can also compile it yourself on your machine by executing the script found at https://github.com/glenndehaan/ikea-tradfri-coap-docs/tree/master/scripts.

A 3rd option, during development, you can use the coap-client simulator that's available in this repository in the tests/CoapClient folder. This script is also used for unit tests and simulates my own IKEA Home setup.

Tested with IKEA TRÅDFRI products

For testing, I started with the devices I already had in my home. Later I purchased a few extras to be able to test more functionalities. See supported-devices.md for a full list of devices I used during tests.

Other devices will probably also work, but I haven't tested them. Also, keep in mind that sensors/remote controls/dimmers are input devices. Just as this app, they're ment to write to output devices. So although I detect those devices, it's not possible to interact with them, except for reading their battery state and meta data.

On my wishlist I have these items:

  • FYRTUR Block-out roller blind
    My home office has two windows next to each other, one of 160cm and one of 60cm wide. The current sizes of the FYRTUR series won't cover this whole set of windows. But it would be nice if this project also supported the blinds in the future.
  • TRÅDFRI LED bulb GU10 CWS opal 345 lumen
    On my attic I have four spots on my Lego train table. At some point I want to add multicolor lights there.

Tip for Windows Developers

In the bin folder, a few batch files exist, to make development easier.

If you install Docker Desktop for Windows, you can use bin\composer.cmd, bin\phpcs.cmd, bin\phpunit.cmd and bin\security-checker.cmd as shortcuts for Composer, CodeSniffer, PHPUnit and the Security Checker, without the need of installing PHP and other dependencies on your machine.

The same Docker container and tools are used in Bitbucket Pipelines to automatically test this project.

External resources

Before I started on this project, I used Google to find something simular. I did not find much PHP related that I could use, but I found some useful resources:

  • A basic PHP-wrapper for the libcoap coap-client. I didn't use this because it only has 1 commit and is not a complete application, nor a ready-to-use package, but it was a good inspiration nonetheless;
    https://github.com/MiniMeOSc/phpTradfri
  • Very well written documentation on how the TRÅDFRI gateway works with CoAP:
    https://github.com/glenndehaan/ikea-tradfri-coap-docs
  • A list of many constants that helped identifying the numeric values in the CoAP protocol:
    https://gist.github.com/r41d/5d62033f88b3046bccf406c9158d4e59