MQTT Sensor Alerts: A Human-Gated Workshop Workflow

A workshop sensor crosses a threshold. Someone needs to know whether it is a brief spike, a repeated reading, or an old value replayed after reconnecting. A useful alert answers those questions before asking the operator to decide what happens next.

Apteva — the open-source AI operating system — provides an open-source, self-hostable AI agent framework and runtime for ongoing autonomous operations. In this workflow, the agent monitors device events and prepares an evidence-rich notification. Physical action stays behind an explicit human decision.

The example below follows the official Apteva IoT guide. It is an illustrative design, not a tested workshop deployment or a safety system. The guide's example threshold, two consecutive sensor values above 35, is a demonstration value: it has no implied unit or safe operating meaning. Choose real thresholds with someone who understands the equipment and sensor.

Give each layer one job

MQTT is a publish/subscribe messaging protocol. Devices send messages through a broker, and subscribers receive messages on matching topics. It provides transport semantics; your application supplies sensor meaning, alert policy, permissions, and the operator's decision process.

The OASIS MQTT 3.1.1 standard describes a payload-agnostic transport. Receiving a message is therefore different from understanding its freshness, and acknowledging a command message is different from confirming that equipment changed state.

Apteva's guide assigns transport and credentials to MQTT Broker and device manifests, telemetry, and correlated command responses to Devices. The surrounding runtime lets an agent retain context and respond to events. For that broader distinction, see MCP versus agent frameworks.

Start with one device and narrow access

Use a reachable Apteva installation, MQTT Broker, Devices, and one compatible client. The official walkthrough uses an ESP32; it also links maintained Arduino and Python examples. Devices requires MQTT Broker 0.3.0 or newer, according to the guide.

Provision a stable device identity such as workshop-esp32. Save its returned credentials outside source control. Leave anonymous access disabled and keep a separate credential for each device. The documented device identity is restricted to its assigned topics rather than sharing unrestricted broker access.

For this device, telemetry belongs on devices/workshop-esp32/telemetry; availability, state, and the capability manifest have their own topics. Commands and correlated responses use separate topics too. Follow the official client contract rather than inventing a new payload that the Devices app may not understand.

The manifest describes exposed variables, functions, and pins. Apteva documents GPIO as deny-by-default: a pin must be declared before it can be controlled through Devices. For a monitoring pilot, expose only the readings needed and omit unnecessary writable capabilities. Check the agent's available tools separately; a device manifest and an agent permission policy solve different problems.

Keep the broker on a trusted network, or protect remote transport through an appropriate private network or TLS gateway, as the guide recommends. Its port 1883 example is not evidence that the connection is encrypted. Verify the actual transport before sending credentials beyond a trusted network.

Turn two readings into a defined alert condition

The documentation proposes notifying an operator when a sensor remains above 35 for two consecutive samples. To implement that usefully, define what counts as a sample and how long evidence remains relevant.

Start with an explicit policy:

• Count two distinct, valid readings from the same device and sensor.
• Require both readings to exceed the configured threshold.
• Set a maximum permitted age and gap based on the sampling interval.
• Reset the candidate pair after an invalid reading, a stale gap, or a reconnect that breaks continuity.
• Keep one open incident for the condition, with updates rather than repeated identical alerts.

These are recommended application rules, not claims that Apteva automatically applies them. Record them in the implementation and verify them with replayed events before relying on the workflow.

Duplicates deserve particular attention. MQTT QoS 1 provides at-least-once delivery, so duplicates can occur. Use a device sequence number or another suitable stable sample identity when your client supports it; receiving the same sample twice should not satisfy a two-sample rule. Decide how to handle missing or out-of-order samples as well.

Retained state helps a subscriber recover context after connecting. Treat that recovered value as historical until its age and provenance are established, not as a new measurement. A fresh transport connection alone says little about the freshness of the sensor reading.

For a simple threshold, deterministic validation and counting are usually easier to inspect than asking a language model to infer whether two events qualify. Let the agent explain the accepted evidence and coordinate follow-up around that rule.

