Skip to content

Commit

Permalink
[unifi] New site, wlan, wiredClient, and poePort. Discovery support (o…
Browse files Browse the repository at this point in the history 
…penhab#11959)

* [unifi] New wiredClient and poePort, Discovery support

This change adds the following changes:
- 2 new things: a wired client and POE port.
- Adds discovery of clients and poePort.
- Adds guest channel to client thing.
Also included some refactoring and bug fixes.

This change includes changes made by Matthew Bowman that he created on his own branch but were never completed.

Closes openhab#9609: Implemented async http call, which should fix the buffer overflow.
Closes openhab#10375: At least should avoid the stack overflow.
Closes openhab#11964: cid will be handled in lower case.

* Removed type from UniFiCache constructor

It's redundant and only used for logging.

* Added UniFi Site and wLAN things

* Improved default state handling

Updated refresh/state update, to also update when no data available.
Simplified usage of cache: call cache directly instead of implicit via controller class.
Made getDefaultState generic to all things, and simplified passing channelId instead of channelUID to sub methods.

* Moved dto objects to dto package.

* Added support for client experience

* Made fields private

No need to have them protected.

* Added PoE power-cycle command

Also added wireless client as command as this better fits with the openHAB model to handle commands that are only one way and not have a state.

* Updated readme

* [unifi] Added client/guest count to wlan

* Fix QRcode construction and added hidden ssid support in qrcode string

Also-by: Matthew Bowman <mgb@otr.mx>
Signed-off-by: Hilbrand Bouwkamp <hilbrand@h72.nl>
Co-authored-by: Matthew Bowman <mgb@otr.mx>
Signed-off-by: Andras Uhrin <andras.uhrin@gmail.com>
  • Loading branch information
@Hilbrand @mgbowman @andrasU
2 people authored and andrasU committed Nov 12, 2022
1 parent c712924 commit 77adf69
Show file tree
Hide file tree
Showing 57 changed files with 3,271 additions and 904 deletions.
169 changes: 140 additions & 29 deletions bundles/org.openhab.binding.unifi/README.md
View file
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 @@ -36,9 +39,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 @@ -56,8 +78,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 @@ -69,37 +93,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 `passphrase` or `qrcodeEncoding` channel your Wi-Fi password will be exposed in openHAB.
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 reconnect | Write |
| reconnect | Switch | Force the client to reconnect | Write |


_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 | Overall health indication of the client (in percentage) | Read |
| 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 @@ -126,7 +237,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

0 comments on commit 77adf69

Please sign in to comment.