Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[unifi] New site, wlan, wiredClient, and poePort. Discovery support #11959

Merged
merged 21 commits into from
May 16, 2022
Merged

[unifi] New site, wlan, wiredClient, and poePort. Discovery support #11959

Show file tree
Hide file tree
Changes from 19 commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
f9cd44c
[unifi] New wiredClient and poePort, Discovery support
Hilbrand Jan 4, 2022
9e1812c
[unifi] Review comments
Hilbrand Jan 12, 2022
f649c71
Removed type from UniFiCache constructor
Hilbrand Feb 15, 2022
783b2dc
Added UniFi Site and wLAN things
Hilbrand Feb 15, 2022
fdc3f5b
Improved default state handling
Hilbrand Feb 20, 2022
5f690b4
Review comments
Hilbrand Feb 25, 2022
41d19ae
Added support for client experience
mgbowman Mar 17, 2020
0ac9edb
Made fields private
Hilbrand Feb 27, 2022
33e7eb8
Added PoE power-cycle command
Hilbrand Feb 27, 2022
eabb4e1
Updated readme
Hilbrand Feb 27, 2022
d25f91b
Review comment
Hilbrand Feb 27, 2022
8aac957
[unifi] Added client/guest count to wlan
Hilbrand Mar 16, 2022
5b04071
Fix QRcode construction and added hidden ssid support in qrcode string
Hilbrand Mar 17, 2022
7b09c6e
Typo in format string wifi qrcode
Hilbrand Mar 17, 2022
8200b61
Fixed wlan bug with no password wifi
Hilbrand Mar 20, 2022
a98524b
Review comment
Hilbrand Mar 30, 2022
995837d
Review comments
Hilbrand Apr 20, 2022
4b0d563
Review comments readme
Hilbrand May 12, 2022
fb86cf4
Made experience channel dimensionless
Hilbrand May 16, 2022
f933170
Review comments
Hilbrand May 16, 2022
221bff9
review comments
Hilbrand May 16, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
169 changes: 140 additions & 29 deletions bundles/org.openhab.binding.unifi/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,23 +5,26 @@ This binding integrates with [Ubiquiti UniFi Networks](https://www.ubnt.com/prod

## Supported Things

* `controller` - An instance of the UniFi controller software
* `controller` - An instance of the UniFi controller software
* `site` - A site thing with connection statistics
* `wlan` - A wireless network thing. Control Wi-Fi network and easy access to access.
* `wirelessClient` - Any wireless client connected to a UniFi wireless network

* `wiredClient` - A wired client connected to the UniFi network
* `poePort` - A PoE (Power over Ethernet) port on a UniFi switch

## Discovery

Discovery is currently not supported.

The binding supports discovery of things connected to a UniFi controller (Bridge).
To discover things start the discovery process manually.

## 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](https://www.ubnt.com/download/unifi).
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](https://www.ubnt.com/download/unifi).

The following table describes the Bridge configuration parameters:

Expand All @@ -37,9 +40,28 @@ The following table describes the Bridge configuration parameters:

## Thing Configuration

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

### `site`

The following table describes the `site` configuration parameters:

| Parameter | Description | Config | Default |
| ------------ | -------------------------------------------------------------|--------- | ------- |
| sid | The name, description or id of the site | Required | - |

### `wlan`

The following table describes the `wlan` configuration parameters:

| Parameter | Description | Config | Default |
| ------------ | -------------------------------------------------------------|--------- | ------- |
| wid | The name or id of the WLAN | Required | - |

### `wirelessClient` & `wiredClient`

The following table describes the `wirelessClient` & `wiredClient` configuration parameters:

The following table describes the Thing configuration parameters:

| Parameter | Description | Config | Default |
| ------------ | -------------------------------------------------------------|--------- | ------- |
Expand All @@ -57,8 +79,10 @@ The `cid` parameter is a universal "client identifier". It accepts the following
1. IP address
1. Hostname (as show by the controller)
1. 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.

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`

Expand All @@ -70,37 +94,124 @@ Additionally, you may use friendly site names as they appear in the controller U

##### `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`
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`.

### `poePort`

The following table describes the `poePort` configuration parameters:


| Parameter | Description | Config |
|------------|-----------------------------------------------------------|----------|
| portNumber | The port number as reported by the switch (starts with 1) | Required |
| macAddress | The MAC address of the switch device the port is part of | Required |


## Channels

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

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

The `site` information that is retrieved is available as these channels:

| Channel ID | Item Type | Description | Permissions |
|-----------------|-----------|--------------------------------------|-------------|
| totalClients | Number | Total number of clients connected | Read |
| wirelessClients | Number | Number of wireless clients connected | Read |
| wiredClients | Number | Number of wired clients connected | Read |
| guestClients | Number | Number of guest clients connected | Read |

### `wlan`

The `wlan` information that is retrieved is available as these channels:

| Channel ID | Item Type | Description | Permissions |
|-----------------|-----------|---------------------------------------------------------------------------------|-------------|
| enable | Switch | Enable status of the WLAN | Read, Write |
| wirelessClients | Number | Number of wireless clients connected | Read |
| guestClients | Number | Number of guest clients connected | Read |
| essid | String | Wireless Network (ESSID) | Read |
| site | String | UniFi Site the client is associated with | Read |
| security | String | Security protocol of the Wi-Fi network | Read |
| wlanBand | String | Wireless LAN band of the Wi-Fi network | Read |
| wpaEnc | String | WPA Encoding of the Wi-Fi network | Read |
| wpaMode | String | WPA Mode of the Wi-Fi network | Read |
| passphrase | String | Passphrase of the Wi-Fi network | Read |
| qrcodeEncoding | String | MECARD like encoding to generate a QR Code for easy access to the Wi-Fi network | Read |

::: warning Attention
If you link an item to the `xPrassphrase` or `qrcodeEncoding` channel your Wi-Fi password will be exposed in openHAB.
jlaur marked this conversation as resolved.
Show resolved Hide resolved
The password will also be visible in openHAB event log.
:::

The `qrcodeEncoding` channel can be used to easily create a QR Code to access, for example, a guest network.
It contains a MECARD like representation of the access.
This is the notation used in QR Codes that can be scanned by mobile phones.

### `wirelessClient`

The `wirelessClient` information that is retrieved is available as these channels:

| Channel ID | Item Type | Description | Permissions |
|------------|----------------------|----------------------------------------------------------------------|-------------|
| online | Switch | Online status of the client | Read |
| site | String | Site name (from the controller web UI) the client is associated with | Read |
| macAddress | String | MAC address of the client | Read |
| ipAddress | String | IP address of the client | Read |
| guest | Switch | On if this is a guest client | Read |
| ap | String | Access point (AP) the client is connected to | Read |
| essid | String | Network name (ESSID) the client is connected to | Read |
| rssi | Number | Received signal strength indicator (RSSI) of the client | Read |
| uptime | Number | Uptime of the client (in seconds) | Read |
| lastSeen | DateTime | Date and Time the client was last seen | Read |
| experience | Number:Dimensionless | Overall health indication of the client (in percentage) | Read |
| blocked | Switch | Blocked status of the client | Read, Write |
| cmd | String | Command channel: `reconnect` to force the client to be reconnect | Write |
jlaur marked this conversation as resolved.
Show resolved Hide resolved
| reconnect | Switch | Force the client to be reconnect | Write |
jlaur marked this conversation as resolved.
Show resolved Hide resolved


_Note: All channels with the Write permission require administrator credentials as defined in the controller._

### `wiredClient`

The `wiredClient` information that is retrieved is available as these channels:

| Channel ID | Item Type | Description | Permissions |
|------------|----------------------|----------------------------------------------------------------------|-------------|
| online | Switch | Online status of the client | Read |
| site | String | Site name (from the controller web UI) the client is associated with | Read |
| macAddress | String | MAC address of the client | Read |
| ipAddress | String | IP address of the client | Read |
| uptime | Number | Uptime of the client (in seconds) | Read |
| lastSeen | DateTime | Date and Time the client was last seen | Read |
| experience | Number:Dimensionless | Experience of the client | Read |
jlaur marked this conversation as resolved.
Show resolved Hide resolved
| blocked | Switch | Blocked status of the client | Read, Write |

##### `blocked`

The `blocked` channel allows you to block / unblock a client via the controller.

##### `reconnect`

The `reconnect` channel allows you to force a client to reconnect. Sending `ON` to this channel will trigger a reconnect via the controller.
The `reconnect` channel allows you to force a client to reconnect.
Sending `ON` to this channel will trigger a reconnect via the controller.

### `poePort`

The `poePort` information that is retrieved is available as these channels:

| Channel ID | Item Type | Description | Permissions |
|------------|--------------------------|----------------------------------------------------|-------------|
| online | Switch | Online status of the port | Read |
| mode | Selection | Select the PoE mode: off, auto, 24v or passthrough | Read, Write |
| enable | Switch | Enable Power over Ethernet | Read, Write |
| cmd | String | Command channel: `power-cycle`: Power Cycle port | Write |
| power | Number:Power | Power consumption of the port in Watt | Read |
| voltage | Number:ElectricPotential | Voltage of the port in Volt | Read |
| current | Number:ElectricCurrent | Current used by the port in mA | Read |

The `enable` switch channel has a configuration parameter `mode` which is the value used to switch PoE on when the channel is switched to ON.
The default mode value is `auto`.

## Full Example

Expand All @@ -125,7 +236,7 @@ String MatthewsPhoneAP "Matthew's iPhone: AP [%s]"
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" }
DateTime MatthewsPhoneLastSeen "Matthew's iPhone: Last Seen [%1$tH:%1$tM:%1$tS]" { channel="unifi:wirelessClient:home:matthewsPhone:lastSeen" }
Switch MatthewsPhoneBlocked "Matthew's iPhone: Blocked" { channel="unifi:wirelessClient:home:matthewsPhone:blocked" }
Switch MatthewsPhoneReconnect "Matthew's iPhone: Reconnect" { channel="unifi:wirelessClient:home:matthewsPhone:reconnect" }
```
Expand Down
Loading