# TapoControl Binding

This binding adds support to control Tapo (Copyright © TP-Link Corporation Limited) Smart Home Devices from your local openHAB system.

## Supported Things

The following Tapo-Devices are supported. For precise channel-description look at `channels-table` below:

| DeviceType                         | ThingType | Description                                   |
|------------------------------------|-----------|-----------------------------------------------|
| SmartPlug (Wi-Fi)                  | P100      | Smart Socket                                  |
|                                    | P105      | Smart Mini Socket                             |
| EnergyMonitoring SmartPlug (Wi-Fi) | P110      | Energy Monitoring Smart Socket                |
|                                    | P115      | Energy Monitoring Mini Smart Socket           |
| Power Strip (Wi-Fi)                | P300      | Smart Wi-Fi Power Strip - 3 sockets           |
| Dimmable SmartBulb (Wi-Fi)         | L510      | Dimmable White-Light Smart-Bulb (E27)         |
|                                    | L610      | Dimmable White-Light Smart-Spot (GU10)        |
| MultiColor SmartBulb (Wi-Fi)       | L530      | Multicolor Smart-Bulb (E27)                   |
|                                    | L630      | Multicolor Smart-Spot (GU10)                  |
| MultiColor LightStrip (Wi-Fi)      | L900      | Multicolor RGB Dimmable LightStrip (5m)       |
|                                    | L920      | Multicolor RGB-IC ColorZone LightStrip (5m)   |
|                                    | L930      | Multicolor RGBW-IC 50-Zone LightStrip (5m)    |
| Smart Hub (Wi-Fi / RF)             | H100      | Smart Hub with Chime to control Child Devices |
| Smart Contact Sensor (RF)          | T110      | Window/Door Smart Contact Sensor              |
| Smart Temperature Sensor (RF)      | T310      | Temperature and Humidity Sensor               |
|                                    | T315      | Temperature and Humidity Sensor with Display  |
| Smart Switch (RF)                  | S210      | Wall switch with 1 contact                    |
| Smart Switch (RF)                  | S220      | Wall switch with 2 contacts                   |
| Smart Light Switch (Wi-Fi)         | HS200     | Wall switch with 1 contact                    |

## Prerequisites

Before using Smart Plugs with openHAB the devices must be connected to the Wi-Fi network.
This can be done using the Tapo provided mobile app.
Some devices require Third-Party Compatibility to be disabled then re-enabled via the mobile app after initial installation or firmware upgrade.
You need to setup a bridge (Cloud-Login) to communicate with your devices.

**Note:** If the Tapo device is to be isolated from the internet e.g. on an IoT LAN, the P110 will not expose its energy and power data until it has successfully synchronised it's clock with an NTP server - at time of writing, this was `pool.ntp.org`.
To satisfy this requirement while keeping the device isolated, your router should be configured to either permit `udp/123` out to the internet or a NAT rule created to redirect all internet bound NTP traffic to a local NTP server.

## Discovery

For Wi-Fi devices, discovery is done by connecting to the Tapo Cloud Service or use local UDP discovery.
If enabled, all devices stored in your cloud account will be detected even if they are not in your local network.
From cloud you can get more information such as "Device-Alias" than from UDP discovery.
But you need to know the IP address of your device. This must be set manually in the Thing configuration.

UDP discovery can find only devices which are online in your local network and get less information than from the cloud.
But therefore it sets device IP and protocol automatically.
If you have problems with UDP discovery, try to set the advanced setting 'broadcastAddress' to your local subnet (e.g. 192.168.0.255).
Default is '255.255.255.255'

You can combine both discovery methods to get any information from local devices.
If you enable setting 'onlyLocalOnlineDevices' results will only be generated for local online devices but with the combined data of cloud discovery.
RF devices will be discovered by the hub they are connected to.
You can discover them manually or use `backgroundDiscovery`

## Bridge Configuration

The bridge needs to be configured with by `username` and `password` (Tapo-Cloud login) .
This is used for device discovery and to create a handshake (cookie) to act with your devices over the local network.

The Thing has the following configuration parameters:

| Parameter              | Description                                                                                                                                                |
|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|
| username               | Username (email) of your Tapo Cloud                                                                                                                        |
| password               | Password of your Tapo Cloud                                                                                                                                |
| cloudDiscovery         | Use Cloud Discovery Service to get all in Tapo App registered devices. Includes device name. IP address and encryption have to be set manually             |
| udpDiscovery           | Use UDP Discovery Service to discover online devices in the local network. Includes encryption and IP address. Results will be merged with cloud discovery |
| onlyLocalOnlineDevices | [advanced] Uses Cloud and UDP Discovery to get more information but will only discover online devices via UDP                                              |
| broadcastAddress       | [advanced] Set broadcast address to your local subnet  if you have problems with default address                                                           |
| discoveryInterval      | [advanced] Interval in minutes when a background device scan should be executed. Default is 60                                                             |

## Thing Configuration

Wi-Fi-based Things need to be configured with `ipAddress`.
RF-based things need a SmartHub (Wi-Fi device) to operate.

