Installation and configuration

[stefxx]

DESCRIPTION

This plugin is created to monitor and operate Unifi devices from HomeSeer HS4. It runs both on Windows and Linux. The plugin support most common Unifi systems:

• UDM (UniFi Network and UniFi Protect)
• UDM-Pro (UniFi Network and UniFi Protect)
• UDM-SE (UniFi Network and UniFi Protect)
• UniFi Cloud Key Gen2 (UniFi Network and UniFi Protect)
• UniFi Cloud Key Gen2 Plus (UniFi Network and UniFi Protect)
• UNVR (UniFi Protect only)
• UNVR-Pro (UniFi Protect only)
• Unifi Network Controller on Windows, MacOS and Linux (UniFi Network only)

Note that the Cloud Key Gen1 is not supported, but the Network Controller running on the CK1 is supported. Also, you can use multiple systems at the same time.

When using a supported system, the plugin will support most popular models of the following Unifi devices:

• UniFi Routers (udm/ugw)
• UniFi Switches (usw)
• UniFi Access Points (uap)
• UniFi Cameras (most G3 and up models)
• UniFi Doorbell
• UniFi ViewPoint
• Some other UniFi devices like PDU, Floodlight, All-In-One Sensor etc.

Note that when using multiple systems, there is no obvious distinction between them when accessing devices. For the plugin, all devices are considered part of a single system.

For all systems and devices, I’ll test as much as possible against the latest available stable firmware versions. This means that support for older firmware is very limited.

REQUIREMENTS

• This Plugin is for HS4 only. It works with both Windows and Linux versions
• Windows: .NET Framework 4.7.2 or later
• Linux: mono 5.18 or later
• A supported and correctly configured Unifi System, running one or more supported Unifi devices

INSTALLATION

There are no additional software requirements. Start by selecting “Add” from the “Plugins” menu:


Search for “Unifi” and click on the “Unifi” plugin found:



Click “INSTALL” from the popup shown above, and the plugin will complete the installation:


CONFIGURATION

After installation and starting the Plugin, start by adding a new Unifi System. Select “Unifi” from the “Plugins” menu, and click “Add new Unifi System”.

• After clicking “CONTINUE” on the intro text, enter the IP address of your Unifi System. This can be either a IPv4 or IPv6 address. Enter only the IP address, no prefix, suffix, port numbers or other info. Click “CONTINUE”.
• Enter a valid Unifi username. A cloud account might work if 2FA is disabled, but it is strongly recommended to use a local account. In case of a UDM, UDM-Pro, Cloud Key Gen2 or other Unifi OS device, use those credentials. For systems without Unifi OS, use the Unifi Network or Unifi Protect credentials. Click “CONTINUE”.
• Enter the password. Click “CONTINUE”.
• Give your system a name. This is only used to identify your Unifi system and is especially useful when using multiple systems. Click “CONTINUE”.
• Double check all info and click “SUBMIT”. A “success” message should show.

Repeat the steps above if you have multiple Unifi Systems. There is no hard limit to the number of Systems you can configure.

After all Unifi Systems have been configured, select “Unifi” from the “Plugins” menu, and click “Setup”. You should see a screen like the one below, showing all your Unifi Systems and detected Unifi Devices. Please allow a minute after setup to auto detect your system type and attached devices. Refresh the page a few times if devices are missing. Below an example of a Cloud Key Gen2 Plus setup:


Settings tab:

• An overview of your Unifi System(s) and status indicators. The app services are described below per Unifi System. The status can be any of the following:
  • Black/Disabled: this feature is disabled and/or unsupported
  • Red/Offline: this feature is enabled, but disconnected or still starting
  • Green/Online: this feature is enabled and connected
• Temperature unit: Celsius or Fahrenheit
• Doorbell ring timeout: how long will the doorbell feature ring (ON) before being reset
• Throttling: some features are updated extremely fast (every second or more), too fast for many HS4 systems. Here you can specify how often the HS4 feature will be updated. 0 means it will update near real-time. Make sure you have a (very) fast HS4 system!

System tab(s):
Those tabs will be named after your Unifi System(s).

