A Home Assistant custom integration for managing TR-069 CPE devices (routers, ONTs, gateways) through a GenieACS instance.
GenieACS is an open-source Auto Configuration Server (ACS) that speaks the TR-069 protocol. This integration connects to the GenieACS Northbound Interface (NBI) REST API to bring your managed network devices into Home Assistant.
- A running GenieACS instance with the NBI accessible (default port
7557) - One or more CPE devices connected to GenieACS via TR-069
- Home Assistant 2024.1 or later
- HACS installed
- Open HACS in Home Assistant
- Click the three-dot menu in the top right and select Custom repositories
- Add
https://github.com/GeiserX/genieacs-hawith category Integration - Search for "GenieACS" and install it
- Restart Home Assistant
- Copy the
custom_components/genieacsfolder into your Home Assistantconfig/custom_components/directory - Restart Home Assistant
- Go to Settings > Devices & Services > Add Integration
- Search for GenieACS
- Enter your NBI URL (e.g.,
http://genieacs:7557) - Optionally enter HTTP Basic auth credentials if your NBI requires authentication
- The integration will test the connection and discover all managed devices
For each CPE device managed by GenieACS, the integration creates the following entities:
| Entity | Type | Description |
|---|---|---|
| Online | Binary Sensor | on if the device reported to GenieACS within the last 5 minutes |
| WAN IP address | Sensor | External IP address from the WAN interface |
| Uptime | Sensor | Device uptime in seconds |
| Firmware | Sensor | Software version (diagnostic) |
| Manufacturer | Sensor | Device manufacturer (diagnostic) |
| Model | Sensor | Device model name (diagnostic) |
| Serial number | Sensor | Device serial number (diagnostic) |
| Reboot | Button | Send a reboot command to the device via TR-069 |
| Refresh parameters | Button | Trigger a parameter refresh from the device (diagnostic) |
TR-069 devices use one of two parameter tree roots:
- TR-181:
Device.(newer standard) - TR-098:
InternetGatewayDevice.(older standard)
This integration automatically handles both. It checks both root paths when reading device parameters, so it works with any compliant CPE regardless of which data model it implements.
- genieacs-container -- Production-ready Docker deployment for GenieACS
- genieacs-mcp -- Model Context Protocol server for GenieACS