Vantage InFusion

The Vantage InFusion driver controls a Vantage InFusion lighting and automation controller over your local network using Vantage's Host Command protocol — an ASCII, line-based protocol spoken over TCP. One InFusion controller becomes one GEM device, and each thing you want GEM to drive — a lighting load, a motorized shade, a keypad button, an automation task — becomes its own GEM zone, addressed by that object's Vantage VID (the numeric object id from your Vantage Design Center project).

Because it runs on the LAN, response is fast and there is no cloud account or hub in the middle. GEM keeps one persistent connection open to the controller and reconnects on its own if the link drops.

What's controlled

• Lighting loads — turn a load on or off, dim it to a level with an optional fade, and read the load's current level back so GEM stays in step with changes made at a keypad.
• Motorized shades / coverings — open and close a covering by pressing its Vantage button. The press is debounced: GEM only fires it when the covering isn't already in the requested state (see Shade zones).
• Keypad buttons and tasks — simulate a button press or run a programmed Vantage task.
• Passthrough — send a raw Host Command string for anything the standard commands don't cover.

This driver controls lighting levels with a real 0–100 % set-point and fade. Shades are button-driven only — there is no set-to-position (percentage) command and no stop for a shade. See Known limitations.

How GEM addresses Vantage objects (VIDs)

Every object in a Vantage project — each load, keypad button, and task — has a unique numeric id called a VID (the object id you see in Design Center). GEM identifies what a zone controls by putting that VID in the zone's Address field. There is no discovery step: you read the VIDs out of your Design Center project and enter them by hand.

Which VID you use depends on what the zone does:

• A lighting load zone takes the load's VID. The on/off, dim, and level-read commands (LOAD / RAMPLOAD / GETLOAD under the hood) all act on a load object.
• A shade or keypad/task zone takes the VID of the button or task to press. The open/close, press, and pulse commands fire a TASK <vid> PRESS against a button or task object, not a load.

Using a load VID where a button VID is expected (or vice-versa) is the most common reason a zone "does nothing" — double-check the object type in Design Center.

Prerequisites

• An InFusion controller on the same LAN as GEM, reachable by IP. Give it a DHCP reservation so its address never moves — a moved address means GEM can no longer reach it.
• Host Command (TCP) access enabled on the controller. This is configured in Vantage Design Center; some installs ship with it turned off, in which case GEM connects to nothing until it's enabled.
• A programmed Vantage project. GEM does not commission the Vantage system — the loads, shades, keypads, and tasks must already exist, and you need their VIDs from Design Center.
• No username or password — the Host Command port is unauthenticated, so treat network access to the controller as the security boundary (keep it on a trusted/automation VLAN).

Setup — adding the controller

1. Open Devices, add a device, and set the Driver to Vantage InFusion.
2. Set the device Type to controller.
3. Set InFusion IP Address to the controller's LAN IP.
4. Leave TCP Port at 3001 unless you've changed the Host Command port on the controller.
5. Save and enable the device. On connect, GEM opens the Host Command session, starts a keepalive, and immediately begins syncing the level of every lighting zone (see Keeping lighting in sync).

If the device won't connect, the usual causes are Host Command access being disabled in Design Center or the controller IP having moved — see Troubleshooting.

Mapping objects to zones

Zones are not created automatically. Add one zone per Vantage object you want to control.

Lighting load zones

1. Open Zones and add a zone.
2. Set its Subsystem to Lights. This matters: GEM only level-syncs zones in the Lights subsystem (see Keeping lighting in sync). Put a Vantage load anywhere else and GEM will still command it, but it won't auto-read the level back.
3. Pick a Control — a dimmer control for a dimmable load, an on/off control for a switched load.
4. Under Device Assignment, set the controlling Device to the InFusion controller.
5. Set the Address to the load's VID from Design Center.
6. Save. Repeat for each load.

On a dimmer control, GEM sends the level for you; on an on/off control it sends full-on or off. A moment after any change GEM re-reads the load so the displayed level (and the on/off indication) matches what the controller actually did.

Shade zones

A Vantage shade is driven by pressing a button, so a shade zone is addressed by the button's VID, not a load:

1. Add a zone and set its Subsystem to Shades.
2. Set the Device to the InFusion controller.
3. Set the Address to the VID of the button that moves the covering.
4. Save.

When you command Open, GEM presses that button only if the zone's tracked state is closed; when you command Close, it presses only if the state is open. This debounce keeps a repeated "open" from re-pressing a covering that's already open. Because the press is gated on GEM's tracked state, make sure the zone's initial state is correct during commissioning — if GEM and the physical shade disagree, the first press can be skipped. There is no stop and no set-to-percentage for a Vantage shade through this driver.

Keypad button and task zones

To fire a keypad button or run a programmed task, create a zone addressed by that button or task VID and use the press (or pulse) command — typically from a macro, a scene, or a custom UI button. Both send a TASK <vid> PRESS.

Keeping lighting in sync

So GEM reflects changes made at physical Vantage keypads, the driver continuously re-reads load levels:

• On connect, it walks every zone in the Lights subsystem and queries each load's level one at a time, pausing Zone Monitor Throttle milliseconds (default 2000) between queries so it doesn't flood the controller.
• After finishing a sweep it waits the device's polling_rate (default 5000 ms) and sweeps again, indefinitely.

