Your MQTT Broker Delivered the Message. But Did Your Device Actually Execute the Command?

Let's look at how this can be implemented in a backend application.

First, we need a database model to track commands.

A simplified SQLAlchemy model could look like this:

import uuid

from sqlalchemy import (
    Column,
    String,
    DateTime,
    JSON,
    Integer,
    func
)

from sqlalchemy.dialects.postgresql import UUID

from database import Base


class DeviceCommand(Base):

    __tablename__ = "device_commands"

    id = Column(
        UUID(as_uuid=True),
        primary_key=True,
        default=uuid.uuid4
    )

    device_id = Column(
        String,
        nullable=False,
        index=True
    )

    command_type = Column(
        String,
        nullable=False
    )

    status = Column(
        String,
        nullable=False,
        default="CREATED"
    )

    payload = Column(
        JSON,
        nullable=False
    )

    attempts = Column(
        Integer,
        nullable=False,
        default=0
    )

    created_at = Column(
        DateTime(timezone=True),
        server_default=func.now()
    )

    completed_at = Column(
        DateTime(timezone=True),
        nullable=True
    )

This model provides a persistent record of every command sent to a device.

Now let's create an API endpoint.

from fastapi import APIRouter, HTTPException
from uuid import uuid4

router = APIRouter()


@router.post("/devices/{device_id}/commands")
async def send_device_command(
    device_id: str,
    command: str
):

    command_id = str(uuid4())

    payload = {
        "command_id": command_id,
        "device_id": device_id,
        "command": command,
        "parameters": {}
    }

    # 1. Persist command as CREATED.
    # 2. Publish through MQTT.
    # 3. Wait for broker publisher confirmation.
    # 4. Update status to PUBLISHED.

    return {
        "command_id": command_id,
        "device_id": device_id,
        "status": "PUBLISHED"
    }

The omitted database and MQTT operations are deliberate placeholders; a production implementation must persist the command before publication and only mark it PUBLISHED after the configured broker confirmation succeeds.

For stronger reliability, command creation and an outbox event can be committed in the same PostgreSQL transaction. A background publisher can then publish the command without losing the intent if the broker is temporarily unavailable.

This also prevents the API from becoming tightly coupled to the availability of the MQTT broker.

Receiving device acknowledgements

The device should publish an application-level response after processing the command.

For example:

{
    "command_id": "cmd-10245",
    "device_id": "device-101",
    "status": "SUCCEEDED",
    "completed_at": "2026-11-11T09:01:12Z",
    "result": {
        "restart_completed": true
    }
}

A backend MQTT consumer listens to the acknowledgement topic:

async def handle_device_acknowledgement(
    message: dict,
    session
):

    command_id = message.get("command_id")

    command = (
        session.query(DeviceCommand)
        .filter(
            DeviceCommand.id == command_id
        )
        .with_for_update()
        .first()
    )

    if not command:
        return

    if command.status in {
        "SUCCEEDED",
        "FAILED",
        "EXPIRED"
    }:
        return

    if message["device_id"] != command.device_id:
        return

    command.status = message["status"]

    session.commit()

This is an illustrative starting point. A real implementation should validate device identity and authorization, validate allowed state transitions, handle malformed or delayed acknowledgements, and commit updates transactionally.

The backend now has an application-level confirmation instead of relying only on MQTT publication status.

5. Handling Real-World Device Failures

Implementing command tracking is only the beginning.

Production IoT systems must account for situations where devices and networks behave unpredictably.

Here are some important cases.

Scenario A: Device receives the same command twice

With QoS 1, duplicate message delivery is possible.

Imagine a device receives the same restart command twice.

Without duplicate protection, it might execute the operation multiple times.

The solution is application-level idempotency.

The device should maintain processed command identifiers and reject or safely acknowledge commands it has already handled.

For operations involving persistent device state, the deduplication record should survive reboots where necessary.

Scenario B: Device disconnects during execution

Suppose a device receives a configuration update and disconnects before publishing its acknowledgement.

Did the configuration update succeed?

The backend cannot safely assume either outcome.

It should keep the command in an uncertain or pending state until it receives a valid acknowledgement or performs a reconciliation process.

For critical configuration updates, the device can report its actual configuration after reconnecting.

Scenario C: An old command arrives late

Imagine an operator sends a configuration command, but the device remains offline for several hours.

When it reconnects, should it execute that old command?

Not necessarily.

Commands should have an application-level expiry timestamp.

The device should compare the current time against the expiry and reject commands that are no longer valid.

MQTT 5 also provides Message Expiry Interval, which can help limit how long a message remains available for delivery.

However, broker-side expiry does not replace device-side validation, particularly when messages have already been delivered or persisted elsewhere.

Scenario D: The backend times out, but the device completed the operation

This is another important distributed-systems problem.

The backend waits for an acknowledgement, but the network drops the response.

The device successfully performs the operation, while the backend marks it TIMED_OUT.

Automatically retrying the same command might cause unintended behavior.

For this reason, timeouts should be treated as uncertain outcomes, not automatic proof of failure.

A reconciliation mechanism can compare the desired state with the device's reported state before deciding whether another command is necessary.

6. Building a More Reliable IoT Command Architecture

A production-ready command architecture should separate command creation, message delivery, device execution, and state verification.

A simplified architecture looks like this:

Command flow:

FastAPI → PostgreSQL → Command Publisher → MQTT Broker → IoT Device

Acknowledgement flow:

IoT Device → MQTT Broker → Acknowledgement Consumer → PostgreSQL → Dashboard

The database acts as the source of truth for command tracking, while the device's reported state provides evidence of its actual condition.

For larger device fleets, additional considerations become important:

1. Command expiry

Prevent stale commands from being executed long after they were requested.

2. Idempotent execution

Ensure duplicate delivery does not cause repeated unintended operations.

3. Retry policies

Use controlled retries with backoff, and distinguish between retryable failures and permanent failures.

4. Device authentication

Never trust an acknowledgement solely because it contains a valid command ID. Authenticate the publishing device and verify that it is authorized to acknowledge the targeted command.

5. Observability

Track command latency, failure rates, acknowledgement timeouts, retry counts, and device execution outcomes.

6. Desired versus reported state

For configuration management, maintain the configuration the backend wants the device to have separately from the configuration the device reports it currently has.

This allows the backend to identify configuration drift and initiate reconciliation when appropriate.

It is also important to remember that MQTT retained messages, persistent sessions, and offline message queues have different delivery semantics. They should be configured according to the command's purpose. A retained restart command, for example, can be dangerous if a device reconnects much later and receives an outdated instruction.

Conclusion

A successful MQTT publication does not necessarily mean a device has successfully executed a command.

The broker can guarantee message delivery according to the selected QoS level, but application-level execution requires additional engineering.

By introducing unique command identifiers, persistent command tracking, application-level acknowledgements, idempotency, expiry handling, and state reconciliation, developers can build much more reliable IoT communication systems.

The most important lesson is simple:

Message delivery is a communication guarantee. Successful execution is a business guarantee. They are not the same thing.

When building an IoT platform, don't just ask whether the broker delivered the message.

Ask whether the device received it, accepted it, executed it, and reached the expected state.

That is where reliable IoT engineering really begins.

Technologies discussed: MQTT, MQTT QoS, Python, FastAPI, PostgreSQL, SQLAlchemy, Event-Driven Architecture, IoT Device Management, Distributed Systems.

Suggested C# Corner tags: IoT Development, Python, Backend Development, MQTT, Software Architecture, Distributed Systems.