Dirigera

An unofficial TypeScript client library for IKEA's DIRIGERA smart home hub.

The library is based on reverse-engineering the communication with the DIRIGERA hub. Changes to the hub's firmware may
break functionality. Some of the type definitions are incomplete, and some of the methods are not tested. Feedback and
contributions are welcome!

- Quick start
- CLI
- Help
- Authentication
- Dump
- Library
- Client
- Hub
- Devices
- Air purifiers
- Blinds
- Controllers
- Environment sensors
- Lights
- Light sensors
- Motion sensors
- Occupancy sensors
- Outlets
- Open/close sensors
- Repeaters
- Speakers
- Water sensors
- Device sets
- Rooms
- Scenes
- Music
- Users
- Update events
- Troubleshooting

Quick start

1. Execute npx dirigera authenticate in your terminal and follow the instructions.
2. Save the obtained access token.
3. [Optional] To get your device IDs, dump your Dirigera system's information as a JSON:
npx dirigera dump --access-token
4. Install the library as a dependency: npm i dirigera
5. Create a client instance in your code with the access token:

``typescript
import { createDirigeraClient } from 'dirigera'

const client = await createDirigeraClient({
accessToken: 'YOUR_ACCESS_TOKEN',
})
`

6. You are ready to control your devices!
`typescript
await client.lights.setIsOn({
id: 'YOUR_DEVICE_ID',
isOn: true,
})
`

CLI

$3

`bash
npx dirigera help [command]
`

$3

To be able to communicate with your DIRIGERA hub, you have to obtain an access token by pairing with it.

Use the following command to do this via the CLI:

`bash
npx dirigera authenticate
`

You'll be prompted to press the action button on the bottom of the gateway within 60 seconds. If the pairing is
successful, an access token will be printed on your console.

Store the access token in a secure place, and never share it with anyone outside your household!

$3

Use the following command to dump a JSON from your gateway. This can be useful for adding support of new devices to the
library or to debug issues that may arise from device or gateway firmware changes.

`bash
npx dirigera dump --access-token YOUR_ACCESS_TOKEN
`

Library

$3

You can rely on mDNS discovery to connect to the gateway without specifying an IP address.

`typescript
const client = await createDirigeraClient({
accessToken: 'YOUR_ACCESS_TOKEN',
})
`

Alternatively, if mDNS discovery fails, it's possible to explicitly set the IP address.

`typescript
const client = await createDirigeraClient({
gatewayIP: 'YOUR_GATEWAY_IP',
accessToken: 'YOUR_ACCESS_TOKEN',
})
`

If you want to authenticate without using the CLI, you can use the following method:

`typescript
const client = await createDirigeraClient()

const accessToken = await client.authenticate() // You have to press the action button on the gateway after this
`

To get every device, room, scene, etc. in a single object:

`typescript
const home = await client.home()
`

$3

`typescript
const hubStatus = await client.hub.status()

await client.hub.checkFirmwareUpdate()

await client.hub.installFirmwareUpdate()
`

$3

Generic device API.

`typescript
const devices = await client.devices.list()

const device = await client.devices.get({
id: 'YOUR_DEVICE_ID',
})

await client.devices.setCustomName({
id: 'YOUR_DEVICE_ID',
customName: 'A_CUSTOM_NAME',
})

// low level method to set attributes, use device type specific apis if possible
// some attributes may not be combined with each other and require separate setAttributes calls
await client.devices.setAttributes({
id: 'YOUR_DEVICE_ID',
attributes: {
// ...
},
transitionTime: 5000, // optional, in milliseconds
})

await client.devices.startIdentifying({
id: 'YOUR_DEVICE_ID',
})

await client.devices.stopIdentifying({
id: 'YOUR_DEVICE_ID',
})
`

#### Air purifiers

`typescript
const airPurifiers = await client.airPurifiers.list()

const airPurifier = await client.airPurifiers.get({
id: 'YOUR_DEVICE_ID',
})

