api-itach (2)

5/28/2018 API-iTach (2)

1/16

iTach API SpecificationVersion 1.5

1. The iTach Modular Design Concept

The iTach family of products' modular design provides a variety of capabilities. Each module provides aparticular function: power and network connections, infrared (I!, digital input ("#$#!, and contactclosures (relay!. % module may also support one or more connectors of the same type. &or eample, anI 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 withinthe iTach enclosure. Each module occupies ).* inches of front panel space, even if it is part of a largerproduct. %t power on, module addresses are assigned starting with - for the leftmost module(containing the network and power connectors! and increasing se/uentially to the right until all moduleaddresses are assigned (see figure!. This presents a consistent programming interface as additionalmodules are added.

% connector's address is its position within a module, starting at ) on the left, and increasing se/uentiallyas you move to the right. % complete connector address includes the module address and the connectorlocation in the module, separated by a colon. In figure ) below, one I module is contained in the iTachI0#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 arealways physically located in module ) ():2!. 3owever, modules ) through $ will be accepted in commandsto the I, and ) through * will be accepted by the 11. This is deliberate and allows drivers developed forthe 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,):),) correct module number ():2!

setstate,*:),)

incorrect module but is an accepted, functional command

I# Connectors:

"upport for an I blaster is enabled on the third (2:$! I connector on an I module. This can beconfigured via command, or must be selected on the web site. %ttempts to configure connectors otherthan 2:$ as an I blaster will result in a returned error message.

&igure )

iTach API Specification 160 East California Street, PO Box 1659

Effective A!"!st #5, #011 $ac%sonville, Ore"on 9&5'0

P( 100)15*01 ver+ 1+5 Phone 5)1*99*)00

)of )7 -ax 5)1*99*)0 ...+"lo/alcache+co

Inforation s!/ect to chan"e .itho!t n otice+

1:1 1:3

Module 0 Module 1

5/28/2018 API-iTach (2)

2/16


$. Configure the IP Address

The 8i&i connected iTach web server+s default address is http:99)7.#*;.).310 (for automatic I0 allocation!, or designate a static I0address. The T109I0 connected iTach is set by default to use >310 to automatically obtain an I0 addressfrom the router. To determine the I0 address of an iTach using >310, run the i3elp ?tility found atwww.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 alsoperiodically announce its I0 address at intervals between )- and 7- seconds while powered up tomaintain uptodate i3elp display information. The i3elp display may be refreshed from the Vie% taboption.

'. Disco(er) *eaconThe iTach features a beacon message that can assist in locating iTach units on the network. The beaconis a ?>0 packet sent to the multicast I0 address #$.#**.#*-.#*- on ?>0 port number )$). %ny systemlistening to this address and port will receive the periodic beacon message. The message is sent shortlyafter power on and then at random intervals of )- to 7- seconds thereafter.

The beacon message has the following format:

%@A6B??I>C4lobal1acheD---1)E-#;#$B">F1lassC?tility

B@akeC4lobal1acheB@odelCiTach8IBevisionC

5/28/2018 API-iTach (2)

3/16


used for such things as iTach status, I data, relay operation, and reading digital input states. %llinformation, with the eception of serial data, is communicated by comma delimited %"1II tet stringsterminated by a carriage return ( !.

"erial data is communicated via 0orts ; and above. The serial connection in module ) willcommunicate over 0ort ;. "erial connections in the net 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 addressand data information will follow. The structures of iTach commands are described in the followingsections. Tet enclosed in brackets (Btet! must be substituted by its %"1II definition. @ultiple %"1IIchoices are divided by separator ( L ! characters.

Note:1ommands arecase sensitive.

!a"ple:The network settings are /ueried with the getD5ET command:

getD5ET,Bconnectoraddress

where

Bconnectoraddress is -:) (network module address!

The command %"1II string sent to the iTach is:

getD5ET,-:)

Note: getD5ET command is documented fully in section 5.1below.

5.1 ,eneral Co""ands

getde(ices

This iTach command is used to determine installed modules and capabilities. Each module responds withits address and type. This process is completed after receiving an endlistdevices response.

"ent to iTach:

getdevices (/uery for modules and capabilities!

de(ice

"ent from each iTach module in response to getdevices:

device,Bmoduleaddress,Bmoduletype (one sent for each module!

where for iTach products

Bmoduleaddress is L-L)L

Bmoduletype is L8I&ILET3E5ETL$ EG%ML$ IL) "EI%GL

%ll modules are included in the response followed by endlistdevices The following are the possibleiTachI responses to a getdevices command.

device,-,- 8I&I device,),$ I endlistdevices for 8i&i to three infrared

device,-,- 8I&I device,),) "EI%G endlistdevices for 8i&i to one serialiTach API Specification 160 East California Street, PO Box 1659


