Home Assistant Bridge v3.0

Custom Control Drivers LLC

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

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

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).

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 10, Media Players 8, Vacuums 5. Global cap: 100 entities total.

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

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 Auto, Stat Fan On, Stat Fan Cycle

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.

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.

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" - connect attempt hung (HA host unreachable); driver retries with backoff

"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

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. Use after configuration changes.

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.

Set Debug Level to High (3) under Debug Settings to see WebSocket TX/RX in the trace viewer. 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.

Invalid service names, malformed JSON, or unreachable entities cause HA to silently reject the call. 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. The 2-hour timer resumes from where it left off if a license is later removed.

Support

Custom Control Drivers LLC - customcontroldrivers.com