await client.airPurifiers.setFanMode({
id: 'YOUR_DEVICE_ID',
fanMode: 'auto', // 'auto' | 'low' | 'medium' | 'high' | 'off'
})

await client.airPurifiers.setMotorState({
id: 'YOUR_DEVICE_ID',
motorState: 0, // between 0 and 50
})

await client.airPurifiers.setChildLock({
id: 'YOUR_DEVICE_ID',
childLock: true,
})

await client.airPurifiers.setStatusLight({
id: 'YOUR_DEVICE_ID',
statusLight: true,
})
`

#### Blinds

Not tested, feedback required.

`typescript
const blinds = await client.blinds.list()

const blind = await client.blinds.get({
id: 'YOUR_DEVICE_ID',
})

await client.blinds.setCurrentLevel({
id: 'YOUR_DEVICE_ID',
blindsCurrentLevel: 0,
})

await client.blinds.setTargetLevel({
id: 'YOUR_DEVICE_ID',
blindsTargetLevel: 60,
})

await client.blinds.setState({
id: 'YOUR_DEVICE_ID',
blindsState: 'stopped', // 'stopped' | 'up' | 'down'
})
`

#### Controllers

Some controllers, such as the BILRESA remote appear as multiple devices.

`typescript
const controllers = await client.controllers.list()

const controller = await client.controllers.get({
id: 'YOUR_DEVICE_ID',
})

// Set the control mode of a BILRESA remote.
// The scroll wheel version supports 'light' and 'speaker' modes, the dual button version supports all four modes.
await client.controllers.setControlMode({
id: 'YOUR_DEVICE_ID',
controlMode: 'light', // 'light' | 'speaker' | 'blind' | 'shortcut'
})
`

#### Environment sensors

Supports VINDSTYRKA, TIMMERFLOTTE and ALPSTUGA sensors. The available attributes vary between models.

The TIMMERFLOTTE sensor appears as two devices, one measures temperature, the other measures relative humidity.

`typescript
const environmentSensors = await client.environmentSensors.list()

const environmentSensor = await client.environmentSensors.get({
id: 'YOUR_DEVICE_ID',
})

const { currentTemperature, currentRH, currentPM25, vocIndex } =
environmentSensor.attributes

// The ALPSTUGA screen can be turned on and off
await client.devices.setAttributes({
id: 'YOUR_DEVICE_ID',
attributes: {
isOn: false,
},
})
`

#### Lights

`typescript
const lights = await client.lights.list()

const light = await client.lights.get({ id: 'YOUR_DEVICE_ID' })

await client.lights.setIsOn({
id: 'YOUR_DEVICE_ID',
isOn: true,
})

await client.lights.setLightLevel({
id: 'YOUR_DEVICE_ID',
lightLevel: 50, // between 1 and 100
transitionTime: 5000, // optional, in milliseconds
})

await client.lights.setLightColor({
id: 'YOUR_DEVICE_ID',
colorHue: 260, // between 0 and 359
colorSaturation: 0.8, // between 0 and 1
})

await client.lights.setLightTemperature({
id: 'YOUR_DEVICE_ID',
colorTemperature: 2700, // between colorTemperatureMax and colorTemperatureMin
})

await client.lights.setStartupOnOff({
id: 'YOUR_DEVICE_ID',
startupOnOff: 'startOn', // 'startOn' | 'startPrevious' | 'startToggle'
})
`

#### Light sensors

The VALLHORN motion sensor has a light sensor built-in.

`typescript
const lightSensors = await client.lightSensors.list()

const lightSensor = await client.lightSensors.get({
id: 'YOUR_DEVICE_ID',
})

const { illuminance } = lightSensor.attributes
`

#### Motion sensors

`typescript
const motionSensors = await client.motionSensors.list()

const motionSensor = await client.motionSensors.get({
id: 'YOUR_DEVICE_ID',
})

