# node-tradfri

> Async Node Module To Control IKEA Tradfri Lights

Latest version **0.2.3** (published 2018-05-23) · MIT License license · 0 weekly downloads

## Install

```sh
npm install node-tradfri
pnpm add node-tradfri
yarn add node-tradfri
bun add node-tradfri
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.2.3 |
| Published | 2018-05-23 |
| First published | 2017-04-21 |
| Weekly downloads | 0 |
| License | MIT License |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 354.8 KB |
| Known vulnerabilities | 0 (+11 in 2 direct dependencies) |
| Install scripts | no |
| Author | Marton Papp |
| Maintainers | morz |
| Keywords | ikea, tradfri |

## Links

- npm: https://www.npmjs.com/package/node-tradfri
- npm.io page: https://npm.io/package/node-tradfri

## Dependencies (2)

- [uuid](https://npm.io/package/uuid.md) 3.1.0
- [lodash](https://npm.io/package/lodash.md) 4.17.4

## Recent versions

- 0.2.3 (latest) — 2018-05-23
- 0.2.2 — 2017-11-26
- 0.2.1 — 2017-11-08
- 0.1.9 — 2017-11-01
- 0.1.7 — 2017-05-31
- 0.1.6 — 2017-05-27
- 0.1.5 — 2017-05-26
- 0.1.4 — 2017-05-25
- 0.1.2 — 2017-05-20
- 0.0.9 — 2017-04-29
- 0.0.8 — 2017-04-22
- 0.0.7 — 2017-04-22
- 0.0.6 — 2017-04-22
- 0.0.5 — 2017-04-22
- 0.0.4 — 2017-04-21
- … 3 more at https://npm.io/package/node-tradfri/versions

## README

# Node TRÅDFRI API ![img](http://i.imgur.com/Qicn5wu.jpg) [![Build Status](https://travis-ci.org/morzzz007/node-tradfri.svg?branch=master)](https://travis-ci.org/morzzz007/node-tradfri) [![npm version](https://badge.fury.io/js/node-tradfri.svg)](https://badge.fury.io/js/node-tradfri) [![npm](https://img.shields.io/npm/dm/node-tradfri.svg)]()
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](https://github.com/obgm/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.](#how-to-build-coap-client)

## 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
```javascript
  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:
```javascript
  const deviceIds = await tradfri.getDeviceIds();
```

Or the typical promises approach:
```javascript
  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](#methods-for-working-with-groups))

### getDeviceIds()
Returns device id's.

Response:
```javascript
  [65536, 65537, 65538]
```

### getDevices()
Returns an array with every device connected to the hub.

Example:
```javascript
[ { 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:
```javascript
await tradfri.setDeviceState(65537, { state: 'on' });
```

Combine settings, turn on and set brightness:
```javascript
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)](https://github.com/morzzz007/node-tradfri/pull/13)
|`transitionTime`|number|Sets the trainsition time

## Methods for working with groups

### getGroupIds()
Returns group id's.

Response:
```javascript
  [150429]
```

### getGroups()
Returns an array of groups with the devices in it.

Response:
```javascript
[ { 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:
```javascript
await tradfri.setGroupState(150429, { state: 'on' });
```

Combine settings, turn on and set brightness:
```javascript
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
```shell
brew install libtool
brew install automake
brew install autoconf
```

### Build
```shell
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
```shell
sudo apt-get install autoconf automake libtool
```
### Build
```shell
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

---
_Source: https://npm.io/package/node-tradfri · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._