TPLink RTI Driver

Revision: 20200130

Date: 2020/01/30

Author(s): Richard Woodburn

Overview

The TPLink RTI driver allows for control over a wide range of TPLink WiFi products.

TPLink light switches, lighting and plugs are inexpensive and widely available, simple to install and, with this driver, fully controllable by RTI.

Each device supports on / off control, devices with multiple outlets are individually switchable. Devices with energy monitoring support custom power usage can be set per outlet for on and off events. Using this you can tune the power levels that indicate a device being powered on or powered off to suit.

Supported Devices

This TPLink driver has been written and tested to support the following devices

Light Switches

HS200 - with brightness setting

Plugs

HS100 - Wi-Fi Plug

HS110 - Wi-Fi Plug with energy monitoring

HS300 - Wi-Fi Power Strip with six outlets and energy monitoring

KP200 - Wi-Fi Two Outlet In-Wall Plug

KP400 - Wi-Fi Outdoor Plug with 2 Outlets

Lighting

KL110 - Globe with brightness control

KL120 - Globe with brightness and color temperature controls

KL130 - Globe with full RGB color, brightness and color temperature controls

KL430 - Light Strip with full RGB color, brightness, color temperature controls and animated lighting effects

Driver Installation

The zip file that included this documentation has the rtidriver file you will need to add. The first step is to download and extract the driver from the zip file. It doesn’t matter where you store the file but we advise keeping them together.

The default location is Documents\Integration Designer\Control Drivers

Add the driver

Select Add Workspace Item from the top of the Workspace panel or Add.. from the Device menu

Click on the Drivers Tab and select TPLink model Kasa Smart from the list of Drivers. You can also enter tplink in the search bar to help with selection.

Select the location of the driver, then click Next > at the bottom of the dialogue.

Review Device information, Add pages to devices as required and Name the device then click Add Device.

The driver is now ready to configure.

Update an existing driver

It is recommended that you copy the updated driver to your default driver folder.

This will prevent accidentally selecting an old driver when starting a new project.

The default location is Documents\Integration Designer\Control Drivers

Once the file has been replaced, it will need to be updated in the project.

Select the Bond Bridge driver in your workspace then Click on Driver Utilities... and Update Drivers…

Navigate to the driver location select and click open.

Note: You can review driver information in the open control driver dialogue.

Driver Configuration

Licence

The driver will work without a licence for 7 days, automatically entering the trial phase if you don’t enter a licence key. To keep using the driver after the trial has expired you will need to purchase a licence key.

Once you have your key it should be entered into the Licence field.

TPLink Settings

The TPLink driver supports multiple device types and setup for each is slightly different.

All drivers require the following:

IP Address - the address of the device on the local network.

Port - defaults to 9999 only change if required.

Type - Selection exposes additional configuration in some cases.

Poll rate (s) - How many seconds between status checks by the driver.

Current device types are:

White Light bulb

Color Light bulb

Color Light Strip

Outlet (with Monitoring)

Outlet (without Monitoring)

Dimmer Switch

White Light Bulb and Dimmer Switch

No further configuration required

Color Light Bulb / Color Light Strip

Circadian Rhythm Color - select a driver or device that can output a colour temperature to set the bulb to. Anytime this variable changes an update will be sent to the bulb.

Outlet (with Monitoring)

Outlet Count - for devices that have more than 1 outlet this must be set to the count of outlets available.

Power On value (W) - when the device indicates a power draw above this value the attached device will be considered on and a POWER_HIGH event will be triggered

Power Off value (W) - when the device indicates a power draw below this value the attached device will be considered off and a POWER_LOW event will be triggered.

Hint: Try and set a on value that is just below the amount the usual running use and set an off value just over the standby.

Note: An event is only triggered when the device transitions from outside the dead zone.

Outlet (without Monitoring)

Outlet Count - for devices that have more than 1 outlet this must be set to the count of outlets available.

Driver Variables

State

Power [boolean]

This variable indicates the current power state of the outlet.

On Time (s) [number]

The On Time (s) variable contains the time since the outlet was last switched on. The time is in seconds.

Energy Use

The following variables will only contain values if the outlet supports energy monitoring. There are also different values depending on your geographical region. In some regions the values are in millivolts, milliamps and milliwatts and in others its in volts, amps and watts. You will need to configure your variables appropriately.

Voltage [number]

The Voltage variable contains the mains voltage level. The voltage reported varies depending on your region. It will either be in millivolts or volts.

Current [number]

The Current variable contains the current being consumed by the device. The current reported varies depending on your region. It will either be in milliamps or amps.

Power [number]

The Power variable contains the power being consumed by the device. The power reported varies depending on your region. It will either be in milliwatts or watts.

Total Watt Hours[number]

The Total Watt Hours variable contains the power that has been consumed over the time since the outlet was switched on. Regardless of region it is reported in Watt Hours.

Light Color

Light can be controlled by a number of modes,

HSB Values

RGB Values

Color Temperature (deg kelvin)

Hue [number]

Degrees displayed as a number between 0 and 360

Saturation [number]

Percentage displayed as a number between 0 and 100

Brightness [number]

Percentage displayed as a number between 0 and 100

Red [number]

Value displayed as a number between 0 and 255

Green [number]

Value displayed as a number between 0 and 255

Blue [number]

Value displayed as a number between 0 and 255

Temperature [number]

Percentage displayed as a number between 0 and 100

Dimmer Switch

Brightness [number]

Percentage displayed as a number between 0 and 100

System

Version [string]

This variable contains the current firmware version.

Model [string]

This variable contains the model number of the outlet.

Name [string]

This variable contains the name that you have assigned the outlet in the Kasa app.

Driver Details

Licence Valid [boolean]

