Integrate components Zigbee a Home Assistant by zigbee2mqtt (part 2)

8 minutes of reading
PURPOSES OF THE GUIDE:
CONCEPTS FACED:
  • Software use and configuration
SOFTWARE COMPONENTS USED:
Prerequisites:
PHYSICAL DEVICES USED:
  • The computer on which it resides Home Assistant
  • the component ZigBee to be integrated
GUIDE more indicated for:

All environments

Notes and disclaimer
  • qualsiasi eventuale modifica agli impianti domestici dev'essere progettata ed realizzata SOLO da personale qualificato;
  • any changes implemented in probefore is a propersonal responsibility as well as a profirst risk and danger (the contents of the present page are purely educational);
  • any changes implemented in proprior to a device it voids the guarantee, quality approvals and certifications.
Driving review: 1.1

Abstract

Il proProtocol ZigBee.

As sappIAMO the interoperability with desktop between components based on this protocollo but of different typology and different proproducers it is often - indeed, almost always - a proBlema. There are indeed very interesting components but very different lines between them and, not being able to think of buying a BRIDGE/Gateway for each of the lines proonce you have learned, you are often faced with the choice of having to "settle" for a line promade by giving up perhaps other single components that we would be interested in introducing in home automation.

More proof this situation is often the impossibility of integrating the BRIDGE/Gateway (and therefore the components ZigBee connected to it) with proprio personale HUB, as in the case of that of the line LUMI Aqara - were it not that, fortunately, the (very valid) components of this line are manageable even from the gateway Xiaomi Mijia, who can be integrated with Home Assistant. When of the components ZigBee they are not otherwise controllable if not with "proprio " gateway (maybe not integrable with ours Home Assistant), essentially they become useless, if not in the context of proits ecosystem and its proman app phones.

To save goat and cabbage exists a great solution, or that of implementing a BRIDGE/Gateway ZigBee↔︎TCP/IP divorced from the logic of the individual proproducers: the answer is given by the synergy of zigbee2mqtt (software component) the USB dongle CC2531 (hardware component), a combination that allows to survey the highest number of components ZigBee possible bypassing i proproblems mentioned above. Obviously, such BRIDGE/Gateway "Standard" is pienamecan be integrated with Home Assistant.

In this guide we will see what the steps are to integrate a component ZigBee su Home Assistant using appgreasy zigbee2mqtt which BRIDGE/Gateway, which means already installed and configured.

Nb This guide, "partners 2“, Serves to understand how to integrate the components ZigBee a Home Assistant. The "partners 1”Instead illustrates how to install and configure zigbee2mqtt (conditio sine qua non for prosurrender with the present). This "1 part guide" is available to users who have Home Assistant installed as applicensee on Raspbian or that they use the distribution HASSIO.

Nb Alternative to the binomial zigbee2mqtt + CC2531 is the adoption of deCONZ+ConBee/RaspBee, not the subject of this specific guide.

It starts

How it works

First di profollow, ask yourself the question: do I know MQTT? If the answer is yes, well, otherwise provvedere to an approfoundation on this proProtocol. The guide takes for granted that, when referring to MQTT commands and telemetry, yesappwhat we are talking about, at least in broad terms.

Therefore, how it works zigbee2mqtt, and because it allows us to integrate components ZigBee?
Arrived so far it should already be clear, but if it were not, repetita iuvant.

zigbee2mqtt allows, through the antenna CC2531, to act as a bridge between the proProtocol ZigBee and the protocollo MQTT; the latter is well understood and managed by Home Assistant, which thus manages to integrate any components ZigBee compatible with zigbee2mqtt. This "bridging" means "translating" the proProtocol ZigBee in MQTT messages, to and from the component.

Il proCessus server of zigbee2mqtt it is itself an MQTT client therefore, to control its behavior and that of its components ZigBee connected to it, it goes without saying that MQTT messages are used.

When connecting a component ZigBee a zigbee2mqtt (procedura of pairing), it records - so to speak - the unique identity, thus generating a set of telemetry and MQTT commands from and to the component. From here on, his job will be finished. When a telemetry arrives via ZigBee from the component (for example, a temperature from a thermal sensor), will publish on the broker MQTT the telemetry message, obviously "baptized" with the "name" of the component that generated it. Since zigbee2mqtt will also have subscribed on the broker the command topics for that component, if an MQTT command is published on the broker zigbee2mqtt will receive it and turn it to the component via zigbee. And so on.

