GenieACS for Home Assistant
April 16, 2026 · View on GitHub
GenieACS for Home Assistant
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.
Prerequisites
- 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
Installation
HACS (Recommended)
- 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
Manual
- Copy the
custom_components/genieacsfolder into your Home Assistantconfig/custom_components/directory - Restart Home Assistant
Configuration
- 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
Entities
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-181 and TR-098 Compatibility
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 Ecosystem
This project is part of a broader set of tools for working with GenieACS:
| Project | Type | Description |
|---|---|---|
| genieacs-docker | Docker + Helm | Production-ready multi-arch Docker image and Helm chart |
| genieacs-ansible | Ansible Collection | Dynamic inventory plugin and device management modules |
| genieacs-mcp | MCP Server | AI-assisted device management via Model Context Protocol |
| n8n-nodes-genieacs | n8n Node | Workflow automation for GenieACS |
| genieacs-services | Service Defs | Systemd/Supervisord service definitions |
| genieacs-sim-container | Simulator | Docker-based GenieACS simulator for testing |
Other Home Assistant Integrations by GeiserX
- cashpilot-ha — Passive income earnings sensors
- duplicacy-ha — Backup status monitoring
- pumperly-ha — Fuel and EV charging price sensors