From 8a0ca75de1845aebb6495f5e791630bef027aaff Mon Sep 17 00:00:00 2001 From: jessikitty Date: Tue, 23 Dec 2025 12:53:40 +1100 Subject: [PATCH] Update README for v2 with !include file support Explains the critical v2 fix for handling templates in included files: - Why v1 didn't work (only scanned configuration.yaml) - What v2 fixes (scans all .yaml files, handles list format) - Updated example showing binary_sensors.yaml format - Clearer installation and troubleshooting instructions --- README.md | 178 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 114 insertions(+), 64 deletions(-) diff --git a/README.md b/README.md index 0e11225..68d855e 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,52 @@ # Home Assistant Legacy Template Migration -**Pure Bash script** to fix all **67 template deprecation warnings** by migrating from legacy `platform: template` syntax to modern `template:` syntax. +**✨ v2 UPDATE**: Fixed script now properly handles templates in included files (`sensors.yaml`, `binary_sensors.yaml`)! -✅ **No Python required** - Works directly in SSH add-on! +Automatically migrates legacy `platform: template` syntax to modern `template:` syntax in Home Assistant. -## 🚀 Quick Start +## What's New in v2 + +The original script looked only at `configuration.yaml`, but many Home Assistant configurations use `!include` directives to split sensors into separate files like: +- `binary_sensors.yaml` +- `sensors.yaml` +- `packages/*.yaml` + +**v2 fixes:** +- ✅ Scans ALL .yaml files in `/config/` and `/config/packages/` +- ✅ Handles `- platform: template` (list item format with dash) +- ✅ Properly extracts sensors from `sensors:` blocks +- ✅ Handles multiline templates with `>` operator +- ✅ Correct indentation for modern `template:` format +- ✅ Counts sensors correctly from included files + +## Why Migrate? + +Home Assistant is deprecating the legacy `platform: template` syntax in favor of modern `template:` syntax. Starting in **version 2026.6**, the old syntax will stop working. + +This script safely migrates all your legacy template definitions: +- **Binary sensors** (`binary_sensor: !include binary_sensors.yaml`) +- **Sensors** (`sensor: !include sensors.yaml`) +- **Packages** (if you use `/config/packages/`) + +## Features + +✅ **Safe Migration**: Creates timestamped backups before making changes +✅ **Automatic Conversion**: Converts all legacy fields to modern syntax +✅ **Field Mapping**: + - `friendly_name` → `name` + - `value_template` → `state` + - `icon_template` → `icon` + - `entity_picture_template` → `picture` + - `availability_template` → `availability` + - `attribute_templates` → `attributes` + +✅ **Rollback Support**: Includes restore script in backup directory +✅ **Clean Removal**: Removes legacy definitions from original files +✅ **Modern Addition**: Adds new `template:` section to configuration.yaml + +## Installation + +### SSH Add-on or Terminal ```bash cd /config @@ -13,87 +55,95 @@ chmod +x migrate_templates.sh bash migrate_templates.sh ``` -Then: -```bash -ha core check # Verify configuration -ha core restart # Apply changes -``` +### What It Does -## ⚠️ What This Fixes +1. **Scans** all YAML files in `/config/` and `/config/packages/` +2. **Extracts** legacy template definitions +3. **Converts** to modern syntax +4. **Backs up** original files to `/config/backups/template_migration_TIMESTAMP/` +5. **Removes** legacy `- platform: template` blocks +6. **Adds** modern `template:` section to configuration.yaml -Home Assistant 2026.6 will remove support for legacy template syntax. +## Example Migration -**Before (deprecated):** +### Before (binary_sensors.yaml) ```yaml -binary_sensor: - - platform: template - sensors: - router_authenticated: - friendly_name: "Router Authenticated" - value_template: "{{ states('input_text.router_token') != '' }}" +- platform: template + sensors: + router_authenticated: + friendly_name: "Router Authenticated" + value_template: > + {{ states('input_text.router_token') not in ['unknown', '', 'unavailable', ''] }} + icon_template: > + {% if states('input_text.router_token') not in ['unknown', '', 'unavailable', ''] %} + mdi:check-circle + {% else %} + mdi:close-circle + {% endif %} ``` -**After (modern):** +### After (configuration.yaml) ```yaml template: - binary_sensor: - - name: "Router Authenticated" - state: "{{ states('input_text.router_token') != '' }}" - unique_id: router_authenticated + - unique_id: router_authenticated + name: "Router Authenticated" + state: > + {{ states('input_text.router_token') not in ['unknown', '', 'unavailable', ''] }} + icon: > + {% if states('input_text.router_token') not in ['unknown', '', 'unavailable', ''] %} + mdi:check-circle + {% else %} + mdi:close-circle + {% endif %} ``` -## 📊 What It Does +## After Running -✅ Pure Bash - no Python dependencies -✅ Scans all YAML files -✅ Creates timestamped backups -✅ Converts to modern syntax -✅ Updates configuration.yaml -✅ Generates restore script +1. **Review** the new `template:` section at end of configuration.yaml +2. **Check config**: `ha core check` +3. **Restart HA**: `ha core restart` +4. **Verify** all template entities still work -## 🛡️ Safety Features - -- **No Dependencies** - Works in SSH add-on without Python -- **Automatic Backups** - All files backed up before changes -- **Exit on Error** - Stops if any step fails -- **Easy Restore** - One command rollback -- **No Data Loss** - Preserves all configurations - -## 📝 Expected Output - -``` -====================================================================== -Home Assistant Legacy Template Migration (Bash) -====================================================================== - -✓ Created backup: /config/backups/template_migration_20251223_123456 - -ℹ Found 67 legacy template entities: - - 15 sensor(s) - - 52 binary_sensor(s) - -✓ MIGRATION COMPLETE -Migrated: 67 template entities -``` - -## 🔄 Restore if Needed +## If Something Goes Wrong ```bash -bash /config/backups/template_migration_YYYYMMDD_HHMMSS/restore.sh +# Restore from backup +cd /config/backups/template_migration_TIMESTAMP +bash restore.sh ha core restart ``` -## 🎯 Result +## Requirements -After running, all **67 repair warnings will be cleared!** ✅ +- Home Assistant OS or Supervised (with SSH add-on) +- Core or Docker installations (adjust paths as needed) +- Bash shell -## 💡 Why Bash? +## What Gets Migrated -✅ Works in SSH add-on without installing packages -✅ Faster execution -✅ No dependency issues -✅ Native YAML parsing with awk +✅ Template binary sensors +✅ Template sensors +✅ All template fields (value, icon, availability, attributes, etc.) +✅ Multiline templates with `>` operator +✅ Templates in `!include` files ---- +## Technical Details -**Repository:** https://gitea.hideawaygaming.com.au/jessikitty/ha-template-migration +- Uses pure bash + awk (no Python dependencies) +- Handles complex YAML indentation +- Preserves template logic exactly +- Safe for large configurations (handles 67+ sensors) + +## Version History + +- **v2** (2025-12-23): Fixed to handle `!include` files and list-item format +- **v1** (2025-12-23): Initial release (only scanned configuration.yaml) + +## License + +MIT License - feel free to use and modify! + +## Support + +Issues? Check the [Gitea repository](https://gitea.hideawaygaming.com.au/jessikitty/ha-template-migration) or file a bug report.