1.1.1

* Update how_to_secure_network.md

Make clear that the key consists of 16 hex values and gave an example how to generate a key with command line tools.

* Clarified info about network key notation

* clarified network key notation (dec or hex)

* Update how_to_secure_network.md

Make clear that the key consists of 16 hex values and gave an example how to generate a key with command line tools.

* Remove trailing comma. #916

.eslintignore

@@ -1,2 +1 @@
-node_modules/*
-support/*
+node_modules/*

.eslintrc.json

@@ -1,17 +1,21 @@
 {
     "env": {
+        "mocha": true,
+        "es6": true,
         "node": true
     },
     "extends": ["eslint:recommended", "google"],
     "parserOptions": {
-        "ecmaFeatures": {
-            "experimentalObjectRestSpread": true
-        },
+        "ecmaVersion": 2018,
         "sourceType": "module"
     },
     "rules": {
         "require-jsdoc": "off",
         "indent": ["error", 4],
-        "max-len": ["error", { "code": 120 }]
-    }
+        "max-len": ["error", { "code": 120 }],
+        "mocha/no-exclusive-tests": "error"
+    },
+    "plugins": [
+        "mocha"
+    ]
 }

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,16 @@
+Did you read the FAQ?
+https://koenkk.github.io/zigbee2mqtt/information/FAQ.md
+
+Unsupported device?
+https://koenkk.github.io/zigbee2mqtt/how_tos/how_to_support_new_devices.html
+
+A question?
+Read the documentation: https://koenkk.github.io/zigbee2mqtt/
+
+Bug report:
+- First make sure your on the latest version of zigbee2mqtt.
+- Make sure you are running the latest CC253X firmware from https://github.com/koenkk/z-stack-firmware.
+- Provide a clear description of the problem.
+- If applicable, provide steps how to reproduce the problem.
+- Provide a log with `log_level` set to `debug`, see https://koenkk.github.io/zigbee2mqtt/configuration/configuration.html
+- DON'T copy logs directly here, post a link to https://hastebin.com/ or https://pastebin.com/.

.github/stale.yml

@@ -2,10 +2,6 @@
 daysUntilStale: 60
 # Number of days of inactivity before a stale issue is closed
 daysUntilClose: 7
-# Issues with these labels will never be considered stale
-exemptLabels:
-  - enhancement
-  - bug
 # Label to use when marking an issue as stale
 staleLabel: stale
 # Comment to post when marking an issue as stale. Set to `false` to disable

.gitignore

@@ -60,4 +60,7 @@ typings/
 # data
 data/database.db
 data/config.json
-data/log*.txt
+data/log*.txt
+data/state.json
+data/log
+data-backup/

.travis.yml

@@ -6,18 +6,23 @@ services:
   - docker
 
 node_js:
-  - "8"
+  - "10"
+
+before_install:
+  - "echo '{\"experimental\": true}' | sudo tee /etc/docker/daemon.json"
+  - sudo apt update -y
+  - sudo apt install --only-upgrade docker-ce -y
+  - sudo service docker restart
 
 install:
   - npm install
 
-script:
-  - npm run verify-homeassistant-mapping
+before_script:
+  - npm test
   - npm run eslint
 
-after_success:
+script:
   - ".travis/docker.sh"
-  - ".travis/wiki.sh"
   - ".travis/trigger-downstream.sh"
 
 env:

.travis/docker.sh

@@ -10,22 +10,22 @@ tag_push() {
 }
 
 build_and_push() {
-  docker build --build-arg COMMIT=$(git rev-parse --short HEAD) -t $DOCKER_USERNAME/zigbee2mqtt:$1 -f $2 .
+  docker build --platform=$3 --build-arg COMMIT=$(git rev-parse --short HEAD) -t $DOCKER_USERNAME/zigbee2mqtt:$1 -f $2 .
   docker push $DOCKER_USERNAME/zigbee2mqtt:$1
 }
 
 # Only update Docker images for:
 # - dev branch
 # - version release
-if [ "$TRAVIS_PULL_REQUEST" = "false" ] && [ ! -z ${TRAVIS_TAG+x} ]
+if [ "$TRAVIS_PULL_REQUEST" = "false" ] && [ ! -z ${TRAVIS_TAG+x} ] && [ ! "$TRAVIS_TAG" = "" ]
 then
   echo "Updating docker images for master branch!"
   login
 
   # Push versioned images
-  build_and_push "$TRAVIS_TAG" docker/Dockerfile.amd64
-  build_and_push "$TRAVIS_TAG-arm32v6" docker/Dockerfile.arm32v6
-  build_and_push "$TRAVIS_TAG-arm64v8" docker/Dockerfile.arm64v8
+  build_and_push "$TRAVIS_TAG" docker/Dockerfile.amd64 amd64
+  build_and_push "$TRAVIS_TAG-arm32v6" docker/Dockerfile.arm32v6 arm
+  build_and_push "$TRAVIS_TAG-arm64v8" docker/Dockerfile.arm64v8 arm64
 
   # Push latest images.
   tag_push "$TRAVIS_TAG-arm32v6" "arm32v6"
@@ -35,9 +35,9 @@ elif [ "$TRAVIS_BRANCH" = "dev" -a "$TRAVIS_PULL_REQUEST" = "false" ]
 then
   echo "Updating docker images for dev branch!"
   login
-  build_and_push latest-dev docker/Dockerfile.amd64
-  build_and_push arm32v6-dev docker/Dockerfile.arm32v6
-  build_and_push arm64v8-dev docker/Dockerfile.arm64v8
+  build_and_push latest-dev docker/Dockerfile.amd64 amd64
+  build_and_push arm32v6-dev docker/Dockerfile.arm32v6 arm
+  build_and_push arm64v8-dev docker/Dockerfile.arm64v8 arm64
 else
   echo "Not updating docker images, triggered by pull request or not on master/dev branch"
 fi

.travis/trigger-downstream.sh

@@ -20,11 +20,11 @@ function travis_trigger() {
           "https://api.travis-ci.org/repo/${org}%2F${repo}/requests"
 }
 
-# Only trigger downstream if on master branch and not pull request
-if [ "$TRAVIS_BRANCH" = "master" -a "$TRAVIS_PULL_REQUEST" = "false" ]
+# Only trigger downstream if on dev branch and not pull request
+if [ "$TRAVIS_BRANCH" = "dev" -a "$TRAVIS_PULL_REQUEST" = "false" ]
 then
   echo "Triggering build of downstream projects!"
   travis_trigger "danielwelch" "hassio-zigbee2mqtt" "master"
 else
-  echo "Not triggering build of downstream projects, triggered by pull request or not on master branch"
+  echo "Not triggering build of downstream projects, triggered by pull request or not on dev branch"
 fi

.travis/wiki.sh

@@ -1,28 +0,0 @@
-#!/bin/sh -e
-
-setup_git() {
-  git config --global user.email "travis@travis-ci.org"
-  git config --global user.name "Travis CI"
-}
-
-update_wiki() {
-  rm -rf zigbee2mqtt.wiki
-  git clone https://${GH_TOKEN}@github.com/Koenkk/zigbee2mqtt.wiki.git
-  npm run docgen zigbee2mqtt.wiki
-  cd zigbee2mqtt.wiki
-  git add -A
-  git diff-index --quiet HEAD || git commit -m "Travis CI: update wiki"
-  git push origin
-  cd ..
-  rm -rf zigbee2mqtt.wiki
-}
-
-# Only update wiki if on master branch and not pull request
-if [ "$TRAVIS_BRANCH" = "master" -a "$TRAVIS_PULL_REQUEST" = "false" ]
-then
-  echo "Updating wiki!"
-  setup_git
-  update_wiki
-else
-  echo "Not updating wiki, triggered by pull request or not on master branch"
-fi

README.md

@@ -1,44 +1,60 @@
-[![Travis](https://img.shields.io/travis/Koenkk/zigbee2mqtt.svg)](https://api.travis-ci.org/Koenkk/zigbee2mqtt.svg)
+<div align="center">
+    <a href="https://github.com/koenkk/zigbee2mqtt">
+        <img width="150" height="150" src="images/logo.png">
+    </a>
+    <br>
+    <br>
+    <div style="display: flex;">
+        <a href="https://travis-ci.org/Koenkk/zigbee2mqtt/">
+            <img src="https://img.shields.io/travis/Koenkk/zigbee2mqtt.svg">
+        </a>
+        <a href="https://github.com/Koenkk/zigbee2mqtt/releases">
+            <img src="https://img.shields.io/github/release/koenkk/zigbee2mqtt.svg">
+        </a>
+        <a href="https://github.com/Koenkk/zigbee2mqtt/stargazers">
+            <img src="https://img.shields.io/github/stars/koenkk/zigbee2mqtt.svg">
+        </a>
+        <a href="https://www.paypal.me/koenkk">
+            <img src="https://img.shields.io/badge/donate-PayPal-blue.svg">
+        </a>
+    </div>
+    <h1>Zigbee2mqtt  🌉 🐝</h1>
+    <p>
+        Allows you to use your Zigbee devices <b>without</b> the vendors bridge or gateway.
+    </p>
+    <p>
+        It bridges events and allows you to control your Zigbee devices via MQTT. In this way you can integrate your Zigbee devices with whatever smart home infrastructure you are using.
+    </p>
+</div>
 
-# zigbee2mqtt :bridge_at_night: :honeybee:
-![Thumbs up or down?](header.png)
-<img align="right" height="40px" src="https://user-images.githubusercontent.com/7738048/40915536-1993dd32-6805-11e8-9f22-4dfca52133c0.png">
+## [Getting started](https://koenkk.github.io/zigbee2mqtt/#getting-started)
+The [documentation](https://koenkk.github.io/zigbee2mqtt/) provides you all the information needed to get up and running! Make sure you don't skip sections if this is your first visit, as there might be important details in there for you.
 
-Allows you to use your Zigbee devices **without** the vendors (Xiaomi/TRADFRI/Hue) bridge or gateway.
+If you aren't familiar with **Zigbee** terminology make sure you [read this](https://koenkk.github.io/zigbee2mqtt/information/zigbee_network.html) to help you out.
 
-It bridges events and allows you to control your Zigbee devices via MQTT. In this way you can integrate your Zigbee devices with whatever smart home infrastructure you are using. 
-
-## [Getting started](https://github.com/Koenkk/zigbee2mqtt/wiki/Getting-started)
-The [wiki](https://github.com/Koenkk/zigbee2mqtt/wiki) provides you all the information needed to get up and running! Make sure you don't skip sections if this is your first visit, as there might be important details in there for you.
-
-[The documentation](https://github.com/Koenkk/zigbee2mqtt/wiki) will provide information on how to prepare, configure and start **zigbee2mqtt**, but also on how to customize the setup to fit your needs. 
-
-If you aren't familiar with **zigbee** terminology make sure you [read this](https://github.com/Koenkk/zigbee2mqtt/wiki/ZigBee-network) to help you out.
-
-## Integrations
+## [Integrations](https://koenkk.github.io/zigbee2mqtt/#integration)
 Zigbee2mqtt integrates well with (almost) every home automation solution because it uses MQTT. However the following integrations are worth mentioning:
 
 <img align="left" height="100px" width="100px" src="https://user-images.githubusercontent.com/7738048/40914297-49e6e560-6800-11e8-8904-36cce896e5a8.png">
 
 ### [Home Assistant](https://www.home-assistant.io/)
 - [Hassio](https://www.home-assistant.io/hassio/): Using [the official addon](https://github.com/danielwelch/hassio-zigbee2mqtt) from [danielwelch](https://github.com/danielwelch)
-- Generic install or Hassbian: Using instructions [here](https://github.com/Koenkk/zigbee2mqtt/wiki/Integrating-with-Home-Assistant)
+- Generic install or Hassbian: Using instructions [here](https://koenkk.github.io/zigbee2mqtt/integration/home_assistant.html)
 
-## Architecture 
-![Architecture](architecture.png)
+<img align="left" height="100px" width="100px" src="https://user-images.githubusercontent.com/2734836/47615848-b8dd8700-dabd-11e8-9d77-175002dd8987.png">
+
+### [Domoticz](https://www.domoticz.com/)
+- Integration implemented in [domoticz-zigbee2mqtt-plugin](https://github.com/stas-demydiuk/domoticz-zigbee2mqtt-plugin)
+
+<br>
+
+## Architecture
+![Architecture](images/architecture.png)
 
 ## Supported devices
-See [Supported devices](https://github.com/Koenkk/zigbee2mqtt/wiki/Supported-devices) to check whether your device is supported. There is quite an extensive list, including devices from vendors like Xiaomi, Ikea, Philips, OSRAM and more. 
+See [Supported devices](https://koenkk.github.io/zigbee2mqtt/information/supported_devices.html) to check whether your device is supported. There is quite an extensive list, including devices from vendors like Xiaomi, Ikea, Philips, OSRAM and more.
 
-If it's not listed in [Supported devices](https://github.com/Koenkk/zigbee2mqtt/wiki/Supported-devices), support can be added (fairly) easy, see [How to support new devices](https://github.com/Koenkk/zigbee2mqtt/wiki/How-to-support-new-devices).
+If it's not listed in [Supported devices](https://koenkk.github.io/zigbee2mqtt/information/supported_devices.html), support can be added (fairly) easy, see [How to support new devices](https://koenkk.github.io/zigbee2mqtt/how_tos/how_to_support_new_devices.html).
 
 ## Support & help
-If you need assistance you can check [opened issues](https://github.com/Koenkk/zigbee2mqtt/issues). Feel free to help with Pull Requests when you were able to fix things or add new devices or just share the love on social media. 
-
-## Contributors
-* [AndrewLinden](https://github.com/AndrewLinden)
-* [oskarn97](https://github.com/oskarn97)
-* [dgomes](https://github.com/dgomes)
-* [Koenkk](https://github.com/Koenk)
-* [kirovilya](https://github.com/kirovilya)
-* [ciotlosm](https://github.com/ciotlosm)
+If you need assistance you can check [opened issues](https://github.com/Koenkk/zigbee2mqtt/issues). Feel free to help with Pull Requests when you were able to fix things or add new devices or just share the love on social media.

docgen/docgen.js

@@ -0,0 +1,10 @@
+const fs = require('fs');
+const path = require('path');
+
+const base = path.join(__dirname, '..', 'docs');
+
+const supportDevices = require('./supported-devices');
+const integratingWithHomeassistant = require('./integrating-with-homeassistant');
+
+fs.writeFileSync(path.join(base, 'information', 'supported_devices.md'), supportDevices);
+fs.writeFileSync(path.join(base, 'integration', 'home_assistant.md'), integratingWithHomeassistant);

docgen/integrating-with-homeassistant.js

@@ -0,0 +1,299 @@
+/**
+ * This script generates the integrating-with-homeassistant page.
+ */
+
+const devices = require('zigbee-shepherd-converters').devices;
+const HomeassistantExtension = require('../lib/extension/homeassistant');
+const homeassistant = new HomeassistantExtension(null, null, null, null);
+const YAML = require('json2yaml');
+
+let template = `# Home Assistant
+
+*NOTE 1: This file has been generated, do not edit this file manually!*
+
+*NOTE 2: If you are using the [Zigbee2mqtt Hass.io add-on](https://github.com/danielwelch/hassio-zigbee2mqtt)
+use their documentation*
+
+
+## MQTT discovery
+**At least Home Assistant >= 0.84 is required!**
+
+**NOTE:** Groups are not auto-discovered, see configuration below.
+
+The easiest way to integrate Zigbee2mqtt with Home Assistant is by
+using [MQTT discovery](https://www.home-assistant.io/docs/mqtt/discovery/).
+This allows Zigbee2mqtt to automatically add devices to Home Assistant.
+
+To achieve the best possible integration (including MQTT discovery):
+- In your **Zigbee2mqtt** \`configuration.yaml\` set \`homeassistant: true\`
+- In your **Home Assistant** \`configuration.yaml\`:
+\`\`\`yaml
+mqtt:
+  discovery: true
+  broker: [YOUR MQTT BROKER]  # Remove if you want to use builtin-in MQTT broker
+  birth_message:
+    topic: 'hass/status'
+    payload: 'online'
+  will_message:
+    topic: 'hass/status'
+    payload: 'offline'
+\`\`\`
+
+Mind you that if you want to use the embedded broker of Home Assistant you
+have to [follow this guide](https://www.home-assistant.io/docs/mqtt/broker#embedded-broker).
+
+Zigbee2mqtt is expecting Home Assistant to send it's birth/will
+messages to \`hass/status\`. Be sure to add this to your \`configuration.yaml\` if you want
+Zigbee2mqtt to resend the cached values when Home Assistant restarts
+
+## Home Assistant device registry
+When using Home Assistant MQTT discovery, Zigbee2mqtt integrates
+with the [Home Assistant device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html).
+This allows you to change the Home Assistant \`device_id\` and \`friendly_name\` from the web interface
+without having to restart Home Assistant. It also makes it possible to show which entities belong to which device.
+
+![Changing name and device ID via web interface](../images/home_assistant_change_name.png)
+
+![Device registry](../images/home_assistant_device_registry.png)
+
+## I'm confused about the different device IDs, names and friendly names
+- Home Assistant \`device_id\`: determined on first discovery of the device, can only be changed
+via the Home Assistant web interface afterwards. Used to control/read the state from the device (e.g. in automations)
+- Zigbee2mqtt \`friendly_name\`: used to change the MQTT topic where the device listens and publishes to.
+- Home Assistant \`name\`: name shown in the Home Assistant UI (unless overridden
+via a \`friendly_name\` in \`customize.yaml\`). If not changed via the Home Assistant web interface,
+it is equal to the Zigbee2mqtt \`friendly_name\`. Is updated if the Zigbee2mqtt \`friendly_name\` changes
+(requires restart of Home Assistant)
+- Home Assistant \`friendly_name\` (\`customize.yaml\`): overrides the name in the Home Assistant web interface.
+
+## Responding to button clicks
+To respond to button clicks (e.g. WXKG01LM) you can use the following Home Assistant configuration:
+
+{% raw %}
+\`\`\`yaml
+automation:
+  - alias: Respond to button clicks
+    trigger:
+      platform: mqtt
+      topic: 'zigbee2mqtt/<FRIENDLY_NAME'
+    condition:
+      condition: template
+      value_template: '{{ "single" == trigger.payload_json.click }}'
+    action:
+      entity_id: light.bedroom
+      service: light.toggle
+\`\`\`
+{% endraw %}
+
+## Groups
+Groups are not auto-discovered. Use the following configuration:
+
+{% raw %}
+
+\`\`\`yaml
+- platform: mqtt
+  schema: json
+  name: MY_GROUP
+  command_topic: "zigbee2mqtt/[GROUP_FRIENDLY_NAME]/set"
+  state_topic: "zigbee2mqtt/[GROUP_FRIENDLY_NAME]/set"
+
+  // Modify according to features supported by all devices in group
+  color_temp: true
+  brightness: true
+  rgb: true
+\`\`\`
+
+{% endraw %}
+
+## Controlling Zigbee2mqtt via Home Assistant
+The following Home Assistant configuration allows you to control Zigbee2mqtt from Home Assistant.
+
+{% raw %}
+\`\`\`yaml
+# Group
+group:
+  zigbee_group:
+    view: false
+    control: hidden
+    name: Zigbee2mqtt
+    entities:
+      - input_boolean.zigbee_permit_join
+      - timer.zigbee_permit_join
+      - sensor.zigbee2mqtt_bridge_state
+      - switch.zigbee2mqtt_main_join
+      - automation.enable_zigbee_joining
+      - automation.disable_zigbee_joining
+      - automation.disable_zigbee_joining_by_timer
+      - input_select.zigbee2mqtt_log_level
+      - automation.zigbee2mqtt_log_level
+
+# Input select for Zigbee2mqtt debug level
+input_select:
+  zigbee2mqtt_log_level:
+    name: Zigbee2mqtt Log Level
+    options:
+     - debug
+     - info
+     - warn
+     - error
+    initial: info
+    icon: mdi:format-list-bulleted
+
+# Input boolean for enabling/disabling joining
+input_boolean:
+  zigbee_permit_join:
+    name: Allow devices to join
+    initial: off
+    icon: mdi:cellphone-wireless
+
+# Timer for joining time remaining (120 sec = 2 min)
+timer:
+  zigbee_permit_join:
+    name: Time remaining
+    duration: 120
+
+# Sensor for monitoring the bridge state
+sensor:
+  - platform: mqtt
+    name: Zigbee2mqtt Bridge state
+    state_topic: "zigbee2mqtt/bridge/state"
+    icon: mdi:router-wireless
+
+# Switch for enabling joining
+switch:
+  - platform: mqtt
+    name: "Zigbee2mqtt Main join"
+    state_topic: "zigbee2mqtt/bridge/config/permit_join"
+    command_topic: "zigbee2mqtt/bridge/config/permit_join"
+    payload_on: "true"
+    payload_off: "false"
+
+# Automations
+automation:
+  - alias: Zigbee2mqtt Log Level
+    initial_state: 'on'
+    trigger:
+      - platform: state
+        entity_id: input_select.zigbee2mqtt_log_level
+        to: debug
+      - platform: state
+        entity_id: input_select.zigbee2mqtt_log_level
+        to: warn
+      - platform: state
+        entity_id: input_select.zigbee2mqtt_log_level
+        to: error
+      - platform: state
+        entity_id: input_select.zigbee2mqtt_log_level
+        to: info
+    action:
+      - service: mqtt.publish
+        data:
+          payload_template: '{{ states(''input_select.zigbee2mqtt_log_level'') }}'
+          topic: zigbee2mqtt/bridge/config/log_level
+
+  - id: enable_zigbee_join
+    alias: Enable Zigbee joining
+    hide_entity: true
+    trigger:
+      platform: state
+      entity_id: input_boolean.zigbee_permit_join
+      to: 'on'
+    action:
+    - service: mqtt.publish
+      data:
+        topic: zigbee2mqtt/bridge/config/permit_join
+        payload: 'true'
+    - service: timer.start
+      data:
+        entity_id: timer.zigbee_permit_join
+
+  - id: disable_zigbee_join
+    alias: Disable Zigbee joining
+    hide_entity: true
+    trigger:
+    - entity_id: input_boolean.zigbee_permit_join
+      platform: state
+      to: 'off'
+    action:
+    - data:
+        payload: 'false'
+        topic: zigbee2mqtt/bridge/config/permit_join
+      service: mqtt.publish
+    - data:
+        entity_id: timer.zigbee_permit_join
+      service: timer.cancel
+
+  - id: disable_zigbee_join_timer
+    alias: Disable Zigbee joining by timer
+    hide_entity: true
+    trigger:
+    - platform: event
+      event_type: timer.finished
+      event_data:
+        entity_id: timer.zigbee_permit_join
+    action:
+    - service: mqtt.publish
+      data:
+        topic: zigbee2mqtt/bridge/config/permit_join
+        payload: 'false'
+    - service: input_boolean.turn_off
+      data:
+        entity_id: input_boolean.zigbee_permit_join
+\`\`\`
+{% endraw %}
+
+## Configuration when NOT using Home Assistant MQTT discovery
+
+[CONFIGURATION]
+`;
+
+const homeassistantConfig = (device) => {
+    const payload = {
+        platform: 'mqtt',
+        state_topic: 'zigbee2mqtt/<FRIENDLY_NAME>',
+        availability_topic: 'zigbee2mqtt/bridge/state',
+        ...device.discovery_payload,
+    };
+
+    if (payload.command_topic) {
+        if (payload.command_topic_prefix) {
+            payload.command_topic = `zigbee2mqtt/<FRIENDLY_NAME>/${payload.command_topic_prefix}/set`;
+        } else {
+            payload.command_topic = `zigbee2mqtt/<FRIENDLY_NAME>/set`;
+        }
+    }
+
+    delete payload.command_topic_prefix;
+
+    let yml = YAML.stringify([payload]);
+    yml = yml.replace(/(-) \n {4}/g, '- ');
+    yml = yml.replace('---', `${device.type}:`);
+    return yml;
+};
+
+let configuration = '';
+devices.forEach((device) => {
+    configuration += `### ${device.model}\n`;
+    configuration += `{% raw %}\n`;
+    configuration += '```yaml\n';
+
+    const configurations = homeassistant._getMapping()[device.model];
+
+    if (configurations) {
+        configurations.forEach((d, i) => {
+            configuration += homeassistantConfig(d);
+            if (configurations.length > 1 && i < configurations.length - 1) {
+                configuration += '\n';
+            }
+        });
+
+        configuration += '```\n';
+        configuration += '{% endraw %}\n\n';
+    }
+});
+
+
+// Insert into template
+template = template.replace('[CONFIGURATION]', configuration);
+
+module.exports = template;

