{"id":31398056,"url":"https://github.com/definitelyadev/custom-areas-integration","last_synced_at":"2025-09-29T14:03:23.155Z","repository":{"id":313826574,"uuid":"1052971841","full_name":"DefinitelyADev/custom-areas-integration","owner":"DefinitelyADev","description":"A custom integration for Home Assistant that creates composite \"Room\" sensors with UI configuration.","archived":false,"fork":false,"pushed_at":"2025-09-19T00:33:01.000Z","size":435,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-19T00:40:38.910Z","etag":null,"topics":["hacs","home-assistant","home-automation","integration","sensor"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DefinitelyADev.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-09-08T20:03:11.000Z","updated_at":"2025-09-19T00:38:16.000Z","dependencies_parsed_at":"2025-09-09T02:37:31.153Z","dependency_job_id":"c9f0497c-21a6-40d4-b7ed-f081b45a2784","html_url":"https://github.com/DefinitelyADev/custom-areas-integration","commit_stats":null,"previous_names":["definitelyadev/room-entity","definitelyadev/custom-areas-integration"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/DefinitelyADev/custom-areas-integration","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DefinitelyADev%2Fcustom-areas-integration","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DefinitelyADev%2Fcustom-areas-integration/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DefinitelyADev%2Fcustom-areas-integration/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DefinitelyADev%2Fcustom-areas-integration/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DefinitelyADev","download_url":"https://codeload.github.com/DefinitelyADev/custom-areas-integration/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DefinitelyADev%2Fcustom-areas-integration/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":277526756,"owners_count":25833447,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-29T02:00:09.175Z","response_time":84,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["hacs","home-assistant","home-automation","integration","sensor"],"created_at":"2025-09-29T14:01:17.738Z","updated_at":"2025-09-29T14:03:23.140Z","avatar_url":"https://github.com/DefinitelyADev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Custom Areas Integration](/docs/images/logo.png \"Custom Areas Integration Logo\")\n\n# Custom Areas Integration\n\nA custom integration for Home Assistant that creates composite \"Area\" sensors with UI configuration.\n\n[![CI](https://github.com/DefinitelyADev/custom-areas-integration/actions/workflows/ci.yml/badge.svg)](https://github.com/DefinitelyADev/custom-areas-integration/actions/workflows/ci.yml)\n[![HACS](https://img.shields.io/badge/HACS-Custom%20Areas-blue.svg)](https://github.com/hacs/integration)\n[![codecov](https://codecov.io/gh/DefinitelyADev/custom-areas-integration/branch/master/graph/badge.svg)](https://codecov.io/gh/DefinitelyADev/custom-areas-integration)\n[![Release](https://img.shields.io/github/v/release/DefinitelyADev/custom-areas-integration?sort=semver)](https://github.com/DefinitelyADev/custom-areas-integration/releases)\n![Python Versions](https://img.shields.io/badge/python-3.10+-blue.svg)\n![GitHub License](https://img.shields.io/github/license/DefinitelyADev/custom-areas-integration)\n\n## Features\n\n- **UI Configuration**: Add areas through Home Assistant's UI with an intuitive config flow\n- **Composite Sensors**: Each area creates a summary sensor that combines multiple entity states\n- **Real-time Updates**: Uses event-driven updates instead of polling for instant state changes\n- **Device Registry**: Creates proper devices in Home Assistant's device registry\n\n## Documentation\n\n📖 **Complete Documentation**: [docs/](docs/)\n\n- **[Design Rationale](docs/rationale.md)** - Why this exists and how it pairs with Custom Features for Home Assistant Cards/Area-like UX\n- **[API Reference](docs/api.md)** - Entity states, attributes, and configuration schema\n- **[Configuration Examples](docs/examples.md)** - Real-world setup examples and use cases\n- **[Developer Guide](docs/developer.md)** - Architecture overview and development setup\n- **[CHANGELOG.md](CHANGELOG.md)** - Version history and release notes\n\n## Disclaimer (The Vibe Clause)\n\nThis project is proudly *vibe coded*. It was started because it felt like a good idea at the time, and it will continue evolving based on equal parts usefulness, curiosity, and whatever soundtrack is playing. That means:\n\n- Some abstractions may appear only after their third sibling arrives\n- Refactors can materialize suddenly (like motion-triggered automation)\n- Tests occasionally chase features (they do catch up)\n- Naming conventions are consistent... with the mood of the day\n\nIf you demand immaculate enterprise architecture, you are lovingly invited to open a PR. If you enjoy useful sensors, good intentions, and iterative polish: welcome. It works, it's helpful, and it will continue to vibe forward. 🚀\n\nNot affiliated with Home Assistant — just vibing on top of it.\n\n## Installation\n\n### HACS Installation (Recommended)\n\n1. Ensure [HACS](https://hacs.xyz/) is installed in your Home Assistant instance\n2. Add this repository as a custom repository in HACS:\n   - Go to HACS → Integrations\n   - Click the three dots (⋮) in the top right\n   - Select \"Custom repositories\"\n   - Add: `https://github.com/DefinitelyADev/room-entity`\n   - Category: Integration\n3. Search for \"Areas\" in HACS and install it\n4. Restart Home Assistant\n\n### Manual Installation\n\n1. Download the `custom_components/custom_areas/` folder from this repository\n2. Copy it to your Home Assistant's `custom_components/` directory\n3. Restart Home Assistant\n\n## Configuration\n\n### Adding an Area\n\n1. Go to **Settings** → **Devices \u0026 Services** → **Add Integration**\n2. Search for \"Areas\" and select it\n3. Configure your area:\n   - **Area Name**: Display name for the area\n   - **Power Sensor**: Optional sensor for power consumption\n   - **Energy Sensor**: Optional sensor for energy consumption\n   - **Temperature Sensor**: Optional temperature sensor\n   - **Humidity Sensor**: Optional humidity sensor\n   - **Motion Sensor**: Optional motion detection sensor\n   - **Window Sensor**: Optional window/door sensor\n   - **Climate Entity**: Optional climate control entity\n   - **Active Power Threshold**: Power level (in watts) above which the area is considered \"active\"\n\n## Usage\n\n### Summary Sensor\n\nEach area creates a summary sensor with these states:\n- **active**: Area is currently active (motion detected OR power above threshold)\n- **idle**: Area has configured entities but is not active\n- **unknown**: No entities configured for the area\n\nThe summary sensor includes these attributes:\n- `power_w` (numeric) and `power` (string with unit, e.g. \"28.6 W\")\n- `energy_wh` (numeric) and `energy` (string with unit, e.g. \"12.3 Wh\")\n- `temperature_c` (numeric) and `temperature` (string with unit, e.g. \"21.5 °C\")\n- `humidity_pct` (numeric) and `humidity` (string with unit, e.g. \"45 %\")\n- `occupied`: Motion detection status\n- `window_open`: Window/door status\n- `climate_mode`: Current climate mode\n   - `climate_target_c` (numeric) and `climate_target` (string with unit)\n\n### Area vs Tile (with Custom Features for Home Assistant Cards)\n\nIf you want to mimic the Area card using a Tile card with Custom Features for Home Assistant Cards features and the area summary sensor:\n\n![Area card vs Tile card with Custom Features for Home Assistant Cards](docs/images/area-vs-tile.png)\n\n## State Logic\n\nThe area state is determined by this priority:\n1. If motion sensor is ON → **active**\n2. If power consumption \u003e active threshold → **active**\n3. If any core entities exist but conditions 1-2 are false → **idle**\n4. If no entities configured → **unknown**\n\n## Icons\n\nThe summary sensor icon changes based on area status:\n- Window open: `mdi:window-open-variant`\n- Motion detected: `mdi:motion-sensor`\n- Default: `mdi:home`\n\n## Device Registry\n\nEach area creates a device in Home Assistant's device registry, allowing you to:\n- Group all area sensors together\n- View device information\n- Manage device settings\n\n## Requirements\n\n- Home Assistant 2024.1.0 or later\n- Python 3.10 or later\n- Entities must exist before configuring the area\n\n## Troubleshooting\n\n### Common Issues\n\n1. **\"Entity not found\" error**: Ensure all selected entities exist and are available\n2. **Sensor not updating**: Check that source entities are publishing state changes\n\n### Debug Logging\n\nAdd this to your `configuration.yaml` to enable debug logging:\n\n```yaml\nlogger:\n  default: info\n  logs:\n    custom_components.custom_areas: debug\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Submit a pull request\n\n## CI/CD\n\nThis project uses GitHub Actions for continuous integration and deployment:\n\n### Automated Checks\n\n- **Tests**: Run on Python 3.10, 3.11, and 3.12\n- **Validation**: Custom validation of manifest, translations, and structure\n- **Type Checking**: Pyright type checking\n- **Linting**: Black formatting, isort import sorting, and flake8 linting\n- **HACS Validation**: Ensures compatibility with HACS\n- **Pre-commit**: Code quality checks on pull requests\n\n### Workflows\n\n- `ci.yml`: Main CI pipeline triggered on push/PR\n- `pre-commit.yml`: Code quality checks\n- `manual-validation.yml`: Manual validation triggers\n\n### Local Development\n\nRun all checks locally:\n\n```bash\npip install -r requirements-dev.txt\npython check_all.py\n```\n\nOr run individual checks:\n\n```bash\npython validate.py          # Custom validation\npython run_tests.py         # Unit tests\npyright                    # Type checking\nblack --check custom_components/custom_areas/    # Code formatting\nisort --check-only custom_components/custom_areas/  # Import sorting\nflake8 custom_components/custom_areas/           # Linting\n```\n\n### Pre-commit Setup\n\nInstall pre-commit hooks for automatic code quality:\n\n```bash\npip install pre-commit\npre-commit install\n```\n\n## License\n\nThis integration is licensed under the Apache License 2.0.\n\n## Author\n\n**Tsakiridis Ilias**\nGitHub: [@DefinitelyADev](https://github.com/DefinitelyADev)\nLocation: Greece\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdefinitelyadev%2Fcustom-areas-integration","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdefinitelyadev%2Fcustom-areas-integration","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdefinitelyadev%2Fcustom-areas-integration/lists"}