From 7259f3f2d50ebd5e7fb19bd0094a4ba38a3c4782 Mon Sep 17 00:00:00 2001 From: fredlcore Date: Fri, 8 Nov 2024 13:58:36 +0800 Subject: [PATCH] Added examples for Home Assistant --- docs/EN/homeautomation.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/docs/EN/homeautomation.md b/docs/EN/homeautomation.md index f2b02a0a..c4a95b16 100644 --- a/docs/EN/homeautomation.md +++ b/docs/EN/homeautomation.md @@ -12,22 +12,23 @@ BSB-LAN provides four ways to connect to home automation systems: ## Exchanging data via MQTT This is the recommended way to connect BSB-LAN to home automation systems because it allows seamless exchange of data. -As a prerequisite, a MQTT broker (such as [mosquitto](https://mosquitto.org) is needed, either running locally or via making use of a public service. Some home automation systems such as Home Assistant offer the installation of mosquitto as part of their software. +As a prerequisite, a MQTT broker (such as [mosquitto](https://mosquitto.org)) is needed, either running locally or via making use of a public service. Some home automation systems such as Home Assistant offer the installation of mosquitto as part of their software. -**Attention:** Currently, the mosquitto broker seems to have an issue with handling larger numbers of messages from versions 2.0.16 onwards ([see this bug report](https://github.com/eclipse-mosquitto/mosquitto/issues/2887)). If you encounter the problem that your BSB-LAN entities become "unavailable", especially after using the auto-discovery feature above, please downgrade to mosquitto version 2.0.15. However, be aware that this version has security issues, so make sure that your broker runs at least in a firewalled environment. +**Attention:** Currently, the mosquitto broker seems to have an issue with handling larger numbers of messages from versions 2.0.16 onwards ([see this bug report](https://github.com/eclipse-mosquitto/mosquitto/issues/2887)). If you encounter the problem that your BSB-LAN entities become "unavailable", especially after using the auto-discovery feature below, please downgrade to mosquitto version 2.0.15. However, be aware that this version has security issues, so make sure that your broker runs at least in a firewalled environment. In BSB-LAN, you need to make or enable at least the following configurations: - Set **Logging mode** (additionally) to **Send to MQTT Broker**. - Set **Log Interval** to the time (in seconds) you want the log parameters to be published. - Select up to 20 **Log Parameters** you want to be sent to your home automation system. -- Set **MQTT Usage** to **plain text** -- Set **MQTT Broker Server** to the hostname of your MQTT broker (such as the mosquitto server) +- Set **MQTT Usage** to **plain text**. +- Set **MQTT Broker Server** to the hostname of your MQTT broker (such as the mosquitto server). -If your home automation system supports MQTT auto-discovery (as is the case with Home Assistant), you can call URL command `/M1` and BSB-LAN will send auto-discovery messages for **all available parameters** to the MQTT broker and thus to the home automation system. You may have to clean up afterwards or send a removal message for all these parameters using URL command `/M0`. -Every time a query is made in BSB-LAN or a parameter changes its value through the room unit, the new value will be sent to the MQTT broker, so even changes made outside of BSB-LAN should be updated into the home automation system, which is why the MQTT approach is the recommended way to connect to a home automation system. +If your home automation system supports MQTT auto-discovery (as is the case with Home Assistant), you can call URL command `/M1!` and BSB-LAN will send auto-discovery messages for **all available parameters** from device ID `` to the MQTT broker and thus to the home automation system. You may have to clean up afterwards or send a removal message for all these parameters using URL command `/M0!` if you don't want to use this feature anymore. -Here is a link to a [video in the BSB-LAN YouTube channel](https://youtu.be/DbHEiWm5nBs) that shows how to set up BSB-LAN in Home Assistant using the auto-discovery feature of Home Assistant. +Additionally, every time a URL query is made to BSB-LAN, or a parameter is changed through the room unit, the respective values of these parameters will be sent to the MQTT broker. So even changes made outside of BSB-LAN are sent to the home automation system, which is why the MQTT approach is the recommended way to connect to a home automation system. +So, as an alternative to the built-in logging feature of BSB-LAN, you can also just periodically call a URL with the parameters you want to see updated. Since these parameters will also be sent to the MQTT broker, your home automation system will receive them as well. +For example, if you periodically call the URL `http://bsb-lan.local/700/8700`, both the operating mode of heat circuit 1 (parameter 700) as well as the current outside temperature (parameter 8700) will be sent to the MQTT broker. Examples for querying or setting parameters via MQTT would look like this (using mosquitto): Query the outside temperature (parameter 8700): @@ -50,7 +51,9 @@ For some systems, specific modules exist that can be used to access BSB-LAN seam ### Home Assistant While the official plugin no longer works, the MQTT approach above works well with Home Assistant. -For the details of the implementation, you may also refer to these tutorials: +Here is a link to a [video in the BSB-LAN YouTube channel](https://youtu.be/DbHEiWm5nBs) that shows how to set up BSB-LAN in Home Assistant using the auto-discovery feature of Home Assistant. + +For further details of the implementation, you may also refer to these tutorials: GitHub user @ryann72 wrote detailed instructions for [BSB-LAN and HomeAssistant/Mosquitto](https://github.com/ryann72/Home-assistant-tutoriel/blob/main/BSB-LAN/tutoriel%20BSB-LAN%20English.md). It is also available in [French](https://github.com/ryann72/Home-assistant-tutoriel/blob/main/BSB-LAN/tutoriel%20BSB-LAN.md).