docgen/supported-devices.js

@@ -0,0 +1,55 @@
+/**
+ * This script generates the supported devices page.
+ */
+
+const devices = require('zigbee-shepherd-converters').devices;
+const replaceByDash = [new RegExp('/', 'g'), new RegExp(':', 'g'), new RegExp(' ', 'g')];
+const imageBase = '../images/devices/';
+
+function onlyUnique(value, index, self) {
+    return self.indexOf(value) === index;
+}
+
+const vendorsCount = devices.map((d) => d.vendor).filter(onlyUnique).length;
+
+let template = `# Supported devices
+
+*NOTE: This file has been generated, do not edit this file manually!*
+
+Currently **${devices.length}** devices are supported from **${vendorsCount}** different vendors.
+
+In case you own a Zigbee device which is **NOT** listed here, please see
+[How to support new devices](https://koenkk.github.io/zigbee2mqtt/how_tos/how_to_support_new_devices.html).
+
+[DEVICES]
+`;
+
+const generateTable = (devices) => {
+    let text = '';
+    text += '| Model | Description | Picture |\n';
+    text += '| ------------- | ------------- | -------------------------- |\n';
+    devices = new Map(devices.map((d) => [d.model, d]));
+    devices.forEach((d) => {
+        let image = d.model;
+        replaceByDash.forEach((r) => image = image.replace(r, '-'));
+        image = imageBase + `${image}.jpg`;
+        text += `| ${d.model} | ${d.vendor} ${d.description} (${d.supports}) | ![${image}](${image}) |\n`;
+    });
+
+    return text;
+};
+
+// Generated devices text
+let devicesText = '';
+const vendors = Array.from(new Set(devices.map((d) => d.vendor)));
+vendors.sort();
+vendors.forEach((vendor) => {
+    devicesText += `### ${vendor}\n\n`;
+    devicesText += generateTable(devices.filter((d) => d.vendor === vendor));
+    devicesText += '\n';
+});
+
+// Insert into template
+template = template.replace('[DEVICES]', devicesText);
+
+module.exports = template;

