Generic Relay

The Generic Relay driver models a single relay channel on an existing relay controller as its own GEM device. It has no connection or IP of its own — it forwards its open / close / pulse commands to a parent controller you have already created (a ControlByWeb board, a Brainboxes I/O module, or any relay controller that exposes those verbs). One Generic Relay device drives one channel on that controller.

Reach for it when you want an individual relay to stand on its own — its own name, its own zone, its own place in the interface — instead of being one of many channels on the controller device. The simpler default is to address each channel as a zone directly on the controller (see ControlByWeb Relay / I/O and Brainboxes I/O); Generic Relay is the alternative when per-device modeling fits the job better — for example, giving the strike relay on a shared I/O board its own device so it can be permissioned, scheduled, or grouped independently.

How it works

• The relay device carries two things: a Controller (the parent board) and an Address (the channel on that board).
• When you send open, close, or pulse to the relay, the driver looks up the same-named command on the parent controller, sets the channel from this device's Address, and hands it to the controller to put on the wire.
• The parent controller serializes the write for you, so several Generic Relay devices can safely ride on one physical board.
• If you later reload or reconfigure the parent controller, the relay device re-points to it automatically — you do not need to reload the relay device as well.
• The relay device's online/offline state mirrors the parent controller's connection — it shows online while the board is reachable and drops with it. The controller raises the single Device Offline alarm for the shared link, so its relay devices don't each alarm separately.

Because everything is forwarded to the controller, the channel address you enter must be exactly what the parent controller expects for [address]. For a ControlByWeb board that is relay_1, relay_2, …; for a Brainboxes module it is the channel number. When in doubt, check the parent controller's page for how it names its channels.

One device, one channel

The channel lives on the device's Address, not on the zone. Each relay you want to control as its own device gets its own Generic Relay device with its own Address. To drive several channels, create several Generic Relay devices that share the same Controller.

Prerequisites

• A parent relay controller device already created and enabled, and it must be a controller-type device so it appears in the Controller picker. ControlByWeb and Brainboxes both qualify and both expose open / close / pulse.
• The channel address on that controller you want this device to drive (for ControlByWeb, the relay_N name; for Brainboxes, the channel number).

Setup

1. Create the parent relay controller first if it does not exist yet — Open Devices, add the controller (for example a ControlByWeb board), and confirm it is enabled. See its own page for wiring and addressing.
2. Open Devices → New Device and choose Generic Relay as the driver.
3. In the Controller field, select the parent controller you created. (Only controller-type devices appear here.)
4. In the Address field, enter the channel address on that controller — relay_1 for a ControlByWeb relay, or the channel number for a Brainboxes output.
5. Save and enable the device.
6. Create a zone bound to this device — Open Zones, New Zone, and bind it to the Generic Relay device. Put it under the subsystem that matches what the relay actually drives (Doors, Gates, Lights, Power, …). The subsystem decides how the relay's contact reads as a logical state — see Subsystem and state below. GEM does not create this zone for you.

Now controlling that zone — from a touchpanel button, a macro, or the Commands page — energizes the mapped relay on the controller.

Commands

Name	Args	Description
open	address	Forwards the parent controller's open verb to this device's channel.
close	address	Forwards the parent controller's close verb to this device's channel.
pulse	delay, address	Momentarily flips the relay and returns it — a dry-contact trigger. Set delay (milliseconds) for the hold time; the default hold comes from the parent controller.

address is filled from the device's Address automatically — sending open / close / pulse to the zone supplies it for you, so you rarely type it by hand. The relay device only exposes open / close / pulse; any other verb the parent supports (for example on / off) must be sent to the controller directly.

Pulse for momentary triggers

pulse is the "buzz the door / trigger the gate" action — it energizes the contact briefly, then releases. Many gate and garage operators need more than half a second of closure to register, so set the delay argument high enough (for example 3000 for a three-second release) if a short pulse does nothing.

Attributes

Set on the device:

Attribute	Type	Required	Description
controller_id (Controller)	device reference	yes	The parent relay controller. The relay refuses to dispatch and returns missing controller if it is empty, missing, or disabled.
address (Address)	string	yes	The channel on the parent controller (relay_1… for ControlByWeb, a channel number for Brainboxes). Commands error with generic relay device address if it is blank.
command_throttle	integer (ms)	no	Minimum spacing between commands forwarded to the controller. Add it from the Attribute editor only if the parent board is rate-sensitive and drops rapid bursts; unset means no added delay.

The relay device itself has no polling interval, credentials, or connection attributes — the parent controller owns the connection.

Subsystem and state

The zone's subsystem decides how the relay's raw contact (open / closed) reads as a logical state:

• Under Doors / Locks, a closed contact reads as unlocked.
• Under Gates / Garages / Lifts, a closed contact reads as open.
• Under Lights / Fans / Power, a closed contact reads as on.

If the relay fires the correct way but the state word is backwards for your wiring (for example it reads "locked" when the strike is actually released), flip the zone's Normally Closed toggle, or set a relay_states override on the zone. The full mapping — including custom subsystems that have no built-in meaning — is covered in Relay semantics.

Generic Relay drives; it does not monitor

This driver is a command path only — it sends open / close / pulse and does not poll the controller for live state. A Generic Relay zone will not reflect a contact that changes on the hardware (someone flips the relay locally, or a wired input trips). If you need live contact-state feedback in GEM, model that channel as a zone directly on the controller instead, which polls and reports state — see ControlByWeb Relay / I/O or Brainboxes I/O. Use Generic Relay when drive-only control of an individual relay is what you want.

Troubleshooting

Symptom	Check
Command returns missing controller	The Controller field is empty, or the parent controller device is missing, disabled, or not yet connected. Confirm the parent exists and is enabled, then reload it.
Command returns generic relay device address	The Address field is blank. Enter the channel address the parent controller uses for this relay.
Command returns generic relay controller missing command: …	The parent controller does not expose that verb. Confirm the parent is a relay controller that supports open / close / pulse (ControlByWeb, Brainboxes). A controller without a pulse command cannot pulse.
Relay fires the wrong way, or the state word is backwards	The zone's subsystem or mapping. Flip the zone's Normally Closed toggle, or set a relay_states override — see Relay semantics.
The zone never reflects a relay that changed on the hardware	Expected — Generic Relay does not poll. Model the channel as a zone on the controller for live state feedback.
Rapid bursts of commands seem to drop or collide	Add a command_throttle (ms) attribute to widen the spacing between commands sent to the parent controller.

Related

• Devices — adding the relay device, picking its Controller, and setting its Address.
• Zones — binding a zone to the device and choosing its subsystem.
• Subsystems — where the zone lives and how its default relay mapping is chosen.
• Commands — how open / close / pulse verbs route to a device.
• Relay semantics — how relay open/closed maps to on/off, locked/unlocked, and open/closed across subsystems.
• ControlByWeb Relay / I/O, Brainboxes I/O — relay controllers that can act as the parent for a Generic Relay.