P( 100)15*01 ver+ 1+5 Phone 5)1*99*)00

$of )7 -ax 5)1*99*)0 ...+"lo/alcache+co


5/28/2018 API-iTach (2)

4/16


device,-,- 8I&I device,),$ EG%M endlistdevices for 8i&i to three relays

device,-,- ET3E5ET device,),$ I endlistdevices for I0 to three infrared

device,-,- ET3E5ET device,),) "EI%G endlistdevices for I0 to one serialdevice,-,- ET3E5ET device,),$ EG%M endlistdevices for I0 to three relays

get(ersion

The module version number may be obtained from any or all modules in an iTach. &or backwardcompatibility with the 41)--, the previous implementation of getversion has been enabled, and bothwork functionally.

"ent to iTach:

getversion

"ent from iTach in response to getversion:

Btetversionstring

where

Btetversionstring is the version number %"1II string

"ent to iTach:

getversion,Bmoduleaddress

where

Bmoduleaddress is L-L)L

"ent from iTach in response to getversion:

version,Bmoduleaddress,Btetversionstring

get-NTThis command will retrieve the current network settings and return a comma delimited string with thenetwork settings.

"ent to iTach:

getD5ET,-:)

"ent from iTach in response to getD5ET command:

5ET,-:),Bconfiglock,Bipsettings,Bipaddress,Bsubnet,Bgateway

where

Bconfiglock LG=1FE>L?5G=1FE>L

Bipsettings L>310L"T%TI1L

Bipaddress is the assigned network I0

Bsubnet is the network subnet mask

Bgateway is the default network gateway

un&no%nco""and



P( 100)15*01 ver+ 1+5 Phone 5)1*99*)00

;of )7 -ax 5)1*99*)0 ...+"lo/alcache+co


5/28/2018 API-iTach (2)

5/16


%n unknowncommand response will be sent by the iTach when a command is not understood. This canhappen if, for eample, 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, error codeJ

Note:>efinitions are contained in the rror Codestable in section .

5.$ Serial Connection

iTach serial is bidirectional, "#$# 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 viaconfiguration 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. TheiTach serial connector is assigned to I0 0ort ;.

If a serial connector is not configured correctly, buffer overflows (indicating data loss!, or parity errors willoccur. %ny errors will be captured and presented on the Serialweb page to aid in proper setup. "ettingssuch 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"EI%G,):),Bbaudrate,Bflowcontrol,Bparity

where:

):) is the iTach serial connector's address

Bbaudrate is L))*#--L*8%EL&G=8D5=5EL

Bparity is L0%ITMD5=L0%ITMD=>>L0%ITMDENE5L

!a"ple:

setD"EI%G,):),$H;--,&G=8D3%>8%E,0%ITMD5=

This command string will set the iTach serial connector to operate at $H;-- baud withhardware flow control and no parity.

get-S#IA/

This command will retrieve the current iTach serial settings.

getD"EI%G,):)



P( 100)15*01 ver+ 1+5 Phone 5)1*99*)00

*of )7 -ax 5)1*99*)0 ...+"lo/alcache+co


5/28/2018 API-iTach (2)

6/16


S#IA/

"ent from iTach in response to setD"EI%G and getD"EI%G.

"EI%G,):),Bbaudrate,Bflowcontrol,Bparity

5.$.$ #S$'$ Multiple Connection Mode

This mode enables four simultaneous T10 sockets to iTach port ;. In this mode, each socket cantransmit data out the serial connector on a packetbypacket basis. Each packet received for port ;will be transmitted completely before another packet (from the same or different socket! is transmitted outthe serial connector. This ensures complete commands can be received and understood by the seriallyconnected device. The only re/uirement is for each entire command(s! to be sent in one T10 packet. %llserial 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 beenabled or disabled from the Serialsettings web page.

5.' #ela) Closure Co""unication

iTach relays are activated by sending a B) state (close contacts!, and deactivated by a B- state (opencontacts!. elay states are not preserved through a power cycle and all relays will go back to theirinactive (open! state until a B) state is restored via command.

5.'.1 #ela) Co""ands

setstate

elay state is set as follows:

setstate,):),Boutputstate for the )st

