This Home Assistant custom integration provides real-time speed test monitoring for UniFi networks with enhanced dual WAN support. It supports all UniFi platforms including UDM Pro, UDM SE, Cloud Key, and traditional UniFi Controller software, allowing you to track download speed, upload speed, and ping directly within Home Assistant.
π v2.2.0: Smart Controller Detection - User-controlled controller type selection with intelligent entity creation based on actual WAN connections.
If you find this plugin useful, please consider donating. Your support is greatly appreciated!
- οΏ½ Smart Controller Detection: User-controlled selection between UDM and traditional controller types
- οΏ½ Intelligent WAN Management: UDM controllers automatically detect multiple WANs, traditional controllers use single WAN
- π Connection-Based Entities: Only creates entities for actually connected WAN interfaces
- π§ Universal Compatibility: Works with UDM Pro, UDM SE, UDM Base, Cloud Key Gen2+, and traditional UniFi Controllers
- οΏ½ Real-time Metrics: Monitor download speeds, upload speeds, and network latency (ping) for each connected WAN
- π Speed Test Initiation: Start speed tests remotely via Home Assistant (traditional controllers)
- π Home Assistant Integration: Full integration with automations, scripts, and dashboards
- βοΈ Clean Naming: Smart entity names based on number of connected WANs (single WAN gets clean names)
- π Reliable Authentication: Fixed endpoint selection prevents 401/404 errors
Configure multi-WAN support during setup to enable separate monitoring for each WAN interface:
See how the integration creates separate sensors for each WAN interface, providing individual speed metrics:
Monitor your primary WAN connection with dedicated sensors for download, upload, and ping:
Track your secondary WAN connection independently with its own set of performance metrics:
Notice how each WAN interface gets its own sensors, solving the issue where dual WAN setups previously showed identical speeds for both connections.
- Multi-WAN Support: β Full dual WAN detection and monitoring
- Speed Test Monitoring: β Automatic retrieval of speed test results
- Separate Sensors: β Individual sensors for each WAN interface
- URL Format:
https://udm-ip(port 443)
- Multi-WAN Support: β Single WAN hardware limitation
- Speed Test Monitoring: β Standard monitoring for single WAN
- Backward Compatible: β Works exactly as before
- URL Format:
https://udm-ip(port 443)
- Multi-WAN Support: β Depends on gateway model (USG Pro 4, UXG Pro)
- Speed Test Monitoring: β Full functionality
- API Support: β Modern UniFi OS endpoints
- URL Format:
https://cloudkey-ip(port 443)
- Multi-WAN Support:
β οΈ Depends on gateway hardware - Speed Test Monitoring: β Full functionality including API-initiated tests
- Legacy Support: β Enhanced compatibility with older API structures
- URL Format:
https://controller-ip:8443
- Open HACS in your Home Assistant instance
- Click on "Integrations"
- Click the three dots in the top right corner
- Select "Custom repositories"
- Add this repository URL
- Select "Integration" as the category
- Click "Add"
- Find "HA Unifi Speedtest" in the integration list
- Click "Download"
- Restart Home Assistant
- Download the latest release
- Copy the
custom_components/ha_unifi_speedtestdirectory to your Home Assistant'scustom_componentsdirectory - Restart Home Assistant
- Go to Configuration > Integrations
- Click "+" to add a new integration
- Search for "HA Unifi Speedtest"
- Enter the following details:
- URL: Your UniFi Controller URL
- UDM Pro/SE:
https://udm-ip - Cloud Key Gen2+:
https://cloudkey-ip - Traditional Controller:
https://controller-ip:8443
- UDM Pro/SE:
- Username: UniFi Controller admin username
- Password: UniFi Controller admin password
- Controller Type: Select your controller type
- UDM Pro/SE/Cloud Key Gen2+ - for UniFi OS devices (supports multi-WAN detection)
- Self-hosted Controller - for traditional UniFi Controller software (single WAN mode)
- Site (Optional): Site name (default: "default")
- SSL Verification (Optional): Enable/disable SSL certificate verification
- Multi-WAN Detection: Automatically enabled for UDM controllers, disabled for traditional controllers
- Enable Automatic Speed Tests: Schedule regular speed tests
- Speed Test Interval: How often to run automatic tests (15-1440 minutes)
- URL: Your UniFi Controller URL
π See the Screenshots section above for visual examples of the configuration process and resulting sensors.
The integration creates three sensors for monitoring network performance:
- UniFi Speed Test Download Speed (Mbit/s)
- UniFi Speed Test Upload Speed (Mbit/s)
- UniFi Speed Test Ping (ms)
For multi-WAN configurations, separate sensors are created for each WAN interface:
WAN 1:
- UniFi Speed Test Download Speed WAN (Mbit/s)
- UniFi Speed Test Upload Speed WAN (Mbit/s)
- UniFi Speed Test Ping WAN (ms)
WAN 2:
- UniFi Speed Test Download Speed WAN2 (Mbit/s)
- UniFi Speed Test Upload Speed WAN2 (Mbit/s)
- UniFi Speed Test Ping WAN2 (ms)
- UniFi Speed Test Runs: Track total number of speed tests performed
- UniFi API Health: Monitor integration connection status
Each multi-WAN sensor includes additional attributes:
interface_name: Physical interface (e.g., "eth9", "eth10")wan_networkgroup: WAN group name (e.g., "WAN", "WAN2")wan_number: Sequential WAN numbertotal_wan_interfaces: Total detected WAN interfacesis_primary_wan: Boolean indicating primary WAN (intelligently determined from routing/config)timestamp: Last speedtest timestampstatus: Interface status
Note on is_primary_wan: This attribute now reflects the actual primary WAN as configured in your UniFi controller, not just the first physical port detected. If you've configured a secondary port (like SFP+ port 2) as your primary WAN, that interface will correctly show is_primary_wan: true.
Initiates a speed test on your UniFi network.
Note: Only available for traditional UniFi Controller software. UDM Pro users must start speed tests manually via the UniFi Network web interface.
In Automations:
action:
- service: ha_unifi_speedtest.start_speed_testIn Scripts:
test_network_speed:
sequence:
- service: ha_unifi_speedtest.start_speed_test
- delay: "00:02:00" # Wait for test to complete
- service: notify.mobile_app
data:
message: "Speed test completed. Download: {{ states('sensor.unifi_speed_test_download_speed') }} Mbps"Lovelace Button:
type: button
name: Start Speed Test
tap_action:
action: call-service
service: ha_unifi_speedtest.start_speed_testManually refreshes speed test data from your UniFi controller.
type: entities
title: Network Speed Test
entities:
- entity: sensor.unifi_speed_test_download_speed
name: Download Speed
- entity: sensor.unifi_speed_test_upload_speed
name: Upload Speed
- entity: sensor.unifi_speed_test_ping
name: Ping- UDM Pro Compatibility: Fixed 404 errors on UDM Pro devices that don't support advanced routing endpoints
- Graceful Fallback: Integration now automatically detects unsupported UDM routing endpoints and switches to controller mode
- Cleaner Logs: Eliminated repetitive 404 error messages during setup
- Improved Stability: Better error handling prevents integration setup failures
- Smart Primary WAN Detection: Now properly identifies the primary WAN interface based on routing tables and network configuration
- Resolves Dual WAN Issues: Fixes issues where secondary physical ports configured as primary WAN showed incorrect "is_primary_wan" status
- Multiple Detection Methods: Uses routing table analysis, network configuration, and speed test data to determine the true primary WAN
- Smart Device Naming: Automatically names devices and sensors as "Primary WAN" and "Secondary WAN" for clarity
- Backward Compatible: Falls back to previous behavior if advanced detection fails
- Clear Device Names: Devices now show as "Primary WAN" and "Secondary WAN" instead of "WAN" and "WAN2"
- Improved Sensor Names: Sensors clearly indicate which is primary vs secondary
- Better Attributes: Enhanced sensor attributes show primary WAN status and interface details
- No More Auto-Detection: Eliminated confusing automatic controller detection that could misidentify your setup
- Clear Controller Options: Choose between "UDM Pro/SE/Cloud Key Gen2+" or "Self-hosted Controller"
- Reliable Endpoint Selection: Always uses the correct API endpoints for your controller type
- Fixed Authentication Issues: Resolved 401/404 errors caused by incorrect endpoint detection
- UDM Multi-WAN Logic: UDM controllers automatically check for multiple WAN connections
- Connection-Based Entity Creation: Only creates entities for actually connected WAN interfaces
- Clean Single WAN Naming: When only one WAN is connected, gets clean names like "Download Speed" instead of "Download Speed WAN1"
- Traditional Controller Single WAN: Self-hosted controllers use single WAN mode with appropriate endpoints
- Eliminated Unknown Entities: No more persistent "Unknown" entities that couldn't be removed
- Better Configuration UI: Clear descriptions help you choose the right controller type
- Improved Error Messages: More helpful messages when no speedtest data is available
- Predictable Behavior: Integration behaves consistently based on your controller type selection
- Added Poll Control: Configurable poll interval
- Fixed Compatibility Issues: Resolved UDM and Software-based controller issues
- Adjusted Initial Run Time: Corrected initial run timing for software controllers
- Manual Speed Test Button: Added on-demand speed test capability
Add this button to your dashboard for on-demand speed tests:
show_name: true
show_icon: true
type: button
name: Start Speed Test
icon: mdi:speedometer
tap_action:
action: call-service
service: ha_unifi_speedtest.start_speed_test- UniFi Speed Test Download Speed - Download speed in
Mbit/s - UniFi Speed Test Upload Speed - Upload speed in
Mbit/s - UniFi Speed Test Ping - Latency in
ms
- β UDM Pro / UDM SE / Cloud Key - Full support with automatic speed test triggering
- β Traditional UniFi Controller Software - Full support
- β Both controller types get fresh speed test data every hour automatically
- Install Integration: Add via HACS or copy files to
custom_components/ha_unifi_speedtest/ - Configure: Settings β Devices & Services β Add Integration β "HA Unifi Speedtest"
- Enter Details: Your UniFi controller URL, username, password, and controller type
- Done!: Sensors will appear automatically with hourly speed tests
The integration now works seamlessly with both UDM Pro and traditional UniFi Controllers, providing regular speed test data with proper Home Assistant unit standards.
403 Forbidden Error:
- Verify your username/password are correct
- Ensure the user account has admin privileges
- For UDM Pro: Disable 2FA temporarily or create a local admin user
Connection Refused:
- Check the URL format matches your controller type
- Verify the controller is accessible from Home Assistant
- Check firewall settings
No Speed Test Data:
- Ensure at least one speed test has been run on your controller
- Traditional controllers: Use the
start_speed_testservice - UDM Pro: Run a speed test via the web interface first
The integration now uses intelligent primary WAN detection to properly identify which WAN interface is actually your primary connection, even if you've configured a secondary port (like SFP+ port 2) as your primary WAN.
Primary WAN Detection Methods (in order of priority):
- Routing Table Analysis: Checks the default route (0.0.0.0/0) to identify which interface handles the primary traffic
- Network Configuration: Looks for explicitly configured primary WAN settings in the UniFi controller
- Speed Test Data: Uses the WAN interface with the most recent and complete speed test data
- Fallback: Uses the first detected interface (legacy behavior)
If Primary WAN Detection is Incorrect:
-
Check UniFi Network Settings:
- Verify that your desired primary WAN is correctly configured in the UniFi Network application
- Ensure the routing table reflects your intended primary WAN
-
Check Integration Logs:
- Enable debug logging (see below)
- Look for messages like: "Primary WAN determined from routing table: eth9_WAN"
- The logs will show which detection method was used
-
Check Sensor Attributes:
- Go to Developer Tools > States
- Find your UniFi speed test sensors
- Check if
is_primary_wanis correct on your configured primary WAN
Expected Behavior:
- The WAN interface you've configured as primary in UniFi should show
is_primary_wan: true - That interface should have the speed test results
- Other WAN interfaces should show
is_primary_wan: false - Devices and sensors will be named "Primary WAN" and "Secondary WAN"
To enable debug logging, add the following to your configuration.yaml:
logger:
default: info
logs:
custom_components.ha_unifi_speedtest: debugFeel free to contribute to this project. Please read the contributing guidelines before making a pull request.
This project is licensed under the MIT License - see the LICENSE file for details.
This integration is not affiliated with Ubiquiti Inc. or UI.com. All product names, logos, and brands are property of their respective owners.