Author Topic: PLUGIN: Unifi Sensor - Presence detection using a Unifi Wi-Fi controller  (Read 473 times)

Offline Spanners

  • Full Member
  • ***
  • Posts: 212
  • Karma: +12/-5
    • https://www.livehouseautomation.com.au
Firstly we must acknowledge our ancestors and traditional owners of the code upon which we stand.

TedStriker, the original author of the Ping Sensor Plugin and everyone who updated and modified the plugin since 2009.
Salvation, over on the Domoticz forum who posted a shell script which I've re-purposed for use on Vera.

Introduction:

The Unifi Sensor operates in much the same way as the Ping Sensor on which it's based. The difference is it queries your Unifi Controller and looks for a MAC or IP address - if that address is found, the sensor trips. This method means you can detect the presence of devices that don't respond to ping, or go into a deep sleep state (eg Galaxy S smartphones) and ignores network pings.

Things to know:

Your Unifi controller needs to be up to the task of dealing with the volume of queries based on your polling interval. Each query involves authentication and returning a JSON result that is between 2kb and 30kb for the 'average' home network. Queries that run too long risk upsetting Vera's watchdog.

Recommended interval is 60 seconds or more, and if you have multiple instance stagger the times a little so they don't all run at the same time. (eg, 60, 63, 65).
Retry count is recommended to be at least 2 in my testing, I have had some false trips with 0/1, mainly due to issues with the Unifi controller rather than the plugin.

Devices appearing on the network are picked up pretty quickly, devices that have left the network will stay on the controller for a several minutes. Using a 60 second interval it takes 4-8 minutes for devices to be detected as offline.

Tested on UI7 1.7.3016 - VeraEdge, VeraPlus and VeraSecure. This plugin is probably not UI5 friendly.
Tested on Unifi Controller v5.4.19, 5.5.20 (note that 5.4.19 suffered performance degradation over a few days of polling).

Installation:

Download the plugin files in the attached zip file.
Copy these files to Vera using Apps->Develop Apps->Luup Files
- D_UnifiSensor.json
- D_UnifiSensor.xml
- I_UnifiSensor.xml
- S_UnifiSensor.xml
- J_UnifiSensor.js

You'll need to use WinSCP or similar to copy the unifi_check_v1.sh to the /etc/cmh-ludl folder. Once it's copied in you need to give execute permissions. You can do this with WinSCP by setting properties on the file, you want Octal 0775 as the result.

Once the files are in place, create a new device specifying device file (D_UnifiSensor.xml) and implementation file (I_UnifiSensor.xml).

You'll need to reload the Luup Engine and refresh your browser before the device will appear in the UI.

Configuration:

Create a separate user on your Unifi Controller for Vera to use, don't use your main Admin account - the continual authentications against the controller will make it hard to access the webpages if you share accounts.

In the UI for the device, go into the Settings tab and provide the information needed - it should be self explanatory.

You will see polling details and results in the UI so you can see if it's active. Device will show Green if the address you've provided is detected on the controller and will be Blue if not. Using the Invert option will reverse that, and provides a means to test if the device is functioning/triggering alerts correctly.

Future:

If someone wants to create a Lua replacement for the script code using curl that'd be awesome.
A mechanism to share logins/reuse cookies rather than authenticate for every query and reduce the load on the unifi controller.
Better logging of time taken for queries to run.
Some error checking, better handling of failed responses from Unifi controller. Currently no response is treated as device not detected.

Changelog: (Proper dates)

9/8/17 v1.03 - updated Implementation file and polling script to put a timeout value on curl queries and only change status if the commands complete successfully in less than 15 seconds per query. Tested on new version 5.5.20 of Unifi Controller and it handles the repeated polling with much greater efficiency, query times typically complete within a second. Device UI now reports execution time and displays an error if curl does not complete successfully. Reliability of detection is much improved. Recommended retry setting now 1.

21/8/17 - Created Github Repository, check here for updates in future. Will leave the ZIP file here for now.

https://github.com/livehouse-automation/unifi-sensor

« Last Edit: August 21, 2017, 01:46:24 am by Spanners »

Offline parkerc

  • Sr. Hero Member
  • ******
  • Posts: 2330
  • Karma: +32/-44
  • Life Moves Pretty Fast....
    • Node Central
Love it - at last a Unifi Plugin :)

Offline Spanners

  • Full Member
  • ***
  • Posts: 212
  • Karma: +12/-5
    • https://www.livehouseautomation.com.au
