[PROJECT] Driver for Unifi Network Controllers

Yep thanks, That's a lot of complexity based on model for the number of Wan ports and what they are "mapped" to. I may try extended to Wan 3 on my local copy of the code just to see what I can get away with.

For example I have

Port 10 (SPF+) mapped to Wan 1 (T-Mob) - Primary
Port 9 (2.5 GB) mapped to Wan 2 (ATT) - 1st Backup
Port 8 (GB) mapped to Wan 3 (Starlink) - 2nd Backup

I have the new code for it in my version of the parent driver. I made that able to handle all 8 without issue. The annoying part is adding the attributes to the children. Lot of copy/paste there. I should have the main ones posted tonight, since I was able to test it a bit with my home setup (I have mine configured for 2 WAN ports, although one is non-functional so it only results in an "Unknown" value for each).

Updated Version(s):

  • UnifiNetworkAPI.groovy = 0.4.82
  • UnifiNetworkChild-USG.groovy = 0.1.5
  • UnifiNetworkChild-UX.groovy = 0.1.4
  • UnifiNetworkChild-UXG.groovy = 0.1.5
  • UnifiNetworkChild-UDM.groovy = 0.1.9
  • UnifiNetworkChild-UCGMax.groovy = 0.1.2
  • UnifiNetworkChild-UDMP.groovy = 0.1.12
  • UnifiNetworkChild-UDMPSE.groovy = 0.1.7
  • UnifiNetworkChild-UGW3.groovy = 0.1.2
  • UnifiNetworkChild-UGW4.groovy = 0.1.5

Change(s):

  • Added handling for additional WAN ports in parent and related attributes for the listed child drivers (per what the Ubiquiti tech specs indicate each model supports)
  • Additional data handling
1 Like

Updates worked great Wan 3 showed up just fine. Initially it was unknown and then I powered up the Starlink and was treated to the latency and availability stats. For the compete view I am working on a API on the Chestertech 5G gateway that will allow me to poll the 5G network data.

Did a test with disabling and enabling POE on a port and it worked fine.

1 Like

Just installed some new Unifi equipment, here are the model names and what drivers I am using. Thanks for putting these drivers together! Happy to provide more info if helpful.

Device - Model Name - Driver

Working

  • Refresh statistics and view ports
  • PoE Control/Power cycling
  • Locating
  • Restarting
  • LED control on E7 + E7-Campus + USW Pro XG 8 PoE

