https://github.com/finitelabs/control4-mqtt
Control4 drivers for MQTT integration. Connect your Control4 system to any MQTT broker to control switches, buttons, and contact sensors.
https://github.com/finitelabs/control4-mqtt
Last synced: 2 months ago
JSON representation
Control4 drivers for MQTT integration. Connect your Control4 system to any MQTT broker to control switches, buttons, and contact sensors.
- Host: GitHub
- URL: https://github.com/finitelabs/control4-mqtt
- Owner: finitelabs
- License: agpl-3.0
- Created: 2025-12-29T19:17:27.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-04-14T21:06:18.000Z (2 months ago)
- Last Synced: 2026-04-14T22:23:13.971Z (2 months ago)
- Language: Lua
- Homepage:
- Size: 1.3 MB
- Stars: 8
- Watchers: 2
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
---
# Overview
> DISCLAIMER: This software is neither affiliated with nor endorsed by either
> Control4 or MQTT.
The MQTT Broker driver connects Control4 to an MQTT broker (such as Mosquitto,
HiveMQ, or other MQTT-compatible platforms). It manages the connection and
provides pub/sub services to child drivers that connect via the MQTT broker
connection binding.
## Driver Suite
The MQTT driver suite consists of two drivers:
| Driver | Direction | Purpose |
| ------------------ | --------- | ------------------------------------------------------------------------------------------------ |
| **MQTT Broker** | N/A | Connection management to your MQTT broker |
| **MQTT Universal** | Inbound | External MQTT device -\> Control4 (create relays, contacts, buttons, variables from MQTT topics) |
**Typical Setup:**
1. Add the **MQTT Broker** driver and configure your broker connection
2. Add **MQTT Universal** if you need to bring external MQTT devices into
Control4
# Index
- [System Requirements](#system-requirements)
- [Features](#features)
- [Installer Setup](#installer-setup)
- [Driver Installation](#driver-installation)
- [Driver Setup](#driver-setup)
- [Driver Properties](#driver-properties)
- [Cloud Settings](#cloud-settings)
- [Driver Settings](#driver-settings)
- [MQTT Settings](#mqtt-settings)
- [Driver Actions](#driver-actions)
- [Programming](#programming)
- [Support](#support)
- [Changelog](#changelog)
# System Requirements
- Control4 OS 3.3+
- An MQTT broker accessible on the local network
# Features
- Local network communication requiring no cloud services
- Connects to any standard MQTT broker
- Supports username/password authentication
- Manages subscriptions for connected child drivers
- Automatic reconnection on disconnect
- Message caching for late-subscribing devices
# Installer Setup
## 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.
1. Download the latest `control4-mqtt.zip` from
[Github](https://github.com/finitelabs/control4-mqtt/releases/latest).
2. Extract and
[install](<(https://www.control4.com/help/c4/software/cpro/dealer-composer-help/content/composerpro_userguide/adding_drivers_manually.htm)>)
the `mqtt_broker.c4z` and `mqtt_universal.c4z` drivers.
3. Use the "Search" tab to find the "MQTT Broker" driver and add it to your
project.
> ⚠️ A **_single_** broker driver instance is required per broker you wish
> to connect to.
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 run action [`Reconnect`](#reconnect) from the actions tab. Then check
the lua output window for more information.
## Driver Setup
### Driver Properties
#### Cloud Settings
##### Automatic Updates
Turns on/off the GitHub cloud automatic updates.
##### Update Channel
Sets the update channel for which releases are considered during an automatic
update from the GitHub repo releases.
#### Driver Settings
##### Driver Status (read-only)
Displays the current status of the driver.
##### Driver Version (read-only)
Displays the current version of the driver.
##### Log Level \[ Fatal \| Error \| Warning \| **_Info_** \| Debug \| Trace \| Ultra \]
Sets the logging level. Default is `Info`.
##### Log Mode \[ **_Off_** \| Print \| Log \| Print and Log \]
Sets the logging mode. Default is `Off`.
#### MQTT Settings
##### Broker Address
Sets the broker 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.
##### Port
Sets the broker port. The default port for most brokers is `1883`.
##### Username
Sets the username for broker authentication (optional).
##### Password
Sets the password for broker authentication (optional).
##### Keep Alive
Sets the keep-alive interval in seconds. Default is `60`.
#### Driver Actions
##### Reconnect
Manually trigger a reconnection to the MQTT broker.
##### Update Drivers
Trigger all MQTT drivers to update from the latest release on GitHub, regardless
of the current version.
### Programming
**Events:**
- **Broker Connected** - Fires when the driver connects to the MQTT broker
- **Broker Disconnected** - Fires when the driver disconnects from the MQTT
broker
**Conditionals:**
- **Broker Connected** - Check if the broker is connected or disconnected
# Support
If you have any questions or issues integrating this driver with Control4, you
can file an issue on GitHub:
# Changelog
## v20260414 - 2026-04-14
### Fixed
- Fixed MQTT Universal variables losing their programming "Set Variable"
callback after the first inbound MQTT message on the variable's state topic.
- Fixed MQTT Universal BOOL variables not toggling reliably from programming due
to incorrect serialization to Control4.
- Fixed MQTT Universal variables losing their writable state after a controller
reboot or driver reload.
- Fixed automatic driver updates not working when the leader instance is removed
from the project
## v20260217 - 2026-02-17
### Changed
- Broker properties (Automatic Updates, Update Channel) now automatically sync
across all MQTT Broker driver instances.
- Temperature conversions (Fahrenheit/Celsius) now use single decimal precision
instead of rounding to the nearest integer or half degree.
### Fixed
- Fixed variable restore order during driver initialization on controller
reboot.
## v20260120 - 2026-01-27
### Fixed
- Fixed incorrect DriverCentral product ID in MQTT Universal driver.
## v20260120 - 2026-01-20
### Fixed
- Fixed consumer bindings (e.g., BUTTON_LINK for Event entities) not restoring
their connections on controller reboot. The bindings module now tracks
connection info and automatically re-establishes consumer binding connections
when bindings are restored.
## v20260119 - 2026-01-19
### Added
- Added Event entity type to MQTT Universal driver for receiving MQTT events and
triggering Control4 buttons/keypads.
### Changed
- Updated MQTT Broker documentation to include Programming section with events
and conditionals.
- Updated MQTT Universal documentation to include missing read-only properties
and BUTTON_LINK binding information.
### Removed
- Removed deprecated MQTT Switch, MQTT Contact, and MQTT Button drivers.
## v20260117 - 2026-01-17
### Added
- Added the MQTT Universal driver for managing multiple MQTT devices from a
single driver instance. Supports relays, contacts, buttons, variables, and
sensors with features including:
- Keypad button linking for MQTT buttons
- Device availability conditionals and events
- State variables for relay and contact items
- JSONPath value extraction for complex JSON payloads
- Added "Broker Connected" conditional and events to the MQTT Broker driver.
### Deprecated
- Deprecated the MQTT Switch, MQTT Contact, and MQTT Button drivers. Use MQTT
Universal instead. This is the terminal release for these drivers.
## v20251229 - 2025-12-29
### Added
- Initial Release