diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 00000000..c4192631 --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1 @@ +theme: jekyll-theme-cayman \ No newline at end of file diff --git a/docs/configuration/configuration.md b/docs/configuration/configuration.md new file mode 100644 index 00000000..27cdedd3 --- /dev/null +++ b/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 +``` \ No newline at end of file diff --git a/docs/configuration/device_specific_configuration.md b/docs/configuration/device_specific_configuration.md new file mode 100644 index 00000000..a1e55f53 --- /dev/null +++ b/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) +``` \ No newline at end of file diff --git a/docs/getting_started/flashing_the_cc2531.md b/docs/getting_started/flashing_the_cc2531.md new file mode 100644 index 00000000..b59d0187 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/docs/getting_started/pairing_devices.md b/docs/getting_started/pairing_devices.md new file mode 100644 index 00000000..0e1e5f04 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/getting_started/running_zigbee2mqtt.md b/docs/getting_started/running_zigbee2mqtt.md new file mode 100644 index 00000000..fc571ee3 --- /dev/null +++ b/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) diff --git a/docs/getting_started/what_do_i_need.md b/docs/getting_started/what_do_i_need.md new file mode 100644 index 00000000..8530b728 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/docs/how_tos/how_to_debug.md b/docs/how_tos/how_to_debug.md new file mode 100644 index 00000000..b76813c7 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/docs/how_tos/how_to_support_new_devices.md b/docs/how_tos/how_to_support_new_devices.md new file mode 100644 index 00000000..fb3dc1c2 --- /dev/null +++ b/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: diff --git a/docs/how_tos/how_to_support_new_devices_on_hassio.md b/docs/how_tos/how_to_support_new_devices_on_hassio.md new file mode 100644 index 00000000..b0f1d9ee --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/images/cc2530.jpg b/docs/images/cc2530.jpg new file mode 100644 index 00000000..7bb24513 Binary files /dev/null and b/docs/images/cc2530.jpg differ diff --git a/docs/images/cc2530_cc2591.jpg b/docs/images/cc2530_cc2591.jpg new file mode 100644 index 00000000..9f92ce8c Binary files /dev/null and b/docs/images/cc2530_cc2591.jpg differ diff --git a/docs/images/cc2530_rfx2401.png b/docs/images/cc2530_rfx2401.png new file mode 100644 index 00000000..0cc721fb Binary files /dev/null and b/docs/images/cc2530_rfx2401.png differ diff --git a/docs/images/cc2531.jpg b/docs/images/cc2531.jpg new file mode 100644 index 00000000..ddcf3019 Binary files /dev/null and b/docs/images/cc2531.jpg differ diff --git a/docs/images/cc_debugger.jpg b/docs/images/cc_debugger.jpg new file mode 100644 index 00000000..e5adac6f Binary files /dev/null and b/docs/images/cc_debugger.jpg differ diff --git a/docs/images/connected.jpg b/docs/images/connected.jpg new file mode 100644 index 00000000..ac465ba3 Binary files /dev/null and b/docs/images/connected.jpg differ diff --git a/docs/images/devices/22670.jpg b/docs/images/devices/22670.jpg new file mode 100755 index 00000000..fe031d42 Binary files /dev/null and b/docs/images/devices/22670.jpg differ diff --git a/docs/images/devices/3210-L.jpg b/docs/images/devices/3210-L.jpg new file mode 100755 index 00000000..f1787d56 Binary files /dev/null and b/docs/images/devices/3210-L.jpg differ diff --git a/docs/images/devices/3216331P5.jpg b/docs/images/devices/3216331P5.jpg new file mode 100755 index 00000000..434fc6d1 Binary files /dev/null and b/docs/images/devices/3216331P5.jpg differ diff --git a/docs/images/devices/324131092621.jpg b/docs/images/devices/324131092621.jpg new file mode 100755 index 00000000..ff78bbf4 Binary files /dev/null and b/docs/images/devices/324131092621.jpg differ diff --git a/docs/images/devices/3261030P7.jpg b/docs/images/devices/3261030P7.jpg new file mode 100755 index 00000000..3aa3a923 Binary files /dev/null and b/docs/images/devices/3261030P7.jpg differ diff --git a/docs/images/devices/3320-L.jpg b/docs/images/devices/3320-L.jpg new file mode 100755 index 00000000..7b6e0849 Binary files /dev/null and b/docs/images/devices/3320-L.jpg differ diff --git a/docs/images/devices/3326-L.jpg b/docs/images/devices/3326-L.jpg new file mode 100755 index 00000000..955c1fa9 Binary files /dev/null and b/docs/images/devices/3326-L.jpg differ diff --git a/docs/images/devices/4052899926110.jpg b/docs/images/devices/4052899926110.jpg new file mode 100755 index 00000000..7a40b28b Binary files /dev/null and b/docs/images/devices/4052899926110.jpg differ diff --git a/docs/images/devices/4052899926158.jpg b/docs/images/devices/4052899926158.jpg new file mode 100755 index 00000000..f505cab7 Binary files /dev/null and b/docs/images/devices/4052899926158.jpg differ diff --git a/docs/images/devices/4058075036147.jpg b/docs/images/devices/4058075036147.jpg new file mode 100755 index 00000000..590f91d0 Binary files /dev/null and b/docs/images/devices/4058075036147.jpg differ diff --git a/docs/images/devices/4058075036185.jpg b/docs/images/devices/4058075036185.jpg new file mode 100755 index 00000000..d5f5fc76 Binary files /dev/null and b/docs/images/devices/4058075036185.jpg differ diff --git a/docs/images/devices/4058075816718.jpg b/docs/images/devices/4058075816718.jpg new file mode 100755 index 00000000..90cca5a1 Binary files /dev/null and b/docs/images/devices/4058075816718.jpg differ diff --git a/docs/images/devices/4058075816794.jpg b/docs/images/devices/4058075816794.jpg new file mode 100755 index 00000000..077fc124 Binary files /dev/null and b/docs/images/devices/4058075816794.jpg differ diff --git a/docs/images/devices/4256251-RZHAC.jpg b/docs/images/devices/4256251-RZHAC.jpg new file mode 100755 index 00000000..a42392ca Binary files /dev/null and b/docs/images/devices/4256251-RZHAC.jpg differ diff --git a/docs/images/devices/433714.jpg b/docs/images/devices/433714.jpg new file mode 100755 index 00000000..938fe325 Binary files /dev/null and b/docs/images/devices/433714.jpg differ diff --git a/docs/images/devices/45852GE.jpg b/docs/images/devices/45852GE.jpg new file mode 100755 index 00000000..59fc8ccc Binary files /dev/null and b/docs/images/devices/45852GE.jpg differ diff --git a/docs/images/devices/45857GE.jpg b/docs/images/devices/45857GE.jpg new file mode 100755 index 00000000..17353142 Binary files /dev/null and b/docs/images/devices/45857GE.jpg differ diff --git a/docs/images/devices/50045.jpg b/docs/images/devices/50045.jpg new file mode 100755 index 00000000..efd2a298 Binary files /dev/null and b/docs/images/devices/50045.jpg differ diff --git a/docs/images/devices/50049.jpg b/docs/images/devices/50049.jpg new file mode 100755 index 00000000..d5739679 Binary files /dev/null and b/docs/images/devices/50049.jpg differ diff --git a/docs/images/devices/53170161.jpg b/docs/images/devices/53170161.jpg new file mode 100755 index 00000000..a4afaaa5 Binary files /dev/null and b/docs/images/devices/53170161.jpg differ diff --git a/docs/images/devices/7146060PH.jpg b/docs/images/devices/7146060PH.jpg new file mode 100755 index 00000000..3168e327 Binary files /dev/null and b/docs/images/devices/7146060PH.jpg differ diff --git a/docs/images/devices/7199960PH.jpg b/docs/images/devices/7199960PH.jpg new file mode 100755 index 00000000..84b9fb8e Binary files /dev/null and b/docs/images/devices/7199960PH.jpg differ diff --git a/docs/images/devices/72922-A.jpg b/docs/images/devices/72922-A.jpg new file mode 100755 index 00000000..4ec35a2f Binary files /dev/null and b/docs/images/devices/72922-A.jpg differ diff --git a/docs/images/devices/7299355PH.jpg b/docs/images/devices/7299355PH.jpg new file mode 100755 index 00000000..7273f743 Binary files /dev/null and b/docs/images/devices/7299355PH.jpg differ diff --git a/docs/images/devices/7299760PH.jpg b/docs/images/devices/7299760PH.jpg new file mode 100755 index 00000000..8762abbe Binary files /dev/null and b/docs/images/devices/7299760PH.jpg differ diff --git a/docs/images/devices/73693.jpg b/docs/images/devices/73693.jpg new file mode 100755 index 00000000..fce2981f Binary files /dev/null and b/docs/images/devices/73693.jpg differ diff --git a/docs/images/devices/73740.jpg b/docs/images/devices/73740.jpg new file mode 100755 index 00000000..1f6c9340 Binary files /dev/null and b/docs/images/devices/73740.jpg differ diff --git a/docs/images/devices/73742.jpg b/docs/images/devices/73742.jpg new file mode 100755 index 00000000..57d6c256 Binary files /dev/null and b/docs/images/devices/73742.jpg differ diff --git a/docs/images/devices/74282.jpg b/docs/images/devices/74282.jpg new file mode 100755 index 00000000..67b78c3c Binary files /dev/null and b/docs/images/devices/74282.jpg differ diff --git a/docs/images/devices/74283.jpg b/docs/images/devices/74283.jpg new file mode 100755 index 00000000..75b9c457 Binary files /dev/null and b/docs/images/devices/74283.jpg differ diff --git a/docs/images/devices/74696.jpg b/docs/images/devices/74696.jpg new file mode 100755 index 00000000..cbdb852d Binary files /dev/null and b/docs/images/devices/74696.jpg differ diff --git a/docs/images/devices/8718696449691.jpg b/docs/images/devices/8718696449691.jpg new file mode 100755 index 00000000..14b88142 Binary files /dev/null and b/docs/images/devices/8718696449691.jpg differ diff --git a/docs/images/devices/8718696485880.jpg b/docs/images/devices/8718696485880.jpg new file mode 100755 index 00000000..f1999f87 Binary files /dev/null and b/docs/images/devices/8718696485880.jpg differ diff --git a/docs/images/devices/8718696548738.jpg b/docs/images/devices/8718696548738.jpg new file mode 100755 index 00000000..b05420e0 Binary files /dev/null and b/docs/images/devices/8718696548738.jpg differ diff --git a/docs/images/devices/8718696598283.jpg b/docs/images/devices/8718696598283.jpg new file mode 100755 index 00000000..35fd450d Binary files /dev/null and b/docs/images/devices/8718696598283.jpg differ diff --git a/docs/images/devices/8718696695203.jpg b/docs/images/devices/8718696695203.jpg new file mode 100755 index 00000000..9562ea93 Binary files /dev/null and b/docs/images/devices/8718696695203.jpg differ diff --git a/docs/images/devices/900008-WW.jpg b/docs/images/devices/900008-WW.jpg new file mode 100755 index 00000000..ad814e83 Binary files /dev/null and b/docs/images/devices/900008-WW.jpg differ diff --git a/docs/images/devices/915005106701.jpg b/docs/images/devices/915005106701.jpg new file mode 100755 index 00000000..fec85c27 Binary files /dev/null and b/docs/images/devices/915005106701.jpg differ diff --git a/docs/images/devices/915005733701.jpg b/docs/images/devices/915005733701.jpg new file mode 100755 index 00000000..78d76235 Binary files /dev/null and b/docs/images/devices/915005733701.jpg differ diff --git a/docs/images/devices/9290002579A.jpg b/docs/images/devices/9290002579A.jpg new file mode 100755 index 00000000..f4a13a55 Binary files /dev/null and b/docs/images/devices/9290002579A.jpg differ diff --git a/docs/images/devices/9290011370.jpg b/docs/images/devices/9290011370.jpg new file mode 100755 index 00000000..71d2f57b Binary files /dev/null and b/docs/images/devices/9290011370.jpg differ diff --git a/docs/images/devices/9290012573A.jpg b/docs/images/devices/9290012573A.jpg new file mode 100755 index 00000000..22ba1a03 Binary files /dev/null and b/docs/images/devices/9290012573A.jpg differ diff --git a/docs/images/devices/9290012607.jpg b/docs/images/devices/9290012607.jpg new file mode 100755 index 00000000..89762d1e Binary files /dev/null and b/docs/images/devices/9290012607.jpg differ diff --git a/docs/images/devices/A6121.jpg b/docs/images/devices/A6121.jpg new file mode 100755 index 00000000..ea2488fe Binary files /dev/null and b/docs/images/devices/A6121.jpg differ diff --git a/docs/images/devices/AA68199.jpg b/docs/images/devices/AA68199.jpg new file mode 100755 index 00000000..5af7f11c Binary files /dev/null and b/docs/images/devices/AA68199.jpg differ diff --git a/docs/images/devices/AA69697.jpg b/docs/images/devices/AA69697.jpg new file mode 100755 index 00000000..abbdc893 Binary files /dev/null and b/docs/images/devices/AA69697.jpg differ diff --git a/docs/images/devices/AA70155.jpg b/docs/images/devices/AA70155.jpg new file mode 100755 index 00000000..82623908 Binary files /dev/null and b/docs/images/devices/AA70155.jpg differ diff --git a/docs/images/devices/AB3257001NJ.jpg b/docs/images/devices/AB3257001NJ.jpg new file mode 100755 index 00000000..508bce40 Binary files /dev/null and b/docs/images/devices/AB3257001NJ.jpg differ diff --git a/docs/images/devices/AB32840.jpg b/docs/images/devices/AB32840.jpg new file mode 100755 index 00000000..b6a0d704 Binary files /dev/null and b/docs/images/devices/AB32840.jpg differ diff --git a/docs/images/devices/AB35996.jpg b/docs/images/devices/AB35996.jpg new file mode 100755 index 00000000..2b76958f Binary files /dev/null and b/docs/images/devices/AB35996.jpg differ diff --git a/docs/images/devices/AB401130055.jpg b/docs/images/devices/AB401130055.jpg new file mode 100755 index 00000000..fbb9bf27 Binary files /dev/null and b/docs/images/devices/AB401130055.jpg differ diff --git a/docs/images/devices/AC01353010G.jpg b/docs/images/devices/AC01353010G.jpg new file mode 100755 index 00000000..2b51e4e1 Binary files /dev/null and b/docs/images/devices/AC01353010G.jpg differ diff --git a/docs/images/devices/AC03641.jpg b/docs/images/devices/AC03641.jpg new file mode 100755 index 00000000..d86e1975 Binary files /dev/null and b/docs/images/devices/AC03641.jpg differ diff --git a/docs/images/devices/AC03642.jpg b/docs/images/devices/AC03642.jpg new file mode 100755 index 00000000..d7428efa Binary files /dev/null and b/docs/images/devices/AC03642.jpg differ diff --git a/docs/images/devices/AC03645.jpg b/docs/images/devices/AC03645.jpg new file mode 100755 index 00000000..d13af7e7 Binary files /dev/null and b/docs/images/devices/AC03645.jpg differ diff --git a/docs/images/devices/AC03845.jpg b/docs/images/devices/AC03845.jpg new file mode 100755 index 00000000..f9813167 Binary files /dev/null and b/docs/images/devices/AC03845.jpg differ diff --git a/docs/images/devices/AC08562.jpg b/docs/images/devices/AC08562.jpg new file mode 100755 index 00000000..f86af7b7 Binary files /dev/null and b/docs/images/devices/AC08562.jpg differ diff --git a/docs/images/devices/AV2010-22.jpg b/docs/images/devices/AV2010-22.jpg new file mode 100755 index 00000000..80436f32 Binary files /dev/null and b/docs/images/devices/AV2010-22.jpg differ diff --git a/docs/images/devices/BY-165.jpg b/docs/images/devices/BY-165.jpg new file mode 100755 index 00000000..0eab667d Binary files /dev/null and b/docs/images/devices/BY-165.jpg differ diff --git a/docs/images/devices/CC2530.ROUTER.jpg b/docs/images/devices/CC2530.ROUTER.jpg new file mode 100755 index 00000000..f8d2f513 Binary files /dev/null and b/docs/images/devices/CC2530.ROUTER.jpg differ diff --git a/docs/images/devices/DJT11LM.jpg b/docs/images/devices/DJT11LM.jpg new file mode 100755 index 00000000..2d58b326 Binary files /dev/null and b/docs/images/devices/DJT11LM.jpg differ diff --git a/docs/images/devices/DL-110-N.jpg b/docs/images/devices/DL-110-N.jpg new file mode 100755 index 00000000..2a6184d3 Binary files /dev/null and b/docs/images/devices/DL-110-N.jpg differ diff --git a/docs/images/devices/DL-110-W.jpg b/docs/images/devices/DL-110-W.jpg new file mode 100755 index 00000000..2a6184d3 Binary files /dev/null and b/docs/images/devices/DL-110-W.jpg differ diff --git a/docs/images/devices/DNCKATSW001.jpg b/docs/images/devices/DNCKATSW001.jpg new file mode 100755 index 00000000..48e8fbe1 Binary files /dev/null and b/docs/images/devices/DNCKATSW001.jpg differ diff --git a/docs/images/devices/DNCKATSW002.jpg b/docs/images/devices/DNCKATSW002.jpg new file mode 100755 index 00000000..48e8fbe1 Binary files /dev/null and b/docs/images/devices/DNCKATSW002.jpg differ diff --git a/docs/images/devices/DNCKATSW003.jpg b/docs/images/devices/DNCKATSW003.jpg new file mode 100755 index 00000000..48e8fbe1 Binary files /dev/null and b/docs/images/devices/DNCKATSW003.jpg differ diff --git a/docs/images/devices/DNCKATSW004.jpg b/docs/images/devices/DNCKATSW004.jpg new file mode 100755 index 00000000..48e8fbe1 Binary files /dev/null and b/docs/images/devices/DNCKATSW004.jpg differ diff --git a/docs/images/devices/E11-G13.jpg b/docs/images/devices/E11-G13.jpg new file mode 100755 index 00000000..a9f60056 Binary files /dev/null and b/docs/images/devices/E11-G13.jpg differ diff --git a/docs/images/devices/E11-G23-E11-G33.jpg b/docs/images/devices/E11-G23-E11-G33.jpg new file mode 100755 index 00000000..f5216578 Binary files /dev/null and b/docs/images/devices/E11-G23-E11-G33.jpg differ diff --git a/docs/images/devices/E11-N1EA.jpg b/docs/images/devices/E11-N1EA.jpg new file mode 100755 index 00000000..2fd1c9c0 Binary files /dev/null and b/docs/images/devices/E11-N1EA.jpg differ diff --git a/docs/images/devices/E1603.jpg b/docs/images/devices/E1603.jpg new file mode 100755 index 00000000..47456f6c Binary files /dev/null and b/docs/images/devices/E1603.jpg differ diff --git a/docs/images/devices/F7C033.jpg b/docs/images/devices/F7C033.jpg new file mode 100755 index 00000000..df2f4f0a Binary files /dev/null and b/docs/images/devices/F7C033.jpg differ diff --git a/docs/images/devices/FB56+ZSW05HG1.2.jpg b/docs/images/devices/FB56+ZSW05HG1.2.jpg new file mode 100755 index 00000000..da69311b Binary files /dev/null and b/docs/images/devices/FB56+ZSW05HG1.2.jpg differ diff --git a/docs/images/devices/GL-C-008.jpg b/docs/images/devices/GL-C-008.jpg new file mode 100755 index 00000000..7ba03e62 Binary files /dev/null and b/docs/images/devices/GL-C-008.jpg differ diff --git a/docs/images/devices/HALIGHTDIMWWE27.jpg b/docs/images/devices/HALIGHTDIMWWE27.jpg new file mode 100755 index 00000000..f94fb240 Binary files /dev/null and b/docs/images/devices/HALIGHTDIMWWE27.jpg differ diff --git a/docs/images/devices/HS1SA.jpg b/docs/images/devices/HS1SA.jpg new file mode 100755 index 00000000..ce0a47e1 Binary files /dev/null and b/docs/images/devices/HS1SA.jpg differ diff --git a/docs/images/devices/ICPSHC24-10EU-IL-1.jpg b/docs/images/devices/ICPSHC24-10EU-IL-1.jpg new file mode 100755 index 00000000..04e9dc8b Binary files /dev/null and b/docs/images/devices/ICPSHC24-10EU-IL-1.jpg differ diff --git a/docs/images/devices/ICPSHC24-30EU-IL-1.jpg b/docs/images/devices/ICPSHC24-30EU-IL-1.jpg new file mode 100755 index 00000000..15516822 Binary files /dev/null and b/docs/images/devices/ICPSHC24-30EU-IL-1.jpg differ diff --git a/docs/images/devices/ICTC-G-1.jpg b/docs/images/devices/ICTC-G-1.jpg new file mode 100755 index 00000000..49051e23 Binary files /dev/null and b/docs/images/devices/ICTC-G-1.jpg differ diff --git a/docs/images/devices/JTQJ-BF-01LM-BW.jpg b/docs/images/devices/JTQJ-BF-01LM-BW.jpg new file mode 100755 index 00000000..3f74ae62 Binary files /dev/null and b/docs/images/devices/JTQJ-BF-01LM-BW.jpg differ diff --git a/docs/images/devices/JTYJ-GD-01LM-BW.jpg b/docs/images/devices/JTYJ-GD-01LM-BW.jpg new file mode 100755 index 00000000..030ad513 Binary files /dev/null and b/docs/images/devices/JTYJ-GD-01LM-BW.jpg differ diff --git a/docs/images/devices/K2RGBW01.jpg b/docs/images/devices/K2RGBW01.jpg new file mode 100755 index 00000000..83d43d02 Binary files /dev/null and b/docs/images/devices/K2RGBW01.jpg differ diff --git a/docs/images/devices/KS-SM001.jpg b/docs/images/devices/KS-SM001.jpg new file mode 100755 index 00000000..b80c7fbd Binary files /dev/null and b/docs/images/devices/KS-SM001.jpg differ diff --git a/docs/images/devices/KTBL01LM.jpg b/docs/images/devices/KTBL01LM.jpg new file mode 100755 index 00000000..9ee2bfd7 Binary files /dev/null and b/docs/images/devices/KTBL01LM.jpg differ diff --git a/docs/images/devices/KTBL02LM.jpg b/docs/images/devices/KTBL02LM.jpg new file mode 100755 index 00000000..993840ee Binary files /dev/null and b/docs/images/devices/KTBL02LM.jpg differ diff --git a/docs/images/devices/L1527.jpg b/docs/images/devices/L1527.jpg new file mode 100755 index 00000000..f97345c7 Binary files /dev/null and b/docs/images/devices/L1527.jpg differ diff --git a/docs/images/devices/L1528.jpg b/docs/images/devices/L1528.jpg new file mode 100755 index 00000000..ee719d66 Binary files /dev/null and b/docs/images/devices/L1528.jpg differ diff --git a/docs/images/devices/L1529.jpg b/docs/images/devices/L1529.jpg new file mode 100755 index 00000000..fec26c92 Binary files /dev/null and b/docs/images/devices/L1529.jpg differ diff --git a/docs/images/devices/LED1536G5.jpg b/docs/images/devices/LED1536G5.jpg new file mode 100755 index 00000000..ea0cabaa Binary files /dev/null and b/docs/images/devices/LED1536G5.jpg differ diff --git a/docs/images/devices/LED1537R6.jpg b/docs/images/devices/LED1537R6.jpg new file mode 100755 index 00000000..670f9843 Binary files /dev/null and b/docs/images/devices/LED1537R6.jpg differ diff --git a/docs/images/devices/LED1545G12.jpg b/docs/images/devices/LED1545G12.jpg new file mode 100755 index 00000000..48bcd3e1 Binary files /dev/null and b/docs/images/devices/LED1545G12.jpg differ diff --git a/docs/images/devices/LED1546G12.jpg b/docs/images/devices/LED1546G12.jpg new file mode 100755 index 00000000..147a99ce Binary files /dev/null and b/docs/images/devices/LED1546G12.jpg differ diff --git a/docs/images/devices/LED1622G12.jpg b/docs/images/devices/LED1622G12.jpg new file mode 100755 index 00000000..652a167a Binary files /dev/null and b/docs/images/devices/LED1622G12.jpg differ diff --git a/docs/images/devices/LED1623G12.jpg b/docs/images/devices/LED1623G12.jpg new file mode 100755 index 00000000..f7f6ac1b Binary files /dev/null and b/docs/images/devices/LED1623G12.jpg differ diff --git a/docs/images/devices/LED1624G9.jpg b/docs/images/devices/LED1624G9.jpg new file mode 100755 index 00000000..f7f6ac1b Binary files /dev/null and b/docs/images/devices/LED1624G9.jpg differ diff --git a/docs/images/devices/LED1649C5.1.jpg b/docs/images/devices/LED1649C5.1.jpg new file mode 100755 index 00000000..9932a6e0 Binary files /dev/null and b/docs/images/devices/LED1649C5.1.jpg differ diff --git a/docs/images/devices/LED1649C5.jpg b/docs/images/devices/LED1649C5.jpg new file mode 100755 index 00000000..9932a6e0 Binary files /dev/null and b/docs/images/devices/LED1649C5.jpg differ diff --git a/docs/images/devices/LED1650R5.jpg b/docs/images/devices/LED1650R5.jpg new file mode 100755 index 00000000..0b337538 Binary files /dev/null and b/docs/images/devices/LED1650R5.jpg differ diff --git a/docs/images/devices/MCCGQ01LM.jpg b/docs/images/devices/MCCGQ01LM.jpg new file mode 100755 index 00000000..d25b3c83 Binary files /dev/null and b/docs/images/devices/MCCGQ01LM.jpg differ diff --git a/docs/images/devices/MCCGQ11LM.jpg b/docs/images/devices/MCCGQ11LM.jpg new file mode 100755 index 00000000..7663d7a8 Binary files /dev/null and b/docs/images/devices/MCCGQ11LM.jpg differ diff --git a/docs/images/devices/MFKZQ01LM.jpg b/docs/images/devices/MFKZQ01LM.jpg new file mode 100755 index 00000000..6ce8ef56 Binary files /dev/null and b/docs/images/devices/MFKZQ01LM.jpg differ diff --git a/docs/images/devices/MG-AUWS01.jpg b/docs/images/devices/MG-AUWS01.jpg new file mode 100755 index 00000000..8a20454e Binary files /dev/null and b/docs/images/devices/MG-AUWS01.jpg differ diff --git a/docs/images/devices/Mega23M12.jpg b/docs/images/devices/Mega23M12.jpg new file mode 100755 index 00000000..bdb51c7d Binary files /dev/null and b/docs/images/devices/Mega23M12.jpg differ diff --git a/docs/images/devices/NL08-0800.jpg b/docs/images/devices/NL08-0800.jpg new file mode 100755 index 00000000..f503371c Binary files /dev/null and b/docs/images/devices/NL08-0800.jpg differ diff --git a/docs/images/devices/PL-110.jpg b/docs/images/devices/PL-110.jpg new file mode 100755 index 00000000..6b92dd71 Binary files /dev/null and b/docs/images/devices/PL-110.jpg differ diff --git a/docs/images/devices/PLUG-EDP-RE-DY.jpg b/docs/images/devices/PLUG-EDP-RE-DY.jpg new file mode 100755 index 00000000..b9e13ff6 Binary files /dev/null and b/docs/images/devices/PLUG-EDP-RE-DY.jpg differ diff --git a/docs/images/devices/PSS-23ZBS.jpg b/docs/images/devices/PSS-23ZBS.jpg new file mode 100755 index 00000000..bab9ffdc Binary files /dev/null and b/docs/images/devices/PSS-23ZBS.jpg differ diff --git a/docs/images/devices/QBCZ11LM.jpg b/docs/images/devices/QBCZ11LM.jpg new file mode 100755 index 00000000..52cfa3ec Binary files /dev/null and b/docs/images/devices/QBCZ11LM.jpg differ diff --git a/docs/images/devices/QBKG03LM.jpg b/docs/images/devices/QBKG03LM.jpg new file mode 100755 index 00000000..093c5262 Binary files /dev/null and b/docs/images/devices/QBKG03LM.jpg differ diff --git a/docs/images/devices/QBKG04LM.jpg b/docs/images/devices/QBKG04LM.jpg new file mode 100755 index 00000000..54a0f722 Binary files /dev/null and b/docs/images/devices/QBKG04LM.jpg differ diff --git a/docs/images/devices/QBKG11LM.jpg b/docs/images/devices/QBKG11LM.jpg new file mode 100755 index 00000000..7bb0fbc3 Binary files /dev/null and b/docs/images/devices/QBKG11LM.jpg differ diff --git a/docs/images/devices/QBKG12LM.jpg b/docs/images/devices/QBKG12LM.jpg new file mode 100755 index 00000000..093c5262 Binary files /dev/null and b/docs/images/devices/QBKG12LM.jpg differ diff --git a/docs/images/devices/RB-145.jpg b/docs/images/devices/RB-145.jpg new file mode 100755 index 00000000..d77af8b2 Binary files /dev/null and b/docs/images/devices/RB-145.jpg differ diff --git a/docs/images/devices/RB-165.jpg b/docs/images/devices/RB-165.jpg new file mode 100755 index 00000000..8d583039 Binary files /dev/null and b/docs/images/devices/RB-165.jpg differ diff --git a/docs/images/devices/RB-175-W.jpg b/docs/images/devices/RB-175-W.jpg new file mode 100755 index 00000000..c1535598 Binary files /dev/null and b/docs/images/devices/RB-175-W.jpg differ diff --git a/docs/images/devices/RB-185-C.jpg b/docs/images/devices/RB-185-C.jpg new file mode 100755 index 00000000..b852fa64 Binary files /dev/null and b/docs/images/devices/RB-185-C.jpg differ diff --git a/docs/images/devices/RB-285-C.jpg b/docs/images/devices/RB-285-C.jpg new file mode 100755 index 00000000..b07f5a4e Binary files /dev/null and b/docs/images/devices/RB-285-C.jpg differ diff --git a/docs/images/devices/RS-125.jpg b/docs/images/devices/RS-125.jpg new file mode 100755 index 00000000..432ee6ba Binary files /dev/null and b/docs/images/devices/RS-125.jpg differ diff --git a/docs/images/devices/RS-128-T.jpg b/docs/images/devices/RS-128-T.jpg new file mode 100755 index 00000000..786ce903 Binary files /dev/null and b/docs/images/devices/RS-128-T.jpg differ diff --git a/docs/images/devices/RTCGQ01LM.jpg b/docs/images/devices/RTCGQ01LM.jpg new file mode 100755 index 00000000..82f6241d Binary files /dev/null and b/docs/images/devices/RTCGQ01LM.jpg differ diff --git a/docs/images/devices/RTCGQ11LM.jpg b/docs/images/devices/RTCGQ11LM.jpg new file mode 100755 index 00000000..be207cb6 Binary files /dev/null and b/docs/images/devices/RTCGQ11LM.jpg differ diff --git a/docs/images/devices/SJCGQ11LM.jpg b/docs/images/devices/SJCGQ11LM.jpg new file mode 100755 index 00000000..9e5f9133 Binary files /dev/null and b/docs/images/devices/SJCGQ11LM.jpg differ diff --git a/docs/images/devices/SL-110-M.jpg b/docs/images/devices/SL-110-M.jpg new file mode 100755 index 00000000..c1a35753 Binary files /dev/null and b/docs/images/devices/SL-110-M.jpg differ diff --git a/docs/images/devices/SL-110-N.jpg b/docs/images/devices/SL-110-N.jpg new file mode 100755 index 00000000..c1a35753 Binary files /dev/null and b/docs/images/devices/SL-110-N.jpg differ diff --git a/docs/images/devices/SL-110-W.jpg b/docs/images/devices/SL-110-W.jpg new file mode 100755 index 00000000..c1a35753 Binary files /dev/null and b/docs/images/devices/SL-110-W.jpg differ diff --git a/docs/images/devices/ST-110.jpg b/docs/images/devices/ST-110.jpg new file mode 100755 index 00000000..53306a2c Binary files /dev/null and b/docs/images/devices/ST-110.jpg differ diff --git a/docs/images/devices/STS-PRS-251.jpg b/docs/images/devices/STS-PRS-251.jpg new file mode 100755 index 00000000..54a9b990 Binary files /dev/null and b/docs/images/devices/STS-PRS-251.jpg differ diff --git a/docs/images/devices/STSS-MULT-001.jpg b/docs/images/devices/STSS-MULT-001.jpg new file mode 100755 index 00000000..8529c894 Binary files /dev/null and b/docs/images/devices/STSS-MULT-001.jpg differ diff --git a/docs/images/devices/UC-110.jpg b/docs/images/devices/UC-110.jpg new file mode 100755 index 00000000..30cd07b6 Binary files /dev/null and b/docs/images/devices/UC-110.jpg differ diff --git a/docs/images/devices/WSDCGQ01LM.jpg b/docs/images/devices/WSDCGQ01LM.jpg new file mode 100755 index 00000000..223f8dd0 Binary files /dev/null and b/docs/images/devices/WSDCGQ01LM.jpg differ diff --git a/docs/images/devices/WSDCGQ11LM.jpg b/docs/images/devices/WSDCGQ11LM.jpg new file mode 100755 index 00000000..d85f84d4 Binary files /dev/null and b/docs/images/devices/WSDCGQ11LM.jpg differ diff --git a/docs/images/devices/WXKG01LM.jpg b/docs/images/devices/WXKG01LM.jpg new file mode 100755 index 00000000..3b16fed0 Binary files /dev/null and b/docs/images/devices/WXKG01LM.jpg differ diff --git a/docs/images/devices/WXKG02LM.jpg b/docs/images/devices/WXKG02LM.jpg new file mode 100755 index 00000000..81091138 Binary files /dev/null and b/docs/images/devices/WXKG02LM.jpg differ diff --git a/docs/images/devices/WXKG03LM.jpg b/docs/images/devices/WXKG03LM.jpg new file mode 100755 index 00000000..deda0caf Binary files /dev/null and b/docs/images/devices/WXKG03LM.jpg differ diff --git a/docs/images/devices/WXKG11LM.jpg b/docs/images/devices/WXKG11LM.jpg new file mode 100755 index 00000000..7044bfe1 Binary files /dev/null and b/docs/images/devices/WXKG11LM.jpg differ diff --git a/docs/images/devices/WXKG12LM.jpg b/docs/images/devices/WXKG12LM.jpg new file mode 100755 index 00000000..7044bfe1 Binary files /dev/null and b/docs/images/devices/WXKG12LM.jpg differ diff --git a/docs/images/devices/Z01-A19NAE26.jpg b/docs/images/devices/Z01-A19NAE26.jpg new file mode 100755 index 00000000..2c19b6df Binary files /dev/null and b/docs/images/devices/Z01-A19NAE26.jpg differ diff --git a/docs/images/devices/Z01-CIA19NAE26.jpg b/docs/images/devices/Z01-CIA19NAE26.jpg new file mode 100755 index 00000000..cba2c8ee Binary files /dev/null and b/docs/images/devices/Z01-CIA19NAE26.jpg differ diff --git a/docs/images/devices/Z809A.jpg b/docs/images/devices/Z809A.jpg new file mode 100755 index 00000000..eda5a51e Binary files /dev/null and b/docs/images/devices/Z809A.jpg differ diff --git a/docs/images/devices/ZLED-2709.jpg b/docs/images/devices/ZLED-2709.jpg new file mode 100755 index 00000000..4525b8e4 Binary files /dev/null and b/docs/images/devices/ZLED-2709.jpg differ diff --git a/docs/images/devices/ZNCZ02LM.jpg b/docs/images/devices/ZNCZ02LM.jpg new file mode 100755 index 00000000..fcf3762e Binary files /dev/null and b/docs/images/devices/ZNCZ02LM.jpg differ diff --git a/docs/images/downloader_cable.png b/docs/images/downloader_cable.png new file mode 100644 index 00000000..1240ecb1 Binary files /dev/null and b/docs/images/downloader_cable.png differ diff --git a/docs/images/home_assistant_change_name.png b/docs/images/home_assistant_change_name.png new file mode 100644 index 00000000..bea63895 Binary files /dev/null and b/docs/images/home_assistant_change_name.png differ diff --git a/docs/images/home_assistant_device_registry.png b/docs/images/home_assistant_device_registry.png new file mode 100644 index 00000000..4d714edc Binary files /dev/null and b/docs/images/home_assistant_device_registry.png differ diff --git a/docs/images/pi.jpg b/docs/images/pi.jpg new file mode 100644 index 00000000..642fb853 Binary files /dev/null and b/docs/images/pi.jpg differ diff --git a/docs/images/smartrf.png b/docs/images/smartrf.png new file mode 100644 index 00000000..390fb68c Binary files /dev/null and b/docs/images/smartrf.png differ diff --git a/docs/images/xiaomi_sensors.jpg b/docs/images/xiaomi_sensors.jpg new file mode 100644 index 00000000..fd25daca Binary files /dev/null and b/docs/images/xiaomi_sensors.jpg differ diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..68eb01b7 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,30 @@ +Welcome to the Zigbee2mqtt documentation! + +### Getting started +* [What do I need?](getting_started/what_do_i_need.md) +* [Flashing the CC2531 USB stick](getting_started/flashing_the_cc2531.md) +* [Running Zigbee2mqtt](getting_started/running_zigbee2mqtt.md) +* [Pairing devices](getting_started/pairing_devices.md) + +### Configuration +* [Configuration](configuration/configuration.md) +* [Device specific configuration](configuration/device_specific_configuration.md) + +### Integration +* [Home Assistant](integration/home_assistant.md) +* [Admin Panel for Node-Red](https://github.com/ben423423n32j14e/zigbee2mqttadminpanel) +* [Domoticz](https://github.com/stas-demydiuk/domoticz-zigbee2mqtt-plugin) + +### How tos +* [How to support new devices](how_tos/how_to_support_new_devices.md) +* [How to debug](how_tos/how_to_debug.md) +* [How to support new devices on Hass.io](how_tos/how_to_support_new_devices_on_hassio.md) + +### Information +* [Supported devices](information/supported_devices.md) +* [MQTT topics and message structure](information/mqtt_topics_and_message_structure.md) +* [Docker](information/docker.md) +* [Zigbee network](information/zigbee_network.md) +* [3D cases](information/3d_cases.md) +* [CC sniffer devices](information/cc_sniffer_devices.md) +* [Alternative flashing methods](information/alternative_flashing_methods.md) diff --git a/docs/information/3d_cases.md b/docs/information/3d_cases.md new file mode 100644 index 00000000..7b6a5ab1 --- /dev/null +++ b/docs/information/3d_cases.md @@ -0,0 +1,19 @@ +# 3D cases + +## Raspberry Pi Zero + - Blog post about a [round case for the Raspberry Pi Zero by Jens Willmer][jwillmer-blog-post]. The files can also be found on [Thingiverse][thingiverse-jwillmer-design]. + +## Raspberry Pi + - Case design for a [Raspberry Pi with hard drive and optional USB stick by Kelvin Shirley on Thingiverse][thingiverse-rpi-owncloud-design]. + +## CC2531 Zigbee dongle + - Case design for a [CC2531 Zigbee dongle][thingiverse-rpi-cc2531-dongle] + +## Alternatives +A lot of different case designs can be found via the [Thingiverse search][thingiverse-search-rpi] + +[jwillmer-blog-post]: https://jwillmer.de/blog/tools/raspberry-pi-zero-cc2531-case +[thingiverse-jwillmer-design]: https://www.thingiverse.com/thing:3101600 +[thingiverse-search-rpi]: https://www.thingiverse.com/search?q=raspberry+pi+case +[thingiverse-rpi-owncloud-design]: https://www.thingiverse.com/thing:1357022 +[thingiverse-rpi-cc2531-dongle]: https://www.thingiverse.com/thing:2803664 \ No newline at end of file diff --git a/docs/information/alternative_flashing_methods.md b/docs/information/alternative_flashing_methods.md new file mode 100644 index 00000000..faf83282 --- /dev/null +++ b/docs/information/alternative_flashing_methods.md @@ -0,0 +1,121 @@ +# Alternative flashing methods + +### Via Arduino/ESP8266 +Flashing firmware via Arduino is implemented using the project https://github.com/wavesoft/CCLib +**But with minor improvements!!!** + +[AndrewLinden](https://github.com/AndrewLinden) described that he was able to flash CC2531 using CCLib [with comments](https://github.com/wavesoft/CCLib/issues/19). + +As described [I made a fork of the CCLib library with minor changes](https://github.com/kirovilya/CCLib) for flashing firmware via Arduino: + +* Timeouts of operations +* After opening the port (I have in Windows 7) Arduino reboots and, accordingly, does not respond to requests - made a 3 seconds pause (found somewhere in internet). +* The port speed is reduced to 9600, because at another speed leaving communication errors: +`ERROR: Could not read from the serial port!` + +Flashing proccess: +1. Download and unpack the archive with the library https://github.com/kirovilya/CCLib. + +2. Flashing Arduino sketch via Arduino IDE +CCLib\Arduino\CCLib\Examples\CCLib_proxy\CCLib_proxy.ino + +**If flashing via esp8266 (wemos d1 mini), you need change connection (p. 5) and Pinout configuration in Arduino/CCLib/Examples/CCLib_proxy/CCLib_proxy.ino:** +``` +int CC_RST = 5; +int CC_DC = 4; +int CC_DD_I = 14; +int CC_DD_O = 12; +``` + +3. Install Python 2.7 or later (tested with python 2.7.13), if not installed + +4. Install pyserial 3.0.1, if not installed +`pip install -r CCLib\Python\requirements.txt` +or +`pip install pyserial==3.0.1` + +5. Connect the contacts as described https://github.com/kirovilya/CCLib#1-prepare-your-arduino-board +**But in my case, I connected completely without resistors, combined the contacts CC_DD_I and CC_DD_O together and connected to the DD pin of the DEBUG connector!** + +![](https://www.waveshare.com/img/devkit/CC-Debugger/CC-Debugger-JTAG-Header.jpg) + +I connected only 3 specified contacts and GND. During the firmware, the stick and Arduino must be connected to the USB. + +![](https://github.com/kirovilya/files/blob/master/IMG_20180111_193941.jpg) +![](https://github.com/kirovilya/files/blob/master/IMG_20180111_193923.jpg) +![](https://github.com/kirovilya/files/blob/master/IMG_20180110_234401.jpg) + +6. After that, try to get information about the chip - if it works, then the connection is correct (example for COM9 port - Arduino port): + +``` +C:\Projects\CCLib\Python>python cc_info.py -p COM9 +INFO: Found a CC2531 chip on COM9 + +Chip information: + Chip ID : 0xb524 + Flash size : 256 Kb + Page size : 2 Kb + SRAM size : 8 Kb + USB : Yes + +Device information: + IEEE Address : 00124b0014aa + PC : 0000 + +Debug status: + [ ] CHIP_ERASE_BUSY + [ ] PCON_IDLE + [X] CPU_HALTED + [ ] PM_ACTIVE + [ ] HALT_STATUS + [ ] DEBUG_LOCKED + [X] OSCILLATOR_STABLE + [ ] STACK_OVERFLOW + +Debug config: + [ ] SOFT_POWER_MODE + [ ] TIMERS_OFF + [X] DMA_PAUSE + [X] TIMER_SUSPEND +``` +[Another example of connection on MacOS](https://github.com/wavesoft/CCLib/issues/22#issuecomment-384452424) + +7. If everything is successful, then download [modified firmware for flashing via Arduino](https://github.com/kirovilya/files/blob/master/CC2531ZNP-Pro-Secure_LinkKeyJoin_mod.hex) + +8. Start the flashing firmware (it takes a long time, about 2-3 hours): + +``` +C:\Projects\ZigBee>python cc_write_flash.py -e -p COM9 --in=CC2531ZNP-Pro-Secure_LinkKeyJoin_mod.hex +INFO: Found a CC2531 chip on COM9 + +Chip information: + Chip ID : 0xb524 + Flash size : 256 Kb + Page size : 2 Kb + SRAM size : 8 Kb + USB : Yes +Sections in CC2531ZNP-Pro-Secure_LinkKeyJoin_mod.hex: + + Addr. Size +-------- ------------- + 0x0000 8176 B + 0x1ff6 10 B + 0x3fff0 1 B + 0x2000 239616 B + +This is going to ERASE and REPROGRAM the chip. Are you sure? : y + +Flashing: + - Chip erase... + - Flashing 4 memory blocks... + -> 0x0000 : 8176 bytes + Progress 100%... OK + -> 0x1ff6 : 10 bytes + Progress 100%... OK + -> 0x3fff0 : 1 bytes + Progress 100%... OK + -> 0x2000 : 239616 bytes + Progress 100%... OK + +Completed +``` \ No newline at end of file diff --git a/docs/information/cc_sniffer_devices.md b/docs/information/cc_sniffer_devices.md new file mode 100644 index 00000000..22c4d50f --- /dev/null +++ b/docs/information/cc_sniffer_devices.md @@ -0,0 +1,19 @@ +# CC sniffer devices + +Zigbee2mqtt supports several CC2530 and CC2531 devices. Both can be used as a router or coordinator. +A discussion of these devices can be found [here](https://github.com/Koenkk/zigbee2mqtt/issues/52). +For more information about a coordinator and routers can be found [here](zigbee_network.md). + +## How to flash +- [CC2530 based devices](http://ptvo.info/how-to-select-and-flash-cc2530-144/) +- [CC2531 based devices](../getting_started/flashing_the_cc2531.md) + +## Supported devices + +| Device| Description | Firmware | Example | Link | +| --- | --- | --- | --- | --- | +| **CC2531** | (_Default Option_). USB connected Zigbee sniffer based on CC2531 with PCB antenna and no RF frontend. A very cheap option but has limited range (~30m line of sight) | [Coordinator firmware](https://github.com/Koenkk/Z-Stack-firmware/tree/master/coordinator/CC2531/bin)

