Global Caché iTach

Driver for the Global Caché iTach family — the compact Ethernet (or Wi-Fi) gateways that turn a network connection into infrared emitter ports, dry-contact relays, and serial ports:

• IP2IR / WF2IR — three IR emitter ports for blasting cable boxes, TVs, projectors, and other IR-controlled gear.
• IP2CC / WF2CC — three dry-contact relays for gates, garage strikes, screens, drapes, or any contact-closure load.
• IP2SL / WF2SL — a single RS-232 serial port (see Serial control below).
• iTach Flex — a single chassis with a swappable IR / serial / relay cable.

The iTach speaks the Global Caché Unified TCP API over TCP port 4998 and needs no username or password. This is a controller: when it connects it asks the unit which ports it has and auto-creates a child device for every IR emitter and relay port it finds. You then attach zones — and, for IR, the controlled component's code set — to those children.

Which driver to pick — iTach vs. the family driver

There are two Global Caché entries in the driver list. Global Caché iTach (this page) is tuned for iTach units. Global Caché (iTach / Flex / GC-100 / Global Connect) is the broader family driver that also covers the older GC-100 rack units and the newer Global Connect models. Both share the same command set and module auto-discovery — for a plain iTach either works. If you have a GC-100, a Global Connect model, a mixed chassis, or you're not sure which model is in the rack, choose the family driver instead; its error decoding covers every model.

Prerequisites

• Give the iTach a static IP or a DHCP reservation. iTach units grab DHCP leases out of the box; without a reservation the unit can move and the integration will go offline.
• The control port 4998 (TCP) must be reachable from the GEM host. The API is unauthenticated — there is nothing to log into.
• Wire the unit before you onboard it. Plug IR emitters into their ports and aim them at each component's IR window; land relay/contact-closure loads on the relay ports. The driver enumerates whatever the unit reports, so the port layout it discovers reflects how the hardware is populated.
• The iTach broadcasts a discovery beacon on UDP 9131, but typing the unit's IP in by hand is equally fine.

Setup

1. In System → Devices → Add Device, set:
   • Driver → Global Caché iTach.
   • Type → a controller-class device type, so the iTach appears as a parent Controller for its auto-created children.
   • IP Address → the unit's LAN IP.
   • TCP Command Port → leave at 4998 unless you have remapped it on the unit.
   • Command Set → leave the auto-selected Global Caché set in place; the child devices inherit it.
2. Enable the device and save. On connect the driver asks the unit for its module list and auto-creates one child device per IR and relay port:
   • Each IR port becomes a child on the Generic IR driver, device type IR Transmitter, carrying its connector address (module:port, e.g. 1:1).
   • Each relay / contact-closure port becomes a child on the Global Caché driver, device type Relay, carrying its connector address.
   • Reconnecting never duplicates a child — existing ones are matched by their connector address.
3. Finish each IR port. Open the auto-created IR Transmitter child and set its Command Set to the controlled component's IR code set (the cable box, TV, or projector codes). See Sending IR for the code format. Then add a zone under that child to represent the component.
4. Finish each relay port. Add a zone under the Relay child and set the zone Address to the same connector string (module:port). Drive it with open / close / on / off / pulse / set_state — the verbs and the reported state are translated per the zone's subsystem (see Relay state convention).

Which subsystem a zone lands in

When you add a zone directly under the iTach device, the New Zone editor pre-selects the AV subsystem (the iTach hints AV). A zone added under a Relay child gets no pre-selection, so pick the subsystem that matches the load — a gate relay under Gates, a garage strike under Garages, a lighting relay under Lights, a door strike under Doors. IR-controlled sources and displays generally belong under AV. The pre-selection is only a default; change it to whatever the port actually controls.

Connector addressing — module:port

Every IR emitter and relay is addressed as module:port:

• module is the slot number the unit reports (1 on a single-module iTach).
• port is the 1-based connector on that module.

So a 3-port iTach IR module presents 1:1, 1:2, 1:3; a 3-relay IP2CC presents 1:1, 1:2, 1:3 as well. That exact string is what you put in a zone's Address field, and it is the address the auto-created child devices already carry. A device or zone left without an address defaults to 1:1. The IR Learner is fixed at 1:1 per the Global Caché specification.

Relay state convention

A relay / contact-closure connector reports closed (1) or open (0). When the connector address is bound to a zone, the driver routes both the reading and the open / close / on / off verbs through the subsystem-aware relay-to-zone mapping shared with the family Global Caché driver — a closed contact on a Lights zone reports on, on a Gates zone reports open, on a Doors/Locks zone reports unlocked, and the verbs translate the same way in reverse (open on a gate zone closes the contact that triggers the opener). Three overrides refine the mapping:

• normally_closed (zone attribute, bool) — invert the translation for NC-wired contacts.
• relay_states (zone or subsystem attribute, JSON) — a custom {"closed": "...", "open": "..."} state map replacing the subsystem default.
• on_state / off_state (zone attributes, legacy) — when either is set, the zone skips translation entirely and keeps the original raw behavior: closed reports on (relabelled by the override), and open / close drive the contact literally.

The driver polls the state of every relay zone and relay child on a fixed interval (see status_interval below, default 5000 ms), so a relay switched by a wall button or another system still reconciles in GEM.

Where a port must momentarily trigger rather than hold a state, pulse closes the contact, waits the requested time (default 1000 ms), and re-opens it — the standard "buzz the gate / fire the garage strike" action.

