FlowFuse · dimitrieh · Jul 6, 2026 · Jul 6, 2026 · Jul 6, 2026 · Jul 6, 2026
diff --git a/docs/install/configuration.md b/docs/install/configuration.md
@@ -115,8 +115,24 @@ Option        | Description
 
 ## MQTT Broker configuration
 
-By default, the platform runs without an MQTT broker. This restricts some features
-in the platform, such as the Project Nodes, Device Actions and Remote Device Editing.
+The platform uses an MQTT broker to provide real-time messaging between devices,
+Node-RED instances and the platform. The broker shipped with the platform's
+Docker Compose and Kubernetes installations is [EMQX](https://www.emqx.io/). It is
+deployed and configured automatically by those installers.
+
+By default, the platform runs without an MQTT broker. This restricts what features
+are available:
+
+- Without a broker: Project Nodes, Device Actions and Remote Device Editing are unavailable.
+- The following features additionally require the platform broker to be EMQX, as they
+  rely on EMQX-specific capabilities (its authentication hooks, per-team topic
+  namespacing and management API): the [Team Broker](/docs/user/teambroker.md),
+  [FlowFuse Expert](/docs/user/expert/index.md) and real-time updates in the platform UI.
+
+[Mosquitto](https://mosquitto.org/) is supported at a legacy level for existing
+installations: core platform messaging works, but the EMQX-dependent features listed
+above are unavailable. Replacing the platform broker with a different customer-supplied
+broker is not supported.
 
 If a broker has been setup in the platform, the following configuration is required:
 
@@ -216,19 +232,6 @@ Option        | Description
 `support.frontend.hubspot.trackingcode` | The numerical identifier within your [HubSpot Tracking Code](https://knowledge.hubspot.com/conversations/chat-widget-is-not-appearing-on-your-pages). Default: `null`
 
 
-## MQTT Broker configuration
-
-The platform depends on the [Mosquitto MQTT Broker](https://mosquitto.org/) to
-provide real-time messaging between devices and the platform.
-
-This is currently an *optional* component - the platform will work without the
-broker, but some features will not be available.
-
-Option         | Description
----------------|--------------
-`broker.url`   | The full url to the platform broker. This is used by the platform and Node-RED instances to connect to the broker. For example: `mqtt://localhost:1883`.
-`broker.public_url` | If set, this is the url provided to Devices to connect to the broker with. When running in a Docker or K8S environment, this url should be the externally addressable url the broker is provided on. This could be via WebSockets, for example: `ws://example.com:1884`
-
 ## AI Configuration
 
 Option         | Description

diff --git a/docs/install/kubernetes/README.md b/docs/install/kubernetes/README.md
@@ -92,7 +92,7 @@ Before you begin, ensure you have the following:
      - [Digital Ocean](digital-ocean.md)
      - MicroK8s
 5. **Ingress Controller:** [The Traefik](https://doc.traefik.io/traefik/) installed on the cluster.
-6. **EMQX Operator:** This is required to install the required MQTT broker when the Team Broker features are enabled. Instructions for installing the operator can be found [here](https://docs.emqx.com/en/emqx-operator/latest/getting-started/getting-started.html#install-emqx-operator)
+6. **EMQX Operator:** This is required to install the platform's MQTT broker when the broker is enabled. The broker provides device and instance communication, the Team Broker, and FlowFuse Expert. Instructions for installing the operator can be found [here](https://docs.emqx.com/en/emqx-operator/latest/getting-started/getting-started.html#install-emqx-operator)
 
 For a production-ready environment, we also recommend: 
 * **Database:** Prepare dedicated database on a external database server (see [FAQ](#how-to-use-external-database-server%3F) for more details)

diff --git a/docs/upgrade/README.md b/docs/upgrade/README.md
@@ -28,6 +28,20 @@ Details of how to upgrade can be found for each deployment model:
 To upgrade the version of Node-RED your Instances run (for example, moving to
 Node-RED 5.0), see [Upgrading the Node-RED version](./nodered-version.md).
 
+### Upgrading to 2.32
+
+#### Kubernetes: default MQTT broker is now EMQX
+
+From Helm chart v2.78.0, the chart deploys [EMQX](https://www.emqx.io/) as the platform
+MQTT broker, replacing Mosquitto. Existing installations are migrated automatically when
+upgrading the chart. If the broker is enabled, the
+[EMQX Operator](https://docs.emqx.com/en/emqx-operator/latest/getting-started/getting-started.html)
+must be installed on the cluster before upgrading.
+
+Mosquitto remains supported at a legacy level for existing installations, but the
+broker-based platform features (Team Broker, FlowFuse Expert, real-time UI updates)
+require EMQX. See [MQTT Broker configuration](../install/configuration.md#mqtt-broker-configuration).
+
 ### Upgrading to 2.6.0
 
 #### Required AWS EKS configuration change

diff --git a/docs/user/expert/index.md b/docs/user/expert/index.md
@@ -8,6 +8,8 @@ FlowFuse Expert is the AI built into FlowFuse and the Node-RED editor. It is not
 
 **FlowFuse Expert is automatically installed and available in all hosted and remote instances running within or connected to FlowFuse**, no manual installation or configuration required. For self-hosted Enterprise customers, FlowFuse Expert can be enabled on request. [Contact us](https://flowfuse.com/contact-us/) to get it set up on your infrastructure.
 
+> **Note:** On self-hosted installations, FlowFuse Expert requires an Enterprise license and the platform's EMQX-based MQTT broker with the Team Broker feature enabled (see [MQTT Broker configuration](/docs/install/configuration.md)). Expert communicates through a bridge between your platform broker and FlowFuse's central Expert service, which is set up as part of enabling Expert. Installations running without EMQX, for example legacy Mosquitto-based installs, cannot enable Expert.
+
 ## Managing AI Features
 
 **Team owners** can enable or disable all AI features for their team from the team settings page. When disabled, the Expert chat panel with all AI feature will get removed for that team. Running instances need to be restarted for the change to take full effect.

diff --git a/docs/user/teambroker.md b/docs/user/teambroker.md
@@ -8,6 +8,22 @@ When FlowFuse is deployed with an Enterprise license from v2.11.0 onwards comes
 
 This is a single shared MQTT broker, but each team has their own separate topic space and the ability to provision credentials for clients.
 
+## What the Team Broker is
+
+The Team Broker is a multi-tenant MQTT broker service built into the FlowFuse platform:
+one broker instance, managed by the platform, where every team gets its own fully
+isolated topic space and can provision client credentials in a self-service way. It
+removes the need to install and operate a separate broker to move MQTT data between
+devices, Node-RED instances and other clients.
+
+Under the hood the Team Broker is provided by [EMQX](https://www.emqx.io/), and the
+platform integrates with EMQX-specific capabilities for client authentication, per-team
+topic isolation and bridging. The Team Broker cannot be backed by a different broker
+(see [MQTT Broker configuration](/docs/install/configuration.md)). If your company
+already operates its own MQTT broker, that broker can still be connected to FlowFuse
+as an external broker to browse its topic hierarchy alongside the Team Broker, and
+Node-RED instances can connect to it directly as a regular MQTT client.
+
 ## Foreword
 FlowFuse offers zero config MQTT integration with the Team Broker via the [FlowFuse MQTT Nodes](/docs/user/mqtt-nodes/) that greatly simplifies the whole process by removing the need for manual configuration.