{"id":39736870,"url":"https://github.com/jonducrou/ha_visualiser","last_synced_at":"2026-01-18T11:07:36.045Z","repository":{"id":308466640,"uuid":"1032917809","full_name":"jonducrou/ha_visualiser","owner":"jonducrou","description":"A powerful Home Assistant custom integration that visualizes your smart home as an interactive graph, revealing the hidden relationships between your entities, devices, areas, automations, groups, and zones.","archived":false,"fork":false,"pushed_at":"2025-12-03T09:03:37.000Z","size":820,"stargazers_count":86,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-06T11:24:40.774Z","etag":null,"topics":["custom-integration","entity-graph","hacs","home-assistant","smart-home","visualization"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jonducrou.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-06T03:15:46.000Z","updated_at":"2025-12-03T09:03:38.000Z","dependencies_parsed_at":"2025-09-01T09:09:37.471Z","dependency_job_id":"a3baf938-0794-46d5-88da-e46e2db317ee","html_url":"https://github.com/jonducrou/ha_visualiser","commit_stats":null,"previous_names":["jonducrou/ha_visualiser"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/jonducrou/ha_visualiser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonducrou%2Fha_visualiser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonducrou%2Fha_visualiser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonducrou%2Fha_visualiser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonducrou%2Fha_visualiser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jonducrou","download_url":"https://codeload.github.com/jonducrou/ha_visualiser/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonducrou%2Fha_visualiser/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28535156,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T10:13:46.436Z","status":"ssl_error","status_checked_at":"2026-01-18T10:13:11.045Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["custom-integration","entity-graph","hacs","home-assistant","smart-home","visualization"],"created_at":"2026-01-18T11:07:34.146Z","updated_at":"2026-01-18T11:07:36.033Z","avatar_url":"https://github.com/jonducrou.png","language":"Python","readme":"# Home Assistant Entity Visualizer\n\n[![GitHub Release](https://img.shields.io/github/release/jonducrou/ha_visualiser.svg?style=for-the-badge)](https://github.com/jonducrou/ha_visualiser/releases)\n[![GitHub Activity](https://img.shields.io/github/commit-activity/y/jonducrou/ha_visualiser.svg?style=for-the-badge)](https://github.com/jonducrou/ha_visualiser/commits/main)\n[![License](https://img.shields.io/github/license/jonducrou/ha_visualiser.svg?style=for-the-badge)](LICENSE)\n[![HACS](https://img.shields.io/badge/HACS-Custom-orange.svg?style=for-the-badge)](https://github.com/hacs/integration)\n\nA powerful Home Assistant custom integration that visualizes your smart home as an interactive graph, revealing the hidden relationships between your entities, devices, areas, automations, groups, and zones.\n\n## 📸 Screenshots\n\n### Interactive Network Visualization\n![Home Assistant Entity Visualizer - En Suite Bathroom](images/demo-en_suite.png)\n*Visualizing relationships in an en suite bathroom setup - showing devices, entities, areas, and their connections*\n\n### Complex Entity Relationships  \n![Home Assistant Entity Visualizer - Solar System](images/demo-solar.png)\n*Exploring solar system entities with templates, sensors, and automation relationships*\n\n## ✨ Key Features\n\n### 🎨 **Advanced Interactive Interface**\n- **Clean Design**: Consistent rounded boxes with subtle light color palette\n- **Entity Icons**: Visual icons for each domain (💡 lights, 🔌 switches, 🤖 automations, etc.)  \n- **Focus Highlighting**: Enhanced visual feedback for the currently selected entity\n- **Dual Layout Modes**: Hierarchical for simple graphs, force-directed for complex networks\n- **Native HA Integration**: Single-click opens Home Assistant entity details dialogs\n- **Double-Click Navigation**: Smooth, intuitive entity exploration through relationship networks\n\n### 🔍 **Comprehensive Relationship Detection**\n- **Device Relationships**: Physical device to entity mappings\n- **Area \u0026 Zone Hierarchies**: Spatial organization and containment with optional filtering\n- **Group Support**: Light groups, switch groups, media player groups, and traditional groups\n- **Label Organization**: Home Assistant label-based groupings and classifications  \n- **Automation Dependencies**: Complete trigger and control relationship chains with UUID resolution\n- **Template References**: Advanced parsing for complex multi-line Jinja2 templates\n- **Alert Monitoring**: Home Assistant alert entity relationships\n- **Bidirectional Navigation**: True symmetrical relationship discovery and visualization\n\n### 🚀 **Advanced Visualization**\n- **Interactive Navigation**: Double-click any node to explore its neighborhood smoothly\n- **2-Level Depth**: Rich context showing extended relationship networks\n- **Intelligent Layout Selection**: Automatic hierarchical vs force-directed algorithm selection\n- **Area Filtering**: Toggle areas on/off to simplify or expand relationship views\n- **Search \u0026 Discovery**: Powerful search across entities, devices, areas, zones, groups, and labels\n- **Enhanced Edge Bundling**: Clean handling of bidirectional relationships with proper grouping\n- **Consistent Arrows**: Logical relationship directions (container → contained, actor → target)\n\n### 🎯 **Smart Entity Management**\n- **UUID Resolution**: Handles complex automation configurations correctly\n- **Entity Type Recognition**: Supports all HA entity domains with appropriate styling\n- **Real-time Updates**: Live WebSocket API integration\n- **Professional Integration**: Native HA sidebar panel with authentication\n\n## 💡 Use Cases\n\n### **🔧 Smart Home Management**\n- **Impact Analysis**: Understand which entities are connected before making changes\n- **Automation Debugging**: Visualize trigger → automation → control chains\n- **Device Organization**: See device-to-entity mappings and area hierarchies\n- **Label Management**: Explore label-based groupings and organizational structures\n- **Orphan Detection**: Identify isolated or unused entities\n\n### **🎯 Planning \u0026 Optimization** \n- **Area Planning**: Visualize and optimize room/area organization\n- **Label Strategy**: Design and refine your labeling system for better organization\n- **Automation Design**: Understand existing patterns before creating new automations\n- **Template Dependencies**: See which entities your templates depend on\n- **System Understanding**: Get a bird's-eye view of your smart home ecosystem\n\n### **🚨 Troubleshooting**\n- **Broken Automations**: Trace automation dependencies and control flows\n- **Missing Relationships**: Identify entities that should be connected but aren't\n- **Complex Debugging**: Navigate multi-level entity relationships quickly\n\n## 🚀 Installation\n\n### **Via HACS (Recommended)**\n1. Install [HACS](https://hacs.xyz/) if you haven't already\n2. Add this repository to HACS as a custom repository\n3. Download \"Home Assistant Entity Visualizer\"\n4. Restart Home Assistant\n5. Go to **Settings** → **Devices \u0026 Services** → **Add Integration**\n6. Search for \"Entity Visualizer\" and add it\n7. ✅ **\"Entity Visualizer\" now appears in your sidebar**\n\n### **Manual Installation**\n1. Copy the `custom_components/ha_visualiser/` directory to your HA `custom_components/` folder\n2. Restart Home Assistant\n3. Go to **Settings** → **Devices \u0026 Services** → **Add Integration**\n4. Search for \"Entity Visualizer\" and add it\n5. ✅ **\"Entity Visualizer\" now appears in your sidebar**\n\n## 📖 Usage\n\n### **Basic Navigation**\n1. **Open the Panel**: Click \"Entity Visualizer\" in your HA sidebar\n2. **Search**: Type in the search box to find entities, devices, areas, zones, or labels\n3. **Entity Details**: Single-click any entity to open its native Home Assistant details dialog\n4. **Navigate**: Double-click any node to explore its neighborhood relationships\n5. **Explore**: Continue navigating through different areas of your smart home\n\n### **Understanding the Visualization**\n- **Nodes**: Represent entities, devices, areas, zones, labels, and automations\n- **Arrows**: Show relationship directions (container → contained, label → labeled, trigger → automation → control)\n- **Icons**: Visual indicators for entity types (💡🔌🤖🏠📍🏷️)\n- **Colors**: Subtle color coding by domain with light, professional palette\n- **Focus**: Selected entities are highlighted with enhanced borders and styling\n\n### **Advanced Features**\n- **2-Level Exploration**: See not just direct relationships but extended networks\n- **Area Filtering**: \"Show Areas\" checkbox to toggle area relationships on/off ([detailed documentation](FILTERS.md))\n- **Layout Toggle**: Switch between hierarchical and force-directed layouts for optimal visualization\n- **Symmetrical Navigation**: Relationships work bidirectionally for complete context\n- **Group Support**: Comprehensive support for all Home Assistant group types\n- **Enhanced Template Parsing**: Support for complex multi-line Jinja2 templates with advanced regex\n- **Real-time Updates**: Live reflection of changes in your HA setup\n\n## 📋 Requirements\n\n- **Home Assistant**: 2023.7 or later\n- **Browser**: Modern web browser with JavaScript enabled\n- **Network**: WebSocket support (standard in all modern browsers)\n\n## 🏗️ Technical Details\n\n### **Architecture**\n- **Backend**: Python integration using HA's native APIs\n- **Frontend**: JavaScript with vis.js for graph visualization  \n- **Communication**: Real-time WebSocket API\n- **Data Sources**: Entity registry, device registry, area registry, label registry, automation configs\n\n### **Supported Relationship Types**\n- **Device → Entity**: Physical device contains multiple entities\n- **Area → Device/Entity**: Spatial organization and room assignments (with filtering)\n- **Zone → Entity**: Geographic/proximity-based relationships\n- **Label → Entity/Device/Area**: Organizational labeling and classification\n- **Group → Entity**: Group containment (light groups, switch groups, media player groups)\n- **Entity → Group**: Group membership relationships (bidirectional)\n- **Entity → Automation**: Trigger relationships (state changes activate automations)\n- **Automation → Entity**: Control relationships (automations modify entity states)\n- **Template → Entity**: Dependency relationships (templates reference other entities)\n- **Alert → Entity**: Alert monitoring relationships\n\n### **Performance**\n- **Lazy Loading**: Only loads neighborhoods on demand\n- **Efficient Algorithms**: Optimized graph traversal and layout algorithms\n- **Caching**: Smart caching of relationship data\n- **Responsive**: Handles large smart home setups efficiently\n\n## 🧪 Development \u0026 Testing\n\nThis project includes comprehensive testing infrastructure:\n\n```bash\n# Run unit tests\npython tests/test_runner.py\n\n# Validate code syntax\npython tests/validate_code.py\n\n# Test file serving\nbash tests/test_file_serving.sh\n```\n\nSee `/tests/README.md` for detailed testing documentation.\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n### Development Setup\n1. Fork and clone the repository\n2. Copy to your HA `custom_components/` directory for testing\n3. Make your changes\n4. Run the test suite\n5. Submit a pull request\n\n## 📝 License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n## 🐛 Bug Reports \u0026 Feature Requests\n\nPlease use the [GitHub Issues](https://github.com/jonducrou/ha_visualiser/issues) to report bugs or request features.\n\n## 🙏 Acknowledgments\n\n- Built on the excellent [vis.js](https://visjs.org/) visualization library\n- Inspired by the Home Assistant community's need for better entity relationship visualization\n- Thanks to all contributors and users who provided feedback and testing\n\n## 📊 Project Status\n\nThis project is actively maintained and production-ready. Current version: **0.8.17**\n\n### Major Recent Updates\n\n#### **v0.8.17 - Template Select Support** ✨\n- **🔧 Template Select Fix**: Added support for `options` field in template select entities\n- **🔗 Enhanced Relationships**: Template select helpers now properly show entity dependencies\n- **📋 Select Action Support**: Detects entity references in select_option actions\n\n#### **v0.8.10 - \"No visualisations\" Error Fix** 🐛\n- **🔧 Graph Loading Fix**: Fixed critical \"'NoneType' object is not iterable\" error preventing visualization\n- **🛡️ Defensive Programming**: Added comprehensive error handling throughout graph building pipeline\n- **🔄 Safe Fallbacks**: Graph service returns empty results instead of crashing on errors\n\n#### **v0.8.9 - Critical Hotfix** 🚨\n- **🔧 Boot Failure Fix**: Fixed critical issue where v0.8.8 prevented Home Assistant from starting\n- **🛡️ Safe Auto-Setup**: Restored initialization safety checks while preserving automatic sidebar functionality\n- **⚡ Same-Day Fix**: Immediate hotfix release with comprehensive error handling and cleanup\n\n#### **v0.8.8 - Critical Architecture Fixes** 🔧\n- **✅ Bidirectional Relationships Fixed**: Automation relationships now work properly from devices, areas, zones, labels, and scenes\n- **✅ Automatic Installation**: Sidebar appears automatically after file installation - no manual setup required\n- **🏗️ Architecture**: Fixed early return bugs that prevented universal relationship detection\n\n#### **v0.8.4-0.8.7 - User Experience \u0026 Bug Fixes** 🎯\n- **🖱️ Native HA Entity Dialogs (v0.8.4)**: Single-click entities to open Home Assistant details dialogs\n- **🐛 Double-Click Navigation (v0.8.6)**: Fixed regression where double-click navigation stopped working  \n- **🏠 Enhanced Scene Support (v0.8.5)**: Comprehensive scene entity relationship detection\n- **🔗 Zone Self-Reference Fix (v0.8.7)**: Zones no longer show confusing relationships to themselves\n\n#### **Earlier Releases**\n- **✅ HACS Compliance \u0026 Scene Support (v0.8.3)**: Fixed HACS path conflicts and scene relationships\n- **✅ Comprehensive Group Support**: Light groups, switch groups, media player groups\n- **✅ Advanced Template Parsing**: Complex multi-line Jinja2 template support  \n- **✅ Helper Entity Detection**: Change-type helpers and proxy relationships\n- **✅ Enhanced Navigation**: Bidirectional relationship discovery\n\n### Roadmap\n- 🔄 Performance optimization for very large installations (\u003e1000 entities)\n- 🔄 Dashboard entity relationships\n- 🔄 Custom relationship definitions\n- 🔄 Saved views and layouts","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonducrou%2Fha_visualiser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonducrou%2Fha_visualiser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonducrou%2Fha_visualiser/lists"}