ESPHome Device v2.4: RTI Driver

Control any ESPHome device from RTI, with no Home Assistant required.

One driver for every ESPHome device. It connects straight to your ESP8266 or ESP32, finds everything it can do (lights, switches, dimmers, covers, fans, locks, buttons, numbers, selects, climate, and every kind of sensor) and gives you two-way control and feedback on your RTI panels and remotes.

It works with encrypted devices (the modern default). And because an ESP32 running ESPHome can act as a Bluetooth bridge, it even reaches BLE-only gear (adjustable beds, locks, sensors) that RTI can't control on its own.

WHAT THIS DRIVER IS

If your device runs ESPHome, this driver controls it directly, over your network, with no Home Assistant, no cloud, and nothing to program by hand. Add the driver, point it at the device, click one button to import every control by its real name, and drag those onto your pages. That's the whole job.

WHAT'S NEW IN 2.4

We checked every message this driver sends and reads against ESPHome's own published protocol and device source code, and fixed everything that did not match.

Covers open and close again on current ESPHome firmware. ESPHome 2025.8 stopped acting on the old open/close command this driver used, so on devices flashed since then Cover Open and Cover Close did nothing. They now use the position command (fully open or fully closed), which ESPHome accepts on every cover, including ones that cannot report a position. Older firmware still works.

Thermostats now use your temperature units. ESPHome thermostats work in Celsius unless they say otherwise. The new Temperature Units setting (Fahrenheit by default) converts every temperature in both directions, and a setpoint outside the thermostat's own range is limited to that range and noted in the System Log. Before 2.4, a setpoint of 70 was sent as 70 degrees Celsius.

Fan speed is a percentage. ESPHome fans have a fixed number of speeds (often 3). Set Speed and the Speed variable now use 0 to 100 percent and convert to the fan's own speeds, so a slider works across its whole travel.

Less work inside the device's handshake time limit. The secure handshake involves two heavy calculations. The driver now does the first one before it contacts the device, so only one runs while the device is timing the connection.

Clear answers when a connection fails. If a device closes the connection during the secure handshake, Last Error now says why, including the case of ESPHome 2026.3.0 firmware, which allows only 15 seconds for that step (2026.3.1 and newer allow 60).

Stable on current ESPHome firmware. ESPHome 2026.7.0 and newer no longer send each control's ID, which made the order of unnamed controls, and the Object ID variables, depend on the firmware version. The driver now rebuilds the ID exactly the way ESPHome does, and it checks each one against the device, so a firmware update no longer moves controls between slots. If a reconnect ever finds the controls in different slots, the System Log says so.

ESPHome sub-devices are supported. Controls that belong to a sub-device (ESPHome 2025.7 and newer) are now addressed correctly and named "Sub-device Control".

Valves. Open, Close, Toggle, Stop and Set Position, with position and open/closing feedback.

Recovers from its own start-up problems. If the processor is too busy to start one of the driver's timers, or a start-up step fails, the driver now retries by itself or names the problem in Last Error, instead of sitting silently disconnected.

Connection rules now match Home Assistant's. Keepalive, reconnect timing and connection errors follow the same rules as Home Assistant's published ESPHome client. The driver pings a quiet device every 20 seconds and rebuilds the link if nothing comes back within 90 seconds. A send that fails rebuilds the link at once. A device that asks to disconnect (for a reboot or a firmware update) gets 5 seconds before the driver reconnects. Last Error now names each encryption mismatch the way Home Assistant does.

Sized for the RTI processor where it has to be. The processor does the encryption math in software, so two things differ from Home Assistant on purpose. A device that keeps dropping the connection within two minutes of connecting is retried with a growing delay instead of immediately. A wrong Encryption Key is retried every minute for three tries, then every 10 minutes. A wrong API Password costs no encryption work, so the driver keeps retrying it every minute.

An expired trial now disconnects. When the trial ends without a license, the driver disconnects from the device and stops updating its values, instead of staying connected. Entering a license reconnects it automatically.

