Skip to main content

Brainboxes Ethernet I/O

The brainboxes driver controls and monitors a Brainboxes ED-series Ethernet I/O module over its ASCII @ command protocol on the LAN. Each digital channel on the module becomes a GEM zone: an output you energize, de-energize, or pulse as a dry-contact trigger, or an input whose contact state GEM watches and reflects live. It is the general-purpose Ethernet contact controller for jobs where GEM needs to throw a hard contact or read a hard-wired signal — pulsing a gate or garage operator, latching a lock strike, switching a lighting contactor or a power circuit, or watching a door, PIR, or flow contact.

The module is addressed over TCP (the Brainboxes ASCII "@" server, typically on port 9500). GEM polls the module's status about twice a second and drives outputs with short CR-terminated ASCII writes. No username or password is used — access is controlled by the network path to the module.

Put the module in TCP Server mode and create zones by hand

This driver does not auto-discover the module's I/O or auto-create zones. Two things are on you: (1) the Brainboxes module must be configured for TCP Server mode so it accepts GEM's outbound connection, and (2) you create one zone per channel and address it with the channel number. See Setup below.

How banks, channels, and zones map​

One Brainboxes module is one GEM device. Its I/O is organized into two banks of up to eight channels each, and GEM addresses a single channel by its module-wide channel number, counting from 1:

  • Channels 1–8 belong to bank 1.
  • Channels 9–16 belong to bank 2.

Every channel you want to control or monitor becomes a zone bound to the device, with its Address set to that channel number (1, 2, … 16). The Bank 1 Type and Bank 2 Type attributes on the device record whether each bank is wired for input or output.

  • Output channels accept close (energize the contact), open (release it), and pulse (a momentary close-then-release). Use them for gates, garages, locks, contactors, and power circuits.
  • Input channels are read-only. The driver polls the module and writes each channel's state onto the bound zone as on (contact true) or off (contact false).
Address is the channel number, 1–16

The Brainboxes device-creation form hints the address as "channel index within the module." In practice the driver uses the module-wide channel number — 1–8 for bank 1 and 9–16 for bank 2 — so a zone on bank 2's first channel is addressed 9, not 1.

Prerequisites​

  • A Brainboxes ED-series Ethernet I/O module on the same LAN as GEM, reachable at a known IP (use a DHCP reservation — the driver addresses the module by IP).
  • The module set to TCP Server mode, with the ASCII command port noted (Brainboxes ED modules default to 9500). In TCP Client mode the module will not accept GEM's connection and nothing will work.
  • The module's configured address (a two-character hex value, 01 out of the box). GEM's Device ID must match it.
  • Know your wiring: which bank is inputs and which is outputs, and which physical channel each load or contact lands on. You enter the bank types on the device and the channel number as each zone's address.

Setup​

  1. Add the device. Go to System → Devices → Add Device on the Devices page and choose the driver Brainboxes Ethernet I/O. Enter the Brainboxes IP Address and the TCP Port (typically 9500).
  2. Set the bank types. Under the device's advanced attributes set Bank 1 Type and Bank 2 Type to input or output to match how the module is wired. Set the Device ID if the module is not at its default address 01.
  3. Save and enable the device. GEM opens the TCP connection and begins polling the module for status.
  4. Create a zone per channel. On the Zones page, add a zone bound to the Brainboxes device and set its Address to the channel number (1–16). Pick the subsystem that matches what the channel drives — the list pre-selects a sensible default (Gates, Access, Locks, Lights, or a sensor subsystem) from the driver's hints, but you choose the right home.
  5. Relabel the reported state if you need semantic wording. A monitored channel reports plain on / off. If the zone represents a gate or lock and you want its control and status to read "open"/"closed" or "locked"/"unlocked", set the zone's On State and Off State attributes to those words — see Reported state.

Attributes​

Device​

AttributeUI labelRequiredTypeDefaultNotes
ipBrainboxes IP Addressyesstring—Module LAN IP (DHCP reservation recommended).
portTCP Portyesint—The ASCII "@" command port. Brainboxes ED modules default to 9500.
bank_1_typeBank 1 Typeyesstring (input / output)—How channels 1–8 are wired. Advisory — see the note below.
bank_2_typeBank 2 Typeyesstring (input / output)—How channels 9–16 are wired. Advisory — see the note below.
device_idDevice IDnostring01The module's address as a two-character hex value; must match the module's configured address.
status_intervalStatus Poll Interval (ms)noint2000Present for future use. The current driver polls at a fixed ~2-second cadence — see Known quirks.
Bank types describe wiring; the driver does not enforce them

Bank 1 Type / Bank 2 Type document your wiring so you (and the zones you create) know which channels are outputs. The current driver does not block an output write to a channel you've marked as an input, so treat the bank types as documentation and only send close / open / pulse to channels physically wired as outputs.

Zone​