docker/Dockerfile.amd64

@@ -1,4 +1,4 @@
-FROM alpine:3.7
+FROM alpine:3.8
 
 # Copy files
 ADD . /app
@@ -12,7 +12,7 @@ ARG COMMIT
 RUN echo "{\"hash\": \"$COMMIT\"}" > .hash.json
 
 # Install dependencies
-RUN apk add --update --no-cache make gcc g++ python linux-headers udev nodejs git && \
+RUN apk add --update --no-cache make gcc g++ python linux-headers udev nodejs npm git && \
     npm install --unsafe-perm && \
     apk del make gcc g++ python linux-headers udev git
 

docker/Dockerfile.arm32v6

@@ -1,4 +1,4 @@
-FROM arm32v6/alpine:3.7
+FROM arm32v6/alpine:3.8
 
 # Setup cross-build
 ENV QEMU_EXECVE 1
@@ -14,7 +14,7 @@ ADD . /app
 RUN [ "qemu-arm-static", "/bin/sh", "-c", \
       "cp /app/data/configuration.yaml /app && \
        cp /app/docker/run.sh /app && chmod +x /app/run.sh && \
-       apk add --update --no-cache make gcc g++ python linux-headers udev nodejs git && \
+       apk add --update --no-cache make gcc g++ python linux-headers udev nodejs npm git && \
        npm install --unsafe-perm && \
        apk del make gcc g++ python linux-headers udev git"]
 

