deCONZ


deCONZ by Dresden Elektronik is a software that communicates with Conbee/Raspbee Zigbee gateways and exposes Zigbee devices that are connected to the gateway.

deCONZ REST API.

Recommended way of running deCONZ

Use community container by Marthoc for your deCONZ needs. It works both as a standalone container as well as with HASS.io.

Supported devices

See deCONZ wiki for a list of supported devices.

Configuration

Home Assistant will automatically discover deCONZ presence on your network, if discovery: is present in your configuration.yaml file.

If you don’t have the API key, you can generate an API key for deCONZ by using the one-click functionality similar to Philips Hue. Go to Menu -> Settings -> Unlock Gateway in deCONZ and then use the deCONZ configurator in Home Assistant frontend to create an API key. When you’re done setting up deCONZ it will be stored as a config entry.

You can add the following to your configuration.yaml file if you are not using the discovery: component:

# Example configuration.yaml entry
deconz:
  host: IP_ADDRESS

Configuration Variables

host

(string)(Optional)The IP address of your deCONZ web server.

api_key

(string)(Optional)The API key to access your deCONZ web server.

port

(int)(Optional)Configure port deCONZ web server is accessible from.

Default value: 80

A full configuration could look like this:

# Example configuration.yaml entry
deconz:
  host: 127.0.0.1
  api_key: 0123456789
  port: 80

Debugging component

If you have problems with deCONZ or the component you can add debug prints to the log.

logger:
  default: info
  logs:
    pydeconz: debug
    homeassistant.components.deconz: debug

Device services

Available services: configure.

Service deconz.configure

Set attribute of device in Deconz using Rest API.

Service data attribute Optional Description
field No String representing a specific device in deCONZ.
entity No String representing a specific HASS entity of a device in deCONZ.
data No Data is a JSON object with what data you want to alter.

Field and entity are exclusive, i.e you can only use one in a request.

{ “field”: “/lights/1”, “data”: {“name”: “light2”} }

{ “entity”: “light.light1”, “data”: {“name”: “light2”} }

{ “field”: “/config”, “data”: {“permitjoin”: 60} }

Remote control devices

Remote controls (ZHASwitch category) will be not be exposed as a regular entity, but as events named ‘deconz_event’ with a payload of ‘id’ and ‘event’. Id will be the device name from deCONZ and Event will be the momentary state of the switch. However, a sensor entity will be created that shows the battery level of the switch as reported by deCONZ, named sensor.device_name_battery_level.

Typical values for switches, the event codes are 4 numbers where the first and last number are of interest here.

Switch code Description
1XXX Button #1 up to #8
XXX1 Button hold
XXX2 Button short release
XXX3 Button long release

Where for example on a Philips Hue Dimmer, 2001 would be holding the dim up button.

For the IKEA Tradfri remote, 1 is the middle button, 2 is up, 3 is down, 4 is left, and 5 is right.

Examples

Step up and step down input number with wireless dimmer

YAML

automation:
  - alias: 'Toggle lamp from dimmer'
    initial_state: 'on'
    trigger:
      platform: event
      event_type: deconz_event
      event_data:
        id: remote_control_1
        event: 1002
    action:
      service: light.toggle
      entity_id: light.lamp

  - alias: 'Increase brightness of lamp from dimmer'
    initial_state: 'on'
    trigger:
      platform: event
      event_type: deconz_event
      event_data:
        id: remote_control_1
        event: 2002
    action:
      - service: light.turn_on
        data_template:
          entity_id: light.lamp
          brightness: >
            {% set bri = states.light.lamp.attributes.brightness | int %}
            {{ [bri+30, 249] | min }}

  - alias: 'Decrease brightness of lamp from dimmer'
    initial_state: 'on'
    trigger:
      platform: event
      event_type: deconz_event
      event_data:
        id: remote_control_1
        event: 3002
    action:
      - service: light.turn_on
        data_template:
          entity_id: light.lamp
          brightness: >
            {% set bri = states.light.lamp.attributes.brightness | int %}
            {{ [bri-30, 0] | max }}

Appdaemon

remote_control_living_room:
  module: remote_control
  class: RemoteControl
  event: deconz_event
  id: dimmer_switch_3
import appdaemon.plugins.hass.hassapi as hass

class RemoteControl(hass.Hass):

    def initialize(self):
        if 'event' in self.args:
            self.listen_event(self.handle_event, self.args['event'])

    def handle_event(self, event_name, data, kwargs):
        if data['id'] == self.args['id']:
            self.log(data['event'])
            if data['event'] == 1002:
                self.log('Button on')
            elif data['event'] == 2002:
                self.log('Button dim up')
            elif data['event'] == 3002:
                self.log('Button dim down')
            elif data['event'] == 4002:
                self.log('Button off')