Mac Home Automation

It is not required that a plugin implement any Unit definitions. If this is left out then you will not be able to create any Units associated with the plugin instance. If this is present then when creating a new Unit and assigning the new unit to this plugin instance these unit types will be available in the edit unit window to select from. This is also where you would include any custom interfaces for the specific Edit Unit window or the 2 different sizes of specific control windows.

The deviceTypes block is a list of json dictionaries each with the keys necessary to describe a kind of Unit the plugin will use.

An example of what a unit definition block in the info.json file might look like:

“deviceTypes”:[
    {“name”:”Mantle Heating Element”, 
      “tag”:”jamie.chemcontrol.heater1”, 
      “info”:”shows the state of the heater and allows for manual control"
    },
    {“name”:”separator”},
    {“name”:”Mantle Temperature Setpoint”, 
      “tag”:”jamie.chemcontrol.setpoint”, 
      “info”:”The goal temperature of the mantle”, 
      “dimmable”:true,
      “suffix”:”°”,
      “format”:”#.##”.
       "editControls":[
         {"type":"groupbox","text":"Temperature:","bounds":[0,0,547,211]},
         {"key":"","type":"label","text":"Temperature Format:","align":"left","bounds":[20,36,138,20]},
         {"type":"popup","key":"xt.tempformat","action":"",
           "options":[["°F","f",true],["°C","c"]],
           "bounds":[170,35,80,20]
          }
        ]
     },
    {“name”:”Current Mantle Temperature”, 
      “tag”:”jamie.chemcontrol.temp”, 
      “info”:”the current measured temperature”,
      “dimmable”:true, 
      “receiveonly”:true, 
      “ignoreclicks”:true, 
      “hasQuery”:true,
      “suffix”:”°”,
      “format”:”#.##"
     }
]

This defines 3 Units each with a unique tag which is required and used internally for indexing and re-assigning this unit type popup and controlling which unit subclass you create in your plugin and so forth.

name String - The name of this type of Unit. This is how the user will select the unit type from the popup when creating a new unit and how it will be displayed in the device type field of the unit list windows.

“name”:”Mantle Heating Element, Stage 1”,

tag String - The unique “tag” for this unit type. These must be unique in the entirty of XTension. This is the same idea as the tag that is required in the root level of the info.json file that is unique for this plugin. XTension reserves all tags starting with “xt.” it is recommended to use something like a path that has your name or company, the plugin device and then something that describes the unit. There is no length restriction on the tag but don’t get too creative. They do not necessarily need to be human readable with full sentences just something so that when debugging you can look at this value and know what it is.

“tag”:”jamie.chemcontrol.heater”,

info String - A short description also displayed when the unit type is selected in the Edit Unit dialog. This space is not dynamically sized so your description will get cut off if too long.

“info”:”Controls the state of the heater”,

These keys are not required and are not permanent for the Unit. They can be edited at any time by the user or set programattically from your plugin. These settings offer a default setup for the Unit when created by the User. If you create them automatically from inside your plugin you still need to include the appropriate keys for the behavior you wish.

dimmable Boolean - defaults to false. With this set to true the Unit will be “dimmable” or just able to hold a numerical value. Without this the Unit will be discrete just being able to be turned on or off. Corresponds to the checkbox of the same name.

“dimmable”:true,

receiveonly Boolean - (note all lower case) defaults to false, if set to true then when the Unit is controlled in XTension it will not send any command to the plugin. This does not stop the user from controlling the Unit in XTension it just will not send any commands if you do. Corresponds to the checkbox of the same name on the Edit Unit dialog.

“receiveonly”:true,

ignoreclicks Boolean - (note all lower case) defaults to false. If this is set to true then the Unit’s interface will not easily allow the control of the Unit. For example the default control of a toggle control in list windows will just display the current value or on label rather than offer a control. The Unit may still be controlled through the advanced control windows or via a script. Usually you will want to combine both the receiveonly and ignoreclicks keys. Corresponds to the checkbox of the same name on the Edit Unit dialog.

“ignoreclicks”:true,

useMinMax Boolean - Sets or clears the checkbox of the same name in the Edit Unit dialog. Setting it to true enables the min and max values edit fields in the Advanced tab of the Edit Unit Dialog. Defaults to false. If a Unit receives a value or is controlled by the User or a script to a value over the max the max of the Unit will be set to the Max. if sending a command due to user or script action for a value above the max, only the max value will be sent, the same action is taken for the min value.

“useMinMax”:true,

min float - The value that will be filled into the Min value field if useMinMax is turned on. Defaults to 0.

“min”:15,

max float - The value that will be filled into the Max value field if useMinMax is turned on. Defaults to 100.

“max”: 275,

format String - The default value that will be inserted into the Format field in the Edit Unit dialog.

“format”:”#.##”,

suffix String - The default value that will be inserted into the suffix field on the display tab of the Edit Unit dialog.

“suffix”:”°F”,

allowColor Boolean - Defaults to false, if set to true then the standard color and color preset controls will be displayed for the Unit. May be combined with the allowColorTemp key below. Note that this setting cannot be changed by the User. There is no per-unit interface to this setting.

“allowColor”:true,

allowColorTemp Boolean - Defaults to false. If set to true then the standard color temperature and color preset controls will be displayed for the Unit. May be combined with the allowColor setting. Note that this setting cannot be changed by the user. There is no interface offered for this.

“allowColorTemp”:true,

There is a dimmable type popup for every dimmable unit that has options you can preset in the Unit definition section of the info.json file. The user can change this manually if they wish to. There are 3 valid settings: simple, simulated and smart. These are somewhat historical but can still have valid uses for modern units as they change the turn on behavior.

In general setting a unit to “dimmable” just means that it can accept a floating point value as opposed to a boolean value of on or off for a “discrete” or non-dimmable unit. For receive only devices like say a temperature sensor they should be set to dimmable but this setting would not matter as you do not send updates to a temperature sensor.

This also does not affect devices that never get sent an On command. For example an HVAC cooling setpoint makes no sense to send it an ON command so this setting will not affect it as this only changes the On command behavior and not the set value behavior which is what you would use for something like a thermostat.

In this case an ON command sends an On command to the plugin without any preset value or dim level or any other information. It assumes the device that has been sent the command will go to 100% and the value of the Unit in XTension will be set to 100% upon getting an ON through user interface or a script.

The name is historical but the functionality is what most modern devices would expect. In this case XTension will keep track of the last value that it sent to the Unit and saves that as it’s preset value. When it next wants to send an On command it will also include this last preset value and assume the physical device that was controlled has returned to the last value it set. it’s up to the plugin to make use of the Value property of the On command and make sure this works properly or not. The last set color, color temperature and color mode are also sent in an On command. This should be the default of almost every lighting Unit.

This is entirely historical and should only be used if this behavior makes sense. This is from the age old time when some X10 devices were “smart” meaning that they would remember their last set value and return to that upon receiving an On command. If a Unit is set to this then when you tell it to turn on the value will NOT be included in the On command and XTension will assume the value of the unit has returned to what it remembers in it’s database as the preset value.

dimmableType Enumerated String - must be one of the following types: “simple”, “simulated” or “smart”

“dimmableType”:”simulated”,