iTach API Specification Version 1.

5
1. The iTach Modular Design Concept
The iTach family of products' modular design provides a variety of capabilities. Each module provides a particular function: power and network connections, infrared (I !, digital input ( "#$#!, and contact closures (relay!. % module may also support one or more connectors of the same type. &or e'ample, an I module has three independent I connectors( whereas, a serial module has only one serial "#$# connector. This is due to the fact that the number of connectors a module can support is dictated by its ).* inch physical width. It is important to understand that a module+s address is determined solely by its physical position within the iTach enclosure. Each module occupies ).* inches of front panel space, even if it is part of a larger product. %t power on, module addresses are assigned starting with ,-, for the left.most module (containing the network and power connectors! and increasing se/uentially to the right until all module addresses are assigned (see figure!. This presents a consistent programming interface as additional modules are added. % connector's address is its position within a module, starting at ) on the left, and increasing se/uentially as you move to the right. % complete connector address includes the module address and the connector location in the module, separated by a colon. In figure ) below, one I module is contained in the iTach I0#I , and is located in module ). The first I connector on the I module has an address of ):), whereas the third I connector has an address of ):$. Note: In iTach units containing infrared (I ! and relay contact closure (11! modules, those modules are always physically located in module ) ():2!. 3owever, modules ) through $ will be accepted in commands to the I , and ) through * will be accepted by the 11. This is deliberate and allows drivers developed for the 41.)-- 5etwork %dapter series of products to function without change. !a"ple: 6oth of the following commands will set the first relay to closed: setstate,):),) setstate,*:),) I# Connectors: "upport for an I blaster is enabled on the third (2:$! I connector on an I module. This can be configured via command, or must be selected on the web site. %ttempts to configure connectors other than 2:$ as an I blaster will result in a returned error message.
1:1 1:3

correct module number ():2! incorrect module but is an accepted, functional command

Module 0 &igure )
iTach API Specification Effective A!"!st #5, #011 P( 100)15*01 ver+ 1+5 ) of )7

Module 1

160 East California Street, PO Box 1659 $ac%sonville, Ore"on 9&5'0 Phone 5)1*,99*),00 -ax 5)1*,99*),0, ...+"lo/alcache+co0
Infor0ation s!/1ect to chan"e .itho!t notice+

iTach API Specification Version 1.5

$. Configure the IP Address
The 8i&i connected iTach web server+s default address is http:99)7:.#*;.).<-, when in adhoc mode. =n the Net%or& settings page, either enable >310 (for automatic I0 allocation!, or designate a static I0 address. The T109I0 connected iTach is set by default to use >310 to automatically obtain an I0 address from the router. To determine the I0 address of an iTach using >310, run the i3elp ?tility found at www.globalcache.com9downloads. 8ithin $- seconds of power up, the iTach will announce its model type, I0 address, and @%1 I> via a network wide beacon broadcast, which i3elp displays. The iTach will also periodically announce its I0 address at intervals between )- and 7- seconds while powered up to maintain up.to.date i3elp display information. The i3elp display may be refreshed from the Vie% tab option.

'. Disco(er) *eacon

The iTach features a beacon message that can assist in locating iTach units on the network. The beacon is a ?>0 packet sent to the multicast I0 address #$:.#**.#*-.#*- on ?>0 port number :)$). %ny system listening to this address and port will receive the periodic beacon message. The message is sent shortly after power on and then at random intervals of )- to 7- seconds thereafter. The beacon message has the following format: %@A6B.??I>C4lobal1acheD---1)E-#;#$:EB.">F1lassC?tilityE B.@akeC4lobal1acheEB.@odelCiTach8&#I EB. evisionC<)-.)--).-*E B.0kgDGevelC410F--)EB.1onfig.? GChttp:99):#.)7H.).)--.EB.016D05C-#*.--#7.-7E B."tatusC eadyE The ??I> value contains the uni/ue @%1 address of the iTach which is also the name registered with the >310 server (printed as 4lobal1acheDI@%1J!. The @odel value, at this time, will be one of the following: iTachI0#I iTach8&#I iTachI0#"G iTach8&#"G iTachI0#11 iTach8&#11 Ethernet (I0! to infrared (I ! 8i&i to infrared Ethernet (I0! to serial ( "#$#! 8i&i to serial Ethernet (I0! to contact closure (relay! 8i&i to contact closure K;* )--9)- @bit9s connection, and 8i&i is a standard

