100 lines
5.8 KiB
Markdown
100 lines
5.8 KiB
Markdown
# 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.
|
|
|
|
<!-- markdownlint-disable MD028 -->
|
|
> [!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.
|
|
<!-- markdownlint-enable MD028 -->
|
|
|
|
## 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:
|
|
|
|
|
|
|
|
2. Change the value of `ref:` to the version you want to install, like `ref: dev` or `ref: v4.1.4`:
|
|
|
|
|
|
|
|
3. Save your settings and then install it.
|
|
|
|
<!-- markdownlint-disable MD028 -->
|
|
> [!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.
|
|
<!-- markdownlint-enable MD028 -->
|
|
|
|
### 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 (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 (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:
|
|
|
|
|
|
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.
|
|
|
|
|
|
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. Go to the GitHub repository and select the [branch (`main`, `beta` or `dev`)](https://github.com/Blackymas/NSPanel_HA_Blueprint/branches)
|
|
or the [tag](https://github.com/Blackymas/NSPanel_HA_Blueprint/tags) (for previous versions) you want to use.
|
|
3. Find the file `nspanel_blueprint.yaml` in the root of the branch/tag, then click on it to open the file content visualization.
|
|
4. Click the button "**Copy raw file**" in the top right area of the code box. This will copy the entire code to the clipboard.
|
|
5. Go back to your code editor in Home Assistant and replace the entire old code by the one in your clipboard (typically CTRL+A & CTRL+V).
|
|
6. Go 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.
|