openHAB

The openHAB driver bridges GEM zones to items on an openHAB server over its REST Items API. One GEM device points at one openHAB server; each GEM zone you create maps to one openHAB Item by name. GEM sends commands to the item (turn a switch on or off, set a dimmer level, lock or unlock, momentarily pulse) and reads the item's state back by polling, so the item's current value shows up on the zone.

This is a poll-based bridge you wire up by hand: GEM drives each item and reads its state on a timer. There is no auto-discovery and no real-time push — you name each item yourself, and state refreshes at the poll interval.

How it works

• The device holds the openHAB server's address (host and port) and talks to …/rest/items/<item>.
• Each zone bound to the device carries an Address that is the exact openHAB Item name. Commands you send to the zone are POSTed to that item; the poll reads that item's state back.
• On the poll interval GEM issues one HTTP GET per mapped item. A numeric state (a Dimmer or Number item) is stored on the zone as level; anything else (a Switch's ON / OFF, a String) is stored as state.
• Item names are case-sensitive and must match openHAB exactly.

Poll-based, one server per device

Create one openHAB device per openHAB server, then a zone per item you want to control. GEM does not import your openHAB items — you add each zone by hand with its item name. State is read on a timer (default every 3 seconds), not pushed, so a change made in openHAB shows up in GEM within one poll cycle.

Prerequisites

• An openHAB server reachable from the GEM controller on the LAN (default http://localhost:8080).
• The openHAB REST API enabled and reachable. This driver sends no credentials, so the REST API must be reachable without authentication — keep it on the controller LAN only.
• The exact Item names for everything you want to control (case-sensitive).

Setup

1. Open Devices → New Device and choose openHAB as the driver.
2. Set Host IP to the openHAB server (leave it at localhost if openHAB runs on the same machine as GEM) and HTTP Port to the REST port (default 8080). Set Protocol to https only if your openHAB server is behind TLS.
3. Optionally adjust Status Poll Interval (ms) (default 3000) — see the note on polling cost below.
4. Save and enable the device.
5. For each openHAB item you want in GEM, Open Zones → New Zone, bind it to the openHAB device, and set the zone Address to the openHAB Item name. Put the zone under the subsystem that matches what it drives (Lights, Locks, Power, …). GEM does not create these zones for you.

Now controlling that zone — from a touchpanel, a macro, or the Commands page — POSTs to the openHAB item, and the poll keeps the zone's state in sync with openHAB.

Mapping zones to items

The zone Address is the openHAB Item name, verbatim and case-sensitive. Match the GEM commands you use to the openHAB Item type:

• Switch item → use on / off (they POST ON / OFF).
• Dimmer / Number item → use level to POST a numeric value (0–100 for a Dimmer). The polled value comes back as the zone's level.
• A lock or relay modeled as a Switch → use lock / unlock (they POST ON / OFF), or pulse for a momentary "buzz" (POST ON, wait, POST OFF).

If you POST a value the item cannot accept (for example ON to a Number item), openHAB returns an error — match the command to the item type.

Commands

Name	Args	Sends to the item	Description
on	—	ON	Turn a Switch item on.
off	—	OFF	Turn a Switch item off.
lock	—	ON	Same effect as on; use it on a lock/relay item so the verb reads correctly.
unlock	—	OFF	Same effect as off; use it on a lock/relay item.
level	level	the number	Set a Dimmer/Number item to a value (for example 50).
pulse	delay (optional)	ON, then OFF	Momentary trigger — energize the item, wait delay ms (default 500), then release. Raise delay (for example 3000) for a gate or strike that needs a longer hold.

The zone Address (the item name) is supplied automatically when you command the zone, so you rarely type it by hand.

Attributes

Set on the device:

Attribute	Type	Default	Description
ip (Host IP)	string	localhost	openHAB server host.
port (HTTP Port)	integer	8080	openHAB REST port.
protocol (Protocol)	string	http	http or https.
status_interval (Status Poll Interval (ms))	integer	3000	How often every mapped item is polled for state.

Set on each zone:

Attribute	Type	Required	Description
address (Address)	string	yes	The openHAB Item name (case-sensitive).
state_map	JSON	no	Optional state translation applied when reading the item — see below.
status_zone	boolean	no	Marks a zone as taking its status from another zone, so the poll skips it. Leave unset for a normal item.

Translating state on read (state_map)

By default the item's polled state is stored as-is (lower-cased) — a Switch reads as on / off, a Dimmer stores its number as level. If you want the zone to read in different words — for example a lock item whose ON should display as locked — add a state_map attribute on the zone from the Attribute editor. It is a JSON object with a response map from the openHAB value to the word you want:

{"response": {"on": "locked", "off": "unlocked"}}

Only the response side is applied by this driver; the commands you send always use the fixed verbs in the table above.

Notes and limits

Poll-only, no auth, no discovery

• No push. State is read on the poll timer only. A change made in openHAB appears in GEM within one Status Poll Interval, not instantly.
• No authentication. The driver sends no credentials, so the openHAB REST API must be reachable unauthenticated — keep it on the controller LAN and never expose it to the internet.
• Polling cost scales with zone count. Every poll cycle issues one HTTP GET per mapped item. Many items on a short interval load both GEM and the openHAB server — raise Status Poll Interval or split items across devices if the controller's CPU climbs.
• Nothing is auto-created. Every item you want in GEM is a zone you add by hand with the exact item name.

For tighter, real-time, two-way interop, a message bus is usually a better fit than this poll-based bridge — see MQTT (openHAB can publish and subscribe on the same broker) or, for standards-based device sharing, Matter.

Troubleshooting

Symptom	Check
Zone state never updates	The zone Address must equal the openHAB Item name exactly — names are case-sensitive. Confirm the item exists and the REST API returns it.
A command returns a 404	The item exists but the command does not fit its type (for example ON to a Number item). Match the GEM command to the openHAB item type.
Nothing reaches openHAB at all	Confirm Host IP / HTTP Port point at the openHAB REST API, Protocol matches (http vs https), and the API is reachable from the GEM controller without a login.
High CPU on the GEM controller	Too many items polled too often. Raise Status Poll Interval (ms), or reduce the number of mapped zones.

Related

• Devices — creating the openHAB device and its connection attributes.
• Zones — binding a zone to the device and setting its Address to the item name.
• Subsystems — where each zone lives and how its state is grouped.
• Commands — how on / off / level / pulse verbs route to a device.
• Attributes — adding a state_map to a zone.
• MQTT, Matter — alternative, real-time interop paths.