Home Assistant Driver for RTI

SETUP

1. This driver requires a small free companion proxy to be installed and running somewhere on your network, alongside Home Assistant - it works around a compatibility issue between RTI's built-in HTTP object and Home Assistant's WebSocket API (the connection would otherwise repeatedly fail to authenticate). Download it and see full install/setup instructions at https://goldknighttech.ca/homeassistant-proxy.html - this must be done before step 2 below, since the driver connects to the proxy, not to Home Assistant directly.

2. In Home Assistant, go to your user profile (click your name, bottom left) > Security > Long-Lived Access Tokens > Create Token. Copy it immediately - it is only shown once.

3. In this driver's Home Assistant Connection settings, enter the Host/IP Address and Port of the machine running the proxy from step 1 (not Home Assistant's own port), plus the Long-Lived Access Token from step 2. Enable "Use SSL" only if the proxy is reachable via https/wss (e.g. behind a reverse proxy).

4. This driver keeps a single persistent WebSocket connection open (via the proxy) to Home Assistant's native WebSocket API (/api/websocket) - it is used both to receive real-time feedback and to send every command, so button feedback updates instantly instead of polling and no separate REST connection is needed.

5. To get real-time feedback for an entity, open one of the 100 "Entity Monitor" categories and enter its entity id (e.g. "light.kitchen", "switch.fan", "sensor.living_room_temperature", exactly as shown in Home Assistant under Settings > Devices & Services > Entities) plus a friendly name. Leave unused slots blank.

6. Each configured slot exposes four System Variables (State, On, Numeric Value, Brightness) and three Events (Changed, On, Off) you can bind to buttons and feedback in the RTI Integration Designer. Numeric Value is useful for sensors (temperature, humidity, battery, etc.) and is the entity's state rounded to the nearest whole number. Brightness (0-100) comes from the light's brightness attribute, not its state, and resets to 0 when the light is off (Home Assistant reports brightness as null, not a number, while off).

7. For richer media player feedback (now-playing title/artist/album/artwork, volume, shuffle/repeat, source, sound mode), use one of the 8 "Media Player Monitor" slots instead of a generic Entity Monitor slot - these are separate so the other 100 slots aren't cluttered with media-only fields they'd never use. See MEDIA PLAYERS below.

CONTROL

"Turn On", "Turn Off", and "Toggle" work with any entity id - the driver automatically calls the matching domain's service (e.g. light.turn_on, switch.turn_off) based on the entity id's prefix. These do not require an Entity Monitor slot to be configured.

"Light Control" sets brightness, RGB color, or color temperature via light.turn_on. Color Temperature uses Kelvin (color_temp_kelvin), which requires Home Assistant Core 2023.9 or later - on older versions, set it instead via "Call Service" under Advanced with Service Data "color_temp": <mireds> (mireds = 1000000 / Kelvin).

SLIDERS (e.g. dimmer brightness)

In Integration Designer, a Slider's drag value can only be bound to an integer-type Driver Command parameter, and its feedback can only be bound to an integer-type System Variable. "Set Brightness" already takes an integer "Brightness % (0-100)" parameter, so bind a Slider's command directly to it (fix Entity ID to a constant in the binding); bind the Slider's feedback to that same entity's Entity Monitor slot Brightness variable.

"Climate Control" sets target temperature or HVAC mode on a climate entity.

"Cover Control" opens, closes, stops, or sets the position of a cover (blind/garage door/etc).

"Media Player Control" plays, pauses, stops, sets volume/mute, seeks, shuffles, sets repeat mode, selects source/sound mode, plays arbitrary media, groups/ungroups speakers, or announces an audio URL (ducking playback) on a media_player entity - see MEDIA PLAYERS below for details and readback variables.

"Scenes & Scripts" activates a scene or runs a script by entity id.

"Lock Control" locks or unlocks a lock entity (lock.lock / lock.unlock).

"Fan Control" sets a fan's speed 0-100% (fan.set_percentage); 0% turns the fan off instead of calling set_percentage with 0, since not every fan integration turns off cleanly that way.

"Vacuum Control" starts, pauses, stops, or sends a vacuum entity back to its dock.

