KeyError in TP-Link Omada Integration due to Missing 'wireless' Key in Client Data

dktrekkie commented 2 months ago

The problem

I encountered a KeyError in the TP-Link Omada integration within Home Assistant when attempting to load device trackers. In my opinion the issue occurs because some clients in the returned data do not have a 'wireless' key, which the integration's code assumes to be present for all clients.

The error trace indicates that the 'wireless' key is missing from certain client entries in the API response. This causes the integration to fail when it tries to access this key without checking its existence first.

Here's the error log:

2024-08-15 12:36:04.016 ERROR (MainThread) [homeassistant.components.device_tracker] Error while setting up tplink_omada platform for device_tracker
Traceback (most recent call last):
  File "/usr/local/lib/python3.12/site-packages/homeassistant/helpers/entity_platform.py", line 364, in _async_setup_platform
    await asyncio.shield(awaitable)
  File "/usr/local/lib/python3.12/site-packages/homeassistant/components/tplink_omada/device_tracker.py", line 35, in async_setup_entry
    [
  File "/usr/local/lib/python3.12/site-packages/tplink_omada_client/omadasiteclient.py", line 147, in get_known_clients
    if client["wireless"]:
       ~~~~~~^^^^^^^^^^^^
KeyError: 'wireless'

What version of Home Assistant Core has the issue?

core-2024.8.1

What was the last working version of Home Assistant Core?

No response

What type of installation are you running?

Home Assistant Container

Integration causing the issue

TP-Link Omada

Link to integration documentation on our website

https://www.home-assistant.io/integrations/tplink_omada

Diagnostics information

home-assistant_tplink_omada_2024-08-15T10-36-20.745Z.log

Example YAML snippet

No response

Anything in the logs that might be useful for us?

No response

Additional information

I believe I have identified the root cause of the KeyError in the TP-Link Omada integration. Below is a snippet of JSON data that I manually fetched using Postman. In this data, some client entries are missing the wireless key, which appears to trigger the error in the integration code. The integration currently assumes that all client objects will include the wireless key, but as you can see from my setup, this is not always the case.

Perhaps this issue could be related to the fact that I have added a significant number of DHCP reservations for devices that have not yet connected to my network. I added these reservations during my setup because I already had the list from my previous network configuration. For example, one of the devices listed has not yet connected because it is associated with an unused Ethernet port on my son's computer, which he currently connects using a different port. My primary use for these reservations is to whitelist only known devices on my network.

{
    "errorCode": 0,
    "msg": "Success.",
    "result": {
        "totalRows": 44,
        "currentPage": 1,
        "currentSize": 10,
        "data": [
            {
                "name": "REMOVED",
                "mac": "REMOVED",
                "duration": 0,
                "lastSeen": 1723575923197,
                "block": false,
                "manager": false,
                "lockToAp": false,
                "blockDisable": false
            },
            {
                "name": "REMOVED",
                "mac": "REMOVED",
                "wireless": true,
                "guest": false,
                "duration": 30,
                "lastSeen": 1723720698381,
                "block": false,
                "manager": false,
                "lockToAp": false,
                "blockDisable": false
            },
            {
                "name": "REMOVED",
                "mac": "REMOVED",
                "duration": 0,
                "lastSeen": 1723575923130,
                "block": false,
                "manager": false,
                "lockToAp": false,
                "blockDisable": false
            },
            {
                "name": "ASPC-NEW2018",
                "mac": "REMOVED",
                "wireless": false,
                "guest": false,
                "download": 824784,
                "upload": 1118139,
                "duration": 47870,
                "lastSeen": 1723710244096,
                "block": false,
                "manager": true,
                "lockToAp": false,
                "blockDisable": false
            },
            {
                "name": "iPhone15Pro",
                "mac": "REMOVED",
                "wireless": true,
                "guest": false,
                "duration": 1706,
                "lastSeen": 1723710172953,
                "block": false,
                "manager": false,
                "lockToAp": false,
                "blockDisable": false
            },
            {
                "name": "Work-Laptop-Port1",
                "mac": "REMOVED",
                "wireless": false,
                "guest": false,
                "duration": 3625,
                "lastSeen": 1723710244096,
                "block": false,
                "manager": false,
                "lockToAp": false,
                "blockDisable": false
            },
            {
                "name": "Work-Laptop-Port2",
                "mac": "REMOVED",
                "duration": 0,
                "lastSeen": 1723575923271,
                "block": false,
                "manager": false,
                "lockToAp": false,
                "blockDisable": false
            },
            {
                "name": "Amazon-Kindle",
                "mac": "REMOVED",
                "wireless": true,
                "guest": false,
                "duration": 44,
                "lastSeen": 1723622622897,
                "block": false,
                "manager": false,
                "lockToAp": false,
                "blockDisable": false
            },
            {
                "name": "AppleTV-2",
                "mac": "REMOVED",
                "wireless": false,
                "guest": false,
                "duration": 131357,
                "lastSeen": 1723710244096,
                "block": false,
                "manager": false,
                "lockToAp": false,
                "blockDisable": false
            },
            {
                "name": "AppleTV-1",
                "mac": "REMOVED",
                "wireless": false,
                "guest": false,
                "duration": 40893,
                "lastSeen": 1723710194198,
                "block": false,
                "manager": false,
                "lockToAp": false,
                "blockDisable": false
            }
        ]
    }
}

home-assistant[bot] commented 2 months ago

Hey there @markgodwin, mind taking a look at this issue as it has been labeled with an integration (tplink_omada) you are listed as a code owner for? Thanks!

Code owner commands

Code owners of `tplink_omada` can trigger bot actions by commenting: - `@home-assistant close` Closes the issue. - `@home-assistant rename Awesome new title` Renames the issue. - `@home-assistant reopen` Reopen the issue. - `@home-assistant unassign tplink_omada` Removes the current integration label and assignees on the issue, add the integration domain after the command. - `@home-assistant add-label needs-more-information` Add a label (needs-more-information, problem in dependency, problem in custom component) to the issue. - `@home-assistant remove-label needs-more-information` Remove a label (needs-more-information, problem in dependency, problem in custom component) on the issue.

_{^{(message by CodeOwnersMention)}}

tplink_omada documentation tplink_omada source _{^{(message by IssueLinks)}}

MarkGodwin commented 2 months ago

Thanks for the detailed info. That does indeed look like the problem. I'll release a new version of the library that is tolerant to the missing "wireless" parameter.

MarkGodwin commented 2 months ago

I've released a new version of the omada API library (1.4.2). If you could give it a try, that would be great.

In a python environment...

pip install tplink-omada-client

Then use the omada target command to add a new target name with something like omada --target Omada target --set-default -url https://your-controller-ip --site Default --no-verify-ssl --username admin

Finally try the omada known-clients command, and check it returns good output.

Once you've confirmed that is working, I will put in an PR to update HA with the new version dependency.

dktrekkie commented 2 months ago

Just wanted to let you know that I gave the new tplink-omada-client (1.4.2) a spin (never used Python much, but got it working! 😀), and it’s looking good! The known-clients command returned a list with no errors, so everything seems to be in order.

By the way, how did you end up handling those entries without the wireless key? Are they just being ignored, or did you find another way to deal with them? Just curious!

Thanks a bunch for the speedy update—really appreciate it!

dktrekkie commented 2 months ago

@MarkGodwin: Is there a way to get this faster, other than just changing the code myself? (even though I will have to do it every time I update my container)

MarkGodwin commented 2 months ago

There is a PR in now. Once that is approved, I think fixes usually make it into the next patch release, I think

home-assistant / core