Therefore, it is clear how zigbee2mqtt does not connect directly to Home Assistant, but limit yourself to "talking" with the MQTT broker.

Home Assistant, for its part, it is also connected to the MQTT broker: if the autodiscovery is active (which we recommend activating in the "1 part" of the guide), at the first publication on the broker by zigbee2mqtt of the availability of a new component ZigBee through it surveyed (communicated with a special MQTT "presentation" message, so to speak), Home Assistant proit sees to automatically create some entity which, of course, will receive states and send commands via MQTT in the logic described above.

zigbee2mqtt architecture

Pairing

Il pairing, or the association of a device ZigBee with zigbee2mqtt, this is done by setting the latter in this specific mode. To do this it is possible to pursue two paths:

  • set it "fixed", so that the BRIDGE/Gateway is always listening to new components (strongly discouraged);
  • activate it temporarily:
    • vi manual control;
    • via interface.
PAIRING FIXED

To ensure that zigbee2mqtt is perpetually active in the mode pairing (but we strongly advise against it as a matter of performance and correct functionnamento) is necessary:

  • su Home Assistant installed as applicense on Rasbian, edit the file "opt/zigbee2mqtt/data/configuration.yaml"Setting to"true" the field "permit_join"And then restarting the service (command from terminal"sudo systemctl restart zigbee2mqtt");
  • su HASSIO, change the configuration of theadd-on (stopping it, first) by setting to "true" the field "permit_join"(And then save and restart theadd-on).

At this point (after restarting the service / of theadd-on) simply press the button pairing placed on the component ZigBee to integrate (refer to the official documentation of the component itself to find out how to activate the pairing) and wait a few seconds. The component, if compatible with zigbee2mqtt, will be integrated into the BRIDGE/Gateway.

PAIRING TEMPORARY

To temporarily activate the mode pairing side zigbee2mqtt must be published a specific MQTT command on brokers. This command is usually:

zigbee2mqtt/bridge/config/permit_join true

while that to interrupt the mode of pairing:

zigbee2mqtt/bridge/config/permit_join false

To send this MQTT command it is possible:

  • do it manually via client MQTT;
  • send it automatically via the interface Home Assistant.

