Node TRÅDFRI API

Node API to control IKEA Tradfri (Trådfri) Lights. Currently supports Node versions 7.6+ only!

Installation

npm install node-tradfri --save

CoAP

This library uses libcoap with tinydtls to send CoAP requests. Prebuilt OsX client is included or you can build your own and set the coapClientPath config setting to point to your library. For more information on building a CoAP client for Raspibian or macOS see this section.

First steps

1. Obtain the TRÅDFRI Gateway's IP address and Security Code (found at the bottom of the gateway)
2. Generate a DTLS IDENTITY and a PRE_SHARED_KEY

How to generate a DTLS Identity

The identities will expire after 6 weeks without any usage. Each time you use it the expiration will be moved in time. That means that you should not need to think about renewals of the identities as long as it is used continuously.

Use the included script

node node_modules/node-tradfri/dtls.js HUB_IP_ADDRESS SECURITY_CODE (COAP_CLIENT_PATH [optional])

Example: node node_modules/node-tradfri/dtls.js 192.168.0.33 ABCDEFGHIJKLM

Manually

coap-client -m post -u "Client_identity" -k "SECURITY_CODE" -e '{"9090":"IDENTITY"}' "coaps://IP_ADDRESS:5684/15011/9063"

Usage

  const tradfri = require('node-tradfri').create({
    coapClientPath: './lib/coap-client', // use embedded coap-client
    identity: '<identity>',
    preSharedKey: '<pre_shared_key>',
    hubIpAddress: '<hub_ip_address>'
  });

  const devices = await tradfri.getDevices();

  // or

  await tradfri.setDeviceState(65537, {
    state: 'on',
    color: 'ffffff',
    brightness: 255
  });

API

Basics

Every exposed method is asynchronous and returns a promise.

You can use async/await:

  const deviceIds = await tradfri.getDeviceIds();

Or the typical promises approach:

  tradfri.getDeviceIds().then(deviceIds => {
    // do something
  });

Public API List

Devices	Groups
getDeviceIds()	getGroupIds()
getDevices()	getGroups()
turnOnDevice()	turnOnGroup()
turnOffDevice()	turnOffGroup()
toggleDevice()	toggleGroup()
setDeviceState()	setGroupState()

Methods for working with indivudial devices/bulbs (for groups see this section)

getDeviceIds()

Returns device id's.

Response:

  [65536, 65537, 65538]

getDevices()

Returns an array with every device connected to the hub.

Example:

[ { id: 65540,
    name: 'Ceiling 2',
    type: 'TRADFRI bulb E14 WS opal 400lm',
    on: true,
    color: 'efd275',
    brightness: 254 },
  { id: 65539,
    name: 'Ceiling 1',
    type: 'TRADFRI bulb E14 WS opal 400lm',
    on: true,
    color: 'efd275',
    brightness: 254 } ]

turnOnDevice(<deviceId>)

Parameters	type	values
deviceId	required	int/string

turnOffDevice(<deviceId>)

Parameters	type	values
deviceId	required	int/string

toggleDevice(<deviceId>, <state>)

Parameters	type	values
deviceId	required	int/string
state	optional	boolean

setDeviceState(<deviceId>, <newState>)

Examples

Turn device on:

await tradfri.setDeviceState(65537, { state: 'on' });

Combine settings, turn on and set brightness:

await tradfri.setDeviceState(65537, { state: 'on', brightness: 255 });

Usage

Parameters	type	values
deviceId	required	int/string
newState	required	object

In newState you can combine the following values:

Parameters	values	action
state	boolean/string ('on', 'off')	Toggle light on/off
color	string (hex color value, ex: 'efd275')	Sets color
brightness	number/string (0-255)	Sets brightness
colorX, colorY	number	Sets color (how to use)
transitionTime	number	Sets the trainsition time

Methods for working with groups

getGroupIds()

Returns group id's.

Response:

  [150429]

getGroups()

Returns an array of groups with the devices in it.

Response:

[ { id: 150429,
    name: 'Kitchen',
    devices: [ [Object], [Object], [Object] ],
    on: false } ]

turnOnGroup(<groupId>)

Parameters	type	values
groupId	required	int/string

turnOffGroup(<groupId>)

Parameters	type	values
groupId	required	int/string

toggleGroup(<groupId>, <state>)

Parameters	type	values
groupId	required	int/string
state	optional	boolean

setGroupState(<groupId>, <newState>)

Examples

Turn group on:

await tradfri.setGroupState(150429, { state: 'on' });

Combine settings, turn on and set brightness:

await tradfri.setGroupState(150429, { state: 'on', brightness: 255 });

Usage

Parameters	type	values
groupId	required	int/string
newState	required	object

In newState you can combine the following values:

Parameters	values	action
state	boolean/string ('on', 'off')	Toggle light on/off
color	string (hex color value, ex: 'efd275')	Sets color
brightness	number/string (0-255)	Sets brightness

How to build CoAP client

OsX

Prerequisites

brew install libtool
brew install automake
brew install autoconf

Build

git clone https://github.com/obgm/libcoap.git
cd libcoap
git checkout origin/dtls
git checkout -b dtls
git submodule update --init ext/tinydtls
cd ext/tinydtls
autoreconf
./configure
cd ../../
./autogen.sh
./configure --disable-shared --disable-documentation
make

Now you can find the coap-client in the /examples directory

Raspibian (Raspberry Pi)

Prerequisites

sudo apt-get install autoconf automake libtool

Build

git clone https://github.com/obgm/libcoap.git
cd libcoap
git checkout origin/dtls
git checkout -b dtls
git submodule update --init ext/tinydtls
cd ext/tinydtls
autoreconf
cd ../../
./autogen.sh
./configure --disable-shared --disable-documentation
make

Now you can find the coap-client in the /examples directory