Ethernet (T109I0! communicates by way of an H-#.))b wireless interface.

+. Co""and and Data Structure

1ommunication with the iTach is accomplished by opening a T10 socket on 0ort ;::H. %ll commands and data, with the e'ception of serial ( "#$#! data, are communicated through 0ort ;::H. 0ort ;::H is
iTach API Specification Effective A!"!st #5, #011 P( 100)15*01 ver+ 1+5 # of )7 160 East California Street, PO Box 1659 $ac%sonville, Ore"on 9&5'0 Phone 5)1*,99*),00 -ax 5)1*,99*),0, ...+"lo/alcache+co0
Infor0ation s!/1ect to chan"e .itho!t notice+

iTach API Specification Version 1.5

used for such things as iTach status, I data, relay operation, and reading digital input states. %ll information, with the e'ception of serial data, is communicated by comma delimited %"1II te't strings terminated by a carriage return (!. "erial data is communicated via 0orts ;::: and above. The serial connection in module ) will communicate over 0ort ;:::. "erial connections in the ne't lowest module will communicate over 0ort *---, and so on (i.e. ):;:::, #:*---, $:*--), etc.!.

5. Co""and Set
1ommands are initiated by short %"1II string representing the command type. Typically, physical address and data information will follow. The structures of iTach commands are described in the following sections. Te't enclosed in brackets (Bte'tE! must be substituted by its %"1II definition. @ultiple %"1II choices are divided by separator ( L ! characters. Note: 1ommands are case sensitive. !a"ple: The network settings are /ueried with the getD5ET command: getD5ET,BconnectoraddressE where( BconnectoraddressE is -:) (network module address! The command %"1II string sent to the iTach is: getD5ET,-:) Note: getD5ET command is documented fully in section 5.1 below. 5.1 ,eneral Co""ands getde(ices This iTach command is used to determine installed modules and capabilities. Each module responds with its address and type. This process is completed after receiving an endlistdevices response. "ent to iTach: getdevices de(ice "ent from each iTach module in response to getdevices: device,BmoduleaddressE,BmoduletypeE (one sent for each module! where for iTach products( BmoduleaddressE is L-L)L BmoduletypeE is L8I&ILET3E 5ETL$ EG%ML$ I L) "E I%GL %ll modules are included in the response followed by endlistdevices The following are the possible iTachI responses to a getdevices command. device,-,- 8I&Idevice,),$ I endlistdevices device,-,- 8I&Idevice,),) "E I%Gendlistdevices
iTach API Specification Effective A!"!st #5, #011 P( 100)15*01 ver+ 1+5 $ of )7

(/uery for modules and capabilities!

for 8i&i to three infrared for 8i&i to one serial

160 East California Street, PO Box 1659 $ac%sonville, Ore"on 9&5'0 Phone 5)1*,99*),00 -ax 5)1*,99*),0, ...+"lo/alcache+co0
Infor0ation s!/1ect to chan"e .itho!t notice+

iTach API Specification Version 1.5

device,-,- 8I&Idevice,),$ EG%Mendlistdevices device,-,- ET3E 5ETdevice,),$ I endlistdevices device,-,- ET3E 5ETdevice,),) "E I%Gendlistdevices device,-,- ET3E 5ETdevice,),$ EG%Mendlistdevices get(ersion The module version number may be obtained from any or all modules in an iTach. &or backward compatibility with the 41.)--, the previous implementation of getversion has been enabled, and both work functionally. "ent to iTach: getversion "ent from iTach in response to getversion: Bte'tversionstringE where( Bte'tversionstringE is the version number %"1II string "ent to iTach: getversion,BmoduleaddressE where( BmoduleaddressE is L-L)L "ent from iTach in response to getversion: version,BmoduleaddressE,Bte'tversionstringE get-N T This command will retrieve the current network settings and return a comma delimited string with the network settings. "ent to iTach: getD5ET,-:) "ent from iTach in response to getD5ET command: 5ET,-:),BconfiglockE,BipsettingsE,BipaddressE,BsubnetE,BgatewayE where( BconfiglockE LG=1FE>L?5G=1FE>L BipsettingsE L>310L"T%TI1L BipaddressE is the assigned network I0 BsubnetE is the network subnet mask BgatewayE is the default network gateway un&no%nco""and
iTach API Specification Effective A!"!st #5, #011 P( 100)15*01 ver+ 1+5 ; of )7 160 East California Street, PO Box 1659 $ac%sonville, Ore"on 9&5'0 Phone 5)1*,99*),00 -ax 5)1*,99*),0, ...+"lo/alcache+co0
Infor0ation s!/1ect to chan"e .itho!t notice+

