PLUGIN: Unifi Sensor - Presence detection using a Unifi Wi-Fi controller

Plugins & Plugin Development General Plugin Discussion
1

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.

[url=https://github.com/livehouse-automation/unifi-sensor]https://github.com/livehouse-automation/unifi-sensor[/url]

2

Love it - at last a Unifi Plugin :slight_smile:

3

Thanks. :slight_smile:

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.

4

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.

5

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 ?

6

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…

7

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?

8

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.

9

Thanks for the efforts! It seems to be working fine! Only thing is that I don’t see it back in Imperihome, when refreshing the devices… any ideas?

Again thanks!! I made something with a log data collector and a data analyzer, but that was per device, this is much handier… :slight_smile:

Richard

10

[quote=“riochicken, post:9, topic:196889”]Thanks for the efforts! It seems to be working fine! Only thing is that I don’t see it back in Imperihome, when refreshing the devices… any ideas?

Again thanks!! I made something with a log data collector and a data analyzer, but that was per device, this is much handier… :slight_smile:

Richard[/quote]

Thank you, you’re welcome.

Not sure about Imperihome - but they show up as a motion sensor in Homewave, so I’d hope they’d be visible in other mobile apps.

The plugin is built on standard services for: SecuritySensor1 and SwitchPower1 (binary switch). So see if you can add it as a switch device if it doesn’t show up as a sensor.

11

[quote=“Spanners, post:10, topic:196889”][quote=“riochicken, post:9, topic:196889”]Thanks for the efforts! It seems to be working fine! Only thing is that I don’t see it back in Imperihome, when refreshing the devices… any ideas?

Again thanks!! I made something with a log data collector and a data analyzer, but that was per device, this is much handier… :slight_smile:

Richard[/quote]

Thank you, you’re welcome.

Not sure about Imperihome - but they show up as a motion sensor in Homewave, so I’d hope they’d be visible in other mobile apps.

The plugin is built on standard services for: SecuritySensor1 and SwitchPower1 (binary switch). So see if you can add it as a switch device if it doesn’t show up as a sensor.[/quote]

Just checked, but there is no device at all in the place it should be, I see them in the Vera interface like the nice icons they are, but nowhere to be found in Imperihome, I have the same issue with on of my mysensors sensors, it appears nicely in the Vera interface but not in the Imperihome interface, already mailed them but no answer whatsoever…

12

I cannot get it to work, but I’m also not using default site. Is that the problem?
Edit: changed the script to “mysitename” and did’t not work. Using api/self/sites i looked up an “internal” ID for my site, and changed the script to that ID, and now it worked!

Thanks

13

How would I proceed if I have 3 devices, and EG want to set the house to “away” if none of the 3 is present?
And of course the other way, if one of these 3 devices is present, set house mode to “Home”?

I’m abit stuck, so any help is appricated. Love the plugin!

14

I clearly need to add site ID to the UI. :slight_smile:

I have 4 instances of the plugin, each watching a different mobile phone.

I use a PLEG condition to monitor the status, and if all are offline it changes to away mode. Another condition changes it back to home if any one of the devices becomes active.

cHouseMode_Away (!tiPhone1Present AND !tiPhone2Present AND !tiPhone3Present AND !tiPhone4Present) AND (tHouseMode_Home OR tHouseMode_Night) AND (tHouseMode_Home; NOW > 00:10:00)

cHouseMode_Home (tiPhone1Present OR tiPhone2Present OR tiPhone3Present OR tiPhone4Present) AND tHouseMode_Away

Until they add AND logic to the Vera Scene editor you’ll need to use PLEG or Lua code in a scene to achieve it.

15

[quote=“Spanners, post:14, topic:196889”]I clearly need to add site ID to the UI. :slight_smile:

I have 4 instances of the plugin, each watching a different mobile phone.

I use a PLEG condition to monitor the status, and if all are offline it changes to away mode. Another condition changes it back to home if any one of the devices becomes active.

cHouseMode_Away (!tiPhone1Present AND !tiPhone2Present AND !tiPhone3Present AND !tiPhone4Present) AND (tHouseMode_Home OR tHouseMode_Night) AND (tHouseMode_Home; NOW > 00:10:00)

cHouseMode_Home (tiPhone1Present OR tiPhone2Present OR tiPhone3Present OR tiPhone4Present) AND tHouseMode_Away

Until they add AND logic to the Vera Scene editor you’ll need to use PLEG or Lua code in a scene to achieve it.[/quote]

Exactly the way I would do it except I would make a virtual switch on or off, although the houseaway mode also seems tempting although there seems to be no way to put Vera in away modes using Pleg, or is there?

16

Sorry but I can’t understand what I should configure for attribute - Unifi URL - is it some external device, which should be present in the system - or is it a Vera’s IP address should be used, If we are talking about external UNIFI controller has be present in the network - why on the page there is no notice about UNIFI controller configuration…
I am confused about how it should work, - I have uploaded files to Vera, gave permission to script and create a UNIFI device, so - what else should be present / configured to get MAС tracking workable?

17

Sure, you just set the SetHMode variable to the value you want. I use it to set night mode.

18

[quote=“riochicken, post:15, topic:196889”][quote=“Spanners, post:14, topic:196889”]I clearly need to add site ID to the UI. :slight_smile:

I have 4 instances of the plugin, each watching a different mobile phone.

I use a PLEG condition to monitor the status, and if all are offline it changes to away mode. Another condition changes it back to home if any one of the devices becomes active.

cHouseMode_Away (!tiPhone1Present AND !tiPhone2Present AND !tiPhone3Present AND !tiPhone4Present) AND (tHouseMode_Home OR tHouseMode_Night) AND (tHouseMode_Home; NOW > 00:10:00)

cHouseMode_Home (tiPhone1Present OR tiPhone2Present OR tiPhone3Present OR tiPhone4Present) AND tHouseMode_Away

Until they add AND logic to the Vera Scene editor you’ll need to use PLEG or Lua code in a scene to achieve it.[/quote]

Exactly the way I would do it except I would make a virtual switch on or off, although the houseaway mode also seems tempting although there seems to be no way to put Vera in away modes using Pleg, or is there?[/quote]

Device 19 is a PLEG instance.

Action: cHouseMode_Away

Device Actions:Immediate

Device Action Arguments
Logic - Geo Security[19] SetHouseMode Mode=2

Action: cHouseMode_Home

Device Actions:Immediate

Device Action Arguments
Logic - Geo Security[19] SetHouseMode Mode=1

19

I’m in too deep water here. Any chance anyone would take the time to give step-by-step direction,or example on how I can use this to trigger housemode=away when my 3 Unify er gone, and set homemode if one or more is present?

Thanks

20

[quote=“s83569, post:16, topic:196889”]Sorry but I can’t understand what I should configure for attribute - Unifi URL - is it some external device, which should be present in the system - or is it a Vera’s IP address should be used, If we are talking about external UNIFI controller has be present in the network - why on the page there is no notice about UNIFI controller configuration…
I am confused about how it should work, - I have uploaded files to Vera, gave permission to script and create a UNIFI device, so - what else should be present / configured to get MAС tracking workable?[/quote]

Hi - here are my settings for a Unifi Sensor device:

Address d4:f4:6f:12:80:c7
Poll Period 90 seconds
Device Retries 0
Unifi URL 192.168.0.20:8443
Unifi Username vera
Unifi Password obscuredbyclouds

Address - is an IP or MAC of the device you want to check on the Unifi controller.
Poll Period -how often you want to hit the Unifi conroller for info
Device Retries - how many negative responses you want before you change the state of the sensor
Unifi URL (probably a poor choice of name) - the IP address and Port number of your Unifi Controller.
Unifi Username - a user ID you’ve created on the Unifi Controller for Vera to use. DO NOT use your default admin account.
Unifi Password - password for user ID above.

The only thing you need to configure on your Unifi Controller, assuming you’re running 5.5 or thereabouts is a username and password. You may need to get the site ID and edit the shell script if you’re not accessing the default Unifi site.

You can test by logging into your Unifi controller and then changing the URL to: https://xxx.xxx.xxx.xxx:xxxx/api/s/default/stat/sta where the x’s are your IP/port details. You should get a browser full of JSON text in response.