Looking for practical details, troubleshooting, and behavior notes? See documentation.md.
A Home Assistant integration that connects your Homely alarm system to Home Assistant using the Homely API, providing read-only, real-time monitoring of your alarm and supported devices.
Make sure HACS is installed.
Click Download, then restart Home Assistant.
Download the latest release, copy the homely folder to /config/custom_components/homely/, then restart Home Assistant and configure the integration.
- Go to Settings → Devices & Services → "+ Add Integration"
- Search for "Homely"
- Enter your Homely account credentials (username and password)
- If your account has multiple Homely homes, choose either Add all homes or one specific home from the dropdown
- Finish setup
Add all homes creates one config entry per available home. Homes that are already configured are skipped automatically.
⭐ If you find this integration useful, please consider giving it a star on GitHub! ⭐
After setup, open the integration options to adjust:
- Polling interval: Adjust API polling frequency in seconds as a backup for WebSocket updates Default is 180 seconds and the minimum is 30 seconds.
- WebSocket toggle: Enable or disable instant updates
- Polling while WebSocket is connected: Optional. If disabled, API polling pauses while WebSocket is connected, does a safety poll every 6 hours, and resumes automatically if the WebSocket disconnects
For deeper details and value references, including sensor status values, see documentation.md.
If Homely adds or removes devices on a location, the integration detects the topology change and reloads the entry automatically. New devices can then appear without manual reconfiguration. Devices that disappear from the API are not deleted automatically.
- Verify your Homely username and password are correct
- If your account has multiple locations, make sure the correct location was selected during setup
- Enable debugging (shown below) and check HA logs
- If a device or sensor is present but does not work as expected, please use the Bug report form
If you can't resolve your problem, please open a GitHub issue and choose the matching form.
If a device is missing, or a device is present but missing sensors, use the Missing device or sensor issue form.
To troubleshoot issues or monitor WebSocket and API activity, open the Homely integration, click the three dots in the upper-right corner, and select Enable debug logging. You can also add this to your configuration.yaml:
logger:
default: info
logs:
custom_components.homely: debugThen check the logs under Settings → System → Logs.
The integration aims to support all devices and sensors exposed by the Homely API. In practice, Frient devices should generally be well supported, and Yale Doorman and similar locks should also work when their states are available through the API.
Not every device shown in the Homely app is necessarily exposed through the API. If Homely does not expose a device or a sensor, the integration cannot add it in Home Assistant. Some vendor-specific devices, such as the Namron Smart Plug 16A, are known examples.
The Homely API is currently read-only, so this integration focuses on monitoring and status in Home Assistant rather than direct device control.
- Alarm status is supported
- Frient devices should generally be supported
- Yale Doorman and similar locks should generally work when exposed through the API
- Direct device control is not available because the Homely API is read-only
For a support matrix and more detail about device coverage, API limitations, and known gaps, see documentation.md.
If a device is missing, or a device is present but missing sensors, please use the Missing device or sensor issue form.
Contributions are welcome. You can report bugs or suggest features, or submit a pull request.
Before opening a PR, run:
python -m ruff check custom_components testspytestpython -m mypy --config-file mypy.ini -p custom_components.homely
Created by: Ludvik | Inspired by Homely MQTT Add-on
Disclaimer: Unofficial project, not affiliated with Homely. Relies on Homely's cloud API which may change.
License: MIT License - see LICENSE