for 8i&i to three relays for I0 to three infrared for I0 to one serial for I0 to three relays

iTach API Specification Version 1.5

%n unknowncommand response will be sent by the iTach when a command is not understood. This can happen if, for e'ample, a connector is set up as a digital input and the command re/uested is sendir. "ent from iTach in response to unknown commands: unknowncommand, Ierror codeJ Note: >efinitions are contained in the rror Codes table in section .. 5.$ Serial Connection iTach serial is bi.directional, "#$# communication. %ll communication is H data bits and one stop bit. 0arity, hardware flow control, and baud rate are set through the iTach internal web page or via configuration command, with baud rate enabled up to ))*.# Fbaud. %ll serial data is passed through without interpretation or conversion via an assigned, uni/ue I0 port. The iTach serial connector is assigned to I0 0ort ;:::. If a serial connector is not configured correctly, buffer overflows (indicating data loss!, or parity errors will occur. %ny errors will be captured and presented on the Serial web page to aid in proper setup. "ettings such as "erial @ulticonnection @ode, < data bit mode, or # stop bit mode are only accessible from the "erial web page. 5.$.1 Serial Co""ands set-S #IA/ This command allows for configuration of the iTach serial. "ent to iTach: setD"E I%G,):),BbaudrateE,BflowcontrolE,BparityE where: ):) is the iTach serial connector's address BbaudrateE is L))*#--L*<7--L$H;--L):#--L);;--L:7--L;H--L#;--L)#--L BflowcontrolE is L&G=8D3% >8% EL&G=8D5=5EL BparityE is L0% ITMD5=L0% ITMD=>>L0% ITMDENE5L !a"ple: setD"E I%G,):),$H;--,&G=8D3% >8% E,0% ITMD5= This command string will set the iTach serial connector to operate at $H;-- baud with hardware flow control and no parity.

get-S #IA/ This command will retrieve the current iTach serial settings. getD"E I%G,):)
iTach API Specification Effective A!"!st #5, #011 P( 100)15*01 ver+ 1+5 * of )7 160 East California Street, PO Box 1659 $ac%sonville, Ore"on 9&5'0 Phone 5)1*,99*),00 -ax 5)1*,99*),0, ...+"lo/alcache+co0
Infor0ation s!/1ect to chan"e .itho!t notice+

iTach API Specification Version 1.5

S #IA/ "ent from iTach in response to setD"E I%G and getD"E I%G. "E I%G,):),BbaudrateE,BflowcontrolE,BparityE 5.$.$ #S$'$ Multiple Connection Mode This mode enables four simultaneous T10 sockets to iTach port ;:::. In this mode, each socket can transmit data out the serial connector on a packet.by.packet basis. Each packet received for port ;::: will be transmitted completely before another packet (from the same or different socket! is transmitted out the serial connector. This ensures complete commands can be received and understood by the serially. connected device. The only re/uirement is for each entire command(s! to be sent in one T10 packet. %ll serial data received by the serial connection is transmitted to all =0E5 T10 sockets on port ;:::, allowing each connected application to maintain and update serial device status. This mode can only be enabled or disabled from the Serial settings web page. 5.' #ela) Closure Co""unication iTach relays are activated by sending a B)E state (close contacts!, and deactivated by a B-E state (open contacts!. elay states are not preserved through a power cycle and all relays will go back to their inactive (open! state until a B)E state is restored via command. 5.'.1 #ela) Co""ands setstate elay state is set as follows: setstate,):),BoutputstateE setstate,):#,BoutputstateE setstate,):$,BoutputstateE where( BoutputstateE is L-L)L (B-E is open, B)E is closed! "ent from iTach in response to setstate: state,):)B-L)E for the )st relay state state,):#B-L)E for the #nd relay state state,):$B-L)E for the $rd relay state Note: elay type connectors can be polled for their state with the getstate command (*.;.)!. 5.+ I# Co""ands set-I# for the )st relay output for the #nd relay output for the $rd relay output

iTach API Specification Effective A!"!st #5, #011 P( 100)15*01 ver+ 1+5 7 of )7

160 East California Street, PO Box 1659 $ac%sonville, Ore"on 9&5'0 Phone 5)1*,99*),00 -ax 5)1*,99*),0, ...+"lo/alcache+co0
Infor0ation s!/1ect to chan"e .itho!t notice+

iTach API Specification Version 1.5