relay outputsetstate,):#,Boutputstate for the #ndrelay output

setstate,):$,Boutputstate for the $rdrelay output

where

Boutputstate is L-L)L (B- is open, B) is closed!

"ent from iTach in response to setstate:

state,):)B-L) for the )strelay state

state,):#B-L) for the #ndrelay state

state,):$B-L) for the $ rdrelay state

Note:elay type connectors can be polled for their state with the getstate command (*.;.)!.

5.+ I# Co""ands

set-I#



P( 100)15*01 ver+ 1+5 Phone 5)1*99*)00

7of )7 -ax 5)1*99*)0 ...+"lo/alcache+co


5/28/2018 API-iTach (2)

7/16


This command allows configuration of each I connector to the desired mode of operation. The possiblemodes are I output, sensor input, sensor notify (see *.;.#!, I blaster, and GE> lighting (see *.;.$!. TheI blaster is only supported on the third I connector.

"ent to iTach:

setDI,):),Bmode

where:

Bmode is LIL"E5"=L"E5"=D5=TI&MLID6G%"TELGE>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,):) for the )stI connector

getDI,):# for the #ndI connector

getDI,):$ for the $rdI connector

"ent from iTach in response to getDI /uery:

I,):),BIL"E5"=L"E5"=D5=TI&MLID6G%"TELGE>DGI43TI54

stopir

% stopir command is used to halt I transmission. %ny remaining Brepeat counts will be discarded. %stopir command sent to a connector configured as an input will return an error message. %n Itransmission halted with the stopir command will return a stopir response. &urthermore, if an Icommand is halted before its completion by another connection, the originating I connection and theconnection sending stopir will both receive a stopir response. If stopped, the originating connection willnot receive a completeir response.

"ent to iTach:

stopir,):) to stop the )stI connector transmission

stopir,):# to stop the #nd I connector transmission

stopir,):$ to stop the $rdI connector transmission

"ent from iTach in response to stopir command:

stopir,Bconnectoraddress

where

Bconnectoraddress is as defined in stopir command

% stopir command always returns a stopir response regardless if the connector is idle or an Itransmission is actually halted. % stopir response means only that the stopir command was successfullysent to the iTach, and any transmission has been halted from the designated Bconnectoraddress.iTach API Specification 160 East California Street, PO Box 1659


P( 100)15*01 ver+ 1+5 Phone 5)1*99*)00

5/28/2018 API-iTach (2)

8/16


0us)I#

% busyI response occurs when an I command is received by a connector that is already sending an Itransmission. 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 Iconnector from another I0 connection, and will cause a busyI response.

% busyI response does not occur if the two I commands are eecuted on different I connectors.

"ent from iTach in response to an attempt to interrupt I transmission by another I0 connectionor socket:

busyI,Bconnectoraddress,BI>

where:

Bconnectoraddress is the busy connector

BI> is L-L)L#LOL7**$*L (I> is specified in sendir command!

Note: The busyI response is returned to the originator of the uneecuted I command. % command tostopir will only return the stopir response. %t no time will a command of stopir return a response of busyI.

5.+.1 Sensor#ela) State Co""ands

The iTach sends out notifications for digital sensor input state changes as well as allowing the inputs to bepolled for their current state at any time. This command can also be used to poll the state of contactclosure relays, with a value of B- representing an open contact, and B) representing a closed contact.>igital input connectors are the same connectors used for I output on I modules. The connectorconfiguration is determined by the iTach configuration on an individual connector basis. &or the followingcommands to operate correctly, the connector being addressed must be configured for sensor input or asa sensor notify connector. If a command re/uests information from a connector configured as outputrather than input, an unknowncommand response will be sent from the iTach.

getstate

"ent to iTach:

getstate,):) for the )st"ensor input or elay

getstate,):# for the #nd"ensor input or elay

getstate,):$ for the $rd"ensor input or elay

state

"ent from iTach in response to getstate:

state,):),Binputstate for the )stconnector

state,):#,Binputstate for the #ndconnector

state,):$,Binputstate for the $rdconnector

where

Binputstate is L-L)L

%n inputstate of B) represents a high digital voltage level, or absence of an input (no connection! and aB- represents a low digital voltage level, less than .HN. The iTach sensor input level is held highinternally and as such will indicate a B) with no connection.



