Table of Contents
v0.1 by James Sentman This plugin is currently in beta and is not feature complete.
The Wiz Connected plugin for XTension supports the WiFi versions of bulbs and switches from Phillips. This plugin does not support the Zigbee “Hue” lights or the Blue Tooth versions of their bulbs. For connecting XTension to a Hue Zigbee hub please use the separate Phillips Hue Plugin.
The Wiz bulbs use a local network broadcast system to find each other and for control and so can only control devices on the same local network as XTension. Only a single instance of the plugin running is necessary to support any number of devices on the same network. No setup for the plugin is required beyond creating a new interface in XTension and selecting “Wiz Connected” from the device/plugin popup.
Once you save and enable the plugin it will begin by doing a discovery on the local network. Any devices that are found will have a Unit in XTension created automatically for them if it doesn’t already exist. The Unit will reflect the capabilities of the device as far as dimmable or not and what color or color temperature capabilities are available.
Discovered devices will initially be named with the interface name you used above and the unique MAC address of the unit. There does not appear to be a good way to get the name of the device that you configured into the Wiz system at this time. Once the Unit is created you can edit it and give it a more descriptive name. The current status and color or color temperature values will be reflected immediately in the new Unit.
You can run a discovery of new devices at any time by clicking the Discover New Devices Now button or using the script command “discoverDevices()” as documented below.
The Unit Setup dialog has controls for setting the scene as well as setting the polling options. There is no way to get an event when a Wiz light is controlled from some other source such as one of their remotes or one of their Apps and so XTension much poll the lights regularly to pick up any changes that are made outside of XTension. If the light won’t be controlled from elsewhere or if it doesn’t matter that XTension always properly represent it’s state you can set this to None to save the CPU and network traffic. If you need to find out as quickly as possible in order to trigger some other action based on it’s state you can set the interval as low as 1 second though I would recommend a normal setting of every 5 as a minimum and every minute or so for bulbs that don’t matter as much. The default is 30 seconds. Beta Note, when first created a unit will show “Don’t Poll” as the default in the edit unit dialog. If you edit the unit be sure to reset this to 30 seconds or you will stop polling the unit. Once you’ve set it that way it will stick.
Dealing With Scenes:
The Wiz bulbs have many “Scenes” that can be triggered from their remotes, apps and also from XTension. If a device is running a scene the name of the scene will be displayed in XTension as a label over the Value fields in any display. You can run a scene from XTension via the interface or via a script command. In the user interface you can run a script from the Edit Unit dialog as displayed above or from the advanced controls popup that you can reach from any list or web interface in XTension.
Many scenes have a “speed” or other value that goes with them. If the scene requires that enter it into the Value field before clicking the Send Command button. It seems most values are in the range of 0 to 200. The Warm and Cold light scenes are a bit confusing as they also take a value between 0 and 200 but will look later to XTension as if you are simply showing a white with a specific color temperature.
When using the user interface the current brightness is used as the brightness for the scene. Changing the brightness of the unit may cancel the scene at least in this beta version. In the future you’ll be able to change the brightness of a scene without having to re-select it.
There remains some oddness in XTension’s handling of scenes in this beta version. As I get more experience of just how it works I will continue to flesh out the support for them.
A device running a scene will display the name of the scene and then the brightness in the Value fields throughout XTension. Here is an example of a device running the “Fireplace” scene at a brightness of 11%:
While this is the default behavior you can override it by changing the On Label or Off Label in the Edit Unit dialogs Display tab. For example: if you wish to always display just the value in the field adding the Advanced Label Syntax of just “<value>” to the On Label field would make it always display the brightness without any of the other labels.
Setting Scenes From a Script:
The script command allows you to send the speed as well as the brightness:
sendSceneCommand( name of scene, speed of scene [0-200], brightness of scene [0-100])
tell xUnit “wiz device a8442233xx” to sendSceneCommand( “Party”, 200, 100)
would set the bulb to run the “Party” scene at a speed of 200 and full brightness. Note that the scene name is not case sensitive “party” would work as well.
There is some oddness about how the bulbs respond to these commands that I haven’t figured out yet. When trying to just change the speed of the Party scene without changing the brightness the command is often ignored. If however you also change the brightness as well it seems to accept it. There also appear to be limits to what speeds are available at lower dimming ranges. Some experimentation may be necessary to get these bulbs to do what you desire.
Valid Scene Names:
The following are the currently valid scene names you can use as the name in the script command. The names are not case sensitive when sent through the script.
- Cool White (not recommended: just use the regular color temperature settings)
- Golden White
- Night Light
- Pastel Colors
- Rhythm (I think this is used as part of a remote control type display and might not do anything otherwise)
- True Colors
- TV Time
- Wake up
- Warm White (not recommended: just use the regular color temperature settings)
Other Supported Functions:
- The bulb will respond to the Query verb to force a poll via a script. Note that no value is returned from the query command, but if the value or settings of the bulb are different when the data is returned it will be updated. The Query verb is run async and operates in the background. The query command will update the data for the Unit in XTension regardless of the polling settings for the device. Even if the device is set for no polling at all you can do so manually via the query command.
query “wiz device in bedroom”
- To run a discover of new devices from a script use the discoverDevices command.
tell xInterface “name of your wiz interface” to discoverDevices()
- Reboot a device. A device can be rebooted from the script command reboot()
tell xUnit “name of your wiz device unit” to reboot()
Known Issues and Yet To Do:
- Values often pop down one from what you set them after the next poll. For example you set the light to 100 and it resets to 99 after the next poll. This is a problem with conversion between the internal 0-255 value and XTensions 0-100 percent that is not completely sorted everywhere. This will be fixed before the release.
- If you are running a scene and issue a regular turnon or turn off it will reset the bulb to a non-scene regular setting but the value in XTension will not remove the name of the last scene until the next poll. This will be fixed before the non-beta release.
- Setting the scene to “None” does not stop the scene yet. Use a turn off or turn on to a specific color or color temperature to cancel a scene for the moment.
- If the bulb goes offline you’ll get errors in the log about it not being available for polling rather than an error in the Unit display as is the norm. This will be fleshed out in the next version.
- If the bulb changes it’s IP address it will not yet be re-discovered until you disable and re-enable the interface. This will also be fixed in the next version. For most routers/DHCP servers this is not terribly likely to happen as it will ask for it’s same IP address with each update to it’s lease but not all devices support that so your milage may vary.
- The Wiz plugin was first included in XTension version 9.4.37 as a beta.