This command allows configuration of each I connector to the desired mode of operation. The possible modes are I output, sensor input, sensor notify (see *.;.#!, I blaster, and GE> lighting (see *.;.$!. The I blaster is only supported on the third I connector. "ent to iTach: setDI ,):),BmodeE where: BmodeE is LI L"E5"= L"E5"= D5=TI&MLI D6G%"TE LGE>DGI43TI54L !a"ple: setDI ,):$,GE>DGI43TI54 This will set the third I connector to GE> lighting mode. get-I# This command will retrieve the current mode setting for a designated connector. "ent to iTach: getDI ,):) getDI ,):# getDI ,):$ for the )st I for the #nd I connector connector /uery:

for the $rd I connector

"ent from iTach in response to getDI

I ,):),BI L"E5"= L"E5"= D5=TI&MLI D6G%"TE LGE>DGI43TI54E stopir % stopir command is used to halt I transmission. %ny remaining BrepeatE counts will be discarded. % stopir command sent to a connector configured as an input will return an error message. %n I transmission halted with the stopir command will return a stopir response. &urthermore, if an I command is halted before its completion by another connection, the originating I connection and the connection sending stopir will both receive a stopir response. If stopped, the originating connection will not receive a completeir response. "ent to iTach: stopir,):) stopir,):# stopir,):$ to stop the )st I connector transmission to stop the #nd I to stop the $rd I connector transmission connector transmission

"ent from iTach in response to stopir command: stopir,BconnectoraddressE where( BconnectoraddressE is as defined in stopir command % stopir command always returns a stopir response regardless if the connector is idle or an I transmission is actually halted. % stopir response means only that the stopir command was successfully sent to the iTach, and any transmission has been halted from the designated BconnectoraddressE.
iTach API Specification Effective A!"!st #5, #011 P( 100)15*01 ver+ 1+5 < of )7 160 East California Street, PO Box 1659 $ac%sonville, Ore"on 9&5'0 Phone 5)1*,99*),00 -ax 5)1*,99*),0, ...+"lo/alcache+co0
Infor0ation s!/1ect to chan"e .itho!t notice+

iTach API Specification Version 1.5

0us)I# % busyI response occurs when an I command is received by a connector that is already sending an I transmission. If multiple I0 connections are present (i.e. from multiple i0hone users! there is a possibility of an I transmission not being transmitted. This occurs when an I command is sent to the same I connector from another I0 connection, and will cause a busyI response. % busyI response does not occur if the two I commands are e'ecuted on different I connectors. "ent from iTach in response to an attempt to interrupt I or socket: busyI ,BconnectoraddressE,BI>E where: BconnectoraddressE is the busy connector BI>E is L-L)L#LOL7**$*L (I> is specified in sendir command! Note: The busyI response is returned to the originator of the une'ecuted I command. % command to stopir will only return the stopir response. %t no time will a command of stopir return a response of busyI . 5.+.1 Sensor1#ela) State Co""ands The iTach sends out notifications for digital sensor input state changes as well as allowing the inputs to be polled for their current state at any time. This command can also be used to poll the state of contact closure relays, with a value of B-E representing an open contact, and B)E representing a closed contact. >igital input connectors are the same connectors used for I output on I modules. The connector configuration is determined by the iTach configuration on an individual connector basis. &or the following commands to operate correctly, the connector being addressed must be configured for sensor input or as a sensor notify connector. If a command re/uests information from a connector configured as output rather than input, an unknowncommand response will be sent from the iTach. getstate "ent to iTach: getstate,):) getstate,):# getstate,):$ state "ent from iTach in response to getstate: state,):),BinputstateE for the )st connector state,):#,BinputstateE for the #nd connector state,):$,BinputstateE for the $rd connector where( BinputstateE is L-L)L %n inputstate of B)E represents a high digital voltage level, or absence of an input (no connection! and a B-E represents a low digital voltage level, less than .HN. The iTach sensor input level is held high internally and as such will indicate a B)E with no connection.
iTach API Specification Effective A!"!st #5, #011 P( 100)15*01 ver+ 1+5 H of )7 160 East California Street, PO Box 1659 $ac%sonville, Ore"on 9&5'0 Phone 5)1*,99*),00 -ax 5)1*,99*),0, ...+"lo/alcache+co0
Infor0ation s!/1ect to chan"e .itho!t notice+

transmission by another I0 connection

for the )st "ensor input or elay for the #nd "ensor input or elay for the $rd "ensor input or elay

iTach API Specification Version 1.5

