Integração MQTT

O SimpIoT utiliza o protocolo MQTT (Message Queuing Telemetry Transport) como padrão para a comunicação entre dispositivos de borda e a plataforma. Este guia detalha o fluxo de integração necessário para que seu hardware opere de forma segura e eficiente.

1. Configurações de Autenticação

Cada dispositivo possui credenciais exclusivas geradas durante o provisionamento no painel administrativo. A autenticação é obrigatória e garante o isolamento lógico do seu projeto.

• Username: Deve ser preenchido com o seu mqttClientId.
• Password: Deve ser preenchido com o seu mqttSecretId.
• Client ID: Recomenda-se o uso do próprio mqttClientId para identificação única da sessão.

2. Primeira Conexão e LWT (Last Will and Testament)

A plataforma exige que o firmware seja o responsável por declarar seu estado de disponibilidade. É obrigatório configurar a mensagem de Last Will and Testament (LWT) no momento da conexão para que o sistema detecte quedas inesperadas de sinal.

• Tópico LWT: {mqttClientId}/telemetry/state
• Payload LWT:

  {
  	"deviceType": "self",
  	"data": {
  		"state": {
  			"status": "OFFLINE"
  		}
  	}
  }
  

  Nota Importante: Caso não envie dtState, o servidor do SimpIoT registrará automaticamente o momento de recebimento da mensagem.

3. Enviando Status de Dispositivo

O dispositivo deve reportar transições de estado para alimentar o histórico operacional e disparar automações.

• Tópico: {mqttClientId}/telemetry/state
• Estados Suportados: ONLINE, OFFLINE, MEASURING, ERROR, MAINTENANCE.

Exemplo de Payload:

{
	"deviceType": "self",
	"data": {
		"state": {
			"status": "ONLINE",
			"battery": 88,
			"signal": -62
		},
		"dtState": "2026-05-13T09:49:00Z"
	}
}

O campo dtState é opcional. Se informado (ISO 8601 UTC), ajuda a manter maior sincronização com o instante real do evento no dispositivo. Se omitido, o backend usa o timestamp de recebimento.

4. Enviando Medidas (Telemetria)

Este é o fluxo principal de dados, onde as leituras dos sensores são enviadas para persistência e visualização em dashboards.

• Tópico: {mqttClientId}/telemetry/measure

Exemplo de Payload:

{
	"deviceType": "self",
	"measurements": [
		{
			"sensor": "temperature",
			"ch": 1,
			"value": 23.4,
			"dtMeasure": "2026-05-13T09:49:00Z"
		}
	]
}

O campo dtMeasure deve seguir o formato ISO 8601 em UTC.

5. Recebendo Comandos e Retornando ACK

O sistema de comandos é bidirecional e exige uma confirmação ativa do dispositivo para garantir que a instrução foi executada com sucesso.

• Tópico para Inscrição (CMD): {mqttClientId}/cmd
• Tópico para Resposta (ACK): {mqttClientId}/cmd/ack

A Importância do ACK

Ao enviar um comando, a plataforma o marca como SENT. O dispositivo precisa retornar um ACK (Acknowledgement). Sem essa resposta, o sistema não confirmará a conclusão e a requisição passará para o status de TIMEOUT após o período configurado.

Exemplo de ACK (Retorno do Dispositivo):

{
	"msgId": "id-recebido-no-header",
	"nodeId": null,
	"status": "COMPLETED",
	"responseMessage": "Relé acionado com sucesso",
	"error": null
}

Utilize COMPLETED para sucesso ou FAILED para erros no hardware.

QoS e Confiabilidade

Para garantir a integridade dos dados sob condições instáveis de rede, utilize as configurações de QoS (Quality of Service) recomendadas:

Bibliotecas Prontas

Para acelerar sua integração, utilize a biblioteca C++ oficial para ESP32/Arduino, que já implementa automaticamente todos os payloads, fluxos de reconexão e tratamento de mensagens acima descritos.