IKEA controllers - dresden-elektronik/deconz-rest-plugin GitHub Wiki
This page provides info on the IKEA controllers. Make no mistake: the IKEA motion "sensors" aren't sensors; they actually are controllers.
Overview
The following table lists the known controllers (in order of product code, which more or less matches the order in which they were introduced):
| Device | Model | Product | Firmware | Profile | Notes |
|---|---|---|---|---|---|
| Dimmer | TRADFRI wireless dimmer |
ICTC-G-1 | 0x11c2 | ZB3* | Discontinued |
| Remote | TRADFRI remote control |
E1524 | 0x11c1 | ZB3* | Discontinued |
| Motion sensor | TRADFRI motion sensor |
E1525 | 0x11c4 | ZLL | Discontinued |
| Dimmer | TRADFRI on/off switch |
E1743 | 0x11c5 | ZB3 | |
| Symfonisk | SYMFONISK Sound Controller |
E1744 | 0x11ca | ZB3 | |
| Motion sensor | TRADFRI motion sensor |
E1745 | 0x11c8 | ZB3 | |
| Open/Close remote | TRADFRI open/close remote |
E1766 | 0x11c5 | ZB3 | |
| Remote | TRADFRI remote control |
E1810 | 0x11c1 | ZB3 | |
| Shortcut button | TRADFRI SHORTCUT Button |
E1812 | 0x11c6 | ZB3 | |
| Knycklan | KNYCKLAN Open/Close remote |
E1841 | 0x11c9 | ZB3 | Not yet supported |
| Stryrbar | Remote Control N2 |
E2001 | 0x11cb | ZB3 |
*) With the latest firmware; originally released as ZLL.
Generic Information
Reset and Pairing
All controllers have a reset button, but it might be hidden in the battery compartment. All controllers have a status LED, but it might be hidden on the back or inside of the device.
Press the reset button four times in quick succession (i.e. within a second or so), to factory-reset the controller and make it available for regular pairing. The status LED will fade in and out when the reset was successful. While the LED is fading, the controller should pair with deCONZ without any issue. Note that the TRADFRI hub doesn't support regular pairing.
Hold the reset button for 10 seconds for touchlink pairing. Unlike devices from other vendors, IKEA controllers will remain the the network they've currently joined on touchlink pairing. They share the network details with the router being touchlink paired. This is how you add routers to the TRADFRI hub.
Zigbee Contollers
Zigbee controllers are devices that control other Zigbee devices, by sending commands to them. The communicate directly with the devices being controlled, and work even when the gateway or hub is down. They are great from a reliability perspective, but limited in functionality to the commands that the controller send. While professional-grade controllers allow these commands to be configured, the commands sent by the IKEA controllers are hardcoded in the controller firmware. Typically, the controller carries a client (grey) cluster, to match the server (blue) cluster on the device being controlled.
The best practice is to bind the client cluster to a group, and add that group the lights you want to control.
Where needed, the deCONZ gateway will create the group and setup this binding, when pairing the controller (except for the Symfonisk).
The group is exposed as config.group on the /sensors resource.
With this setup, there's no need for touchline-pairing.
Also, the REST API can be used to add or remove lights to or from the group.
Note that Phoscon doesn't support this and actually hides these (initially empty) groups.
The deCONZ gateway eavesdrops on the commands the controller sends to the group, and maps these to button events, and updates state.buttonevent (or state.presence for the motion sensors).
This way the controllers can also be used to trigger rules on the gateway, or automations by an API client.
It is possible to use direct control and automations at the same time, but you need to make sure that these are consistent.
E.g. don't trigger an automation to turn off the lights on a buttonevent mapped from an On command.
Note that Phoscon actually creates gateway rules when setting up switches and sensors.
Binding of Client Clusters
As far as I can tell, there's different behaviours:
- The newer ZB3 controllers (Symfonisk, shortcut button, and Strybar) send commands by unicast to the coordinator by default. When a client cluster is bound to a group, they instead send commands by broadcast to that group. However, when the Power Configuration cluster is bound to the coordinator, they send commands by broadcast to the group as well as by unicast to the coordinator.
- The other ZB3 controllers send commands by broadcast to all devices by default. When a client cluster is bound to a group, they instead send commands by broadcast to that group.
- The (now discontinued) ZLL contollers pick a random group on reset, and send broadcast commands to that group. No need for binding the client clusters.
For 1) and 2), only one of the client clusters actually needs to be bound to the group. The other client clusters follow suit.
The old dimmer and Symfonisk can generate a lot of traffic, potentially flooding the network when bound to a group. Consequently, the API plugin doesn't setup a group for these controller. The wireless dimmer doesn't even seem to support binding a client cluster to a group.
Battery
The Styrbar uses two AAA batteries. The motion sensors use two CR2032 cells, but they're wired in parallel. The sensors seem to work fine with just one battery installed. The other controllers use a single CR2032 cell. IKEA offers the cheapest CR2032 replacement batteries, by far: the PLATTBOJ at EUR 1.29 for 8 pieces.
All controllers support reporting the battery through the Battery Percentage Remaining attribute of the Power Configuration cluster. However, they deviate from the Zigbee standard, and report the value in full percentage, instead of half percentage. So a report value of 100 means 100%, instead of 50%.
The Power Configuration cluster needs to be bound to the coordinator, and the reporting for Battery Percentage Remaining needs to be setup. The deCONZ gateway does this on pairing the controllers.
IKEA-Specific Scenes
The remotes and the Strybar send manufacturer-specific Scenes commands on the Left and Right buttons. These commands are understood only by IKEA WS (white spectrum) and CWS (colour white spectrum) lights. So when used to control lights directly, only these lights react to the Left and Right buttons.
The IKEA WS and CWS lights needs to be in a specific configuration for the special Scenes commands to be honoured.
Unfortunately, we haven't figured this out in full.
I seems that the deCONZ gateway somehow breaks this configuration when pairing the lights, maybe because it adds them to the group for /groups/0?
The latest CWS bulb (the Extended Color Light) that came with my Styrbar still reacts to the _Left and Right buttons, even after pairing it to deCONZ.
Effectively, this means that the Left and Right buttons are only usable in automations.
Motion Sensors
As mentioned before, the motion "sensors" are actually controllers, sending an On with Timed Off command directly to the devices being controlled. This command causes the lights to turn off automatically, after the specified delay, without any further communication from the controller. The dial on the E1525 configures the delay between one and ten minutes; on the E1745 the delay is hard coded to three minutes. Because the E1745 expects the controlled lights to remain on for three minutes, it won't send another command within ~2.5 minutes.
The gateway acts on the On with Timed Off command by setting state.presence to true and by populating config.delay and state.dark from the command parameters (On Time and Accept Only When On).
Note that the sensor needs to be in Night mode, or state.dark will always be set to true.
The gateways resets state.presence to false automatically, after config.delay seconds, so that state.presence matches state.on of the controlled lights.
Unfortunately, the API also exposes config.duration for these motion sensors.
Worse, it defaults config.duration to 60, overriding the config.delay logic.
With this setting, and standard automation to turn lights off when state.presence becomes false, you will be left in the dark, as the E1745 won't send the next command for another 1.5 minutes.
I strongly suggest to set config.duration to 0 to make the gateway use config.delay instead.
Device-Specific Information
ICTC-G-1
The old wireless dimmer is exposed as a ZHASwitch resource.
It should be exposed as a ZHARelativeRotary, once we'll support that sensor type.
The sensor sends _Move to Level on an abrupt turn (to turn on or off the lights), and Move / Stop on a gentle turn (to dim the lights).
This was one of the first IKEA devices supported. At that time, we modelled it after the Hue dimmer switch, with four buttons: On, DimUp, DimDown, and Off.
| Button | Action | Buttonevent | Command | Parameters |
|---|---|---|---|---|
| Dial | Turn right | 1002 | Move to Level with On/Off | 255 |
| Dial | Turn right | 2002 | Move with On/Off | Up |
| Dial | Turn right | Stop with OnOff | ||
| Dial | Turn left | 3002 | Move | Down |
| Dial | Turn left | Stop with OnOff | ||
| Dial | Turn left | 4002 | Move to Level with On/Off | 0 |
Today, we would expose this as two buttons: Turn Right (clockwise) and Turn Left (counter clockwise), cf. the Symfonisk.
| Button | Action | Buttonevent | Command | Parameters |
|---|---|---|---|---|
| Dial | Turn right | 1002 | Move to Level with On/Off | 255 |
| Dial | Turn right | 1001 | Move with On/Off | Up |
| Dial | Turn right | 1003 | Stop with OnOff | |
| Dial | Turn left | 2002 | Move | Down |
| Dial | Turn left | 2001 | Stop with OnOff | |
| Dial | Turn left | 2003 | Move to Level with On/Off | 0 |
The gateway sets mode to 4 (Dimmer) for the wireless dimmer.
The new mappings are available under mode 1 (Scenes).
Unfortunately, the ZHASwitch mode cannot be updated through the API; you need to patch the database to change this.