5.+.$ Sensor Notif) iTach I connectors can now be configured as "ensor 5otify. ?se of the setDI command to enable "ensor 5otify status will enable default settings. This will set the ?>0 broadcast port to :)$# with a timer of )- seconds. 1onfiguration of "ensor 5otify parameters (port and timer! must be changed by way of the I# settings web page. There, both the ?>0 port and timer settings can be changed to suit network and software specifications. "ensor notifications are broadcast by way of ?>0 packet, sent in timed increments specified by the web configuration (in seconds!, and also sent when a sensor state changes, notifying anything listening to the specified ?>0 port by way of an immediate network broadcast. If the timer value is set to -, sensor notifications will broadcast only when the sensor state changes. "ensor 5otify ?>0 broadcast packet contents are as follows: sensornotify,BconnectoraddressE:BinputstateE where: BconnectoraddressE is as defined in section ). BinputstateE is as defined in *.;.) 5.+.' / D /ighting This connector state allows for pulse width modulated control (at )#-3P! of GE> lighting. 8iring for the $.*mm connector must be connected so that the >im line comes in on the tip, and the >im eturn line is on the base. The necessary command synta' and parameters for changing the pulse width carried on the connector are located below: "ent to iTach: setDGE>DGI43TI54,BconnectoraddressE,BQ intensityE,Blinear rampE where: BQ intensityE is the target percentage light intensity upon completion L).)--L Blinear rampE L-.)-L is the rate of change per unit time( ) being slowest )- being fastest. % ramp of ) will go from -Q to )--Q in about )- seconds, a rate of )will take about ) second, while a ramp of - will change the value instantly. "ent from iTach in response to setDGE>DGI43TI54: GE>DGI43TI54,BconnectoraddressE,BQ intensity)E,BQ intensity #E where: BQ intensity)E L-.)--L is the current lighting intensity BQ intensity#E L-.)--L is the target lighting intensity upon completion The state of the GE> Gighting connector can be polled for its intensity with the getDGE>DGI43TI54 command. 5ote that the GE>DGI43TI54 response will always return with two BQ intensityE values. If the connector is not currently changing the lighting intensity, then both BQ intensityE levels will be the same value. "ent to iTach: getDGE>DGI43TI54,BconnectoraddressE "ent from iTach in response to getDGE>DGI43TI54: GE>DGI43TI54,BconnectoraddressE,BQ intensity)E,BQ intensity #E
iTach API Specification Effective A!"!st #5, #011 P( 100)15*01 ver+ 1+5 : of )7 160 East California Street, PO Box 1659 $ac%sonville, Ore"on 9&5'0 Phone 5)1*,99*),00 -ax 5)1*,99*),0, ...+"lo/alcache+co0
Infor0ation s!/1ect to chan"e .itho!t notice+

iTach API Specification Version 1.5

where: BQ intensity)E is the current lighting intensity BQ intensity#E is the target lighting intensity upon completion 5.+.+ Dedicated / D /ighting Modes iTach I units now have two new >edicated GE> Gighting modes, which are the first iTach functions using more than one connector in tandem. In the "ingle Input GE> mode, the second connector is configured as a lighting control sensor while the third connector is configured as an GE> Gighting connector. 8hen enabled, standard setDGE>DGI43TI54 commands function properly when sent to the GE> Gighting connector. This works alongside the lighting control sensor, which monitors the circuit between the tip and the base of the $.*mm connector. 8hen a momentary contact is made, the lighting control sensor toggles the lighting level between on and off. 8hen held for a long press, the lighting control sensor will dim or elevate the lighting level for as long as the contact is closed. The long press function toggles between elevating light levels and dimming them. In the >ual Input GE> @ode, the first two connectors are configured as lighting control sensors, while the third connector is configured as an GE> Gighting connector. 8hen in this mode, standard setDGE>DGI43TI54 commands function properly when sent to the GE> Gighting connector. This mode works alongside the lighting control sensors, which monitor the circuit between the tip and base of each respective connector. 1onnector ) is the down function sensor. 8hen a momentary contact is made, this sensor turns the GE> Gighting connector to -Q. 8hen held for a long press, the lighting control sensor will dim the lighting level for as long as the contact is closed or until it reaches - percent (Q!. 1onnector # is the up function sensor. 8hen a momentary contact is made, this sensor turns the GE> Gighting connector to )-- percent. 8hen held for a long press, the lighting control sensor will elevate the lighting level for as long as the contact is closed, or until it reaches )-- percent. 5.+.5 I# Structure %n I , or infrared transmission, is created by sending an I timing pattern to the iTach. This pattern is a collection of BonE and BoffE states modulated with a carrier fre/uency ( R ! which is present during the BonE state. % carrier fre/uency is typically between $* to ;* F3P with some e/uipment manufacturers using as high as *-- F3P. The length of time for an BonE or BoffE state is calculated in units of the carrier fre/uency period. &or e'ample, an BoffE value of #; modulated at ;- F3P produces an BoffE state of 7--S", as calculated below. % period is ) 9R or )9;---- or .----#* seconds or #* ", and a value of #; periods is 7--" &igure *.;.) illustrates an I timing pattern that would be created for the value shown below. I timing patterns typically have a long, final BoffE value (or rest state! to ensure the ne't I command is interpreted as a separate I transmission.

