search

moroen / IKEA-Tradfri-plugin

A Python plugin for Domoticz to controll IKEA Gateway
68 stars 23 forks source link

readme

A Domoticz plugin for IKEA Trådfri (Tradfri) gateway

Supported IKEA Devices

The plugin supports and is able to controll the following devices:

The plugin doesn't work with:

Compatible hardware

Most systems capable of running domoticz and has a version of python3 available should be able to run the plugin. There are special instructions for:

Software requirements:

  1. Python version 3.5.3 or higher, 3.7.x recommended.
  2. Domoticz compiled with support for Python-Plugins.
  3. Upgraded pip and setuptools

Local Installation

This is the instructions for *nix based systems and Windows. There are special instructions for installing on a Raspberry PI or Synology. For instructions on installing the plugin these systems, please see the readme for Raspberry or Synology.

1. Clone IKEA-tradfri plugin into domoticz plugins-directory:

$ cd domoticz/plugins/
$ git clone https://github.com/moroen/IKEA-Tradfri-plugin.git IKEA-Tradfri

2. Update pip and setuptools:

  $ pip3 install -U pip
  $ pip3 install -U setuptools

3. Install tradfricoap

The plugin uses the tradfricoap python module (PyPi) 

  $ pip3 install -U tradfricoap

If upgrading from version 0.9.13 or lower, remove the tradfri directory after upgradring the plugin to version 0.9.14 or higher. If the plugin fails to load tradfricoap, check the common errors page in the wiki.

3.1 Installing an API for coap requests

Tradfricoap supports two different COAP-transports for communicating with the IKEA Tradfri gateway. The py3coap module is the default, recommended transport on linux and MacOS, coapcmd is recommended for Windows and Synology NAS. Using py3coap on Windows is possible, but requires python3 compiled with the mingw gcc toolchain, and will not work with the official python distributions on windows.

On systems with a working GO compiler, but without the needed libraries for creating python3 modules (like a Synology NAS), a command line utility - coapcmd (https://github.com/moroen/coapcmd) - can be used. For systems without a working go compiler, prebuild binaries are available in the repository on github.com.

3.1a py3coap (recommended)

Py3coap is available as precompiled wheels for linux (amd64) and MacOS. On other systems, and for installing on a Raspberry PI (PI readme), a go compiler (version 1.11 or greater recommended) and the python3 development libraries must be installed before installing via pip3 and requirements.txt.

  $ pip3 install py3coap
Alternative installation of py3coap

On some systems, installing py3coap using pip fails. Installing py3coap manually might help, or at least give some more information on why installation fails.

$ git clone https://github.com/moroen/pycoap.git
$ cd pycoap
$ sudo -H python3 setup.py install

3.1b coapcmd (alternative)

The coapcmd command must be installed as IKEA-Tradfri/bin/coapcmd and the plugin configured to use coapcmd for COAP-requests. On systems with git and go installed, coapcmd can be installed with the provided install-script:

$ bash install_coapcmd.sh

Configure the plugin to use coapcmd:

$ python3 plugin.py config api coapcmd

For systems without a working git and/or go compiler, please refer to the repository for coapcmd (https://github.com/moroen/coapcmd) for alternative install options and prebuilt binaries for common architectures. To use a prebuild binary, download the correct file from https://github.com/moroen/coapcmd/releases, rename it to coapcmd (coapcmd.exe on windows) and place it in the bin directory of the plugin (domoticz/plugins/IKEA-Tradfri/bin).

Switching between APIs:

$ python3 plugin.py config api py3coap # Use py3coap module
$ python3 plugin.py config api coapcmd # Use coapcmd

4. Configure Tradfri COAP:

  $ python3 plugin.py config gw IP KEY

5. Check communication with the gateway:

  $ python3 plugin.py list

For other command line commands, refer to help

  $ python3 plugin.py --help

6. Restart domoticz and enable IKEA-Tradfri from the hardware page

Check installed version

To find the current version of the plugin and modules:

  $ cd domoticz/plugins/IKEA-Tradfri
  $ python3 plugin.py version

Updating plugin

To update the plugin to the newest version, stop domoticz, enter the plugin directory, pull the latest changes from git and restart domoticz:

  $ cd domoticz/plugins/IKEA-Tradfri
  $ git pull

It's usually recommended to upgrade to the latest version of tradfricoap and py3coap as well:

  $ sudo -H pip3 install -U tradfricoap py3coap

Usage

Lights and devices have to be added to the gateway as per IKEA's instructions, using the official IKEA-tradfri app.

Observing changes

To observe changes to buld or socket when switched using another method than domoticz, enable "Observe changes" and specify a poll interval in seconds. As long an intervall as possible is recommended. The mininum poll intervall is 10 seconds, and the intervall should be a multiple of 10 seconds. Using a too short interval tends to freeze the gateway, requiring cycling the power of the gateway to restore communication. A polling interval of 300 seconds or greater seems to be fine and reduce the occurence of freezes.

A note about colors

When using a CWS (color) bulb, a CWS color selector device is created. Due to a known limitation when setting levels in Domoticz scenes, it's only possible to specify the first half of the available colors in a scene. Selecting a color from the last half, gives the color for level 100 (lime) when the scene is activated. A workaround for this is planned, but currently not implemented.

Curtains

Domoticz sets the position of a curtain as a percentage between 0 (fully open) to 100 (fully closed). You need to set the maximum posistion of the curtain before using Domoticz. Please refer to the instructions from IKEA on how to set the maximum position of a curtain.