Get Config keeps every slot variable. The numbered slot variables (for example a thermostat's low and high setpoints) now stay available after Get Config, alongside the named ones.

Controls without their own name (ESPHome's recommended setup for a device's main control) now show the device's name instead of a blank.

Locks now report Opening and Open, and names containing emoji display correctly.

UPDATING FROM 2.3 OR EARLIER

Updating the driver in an existing project replaces its function list, and Integration Designer can then lose the link between your buttons and the named functions that Get Config created. When that happens the buttons do nothing and no error appears. After you update:

Select the driver and click Get Config from ESPHome Device again.

Open one macro that uses a named function (for example Bed Head Up). If it shows Select a function, choose the function again, and check your other named buttons the same way.

Buttons built with the numbered slot functions (for example Button Press with a slot number) and the slot variables are not affected by this (but see the note on ESPHome 2026.7.0 and newer below).

Two values also mean something different in 2.4, so check them if you used them on 2.3:

Thermostat temperatures now follow the Temperature Units setting, which is Fahrenheit by default. If you programmed setpoints in Celsius on 2.3, set Temperature Units to Celsius.

Fan Set Speed is now a percentage. A 2.3 value of 1, 2 or 3 now selects the fan's lowest speed; for a 3-speed fan use 33, 66 and 100.

If the device runs ESPHome 2026.7.0 or newer, controls that have no name of their own can land in a different slot than they did on 2.3, and a named button made by the old Get Config could then operate a different control on the device. To prevent that, the update removes the named functions in this case, so a macro that used one shows Select a function instead of operating the wrong control. Running Get Config again (step 1) recreates them correctly. Buttons and variables that use slot numbers are not protected this way: in a control type (switches, lights, buttons and so on) that includes a control with no name, the slots can move by one. Check each slot's Name variable (for example Switch01_Name) and pick the slot numbers again where they moved.

WHAT'S NEW IN 2.3

It now notices if the device stops listening. Previously the driver treated any incoming data as proof the connection was healthy. Most ESPHome devices publish sensor readings on their own schedule, so that traffic kept arriving even in the rare case where the driver's own commands were no longer getting through, and the driver had no way to tell the difference. It now checks that the device actually answers, and rebuilds the connection if it stops answering (2.4 uses Home Assistant's timing for this: a check every 20 seconds while the device is quiet, and a rebuild when it has not answered for 90 seconds). Nothing to configure.

Every command is confirmed onto the network. If the processor ever refuses a send, the driver detects it, keeps the secure session in step with the device, and recovers instead of carrying on as though the command went out.

Recovery is guaranteed. Rebuilding the connection is now scheduled no matter what else happens while the old one is being torn down.

It reports for itself in the System Log. The driver now writes to the processor's System Log (Integration Designer, enter the processor IP, System Log), including a short status summary every minute for the first five minutes after a reload and every five minutes after that, so there is something to look at whenever you happen to check rather than only in the seconds after a reload. Real faults are always logged regardless of the Debug Level.

New status variables for diagnosing a link at a glance: Mute Recoveries, Connect Stalls, Watchdog Trips, and Last Handshake ms.

WHAT'S NEW IN 2.2

Rock-solid under load. A device with lots of controls sends the state of everything at once the moment it connects. The driver now takes that in small batches instead of all in one go, so it never ties up the processor or loses its own connection while catching up. It stays responsive even on a busy system running many drivers.

Smarter reconnect timing. If a connection ever stalls, the driver now retries in step with the device's own timeout, so it recovers quickly instead of waiting too long.

Cleaner disconnects. When you reconnect or the processor reboots, the driver now tells the device it's leaving, so the device frees the connection right away and the next connect is clean.

WHAT'S NEW IN 2.1

Self-healing connection. If the secure connection ever stalls while connecting (for example right after the device reboots) the driver now notices and reconnects on its own, instead of sitting there until you reload it.