0eriod

<

: )- )) )# )$ ); )* )7 )< )H ): #160 East California Street, PO Box 1659 $ac%sonville, Ore"on 9&5'0 Phone 5)1*,99*),00 -ax 5)1*,99*),0, ...+"lo/alcache+co0
Infor0ation s!/1ect to chan"e .itho!t notice+

iTach API Specification Effective A!"!st #5, #011 P( 100)15*01 ver+ 1+5 )- of )7

iTach API Specification Version 1.5

Bon)E C ; Boff)E C * Bon#E C 7
&igure *.;.)

Boff#E C *

5.+.. Sending I# 1ontrol of I devices is accomplished through use of the sendir command. "ince I commands may take up to )--m" to complete, the iTach provides a completeir acknowledgment to indicate when it is ready to accept the ne't I command for the connector in use. sendir "ent to iTach: sendir,BconnectoraddressE,BI>E,Bfre/uencyE,BrepeatE,BoffsetE,Bon)E, Boff)E,Bon#E,Boff#E,O.,Bon5E,Boff5E (where 5 is less than #7- or a total of *#numbers! where( BconnectoraddressE is as defined in section ). BI>E is L-L)L#LOL7**$*L ()! (for the completeir response, see below! Bfre/uencyE is L)*---L)*--)LO.L*-----L (in hertP! 2repeat3 is L)L#LO.L*-L (#! (the I command is sent BrepeatE times!

BoffsetE is L)L$L*LO.L$H$L ($! (used if BrepeatE is greater than ), see below! Bon)E is L)L#LOL7*7$*L (;! (number of pulses! Boff)E is L)L#LOL7*7$*L (;! (absence of pulse periods of the carrier fre/uency!
()!

The BI>E is an %"1II number generated by the sender of the sendir command, which is included later in the completeir command to confirm completion of each respective sendir transmission.
(#!

The BrepeatE is the number of times an I transmission is sent, if it is not halted early via a stopir or another I command (see section *.;!. Nalues above *- are accepted, but I commands are sent only the ma'imum *- times. In all cases, the preamble is only sent once (see BoffsetE below!.
($!%n

BoffsetE applies when the BrepeatE is greater than ). &or I commands that have preambles, an BoffsetE is employed to avoid repeating the preamble during repeated I timing patterns. The BoffsetE value indicates the location within the timing pattern to start repeating the I command as indicated below. The BoffsetE will always be an odd value since a timing pattern begins with an BonE state and must end with an BoffE state. BoffsetE odd value ) $ O. n.)
iTach API Specification Effective A!"!st #5, #011 P( 100)15*01 ver+ 1+5 )) of )7

repeat start location Bon)E Bon#E O. Bon((n9#! .)!E

BoffsetE even value # ; O. n

should not point here Boff)E Boff#E O. off(n9#!E where n is an even number
160 East California Street, PO Box 1659 $ac%sonville, Ore"on 9&5'0 Phone 5)1*,99*),00 -ax 5)1*,99*),0, ...+"lo/alcache+co0
Infor0ation s!/1ect to chan"e .itho!t notice+

no preamble

iTach API Specification Version 1.5

"ince I transmissions ends in an BoffE condition, there must be an e/ual number of BonE and BoffE states. %lso, every BonE and BoffE state must meet an H-S" minimum time re/uirement for the iTach to work properly. !a"ple: 8ith a carrier fre/uency of ;H F3P, the minimum value for BonE and BoffE states is calculated below. BoffE min C BonEmin T H-S" 2 R C H-S" 2 ;HF3P C $.H; &or proper iTach operation, all BonE and BoffE values in the timing pattern must be ; or higher. %ll of the conditions above must be met for valid sendir commands. 8hen a variable is missing or outside the accepted range, an unknowncommand will be sent by the iTach. %s an e'ercise, the sendir commands below will trigger an iTach unknowncommand response. sendir,*:$,$;*7,#$;--,),),#;,;H,#;,:7- Response: E Response: E Response: E D-:-,--# not an e/ual number of BonE and BoffE BoffsetE is an even number D):#,-)D):$,--< sendir,):#,#$$$$,;----,#,$,#;,;H,#;,;H,:7- sendir,):$,-,;----,#,#,#;,;H,#;,:7- iTach module * does not e'ist

