Skip to content

TRÅDFRI Binding ​

This binding integrates the IKEA TRÅDFRI gateway and devices connected to it (such as dimmable LED bulbs). This binding only supports IKEA TRÅDFRI gateway v1.x, it is not compatible with DIRIGERA.

Supported Things ​

Besides the gateway (thing type "gateway"), the binding currently supports colored bulbs, dimmable warm white bulbs as well as white spectrum bulbs, control outlets and blinds. The binding also supports read-only data from remote controls and motion sensors (e.g. the battery status). The TRÅDFRI controller and sensor devices currently cannot be observed right away because they are communicating directly with the bulbs or lamps without routing their commands through the gateway. This makes it nearly impossible to trigger events for pressed buttons. We can only access some static data like the present status or battery level.

The Thing type ids are defined according to the lighting devices defined for Zigbee Light Link (see page 24, table 2). These are:

Device typeZigbee Device IDThing type
Dimmable Light0x01000100
Colour Temperature Light0x02200220
Extended Colour Light0x02100210
Occupancy Sensor0x01070107
Non-Colour Controller0x08200820
Non-Colour Scene Controller0x08300830
Control Outlet0x00100010

The following matrix lists the capabilities (channels) for each of the supported lighting device types:

Thing typeBrightnessColorColor TemperatureBattery LevelBattery LowPower
0010X
0100X
0220XX
0210XX
0107XX
0820XX
0830XX

The following things are also supported even though they are not standardized in Zigbee Light Link:

Device typeZigbee Device IDThing type
Window Covering Device0x02020202
Window Covering Controller0x02030203
Air Purifier0x00070007

The following matrix lists the capabilities (channels) for each of the supported non-lighting device types:

Thing typeBattery LevelBattery LowPositionFan ModeLock ButtonDisabled LEDAir QualityFan SpeedFilter CheckFilter Uptime
0202XXX
0203XX
0007XXXXXXX

Thing Configuration ​

For first pairing - the gateway requires a host parameter for the hostname or IP address and a code, which is the security code that is printed on the bottom of the gateway. Optionally, a port can be configured, but any standard gateway uses the default port 5684. The gateway requires at least firmware version 1.2.42 to connect to this binding.

The code is used during the initialization for retrieving unique identity and pre-shared key from the gateway and then it is discarded from the configuration. The newly created authentication data is stored in advanced parameters identity and preSharedKey. On each initialization if the code is present in the Thing configuration - the identity and preSharedKey are recreated and the code is again discarded.

The devices require only a single (integer) parameter, which is their instance id. Unfortunately, this is not displayed anywhere in the IKEA app, but it seems that they are sequentially numbered starting with 65537 for the first device. If in doubt, use the auto-discovered things to find out the correct instance ids.

Channels ​

The dimmable bulbs support the brightness channel. The white spectrum bulbs additionally also support the color_temperature channel.

Full color bulbs support the color_temperature and color channels. Brightness can be changed with the color channel.

The remote control and the motion sensor support the battery_level and battery_low channels for reading the battery status.

The control outlet supports the power channel.

A blind or curtain supports, besides the battery_level and battery_low channels, a position channel.

An air purifier supports:

  • fan_mode and fan_speed channels, which allows for control of the fan and reading of the current speed.
  • disable_led and lock_button channels, to respectively disable the LEDs and lock the button on the physical device.
  • air_quality_pm25 and air_quality_rating channels, which reads the particulate matter 2.5μm and corresponding indication of air quality (similar to Tradfri app rating).
  • filter_check_next and filter_check_alarm channels, which represents the remaining number of minutes until the next filter check and whether it is time to do the filter check now. Filter check must be completed through the TRÅDFRI app (or on the hardware buttons in case of replacement).
  • a filter_uptime channel, which represents the current time since last filter change.

Refer to the matrices above.

Channel Type IDItem TypeDescription
brightnessDimmerThe brightness of the bulb in percent
color_temperatureDimmerColor temperature from 0% = cold to 100% = warm
colorColorFull color
battery_levelNumberBattery level (in %)
battery_lowSwitchBattery low warning (<=10% = ON, >10% = OFF)
powerSwitchPower switch
positionRollershutterPosition of the blinds from 0% = open to 100% = closed
fan_modeNumberFan mode, target speed of the fan (0 = off, 1 = auto, 10..50 = Level 1 to 5)
fan_speedNumberCurrent Fan Speed between 0 (off) and 50 (maximum speed)
disable_ledSwitchDisables the LEDs on the device
lock_buttonSwitchDisables the physical button on the device (applications can still make changes)
air_quality_pm25Number:DimensionlessDensity of Particulate Matter of 2.5μm, measured in ppm
air_quality_ratingNumberGives an air quality rating (1 = Good, 2 = OK, 3 = Bad), similar to the TRÅDFRI app
filter_check_nextNumber:TimeTime in minutes before the next filter check if > 0, if < 0 you are late checking the filter
filter_check_alarmSwitchWhen ON, you must perform a filter check (i.e. filter_check_next is < 0)
filter_uptimeNumber:TimeTime elapsed since the last filter change, in minutes