Everything from 2.0 still applies: one-click AutoConfig, support for encrypted devices, and very light CPU once the one-time key exchange is done.

SET IT UP

You do everything in Integration Designer. No app, no terminal.

1. Add the driver and enter the connection settings. Add one ESPHome Device driver per device, select it, and fill in its settings:

Device IP Address: your device's IP, e.g. 192.168.1.50. Give it a static IP or DHCP reservation so it never changes. (RTI connects by IP, not a hostname.)

Port: leave at 6053 (the ESPHome default).

Encryption Key: paste your device's base64 key (see Finding your encryption key below). Leave blank only for older, unencrypted devices.

License Key: paste your purchased key, or leave it blank to start the 2-hour free trial.

Startup Delay (seconds): leave at 30 for now (explained in Options).

Temperature Units: Fahrenheit or Celsius, for thermostat temperatures on your panels and in the climate functions.

2. Import your controls: click "Get Config from ESPHome Device". With the driver selected, look in the Driver Configuration panel (left side, just below Driver Info) and click Get Config from ESPHome Device. It's a normal single click.

The driver connects, reads every control on the device, and creates functions and feedback variables labeled with the device's real names ("Living Room Lamp On," "Bed Head Up") grouped by type. No guessing what a button does, and no slot numbers to fill in by hand. Run it again any time the device's controls change, after updating the device's ESPHome firmware, and after updating this driver.

3. Place your controls. Drag the named functions onto your page buttons (e.g. Bed Head Up) and bind the named variables for feedback. Done.

4. Give the first connection a minute or two. Watch Connection State and Status Text. After a reboot, an encrypted device takes up to a minute or two to come online. This happens only once per reboot:

First it waits out the Startup Delay so your other drivers finish booting. Status Text shows "Waiting 30s before connecting..."

Then it prepares its half of the encryption key before contacting the device. Status Text shows "Preparing secure connection..."

Then it makes its secure connection. Status Text then shows "Connected - N entities".

After that it stays connected, and day-to-day button presses and feedback are instant. The startup wait only happens after a processor reboot or driver reload.

About that first connection: high CPU is normal. Encrypted devices do a one-time security handshake (an elliptic-curve key exchange) when they connect. On RTI hardware that handshake is heavy: it briefly pushes this driver's CPU high (and bumps its memory) while it runs. This is expected, it is a one-time cost paid only on connect, and it self-recovers. The moment the handshake finishes, CPU drops back to near zero and stays there. You'll see the same brief spike if the device reboots and the driver reconnects. The Startup Delay above exists to hold this handshake off until your other drivers have finished booting, so it has the processor to itself. If you run many drivers on one processor, raise the Startup Delay (90–120s) so the handshake never competes with the boot. (Plaintext devices skip the handshake entirely and connect instantly.)

FINDING YOUR ENCRYPTION KEY