[Router firmware](https://github.com/Koenkk/Z-Stack-firmware/tree/master/router/CC2531/bin) | ![CC2531](../images/cc2531.jpg) | [Texas Instruments](http://www.ti.com/tool/cc2531emk)

[Aliexpress](http://www.aliexpress.com/w/wholesale-cc2531.html) | | +| **CC2530** | Serial connected Zigbee sniffer based on CC2530 with either PCB antenna OR external antenna, and no RF frontend. A very cheap option with potentially increased range with external antenna (~50-60m line of sight). More difficult to connect unless paired with serial-USB | [Coordinator firmware](https://github.com/Koenkk/Z-Stack-firmware/tree/master/coordinator/CC2530/bin)

[Router firmware](https://github.com/Koenkk/Z-Stack-firmware/tree/master/router/CC2530/bin) | ![CC2530](../images/cc2530.jpg) | [Aliexpress](http://www.aliexpress.com/wholesale?catId=0&initiative_id=SB_20181213104041&SearchText=cc2530) | +| **CC2530 + CC2591** | Serial connected Zigbee sniffer based on CC2530 with CC2591 RF frontend and external antenna. A more expensive option with increased range (~50-60m line of sight) and higher sensitivity. More difficult to connect unless paired with serial-USB | [Coordinator firmware](https://github.com/Koenkk/Z-Stack-firmware/tree/master/coordinator/CC2530_CC2591/bin)

[Router firmware](https://github.com/Koenkk/Z-Stack-firmware/tree/master/router/CC2530_CC2591/bin) |![CC2530 + CC2591](../images/cc2530_cc2591.jpg) | [Aliexpress](http://www.aliexpress.com/wholesale?catId=0&initiative_id=SB_20181213104521&SearchText=cc2530+cc2591) | +| **CC2530 with RFX2401** | Serial connected Zigbee sniffer based on CC2530 with RFX2401 RF frontend and external antenna. A more expensive option with increased range (~50-60m line of sight) and higher sensitivity. More difficult to connect unless paired with serial-USB (such as the example shown). **Note** that for the GBAN unit shown it is necessary to connect P04, P06 and P20 to GND - see [here](https://github.com/Koenkk/zigbee2mqtt/issues/52#issuecomment-391115143)| [Coordinator firmware (same as CC2530 + CC2591)](https://github.com/Koenkk/Z-Stack-firmware/tree/master/coordinator/CC2530_CC2591/bin)

[Router firmware (same as CC2530 + CC2591)](https://github.com/Koenkk/Z-Stack-firmware/tree/master/router/CC2530_CC2591/bin) | ![CC2530 with RFX2401](../images/cc2530_rfx2401.png) | [GBAN](http://www.gban.cn/en/product_show.asp?id=43)

[Aliexpress](http://www.aliexpress.com/wholesale?catId=0&initiative_id=SB_20181213104722&SearchText=cc2530+rf) | + diff --git a/docs/information/docker.md b/docs/information/docker.md new file mode 100644 index 00000000..c37f8159 --- /dev/null +++ b/docs/information/docker.md @@ -0,0 +1,50 @@ +# Docker +It is possible to run Zigbee2mqtt in a Docker container using the official [Zigbee2mqtt Docker image](https://hub.docker.com/r/koenkk/zigbee2mqtt/). + +First run the container, this will create the configuration directory. Change `configuration.yaml` according to your situation and start again. + +### Parameters +* `-v $(pwd)/data:/app/data`: Directory where Zigbee2mqtt stores it configuration +* `--device=/dev/ttyACM0`: Location of CC2531 USB sniffer + +## Supported architectures +### amd64 +```bash +docker run \ + -it \ + -v $(pwd)/data:/app/data \ + --device=/dev/ttyACM0 \ + koenkk/zigbee2mqtt +``` + +### arm32v6 (E.G. Raspberry Pi) +```bash +docker run \ + -it \ + -v $(pwd)/data:/app/data \ + --device=/dev/ttyACM0 \ + koenkk/zigbee2mqtt:arm32v6 +``` + +### arm64v8 +```bash +docker run \ + -it \ + -v $(pwd)/data:/app/data \ + --device=/dev/ttyACM0 \ + koenkk/zigbee2mqtt:arm64v8 +``` + +## Updating +To update to the latest Docker image: +```bash +docker rm -f [ZIGBEE2MQTT_CONTAINER_NAME] +docker rmi -f [ZIGBEE2MQTT_IMAGE_NAME] # e.g. koenkk/zigbee2mqtt:arm32v6 +# Now run the container again, Docker will automatically pull the latest image. +``` + +## Tags +The following tags are available: +- Latest release version: `latest`, `arm32v6`, `arm64v8` +- Latest dev version (based on [`dev`](https://github.com/Koenkk/zigbee2mqtt/tree/dev) branch): `latest-dev`, `arm32v6-dev`, `arm64v8-dev` +- Locked to a specific release version: `X.X.X` (e.g. `0.2.0`), `X.X.X-arm32v6` (e.g. `0.2.0-arm32v6`), `X.X.X-arm64v8` (e.g. `0.2.0-arm64v8`) \ No newline at end of file diff --git a/docs/information/mqtt_topics_and_message_structure.md b/docs/information/mqtt_topics_and_message_structure.md new file mode 100644 index 00000000..8de85d4b --- /dev/null +++ b/docs/information/mqtt_topics_and_message_structure.md @@ -0,0 +1,140 @@ +# MQT topics and message structure + +This page describes which MQTT topics are used by Zigbee2mqtt. Note that the base topic (by default `zigbee2mqtt`) is configurable in the [Zigbee2mqtt `configuration.yaml`](../configuration/configuration.md). + +## zigbee2mqtt/bridge/state +zigbee2mqtt publishes the bridge state to this topic. Possible message are: +* `"online"`: published when the bridge is running (on startup) +* `"offline"`: published right before the bridge stops + +## zigbee2mqtt/bridge/log +zigbee2mqtt will output log to this endpoint. Message are always in the form of `{"type":"TYPE","message":"MESSAGE"}`. Possible message types are: +* `"pairing"`: logging when device is connecting to the network. +* `"device_connected"`: send when a new device connects to the network. +* `"device_removed"`: send when a device is removed from the network. +* `"devices"`: a list of all devices, this message can be triggered by sending a message to `zigbee2mqtt/bridge/config/devices` (payload doesn't matter). + +## zigbee2mqtt/bridge/config/permit_join +Allows you to permit joining of new devices via MQTT. This is not persistent (will not be saved to `configuration.yaml`). Possible messages are: +* `"true"`: permit joining of new devices +* `"false"`: disable joining of new devices + +## zigbee2mqtt/bridge/config/log_level +Allows you to switch the `log_level` during runtime. This is not persistent (will not be saved to `configuration.yaml`). Possible payloads are: `"debug"`, `"info"`, `"warn"`, `"error"`. + +## zigbee2mqtt/bridge/config/remove +Allows you to remove devices from the network. Payload should be the `friendly_name`, e.g. `0x00158d0001b79111`. On successful remove a [`device_removed`](https://github.com/Koenkk/zigbee2mqtt/wiki/MQTT-topics-and-message-structure#zigbee2mqttbridgelog) message is send. + +## zigbee2mqtt/bridge/config/rename +Allows you to change the `friendly_name` of a device on the fly. +Format should be: `{"old": "OLD_FRIENDLY_NAME", "new": "NEW_FRIENDLY_NAME"}`. + +## zigbee2mqtt/bridge/networkmap +Allows you to retrieve a map of your zigbee network. Possible payloads are `raw`, `graphviz`. Zigbee2mqtt will send the networkmap to `zigbee2mqtt/bridge/networkmap/[graphviz OR raw]`. + +## zigbee2mqtt/[DEVICE_ID] +Where `[DEVICE_ID]` is E.G. `0x00158d0001b79111`. Message published to this topic are **always** in a JSON format. Each device produces a different JSON message, **some** examples: + +**Xiaomi MiJia temperature & humidity sensor (WSDCGQ01LM)** +```json +{ + "temperature": 27.34, + "humidity": 44.72 +} +``` + +**Xiaomi MiJia wireless switch (WXKG01LM)** +```json +{ + "click": "double" +} +``` + +**Xiaomi MiJia human body movement sensor (RTCGQ01LM)** +```json +{ + "occupancy": true +} +``` + +**IKEA TRADFRI LED bulb E27 980 lumen, dimmable, white spectrum, opal white (LED1545G12)** +```json +{ + "state": "ON", + "brightness": 215, + "color_temp": 325 +} +``` + +## zigbee2mqtt/[DEVICE_ID]/set +Publishing messages to this topic allows you to control your Zigbee devices via MQTT. Only accepts JSON messages. An example to control a Philips Hue Go (7146060PH). + +```json +{ + "state": "ON", // Or "OFF", "TOGGLE" + "brightness": 255, + "color_temp": 155, + "color": { + // XY color + "x": 0.123, + "y": 0.123, + + // OR + + // RGB color + "r": 46, + "g": 102, + "b": 193 + }, + + // Blinks the bulbs, possible values: + // - "select": single blink + // - "lselect": blinking for a longer time + // - "none": stop blinking + "alert": "select", + + // Specifies the number of seconds the transition to this state takes (0 by default). + "transition": 3, +} +``` + +`transition` specifies the number of seconds the transition to this state takes (0 by default). + +Remove attributes which are not supported for your device. E.G. in case of a Xiaomi Mi power plug ZigBee (ZNCZ02LM) only send the `"state"` attribute. + +## homeassistant/[DEVICE_TYPE]/[DEVICE_ID]/[OBJECT_ID]/config +Only used when `homeassistant: true` in `configuration.yaml`. Required for [Home Assistant MQTT discovery](https://www.home-assistant.io/docs/mqtt/discovery/). + +## Device specific +Device specific commands are always send to the topic: `zigbee2mqtt/[DEVICE_ID]/set`. Below you will find the possible payloads. + +### Xiaomi Aqara vibration sensor (DJT11LM) +Set the sensitivity of the sensor. **NOTE:** As this device is sleeping most of the time, right before sending this command press the button on the device. +```json +{ + "sensitivity": "medium" // Possible values: 'low', 'medium', 'high' +} +``` + +### Xiaomi MiJia gas leak detector (JTQJBF01LMBW) +Set/read the sensitivity of the sensor. +```json +{ + "sensitivity": "medium" // Possible values; to set: 'low', 'medium', 'high'; to read: 'read' +} +``` + +Execute selftest +```json +{ + "selftest": "" +} +``` + +### SmartThings arrival sensor (STS-PRS-251) +Let the device beep. +```json +{ + "beep": 5 +} +``` \ No newline at end of file diff --git a/docs/information/supported_devices.md b/docs/information/supported_devices.md new file mode 100644 index 00000000..29b8515a --- /dev/null +++ b/docs/information/supported_devices.md @@ -0,0 +1,292 @@ +# Supported devices + +*NOTE: This file has been generated, do not edit this file manually!* + +Currently **137** devices are supported from **29** different vendors. + +In case you own a Zigbee device which is **NOT** listed here, please see +[How to support new devices](https://github.com/Koenkk/zigbee2mqtt/wiki/How-to-support-new-devices). + +### Belkin + +| Model | Description | Picture | +| ------------- | ------------- | -------------------------- | +| F7C033 | Belkin WeMo smart LED bulb (on/off, brightness) | ![../images/devices/F7C033.jpg](../images/devices/F7C033.jpg) | + +### Bitron Home + +| Model | Description | Picture | +| ------------- | ------------- | -------------------------- | +| AV2010/22 | Bitron Home Wireless motion detector (occupancy) | ![../images/devices/AV2010-22.jpg](../images/devices/AV2010-22.jpg) | + +### Centralite + +| Model | Description | Picture | +| ------------- | ------------- | -------------------------- | +| 4256251-RZHAC | Centralite White Swiss power outlet switch with power meter (switch and power meter) | ![../images/devices/4256251-RZHAC.jpg](../images/devices/4256251-RZHAC.jpg) | + +### Climax + +| Model | Description | Picture | +| ------------- | ------------- | -------------------------- | +| PSS-23ZBS | Climax Power plug (on/off) | ![../images/devices/PSS-23ZBS.jpg](../images/devices/PSS-23ZBS.jpg) | + +### Commercial Electric + +| Model | Description | Picture | +| ------------- | ------------- | -------------------------- | +| 53170161 | Commercial Electric Matte White Recessed Retrofit Smart Led Downlight - 4 Inch (on/off, brightness, color temperature) | ![../images/devices/53170161.jpg](../images/devices/53170161.jpg) | + +### Custom devices (DiY) + +| Model | Description | Picture | +| ------------- | ------------- | -------------------------- | +| CC2530.ROUTER | Custom devices (DiY) [CC2530 router](http://ptvo.info/cc2530-based-zigbee-coordinator-and-router-112/) (state, description, type, rssi) | ![../images/devices/CC2530.ROUTER.jpg](../images/devices/CC2530.ROUTER.jpg) | +| DNCKATSW001 | Custom devices (DiY) [DNCKAT single key wired wall light switch](https://github.com/dzungpv/dnckatsw00x/) (on/off) | ![../images/devices/DNCKATSW001.jpg](../images/devices/DNCKATSW001.jpg) | +| DNCKATSW002 | Custom devices (DiY) [DNCKAT double key wired wall light switch](https://github.com/dzungpv/dnckatsw00x/) (hold/release, on/off) | ![../images/devices/DNCKATSW002.jpg](../images/devices/DNCKATSW002.jpg) | +| DNCKATSW003 | Custom devices (DiY) [DNCKAT triple key wired wall light switch](https://github.com/dzungpv/dnckatsw00x/) (hold/release, on/off) | ![../images/devices/DNCKATSW003.jpg](../images/devices/DNCKATSW003.jpg) | +| DNCKATSW004 | Custom devices (DiY) [DNCKAT quadruple key wired wall light switch](https://github.com/dzungpv/dnckatsw00x/) (hold/release, on/off) | ![../images/devices/DNCKATSW004.jpg](../images/devices/DNCKATSW004.jpg) | + +### Dresden Elektronik + +| Model | Description | Picture | +| ------------- | ------------- | -------------------------- | +| Mega23M12 | Dresden Elektronik ZigBee Light Link wireless electronic ballast (on/off, brightness, color temperature, color xy) | ![../images/devices/Mega23M12.jpg](../images/devices/Mega23M12.jpg) | + +### EDP + +| Model | Description | Picture | +| ------------- | ------------- | -------------------------- | +| PLUG EDP RE:DY | EDP re:dy plug (on/off, power measurement) | ![../images/devices/PLUG-EDP-RE-DY.jpg](../images/devices/PLUG-EDP-RE-DY.jpg) | + +### GE + +| Model | Description | Picture | +| ------------- | ------------- | -------------------------- | +| 22670 | GE Link smart LED light bulb, BR30 soft white (2700K) (on/off, brightness) | ![../images/devices/22670.jpg](../images/devices/22670.jpg) | +| 45852GE | GE ZigBee plug-in smart dimmer (on/off, brightness) | ![../images/devices/45852GE.jpg](../images/devices/45852GE.jpg) | +| 45857GE | GE ZigBee in-wall smart dimmer (on/off, brightness) | ![../images/devices/45857GE.jpg](../images/devices/45857GE.jpg) | + +### Gledopto + +| Model | Description | Picture | +| ------------- | ------------- | -------------------------- | +| GL-C-008 | Gledopto Zigbee LED controller RGB + CCT / RGBW / WWCW / Dimmer (on/off, brightness, color temperature, color xy) | ![../images/devices/GL-C-008.jpg](../images/devices/GL-C-008.jpg) | + +### HEIMAN + +| Model | Description | Picture | +| ------------- | ------------- | -------------------------- | +| HS1SA | HEIMAN Smoke detector (smoke) | ![../images/devices/HS1SA.jpg](../images/devices/HS1SA.jpg) | + +### Hive + +| Model | Description | Picture | +| ------------- | ------------- | -------------------------- | +| HALIGHTDIMWWE27 | Hive Active light dimmable (on/off, brightness) | ![../images/devices/HALIGHTDIMWWE27.jpg](../images/devices/HALIGHTDIMWWE27.jpg) | + +### IKEA + +| Model | Description | Picture | +| ------------- | ------------- | -------------------------- | +| LED1545G12 | IKEA TRADFRI LED bulb E26/E27 980 lumen, dimmable, white spectrum, opal white (on/off, brightness, color temperature) | ![../images/devices/LED1545G12.jpg](../images/devices/LED1545G12.jpg) | +| LED1546G12 | IKEA TRADFRI LED bulb E26/E27 950 lumen, dimmable, white spectrum, clear (on/off, brightness, color temperature) | ![../images/devices/LED1546G12.jpg](../images/devices/LED1546G12.jpg) | +| LED1623G12 | IKEA TRADFRI LED bulb E27 1000 lumen, dimmable, opal white (on/off, brightness) | ![../images/devices/LED1623G12.jpg](../images/devices/LED1623G12.jpg) | +| LED1537R6 | IKEA TRADFRI LED bulb GU10 400 lumen, dimmable, white spectrum (on/off, brightness, color temperature) | ![../images/devices/LED1537R6.jpg](../images/devices/LED1537R6.jpg) | +| LED1650R5 | IKEA TRADFRI LED bulb GU10 400 lumen, dimmable (on/off, brightness) | ![../images/devices/LED1650R5.jpg](../images/devices/LED1650R5.jpg) | +| LED1536G5 | IKEA TRADFRI LED bulb E12/E14 400 lumen, dimmable, white spectrum, opal white (on/off, brightness, color temperature) | ![../images/devices/LED1536G5.jpg](../images/devices/LED1536G5.jpg) | +| LED1622G12 | IKEA TRADFRI LED bulb E26 1000 lumen, dimmable, opal white (on/off, brightness) | ![../images/devices/LED1622G12.jpg](../images/devices/LED1622G12.jpg) | +| LED1624G9 | IKEA TRADFRI LED bulb E27/E26 600 lumen, dimmable, color, opal white (on/off, brightness, color temperature, color xy) | ![../images/devices/LED1624G9.jpg](../images/devices/LED1624G9.jpg) | +| LED1649C5 | IKEA TRADFRI LED bulb E12/E14/E17 400 lumen, dimmable warm white, chandelier opal (on/off, brightness) | ![../images/devices/LED1649C5.jpg](../images/devices/LED1649C5.jpg) | +| ICTC-G-1 | IKEA TRADFRI wireless dimmer (brightness [0-255], quick rotate for instant 0/255) | ![../images/devices/ICTC-G-1.jpg](../images/devices/ICTC-G-1.jpg) | +| ICPSHC24-10EU-IL-1 | IKEA TRADFRI driver for wireless control (10 watt) (on/off, brightness) | ![../images/devices/ICPSHC24-10EU-IL-1.jpg](../images/devices/ICPSHC24-10EU-IL-1.jpg) | +| ICPSHC24-30EU-IL-1 | IKEA TRADFRI driver for wireless control (30 watt) (on/off, brightness) | ![../images/devices/ICPSHC24-30EU-IL-1.jpg](../images/devices/ICPSHC24-30EU-IL-1.jpg) | +| L1527 | IKEA FLOALT LED light panel, dimmable, white spectrum (30x30 cm) (on/off, brightness, color temperature) | ![../images/devices/L1527.jpg](../images/devices/L1527.jpg) | +| L1529 | IKEA FLOALT LED light panel, dimmable, white spectrum (60x60 cm) (on/off, brightness, color temperature) | ![../images/devices/L1529.jpg](../images/devices/L1529.jpg) | +| L1528 | IKEA FLOALT LED light panel, dimmable, white spectrum (30x90 cm) (on/off, brightness, color temperature) | ![../images/devices/L1528.jpg](../images/devices/L1528.jpg) | +| E1603 | IKEA TRADFRI control outlet (on/off) | ![../images/devices/E1603.jpg](../images/devices/E1603.jpg) | + +### Innr + +| Model | Description | Picture | +| ------------- | ------------- | -------------------------- | +| RB 185 C | Innr E27 Bulb RGBW (on/off, brightness, color temperature, color xy) | ![../images/devices/RB-185-C.jpg](../images/devices/RB-185-C.jpg) | +| RB 285 C | Innr E27 Bulb RGBW (on/off, brightness, color temperature, color xy) | ![../images/devices/RB-285-C.jpg](../images/devices/RB-285-C.jpg) | +| RB 165 | Innr E27 Bulb (on/off, brightness) | ![../images/devices/RB-165.jpg](../images/devices/RB-165.jpg) | +| RB 175 W | Innr E27 Bulb warm dimming (on/off, brightness) | ![../images/devices/RB-175-W.jpg](../images/devices/RB-175-W.jpg) | +| RS 125 | Innr GU10 Spot (on/off, brightness) | ![../images/devices/RS-125.jpg](../images/devices/RS-125.jpg) | +| RS 128 T | Innr GU10 Spot 350 lm, dimmable, white spectrum (on/off, brightness, color temperature) | ![../images/devices/RS-128-T.jpg](../images/devices/RS-128-T.jpg) | +| RB 145 | Innr E14 Candle (on/off, brightness) | ![../images/devices/RB-145.jpg](../images/devices/RB-145.jpg) | +| BY 165 | Innr B22 Bulb dimmable (on/off, brightness) | ![../images/devices/BY-165.jpg](../images/devices/BY-165.jpg) | +| PL 110 | Innr Puck Light (on/off, brightness) | ![../images/devices/PL-110.jpg](../images/devices/PL-110.jpg) | +| ST 110 | Innr Strip Light (on/off, brightness) | ![../images/devices/ST-110.jpg](../images/devices/ST-110.jpg) | +| UC 110 | Innr Under Cabinet Light (on/off, brightness) | ![../images/devices/UC-110.jpg](../images/devices/UC-110.jpg) | +| DL 110 N | Innr Spot narrow (on/off, brightness) | ![../images/devices/DL-110-N.jpg](../images/devices/DL-110-N.jpg) | +| DL 110 W | Innr Spot wide (on/off, brightness) | ![../images/devices/DL-110-W.jpg](../images/devices/DL-110-W.jpg) | +| SL 110 N | Innr Spot Flex narrow (on/off, brightness) | ![../images/devices/SL-110-N.jpg](../images/devices/SL-110-N.jpg) | +| SL 110 M | Innr Spot Flex medium (on/off, brightness) | ![../images/devices/SL-110-M.jpg](../images/devices/SL-110-M.jpg) | +| SL 110 W | Innr Spot Flex wide (on/off, brightness) | ![../images/devices/SL-110-W.jpg](../images/devices/SL-110-W.jpg) | + +### Iris + +| Model | Description | Picture | +| ------------- | ------------- | -------------------------- | +| 3210-L | Iris Smart plug (on/off) | ![../images/devices/3210-L.jpg](../images/devices/3210-L.jpg) | +| 3326-L | Iris Motion sensor (occupancy and temperature) | ![../images/devices/3326-L.jpg](../images/devices/3326-L.jpg) | +| 3320-L | Iris Contact sensor (contact) | ![../images/devices/3320-L.jpg](../images/devices/3320-L.jpg) | + +### JIAWEN + +| Model | Description | Picture | +| ------------- | ------------- | -------------------------- | +| K2RGBW01 | JIAWEN Wireless Bulb E27 9W RGBW (on/off, brightness, color temperature, color xy) | ![../images/devices/K2RGBW01.jpg](../images/devices/K2RGBW01.jpg) | + +### Ksentry Electronics + +| Model | Description | Picture | +| ------------- | ------------- | -------------------------- | +| KS-SM001 | Ksentry Electronics [Zigbee OnOff Controller](http://ksentry.manufacturer.globalsources.com/si/6008837134660/pdtl/ZigBee-module/1162731630/zigbee-on-off-controller-modules.htm) (on/off) | ![../images/devices/KS-SM001.jpg](../images/devices/KS-SM001.jpg) | + +### Nanoleaf + +| Model | Description | Picture | +| ------------- | ------------- | -------------------------- | +| NL08-0800 | Nanoleaf Smart Ivy Bulb E27 (on/off, brightness) | ![../images/devices/NL08-0800.jpg](../images/devices/NL08-0800.jpg) | + +### Netvox + +| Model | Description | Picture | +| ------------- | ------------- | -------------------------- | +| Z809A | Netvox Power socket with power consumption monitoring (on/off, power measurement) | ![../images/devices/Z809A.jpg](../images/devices/Z809A.jpg) | + +### Nue + +| Model | Description | Picture | +| ------------- | ------------- | -------------------------- | +| FB56+ZSW05HG1.2 | Nue ZigBee one gang smart switch (on/off) | ![../images/devices/FB56+ZSW05HG1.2.jpg](../images/devices/FB56+ZSW05HG1.2.jpg) | +| MG-AUWS01 | Nue ZigBee Double GPO (on/off) | ![../images/devices/MG-AUWS01.jpg](../images/devices/MG-AUWS01.jpg) | + +### OSRAM + +| Model | Description | Picture | +| ------------- | ------------- | -------------------------- | +| 4058075816718 | OSRAM SMART+ outdoor wall lantern RGBW (on/off, brightness, color temperature, color xy) | ![../images/devices/4058075816718.jpg](../images/devices/4058075816718.jpg) | +| AA69697 | OSRAM Classic A60 RGBW (on/off, brightness, color temperature, color xy) | ![../images/devices/AA69697.jpg](../images/devices/AA69697.jpg) | +| AC03645 | OSRAM LIGHTIFY LED CLA60 E27 RGBW (on/off, brightness, color temperature, color xy) | ![../images/devices/AC03645.jpg](../images/devices/AC03645.jpg) | +| AC03642 | OSRAM SMART+ CLASSIC A 60 TW (on/off, brightness, color temperature) | ![../images/devices/AC03642.jpg](../images/devices/AC03642.jpg) | +| AA70155 | OSRAM LIGHTIFY LED A19 tunable white / Classic A60 TW (on/off, brightness, color temperature) | ![../images/devices/AA70155.jpg](../images/devices/AA70155.jpg) | +| AA68199 | OSRAM LIGHTIFY LED PAR16 50 GU10 tunable white (on/off, brightness, color temperature) | ![../images/devices/AA68199.jpg](../images/devices/AA68199.jpg) | +| AB32840 | OSRAM LIGHTIFY LED Classic B40 tunable white (on/off, brightness, color temperature) | ![../images/devices/AB32840.jpg](../images/devices/AB32840.jpg) | +| 4058075816794 | OSRAM Smart+ Ceiling TW (on/off, brightness, color temperature) | ![../images/devices/4058075816794.jpg](../images/devices/4058075816794.jpg) | +| AC03641 | OSRAM LIGHTIFY LED Classic A60 clear (on/off, brightness) | ![../images/devices/AC03641.jpg](../images/devices/AC03641.jpg) | +| 4052899926158 | OSRAM LIGHTIFY Surface Light TW (on/off, brightness) | ![../images/devices/4052899926158.jpg](../images/devices/4052899926158.jpg) | +| AB401130055 | OSRAM LIGHTIFY Surface Light LED Tunable White (on/off, brightness, color temperature) | ![../images/devices/AB401130055.jpg](../images/devices/AB401130055.jpg) | +| AB3257001NJ | OSRAM Smart+ plug (on/off) | ![../images/devices/AB3257001NJ.jpg](../images/devices/AB3257001NJ.jpg) | +| 4052899926110 | OSRAM Flex RGBW (on/off, brightness, color temperature, color xy) | ![../images/devices/4052899926110.jpg](../images/devices/4052899926110.jpg) | +| 4058075036185 | OSRAM Outdoor Flex RGBW (on/off, brightness, color temperature, color xy) | ![../images/devices/4058075036185.jpg](../images/devices/4058075036185.jpg) | +| 4058075036147 | OSRAM Smart+ Gardenpole RGBW (on/off, brightness, color temperature, color xy) | ![../images/devices/4058075036147.jpg](../images/devices/4058075036147.jpg) | +| AB35996 | OSRAM Smart+ Spot GU10 Multicolor (on/off, brightness, color temperature, color xy) | ![../images/devices/AB35996.jpg](../images/devices/AB35996.jpg) | +| AC08562 | OSRAM SMART+ Candle E14 Dimmable White (on/off, brightness) | ![../images/devices/AC08562.jpg](../images/devices/AC08562.jpg) | +| AC01353010G | OSRAM SMART+ Motion Sensor (occupancy and temperature) | ![../images/devices/AC01353010G.jpg](../images/devices/AC01353010G.jpg) | + +### Paulmann + +| Model | Description | Picture | +| ------------- | ------------- | -------------------------- | +| 50045 | Paulmann SmartHome Zigbee LED-stripe (on/off, brightness) | ![../images/devices/50045.jpg](../images/devices/50045.jpg) | +| 50049 | Paulmann SmartHome Yourled RGB Controller (on/off, brightness, color xy) | ![../images/devices/50049.jpg](../images/devices/50049.jpg) | + +### Philips + +| Model | Description | Picture | +| ------------- | ------------- | -------------------------- | +| 7299760PH | Philips Hue Bloom (on/off, brightness, color xy) | ![../images/devices/7299760PH.jpg](../images/devices/7299760PH.jpg) | +| 7146060PH | Philips Hue Go (on/off, brightness, color temperature, color xy) | ![../images/devices/7146060PH.jpg](../images/devices/7146060PH.jpg) | +| 433714 | Philips Hue Lux A19 bulb E27 (on/off, brightness) | ![../images/devices/433714.jpg](../images/devices/433714.jpg) | +| 9290011370 | Philips Hue white A60 bulb E27 (on/off, brightness) | ![../images/devices/9290011370.jpg](../images/devices/9290011370.jpg) | +| 8718696449691 | Philips Hue White Single bulb B22 (on/off, brightness) | ![../images/devices/8718696449691.jpg](../images/devices/8718696449691.jpg) | +| 7299355PH | Philips Hue white and color ambiance LightStrip (on/off, brightness, color xy) | ![../images/devices/7299355PH.jpg](../images/devices/7299355PH.jpg) | +| 915005106701 | Philips Hue white and color ambiance LightStrip plus (on/off, brightness, color temperature, color xy) | ![../images/devices/915005106701.jpg](../images/devices/915005106701.jpg) | +| 9290012573A | Philips Hue white and color ambiance E26/E27/E14 (on/off, brightness, color temperature, color xy) | ![../images/devices/9290012573A.jpg](../images/devices/9290012573A.jpg) | +| 9290002579A | Philips Hue white and color ambiance BR30 (on/off, brightness, color temperature, color xy) | ![../images/devices/9290002579A.jpg](../images/devices/9290002579A.jpg) | +| 8718696485880 | Philips Hue white and color ambiance GU10 (on/off, brightness, color temperature, color xy) | ![../images/devices/8718696485880.jpg](../images/devices/8718696485880.jpg) | +| 915005733701 | Philips Hue White and color ambiance Play Lightbar (on/off, brightness, color temperature, color xy) | ![../images/devices/915005733701.jpg](../images/devices/915005733701.jpg) | +| 8718696695203 | Philips Hue white ambiance E14 (on/off, brightness, color temperature) | ![../images/devices/8718696695203.jpg](../images/devices/8718696695203.jpg) | +| 8718696598283 | Philips Hue white ambiance GU10 (on/off, brightness, color temperature) | ![../images/devices/8718696598283.jpg](../images/devices/8718696598283.jpg) | +| 8718696548738 | Philips Hue white ambiance E26/E27 (on/off, brightness, color temperature) | ![../images/devices/8718696548738.jpg](../images/devices/8718696548738.jpg) | +| 3261030P7 | Philips Hue Being (on/off, brightness, color temperature) | ![../images/devices/3261030P7.jpg](../images/devices/3261030P7.jpg) | +| 3216331P5 | Philips Philips Hue White ambiance Aurelle Rectangle Panel Light (on/off, brightness, color temperature) | ![../images/devices/3216331P5.jpg](../images/devices/3216331P5.jpg) | +| 7199960PH | Philips Hue Iris (on/off, brightness, color xy) | ![../images/devices/7199960PH.jpg](../images/devices/7199960PH.jpg) | +| 324131092621 | Philips Hue dimmer switch (on/off) | ![../images/devices/324131092621.jpg](../images/devices/324131092621.jpg) | +| 9290012607 | Philips Hue motion sensor (occupancy, temperature, illuminance) | ![../images/devices/9290012607.jpg](../images/devices/9290012607.jpg) | + +### Sengled + +| Model | Description | Picture | +| ------------- | ------------- | -------------------------- | +| E11-G13 | Sengled Element Classic (A19) (on/off, brightness) | ![../images/devices/E11-G13.jpg](../images/devices/E11-G13.jpg) | +| E11-G23/E11-G33 | Sengled Element Classic (A60) (on/off, brightness) | ![../images/devices/E11-G23-E11-G33.jpg](../images/devices/E11-G23-E11-G33.jpg) | +| Z01-CIA19NAE26 | Sengled Element Touch (A19) (on/off, brightness) | ![../images/devices/Z01-CIA19NAE26.jpg](../images/devices/Z01-CIA19NAE26.jpg) | +| Z01-A19NAE26 | Sengled Element Plus (A19) (on/off, brightness, color temperature) | ![../images/devices/Z01-A19NAE26.jpg](../images/devices/Z01-A19NAE26.jpg) | +| E11-N1EA | Sengled Element Plus Color (A19) (on/off, brightness, color temperature, color xy) | ![../images/devices/E11-N1EA.jpg](../images/devices/E11-N1EA.jpg) | + +### SmartThings + +| Model | Description | Picture | +| ------------- | ------------- | -------------------------- | +| STSS-MULT-001 | SmartThings SmartSense multi sensor (contact) | ![../images/devices/STSS-MULT-001.jpg](../images/devices/STSS-MULT-001.jpg) | +| STS-PRS-251 | SmartThings SmartThings arrival sensor (presence) | ![../images/devices/STS-PRS-251.jpg](../images/devices/STS-PRS-251.jpg) | + +### Sylvania + +| Model | Description | Picture | +| ------------- | ------------- | -------------------------- | +| 73742 | Sylvania LIGHTIFY LED adjustable white RT 5/6 (on/off, brightness, color temperature) | ![../images/devices/73742.jpg](../images/devices/73742.jpg) | +| 73740 | Sylvania LIGHTIFY LED adjustable white BR30 (on/off, brightness, color temperature) | ![../images/devices/73740.jpg](../images/devices/73740.jpg) | +| 73693 | Sylvania LIGHTIFY LED RGBW A19 (on/off, brightness, color temperature, color xy) | ![../images/devices/73693.jpg](../images/devices/73693.jpg) | +| 74283 | Sylvania LIGHTIFY LED soft white dimmable A19 (on/off, brightness) | ![../images/devices/74283.jpg](../images/devices/74283.jpg) | +| 74696 | Sylvania LIGHTIFY LED soft white dimmable A19 (on/off, brightness) | ![../images/devices/74696.jpg](../images/devices/74696.jpg) | +| 72922-A | Sylvania SMART+ Smart Plug (on/off) | ![../images/devices/72922-A.jpg](../images/devices/72922-A.jpg) | +| 74282 | Sylvania Smart Home adjustable white MR16 LED bulb (on/off, brightness, color temperature) | ![../images/devices/74282.jpg](../images/devices/74282.jpg) | + +### Trust + +| Model | Description | Picture | +| ------------- | ------------- | -------------------------- | +| ZLED-2709 | Trust Smart Dimmable LED Bulb (on/off, brightness) | ![../images/devices/ZLED-2709.jpg](../images/devices/ZLED-2709.jpg) | + +### Xiaomi + +| Model | Description | Picture | +| ------------- | ------------- | -------------------------- | +| WXKG01LM | Xiaomi MiJia wireless switch (single, double, triple, quadruple, many, long, long_release click) | ![../images/devices/WXKG01LM.jpg](../images/devices/WXKG01LM.jpg) | +| WXKG11LM | Xiaomi Aqara wireless switch (single, double click (and triple, quadruple, hold, release depending on model)) | ![../images/devices/WXKG11LM.jpg](../images/devices/WXKG11LM.jpg) | +| WXKG12LM | Xiaomi Aqara wireless switch (with gyroscope) (single, double, shake, hold, release) | ![../images/devices/WXKG12LM.jpg](../images/devices/WXKG12LM.jpg) | +| WXKG03LM | Xiaomi Aqara single key wireless wall switch (single click) | ![../images/devices/WXKG03LM.jpg](../images/devices/WXKG03LM.jpg) | +| WXKG02LM | Xiaomi Aqara double key wireless wall switch (left, right and both click) | ![../images/devices/WXKG02LM.jpg](../images/devices/WXKG02LM.jpg) | +| QBKG04LM | Xiaomi Aqara single key wired wall switch (on/off) | ![../images/devices/QBKG04LM.jpg](../images/devices/QBKG04LM.jpg) | +| QBKG11LM | Xiaomi Aqara single key wired wall switch (on/off, power measurement) | ![../images/devices/QBKG11LM.jpg](../images/devices/QBKG11LM.jpg) | +| QBKG03LM | Xiaomi Aqara double key wired wall switch (release/hold, on/off) | ![../images/devices/QBKG03LM.jpg](../images/devices/QBKG03LM.jpg) | +| QBKG12LM | Xiaomi Aqara double key wired wall switch (on/off, power measurement) | ![../images/devices/QBKG12LM.jpg](../images/devices/QBKG12LM.jpg) | +| WSDCGQ01LM | Xiaomi MiJia temperature & humidity sensor (temperature and humidity) | ![../images/devices/WSDCGQ01LM.jpg](../images/devices/WSDCGQ01LM.jpg) | +| WSDCGQ11LM | Xiaomi Aqara temperature, humidity and pressure sensor (temperature, humidity and pressure) | ![../images/devices/WSDCGQ11LM.jpg](../images/devices/WSDCGQ11LM.jpg) | +| RTCGQ01LM | Xiaomi MiJia human body movement sensor (occupancy) | ![../images/devices/RTCGQ01LM.jpg](../images/devices/RTCGQ01LM.jpg) | +| RTCGQ11LM | Xiaomi Aqara human body movement and illuminance sensor (occupancy and illuminance) | ![../images/devices/RTCGQ11LM.jpg](../images/devices/RTCGQ11LM.jpg) | +| MCCGQ01LM | Xiaomi MiJia door & window contact sensor (contact) | ![../images/devices/MCCGQ01LM.jpg](../images/devices/MCCGQ01LM.jpg) | +| MCCGQ11LM | Xiaomi Aqara door & window contact sensor (contact) | ![../images/devices/MCCGQ11LM.jpg](../images/devices/MCCGQ11LM.jpg) | +| SJCGQ11LM | Xiaomi Aqara water leak sensor (water leak true/false) | ![../images/devices/SJCGQ11LM.jpg](../images/devices/SJCGQ11LM.jpg) | +| MFKZQ01LM | Xiaomi Mi/Aqara smart home cube (shake, wakeup, fall, tap, slide, flip180, flip90, rotate_left and rotate_right) | ![../images/devices/MFKZQ01LM.jpg](../images/devices/MFKZQ01LM.jpg) | +| ZNCZ02LM | Xiaomi Mi power plug ZigBee (on/off, power measurement) | ![../images/devices/ZNCZ02LM.jpg](../images/devices/ZNCZ02LM.jpg) | +| QBCZ11LM | Xiaomi Aqara socket Zigbee (on/off, power measurement) | ![../images/devices/QBCZ11LM.jpg](../images/devices/QBCZ11LM.jpg) | +| JTYJ-GD-01LM/BW | Xiaomi MiJia Honeywell smoke detector (smoke) | ![../images/devices/JTYJ-GD-01LM-BW.jpg](../images/devices/JTYJ-GD-01LM-BW.jpg) | +| JTQJ-BF-01LM/BW | Xiaomi MiJia gas leak detector (gas) | ![../images/devices/JTQJ-BF-01LM-BW.jpg](../images/devices/JTQJ-BF-01LM-BW.jpg) | +| A6121 | Xiaomi Vima Smart Lock (inserted, forgotten, key error) | ![../images/devices/A6121.jpg](../images/devices/A6121.jpg) | +| DJT11LM | Xiaomi Aqara vibration sensor (drop, tilt and touch) | ![../images/devices/DJT11LM.jpg](../images/devices/DJT11LM.jpg) | + +### ilux + +| Model | Description | Picture | +| ------------- | ------------- | -------------------------- | +| 900008-WW | ilux Dimmable A60 E27 LED Bulb (on/off, brightness) | ![../images/devices/900008-WW.jpg](../images/devices/900008-WW.jpg) | + + diff --git a/docs/information/zigbee_network.md b/docs/information/zigbee_network.md new file mode 100644 index 00000000..e2cc59ab --- /dev/null +++ b/docs/information/zigbee_network.md @@ -0,0 +1,34 @@ +# Zigbee network + +## Device types +In Zigbee, there are three different types of devices: end device, router, and coordinator. A Zigbee network always has **one** (and no more) coordinator, and can have multiple routers and end devices. In the case of zigbee2mqtt, the coordinator is your CC2531 USB stick. + +### End Device +End devices do not route traffic. They may also sleep, which makes end devices a suitable choice for battery operated devices. + +*Examples: WXKG01LM, RTCGQ01LM, MCCGQ11LM* + +### Router +Routers are responsible for routing traffic between different nodes. Routers may not sleep. As such, routers are not a suitable choice for battery operated devices. Routers are also responsible for receiving and storing messages intended for their children. In addition to this, routers are the gate keepers to the network. They are responsible for allowing new nodes to join the network. + +*Examples: LED1545G12, 7146060PH, ZNCZ02LM, [CC2531 USB sniffer flashed with the router firmware](https://github.com/Koenkk/Z-Stack-firmware/tree/master/router/CC2531/bin)* + + +### Coordinator +A coordinator is a special router. In addition to all of the router capabilities, the coordinator is responsible for forming the network. To do that, it must select the appropriate channel, PAN ID, and extended network address. It is also responsible for selecting the security mode of the network. + +*Examples: [CC2531 USB sniffer flashed with the coordinator firmware](https://github.com/Koenkk/Z-Stack-firmware/tree/master/coordinator/CC2531/bin)* + +### Finding out the type of your device +Zigbee2mqtt logs the device type of your devices on startup, e.g.: +``` +2018-5-28 20:39:46 INFO 0x00158d00018255df (0x00158d00018255df): ZNCZ02LM - Xiaomi Mi power plug ZigBee (Router) +2018-5-28 20:39:46 INFO 0x00158d0001b79111 (0x00158d0001b79111): WSDCGQ01LM - Xiaomi MiJia temperature & humidity sensor (EndDevice) +``` + +## Network size +The [CC2531 USB sniffer coordinator firmware](https://github.com/Koenkk/Z-Stack-firmware/tree/master/coordinator/CC2531/bin) has a limit of 20 **direct** children. This means 1 coordinator + 20 end devices and 0 routers. + +However by adding routers to your network you can overcome the limit of 20 devices. This means that, e.g. a network of 1 coordinator, 4 routers and 50 end devices is possible. + +The number of childs that a router support differs per device! Therefore, the increased size of a network by adding a router is arbitrary. diff --git a/docs/integration/home_assistant.md b/docs/integration/home_assistant.md new file mode 100644 index 00000000..50f2162b --- /dev/null +++ b/docs/integration/home_assistant.md @@ -0,0 +1,2060 @@ +# 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 +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' +``` + +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/