MQTT devices (LEDs, gongs, clocks, Home Assistant)

Add a device on the MQTT devices page of the dashboard; the PushBell MQTT broker passes notifications on to it. When a sale comes in, the gong in the shop rings, the LED strip lights up, the clock scrolls a message. MQTT devices are included from the Pro plan; the number of devices depends on the plan. Devices aren’t people and don’t count toward your quota.

Broker


Host	`mqtt.pushbell.app`
TLS (recommended)	`8883`
Plain	`1883` (WLED and the Ulanzi TC001 don’t support TLS)
WebSocket	`wss://mqtt-ws.pushbell.app`

Every device has its own username and password. The username is also the device’s topic code; a device only sees its own topics. The password is shown once; if you lose it, use New password (the old one stops working right away).

Without TLS the password can be read on the network. That’s why acknowledging emergencies with the device’s button is off by default; turn it on in the device’s settings if you trust your network.

Look

For every device you choose how notifications look:

Color, effect (WLED), duration: when it’s over, the device goes back. WLED turns off or loads the preset you pick.
Relay and beeps (Tasmota), melody (AWTRIX NG, RTTTL).
By type: a different look per notification type key. For example sale gold with fireworks, refund red. Skip hides that type on the device.
For emergencies: red and until acknowledged by default. Once acknowledged (in the app, the dashboard, a channel or with the device’s button) the alert on the device stops; it also stops if it expires unacknowledged.

Projects selects which projects’ notifications the device gets. End-to-end encrypted notifications don’t go to devices.

Show test shows a test notification on the device. The list also shows whether the device is online (WLED, Tasmota and AWTRIX NG report it). With an Offline alert you get a notification when the device stays disconnected that many minutes, and another when it is back.

A sales gong in 5 minutes

Get a smart plug or relay running Tasmota and connect a bell or beacon to it. (For an LED strip, use WLED.)
In the dashboard: MQTT devices → Add device → Tasmota relay / siren. Give it a name and set Duration to 2 seconds. Under By type add your sale type; if it shouldn’t ring for other notifications, pick Only show the types below in Look.
Copy the Backlog command from the setup window, paste it into Console in Tasmota’s web UI and press Enter. The device reconnects.
Press Show test: the gong rings. From now on it rings for every sale notification.

WLED

In WLED: Config → Sync Interfaces → MQTT:

Turn on Enable MQTT.
Broker mqtt.pushbell.app, Port 1883, the Username and Password from the setup window.
Set Device Topic to the topic from the setup window (pb/…).
For button acknowledgement, turn on Publish on button press.
Save, then reboot the device.

WLED doesn’t support TLS (1883 only). To go back to a preset afterwards, save the preset in WLED and enter its number in the look.

Tasmota

The command in the setup window does it all at once:

Backlog MqttHost mqtt.pushbell.app; MqttPort 8883; MqttUser pb…; MqttPassword …; Topic pb…; FullTopic %prefix%/%topic%/; SetOption103 1

TLS (SetOption103 1, port 8883) is only in tasmota32 (ESP32) builds. On ESP8266 use it without TLS: MqttPort 1883 and no SetOption103.
The relay turns on for the duration with Power1 ON; Delay; Power1 OFF. If a buzzer GPIO is set, it beeps the chosen number of times. For emergencies it stays on until acknowledged.
Button acknowledgement: SetOption73 1 (the button is detached from the relay and presses go to PushBell), and turn on The device’s button acknowledges emergencies in the device’s settings.

Ulanzi clock (AWTRIX NG)

In AWTRIX NG: System → MQTT: the host, port, username, password and the topic from the setup window as Prefix. Save and reboot. Notifications scroll with title and message in your color; emergencies stay on screen until acknowledged. The middle button acknowledges (if enabled).

The TC001 has no TLS (1883); the TC002 can use TLS (8883).
AWTRIX NG’s license (PolyForm Noncommercial) doesn’t allow commercial use: using it in a shop or at work needs its author’s permission. For businesses we recommend WLED or Tasmota.

Home Assistant

In Home Assistant a PushBell device has three parts: the Notification event (notification, emergency, acknowledged), the Last notification sensor (the title; message, project and priority in its attributes) and the Acknowledge button (acknowledges the emergency). Build your automations with them.

