Mac Home Automation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
=====Global Cache iTach Devices=====

The iTach plugin is currently in an Alpha state meaning that it is both mostly untested and is not feature complete. Please experiment and make suggestions or report problems.

The iTach plugin provides communication with the [[https://www.globalcache.com/products/itach/models2/|Global Cache iTach devices.]] The main purpose for this plugin is to provide a link between their IR sending devices and Units in XTension though you can use the same system below to also control their relay output devices and when the plugin is complete and promoted out of alpha and beta testing it will also support receiving changes from their various sensor input systems as well.

====XTension Setup====


Create a new Interface and select the Global Cache iTach Plugin from the Device popup.

{{:supported_hardware:itach_setup.png?550 |}}
\\
Enter the IP address or mdns name of your Global Cache device. I would recommended that you assign such devices a static IP either through their own configuration or via a DHCP reservation in your router as this may avoid confusion later on but it is not strictly necessary. The default port for the control connection to a Global Cache device is 4998.\\
\\
**Use Persistent Connection:**\\
If you have a recent Global Cache device you can keep the connection open all the time which results in slightly faster response. Older devices supported only a single remote connection and so in order to be able to use other apps to send IR codes the XTension plugin must not try to keep the connection open all the time.\\
\\
**Non-persistent timeout:**\\
How long in seconds to keep the connection open after sending a command. You may send several commands in a row and building up and tearing down the connection between each one is unnecessary. This is how long after the last command is sent before the connection is dropped. The default is 3 seconds. This way we can wait for the response from the device and check for errors or other information.


====The XTension “Raw Command” Unit====
As of this first Alpha release the plugin supports only a single Unit type, the **Raw Command Unit**. This unit is not specific to any type of input or output in the Global Cache devices but rather provides a list where you can add any number of command to be sent to the device when the Unit is controlled. This is generic enough that you can both send IR commands or control relays or other end points on their devices with it. There will ultimately be devices specifically to represent IR commands and others but for the moment this is whats available.

You can create any number of Units linked to the plugin. Unlike most XTension Units it is not necessary to set the Address field. Leave the field blank and XTension will fill in the Address with a unique address generated during the save. Other basic Unit settings are identical to any other Unit.

{{ :supported_hardware:itach_raw_unit_settings.png?550 |}}

The controls specific to the Global Cache device are a field into which you can enter a list of any number of standard [[https://www.globalcache.com/files/01-2020/API-GC-TCP_1.0.pdf|Global Cache TCP API Commands]] That document and their website contains much information about the formatting of the commands.\\ Place each command on a separate line. While they all will go to the same physical device they could be routed to different modules on the device or perform completely different functions. There is no need for them all to be IR commands or all relay commands. Since the commands are not post processed to be specifically for any kind of Global Cache device you must include the complete command including the command such as sendir and the module number and such as shown in the Global Cache documentation above. It is not necessary to worry about the trailing return, that will be added automatically. Future versions may include Unit types specifically setup for IR Codes or others that will simplify the command generation. This unit is “raw” and will simply send what you enter into the fields.\\
\\
**Value Tag:** If you make the unit in XTension dimmable then you can also insert the “<value>” tag into the commands which will be replaced by the future value of the unit when being controlled. In the case of a non-dimmable unit the value would be 0 or 100 depending on the on or off state. I’m not sure initially if this will be of any use. I was imagining it as providing a way to send specific codes to go to a specific volume level if the device supports it for example but the formatting of the commands do not seem to lend themselves to just including such a thing. If there is a way to make this more useful that is obvious to those more familiar with the devices than I am please let me know.\\
\\
Beyond the <value> tag you can use the [[dictionary:xtension:senddata|Send Data]] verb in the Unit’s on and off script to send custom formatted commands based on the value or other information at the time the command goes out. See the discussion below of the use of the [[dictionary:xtension:senddata|Send Data]] verb. If you wish to handle the creation of the command yourself you can leave the on or off command fields above blank and then no action will be taken automatically, it will be up to use to format and send the commands in the Unit Scripts.
\\
**Delay command”** There is one other command you can include in the lists to create a **delay** if there must be a delay between sending one command and the device being ready to accept the next one you can include this command to create that. For instance when turning on a device it may be necessary to wait a certain amount of time before it will be ready to accept an input selection or volume setting.\\
\\
The delay command must be on a separate line and has the format of:\\
<code>
delay=milliseconds
</code>
so to delay for 2 seconds you would add a line that says:\\
<code>
delay=2000
</code>

**Test Buttons:**

The interface also provides a test button for the On and Off list of commands. If the interface is running these will be enabled and will send the commands that are entered into the fields above to make it easier to test and iterate until you get things working properly. This way you do not have to continually save or apply the changes to the unit and control it as you setup more complicated commands. These buttons are only available if the interface is enabled.

====Sending Commands from the Scripts====
The Global Cache plugin implements the [[dictionary:xtension:senddata|Send Data]] verb identically to how it is implemented in the [[supported_hardware:diy|DIY]] plugin. Any text data you send via the Send Data verb will be sent to the device exactly as you enter it. No assumptions about when the command ends are made in the processing of the verb so you must add your own return character at the end of the command. In applescript it would look something like:
<code>
send data "sendir,1:2,1,38000,1,1,347,174,21,21BBBBBBB,21,65CCCCCCCBBBBBBCBCCCCCCBC,21,1572,347,87,21,3708” & (return)
</code>

or
<code>
send data "sendir,1:2,1,38000,1,1,347,174,21,21BBBBBBB,21,65CCCCCCCBBBBBBCBCCCCCCBC,21,1572,347,87,21,3708” & (ASCII Character 13)
</code>

it is not necessary to send the entire command in a single Send Data command. Since it is not automatically adding the carriage return at the end you can build a command from several send data commands in the code, or build a string that contains the entire command and send it just once.

If you are running the send data command from inside the Raw Command Unit’s on or off script it is not necessary to supply the **interface** parameter of the Send Data verb as that will be implied by the fact that the Unit is assigned to that interface. You can use the send data verb from any Global Script or other script but in that case it will be necessary to supply the plugin interface name to which you wish to send the command:

<code>
send data “sendir...” interface “name of the plugin interface”
</code>

====Error Handling and Replies From the Device:====
As of this moment error handling is rudimentary and will not retry or otherwise attempt to fix the problem. Errors are written to the XTension log as they are received and the error code is translated into the more user readable version but are otherwise not processed.

Non error replies from the device are not written to the log unless you turn on debug mode for the plugin interface. When in debug mode all communications to and from the device are logged to the XTension log so you can see exactly what is happening.

===The IR Busy Error:===
There is a special class of error sent when one connection tries to send a command while another connection is using the port. Ultimately I believe the appropriate handling of this error will be to pause and retry until the port is available. In this alpha version this error does not trigger a retry or any error hook into the code but is logged to the XTension log. If you have thoughts on the proper handling of this situation please let me know. When the plugin is promoted to a release version we will know how to properly deal with this potential situation.

===Non Persistent Connection Errors:===
If you are using an older device that supports only a single connection it is possible that you will hit an error when attempting to connect to send a command as some other remote control may be connected to it. At this moment the plugin will retry the connection for up to 10 seconds before giving up and logging an error. If the connection can be made during those 10 seconds the commands will then be sent, if not then there is not yet any further retry, the commands will not be sent. If this is not sufficient or if you have other thoughts on the proper handling of this situation please let me know. There should be no problem connecting to more recent devices to send commands as they support up to 10 simultaneous connections.

===Managing Other Connection or Network Errors:===
If a persistent connection is dropped due to a network error or a power cycle or reset of the Global Cache device it will remain in an error state in the Interface list in XTension until the next time a command is sent to the device. Every time a command is sent the state of the connection is checked and if it is not open the connection is re-opened. It is not necessary to recycle the XTension plugin interface if you reset the device, it will reconnect when you next attempt to send a command. 


====History:====
  * The Global Cache plugin first appeared in it’s initial Alpha release in XTension 9.4.31 in June of 2020.
Mac Home Automation

User Tools

Site Tools

Page Tools
