From 4e33bfa46369d1e2e65fa8c21428270ff8531071 Mon Sep 17 00:00:00 2001 From: Derek Miller Date: Tue, 12 May 2026 09:58:18 -0500 Subject: [PATCH 1/2] Release v20260512 --- CHANGELOG.md | 2 +- README.md | 769 +++++++++++++++++++++++++++------------------------ 2 files changed, 407 insertions(+), 364 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1119aa8..4fa8a1f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,7 +12,7 @@ [//]: # "- Removed" -## Unreleased +## v20260512 - 2026-05-12 ### Added diff --git a/README.md b/README.md index f952454..b545f2b 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,19 @@ ESPHome ---- +------------------------------------------------------------------------ # Overview -> DISCLAIMER: This software is neither affiliated with nor endorsed by either -> Control4 or ESPHome. +> DISCLAIMER: This software is neither affiliated with nor endorsed by +> either Control4 or ESPHome. -Integrate [ESPHome-based devices](https://devices.esphome.io) into Control4. -ESPHome is an open-source system that transforms common microcontrollers, like -ESP8266 and ESP32, into smart home devices through simple YAML configuration. -ESPHome devices can be set up, monitored, and controlled using a web browser, -Home Assistant, or other compatible platforms. This driver enables seamless -monitoring and control of ESPHome devices directly from your Control4 system. +Integrate [ESPHome-based devices](https://devices.esphome.io) into +Control4. ESPHome is an open-source system that transforms common +microcontrollers, like ESP8266 and ESP32, into smart home devices +through simple YAML configuration. ESPHome devices can be set up, +monitored, and controlled using a web browser, Home Assistant, or other +compatible platforms. This driver enables seamless monitoring and +control of ESPHome devices directly from your Control4 system. # Index @@ -36,7 +37,8 @@ monitoring and control of ESPHome devices directly from your Control4 system. - [Programming Reference](#programming-reference) - [Configuration Guides](#configuration-guides) - [ratgdo Configuration Guide](#ratgdo-configuration-guide) - - [Bluetooth Proxy Configuration Guide](#bluetooth-proxy-configuration-guide) + - [Bluetooth Proxy Configuration + Guide](#bluetooth-proxy-configuration-guide) - [Support](#support) - [Changelog](#changelog) @@ -51,8 +53,8 @@ monitoring and control of ESPHome devices directly from your Control4 system. # Features - Local network communication requiring no cloud services -- Real-time updates from all [supported entities](#supported-esphome-entities) - exposed by the device +- Real-time updates from all [supported + entities](#supported-esphome-entities) exposed by the device - Supports encrypted connections using the device encryption key - Variable Programming Support @@ -60,25 +62,26 @@ monitoring and control of ESPHome devices directly from your Control4 system. ## Verified Devices -This driver will generically work with any ESPHome device, but we have tested -extensively with the following devices: +This driver will generically work with any ESPHome device, but we have +tested extensively with the following devices: -- [ratgdo](https://ratcloud.llc) - - [Configuration Guide](#ratgdo-configuration-guide) +- [ratgdo](https://ratcloud.llc) - [Configuration + Guide](#ratgdo-configuration-guide) -If you try this driver on a product listed above, and it works, let us know! +If you try this driver on a product listed above, and it works, let us +know! ## Supported Bluetooth Devices -When used as a Bluetooth proxy, this driver supports the following BLE device -types through sub-drivers: +When used as a Bluetooth proxy, this driver supports the following BLE +device types through sub-drivers: -| Protocol | Sub-Driver | Example Devices | -| ----------- | ----------------- | ---------------------------------------------------- | -| SwitchBot | ESPHome SwitchBot | Bot, Plug Mini, Relay Switch, Meter, Motion, Contact | -| BTHome | ESPHome BTHome | Shelly BLU Button/Door/Motion/H&T, DIY sensors | -| Govee | ESPHome Govee | Temperature/humidity monitors, meat thermometers | -| Yale/August | ESPHome Yale | Yale and August smart locks | +| Protocol | Sub-Driver | Example Devices | +|----|----|----| +| SwitchBot | ESPHome SwitchBot | Bot, Plug Mini, Relay Switch, Meter, Motion, Contact | +| BTHome | ESPHome BTHome | Shelly BLU Button/Door/Motion/H&T, DIY sensors | +| Govee | ESPHome Govee | Temperature/humidity monitors, meat thermometers | +| Yale/August | ESPHome Yale | Yale and August smart locks | See the individual sub-driver documentation for device-specific details. @@ -89,7 +92,7 @@ See the individual sub-driver documentation for device-specific details.
| Entity Type | Supported | -| ------------------- | ----------------------------- | +|---------------------|-------------------------------| | Alarm Control Panel | ❌ | | API Noise | ✅ | | Binary Sensor | ✅ | @@ -122,23 +125,23 @@ See the individual sub-driver documentation for device-specific details. -> \* Voice Assistant requires a speech-to-text and intent processing pipeline -> (e.g. Home Assistant Assist). Control4 does not natively provide voice intent -> handling, so this entity type is not supported. +> \* Voice Assistant requires a speech-to-text and intent processing +> pipeline (e.g. Home Assistant Assist). Control4 does not natively +> provide voice intent handling, so this entity type is not supported.
# Installer Setup -> ⚠️ Only a **_single_** driver instance is required per ESPHome device. -> Multiple instance of this driver connected to the same device will have -> unexpected behavior. However, you can have multiple instances of this driver -> connected to **_different_** ESPHome devices. +> ⚠️ Only a ***single*** driver instance is required per ESPHome device. +> Multiple instance of this driver connected to the same device will +> have unexpected behavior. However, you can have multiple instances of +> this driver connected to ***different*** ESPHome devices. ## Driver Installation -Driver installation and setup are similar to most other ip-based drivers. Below -is an outline of the basic steps for your convenience. +Driver installation and setup are similar to most other ip-based +drivers. Below is an outline of the basic steps for your convenience. 1. Download the latest `control4-esphome.zip` from [Github](https://github.com/finitelabs/control4-esphome/releases/latest). @@ -150,29 +153,30 @@ is an outline of the basic steps for your convenience. 3. Use the "Search" tab to find the "ESPHome" driver and add it to your project. - > ⚠️ A **_single_** driver instance is required per ESPHome device. + > ⚠️ A ***single*** driver instance is required per ESPHome device. ![Search Drivers](images/search-drivers.png) -4. Configure the [Device Settings](#device-settings) with the connection - information. +4. Configure the [Device Settings](#device-settings) with the + connection information. -5. After a few moments the [`Driver Status`](#driver-status-read-only) will - display `Connected`. If the driver fails to connect, set the - [`Log Mode`](#log-mode--off--print--log--print-and-log-) property to `Print` - and re-set the [`IP Address`](#ip-address) field to reconnect. Then check - the lua output window for more information. +5. After a few moments the [`Driver Status`](#driver-status-read-only) + will display `Connected`. If the driver fails to connect, set the + [`Log Mode`](#log-mode--off--print--log--print-and-log-) property to + `Print` and re-set the [`IP Address`](#ip-address) field to + reconnect. Then check the lua output window for more information. 6. Once connected, the driver will automatically create variables and connection bindings for each supported entity type. -7. To control climate, lights, fans, locks, and/or water heaters, use the - "Search" tab to find the "ESPHome Climate", "ESPHome Light", "ESPHome Fan", - and/or "ESPHome Lock" driver. For fans, choose the speed variant that - matches your fan (e.g., "ESPHome Fan (3 Speed)"). Water heater entities use - the "ESPHome Climate" driver. Add one driver instance for each exposed - entity in your project. In the "Connections" tab, select the "ESPHome" - driver and bind the entities to the newly added drivers. +7. To control climate, lights, fans, locks, and/or water heaters, use + the "Search" tab to find the "ESPHome Climate", "ESPHome Light", + "ESPHome Fan", and/or "ESPHome Lock" driver. For fans, choose the + speed variant that matches your fan (e.g., "ESPHome Fan (3 Speed)"). + Water heater entities use the "ESPHome Climate" driver. Add one + driver instance for each exposed entity in your project. In the + "Connections" tab, select the "ESPHome" driver and bind the entities + to the newly added drivers. ## Driver Setup @@ -180,14 +184,14 @@ is an outline of the basic steps for your convenience. #### Cloud Settings -##### Automatic Updates \[ Off \| **_On_** \] +##### Automatic Updates \[ Off \| ***On*** \] Enables or disables automatic driver updates from GitHub releases. -##### Update Channel \[ **_Production_** \| Prerelease \] +##### Update Channel \[ ***Production*** \| Prerelease \] -Sets the update channel for which releases are considered during automatic -updates from GitHub releases. +Sets the update channel for which releases are considered during +automatic updates from GitHub releases. #### Driver Settings @@ -199,85 +203,87 @@ Displays the current status of the driver. Displays the current version of the driver. -##### Log Level \[ 0 - Fatal \| 1 - Error \| 2 - Warning \| **_3 - Info_** \| 4 - Debug \| 5 - Trace \| 6 - Ultra \] +##### Log Level \[ 0 - Fatal \| 1 - Error \| 2 - Warning \| ***3 - Info*** \| 4 - Debug \| 5 - Trace \| 6 - Ultra \] Sets the logging level. Default is `3 - Info`. -##### Log Mode \[ **_Off_** \| Print \| Log \| Print and Log \] +##### Log Mode \[ ***Off*** \| Print \| Log \| Print and Log \] Sets the logging mode. Default is `Off`. -##### Device Log Forwarding \[ **_Off_** \| On \] +##### Device Log Forwarding \[ ***Off*** \| On \] -Forward ESPHome device logs to the driver's Lua output at the current Log Level. -Changing Log Level or disabling Log Mode will reconnect to apply the new -settings. +Forward ESPHome device logs to the driver's Lua output at the current +Log Level. Changing Log Level or disabling Log Mode will reconnect to +apply the new settings. #### Device Settings ##### IP Address -Sets the device IP address (e.g. `192.168.1.30`). Domain names are allowed as -long as they can be resolved to an accessible IP address by the controller. -HTTPS is not supported. +Sets the device IP address (e.g. `192.168.1.30`). Domain names are +allowed as long as they can be resolved to an accessible IP address by +the controller. HTTPS is not supported. -> ⚠️ If you are using an IP address, you should ensure it will not change by -> assigning a static IP or creating a DHCP reservation. +> ⚠️ If you are using an IP address, you should ensure it will not +> change by assigning a static IP or creating a DHCP reservation. -##### Port \[ 1 - 65535, default: **_6053_** \] +##### Port \[ 1 - 65535, default: ***6053*** \] Sets the device port. The default port for ESPHome devices is `6053`. -##### Authentication Mode \[ **_None_** \| Password \| Encryption Key \] +##### Authentication Mode \[ ***None*** \| Password \| Encryption Key \] Selects the authentication method for connecting to the ESPHome device. - **None**: No authentication required. - **Password**: Use a password for authentication (see below). -- **Encryption Key**: Use an encryption key for secure communication (see - below). - -> **Tip:** For ESPHome devices used primarily as Bluetooth proxies, consider -> configuring the firmware without API encryption. In busy BLE environments, the -> volume of proxy traffic combined with the controller's limited cryptographic -> performance can cause significant CPU load. BLE traffic is inherently -> over-the-air, and sensitive protocols (such as Yale/August lock commands) use -> their own end-to-end encryption between the driver and the device, making it -> safe to relay through an unencrypted proxy. To disable encryption, omit the +- **Encryption Key**: Use an encryption key for secure communication + (see below). + +> **Tip:** For ESPHome devices used primarily as Bluetooth proxies, +> consider configuring the firmware without API encryption. In busy BLE +> environments, the volume of proxy traffic combined with the +> controller's limited cryptographic performance can cause significant +> CPU load. BLE traffic is inherently over-the-air, and sensitive +> protocols (such as Yale/August lock commands) use their own end-to-end +> encryption between the driver and the device, making it safe to relay +> through an unencrypted proxy. To disable encryption, omit the > `encryption` block from the ESPHome `api:` configuration and set > Authentication Mode to `None`. ##### Password -Shown only if -[Authentication Mode](#authentication-mode--none--password--encryption-key-) is -set to `Password`. Sets the device password. This must match the password +Shown only if [Authentication +Mode](#authentication-mode--none--password--encryption-key-) is set to +`Password`. Sets the device password. This must match the password configured on the ESPHome device. ##### Encryption Key -Shown only if -[Authentication Mode](#authentication-mode--none--password--encryption-key-) is -set to `Encryption Key`. Sets the device encryption key for secure -communication. This must match the encryption key configured on the ESPHome -device. +Shown only if [Authentication +Mode](#authentication-mode--none--password--encryption-key-) is set to +`Encryption Key`. Sets the device encryption key for secure +communication. This must match the encryption key configured on the +ESPHome device. -##### Use OpenSSL \[ **_Yes_** \| No \] +##### Use OpenSSL \[ ***Yes*** \| No \] -Use OpenSSL for encryption. This should typically be left at the default value -of `Yes` for better performance and compatibility. +Use OpenSSL for encryption. This should typically be left at the default +value of `Yes` for better performance and compatibility. #### Bluetooth Proxy Settings > The Bluetooth Proxy feature requires an ESP32 device with the -> `bluetooth_proxy` component configured in ESPHome. See the -> [ESPHome Bluetooth Proxy documentation](https://esphome.io/components/bluetooth_proxy.html) -> for firmware configuration. +> `bluetooth_proxy` component configured in ESPHome. See the [ESPHome +> Bluetooth Proxy +> documentation](https://esphome.io/components/bluetooth_proxy.html) for +> firmware configuration. ##### Bluetooth Proxy Status (read-only) -Shows the current state of the Bluetooth proxy. The format is a pipe-separated -list of status components: +Shows the current state of the Bluetooth proxy. The format is a +pipe-separated list of status components: **Standalone Mode:** `Standalone Mode | Scanning (Passive) | 1/4 Active` @@ -286,41 +292,43 @@ list of status components: Components explained: -- **Mode** - "Standalone Mode" or "Coordinator Mode" depending on whether the - driver is connected to a Bluetooth Coordinator -- **Scanner State** - Current state (Idle, Starting, Running, Stopping, Stopped, - Failed) and mode (Passive or Active) -- **Connection Slots** - Shows "used/total Active" slots (e.g., "1/4 Active" - means 1 slot in use out of 4 available). If you select more active devices - than available slots, "(Oversubscribed)" is appended (see - [Oversubscription](#oversubscription)) -- **MAC Filter** - (Coordinator mode only) Shows how many device MACs are being - filtered for, or "none" if forwarding all advertisements +- **Mode** - "Standalone Mode" or "Coordinator Mode" depending on + whether the driver is connected to a Bluetooth Coordinator +- **Scanner State** - Current state (Idle, Starting, Running, Stopping, + Stopped, Failed) and mode (Passive or Active) +- **Connection Slots** - Shows "used/total Active" slots (e.g., "1/4 + Active" means 1 slot in use out of 4 available). If you select more + active devices than available slots, "(Oversubscribed)" is appended + (see [Oversubscription](#oversubscription)) +- **MAC Filter** - (Coordinator mode only) Shows how many device MACs + are being filtered for, or "none" if forwarding all advertisements ##### Bluetooth Proxy Capabilities (read-only) -Displays a comma-separated list of capabilities supported by this ESPHome -Bluetooth proxy: +Displays a comma-separated list of capabilities supported by this +ESPHome Bluetooth proxy: - **Scan** - Can receive BLE advertisements (passive scanning) -- **Connect** - Can establish GATT connections to devices (active connections) +- **Connect** - Can establish GATT connections to devices (active + connections) - **Cache** - Caches GATT service data remotely - **Pair** - Can pair with devices requiring authentication - **Raw** - Can receive raw advertisement data ##### Select Bluetooth Devices -> Only visible in **Standalone Mode** (hidden when connected to a Bluetooth -> Coordinator, as device selection is done there instead). +> Only visible in **Standalone Mode** (hidden when connected to a +> Bluetooth Coordinator, as device selection is done there instead). -A dropdown list showing discovered BLE devices. Select "Refresh List" to start a -new scan. +A dropdown list showing discovered BLE devices. Select "Refresh List" to +start a new scan. **During scanning:** - The dropdown displays "-- Scanning..." while the scan is in progress - Select "-- Stop Scan" to stop early and keep newly discovered devices -- Select "-- Abort Scan" to stop early and discard newly discovered devices +- Select "-- Abort Scan" to stop early and discard newly discovered + devices - When complete, the dropdown repopulates with discovered devices **Device list shows:** @@ -330,40 +338,43 @@ new scan. - Device Type (BTHome, SwitchBot, Govee, etc.) - Connection Type (Active/Passive) -After selecting a device, a connection binding is automatically created for the -appropriate sub-driver. +After selecting a device, a connection binding is automatically created +for the appropriate sub-driver. -> **Tip:** Some BLE devices (buttons, sensors with long advertisement intervals) -> may be in sleep mode. Wake them by pressing buttons, triggering motion -> sensors, or opening/closing contact sensors during the scan to ensure they -> appear in the device list. +> **Tip:** Some BLE devices (buttons, sensors with long advertisement +> intervals) may be in sleep mode. Wake them by pressing buttons, +> triggering motion sensors, or opening/closing contact sensors during +> the scan to ensure they appear in the device list. -##### Bluetooth Scan Duration \[ 5 - 60, default: **_30_** \] +##### Bluetooth Scan Duration \[ 5 - 60, default: ***30*** \] > Only visible in **Standalone Mode**. -Sets how long (in seconds) to scan for BLE devices when refreshing the device -list. Longer scans may discover more devices with long advertisement intervals. +Sets how long (in seconds) to scan for BLE devices when refreshing the +device list. Longer scans may discover more devices with long +advertisement intervals. ##### Bluetooth Proxy Room > Only visible in **Coordinator Mode** (when connected to a Bluetooth > Coordinator). -Sets the room where this Bluetooth proxy is physically located. This is used for -presence tracking to determine which room a device is in based on signal -strength. +Sets the room where this Bluetooth proxy is physically located. This is +used for presence tracking to determine which room a device is in based +on signal strength. -##### Minimum Room RSSI Override (dBm) \[ -100 - -40, default: **_-100_** \] +##### Minimum Room RSSI Override (dBm) \[ -100 - -40, default: ***-100*** \] > Only visible in **Coordinator Mode** (when connected to a Bluetooth > Coordinator). -Overrides the coordinator's global "Minimum Room RSSI" setting for this proxy's -room. Use this when a room has different size or characteristics than others. +Overrides the coordinator's global "Minimum Room RSSI" setting for this +proxy's room. Use this when a room has different size or characteristics +than others. - **-100 (default)** - Use the coordinator's global setting -- **-85** - More permissive; allow detection from further away (large rooms) +- **-85** - More permissive; allow detection from further away (large + rooms) - **-60** - More restrictive; require closer proximity (small rooms) **Examples:** @@ -372,9 +383,9 @@ room. Use this when a room has different size or characteristics than others. - Small bathroom: Set to `-60` to require closer proximity - Leave at `-100` to use the coordinator's global setting -> **Note:** Only affects room assignment for this proxy. The value is sent to -> the Bluetooth Coordinator when this proxy connects or when the setting -> changes. +> **Note:** Only affects room assignment for this proxy. The value is +> sent to the Bluetooth Coordinator when this proxy connects or when the +> setting changes. #### Device Info @@ -402,8 +413,8 @@ Displays the firmware version of the connected ESPHome device. #### Update Drivers -Trigger the driver to update from the latest release on GitHub, regardless of -the current version. +Trigger the driver to update from the latest release on GitHub, +regardless of the current version. #### Reset Driver @@ -411,26 +422,28 @@ the current version. > associated with the variables. Resets the driver to its initial state, removing all dynamically created -connections and variables. This is useful if you change the connected ESPHome -device or there are stale connections or variables. +connections and variables. This is useful if you change the connected +ESPHome device or there are stale connections or variables. **Parameters:** -- **Are You Sure?** \[ **_No_** \| Yes \] - Confirmation to reset the driver. +- **Are You Sure?** \[ ***No*** \| Yes \] - Confirmation to reset the + driver. ## Programming Reference -Once connected, the driver automatically creates variables and bindings for each -supported ESPHome entity. Use this reference for Control4 programming. +Once connected, the driver automatically creates variables and bindings +for each supported ESPHome entity. Use this reference for Control4 +programming. ### Driver Variables In addition to per-entity variables, the driver publishes the following -device-level variables sourced from the ESPHome device info. They mirror the -matching read-only Device Info properties. +device-level variables sourced from the ESPHome device info. They mirror +the matching read-only Device Info properties. | Variable | Type | Description | -| ------------ | ------ | -------------------------------------------- | +|--------------|--------|----------------------------------------------| | Name | STRING | Friendly name reported by the ESPHome device | | Model | STRING | Device model string reported by ESPHome | | Manufacturer | STRING | Manufacturer string reported by ESPHome | @@ -438,101 +451,105 @@ matching read-only Device Info properties. ### Variables by Entity Type -| Entity Type | Variable Name | Type | Notes | -| ------------- | ------------------- | ------ | ------------------------------------------ | -| Binary Sensor | `{name} State` | BOOL | "1" = triggered, "0" = clear | -| Button | (none) | \- | Use "Press Button" command (see below) | -| Climate | (none) | \- | State via Thermostat proxy | -| Cover | `{name} State` | STRING | "open", "closed", "opening", "closing" | -| Date | `{name}` | STRING | Writable, formatted as YYYY-MM-DD | -| Datetime | `{name}` | STRING | Writable, formatted as YYYY-MM-DD HH:MM:SS | -| Event | `{name} Last Event` | STRING | Last event type (e.g., "single_press") | -| Fan | (none) | \- | State via Fan proxy | -| Light | (none) | \- | State via Light proxy | -| Lock | (none) | \- | State via Lock proxy | -| Number | `{name}` | NUMBER | Writable, 1 decimal precision | -| Select | `{name}` | STRING | Writable, current option | -| Sensor | `{name}` | NUMBER | Read-only, 1 decimal precision | -| Switch | `{name} State` | BOOL | "1" = on, "0" = off (writable) | -| Text | `{name}` | STRING | Writable | -| Text Sensor | `{name}` | STRING | Read-only | -| Time | `{name}` | STRING | Writable, formatted as HH:MM:SS | -| Water Heater | (none) | \- | State via Thermostat proxy | - -> **Note:** `{name}` is replaced with the entity's display name from ESPHome -> (e.g., a sensor named "Temperature" creates a variable called "Temperature"). +| Entity Type | Variable Name | Type | Notes | +|----|----|----|----| +| Binary Sensor | `{name} State` | BOOL | "1" = triggered, "0" = clear | +| Button | (none) | \- | Use "Press Button" command (see below) | +| Climate | (none) | \- | State via Thermostat proxy | +| Cover | `{name} State` | STRING | "open", "closed", "opening", "closing" | +| Date | `{name}` | STRING | Writable, formatted as YYYY-MM-DD | +| Datetime | `{name}` | STRING | Writable, formatted as YYYY-MM-DD HH:MM:SS | +| Event | `{name} Last Event` | STRING | Last event type (e.g., "single_press") | +| Fan | (none) | \- | State via Fan proxy | +| Light | (none) | \- | State via Light proxy | +| Lock | (none) | \- | State via Lock proxy | +| Number | `{name}` | NUMBER | Writable, 1 decimal precision | +| Select | `{name}` | STRING | Writable, current option | +| Sensor | `{name}` | NUMBER | Read-only, 1 decimal precision | +| Switch | `{name} State` | BOOL | "1" = on, "0" = off (writable) | +| Text | `{name}` | STRING | Writable | +| Text Sensor | `{name}` | STRING | Read-only | +| Time | `{name}` | STRING | Writable, formatted as HH:MM:SS | +| Water Heater | (none) | \- | State via Thermostat proxy | + +> **Note:** `{name}` is replaced with the entity's display name from +> ESPHome (e.g., a sensor named "Temperature" creates a variable called +> "Temperature"). ### Bindings by Entity Type -| Entity Type | Binding Class | Purpose | -| ------------- | ------------------------------- | ----------------------------------------------------------------- | -| Binary Sensor | `CONTACT_SENSOR` | Integrates with Contact Sensor proxy | -| Switch | `RELAY` | Control via Relay proxy | -| Cover | `CONTACT_SENSOR` | Open/closed state contacts | -| Cover | `RELAY` | Open/close/stop control relays | -| Button | `BUTTON_LINK` | Allows other devices to trigger button | -| Climate | `ESPHOME_CLIMATE` | Bind to ESPHome Climate sub-driver [\*\*](#climate-services-note) | -| Fan | `ESPHOME_FAN_N_SPEED[_REVERSE]` | Bind to ESPHome Fan sub-driver | -| Light | `ESPHOME_LIGHT` | Bind to ESPHome Light sub-driver | -| Lock | `ESPHOME_LOCK` | Bind to ESPHome Lock sub-driver | -| Water Heater | `ESPHOME_CLIMATE` | Bind to ESPHome Climate sub-driver | - -> **Note:** Sensor, Number, Select, Text, Text Sensor, Date, Time, Datetime, and -> Event entities do not create bindings. They expose data only through variables -> and events. - -> **Note:** Water Heater entities share the `ESPHOME_CLIMATE` binding class and -> are controlled via the ESPHome Climate sub-driver. Device modes (such as Eco, -> Heat Pump, Gas) are exposed as presets. +| Entity Type | Binding Class | Purpose | +|----|----|----| +| Binary Sensor | `CONTACT_SENSOR` | Integrates with Contact Sensor proxy | +| Switch | `RELAY` | Control via Relay proxy | +| Cover | `CONTACT_SENSOR` | Open/closed state contacts | +| Cover | `RELAY` | Open/close/stop control relays | +| Button | `BUTTON_LINK` | Allows other devices to trigger button | +| Climate | `ESPHOME_CLIMATE` | Bind to ESPHome Climate sub-driver [\*\*](#climate-services-note) | +| Fan | `ESPHOME_FAN_N_SPEED[_REVERSE]` | Bind to ESPHome Fan sub-driver | +| Light | `ESPHOME_LIGHT` | Bind to ESPHome Light sub-driver | +| Lock | `ESPHOME_LOCK` | Bind to ESPHome Lock sub-driver | +| Water Heater | `ESPHOME_CLIMATE` | Bind to ESPHome Climate sub-driver | + +> **Note:** Sensor, Number, Select, Text, Text Sensor, Date, Time, +> Datetime, and Event entities do not create bindings. They expose data +> only through variables and events. + +> **Note:** Water Heater entities share the `ESPHOME_CLIMATE` binding +> class and are controlled via the ESPHome Climate sub-driver. Device +> modes (such as Eco, Heat Pump, Gas) are exposed as presets. -> \*\* **Climate remote sensor:** The Climate sub-driver supports using an -> external Control4 temperature sensor instead of the climate device's built-in -> sensor. This feature requires the ESPHome device YAML to define user-defined -> API services (e.g., `set_remote_temperature` and `use_internal_temperature`). -> See the ESPHome Climate sub-driver documentation for full details and YAML +> \*\* **Climate remote sensor:** The Climate sub-driver supports using +> an external Control4 temperature sensor instead of the climate +> device's built-in sensor. This feature requires the ESPHome device +> YAML to define user-defined API services (e.g., +> `set_remote_temperature` and `use_internal_temperature`). See the +> ESPHome Climate sub-driver documentation for full details and YAML > examples. ### Bluetooth Proxy Bindings -When the connected ESPHome device exposes a Bluetooth proxy, additional dynamic -bindings are created separately from the entity bindings above: +When the connected ESPHome device exposes a Bluetooth proxy, additional +dynamic bindings are created separately from the entity bindings above: -| Source | Binding Class | Purpose | -| -------------------------- | ------------------- | -------------------------------------------------------- | +| Source | Binding Class | Purpose | +|----|----|----| | Bluetooth Coordinator link | `ESPHOME_BLUETOOTH` | Connects the ESPHome driver to the Bluetooth Coordinator | -| Selected BTHome device | `ESPHOME_BTHOME` | Bind to ESPHome BTHome sub-driver | -| Selected Govee device | `ESPHOME_GOVEE` | Bind to ESPHome Govee sub-driver | -| Selected SwitchBot device | `ESPHOME_SWITCHBOT` | Bind to ESPHome SwitchBot sub-driver | -| Selected Yale/August lock | `ESPHOME_YALE` | Bind to ESPHome Yale sub-driver | +| Selected BTHome device | `ESPHOME_BTHOME` | Bind to ESPHome BTHome sub-driver | +| Selected Govee device | `ESPHOME_GOVEE` | Bind to ESPHome Govee sub-driver | +| Selected SwitchBot device | `ESPHOME_SWITCHBOT` | Bind to ESPHome SwitchBot sub-driver | +| Selected Yale/August lock | `ESPHOME_YALE` | Bind to ESPHome Yale sub-driver | -> **Note:** Per-device Bluetooth bindings are created automatically when a -> device is chosen via the `Select Bluetooth Devices` property (standalone mode) -> or via the Bluetooth Coordinator's device selector (coordinator mode). Binding -> display names include the device MAC address suffix for easy identification. +> **Note:** Per-device Bluetooth bindings are created automatically when +> a device is chosen via the `Select Bluetooth Devices` property +> (standalone mode) or via the Bluetooth Coordinator's device selector +> (coordinator mode). Binding display names include the device MAC +> address suffix for easy identification. ### Events by Entity Type -| Entity Type | Event Name | Description | -| ----------- | ---------------------- | ------------------------------------------- | -| Event | `{name}: {event_type}` | One C4 event per event type for programming | +| Entity Type | Event Name | Description | +|----|----|----| +| Event | `{name}: {event_type}` | One C4 event per event type for programming | -> **Note:** Event entities are stateless triggers (button presses, gestures, -> doorbell rings). Each discovered event type creates a Control4 event that can -> be used in programming. The `{name} Last Event` variable tracks the most -> recent event type. +> **Note:** Event entities are stateless triggers (button presses, +> gestures, doorbell rings). Each discovered event type creates a +> Control4 event that can be used in programming. The +> `{name} Last Event` variable tracks the most recent event type. ### Commands | Command | Parameters | Description | -| ------------ | -------------- | -------------------------------------------- | +|--------------|----------------|----------------------------------------------| | Press Button | Button | Triggers an ESPHome button entity by name | | Set Select | Select, Option | Sets a select entity to the specified option | -> **Note:** The Button parameter is a dynamic list populated with discovered -> ESPHome button entities. The Select and Option parameters are dynamic lists -> populated with discovered ESPHome select entities and their available options. +> **Note:** The Button parameter is a dynamic list populated with +> discovered ESPHome button entities. The Select and Option parameters +> are dynamic lists populated with discovered ESPHome select entities +> and their available options.
@@ -540,39 +557,41 @@ bindings are created separately from the entity bindings above: # ratgdo Configuration Guide -This guide provides instructions for configuring the ESPHome driver to work with -ratgdo devices for garage door control via relays in Control4 Composer Pro. +This guide provides instructions for configuring the ESPHome driver to +work with ratgdo devices for garage door control via relays in Control4 +Composer Pro. ## Add Relay Controller Driver -Add the desired relay controller driver to your Control4 project in Composer -Pro. +Add the desired relay controller driver to your Control4 project in +Composer Pro. Relay Controller Drivers ## Relay Controller Properties -The ratgdo device exposes a "Cover" entity in ESPHome, which maps to the relay -controller functionality in Control4. +The ratgdo device exposes a "Cover" entity in ESPHome, which maps to the +relay controller functionality in Control4. ### Number of Relays -The ratgdo device uses a multi-relay configuration to control the garage door. -In Composer Pro, you should configure the relay settings as follows: +The ratgdo device uses a multi-relay configuration to control the garage +door. In Composer Pro, you should configure the relay settings as +follows: - Set to **2 Relays** (Open/Close) or **3 Relays** (Open/Close/Stop) - - The ratgdo device uses separate commands for opening and closing the garage - door - - If your ratgdo firmware supports the "stop" command, configure for 3 relays - to enable the stop functionality. If you are not sure, you can look at the - ratgdo connections in Composer Pro to see if the "Stop Door" relay is - available. + - The ratgdo device uses separate commands for opening and closing the + garage door + - If your ratgdo firmware supports the "stop" command, configure for 3 + relays to enable the stop functionality. If you are not sure, you + can look at the ratgdo connections in Composer Pro to see if the + "Stop Door" relay is available. ### Relay Configuration - Set to **Pulse** - - ratgdo uses momentary pulses to trigger the garage door opener, similar to a - wall button press + - ratgdo uses momentary pulses to trigger the garage door opener, + similar to a wall button press ### Pulse Time @@ -594,8 +613,8 @@ In Composer Pro, you should configure the relay settings as follows: ### Example Properties -For reference, here is an example of the relay controller properties in Composer -Pro: +For reference, here is an example of the relay controller properties in +Composer Pro: Relay Controller Properties @@ -614,8 +633,8 @@ Pro: ### Example Connections -For reference, here is an example of how the connections should look in Composer -Pro: +For reference, here is an example of how the connections should look in +Composer Pro: Relay Controller Connections @@ -632,15 +651,17 @@ You can create programming in Control4 to: Using the "Still Open Time" property from the relay controller driver: -1. Set the "Still Open Time" to your desired duration (e.g., 10 minutes) -2. Create a programming rule that triggers when the "Still Open" event fires +1. Set the "Still Open Time" to your desired duration (e.g., 10 + minutes) +2. Create a programming rule that triggers when the "Still Open" event + fires 3. Add actions to send notifications or perform other tasks ## Additional Entities -Depending on your ratgdo device, firmware, and its capabilities, there may be -additional entities exposed by the ESPHome driver. These can come as additional -connections or driver variables. +Depending on your ratgdo device, firmware, and its capabilities, there +may be additional entities exposed by the ESPHome driver. These can come +as additional connections or driver variables. Please refer to ratgdo's documentation for more information on specific entities: @@ -651,33 +672,37 @@ entities: # Bluetooth Proxy Configuration Guide -This guide explains how to use the ESPHome Bluetooth Proxy feature to integrate -BLE devices into Control4. +This guide explains how to use the ESPHome Bluetooth Proxy feature to +integrate BLE devices into Control4. ## Prerequisites -- ESP32 device with ESPHome firmware and `bluetooth_proxy` component enabled +- ESP32 device with ESPHome firmware and `bluetooth_proxy` component + enabled - BLE devices within range of the ESP32 **Recommended Hardware:** -The following POE-powered Bluetooth proxies are excellent choices with 4 active -connection slots: +The following POE-powered Bluetooth proxies are excellent choices with 4 +active connection slots: -- [Seeed Studio XIAO ESP32C6](https://www.seeedstudio.com/Seeed-Studio-XIAO-ESP32C6-p-5884.html) +- [Seeed Studio XIAO + ESP32C6](https://www.seeedstudio.com/Seeed-Studio-XIAO-ESP32C6-p-5884.html) with POE expansion board -- [Olimex ESP32-POE](https://www.olimex.com/Products/IoT/ESP32/ESP32-POE/open-source-hardware) +- [Olimex + ESP32-POE](https://www.olimex.com/Products/IoT/ESP32/ESP32-POE/open-source-hardware) or [ESP32-POE-ISO](https://www.olimex.com/Products/IoT/ESP32/ESP32-POE-ISO/open-source-hardware) **Firmware Installation:** -- **Quick Start:** Use [web.esphome.io](https://web.esphome.io) for one-click - firmware installation directly in your browser - no YAML configuration needed. +- **Quick Start:** Use [web.esphome.io](https://web.esphome.io) for + one-click firmware installation directly in your browser - no YAML + configuration needed. - **Advanced:** For more control over settings, create a custom YAML - configuration. See the - [ESPHome Bluetooth Proxy documentation](https://esphome.io/components/bluetooth_proxy.html) - for configuration options. + configuration. See the [ESPHome Bluetooth Proxy + documentation](https://esphome.io/components/bluetooth_proxy.html) for + configuration options. ## Understanding Connection Types @@ -685,57 +710,66 @@ BLE devices use one of two connection modes: ### Passive Mode (No Slot Required) -Passive devices broadcast their data in advertisements. The proxy listens -without establishing a connection. These devices include: +Passive devices broadcast their data in advertisements. The proxy +listens without establishing a connection. These devices include: -- **Shelly BLU devices** - Button, Door/Window, Motion, H&T sensors (native - BTHome support) +- **Shelly BLU devices** - Button, Door/Window, Motion, H&T sensors + (native BTHome support) - **BTHome sensors** - Temperature, humidity, motion, door sensors - **Govee sensors** - Temperature/humidity monitors, meat thermometers -- **SwitchBot sensors** - Meters, motion sensors, contact sensors, water leak +- **SwitchBot sensors** - Meters, motion sensors, contact sensors, water + leak -**Advantage:** Unlimited passive devices can be monitored simultaneously. +**Advantage:** Unlimited passive devices can be monitored +simultaneously. ### Active Mode (Uses Connection Slot) -Active devices require a GATT connection to send commands. The ESP32 has limited -connection slots (typically 3-4). These devices include: +Active devices require a GATT connection to send commands. The ESP32 has +limited connection slots (typically 3-4). These devices include: - **SwitchBot Bot** - Requires connection to send press/on/off commands - **SwitchBot Switch** - Plug Mini, Relay switches (encrypted commands) -- **Yale/August Locks** - Requires connection for encrypted lock/unlock commands +- **Yale/August Locks** - Requires connection for encrypted lock/unlock + commands ### Oversubscription -You can select more active devices than available connection slots. This is -called **oversubscription** and works well when devices only need brief -connections to exchange data (e.g., sending a command to a SwitchBot Bot). The -device connects, sends the command, and immediately frees the slot. +You can select more active devices than available connection slots. This +is called **oversubscription** and works well when devices only need +brief connections to exchange data (e.g., sending a command to a +SwitchBot Bot). The device connects, sends the command, and immediately +frees the slot. -Oversubscription becomes problematic when multiple devices need simultaneous -connections. If all slots are in use, commands to additional devices will queue -and retry until a slot becomes available. +Oversubscription becomes problematic when multiple devices need +simultaneous connections. If all slots are in use, commands to +additional devices will queue and retry until a slot becomes available. -> **Tip:** If you see "Allocation failed" errors in the logs, you have too many -> concurrent active connections. Consider reducing the number of active devices -> or adding another proxy. +> **Tip:** If you see "Allocation failed" errors in the logs, you have +> too many concurrent active connections. Consider reducing the number +> of active devices or adding another proxy. ## Step-by-Step Setup -1. **Add the ESPHome driver** and configure it to connect to your ESP32 device. +1. **Add the ESPHome driver** and configure it to connect to your ESP32 + device. -2. **Verify Bluetooth Proxy Status** shows "Ready" with available slots. +2. **Verify Bluetooth Proxy Status** shows "Ready" with available + slots. 3. **Scan for devices:** + - Set "Bluetooth Scan Duration" (30 seconds recommended) - Select "Refresh List" from the "Select Bluetooth Devices" dropdown - Wait for the scan to complete -4. **Select a discovered device** from the dropdown. A connection will be - automatically created. +4. **Select a discovered device** from the dropdown. A connection will + be automatically created. 5. **Add the appropriate sub-driver:** - - Search for the driver matching your device type (e.g., "ESPHome BTHome") + + - Search for the driver matching your device type (e.g., "ESPHome + BTHome") - Add it to your project 6. **Bind the sub-driver** to the connection created in step 4. @@ -745,7 +779,7 @@ and retry until a slot becomes available. ## Supported Device Types | Device Protocol | Sub-Driver | Connection | -| --------------- | ----------------- | -------------- | +|-----------------|-------------------|----------------| | BTHome | ESPHome BTHome | Passive | | Govee | ESPHome Govee | Passive | | SwitchBot | ESPHome SwitchBot | Active/Passive | @@ -758,7 +792,7 @@ and retry until a slot becomes available. The ESP32 Bluetooth proxy has practical limits on device capacity: | Connection Type | Recommended Limit | Notes | -| ------------------ | ----------------- | ----------------------------------- | +|--------------------|-------------------|-------------------------------------| | Passive devices | 20-30 | Sensors broadcasting advertisements | | Active connections | 3-5 | Devices requiring GATT connections | @@ -768,28 +802,30 @@ Exceeding these limits may cause: - "Allocation failed" errors for active connections - Delayed or failed commands to active devices -> **Warning:** If you see "Too many BLE events to process" in the logs, the -> proxy is overwhelmed. Reduce the number of tracked devices or add another -> proxy. +> **Warning:** If you see "Too many BLE events to process" in the logs, +> the proxy is overwhelmed. Reduce the number of tracked devices or add +> another proxy. ### Busy BLE Environments -In environments with many BLE devices (smart home hubs, fitness equipment, -wireless speakers, neighbors' devices), performance may degrade: +In environments with many BLE devices (smart home hubs, fitness +equipment, wireless speakers, neighbors' devices), performance may +degrade: -- **2.4 GHz congestion** - BLE and WiFi share spectrum; heavy WiFi traffic - affects BLE reception -- **Advertisement flooding** - Many devices broadcasting simultaneously can - overwhelm the scanner -- **Interference sources** - Microwaves, USB 3.0 devices, and poorly shielded - electronics cause interference +- **2.4 GHz congestion** - BLE and WiFi share spectrum; heavy WiFi + traffic affects BLE reception +- **Advertisement flooding** - Many devices broadcasting simultaneously + can overwhelm the scanner +- **Interference sources** - Microwaves, USB 3.0 devices, and poorly + shielded electronics cause interference **Mitigation strategies:** -1. Use Ethernet-connected ESP32 boards (Olimex ESP32-POE) to avoid WiFi/BLE - contention +1. Use Ethernet-connected ESP32 boards (Olimex ESP32-POE) to avoid + WiFi/BLE contention 2. Position proxies away from WiFi routers (at least 2-3 meters) -3. Use the Bluetooth Coordinator to distribute load across multiple proxies +3. Use the Bluetooth Coordinator to distribute load across multiple + proxies 4. Reduce scan duration if not actively discovering new devices ### Proxy Placement Tips @@ -797,16 +833,17 @@ wireless speakers, neighbors' devices), performance may degrade: For optimal BLE reception: - **Height matters** - Place at chest height or higher, not on the floor -- **Avoid metal** - Keep away from refrigerators, filing cabinets, and metal - shelving (metal causes reflections and unstable signals) -- **Avoid enclosed spaces** - Don't place inside cabinets or behind furniture -- **Distance from electronics** - Keep 2-3 meters from routers, switches, and - other network equipment +- **Avoid metal** - Keep away from refrigerators, filing cabinets, and + metal shelving (metal causes reflections and unstable signals) +- **Avoid enclosed spaces** - Don't place inside cabinets or behind + furniture +- **Distance from electronics** - Keep 2-3 meters from routers, + switches, and other network equipment **Coverage expectations:** | Environment | Typical Range | -| -------------------- | ----------------------- | +|----------------------|-------------------------| | Open indoor space | 10-15 meters (30-50 ft) | | Through 1-2 walls | 5-10 meters (15-30 ft) | | Concrete/brick walls | 3-5 meters (10-15 ft) | @@ -816,24 +853,25 @@ For optimal BLE reception: ## Bluetooth Coordinator Setup For advanced setups with **multiple ESPHome Bluetooth proxies**, use the -**ESPHome Bluetooth Coordinator** driver to aggregate them. The coordinator -provides: +**ESPHome Bluetooth Coordinator** driver to aggregate them. The +coordinator provides: -- **RSSI-based routing** - Commands are routed to the proxy with the best signal - strength for each BLE device -- **Automatic failover** - If a connection fails, the coordinator retries - through alternate proxies -- **Room-level presence tracking** - Track which room a BLE device (like a - phone) is in based on signal strength from each proxy +- **RSSI-based routing** - Commands are routed to the proxy with the + best signal strength for each BLE device +- **Automatic failover** - If a connection fails, the coordinator + retries through alternate proxies +- **Room-level presence tracking** - Track which room a BLE device (like + a phone) is in based on signal strength from each proxy -> **Note:** Apple devices (iPhone, iPad, Apple Watch) and Android devices with -> MAC randomization enabled cannot be tracked for presence. Use dedicated BLE -> beacons or devices with static MAC addresses instead. +> **Note:** Apple devices (iPhone, iPad, Apple Watch) and Android +> devices with MAC randomization enabled cannot be tracked for presence. +> Use dedicated BLE beacons or devices with static MAC addresses +> instead. ### When to Use the Coordinator | Setup | Recommendation | -| ------------------------ | --------------------------- | +|--------------------------|-----------------------------| | Single ESP32 proxy | Use ESPHome driver directly | | Multiple proxies | Use Bluetooth Coordinator | | Want presence tracking | Use Bluetooth Coordinator | @@ -844,27 +882,29 @@ provides: 1. **Add the Bluetooth Coordinator driver** to your project 2. **Connect your ESPHome drivers** to the coordinator's proxy bindings (Connections tab) -3. **Set the "Bluetooth Proxy Room" property** on each ESPHome driver to - indicate where that proxy is physically located -4. **Select devices** via the coordinator's "Select Bluetooth Devices" property -5. **For presence tracking**, select devices via "Select Presence Devices" +3. **Set the "Bluetooth Proxy Room" property** on each ESPHome driver + to indicate where that proxy is physically located +4. **Select devices** via the coordinator's "Select Bluetooth Devices" + property +5. **For presence tracking**, select devices via "Select Presence + Devices" When an ESPHome driver is connected to the coordinator: -- The "Select Bluetooth Devices" property is hidden (selection is done in the - coordinator) -- The "Bluetooth Proxy Room" property becomes visible for presence tracking - configuration +- The "Select Bluetooth Devices" property is hidden (selection is done + in the coordinator) +- The "Bluetooth Proxy Room" property becomes visible for presence + tracking configuration -See the **ESPHome Bluetooth Coordinator** driver documentation for full details -on presence tracking settings and events. +See the **ESPHome Bluetooth Coordinator** driver documentation for full +details on presence tracking settings and events.
# Support -If you have any questions or issues integrating this driver with Control4, you -can file an issue on GitHub: +If you have any questions or issues integrating this driver with +Control4, you can file an issue on GitHub: @@ -874,15 +914,15 @@ can file an issue on GitHub: # Changelog -## Unreleased +## v20260512 - 2026-05-12 ### Added -- Added brightness and dimming support to ESPHome lights with smooth ramping, - preset management, and hold-to-dim button control -- Added color and color-temperature support to ESPHome lights for every ESPHome - color mode (white, color-temperature, cold/warm white, RGB, RGBW, and combined - RGB + white modes) +- Added brightness and dimming support to ESPHome lights with smooth + ramping, preset management, and hold-to-dim button control +- Added color and color-temperature support to ESPHome lights for every + ESPHome color mode (white, color-temperature, cold/warm white, RGB, + RGBW, and combined RGB + white modes) - Added Advanced Lighting Scenes support to ESPHome lights so they can participate in lighting scenes alongside other Control4 dimmers @@ -890,17 +930,17 @@ can file an issue on GitHub: ### Added -- Added Event entity support: stateless triggers (button presses, gestures, - doorbell rings) now create Control4 events for programming and track the last - event type in a variable -- Added Date, Time, and Datetime entity support: configurable date/time values - on the device are exposed as writable string variables (YYYY-MM-DD, HH:MM:SS, - YYYY-MM-DD HH:MM:SS) +- Added Event entity support: stateless triggers (button presses, + gestures, doorbell rings) now create Control4 events for programming + and track the last event type in a variable +- Added Date, Time, and Datetime entity support: configurable date/time + values on the device are exposed as writable string variables + (YYYY-MM-DD, HH:MM:SS, YYYY-MM-DD HH:MM:SS) - Added Climate entity support: ESPHome climate devices are exposed as - thermostatV2 sub-drivers with HVAC mode, setpoints, fan mode, presets, and - humidity control -- Added Select entity support: STRING variable with the current option, writable - via programming or variable writes + thermostatV2 sub-drivers with HVAC mode, setpoints, fan mode, presets, + and humidity control +- Added Select entity support: STRING variable with the current option, + writable via programming or variable writes - Added "Set Select" programming command with dynamic Select and Option dropdowns @@ -908,25 +948,25 @@ can file an issue on GitHub: ### Fixed -- Fixed automatic driver updates not working when the leader instance is removed - from the project +- Fixed automatic driver updates not working when the leader instance is + removed from the project ## v20260325 - 2026-03-25 ### Fixed -- Fixed cover contact sensors sending duplicate notifications during open/close - operations -- Fixed Yale DoorSense contact sensor sending duplicate "Closed" notifications - on every poll cycle by tracking the last known door status and only reporting - on actual state changes +- Fixed cover contact sensors sending duplicate notifications during + open/close operations +- Fixed Yale DoorSense contact sensor sending duplicate "Closed" + notifications on every poll cycle by tracking the last known door + status and only reporting on actual state changes ## v20260319 - 2026-03-19 ### Fixed -- Fixed an issue where entities were no longer being detected reliably on - connection +- Fixed an issue where entities were no longer being detected reliably + on connection ## v20260318 - 2026-03-18 @@ -939,34 +979,35 @@ can file an issue on GitHub: ### Added -- Added fan support with on/off, speed control (1-6 speed variants), direction, - and oscillation -- Added ESPHome Yale sub-driver for Yale/August BLE smart locks with lock/unlock - control, door sense, and battery monitoring +- Added fan support with on/off, speed control (1-6 speed variants), + direction, and oscillation +- Added ESPHome Yale sub-driver for Yale/August BLE smart locks with + lock/unlock control, door sense, and battery monitoring ## v20260217 - 2026-02-17 ### Added -- Added Bluetooth proxy support with scanner infrastructure, advertisement - parsing, and GATT connection management -- Added ESPHome Bluetooth Coordinator driver for multi-proxy aggregation with - RSSI-based routing and connection failover -- Added room presence tracking with RSSI-based detection, anti-flapping, and - contact sensor bindings -- Added ESPHome BTHome sub-driver for Shelly BLU and BTHome v1/v2 sensors -- Added ESPHome Govee sub-driver for temperature, humidity, and meat thermometer +- Added Bluetooth proxy support with scanner infrastructure, + advertisement parsing, and GATT connection management +- Added ESPHome Bluetooth Coordinator driver for multi-proxy aggregation + with RSSI-based routing and connection failover +- Added room presence tracking with RSSI-based detection, anti-flapping, + and contact sensor bindings +- Added ESPHome BTHome sub-driver for Shelly BLU and BTHome v1/v2 sensors -- Added ESPHome SwitchBot sub-driver for Bot, Plug Mini, Meter, Motion, and - Contact devices +- Added ESPHome Govee sub-driver for temperature, humidity, and meat + thermometer sensors +- Added ESPHome SwitchBot sub-driver for Bot, Plug Mini, Meter, Motion, + and Contact devices - Added device log forwarding to the ESPHome driver ## v20251031 - 2025-10-31 ### Fixed -- Fixed compatibility with ESPHome 2025.10.0 for devices configured without - passwords +- Fixed compatibility with ESPHome 2025.10.0 for devices configured + without passwords - Improved password authentication failure detection and error reporting ## v20251022 - 2025-10-22 @@ -979,12 +1020,13 @@ can file an issue on GitHub: ### Added -- Added support for OpenSSL with "Encryption Key" authentication mode across all - applicable algorithms +- Added support for OpenSSL with "Encryption Key" authentication mode + across all applicable algorithms ### Fixed -- Fixed a bug with the authentication flow in the latest 2025.10.0 firmware +- Fixed a bug with the authentication flow in the latest 2025.10.0 + firmware ## v20250811 - 2025-08-11 @@ -1002,7 +1044,8 @@ can file an issue on GitHub: ### Added -- Added support for encrypted connections using the device encryption key +- Added support for encrypted connections using the device encryption + key ## v20250619 - 2025-06-19 From 69866e9013738a5b9de40eb22863b2fed7b45fee Mon Sep 17 00:00:00 2001 From: "svc-finitelabs[bot]" <269744575+svc-finitelabs[bot]@users.noreply.github.com> Date: Tue, 12 May 2026 10:09:16 -0500 Subject: [PATCH 2/2] Re-format README.md with prettier The v20260512 release commit regenerated README.md via pandoc but did not run the prettier step. `make build` runs pandoc + prettier and the CI "Check for dirty tree" step failed because prettier reformatted the committed README. Apply `prettier --prose-wrap always` to bring README.md in sync with what the build pipeline produces. Fixes failing build run: https://github.com/finitelabs/control4-esphome/actions/runs/25742811133 --- README.md | 767 ++++++++++++++++++++++++++---------------------------- 1 file changed, 362 insertions(+), 405 deletions(-) diff --git a/README.md b/README.md index b545f2b..e026c6a 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,18 @@ ESPHome ------------------------------------------------------------------------- +--- # Overview -> DISCLAIMER: This software is neither affiliated with nor endorsed by -> either Control4 or ESPHome. +> DISCLAIMER: This software is neither affiliated with nor endorsed by either +> Control4 or ESPHome. -Integrate [ESPHome-based devices](https://devices.esphome.io) into -Control4. ESPHome is an open-source system that transforms common -microcontrollers, like ESP8266 and ESP32, into smart home devices -through simple YAML configuration. ESPHome devices can be set up, -monitored, and controlled using a web browser, Home Assistant, or other -compatible platforms. This driver enables seamless monitoring and -control of ESPHome devices directly from your Control4 system. +Integrate [ESPHome-based devices](https://devices.esphome.io) into Control4. +ESPHome is an open-source system that transforms common microcontrollers, like +ESP8266 and ESP32, into smart home devices through simple YAML configuration. +ESPHome devices can be set up, monitored, and controlled using a web browser, +Home Assistant, or other compatible platforms. This driver enables seamless +monitoring and control of ESPHome devices directly from your Control4 system. # Index @@ -37,8 +36,7 @@ control of ESPHome devices directly from your Control4 system. - [Programming Reference](#programming-reference) - [Configuration Guides](#configuration-guides) - [ratgdo Configuration Guide](#ratgdo-configuration-guide) - - [Bluetooth Proxy Configuration - Guide](#bluetooth-proxy-configuration-guide) + - [Bluetooth Proxy Configuration Guide](#bluetooth-proxy-configuration-guide) - [Support](#support) - [Changelog](#changelog) @@ -53,8 +51,8 @@ control of ESPHome devices directly from your Control4 system. # Features - Local network communication requiring no cloud services -- Real-time updates from all [supported - entities](#supported-esphome-entities) exposed by the device +- Real-time updates from all [supported entities](#supported-esphome-entities) + exposed by the device - Supports encrypted connections using the device encryption key - Variable Programming Support @@ -62,26 +60,25 @@ control of ESPHome devices directly from your Control4 system. ## Verified Devices -This driver will generically work with any ESPHome device, but we have -tested extensively with the following devices: +This driver will generically work with any ESPHome device, but we have tested +extensively with the following devices: -- [ratgdo](https://ratcloud.llc) - [Configuration - Guide](#ratgdo-configuration-guide) +- [ratgdo](https://ratcloud.llc) - + [Configuration Guide](#ratgdo-configuration-guide) -If you try this driver on a product listed above, and it works, let us -know! +If you try this driver on a product listed above, and it works, let us know! ## Supported Bluetooth Devices -When used as a Bluetooth proxy, this driver supports the following BLE -device types through sub-drivers: +When used as a Bluetooth proxy, this driver supports the following BLE device +types through sub-drivers: -| Protocol | Sub-Driver | Example Devices | -|----|----|----| -| SwitchBot | ESPHome SwitchBot | Bot, Plug Mini, Relay Switch, Meter, Motion, Contact | -| BTHome | ESPHome BTHome | Shelly BLU Button/Door/Motion/H&T, DIY sensors | -| Govee | ESPHome Govee | Temperature/humidity monitors, meat thermometers | -| Yale/August | ESPHome Yale | Yale and August smart locks | +| Protocol | Sub-Driver | Example Devices | +| ----------- | ----------------- | ---------------------------------------------------- | +| SwitchBot | ESPHome SwitchBot | Bot, Plug Mini, Relay Switch, Meter, Motion, Contact | +| BTHome | ESPHome BTHome | Shelly BLU Button/Door/Motion/H&T, DIY sensors | +| Govee | ESPHome Govee | Temperature/humidity monitors, meat thermometers | +| Yale/August | ESPHome Yale | Yale and August smart locks | See the individual sub-driver documentation for device-specific details. @@ -92,7 +89,7 @@ See the individual sub-driver documentation for device-specific details.
| Entity Type | Supported | -|---------------------|-------------------------------| +| ------------------- | ----------------------------- | | Alarm Control Panel | ❌ | | API Noise | ✅ | | Binary Sensor | ✅ | @@ -125,23 +122,23 @@ See the individual sub-driver documentation for device-specific details. -> \* Voice Assistant requires a speech-to-text and intent processing -> pipeline (e.g. Home Assistant Assist). Control4 does not natively -> provide voice intent handling, so this entity type is not supported. +> \* Voice Assistant requires a speech-to-text and intent processing pipeline +> (e.g. Home Assistant Assist). Control4 does not natively provide voice intent +> handling, so this entity type is not supported.
# Installer Setup -> ⚠️ Only a ***single*** driver instance is required per ESPHome device. -> Multiple instance of this driver connected to the same device will -> have unexpected behavior. However, you can have multiple instances of -> this driver connected to ***different*** ESPHome devices. +> ⚠️ Only a **_single_** driver instance is required per ESPHome device. +> Multiple instance of this driver connected to the same device will have +> unexpected behavior. However, you can have multiple instances of this driver +> connected to **_different_** ESPHome devices. ## Driver Installation -Driver installation and setup are similar to most other ip-based -drivers. Below is an outline of the basic steps for your convenience. +Driver installation and setup are similar to most other ip-based drivers. Below +is an outline of the basic steps for your convenience. 1. Download the latest `control4-esphome.zip` from [Github](https://github.com/finitelabs/control4-esphome/releases/latest). @@ -153,30 +150,29 @@ drivers. Below is an outline of the basic steps for your convenience. 3. Use the "Search" tab to find the "ESPHome" driver and add it to your project. - > ⚠️ A ***single*** driver instance is required per ESPHome device. + > ⚠️ A **_single_** driver instance is required per ESPHome device. ![Search Drivers](images/search-drivers.png) -4. Configure the [Device Settings](#device-settings) with the - connection information. +4. Configure the [Device Settings](#device-settings) with the connection + information. -5. After a few moments the [`Driver Status`](#driver-status-read-only) - will display `Connected`. If the driver fails to connect, set the - [`Log Mode`](#log-mode--off--print--log--print-and-log-) property to - `Print` and re-set the [`IP Address`](#ip-address) field to - reconnect. Then check the lua output window for more information. +5. After a few moments the [`Driver Status`](#driver-status-read-only) will + display `Connected`. If the driver fails to connect, set the + [`Log Mode`](#log-mode--off--print--log--print-and-log-) property to `Print` + and re-set the [`IP Address`](#ip-address) field to reconnect. Then check + the lua output window for more information. 6. Once connected, the driver will automatically create variables and connection bindings for each supported entity type. -7. To control climate, lights, fans, locks, and/or water heaters, use - the "Search" tab to find the "ESPHome Climate", "ESPHome Light", - "ESPHome Fan", and/or "ESPHome Lock" driver. For fans, choose the - speed variant that matches your fan (e.g., "ESPHome Fan (3 Speed)"). - Water heater entities use the "ESPHome Climate" driver. Add one - driver instance for each exposed entity in your project. In the - "Connections" tab, select the "ESPHome" driver and bind the entities - to the newly added drivers. +7. To control climate, lights, fans, locks, and/or water heaters, use the + "Search" tab to find the "ESPHome Climate", "ESPHome Light", "ESPHome Fan", + and/or "ESPHome Lock" driver. For fans, choose the speed variant that + matches your fan (e.g., "ESPHome Fan (3 Speed)"). Water heater entities use + the "ESPHome Climate" driver. Add one driver instance for each exposed + entity in your project. In the "Connections" tab, select the "ESPHome" + driver and bind the entities to the newly added drivers. ## Driver Setup @@ -184,14 +180,14 @@ drivers. Below is an outline of the basic steps for your convenience. #### Cloud Settings -##### Automatic Updates \[ Off \| ***On*** \] +##### Automatic Updates \[ Off \| **_On_** \] Enables or disables automatic driver updates from GitHub releases. -##### Update Channel \[ ***Production*** \| Prerelease \] +##### Update Channel \[ **_Production_** \| Prerelease \] -Sets the update channel for which releases are considered during -automatic updates from GitHub releases. +Sets the update channel for which releases are considered during automatic +updates from GitHub releases. #### Driver Settings @@ -203,87 +199,85 @@ Displays the current status of the driver. Displays the current version of the driver. -##### Log Level \[ 0 - Fatal \| 1 - Error \| 2 - Warning \| ***3 - Info*** \| 4 - Debug \| 5 - Trace \| 6 - Ultra \] +##### Log Level \[ 0 - Fatal \| 1 - Error \| 2 - Warning \| **_3 - Info_** \| 4 - Debug \| 5 - Trace \| 6 - Ultra \] Sets the logging level. Default is `3 - Info`. -##### Log Mode \[ ***Off*** \| Print \| Log \| Print and Log \] +##### Log Mode \[ **_Off_** \| Print \| Log \| Print and Log \] Sets the logging mode. Default is `Off`. -##### Device Log Forwarding \[ ***Off*** \| On \] +##### Device Log Forwarding \[ **_Off_** \| On \] -Forward ESPHome device logs to the driver's Lua output at the current -Log Level. Changing Log Level or disabling Log Mode will reconnect to -apply the new settings. +Forward ESPHome device logs to the driver's Lua output at the current Log Level. +Changing Log Level or disabling Log Mode will reconnect to apply the new +settings. #### Device Settings ##### IP Address -Sets the device IP address (e.g. `192.168.1.30`). Domain names are -allowed as long as they can be resolved to an accessible IP address by -the controller. HTTPS is not supported. +Sets the device IP address (e.g. `192.168.1.30`). Domain names are allowed as +long as they can be resolved to an accessible IP address by the controller. +HTTPS is not supported. -> ⚠️ If you are using an IP address, you should ensure it will not -> change by assigning a static IP or creating a DHCP reservation. +> ⚠️ If you are using an IP address, you should ensure it will not change by +> assigning a static IP or creating a DHCP reservation. -##### Port \[ 1 - 65535, default: ***6053*** \] +##### Port \[ 1 - 65535, default: **_6053_** \] Sets the device port. The default port for ESPHome devices is `6053`. -##### Authentication Mode \[ ***None*** \| Password \| Encryption Key \] +##### Authentication Mode \[ **_None_** \| Password \| Encryption Key \] Selects the authentication method for connecting to the ESPHome device. - **None**: No authentication required. - **Password**: Use a password for authentication (see below). -- **Encryption Key**: Use an encryption key for secure communication - (see below). - -> **Tip:** For ESPHome devices used primarily as Bluetooth proxies, -> consider configuring the firmware without API encryption. In busy BLE -> environments, the volume of proxy traffic combined with the -> controller's limited cryptographic performance can cause significant -> CPU load. BLE traffic is inherently over-the-air, and sensitive -> protocols (such as Yale/August lock commands) use their own end-to-end -> encryption between the driver and the device, making it safe to relay -> through an unencrypted proxy. To disable encryption, omit the +- **Encryption Key**: Use an encryption key for secure communication (see + below). + +> **Tip:** For ESPHome devices used primarily as Bluetooth proxies, consider +> configuring the firmware without API encryption. In busy BLE environments, the +> volume of proxy traffic combined with the controller's limited cryptographic +> performance can cause significant CPU load. BLE traffic is inherently +> over-the-air, and sensitive protocols (such as Yale/August lock commands) use +> their own end-to-end encryption between the driver and the device, making it +> safe to relay through an unencrypted proxy. To disable encryption, omit the > `encryption` block from the ESPHome `api:` configuration and set > Authentication Mode to `None`. ##### Password -Shown only if [Authentication -Mode](#authentication-mode--none--password--encryption-key-) is set to -`Password`. Sets the device password. This must match the password +Shown only if +[Authentication Mode](#authentication-mode--none--password--encryption-key-) is +set to `Password`. Sets the device password. This must match the password configured on the ESPHome device. ##### Encryption Key -Shown only if [Authentication -Mode](#authentication-mode--none--password--encryption-key-) is set to -`Encryption Key`. Sets the device encryption key for secure -communication. This must match the encryption key configured on the -ESPHome device. +Shown only if +[Authentication Mode](#authentication-mode--none--password--encryption-key-) is +set to `Encryption Key`. Sets the device encryption key for secure +communication. This must match the encryption key configured on the ESPHome +device. -##### Use OpenSSL \[ ***Yes*** \| No \] +##### Use OpenSSL \[ **_Yes_** \| No \] -Use OpenSSL for encryption. This should typically be left at the default -value of `Yes` for better performance and compatibility. +Use OpenSSL for encryption. This should typically be left at the default value +of `Yes` for better performance and compatibility. #### Bluetooth Proxy Settings > The Bluetooth Proxy feature requires an ESP32 device with the -> `bluetooth_proxy` component configured in ESPHome. See the [ESPHome -> Bluetooth Proxy -> documentation](https://esphome.io/components/bluetooth_proxy.html) for -> firmware configuration. +> `bluetooth_proxy` component configured in ESPHome. See the +> [ESPHome Bluetooth Proxy documentation](https://esphome.io/components/bluetooth_proxy.html) +> for firmware configuration. ##### Bluetooth Proxy Status (read-only) -Shows the current state of the Bluetooth proxy. The format is a -pipe-separated list of status components: +Shows the current state of the Bluetooth proxy. The format is a pipe-separated +list of status components: **Standalone Mode:** `Standalone Mode | Scanning (Passive) | 1/4 Active` @@ -292,43 +286,41 @@ pipe-separated list of status components: Components explained: -- **Mode** - "Standalone Mode" or "Coordinator Mode" depending on - whether the driver is connected to a Bluetooth Coordinator -- **Scanner State** - Current state (Idle, Starting, Running, Stopping, - Stopped, Failed) and mode (Passive or Active) -- **Connection Slots** - Shows "used/total Active" slots (e.g., "1/4 - Active" means 1 slot in use out of 4 available). If you select more - active devices than available slots, "(Oversubscribed)" is appended - (see [Oversubscription](#oversubscription)) -- **MAC Filter** - (Coordinator mode only) Shows how many device MACs - are being filtered for, or "none" if forwarding all advertisements +- **Mode** - "Standalone Mode" or "Coordinator Mode" depending on whether the + driver is connected to a Bluetooth Coordinator +- **Scanner State** - Current state (Idle, Starting, Running, Stopping, Stopped, + Failed) and mode (Passive or Active) +- **Connection Slots** - Shows "used/total Active" slots (e.g., "1/4 Active" + means 1 slot in use out of 4 available). If you select more active devices + than available slots, "(Oversubscribed)" is appended (see + [Oversubscription](#oversubscription)) +- **MAC Filter** - (Coordinator mode only) Shows how many device MACs are being + filtered for, or "none" if forwarding all advertisements ##### Bluetooth Proxy Capabilities (read-only) -Displays a comma-separated list of capabilities supported by this -ESPHome Bluetooth proxy: +Displays a comma-separated list of capabilities supported by this ESPHome +Bluetooth proxy: - **Scan** - Can receive BLE advertisements (passive scanning) -- **Connect** - Can establish GATT connections to devices (active - connections) +- **Connect** - Can establish GATT connections to devices (active connections) - **Cache** - Caches GATT service data remotely - **Pair** - Can pair with devices requiring authentication - **Raw** - Can receive raw advertisement data ##### Select Bluetooth Devices -> Only visible in **Standalone Mode** (hidden when connected to a -> Bluetooth Coordinator, as device selection is done there instead). +> Only visible in **Standalone Mode** (hidden when connected to a Bluetooth +> Coordinator, as device selection is done there instead). -A dropdown list showing discovered BLE devices. Select "Refresh List" to -start a new scan. +A dropdown list showing discovered BLE devices. Select "Refresh List" to start a +new scan. **During scanning:** - The dropdown displays "-- Scanning..." while the scan is in progress - Select "-- Stop Scan" to stop early and keep newly discovered devices -- Select "-- Abort Scan" to stop early and discard newly discovered - devices +- Select "-- Abort Scan" to stop early and discard newly discovered devices - When complete, the dropdown repopulates with discovered devices **Device list shows:** @@ -338,43 +330,40 @@ start a new scan. - Device Type (BTHome, SwitchBot, Govee, etc.) - Connection Type (Active/Passive) -After selecting a device, a connection binding is automatically created -for the appropriate sub-driver. +After selecting a device, a connection binding is automatically created for the +appropriate sub-driver. -> **Tip:** Some BLE devices (buttons, sensors with long advertisement -> intervals) may be in sleep mode. Wake them by pressing buttons, -> triggering motion sensors, or opening/closing contact sensors during -> the scan to ensure they appear in the device list. +> **Tip:** Some BLE devices (buttons, sensors with long advertisement intervals) +> may be in sleep mode. Wake them by pressing buttons, triggering motion +> sensors, or opening/closing contact sensors during the scan to ensure they +> appear in the device list. -##### Bluetooth Scan Duration \[ 5 - 60, default: ***30*** \] +##### Bluetooth Scan Duration \[ 5 - 60, default: **_30_** \] > Only visible in **Standalone Mode**. -Sets how long (in seconds) to scan for BLE devices when refreshing the -device list. Longer scans may discover more devices with long -advertisement intervals. +Sets how long (in seconds) to scan for BLE devices when refreshing the device +list. Longer scans may discover more devices with long advertisement intervals. ##### Bluetooth Proxy Room > Only visible in **Coordinator Mode** (when connected to a Bluetooth > Coordinator). -Sets the room where this Bluetooth proxy is physically located. This is -used for presence tracking to determine which room a device is in based -on signal strength. +Sets the room where this Bluetooth proxy is physically located. This is used for +presence tracking to determine which room a device is in based on signal +strength. -##### Minimum Room RSSI Override (dBm) \[ -100 - -40, default: ***-100*** \] +##### Minimum Room RSSI Override (dBm) \[ -100 - -40, default: **_-100_** \] > Only visible in **Coordinator Mode** (when connected to a Bluetooth > Coordinator). -Overrides the coordinator's global "Minimum Room RSSI" setting for this -proxy's room. Use this when a room has different size or characteristics -than others. +Overrides the coordinator's global "Minimum Room RSSI" setting for this proxy's +room. Use this when a room has different size or characteristics than others. - **-100 (default)** - Use the coordinator's global setting -- **-85** - More permissive; allow detection from further away (large - rooms) +- **-85** - More permissive; allow detection from further away (large rooms) - **-60** - More restrictive; require closer proximity (small rooms) **Examples:** @@ -383,9 +372,9 @@ than others. - Small bathroom: Set to `-60` to require closer proximity - Leave at `-100` to use the coordinator's global setting -> **Note:** Only affects room assignment for this proxy. The value is -> sent to the Bluetooth Coordinator when this proxy connects or when the -> setting changes. +> **Note:** Only affects room assignment for this proxy. The value is sent to +> the Bluetooth Coordinator when this proxy connects or when the setting +> changes. #### Device Info @@ -413,8 +402,8 @@ Displays the firmware version of the connected ESPHome device. #### Update Drivers -Trigger the driver to update from the latest release on GitHub, -regardless of the current version. +Trigger the driver to update from the latest release on GitHub, regardless of +the current version. #### Reset Driver @@ -422,28 +411,26 @@ regardless of the current version. > associated with the variables. Resets the driver to its initial state, removing all dynamically created -connections and variables. This is useful if you change the connected -ESPHome device or there are stale connections or variables. +connections and variables. This is useful if you change the connected ESPHome +device or there are stale connections or variables. **Parameters:** -- **Are You Sure?** \[ ***No*** \| Yes \] - Confirmation to reset the - driver. +- **Are You Sure?** \[ **_No_** \| Yes \] - Confirmation to reset the driver. ## Programming Reference -Once connected, the driver automatically creates variables and bindings -for each supported ESPHome entity. Use this reference for Control4 -programming. +Once connected, the driver automatically creates variables and bindings for each +supported ESPHome entity. Use this reference for Control4 programming. ### Driver Variables In addition to per-entity variables, the driver publishes the following -device-level variables sourced from the ESPHome device info. They mirror -the matching read-only Device Info properties. +device-level variables sourced from the ESPHome device info. They mirror the +matching read-only Device Info properties. | Variable | Type | Description | -|--------------|--------|----------------------------------------------| +| ------------ | ------ | -------------------------------------------- | | Name | STRING | Friendly name reported by the ESPHome device | | Model | STRING | Device model string reported by ESPHome | | Manufacturer | STRING | Manufacturer string reported by ESPHome | @@ -451,105 +438,101 @@ the matching read-only Device Info properties. ### Variables by Entity Type -| Entity Type | Variable Name | Type | Notes | -|----|----|----|----| -| Binary Sensor | `{name} State` | BOOL | "1" = triggered, "0" = clear | -| Button | (none) | \- | Use "Press Button" command (see below) | -| Climate | (none) | \- | State via Thermostat proxy | -| Cover | `{name} State` | STRING | "open", "closed", "opening", "closing" | -| Date | `{name}` | STRING | Writable, formatted as YYYY-MM-DD | -| Datetime | `{name}` | STRING | Writable, formatted as YYYY-MM-DD HH:MM:SS | -| Event | `{name} Last Event` | STRING | Last event type (e.g., "single_press") | -| Fan | (none) | \- | State via Fan proxy | -| Light | (none) | \- | State via Light proxy | -| Lock | (none) | \- | State via Lock proxy | -| Number | `{name}` | NUMBER | Writable, 1 decimal precision | -| Select | `{name}` | STRING | Writable, current option | -| Sensor | `{name}` | NUMBER | Read-only, 1 decimal precision | -| Switch | `{name} State` | BOOL | "1" = on, "0" = off (writable) | -| Text | `{name}` | STRING | Writable | -| Text Sensor | `{name}` | STRING | Read-only | -| Time | `{name}` | STRING | Writable, formatted as HH:MM:SS | -| Water Heater | (none) | \- | State via Thermostat proxy | - -> **Note:** `{name}` is replaced with the entity's display name from -> ESPHome (e.g., a sensor named "Temperature" creates a variable called -> "Temperature"). +| Entity Type | Variable Name | Type | Notes | +| ------------- | ------------------- | ------ | ------------------------------------------ | +| Binary Sensor | `{name} State` | BOOL | "1" = triggered, "0" = clear | +| Button | (none) | \- | Use "Press Button" command (see below) | +| Climate | (none) | \- | State via Thermostat proxy | +| Cover | `{name} State` | STRING | "open", "closed", "opening", "closing" | +| Date | `{name}` | STRING | Writable, formatted as YYYY-MM-DD | +| Datetime | `{name}` | STRING | Writable, formatted as YYYY-MM-DD HH:MM:SS | +| Event | `{name} Last Event` | STRING | Last event type (e.g., "single_press") | +| Fan | (none) | \- | State via Fan proxy | +| Light | (none) | \- | State via Light proxy | +| Lock | (none) | \- | State via Lock proxy | +| Number | `{name}` | NUMBER | Writable, 1 decimal precision | +| Select | `{name}` | STRING | Writable, current option | +| Sensor | `{name}` | NUMBER | Read-only, 1 decimal precision | +| Switch | `{name} State` | BOOL | "1" = on, "0" = off (writable) | +| Text | `{name}` | STRING | Writable | +| Text Sensor | `{name}` | STRING | Read-only | +| Time | `{name}` | STRING | Writable, formatted as HH:MM:SS | +| Water Heater | (none) | \- | State via Thermostat proxy | + +> **Note:** `{name}` is replaced with the entity's display name from ESPHome +> (e.g., a sensor named "Temperature" creates a variable called "Temperature"). ### Bindings by Entity Type -| Entity Type | Binding Class | Purpose | -|----|----|----| -| Binary Sensor | `CONTACT_SENSOR` | Integrates with Contact Sensor proxy | -| Switch | `RELAY` | Control via Relay proxy | -| Cover | `CONTACT_SENSOR` | Open/closed state contacts | -| Cover | `RELAY` | Open/close/stop control relays | -| Button | `BUTTON_LINK` | Allows other devices to trigger button | -| Climate | `ESPHOME_CLIMATE` | Bind to ESPHome Climate sub-driver [\*\*](#climate-services-note) | -| Fan | `ESPHOME_FAN_N_SPEED[_REVERSE]` | Bind to ESPHome Fan sub-driver | -| Light | `ESPHOME_LIGHT` | Bind to ESPHome Light sub-driver | -| Lock | `ESPHOME_LOCK` | Bind to ESPHome Lock sub-driver | -| Water Heater | `ESPHOME_CLIMATE` | Bind to ESPHome Climate sub-driver | - -> **Note:** Sensor, Number, Select, Text, Text Sensor, Date, Time, -> Datetime, and Event entities do not create bindings. They expose data -> only through variables and events. - -> **Note:** Water Heater entities share the `ESPHOME_CLIMATE` binding -> class and are controlled via the ESPHome Climate sub-driver. Device -> modes (such as Eco, Heat Pump, Gas) are exposed as presets. +| Entity Type | Binding Class | Purpose | +| ------------- | ------------------------------- | ----------------------------------------------------------------- | +| Binary Sensor | `CONTACT_SENSOR` | Integrates with Contact Sensor proxy | +| Switch | `RELAY` | Control via Relay proxy | +| Cover | `CONTACT_SENSOR` | Open/closed state contacts | +| Cover | `RELAY` | Open/close/stop control relays | +| Button | `BUTTON_LINK` | Allows other devices to trigger button | +| Climate | `ESPHOME_CLIMATE` | Bind to ESPHome Climate sub-driver [\*\*](#climate-services-note) | +| Fan | `ESPHOME_FAN_N_SPEED[_REVERSE]` | Bind to ESPHome Fan sub-driver | +| Light | `ESPHOME_LIGHT` | Bind to ESPHome Light sub-driver | +| Lock | `ESPHOME_LOCK` | Bind to ESPHome Lock sub-driver | +| Water Heater | `ESPHOME_CLIMATE` | Bind to ESPHome Climate sub-driver | + +> **Note:** Sensor, Number, Select, Text, Text Sensor, Date, Time, Datetime, and +> Event entities do not create bindings. They expose data only through variables +> and events. + +> **Note:** Water Heater entities share the `ESPHOME_CLIMATE` binding class and +> are controlled via the ESPHome Climate sub-driver. Device modes (such as Eco, +> Heat Pump, Gas) are exposed as presets. -> \*\* **Climate remote sensor:** The Climate sub-driver supports using -> an external Control4 temperature sensor instead of the climate -> device's built-in sensor. This feature requires the ESPHome device -> YAML to define user-defined API services (e.g., -> `set_remote_temperature` and `use_internal_temperature`). See the -> ESPHome Climate sub-driver documentation for full details and YAML +> \*\* **Climate remote sensor:** The Climate sub-driver supports using an +> external Control4 temperature sensor instead of the climate device's built-in +> sensor. This feature requires the ESPHome device YAML to define user-defined +> API services (e.g., `set_remote_temperature` and `use_internal_temperature`). +> See the ESPHome Climate sub-driver documentation for full details and YAML > examples. ### Bluetooth Proxy Bindings -When the connected ESPHome device exposes a Bluetooth proxy, additional -dynamic bindings are created separately from the entity bindings above: +When the connected ESPHome device exposes a Bluetooth proxy, additional dynamic +bindings are created separately from the entity bindings above: -| Source | Binding Class | Purpose | -|----|----|----| +| Source | Binding Class | Purpose | +| -------------------------- | ------------------- | -------------------------------------------------------- | | Bluetooth Coordinator link | `ESPHOME_BLUETOOTH` | Connects the ESPHome driver to the Bluetooth Coordinator | -| Selected BTHome device | `ESPHOME_BTHOME` | Bind to ESPHome BTHome sub-driver | -| Selected Govee device | `ESPHOME_GOVEE` | Bind to ESPHome Govee sub-driver | -| Selected SwitchBot device | `ESPHOME_SWITCHBOT` | Bind to ESPHome SwitchBot sub-driver | -| Selected Yale/August lock | `ESPHOME_YALE` | Bind to ESPHome Yale sub-driver | +| Selected BTHome device | `ESPHOME_BTHOME` | Bind to ESPHome BTHome sub-driver | +| Selected Govee device | `ESPHOME_GOVEE` | Bind to ESPHome Govee sub-driver | +| Selected SwitchBot device | `ESPHOME_SWITCHBOT` | Bind to ESPHome SwitchBot sub-driver | +| Selected Yale/August lock | `ESPHOME_YALE` | Bind to ESPHome Yale sub-driver | -> **Note:** Per-device Bluetooth bindings are created automatically when -> a device is chosen via the `Select Bluetooth Devices` property -> (standalone mode) or via the Bluetooth Coordinator's device selector -> (coordinator mode). Binding display names include the device MAC -> address suffix for easy identification. +> **Note:** Per-device Bluetooth bindings are created automatically when a +> device is chosen via the `Select Bluetooth Devices` property (standalone mode) +> or via the Bluetooth Coordinator's device selector (coordinator mode). Binding +> display names include the device MAC address suffix for easy identification. ### Events by Entity Type -| Entity Type | Event Name | Description | -|----|----|----| -| Event | `{name}: {event_type}` | One C4 event per event type for programming | +| Entity Type | Event Name | Description | +| ----------- | ---------------------- | ------------------------------------------- | +| Event | `{name}: {event_type}` | One C4 event per event type for programming | -> **Note:** Event entities are stateless triggers (button presses, -> gestures, doorbell rings). Each discovered event type creates a -> Control4 event that can be used in programming. The -> `{name} Last Event` variable tracks the most recent event type. +> **Note:** Event entities are stateless triggers (button presses, gestures, +> doorbell rings). Each discovered event type creates a Control4 event that can +> be used in programming. The `{name} Last Event` variable tracks the most +> recent event type. ### Commands | Command | Parameters | Description | -|--------------|----------------|----------------------------------------------| +| ------------ | -------------- | -------------------------------------------- | | Press Button | Button | Triggers an ESPHome button entity by name | | Set Select | Select, Option | Sets a select entity to the specified option | -> **Note:** The Button parameter is a dynamic list populated with -> discovered ESPHome button entities. The Select and Option parameters -> are dynamic lists populated with discovered ESPHome select entities -> and their available options. +> **Note:** The Button parameter is a dynamic list populated with discovered +> ESPHome button entities. The Select and Option parameters are dynamic lists +> populated with discovered ESPHome select entities and their available options.
@@ -557,41 +540,39 @@ dynamic bindings are created separately from the entity bindings above: # ratgdo Configuration Guide -This guide provides instructions for configuring the ESPHome driver to -work with ratgdo devices for garage door control via relays in Control4 -Composer Pro. +This guide provides instructions for configuring the ESPHome driver to work with +ratgdo devices for garage door control via relays in Control4 Composer Pro. ## Add Relay Controller Driver -Add the desired relay controller driver to your Control4 project in -Composer Pro. +Add the desired relay controller driver to your Control4 project in Composer +Pro. Relay Controller Drivers ## Relay Controller Properties -The ratgdo device exposes a "Cover" entity in ESPHome, which maps to the -relay controller functionality in Control4. +The ratgdo device exposes a "Cover" entity in ESPHome, which maps to the relay +controller functionality in Control4. ### Number of Relays -The ratgdo device uses a multi-relay configuration to control the garage -door. In Composer Pro, you should configure the relay settings as -follows: +The ratgdo device uses a multi-relay configuration to control the garage door. +In Composer Pro, you should configure the relay settings as follows: - Set to **2 Relays** (Open/Close) or **3 Relays** (Open/Close/Stop) - - The ratgdo device uses separate commands for opening and closing the - garage door - - If your ratgdo firmware supports the "stop" command, configure for 3 - relays to enable the stop functionality. If you are not sure, you - can look at the ratgdo connections in Composer Pro to see if the - "Stop Door" relay is available. + - The ratgdo device uses separate commands for opening and closing the garage + door + - If your ratgdo firmware supports the "stop" command, configure for 3 relays + to enable the stop functionality. If you are not sure, you can look at the + ratgdo connections in Composer Pro to see if the "Stop Door" relay is + available. ### Relay Configuration - Set to **Pulse** - - ratgdo uses momentary pulses to trigger the garage door opener, - similar to a wall button press + - ratgdo uses momentary pulses to trigger the garage door opener, similar to a + wall button press ### Pulse Time @@ -613,8 +594,8 @@ follows: ### Example Properties -For reference, here is an example of the relay controller properties in -Composer Pro: +For reference, here is an example of the relay controller properties in Composer +Pro: Relay Controller Properties @@ -633,8 +614,8 @@ Composer Pro: ### Example Connections -For reference, here is an example of how the connections should look in -Composer Pro: +For reference, here is an example of how the connections should look in Composer +Pro: Relay Controller Connections @@ -651,17 +632,15 @@ You can create programming in Control4 to: Using the "Still Open Time" property from the relay controller driver: -1. Set the "Still Open Time" to your desired duration (e.g., 10 - minutes) -2. Create a programming rule that triggers when the "Still Open" event - fires +1. Set the "Still Open Time" to your desired duration (e.g., 10 minutes) +2. Create a programming rule that triggers when the "Still Open" event fires 3. Add actions to send notifications or perform other tasks ## Additional Entities -Depending on your ratgdo device, firmware, and its capabilities, there -may be additional entities exposed by the ESPHome driver. These can come -as additional connections or driver variables. +Depending on your ratgdo device, firmware, and its capabilities, there may be +additional entities exposed by the ESPHome driver. These can come as additional +connections or driver variables. Please refer to ratgdo's documentation for more information on specific entities: @@ -672,37 +651,33 @@ entities: # Bluetooth Proxy Configuration Guide -This guide explains how to use the ESPHome Bluetooth Proxy feature to -integrate BLE devices into Control4. +This guide explains how to use the ESPHome Bluetooth Proxy feature to integrate +BLE devices into Control4. ## Prerequisites -- ESP32 device with ESPHome firmware and `bluetooth_proxy` component - enabled +- ESP32 device with ESPHome firmware and `bluetooth_proxy` component enabled - BLE devices within range of the ESP32 **Recommended Hardware:** -The following POE-powered Bluetooth proxies are excellent choices with 4 -active connection slots: +The following POE-powered Bluetooth proxies are excellent choices with 4 active +connection slots: -- [Seeed Studio XIAO - ESP32C6](https://www.seeedstudio.com/Seeed-Studio-XIAO-ESP32C6-p-5884.html) +- [Seeed Studio XIAO ESP32C6](https://www.seeedstudio.com/Seeed-Studio-XIAO-ESP32C6-p-5884.html) with POE expansion board -- [Olimex - ESP32-POE](https://www.olimex.com/Products/IoT/ESP32/ESP32-POE/open-source-hardware) +- [Olimex ESP32-POE](https://www.olimex.com/Products/IoT/ESP32/ESP32-POE/open-source-hardware) or [ESP32-POE-ISO](https://www.olimex.com/Products/IoT/ESP32/ESP32-POE-ISO/open-source-hardware) **Firmware Installation:** -- **Quick Start:** Use [web.esphome.io](https://web.esphome.io) for - one-click firmware installation directly in your browser - no YAML - configuration needed. +- **Quick Start:** Use [web.esphome.io](https://web.esphome.io) for one-click + firmware installation directly in your browser - no YAML configuration needed. - **Advanced:** For more control over settings, create a custom YAML - configuration. See the [ESPHome Bluetooth Proxy - documentation](https://esphome.io/components/bluetooth_proxy.html) for - configuration options. + configuration. See the + [ESPHome Bluetooth Proxy documentation](https://esphome.io/components/bluetooth_proxy.html) + for configuration options. ## Understanding Connection Types @@ -710,66 +685,57 @@ BLE devices use one of two connection modes: ### Passive Mode (No Slot Required) -Passive devices broadcast their data in advertisements. The proxy -listens without establishing a connection. These devices include: +Passive devices broadcast their data in advertisements. The proxy listens +without establishing a connection. These devices include: -- **Shelly BLU devices** - Button, Door/Window, Motion, H&T sensors - (native BTHome support) +- **Shelly BLU devices** - Button, Door/Window, Motion, H&T sensors (native + BTHome support) - **BTHome sensors** - Temperature, humidity, motion, door sensors - **Govee sensors** - Temperature/humidity monitors, meat thermometers -- **SwitchBot sensors** - Meters, motion sensors, contact sensors, water - leak +- **SwitchBot sensors** - Meters, motion sensors, contact sensors, water leak -**Advantage:** Unlimited passive devices can be monitored -simultaneously. +**Advantage:** Unlimited passive devices can be monitored simultaneously. ### Active Mode (Uses Connection Slot) -Active devices require a GATT connection to send commands. The ESP32 has -limited connection slots (typically 3-4). These devices include: +Active devices require a GATT connection to send commands. The ESP32 has limited +connection slots (typically 3-4). These devices include: - **SwitchBot Bot** - Requires connection to send press/on/off commands - **SwitchBot Switch** - Plug Mini, Relay switches (encrypted commands) -- **Yale/August Locks** - Requires connection for encrypted lock/unlock - commands +- **Yale/August Locks** - Requires connection for encrypted lock/unlock commands ### Oversubscription -You can select more active devices than available connection slots. This -is called **oversubscription** and works well when devices only need -brief connections to exchange data (e.g., sending a command to a -SwitchBot Bot). The device connects, sends the command, and immediately -frees the slot. +You can select more active devices than available connection slots. This is +called **oversubscription** and works well when devices only need brief +connections to exchange data (e.g., sending a command to a SwitchBot Bot). The +device connects, sends the command, and immediately frees the slot. -Oversubscription becomes problematic when multiple devices need -simultaneous connections. If all slots are in use, commands to -additional devices will queue and retry until a slot becomes available. +Oversubscription becomes problematic when multiple devices need simultaneous +connections. If all slots are in use, commands to additional devices will queue +and retry until a slot becomes available. -> **Tip:** If you see "Allocation failed" errors in the logs, you have -> too many concurrent active connections. Consider reducing the number -> of active devices or adding another proxy. +> **Tip:** If you see "Allocation failed" errors in the logs, you have too many +> concurrent active connections. Consider reducing the number of active devices +> or adding another proxy. ## Step-by-Step Setup -1. **Add the ESPHome driver** and configure it to connect to your ESP32 - device. +1. **Add the ESPHome driver** and configure it to connect to your ESP32 device. -2. **Verify Bluetooth Proxy Status** shows "Ready" with available - slots. +2. **Verify Bluetooth Proxy Status** shows "Ready" with available slots. 3. **Scan for devices:** - - Set "Bluetooth Scan Duration" (30 seconds recommended) - Select "Refresh List" from the "Select Bluetooth Devices" dropdown - Wait for the scan to complete -4. **Select a discovered device** from the dropdown. A connection will - be automatically created. +4. **Select a discovered device** from the dropdown. A connection will be + automatically created. 5. **Add the appropriate sub-driver:** - - - Search for the driver matching your device type (e.g., "ESPHome - BTHome") + - Search for the driver matching your device type (e.g., "ESPHome BTHome") - Add it to your project 6. **Bind the sub-driver** to the connection created in step 4. @@ -779,7 +745,7 @@ additional devices will queue and retry until a slot becomes available. ## Supported Device Types | Device Protocol | Sub-Driver | Connection | -|-----------------|-------------------|----------------| +| --------------- | ----------------- | -------------- | | BTHome | ESPHome BTHome | Passive | | Govee | ESPHome Govee | Passive | | SwitchBot | ESPHome SwitchBot | Active/Passive | @@ -792,7 +758,7 @@ additional devices will queue and retry until a slot becomes available. The ESP32 Bluetooth proxy has practical limits on device capacity: | Connection Type | Recommended Limit | Notes | -|--------------------|-------------------|-------------------------------------| +| ------------------ | ----------------- | ----------------------------------- | | Passive devices | 20-30 | Sensors broadcasting advertisements | | Active connections | 3-5 | Devices requiring GATT connections | @@ -802,30 +768,28 @@ Exceeding these limits may cause: - "Allocation failed" errors for active connections - Delayed or failed commands to active devices -> **Warning:** If you see "Too many BLE events to process" in the logs, -> the proxy is overwhelmed. Reduce the number of tracked devices or add -> another proxy. +> **Warning:** If you see "Too many BLE events to process" in the logs, the +> proxy is overwhelmed. Reduce the number of tracked devices or add another +> proxy. ### Busy BLE Environments -In environments with many BLE devices (smart home hubs, fitness -equipment, wireless speakers, neighbors' devices), performance may -degrade: +In environments with many BLE devices (smart home hubs, fitness equipment, +wireless speakers, neighbors' devices), performance may degrade: -- **2.4 GHz congestion** - BLE and WiFi share spectrum; heavy WiFi - traffic affects BLE reception -- **Advertisement flooding** - Many devices broadcasting simultaneously - can overwhelm the scanner -- **Interference sources** - Microwaves, USB 3.0 devices, and poorly - shielded electronics cause interference +- **2.4 GHz congestion** - BLE and WiFi share spectrum; heavy WiFi traffic + affects BLE reception +- **Advertisement flooding** - Many devices broadcasting simultaneously can + overwhelm the scanner +- **Interference sources** - Microwaves, USB 3.0 devices, and poorly shielded + electronics cause interference **Mitigation strategies:** -1. Use Ethernet-connected ESP32 boards (Olimex ESP32-POE) to avoid - WiFi/BLE contention +1. Use Ethernet-connected ESP32 boards (Olimex ESP32-POE) to avoid WiFi/BLE + contention 2. Position proxies away from WiFi routers (at least 2-3 meters) -3. Use the Bluetooth Coordinator to distribute load across multiple - proxies +3. Use the Bluetooth Coordinator to distribute load across multiple proxies 4. Reduce scan duration if not actively discovering new devices ### Proxy Placement Tips @@ -833,17 +797,16 @@ degrade: For optimal BLE reception: - **Height matters** - Place at chest height or higher, not on the floor -- **Avoid metal** - Keep away from refrigerators, filing cabinets, and - metal shelving (metal causes reflections and unstable signals) -- **Avoid enclosed spaces** - Don't place inside cabinets or behind - furniture -- **Distance from electronics** - Keep 2-3 meters from routers, - switches, and other network equipment +- **Avoid metal** - Keep away from refrigerators, filing cabinets, and metal + shelving (metal causes reflections and unstable signals) +- **Avoid enclosed spaces** - Don't place inside cabinets or behind furniture +- **Distance from electronics** - Keep 2-3 meters from routers, switches, and + other network equipment **Coverage expectations:** | Environment | Typical Range | -|----------------------|-------------------------| +| -------------------- | ----------------------- | | Open indoor space | 10-15 meters (30-50 ft) | | Through 1-2 walls | 5-10 meters (15-30 ft) | | Concrete/brick walls | 3-5 meters (10-15 ft) | @@ -853,25 +816,24 @@ For optimal BLE reception: ## Bluetooth Coordinator Setup For advanced setups with **multiple ESPHome Bluetooth proxies**, use the -**ESPHome Bluetooth Coordinator** driver to aggregate them. The -coordinator provides: +**ESPHome Bluetooth Coordinator** driver to aggregate them. The coordinator +provides: -- **RSSI-based routing** - Commands are routed to the proxy with the - best signal strength for each BLE device -- **Automatic failover** - If a connection fails, the coordinator - retries through alternate proxies -- **Room-level presence tracking** - Track which room a BLE device (like - a phone) is in based on signal strength from each proxy +- **RSSI-based routing** - Commands are routed to the proxy with the best signal + strength for each BLE device +- **Automatic failover** - If a connection fails, the coordinator retries + through alternate proxies +- **Room-level presence tracking** - Track which room a BLE device (like a + phone) is in based on signal strength from each proxy -> **Note:** Apple devices (iPhone, iPad, Apple Watch) and Android -> devices with MAC randomization enabled cannot be tracked for presence. -> Use dedicated BLE beacons or devices with static MAC addresses -> instead. +> **Note:** Apple devices (iPhone, iPad, Apple Watch) and Android devices with +> MAC randomization enabled cannot be tracked for presence. Use dedicated BLE +> beacons or devices with static MAC addresses instead. ### When to Use the Coordinator | Setup | Recommendation | -|--------------------------|-----------------------------| +| ------------------------ | --------------------------- | | Single ESP32 proxy | Use ESPHome driver directly | | Multiple proxies | Use Bluetooth Coordinator | | Want presence tracking | Use Bluetooth Coordinator | @@ -882,29 +844,27 @@ coordinator provides: 1. **Add the Bluetooth Coordinator driver** to your project 2. **Connect your ESPHome drivers** to the coordinator's proxy bindings (Connections tab) -3. **Set the "Bluetooth Proxy Room" property** on each ESPHome driver - to indicate where that proxy is physically located -4. **Select devices** via the coordinator's "Select Bluetooth Devices" - property -5. **For presence tracking**, select devices via "Select Presence - Devices" +3. **Set the "Bluetooth Proxy Room" property** on each ESPHome driver to + indicate where that proxy is physically located +4. **Select devices** via the coordinator's "Select Bluetooth Devices" property +5. **For presence tracking**, select devices via "Select Presence Devices" When an ESPHome driver is connected to the coordinator: -- The "Select Bluetooth Devices" property is hidden (selection is done - in the coordinator) -- The "Bluetooth Proxy Room" property becomes visible for presence - tracking configuration +- The "Select Bluetooth Devices" property is hidden (selection is done in the + coordinator) +- The "Bluetooth Proxy Room" property becomes visible for presence tracking + configuration -See the **ESPHome Bluetooth Coordinator** driver documentation for full -details on presence tracking settings and events. +See the **ESPHome Bluetooth Coordinator** driver documentation for full details +on presence tracking settings and events.
# Support -If you have any questions or issues integrating this driver with -Control4, you can file an issue on GitHub: +If you have any questions or issues integrating this driver with Control4, you +can file an issue on GitHub: @@ -918,11 +878,11 @@ Control4, you can file an issue on GitHub: ### Added -- Added brightness and dimming support to ESPHome lights with smooth - ramping, preset management, and hold-to-dim button control -- Added color and color-temperature support to ESPHome lights for every - ESPHome color mode (white, color-temperature, cold/warm white, RGB, - RGBW, and combined RGB + white modes) +- Added brightness and dimming support to ESPHome lights with smooth ramping, + preset management, and hold-to-dim button control +- Added color and color-temperature support to ESPHome lights for every ESPHome + color mode (white, color-temperature, cold/warm white, RGB, RGBW, and combined + RGB + white modes) - Added Advanced Lighting Scenes support to ESPHome lights so they can participate in lighting scenes alongside other Control4 dimmers @@ -930,17 +890,17 @@ Control4, you can file an issue on GitHub: ### Added -- Added Event entity support: stateless triggers (button presses, - gestures, doorbell rings) now create Control4 events for programming - and track the last event type in a variable -- Added Date, Time, and Datetime entity support: configurable date/time - values on the device are exposed as writable string variables - (YYYY-MM-DD, HH:MM:SS, YYYY-MM-DD HH:MM:SS) +- Added Event entity support: stateless triggers (button presses, gestures, + doorbell rings) now create Control4 events for programming and track the last + event type in a variable +- Added Date, Time, and Datetime entity support: configurable date/time values + on the device are exposed as writable string variables (YYYY-MM-DD, HH:MM:SS, + YYYY-MM-DD HH:MM:SS) - Added Climate entity support: ESPHome climate devices are exposed as - thermostatV2 sub-drivers with HVAC mode, setpoints, fan mode, presets, - and humidity control -- Added Select entity support: STRING variable with the current option, - writable via programming or variable writes + thermostatV2 sub-drivers with HVAC mode, setpoints, fan mode, presets, and + humidity control +- Added Select entity support: STRING variable with the current option, writable + via programming or variable writes - Added "Set Select" programming command with dynamic Select and Option dropdowns @@ -948,25 +908,25 @@ Control4, you can file an issue on GitHub: ### Fixed -- Fixed automatic driver updates not working when the leader instance is - removed from the project +- Fixed automatic driver updates not working when the leader instance is removed + from the project ## v20260325 - 2026-03-25 ### Fixed -- Fixed cover contact sensors sending duplicate notifications during - open/close operations -- Fixed Yale DoorSense contact sensor sending duplicate "Closed" - notifications on every poll cycle by tracking the last known door - status and only reporting on actual state changes +- Fixed cover contact sensors sending duplicate notifications during open/close + operations +- Fixed Yale DoorSense contact sensor sending duplicate "Closed" notifications + on every poll cycle by tracking the last known door status and only reporting + on actual state changes ## v20260319 - 2026-03-19 ### Fixed -- Fixed an issue where entities were no longer being detected reliably - on connection +- Fixed an issue where entities were no longer being detected reliably on + connection ## v20260318 - 2026-03-18 @@ -979,35 +939,34 @@ Control4, you can file an issue on GitHub: ### Added -- Added fan support with on/off, speed control (1-6 speed variants), - direction, and oscillation -- Added ESPHome Yale sub-driver for Yale/August BLE smart locks with - lock/unlock control, door sense, and battery monitoring +- Added fan support with on/off, speed control (1-6 speed variants), direction, + and oscillation +- Added ESPHome Yale sub-driver for Yale/August BLE smart locks with lock/unlock + control, door sense, and battery monitoring ## v20260217 - 2026-02-17 ### Added -- Added Bluetooth proxy support with scanner infrastructure, - advertisement parsing, and GATT connection management -- Added ESPHome Bluetooth Coordinator driver for multi-proxy aggregation - with RSSI-based routing and connection failover -- Added room presence tracking with RSSI-based detection, anti-flapping, - and contact sensor bindings -- Added ESPHome BTHome sub-driver for Shelly BLU and BTHome v1/v2 +- Added Bluetooth proxy support with scanner infrastructure, advertisement + parsing, and GATT connection management +- Added ESPHome Bluetooth Coordinator driver for multi-proxy aggregation with + RSSI-based routing and connection failover +- Added room presence tracking with RSSI-based detection, anti-flapping, and + contact sensor bindings +- Added ESPHome BTHome sub-driver for Shelly BLU and BTHome v1/v2 sensors +- Added ESPHome Govee sub-driver for temperature, humidity, and meat thermometer sensors -- Added ESPHome Govee sub-driver for temperature, humidity, and meat - thermometer sensors -- Added ESPHome SwitchBot sub-driver for Bot, Plug Mini, Meter, Motion, - and Contact devices +- Added ESPHome SwitchBot sub-driver for Bot, Plug Mini, Meter, Motion, and + Contact devices - Added device log forwarding to the ESPHome driver ## v20251031 - 2025-10-31 ### Fixed -- Fixed compatibility with ESPHome 2025.10.0 for devices configured - without passwords +- Fixed compatibility with ESPHome 2025.10.0 for devices configured without + passwords - Improved password authentication failure detection and error reporting ## v20251022 - 2025-10-22 @@ -1020,13 +979,12 @@ Control4, you can file an issue on GitHub: ### Added -- Added support for OpenSSL with "Encryption Key" authentication mode - across all applicable algorithms +- Added support for OpenSSL with "Encryption Key" authentication mode across all + applicable algorithms ### Fixed -- Fixed a bug with the authentication flow in the latest 2025.10.0 - firmware +- Fixed a bug with the authentication flow in the latest 2025.10.0 firmware ## v20250811 - 2025-08-11 @@ -1044,8 +1002,7 @@ Control4, you can file an issue on GitHub: ### Added -- Added support for encrypted connections using the device encryption - key +- Added support for encrypted connections using the device encryption key ## v20250619 - 2025-06-19