Mac Home Automation

This article is in work and not complete.

For those that would like to roll their own web or other interfaces this plugin provides a standardized protocol for sharing your database to a web browser or other program that can speak websockets.

All communications are in JSON format. Upon connection you will receive a long array of JSON objects describing all the units that the user has chosen to share with this interface as well as any Global Scripts that were selected in the sharing dialog. As any of the keyed values in the unit’s data change you will receive another update containing the same unique id but only the changed values will be included. A local index of the Units keyed by their unique ID should be maintained on the client so that changes to unit values can be merged with the existing data and provide events for your interface to change display elements.

The plugin includes a simple webpage with enough embedded javascript to provide a live updating interface to a unit and some simple controls to them as well. It also has a console to show the exact data being sent back and forth. Also included are all the constants needed to read unit data and create commands.

As of this alpha level release there is no security or support for SSL communications though that will come in the future. At this moment if you negotiate a successful web socket connection then you’ll receive the data dump containing all the units and scripts that are shared with this interface.

All data received from XTension will be a JSON object. Inside that JSON object will be named arrays containing descriptions of different system objects. As of this alpha only units and global scripts are included. The key for the array of units is just “units” and for global scripts it’s just “scripts”. Even if this is an update for just a single unit it will still be contained in the units array.

If this is a different command or if no units have changed state but some other object is generating the update then the units key may not be present in the JSON object. Don’t assume it will be there.

{
    “units”:[
         { a unit record...},
         { another unit record...},
         { and so forth}
    ],
    “scripts”:[
         { a global script record...},
         { another script record...}
         { and so forth}
    ]
}

XTension uses standard JSON conventions for integers, floats, strings, booleans and dates. Additionally the JSON data may encode colors which will be sent as a string of 3 comma separated values for RGB or if being sent in HSV then will be a comma separated list of those 3 values.

Additionally you will find another value that describes what the value should be translated into before being passed to an event. For each value in the database there will be another that describes the type of the data. It will be prefixed with the NamedTypePrefix which is “_typ_” followed by the name of the key of the regular value. If you have a string with a key of “name” then there will be 2 entries in the JSON object for that like this:

{
    “name”:”James”,
    “_typ_name”:”str”
}

this is mostly unimportant for most objects in the JSON as they are already sent as their primitive type. The exceptions are colors and dates. If you receive an update for those values you may want to coerce them to the proper types before passing them to the update events. If an update is received where the value is equal to “_del_” then that value has been removed from the host database and should be removed from yours as well.

Everything you need to know about the state or settings of a unit will be sent through as the individual unit records. Due to historical reasons the keys into the unit record are not the same as when sending other commands to XTension. When accessing the Unit record be sure to use the keys that start with a “u” for unit. xt.uKeyUniqueId and not xt.kUniqueID.

All units can always be accessed via their unique id. The unique ID is guaranteed to be included in every update unit record sent from XTension. You should use that as the index into an object so you can find the existing data

There are 2 different ways units may be presented to you, and depending on the application you may have both present in the array of unit records. Most interfaces want to create units in XTension that belong to them. Your ZWave controller wants access to the units that are assigned to that interface and isn’t interested in units assigned to your Phillips hue hub. Such units belong to a specific interface and you can control them by sending their Address and Address Prefix (tag). Units or Global Scripts that are shared to you should instead be targeted by their unique id and not their address.

The xt.uKeyUniqueId is guarenteed to be present in every update frame for a Unit or a Global Script so that you can find the previous data structure and merge them together.

XTension version 9.4.12 added another section to the websocket data with a key of “removed” if a shared object is deleted in XTension or just removed from a list that is shared you will receive an array of the removed objects in this manner. The “removed” array is a list of json objects with 2 keys in them. The first is “type” which is the name of the shared object to be removed, as of this writing “unit”, “script” or “list” and then the “UniqueId” key which has the unique id of the removed object. It is up to your implementation to remove the object from any saved arrays of available shared objects as XTension will no longer accept commands for that unit.