supported_hardware:tplink
Differences
This shows you the differences between two versions of the page.
Next revision | Previous revisionLast revisionBoth sides next revision | ||
supported_hardware:tplink [2019/11/15 14:37] – created James Sentman | supported_hardware:tplink [2023/03/04 16:23] – [TP-Link/Kasa Device:] added power recovery preset info and new screenshot James Sentman | ||
---|---|---|---|
Line 1: | Line 1: | ||
=====TP-Link / Kasa===== | =====TP-Link / Kasa===== | ||
- | The TP-Link/Kasa plugin is included in the standard | + | Currently at version 1.1 2/19/2020 and included in XTension |
- | **Note:** This plugin | + | The TP-Link/ |
+ | This plugin uses the local subnet protocol for discovering devices and controlling them. Only devices on the same local subnet with the XTension machine will be found, devices elsewhere in the cloud will not be discovered. An active internet connection then is not needed to control devices on the same subnet. | ||
+ | |||
+ | **Note:** There are many and varied WiFi controllable devices out there. This one is compatible only with devices branded as TP-Link or Kasa. This is not compatible with Sonoff or any other devices that I am aware of. There may be other off brand ones that use the same local network protocol, but I wouldn’t count on it just because they are made to look like the TP-Link devices. | ||
+ | |||
+ | ====Requirements: | ||
+ | This plugin requires Python3 which is not part of the standard MacOSX install. If you haven’t already done so for one of the other plugins that also require python3 please download and install that from [[https:// | ||
+ | |||
+ | ====Device Configuration: | ||
+ | Add the device to your local network in the normal way using the iOS or Android app. Once the device is available on your local wifi it will be discoverable by the XTension plugin. | ||
+ | |||
+ | ====Plugin Configuration: | ||
+ | {{: | ||
+ | |||
+ | **Device Discovery: | ||
+ | < | ||
+ | tell xInterface “this interface name” to discover() | ||
+ | </ | ||
+ | |||
+ | That will return immediately as the discovery is an async process. If the “Create New Units” checkbox above is selected then any new units discovered will be created in XTension. | ||
+ | |||
+ | **Default Polling Interval:** TP-Link/ | ||
+ | |||
+ | Each Unit has a configuration option to override the default polling interval for that specific device. | ||
+ | |||
+ | |||
+ | ====XTension Unit Types:==== | ||
+ | |||
+ | In XTension a Unit will be created for each Device discovered. You can manually create other units for the energy monitor functions if available. The Units when created will be given the same name that you have configured in the Kasa app when you set them up. After that you can change the name of the XTension unit to anything you wish. These changes are not sent back to the Devices. The names are only read when creating the units. Once the unit is created you can change the name of either the XTension Unit or the Device without affecting the other. | ||
+ | |||
+ | The address of the XTension Units will be the MAC address of the device with the exception of the powerstrip outlet Units which will be the MAC address followed by a period and then the index of the outlet starting at 0. So something like 12: | ||
+ | |||
+ | All units support the [[dictionary: | ||
+ | |||
+ | < | ||
+ | query “name of unit you wish to query” | ||
+ | </ | ||
+ | |||
+ | Remember that the query is done async. The query command returns immediately and if there is any change to the unit status then the unit will update when that is received back from the device. | ||
+ | |||
+ | ===TP-Link/ | ||
+ | |||
+ | {{: | ||
+ | |||
+ | |||
+ | **Device Polling:** | ||
+ | If you wish you can override the Default Polling Interval you set in the Plugin Settings window above. If you have polling turned off globally you can still enable it for individual Devices by setting a value here. Enter 0 to disable polling for this Device, leave blank to use the global default setting or set to any value greater than 5 seconds. The faster you poll a device the faster the XTension database will conform to the current settings of the device. When controlling a Device from XTension the database will always be correct, if you control the Device from another control point like the mobile app those changes must be polled to be found. If you never control the Device from anywhere but XTension you can turn polling off. | ||
+ | |||
+ | **Send Power Recovery Preset Level:** | ||
+ | Some especially older Bulbs have a problem with turning on remotely to a different level or color than they were at when they were turned off. They will immediately start ramping to the last in use level before then changing to the new level you are sending them. This can be a problem if you are using the bulb somewhere you don’t want a flash of bright light when you turn on the light. Checking this box will have XTension send the brightness level you set immediately before turning it off. A low value like the default of 1% will avoid the Nova effect but it also makes it impossible to turn the lamp on by physically turning the bulb off and back on again, as it will only return to the 1% level. So for bulbs that do not nova you can turn this off. | ||
+ | |||
+ | You can also leave this on and then whenever XTension turns the bulb off it will send whatever value is there, This makes it possible to set the power on level whenever you turn off the bulb. This value is ONLY sent if XTension turns off the light, and the light is powered on and available at the time. It cannot change the level if the bulb is offline. | ||
+ | |||
+ | This is sent to the bulb anytime an Off is sent. The bulb does not have to be On to get this command, though you may see a momentary flicker of light from it as it starts to ramp up to the preset level before receiving it’s off command again. | ||
+ | |||
+ | You can change this value programmatically by using the setPowerRecoveryPreset command. See the section below on scripting commands for more info on using that. | ||
+ | |||
+ | **Manage Meta Data Units:** | ||
+ | In addition to the Unit that controls the state of the device, you can optionally create units to track the energy usage and the devices wifi signal strength. Not all devices support these functions. If you create one for a device that does not track that information the new unit will be created but will quickly set an error condition noting that it cannot get that information. | ||
+ | |||
+ | ===TP-Link/ | ||
+ | The “Smart Strip” or other multi-outlet devices will be configured as a Powerstrip Unit. A top level unit will be created with it’s device type popup set to “Kasa Power Strip” Controlling this Unit will turn on or off all the outlets of the powerstrip. | ||
+ | |||
+ | If you create energy usage units for this unit they will be the sum of all the watts or KWH usage of all the outlets. To measure the usage of a single outlet create the appropriate unit from the Powerstrip Outlet unit below. | ||
+ | |||
+ | Only the top level powerstrip device can read it’s wifi signal strength. Creating an RSSI unit for an individual outlet will result in a unit with an error set. | ||
+ | |||
+ | After the main powerstrip Unit is created, a separate “Powerstrip Outlet” Unit will be created for each controllable outlet in the device. For many devices they can have their own watts and KWH monitoring units created but if you create an RSSI unit for an outlet it will just log an error condition as the individual outlets do not send a separate RSSI from the main device. | ||
+ | |||
+ | Other multi-outlet devices such as the outdoor dual outlet module and the wired outlet devices with each outlet controllable separately will show up as powerstrips with only 2 outlets or however many outlets that they support. | ||
+ | |||
+ | |||
+ | |||
+ | |||
+ | |||
+ | ====Note: | ||
+ | |||
+ | This plugin uses an undocumented protocol to talk to the devices on the local network and therefore does not require internet access or for the devices to be connected to the cloud in order to work. This is the same protocol that the Kasa iOS and Android app use to control the devices when on the same subnet. While I hope it is unlikely, it is possible that they could change this at any moment making the plugin unusable. I would recommend that before updating any devices firmware in the future that you verify either on this site or by experimenting with one device that things continue to work properly. | ||
+ | |||
+ | ====ToDo: | ||
+ | * Test with other multi-outlet devices such as the hardwired Electric Outlets that have 2 controllable outlets and the outside dual controllable outlet device. I have an outdoor unit on order which should arrive soon and I’ll be able to verify that these work or work on supporting them in the next version. | ||
+ | * Some of the devices that support KWH tracking can also give historical information for just this day as well as monthly or other intervals. A meta data unit that tracked the usage for the current day and month would be useful. | ||
+ | * A way to reset the KWH usage would be useful. | ||
+ | * Some devices also report the voltage level at the plug. Create an optional meta data unit to track this for supported devices. | ||
- | This document is in the process of being created, please check back shortly for more info. | ||
===History=== | ===History=== | ||
- | * The TP-Link/ | + | * The TP-Link/ |
+ | * The automatic discovery interval was removed in version 1.1 of the plugin which was included in XTension build 9.4.28. The discovery would cause units to be lost if it intersected with an actual control or poll of a device. If you need to discover a new device click the Discover New Devices Now button at any time or use the scripting command documented above. |
supported_hardware/tplink.txt · Last modified: 2023/03/04 16:33 by James Sentman