Omnibus VRF (REST)

HTTPS/JSON integration for a Omnibus protocol-adapter gateway's VRF/HVAC port. Omnibus taps a manufacturer's indoor-unit bus and normalizes every indoor unit, then exposes them over a REST API. GEM speaks only HTTPS + JSON to the gateway — there is no serial wiring or bus protocol knowledge in GEM; Omnibus does all of that.

One Omnibus VRF port becomes one GEM device row; each indoor air handler becomes a climate zone addressed by its bus id (for example 20.2.4).

The integration is validated against Samsung DVM-S (the NASA bus). Daikin, Mitsubishi, LG, and Toshiba share the identical REST contract — only the mode / fanSpeed enum sets and the unit address format differ, and the driver reads those from the gateway rather than hardcoding them, so no driver change is needed per brand.

What this integration covers

• Power — on / off per indoor unit.
• Mode — the gateway-advertised modes (Samsung: auto, cool, dry, fan, heat), mapped to GEM system_mode; off powers the unit down.
• Setpoint — single target temperature per unit. Default presentation is °F (writes setpointF, whole degrees); switchable to °C (writes setpointC).
• Fan speed — the gateway-advertised speeds (Samsung: auto, low, mid, high, turbo). Common GEM synonyms (medium→mid, very_strong→turbo, …) are bridged automatically.
• Status polling of on/off, mode, room temperature, setpoint, fan speed, humidity, thermostat demand, and the unit fault code — refreshed from the gateway's cached snapshot on the poll interval.
• Auto-discovery — the driver enumerates indoor units from the status snapshot and (by default) creates a climate zone per unit. Each zone's name is derived from the gateway-reported unit label (e.g. Livingroom Climate → livingroom_climate), falling back to a device+unit slug when the unit has no name. Zones are deduped by address, so renaming a unit only affects display naming, not which zone it maps to. The unit label carries no device prefix, so when the derived name is already taken by another zone the unit's bus id is appended to the name — see auto-created zones.
• Gateway health tags on the device row — brand, gateway_mode, dry_run, writes_live, controller, crc_fail, parse_errors, frame counters.

What this integration does NOT cover (yet)

• Push updates. The status snapshot is a cached, periodically-broadcast view; a change made elsewhere appears at the next poll (within poll_interval), not instantly. The gateway also publishes the same state over MQTT — a future event-driven alternative to polling — but this driver uses the REST poll path.
• Dry-run / mode control. Whether the port is in sniffer/poll vs control, and whether dry-run is on, is an operator decision on the Omnibus panel. The driver reflects these as read-only device tags and flags writes that can't actuate; it never flips them.
• Dual heat/cool setpoints. A VRF indoor unit has a single setpoint; the setpoint command accepts a mode argument for climate-UI compatibility but always applies that one setpoint.
• Hardware-confirmed power/mode/fan on Samsung. Only the setpoint write is hardware-confirmed today; power/mode/fan writes are functional-but-unverified until the operator confirms on real equipment.

Prerequisites