P( 100)15*01 ver+ 1+5 Phone 5)1*99*)00

Hof )7 -ax 5)1*99*)0 ...+"lo/alcache+co


5/28/2018 API-iTach (2)

9/16


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 theI#settings web page. There, both the ?>0 port and timer settings can be changed to suit network andsoftware specifications. "ensor notifications are broadcast by way of ?>0 packet, sent in timedincrements 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 thetimer value is set to -, sensor notifications will broadcast only when the sensor state changes.

"ensor 5otify ?>0 broadcast packet contents are as follows:

sensornotify,Bconnectoraddress:Binputstate

where:

Bconnectoraddress is as defined in section ).

Binputstate 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 ison the base. The necessary command synta and parameters for changing the pulse width carried on theconnector are located below:

"ent to iTach:setDGE>DGI43TI54,Bconnectoraddress,BQ intensity,Blinear ramp

where:BQ intensity is the target percentage light intensity upon completion L))--LBlinear ramp 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 valueinstantly.

"ent from iTach in response to setDGE>DGI43TI54:GE>DGI43TI54,Bconnectoraddress,BQ intensity),BQ intensity #

where:BQ intensity) L-)--L is the current lighting intensityBQ intensity# 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>DGI43TI54command. 5ote that the GE>DGI43TI54 response will always return with two BQ intensity values. If the

connector is not currently changing the lighting intensity, then both BQ intensity levels will be the samevalue.

"ent to iTach:getDGE>DGI43TI54,Bconnectoraddress

"ent from iTach in response to getDGE>DGI43TI54:GE>DGI43TI54,Bconnectoraddress,BQ intensity),BQ intensity #



P( 100)15*01 ver+ 1+5 Phone 5)1*99*)00

of )7 -ax 5)1*99*)0 ...+"lo/alcache+co


5/28/2018 API-iTach (2)

10/16


where:BQ intensity) is the current lighting intensityBQ intensity# 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 usingmore than one connector in tandem.

In the "ingle Input GE> mode, the second connector is configured as a lighting control sensor while thethird connector is configured as an GE> Gighting connector. 8hen enabled, standard setDGE>DGI43TI54commands function properly when sent to the GE> Gighting connector. This works alongside the lightingcontrol sensor, which monitors the circuit between the tip and the base of the $.*mm connector. 8hen amomentary 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 asthe 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 thethird connector is configured as an GE> Gighting connector. 8hen in this mode, standardsetDGE>DGI43TI54 commands function properly when sent to the GE> Gighting connector. This modeworks alongside the lighting control sensors, which monitor the circuit between the tip and base of eachrespective connector. 1onnector ) is the down function sensor. 8hen a momentary contact is made, thissensor turns the GE> Gighting connector to -Q. 8hen held for a long press, the lighting control sensor willdim the lighting level for as long as the contact is closed or until it reaches - percent (Q!. 1onnector # isthe up function sensor. 8hen a momentary contact is made, this sensor turns the GE> Gighting connectorto )-- percent. 8hen held for a long press, the lighting control sensor will elevate the lighting level for aslong 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 acollection of Bon and Boff states modulated with a carrier fre/uency ( R ! which is present during theBon state. % carrier fre/uency is typically between $* to ;* F3P with some e/uipment manufacturersusing as high as *-- F3P. The length of time for an Bon or Boff state is calculated in units of the carrierfre/uency period. &or eample, an Boff value of #; modulated at ;- F3P produces an Boff state of7--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 timingpatterns typically have a long, final Boff value (or rest state! to ensure the net I command is

interpreted as a separate I transmission.

0eriod ) # $ ; * 7 < H )- )) )# )$ ); )* )7 )< )H ) #-



P( 100)15*01 ver+ 1+5 Phone 5)1*99*)00

)-of )7 -ax 5)1*99*)0 ...+"lo/alcache+co


5/28/2018 API-iTach (2)

11/16


Bon) C ; Boff) C * Bon# C 7 Boff# C *

&igure *.;.)

5.+. Sending I#

1ontrol of I devices is accomplished through use of the sendir command. "ince I commands may takeup to )--m" to complete,the iTach provides a completeir acknowledgment to indicate when it is ready toaccept the net I command for the connector in use.

sendir

"ent to iTach:

