Comandos

Os dispositivos IoTWeaver suportam comandos para controle remoto e gerenciamento através da API REST. A documentação completa da API está disponível no Swagger.

Execução Assíncrona

O envio de comandos não garante resposta imediata e os comandos são executados de forma assíncrona no dispositivo. A resposta da API apenas confirma que o comando foi recebido com sucesso pelo Nexus. Recomenda-se verificar o status do commando após o envio para confirmar a execução ou também é possivel adicionar um callbackUrl e callbackAuth no body para receber notificações de status.

Timeout: Comandos que não recebem resposta em 60 segundos retornam TIMEOUT.

Projeto Exemplo

Existe um projeto de exemplo no Github demonstrando a a integração tanto do webhook quanto do envio de comandos que pode ser acessado aqui.

Comandos Disponíveis

ping

Verifica a conectividade e disponibilidade do dispositivo através de um sinal de ping/pong.

• Método: POST
• Body: Não aceita
• Resposta: SUCCESS ou códigos de erro

restart

Executa a reinicialização remota do dispositivo, útil para aplicar configurações ou resolver problemas sem intervenção física.

• Método: POST
• Body: Não aceita
• Resposta: SUCCESS ou códigos de erro

config

Atualiza as configurações do dispositivo com os parâmetros fornecidos. Único comando que requer um body na requisição.

• Método: POST
• Body: Objeto CommandReq (veja estrutura abaixo)
• Resposta: SUCCESS, FORWARDED ou códigos de erro

Estrutura da Requisição Config

CommandReq

POST: /commands/send/{deviceID}?type={CommandType}

{
  "callbackUrl": "https://example.com/callback", // always optional
  "callbackAuth": "your_generated_token", // required if callbackUrl is provided, ideally with a 60s expiration
  "version": 0,
  "commands": [],
  "restart": false
}

Campos:

• callbackUrl (string, opcional): URL para receber notificações de status do comando
• callbackAuth (string, opcional): Token de autenticação para callbacks gerado pelo seu sistema, necessário se callbackUrl for fornecido, idealmente com um tempo de expiraçao de 60s
• version (uint16): Versão do formato de configuração
• commands (array): Lista de objetos Command com as configurações a aplicar
• restart (boolean): Se true, reinicia o dispositivo após aplicar as configurações

Command

{
  "key": "",
  "section": "",
  "value": 0,
  "id": 0
}

Campos:

• key (string): Nome da configuração a ser alterada
• section (string): Seção da configuração (ex: sensors, devices, transmission)
• value (int64): Novo valor para a configuração
• id (int8): Identificador do elemento dentro da seção
  • 0: Seções sem IDs específicos
  • -1: Aplica a todos os elementos da seção
  • Valor específico: Afeta apenas o elemento com aquele ID (ex: sensor 3)

Códigos de Resposta

Código	Descrição
SUCCESS	Comando executado com sucesso
FORWARDED	Comando encaminhado para outro dispositivo na rede mesh
TIMEOUT	Dispositivo não respondeu dentro de 30 segundos
INVALID_MSG_ID	ID de comando inválido ou fora do intervalo permitido
COMMAND_NOT_AVAILABLE	Comando indisponível neste dispositivo
INVALID_TOPIC	Tópico MQTT inválido para resposta de comando
ID_REQUIRED	ID válido é necessário para executar o comando
COMMAND_NOT_FOUND	Comando não reconhecido pelo dispositivo
LORA_FAILURE	Falha na comunicação LoRa entre Iris e Hecate
FS_ERROR	Erro ao acessar sistema de arquivos
NVS_ERROR	Erro ao acessar memória não volátil (NVS)
CRASH_DETECTED	Dispositivo reiniciou inesperadamente devido a erro crítico
LORA_TIMEOUT	Iris não conseguiu comunicar com o Hecate via LoRa no tempo limite
FBS_ERROR	Erro relacionado ao subsistema FBS
INVALID_CERT_FORMAT	Formato de certificado inválido
SENSOR_NOT_FOUND	Sensor especificado não encontrado
MEASUREMENT_ERROR	Falha ao realizar medição
DEVICE_NOT_FOUND	Dispositivo não encontrado na rede
SET_STATE_FAILED	Falha ao alterar o estado do dispositivo
INVALID_PAYLOAD	Payload do comando malformado ou com dados inválidos
INVALID_LOG_LEVEL	Nível de log especificado é inválido

ErrorResponse

{
  "error": "descrição do erro"
}

Exemplos de Uso

Atualizar intervalo de um sensor específico

POST: /commands/send/{deviceID}?type=config

{
  "version": 1,
  "commands": [
    {
      "key": "interval",
      "section": "sensors",
      "value": 5000,
      "id": 2
    }
  ],
  "restart": false
}

Atualiza o intervalo de leitura do sensor ID 2 para 5000ms sem reiniciar o dispositivo.

Habilitar todos os sensores e reiniciar

POST: /commands/send/{deviceID}?type=config

{
  "version": 1,
  "commands": [
    {
      "key": "enabled",
      "section": "sensors",
      "value": 1,
      "id": -1
    }
  ],
  "restart": true
}

Habilita todos os sensores e executa reinicialização para aplicar as mudanças.

Múltiplas configurações simultâneas

POST: /commands/send/{deviceID}?type=config

{
  "version": 1,
  "commands": [
    {
      "section": "sensors",
      "key": "interval",
      "value": 10000,
      "id": -1
    },
    {
      "section": "transmission",
      "key": "retry_count",
      "value": 5,
      "id": 0
    }
  ],
  "restart": false
}

Altera o intervalo de todos os sensores para 10000ms e ajusta o retry_count para 5 tentativas, sem reiniciar.

Restart Necessário

Quando enviado um comando "config", o dipositivo somente aplicará as configuraçoes após um restart.

Comando ping

POST: /commands/send/{deviceID}?type=ping

{
}

Comando ping com callback

POST: /commands/send/{deviceID}?type=ping

{
  "callbackUrl": "https://example.com/callback",
  "callbackAuth": "your_generated_token"
}