UniFi Binding

This binding integrates with Ubiquiti UniFi Networks allowing for presence detection of network clients.

Supported Things

  • controller - An instance of the UniFi controller software
  • wirelessClient - Any wireless client connected to a UniFi wireless network

Discovery

Discovery is currently not supported.

Binding Configuration

The binding has no configuration options, all configuration is done at the Bridge and Thing levels.

Bridge Configuration

You need at least one UniFi Controller (Bridge) for this binding to work. It requires a network accessible instance of the Ubiquiti Networks Controller Software.

The following table describes the Bridge configuration parameters:

Parameter Description Config Default
host Hostname of IP address of the UniFi Controller Required -
port Port of the UniFi Controller Required -
username The username to access the UniFi Controller Required -
password The password to access the UniFi Controller Required -
refresh Refresh interval in seconds Optional 10

Thing Configuration

You must define a UniFi Controller (Bridge) before defining UniFi Clients (Things) for this binding to work.

The following table describes the Thing configuration parameters:

Parameter Description Config Default
cid The MAC address, IP address, hostname or alias of the client Required -
site The site where the client should be found Optional -
considerHome The interval in seconds to consider the client as home Optional 180

Here's some additional notes regarding the thing configuration parameters:

cid

The cid parameter is a universal "client identifier". It accepts the following values:

  1. MAC address [highest priority]
  2. IP address
  3. Hostname (as show by the controller)
  4. Alias (as defined by you in the controller UI) [lowest priority]

The priority essentially means the binding attempts to lookup by MAC address, then by IP address, then by hostname and finally by alias. Once it finds a matching client, it short circuits and stops searching. Most of the time, you will simply use the MAC address.

site

The site parameter is optional. If you leave it blank, the client will appear ONLINE if found in any site defined on the controller.

You may use the site parameter as a filter if you only want the client to appear home if it's found in the site defined in the site parameter.

Additionally, you may use friendly site names as they appear in the controller UI.

considerHome

The considerHome parameter allows you to control how quickly the binding marks a client as away. For example, using the default of 180 (seconds), the binding will report a client away as soon as lastSeen + 180 (seconds) < now

Channels

The Wireless Client information that is retrieved is available as these channels:

Channel ID Item Type Description
online Switch Online status of the client
site String Site name (from the controller web UI) the client is associated with
macAddress String MAC address of the client
ipAddress String IP address of the client
ap String Access point (AP) the client is connected to
essid String Network name (ESSID) the client is connected to
rssi Number Received signal strength indicator (RSSI) of the client
uptime Number Uptime of the wireless client (in seconds)
lastSeen DateTime Date and Time the wireless client was last seen

Note: All channels are read-only

Full Example

things/unifi.things

Bridge unifi:controller:home "UniFi Controller" [ host="unifi", port=8443, username="$username", password="$password", refresh=10 ] {
	Thing wirelessClient matthewsPhone "Matthew's iPhone" [ cid="$cid", site="default", considerHome=180 ]
}

Replace $user, $password and $cid accordingly.

items/unifi.items

Switch   MatthewsPhone           "Matthew's iPhone [MAP(unifi.map):%s]"             { channel="unifi:wirelessClient:home:matthewsPhone:online" }
String   MatthewsPhoneSite       "Matthew's iPhone: Site [%s]"                      { channel="unifi:wirelessClient:home:matthewsPhone:site" }
String   MatthewsPhoneMAC        "Matthew's iPhone: MAC [%s]"                       { channel="unifi:wirelessClient:home:matthewsPhone:macAddress" }
String   MatthewsPhoneIP         "Matthew's iPhone: IP [%s]"                        { channel="unifi:wirelessClient:home:matthewsPhone:ipAddress" }
String   MatthewsPhoneAP         "Matthew's iPhone: AP [%s]"                        { channel="unifi:wirelessClient:home:matthewsPhone:ap" }
String   MatthewsPhoneESSID      "Matthew's iPhone: ESSID [%s]"                     { channel="unifi:wirelessClient:home:matthewsPhone:essid" }
Number   MatthewsPhoneRSSI       "Matthew's iPhone: RSSI [%d]"                      { channel="unifi:wirelessClient:home:matthewsPhone:rssi" }
Number   MatthewsPhoneUptime     "Matthew's iPhone: Uptime [%d]"                    { channel="unifi:wirelessClient:home:matthewsPhone:uptime" }
DateTime MatthewsPhoneLastSeen   "Matthew's iPhone: Last Seen [%1$tH:%1$tM:%1$tS]"  { channel="unifi:wirelessClient:home:matthewsPhone:lastSeen" } 

transform/unifi.map

ON=Home
OFF=Away

sitemaps/unifi.sitemap

sitemap unifi label="UniFi Binding"
{
	Frame {
		Text item=MatthewsPhone
		Text item=MatthewsPhoneSite
		Text item=MatthewsPhoneMAC
		Text item=MatthewsPhoneIP
		Text item=MatthewsPhoneAP
		Text item=MatthewsPhoneESSID
		Text item=MatthewsPhoneRSSI
		Text item=MatthewsPhoneUptime
		Text item=MatthewsPhoneLastSeen
	}
}