Global Caché (iTach / Flex / GC-100 / Global Connect)

Driver for Global Caché Ethernet-to-control gateways — the small boxes that turn a network connection into IR emitter ports, contact-closure relays, RS-232 serial ports, and sensor inputs. One driver covers the whole product line:

• iTach — IP2IR (3 IR ports), IP2SL (serial), IP2CC (relays), and the Wi-Fi variants.
• Flex — Flex Link / Flex IP, with swappable cables (IR, serial, relay) on a single chassis.
• GC-100 — the older multi-module rack unit (GC-100-06 / -12 / -18) with mixed IR, serial, and relay slots.
• Global Connect — the current GC family, including the relay and HDMI-switch models.

All four speak the Global Caché Unified TCP API over TCP port 4998. The driver auto-detects which family it is talking to from the unit's own module list, so you pick this one driver regardless of model.

This is a controller: when it connects it asks the unit what ports it has and automatically 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

For any Global Caché gateway, choose Global Caché (iTach / Flex / GC-100 / Global Connect). There is also a thinner Global Caché iTach driver that inherits everything here; the family driver on this page is the recommended choice because its module enumeration and error decoding cover every model.

Prerequisites

• Give the unit a static IP or a DHCP reservation. Global Caché gateways pick up DHCP leases out of the box; without a reservation the device can move and the integration will go offline.
• The control port 4998 (TCP) must be reachable from the GEM host. No username or password is required — the API is unauthenticated.
• Have the unit physically wired before you onboard it: IR emitters plugged into (and aimed at) the target components, relay/contact-closure loads landed on the relay ports, serial cables connected. The driver enumerates whatever modules the unit reports, so the port layout it discovers reflects how the hardware is populated.

Setup

1. In System → Devices → Add Device, set:
   • Driver → Global Caché (iTach / Flex / GC-100 / Global Connect).
   • Type → a controller-class device type (so it appears as a parent Controller for its children).
   • IP Address → the unit's LAN IP.
   • TCP Port → leave at 4998 unless you have remapped it.
   • Command Set → leave the auto-selected set in place; the child devices inherit it.
2. Enable the device and save. On connect the driver issues getdevices, detects the product family, and auto-creates one child device per IR and relay port it finds:
   • Each IR port becomes a child device on the Generic IR driver, device type IR Transmitter, with its connector address (module:port, e.g. 1:1).
   • Each relay / contact-closure port becomes a child device on this same Global Caché driver, device type Relay, with its connector address.
   • Serial and sensor modules are detected (and used to identify the family) but are not auto-created as child devices — drive serial ports with the send_serial / passthrough commands, or use the dedicated iTach serial driver where appropriate.
   • Re-running discovery (reconnect) never duplicates a child — existing ones are matched by their connector address.
3. Finish each IR port. Open the auto-created IR Transmitter child device and set its Command Set to the controlled component's IR code set (the cable box, TV, projector codes, etc.). If those codes are in Pronto hex format, set the child device's command_format attribute to hex so they are converted to Global Caché sendir format on connect; use repeat_count to repeat each burst. Then add a zone under that child to represent the component — the IR commands fire out the port the child already carries.
4. Finish each relay port. Add a zone under the Relay child device and set the zone Address to the same connector string (module:port). Use open / close / on / off / pulse / get_state against it — the verbs and the reported state are translated per the zone's subsystem (see Relay state convention).

Subsystem is not pre-selected

This driver hints the ir / relays subsystems, but a stock install does not seed subsystems with those names, so the New Zone editor will not pre-select one for you. Choose the subsystem that matches what the port actually controls — a relay on a gate goes under Gates, a garage contact under Garages, a lighting relay under Lights, an IR-driven source or display under AV.

Connector addressing — module:port

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

• module is the slot number the unit reports in its device list (1, 4, …). On a single-module iTach this is almost always 1; on a GC-100 it is the physical slot.
• port is the 1-based connector on that module.

