The Server Sent Events plugin can connect to a standard HTTP Server-Sent Events stream. This is commonly used as a way for a server to send live updates to a web page running in a browser, but it may also contain information you wish to get into XTension units.

There is no completely predictable way that a server events stream is managed, they can contain just about any data at all but every “event” will at least have a name even if it does not have any data. I have tried to do a generic implementation that can get the data into Units in XTension in a way that you can handle the further scripting of if necessary.

All command matches with unit addresses talked about below are not case sensitive. An event named “Motion” will match a unit with an address of “MOTION” and so forth.

Note: that as of version 1.0 of this plugin secure sockets connections are not supported. If you need to make an HTTPS connection please let me know and I’ll bump up the adding of that on the list of priorities.

Outgoing Network Connection: Enter the address and port that the server is running on. If possible assign a static IP address to the remote device or server so that it won’t change and break the connection. You can also use an mDNS/Bonjour name or standard DNS name here if necessary.

HTTP Path: This is the request path to start the server events stream. Any GET parameters can be included after the path as in the example picture. As of version 1.0 it is not possible to send a PUT or POST request to start the stream. If you need to do this please drop me a note and I’ll move adding this up the priorities list.

Note that this is not the full URL. This field should not contain the “http://192.167.54.3:80/“ portion of the URL. Only the path portion beginning with a forward slash as in the example.

If an event is received with no Data section after it two things are done. First the event name is written to the XTension log in case that is something that you wish to see. In addition an ON is sent for a unit with the same address as the event name. In the case of something like the data stream from a networked video camera it may just send “event: Motion” type events without any extra data. If you create a Unit on this interface and set it’s address to “Motion” then it will receive an On command whenever that is received and you can now process the motion hit in the On script of that Unit.

For example, if we receive:

event: Motion

with no data section then an On will be sent for an XTension Unit with the address of “MOTION“

If the Data portion of the event is equal to “on”, “true” or “yes” then an On event is sent to the XTension unit with the same address as the Event name.

If the Data portion of the event is equal to “off’, “false” or “no” then an Off event is sent to the XTension unit with the same address as the event name.

The matching of these strings is not case sensitive, “on”, “On”, “oN” or “ON“ will all send an On command to the unit. The matching of the unit address is not also not case sensitive.

For example if we receive:

event: Motion
data: True

then a Unit with the address of “MOTION” will be turned on.

If instead the data is numeric the Unit in XTension with the same Event name as it’s address will receive a set value command for that. Floating point values or integers are supported with either the period or a comma as the decimal separator, if a float.

for example is we receive:

event: Brightness
data: 47.5

a set value command will be sent to a Unit in XTension with the Address of “BRIGHTNESS” to set it’s value to 47.5. Make sure that the Unit you create is dimmable or the unit will act as if it has just received an On command rather than a set value.

As of release 1.0 if the data is not matched for an on/off command nor is it numeric then the data is just written to the XTension log. If you need instead to parse this data in the Script of the unit I can forward it to a scripting handler. This is not implemented at this moment so please drop me a note if you need this and I’ll move it up the priorities list.

If the server disconnects the plugin will attempt to reconnect every second until the connection is re-established. The Interface error handler is executed if the server disconnects or refuses the initial connection and the error is displayed in the log and in the interface status field of the interface list window.

The Server Events plugin first appeared in XTension 9.4.28 in March of 2020. It is part of the standard XTension plugin pack and included with the download of the app. No extra install is required.

The Server events plugin was updated to run under the embedded version of python in 9.4.45 in march of 2022. As of the initial embedding the python version was 3.10. No longer requires a system version of python2.7