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 <YOUR_ACCESS_TOKEN>

4. Install the library as a dependency: npm i dirigera

5. Create a client instance in your code with the access token:

   import { createDirigeraClient } from 'dirigera'
   
   const client = await createDirigeraClient({
     accessToken: 'YOUR_ACCESS_TOKEN',
   })
   

6. You are ready to control your devices!

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

CLI

Help

npx dirigera help [command]

Authentication

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:

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!

Dump

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.

npx dirigera dump --access-token YOUR_ACCESS_TOKEN

Library

Client

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

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

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

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:

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:

const home = await client.home()

Hub

const hubStatus = await client.hub.status()

await client.hub.checkFirmwareUpdate()

await client.hub.installFirmwareUpdate()

Devices

Generic device API.

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

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.

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.

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.

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

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.

const lightSensors = await client.lightSensors.list()

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

const { illuminance } = lightSensor.attributes

Motion sensors

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:

const occupancySensors = await client.occupancySensors.list()

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

Outlets

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

const openCloseSensors = await client.openCloseSenso