Mac Home Automation

The info.json file must also contain at least one unit type definition but may contain any number of extra unit types that your plugin can support. These unit types are the selections in the “Device” popup on the Edit Unit dialog. A single interface may support several different types of physical devices with different interface and addressing requirements.

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 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.

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.

In addition to the tags below you may specify 2 different dynamic interfaces for each device type. See the next section on interface setup for more info.

The device types are a JSON list containing multiple JSON dictionaries for each device type you’re setting up.

Required: (json list) a list of the JSON data describing at least one unit device type

deviceTypes:[
	{"name":"digital output", "tag":"out", "desc":"GPIO outputs on pins 1-7"}
	{"name":"motor speed", "tag":"speed"}
	{"name":"Alert LED", "tag":"alert", "allowColor":True}
]

Each device type dictionary may use the following keys to describe it’s behavior and interface:

REQUIRED: (string) the name of the device.

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.

OPTIONAL: (string) a more descriptive string about the device to be displayed in the edit unit dialog if present.

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.

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

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:

address:["1", "2", "3”]

any of those strings can be another JSON list which allows you to include a description of the device or function of that address. The first item should be a string that is the address that will be filled into the address field, the second item is a string that is the description. In the popup menu the address will be included in parans followed by the description.

You can combine both individual string elements and list elements.

address:[
   ["1", "PWM Channel 1"],
   ["2", "PWM Channel 2"],
   ["RATE", "Ramp Rate"],
  "3", 
   “4"
]

would result in a menu that looked like:

(1) PWM Channel 1
(2) PWM Channel 2
(RATE) Ramp Rate
3
4

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.

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.

menuHandlers:[
	["Start Color Loop", "startColorLoop", [14, 55, 75]],
	["End Color Loop", "endColorLoop"]
]

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:

def startColorLoop( unitData, scriptData):

If the optional 3rd entry is included then the scriptData will contain that list, if not it will be an empty list.

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:

xtKeyAddress 		("addr") 	The address of the unit
xtKeyTag		("APfx")	The tag or address prefix of the unit
xtKeyUniqueID		("UnID")	The unique ID string of the unit.
xtKeyValue		(“Valu”)	The current value of the unit.

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.

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.

scriptHandlers:[ "startColorLoop", "endColorLoop", "colorFlash", "setColorLoopSpeed”]

after defining them they can be called from any AppleScript in the application for the unit and will allow any number of parameters to be entered and passed such as:

tell xUnit "name of unit" to startColorLoop( 14, 55, 75) 

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.

def startColorLoop( unitData, scriptData):

unitData will again be a dictionary with the keys xtKeyAddress, xtKeyTag and xtKeyUniqueId

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.

PREVIOUS: Plugin API: info.json and Communication Settings NEXT: Plugin API: Dynamic Interfaces