(;!

I compressed format assigns the first )* unique BonEBoffE pairs capital letters (i.e. %,6,1, etc.! to represent them. In the event that a pair is used in many places inside an I command, commands can be written with the capital letter in place of the designated pair without being offset by commas. !a"ple: The simple I command sendir,):#,#;;*,;----,),),;,*,;,*,H,:,;,*,H,:,H,: can be shortened with this feature: (U;,*V is assigned %, and UH,:V is assigned 6! sendir,):#,#;;*,;----,),),;,*%H,:%66 6oth commands are syntactically correct, are accepted by the iTach, and will transmit an identical I command. co"pleteir %ll successful sendir commands are acknowledged with a completeir response from the iTach after completion of the I transmission. The completeir response associates with the sendir command through an BI>E. 8hen utiliPed, the BI>Es can provide a uni/ue identifier to determine which I transmission has completed. "ent from iTach in response to successful sendir: completeir,):),BI>E completeir,):#,BI>E completeir,):$,BI>E where( BI>E is L-L)L#LOL7**$*L
iTach API Specification Effective A!"!st #5, #011 P( 100)15*01 ver+ 1+5 )# of )7

for the )st I for the #

nd

connector connector

for the $rd I connector (I> is specified by originating sendir command!

160 East California Street, PO Box 1659 $ac%sonville, Ore"on 9&5'0 Phone 5)1*,99*),00 -ax 5)1*,99*),0, ...+"lo/alcache+co0
Infor0ation s!/1ect to chan"e .itho!t notice+

iTach API Specification Version 1.5

!a"ple: % few simple I

commands are shown below: timing se/uence illustrated in figure ;.#a to the #nd I connector on the

The following will send the I iTach shown in &igure ). "ent to iTach:

sendir,):#,#;;*,;----,),),;,*,7,* "ent by iTach in response to sendir: completeir,):#,#;;* In the ne't e'ample, the following two I commands will send the same I timing pattern. timing pattern of #;,)#,#;,:7- four times with a preamble 6elow are two ways to send the same simple I of $;,;H:

sendir,):#,;;;;,$;*--,),),$;,;H,#;,)#,#;,:7-,#;,)#,#;,:7-,#;,)#,#;,:7-,#;,)#,#;,:7- sendir,):#,$;,$;*--,;,$,$;,;H,#;,)#,#;,:7- %cknowledgments for above I completeir,):#,;;;; completeir,):#,$; %lthough the same command is sent four times by both sendir commands, the BI>Es are different, and therefore cannot be considered the same command. The second I command structure is the recommended method, avoiding long commands and allowing repetition of the command to be halted if re/uested. 5.+.4 S"ooth Continuous I# Co""ands % general discussion is necessary to better understand how smooth continuous I commands are e'ecuted by the iTach. This desirable feature is utiliPed for smooth volume control or repeating an operation without the appearance of choppy actions. The approach of sending an I command with very large repeat counts and stopping it upon re/uest will work, but can lead to undesirable incidents. 1onsider the scenario of large repeat count I command for raising the volume in a smooth fashion. The command works properly until the connection is broken. % repeating I command is sent, volume continuously increases, then the controlling i0hone is une'pectedly dropped. The volume continues to rise (possibly damaging e/uipment! until a stopir command is ultimately received. The iTach solution is to limit the repeat count. 3ence, to create a smooth I operation, the iTach resets the I repeat count each time the identical I command (from the same I0 connection! is resent. This method will not interrupt and restart the I command, but reset the I repeat count back to the original value. !a"ple: If the I repeat count is set to *, and the I command has transmitted $ times, receipt of the same command causes the repeat count to be reset back to *. This process can continue indefinitely while a volume button is held down to create a smooth operation. 3owever, at no time can the command repeat more than * times after the button is released or an I0 connection is inadvertently lost, preventing a potentially serious issue. 6y selecting an appropriate BrepeatE value, the need for a stopir command is eliminated. In this e'ample the volume continues to increase smoothly by retransmitting repeated I commands due to the volume
iTach API Specification Effective A!"!st #5, #011 P( 100)15*01 ver+ 1+5 )$ of )7 160 East California Street, PO Box 1659 $ac%sonville, Ore"on 9&5'0 Phone 5)1*,99*),00 -ax 5)1*,99*),0, ...+"lo/alcache+co0
Infor0ation s!/1ect to chan"e .itho!t notice+