This variable returns true when the driver licence is valid

Licence Info [string]

This variable returns a string stating the validity of the driver licence

Connection Status [boolean]

This variable returns true when the driver has an active connection to the device

Supports Energy Monitoring [boolean]

This variable returns true when the device has returned that it supports energy monitoring in after the driver has requested system information.

Supports Timer Functions [boolean]

This variable returns true when the device has returned that it supports timer like functions after the driver has requested system information.

Note: TP-Link schedule features are not supported in this driver as the control system can provide this functionality natively.

Driver Commands

The driver polls periodically for device changes, if the unit turned on or off from the mobile application or physical switch then the driver the state may not have updated. If you are in a situation where you need to use the mobile application and the RTI driver concurrently the get system and get energy commands can be used to make certain that the driver has an accurate representation of the current state. The Get Energy command is only required for the outlets that support energy monitoring.

Power Commands

Some devices support a transition time which can be entered along with the following commands if available

Power On

This command will turn the device on.

Power Off

This command will turn the device off.

Power Toggle

This command will toggle the power state of the device. It tracks the current state and will change appropriately.

Energy Commands

Get Energy

This command will fetch the current energy usage for the outlet. This command only applies to outlets that support energy monitoring. These devices can send a POWER_HIGH or POWER_LOW event based on configuration and current power usage. (see TPLink Settings section above)

Get System

This command will update the system details. This includes the name and the current power state. This can be used to ensure the toggle always works if you are using the mobile application and the driver concurrently.

Bulb Control

Note: transition time can be entered along with the following commands

Set Color Temperature

This will set the globe to a white to off white color according to the temperature (degrees kelvin) entered. Setting this value will cause any other color values to be ignored.

Temperature ranges vary from device to device but are usually between 2700 and 6000 but can go as high as 9000.

Set Hue

This will set the hue value of the globe. This is a degrees value entered as an integer between 1 and 360. RGB values will be updated with this change.

Set Saturation

This will set the saturation value of the globe. This is a percentage value entered as an integer between 0 and 100. RGB values will be updated with this change.

Set Brightness

This will set the brightness value of the globe. This is a percentage value entered as an integer between 0 and 100. RGB values will be updated with this change.

Set Red

This will set the Red portion of the RGB value of the globe. This is a value entered as an integer between 0 and 255. HSB values will be updated with this change.

Set Green

This will set the Green portion of the RGB value of the globe. This is a value entered as an integer between 0 and 255. HSB values will be updated with this change.

Set Blue

This will set the Blue portion of the RGB value of the globe. This is a value entered as an integer between 0 and 255. HSB values will be updated with this change.

Dimmer Control

Set Brightness

This will set the brightness value of the device attached to the Dimmer Switch. This is a percentage value entered as an integer between 0 and 100. This value can be changed independent of the power state.

Circadian Color Commands

These commands change the light from a normal operation mode to circadian where the color temperature and brightness are calculated and automatically updated vs the time of day.

There are two options in how to use this feature.

Circadian - Driver Properties

This method creates a subscription to the selected driver or device and when this value changes a Color Temperature on the current driver will be updated as well.

To disable this feature use the Disable Circadian Mode command and to reenable use the Enable Circadian Mode command

Circadian - Device Command

Globes can have this feature enabled directly by sending a command, calling Enable Circadian Mode will do this. Changing any color settings will disable this feature by default but the Disable Circadian Mode is still available to do so. Note using the built in mode will change the color and brightness so these will need to be reset when disabling.

EVENTS

Power Usage

In the driver configuration where a device type with energy monitoring has been selected a Power ON value and and a Power OFF value can also be configured. These values are used to determine when power usage events trigger and can be set individually for devices that have multiple outlets.

This can be used to fire other actions when the device transitions from a standby to a fully active and vice versa this is so you can leave a device connected and the outlet powered on, but have the event trigger when the connected device itself turns on.

An example would be connecting a playstation to the outlet. When the playstation is placed into sleep more it uses less power.

With the device plugged in and in sleep mode monitor the power variable (under Energy Use) for a few minutes and note down the highest value observed.

Set the Power Off value (W) to a slightly greater larger value than what you wrote down.

With the device plugged in and in active mode monitor the power variable (under Energy Use) for a few minutes and note down the lowest value observed.

Set the Power On value (W) to a slightly lower value than what you wrote down.

By configuring the device to use the Power ON and Power OFF values you can trigger macros when the device powers on independently of RTI. Using this method, simply turning on the Playstation with the controller could be used to turn on your entire system, select the correct input on your AVR and power on the TV and switch it to the correct input all without needing to use the RTI remote.

Power High

The Power High event will trigger when the device transitions from a POWER_LOW to a POWER_HIGH state, transitioning from a POWER_HIGH to DEAD ZONE back to POWER_HIGH will not trigger an event.

Power Low

The Power Low event will trigger when the device transitions from a POWER_HIGH to a POWER_LOW state, transitioning from a POWER_LOW to DEAD ZONE back to POWER_LOW will not trigger an event.

Note: On startup of the RTI system the initial state will not trigger an event, only the transition from a known LOW to HIGH or HIGH to LOW will trigger an event.

Switch Event

Power On

The Power On event will trigger when the outlet is turned on via the driver or via the app or by a physical switch on the device. The unit is polled so the event will not trigger immediately if the unit is turned on via the app or a physical switch.

Power OFF

The Power Off event will trigger when the outlet is turned off via the driver or via the app or by a physical switch on the device. The unit is polled so the event will not trigger immediately if the unit is turned off via the app or a physical switch.

Note: On startup of the RTI system the initial switch state will not trigger an event, only the transition from a known OFF to ON or ON to OFF will trigger an event.