Full Example ​

demo.things:

dsl
Bridge tradfri:gateway:mygateway [ host="192.168.0.177", code="EHPW5rIJKyXFgjH3" ] {
    0100 myDimmableBulb "My Dimmable Bulb" [ id=65537 ]
    0220 myColorTempBulb "My Color Temp Bulb" [ id=65538 ]
    0210 myColorBulb "My Color Bulb" [ id=65539 ]
    0830 myRemoteControl "My Remote Control" [ id=65545 ]
    0010 myControlOutlet "My Control Outlet" [ id=65542 ]
    0202 myBlinds "My Blinds" [ id=65547 ]
    0007 myAirPurifier "My Air Purifier" [ id=65548 ]
}

demo.items:

dsl
Dimmer Light1 { channel="tradfri:0100:mygateway:myDimmableBulb:brightness" }
Dimmer Light2_Brightness { channel="tradfri:0220:mygateway:myColorTempBulb:brightness" }
Dimmer Light2_ColorTemperature { channel="tradfri:0220:mygateway:myColorTempBulb:color_temperature" }
Color ColorLight { channel="tradfri:0210:mygateway:myColorBulb:color" }
Number RemoteControlBatteryLevel { channel="tradfri:0830:mygateway:myRemoteControl:battery_level" }
Switch RemoteControlBatteryLow { channel="tradfri:0830:mygateway:myRemoteControl:battery_low" }
Switch ControlOutlet { channel="tradfri:0010:mygateway:myControlOutlet:power" }
Rollershutter BlindPosition { channel="tradfri:0202:mygateway:myBlinds:position" }
Number AirPurifierFanMode { channel="tradfri:0007:mygateway:myAirPurifier:fan_mode" }
Number AirPurifierFanSpeed { channel="tradfri:0007:mygateway:myAirPurifier:fan_speed" }
Switch AirPurifierDisableLED { channel="tradfri:0007:mygateway:myAirPurifier:disable_led" }
Switch AirPurifierLockPhysicalButton { channel="tradfri:0007:mygateway:myAirPurifier:lock_button" }
Number AirPurifierQualityPM25 { channel="tradfri:0007:mygateway:myAirPurifier:air_quality_pm25" }
Number AirPurifierQualityRating { channel="tradfri:0007:mygateway:myAirPurifier:air_quality_rating" }
Number AirPurifierFilterCheckTTL { channel="tradfri:0007:mygateway:myAirPurifier:filter_check_next" }
Switch AirPurifierFilterCheckAlarm { channel="tradfri:0007:mygateway:myAirPurifier:filter_check_alarm" }
Number AirPurifierFilterUptime { channel="tradfri:0007:mygateway:myAirPurifier:filter_uptime" }

demo.sitemap:

dsl
sitemap demo label="Main Menu"
{
    Frame {
        Slider item=Light1 label="Light1 Brightness [%.1f %%]"
        Slider item=Light2_Brightness label="Light2 Brightness [%.1f %%]"
        Slider item=Light2_ColorTemperature label="Light2 Color Temperature [%.1f %%]"
        Colorpicker item=ColorLight label="Color"
        Text item=RemoteControlBatteryLevel label="Battery Level [%d %%]"
        Switch item=RemoteControlBatteryLow label="Battery Low Warning"
        Switch item=ControlOutlet label="Power Switch"
        Switch item=BlindPosition label="Blind Position [%d]"
        Selection item=AirPurifierFanMode label="Fan Mode"
        Text item=AirPurifierFanSpeed label="Current Fan Speed [%d]"
        Switch item=AirPurifierDisableLED label="Disable LEDs"
        Switch item=AirPurifierLockPhysicalButton label="Disable Physical Buttons"
        Text item=AirPurifierQualityPM25 label="PM2.5"
        Text item=AirPurifierQualityRating label="Air Quality"
        Text item=AirPurifierFilterCheckTTL label="TTL before next filter check [%d min]"
        Text item=AirPurifierFilterCheckAlarm label="Need to Check Filter [%s]"
        Text item=AirPurifierFilterUptime label="Current filter uptime [%d min]"
    }
}