sendir,Bconnectoraddress,BI>,Bfre/uency,Brepeat,Boffset,Bon),

Boff),Bon#,Boff#,O.,Bon5,Boff5 (where 5 is less than #7- or a total of *#-numbers!

where

Bconnectoraddress is as defined in section ).

BI> is L-L)L#LOL7**$*L ()! (for the completeir response, see below!

Bfre/uency is L)*---L)*--)LO.L*-----L (in hertP!

2repeat3 is L)L#LO.L*-L (#! (the I command is sent Brepeat times!

Boffset is L)L$L*LO.L$H$L ($! (used if Brepeat is greater than ), see below!

Bon) is L)L#LOL7*7$*L (;! (number of pulses!

Boff) is L)L#LOL7*7$*L (;! (absence of pulse periods of the carrier fre/uency!

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

(#! The Brepeat is the number of times an I transmission is sent, if it is not halted early via a stopir oranother I command (see section *.;!. Nalues above *- are accepted, but I commands are sent onlythe maimum *- times. In all cases, the preamble is only sent once (see Boffset below!.

($!%n Boffset applies when the Brepeat is greater than ). &or I commands that have preambles, anBoffset is employed to avoid repeating the preamble during repeated I timing patterns. The Boffsetvalue indicates the location within the timing pattern to start repeating the I command as indicatedbelow. The Boffset will always be an odd value since a timing pattern begins with an Bon state andmust end with an Boff state.

Boffset repeat Boffset should not

odd value start location even value point here

) Bon) # Boff) no preamble

$ Bon# ; Boff#

O. O. O. O.

n) Bon((n9#! )! n off(n9#! where n is an even number



P( 100)15*01 ver+ 1+5 Phone 5)1*99*)00

))of )7 -ax 5)1*99*)0 ...+"lo/alcache+co


5/28/2018 API-iTach (2)

12/16


(;! "ince I transmissions ends in an Boff condition, there must be an e/ual number of Bon and Boffstates. %lso, every Bon and Boff 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 Bon and Boff states is calculatedbelow.

Boff min C Bonmin H-S" 2 R C H-S" 2 ;HF3P C $.H;

&or proper iTach operation, all Bon and Boff 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 outsidethe accepted range, an unknowncommand will be sent by the iTach. %s an eercise, the sendircommands below will trigger an iTach unknowncommand response.

sendir,*:$,$;*7,#$;--,),),#;,;H,#;,7- iTach module * does not eist

Response:ED-:-,--#

sendir,):#,#$$$$,;----,#,$,#;,;H,#;,;H,7- not an e/ual number of Bon and Boff

Response:ED):#,-)-

sendir,):$,-,;----,#,#,#;,;H,#;,7- Boffset is an even number

Response:ED):$,--. 8hen utiliPed, the BI>s can provide a uni/ue identifier to determine which I transmission hascompleted.

"ent from iTach in response to successful sendir:

completeir,):),BI> for the )stI connector

completeir,):#,BI> for the #ndI connector

completeir,):$,BI> for the $rdI connector

where

BI> is L-L)L#LOL7**$*L (I> is specified by originating sendir command!



P( 100)15*01 ver+ 1+5 Phone 5)1*99*)00

)#of )7 -ax 5)1*99*)0 ...+"lo/alcache+co


5/28/2018 API-iTach (2)

13/16


!a"ple:% few simple I commands are shown below:

The following will send the I timing se/uence illustrated in figure ;.#a to the #nd I connector on theiTach shown in &igure ).

"ent to iTach:

sendir,):#,#;;*,;----,),),;,*,7,*

"ent by iTach in response to sendir:

completeir,):#,#;;*

In the net eample, the following two I commands will send the same I timing pattern.

6elow are two ways to send the same simple I timing pattern of #;,)#,#;,7- four times with a preambleof $;,;H:

sendir,):#,;;;;,$;*--,),),$;,;H,#;,)#,#;,7-,#;,)#,#;,7-,#;,)#,#;,7-,#;,)#,#;,7-

sendir,):#,$;,$;*--,;,$,$;,;H,#;,)#,#;,7-

%cknowledgments for above I commands are:

completeir,):#,;;;;

completeir,):#,$;

%lthough the same command is sent four times by both sendir commands, the BI>s are different, andtherefore cannot be considered the same command. The second I command structure is therecommended method, avoiding long commands and allowing repetition of the command to be halted ifre/uested.

