Differences

This shows you the differences between two versions of the page.

--- supported_hardware:websocket [2018/08/20 19:01] – created James Sentman
+++ supported_hardware:websocket [2023/02/13 14:52] (current) – external edit 127.0.0.1
@@ Line 3: / Line 3: @@
 **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. At the moment this is more geared towards sharing a portion or all of your database with something else and not for creating an interface that creates units in XTension though that will be possible too it’s not implemented fully in this version of the plugin.
+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 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.
+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.
@@ Line 11: / Line 11: @@
 ====Talking To XTension====
-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 that are shared with this interface.
+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 other than direct unit commands, which aren’t supported in the first alpha anyway, will be a JSON object. Inside that JSON object will be arrays containing descriptions of different system objects. As of this alpha only units are sent but global scripts will be added in the near future as well followed by the other objects that XTension creates. The key for the array of units is just “units”. Even if this is an update for just a single unit it will still be contained in the units array.
+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.
@@ Line 22: / Line 22: @@
          { a unit record...},
          { another unit record...},
+         { and so forth}
+    ],
+    “scripts”:[
+         { a global script record...},
+         { another script record...}
          { and so forth}
     ]
@@ Line 38: / Line 43: @@
 </code>
-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. The
+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.
+====The XTension Unit Record====
+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.
+===Addressing Units===
+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.
+===Deleting Units===
+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.