{"id":45261616,"url":"https://github.com/bullitt186/ha-omada-open-api","last_synced_at":"2026-04-11T08:07:04.401Z","repository":{"id":334512572,"uuid":"1140110146","full_name":"bullitt186/ha-omada-open-api","owner":"bullitt186","description":"TP-Link Omada SDN integration for Home Assistant — monitor APs, switches, gateways, and clients with sensors, device trackers, PoE control, firmware updates, and more via the Omada Open API.","archived":false,"fork":false,"pushed_at":"2026-02-20T23:16:53.000Z","size":1273,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-21T04:31:34.369Z","etag":null,"topics":["custom-component","hacs","home-assistant","home-assistant-integration","network-monitoring","omada","sdn","tp-link"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bullitt186.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-22T20:55:53.000Z","updated_at":"2026-02-20T23:16:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bullitt186/ha-omada-open-api","commit_stats":null,"previous_names":["bullitt186/ha-omada-open-api"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/bullitt186/ha-omada-open-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bullitt186%2Fha-omada-open-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bullitt186%2Fha-omada-open-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bullitt186%2Fha-omada-open-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bullitt186%2Fha-omada-open-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bullitt186","download_url":"https://codeload.github.com/bullitt186/ha-omada-open-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bullitt186%2Fha-omada-open-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29969243,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T11:43:06.159Z","status":"ssl_error","status_checked_at":"2026-03-01T11:43:03.887Z","response_time":124,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["custom-component","hacs","home-assistant","home-assistant-integration","network-monitoring","omada","sdn","tp-link"],"created_at":"2026-02-21T00:27:24.858Z","updated_at":"2026-03-01T12:00:54.389Z","avatar_url":"https://github.com/bullitt186.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TP-Link Omada Open API Integration for Home Assistant\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/logo@2x.png\" alt=\"TP-Link Omada Open API\" width=\"256\"\u003e\n\u003c/p\u003e\n\n[![HACS Custom](https://img.shields.io/badge/HACS-Custom-41BDF5.svg?style=for-the-badge)](https://github.com/hacs/integration)\n[![GitHub Release](https://img.shields.io/github/release/bullitt186/ha-omada-open-api.svg?style=for-the-badge)](https://github.com/bullitt186/ha-omada-open-api/releases)\n[![License](https://img.shields.io/github/license/bullitt186/ha-omada-open-api.svg?style=for-the-badge)](LICENSE)\n\n**Monitor and control your TP-Link Omada SDN infrastructure directly from Home Assistant.**\n\n[![My Home Assistant](https://my.home-assistant.io/badges/config_flow_start.svg)](https://my.home-assistant.io/redirect/config_flow_start/?domain=omada_open_api)\n\n---\n\n## Disclaimer\n\n\u003e This integration is under active development and has been heavily developed with AI assistance. The maintainer cannot guarantee long-term support. Use at your own risk and always test in a non-production environment first. Contributions and feedback are welcome!\n\n---\n\n## Table of Contents\n\n- [About](#about)\n- [Features](#features)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Entities](#entities)\n- [Automation Examples](#automation-examples)\n- [Options](#options)\n- [Supported Devices](#supported-devices)\n- [Data Update](#data-update)\n- [Use Cases](#use-cases)\n- [Diagnostics](#diagnostics)\n- [Removing the Integration](#removing-the-integration)\n- [Troubleshooting](#troubleshooting)\n- [Services](#services)\n- [Known Limitations](#known-limitations)\n- [Development](#development)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## About\n\nThis integration connects to your **TP-Link Omada SDN** controller through the **Omada Open API** and exposes your network infrastructure as Home Assistant devices and entities. It supports cloud-managed and locally-hosted controllers.\n\nWith it you can:\n\n- Monitor access points, switches, and gateways (status, CPU, memory, uptime, PoE budgets)\n- Track connected clients with presence detection\n- Control PoE per switch port, toggle site-wide LEDs, and block/unblock clients\n- Reboot devices, trigger locate (LED flash), reconnect wireless clients, and start WLAN optimization\n- Install firmware updates directly from Home Assistant\n- Monitor per-client application traffic when DPI is enabled\n- Automate based on any of the above\n\nAuthentication uses **OAuth 2.0 Client Credentials** with fully automatic token refresh — set it up once and forget it.\n\n---\n\n## Features\n\n| Platform | What it provides |\n|---|---|\n| **Sensor** | Device metrics (clients, uptime, CPU, memory, model, firmware, link speed, public IP, etc.), per-band client counts for APs, client metrics (IP, RSSI, SNR, SSID, traffic, activity rates), PoE budget \u0026 per-port power, per-app traffic |\n| **Binary Sensor** | Device online/offline, firmware update available, client power-save mode |\n| **Device Tracker** | Presence detection for devices (APs, switches, gateways) and selected clients |\n| **Switch** | PoE enable/disable per switch port, site-wide LED toggle, client network access (block/unblock) |\n| **Button** | Device reboot, device locate (flash LEDs), wireless client reconnect, site-wide WLAN optimization |\n| **Update** | Firmware update entity with install action |\n\n\u003e **Note on permissions:** PoE and LED switches are only created when the API credentials have editing rights. If your credentials are viewer-only, the integration automatically detects this during setup and skips those controls — all monitoring entities are still created.\n\n---\n\n## Installation\n\n### HACS (Recommended)\n\n1. Open **HACS → Integrations → ⋮ → Custom repositories**\n2. Add `https://github.com/bullitt186/ha-omada-open-api` as **Integration**\n3. Search for **TP-Link Omada Open API**, click **Download**, then restart Home Assistant\n4. Go to **Settings → Devices \u0026 Services → Add Integration** and search for **TP-Link Omada Open API**\n\n[![My Home Assistant](https://my.home-assistant.io/badges/config_flow_start.svg)](https://my.home-assistant.io/redirect/config_flow_start/?domain=omada_open_api)\n\n### Manual\n\n1. Download the [latest release](https://github.com/bullitt186/ha-omada-open-api/releases) and copy the `omada_open_api` folder into your `custom_components/` directory\n2. Restart Home Assistant\n3. Add the integration via **Settings → Devices \u0026 Services**\n\n---\n\n## Configuration\n\n### Obtaining API Credentials\n\n1. Log in to the [TP-Link Omada Cloud Portal](https://omada.tplinkcloud.com)\n2. Go to **Settings → Platform Integration → OpenAPI** (or your controller's equivalent)\n3. Create an application to obtain your **Client ID**, **Client Secret**, and note your **Omada ID** (controller ID)\n\n### Setup Flow\n\nThe integration guides you through a multi-step configuration:\n\n1. **Controller type** — Cloud or local\n2. **Region** (cloud) or **API URL** (local)\n3. **Credentials** — Omada ID, Client ID, Client Secret\n4. **Sites** — Select one or more sites to monitor\n5. **Clients** *(optional)* — Select clients for presence detection and detailed monitoring\n6. **Applications** *(optional)* — Select DPI-tracked applications for per-client traffic sensors (requires DPI enabled on your gateway)\n\n### Installation Parameters\n\nThe following parameters are required during the initial setup flow:\n\n| Parameter | Step | Required | Description |\n|---|---|---|---|\n| **Controller Type** | 1 – Controller type | Yes | `Cloud` (TP-Link cloud-hosted) or `Local` (self-hosted controller). Determines the API endpoint used. |\n| **Region** | 2 – Region *(cloud only)* | Yes (cloud) | Cloud region where your controller is deployed: **United States**, **Europe**, or **Asia Pacific (Singapore)**. Sets the API base URL automatically. |\n| **Controller URL** | 2 – Local URL *(local only)* | Yes (local) | Full URL of your self-hosted controller, including protocol and port (e.g., `https://192.168.1.100:8043`). |\n| **Omada ID** | 3 – Credentials | Yes | The MSP ID or Customer ID from your Open API application. Found in **Settings → Platform Integration → Open API** in the Omada controller. |\n| **Client ID** | 3 – Credentials | Yes | OAuth2 Client ID from your Open API application. Generated when creating a new application in the controller. |\n| **Client Secret** | 3 – Credentials | Yes | OAuth2 Client Secret from your Open API application. Shown once when the application is created — copy and store it securely. |\n| **Sites** | 4 – Site selection | Yes | One or more Omada sites to monitor. All devices and clients under the selected sites become available as Home Assistant entities. |\n| **Clients** | 5 – Client selection | No | Network clients to track for presence detection and per-client metrics. Can be modified later via Options. Limited to the first 200 clients in the UI. |\n| **Applications** | 6 – Application selection | No | DPI-tracked applications for per-client traffic monitoring (upload/download sensors). Requires DPI enabled on the gateway. Can be modified later via Options. |\n\n**Network requirements:**\n- Cloud: outbound HTTPS (443) to TP-Link cloud\n- Local: network access to your controller's API port\n\n---\n\n## Entities\n\n### Per Device (AP, Switch, Gateway)\n\n| Entity | Example | Description |\n|---|---|---|\n| Sensor | `sensor.office_ap_connected_clients` | Connected client count |\n| Sensor | `sensor.office_ap_uptime` | Uptime as a timestamp |\n| Sensor | `sensor.office_ap_cpu_utilization` | CPU usage (%) |\n| Sensor | `sensor.office_ap_memory_utilization` | Memory usage (%) |\n| Sensor | `sensor.office_ap_clients_2_4_ghz` | 2.4 GHz clients (APs only) |\n| Sensor | `sensor.office_ap_clients_5_ghz` | 5 GHz clients (APs only) |\n| Sensor | `sensor.main_switch_poe_power_used` | PoE power draw (W) |\n| Sensor | `sensor.main_switch_poe_power_budget` | PoE power budget (W) |\n| Sensor | `sensor.main_switch_poe_power_remaining` | PoE remaining (%) |\n| Sensor | `sensor.main_switch_port_3_poe_power` | Per-port PoE power (W) |\n| Binary Sensor | `binary_sensor.office_ap_status` | Online / offline |\n| Binary Sensor | `binary_sensor.office_ap_firmware_update_available` | Firmware update needed |\n| Device Tracker | `device_tracker.office_ap` | Device presence (home/away) |\n| Switch | `switch.main_switch_port_3_poe` | PoE on/off per port |\n| Switch | `switch.home_led` | Site-wide LED on/off |\n| Button | `button.office_ap_reboot` | Reboot device |\n| Button | `button.office_ap_locate` | Flash LEDs / beep to locate |\n| Button | `button.home_wlan_optimization` | Start WLAN optimization |\n| Update | `update.office_ap_firmware` | Firmware with install action |\n\n### Per Client\n\n| Entity | Example | Description |\n|---|---|---|\n| Sensor | `sensor.johns_iphone_ip_address` | Current IP |\n| Sensor | `sensor.johns_iphone_rssi` | Signal strength (dBm) |\n| Sensor | `sensor.johns_iphone_snr` | Signal-to-noise ratio (dB) |\n| Sensor | `sensor.johns_iphone_ssid` | Connected network |\n| Sensor | `sensor.johns_iphone_connected_to` | Connected AP / switch |\n| Sensor | `sensor.johns_iphone_downloaded` | Total downloaded (MB) |\n| Sensor | `sensor.johns_iphone_uploaded` | Total uploaded (MB) |\n| Sensor | `sensor.johns_iphone_rx_activity` | RX rate (MB/s) |\n| Sensor | `sensor.johns_iphone_tx_activity` | TX rate (MB/s) |\n| Sensor | `sensor.johns_iphone_uptime` | Client uptime |\n| Binary Sensor | `binary_sensor.johns_iphone_power_save` | Power-save mode (wireless) |\n| Device Tracker | `device_tracker.johns_iphone` | Presence detection |\n| Switch | `switch.johns_iphone_network_access` | Block / unblock client |\n| Button | `button.johns_iphone_reconnect` | Reconnect wireless client |\n\n### Per Client + Application (DPI)\n\n| Entity | Example | Description |\n|---|---|---|\n| Sensor | `sensor.johns_iphone_youtube_download` | App download traffic (auto-scaled) |\n| Sensor | `sensor.johns_iphone_youtube_upload` | App upload traffic (auto-scaled) |\n\nApplication traffic sensors auto-scale their unit (B, KB, MB, GB, TB) and reset daily at midnight.\n\n---\n\n## Automation Examples\n\n### Alert When an AP Goes Offline\n\n```yaml\nautomation:\n  - alias: \"AP offline alert\"\n    trigger:\n      - platform: state\n        entity_id: binary_sensor.living_room_ap_status\n        to: \"off\"\n    action:\n      - action: notify.mobile_app\n        data:\n          title: \"Network Alert\"\n          message: \"Living Room AP is offline!\"\n```\n\n### Presence-Based Welcome Home\n\n```yaml\nautomation:\n  - alias: \"Welcome home\"\n    trigger:\n      - platform: state\n        entity_id: device_tracker.johns_iphone\n        to: \"home\"\n    action:\n      - action: light.turn_on\n        target:\n          entity_id: light.entrance\n```\n\n### High CPU Alert\n\n```yaml\nautomation:\n  - alias: \"High CPU on switch\"\n    trigger:\n      - platform: numeric_state\n        entity_id: sensor.main_switch_cpu_utilization\n        above: 80\n        for: \"00:05:00\"\n    action:\n      - action: persistent_notification.create\n        data:\n          title: \"Performance Alert\"\n          message: \"Main switch CPU above 80% for 5 minutes\"\n```\n\n### Disable PoE at Night\n\n```yaml\nautomation:\n  - alias: \"Disable PoE on port 5 at night\"\n    trigger:\n      - platform: time\n        at: \"23:00:00\"\n    action:\n      - action: switch.turn_off\n        target:\n          entity_id: switch.main_switch_port_5_poe\n```\n\n---\n\n## Options\n\nAfter initial setup, go to **Settings → Devices \u0026 Services → TP-Link Omada Open API → Configure** to access a menu with the following configuration options:\n\n### Client Selection\n\nAdd or remove tracked network clients. Select clients that should have device tracker entities and per-client sensors (IP, RSSI, SNR, traffic, etc.) created in Home Assistant.\n\n| Parameter | Type | Description |\n|---|---|---|\n| **Clients to Track** | Multi-select | List of network clients discovered on your Omada network. Select one or more to create entities. Deselecting a client removes its entities and device. Limited to 200 clients in the UI. |\n\n### Application Selection\n\nAdd or remove tracked DPI applications for per-client traffic monitoring. Each selected application creates upload and download sensors for every tracked client.\n\n| Parameter | Type | Description |\n|---|---|---|\n| **Applications to Track** | Multi-select | List of DPI-tracked applications discovered on your network. Requires DPI (Deep Packet Inspection) to be enabled on your gateway. Traffic data resets daily at midnight. |\n\n### Update Intervals\n\nConfigure how frequently each data type is polled from the Omada controller. Lower values give more responsive updates but increase API load.\n\n| Parameter | Default | Range | Description |\n|---|---|---|---|\n| **Device polling interval** | 60 s | 10 – 3600 s | How often infrastructure device data (APs, switches, gateways) is refreshed. Affects status, CPU, memory, uptime, PoE, and firmware sensors. |\n| **Client polling interval** | 30 s | 10 – 3600 s | How often client data is refreshed. Affects device trackers, RSSI, SNR, traffic, and activity rate sensors. |\n| **Application traffic polling interval** | 300 s | 10 – 3600 s | How often per-client application traffic data is refreshed. Higher values recommended since DPI data updates less frequently on the controller. |\n\n---\n\n## Supported Devices\n\nAll TP-Link Omada SDN devices accessible via the Open API are supported:\n\n- **Controllers**: OC200, OC300, software controllers, cloud-managed controllers\n- **Access Points**: EAP series (WiFi 5/6/6E/7, indoor \u0026 outdoor)\n- **Switches**: JetStream and Smart Managed switches (PoE and non-PoE)\n- **Gateways**: ER and SafeStream series\n- **Clients**: Any device connected to the Omada network (wireless and wired)\n\nDevice availability depends on your controller's firmware version and API access level.\n\n---\n\n## Data Update\n\nThe integration uses Home Assistant's **DataUpdateCoordinator** pattern to fetch data efficiently from the Omada Open API. Three separate coordinators handle different data types, each with its own polling interval:\n\n| Coordinator | Default Interval | Data Fetched |\n|---|---|---|\n| **Device Coordinator** | 60 s | Infrastructure devices (APs, switches, gateways), SSIDs, PoE budgets, AP band stats, gateway temperature, uplink info, AP SSID overrides |\n| **Client Coordinator** | 30 s | Connected clients (IP, MAC, RSSI, SNR, traffic, activity rates), device tracker state |\n| **App Traffic Coordinator** | 300 s | Per-client application traffic (upload/download) from DPI data, queried from midnight to now, resets daily |\n\n### Polling Architecture\n\n- **One coordinator per site** — each selected site gets its own set of coordinators\n- **Hierarchical fetch** — device data merges supplementary info (uplink, band stats, temperature, PoE) in a single update cycle\n- **Token management** — OAuth2 tokens refresh automatically 5 minutes before expiry; expired refresh tokens trigger full re-authentication using client credentials\n- **Error recovery** — transient API failures raise `UpdateFailed`, triggering HA's automatic back-off and retry. Authentication errors raise `ConfigEntryAuthFailed`, prompting a reauth flow\n\nAll polling intervals are configurable via **Options → Update Intervals** (range: 10–3600 s).\n\n---\n\n## Use Cases\n\n### Network Monitoring Dashboard\n\nBuild a Lovelace dashboard showing all your Omada infrastructure at a glance — device status, connected client counts, CPU/memory usage, and PoE budgets. Use conditional cards to highlight offline devices.\n\n### Presence Detection\n\nTrack family members' phones or laptops as they connect to your Omada network. Use device tracker entities to trigger automations (lights on arrival, lock doors on departure, set thermostat away mode).\n\n### PoE Scheduling\n\nAutomate PoE ports to power down IP cameras, access points, or VoIP phones at night to save energy, then bring them back up in the morning.\n\n### Firmware Management\n\nReceive notifications when firmware updates are available for your network devices. Install updates directly from Home Assistant during maintenance windows.\n\n### Bandwidth Alerts\n\nMonitor per-client download/upload traffic and per-app DPI data. Alert when a device exceeds a traffic threshold or when unusual application usage is detected.\n\n### Guest Network Automation\n\nToggle SSID broadcasts on or off to control guest network availability based on time of day, presence, or manual switch.\n\n### Infrastructure Health\n\nSet up automations that alert you when CPU or memory utilization on any device exceeds a threshold for a sustained period, allowing proactive maintenance.\n\n---\n\n## Diagnostics\n\nThe integration provides downloadable diagnostics to help with troubleshooting. Go to **Settings → Devices \u0026 Services → TP-Link Omada Open API → 3 dots → Download diagnostics**.\n\nThe diagnostics file includes:\n- Redacted configuration data (tokens and credentials are masked)\n- Coordinator summaries (device counts by type, client counts, tracked applications)\n- Write access status\n- Site device information\n\nSensitive data (API tokens, client secrets, MAC addresses, IP addresses) is automatically redacted.\n\n---\n\n## Removing the Integration\n\nTo remove the TP-Link Omada Open API integration from Home Assistant:\n\n1. Go to **Settings → Devices \u0026 Services** in Home Assistant.\n2. Find the **TP-Link Omada Open API** integration in the list.\n3. Click the integration, then click the three-dot menu (⋮) and select **Delete**.\n4. Confirm the removal when prompted.\n\nAll entities and devices created by the integration will be removed. If you wish to remove configuration data and tokens, you may also delete the integration folder from `custom_components/` after removal.\n\nFor more details, see the [removal instructions rule](ha-developer-docs/core/integration-quality-scale/rules/docs-removal-instructions.md).\n\n---\n## Troubleshooting\n\n### Integration Not Loading\n\n1. Check Home Assistant logs at **Settings → System → Logs**\n2. Verify `custom_components/omada_open_api/manifest.json` exists\n3. Restart Home Assistant after installation\n\n### Authentication Errors\n\n1. Double-check Client ID, Client Secret, and Omada ID — no extra spaces\n2. Verify region (cloud) or API URL (local) is correct\n3. Ensure outbound HTTPS is not blocked by a firewall\n4. Use **Settings → Devices \u0026 Services → TP-Link Omada Open API → Reauthenticate** to re-enter credentials\n\n### No Entities Created\n\n1. Verify you selected at least one site during setup\n2. Check that devices and clients exist in your Omada Controller\n3. Check logs for coordinator update errors\n\n### Missing Application Traffic Sensors\n\n1. Enable **DPI** on your gateway: Omada Controller → Gateway → Settings → DPI\n2. Verify applications were selected during setup (or add them via Options → Application selection)\n3. Application data resets daily at midnight\n\n### Entities Showing \"Unavailable\"\n\n1. Confirm the device is online in the Omada Controller\n2. Check logs for API errors\n3. Try increasing the polling interval via Options if you hit rate limits\n\n### Token Errors\n\nToken refresh is fully automatic. If you see persistent token errors in logs, use the **Reauthenticate** flow to obtain fresh credentials.\n\n### Reconfiguring the Integration\n\nTo change the controller type, API URL, credentials, or selected sites without deleting and re-adding the integration, use **Settings → Devices \u0026 Services → TP-Link Omada Open API → ⋮ → Reconfigure**. The reconfigure flow walks through the same steps as initial setup and preserves your options (clients, applications, intervals).\n\n### Repair Notifications\n\nThe integration may create repair notifications under **Settings → Repairs**:\n\n- **Read-only API credentials** — Your API application has viewer-only permissions. Device controls (PoE, LED, reboot) are unavailable. Update the application permissions in your Omada controller.\n- **No gateway for DPI tracking** — You selected applications for traffic tracking but no gateway was found. DPI requires an Omada gateway in your network.\n\n---\n\n\n## Services\n\nThis integration provides the following Home Assistant service:\n\n### `omada_open_api.debug_ssid_switches`\n\n**Description:**\n  Dumps diagnostic information about SSID switch entities for a given config entry to the Home Assistant log. Useful for troubleshooting entity creation and mapping.\n\n**Fields:**\n  - `config_entry_id` (string, required): The config entry ID of the Omada integration instance to debug. You can find this in the entity registry or by inspecting the integration in Home Assistant.\n\n**Example YAML:**\n```yaml\nservice: omada_open_api.debug_ssid_switches\ndata:\n  config_entry_id: \"your_config_entry_id_here\"\n```\n\nSee the [integration documentation](ha-developer-docs/core/integration-quality-scale/rules/docs-actions.md) for more details on service usage and troubleshooting.\n\n---\n## Known Limitations\n\n- **Cloud dependency**: Cloud controllers require internet connectivity\n- **DPI required**: Application traffic monitoring needs DPI enabled on the gateway\n- **Local controller**: Requires Open API enabled (not available on all firmware versions)\n- **API rate limits**: Respected automatically; rarely an issue with default polling intervals\n- **Viewer-only credentials**: PoE and LED switches are not created; all monitoring entities still work\n\n---\n\n## Development\n\nThis project uses VS Code devcontainers for a consistent development environment.\n\n### Prerequisites\n\n- Docker ([Desktop](https://docs.docker.com/desktop/) or [Engine](https://docs.docker.com/engine/install/))\n- [Visual Studio Code](https://code.visualstudio.com/) with the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension\n\n### Getting Started\n\n```bash\ngit clone https://github.com/bullitt186/ha-omada-open-api.git\ncd ha-omada-open-api\n# Open in VS Code → Reopen in Container\n# Dev HA instance at http://localhost:8123\n```\n\n### Code Quality\n\nPre-commit hooks enforce **Ruff** (lint + format), **Pylint**, **Mypy**, and **pytest with a coverage gate** on every commit.\n\n```bash\nruff check custom_components/ \u0026\u0026 ruff format --check custom_components/\nmypy custom_components/omada_open_api/\npytest tests/ -v\npytest tests/ --cov=custom_components.omada_open_api --cov-report=html\n```\n\n---\n\n## Contributing\n\nContributions are welcome — bug reports, feature requests, pull requests, documentation, and testing with different Omada setups.\n\n1. Fork the repository\n2. Create a feature branch\n3. Make changes and add tests\n4. Ensure all checks pass (`pytest`, `ruff`, `mypy`, `pylint`)\n5. Open a pull request\n\n---\n\n## License\n\nThis project is licensed under the **MIT License** — see [LICENSE](LICENSE) for details.\n\n**Acknowledgments**: Home Assistant community, TP-Link for the Omada Open API, HACS for custom component distribution.\n\n---\n\n[![GitHub stars](https://img.shields.io/github/stars/bullitt186/ha-omada-open-api.svg?style=social)](https://github.com/bullitt186/ha-omada-open-api/stargazers)\n[![GitHub forks](https://img.shields.io/github/forks/bullitt186/ha-omada-open-api.svg?style=social)](https://github.com/bullitt186/ha-omada-open-api/network)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbullitt186%2Fha-omada-open-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbullitt186%2Fha-omada-open-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbullitt186%2Fha-omada-open-api/lists"}