A Home Assistant integration that visualizes your UniFi network topology as an interactive map. See how your devices connect, which clients are online, and understand your network structure at a glance.
- Interactive SVG topology map with pan, zoom, and touch gesture support
- Real-time updates via WebSocket, with HTTP polling fallback
- Device type filtering (gateway, switch, AP, clients)
- Node selection with detail panel showing IP, MAC, model, and firmware
- Entity linking to the official UniFi integration for click-through context
- VLAN coloring on nodes and edges
- Port utilization display with PoE power consumption
- 6 SVG themes: unifi, unifi-dark, minimal, minimal-dark, classic, classic-dark
- 2 icon sets: modern and isometric
- Binary sensors for device and client presence
- VLAN client-count sensors
- 4 automation blueprints (device offline/online, AP overload, VLAN threshold)
The built-in unifi integration handles device tracking, presence detection,
and switch control. This integration adds network topology visualization --
it shows how your devices connect to each other, which clients are on which
AP or switch port, and how your network is structured. They share the same
UniFi controller but serve different purposes. Entity linking works best when
both are installed: clicking a device in the map opens its HA entity directly.
You need Home Assistant 2024.12 or newer and a UniFi Network controller — either UniFi OS on a Dream Machine or a self-hosted controller. The integration connects directly to your controller's API, so cloud-only Ubiquiti accounts will not work.
Create a local UniFi account (required — do not use your Ubiquiti cloud account):
- Open the UniFi Network application and go to Settings > Admins & Users (on older firmware: System > Users).
- Click Add Admin and choose Local Access Only.
- Grant at least Read Only access to the Network application.
- Save the credentials — you will enter them during HA setup.
Recommended: Install the official Home Assistant UniFi integration first. This integration uses it to enrich the map with entity links, so clicking a device opens its HA entity directly.
- Click the badge above, or open HACS, go to Integrations, and search for UniFi Network Map.
- Click Download and confirm.
- Restart Home Assistant.
If the integration is not yet listed in HACS:
- In HACS, open the three-dot menu (top right) and select Custom repositories.
- Add
https://github.com/merlijntishauser/unifi-network-maps-hawith category Integration. - Search for UniFi Network Map, install it, and restart Home Assistant.
- Download the latest release from GitHub.
- Copy the
custom_components/unifi_network_mapfolder into your HA configuration directory at<config>/custom_components/unifi_network_map/. - Restart Home Assistant.
- Go to Settings > Devices & services and click Add Integration.
- Search for UniFi Network Map and select it.
- Enter your controller URL including the port — for example
https://192.168.1.1for a Dream Machine orhttps://192.168.1.1:8443for a self-hosted controller. - Enter the local username and password you created above, and the site name (usually
default). - Click Submit. The integration will verify connectivity and create the entry.
UniFi controllers ship with self-signed SSL certificates. SSL verification is disabled by default to handle this. If you have installed a trusted certificate on your controller, you can enable verification under the integration's options.
Once configured, open the integration's options panel to adjust display settings: port labels, client visibility, UniFi-only filter, isometric layout, and SVG dimensions.
The integration automatically registers its Lovelace card when Home Assistant starts. Simply edit your dashboard, add a new card, and search for "UniFi Network Map" in the card picker. Select your integration entry and the card will be configured automatically.
If the card does not appear in the picker after a fresh install, try clearing your browser cache with a hard refresh (Ctrl+Shift+R or Cmd+Shift+R). Home Assistant caches card resources aggressively and may need a manual refresh to pick up new cards.
Manual card configuration: If you prefer to configure the card through YAML, you will need the entry ID of your integration. Find this in Developer Tools under States by looking at the sensor.unifi_network_map_status entity and copying its entry_id attribute. Then add the card to your dashboard:
type: custom:unifi-network-map
entry_id: your_entry_id_here
card_height: 600The card_height option accepts a number (interpreted as pixels) or any valid CSS length value. Adjust this to fit your dashboard layout.
Navigation: Click and drag to pan around the map. Use your scroll wheel or pinch gestures on mobile to zoom in and out. Double-click to reset the view.
Selecting devices: Click on any device to select it. The detail panel on the right shows device information including name, IP address, MAC address, model, and firmware version. For clients, you will also see connection details like signal strength and which access point or switch port they connect through.
Filtering: Use the filter bar at the top of the card to show or hide device types. Click on Gateway, Switch, AP, or Client to toggle visibility. This is useful when you want to focus on infrastructure devices without the clutter of all connected clients.
Context menu: Right-click (or long-press on mobile) on any device to access quick actions. You can copy the device's MAC or IP address to your clipboard, or jump directly to related Home Assistant entities.
The card shows "Missing auth token": This typically means you are viewing the dashboard in a browser that is not logged into Home Assistant. The card requires an authenticated session to fetch data from the API. Log into Home Assistant in the same browser window.
The map appears empty: The integration relies on LLDP (Link Layer Discovery Protocol) to understand your network topology. Ensure LLDP is enabled on your UniFi devices. If you have a very simple network with only a gateway and wireless clients, there may not be much topology to display.
SSL certificate errors: If you see connection failures related to SSL, verify that your controller URL is correct and that SSL verification is disabled in the integration options (which is the default). Only enable SSL verification if you have installed a trusted certificate on your controller.
The card does not appear after installation: Clear your browser cache with a hard refresh. If it still does not appear, manually add the resource in your Lovelace configuration under Resources with URL /unifi-network-map/unifi-network-map.js and type module.
This integration focuses on network topology visualization within Home Assistant. It deliberately does not replicate features that UniFi's native dashboard already does well.
You will not find live throughput graphs, bandwidth statistics, latency monitoring, traffic analytics, DPI data, or speed test integration here. These features are core to the UniFi experience and are best viewed in the UniFi Network application where they receive full attention and polish.
Instead, this integration aims to make your network structure visible and accessible within Home Assistant, treating your network infrastructure as another part of your smart home that you can monitor and eventually automate.
The roadmap focuses on deeper Home Assistant integration rather than competing with UniFi's statistics features. Planned additions include network health sensors that expose device connectivity as automatable entities, and blueprint templates for common monitoring scenarios like alerting when critical infrastructure goes offline or when devices cannot reach expected services across VLANs.
See roadmap.md for details.
Contributions are welcome. The project uses Python 3.13 with strict type checking (Pyright) and Ruff for formatting. The frontend is TypeScript with ESLint and Prettier. Run make ci to execute all checks before submitting a pull request.
See CONTRIBUTING.md for development setup and architecture details.
Yes, LLMs and coding agents are (and will be) used in this project. We integrate AI carefully and responsibly, and never in a way that compromises data integrity, privacy, or security.
Please be responsible and transparent when using AI tools, and always put user privacy and data security first.
When you submit a PR, make sure you fully understand what the code does and what it might affect. Keep PRs small, and always run the tests before opening or updating one.
And a small personal note: using AI tools doesn’t mean this project didn’t take a lot of time and effort. Built with care, and a big shout-out to the entire Home Assistant ecosystem and its community — and to Ubiquiti and the UniFi product line, which are genuinely great products for the home.
I really fancy coffee! and stars! and… oh wait…
If you enjoy this integration, starring the repository and actually using it is already a great reward.
If you have feedback, I’d love to hear it — what you like, and especially what you don’t, so I can keep improving things. Issues and PRs are very welcome.
And if you want to buy me a coffee: that’s hugely appreciated!
MIT License. See LICENSE for details.