nspanel_esphome_version.yaml

#####################################################################################################
#####                 NSPanel Easy - https://github.com/edwardtfn/NSPanel-Easy                  #####
#####################################################################################################
##### ESPHOME VERSION                                                                           #####
##### PLEASE only make changes if it is necessary and also the required knowledge is available. #####
##### For normal use with the Blueprint, no changes are necessary.                              #####
#####################################################################################################
---
substitutions:
  # Automatically updated by CI/CD on each release
  # Value is imported from versioning/version.yaml
  <<: !include ../versioning/version.yaml

  # Minimum required blueprint version for compatibility
  # Select 'next' or '${version}' when you change the "contract" between ESPHome and Blueprint
  # Versioning workflow will replace this by the new version being generated
  min_blueprint_version: 2026.4.2

  # Minimum required TFT version for compatibility
  # Must be manually updated with Nextion Editor
  min_tft_version: 16.0

  # Minimum required ESPHome compiler to run this
  # Versioning workflow will take care of updating this
  min_esphome_compiler_version: 2026.2.0

  TAG_VERSIONING: nspanel.versioning

esphome:
  project:
    version: '"${version}"'
  platformio_options:
    build_flags:
      - -D NSPANEL_EASY_VERSIONING
  min_version: ${min_esphome_compiler_version}

script:
  - id: !extend action_component_text
    then:
      - lambda: |-
          if (page != "mem") return;
          if (component != "ver_blueprint") return;
          if (txt.empty()) {
            ESP_LOGE("${TAG_VERSIONING}", "Invalid Blueprint version: empty string");
            return;
          }
          version_blueprint->publish_state(txt);

  - id: !extend boot_early_routines
    then:
      - text_sensor.template.publish:
          id: version_esphome
          state: ${version}

  - id: check_versions
    mode: restart
    parameters:
      reset_flag: bool
    then:
      - lambda: |-
          ESP_LOGV("${TAG_VERSIONING}", "Script: Check version");
          ESP_LOGV("${TAG_VERSIONING}", "  reset_flag: %s", TRUEFALSE(reset_flag));
          ESP_LOGV("${TAG_VERSIONING}", "  VERSION_CHECK_OK: %s", (system_flags.version_check_ok) ? "Set" : "NOT set");
          ESP_LOGV("${TAG_VERSIONING}", "  is_device_ready_for_tasks: %s", YESNO(is_device_ready_for_tasks()));
          ESP_LOGV("${TAG_VERSIONING}", "  Versions:");
          ESP_LOGV("${TAG_VERSIONING}", "    Blueprint: %s", version_blueprint->state.c_str());
          ESP_LOGV("${TAG_VERSIONING}", "    ESPHome: ${version}");
          ESP_LOGV("${TAG_VERSIONING}", "    TFT: %s", version_tft->state.c_str());
          if (reset_flag) system_flags.version_check_ok = false;
          if (system_flags.version_check_ok) {
            ESP_LOGD("${TAG_VERSIONING}", "VERSION_CHECK_OK is already set");
            return;
          }
          if (!is_device_ready_for_tasks()) {
            ESP_LOGD("${TAG_VERSIONING}", "Device not ready for tasks - Skip version check");
            return;
          }
      - delay: 5s
      - script.execute: wait_for_versions
      - script.wait: wait_for_versions
      - lambda: |-
          ESP_LOGD("${TAG_VERSIONING}", "Versions:");
          ESP_LOGD("${TAG_VERSIONING}", "  Blueprint: %s", version_blueprint->state.c_str());
          ESP_LOGD("${TAG_VERSIONING}", "  ESPHome:   ${version}");
          ESP_LOGD("${TAG_VERSIONING}", "  TFT:       %s", version_tft->state.c_str());
          system_flags.version_check_ok = true;
          if (!calver_gte(version_blueprint->state, "${min_blueprint_version}")) {
            ESP_LOGW("${TAG_VERSIONING}", "Blueprint version mismatch!");
            if (!version_blueprint->state.empty()) {
              system_flags.version_check_ok = false;
              ESP_LOGE("${TAG_VERSIONING}", "Blueprint v${min_blueprint_version} is required");
              ESP_LOGE("${TAG_VERSIONING}", "How to Resolve This Issue:");
              ESP_LOGE("${TAG_VERSIONING}", "1. Navigate to your Blueprint Dashboard on Home Assistant" \
                                            "(Settings > Automations & scenes, tab 'Blueprints')");
              ESP_LOGE("${TAG_VERSIONING}", "2. Locate the blueprint named 'NSPanel Easy Configuration'");
              ESP_LOGE("${TAG_VERSIONING}", "3. Click on the corresponding 3-dot menu");
              ESP_LOGE("${TAG_VERSIONING}", "4. Choose 'Re-import blueprint'");
              ESP_LOGE("${TAG_VERSIONING}", "5. Select the 'Re-import' button");
              ESP_LOGE("${TAG_VERSIONING}", "6. Navigate to YAML configuration reloading dashboard");
              ESP_LOGE("${TAG_VERSIONING}", "7. Select 'Automations' to reload the automations");
              ESP_LOGE("${TAG_VERSIONING}", "For more detailed instructions, please refer to the online documentation:");
              ESP_LOGE("${TAG_VERSIONING}", "https://github.com/edwardtfn/NSPanel-Easy/blob/main/docs/howto.md#update-blueprint");
            }
          }
          if (!tft_ver_gte(version_tft->state, "${min_tft_version}")) {
            ESP_LOGW("${TAG_VERSIONING}", "TFT version mismatch!");
            if (!version_tft->state.empty()) {
              ESP_LOGE("${TAG_VERSIONING}", "TFT v${min_tft_version} is required");
              system_flags.version_check_ok = false;
            }
          }

          fire_ha_event("version", {
            {"blueprint", version_blueprint->state.c_str() },
            {"min_blueprint_version", "${min_blueprint_version}"},
            {"esphome", "${version}"},
            {"tft", version_tft->state.c_str() },
            {"min_tft_version", "${min_tft_version}"},
          #ifdef NSPANEL_EASY_ADDON_UPLOAD_TFT
            {"upload_tft_installed", "true"},
            {"upload_tft_auto", "${upload_tft_automatically}"},
            {"upload_tft_wait_ms", "${upload_tft_wait_ms_after_boot}"}
          #else   // Upload TFT add-on is not installed
            {"upload_tft_installed", "false"}
          #endif  // NSPANEL_EASY_ADDON_UPLOAD_TFT
          });
          ESP_LOGD("${TAG_VERSIONING}", "Check version completed");

  - id: !extend dump_config
    then:
      - lambda: |-
          // Report blueprint version
          ESP_LOGCONFIG("${TAG_VERSIONING}", "Blueprint:");
          if (system_flags.blueprint_ready) {
            ESP_LOGCONFIG("${TAG_VERSIONING}", "  Version: %s", version_blueprint->state.c_str());
            ESP_LOGCONFIG("${TAG_VERSIONING}", "  Progress: %0.1f%%", blueprint_status_flags.get_completion_percentage());
          } else {
            ESP_LOGW("${TAG_VERSIONING}", "  Progress: %0.1f%%", blueprint_status_flags.get_completion_percentage());
            ESP_LOGW("${TAG_VERSIONING}", "  State: %s", (system_flags.wifi_ready and system_flags.api_ready)
                                                    ? "Pending" : "DISCONNECTED");
          }

          // Report ESPHome
          ESP_LOGCONFIG("${TAG_VERSIONING}", "ESPHome:");
          ESP_LOGCONFIG("${TAG_VERSIONING}", "  Version: ${version}");
          ESP_LOGCONFIG("${TAG_VERSIONING}", "  Compiler: %s", ESPHOME_VERSION);

          // Report framework
          #ifdef USE_ESP_IDF
          ESP_LOGCONFIG("${TAG_VERSIONING}", "  Framework: ESP-IDF");
          #elif defined(USE_ARDUINO)
          ESP_LOGW("${TAG_VERSIONING}", "  Framework: Arduino");
          #else
          ESP_LOGE("${TAG_VERSIONING}", "  Framework: Unknown");
          #endif

  - id: !extend stop_all
    then:
      - lambda: |-
          check_versions->stop();
          wait_for_version_blueprint->stop();
          wait_for_versions->stop();

  - id: wait_for_version_blueprint
    mode: single
    then:
      - repeat:
          count: 60  # seconds
          then:
            - lambda: |-
                ESP_LOGV("${TAG_VERSIONING}", "Blueprint version: '%s'", version_blueprint->state.c_str());
                if (!version_blueprint->state.empty()) wait_for_version_blueprint->stop();
                if (iteration % 5 == 1) boot_log->execute("Boot", "Waiting for Blueprint version");
                if (iteration % 9 == 0) boot_request_blueprint_settings->execute("timeout");
            - delay: 1s

  - id: wait_for_versions
    mode: single
    then:
      - script.execute: wait_for_version_blueprint
      - script.wait: wait_for_version_blueprint

