Differences

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

--- plugins:03_units [2017/07/14 15:40]
127.0.0.1 external edit
+++ plugins:03_units [2019/01/20 15:18] (current)
James Sentman added dimmable, dimmableType, receiveOnly and ignore clicks default info
@@ Line 4: / Line 4: @@
 It is important to understand the address space issues with different devices. Each unit in the XTension database must have a unique address path. This is made up from the unique ID of the interface instance, the address prefix which is the unique string you will define in the “tag” property for each unit type you define and then the address which is what the user enters into the Address field. \\
 \\
-A good example is to think about X10 wireless devices and our [[supported_hardware:w800|W800]] interface. There are 2 types of X10 wireless devices, “wireless” and “security” but they both have the same address space. Without being able to tell XTension which type was which the 2 address spaces would overlap in our index making it impossible to have both a wireless and a security device at address B1 for instance. With an address prefix tag defined we can have both a wireless and a security device at the same Address because the tag is different.\\
+A good example is to think about X10 wireless devices and our [[supported_hardware:w800|W800]] interface. There are 2 types of X10 wireless devices, “wireless” and “security” but they both have the same address space. Without being able to tell XTension which type was which the 2 address spaces would overlap in our index making it impossible to have both a wireless and a security device at address B1. With an address prefix tag defined we can have both a wireless and a security device at the same Address because the tag is different.\\
 \\
 When commands are sent to the plugin they will include both the address and the tag associated with the device type so that you can take the proper action. Commands received by you and sent up to XTension must include both the device type tag and the address so that the proper unit to receive the command can be found.\\
@@ Line 12: / Line 12: @@
 The device types are a JSON list containing multiple JSON dictionaries for each device type you’re setting up.
-==deviceTypes==
+====deviceTypes====
-Required: (json list) a list of the JSON data describing at least one unit device type
+Required: (json list) a list of the JSON data describing any unit types. If your plugin does not define any unit types say for a sharing only plugin then the list must be included but can be empty. Any plugin that provides a unit must include at least one unit type even if it’s just a generic “Register” so that the unit type plugin has something that can be selected and there is a unique address tag.
 <code>
@@ Line 22: / Line 22: @@
 ]
 </code>
+====Device Type Keys====
-===Device Type Keys===
 Each device type dictionary may use the following keys to describe it’s behavior and interface:
-==name==
+===name===
-REQUIRED: (string) the name of the device.
+REQUIRED: (string) the name of the device as displayed in the device type popup of the Edit Unit dialog.
-==tag==
+===tag===
 REQUIRED: (string) the short unique address prefix used to guarantee each device type  it's own address space. Also used by the plugin to send the proper command for that device  type regardless of the address.
-==desc==
+===desc===
 OPTIONAL: (string) a more descriptive string about the device to be displayed in the  edit unit dialog if present.
-==allowColor==
+===allowColor===
 OPTIONAL: (boolean) defaults to false. If present and True the color controls will be  offered when controlling this unit and color data will be sent with all the on and  value commands.
-==allowColorTemp==
+===allowColorTemp===
 OPTIONAL: (boolean) defaults to false. If present and True the color temperature controls   will be offered when controlling this unit and color temperature data will be sent with  all the on and value commands. NOTE: this is not yet implemented in XTension 9.3.1
-==address==
+===address===
 OPTIONAL: (JSON list of strings or lists, see below) if your device has a reasonably limited  number of potential device addresses you can include them here. When the "..." button next  to the address field is clicked a menu will be opened to select from this list. The simplest  form is just a list of strings:
@@ Line 73: / Line 72: @@
 The user can always enter anything into the address field that they wish, choosing from the menu is a shortcut for simple devices and not a requirement that the entire address space be included in it to choose from.
-==menuHandlers==
+===dimmable===
+OPTIONAL: (boolean) Set to true if this unit type should default to dimmable when the user is creating new units.
+<code>
+“dimmable”:true
+</code>
+===dimmableType===
+OPTIONAL: (string) a string describing the dimming behavior when the ON command is sent. The valid choices are “simple”, “smart” and “simulated”. Most modern units should be set to “simulated” This only applies to units with the dimmable flag set to true.
+  * simulated: in this case the last value the unit visited will be remembered by XTension and sent as a set value command instead of an On command. This is the normal behavior for most modern devices as you want them to return to the level they were last at when they are commanded On. A unit set to simulate will never receive an On command, but only setValue commands with the last On level already set from the XTension database.
+  * smart: legacy type for “smart” x10 devices. This will send a simple On command and assume the device itself knows what level to go to. This seems like it would be the choice for modern devices as most do remember their own last on level but it isn’t the best choice as the value in the XTension database may not match what the device does.
+  * simple: XTension will just send a simple On to the device when commanded on and the database will show a level of 100% after sending the on. This is a legacy setting for “dumb” devices that always go to full on when sent an On command.
+<code>
+“dimmableType”:”simulated”
+</code>
+===receiveOnly===
+OPTIONAL: (boolean) If the unit can only receive values but should not get commands when the values are changed in XTension this flag should be set to true. For things like analog inputs or temperature sensors that can only receive values and for whom it makes no sense to try to send a new value to.
+<code>
+“receiveOnly”:true
+</code>
+===ignoreClicks===
+OPTIONAL: (boolean) serves the dual purpose of making it harder to accidentally click on a control in the interface and changing the look of that interface. When set to false or absent a unit will provide by default a toggle control on a unit list. When set to true the paddle of that and all other control toggles will be absent so that you can’t click on it and the toggle background will instead just show the current value. Clicks on the toggle control will not cause any commands to be sent immediately but will instead bring up the detailed controls dialog. From there, or from scripts or events or other ways to control a unit the commands will be sent normally.
+This should also be set to true for most receiveOnly units as you do not normally wish to provide a simple interface for controlling something when it cannot be controlled.
+<code>
+“ignoreClicks”:true
+</code>
+===menuHandlers===
 OPTIONAL: (JSON List of lists) Sometimes a device may have other control commands that are not yet included in the applescript dictionary, or for which you'd like to present a simple interface to. Commands entered in this list will show at the top of the contextual menu for the item and also when the gear icon is clicked in either of the popup unit control windows. The value is a JSON list of lists, each embedded list should start with the display name you wish to have in the menu, followed by the actual command name that you want to have called in the script when the menu handler is selected. An optional 3rd entry may be included which will be passed to the script handler in the scriptData parameter as a tuple.