To do it Manually you can use any client MQTT connected to the broker or the client Home Assistant at its interface ("Developer tools">"MQTT“).

If instead it has followed literally the "1 part" of this guide (see the links in theAbstract) you can activate automatically the mode of pairing simply by activating the switch "Zigbee2mqtt Main join", Which other does not - under the hood - send the MQTT commands mentioned above:

Home Assistant  -  zigbee2mqtt mqin join switch

For the following two minutes (as per timer “Time remaining") It will be possible to connect to BRIDGE/Gateway a new component ZigBee: at this point it will be sufficient to press the button pairing placed on the component ZigBee to integrate (refer to the official documentation of the component itself to find out how to activate the pairing) and wait a few seconds. The component, if compatible with zigbee2mqtt, will be integrated into the BRIDGE/Gateway.

Nb Temporary paring - although recommended - can sometimes cause proproblems, the most typical is that of not allowing the members ZigBee that you try to integrate to enter the network. In case, use the pairing fixed.

Home Assistant

As explained before, after it happened pairing zigbee2mqtt "presents" this new component via an MQTT message published to the broker, after which it begins to turn any MQTT telemetry and to listen for any MQTT commands destined to that component.

AUTOMATIC INTEGRATION

If the guide "starts 1" (see the links in theAbstract) was performed literally, Home Assistant gather - thanks to the presence of the MQTT auto-discovery - the "presentation" message of the component published by zigbee2mqtt, which contains all the "coordinates" of configurations useful forHUB to generate entities that will exploit the telemetry and the commands to and from the component (conveyed via MQTT) appena integrated. This is the easiest and most highly recommended route.

To recap: Is Home Assistant has activated the auto-disocovery MQTT (as indicated to do in the "part 1" of the guide), subsequently the pairing of a component ZigBee with zigbee2mqtt appnew entities will be at theHUB so automatic.

For example, here is the list of entities deriving from the integration of a Xiaomi thermal sensor:

Home Assistant - Xiaomi temperature sensor away zigbee2mqtt

Given that no "Friendly name”Is attributed to the entity, at the frontend Lovelace UI the names given are the original ones. As we read in the image, all the entities have a name that begins with "0x0 ...", stretch distinctive of the entities integrated via zigbee2mqtt (it's not just a matter of culture: it's something you need to know later).

Nb Su HASSIO it is possible to "discover" the names automatically assigned to the components integrated in the "HASSIO">"Dashboard">"zigbee2mqtt"And, at the bottom of the card, check the" new entry "via the LOG.
MANUAL INTEGRATION

Where - for reasons that may be the most diverse starting from the desire for personalization pushed - you don't want to use auto-discovery, zigbee2mqtt leaves the user the freedom to configure, as he sees fit, the proentity at Home Assistant.

To do this, refer tol database of supported components: every component has la profirst list of codes to add to the configuration di Home Assistant.

In the case of the above sensor, used as an example, the reference card it's this one: in his case, the code is:

sensor:
  - platform: "mqtt"
    state_topic: "zigbee2mqtt/NOME_COMPONENTE"
    availability_topic: "zigbee2mqtt/bridge/state"
    unit_of_measurement: "°C"
    device_class: "temperature"
    value_template: "{{ value_json.temperature }}"

sensor:
  - platform: "mqtt"
    state_topic: "zigbee2mqtt/NOME_COMPONENTE"
    availability_topic: "zigbee2mqtt/bridge/state"
    unit_of_measurement: "%"
    device_class: "humidity"
    value_template: "{{ value_json.humidity }}"

sensor:
  - platform: "mqtt"
    state_topic: "zigbee2mqtt/NOME_COMPONENTE"
    availability_topic: "zigbee2mqtt/bridge/state"
    unit_of_measurement: "hPa"
    device_class: "pressure"
    value_template: "{{ value_json.pressure }}"

sensor:
  - platform: "mqtt"
    state_topic: "zigbee2mqtt/NOME_COMPONENTE"
    availability_topic: "zigbee2mqtt/bridge/state"
    unit_of_measurement: "%"
    device_class: "battery"
    value_template: "{{ value_json.battery }}"

sensor:
  - platform: "mqtt"
    state_topic: "zigbee2mqtt/NOME_COMPONENTE"
    availability_topic: "zigbee2mqtt/bridge/state"
    unit_of_measurement: "-"
    value_template: "{{ value_json.linkquality }}"

Obviously the "name_of_component”Will be customized with the string used by zigbee2mqtt to "christen" the component; in the example above it would be "0x00158d0002f2dccc"

To discover this string it is necessary to listen to the MQTT broker by consulting all the messages that pass to understand what the name is; if you use RRaspbian (and Mosquitto), a typical command could be the following:

mosquitto_sub -d -v -t +/# -h localhost -u username -P password | grep zigbee2mqtt

Otherwise, it is possible for the same purpose to use any MQTT client to connect to the MQTT broker and subscribe to the messages "zigbee2mqtt / #”(That is“ all those that begin with 'zigbee2mqtt'").

Cancellation

Cancel: depends what is meant. It is one thing to cancel the entity at Home Assistant, it is one thing to remove the pairing of a component ZigBee presso zigbee2mqtt.

In the first case, the practice to be performed varies depending on how it was created: automatically (via auto-discovery) or manually (via manual configuration). In the latter case, to eliminate the entity from theHUB (but not from zigbee2mqtt) simply remove the manual configuration and restart Home Assistant. In the first case (auto-discovery) it is necessary to remove the pairing of the component at zigbee2mqtt.

To remove the pairing of a component it is necessary to send to zigbee2mqtt, through mqtt, a specific command:

zigbee2mqtt/bridge/config/remove NOME_COMPONENTE

where, of course, the "name_of_component”Is the string with which the component is named by zigbee2mqtt.

To send this MQTT command it is possible:

  • do it manually via client MQTT;
  • send it automatically via the interface Home Assistant.

To do it Manually you can use any client MQTT connected to the broker or the client Home Assistant at its interface ("Developer tools">"MQTT“).

If instead it has followed literally the "1 part" of this guide (see the links in theAbstract) you can activate automatically the mode of de-pairing simply by activating the switch "Zigbee2mqtt Remove", Which other does not - under the hood - send the MQTT command mentioned above:

Home Assistant  -  zigbee2mqtt remove

Obviously, before clicking "RUN”It will be necessary to insert, in the text field, the name of the component to be removed (instead of "unknown“).

In summary and concluding:

  • users configured for auto-discovery can simply remove the parining;
  • manually configured users must first remove the configuration at Home Assisatnt related to the component to be removed, then they can remove the pairing.


Home Assistant Official LogoATTENZIONE: remember that there is on our FORUM community an ad hoc section dedicated to Home Assistant, for any doubt, question, information on the specific merit of these components.

inDomus telegram channel