Table of Contents
Control By Web: Outgoing
This plugin is functionally similar to the original Control By Web plugin but instead of using the inter device communications protocol and waiting for the device to make a connection to XTension, XTension will make an outgoing connection to the device. This can be useful if you are already using the inter device channel to talk to another device or if the network parameter is easier managed by having an outgoing connection rather than passing through an incoming one.
Please see the original Control By Web Plugin page for more info on the proper setup of the units, this article will discuss only the differences between that plugin and this one. The potentially complex setup of the inter device communications settings as described for the original plugin is not necessary for this plugin.
With the original plugin only a single instance of the plugin was needed to receive a connection from any number of CBW devices. In the case of the outgoing connection plugin a separate instance of this plugin must be created and setup for each individual device you wish to connect to.
Note that this plugin may not work with the original oldest web relay devices as they may not support sending the data in json format as opposed to XML. In that case please use the original plugin.
Important Safety Tip:
Do not set the web interface port number to the same as the port number for the Remote Services protocol or both will be rendered useless until you do a factory reset on the controller.
Enter the IP Address or local dns name of the device and the Port the web interface is running on. If you have authentication set on the device check the Use Authentication checkbox and fill in the User ID and Password fields.
Choosing a Polling Interval: The devices do not support an incoming persistent connection so we must poll for changes and updates. Most devices recommend a 3 second polling interval, but for digital inputs this may be too slow to catch a quick event. It does not appear to cause my test devices any problem to set this as low as every second but you will need to experiment with your own setup and make sure this is not causing any other performance issues with the control by web devices. Set the polling interval to whatever value makes sense for your use case.
The Log Next Polling Result button is a debugging or development tool. Clicking this button will cause the next polling result to be written to the XTension log. This can be helpful if I need to see different device types that I do not have for testing and will make it easier to support new devices in the future. This button will be greyed out unless the interface is actually running. The log output might be long if you have a lot of devices configured. Copy and paste the output out of the log and send it to me if there are issues with reading the values I need to sort out.
Like the original plugin a Unit will be created for each endpoint that is described in the data received. There are a wide variety of device types that may be included and they add more regularly so the plugin may not know what the proper unit suffix or dimmable or receive only settings are for a particular device. Once the unit is created in XTension please go through the units and make sure that discrete units are not marked as dimmable and that the proper units and receive only settings are setup for the units to avoid confusion later.
By default the Units are created with a name that is the name of the plugin interface instance followed by the endpoint name as sent from the device. This is not the descriptive name you may have already given it in the devices own interface. Once the units are created you can rename them in XTension to be more descriptive or to make better sense inside your own system. Do not change the Address of the Unit as that is how the data to the unit and control from the unit is sent to the right place.
For Units that may update often but for whom you don’t necessarily need to see every update in the log it may also be helpful to check the Dont log new value receptions checkbox in the Advanced Tab of the Edit Unit dialog. This is especially true for the voltage in or “vin” unit created by default for the devices. This value can bounce around quite a bit spamming your log with information that is not terribly useful.
Managing Units To Ignore:
By default some known keys are ignored by XTension as they cannot be easily converted into a unit value for example the time or latitude that the device also sends. There may be more keys that do not translate in newer or more complex systems that also need to be ignored. Or you can use the same procedure to tell it to ignore the voltage input unit which tends to create a lot of traffic as it bounces around. Note that capitalization matters when adding keys to the list so please do a Log Next Polling Result from the setup dialog before adding things to make sure you get the capitalization correct.
This is done via the following scripting commands:
List Keys To Ignore:
writes the list of keys currently being ignored to the log.
tell xInterface “my CBW device” to listKeysToIgnore()
results in output something like:
12/25/22 11:06:12 AM.0645 control by web outgoing: Listing 10 keys to ignore: 12/25/22 11:06:12 AM.0654 control by web outgoing: lat, long, time, utcTime, timezoneOffset, serialNumber, minRecRefresh, downloadSettings, vin, test
Add Key To Ignore:
Pass any number of keys that you would like to add to the ignore list. If the key is already in the list an error is written to the log letting you know it was already there.
tell xInterface “my CBW Device” to addKeyToIgnore( “vin”, “longitude”, ...)
once the command is complete the plugin will no longer send any updates to the units that were previously created for this value. It will not automatically delete the Unit. Once a key is added to the list you may manually delete the Unit and it will not be re-created.
Remove Key To Ignore:
Removes a value from the list of keys to ignore. Pass one or more keys to remove from the list. If the key is not in the list an error is written to the log letting you know it was not found.
tell xInterface “my CBW Device” to removeKeyToIgnore( “vin”)
Set Default Keys To Ignore:
Resets the list of keys to ignore to the default. In case you get so removed from what you wanted you can start over.
tell xInterface “my CBW Device” to setDefaultKeysToIgnore()
Set Log Next Polling:
This is identical to pushing the button of the same name on the Interface Setup dialog. It will cause the entirety of the return from the device showing all available values to be written to the log. Can be useful to see what you might wish you were ignoring or where an error is happening making it easier for me to add support for new device types or fix problems that might crop up.
tell xInterface “my CBW Device” to setLogNextPolling()
- This plugin was added to XTension in version 9.5 in december of 2022 in order to better support newer devices with a different inter application protocol that may not work with the original plugin,