await client.motionSensors.setOnDuration({
id: 'YOUR_DEVICE_ID',
onDuration: 300, // in seconds, between 60 and 86400
})

await client.motionSensors.setScheduleOn({
id: 'YOUR_DEVICE_ID',
scheduleOn: true,
})

await client.motionSensors.setSchedule({
id: 'YOUR_DEVICE_ID',
schedule: {
onCondition: {
time: '22:00',
},
offCondition: {
time: '06:00',
},
},
})

await client.motionSensors.setSchedule({
id: 'YOUR_DEVICE_ID',
schedule: {
onCondition: {
time: 'sunset',
offset: 60, // in minutes
},
offCondition: {
time: 'sunrise',
offset: -60, // in minutes
},
},
})
`

#### Occupancy sensors

The MYGGSPRAY sensor introduced a new device type called occupancy sensor. It works the same way as motion sensors:

`typescript
const occupancySensors = await client.occupancySensors.list()

// For other available methods, see the motion sensors above.
`

#### Outlets

`typescript
const outlets = await client.outlets.list()

const outlet = await client.outlets.get({ id: 'YOUR_DEVICE_ID' })

await client.outlets.setIsOn({
id: 'YOUR_DEVICE_ID',
isOn: true,
})

await client.outlets.setStartupOnOff({
id: 'YOUR_DEVICE_ID',
startupOnOff: 'startOn', // 'startOn' | 'startPrevious' | 'startToggle'
})

await client.outlet.setStatusLight({
id: 'YOUR_DEVICE_ID',
statusLight: true, // true disables the status light, false enables it ¯\_(ツ)_/¯
})

await client.outlet.setChildLock({
id: 'YOUR_DEVICE_ID',
childLock: true,
})

await client.outlet.resetEnergyConsumption({
id: 'YOUR_DEVICE_ID',
})
`

#### Open/close sensors

`typescript
const openCloseSensors = await client.openCloseSensors.list()

const openCloseSensor = await client.openCloseSensors.get({
id: 'YOUR_DEVICE_ID',
})

const { isOpen, batteryPercentage } = openCloseSensor.attributes
`

#### Repeaters

`typescript
const repeaters = await client.repeaters.list()

const repeater = await client.repeaters.get({
id: 'YOUR_DEVICE_ID',
})
`

#### Speakers

`typescript
const speakers = await client.speakers.list()

const speaker = await client.speakers.get({
id: 'YOUR_DEVICE_ID',
})

await client.speakers.setVolume({
id: 'YOUR_DEVICE_ID',
volume: 20, // between 0 and 100
})

await client.speakers.setPlayback({
id: 'YOUR_DEVICE_ID',
playback: 'playbackPaused', // 'playbackPlaying' | 'playbackPaused' | 'playbackNext' | 'playbackPrevious'
})
`

#### Water sensors

`typescript
const waterSensors = await client.waterSensors.list()

const waterSensor = await client.waterSensors.get({
id: 'YOUR_DEVICE_ID',
})

const { waterLeakDetected, batteryPercentage } = waterSensor.attributes
`

$3

For a list of available icons check out DeviceSet.ts.

`typescript
const deviceSets = await client.deviceSets.list()

await client.deviceSets.setIsOn({
id: 'YOUR_DEVICE_SET_ID',
isOn: true,
})

const { id } = await client.deviceSets.create({
name: 'A_CUSTOM_NAME',
icon: 'lighting_chandelier',
})

await client.deviceSets.delete({
id: 'YOUR_DEVICE_SET_ID',
})

await client.deviceSets.update({
id: 'YOUR_DEVICE_SET_ID',
name: 'A_NEW_CUSTOM_NAME',
icon: 'lighting_cone_pendant',
})

await client.deviceSets.updateConfiguration({
id: 'YOUR_DEVICE_SET_ID',
deviceIds: ['YOUR_DEVICE_ID'],
roomId: 'YOUR_ROOM_ID', // optional
remoteLinkIds: ['YOUR_REMOTE_ID'], // optional
})