Love it - at last a Unifi Plugin :)

Thanks. :)

For reference for those either with Ubiquiti or looking at deploying it, my setup is:

- Unifi Controller running on QNAP TVS-873 in a Debian Linux VM (1 core, 256MB RAM - of which it's using less than 2% according to Virtualization Station)
- 3 x UAP-AC-LR Unifi Access Points
- VeraSecure running 4 Instances of Unifi Sensor with 60 second polling (2x iPhones, 2x Galaxy S8s).


Query response time around 1-2 seconds. Retries are 0 on the iPhones (backed up by iPhone Locator Plugin) and 1 on the Samsungs. Still early days on the latest version, but I've gone 2 days with no false trips, perfect presence detection.
« Last Edit: August 09, 2017, 08:33:11 pm by Spanners »

Offline tculpepp

  • Newbie
  • *
  • Posts: 4
  • Karma: +0/-0
Just a note on this.  The unifi_check_v1.sh script hard codes to the default site on the controller.  If your site is anything other than the default site you will need to edit that in the script to reflect your site code or everything will seem to work but it will never find your devices.

Offline Spanners

  • Full Member
  • ***
  • Posts: 212
  • Karma: +12/-5
    • https://www.livehouseautomation.com.au
Just a note on this.  The unifi_check_v1.sh script hard codes to the default site on the controller.  If your site is anything other than the default site you will need to edit that in the script to reflect your site code or everything will seem to work but it will never find your devices.

By default site do you mean that the URL it's trying to query is https://xxx.xxx.xxx.xxx:xxxx/api/s/default/stat/sta ?




Offline Buxton

  • Newbie
  • *
  • Posts: 13
  • Karma: +0/-0
Re: PLUGIN: Unifi Sensor - Presence detection using a Unifi Wi-Fi controller
« Reply #5 on: September 06, 2017, 11:54:25 pm »
I have a Ubiquity ERL router.  Can I run the .sh script on the router instead of my Vera lite?  I'm asking because I'd like the script to survive Vera firmware upgrades as well as not place any additional load on the vera.  Also, I'd like to see a status of specific machines on my network in the Vera UI.  Is it possible to use the script in this fashion as well....

Offline Spanners

  • Full Member
  • ***
  • Posts: 212
  • Karma: +12/-5
    • https://www.livehouseautomation.com.au
Re: PLUGIN: Unifi Sensor - Presence detection using a Unifi Wi-Fi controller
« Reply #6 on: September 07, 2017, 03:02:15 am »
I have a Ubiquity ERL router.  Can I run the .sh script on the router instead of my Vera lite?  I'm asking because I'd like the script to survive Vera firmware upgrades as well as not place any additional load on the vera.  Also, I'd like to see a status of specific machines on my network in the Vera UI.  Is it possible to use the script in this fashion as well....

Not without some serious rejigging, the plugin works locally by looking at return codes from the script and passing the settings to it as parameters. The script should survive firmware upgrades, it's put in the same folder as other user/custom files such as plugins.

I've seen some people running scripts on the controller and then using an http request back to Vera to trip a virtual motion sensor or activate a scene. You'd probably have to hard code the stuff you're looking for.

parkerc was also interested in some status information presented in the UI - what sort of things did you have in mind?

Offline Buxton

  • Newbie
  • *
  • Posts: 13
  • Karma: +0/-0
Re: PLUGIN: Unifi Sensor - Presence detection using a Unifi Wi-Fi controller
« Reply #7 on: September 07, 2017, 05:53:23 pm »
Thx for the reply.  Yeah, I was thinking of modifying the .sh script (perhaps combining with other similar scripts) to work either on the router or the controller server, but was not sure how the script return variables were being picked up.

Basically, I'd like to see in the Vera UI, a status of selected machines on my home network: servers, devices, switches etc--perhaps enumerated in a multiswitch.  If an IP (or mac) address is down, I would be notified via vera alerts, as well as running various actions triggered by a device status (perhaps a power cycle to a zwave power outlet).  It's a similar idea to the occupancy scan you've created.  That's why I thought running something similar on the router would work best, and the occupancy detection via the Unifi controller would then be a subset of an overall network status.  I haven't seen anything like that kind of network management on the vera forum.

I also thought of using some basic logic combining the unifi plugin with the existing vera proximity plugins to confirm occupancy and/or proximity to the desired location, one backing up the other, or even a geo-proximity notice to start the plugin to begin a more active scan of the home network.

Thanks for the plugin. I'm going to give it a try this weekend.