Home Assistant Bridge v3.5

Custom Control Drivers LLC

Connects RTI XP processors to Home Assistant via WebSocket. Exposes up to 100 HA entities across 14 domains as addressable RTI sources with auto-binding to standard templated buttons (lighting, HVAC, transport, NP).

New in v3.5: Climate upgrades. Up to 20 climate devices (was 10). Current and target temperatures are also available with one decimal place (for example 22.5). Temp Up and Temp Down can now move in 1 degree, 0.5 degree, or each device's own step (new Temp Up/Down Step setting in the Climate category, default 1 degree as before), plus new Temp Up 0.5 and Temp Down 0.5 commands. New fan speed control for air conditioners and mini-splits: Set Fan Mode, Fan Mode Next and Fan Mode Previous, plus one-press Fan Auto, Fan On, Fan Cycle, Fan Low, Fan Medium and Fan High commands that auto-bind to templated fan buttons, with the current fan mode and the list of available fan modes shown by name. Existing projects keep every binding: nothing that was already there was renamed or renumbered. Also new: the driver now reports to the processor System Log (XP Diagnostics), with a status summary every 5 minutes and every error logged (see Reading the System Log under Troubleshooting). Templated climate pages now show each thermostat's own readings (before, every templated climate page could show Climate 1's; pages bound on an earlier version keep their bindings until the source is re-added). Reliability: Verify TLS Certificate now reads the certificate status correctly (earlier versions reported every certificate as not trusted on an https URL, so only False worked), a License Key or access token pasted with an extra space or line break now works, the driver now always retries after a failed secure (https) or WebSocket handshake, Entity IDs typed with capital letters now work, and an Entity ID Home Assistant would reject (for example one with a space or a hyphen) now skips only that slot, with an error naming it, instead of stopping every entity.

New in v3.4: Now-playing artwork served through Home Assistant's media proxy (e.g. Apple TV and other players whose art HA hosts) now displays reliably on RTI panels — the driver passes Home Assistant's own signed image link through unchanged, so it stays authorized instead of coming back blank.

New in v3.3: Sensor and Binary Sensor monitoring — bring any Home Assistant temperature, humidity, power, energy, battery, motion, contact, occupancy (and more) reading into RTI for display and macro triggers. Plus a faster write-on-change state engine, an optional Startup Delay for heavily-loaded racks, and all per-entity driver Events now fire reliably for macro wiring.

Requirements

Home Assistant Core 2022.4 or newer (for the subscribe_entities API)

A Home Assistant Long-Lived Access Token (HA Profile, Security, Long-Lived Access Tokens)

HA reachable from the RTI processor on the same network

RTI XP-3, XP-6, or XP-8 processor

Up to 100 Home Assistant entities total exposed to the bridge. See Supported Scale below.

Supported Scale

Important: the supported configuration is up to 100 Home Assistant entities/devices total across all domains. The driver is tested at this scale.

Going beyond 100 entities is not supported and is at your own risk. Symptoms of over-loading on a real processor include slow state-change propagation, memory pressure on the processor, dropped WebSocket frames, and increased reconnect frequency. If your Home Assistant install has more than 100 entities, filter the entities exposed to the bridge before connecting RTI — only configure the entities you actually plan to control or display, leaving the unused slots blank.

The per-domain caps (50 lights, 30 switches, 25 scenes, etc. - see Adding entities below) are upper bounds on what fits in the configuration UI. The 100-entity total is the supported real-world scale across the whole driver instance. For typical installs running other drivers alongside, 40-60 configured entities is the recommended target.

Setup

Connection Settings

HA URL - full URL to your HA server, e.g. http://192.168.1.100:8123. Give the HA server a DHCP reservation or a static IP address: the driver connects to the address entered here, so if the server's address changes, the driver cannot find it.

Long-Lived Access Token - paste from HA

Verify TLS Certificate - True for valid certs, False for self-signed

License Key - leave blank for the 2-hour trial

Adding entities

Each domain has its own slot grid (Lights, Switches, Scenes, etc.). Slots reveal one at a time - fill slot 1's Entity ID and slot 2 appears.

Entity ID is the HA entity_id (light.kitchen, media_player.family_room). Home Assistant entity IDs are lowercase and the driver lowercases what you type. An Entity ID containing a character Home Assistant does not allow (anything other than lowercase letters, numbers and _ after the dot, such as a space or a hyphen) is skipped, and LastError and the System Log name the slot. Copy Entity IDs from Home Assistant (Settings, Entities) to avoid typos.

Name is the friendly label shown in RTI's variable picker, function dropdowns, and event lists.

Note: renaming a source in the workspace tree only changes its label there. The Entity ID and Name fields above are independent and must be filled in here directly. This is by design.

Caps per domain: Lights 50, Switches 30, Scenes 25, Scripts 25, Fans 20, Covers 20, Locks 10, Cameras 10, Alarm Panels 5, Climate 20, Media Players 8, Vacuums 5, Sensors 30, Binary Sensors 30. Global cap: 100 entities total.

For typical installs running other drivers alongside, 40-60 entities is the recommended target.

Advanced settings

Under the Advanced category (defaults are fine for most installs):

Subscribed HA Events - optional comma-separated HA event_type names to forward into RTI macros via the HA Event Received event.

Reconnect Backoff Max - maximum delay (seconds) between reconnect attempts. Default 30, range 5-300.

Startup Delay (seconds) - seconds to wait after boot before first connecting to Home Assistant. Default 0 (connect almost immediately). On a heavily-loaded processor running many drivers, set this to 30-45: Home Assistant's initial state sync is the bridge's single heaviest moment, and delaying the connect keeps that work off the boot storm so the rest of your system - panels and other drivers - comes up responsive first. The bridge then syncs a few seconds later. (Validated on a real XP-8 running ~15 drivers and 100+ HA entities.) Range 0-300.

Auto-binding workflow

Each configured entity becomes an addressable RTI source. To use templated buttons:

1. In your panel project, open a panel room.

2. Add the source for that room (e.g. add the source named "Climate: 1st Floor" to the upstairs page).

3. Drag a templated button from RTI's library - Stat Heat, Stat Cool, Volume Up, Skip Forward, NP Title text, etc. RTI auto-binds via sourceid + buttontag, no manual variable picking needed.

Supported buttontags

HVAC - Stat Mode, Stat Off, Stat Heat, Stat Cool, Stat Auto, Stat Setpoint, Stat Setpoint Up, Stat Setpoint Down, Stat Temp In, Stat Operating State, Stat Fan State, Stat Fan Mode, Stat Fan Auto, Stat Fan On, Stat Fan Cycle, Fan Low, Fan Medium, Fan High

Audio and Transport - Play, Pause, Stop, Volume Up, Volume Down, Mute, Skip Forward, Skip Back, Thumbs Up, Thumbs Down

Now Playing - NP Title, NP Artist, NP Album, NP Cover, NP Progress

Lighting - Light Level, Instance ID

Domain notes

Cameras are state-only (idle / streaming / recording) for triggering macros. For live video, point an RTI RTSP Video tile directly at the camera's native RTSP URL (Unifi Protect: port 7447, drop the ?enableSrtp). HA does not expose a stream the RTSP tile can consume.

Climate - temperature values use whatever unit your HA thermostat reports (F or C). The driver does NOT convert. Heavy-traffic domain - HA pushes current_temperature drift frequently.

Decimal temperatures. The Current Temp, Target Temp, Target Temp Low and Target Temp High variables are whole numbers (unchanged from earlier versions). Each also has a (Decimal) twin, a text variable with one decimal place (74.3, 75.0). Bind the Decimal variables to any text field that should show tenths.

Temp Up/Down Step (Climate category setting) controls how far the Temp Up and Temp Down commands move the setpoint: 1 degree (default, same as earlier versions), 0.5 degree, or Device step, which uses the step the climate entity reports to Home Assistant (1 if it reports none). With 0.5 degree, the setpoint moves to the next half degree (21.3 becomes 21.5 going up). With Device step, the setpoint moves by the entity's own step, as Home Assistant's thermostat card does (75 becomes 77 on a device with a 2-degree step). Both stay within the entity's minimum and maximum temperature.

Temp Up 0.5 / Temp Down 0.5 move to the next half degree, whatever the setting (for example 21.5 goes to 22.0, and 21.3 goes to 21.5).

Half degrees need a thermostat that accepts them. The driver sends the half-degree setpoint to Home Assistant; a thermostat that only accepts whole degrees (or a 2-degree step) rounds it, so the setpoint may not change. For those, use Device step.

Fan speed. Fan Mode (Name) shows the current fan mode exactly as Home Assistant reports it (for example low, medium, high, auto), and Fan Modes Available lists every mode the device supports. Set Fan Mode takes a mode name (not case-sensitive), Fan Mode Next and Fan Mode Previous step through the device's own list and wrap around. The older Fan Mode number and Fan Mode is Auto / On / Cycle variables are unchanged; air conditioner speeds read as Other (99) there, so use the name variables for them.

Fan presets. Fan Auto, Fan On, Fan Cycle, Fan Low, Fan Medium and Fan High are one-press commands that auto-bind to templated fan buttons (Fan Mode Next binds to Stat Fan Mode). Each sends the name your device uses (Fan Cycle also matches circulate, Fan Medium also matches mid). If the device does not offer that mode, nothing is sent and the System Log lists the modes it does offer.

Media Players - the driver exposes the full media_player.* command surface so any HA-supported media player (LG webOS, Roku, Sonos, Echo, Chromecast, Plex, Apple TV, etc.) can be controlled natively. Available commands:

Power: Turn On, Turn Off (LG TVs typically need Wake-on-LAN configured for Turn On)

Transport: Play, Pause, Stop, Play/Pause, Next Track, Previous Track, Seek (position in seconds)

Volume: Volume Up, Volume Down, Set Volume (0-100), Mute Toggle

Source/Mode: Select Source, Select Sound Mode (both case-sensitive strings - copy EXACTLY from HA's source_list / sound_mode_list, or read from the readback variables described below)

Queue/Library: Play Media (Content Type + Content ID + Enqueue Mode: Play Now / Add / Next / Replace), Clear Playlist

Shuffle/Repeat: Shuffle Set (On/Off), Set Repeat Mode (Off / All / One)

Announce: Plays a TTS message or audio URL with announce:true, ducking the current playback (great for Echo, Sonos, Google Cast)

Grouping: Group (comma-separated member entity_ids - joins them under this master via media_player.join), Ungroup (media_player.unjoin)

Each command checks the entity's supported_features at HA's end. If the integration doesn't support a feature, HA silently rejects the call - check supported_features in HA Developer Tools → States before relying on a specific command for an entity.

Readback variables (use for panel feedback / dynamic UIs): Shuffle On (bool), Repeat Mode (string), Sound Mode (string), Sound Mode List (comma-separated), Group Members (comma-separated), Source List (comma-separated), Supported Features (integer bitmask), plus the existing Playing / Paused / Stopped / Muted / Volume / Current Source / Media Title / Artist / Album / Progress / Duration / Elapsed / Elapsed Text / Image. The Sound Mode List and Source List variables let you build a dynamic picker in RTI without hard-coding source names per project.

NP Progress requires the player to report media_position AND media_duration; most AVRs and Pandora-routed audio do not. Use Media Elapsed Text (live counter) instead for those. NP Cover persists across HA token rotation.

Alarm Panels - arming codes are configured on the HA side. The driver fires alarm_arm_home / alarm_arm_away / alarm_disarm services without code parameters.

Sensors (read-only, new in v3.3) - bring any HA sensor.* reading into RTI: temperature, humidity, power, energy, battery, illuminance, air quality, or text/enum sensors. Each slot exposes Value (the raw HA state as text, e.g. 72 or sunny), Value With Unit (a pre-joined string for one-button display, e.g. 72 F), Unit (HA's unit_of_measurement), Device Class (HA's device_class, e.g. temperature), and Available / Unavailable. Bind Value or Value With Unit to a button's text for a live readout, or wire the Came Online / Went Offline events to macros. Sensors are display-only — there are no commands. Note: some sensors (power meters, energy monitors) update very frequently; the v3.3 write-on-change engine suppresses unchanged values, but only configure the sensors you actually need.

Binary Sensors (read-only, new in v3.3) - bring any HA binary_sensor.* into RTI: motion, occupancy, presence, door/window contact, moisture, smoke, and more. Each slot exposes State (1 = On, 0 = Off), On and Off booleans, Device Class, and Available / Unavailable. On = detected / open / wet; Off = clear / closed / dry; an unavailable or unknown sensor leaves both On and Off false. Per-slot Turned On / Turned Off events fire on transitions for clean macro triggers (e.g. "if Front Door Turned On then..."). Binary sensors are display/trigger-only — there are no commands.

Troubleshooting

The driver recovers automatically from network outages, HA reboots, and gateway resets. No manual intervention is needed; reconnection happens once the network is reachable again.

The LastError sysvar shows the most recent failure. Common values:

"Could not reach Home Assistant at host:port" - network or firewall issue

"Authentication failed - check long-lived access token" - token bad or expired

"Heartbeat timeout - reconnecting" - HA stopped responding to pings; driver auto-reconnects

"Connection lost (...) - reconnecting" - transport went dead mid-session; driver auto-reconnects

"Connect attempt timed out - retrying" - the HA host did not answer, or answered but did not complete the secure (TLS) or WebSocket handshake in time; driver retries with backoff

"Driver start-up failed (...)" - the driver could not finish starting; re-send the driver, and if it repeats, contact support@customcontroldrivers.com

"WebSocket upgrade failed (HTTP ...)" - HA reachable but the upgrade was refused; check the HA URL and token

"TLS handshake failed" / "TLS certificate not trusted (...)" - https URL with a cert mismatch, or self-signed without Verify TLS set to False

"Home Assistant URL not configured" / "Long-lived access token not configured" - fill in those Configuration Properties fields

"Light 2: '...' is not a valid entity ID (only a-z 0-9 _ allowed) - slot skipped" - that slot's Entity ID has a character Home Assistant does not allow; correct it (every other entity keeps working)

"Home Assistant rejected the entity subscription (...)" - Home Assistant refused the list of Entity IDs; the reason is in brackets

"Entity cap of 100 reached - N configured entities were not loaded" - more than 100 entities are configured; the extra ones are not loaded

The LicenseStatusText sysvar shows the current license state, separate from LastError:

"Licensed" - valid license key installed

"Trial: N min remaining" - trial running, counter persists across reboots

"Trial expired - license required" - no license installed; commands stop accepting; paste a license key to restore

System Commands include:

Force Reconnect - drops and re-auths immediately, for example after restarting Home Assistant. (Changes to the driver's settings take effect when the project is sent to the processor.)

Refresh HA Rooms - re-fetches HA's area registry. Use after re-assigning entities in HA.

Fire HA Event - fires any HA event_type with optional JSON payload. Useful for triggering HA automations directly from RTI macros.

Call HA Service - universal escape hatch for any HA service call against any entity in any domain. See Raw HA service calls below for parameter details and worked examples.

Reading the System Log

The driver writes to the processor's System Log: in Integration Designer connect to the processor, open System Log, and switch on messages for this driver (the System Log does not remember that choice after a project is sent, so switch it back on after each send). Lines start with HomeAssistantBridge:.

At the default Debug Level (Low), the driver writes a short status summary every minute for the first 5 minutes after the processor starts, then every 5 minutes: status: (connected or not, HA version, entity count, time since HA last sent anything), health: (reconnect, failure and timeout counters), env: (driver version and build, license state, trial minutes), config: (HA host and port, whether a token is set, processor MAC). The token itself is never written to the log.

Connection changes (connected, disconnected) are logged as they happen, and every error (connection and license problems, commands Home Assistant rejects, commands that could not be sent, and Entity ID mistakes) is logged regardless of Debug Level (the same error at most once a minute).

XP Diagnostics starts a little after the drivers do, so lines from the first moments after a reboot may not appear. The status summary repeats, so wait for the next one.

While every driver is loading after a reboot, the processor can briefly refuse to start one of this driver's timers. The driver logs it (a line ending the status loop will restart the connection) and restarts the connection by itself within about a minute; nothing needs to be done. If LastError (or a System Log line) says Driver start-up failed, the driver could not finish starting: re-send the driver, and if it repeats, contact support@customcontroldrivers.com.

Set Debug Level to High (3) under Debug Settings to also see each message the driver sends to Home Assistant, and the size of each message it receives, in the System Log. Drop to Low (1) for normal operation.

Raw HA service calls

Call HA Service is the universal escape hatch - it maps directly to Home Assistant's underlying service-call mechanism and fires any service in any domain against any entity. This includes domains and services this driver does not expose natively (notify, vacuum send_command, homeassistant.restart, scripts with parameters, custom integrations - anything HA can do).

Macro step → Home Assistant Bridge → System Commands → Call HA Service.

Parameters:

Domain - HA domain (light, switch, media_player, notify, climate, scene, script, etc.)

Service - service name within that domain (turn_on, toggle, volume_set, set_temperature, etc.)

Entity ID - HA entity_id to target. Leave blank for global services like homeassistant.restart.

Service Data JSON - optional JSON payload. Leave blank for services that take no data.

Example 1 - simple raw command (no payload):

Domain: light

Service: turn_on

Entity ID: light.ceiling

Service Data JSON: (blank)

Turns the ceiling light on.

Example 2 - raw command with JSON payload:

Domain: light

Service: turn_on

Entity ID: light.ceiling

Service Data JSON: {"brightness_pct": 50}

Turns the ceiling light on at 50% brightness. Any parameter HA's Developer Tools → Services panel lists for a given service (brightness_pct, transition, color_name, rgb_color, effect, etc.) can be passed this way.

Notes:

The call is fire-and-forget - the driver does not surface HA's response back to RTI as a variable.

Home Assistant rejects invalid service names, malformed JSON, and unknown entities. The driver writes Home Assistant's reason to the System Log (at any Debug Level). Verify the exact service name and payload in HA's Developer Tools → Services panel before wiring into a macro.

For looking up available services and their parameters, HA's Developer Tools → Services panel shows every domain and service registered on your HA instance.

License

Runs on a 2-hour trial when no license key is installed. The trial counter persists across reboots. Paste a valid license key in the License Key field to bypass the trial; existing license keys keep working on this version. The 2-hour timer resumes from where it left off if a license is later removed. Each new version of the driver starts a fresh 2-hour trial, so a new version can always be evaluated. Once the trial has ended, commands are refused until a license is installed; Home Assistant status keeps updating.

The License Valid, License Invalid and Trial Expiring events fire exactly as in earlier versions. The events marked (fleet tag) fire at the same moments, and also when the processor starts with the trial already expired (where the earlier events, as before, do not fire); they carry the event names our other drivers use, for dealers who want one naming scheme across drivers.

Support

Custom Control Drivers LLC - customcontroldrivers.com - support@customcontroldrivers.com