docker/Dockerfile.arm64v8

@@ -1,4 +1,4 @@
-FROM arm64v8/alpine:3.7
+FROM arm64v8/alpine:3.8
 
 # Setup cross-build
 ENV QEMU_EXECVE 1
@@ -14,7 +14,7 @@ ADD . /app
 RUN [ "qemu-aarch64-static", "/bin/sh", "-c", \
       "cp /app/data/configuration.yaml /app && \
        cp /app/docker/run.sh /app && chmod +x /app/run.sh && \
-       apk add --update --no-cache make gcc g++ python linux-headers udev nodejs git && \
+       apk add --update --no-cache make gcc g++ python linux-headers udev nodejs npm git && \
        npm install --unsafe-perm && \
        apk del make gcc g++ python linux-headers udev git"]
 

docs/_config.yml

@@ -0,0 +1 @@
+theme: jekyll-theme-cayman

docs/configuration/configuration.md

@@ -0,0 +1,67 @@
+# Configuration
+The following configuration options are available in `data/configuration.yaml`.
+
+The values shown are the default ones.
+
+```yaml
+# Required: Home Assistant integration (MQTT discovery)
+homeassistant: false
+
+# Required: allow new devices to join.
+# WARNING: Disable this after all devices have been paired!
+permit_join: true
+
+# Required: MQTT settings
+mqtt:
+  # Required: MQTT base topic for zigbee2mqtt MQTT messages
+  base_topic: zigbee2mqtt
+  # Required: MQTT server URL
+  server: 'mqtt://localhost:1883'
+  # Optional: MQTT server authentication user
+  user: my_user
+  # Optional: MQTT server authentication password
+  password: my_password
+  # Optional: MQTT client ID
+  client_id: 'MY_CLIENT_ID'
+  # Disable self-signed SSL certificates
+  reject_unauthorized: true
+  # Optional: Include device information to mqtt messages (default: false)
+  include_device_information: true
+
+# Required: serial settings
+serial:
+  # Required: location of CC2531 USB sniffer
+  port: /dev/tty.usbmodem1411
+  # Optional: disable LED of CC2531 USB sniffer
+  disable_led: false
+
+# Optional: advanced settings
+advanced:
+  # Optional: ZigBee pan ID
+  pan_id: 0x1a62
+  # Optional: ZigBee channel
+  channel: 11
+  # Optional: state caching
+  # https://github.com/Koenkk/zigbee2mqtt/commit/9396bde1f3b022e0f634487d1a37d2a5127c8cb3#diff-f68567477d803b49930337bf7fe1556bR16
+  cache_state: true
+  # Optional: Logging level, options: debug, info, warn, error
+  log_level: info
+  # Optional: Location of log directory
+  log_directory: data/log/%TIMESTAMP%
+  # Optional: Baudrate for serial port
+  baudrate: 115200
+  # Optional: RTS / CTS Hardware Flow Control for serial port
+  rtscts: true
+  # Optional: soft reset ZNP after timeout (in seconds); 0 is disabled
+  soft_reset_timeout: 0
+  # Optional: network encryption key, changing requires repairing of all devices.
+  network_key: [1, 3, 5, 7, 9, 11, 13, 15, 0, 2, 4, 6, 8, 10, 12, 13],
+  # Optional: Add a last_seen attribute to MQTT messages, contains date/time of last Zigbee message
+  # possible values are: disable (default), ISO_8601, epoch
+  last_seen: 'disable'
+  # Optional: Add an elapsed attribute to MQTT messages, contains milliseconds since the previous msg
+  elapsed: false
+  # Availability timeout in seconds, disabled by default (0).
+  # When enabled, devices will be checked if they are still online.
+  availability_timeout: 0,
+```

docs/configuration/device_specific_configuration.md