• The Omnibus gateway reachable from the GEM host over HTTPS.
• An admin account on the gateway. Every per-port rest/* action — including the read-only status — requires an admin token, so the driver polls and writes with the same admin credentials.
• The gateway's VRF port configured with the indoor-unit adapter (e.g. Samsung VRF / DVM-S) and seeing decoded bus frames.
• To actuate writes: the operator must set the port to control mode with dry-run OFF on the Omnibus panel. In sniffer/poll or dry-run, writes are accepted and echoed but nothing transmits.

Setup steps

1. In GEM, go to System → Devices → Add Device (Open Devices) and pick Omnibus VRF (REST) as the driver.
2. Enter ip (the gateway host), port (default 443), and the admin username / password.
3. Leave port_path blank to have the driver auto-select the gateway's VRF/REST port, or set it explicitly. The driver matches your value against both the canonical device path and the /dev/ttyUSBx display path, and URL-encodes it for you.
4. Choose tls:
   • verify (default) pins the gateway's internal CA, fetched once (unauthenticated, a public/stable credential) from /api/system/ca-cert. It works whether you reach the gateway by LAN IP, local hostname or a tunnel hostname.
   • insecure skips verification. Use it only if the gateway presents a certificate its own CA did not sign.
5. Set setpoint_unit (F default, or C).
6. Save. The driver authenticates, polls status, and auto-creates one climate zone per indoor unit (address = bus id, e.g. 20.2.4). Run the discover command to list the units the gateway reports.

Subsystem placement

Auto-created zones are placed under the Climate subsystem. If your site has no climate subsystem, the driver creates one. The subsystem only affects grouping/presentation, not whether commands work.

TLS and the gateway certificate

The gateway serves HTTPS with a leaf certificate signed by an internal CA. The names on that certificate can't be relied on: some gateways list only 127.0.0.1, which no LAN IP or hostname you connect by will ever match.

• In verify mode the driver downloads the CA once and pins it. It then accepts the gateway's certificate only if that CA signed it, but it does not check the certificate against the IP or hostname you connected by. Trust comes from the pinned CA, so the same setting works by LAN IP, local hostname or a remote tunnel.
• A certificate the gateway's CA did not sign — the gateway's certificate was regenerated or replaced — is still refused. Reload the device to re-fetch the CA; if the error persists, insecure skips verification altogether. Insecure mode is opt-in and logged.
• The CA itself is fetched over an unverified connection the first time the driver connects, so pinning protects against a certificate changing later, not against something impersonating the gateway on that first connection.

Earlier versions also checked the hostname in verify mode, so a gateway whose certificate names only 127.0.0.1 failed with Hostname/IP does not match certificate's altnames: IP: <gateway ip> is not in the cert's list: 127.0.0.1. Current versions don't raise that error.

Attribute reference

Device attributes

Name	Type	Required	Description
ip	string	yes	LAN IP or hostname of the Omnibus gateway.
username	string	yes	Admin account (the status action needs an admin token).
password	string	yes	Admin password (stored encrypted).
port	int	no	Gateway HTTPS port (default 443).
port_path	string	no	VRF port device path. Blank = auto-select the VRF/REST port. Accepts the /dev/ttyUSBx display path or the canonical /dev/serial/by-id/... path.
tls	string	no	verify (default: pin the gateway CA, no hostname check) or insecure (skip verification).
setpoint_unit	string	no	F (default) writes setpointF; C writes setpointC.
poll_interval	int	no	Status poll cadence in ms (default 3000; floor 1000).
stale_after	int	no	Mark a unit stale when now - lastSeen exceeds this, in ms (default 120000).
request_timeout	int	no	Per-call HTTP timeout in ms (default 5000).
confirm_writes	bool	no	After a write, verify the field reflects the commanded value within ~10 s; flag the zone if not (default false).
auto_create_zones	bool	no	Create a climate zone per discovered indoor unit (default true).
brand, gateway_mode, dry_run, writes_live, controller, crc_fail, parse_errors, frames_seen, frames_decoded	—	Read-only gateway status/health, set from the snapshot. writes_live is true only when gateway_mode = control and dry_run = false.

Zone attributes

Name	Type	Description
address	string	Indoor-unit bus id, e.g. 20.2.4 (required).
state	string	on / off.
system_mode	string	off when the unit is off, otherwise the running mode (cool / heat / auto / dry / fan).
device_mode	string	The unit's actual running mode (modeReal) regardless of power.
setpoint	int	Target temperature in the configured setpoint_unit.
temperature	int	Current room temperature in the configured setpoint_unit.
fan_mode	string	The current fan speed (auto / low / mid / high / turbo).
humidity	int	Relative humidity %, if the unit is equipped.
demand	bool	true while the thermostat is calling (thermoOn).
fault	string	The unit's error code; empty when errorCode is 0.
stale	bool	true when the unit stopped broadcasting past stale_after. Tags are retained, not deleted.
system_modes / fan_modes	json	Capability lists published once so the climate UI renders the right buttons.
min / max	int	Setpoint bounds (60–90 °F, or 16–32 °C).
room_temp_c / room_temp_f / setpoint_c / setpoint_f	number	Both-unit mirrors so an operator can pick the display.
mode_real / fan_real / capacity / unit_name / last_seen	—	Read-only diagnostics mirrored from the snapshot.
write_simulated	bool	Set true when the last write was accepted but could not actuate (port not in control, or dry-run).
write_unconfirmed	bool	With confirm_writes on, true when a commanded change did not read back within the window.

Commands

Command	Args	Notes
on / off	address	Power the unit ({power: true/false}).
system_mode	address, mode	off powers the unit off; any other (gateway-advertised) mode powers it on and selects that mode. Out-of-range modes are rejected before any call.
fan_mode	address, mode	The gateway-advertised speeds; common GEM synonyms are bridged.
setpoint	address, setpoint, mode	Target temperature in the configured unit. Writes setpointF (whole °F) or setpointC — never both. mode is accepted for UI compatibility; the unit has a single setpoint. Rapid changes are debounced.
swing	address, mode	off / vertical / horizontal / both. Samsung: not hardware-confirmed.
get_temperature / get_system_mode / get_fan_mode	address	Return the last-polled value for the zone.
discover	—	List the indoor units the gateway currently reports.
get_status	—	Return the raw gateway status snapshot.

How state mapping works

• Temperature units. The gateway returns both °C and °F for every unit. setpoint_unit selects which mirror feeds the canonical setpoint / temperature tags and which field a write targets (setpointF whole-degree, or setpointC). Both *_c and *_f mirrors are always exposed.
• Off vs. mode. The climate UI treats "off" as a mode. When a unit is off the driver reports system_mode = off while preserving the real selection in device_mode; selecting a non-off mode sends {mode, power: true} so the unit powers on and switches in one write.
• Writes are serialized and audited. All sets run through a single queue so the gateway is never flooded; each set is logged with the unit, the changes, the gateway's dryRun/queued flags, and the hex it transmitted. The zone shows a new mode or fan speed only after the gateway accepts the set. If the gateway refuses it, or it could not be sent, the zone keeps its current values and the command returns an error.
• Dry-run / non-control is surfaced, not hidden. When the port can't actuate, the gateway still accepts the set and echoes the hex it would send; the driver returns simulated: true and sets the zone's write_simulated tag so operators aren't misled.
• Auth and recovery. The admin token (12 h sliding TTL, in-memory on the gateway) is cached and refreshed proactively; any 401 triggers a transparent re-login and one retry. The poll loop runs unconditionally with backoff, so a gateway reboot or transient outage recovers automatically.

Troubleshooting

Symptom	Check
Authenticates but no zones appear	Run discover, or check the Omnibus panel — the VRF port may be configured but not yet seeing decoded indoor-unit frames.
Writes "succeed" but the unit never changes	The port is in sniffer/poll or dry-run. Check the gateway_mode / dry_run / writes_live device tags and the zone's write_simulated; set the port to control with dry-run OFF on the Omnibus panel.
Connection fails with a TLS / certificate error	The gateway presented a certificate its own CA did not sign (regenerated or replaced), or the CA could not be fetched from /api/system/ca-cert. Reload the device to re-fetch the CA; if it persists, set tls = insecure.
Repeated "authentication failed" in the log	Bad admin credentials. The driver backs off (it won't hammer /api/login) and stays in an auth-failed state until corrected.
A zone shows stale	The indoor unit stopped broadcasting (now - lastSeen exceeded stale_after). Check the unit / bus; the zone tags are kept, not deleted.
Setpoint write rejected with a control-mode error	The gateway returned 409 — the port is not in control mode. This is surfaced as a clear fault and not retried blindly.