commands are:

iTach API Specification Version 1.5

button being pressed. %s long as the ne't repeated I command is received before the previous command finishes, smooth operation is realiPed. 6y choosing a low repeat value, the volume increase will stop when the volume button is released. %lso, proper I operations happen even with unintended network delays due to traffic or 8i&i connectivity. In this unlikely event, only small hesitations will be e'perienced during I operation. In the event that the identical command is not received before the original command is finished, the command will be registered as a brand new command, and is sent as such. The command in /uestion will operate functionally the same, but delays between commands may be evident when used in this way. Increasing the BrepeatE value will likely eliminate these discrepancies. 5.+.5 I# /earning Each iTach unit contains an on.board I learner, which is located in the small hole located below and to the right of the power connector. I Gearner @ode is enabled by implementing the getDI G command. I learning mode cannot be activated if the unit is configured to control GE> lighting. get-I#/ "ent to iTach: getDI G "ent from iTach in response to getDI G: I Gearner Enabled =nce enabled, the iTach sends an uncompressed 4lobal 1achW format sendir command, terminated by a carriage return, through T10 packets via port ;::H. %lthough the iTach family of products supports up to eight simultaneous connections, the captured command will only be sent to the connection that initiated learner mode. Gearner mode is disabled when iTach units receive any command, or when stopDI G is sent. If getDI G is sent to a unit which is configured to control GE> lighting, you will be sent the I Gearner ?navailable response. "ent from iTach in response to getDI G when configured with an GE>DGI43TI54 connector: I stop-I#/ "ent to iTach: stopDI G "ent from iTach in response to stopDI G: I Gearner >isabled Gearner ?navailable

iTach API Specification Effective A!"!st #5, #011 P( 100)15*01 ver+ 1+5 ); of )7

160 East California Street, PO Box 1659 $ac%sonville, Ore"on 9&5'0 Phone 5)1*,99*),00 -ax 5)1*,99*),0, ...+"lo/alcache+co0
Infor0ation s!/1ect to chan"e .itho!t notice+

iTach API Specification Version 1.5

.. rror Codes
The chart below provides a list of error messages returned by the iTach from port ;::H and the e'planation of each message. @essages are returned in the aforementioned synta'.

rror Message
E E E E E E E E E E E E E E E E E E E E E E E E E E E D-) D-# D-$ D-; D-* D-7 D-< D-H D-: D)D)) D)# D)$ D); D)* D)7 D)< D)H D): D#D#) D## D#$ D#; D#* D#7 D#<

!planation
Invalid command. 1ommand not found. Invalid module address (does not e'ist!. Invalid connector address (does not e'ist!. Invalid I> value. Invalid fre/uency value. Invalid repeat value. Invalid offset value. Invalid pulse count. Invalid pulse data. ?neven amount of BonLoffE statements. 5o carriage return found. epeat count e'ceeded. I command sent to input connector. 6laster command sent to non.blaster connector. 5o carriage return before buffer full. 5o carriage return. 6ad command synta'. "ensor command sent to non.input connector. epeated I transmission failure. %bove designated I BonLoffE pair limit. "ymbol odd boundary. ?ndefined symbol. ?nknown option. Invalid baud rate setting. Invalid flow control setting. Invalid parity setting. "ettings are locked.

iTach API Specification Effective A!"!st #5, #011 P( 100)15*01 ver+ 1+5 )* of )7

160 East California Street, PO Box 1659 $ac%sonville, Ore"on 9&5'0 Phone 5)1*,99*),00 -ax 5)1*,99*),0, ...+"lo/alcache+co0
Infor0ation s!/1ect to chan"e .itho!t notice+

iTach API Specification Version 1.5

<. 6ugs
The following bugs affect the current revision of all iTach models. They are currently in the process of being removed, but they should not negatively affect the performance of iTach units.

iTach API Specification Effective A!"!st #5, #011 P( 100)15*01 ver+ 1+5 )7 of )7

160 East California Street, PO Box 1659 $ac%sonville, Ore"on 9&5'0 Phone 5)1*,99*),00 -ax 5)1*,99*),0, ...+"lo/alcache+co0
Infor0ation s!/1ect to chan"e .itho!t notice+