Device Command Implementation: A Comprehensive Guide

In this article, we will explore the implementation of a device command infrastructure, focusing on bidirectional communication between an ESP32 device and the cloud. This system enables users to remotely manage and monitor their devices, providing functionalities such as restarting, updating firmware, configuring settings, and retrieving status information. Let's dive into the details of each stage, from defining the data structure to implementing API endpoints and ensuring robust testing.

🎯 Objective

The primary goal is to implement a bidirectional command infrastructure that allows seamless communication between ESP32 devices and the cloud. This will empower users to remotely manage and monitor their devices effectively.

📋 Checklist

Day 1-2: DeviceCommand Entity

The initial phase involves defining the structure and data handling for device commands. This includes creating the DeviceCommand entity and setting up the necessary repositories.

• Creating the DeviceCommand Entity: The foundation of our system lies in the DeviceCommand entity. This entity captures all the essential information related to a command. Here’s a breakdown of its key attributes:

  • Id: A unique identifier for each command, ensuring that every command can be tracked and managed individually.
  • DeviceId: This links the command to a specific ESP32 device, allowing the system to route commands to the correct destination.
  • CommandType: An enumeration that defines the type of command being executed, such as restarting the device, updating the firmware, or setting a configuration.
  • Payload: This field carries the data required for the command execution. For example, it might contain the URL of the new firmware or the specific configuration settings to be applied.
  • Status: An enumeration that indicates the current state of the command, such as pending, sent, executing, completed, failed, or timed out. This attribute is crucial for tracking the progress and outcome of each command.
  • RequestedBy: The identifier of the user or system that initiated the command, providing accountability and auditability.
  • RequestedAt: A timestamp indicating when the command was requested, allowing for chronological tracking and analysis.
  • ExecutedAt: A timestamp indicating when the command was executed on the device, useful for performance monitoring and troubleshooting.

• Creating Enums: To manage the types and statuses of commands, we define two enumerations:

  • CommandType: This enum includes values such as Restart, UpdateFirmware, SetConfig, and GetStatus. These represent the different types of commands that can be sent to the device.
  • CommandStatus: This enum includes values such as Pending, Sent, Executing, Completed, Failed, and Timeout. These represent the various stages in the lifecycle of a command.

• Creating IDeviceCommandRepository: The IDeviceCommandRepository interface defines the methods for interacting with the data storage layer. This interface includes the following methods:

  • GetByIdAsync(): Retrieves a DeviceCommand entity by its unique identifier.
  • GetPendingByDeviceIdAsync(): Retrieves all pending commands for a specific device.
  • AddAsync(): Adds a new DeviceCommand entity to the data store.
  • UpdateStatusAsync(): Updates the status of a DeviceCommand entity.

The implementation of these components ensures a robust and manageable system for handling device commands.

Day 3: Command Queue

Implementing a command queue is crucial for managing the flow of commands to each device, ensuring that they are processed in an orderly manner. This involves setting up a FIFO queue with specific constraints and integrating it with the MQTT communication protocol.

• Implementing DeviceCommandQueue (FIFO): The DeviceCommandQueue is designed as a First-In-First-Out (FIFO) queue to ensure that commands are processed in the order they are received. This queue has the following characteristics:

  • Max 10 comandos pendentes por device: A maximum of 10 pending commands per device to prevent overwhelming the device and ensure timely processing. This limit helps maintain system stability and responsiveness.
  • Timeout 30s por comando: A timeout of 30 seconds per command, after which the command is considered failed if no response is received. This prevents commands from being stuck indefinitely and allows for timely error handling.
  • Retry manual (usuário decide): Manual retry option, allowing users to decide whether to retry a failed command. This provides flexibility and control over the command execution process.

• Publicar comando via MQTT: The system publishes commands via MQTT to the topic blueties/devices/{deviceId}/commands. This allows the ESP32 devices to subscribe to their respective command topics and receive commands in real-time.

• Creating Job de Timeout (Background): A background job is created to monitor the status of sent commands and handle timeouts. This job runs every 5 seconds and performs the following tasks:

  • A cada 5s, verifica comandos Sent há >30s: Checks for commands that have been in the Sent status for more than 30 seconds.
  • Marca como Timeout: Marks these commands as Timeout, indicating that they have failed to execute within the expected timeframe.

The command queue ensures that commands are processed efficiently and reliably, with mechanisms in place to handle potential issues such as timeouts and queue overflow.