Sending IR

IR is fired through the auto-created IR Transmitter child device, not the iTach parent:

1. On the IR Transmitter child, set the Command Set to the controlled component's IR code set.
2. If those codes are in Pronto hex format, set the child's command_format attribute to hex — the driver converts them to Global Caché sendir format on connect. The other accepted value is gc (codes already in Global Caché format). Use repeat_count to repeat each burst (default 1).
3. Each command on that child sends out the port the child carries — no address wrangling needed.

If you don't have codes for a component, the iTach can learn them:

1. Run learn_ir on the iTach. The unit enters IR Learner mode on the fixed 1:1 learning window.
2. Point the original remote at the unit's learning sensor and press the button. The captured sendir code appears in the device logs.
3. Run stop_learn to leave learner mode, then save the captured code as a command in the IR Transmitter child's command set.

If an IR burst is still transmitting when the next one arrives, the unit reports busyir in the logs; space commands out, or send stop_ir on that port to halt an in-progress transmission before re-firing.

Serial control — use a separate device

This IR/relay driver does not drive RS-232. For an IP2SL or a Flex with a serial cable, add a separate Global Caché iTach Serial Pass-Through device pointed at the same unit's IP on TCP port 4999 — that pass-through carries bytes transparently to and from the serial port. The send_serial command listed on the Global Caché command set is not wired on this driver; treat serial as its own device.

Attributes

Device (the iTach)

Attribute	Type	Required	Description
ip	string	yes	LAN IP of the iTach.
port	int	no	TCP command port. Default 4998.
status_interval	int	no	How often (ms) the driver polls relay state for its zones and relay children. Default 5000.

IR Transmitter child (Generic IR)

Attribute	Type	Description
command_format	string	hex to auto-convert Pronto hex codes to Global Caché sendir format on connect; gc for codes already in Global Caché format.
repeat_count	int	Number of times each IR pattern is repeated per command. Default 1.

Relay zone

The driver publishes state for each relay connector it polls — the subsystem-translated value (see Relay state convention), or the raw on / off (optionally relabelled via the legacy on_state / off_state attributes).

Commands

These are the working commands the iTach and its relay children expose. Driver command rows are written by the driver on every boot — add commands of your own, but don't hand-edit the templates or args below; they are overwritten on restart.

Command	Args	What it does
open	address	Open the contact (setstate,<addr>,0). Translated through the zone relay mapping when the address is bound to a zone.
close	address	Close the contact (setstate,<addr>,1). Translated through the zone relay mapping when the address is bound to a zone.
on / off	address	Driver-handled semantic verbs — translated through the zone relay mapping to the matching contact state (raw fallback: on closes, off opens).
set_state	address, state	Set the contact to a raw 0 / 1 state.
pulse	delay, address	Close the contact, wait delay ms (default 1000), then open — for momentary triggers.
get_state	address	Query the connector's current state; the reply reconciles the zone.
send_ir	address, command	Transmit an IR code (sendir,<addr>,<code>). Normally fired through the IR Transmitter child rather than called directly.
stop_ir	address	Halt an in-progress IR transmission on that port.
learn_ir	—	Enable the IR Learner on port 1:1; learned codes stream into the logs.
stop_learn	—	Disable the IR Learner.
passthrough	command	Escape hatch — send any literal Global Caché API line (no address required).

note

Use the relay verbs, not set_relay

Relay control goes through open / close / set_state / pulse. A set_relay row also appears in the command list, but it is not handled by this driver — use set_state (or open / close) instead.

Troubleshooting

Symptom	Check
No child devices appear after enabling	Confirm port 4998 is reachable and the unit answers getdevices. The driver only auto-creates IR and relay ports — a serial-only unit creates no children by design.
IR fires but the component doesn't respond	Verify the emitter is on the matching module:port, is seated in the IR jack, and is aimed at the component's IR window. Confirm the IR Transmitter child has the component's code set assigned, and command_format = hex if the codes are Pronto hex.
busyir in the logs	The IR port is still transmitting a previous (different) code. Space out commands, or send stop_ir on that port before re-firing.
Relay zone state never updates	Run get_state on the connector address; the unit replies with the current closed/open state and the zone reconciles. Confirm the zone Address matches the module:port the unit reports.
Relay state or commands read backwards	The wiring is inverted relative to the subsystem default — set the zone's normally_closed attribute to flip the translation, or drive momentary loads with pulse instead of a latched close.
ERR_… errors in the logs	The unit rejected a command — common causes are an invalid module:port, an IR code that is too long, or a verb the port type doesn't support. The driver decodes the code and logs its meaning.
Device goes offline after an IP change	The iTach grabbed a new DHCP lease. Reserve a static IP at the router and re-enter it in IP Address.

Related documentation

• Global Caché (family driver) — the broader driver covering iTach, Flex, GC-100, and Global Connect; shared addressing and error decoding.
• Devices — add the iTach controller and see its auto-created IR/relay children.
• Zones — create the per-port zones that surface relays and IR-controlled components.
• Commands — where open / close / pulse / send_ir appear and can be tested.
• Subsystems — pick the right subsystem for each relay/IR zone.
• Device Types — the Controller, Relay, and IR Transmitter types this driver uses.
• Remotes — mapping IP remote buttons to the commands and macros that drive these ports.