plugins:03_units
Differences
This shows you the differences between two versions of the page.
Next revision | Previous revisionNext revisionBoth sides next revision | ||
plugins:03_units [2017/07/14 15:40] – external edit 127.0.0.1 | plugins:03_units [2019/01/20 15:06] – [deviceTypes] James Sentman | ||
---|---|---|---|
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. \\ | 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: | + | A good example is to think about X10 wireless devices and our [[supported_hardware: |
\\ | \\ | ||
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.\\ | 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. | 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 | + | Required: (json list) a list of the JSON data describing |
< | < | ||
Line 22: | Line 22: | ||
] | ] | ||
</ | </ | ||
- | + | ====Device Type Keys==== | |
- | ===Device Type Keys=== | + | |
Each device type dictionary may use the following keys to describe it’s behavior and interface: | 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 |
- | ==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 | 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 | ||
- | ==desc== | + | ===desc=== |
OPTIONAL: (string) a more descriptive string about the device to be displayed in the edit unit dialog if present. | 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. | 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 | OPTIONAL: (boolean) defaults to false. If present and True the color temperature controls | ||
- | ==address== | + | ===address=== |
OPTIONAL: (JSON list of strings or lists, see below) if your device has a reasonably limited | OPTIONAL: (JSON list of strings or lists, see below) if your device has a reasonably limited | ||
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. | 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== | + | ===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. | 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 82: | ||
</ | </ | ||
- | would add 2 menu entries "Start Color Loop" and "End Color Loop" and if selected | + | would add 2 menu entries "Start Color Loop" and "End Color Loop" and if selected |
+ | |||
+ | A script handler must have the following definition: | ||
< | < | ||
- | def startColorLoop( | + | def startColorLoop( |
</ | </ | ||
- | + | ||
- | If the optional 3rd entry is included | + | 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 | + | If the third list of values was present in the menuHandlers definition |
+ | |||
+ | The dataParms | ||
< | < | ||
Line 102: | Line 105: | ||
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. | 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. |
< | < | ||
Line 115: | Line 118: | ||
</ | </ | ||
- | The format for the python | + | The script |
< | < | ||
- | def startColorLoop( | + | def startColorLoop( |
</ | </ | ||
- | + | ||
- | unitData will again be a dictionary with the keys xtKeyAddress, | + | the command name is also supplied in case you might wish to supply |
+ | |||
+ | the dataParms would again have all the same data as is listed in the above menuHandler section. | ||
\\ | \\ | ||
- | scriptData would be a python tuple of [" | ||
\\ | \\ | ||
- | 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 | + | In the next section we will review |
\\ | \\ | ||
\\ | \\ | ||
PREVIOUS: [[: | PREVIOUS: [[: |