For each level it reads, GEM writes the zone's level attribute (0–100). For a zone whose control includes on/off, it also sets the state attribute — on when the level is above 0, otherwise off.

Only zones in the Lights subsystem are polled this way. Shade, keypad, and task zones are commanded but not auto-read, since the button/task objects don't report a level. On a large site, tune Zone Monitor Throttle and polling_rate to balance how quickly keypad changes show up in GEM against the load you put on the controller.

Attributes

Device — required

Attribute	Type	Description
ip	string	The InFusion controller's LAN IP address. Shown as InFusion IP Address.

Device — optional

Attribute	Type	Default	Description
port	int	3001	Host Command TCP port. Shown as TCP Port. Range 1–65535.
zone_monitor_throttle	int	2000	Delay (ms) between the per-load level queries during a sync sweep. Shown under Advanced as Zone Monitor Throttle (ms). Minimum 100.
polling_rate	int	5000	Delay (ms) after a full sweep before the next one starts. Not shown on the form by default — add it as an attribute on the device if you want to change the resweep cadence.

Zone

Attribute	Type	Description
address	—	Required. The Vantage VID for this zone's object — a load VID for lighting, a button/task VID for shades and keypad actions.
level	int	Read-back: the load's current level (0–100). GEM sets this on each sync sweep and after each change — you don't enter it. It's cataloged, so it autocompletes in the Attribute editor and can drive attribute triggers.
state	string	Read-back: on / off, derived from the level for on/off-control lighting zones. GEM sets this for you. Also cataloged for autocomplete and triggers.

Commands

Driver-declared commands appear on the device's Commands tab and can be used in macros, triggers, and on UI buttons. Commands that take an address use the zone's VID — when you drive a zone from a control or a macro that targets the zone, GEM supplies the address for you.

Command	Args	Action
on	address	Turn the load fully on (LOAD <vid> 100).
off	address	Turn the load off (LOAD <vid> 0).
level	address, level, fade_rate	Ramp the load to level (0–100). fade_rate is an optional fade time the load ramps over (the third argument of Vantage's RAMPLOAD, in seconds).
get_level	address	Query the load's current level; GEM stores it on the zone. Used internally by the sync sweep, and available for a manual read.
open	address	Press the covering's button to open it — only if the zone isn't already open (debounced).
close	address	Press the covering's button to close it — only if the zone isn't already closed (debounced).
press	address	Fire a button or task press (TASK <vid> PRESS).
pulse	—	Fire a button/task press, for use as a momentary/pulse action.
get_task	address	Query a task's state (GETTASK <vid>).
status	type	Send a Host Command STATUS request of the given type (diagnostic).
passthrough	command	Send a raw Host Command string verbatim — the escape hatch for anything the commands above don't cover.

Keepalive

GEM sends a STATUS NONE keepalive about once a minute to confirm the link is alive. You don't need to configure this; it's mentioned only so the periodic traffic on the Host Command port isn't a surprise when you're watching the controller.

Known limitations

• Shades are button-driven, open/close only. There is no set-to-position (percentage) command and no stop for a Vantage shade through this driver — GEM presses the covering's button.
• Shade open/close is gated on GEM's tracked state. If GEM's idea of a shade's state drifts from reality (for example, the covering was moved at the keypad), the next open/close press can be skipped until the states agree. Set the zone's initial state correctly at commissioning.
• Only Lights-subsystem zones are level-synced. A Vantage load placed in another subsystem is still controllable, but GEM won't automatically read its level back, so changes made at a keypad won't be reflected in GEM for that zone.
• The Host Command port is unauthenticated. Anyone who can reach the controller's port can command it — keep the controller on a trusted network.

Troubleshooting

Symptom	Check
Device won't connect	Confirm Host Command access is enabled on the controller in Design Center, the InFusion IP Address is correct and reachable, and TCP Port is 3001 (or your remapped value). A DHCP reservation keeps the IP from drifting.
Zones never receive level updates after a restart	The level sync only runs for zones in the Lights subsystem. Confirm your lighting zones are in Lights and that Host Command is enabled and the port is reachable.
A load doesn't respond	Verify the zone's Address is the load's VID (not a button or task VID) and that the controlling Device is the InFusion controller.
A shade doesn't respond	Verify the zone's Address is the button's VID that moves the covering, and that GEM's tracked state isn't already the state you're commanding (open/close is debounced).
Level updates feel slow on a large site	Lighting zones are read one at a time with Zone Monitor Throttle between them and polling_rate between sweeps, so a full refresh scales with the load count. Lower these to refresh faster, or raise them to lighten the load on the controller.
GEM warns about an unknown Vantage address	The controller reported a level for a VID that has no matching GEM zone. Either create a zone with that VID as its Address, or ignore it if you don't intend to expose that load.

See also

• Devices — adding and configuring devices.
• Zones — how zones map objects to controls and subsystems.
• Subsystems — what the Lights and Shades subsystems are.
• Commands — running and scripting device commands.
• Attributes — viewing and editing the level / state read-backs.
• Macros and Triggers — automating lighting and reacting to load state.