Make the notification useful to the operator

A good notification carries enough context to support a decision without hiding uncertainty. Here is hypothetical alert content, with invented values and times for illustration:

Workshop controller: repeated high sensor reading
Device: workshop-esp32
Previous: 36 at 10:14:00 UTC
Current: 38 at 10:14:30 UTC
Rule: two distinct fresh samples above 35
Availability: reported online; last seen 10:14:30 UTC
Recent command failures: none in the reviewed interval
Action taken: notification only; no device command sent
Next step: inspect the equipment and acknowledge this alert

In a real installation, include the sensor's configured unit, the evidence age, and a link to the relevant device history. Say which interval was reviewed rather than implying that no command has ever failed.

Apteva documents connection, state, telemetry, and command lifecycle events, allowing an agent to react without continuously polling hardware. Connect an authorized notification channel and test it end to end. An event reaching an agent and a message reaching the operator are separate outcomes.

Assign a primary recipient, a backup, and an acknowledgement window suitable for the operation. If the first recipient does not acknowledge, the proposed escalation should identify the existing incident and its latest evidence. Choose the timing locally; this article supplies no universal response deadline.

For an offline event, report when the device was last seen, the latest known reading with its timestamp, and relevant recent command failures. Describe availability as a connectivity signal, not a diagnosis of the equipment. If telemetry is stale, make that the headline rather than presenting an old high value as current.

Put physical action behind an enforceable gate

Start the agent with monitoring and notification permissions. The official guide explicitly instructs it to seek approval before writing pins or calling firmware functions. Pair that instruction with restrictive tool access; a sentence in a prompt should not be your only protection against an unwanted write.

A useful initial operating rule is:

Monitor this device's availability and telemetry.
Explain qualifying alerts with both samples and timestamps.
Notify the designated operator and track acknowledgement.
Do not write pins or call firmware functions without explicit approval.
Report missing or stale evidence instead of inferring current state.

For the first pilot, keep physical operations with a trained operator using established equipment procedures. If you later add an approval-enabled command path, design it as a separate, narrowly scoped capability. Bind approval to a specific device, operation, value, and evidence snapshot, with an expiry. Changed conditions should require a new decision. Those are implementation recommendations, not a documented turnkey approval contract for Devices.

After any authorized command, inspect the correlated response and fresh observed state. A timeout leaves the result unknown; blindly repeating a physical command may create a second action. Equipment interlocks, emergency stops, and other safety controls remain responsibilities of the equipment system and its qualified operators.

Test the workflow before handing it responsibility

Build confidence in stages, keeping records of the exact client, permissions, rules, and observed results.

1. Verify identity. Confirm the intended device authenticates and cannot publish or subscribe outside its assigned topics.
2. Verify evidence. Inspect the manifest, current state, availability, telemetry history, timestamps, and configured units.
3. Replay the threshold. Try below-threshold readings, one high sample, two qualifying highs, and a recovery. Confirm the expected incident transitions.
4. Break continuity. Replay a duplicate, an old retained value, an out-of-order sample, a long gap, and a reconnect. Check that none silently becomes a valid new pair.
5. Exercise communication. Test actual notification receipt, acknowledgement, and escalation to the configured backup. Record failed deliveries honestly.
6. Exercise restrictions. Confirm the monitoring agent cannot invoke physical operations. Test any later approval path separately in a controlled environment.
7. Recover deliberately. Restart the relevant components and inspect open incidents, last-known evidence, and unresolved command outcomes before resuming.

This article verifies the documented design, not those hardware or delivery tests. Complete them in your environment before describing your installation as working. Persistent incident ownership also needs attention; our guide to long-running agents explains the runtime concepts without replacing device-specific testing.

The strongest first version is deliberately small: one sensor, one explicit rule, one accountable recipient, and no unattended physical changes. Explore the Apteva IoT guide to implement that monitoring path with the official client examples.