"Alarm Panel Control" arms (home/away) or disarms an alarm_control_panel entity; Code is optional and only needed if your alarm panel integration requires one.

MEDIA PLAYERS

Configure a "Media Player Monitor" slot (Entity ID + Friendly Name, same pattern as Entity Monitor) to get now-playing feedback: Title, Artist, Album, Image URL (a direct link - bind it to an image widget), Duration/Position in seconds, State, Playing/Paused booleans, Volume %, Muted, Shuffle On, Repeat Mode, Source, Source List (comma-separated, build a dynamic picker instead of hard-coding source names), Sound Mode, Sound Mode List, and Available. Position/Duration reflect Home Assistant's last-known values rather than a live-ticking counter - most integrations (AVRs, Pandora-routed audio, etc.) don't report these reliably enough for a smooth live counter to be worth building.

Select Source / Select Sound Mode take exact strings as Home Assistant reports them (case-sensitive) - read them from that entity's Source List / Sound Mode List variables rather than guessing. Play Media takes a Content Type (e.g. "music", "url") and Content ID (a URL or Home Assistant media id) and maps to media_player.play_media. Announce plays a given audio URL with announce:true, which most players duck the current playback for instead of interrupting it - for text-to-speech messages, use "Call Service" under Advanced against your own Home Assistant instance's TTS integration/entity, since these vary per install. Group takes a comma-separated list of member entity ids and joins them under this entity as the master (media_player.join); Ungroup splits them back apart.

ADVANCED

"Call Service" under Advanced calls any Home Assistant service directly - supply the Domain (e.g. "light"), Service (e.g. "turn_on"), an optional Entity ID, and optional Service Data as a JSON object (e.g. "brightness_pct": 50, "color_name": "red") for fields not otherwise exposed.

"Fire Event" sends an arbitrary event onto the Home Assistant event bus (e.g. to trigger an automation), with optional Event Data as a JSON object.

SYSTEM COMMANDS

"Force Reconnect" immediately drops and re-establishes the connection, bypassing wherever the automatic reconnect backoff currently is - use this after changing Connection settings without wanting to redeploy the whole driver.

CONNECTION TUNING

"Reconnect Interval" is the starting delay before retrying after a disconnect; it doubles on each consecutive failed attempt up to "Reconnect Backoff Max", then resets back to the starting value once a connection actually succeeds - this avoids hammering a Home Assistant instance (or the companion proxy) that's down for an extended period with connection attempts at a fixed short interval forever.

"Startup Delay" delays this driver's very first connection attempt after the processor boots. On a heavily-loaded processor running many drivers, set this to 15-30 seconds so this driver's initial full-state sync (which is its single heaviest moment) doesn't compete with everything else coming up at once.

TROUBLESHOOTING

If the connection repeatedly logs "Websocket upgrade failed" or keeps disconnecting right after connecting without ever authenticating, confirm the companion proxy from SETUP step 1 is actually installed and running, and that this driver's Host/Port point at the proxy - not directly at Home Assistant. This driver cannot connect to Home Assistant without it.

The "Last Error" system variable holds a short, human-readable description of the most recent connection problem (e.g. "Could not reach Home Assistant at host:port", "Authentication failed - check Long-Lived Access Token", "Heartbeat timeout - reconnecting") - check this first before digging into the TraceViewer.

Enable "Enable Trace" in the Connection settings and open the RTI TraceViewer to see the raw websocket traffic (auth, subscribe_events, call_service, get_states, events). If authentication fails, regenerate the Long-Lived Access Token and confirm the clock on the RTI processor and Home Assistant are both reasonably accurate. If entity feedback events never fire, confirm the Entity ID entered exactly matches Home Assistant's own entity id (including the domain prefix, e.g. "light." not just the object id). Check "Last Command Result" after a command if a button appears to do nothing - it reports OK or the error returned by Home Assistant.

LICENSING

This driver includes a 2-hour free trial, starting the first time it connects. After the trial, go to https://goldknighttech.ca or email qinghuaatbc@yahoo.ca, with this driver's Mac Address (shown in this driver's own SystemVariables) to purchase a permanent authorization code. Enter the code into the "Authorization Code" config field and redeploy the driver.