@@ Line 83: / Line 115: @@
 </code>
-would add 2 menu entries "Start Color Loop" and "End Color Loop" and if selected in any  of the interfaces they will cause handlers in your script called "startColorLoop" or "endColorLoop" to be run. There will be 2 values passed to the script along with  the call. In Python the example might be:
+would add 2 menu entries "Start Color Loop" and "End Color Loop" and if selected a doScriptHandler command will be sent to the plugin. If you have registerd a handler for the handler name “startcolorLoop” then that handler will be called. You can create handlers either in the xtUnit objects or at the xtension level to have a single handler called regardless of the unit that was selected. See the using the plugin includes section for more info on registering callback handlers.
+A script handler must have the following definition:
 <code>
-def startColorLoop( unitData, scriptData):
+def startColorLoop( self, commandName, positionalParms, dataParms):
 </code>
-If the optional 3rd entry is included then the scriptData will contain that list, if not it will be an empty list.
+The commandName will be the handler name, in this case “startColorLoop” which does not have the be the same name as the actual handler since you can register any handler using that name as a key.
-unitData is a python dictionary and will contain at least 3 entries so you can find the unit for which the command was requested and perform whatever necessary actions. The available keys in the unitData dictionary will be:
+If the third list of values was present in the menuHandlers definition then the positionalParms will contain a tuple containing them. [14, 55, 75] in the above example.
+The dataParms will include much more information including units address, tag, uniqueid and any other interface information available at the time of the call. It will contain at least these keys:
 <code>
@@ Line 102: / Line 138: @@
 if this info isn't enough to send the command to the device you can use them via the XTGetUnitFromAddress or XTGetUnitFromId commands to get the entire dictionary of unit settings for the unit.
-==scriptHandlers==
+===scriptHandlers===
-OPTIONAL: (JSON list of strings) You can further extend the scripting interface to the unit by listing special commands that can be called from scripting here.
+OPTIONAL: (JSON list of strings) You can further extend the scripting interface to the unit by listing special commands that can be called from scripting here. Note that in AppleScript it’s not actually necessary to define these here. Any script handler invoked by a user script that isn’t found as a command or handled by another script in the calling chain in XTension will be forwarded to the plugin. It may be added at some point in the future to validate these or to provide a type ahead interface to what is known to be available for that unit so you should supply them whenever possible.
 <code>
@@ Line 115: / Line 151: @@
 </code>
-The format for the python script command will be the same as the menuHandlers above but in this case the scriptData parameter will be filled in with a tuple containing the  positional parameters passed to the command.
+The script handler is registered and executed in the same way as the above Menu Handler is. If any parameters are passed to the call they will be included in the positionalParms tuple but only parameters that can be coerced to strings will be forwarded on and all the parameters you receive will be in the form of strings. Complex structures like lists or records or object references cannot be passed to a plugin.
 <code>
-def startColorLoop( unitData, scriptData):
+def startColorLoop( self, commandName, positionalParms, dataParms):
 </code>
-unitData will again be a dictionary with the keys xtKeyAddress, xtKeyTag and xtKeyUniqueId\\
+the command name is also supplied in case you might wish to supply a single callback handler for multiple scripting calls.
+the dataParms would again have all the same data as is listed in the above menuHandler section.
 \\
-scriptData would be a python tuple of ["14", "55", "75"] note that data is always passed as strings even if it's entered to the script as numbers. You may have to convert the data if using it as numbers.\\
 \\
-NOTE: AppleScript does not actually require that I pre-define these handlers. Any tell xUnit command that is not a built in command or handled by the ON or OFF script in an  AppleScript handler will be passed to your script. So it's not technically necessary to include this to include the functionality. However, when XTension implements other scripting languages in the future in addition to AppleScript it will be necessary for me to pre-define the commands you wish to use. You should include this information now regardless.
+In the next section we will review the creation of dynamic interfaces and using them for the edit interface window, the edit unit window and the 2 unit control dialogs.
 \\
 \\
 PREVIOUS: [[:plugins:02_infojson|]] NEXT: [[:plugins:04_interfaces|]]

Mac Home Automation

User Tools

Site Tools

Differences

Page Tools