Merge branch 'master' into dev

docs/_config.yml

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

docs/configuration/configuration.md

@@ -0,0 +1,56 @@
+# 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
+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
+```

docs/configuration/device_specific_configuration.md

@@ -0,0 +1,25 @@
+# Device specific configuration
+The `configuration.yaml` allows to set device specific configuration. The following options are available:
+* `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.
+* `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.
+* `qos`: QoS level for MQTT messages of this device. [What is QoS?](https://www.npmjs.com/package/mqtt#about-qos)
+
+Example:
+``` yaml
+devices:
+  '0x00158d0001d82999':
+    friendly_name: 'my_occupancy_sensor'
+    retain: true
+    occupancy_timeout: 20
+    qos: 1
+```
+
+Once finished, restart Zigbee2mqtt.
+
+The bridge will log the `friendly_name` on startup, e.g.:
+```
+Currently 2 devices are joined:
+switch_bedroom (0x00158d0001d8e1d2): WXKG01LM - Xiaomi MiJia wireless switch (EndDevice)
+sensor_bedroom (0x00158d0001b79111): WSDCGQ01LM - Xiaomi MiJia temperature & humidity sensor (EndDevice)
+```

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](../useful_information/alternative-firmware-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://raw.githubusercontent.com/Koenkk/Z-Stack-firmware/master/coordinator/CC2531/bin/CC2531ZNP-Prod.hex)
+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: 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://raw.githubusercontent.com/Koenkk/Z-Stack-firmware/master/coordinator/CC2531/bin/CC2531ZNP-Prod.hex).
+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,68 @@
+**IMPORTANT:** Before you start, make sure that `permit_join: true` is set in your `configuration.yaml`. Otherwise new devices cannot join the network!
+
+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.
+
+## 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.

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://github.com/Koenkk/zigbee2mqtt/wiki/Supported-devices) | - | ![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_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_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://github.com/Koenkk/zigbee2mqtt/wiki/Pairing-devices).
+
+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://github.com/Koenkk/zigbee2mqtt/wiki/How-to-support-new-devices
+```
+
+*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 wiki and startup logging)
+    description: 'MiJia temperature & humidity sensor ', // Description of the device, copy from vendor site. (only used for wiki and startup logging)
+    supports: 'temperature and humidity', // Actions this device supports (only used for wiki)
+    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://github.com/Koenkk/zigbee2mqtt/wiki/How-to-support-new-devices](https://github.com/Koenkk/zigbee2mqtt/wiki/How-to-support-new-devices)
+
+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.