Each zone carries an Address — the channel number 1–16. Enter it on the Zones page.

AttributeUI labelTypeDefaultNotes
on_stateOn StatestringonWord to report when the channel is true. Set it to open, unlocked, etc. to give a gate/lock zone semantic wording.
off_stateOff StatestringoffWord to report when the channel is false.

The driver also writes a read-only io_state attribute on the device — a 16-character 1/0 snapshot of all channels as last polled (channel 1 first). It is a diagnostic mirror; you normally read individual channels through their zones.

Commands​

Send these from the Commands page, a macro, or a control. When you send a verb to a zone, GEM supplies the zone's Address as the address argument for you — you rarely type it by hand.

CommandArgsDescription
closeaddressEnergize the output channel (drive the contact closed / on).
openaddressDe-energize the output channel (release the contact / off).
pulseaddress, delayMomentary trigger — close the channel, hold, then open it. Uses the delay arg in milliseconds if given, otherwise 1000 ms.
set_outputaddress, stateSet an explicit output state. state energizes the channel only when it is exactly close; any other value de-energizes it. Prefer the plain close / open commands.
read_stateaddressPoll the module now and return that channel's current state.
read_analogaddressReserved. Not implemented in the current driver — analog channels are not read (see Known quirks).
This driver speaks relay verbs, not on/off

The Brainboxes driver defines close / open / pulse, not on / off. Zones in subsystems whose controls already use those verbs — Gates and Garages (which pulse or open/close), and relay-style Doors / Locks — drive the module directly. A plain light or power on/off toggle sends on / off, which this driver does not recognize. To drive an on/off load, either operate the channel with close / open / pulse (from a macro, a trigger, or a gate-style control), or add a per-zone On Action / Off Action override that maps the zone's on to close and off to open. See Zones for per-verb action overrides.

Reported state​

GEM polls the module about every two seconds and reflects every channel onto its bound zone:

  • Channel true → zone state on; channel false → zone state off. The change is written only when the state actually flips, so a static input doesn't churn.
  • If you set the zone's On State / Off State attributes, those words are reported instead (e.g. a gate zone with On State = open reports open / closed).
Brainboxes reports raw on / off, not subsystem-mapped words

Some of GEM's relay drivers re-word a contact's state to fit its subsystem — the same contact reads "open" under Gates and "on" under Lights, and a Normally Closed toggle can invert it. This driver does not do that. It reports the raw channel state as on / off regardless of subsystem, and it does not apply a Normally Closed inversion to the reported value. Use the zone's On State / Off State attributes when you want semantic wording. See Relay semantics for how other drivers handle this.

Using the module as a relay controller​

The Brainboxes device can act as a parent controller for Generic Relay slave devices. Instead of (or alongside) addressing channels as zones on the Brainboxes device itself, you can create a Generic Relay device, point it at the Brainboxes as its controller, and give it a channel address; its open / close / pulse commands are routed to the Brainboxes channel. This lets you model an individual relay as its own device when that fits the job better than a bare zone. The zone-per-channel approach in Setup is the simpler default.

Known quirks​

  • TCP Server mode is mandatory. In TCP Client mode the module will not accept GEM's outbound connection and no status or control works.
  • Device ID must match the module. It is a two-character hex value (default 01). A mismatch means the module ignores GEM's polls and writes.
  • Channels are module-wide 1–16. Bank 1 is channels 1–8, bank 2 is 9–16. Address a zone with the module-wide number, not a per-bank 1–8.
  • The poll interval is fixed. The Status Poll Interval (ms) attribute is present, but the current driver polls at a fixed ~2-second cadence regardless of what you set. Input state can therefore lag a change by up to ~2 seconds.
  • read_analog is not implemented. The command exists but does nothing in the current driver — this driver reads and drives digital channels only. Use a different device or driver for analog I/O.
  • set_output is literal. Its state arg energizes the channel only when it equals close; every other value (including open, on, 1, true) de-energizes it. Use the dedicated close / open commands to avoid surprises.

Troubleshooting​

SymptomCheck
No status updates and state never changesConfirm the module is in TCP Server mode, the IP and TCP Port are correct, and the Device ID matches the module's configured address. The poller silently drops responses it can't parse.
Output commands do nothingThe channel must be on a bank you've wired as an output, and the zone Address must be the module-wide channel number (1–16). Send close / open / pulse — this driver has no on / off verbs.
A light "on/off" button doesn't workThe standard light switch sends on / off, which this driver doesn't define. Drive the channel with close / open / pulse, or add an On Action / Off Action override on the zone (see Zones).
A gate/lock zone shows "on/off" instead of "open/closed"Set the zone's On State and Off State attributes to the words you want — the driver reports the raw channel state otherwise.
Input state lags real-world changesThe module is polled about every two seconds; brief pulses shorter than the poll interval can be missed.
Analog channel reads nothingAnalog is not implemented — this driver handles digital channels only.