Foreword
This tutorial is for openHAB3. If you are on openHAB2 you will need to use my older tutorial .
We have an Ikea Tradfri e14 400lm dimmable bulb.
Here is how I integrated into openHAB, via zigbee2mqtt and Mosquitto .
This tutorial was written with openHAB3 running on a headless Raspberry Pi 3B with Raspberry Pi OS, with SSH access.
Overview
This tutorial assumes you have openHAB3 installed.
This tutorial will show you how to:
- Install an MQTT broker, install the MQTT binding, and connect the two
- Setup bulb with
zigbee2mqtt - Configure openHAB3 to âconnectâ to the bulb
- Configure openHAB3 to control the bulb
Method
1. Install an MQTT broker, install the MQTT binding, and connect the two
In order to use MQTT devices, the following is required:
- An MQTT broker installed
- MQTT Binding installed in openHAB
- MQTT Bridge Thing configured in openHAB
Follow the steps in this tutorial to achieve the above three goals.
2. Setup bulb with zigbee2mqtt
It is assumed that you already have zigbee2mqtt installed and running.
Pair the device with zigbee2mqtt as described here. Ensure that you are able to pair devices by setting permit_join to true in configuration.yaml (usually in /opt/zigbee2mqtt/data)
Once paired, adjust the zigbee2mqtt configuration.yaml (usually in /opt/zigbee2mqtt/data) to:
- Give the paired device a friendly name
- Turn on the experimental attribute output, which means zigbee2mqtt will send plain strings, rather than JSON strings .
Here is my configuration.yaml - your device ID is likely to be different. I have given my device the friendly name bPorchLight :
homeassistant: false
permit_join: true
mqtt:
base_topic: zigbee2mqtt
server: 'mqtt://localhost'
serial:
port: /dev/ttyACM0
disable_led: false
advanced:
log_level: error
availability_timeout: 5
devices:
'0x086bd7fffe210efc':
friendly_name: bPorchLight
experimental:
output: attribute
3. Configure openHAB3 to âconnectâ to the bulb
To control the bulb, we need to configure a Generic MQTT Thing
- Settings -> Things -> Blue + -> MQTT Binding -> Generic MQTT Thing
Enter the initial configuration information:
- Unique ID: You can leave this default, or provide a more convenient ID. Once created, the ID cannot be changed.
- Label: Friendly name for your device
- Location: Physical location of your device
- Bridge: Select your Bridge Thing to your MQTT Broker
In Show advanced:
-
Availability Topic:
zigbee2mqtt/<FRIENDLYNAME>/availability- Adjust to use your friendly name
-
Device Available Payload:
online -
Device Unavailable Payload:
offline
Click Create Thing. Your Generic MQTT Thing will be created and appear in your list of Things. After a couple of seconds, it will appear as ONLINE (assuming your bulb is connected to zigbee2mqtt, and zigbee2mqtt is connected to your MQTT Broker).
4. Configure openHAB3 to control the bulb
To control the bulb we will need to create
- Thing Channels
- Items
4.1 Thing Channels
Channels enable us to capture data from the bulb, and send commands to the bulb. We will create 2 Channels:
- Power: bulb on/off
- Dimmer: bulb dimming
4.1.1 Power: bulb on/off
Click the Channels tab in your Generic MQTT Thing, followed by Add Channel.
Configure the Channel:
- Channel Identifier: Channel ID used internally by openHAB. No spaces allowed.
- Label: Friendly name for the Channel. Spaces allowed.
- Channel type: On/Off Switch
Continue the configuration of the Channel:
-
MQTT State Topic: Assuming default
zigbee2mqttsetup, the State Topic will bezigbee2mqtt/<FRIENDLYNAME>/state. -
MQTT Command Topic: Assuming default
zigbee2mqttsetup, the State Topic will bezigbee2mqtt/<FRIENDLYNAME>/set. -
Custom On/Open Value:
ON -
Custom Off/Closed Value:
OFF
Click Create. The Channel will appear in the Channels tab of your Generic MQTT Thing.
4.1.2 Dimmer: bulb dimming
Click the Channels tab in your Generic MQTT Thing, followed by Add Channel. Configure the Channel:
- Channel Identifier: Channel ID used internally by openHAB. No spaces allowed.
- Label: Friendly name for the Channel. Spaces allowed.
- Channel type: Percentage Value
-
MQTT State Topic: Assuming default
zigbee2mqttsetup, the State Topic will bezigbee2mqtt/<FRIENDLYNAME>/brightness. -
MQTT Command Topic: Assuming default
zigbee2mqttsetup, the State Topic will bezigbee2mqtt/<FRIENDLYNAME>/set/brightness. -
Absolute Minimum:
0 -
Absolute Maximum:
255
4.1.3 YAML code
Below is the YAML code for the complete Thing with its Channels.
UID: mqtt:topic:MosquittoMqttBroker:bPorchLight
label: Porch Light
thingTypeUID: mqtt:topic
configuration:
payloadNotAvailable: offline
availabilityTopic: zigbee2mqtt/bPorchLight/availability
payloadAvailable: online
bridgeUID: mqtt:broker:MosquittoMqttBroker
location: Porch
channels:
- id: power
channelTypeUID: mqtt:switch
label: Power
description: ""
configuration:
commandTopic: zigbee2mqtt/bPorchLight/set
stateTopic: zigbee2mqtt/bPorchLight/state
off: OFF
on: ON
- id: dimmer
channelTypeUID: mqtt:dimmer
label: Dimmer
description: ""
configuration:
commandTopic: zigbee2mqtt/bPorchLight/set/brightness
min: 0
stateTopic: zigbee2mqtt/bPorchLight/brightness
max: 255
4.2 Items
We will create an Equipment group which will contain the Channels via respective Items.
Click Add Equipment to Model from within the Channels tab.
Configuration will depend on how your Model is setup:
- Parent Group: Choose a Group from your Model to suit
-
Category:
lightbulb -
Semantic Class:
Lightbulb
Continue configuration by selecting the Power and Dimmer Channels:
-
Category:
lightbulb -
Semantic Class:
switchforPowerandcontrolforDimmer
Click Add to Model.
We have to make one small adjustment to the Item created for the Dimmer Channel:
Items -> PorchLight_Dimmer -> Add Metadata -> State Description
-
Min:
0 -
Max:
100
Click Save top-right.
From the Equipment tab you can now control the bulb!
4.2.1 JSON Code
The following is the JSON for the Items and Links, queried from the API Explorer
Items
{
"members": [
{
"stateDescription": {
"minimum": 0,
"maximum": 100,
"step": 1,
"pattern": "%s %%",
"readOnly": false,
"options": []
},
"type": "Dimmer",
"name": "PorchLight_Dimmer",
"label": "Dimmer",
"category": "lightbulb",
"tags": [
"Control"
],
"groupNames": [
"PorchLight"
]
},
{
"stateDescription": {
"pattern": "%s",
"readOnly": false,
"options": []
},
"type": "Switch",
"name": "PorchLight_Power",
"label": "Power",
"category": "lightbulb",
"tags": [
"Switch"
],
"groupNames": [
"PorchLight"
]
}
],
"editable": true,
"type": "Group",
"name": "PorchLight",
"label": "Porch Light",
"category": "lightbulb",
"tags": [
"Lightbulb"
],
"groupNames": []
}
Links
{
"channelUID": "mqtt:topic:MosquittoMqttBroker:bPorchLight:power",
"configuration": {},
"itemName": "PorchLight_Power"
}
{
"channelUID": "mqtt:topic:MosquittoMqttBroker:bPorchLight:dimmer",
"configuration": {},
"itemName": "PorchLight_Dimmer"
}