text_sensor:
  - id: version_esphome
    name: "Version - ESPHome"
    platform: template
    entity_category: diagnostic
    icon: mdi:tag-text-outline
    internal: false
    update_interval: never
    # Published by boot_early_routines during boot sequence.

  - id: version_blueprint
    name: "Version - Blueprint"
    platform: template
    entity_category: diagnostic
    icon: mdi:tag-text-outline
    internal: false
    update_interval: never
    # Initial state is empty, which HA renders as unavailable.
    # Published by action_component_text when the version is received from HA.
    on_value:
      then:
        - lambda: |-
            ESP_LOGI("${TAG_VERSIONING}", "Blueprint version: %s", x.c_str());
            blueprint_status_flags.version = (calver_gte(x, "${min_blueprint_version}"));
            check_versions->execute(!blueprint_status_flags.version || version_tft->state.empty());

  - id: version_tft
    name: "Version - TFT"
    platform: template
    entity_category: diagnostic
    icon: mdi:tag-text-outline
    internal: false
    update_interval: never
    on_value:
      then:
        - lambda: |-
            ESP_LOGI("${TAG_VERSIONING}", "TFT version: %s", x.c_str());
            check_versions->execute(!blueprint_status_flags.version || x.empty());
    # Initial state is empty, which HA renders as unavailable.
    # Published by nspanel_esphome_page_boot when the TFT version is received from the display.
...