So a 3-port iTach IR module presents 1:1, 1:2, 1:3; a relay module in GC-100 slot 4 with three relays presents 4:1, 4:2, 4:3. That is the exact string you put in a relay zone's Address field, and it is the address the auto-created child devices carry. 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 — the same translation layer used by the Tasmota and ControlByWeb drivers:

Subsystem	Contact closed reports	Contact open reports
Lights, Fans, Power, Water, Fire	on	off
Gates, Garages, Lifts	open	closed
Shades	open	closed
Doors, Locks	unlocked	locked
Security	armed	disarmed

Commands translate the same way in reverse — on to a lighting-relay zone closes the contact; open to 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. With it set, a closed contact on a lighting relay reports off, and on opens the contact.
• relay_states (zone or subsystem attribute, JSON) — a custom {"closed": "...", "open": "..."} state map that replaces 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. Existing configurations that used these to relabel gates/locks continue to behave exactly as before.

A zone whose state (raw on/off for devices and legacy zones) has no subsystem match is left untranslated. Where a port must momentarily trigger rather than hold a state, pulse closes the contact, waits the requested time, and re-opens it — pulse is never translated.

Attributes

Device

Attribute	Type	Required	Description
ip	string	yes	LAN IP of the Global Caché unit.
port	int	no	Control port. Default 4998.
status_interval	int	no	How often (ms) the driver polls relay/sensor state for its zones and relay children. Default 5000.

IR Transmitter child (Generic IR)

Attribute	Type	Description
command_format	string	Set to hex to auto-convert Pronto hex codes to Global Caché sendir format on connect. gc (already-formatted) is the other accepted value.
repeat_count	int	Number of times each IR pattern is repeated per command. Default 1.

Relay / zone

Attribute	Type	Description
normally_closed	bool	Invert the relay translation for NC-wired contacts. Default false.

The driver publishes state for each relay connector it polls — the subsystem-translated value (on / off, open / closed, unlocked / locked, …) per the relay state convention. Child devices, and zones carrying the legacy on_state / off_state overrides, keep the raw on / off reading (relabelled by those overrides).

Commands

getCommands() is the source of truth; these are what the controller and its relay children expose.

Command	Args	What it does
close	address	Close the contact (setstate,<addr>,1). Translated through the zone relay mapping when the address is bound to a zone.
open	address	Open the contact (setstate,<addr>,0). 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 / set_relay	address, state	Set the contact to a raw 0 / 1 state.
get_state	address	Query the connector's current state; the reply reconciles the zone.
pulse	delay, address	Close the contact, wait delay ms (default 1000), then open — for momentary triggers (gate/garage strikes).
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 (stopir).
learn_ir	—	Enable the IR Learner on port 1:1 (get_IRL); learned codes stream into the logs.
stop_learn	—	Disable the IR Learner (stop_IRL).
send_serial	command	Send a raw string out a serial module.
passthrough	command	Escape hatch — send any literal Global Caché API line (no address required).
ping	—	Liveness check (getversion).

Driver-managed commands

These rows are written by the driver every boot — add new commands of your own, but don't hand-edit the templates or args above; they will be overwritten on the next restart.

Learning IR codes

If you don't have Pronto/Global Caché codes for a component, the iTach, Flex, and Global Connect families can learn them:

1. Run learn_ir on the controller. The unit enters IR Learner mode (the learning window is the dedicated IR Learner port, fixed at 1:1).
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.
4. Save the captured code as a command in the IR Transmitter child's command set.

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 — serial/sensor-only units create no children by design.
IR commands fire 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 … / unknowncommand … 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 module type doesn't support. The driver decodes the code per family (GC-100, iTach, Flex, Global Connect each use a different error format) and logs the meaning.
Device goes offline after an IP change	The unit grabbed a new DHCP lease. Reserve a static IP at the router and re-enter it in IP Address.

Related documentation

• Devices — add the Global Caché 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 (it is not auto-selected).
• Device Types — the Controller, Relay, and IR Transmitter types this driver uses.