Skip to content

Commit 94eceed

Browse files
author
Zach Cheatham
committed
Promote 0.7.0 from beta
1 parent 153b544 commit 94eceed

File tree

2 files changed

+125
-14
lines changed

2 files changed

+125
-14
lines changed

‎CHANGELOG.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Changelog
22

3+
## 0.7.0
4+
- Added wired client support (Thanks @jonathanhoskin)
5+
- Added latest WiFi standards (Thanks @jonathanhoskin)
6+
37
## 0.6.1
48
- Fixes issue related to timeouts in newer versions of HA
59
- Fixes issue related to missing IP addresses from the Omada Controlller

‎info.md

Lines changed: 121 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,126 @@
1-
# Home Assistant TP-Link Omada Integration
2-
Adds Omada SDN Controller support to Home assistant. This integration requires [HACS](https://hacs.xyz).
1+
# TP-Link Omada Integration for Home Assistant
2+
3+
Integrate your TP-Link Omada SDN Controller with Home Assistant. This custom component allows you to monitor network clients and Omada devices, control aspects of your network, and leverage Omada data within your automations.
34

45
## Features
56

6-
- Device tracker for clients.
7-
- Client and device bandwidth sensors.
8-
- Client and device statistics sensors.
9-
- WLAN Radio controls
10-
- WLAN SSID controls
11-
- Client blocking toggles.
12-
- SSID filter.
7+
### Client Monitoring & Management
8+
9+
* **Device Tracker:** Presence detection for both wired and wireless clients.
10+
* Attributes include: IP, MAC, hostname, connection type (wired/wireless), connected AP, SSID, signal strength, etc.
11+
* Configurable disconnect timeout for marking clients as away.
12+
* **Sensors:**
13+
* Total Downloaded & Uploaded data.
14+
* Current RX/TX Activity.
15+
* RSSI & SNR for wireless clients.
16+
* Uptime.
17+
* Power Save status.
18+
* **Controls:**
19+
* Block/Unblock clients.
20+
* Reconnect wireless clients.
21+
* **Filtering:** Track clients only on specific SSIDs.
22+
23+
### Omada Device (APs, Gateways, Switches) Monitoring & Management
24+
25+
* **Device Tracker:** Presence detection for Omada network devices.
26+
* **Sensors:**
27+
* Total Downloaded & Uploaded data.
28+
* Current RX/TX Activity.
29+
* CPU & Memory Usage.
30+
* Uptime.
31+
* Connected client counts (total, 2.4GHz, 5GHz, 6GHz, guests, users).
32+
* AP Radio Utilization: TX/RX utilization and interference levels for 2.4GHz, 5GHz, and 6GHz bands.
33+
* **Controls (Primarily for Access Points):**
34+
* Enable/Disable 2.4GHz, 5GHz, and 6GHz radios (switches).
35+
* Enable/Disable individual SSIDs per AP (switches).
36+
* **Firmware Updates:**
37+
* Update entity to show available firmware, current version, and trigger upgrades.
38+
* Release notes for pending updates.
39+
40+
### Controller Features
41+
42+
* **Sensors:**
43+
* Total number of connected clients across the site.
44+
* WLAN Optimization (AI RF Planning) running status.
45+
* **Controls:**
46+
* Start WLAN Optimization (AI RF Planning).
47+
48+
### Configurability
49+
50+
* Granular control over which types of entities are created (e.g., disable bandwidth sensors if not needed).
51+
* Adjustable scan intervals for main data and detailed data.
52+
53+
### Comparison with Official Home Assistant Support
54+
55+
Home Assistant now includes an official core integration for TP-Link Omada SDN. Here's a comparison to help you choose based on information from the official Home Assistant Wiki as of May 2025:
56+
57+
| Feature | Official Integration | Custom |
58+
| :-------------------------------- | :------------------------------------------------------------- | :------------------------------------------------------------- |
59+
| **Installation** | Built-in, configured via Devices & Services. | Requires HACS, then configured via Devices & Services. |
60+
| **Controller Version Support** | 5.1.0 and later. | 4.4.8+ and v5.x.x |
61+
| **Device Support (General)** | Basic status, CPU/Memory, Firmware updates for all devices. | Similar, plus device trackers for Omada hardware. |
62+
| **Network Switch Control** | PoE per-port enable/disable. | Currently no specific per-port PoE exposed (focuses on APs/Clients). |
63+
| **Internet Gateway Control** | WAN/LAN connectivity, Online detection, Connect/Disconnect WAN. | Limited gateway-specific controls (focuses on APs/Clients). |
64+
| **Access Point Control** | Not explicitly detailed in official docs beyond basic status. | Radio (2G/5G/6G) on/off, SSID on/off per AP. |
65+
| **Client Device Tracking** | Tracks Wi-Fi clients (disabled by default). | Tracks wired and wireless clients. |
66+
| **Client Information** | Basic tracking for presence. | IP, MAC, hostname, AP, SSID, signal, etc. |
67+
| **Client Sensors** | Not detailed. | Download/Upload, RX/TX rate, RSSI, SNR, Uptime, Power Save. |
68+
| **Client Controls** | Not detailed. | Block/Unblock switch, Reconnect button. |
69+
| **Client Filtering** | All known Wi-Fi clients. | SSID-based filtering for wireless clients. |
70+
| **AP Radio/Bandwidth Sensors** | Not detailed. | Client counts per band, radio utilization (TX/RX/Interference). |
71+
| **WLAN Optimization Control** | Not detailed. | Binary sensor for status, button to start. |
72+
| **Configuration Granularity** | Primarily site selection. | Toggle individual sensor/switch types for clients and devices, adjust scan intervals, disconnect timeouts. |
73+
| **Data Update Frequency** | Default HA polling, client refresh via service call. | Configurable scan intervals for basic and detailed data. |
74+
| **Cloud Controller Support** | No. | No. |
75+
76+
You can potentially run both integrations if they target different aspects or if you are migrating, but be mindful of potential API rate limiting on your Omada Controller.
77+
78+
## Configuration
79+
80+
1. Go to **Settings > Devices & Services** in Home Assistant.
81+
2. Click the **+ ADD INTEGRATION** button (bottom right).
82+
3. Search for "TP-Link Omada" and select it.
83+
4. You will be prompted for the following information:
84+
* **URL:** The full URL to access your Omada Controller (e.g., `https://omada.yourdomain.com` or `http://192.168.1.10`).
85+
* **Site:** The name of the Omada site you want to integrate (default is "Default").
86+
* **Username:** Your Omada Controller username.
87+
* **Password:** Your Omada Controller password.
88+
* **Verify SSL:** Check this if your controller uses a valid SSL certificate. Uncheck for self-signed certificates or HTTP.
89+
5. Click **SUBMIT**.
90+
91+
*Tip: If the integration is encountering an API or related error during configuration, ensure your site name is correct!*
92+
93+
### Options
94+
95+
After successful setup, you can further customize the integration's behavior:
96+
97+
1. Go to **Settings > Devices & Services**.
98+
2. Find your TP-Link Omada integration entry and click **CONFIGURE**.
99+
3. You can adjust:
100+
* **Scan Intervals:** How frequently to poll the controller for basic and detailed updates.
101+
* **Tracking:** Enable/disable tracking for clients or Omada devices.
102+
* **Client Entity Options:** Toggle specific sensors (bandwidth, uptime) and controls (block switch) for clients. Set disconnect timeout and SSID filters.
103+
* **Device Entity Options:** Toggle specific sensors (bandwidth, statistics, client counts, radio utilization) and controls for Omada devices.
104+
105+
## Supported Controller Versions
106+
107+
This integration is tested and developed against various Omada Controller versions. Generally, it supports:
108+
109+
* Omada Controller v5.x (including the latest 5.13.x versions).
110+
111+
Please note that TP-Link may introduce API changes in new controller versions. If you encounter issues, check the [CHANGELOG.md](CHANGELOG.md) or open an issue.
112+
Additionally, this integration is known to not be compatible with the cloud version of Omada SDN.
113+
114+
## Future Features
115+
116+
* More comprehensive support for Omada switches and gateways.
117+
* Individual client-based filtering for entity creation (beyond SSID).
118+
* Additional SDN and site-wide controls and statistics.
119+
* PoE Controls
13120

14-
## Planned Features
121+
## Troubleshooting
15122

16-
- Better wired client support (help wanted.)
17-
- Better switch and router support (help wanted.)
18-
- Individual client filters.
19-
- SDN and site controls and statistics.
123+
* **Connectivity Issues:** Ensure your Home Assistant instance can reach the Omada Controller's IP address and port. Ensure "Verify SSL" is set appropriately.
124+
* **API Errors:** Double-check your URL, username, password, and site name.
125+
* **Entities Not Appearing:** Verify the options in the integration's configuration to ensure the desired entity types are enabled. Check Home Assistant logs for errors.
126+
* For other issues, please check the Home Assistant logs and [open an issue](https://github.com/zachcheatham/ha-omada/issues) on GitHub with relevant log details.

0 commit comments

Comments
 (0)