The Things have the following configuration parameters:

| Parameter          | Description                                                           | Things supporting parameter |
|--------------------|-----------------------------------------------------------------------|-----------------------------|
| ipAddress          | IP address of the device.                                             | Any Wi-Fi device            |
| pollingInterval    | [optional] Refresh interval in seconds. The default is 30 seconds     | Any Wi-Fi device            |
| httpPort           | [optional] HTTP communication port. Default is 80                     | Any Wi-Fi device            |
| protocol           | [optional] Used communication protocol (AES/KLAP/'') Default 'AES'    | Any Wi-Fi device            |
| backgroundDiscovery| [optional] RF devices will be discovered after every polling request  | SmartHub                    |

## Channels

All devices support some of the following channels:

| group     | channel          | type                   | description                         | things supporting this channel                                          |
|-----------|----------------- |------------------------|-------------------------------------|-------------------------------------------------------------------------|
| actuator  | output           | Switch                 | Power device on or off              | P100, P105, P110, P115, L510, L530, L610, L630, L900, L920, L930, HS200 |
|           | output1          | Switch                 | Power socket 1 on or off            | P300                                                                    |
|           | output2          | Switch                 | Power socket 2 on or off            | P300                                                                    |
|           | output3          | Switch                 | Power socket 3 on or off            | P300                                                                    |
|           | brightness       | Dimmer                 | Brightness 0-100%                   | L510, L530, L610, L630, L900, L920                                      |
|           | colorTemperature | Number:Temperature     | Color Temperature in Kelvin         | L530 (2500 K .. 6500 K), L630 (2200 K .. 6500 K)                        |
|           | color            | Color                  | Color                               | L530, L630, L900, L920                                                  |
| sensor    | isOpen           | Switch                 | Contact (Door/Window) is Open       | T110                                                                    |
|           | currentTemp      | Number:Temperature     | Current Temperature                 | T310, T315                                                              |
|           | currentHumidity  | Number:Dimensionless   | Current relative humidity in %      | T310, T315                                                              |
| effects   | fxName           | String                 | Active lightning effect             | L530, L900, L920, L930                                                  |
| device    | wifiSignal       | Number                 | WiFi-quality-level                  | P100, P105, P110, P115, L510, L530, L610, L630, L900, L920, L930, HS200 |
|           | onTime           | Number:Time            | seconds output is on                | P100, P105, P110, P115, L510, L530, L900, L920, L930, HS200             |
|           | signalStrength   | Number                 | RF-quality-level                    | T110                                                                    |
|           | isOnline         | Switch                 | Device is Online                    | T110                                                                    |
|           | batteryLow       | Switch                 | Battery of device is low            | T110                                                                    |
| energy    | actualPower      | Number:Power           | actual Power (Watt)                 | P110, P115                                                              |
|           | todayEnergyUsage | Number:Energy          | used energy today (Wh)              | P110, P115                                                              |
|           | todayRuntime     | Number:Time            | seconds output was on today         | P110, P115                                                              |
| alarm     | alarmActive      | Switch                 | Alarm is currntly active            | H100                                                                    |
|           | alarmSource      | String                 | Source causes active alarm          | H100                                                                    |

## Channel Refresh

When the Thing receives a `RefreshType` command the Thing will send a new refresh request over HTTP.
To minimize network traffic the default refresh rate is set to 30 seconds.
This can be reduced down to 10 seconds in advanced settings of the device.
If any command was sent to a channel, it will do an immediate refresh of the whole device.

## Full Example

### `tapocontrol.things` Example

```java
tapocontrol:bridge:myTapoBridge                 "Cloud-Login"               [ username="you@yourpovider.com", password="verysecret" ]
tapocontrol:P100:myTapoBridge:mySocket          "My-Socket"     (tapocontrol:bridge:myTapoBridge)   [ ipAddress="192.168.178.150" ]
tapocontrol:L510:myTapoBridge:whiteBulb         "white-light"   (tapocontrol:bridge:myTapoBridge)   [ ipAddress="192.168.178.151", httpPort=80, pollingInterval=30, protocol="AES" ]
tapocontrol:L530:myTapoBridge:colorBulb         "color-light"   (tapocontrol:bridge:myTapoBridge)   [ ipAddress="192.168.178.152", pollingInterval=30, protocol="KLAP" ]
tapocontrol:L900:myTapoBridge:myLightStrip      "light-strip"   (tapocontrol:bridge:myTapoBridge)   [ ipAddress="192.168.178.153", pollingInterval=30, protocol="" ]

Bridge tapocontrol:bridge:secondBridgeExample            "Cloud-Login"        [ username="youtoo@anyprovider.com", password="verysecret" ] {
   Thing P110 mySocket   "My-Socket"          [ ipAddress="192.168.101.51", pollingInterval=30 ]
}
```

### `tapocontrol.items` Example

```java
Switch       TAPO_SOCKET      "socket"                { channel="tapocontrol:P100:myTapoBridge:mySocket:actuator#output" }
```