Modern ESPHome devices have API encryption on by default, and for those the key is required (the device won't connect without it). You do not need Home Assistant to get it; it lives in the device's own ESPHome config:

From the ESPHome Dashboard (the usual way): open the device you flashed and look at its YAML (often secrets.yaml). The key is under:

api:

encryption:

key: "<your 44-character base64 key>"

Copy that exact 44-character value into Encryption Key.

From Home Assistant (only if you use it): Settings - Devices & Services - ESPHome - (your device) - Encryption key.

The key is write-only on the device: it can only be read from your config, never pulled back off the ESP. If it's lost, re-flash the device with a new key. If a device needs a key and the field is empty, Last Error says so; paste the key and send the project to the processor, and the driver connects after its Startup Delay.

OPTIONS

Startup Delay (seconds): how long to wait after the processor boots before connecting (default 30, range 0–300). Encrypted devices do a one-time, CPU-heavy security handshake on connect, so delaying it lets your other drivers finish booting first and gives the handshake room to complete. Raise it on a heavily-loaded processor (90–120); lower it (even to 0) if you want the device online sooner on a quiet one.

Temperature Units: Fahrenheit (default) or Celsius. Every thermostat temperature the driver shows or sends is in these units; the driver converts to whatever unit each ESPHome thermostat uses. A setpoint outside the thermostat's own range is limited to that range, and the System Log notes it.

API Password: only for legacy devices that set a plaintext API password. Most devices use the Encryption Key instead; leave this blank if yours has none.

Debug Level: how much detail the driver writes to the processor's System Log (enter the processor IP in Integration Designer, then click System Log). Low is the default and is right for normal use: it includes the five-minute status summary, which is what makes the log worth opening later. Raise it to High only while troubleshooting. Real faults are always logged regardless of this setting.

WHAT YOU CAN CONTROL

AutoConfig surfaces only the controls your device actually has, named for what they are:

Lights / dimmers: On, Off, Toggle, Set Brightness, with on/off and brightness feedback.

Switches / relays: On, Off, Toggle + state.

Covers / shades / garage doors: Open, Close, Stop, Set Position + position and operation feedback.

Valves: Open, Close, Toggle, Stop, Set Position + position and operation feedback.

Fans: On, Off, Set Speed (0 to 100 percent; 0 turns the fan off) + speed feedback in percent.

Locks: Lock, Unlock, Open + lock-state feedback.

Buttons: Press, to fire any momentary control on the device (great for BLE-bridged gear like beds).

Numbers: Set Value (sliders, setpoints) + value, min/max feedback.

Selects: Set By Index (choose from the device's option list) + current selection.

Climate / thermostats: Set Mode, Target Temp, Target Temp Range, Fan Mode, Swing Mode, Preset + current temperature, target, action, and mode feedback, all in your Temperature Units. Use Target Temp for a single-setpoint thermostat and Target Temp Range for a heat/cool (low/high) one; the System Log says so if the wrong one is used.

Sensors / binary sensors / text sensors: read as values, on/off states, and text.

The driver also raises events (Connected, Disconnected, Entities Discovered, State Changed, plus license and trial events) so device changes can trigger RTI macros.

A note on safety: AutoConfig automatically omits the device's Factory Reset and Safe Mode buttons (nobody needs those on a touchpanel) and tucks ESP Restart into a System category alongside Reconnect and Refresh All.

MANUAL SETUP (OPTIONAL, WITHOUT AUTOCONFIG)

The driver works the moment you add it, even before you run AutoConfig: discovered controls fill numbered slots by type, and each slot's ..._Name variable shows the control's real name. Bind your pages to the slot variables (for example Light01_Name, Light01_State, Light01_Brightness, Cover01_Position, Climate01_CurrentTemp) and drive them with the slot command functions, picking the slot number from each function's dropdown.

Heads-up: slots are ordered alphabetically by name, so a "Button 1" isn't always the one you'd expect. Check the matching Button##_Name variable before assigning a Button Press, or just use Get Config, which names every button for you and hides the dangerous ones.

IF IT WON'T CONNECT

Check Last Error first. It names the problem in plain language:

"requires an encryption key": the device is encrypted; paste its key into Encryption Key.

"Could not reach ESPHome device...": check the IP address, that the device is powered and on your network, and that the Port is 6053.

"The device closed the connection right after our encrypted hello": first check that the device is not restarting and is not already serving as many API clients as it allows (Home Assistant and every other connected client each use one; ESPHome closes any connection past its limit right away). Otherwise the device may not use API encryption: if its ESPHome config has no encryption: key, clear the Encryption Key setting.

"The device accepted the connection and closed it before it finished connecting": the same two checks, the device restarting or at its API client limit. The driver retries on its own.

"Not connected to the device since the driver started": several attempts have failed and nothing more specific was reported. The System Log names the reason for each attempt.

"This ESPHome device does not use API encryption, but an Encryption Key is set": clear the Encryption Key setting (or turn on encryption in the device's ESPHome config) and send the project.

"...ESPHome 2026.3.0 firmware allows 15 seconds for this step": update the device to ESPHome 2026.3.1 or newer.

"...near its 60-second limit": raise Startup Delay so the connection is made after the processor's other drivers have settled.

"The device rejected the Encryption Key": the key does not match the device's api: encryption: key. Correct it and send the project to the processor; the driver reloads with the new setting and connects after its Startup Delay. Until then it retries every minute, then every 10 minutes after three tries.

"wrong API password": the API Password does not match the device. Correct it and send the project; until then the driver retries every minute.

"The secure connection was refused by the device (...)": the device gave the reason shown in brackets. The driver retries on its own; if it keeps happening, update the device's ESPHome firmware.

"The device did not finish sending its entity list": the device took longer than 60 seconds to list its controls. The driver retries on its own; if it repeats, check that the device is not overloaded or restarting.

"The data from the device could not be read": something other than the ESPHome native API answered on that address and port, or the stream was damaged. The driver reconnects on its own; if it repeats, check the Device IP Address and Port.

"Driver start-up failed" or "The driver failed to start": the processor refused something the driver needs at start-up. The driver keeps retrying the connection on its own; if the message stays, re-send the driver.

A handshake that stalls now retries on its own (new in 2.1). Give it the minute-or-two startup window before assuming it failed.

Two System functions are always there if you need them: Reconnect (drop and rebuild the link) and Refresh All (re-pull every control's current state). While a connection is still being made, or waiting out the Startup Delay, Refresh All lets it finish instead of starting over, so it is safe on a page-open macro.

IF IT CONNECTS BUT NOTHING RESPONDS

If Connection State reads true, the controls were found, and yet nothing happens when you press a button, first check that the button still has its function (see Updating from 2.3 or earlier). Then check Mute Recoveries. The driver watches for this itself, by the same rules as Home Assistant: when the device goes quiet it pings it every 20 seconds and rebuilds the link if nothing comes back within 90 seconds, a send that fails rebuilds the link at once, and a device that can no longer hear the driver closes the connection itself after about two and a half minutes, which the driver answers by reconnecting. A count above 0 means the device went silent and the link was rebuilt.

If the count keeps climbing, the link is being rebuilt repeatedly. Raise Startup Delay and check Last Handshake ms: on a processor running many drivers, the secure handshake needs room to finish, and Connect Stalls rising alongside it points at the same cause.

STATUS & LICENSING

The Status variables show connection state, device info (name, model, MAC, ESPHome version), how many controls were found, and the reconnect count. The Licensing variables show your trial or license status. The driver reconnects on its own if the device drops, goes silent, or stops accepting what the driver sends.

Four counters are there for diagnosing a link at a glance. The first three sitting at 0 on a connection that has been up a while is exactly what a healthy system looks like (Last Handshake ms is a duration, not a count, so it is never 0 after an encrypted connect):

Mute Recoveries: times the device went silent after a ping and the link was rebuilt.

Connect Stalls: connection attempts abandoned because the secure handshake did not finish in time. On a heavily loaded processor, raising Startup Delay gives it more room.

Watchdog Trips: times a backup check found no traffic at all for two and a half minutes and rebuilt the link. Normally 0.

Last Handshake ms: how long the last secure handshake took. Useful for judging whether a processor is under load, since the handshake is the most CPU-heavy thing the driver does.

LICENSE

Each copy of the driver in your project (one per ESPHome device) runs its own 2-hour free trial. To license it permanently, purchase a key at customcontroldrivers.com and paste it into License Key. The license is locked to that processor. When the trial ends without a license, the driver disconnects from the device: it stops sending commands and stops updating the device's values and events. Status Text and Last Error say why, and the Licensing variables keep updating. Entering a license reconnects it automatically.

SUPPORT

Questions or issues: support@customcontroldrivers.com

Custom Control Drivers LLC customcontroldrivers.com