Global Caché iTach Serial Pass-Through

A Global Caché iTach IP2SL (or a Flex fitted with a serial cable) turns a single RS-232 port into a network connection. This driver opens a plain TCP link to that unit's serial pass-through port — 4999 by default — and every byte it sends goes straight out the iTach's RS-232 pins, while every byte the connected device replies with comes back on the same socket. Nothing is interpreted in between: the iTach is a transparent wire, and this driver is how GEM drives whatever legacy serial gear is on the far end (a receiver, a projector, a matrix switcher, a screen controller, an older amp).

Out of the box the driver ships with an Onkyo receiver command set as a working starting point — power, volume, mute, and input over Onkyo's ISCP protocol. If your serial device is an Onkyo (or Integra) receiver, those commands work as-is. For any other RS-232 device, you keep the same driver and connection but replace the command set with your device's control strings (see Controlling a device that isn't an Onkyo).

Which driver to pick

• If your Onkyo/Integra/Pioneer receiver is on the network, use the native Onkyo / Integra / Pioneer Receiver driver instead — it speaks the same protocol directly over TCP and gives you full AV-zone integration. Reach for this driver only when the device is reachable only over RS-232 and you are bridging it with an iTach.
• For the iTach's IR emitter and dry-contact relay ports, use the Global Caché iTach driver (or the broader Global Caché family driver). That driver talks to the unit's control API on port 4998 and auto-creates children for IR and relay ports; it does not drive RS-232. Serial is always a separate device on port 4999, which is this page.

What the bundled Onkyo command set controls

With the default command set, the driver controls an Onkyo receiver's main zone:

• Power — on, off, and a power-state query.
• Volume — set an absolute level, step up, step down, and a volume query.
• Mute — mute on, mute off, a direct mute toggle, and a mute query.
• Input — select an input by its Onkyo input code, plus an input query.

These are a template. The real point of the driver is the transparent serial link — treat the Onkyo commands as an example you either use directly or swap out.

Prerequisites

• Set the iTach's serial port to match the connected device. Baud rate, data bits, parity, stop bits, and flow control live on the iTach, not in GEM — GEM only tunnels bytes. Use Global Caché's iHelp to find the unit and its iLearn / configuration page to set the serial parameters (for an Onkyo receiver that is typically 9600 8N1, no flow control). If these don't match the device, commands go out but nothing responds.
• Wire the RS-232 cable between the iTach serial port and the controlled device, and confirm it is the right cable (straight-through vs. null-modem) for that device.
• Give the iTach a static IP or a DHCP reservation so the address never moves.
• The serial pass-through port 4999 (TCP) must be reachable from the GEM host. The pass-through is unauthenticated — there is nothing to log into.

Setup

1. Open Devices, add a device, and choose the Global Caché iTach Serial Pass-Through driver. Give the device a name and a device type (an AV/receiver or a generic controller type is fine — this driver does not pre-select one).
2. Fill in the connection fields:
   • iTach IP (required) — the LAN IP of the iTach IP2SL or Flex, entered as the ip attribute. This is the iTach's address, not the controlled device's.
   • Serial Pass-Through Port (optional) — the TCP port mapped to the RS-232 line. Defaults to 4999; leave it unless you have remapped it on the unit. Entered as the port attribute.
3. Enable the device and save. GEM opens a persistent TCP connection to the iTach and holds it open, reconnecting automatically if the link drops. A command set named itach_serial is created for the device and pre-populated with the bundled Onkyo commands.
4. On the device's Commands tab, run get_power_status, then power_on / power_off, to confirm control reaches the device before wiring it into macros or a UI.

Onkyo defaults

The bundled example assumes an Onkyo receiver at 9600 8N1. If you're commissioning exactly that, set the iTach serial port to 9600 8N1, wire the cable, enable the device, and the bundled commands should work with no further changes.

How commands reach the device

Each command is a text template that GEM sends over the serial link. For the bundled set, GEM sends Onkyo ISCP control messages — short strings such as !1PWR01 (power on) or !1MVLQSTN (query volume) — wrapped in Onkyo's binary control header, the same protocol the network Onkyo receiver driver uses, carried here over RS-232 instead of the LAN.

Two behaviors are worth knowing when you build or edit commands:

• Arguments are substituted verbatim. set_input takes an input argument and set_volume takes a volume argument, and whatever value you pass is dropped straight into the Onkyo message with no conversion. So set_volume here expects the value in the device's own format (Onkyo takes a two-digit hex level, e.g. 28 ≈ 40), not a friendly 0–100 percentage — this is a raw pass-through, not a scaled volume control.
• A request terminator is appended. GEM adds a carriage return to the end of each string command by default. If your device needs a different end-of-line (a line feed, both, or none), set the request_terminator attribute — see Attributes.

Controlling a device that isn't an Onkyo

To drive a projector, matrix, amp, or any other RS-232 device, keep this driver and the iTach connection and change the commands:

1. Match the iTach serial settings to that device (baud/parity/stop/flow via iHelp/iLearn).
2. On the device's Commands tab, edit the command templates to your device's control strings, or add new commands. Each command's template is the literal text sent out the serial port; use [argname] placeholders for values you'll pass at run time (for example a template POWR[state] with an argument state).
   • Non-printing bytes go in as backslash-hex escapes — for example \02 sends a STX byte and \0D a carriage return. GEM converts those to raw bytes on the wire, so binary protocols work too.
3. Set the Response Terminator if you want GEM to split replies into discrete responses (see Reading replies).
4. Set the correct end-of-line with request_terminator if your device doesn't use a bare carriage return.

Editing driver-managed commands

The bundled power_on / set_volume / etc. rows are written by the driver on every restart, so edits to those specific templates are overwritten on the next boot. When you're adapting the device to a non-Onkyo protocol, add your own commands (or build a fresh command set) rather than hand-editing the bundled Onkyo rows — your own commands are never touched by the driver.

Reading replies

By default GEM splits inbound serial data on a carriage return. If your device ends its replies with a different byte, set the Response Terminator (response_terminator) to match so each reply is framed as one response — for example, Onkyo's ISCP replies end with the 0x1A (EOF) byte, so a serial Onkyo link often wants response_terminator set to that. If the terminator doesn't match what the device actually sends, replies arrive garbled or run together, and the get_* query commands won't report cleanly.

The get_* commands (get_power_status, get_volume, get_mute, get_input) ask the device for its current state. This driver forwards whatever the device returns; it does not decode the Onkyo reply into a friendly power/volume/mute attribute, so use these mainly for verifying the link and reading raw device output in the logs.

Using the device in the system

This driver creates no zones — the iTach serial link is one GEM device, and you control it by sending its commands. The driver-declared commands appear on the device's Commands tab and can be used from:

• Macros — add a device-command step targeting this device and the command name (with any arguments) to sequence it with lights, shades, and other AV steps. See Macros.
• Triggers — fire a command in response to an event. See Triggers.
• UI buttons — bind a button to one of the device's commands.

If the far-end device is the room's receiver and you want a touchpanel's zone volume slider and mute button to drive it, open AV Zones, edit the zone, and set its Volume Device to this device — the zone's volume and mute controls then route to the serial link. (Leave the Volume Device pointed at a separate amp/receiver device if that's what actually carries the room audio, so you aren't fighting two volume controls.)

Attributes

Device — required

Attribute	Type	Description
ip	string	LAN IP of the iTach IP2SL or Flex that carries the serial cable (the iTach, not the controlled device).

Device — optional

Attribute	Type	Default	Description
port	int	4999	TCP port mapped to the iTach's serial pass-through line.

Base TCP tuning (type the name to add)

This driver is built on GEM's base TCP transport, so it also honors the standard TCP tuning attributes below. They are not offered in the device form or the attribute autocomplete list — add them from the device's Attributes tab, typing the name exactly, only if you need them.

Attribute	Type	Default	Description
request_terminator	string	carriage return	Appended to each outgoing string command. Set to match your device's end-of-line (e.g. line feed, both, or empty).
response_terminator	string	carriage return	Byte(s) GEM uses to split the inbound stream into discrete replies. Set to match how the device ends its responses (Onkyo ISCP uses 0x1A).
encoding	string	utf8	Payload encoding — utf8, ascii, hex, or binary.
command_throttle	int	200	Minimum gap in milliseconds between consecutive outgoing commands. Raise it if a slow adapter drops back-to-back commands.
reconnect_timeout	int	1000	Initial delay (ms) before reconnecting after the link drops; the backoff adds one second per attempt.
max_reconnect_delay	int	60000	Upper bound (ms) for the reconnect backoff.
status_interval	int	30000	Interval (ms) for optional status polling, if you configure status commands.
ping_command / ping_response	string	—	Optional keepalive: a command GEM sends periodically and the reply prefix it expects, used to detect a dead link.

Commands

Driver-declared commands appear on the device's Commands tab and can be used in macros, triggers, and on UI buttons. The Sends column shows the Onkyo ISCP control message; GEM wraps each one in Onkyo's binary control header and appends the request terminator before it goes out the serial line.

Power

Command	Sends	Action
power_on	!1PWR01	Turn the receiver on.
power_off	!1PWR00	Turn the receiver off (standby).
get_power_status	!1PWRQSTN	Query the current power state.

Volume and mute

Command	Sends	Action
set_volume (arg volume)	!1MVL[volume]	Set an absolute volume; volume is the device's raw level (Onkyo uses a two-digit hex value), not a 0–100 percentage.
volume_up	!1MVLUP	Step volume up one notch.
volume_down	!1MVLDOWN	Step volume down one notch.
get_volume	!1MVLQSTN	Query the current volume.
mute_on	!1AMT01	Mute the receiver.
mute_off	!1AMT00	Unmute the receiver.
mute_toggle	!1AMTTG	Toggle mute directly.
get_mute	!1AMTQSTN	Query the current mute state.

Input

Command	Sends	Action
set_input (arg input)	!1SLI[input]	Select an input by its Onkyo input code (for example 10 for CBL/SAT, 23 for CD).
get_input	!1SLIQSTN	Query the current input.

Troubleshooting

Symptom	Check
Commands go out but the device doesn't respond	Confirm the iTach serial settings (baud, parity, stop bits, flow control) match the device — use Global Caché iHelp / iLearn to set them. For an Onkyo receiver that's usually 9600 8N1. Also confirm the RS-232 cable type (straight vs. null-modem).
Garbled or partial replies	The Response Terminator doesn't match what the device sends. Set response_terminator to the device's reply framing (Onkyo ISCP ends with 0x1A), and confirm the baud rate matches.
Nothing works after swapping to a non-Onkyo device	The bundled commands are Onkyo-specific. Replace them with your device's control strings and set the correct request_terminator for that device's end-of-line.
Link keeps dropping / reconnecting	The iTach serial pass-through accepts a single TCP client at a time — make sure no other controller or a stuck session is holding port 4999. Reserve a static IP so the unit doesn't move.
set_volume sets the wrong level	set_volume passes the value straight through with no scaling — supply the device's native volume value (Onkyo expects a two-digit hex level), not a 0–100 percentage.
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 iTach IP.

Related documentation

• Global Caché iTach — the IR-emitter and dry-contact relay driver for the same units (port 4998); serial is always this separate device.
• Global Caché (family driver) — the broader driver covering iTach, Flex, GC-100, and Global Connect.
• Onkyo / Integra / Pioneer Receiver — the native network driver; use it when the receiver is reachable over the LAN instead of RS-232.
• Samsung TV (Serial-over-IP) — another device reached through a serial-to-IP gateway, using the same pattern.
• Devices — adding and configuring devices.
• Commands and Command Sets — where these commands live and how to add your own.
• Macros and Triggers — driving the device from automations.
• AV Zones — set this device as a zone's Volume Device when it controls the room's receiver.