Push Notifications & Alarms

VWire can alert users from two sources:

1. Device-originated messages sent from firmware with notify(), alarm(), or email().
2. Dashboard notification rules that the server evaluates when a pin crosses a threshold, a device changes status, or data stops arriving.

---

Delivery channels

Channel	What the user sees	Requirements
In-app bell	A stored notification in dashboard history	User account access
Mobile push	A system notification on the VWire mobile app	Mobile app installed, signed in, permission granted, active push token
Email	Email to the account address or digest	Email notifications available on the plan and enabled in user settings

Delivery settings

The notification category toggles in account settings currently control email categories on the server. Push delivery itself depends on the mobile app being installed and allowed to receive notifications.

Plan support

The following features require a Pro plan or above:

Feature	Free	Pro+
In-app notification (bell)	✅	✅
Mobile push alert (notify())	✅	✅
In-app alarm record	✅	✅
Persistent FCM alarm push (alarm())	❌	✅
Email notifications (email() or automation email action)	❌	✅

On the Free plan, alarm() creates an in-app notification record but the persistent mobile alarm push (looping sound, full-screen UI) is not delivered. Calls to email() and the automation Send Email action are silently skipped.

---

Device-originated notifications

Vwire.notify(message)

Use notify() for a normal alert that should appear in notification history and, when the user has a registered mobile app, as a standard mobile push notification.

Vwire.notify("Temperature exceeded 85 C");

device.notify("Temperature exceeded 85 C")

Typical uses:

• Non-critical threshold warnings
• Job complete messages
• Maintenance reminders

Vwire.alarm(message, sound, priority, volume)

Use alarm() for conditions that need immediate attention. The mobile app turns the incoming alarm push into a full-screen alarm experience with looping audio and vibration, and VWire also records the alarm in notification history.

The current mobile alarm UI offers:

• STOP
• SNOOZE 5M

Alarm sound options:

Sound	Value	Use when
Default	default	General alarm tone
Warning	warning	Elevated but non-catastrophic condition
Urgent	urgent	Critical condition

Alarm parameters:

Parameter	Values	Notes
sound	default, warning, urgent	Defaults to default
priority	1, 2, 3	Included in the alarm payload for downstream handling
volume	0-100	Defaults to 50

Arduino examples:

Vwire.alarm("Leak detected");
Vwire.alarm("Tank level rising quickly", "warning", 2, 65);
Vwire.alarm("Pump failure", "urgent", 3, 90);

Python example:

device.alarm("Leak detected")
device.alarm("Tank level rising quickly", sound="warning", priority=2, volume=65)
device.alarm("Pump failure", sound="urgent", priority=3, volume=90)

Important behavior:

• Alarms are rate-limited to one per device per minute.
• If the user has no active mobile push token, the bell-history record still exists but the full alarm UI cannot open on a phone.
• Free plans do not include alarm notifications.

Vwire.email(subject, body)

Use email() when the message needs to arrive in the user's inbox rather than only inside the app.

Vwire.email("Daily Report", "All sensors nominal at 10:00 AM.");

device.email("Daily Report", "All sensors nominal at 10:00 AM.")

---

Notification rules from the dashboard

You can also create alert rules in the dashboard without changing firmware.

1. Open your project.
2. Go to Notifications.
3. Click + Add Rule.
4. Choose the device, pin, condition, and delivery channels.
5. Save the rule.

Supported rule types:

Rule type	Example
Pin threshold	V0 > 85
Device status	Device went offline
No data	No reading for 30 minutes

These rules create bell-history items and can also send push or email depending on the selected channels and user setup.

---

Delivery limits and throttling

VWire applies a few guardrails to reduce notification floods:

Limit	Behavior
Boot quiet window	Non-status notifications are suppressed for 3 seconds right after device connect/disconnect
General notification rate limit	Maximum 60 notifications per device per minute
Alarm rate limit	Maximum 1 alarm per device per minute

Add cooldown logic in firmware if a sensor can cross the same threshold repeatedly.

unsigned long lastNotify = 0;
const unsigned long COOLDOWN_MS = 60000;

void loop() {
  Vwire.run();

  if (criticalCondition() && millis() - lastNotify > COOLDOWN_MS) {
    lastNotify = millis();
    Vwire.notify("Critical condition detected");
  }
}

---

Alarm acknowledgment MQTT topic

When the user stops or snoozes an alarm in the mobile app, the cloud publishes an acknowledgment to:

vwire/{deviceId}/alarm_ack

Example payload after stop:

{
  "alarmId": "alarm_1740000000000",
  "action": "stopped",
  "timestamp": 1740000123456
}

Example payload after snooze:

{
  "alarmId": "alarm_1740000000000",
  "action": "snoozed",
  "snoozeMinutes": 5,
  "timestamp": 1740000123456
}

Current library note:

• The current Arduino and Python helper libraries do not expose a dedicated high-level alarm acknowledgment callback.
• If firmware must react to stop or snooze events today, subscribe to vwire/{deviceId}/alarm_ack in a custom MQTT client or extend the library.

---

Notification history

All accepted notifications are stored in notification history so the user can review them later, even when a mobile push was missed.

See Mobile App for app setup, Arduino Library for the full Arduino API, and Python Library for the Python equivalents.