h3n3/NSPanel_HA_Blueprint
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #1997 from andythomas/docs240329at

Browse Source 
Update docs, look for references to Arduino.
This commit is contained in:
Edward Firmo
2024-03-29 20:18:53 +01:00
committed by GitHub
parent 67892fb6ed 6c52b16ed1
commit cbd341a784
10 changed files with 85 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/addon_climate.md
View File

@@ -19,7 +19,7 @@ Don't use it for directly power your cooler/heater if exceeding the panel specif
## Installation
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):
and after the `remote_package` (base code), as shown below (for `heat` in this example):
> [!NOTE]
> Occasionally, ESPHome updates may result in the `entity_id` of embedded thermostats being appended with `_2`.
@@ -210,7 +210,7 @@ packages:
### 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.
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.1°C` below and `0.1°C` above the target temperature, respectively.
These adjustments have been effectively maintaining the desired temperature in all of our four rooms.

14
docs/customization.md
View File

@@ -541,11 +541,7 @@ time:
### Frameworks
> [!IMPORTANT]
> When switching between frameworks, make sure to update the device with a serial cable as the partition table is different between the two frameworks
as [OTA Update Component](https://esphome.io/components/ota) updates will not change the partition table.
The `arduino` protocol still more popular and therefore more components are available, but as `esp-idf` is maintained by EspressIF and is kept updated,
more boards are supported and the memory management is better, making it ideal if you wanna customize your panel to support memory consumption functionalities,
like `bluetooth_proxy` or [Improv](https://www.improv-wifi.com/).
as [OTA Update Component](https://esphome.io/components/ota) updates will not change the partition table. While it will appear to work, the device will boot the old framework after a reset.
This project currently uses `esp-idf` as default framework.
You can overlap the settings with this customization.
@@ -553,6 +549,13 @@ You can overlap the settings with this customization.
> [!NOTE]
> For more info about frameworks, please visit [ESPHome docs](https://esphome.io/components/esp32).
`esp-idf` is maintained by EspressIF and is kept updated,
more boards are supported and the memory management is better, making it ideal if you wanna customize your panel to support memory consumption functionalities,
like `bluetooth_proxy` or [Improv](https://www.improv-wifi.com/). Consequently, this project uses `esp-idf` as the default framework since `v4.3`.
However, the `arduino` protocol still very popular and, therefore, more components are available and the project allows to switch between the frameworks
by adding the following lines in your panel's yaml file.
#### Framework `arduino`
```yaml
# Change framework to `arduino`
@@ -563,6 +566,7 @@ esp32:
#### Framework `esp-idf`
```yaml
# Change framework to `esp-idf`
# (should not be required)
esp32:
framework:
type: esp-idf

4
docs/different_version.md
View File

@@ -65,11 +65,11 @@ They're created for each new release, allowing easy access to different project
### For Nextion TFT Component
The instructions to upload TFT will vary depending on the version you are installing and the framework you are using.
#### v4.2 or later (ESP-IDF) or v4.2.5 or later (Arduino)
#### v4.2 or later (if you are using ESP-IDF) or v4.2.5 or later (if you are using Arduino)
1. Go to your device's page under **Settings** > **Devices & Services** > **ESPHome**.
2. On the **Configuration** group, press **Update TFT display** and wait for the upload to complete. The system will automatically find the right TFT file for the ESPHome version you are running.
#### v4.1 or earlier, or v4.2.4 or earlier for Arduino framework
#### v4.1 or earlier (in either case) or v4.2.4 or earlier (if you are using Arduino)
1. On the GitHub repository, click on your chosen version name on the [NSPanel_HA_Blueprint Tags](https://github.com/Blackymas/NSPanel_HA_Blueprint/tags) list, then select the tab **Code**.
2. Double-check that the correct version is shown below the repository name:

16
docs/error_initializing.md
View File

@@ -1,11 +1,11 @@
# Panel startup issues
When your panel starts, a number of different things needs to be set and the ESPHome must establish connection to the Nextion display used by your panel
and also to your Home Assistant, which will provide the propper settings required by your panel.
and also to your Home Assistant, which will provide the proper settings required by your panel.
If everything goes right, the boot page will be shown for just a few seconds, then the wake-up page will be shown.
If something happens during this process, your panel may get stuck on this page.
In many cases, restarting your panel can resolve the issue, but if after a reboot it still showing the boot page, this guide may help you.
In many cases, restarting your panel can resolve the issue, but if it is still showing the boot page after a reboot, this guide may help you.
Understanding what is shown on the boot page can be useful to find the cause of the problem or when you are looking for help.
@@ -13,11 +13,11 @@ Understanding what is shown on the boot page can be useful to find the cause of
Your boot page probably looks like this:
**Before ESPHome is connected:**
**Before Home Assistant/ESPHome is connected:**
![Boot page Initializing](pics/eu_boot_initializing.png)
**When ESPHome is connected:**
**When Home Assistant/ESPHome is connected:**
![Boot page with IP](pics/eu_boot_with_ip_address.png)
@@ -49,7 +49,7 @@ If some of those versions are not shown, you can have an indication of where a p
- **TFT** version will always be shown, as that is part of the display itself.
- **ESPHome** version will be shown as soon the ESPHome establishes the communication with the display.
- **Blueprint** version requires both ESPHome and Blueprint to establish communication to be shown.
- **Blueprint** version requires both ESPHome and the Blueprint (in Home Assistant) to establish communication to be shown.
In normal situation, all the versions should be displayed and should be the same. Different patch versions are supported.
@@ -86,7 +86,7 @@ In some cases you can also see duplicate entities on the device's page in Home A
| You may have an older version of the blueprint installed or the blueprint isn't installed into your Home Assistant. | [Install the blueprint](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fgithub.com%2FBlackymas%2FNSPanel_HA_Blueprint%2Fblob%2Fmain%2Fnspanel_blueprint.yaml).<br>[Update the blueprint](howto.md#update-blueprint).|
| You don't have an automation created using the blueprint. | On Home Assistant, go to **Settings** --> **Automations & Scenes** --> **Blueprints** --> **NSPanel Configuration** --> **CREATE AUTOMATION** and follow the [instructions to setup your automation](blueprint.md).<br>**Attention!!** You need one automation per panel, if you have more than one panel set. |
| Your panel is not selected in the automation. | Open the automation related to your panel and make sure the right device is set on the **NSPanel device** field. |
| Your panel's connection to Home Assistant may have issues.<br>This could be from an invalid entity Id, or some service missing registration. | Reconnect the Panel's device to Home Assistant:<br>1. Go to **Settings** --> **Devices & Services** --> **ESPHome**<br>2. Delete the device<br>3. Restart Home Assistant host<br>4. Go back to **Settings** --> **Devices & Services**<br>5. Click **Add integration**<br>6. Select **ESPHome**<br>7. Enter your panel's hostname or IP address.|
| Your panel's connection to Home Assistant may have issues.<br>This could be from an invalid entity Id (e.g. ending with `_2`), or some service missing registration. | Reconnect the Panel's device to Home Assistant:<br>1. Go to **Settings** --> **Devices & Services** --> **ESPHome**<br>2. Delete the device<br>3. Restart Home Assistant host<br>4. Go back to **Settings** --> **Devices & Services**<br>5. Click **Add integration**<br>6. Select **ESPHome**<br>7. Enter your panel's hostname or IP address.|
<!-- markdownlint-enable MD013 MD033 -->
## Additional Tips and Resources
@@ -94,8 +94,8 @@ In some cases you can also see duplicate entities on the device's page in Home A
After troubleshooting, if issues persist, consult the [Issues](https://github.com/Blackymas/NSPanel_HA_Blueprint/issues) and feel free to create a new one asking for more personalized assistance.
Please share as much info as possible, like:
1. Describing (or a picture of) what is in your screen
2. Are updating from a previous version of this same project, or coming from another NSPanel customization (which one?) or customizing for the first time a panel with original Sonoff settings?
1. Describing (or a picture of) what is on your screen
2. Are you updating from a previous version of this project, or you coming from another NSPanel customization (which one?) or are you customizing for the first time a panel with the original Sonoff settings?
3. Please share the ESPHome logs from when your panel starts to the moment the upload fails.
4. Describe what you have already tried.

28
docs/howto.md
View File

@@ -12,15 +12,15 @@ You can write a short message with your findings, and we'll include it here.
Below are the topics covered in this document, each with relevant tips and solutions.
1. [How do I create "Issues" when I have a problem ](#how-to-create-issues-when-i-have-a-problem)
1. [Update Blueprint](#update-blueprint)
1. [Update ESPHome](#update-esphome)
1. [Update TFT](#update-tft)
1. [Notification via HA](#notification-via-ha)
1. [Climate control with relays](#climate-control-with-relays)
1. [Call a page directly](#call-a-page-directly)
1. [Play RTTTL Sound](#play-rtttl-sound)
1. [Start automations via Input_Boolean](#start-automations-via-input_boolean)
1. [Updating Wi-Fi and OTA passwords in ESPHome with this project](#updating-wi-fi-settings-and-ota-passwords-in-esphome-with-this-project)
2. [Update Blueprint](#update-blueprint)
3. [Update ESPHome](#update-esphome)
4. [Update TFT](#update-tft)
5. [Notification via HA](#notification-via-ha)
6. [Climate control with relays](#climate-control-with-relays)
7. [Call a page directly](#call-a-page-directly)
8. [Play RTTTL Sound](#play-rtttl-sound)
9. [Start automations via Input_Boolean](#start-automations-via-input_boolean)
10. [Updating Wi-Fi and OTA passwords in ESPHome with this project](#updating-wi-fi-settings-and-ota-passwords-in-esphome-with-this-project)
## How to create "issues" when I have a problem
@@ -138,13 +138,13 @@ The new firmware will be built and then flashed to your panel, which will restar
4. The display starts the update process and then restarts.
## Notification via HA
To show a notification on the NSPAnel, the following service call can be used:
To show a notification on the NSPanel, the following service call can be used:
```yaml
service: esphome.panelname_notification_show
data:
label: Example text
message: Example text
label: Example label text
message: Example message text
```
> [!NOTE]
> For more details about this service call, please refer to our [API documentation](api.md#notification-show-service-notification_show).
@@ -177,7 +177,9 @@ trigger:
## Climate control with Relays
> [!ATTENTION]
> Although these instructions are still valid, since v4.0 there is a better way to setup a climate control using the panel's relays an the [add-on climate](addon_climate.md).
> Although these instructions are still valid, since v4.0 there is a better way to setup a climate control using the panel's relays an the [add-on climate](addon_climate.md),
> which will continue to work even if Home Assistant and/or WiFi are not available.
> You probably only want to use this approach, if you are not using the build-in thermometer.
In order to use the NSPanel to control a radiator or underfloor heating, at least one Generic Thermostat must be created in the HA.
More information can be found here: https://www.home-assistant.io/integrations/generic_thermostat/

72
docs/install.md
View File

@@ -80,59 +80,72 @@ Detailed steps for a manual installation can be found in the guide [Installing E
Follow these steps to add a new device in the ESPHome Dashboard:
1. Click the **+ New Device** button.
2. Enter a unique name for your new ESPHome device.
![New Device Name](pics/ha_esphome_dashboard_new_device_01.png)
3. Select **ESP32** as the device type.
![Select ESP32](pics/ha_esphome_dashboard_new_device_02.png)
4. Click **Skip** as we're not starting the installation yet.
![Skip Installation](pics/ha_esphome_dashboard_new_device_03.png)
5. Locate your newly created device in the ESPHome Dashboard and click **Edit**.
![Edit Device](pics/ha_esphome_dashboard_new_device_04.png)
6. (Optional) For enhanced security, consider copying the `api:` section to a temporary file.
6. (Optional) For enhanced security, consider copying the `api:` entry to your panel's yaml file while adding the key itself to the secrets file
![API Section](pics/ha_esphome_dashboard_new_device_05.png)
which can be edited clicking `secrets` at the top right of your ESPHome menu.
![API Section](pics/ha_esphome_dashboard_new_device_05c.png)
7. Note the device name at the beginning of the file under `esphome`.
![Device Name](pics/ha_esphome_dashboard_new_device_05b.png)
8. Clear all existing content and paste the following YAML configuration:
```yaml
substitutions:
# Settings - Editable values
device_name: "YOUR_NSPANEL_NAME"
friendly_name: "Your panel's friendly name"
wifi_ssid: !secret wifi_ssid
wifi_password: !secret wifi_password
nextion_update_url: "http://homeassistant.local:8123/local/nspanel_eu.tft" # Optional
# Add-on configuration (if needed)
# heater_relay: "1" # Possible values: "1" or "2"
```yaml
substitutions:
# Settings - Editable values
device_name: "YOUR_NSPANEL_NAME"
friendly_name: "Your panel's friendly name"
wifi_ssid: !secret wifi_ssid
wifi_password: !secret wifi_password
nextion_update_url: "http://homeassistant.local:8123/local/nspanel_eu.tft" # Optional
# Add-on configuration (if needed)
# heater_relay: "1" # Possible values: "1" or "2"
# Customization area
##### My customization - Start #####
##### My customization - End #####
# Customization area
##### My customization - Start #####
##### My customization - End #####
# Core and optional configurations
packages:
remote_package:
url: https://github.com/Blackymas/NSPanel_HA_Blueprint
ref: main
files:
- nspanel_esphome.yaml # Basic package
# Optional advanced and add-on configurations
# - esphome/nspanel_esphome_advanced.yaml
# - nspanel_esphome_addon_climate_cool.yaml
# - nspanel_esphome_addon_climate_heat.yaml
# - nspanel_esphome_addon_climate_dual.yaml
refresh: 300s
```
# Core and optional configurations
packages:
remote_package:
url: https://github.com/Blackymas/NSPanel_HA_Blueprint
ref: main
files:
- nspanel_esphome.yaml # Basic package
# Optional advanced and add-on configurations
# - esphome/nspanel_esphome_advanced.yaml
# - nspanel_esphome_addon_climate_cool.yaml
# - nspanel_esphome_addon_climate_heat.yaml
# - nspanel_esphome_addon_climate_dual.yaml
refresh: 300s
```
![YAML Code](pics/ha_esphome_dashboard_new_device_06.png)
9. Modify the **Settings** section with your device name (as noted in step 7) and Wi-Fi details.
![Edit Settings](pics/ha_esphome_dashboard_new_device_06b.png)
10. For Wi-Fi credentials, use `!secret` for added security or input them directly.
Learn about secrets in ESPHome: [Home Assistant Secrets in ESPHome](https://www.youtube.com/watch?v=eW4vKDeHh7Y).
11. (Optional) Adjust `nextion_update_url` to the URL of a TFT file hosted on an HTTP or HTTPS server,
ensuring that the file is accessible to the NSPanel.
This URL will be used by ESPHome to download the TFT file to your panel.
For more information on hosting the TFT file and setting up the URL, see the [Upload TFT](#upload-tft) section.
> [!CAUTION]
> **Prefer HTTP over HTTPS for File Transfer**
> While you might encounter examples using HTTPS in URLs for file transfer,
@@ -141,7 +154,6 @@ Learn about secrets in ESPHome: [Home Assistant Secrets in ESPHome](https://www.
> often leading to issues with file transfers.
12. (Optional) Enhance security with API encryption by adding the copied key from step 6 to the **My Customization** area.
> [!TIP]
> You can get a new randomly generated valid key from [ESPHome Native API Component](https://esphome.io/components/api.html#configuration-variables) page.

2
docs/lovelace_ui.md
View File

@@ -12,7 +12,7 @@ If you are coming from there, you have to chose one of the 3 options:
### Common steps
1. Download the file [`nspanel_blank.tft`](../nspanel_blank.tft) from our GitHub repository.
1. Download the file [`nspanel_blank.tft`](../hmi/nspanel_blank.tft) from our GitHub repository.
2. Upload the same file (`nspanel_blank.tft`) to the folder _**"www"**_ in your Home Assistant
3. Double check if the file is available by trying to download it using your local url (typically [`http://homeassistant.local:8123/local/nspanel_blank.tft`](http://homeassistant.local:8123/local/nspanel_blank.tft)).