Directly: Settings → Devices & services → add (or configure) MQTT: host mqtt.pushbell.app, port 8883, TLS on, the username and password from the setup window. In the MQTT options set the discovery prefix to pb/…/ha and the birth message topic to pb/…/ha/status (both are in the setup window).

With your local Mosquitto (bridge): if Home Assistant already uses its Mosquitto add-on, add a bridge to it:

connection pushbell
address mqtt.pushbell.app:8883
bridge_capath /etc/ssl/certs
remote_username pb…
remote_password …
remote_clientid pb…
topic pb/pb…/# both 1

Set the discovery prefix in Home Assistant to pb/…/ha as well.

ESP32 / Arduino

Your code subscribes to pb/<username>/notify; notifications arrive as JSON:

{"event_type": "notification", "id": "0199f…", "project": "Store", "type": "sale", "title": "New sale",
 "message": "$125.00", "priority": 0, "color": "#ffd700", "duration": 5, "timestamp": 1793000000}

Emergencies have "event_type": "emergency" and a receipt; once acknowledged, {"receipt": "…"} arrives on pb/<username>/dismiss. To acknowledge with the device’s button, publish {"receipt": "…"} to pb/<username>/ack. If you publish online / offline (last will) to pb/<username>/state, the dashboard shows the status.

Example with PubSubClient 2.8, ArduinoJson 7 and arduino-esp32 3.x:

#include <WiFi.h>
#include <WiFiClientSecure.h>
#include <PubSubClient.h>
#include <ArduinoJson.h>

const char* WIFI_SSID = "…";
const char* WIFI_PASS = "…";
const char* MQTT_USER = "pb…";  // dashboard → MQTT devices → Setup
const char* MQTT_PASS = "…";
// ISRG Root X1: the contents of https://letsencrypt.org/certs/isrgrootx1.pem
const char* ROOT_CA = R"(-----BEGIN CERTIFICATE-----
…
-----END CERTIFICATE-----)";
const int LED = 2, BUTTON = 0;

WiFiClientSecure net;
PubSubClient mqtt(net);
String base = String("pb/") + MQTT_USER;
String receipt;

void onMessage(char* topic, byte* payload, unsigned int len) {
  JsonDocument doc;
  if (deserializeJson(doc, payload, len)) return;
  String t = topic;
  if (t == base + "/notify") {
    digitalWrite(LED, HIGH);  // doc["title"], doc["message"], doc["color"], doc["duration"]
    receipt = doc["receipt"] | "";
  } else if (t == base + "/dismiss") {
    digitalWrite(LED, LOW);
    receipt = "";
  }
}

void connect() {
  while (!mqtt.connected()) {
    // If the connection drops, the broker publishes "offline" (last will).
    if (mqtt.connect(MQTT_USER, MQTT_USER, MQTT_PASS, (base + "/state").c_str(), 1, true, "offline")) {
      mqtt.publish((base + "/state").c_str(), "online", true);
      mqtt.subscribe((base + "/notify").c_str(), 1);
      mqtt.subscribe((base + "/dismiss").c_str(), 1);
    } else {
      delay(5000);
    }
  }
}

void setup() {
  pinMode(LED, OUTPUT);
  pinMode(BUTTON, INPUT_PULLUP);
  WiFi.begin(WIFI_SSID, WIFI_PASS);
  while (WiFi.status() != WL_CONNECTED) delay(500);
  net.setCACert(ROOT_CA);
  mqtt.setServer("mqtt.pushbell.app", 8883);
  mqtt.setBufferSize(2048);
  mqtt.setCallback(onMessage);
}

void loop() {
  if (!mqtt.connected()) connect();
  mqtt.loop();
  if (digitalRead(BUTTON) == LOW && receipt != "") {  // acknowledge the emergency with the button
    mqtt.publish((base + "/ack").c_str(), ("{\"receipt\":\"" + receipt + "\"}").c_str());
    receipt = "";
    delay(500);
  }
}

Other systems

The Other (JSON) type uses the same topics and JSON as ESP32; Node-RED, your own server or any other software can connect.

To send notifications to your own MQTT broker instead of PushBell’s, use Channels → Your MQTT broker (Channels): every notification is published to your topic as JSON.