5.+.4 S"ooth Continuous I# Co""ands

% general discussion is necessary to better understand how smooth continuous I commands areeecuted by the iTach. This desirable feature is utiliPed for smooth volume control or repeating anoperation without the appearance of choppy actions. The approach of sending an I command with verylarge 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. Thecommand works properly until the connection is broken. % repeating I command is sent, volumecontinuously increases, then the controlling i0hone is unepectedly dropped. The volume continues torise (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 resetsthe I repeat count each time the identical I command (from the same I0 connection! is resent. Thismethod will notinterrupt and restart the I command, but reset the I repeat count back to the originalvalue.

!a"ple:If the I repeat count is set to *, and the I command has transmitted $ times, receipt of thesame command causes the repeat count to be reset back to *. This process can continue indefinitelywhile a volume button is held down to create a smooth operation. 3owever, at no time can the commandrepeat more than * times after the button is released or an I0 connection is inadvertently lost, preventinga potentially serious issue.

6y selecting an appropriate Brepeat value, the need for a stopir command is eliminated. In this eamplethe volume continues to increase smoothly by retransmitting repeated I commands due to the volume



P( 100)15*01 ver+ 1+5 Phone 5)1*99*)00

)$of )7 -ax 5)1*99*)0 ...+"lo/alcache+co


5/28/2018 API-iTach (2)

14/16


button being pressed. %s long as the net repeated I command is received before the previouscommand finishes, smooth operation is realiPed. 6y choosing a low repeat value, the volume increasewill 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 beeperienced during I operation.

In the event that the identical command is not received before the original command is finished, thecommand will be registered as a brand new command, and is sent as such. The command in /uestion willoperate functionally the same, but delays between commands may be evident when used in this way.Increasing the Brepeat value will likely eliminate these discrepancies.

5.+. I# /earning

Each iTach unit contains an onboard I learner, which is located in the small hole located below and tothe right of the power connector. I Gearner @ode is enabled by implementing the getDIG command. Ilearning mode cannot be activated if the unit is configured to control GE> lighting.

get-I#/

"ent to iTach:

getDIG

"ent from iTach in response to getDIG:

I Gearner Enabled

=nce enabled, the iTach sends an uncompressed 4lobal 1achW format sendir command, terminated by acarriage return, through T10 packets via port ;H. %lthough the iTach family of products supports up toeight simultaneous connections, the captured command will only be sent to the connection that initiatedlearner mode. Gearner mode is disabled when iTach units receive any command, or when stopDIG issent. If getDIG 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 getDIG when configured with an GE>DGI43TI54 connector:

I Gearner ?navailable

stop-I#/

"ent to iTach:

stopDIG

"ent from iTach in response to stopDIG:

I Gearner >isabled



P( 100)15*01 ver+ 1+5 Phone 5)1*99*)00

);of )7 -ax 5)1*99*)0 ...+"lo/alcache+co


5/28/2018 API-iTach (2)

15/16


. rror CodesThe chart below provides a list of error messages returned by the iTach from port ;H and the

eplanation of each message. @essages are returned in the aforementioned synta.

rror Message !planation

ED-) Invalid command. 1ommand not found.

ED-# Invalid module address (does not eist!.

ED-$ Invalid connector address (does not eist!.

ED-; Invalid I> value.

ED-* Invalid fre/uency value.

ED-7 Invalid repeat value.

ED-< Invalid offset value.

ED-H Invalid pulse count.

ED- Invalid pulse data.

ED)- ?neven amount of BonLoff statements.

ED)) 5o carriage return found.

ED)# epeat count eceeded.

ED)$ I command sent to input connector.

ED); 6laster command sent to nonblaster connector.

ED)* 5o carriage return before buffer full.

ED)7 5o carriage return.

ED)< 6ad command synta.

ED)H "ensor command sent to noninput connector.

ED) epeated I transmission failure.

ED#- %bove designated I BonLoff pair limit.

ED#) "ymbol odd boundary.

ED## ?ndefined symbol.

ED#$ ?nknown option.

ED#; Invalid baud rate setting.

ED#* Invalid flow control setting.

ED#7 Invalid parity setting.

ED#< "ettings are locked.



P( 100)15*01 ver+ 1+5 Phone 5)1*99*)00

)*of )7 -ax 5)1*99*)0 ...+"lo/alcache+co


5/28/2018 API-iTach (2)

16/16


api-itach (2)

Documents