• First section you can adjust the name, username, password and address of your Unifi System. A DNS name instead of IP address is supported if preferred.
• You can Enable/Disable this system. Normally this should be left On
• HS4 features: a list of supported features on your Unifi System (Unifi OS devices only). The features depend on the actual Unifi OS device. Every feature that you enable will create a feature in HS4.

Systems tab(s) part 2:

• Apps: this should have been auto detected during setup. The plugin will not function correctly if you select the wrong apps.
  • Unifi OS should only be enabled on a UDM, UDM-Pro or Unifi Cloud Key Gen2, or other devices that might support this in the future.
  • Unifi Network should be enabled for most systems, unless it is a Unifi Protect only device like the UNVR.
  • Unifi Protect should only be enabled when supported and enabled on your Unifi System.
• Sites: Select the sites from your Unifi Network that you want to support with this plugin.
• Advanced: Should not be changed normally
  • IP port: the plugin will adjust the port based on the detected system and/or selected apps. Only when you have changed the port number manually on your device you can overrule the port here
  • Logging: extensive logging is part of the plugin, but normally disabled. If needed, enable “Log to file” first to avoid excessive HS4 logging, especially when enabled “Log data received”. The logfile can be found in the HomeSeer “Logs” directory.
  • Delete this Unifi System: remove this Unifi System but leave the HS4 features
  • Delete this Unifi System and All Connected HS4 Devices”: As above, but also removes all HS4 devices and features connected to this Unifi System

Devices tab(s):
This includes Routers, Switches, Access Points, Cameras and ViewPoints. Doorbells can be found under Cameras.

• All detected Unifi Devices of the selected type will be shown here, with their supported features. Enabling a feature will create a HS4 feature for monitoring and depending on the feature, also control.
• If the feature name contains a “#”, multiple features will be created. For instance, “Port # PoE” will create a feature for every ports supporting PoE for the selected switch.
• All features will be logically grouped in HS4 per device (a “root” device for every Unifi Device)
• Disabling a feature will immediately remove the HS4 feature, so be careful. Enabling the feature again will generate a new HS4 feature reference, so events, HSTouch references etc must be checked and adjusted.

Clients tab:

• Client devices, both wired and wireless, are listed here. Note that all devices known to your Unifi Network will be listed here. Is the status is green, it is online/connected. If the status is red, the client is offline/disconnected. Only when offline/disconnected, you can “Forget” the device from your Unifi system from this page.
• Enabling “Track” will create a HS4 feature for that client device to show status, and buttons to block, unblock and/or kick the device.

Orphans tab:
If devices are removed from the Unifi System, they might end up being orphaned in the plugin. Those Unifi Systems, Unifi Devices and Clients will be shown here, with the option to remove.
WARNING: Make sure that all Unifi Systems are enabled and connected before removing orphans. If you suddenly see many orphans, that might be an indication of other issues!

TROUBLESHOOTING

If anything does not work, you can try one the following:

• Make a backup. If anything goes wrong, you can always revert.
• Verify the connection information. Did the IP address change? Did you change your password?
• Disable and enable a Unifi System to “restart” the connection to the Unifi System.
• Stop and restart the Plugin. Most changes will be picked up during normal operations, but sometimes a restart might help.
• Delete the Unifi System (select your Unifi System and select “Delete this Unifi System”). Recreate the system by adding a new system as described above. Your HS4 devices/features should be re-used with their existing reference numbers, so the impact is limited/none.
• Post your issue on the HomeSeer forum for help. Please include as many details as possible, including Windows/Linux, Unifi System type, Devices, version numbers etc etc. Screenshots can be very helpful.
• Logging can also reveal issues, please always enable “Log to file” and PM me the logfile. Do not post the logfile on the support forum without removing any personal information!

NOTES

• The Plugin is tested with the latest firmware of most popular Unifi Systems and Unifi Devices. Off course I do not own all those systems/devices myself, and every system is different.
• Most popular features of the supported Unifi Devices are supported. If you miss anything, let me know on the HomeSeer forum and I’ll see what I can do.