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
This commit is contained in:
178
README.md
178
README.md
@@ -1,10 +1,52 @@
|
|||||||
# Home Assistant Legacy Template Migration
|
# 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
|
```bash
|
||||||
cd /config
|
cd /config
|
||||||
@@ -13,87 +55,95 @@ chmod +x migrate_templates.sh
|
|||||||
bash migrate_templates.sh
|
bash migrate_templates.sh
|
||||||
```
|
```
|
||||||
|
|
||||||
Then:
|
### What It Does
|
||||||
```bash
|
|
||||||
ha core check # Verify configuration
|
|
||||||
ha core restart # Apply changes
|
|
||||||
```
|
|
||||||
|
|
||||||
## ⚠️ 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
|
```yaml
|
||||||
binary_sensor:
|
- platform: template
|
||||||
- platform: template
|
sensors:
|
||||||
sensors:
|
router_authenticated:
|
||||||
router_authenticated:
|
friendly_name: "Router Authenticated"
|
||||||
friendly_name: "Router Authenticated"
|
value_template: >
|
||||||
value_template: "{{ states('input_text.router_token') != '' }}"
|
{{ 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
|
```yaml
|
||||||
template:
|
template:
|
||||||
- binary_sensor:
|
- binary_sensor:
|
||||||
- name: "Router Authenticated"
|
- unique_id: router_authenticated
|
||||||
state: "{{ states('input_text.router_token') != '' }}"
|
name: "Router Authenticated"
|
||||||
unique_id: 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
|
1. **Review** the new `template:` section at end of configuration.yaml
|
||||||
✅ Scans all YAML files
|
2. **Check config**: `ha core check`
|
||||||
✅ Creates timestamped backups
|
3. **Restart HA**: `ha core restart`
|
||||||
✅ Converts to modern syntax
|
4. **Verify** all template entities still work
|
||||||
✅ Updates configuration.yaml
|
|
||||||
✅ Generates restore script
|
|
||||||
|
|
||||||
## 🛡️ Safety Features
|
## If Something Goes Wrong
|
||||||
|
|
||||||
- **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
|
|
||||||
|
|
||||||
```bash
|
```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
|
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
|
✅ Template binary sensors
|
||||||
✅ Faster execution
|
✅ Template sensors
|
||||||
✅ No dependency issues
|
✅ All template fields (value, icon, availability, attributes, etc.)
|
||||||
✅ Native YAML parsing with awk
|
✅ 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.
|
||||||
|
|||||||
Reference in New Issue
Block a user