MQTT Provider

MQTT (Message Queuing Telemetry Transport) is a lightweight publish/subscribe messaging protocol popular in IoT and home automation. channelBar can subscribe to MQTT topics and display incoming messages directly in your menu bar — making it easy to monitor IoT devices, home automation systems, and sensors at a glance.

Connection Setup

MQTT connections are managed under Settings → Connections → MQTT Connections. Each connection defines the broker address, port, and optional authentication credentials. You can configure multiple connections to different brokers. For details on adding and managing connections, see Managing Connections.

Topic Groups

Each channel can have multiple topic groups. A topic group is associated with a specific MQTT connection and contains one or more topic configurations. This allows subscribing to topics from different brokers in a single channel, aggregating messages from multiple MQTT sources into one unified view.

Topic Configuration

Each topic within a topic group can be configured with the following settings:

Topic Patterns and Wildcards

MQTT supports two wildcard characters for flexible topic subscriptions:

• + — Single-level wildcard. Matches exactly one topic level. For example, home/+/temperature matches home/livingroom/temperature and home/kitchen/temperature, but not home/floor1/livingroom/temperature.
• # — Multi-level wildcard. Matches any number of topic levels. Must be the last character in the pattern. For example, sensors/# matches sensors/temperature, sensors/humidity, and sensors/floor1/room2/co2.

Extracting Values from JSON

When MQTT messages contain JSON payloads, use the JSON Path setting to extract specific values. For example, if a topic receives the following payload:

{"temperature": 23.5, "humidity": 65}

Setting the JSON Path to $.temperature extracts the value 23.5. Combined with a Prefix of 🌡 and a Suffix of °C, the displayed message becomes:

🌡 23.5 °C

Topic Discovery

channelBar can discover available MQTT topics automatically by subscribing to a broad pattern and listening for incoming messages. The following settings control discovery behavior:

• Discovery Root — Base topic pattern to subscribe to during discovery. Defaults to # (all topics).
• Discovery Duration — How long to listen for topics: 5 minutes, 30 minutes, 1 hour, or permanent.
• Topic Retention — How long discovered topics are cached: 7 days, 30 days, 90 days, or never (kept indefinitely).

Discovered topics can then be selected and added to your topic groups without manually typing the full topic path.

Processor Pipeline Integration

Topics can be linked to Processor Pipelines for advanced data transformation before display. This is useful for rounding numbers, filtering by threshold, mapping values to human-readable labels, and more. See Processor Pipelines for details on creating and configuring pipelines.

Activation

To enable MQTT for a channel:

1. Open Settings → Channels and select the desired channel.
2. Navigate to the Providers tab.
3. Enable MQTT.
4. Select an MQTT connection (or create one under Connections first).
5. Configure your topic groups and individual topics.