From 220241863f4ac2424156a7c699b472e914f4a23b Mon Sep 17 00:00:00 2001 From: fredlcore Date: Wed, 10 Jul 2024 01:11:02 +0800 Subject: [PATCH] Clarifications --- docs/EN/README.md | 2 +- docs/EN/bus_systems.md | 5 +++-- docs/EN/configure.md | 4 ++-- docs/EN/install.md | 4 ++-- docs/EN/troubleshooting.md | 13 +++++++------ 5 files changed, 15 insertions(+), 13 deletions(-) diff --git a/docs/EN/README.md b/docs/EN/README.md index 55ae330d..f184bfca 100644 --- a/docs/EN/README.md +++ b/docs/EN/README.md @@ -1,7 +1,7 @@ # What is BSB-LAN?
[BSB-LAN is a software](https://www.bsb-lan.de)/hardware solution for accessing the [“Boiler-System-Bus” (BSB)][BSB], the [“Local-Process-Bus (LPB)”][LPB] and the [“Punkt-zu-Punkt-Schnittstelle” (PPS)][PPS]. The BSB-LAN hardware is available for various *ESP32*-based microcontrollers (ESP32 NodeMCU, Olimex EVB, Olimex POE-ISO) as well as for an *Arduino Due* with Ethernet shield. It allows accessing the heating systems from Atlantic, Brötje, Elco and many other manufacturers via LAN/WLAN, provided that they use one of the Siemens controllers listed below. -BSB-LAN makes it possible to monitor and control the heating and log any given values. This project supports almost all parameters available on the heating systems and can be a more comprehensive and cost-effective alternative to the OZW 672, OCI 700 or Remocon Net B. +BSB-LAN makes it possible to monitor and control the heating system and log any given values. This project supports almost all parameters available on the heating systems and can be a more comprehensive and cost-effective alternative to the OZW 672, OCI 700 or Remocon Net B. Optional [integration into existing smart home systems](homeautomation.md) such as [Home Assistant][HomeAssistant], [ioBroker][ioBroker], [openHAB][openHAB], [Node-RED][NodeRED], [Homebridge][Homebridge], [Jeedom][Jeedom], [SmartHomeNG][SmartHomeNG], [Volkszähler][Volkszaehler], [FHEM][FHEM], [HomeMatic][Homematic], Loxone, IP-Symcon or EDOMI is possible via [MQTT][MQTT], [JSON][JSON] or [HTTP access][using-en]. The adapter can also be used as a standalone logger without LAN or Internet connection when using a microSD card. diff --git a/docs/EN/bus_systems.md b/docs/EN/bus_systems.md index 1012d2a4..b2d51d4b 100644 --- a/docs/EN/bus_systems.md +++ b/docs/EN/bus_systems.md @@ -35,11 +35,12 @@ Except for some Weishaut heaters, room units are not connected to the heating sy [](){#PPS} ## The Point-to-Point Interface (PPS) -The Point-to-Point Interface (PPS deriving from the German term "Punkt-zu-Punkt Schnittstelle") is compatible to the other systems on a physical layer, but not in the way message telegrams are being exchanged. While BSB and LPB talk to each other by sending telegrams and acknowledging their receipt respectively, PPS is dominated by the heating unit. The heating unit constantly sends its data to the room unit and tells the room unit when and what kind of information it should send. It is a very timing sensitive protocol, therefore long other tasks that BSB-LAN is told to do will lead to a temporary interruption and possible error message on the heating system. However, after a short while, this should be clearing by itself when the two components "talk" to each other again. +The Point-to-Point Interface (PPS deriving from the German term "Punkt-zu-Punkt Schnittstelle") is compatible to the other systems on a physical layer, but not in the way message telegrams are being exchanged. While BSB and LPB talk to each other by sending telegrams and acknowledging their receipt respectively, PPS is dominated by the heating unit. The heating unit constantly sends its data to the room unit and tells the room unit when and what kind of information it should send. So it may take up to a few minutes until a value that is set in BSB-LAN is actually requested by the heating system and shown there. +It is also a very timing sensitive protocol, therefore long other tasks that BSB-LAN is told to do will lead to a temporary interruption and possible error message on the heating system. However, after a short while, this should be clearing by itself when the two components "talk" to each other again. Other than BSB and LPB, changes made in BSB-LAN do not take immediate effect. Changing values, for example like the room temperature comfort setpoint, will be stored internally in BSB-LAN first to be sent out to the heating system once it tells the room unit (i.e. BSB-LAN) to do so. This may take up to a minute or so, so one should not be confused that settings do not show up on the heater immediately, as is the case with BSB and LPB. -With PPS, BSB-LAN can run in two modes: passive and as a room unit. In passive mode, BSB-LAN can just listen to the data exchanged between the room unit and the heating device. It is not possible to send one's own data, for the simple fact that it would be overwritten in no time by the same type of data coming from the room unit. +With PPS, BSB-LAN can run in two modes: either listening passively or as a room unit. In passive mode, BSB-LAN can just listen to the data exchanged between the room unit and the heating device. It is not possible to send one's own data, for the simple fact that it would be overwritten in no time by the same type of data coming from the room unit. In order to send parameter data to the heating system, BSB-LAN mus run in "room unit" mode, and this means that any room unit will have to be removed from the heating system. In this case, it is especially important to regularly send a room temperature value to BSB-LAN which in turn will send this value to the heating device. Only if the heater runs solely on outside temperature then this value can be ignored. BSB-LAN stores some values in its non-volatile EEPROM, but some values need to be set anew after a reboot, such as the room temperature setpoint. This is to prevent to store a parameter value that has become invalid but is still sent as it is stored in the EEPROM. diff --git a/docs/EN/configure.md b/docs/EN/configure.md index 017403b7..8625f7e4 100644 --- a/docs/EN/configure.md +++ b/docs/EN/configure.md @@ -43,7 +43,7 @@ table th:nth-of-type(4) { |- |**`#define LANG`**|Set language |`DE`, `EN`, `FR` and other ISO country codes| |Display extended configuration|-|Show all configuration options|**On**
**Off**| |Read config from EEPROM|`UseEEPROM`|Read configuration from EEPROM or file|**On** (`1`)
**Off** (`0`)| -|Write access (level)|- |If `DEFAULT_FLAG`is set to `FL_SW_CTL_RONLY`, you can set the level of write access here.|**Off** (read-only)
**On (Standard)**
**On (Complete)** +|[](){#WriteAccess}Write access (level)|- |If `DEFAULT_FLAG`is set to `FL_SW_CTL_RONLY`, you can set the level of write access here.|**Off** (read-only)
**On (Standard)**
**On (Complete)** |Check for updates|`enable_version_check`|Query BSB-LAN server for new available version|**On** (`true`)| |OTA Update|`enable_ota_update`|Enable over-the-air (OTA) update|**On** (`true`)| |Energy saving|`esp32_save_energy`|Reduces speed, saves energy. Do not enable when using WiFi.|**On** (`true`)
**Off** (`false`)| @@ -80,7 +80,7 @@ table th:nth-of-type(4) { |URL Passkey|`PASSKEY`|Passkey adds a user-defined sequence that needs to be added to the URL after the hostname.
For example, a passkey of `1234` requires every URL to be written as `http://bsb-lan.local/1234/` instead of just `http://bsb-lan.local/1234/`. Leave empty for no passkey.|**1234** (`1234`)| |Trusted IP address|`trusted_ip_addr`|Access to BSB-LAN is only possible from this IP address. Same notation as with IP address.|**192.168.178.89** (`192,168,178,89`)| |Trusted IP address|`trusted_ip_addr2`|Access to BSB-LAN is only possible from this IP address. Same notation as with IP address.|**192.168.178.90** (`192,168,178,90`)| -|-|`bssid`|Enter a specific BSSID address here to ensure connecting to a specific access point. Set to all zeros under normal circumstances.|(`0x00, 0x00, 0x00, 0x00, 0x00, 0x00`)| +|[](){#BSSID}-|`bssid`|Enter a specific BSSID address here to ensure connecting to a specific access point. Set to all zeros under normal circumstances.|(`0x00, 0x00, 0x00, 0x00, 0x00, 0x00`)| |-|`ntp_server`|Set an NTP server here to acquire exact time for BSB-LAN. Set to empty string if you don't want to use NTP. ESP32-based microcontrollers only.|(`pool.ntp.org`)| |-|`local_timezone`|Timezone to use for NTP. See [here](https://github.com/nayarsystems/posix_tz_db/blob/master/zones.csv) for a complete list.|(`CET-1CEST,M3.5.0,M10.5.0/3`)| diff --git a/docs/EN/install.md b/docs/EN/install.md index 18f19f97..1116f54e 100644 --- a/docs/EN/install.md +++ b/docs/EN/install.md @@ -20,7 +20,7 @@ Installing BSB-LAN requires three steps: 1. *Olimex ESP32-POE-ISO* for the ESP32-based Olimex POE ISO 1. *Arduino Due (Programming Port)* for the Arduino Due. **Do not use the Native USB Port here**! 1. Again, go to ***Tools/Board*** and select the proper upload speed (460800 for ESP32, 115200 for Arduino Due). -1. For ESP32-based microcontrollers, again, go to ***Tools/Board*** and select "Minimal SPIFFS (Large APPS with OTA)" for partition scheme (**do not confuse this with the similar "Minimal" partition scheme** which is different and not working in our case). **If you don't set the correct parition scheme, the firmware will not fit into the ESP32!** +1. [](){#SPIFFS}For ESP32-based microcontrollers, again, go to ***Tools/Board*** and select "Minimal SPIFFS (Large APPS with OTA)" for partition scheme (**do not confuse this with the similar "Minimal" partition scheme** which is different and not working in our case). **If you don't set the correct parition scheme, the firmware will not fit into the ESP32!** 1. Go to ***File/Open*** and navigate to the BSB_LAN folder and double-click on `BSB_LAN.ino`. The project will open. 1. You may now proceed to [configure](configure.md) BSB-LAN. 1. When you are done configuring, go to ***Sketch/Upload*** and upload the BSB-LAN software to the microcontroller. @@ -41,7 +41,7 @@ Once the microcontroller and the BSB-LAN adapter are ready, perform the followin 1. Unplug the microcontroller from your computer and turn off your heating system. Locate the BSB/LPB/PPS connectors. You may have to open your heating system for that. Have a look at the list of [supported heating systems](supported_heating_systems.md) to get an idea where the pins are located.
***Do all this at your own risk!***
**Especially take care to prevent electrostatic discharge (ESD) which can destroy both BSB-LAN and the heating controller!** 1. Now plug the BSB-LAN adapter onto the microcontroller and connect the `+` screw connector to the `CL+` (BSB), `DB` (LPB) or `A6` (PPS, different connector names are possible) connector, and the `-` screw connector to the `CL-` (BSB), `MB` (LPB) or `M` (PPS) connector. If there is no empty connector, there is no problem adding the wires for BSB-LAN to an already "used" connector, provided the wires are inserted carefully. -1. Now you need to power on the microcontroller. Take note that the heating system does not power the microcontroller, even if the BSB-LAN adapter's LED turns on when you connect it to the heating system. You need to supply power to the microcontroller via its USB port (or via PoE on the Olimex POE-ISO). Make sure to use a stable power supply with at least 2 amperes. Once the microcontroller is powered on, turn on the heating system. The red LED of the BSB-LAN adapter should alight. It should flicker occasionally. +1. [](){#PowerSupply}Now you need to power on the microcontroller. Take note that the heating system does not power the microcontroller, even if the BSB-LAN adapter's LED turns on when you connect it to the heating system. You need to supply power to the microcontroller via its USB port (or via PoE on the Olimex POE-ISO). Make sure to use a stable power supply with at least 2 amperes. Once the microcontroller is powered on, turn on the heating system. The red LED of the BSB-LAN adapter should alight. It should flicker occasionally. 1. Now open your webbrowser and open the IP address of BSB-LAN. If MDNS is enabled, you can directly go to [`http://bsb-lan.local`](http://bsb-lan.local). Otherwise, you can find the IP address of BSB-LAN either in your router, or you connect the microcontroller to your PC and open the Arduino IDE and go to ***Tools/Serial Monitor*** and set the serial monitor speed to 115200. Restart the microcontroller, and the IP address will be displayed upon connecting to the network. --- ## Generating the device-specific parameter list diff --git a/docs/EN/troubleshooting.md b/docs/EN/troubleshooting.md index 33063a7c..cabd3fc5 100644 --- a/docs/EN/troubleshooting.md +++ b/docs/EN/troubleshooting.md @@ -1,6 +1,7 @@ # Troubleshooting -BSB-LAN tries to make accessing your heating system as easy as possible, but there are always things that can go wrong. If you still have a problem after reading this document as well as the [FAQ](faq.md), please [open up a bug report](https://github.com/fredlcore/BSB-LAN/issues/new?assignees=&labels=&projects=&template=bug_report.md&title=%5BBUG%5D) on the project's GitHub page and make sure that you provide us with all the necessary log files and further required details, especially from the Serial Monitor (or *SerMo* in short). +BSB-LAN tries to make accessing your heating system as easy as possible, but there are always things that can go wrong. If you still have a problem after reading this document as well as the [FAQ](faq.md), please [open up a bug report](https://github.com/fredlcore/BSB-LAN/issues/new?assignees=&labels=&projects=&template=bug_report.md&title=%5BBUG%5D) on the project's GitHub page and make sure that you provide us with all the necessary log files and further required details, especially from the Serial Monitor (or *SerMo* in short). +Before doing so, however, make sure that you install the most recent version of BSB-LAN from the master repository (not the release version), even if yours is "just" a few days old. Still, a lot could have happned since then :)! ### Using the Serial Monitor - Access the Serial Monitor by going to ***Tools/Serial Monitor*** in the Arduino IDE. - Set the transmission speed to 115200 at the top right corner of the serial monitor window. @@ -11,7 +12,7 @@ The Serial Monitor in the Arduino IDE currently has a bug that allows you to onl --- ## Compiling fails: "Sketch too big" -- Select the "Minimal SPIFFS (Large APPS with OTA)" partition scheme in the Arduino IDE under ***Tools/Partition Scheme***. If you are using over-the-air updates, you have to flash the software once via USB after changing the partition scheme before OTA updates will work again. +- [Select the *Minimal SPIFFS (Large APPS with OTA)* partition scheme][SPIFFS] in the Arduino IDE under ***Tools/Partition Scheme***. If you are using over-the-air updates, you have to flash the software once via USB after changing the partition scheme before OTA updates will work again. --- ## No access to web-interface anymore @@ -46,9 +47,9 @@ If you have changed the settings in such a way that you cannot access the web-in --- ## No data even though the adapter's red LED is on - Make sure the adapter is connected to CL+/CL- and not to the third (G+) pin: G+ will drive the LED, but it's not a data line. -- Make sure you have powered on the microcontroller. You may think that the heating system powers the microcontroller because the LED on the BSB-LAN adapter is on, but it doesn't. You need to power it separately. +- [Make sure you have powered on the microcontroller][PowerSupply]. You may think that the heating system powers the microcontroller because the LED on the BSB-LAN adapter is on, but it doesn't. You need to power it separately. - With the adapter for the Olimex microcontrollers: Make sure that the BSB-LAN adapter board sits **exactly** in the center of the UEXT connector. It will still fit in, if it's shifted one pin left or right, but it won't work. -- Make sure the RX/TX pins are set/detected correctly. +- Make sure the RX/TX pins are set/detected correctly. The startup sequence in the Serial Monitor will show you what pins have are used or have been auto-detected. --- ## No or unreliable network connection @@ -57,11 +58,11 @@ If you have changed the settings in such a way that you cannot access the web-in --- ## No connection to hidden WiFi network possible -- Yes, that is a known restriction. The only way to do that is to set the BSSID specifically in `BSB_LAN_config.h`. +- Yes, that is a known restriction. The only way to do that is to [set the BSSID explicitly][BSSID] in `BSB_LAN_config.h`. --- ## Room temperature (or any other parameter) cannot be set -- Check BSB-LAN's settings and make sure that write access is enabled and set to *standard* or *complete*. +- Check BSB-LAN's settings and make sure that [write access is enabled][WriteAccess] and set to *standard* or *complete*. --- ## Web-interface freezes when making new connection