// some attributes may not be combined with each other and require separate setAttributes calls
await client.deviceSets.setAttributes({
id: 'YOUR_DEVICE_SET_ID',
attributes: {
// ...
},
transitionTime: 5000, // optional, in milliseconds
})
`

$3

For a list of available colors and icons check out Room.ts.

`typescript
const rooms = await client.rooms.list()

const room = await client.rooms.get({
id: 'YOUR_ROOM_ID',
})

const { id } = await client.rooms.create({
name: 'A_CUSTOM_NAME',
icon: 'rooms_arm_chair',
color: 'ikea_green_no_65',
})

await client.rooms.delete({
id: 'YOUR_ROOM_ID',
})

await client.rooms.update({
id: 'YOUR_ROOM_ID',
name: 'A_NEW_CUSTOM_NAME',
icon: 'rooms_bathtub',
color: 'ikea_yellow_no_24',
})

await client.rooms.moveDevices({
id: 'YOUR_ROOM_ID',
deviceIds: ['YOUR_DEVICE_ID'],
})

await client.rooms.setIsOn({
id: 'YOUR_ROOM_ID',
deviceType: 'outlet', // optional filter by device type
isOn: true,
})

// some attributes may not be combined with each other and require separate setAttributes calls
await client.rooms.setAttributes({
id: 'YOUR_ROOM_ID',
deviceType: 'light', // optional filter by device type
attributes: {
// ...
},
transitionTime: 5000, // optional
})
`

$3

Scenes are a very powerful way to set up automations. Scenes can be triggered by using the application, at a scheduled
time, at sunset/sunrise, by a button press on a shortcut controller or by a device event, such as an open/close sensor
being triggered. Scenes can optionally also be ended at a scheduled time, a duration after they are triggered or at
sunrise/sunset. The actions can set the attributes of devices or device sets, such as turning on a light.

For a list of available icons check out Scene.ts.

`typescript
const scenes = await client.scenes.list()

const scene = await client.scenes.get({
id: 'YOUR_SCENE_ID',
})

await client.scenes.trigger({
id: 'YOUR_SCENE_ID',
})

await client.scenes.undo({
id: 'YOUR_SCENE_ID',
})

// simple scene, triggerable from app
const { id } = await client.scenes.create({
info: {
name: 'A_CUSTOM_NAME',
icon: 'scenes_arrive_home',
},
type: 'userScene',
actions: [
{
type: 'device',
enabled: true,
deviceId: 'YOUR_DEVICE_ID',
attributes: {
// ...
},
},
],
})

// triggered and ended by time schedule
const { id: timeTriggerSceneId } = await client.scenes.create({
info: {
name: 'A_CUSTOM_NAME',
icon: 'scenes_arrive_home',
},
type: 'userScene',
triggers: [
{
type: 'time',
trigger: {
days: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'], // optional, defaults to every day
time: '8:00',
},
// optional
endTriggerEvent: {
type: 'time',
trigger: {
time: '20:00',
},
},
},
],
actions: [
{
type: 'device',
enabled: true,
deviceId: 'YOUR_DEVICE_ID',
attributes: {
// ...
},
},
],
})

await client.scenese.delete({
id: 'YOUR_SCENE_ID',
})

await client.scenes.update({
id: 'YOUR_SCENE_ID',
// ... all the fields from the create method
})
`

$3

`typescript
const music = await client.music.get()
`

$3

`typescript
const users = await client.users.list()

const currentUser = await client.users.getCurrentUser()

await client.users.setCurrentUserName({
name: 'NEW_NAME',
})

await client.users.delete({
id: 'YOUR_USER_ID',
})
`

$3

The gateway publishes events via a WebSocket. You can listen for these events with the following method:

`typescript
client.startListeningForUpdates(async (updateEvent) => {
console.log(JSON.stringify(updateEvent))
})
`

For a list of available event types, check out Event.ts.

Troubleshooting