BIN
docs/pics/ha_esphome_dashboard_new_device_05.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 43 KiB

After

Width:  |  Height:  |  Size: 68 KiB

BIN
docs/pics/ha_esphome_dashboard_new_device_05c.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 21 KiB

12
hmi/dev/manuals_screenshots.md
View File

@@ -15,9 +15,9 @@ framework.txt="esp-idf"
ip_addr.txt="192.168.0.123"
```
![Boot EU](../docs/pics/eu_boot.png)
![Boot EU](../../docs/pics/eu_boot.png)
![Boot US](../docs/pics/us_boot.png)
![Boot US](../../docs/pics/us_boot.png)
## Home page
@@ -59,7 +59,7 @@ value03_state.txt="715 W"
value03_icon.txt=""
```
![Home EU](../docs/pics/eu_home.png)
![Home EU](../../docs/pics/eu_home.png)
**US version:**
@@ -100,7 +100,7 @@ value03_state.txt="715 W"
value03_icon.txt=""
```
![Home US](../docs/pics/us_home.png)
![Home US](../../docs/pics/us_home.png)
## Settings page
@@ -108,8 +108,8 @@ value03_icon.txt=""
page settings
```
![Settings EU](../docs/pics/eu_settings.png)
![Settings US](../docs/pics/us_settings.png)
![Settings EU](../../docs/pics/eu_settings.png)
![Settings US](../../docs/pics/us_settings.png)
## Buttons pages (DRAFT)