Alerts

Alerts watch your MQTT traffic and notify you by push and email when something happens — a topic matches a condition, or a device goes quiet.

Maker+ Alerts are available on the Maker and Pro tiers. See Account & billing for how the tiers compare.

How topic alerts work

A topic rule watches a single MQTT topic and fires when an inbound payload matches your chosen mode:

• Exact — fires only when the payload is exactly equal to the value you set.
• Contains — fires when the payload contains your value as a substring anywhere in the message.
• Any — fires on every message published to the topic; no match value needed.

For example, a rule on devices/greenhouse-1/alerts with mode Exact and value high_temp fires the moment your firmware publishes high_temp to that topic.

How offline alerts work

An offline rule watches a heartbeat topic instead of a condition. Your firmware publishes to that topic on a regular interval while it's healthy; you choose a silence threshold — how long the topic can go quiet before that counts as offline.

• IoT Parrot records the last time it saw a message on that topic — every heartbeat resets the clock.
• A periodic check looks for rules that have been silent longer than their threshold and fires them.
• There is no server-side pinging: the device is never contacted. Silence is the only signal, so the heartbeat publish itself must keep happening — on an interval shorter than the silence threshold.

Recommended topic convention

Use a dedicated, low-traffic topic per device just for alerts (e.g. devices/<id>/alerts) and a separate one for heartbeats (e.g. devices/<id>/heartbeat), rather than pointing a rule at a high-frequency telemetry topic your dashboard widgets already use.

• Exact/contains rules evaluate every message published to their topic — a fast telemetry stream means constant, mostly-wasted evaluation.
• An Any rule on a busy topic fires (and re-enters cooldown) far more often than you probably want.
• A quiet, dedicated topic keeps behavior predictable and cheap, and makes the firmware logic easy to reason about — publish only when something is actually worth reporting.

Channels, cooldown & daily caps

Alerts can notify you by push (mobile app only — there is no web push in this version) and/or email. By default email goes to your account address, but each rule can override that with a different email target. After a rule fires, it won't fire again until its cooldown window elapses, even if the condition keeps matching.

• Each tier has a maximum number of alert fires per day, reset at UTC midnight (see the table below).
• The first time you hit that daily cap, you get one "daily limit reached" push — you won't be spammed with a warning per rate-limited fire.
• Fires that get rate-limited after the cap is hit still write an entry to alert history (flagged accordingly) so you can see what would have fired.

Alert history

Every time a rule fires, IoT Parrot records it in alert history, viewable in the app. This includes fires that were rate-limited after you hit the daily cap — those are flagged so you can tell why a notification didn't arrive. History is retained up to the per-tier limit in the table above; older events are trimmed automatically.

Sample firmware

This ESP32 / Arduino sketch (WiFi + PubSubClient only, so it compiles as-is on a stock ESP32 Arduino-core install) demonstrates the two firmware-side responsibilities alert rules depend on: publishing on a threshold crossing (for topic rules) and publishing a periodic heartbeat (for offline rules).

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

const char* WIFI_SSID     = "your-wifi-ssid";
const char* WIFI_PASSWORD = "your-wifi-password";
const char* MQTT_HOST     = "your-broker-host";
const int   MQTT_PORT     = 1883;

// Dedicated, low-traffic topics just for alerts — NOT the same topic your
// telemetry/dashboard widgets publish to. See "Recommended topic
// convention" above for why.
const char* ALERT_TOPIC     = "devices/greenhouse-1/alerts";
const char* HEARTBEAT_TOPIC = "devices/greenhouse-1/heartbeat";

const float TEMP_THRESHOLD_C = 35.0;
const unsigned long HEARTBEAT_INTERVAL_MS = 60000; // 1 minute

WiFiClient espClient;
PubSubClient mqtt(espClient);
unsigned long lastHeartbeat = 0;
bool wasOverThreshold = false;

void connectWifi() {
  WiFi.begin(WIFI_SSID, WIFI_PASSWORD);
  while (WiFi.status() != WL_CONNECTED) delay(250);
}

void connectMqtt() {
  while (!mqtt.connected()) {
    mqtt.connect("greenhouse-1");
    if (!mqtt.connected()) delay(1000);
  }
}

float readTemperatureC() {
  // Replace with your actual sensor read.
  return 25.0;
}

void setup() {
  connectWifi();
  mqtt.setServer(MQTT_HOST, MQTT_PORT);
}

void loop() {
  if (!mqtt.connected()) connectMqtt();
  mqtt.loop();

  // 1) Threshold-crossing alert. Publish once on the rising edge rather
  //    than on every loop — the cooldown will suppress repeat fires
  //    anyway, but a quiet topic is cheaper for everyone.
  float tempC = readTemperatureC();
  bool overThreshold = tempC > TEMP_THRESHOLD_C;
  if (overThreshold && !wasOverThreshold) {
    mqtt.publish(ALERT_TOPIC, "high_temp");
  }
  wasOverThreshold = overThreshold;

  // 2) Periodic heartbeat, required for "device offline" rules. The
  //    server never pings the device — it only knows you're alive because
  //    messages keep arriving here, so this publish must keep happening
  //    on an interval shorter than the rule's silence threshold.
  unsigned long now = millis();
  if (now - lastHeartbeat >= HEARTBEAT_INTERVAL_MS) {
    mqtt.publish(HEARTBEAT_TOPIC, "online");
    lastHeartbeat = now;
  }

  delay(100);
}