From 56ea61be3e8fa91fed9291451043e3d2f4c517d6 Mon Sep 17 00:00:00 2001 From: Koen Kanters Date: Thu, 13 Dec 2018 21:40:47 +0100 Subject: [PATCH] Fix docs tests. --- docgen/docgen.js | 4 +- docgen/integrating-with-homeassistant.js | 191 +- docgen/supported-devices.js | 6 +- docs/integrating-with-homeassistant.md | 2223 ---------------------- docs/integration/home_assistant.md | 920 +++++++-- docs/supported-devices.md | 290 --- test/docgen.test.js | 4 +- 7 files changed, 940 insertions(+), 2698 deletions(-) delete mode 100644 docs/integrating-with-homeassistant.md delete mode 100644 docs/supported-devices.md diff --git a/docgen/docgen.js b/docgen/docgen.js index 3bf04755e..64b84b3ea 100644 --- a/docgen/docgen.js +++ b/docgen/docgen.js @@ -6,5 +6,5 @@ const base = path.join(__dirname, '..', 'docs'); const supportDevices = require('./supported-devices'); const integratingWithHomeassistant = require('./integrating-with-homeassistant'); -fs.writeFileSync(path.join(base, 'supported-devices.md'), supportDevices); -fs.writeFileSync(path.join(base, 'integrating-with-homeassistant.md'), integratingWithHomeassistant); +fs.writeFileSync(path.join(base, 'information', 'supported_devices.md'), supportDevices); +fs.writeFileSync(path.join(base, 'integration', 'home_assistant.md'), integratingWithHomeassistant); diff --git a/docgen/integrating-with-homeassistant.js b/docgen/integrating-with-homeassistant.js index 6da7b1d09..58747cf76 100644 --- a/docgen/integrating-with-homeassistant.js +++ b/docgen/integrating-with-homeassistant.js @@ -7,20 +7,22 @@ const HomeassistantExtension = require('../lib/extension/homeassistant'); const homeassistant = new HomeassistantExtension(null, null, null, null); const YAML = require('json2yaml'); -let template = `*NOTE: This file has been generated, do not edit this file manually!* +let template = `# Home Assistant -If you're hosting zigbee2mqtt using [this hassio addon-on](https://github.com/danielwelch/hassio-zigbee2mqtt) use their -documentation on how to configure. +*NOTE 1: This file has been generated, do not edit this file manually!* -The easiest way to integrate zigbee2mqtt with Home Assistant is by using -[MQTT discovery](https://www.home-assistant.io/docs/mqtt/discovery/).' +*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 **Zigbee2mqtt** \`configuration.yaml\` set \`homeassistant: true\` - In your **Home Assistant** \`configuration.yaml\`: - - \`\`\`yaml mqtt: discovery: true @@ -33,13 +35,34 @@ mqtt: 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. +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 @@ -48,16 +71,150 @@ automation: topic: 'zigbee2mqtt/