Not working

  • LED controls do nothing on CGF or USW Pro HD 24 PoE (they don't seem to have status LEDs, but maybe this should control the LCM LCD screens instead?)
  • LCM LCD Screen Brightness Control (don't see a command for this on CGF or USW Pro HD 24 PoE)
  • Etherlighting control on USW Pro XG 8 PoE or USW Pro HD 24 PoE
  • CGF has no PoE control commands for port 4
  • CGF seems to only refresh ports 1-5 by default, but ports 6+7 appear on a manual refresh
  • USW Pro HD 24 PoE seems to only refreshes ports 1-26 by default, but ports 27+28 + RPS appear on a manual refresh
  • USW Pro XG 8 and CGF do not populate the Power statistic (and the AP driver doesn't list it at all)
  • E7 + E7 Outdoor don't show second uplink ethernet port

I will have to reach out for more details about some of them. It may even require new child drivers to break out some, so I appreciate the heads-up.

UPDATED:
Ok, now that I am on my computer and not my phone I can look in more detail. Pretty much none of these devices are ones I have specifically added support for. Did you manually select the drivers for them? Because of differences in the devices almost every single one needs a separate driver and they generally will not work as well if they have not been directly made for the specific device type.

  • The LED On/Off is a mistaken piece for most devices now... I think I did a copy/paste that included it at some point and did not notice until you just mentioned it. I will be removing those from switches and gateways.
  • LCM control is handled within the device Preferences, not as a command. The UCGMax did not have them (it will going forward).
  • USW8PoE child driver is incapable of Etherlighting.
  • USPM24P child driver should have worked for Etherlighting... it does on a PM24, but yours is something different so it might not work properly.
  • UCGMax child driver does not support power, nor does the normal AP child driver, as they do not have PoE. The USW8PoE DOES have the power meter capability... maybe it has not been reported.
  • AP child driver does not have a second port capability.

Looking over this, I think almost all of it is because these are devices that are not yet supported. If you could shoot me a direct message with each one's Model (as reported in the State Variables of the device, which is almost always different from what Unifi lists them as publicly), I can start making specific child device drivers.

Updated Version(s):

  • UnifiNetworkAPI.groovy = 0.4.83
  • UnifiNetworkChild-UCGMax.groovy = 0.1.3
  • UnifiNetworkChild-USPM16P.groovy = 0.1.3
  • UnifiNetworkChild-CGF.groovy = NEW Added to list in initial post
  • UnifiNetworkChild-EAP.groovy = NEW Added to list in initial post
  • UnifiNetworkChild-USPHD24P.groovy = NEW Added to list in initial post
  • UnifiNetworkChild-USPXG8P.groovy = NEW Added to list in initial post

Change(s):

  • Initial recognition added for the Cloud Gateway Fiber, Pro HD 24 PoE, Pro XG 8 PoE, E7, and E7 Campus devices. These should now be recognized on a new install or if you delete an existing temporary device (such as the UnifiNetworkChild) and let the device be recreated automatically with it's next data. This does requiring using the correct child drivers and I have attempted to include their various respective features at this time.
  • Added SFP+ port control to the Pro Max 16 PoE.
  • Removed LED functions from the Cloud Gateway Max because it does not have a separate LED.
1 Like

Updated Version(s):

  • ALL drivers were updated

Change(s):

  • Added helper code to parent driver for @mavrrick58's Integration app
  • Corrected recognition for Unifi Gateway Fiber device
  • Removed LED control commands from the Pro HD 24 Port PoE switch (it has an LCM, not an LED)
  • All drivers now have a common method of logging for ProcessEvent
2 Likes

First time trying these drivers. Got a USW-LITE-16-POE. Added the Controller and can see the three child devices (Gateway and 2 Switches), changed the Device Type to the correct driver. Most things seem to work, but I can't change POE state on the ports. I can see lots of references in the thread, but in most cases, they seem to have been resolved, so trying to figure out if mine is unique or am doing something stupid.

When I try to make the change through the Device itself, I see nothing at all.

If I run it as an action in Rules, I eventually get,

dev:11252025-08-04 15:10:02.940

debug

MyUnifiAPI - Bad Request for SetPortState

Initial check on my USW-Lite-16-POE (I actually have one of these myself) shows that it is responding to "Set PoE Port State" command on the device's page (I set Port 1 to Off, checked it in the Unifi app on my phone AND checked the Port 01 Status on the device's Current States, then changed it back to Auto and checked everything again). So that part seems to be working. I do not think I have a Rule for it, but I will check that and make an edit.

You generally will not see much change on the child device itself except the Port # Status. The only logging that would trigger from that (for the child device) is if you have Trace logging enabled for it. Most actual work and logging happens from the parent device.

In the meantime, if the drivers are loaded you should not need to change the Device Type. It should automatically create the child devices and use the correct child driver (as long as they are all added before the child device(s) are created). Did you get the child drivers after the children were created?

EDIT:
Turns out, I DID have a rule to change a PoE port as a sample, but it was for port 3 (which now has something being powered from it). Below are screenshots from it as port 3, but I did change it to Port 1 and confirmed it worked using Rule Machine (off, and then auto again). It requires 2 parameters, and both must be strings.


You should not get a Bad Request unless something is not formatted properly when the command is sent to the controller for a command like this. Did you create the Rule with 2 parameters and have both as strings (the port should not be a number field)?

Thanks for that. I've tried restarting everything, so Removed the three devices and the Parent device. All drivers downloaded via HPM (and repaired). Restarted Hubitat (just in case) and re-added. So I added the Unifi API device, then went to Preferences, set as per the top of this thread.

Click Save. Went back into new Device, get Cookie error telling me to login again. Click Login and Refresh and then Refresh Unifi Devices. At which point, the three devices are added. The UCG-Ultra however adds as a UCGMax, but the two Switches add as UnifiChild (as they did before), I can then change to the -USW16LPoE driver, but I end up in the same situation, the set POE doesn't make any difference.

So it's not auto discovering the device type of the switches. I did try various combinations of the Rule / Action / Parameters yesterday, but had eventually landed on 2 separate strings, and I've double checked that today as well.

Only other thing I can add is that as above, its discovering the UCG-Ultra as a Max, which isn't a massive issue, except that's the device I connect to initially, could it be something to do with that, or is that clutching at straws?

(as a sidenote, I've separately setup the connection to the switches via HomeAssistant and from there I can change the state as expected, so I'm confident the problem isn't the switches or the user account or anything).

Thanks for taking a look at least.

EDIT:

Did just spot around the same time as the device was initially updated, I get the following, which could explain why its not auto discovering the devices at least...

Ok, so the switches are not being identified properly (which COULD impact how they work) because Ubiquiti changed the model identifier (probably these are a hardware revision) compared to what the code is looking for and what I have already. I already had USL16P, and USL16LP, so the USL16LPB is indeed a new one for the driver. I already had a new version of the driver in the works to add some of the things you got listed for Unhandled data, so this is an easy addition.

The UCGMax child driver supports the Max and the Ultra because they allow for the same functions. That would not impact the other devices at all (the child devices are all independent, everything runs via the parent).

You do not need to delete the whole setup. What you can do is delete a specific child device and it will automatically be created when there is data for it (like doing the Refresh Unifi Devices command).

Updated Version(s):

  • UnifiNetworkAPI.groovy = 0.4.85

Change(s):

  • Added additional data handling for new data being returned by the API
  • Added support for a new model revision of the 16 port Lite PoE switch (@user535 had them, so thank you for providing the model logging).

Updated Version(s):

  • UnifiNetworkAPI.groovy = 0.4.86

Change(s):

  • Fix for the Port Overrides used by the Port State (PoE on/off, not cycling) IF there is an additional data element included in it. @user535's switch was using/providing a data field I had never seen before when copying the Port Override information to send back to the API. As a result, the driver was not handling that field's data properly and the API was rejecting the request. Thanks to @user535 for helping figure this out and testing the fix.

Updated Version(s):

  • UnifiNetworkAPI.groovy = 0.4.87

Change(s):

  • Fix for Port Overrides due to additional data types now being included within it. This prevented port changes (like PoE) from working because the API would reject the override data that was not in the correct format for the data type.
  • Additional data handling (outside of port overrides) for new data the API is returning.

EDIT:
Regarding the Port Override fixes... I had an idea, after the current fix and the new version posted, that should help alleviate this problem in the future. However, I am going to let the changes sit on my system for a couple days to make sure first.

1 Like

Updated Version(s):

  • UnifiNetworkAPI.groovy = 0.4.88
  • UnifiNetworkChild-UPSTower.groovy = NEW Added to list in initial post

Change(s):

  • Added initial support for UPS Tower. At this time it does not appear that much can actually be controlled besides device location and LEDs on/off. Outlet control does not provide errors and DOES change the group display within the Unifi Network app and web browser, but does NOT actually change any outlet states at this time, so I have disabled those. Of course, this required a new child driver that has been added.
  • Update to unknown type handling within port overrides code to handle the data by their individual types. Should prevent problems even if unknown names come up in the future.
1 Like

Hello! Love the drivers. I recently Acquired a U7 Lite AP to add to my network, but it seems like the main driver is having trouble recognizing it. Here are the debug logs I get after running Refresh Devices:

dev:1072025-10-19 13:31:19.296 debug 174-Unifi - Unhandled data for Generic <MAC> station_mode = wifi
dev:1072025-10-19 13:31:19.029 debug 174-Unifi - Unidentified Unifi UFLHD Device
dev:1072025-10-19 13:31:18.293 debug 174-Unifi - addChild(Generic <MAC>)
dev:1072025-10-19 13:31:18.290 debug 174-Unifi - Unidentified Unifi UAPA693 Device
dev:1072025-10-19 13:31:17.323 debug 174-Unifi - Unhandled data for Generic <MAC>:ad ap_downlink_table = []
dev:1072025-10-19 13:31:16.308 debug 174-Unifi - Unidentified Unifi UDMA69B Device

It ends up adding a generic UnifiNetworkChild device called "Generic " with model UAPA693

When I try to use the AP or EAP driver for it, it doesn't work, and actually loses the state variables and doesn't report state.

This is using Driver Version 0.4.88, with all the child drivers up to date.

Yes, if an item comes across as Generic that means I have not received any samples from one of those devices before and it cannot be recognized. It looks like it is right between the Basic AP (those lacking an LED ring) and the standard AP (they have a color-controllable LED ring) because it has the ring, but it was one of the ones they released that only allows for White or Blue (not RGB).

Update will be posted in a minute.

Updated Version(s):

  • UnifiNetworkAPI.groovy = 0.4.89

Change(s):

  • Added recognition for Access Point U7 Lite (Model UAPA693) to use the UnifiNetworkChild-AP.groovy child driver.
1 Like

Working great! Thanks :slight_smile: