# 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 |
# 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. You need to setup a bridge (Cloud-Login) to commiunicate 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 informations such as "Device-Alias" as from udp-discovery. But you need to know the IP-Adress 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 informations as from cloud. But therefore it set's device-ip and protocol automaticly. 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 informations from local devices. If you enable setting 'onlyLocalOnlineDevices' results will only 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´
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 DeviceName. IP-Address and Encryption has to 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 UPD-Discovery to get more informations 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
WiFi-based things needs to be configured with ipAddress.
RF-based things need a SmartHub(WiFi-Device) to operate.
The things has 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 |
| 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 | White-Color-Temp 2500-6500K | L510, L530, L610, L630, L900, L920 | |
| 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 |
| onTime | Number:Time | seconds output is on | P100, P105, P110, P115, L510, L530, L900, L920, L930 | |
| 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 refreshRequest 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 immediately refresh of the whole device.
# Full Example
# tapocontrol.things Example
tapocontrol:bridge:myTapoBridge "Cloud-Login" [ username="[email protected]", 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="[email protected]", password="verysecret" ] {
Thing P110 mySocket "My-Socket" [ ipAddress="192.168.101.51", pollingInterval=30 ]
}
# tapocontrol.items Example
Switch TAPO_SOCKET "socket" { channel="tapocontrol:P100:myTapoBridge:mySocket:actuator#output" }