@@ -0,0 +1,32 @@
+# Device specific configuration
+The `configuration.yaml` allows to set device specific configuration. The following options are available.
+
+### All devices
+* `friendly_name`: Used in the MQTT topic of a device. By default this is the device ID (e.g. `0x00128d0001d9e1d2`).
+* `retain`: Retain MQTT messages of this device.
+* `qos`: QoS level for MQTT messages of this device. [What is QoS?](https://www.npmjs.com/package/mqtt#about-qos)
+
+### Device type specific
+* `occupancy_timeout`: Timeout (in seconds) after the `occupancy: false` message is sent, only available for occupany sensors. If not set, the timeout is `90` seconds. When set to `0` no `occupancy: false` is send.
+* `temperature_precision`: Controls the precision of `temperature` values, e.g. `0`, `1` or `2`; default `2`.
+* `humidity_precision`: Controls the precision of `humidity` values, e.g. `0`, `1` or `2`; default `2`.
+* `pressure_precision`: Controls the precision of `pressure` values, e.g. `0` or `1`; default `1`.
+
+### Example
+``` yaml
+devices:
+  '0x00158d0001d82999':
+    friendly_name: 'my_occupancy_sensor'
+    retain: true
+    occupancy_timeout: 20
+    qos: 1
+```
+
+### Changing device type specific defaults
+The default values used for the device specific configuration can be overriden via e.g.:
+
+```yaml
+device_options:
+  occupancy_timeout: 30
+  temperature_precision: 1
+```

docs/getting_started/flashing_the_cc2531.md

@@ -0,0 +1,46 @@
+# Flashing the firmware on the CC2531 USB stick
+The CC2531 USB stick needs to be flashed with a custom firmware.
+
+*NOTE: The following instructions assume you have a CC Debugger. In case you don't, see [Alternative firmware flashing methods](../information/alternative_flashing_methods.md).*
+
+## Windows
+1. Install [SmartRF Flash programmer](http://www.ti.com/tool/FLASH-PROGRAMMER) (**NOT V2**). This software is free but requires a Texas Instruments account in order to download.
+2. Install the [CC debugger driver](http://www.ti.com/general/docs/lit/getliterature.tsp?baseLiteratureNumber=swrc212&fileType=zip) on your PC (Windows only). Before continuing, verify that the CC Debugger driver has been installed correctly. See [Figure 1. Verify Correct Driver Installation @ Chapter 5.1](http://www.ti.com/lit/ug/swru197h/swru197h.pdf). In case the CC Debugger is not recognized correctly [install the driver manually](https://www.youtube.com/watch?v=jyKrxxXOvQY).
+2. Connect `CC debugger --> Downloader cable CC2531 --> CC2531 USB sniffer`.
+3. Connect **BOTH** the `CC2531 USB sniffer` and the `CC debugger` to your PC using USB.
+3. If the light on the CC debugger is RED press set reset button on the CC debugger. The light on the CC debugger should now turn GREEN. If not use [CC debugger user guide](http://www.ti.com/lit/ug/swru197h/swru197h.pdf) to troubleshoot your problem.
+
+![How to connect](../images/connected.jpg)
+4. Download the firmware [CC2531ZNP-Prod.hex](https://github.com/Koenkk/Z-Stack-firmware/tree/master/coordinator/CC2531/bin)
+5. Start SmartRF Flash Programmer, setup as shown below and press `Perform actions`.
+![SmartRF Flash Programmer](../images/smartrf.png)
+
+## Linux or MacOS
+Credits to [@Frans-Willem](https://github.com/frans-Willem) for majority of instructions.
+
+1. Install prerequisites for [CC-Tool](https://github.com/dashesy/cc-tool) using a package manager (e.g. [Homebrew](https://brew.sh/) for macOS)
+* Ubuntu: dh-autoreconf, libusb-1.0, libboost-all-dev
+* Fedora: dh-autoreconf, boost-devel, libusb1-devel
+* Archlinux: dh-autoreconf, libusb, boost
+* macOS: brew install autoconf automake libusb boost pkgconfig libtool
+
+2. Build cc-tool
+```bash
+git clone https://github.com/dashesy/cc-tool.git
+cd cc-tool
+./bootstrap
+./configure
+make
+```
+3. Connect `CC debugger --> Downloader cable CC2531 --> CC2531 USB sniffer`.
+4. Connect **BOTH** the `CC2531 USB sniffer` and the `CC debugger` to your PC using USB.
+5. If the light on the CC debugger is RED, press the Reset button on the CC debugger. The light on the CC debugger should now turn GREEN. If not, follow the [CC debugger user guide](http://www.ti.com/lit/ug/swru197h/swru197h.pdf) to troubleshoot your problem.
+![How to connect](../images/connected.jpg)
+6. Download the firmware [CC2531ZNP-Prod.hex](https://github.com/Koenkk/Z-Stack-firmware/tree/master/coordinator/CC2531/bin).
+7. Flash your firmware:
+```
+sudo ./cc-tool -e -w CC2531ZNP-Prod.hex
+```
+
+# What's next?
+[Running Zigbee2mqtt](running_zigbee2mqtt.md)

docs/getting_started/pairing_devices.md

@@ -0,0 +1,99 @@
+**IMPORTANT:** Before you start, make sure that `permit_join: true` is set in your `configuration.yaml`. Otherwise new devices cannot join the network!
+It's equally important that `permit_join: false` is set in your `configuration.yaml` after initial setup is done to keep your Zigbee network safe and to avoid accidental joining of other Zigbee devices.
+
+Start by checking if your Zigbee device is supported, see  [Supported devices](../information/supported_devices.md).
+
+Once you see something similar to `New device with address 0x00159d00016da0c8 connected!` in the log your device is paired.
+
+## Xiaomi
+Different devices require different pairing methods. In case you get an `Error [ERR_UNHANDLED_ERROR]: Unhandled error. (Cannot get the Node Descriptor of the Device: 0x00158d0001720111)` you should try a different pairing method. See [Supported devices](../information/supported_devices.md) to figure out if your device is MiJia or Aqara.
+* Most MiJia devices: press and hold the reset button on the device for +- 5 seconds (until the blue light starts blinking). **IMPORTANT**: Release and start pressing the reset button every second. This keeps the device awake, otherwise pairing will **fail!**.
+* Most Aqara devices: press and hold reset button on the device for +- 5 seconds until the blue light blinks three times, release the reset button (the blue light will blink once more) and wait.
+* Most Aqara wall switches: press and hold the button on the device for +- 10 seconds (until the blue light starts blinking and stops blinking), release and wait.
+* [Video: Pairing Xiaomi Aqara Cube MFKZQ01LM](https://www.youtube.com/watch?v=uhMrcIAdGxg&feature=youtu.be)
+
+*NOTE: When you fail to pair a device, try replacing the battery, this could solve the problem.*
+
+## Belkin WeMo smart LED bulb
+[Resetting or Restoring the Wemo® Smart LED Bulb, F7C033](http://www.belkin.com/us/support-article?articleNum=116178)
+
+## IKEA TRADFRI
+The factory reset procedure differs between TRADFRI components:
+
+* Factory reset the light bulb ([video](https://www.youtube.com/watch?v=npxOrPxVfe0)). After resetting the bulb will automatically connect. While pairing, keep the bulb close the the CC2531 USB sniffer.
+What works for me every time is using (very) short “on’s” and a little bit longer “off’s”…
+I start with bulb on, then off, and then 6 “on’s”, where I kill the light as soon as the bulb shows signs of turning on… Hope that make sense…?
+
+* To factory reset the TRADFRI wireless dimmer (ICTC-G-1) press the button 4 times (so the red lights starts blinking).
+
+* To factory reset the TRADFRI control outlet, press and hold the reset button (pinhole underneath the light, located at the top of the outlet) with a paperclip until the white light starts fading. Hold onto the button for a few more seconds, then release. After this, the outlet will automatically connect.
+
+* To factory reset the TRADFRI drivers (ICPSHC24-10EU-IL-1 and ICPSHC24-30EU-IL-1) use a small pin or paperclip to push the reset button once.
+
+### IKEA TRADFRI remote control (E1524)
+This device requires extra setup as it is meant to only control groups. Therefore it does not send any information directly to the coordinator. As the group ID is randomized upon factor reset we need to find out the group ID where it sends its commands to. This can be done by using Zigbee sniffing.
+
+1. Pair the remote to Zigbee2mqtt by holding it close to the coordinator and pressing the button next to the battery 4 times. The red light on the remote will now flash a few times.
+2. Setup your Zigbee traffic sniffer by following [How to sniff Zigbee traffic](../how_tos/how_to_sniff_zigbee_traffic.md).
+3. Press the middle (power) button on the remote, this will produce the following message in Wireshark:
+![E1524 group](../images/E1524_group.png)
+4. Retrieve the group from the message, which is `0xeb12` in the above example.
+5. Add the group to the device in `configuration.yaml`, example:
+```yaml
+devices:
+  '0x000b57fffecb472d':
+    friendly_name: '0x000b57fffecb472d'
+    retain: false
+    coordinator_group: 0xeb12
+```
+6. Restart Zigbee2mqtt, when everything went OK you will see:
+```
+zigbee2mqtt:info 1/8/2019, 8:42:40 PM Sucesfully applied coordinator group for IKEA TRADFRI remote control (0x000b57fffecb472d)
+```
+### Why is this needed?
+The TRADFRI remote sends the group ID using touchlink commissioning (while holding the reset button close to a bulb) but this is currently not supported by the firmware (Z-Stack 1.2 HA). Perhaps it will work in Z-Stack 3.0.
+
+## Philips Hue
+Factory reset the light bulb see [HOWTO: Factory reset a Hue bulb](https://www.youtube.com/watch?v=qvlEAELiJKs). After resetting the bulb will automatically connect.
+
+* This is also possible with the [Tradfri Remote Control](https://www.ikea.com/us/en/images/products/tradfri-remote-control__0489469_PE623665_S4.JPG) by pressing and holding the reset button on the bottom of the remote (next to the battery). [This may not always work](https://github.com/Koenkk/zigbee2mqtt/issues/296#issuecomment-416923751).
+* Philips Hue Lightstrip Plus V2 have been successfully reset using the [Hue Dimmer Switch](https://www2.meethue.com/en-us/support/dimmer-switch) by holding the On and Off buttons at the same time for 10 seconds while holding next to the Lightstrip controller, afterwards the Lightstrips can join Zigbee2MQTT.
+* For the 7146060PH (Philips Hue Go), **the power cord has to be connected**, after the blinking light (**INSTEAD** of step four in the video), press and keep holding the button on the bottom until the device is paired (+- 60 seconds). While holding the button the Hue Go will give you a nice light show :smile:.
+
+### Philips Living Colors IRIS (Friends of HUE)
+Philips Living Colors IRIS comes with Philips (HUE) Remote Gen 3 (Round Click Wheel).
+To Pair hold Hold ON and Bottom Left Key (Favorite 1) in Front of the LED until the Light Blinks and turns Orange. If connection was succesfull the Light will turn Green.
+
+## Innr
+Factory reset using [Innr manual reset instructions](https://www.youtube.com/watch?v=4zkpZSv84H4). After resetting the bulb will automatically connect.
+
+## Hive
+Follow instructions from [How do I reset my Hive Active Light?](https://www.hivehome.com/ca/support/Help_installing_Hive/HIH_Hive_Active_Light/How-do-I-reset-my-Hive-Active-Light). After resetting the bulb will automatically connect.
+
+## OSRAM
+### OSRAM Light Bulb
+Follow instruction from [Manual reset](http://belkin.force.com/Articles/articles/en_US/Troubleshooting_and_Tutorials/Resetting-the-OSRAM-LIGHTIFY-Tunable-White-60-Bulb#a). After resetting the bulb will automatically connect.
+### OSRAM Smart+ Plug
+For the OSRAM Smart+ plug (AB3257001NJ) hold the on/off button until your hear a click (+- 10 seconds).
+### OSRAM Smart+ Switch Mini
+For the OSRAM Smart+ Switch Mini (AC0251100NJ) hold the Middle and Arrow Down Buttons for 10 Seconds to Reset the Device. Hold the Middle and Arrow Up Buttons for 3 Seconds to connect. If the Switch is connected hold Middle and Arrow Up Buttons for 3 Seconds to disconnect.
+### OSRAM Switch 4x-LIGHTIFY
+For the OSRAM Switch 4x-LIGHTIFY (AB371860055) hold the Bottom Left and Top Right Button for 3 Seconds to connect.
+
+## PLUG EDP RE:DY
+Factory reset the plug (hold the switch button for >10sec). After resetting the switch will automatically connect.
+
+## Netvox power socket
+Factory reset by:
+- Press and hold the Binding Key for 15 seconds. The network indicator will flash green 3 times
+(at the 3rd, the 10th, and the 15th second).
+- After releasing the Binding Key, press the Switch Key within 2 seconds. The network indicator
+will rapidly flash green.
+- After fast flashes, Z809A will reboot, and the restore is completed. The socket will automatically connect now.
+
+## Gledopto
+Some of the Gledopto devices are not providing a `modelID`, in that case the modelID `undefined` is shown. Sometimes it helps to repair the device while keeping it close to the coordinator (less than one meter).
+
+If this fails, the `modelID` has to be set manually in `data/database.db`. First find out the `modelID` of your devices from the [Supported devices page](../information/supported_devices.md). Then open `data/database.db` and add the `modelId` as highlighted in **bold** below.
+
+*{"id":50,"type":"Router","ieeeAddr":"0x00124b0019c606cd","nwkAddr":10828,"manufId":0,"manufName":"GLEDOPTO","powerSource":"Mains (single phase)",**"modelId":"GL-S-007Z"**,"epList":[11,13],"status":"offline","joinTime":null,"endpoints":{"11":{"profId":49246,"epId":11,"devId":528,"inClusterList":[0,3,4,5,6,8,768],"outClusterList":[],"clusters":{"genBasic":{"dir":{"value":1},"attrs":{}},"genIdentify":{"dir":{"value":1},"attrs":{}},"genGroups":{"dir":{"value":1},"attrs":{}},"genScenes":{"dir":{"value":1},"attrs":{}},"genOnOff":{"dir":{"value":1},"attrs":{}},"genLevelCtrl":{"dir":{"value":1},"attrs":{}},"lightingColorCtrl":{"dir":{"value":1},"attrs":{}}}},"13":{"profId":49246,"epId":13,"devId":57694,"inClusterList":[4096],"outClusterList":[4096],"clusters":{"lightLink":{"dir":{"value":3},"attrs":{}}}}},"_id":"geCEMkRqlaMe6muE"}*

docs/getting_started/running_zigbee2mqtt.md

@@ -0,0 +1,197 @@
+# Running Zigbee2mqtt
+These instructions explain how to run Zigbee2mqtt on bare-metal Linux.
+
+Other ways to run Zigbee2mqtt are [Docker](../information/docker.md) and the [Hass.io Zigbee2mqtt add-on](https://github.com/danielwelch/hassio-zigbee2mqtt).
+
+For the sake of simplicity this guide assumes running on a Raspberry Pi 3 with Raspbian Stretch Lite, but will work on any Linux machine.
+
+## 1. Determine location of CC2531 USB sniffer and checking user permissions
+We first need to determine the location of the CC2531 USB sniffer. Connect the CC2531 USB to your Raspberry Pi. Most of the times the location of the CC2531 is `/dev/ttyACM0`. This can be verified by:
+
+```bash
+pi@raspberry:~ $ ls -l /dev/ttyACM0
+crw-rw---- 1 root dialout 166, 0 May 16 19:15 /dev/ttyACM0  # <-- CC2531 on /dev/ttyACM0
+```
+
+As an alternative, the device can also be mapped by an ID. This can be handy if you have multiple serial devices connected to your Raspberry Pi. In the example below the device location is: `/dev/serial/by-id/usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B0018ED3DDF-if00`
+```bash
+pi@raspberry:/ $ ls -l /dev/serial/by-id
+total 0
+lrwxrwxrwx. 1 root root 13 Oct 19 19:26 usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B0018ED3DDF-if00 -> ../../ttyACM0
+```
+
+## 2. Installing
+```bash
+# Setup Node.js repository
+sudo curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash -
+
+# Install Node.js
+sudo apt-get install -y nodejs git make g++ gcc
+
+# Verify that the correct nodejs and npm (automatically installed with nodejs)
+# version has been installed
+node --version  # Should output v10.X
+npm --version  # Should output 6.X
+
+# Clone zigbee2mqtt repository
+sudo git clone https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt
+sudo chown -R pi:pi /opt/zigbee2mqtt
+
+# Install dependencies
+cd /opt/zigbee2mqtt
+npm install
+```
+
+If everything went correctly the output of `npm install` is similar to (the number of packages and seconds is probably different on your device):
+```bash
+node-pre-gyp info ok
+added 383 packages in 111.613s
+```
+
+Note that the `npm install` produces some `warning` which can be ignored.
+
+## 3. Configuring
+Before we can start Zigbee2mqtt we need to edit the `configuration.yaml` file. This file contains the configuration which will be used by Zigbee2mqtt.
+
+Open the configuration file:
+```bash
+nano /opt/zigbee2mqtt/data/configuration.yaml
+```
+
+For a basic configuration, the default settings are probably good. The only thing we need to change is the MQTT server url and authentication (if applicable). This can be done by changing the section below in your `configuration.yaml`.
+
+```yaml
+# MQTT settings
+mqtt:
+  # MQTT base topic for zigbee2mqtt MQTT messages
+  base_topic: zigbee2mqtt
+  # MQTT server URL
+  server: 'mqtt://localhost'
+  # MQTT server authentication, uncomment if required:
+  # user: my_user
+  # password: my_password
+```
+Save the file and exit.
+
+## 4. Starting zigbee2mqtt
+Now that we have setup everything correctly we can start zigbee2mqtt.
+
+```bash
+cd /opt/zigbee2mqtt
+npm start
+```
+
+When started successfully, you will see:
+```bash
+2018-5-18 20:35:07 INFO Starting zigbee-shepherd
+2018-5-18 20:35:09 INFO zigbee-shepherd started
+2018-5-18 20:35:09 INFO Currently 0 devices are joined:
+2018-5-18 20:35:09 INFO Connecting to MQTT server at mqtt://localhost
+2018-5-18 20:35:09 INFO zigbee-shepherd ready
+2018-5-18 20:35:09 INFO Connected to MQTT server
+```
+
+Zigbee2mqtt can be stopped by pressing `CTRL + C`.
+
+## 5. (Optional) Running as a daemon with systemctl
+To run zigbee2mqtt as daemon (in background) and start it automatically on boot we will run Zigbee2mqtt with systemctl.
+
+```bash
+# Create a systemctl configuration file for zigbee2mqtt
+sudo nano /etc/systemd/system/zigbee2mqtt.service
+```
+
+Add the following to this file:
+```
+[Unit]
+Description=zigbee2mqtt
+After=network.target
+
+[Service]
+ExecStart=/usr/bin/npm start
+WorkingDirectory=/opt/zigbee2mqtt
+StandardOutput=inherit
+StandardError=inherit
+Restart=always
+User=pi
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Save the file and exit.
+
+Verify that the configuration works:
+```bash
+# Start zigbee2mqtt
+sudo systemctl start zigbee2mqtt
+
+# Show status
+systemctl status zigbee2mqtt.service
+```
+
+Output should look like:
+```bash
+pi@raspberry:/opt/zigbee2mqtt $ systemctl status zigbee2mqtt.service
+● zigbee2mqtt.service - zigbee2mqtt
+   Loaded: loaded (/etc/systemd/system/zigbee2mqtt.service; disabled; vendor preset: enabled)
+   Active: active (running) since Thu 2018-06-07 20:27:22 BST; 3s ago
+ Main PID: 665 (npm)
+   CGroup: /system.slice/zigbee2mqtt.service
+           ├─665 npm
+           ├─678 sh -c node index.js
+           └─679 node index.js
+
+Jun 07 20:27:22 raspberry systemd[1]: Started zigbee2mqtt.
+Jun 07 20:27:23 raspberry npm[665]: > zigbee2mqtt@0.1.0 start /opt/zigbee2mqtt
+Jun 07 20:27:23 raspberry npm[665]: > node index.js
+Jun 07 20:27:24 raspberry npm[665]: 2018-6-7 20:27:24 INFO Starting zigbee-shepherd
+Jun 07 20:27:25 raspberry npm[665]: 2018-6-7 20:27:25 INFO zigbee-shepherd started
+```
+
+Now that everything works, we want systemctl to start zigbee2mqtt automatically on boot, this can be done by executing:
+```bash
+sudo systemctl enable zigbee2mqtt.service
+```
+
+Done! 😃
+
+Some tips that can be handy later:
+```bash
+# Stopping zigbee2mqtt
+sudo systemctl stop zigbee2mqtt
+
+# Starting zigbee2mqtt
+sudo systemctl start zigbee2mqtt
+
+# View the log of zigbee2mqtt
+sudo journalctl -u zigbee2mqtt.service -f
+```
+
+## 6. (For later) Update Zigbee2mqtt to the latest version
+To update Zigbee2mqtt to the latest version, execute:
+
+```sh
+# Stop zigbee2mqtt and go to directory
+sudo systemctl stop zigbee2mqtt
+cd /opt/zigbee2mqtt
+
+# Backup configuration
+cp -R data data-backup
+
+# Update
+git checkout HEAD -- npm-shrinkwrap.json
+git pull
+rm -rf node_modules
+npm install
+
+# Restore configuration
+cp -R data-backup/* data
+rm -rf data-backup
+
+# Start zigbee2mqtt
+sudo systemctl start zigbee2mqtt
+```
+
+# What's next?
+[Pairing devices](pairing_devices.md)

docs/getting_started/what_do_i_need.md

@@ -0,0 +1,13 @@
+# What do I need?
+In order to run zigbee2mqtt we need the following hardware:
+
+| Name | Price | Picture |
+| ------------- | ------------- | ------------- |
+| CC debugger | +-10$ on AliExpress | ![CC debugger](../images/cc_debugger.jpg) |
+| CC2531 USB sniffer | +-8.50$ on AliExpress | ![CC2531 USB sniffer](../images/cc2531.jpg) |
+| Downloader cable CC2531 | +-2$ on AliExpress | ![Downloader cable CC2531](../images/downloader_cable.png) |
+| [Supported Zigbee device(s)](https://koenkk.github.io/zigbee2mqtt/information/supported_devices.html) | - | ![Zigbee devices](../images/xiaomi_sensors.jpg) |
+| PC or Raspberry Pi to run bridge | - | ![Raspberry Pi](../images/pi.jpg) |
+
+# What's next?
+[Flashing the CC2531 USB stick](flashing_the_cc2531.md)

docs/how_tos/how_to_connect_a_cc2530_coordinator_using_a_usb_to_serial_adapter.md

@@ -0,0 +1,39 @@
+# How to connect a CC2530 coordinator using a USB to serial adapter
+
+## Confirmed working
+This how-to has been confirmed working with the following CC2530 based devices:
+
+| Device| Image |
+| --- | --- |
+| **CC2530** | ![CC2530](../images/cc2530.jpg) |
+
+and the following USB to serial adapters:
+
+| Device| Image |
+| --- | --- |
+| **CP2102** | ![CP2102](../images/CP2102.png) |
+
+## Flashing the firmware
+The required coordinator fimrware can be found here: [CC sniffer devices](../information/cc_sniffer_devices.md).
+
+## Connecting
+Connect to CC2530 to the USB to serial adapter using the following mapping:
+
+| USB-Serial Adaper  | CC2530  |
+| :------------: |:---------------:|
+| 3V3 | VCC |
+| GND | GND |
+| TXD | P02 |
+| RXD | P03 |
+
+Now plug in the USB-to-serial adapter in your USB port.
+
+## Configuration
+Add the following to your Zigbee2mqtt `configuration.yaml`:
+
+```yaml
+advanced:
+  rtscts: false
+```
+
+and start Zigbee2mqtt, enjoy!

docs/how_tos/how_to_create_a_cc2530_router.md

@@ -0,0 +1,70 @@
+# How to create a CC2530 router
+The CC2530 is highly suitable for serving as a router. It has an external antenna which will greatly improve the range of your Zigbee network. This tutorial will explain how to create a CC2530 router packed into a nice enclosure which can be powered via any regular outlet.
+
+**DISCLAIMER:** The CC2530 router will use Mains AC so there is a danger of electrocution if not installed properly. If you don't know how to install it, please call an electrician!
+
+![CC2530 in an enclosure](../images/cc2530_router_enclosure.jpg)
+
+## 1. What do I need?
+
+| Name | Price | Picture |
+| ------------- | ------------- | ------------- |
+| CC2530 <br/> **OR** <br/> CC2530 + CC2591 <br/> *The CC2530 + CC2591 is more powerful but more expensive* | +-7.50$ on AliExpress <br/><br/>  +-15$ on AliExpress | ![CC2530](../images/cc2530.jpg)|
+| HLK-PM03 | +-2.20$ on AliExpress | ![HLK-PM03](../images/HLK-PM03.jpg) |
+| Enclosure (the one used has the following dimensions: 100x68x40mm) | +-2$ | ![Enclosure](../images/enclosure.jpg) |
+| Power cable | +-2$ | ![Power cable](../images/power_cable.png) |
+| CC debugger | - | ![CC debugger](../images/cc_debugger.jpg) |
+| 8 female to female jumper wires | - | ![Jumper wires](../images/female_to_female_jumper_wires.jpg) |
+
+# 2. Flashing the CC2530
+The CC2530 has to be flashed with a router firmware which has to be done with a CC debugger using 6 female to female jumper wires. Pins have to connected as follows:
+
+### CC debugger pin layout
+
+<div style="float: right;">
+ <img src="../images/ccdebugger_pins.png"/>
+</div>
+
+| CC debugger | CC2530 |
+| ----------- | ------ |
+| 1 | GND |
+| 2 | VCC |
+| 3 | P2.2 |
+| 4 | P2.1 |
+| 7 | RST |
+| 9 | VCC |
+
+### Pin layout of various CC2530 modules
+
+| Name | Pin layout | Picture |
+| ------------- | ------------- | ------------- |
+| CC2530 | ![CC2530 pin layout](../images/cc2530_pin_layout.png) | ![CC2530](../images/cc2530.jpg)
+| Webee CC2530 + CC2591 | ![Webee CC2530 + CC2591 pin layout](../images/webee_cc2530_cc2591_pinlayout.png) | ![CC2530 + CC2591](../images/cc2530_cc2591.jpg)
+
+### Flashing
+Now the CC2530 can be flashed using the same instructions as [Flashing the CC2531](../getting_started/flashing_the_cc2531.md). The router firmwares can be found [here](https://github.com/Koenkk/Z-Stack-firmware/tree/master/router).
+
+![CC debugger connected to CC2530](../images/ccdebugger_cc2530.jpg)
+
+# 3. Putting it in an enclosure
+The following steps have to be followed:
+- Drill 2 holes in the enclosure; one for the antenna, one for the power cable
+- Lay a knot in the power cable; this serves as strain relief
+- Solder the power cable on to the AC pins of the HLK-PM03
+- Use 2 female to female jumper wires to connect the VC+ pin of the HLK-PM03 to the VCC pin of the CC2530 and the VC- pin of the HLK-PM03 to the GND pin of the CC2530
+- Use double sided tape to fix the CC2530 and HLK-PM03 into the enclosure
+
+### Result
+
+![1](../images/router_1.jpg)
+
+![2](../images/router_2.jpg)
+
+![3](../images/router_3.jpg)
+
+![4](../images/router_4.jpg)
+
+![CC2530 in an enclosure](../images/cc2530_router_enclosure.jpg)
+
+# 4. Done!
+Now plug the CC2530 into a power outlet where it will automatically join your Zigbee network. (don't forget to set `permit_join: true` to enable joining of new devices). Enjoy your extended Zigbee network range! :smile:

docs/how_tos/how_to_debug.md

@@ -0,0 +1,25 @@
+# How to debug
+
+In case Zigbee2mqtt isn't working as expected the following tips can help you in finding the problem.
+
+## Enabling logging
+
+### Zigbee2mqtt debug logging
+To enable debug logging for zigbee2mqtt add the following in your `configuration.yaml`
+
+```yaml
+advanced:
+  log_level: debug
+```
+
+### zigbee-shepherd debug logging
+To enable debug logging for zigbee-shepherd start zigbee2mqtt with: `DEBUG=zigbee-shepherd* npm start`. For more information about zigbee-shepherd debug logging see: [zigbee-shepherd debug messages](https://github.com/zigbeer/zigbee-shepherd/wiki#8-debug-messages).
+
+### All debug logging
+To enable debug logging for both Zigbee2mqtt and zigbee-shepherd start Zigbee2mqtt with `DEBUG=* npm start`.
+
+### Docker
+To enable debug logging in the Zigbee2mqtt Docker container add `-e DEBUG=*` to your `docker run` command.
+
+## Change log level during runtime
+See [MQTT topics and message structure](../information/mqtt_topics_and_message_structure.md)

docs/how_tos/how_to_secure_network.md

@@ -0,0 +1,25 @@
+# How to secure your Zigbee network
+By default your Zigbee network isn't as secured as possible. The following settings are recommeded to apply to your configuration.
+
+## Disable joining
+To disable joining it's important that `permit_join: false` is set in your `configuration.yaml`. Otherwise rogue devices are able to join allowing them to send and receive Zigbee traffic.
+
+## Change Zigbee network encryption key
+**Changing the key requires repairing of all devices!**
+
+Zigbee2mqtt uses a known default encryption key. Therefore it is recommended to use a different one. To use a different encryption key add the following to your `configuration.yaml`:
+
+**Do not use this exact key.**
+```
+advanced:
+  network_key: [7, 3, 5, 7, 9, 11, 13, 15, 0, 2, 4, 6, 8, 11, 12, 13]
+```
+
+The network encryption key size is `128-bit` which is essentially 16 decimal values between `0` and `255` or 16 hexadecimal values between `0x00`and `0xFF`.
+
+If you need to transform your decimals to hexadecimals (or vice versa) please use a [converter](https://www.binaryhexconverter.com/decimal-to-hex-converter). Example: 92 (decimal) would become 5C (hexadecimal).
+
+You can generate a valid key with the following command in most linux systems:
+```
+dd if=/dev/urandom bs=1 count=16 2>/dev/null | od -A n -t x1 | awk '{printf "["} {for(i = 1; i< NF; i++) {printf "0x%s, ", $i}} {printf "0x%s]\n", $NF}'
+```

docs/how_tos/how_to_sniff_zigbee_traffic.md

@@ -0,0 +1,53 @@
+# How to sniff Zigbee traffic
+Sniffing Zigbee traffic can be handy sometimes. E.g. when you want to analyze the commands used by a device.
+
+## Prerequisites
+* Computer
+  * Ubuntu machine (tested with 18.10)
+  * Windows machine (tested with Windows 10)
+* CC2531 stick
+
+## 1. Flashing the CC2531 stick
+The CC2531 needs to be flashed with a sniffer firmware. Flash the firmware using the instructions from [Flashing the CC2531](../getting_started/flashing_the_cc2531.md).
+
+### Ubuntu
+For Ubuntu this firmware is included with [PACKET-SNIFFER](http://www.ti.com/tool/PACKET-SNIFFER) (not **PACKET-SNIFFER-2!**). Download and install PACKET-SNIFFER. The firmware can then be found here: `C:\Program Files (x86)\Texas Instruments\SmartRF Tools\Packet Sniffer\bin\general\firmware\sniffer_fw_cc2531.hex`.
+
+### Windows (and possibly Ubuntu)
+For Windows this firmware is included with [ZBOSS](http://zboss.dsr-wireless.com/downloads/index/zboss). Register an account and download *ZBOSS Sniffer for Windows 64-bit*. Included in the ZIP file is the firmware in subfolder `hw\CC2531 USB dongle\zboss_sniffer.hex`. Please note that ZBOSS is also available for Ubuntu.
+
+## 2. Installing required tools
+
+### Ubuntu
+```bash
+cd /opt
+sudo apt-get install -y libusb-1.0-0-dev wireshark
+curl -L https://github.com/homewsn/whsniff/archive/v1.1.tar.gz | tar zx
+cd whsniff-1.1
+make
+sudo make install
+```
+
+### Windows
+Download and install the latest version of [Wireshark](https://www.wireshark.org/download.html). ZBOSS itself is portable and won't need to be installed.
+
+## 3. Sniffing traffic
+On Ubuntu start wireshark with `sudo whsniff -c ZIGBEE_CHANNEL_NUMBER | wireshark -k -i -`. For Windows run the ZBOSS executable in `gui\zboss_sniffer.exe`, enter the path to your Wireshark executable and click on the `Start` button.
+
+Wireshark will start and log the Zigbee messages. As these messages are encrypted we need to add 2 encryption keys. The first one is the Trust Center link key, which is the same for (almost) every Zigbee network. The second on is the network encryption key.
+
+Add the Trust Center link key by going to to Edit -> Preferences -> Protocols -> ZigBee. Set Security Level to *AES-128 Encryption, 32-bit Integrity Protection* and click on *Edit*. Click on *+* and add `5A:69:67:42:65:65:41:6C:6C:69:61:6E:63:65:30:39` with Byte Order Normal.
+
+*NOTE: The Hue bridge uses a [different Trust Center link key](https://peeveeone.com/?p=166)*
+
+![Wireshark Trust Center link key](../images/wireshark_tclink_key.png)
+
+Next we need to figure out the network encryption key. The network encryption key is exposed when a device joins the network. Pair a new device to the network (or repair an existing one) and grab the message where the Info is *Device Announcement....*. Open the message and expand *ZigBee Network Layer Data* -> *ZigBee Security Header*.
+
+![Wireshark network key](../images/wireshark_network_key.png)
+
+Copy the key value, as shown above and go to Edit -> Preferences -> Protocols -> ZigBee -> Edit and add the key with Byte Order Normal.
+
+Now Wireshark is able to decrypt the messages. When e.g. turning on a light you will see a message similar to:
+
+![Wireshark packet](../images/wireshark_packet.png)

docs/how_tos/how_to_support_new_devices.md

@@ -0,0 +1,99 @@
+# How to support new devices
+
+Zigbee2mqtt uses [zigbee-shepherd-converters](https://github.com/Koenkk/zigbee-shepherd-converters) to parse messages to and from devices. This was originally part of Zigbee2mqtt but has been moved to a separate library so that other projects can also take advantage of this.
+
+This page will guide you through the process of adding support for new devices to [zigbee-shepherd-converters](https://github.com/Koenkk/zigbee-shepherd-converters).
+
+In case you require any help feel free to create an [issue](https://github.com/Koenkk/zigbee2mqtt/issues).
+
+## 1. Pairing the device with Zigbee2mqtt
+The first step is to pair the device with zigbee2mqtt. It should be possible to pair your unsupported device out of the box because zigbee2mqtt can pair with any zigbee device. You need to find out how to bring your device into pairing mode, most of the times via a factory reset. For some vendors this is already documented [here](https://koenkk.github.io/zigbee2mqtt/getting_started/pairing_devices.html).
+
+Once you successfully paired the device you will see something like:
+```
+2018-5-1 18:06:41 INFO New device with address 0x00158d0001b79111 connected!
+2018-5-1 18:06:42 WARN Device with modelID 'lumi.sens' is not supported.
+2018-5-1 18:06:42 WARN Please see: https://koenkk.github.io/zigbee2mqtt/how_tos/how_to_support_new_devices.html
+```
+
+*NOTE: Make sure that `permit_join: true` is set in `configuration.yaml` otherwise new devices cannot join the network.*
+
+## 2. Adding your device
+The next step is the to add an entry of your device to `node_modules/zigbee-shepherd-converters/devices.js`. In order to provide support for E.G. the `lumi.sens` from step 1 you would add:
+```js
+{
+    zigbeeModel: ['lumi.sens'], // The model ID from: Device with modelID 'lumi.sens' is not supported.
+    model: 'WSDCGQ01LM', // Vendor model number, look on the device for a model number
+    vendor: 'Xiaomi', // Vendor of the device (only used for documentation and startup logging)
+    description: 'MiJia temperature & humidity sensor ', // Description of the device, copy from vendor site. (only used for documentation and startup logging)
+    supports: 'temperature and humidity', // Actions this device supports (only used for documentation)
+    fromZigbee: [], // We will add this later
+    toZigbee: [], // Should be empty, unless device can be controlled (e.g. lights, switches).
+},
+```
+
+Once finished, restart Zigbee2mqtt and trigger some actions on the device. You will see messages like:
+```
+2018-5-1 18:19:41 WARN No converter available for 'WSDCGQ01LM' with cid 'msTemperatureMeasurement' and type 'attReport'
+2018-5-1 18:19:41 WARN Please create an issue on https://github.com/Koenkk/zigbee2mqtt/issues with this message.
+```
+
+In case your device is not reporting anything, it could be that this device requires additional configure. This can be done by adding a `configure:` section, [examples]([https://github.com/Koenkk/zigbee-shepherd-converters/blob/master/devices.js). In case your device is a contact or motion sensor, it could be that this is an [IAS device](https://stackoverflow.com/questions/31241211/zigbee-ias-device-enroll-and-response). Example of an IAS `configure:` section can be found [here](https://github.com/Koenkk/zigbee-shepherd-converters/blob/master/devices.js#L1495).
+
+## 3. Adding converter(s) for your device
+In order to parse the messages of your zigbee device we need to add converter(s) to `node_modules/zigbee-shepherd-converters/converters/fromZigbee.js`.
+
+Before adding new converters, please check if you can reuse any existing one.
+
+For E.G. the following message
+```
+2018-5-1 18:19:41 WARN No converter available for 'WSDCGQ01LM' with cid 'msTemperatureMeasurement' and type 'attReport'
+2018-5-1 18:19:41 WARN Please create an issue on https://github.com/Koenkk/zigbee2mqtt/issues with this message.
+```
+
+You would add to `node_modules/zigbee-shepherd-converters/converters/fromZigbee.js`:
+```js
+xiaomi_temperature: {
+    cid: 'msTemperatureMeasurement',
+    type: 'attReport',
+    convert: (model, msg, publish, options) => {
+        return {temperature: parseFloat(msg.data.data['measuredValue']) / 100.0};
+    },
+},
+```
+
+To find out the structure of the message and which attributes you need to grab from the message you could first start with:
+```js
+xiaomi_temperature: {
+    cid: 'msTemperatureMeasurement',
+    type: 'attReport',
+    convert: (model, msg, publish, options) => {
+        console.log(msg.data)
+    },
+},
+```
+
+Now update your device in `node_modules/zigbee-shepherd-converters/devices.js` with the new converter.
+```js
+{
+    zigbeeModel: ['lumi.sens'],
+    model: 'WSDCGQ01LM',
+    vendor: 'Xiaomi',
+    description: 'MiJia temperature & humidity sensor ',
+    supports: 'temperature and humidity',
+    fromZigbee: [fz.xiaomi_temperature],  # <-- added here
+    toZigbee: [],
+},
+```
+
+Repeat until your device does not produce any more log messages like:
+```
+2018-5-1 18:19:41 WARN No converter available for 'WSDCGQ01LM' with cid 'msTemperatureMeasurement' and type 'attReport'
+2018-5-1 18:19:41 WARN Please create an issue on https://github.com/Koenkk/zigbee2mqtt/issues with this message.
+```
+
+## 4. (Optional) Add home assistant configuration for your device
+In order to automatically discover this device in home assistant your device needs to be added to `mapping` in `lib/extension/homeassistant.js`.
+
+## 5. Done!
+Now it's time to submit a pull request to [zigbee-shepherd-converters](https://github.com/Koenkk/zigbee-shepherd-converters) so this device is supported out of the box by zigbee2mqtt. :smiley:

docs/how_tos/how_to_support_new_devices_on_hassio.md

@@ -0,0 +1,49 @@
+# How to support new devices on Hass.io
+
+1. Enable access to your Hass.io host following these instructions
+https://developers.home-assistant.io/docs/en/hassio_debugging.html
+
+2. Connect to your Hass.io host\
+`ssh root@hassio.local -p 22222`\
+`login`
+
+3. Identify the container id of zigbee2mqtt\
+`docker ps`\
+look for IMAGE dwelch2101/zigbee2mqtt-armhf and its corresponding CONTAINER ID\
+example:**622baa375aa1**
+
+4. Enter the running container (replace the below container id with yours)\
+`docker exec -it 622baa375aa1 bash`
+
+5. You are now inside the zigbee2mqtt container and can follow the standard guide:\
+[https://koenkk.github.io/zigbee2mqtt/how_tos/how_to_support_new_devices.html](https://koenkk.github.io/zigbee2mqtt/how_tos/how_to_support_new_devices.html)
+
+6.  The VI editor is installed on the image, if you are not familiar with VI you may want take a look here:
+ [https://www.guru99.com/the-vi-editor.html](https://www.guru99.com/the-vi-editor.html)
+
+7. After making required modifications restart the container for the changes to take effect\
+`exit`\
+`docker restart 622baa375aa1`
+
+Be aware that changes are not persistent, any changes that recreate the docker container HASSIO will result in the changes being lost so make sure you request modifications are provided back to the project for integration.
+
+**Persisting a custom devices.js**
+
+As of hass.io zigbee2mqtt add-on v0.1.8, there is an option for using a custom `devices.js`\
+While the procedure above is very useful for adding / debugging support for devices, making the updates persistent is now possible with this new option. To use a custom `devices.js` by default, follow these steps:
+
+1. Make sure you're using at least 0.1.8 version of zigbee2mqtt add-on.
+
+2. Edit zigbee2mqtt's config in Hass.io GUI and add this option:\
+`"zigbee_shepherd_devices": true`
+
+3. Add custom `devices.js` to the config path of the add-on.\
+This path is `/share/zigbee2mqtt` by default, and controlled with the `data_path` option in the config of the add-on.
+
+4. Restart the add-on.
+
+5. Check the logs of the add-on, it should include the following line:\
+`[Info] Searching for custom devices file in zigbee2mqtt data path...`
+
+If all goes well, your custom `devices.js` will be copied to the zigbee2mqtt container upon container startup, and it will be used by `zigbee-shepherd`.\
+As the add-on config and the files on config path are permanent, this configuration will persist upon reboots and container updates.