Day 4: API Endpoints

Creating API endpoints is essential for providing a user-friendly interface to interact with the device command system. These endpoints allow users to send commands, list commands, and check the status of specific commands.

• POST /devices/{id}/commands - Enviar comando: This endpoint allows users to send a command to a specific device. The request body contains the command details, such as the command type and payload. The system validates the request and adds the command to the device's command queue.
• GET /devices/{id}/commands - Listar comandos (últimos 100): This endpoint allows users to list the last 100 commands for a specific device. This provides a historical view of the commands executed on the device, useful for monitoring and troubleshooting.
• GET /commands/{commandId}/status - Status de comando específico: This endpoint allows users to check the status of a specific command by its ID. This provides real-time information on the progress and outcome of the command.
• Validar permissão: Owner/Admin/Member podem enviar comandos: The system validates the user's permissions before allowing them to send a command. Only users with the Owner, Admin, or Member role are authorized to send commands to the device.

The API endpoints provide a comprehensive interface for managing device commands, ensuring that users can easily interact with the system and monitor their devices.

Day 5: E2E Tests

End-to-end (E2E) testing is crucial to ensure that the entire device command system works seamlessly, from sending a command to receiving a response. These tests simulate real-world scenarios to validate the functionality and reliability of the system.

• Testar: enviar comando → ESP32 recebe via MQTT: This test verifies that a command sent from the API is successfully received by the ESP32 device via MQTT. This ensures that the communication channel between the cloud and the device is functioning correctly.
• Testar: ESP32 responde → status atualiza para Completed: This test verifies that when the ESP32 device responds to a command, the status of the command is updated to Completed in the system. This ensures that the system accurately reflects the outcome of the command execution.
• Testar: timeout 30s → status Timeout: This test verifies that if a command times out after 30 seconds, the status of the command is updated to Timeout in the system. This ensures that the timeout mechanism is functioning correctly and that failed commands are properly identified.
• Testar: fila cheia (10 comandos) → retorna 429: This test verifies that if the command queue is full (10 commands), the system returns a 429 status code, indicating that the request cannot be processed. This ensures that the system is handling queue overflow correctly and preventing commands from being lost.

These E2E tests cover the critical aspects of the device command system, ensuring that it is robust, reliable, and functioning as expected.

✅ Success Criteria

The successful implementation of the device command infrastructure is measured by the following criteria:

• Comando enviado via MQTT para ESP32: Ensuring that commands are successfully transmitted to the ESP32 device via MQTT.
• Timeout funciona (30s): Verifying that the timeout mechanism is functioning correctly, with commands timing out after 30 seconds if no response is received.
• Fila respeita limite (10 comandos/device): Ensuring that the command queue respects the limit of 10 commands per device.
• Histórico persistido (últimos 100 comandos): Verifying that the system persists the history of the last 100 commands for each device.
• Owner/Admin/Member podem enviar comandos: Ensuring that only users with the Owner, Admin, or Member role are authorized to send commands to the device.

📚 References

• ANALISE-ARQUITETURAL-CORRECOES.md - Q11-Q13
• ANALISE-ARQUITETURAL-PARTE-3.md - P1.4

🔧 MQTT Command Format

// Publicado em: blueties/devices/e7:61:75:f7:c2:9f/commands
{
  "commandId": "cmd-123",
  "type": "restart",
  "payload": {},
  "requestedBy": "user-456",
  "timestamp": "2025-11-17T10:30:00Z"
}

// ESP32 responde em: blueties/devices/e7:61:75:f7:c2:9f/commands/responses
{
  "commandId": "cmd-123",
  "status": "completed",
  "result": "Device restarted successfully",
  "executedAt": "2025-11-17T10:30:05Z"
}

⏱️ Estimation

5 days

🏷️ Labels

priority: P1, type: feature, service: device-mgmt, tech: event-driven

🗓️ Milestone

Sprint 3 - Commands + Friendly Names + Observability

Conclusion

Implementing a robust device command infrastructure involves careful planning and execution across several key areas. From defining the DeviceCommand entity and setting up the command queue to creating API endpoints and ensuring thorough end-to-end testing, each step plays a crucial role in the overall success of the system. By adhering to the success criteria and leveraging the provided references, developers can create a reliable and efficient system for remotely managing and monitoring ESP32 devices.

For further information on MQTT and its applications, visit the MQTT official website.