Merge pull request #1865 from andythomas/docs_at240307

Updated docs

ReleaseNotes.md

@@ -213,7 +213,11 @@ or our [online documentation](https://github.com/Blackymas/NSPanel_HA_Blueprint/
 Discover our upcoming projects in our [Milestones](https://github.com/Blackymas/NSPanel_HA_Blueprint/milestones?direction=asc&sort=title&state=open).
 
 ## Special Thanks
-*Details to be added.*
+We extend our heartfelt thanks to the contributors who have played a pivotal role in enhancing the NSPanel's capabilities and documentation in this release:
+- **@shing6326**: For diligently addressing and fixing issues related to the new Fan oscillating feature.
+Your efforts have significantly improved its functionality and reliability (#1839).
+- **@andythomas**: For the comprehensive enhancements made to our documentation.
+Your contributions have made our guides more informative and accessible, enriching the user experience for everyone (#1865).
 
 ## Previous releases
 - [v4.2.6 - Enhancing Stability and User Experience](https://github.com/Blackymas/NSPanel_HA_Blueprint/releases/tag/v4.2.6)

docs/addon_climate.md

@@ -21,6 +21,10 @@ Don't use it for directly power your cooler/heater if exceeding the panel specif
 You will need to add the reference to `addon_climate_heat`, `addon_climate_cool` or `addon_climate_dual` files on your ESPHome settings in the `package` section
 and after the `remote_package` (base code), as shown bellow (for `heat` in this example):
 
+> [!NOTE]
+> Occasionally, ESPHome updates may result in the `entity_id` of embedded thermostats being appended with `_2`. 
+> If you experience this change, refer to this [forum post](https://community.home-assistant.io/t/esphome-devices-all-renamed-with-2-added/388146) on the Home Assistant Forum for guidance.
+
 ```yaml
 substitutions:
   # Settings - Editable values
@@ -81,9 +85,9 @@ heat_overrun|Optional|Number representing a temperature hysteresis in the select
 - For more details on the keys, please take a look at [ESPHome Base Climate Configurations](https://esphome.io/components/climate/index.html#base-climate-configuration)
 and [ESPHome Climate Thermostat - Additional actions behavior](https://esphome.io/components/climate/thermostat.html#additional-actions-behavior).
 
-### Examples
+## Examples
 
-#### Cooler
+### Cooler
 
 ```yaml
 substitutions:
@@ -122,7 +126,7 @@ packages:
     refresh: 300s
 ```
 
-#### Heater
+### Heater
 
 ```yaml
 substitutions:
@@ -161,7 +165,7 @@ packages:
     refresh: 300s
 ```
 
-#### Dual
+### Dual
 
 ```yaml
 substitutions:
@@ -202,3 +206,39 @@ packages:
       - nspanel_esphome_addon_climate_dual.yaml
     refresh: 300s
 ```
+
+### Real Use Case Example: Water Underfloor Heating with NSPanel
+The NSPanel works nicely as a replacement for existing water underfloor heating controllers, installed at eye level and often powered by 100-240VAC.
+In my specific use case, the control valve is of the 'normally closed' type, meaning that an open relay indicates 'no heating.'
+I have utilized relay #1 for this purpose. It's important to note that this setup does not act as a PID controller but operates on a simple on-off mechanism.
+The system initiates heating at a preset value below and turns it off at a value above the set point.
+I have set these values to `0.3°C` below and `0.1°C` above the target temperature, respectively.
+These adjustments, `0.3` and `0.1`, have been effectively maintaining the desired temperature in all of our four rooms.
+The thermostat's settings range from a minimum of `15°C` to a maximum of `22°C`, with a granularity of `0.1°C` for adjustments.
+Furthermore, I have selected `21.2°C` as the default target temperature.
+
+```yaml
+ ##### addon-configuration #####
+  ## addon_climate ##
+  heater_relay: "1" #Use relay 1
+  temp_min: "15" 
+  temp_max: "22" 
+  temp_step: "0.1"
+  cold_tolerance: "0.3"
+  hot_tolerance: "0.1"
+    
+  ##### CHANGE ME END #####
+climate:
+  - id: !extend thermostat_embedded
+    preset:
+      - name: Home
+        default_target_temperature_low: 21.2
+        mode: "heat"
+```
+
+Please note that employing any filter to smooth the temperature readings, such as averaging, is discouraged.
+Such filtering methods can delay the response times of an already slow underfloor heating system.
+Despite this, the temperature stability achieved is quite satisfactory, as illustrated in the graph below.
+
+![Temperature vs Time](pics/addon_underfloor.png)
+*On March 5th, around 9:30 PM, a window was opened, and all heaters were set to 'off.'*

docs/blueprint.md

@@ -19,7 +19,7 @@ For an easier overview, the menu items "Icon Color" and "Label Color" will not b
 
 You will be presented with a list of all of your ESPHome ESP32 devices and you must select your panel from the list.
 
-This is technically the only required field, as basic functionality will be available when the Blueprint knows to which panel it have to send the settings.
+This is technically the only required field, as basic functionality will be available when the Blueprint knows to which panel it has to send the settings.
 
 > [!NOTE]
 > You cannot have more than one blueprint based automation per each panel
@@ -90,22 +90,22 @@ The behavior of these buttons will depend on the entity's domain (light, media p
 ## Alarm Control Panel
 
 An alarm control panel entity can be controlled by your panel.
-When you assign the entity here, it's icon will be shown as a button on the Home page.
+When you assign the entity here, its icon will be shown as a button on the Home page.
 
 ## Climate
 
 ### Climate to Control (Optional)
 
 Here you select the main climate entity controlled by your panel.
-It's temperature will be used on the Home page and by clicking on that value you will be able to control the climate settings.
+Its temperature will be used on the Home page and by clicking on that value you will be able to control the climate settings.
 
-You can optionally use your panel to control a climate system locally, using it's temperature sensor and relays.
+You can optionally use your panel to control a climate system locally, using its temperature sensor and relays.
-You will find more details about this on the Add-on Climate docummentation.
+You will find more details about this on the Add-on Climate documentation.
 
-If you are using the Add-on Climate, it will create a climate entity in your panel's device page.
+If you are using the climate add-on, it will create a climate entity in your panel's device page.
 You still have to select that entity on this field in the blueprint settings to have it used as your main climate.
 
-Additional climate entities can be assigned to buttons and will be explained later in this documment.
+Additional climate entities can be assigned to buttons and will be explained later in this document.
 
 On the blueprint settings, you will also find settings for sensors and custom buttons to be shown on all the climate pages.
 
@@ -118,7 +118,7 @@ Activates the QR Code page and shows the QR Code button on the Home page.
 ### QR Code content (Optional)
 
 String, which is shown as a QR Code on the NSPanel.
-This can be a simple text, a URL or could also be used for a simplified login to the Wi-Fi.
+This can be a simple text, an URL or could also be used for a simplified login to the Wi-Fi.
 Here is an example (simply change SSID and password to your credentials and either use "WPA" or "WEP"):
 
 `WIFI:S:SSID;T:WPA/WEP;P:PASSWORD;;`

docs/error_compiling.md

@@ -1,17 +1,23 @@
 # Compiling Errors Guide
 
-The most common cases for compiling errors are related to build files needing to be cleaned up and to lack of resourced on your ESPHome comoiler host.
+The most common cases for compiling errors are related to build files needing to be cleaned up and the lack of resources on your ESPHome compiler host.
 These are our suggestions for both cases:
 
 ## Clean-up build files
 
-Go to your ESPHome Dashboard, click the 3-dot meny related to your device and then "**Clean Build Files**":
+Go to your ESPHome Dashboard, click the 3-dot menu related to your device and then "**Clean Build Files**":
 
 ![image](https://raw.githubusercontent.com/Blackymas/NSPanel_HA_Blueprint/dev/docs/pics/esphome_dashboard_clean_build_files.png)
 
 ## Limited resources on ESPHome compiler host
 ### Free Up Server Resources
-1. Add the following to your device's YAML to reduce resource usage (this may slow down the compilation process):
+
+1. First, please check the available memory of the ESPHome compiler host. 4GB of memory are recommended if you are installing ESPHome as a Home Assistant add-on. 
+Therefore, a RasPi 4 with 4GB RAM is the minimum if you are using a Raspberry Pi. 
+A manual installation requires at least 2GB of memory and 500MB of swap space or 3GB of memory. 
+With less memory the compiler will crash!
+
+2. Add the following to your device's YAML to reduce resource usage (this may slow down the compilation process):
 
     ```yaml
     # Limit the amount of resources used for compiling
@@ -23,15 +29,15 @@ Go to your ESPHome Dashboard, click the 3-dot meny related to your device and th
     > Place this in a dedicated customization section in your YAML for easier maintenance,
     similar to [this example](https://github.com/Blackymas/NSPanel_HA_Blueprint/blob/main/docs/customization.md#instructions).
 
-2. Restart your host system, not just Home Assistant. Use the advanced options to **Reboot system**, which also restarts add-ons and can free up memory.
+3. Restart your host system, not just Home Assistant. Use the advanced options to **Reboot system**, which also restarts add-ons and can free up memory.
 
-3. Temporarily stop non-essential add-ons in Home Assistant, especially resource-intensive ones like Studio Code Server.
+4. Temporarily stop non-essential add-ons in Home Assistant, especially resource-intensive ones like Studio Code Server.
 
-4. [Clean up build files](#clean-up-build-files)
+5. [Clean up build files](#clean-up-build-files)
 
-5. Try compiling again.
+6. Try compiling again.
 
-6. After completion, restart your host system to reactivate the stopped add-ons.
+7. After completion, restart your host system to reactivate the stopped add-ons.
 
 ### Compile Using Your Computer
 1. Install ESPHome on your computer (Windows, Mac, or Linux) following this guide: [Installing ESPHome Manually](https://esphome.io/guides/installing_esphome.html).