diff --git a/docs/README.md b/docs/README.md index 8f66de4..88ea727 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,6 +3,7 @@ - [First Steps | Installation and Setup](install.md) - [Blueprint | Setup and explanation of the Blueprint](blueprint.md) - [HowTo | All important things you should know](howto.md) +- [Version compatibility matrix](version_compatibility.md) ## Common issues - [TFT Upload](tft_upload.md) @@ -13,6 +14,7 @@ - [Customization](customization.md) - [Add-on climate](addon_climate.md) - [Alarm Control Panel](alarm.md) +- [Using Different Versions of This Project](different_version.md) ## Setup and overview videos: - **_[Overview and features](https://www.youtube.com/watch?v=b7vW4YtUaTs) - Mark Watt Tech_** diff --git a/docs/different_version.md b/docs/different_version.md new file mode 100644 index 0000000..6ba6d16 --- /dev/null +++ b/docs/different_version.md @@ -0,0 +1,101 @@ +# Guide to Using Different Versions of This Project + +## Introduction +This guide provides instructions on how to switch between different versions for each component of this project: +Blueprint, ESPHome, and Nextion TFT, allowing users to access development (`dev`), beta, or previous versions. + + +> [!WARNING] +> Use non-main versions at your own risk. Only the `main`/latest release is officially supported. + +> [!IMPORTANT] +> Ensure all three components (Blueprint, ESPHome, TFT) are synchronized at the same version for system stability. + + +## Suggested Update Order +1. **ESPHome**: Start with ESPHome for its straightforward update process. +2. **TFT**: Then proceed with Nextion TFT. +3. **Blueprint**: Finally, update Blueprint, as it requires more manual effort and careful handling. + +## Finding Available Versions +For available versions and branches, visit: [NSPanel_HA_Blueprint Tags](https://github.com/Blackymas/NSPanel_HA_Blueprint/tags). +Take note of the branch (`dev`, `beta`, or `main`) or version name exactly as it is published, as this is case-sensitive. + +> [!NOTE] +> **Understanding Tags in GitHub** +> Tags on GitHub mark specific versions of a project, akin to bookmarks. +They're created for each new release, allowing easy access to different project stages. + +### Special Versions +- **dev**: The development version, containing the latest code but potentially unstable. +- **beta**: The pre-release version, more stable than `dev` but still undergoing final testing. +- **main**: The default latest version, where you will find the most recent release code. + +> [!NOTE] +> When using `dev` or `beta`, report findings in the [issues](https://github.com/Blackymas/NSPanel_HA_Blueprint/issues) section, clearly stating the version. +> +> **Please do not report issues related to old released versions.** + +## Instructions + +### For ESPHome Component +1. Open your device's YAML config and find the key `ref:`, which is under `remote_package:` in the `packages:` area: + + ![Image](pics/esphome_dashboard_yaml_ref_main.png) + +2. Change the value of `ref:` to the version you want to install, like `ref: dev` or `ref: v4.1.4`: + + ![Image](pics/esphome_dashboard_yaml_ref_v414.png) + +3. Save your settings and then install it. + +> [!IMPORTANT] +> Older versions may require `arduino` framework. +> Please refer to this guide for setting the framework properly: [Change framework](customization.md#frameworks) + +> [!WARNING] +> Older versions of the components may not be compatible with the latest ESPHome compiler or Home Assistant. +> +> Ensure you are using a compatible version of Home Assistant and the compiler when working with older project versions to avoid potential issues. +> +> You can use our [Version compatibility matrix](version_compatibility.md) to identify the minimum requirement per version as a reference for possible version incompatibility, although we don't have a register of the "Maximum version" supported. + +### For Nextion TFT Component +The instructions to upload TFT will vary depending on the branch or version you are installing and the framework you are using. + +#### v4.2 or later, with ESP-IDF framework +1. Go to your device's page under **Settings** > **Devices & Services** > **ESPHome**. +2. On the **Configuration** group, select your option for **Update TFT display - Branch** (either the version you want or `dev`/`beta`). +If that option is not visible, please expand the **+n entities not shown** and enable it. + + ![Image](pics/ha_device_configuration_tft_update_branch_selector.png) +3. Press **Update TFT display** and wait for the upload to complete. + +#### v4.1 or earlier, or Arduino framework +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: + + ![Image](pics/GitHub_repo_select_tag_tft_files.png) +3. Locate the TFT file related to your model and download it to your local http server. +4. Double check your `nextion_update_url` substitution is pointing to the right URL where the file you just downloaded is available. + + ![Image](pics/esphome_dashboard_yaml_nextion_update_url.png) +5. Go to your device's page under **Settings** > **Devices & Services** > **ESPHome**. +6. On the **Configuration** group, press **Update TFT display** and wait for the upload to complete. + +### For Blueprint Component +1. Use your preferred code editor to edit the blueprint file under `/homeassistant/blueprints/automation/Blackymas/nspanel_blueprint.yaml`. +2. In the `source_url` key, change the URL replacing `main` by the version you want to install. +3. Go to **Developer Tools**, select the tab **YAML** and click the button to reload **AUTOMATIONS**. +4. Go to the [Blueprints dashboard](https://my.home-assistant.io/redirect/blueprints/) (under **Settings** > **Automations & Scenes**, then select tab **Blueprints**). +5. Find the Blueprint named **NSPanel Configuration** and click on the 3-dot menu related to that. +6. Click **Re-import blueprint**. +7. Go back to **Developer Tools**, select the tab **YAML** and click the button to reload **AUTOMATIONS**. + +## Additional Notes +- Please note that the images provided in this guide might become outdated as the project evolves. +It's always a good idea to refer to the latest version of the project for current details. +- For the most up-to-date information and updates, +refer to the [project's documents](README.md) +and check the [issues](https://github.com/Blackymas/NSPanel_HA_Blueprint/issues) +and [discussions](https://github.com/Blackymas/NSPanel_HA_Blueprint/discussions) sections on our GitHub repository. diff --git a/docs/pics/GitHub_repo_select_tag_tft_files.png b/docs/pics/GitHub_repo_select_tag_tft_files.png new file mode 100644 index 0000000..44e710c Binary files /dev/null and b/docs/pics/GitHub_repo_select_tag_tft_files.png differ diff --git a/docs/pics/esphome_dashboard_yaml_nextion_update_url.png b/docs/pics/esphome_dashboard_yaml_nextion_update_url.png new file mode 100644 index 0000000..31b88b3 Binary files /dev/null and b/docs/pics/esphome_dashboard_yaml_nextion_update_url.png differ diff --git a/docs/pics/esphome_dashboard_yaml_ref_main.png b/docs/pics/esphome_dashboard_yaml_ref_main.png new file mode 100644 index 0000000..74ccbcd Binary files /dev/null and b/docs/pics/esphome_dashboard_yaml_ref_main.png differ diff --git a/docs/pics/esphome_dashboard_yaml_ref_v414.png b/docs/pics/esphome_dashboard_yaml_ref_v414.png new file mode 100644 index 0000000..fc75a7b Binary files /dev/null and b/docs/pics/esphome_dashboard_yaml_ref_v414.png differ diff --git a/docs/pics/ha_device_configuration_tft_update_branch_selector.png b/docs/pics/ha_device_configuration_tft_update_branch_selector.png new file mode 100644 index 0000000..8b54cf2 Binary files /dev/null and b/docs/pics/ha_device_configuration_tft_update_branch_selector.png differ diff --git a/docs/pics/ha_file_editor_blueprint_source_url_v414.png b/docs/pics/ha_file_editor_blueprint_source_url_v414.png new file mode 100644 index 0000000..e3dc696 Binary files /dev/null and b/docs/pics/ha_file_editor_blueprint_source_url_v414.png differ diff --git a/docs/version_compatibility.md b/docs/version_compatibility.md new file mode 100644 index 0000000..2c0bf83 --- /dev/null +++ b/docs/version_compatibility.md @@ -0,0 +1,11 @@ +# Version compatibility matrix + + +| NSPanel_HA_Blueprint
Version | Home Assistant
Min version | ESPHome
Min version | +| :--: | :--: | :--: | +| v4.2.2+ | 2023.12.0 | 2023.12.0 | +| v4.2.1
v4.2 | 2023.9.0 | 2023.12.0 | +| v4.1 | 2023.9.0 | 2023.5.0 | +| v4.0 | 2023.5.0 | 2023.5.0 | +| Older | 2022.11.1 | 2022.10.2 | +