MQTT

Visão Geral

A Valeiot fornece um MQTT Broker nativo para permitir comunicação em tempo real entre dispositivos e a plataforma.
Utilizando o protocolo MQTT, os dispositivos podem publicar dados de telemetria e receber comandos de forma leve, escalável e confiável.

O MQTT segue o modelo publish/subscribe (pub/sub), onde:

• Um Client (dispositivo) conecta-se a um Broker
• Um client publica mensagens em um Topic
• Outros clients se inscrevem (subscribe) em topics para receber mensagens
• As mensagens podem utilizar diferentes níveis de QoS (Quality of Service)
• As mensagens podem ser marcadas como Retained
• As conexões podem ser protegidas utilizando TLS

 

Enviando dados para a Valeiot

Passo 1: Configurando Valeiot MQTT Broker

Utilize os seguintes parâmetros de conexão:

Host: mqtt.valeiot.com
Port: 1883
TLS Port: 8883

• Port 1883 → MQTT padrão (não criptografado)
• Port 8883 → MQTT sobre TLS (recomendado para produção)

atenção

Para ambientes de produção, utilize sempre TLS (8883) para garantir comunicação criptografada.

 

Passo 2: Autenticação

Os dispositivos podem publicar dados na Valeiot utilizando dois métodos de autenticação.
Escolha autenticar utilizando a opção A ou B, conforme descrito abaixo:

A. Network Token (nível de network)

Utilize este método ao autenticar com o Data Source Network ID (DNID).

Credentials

Username: DNID (Data Source Network ID)
Password: network:YOUR_NETWORK_TOKEN_HERE

• DNID → Identificador único do Data Source dentro da network (ex.: 123)
• network_token → Token de autenticação da network
  (ex.: us1:FaBs8LCPBRPT7ty9f2TRVdACte78wMJKm0pYyi00lDobXVpb9vGOGAFjgJ2in1)

B. Data Source Token (nível de dispositivo)

Utilize este método ao autenticar diretamente usando um Data Source token.

Credentials

Username: client
Password: datasource:server_name:datasource_token

• server_name → Servidor da Valeiot (ex.: us1)
• datasource_token → Token de autenticação do Data Source
  (ex.: datasource:us1:FaBs8LCPBRPT7ty9f2TRVdACte78wMJKm0pYyi00lDobXVpb9vGOGAFjgJ2in2)

 

Exemplo: Inserindo dado com sucesso como um client

Para fins de ilustração, é utilizado o MQTT Explorer como client para simular um dispositivo:

Após a configuração correta, você deverá ver o client conectado com sucesso ao Valeiot Broker:

Preencha o topic, neste exemplo temperature, e o valor 30.

A Valeiot irá registrar um Data Point da seguinte forma:

{
  "variable": "temperature",
  "value": "30"
}

Observe que, caso deseje customizar a forma como os dados são inseridos (por exemplo, alterar o nome da variável ou decodificar bits), é necessário utilizar um Payload Parser.

Consulte a seção Payload Parser para saber mais.

Por fim, verifique o Data Point inserido na Valeiot:

atenção

Ainda não funcionou? Verifique o Live Inspector (em Device > Live Inspector) para identificar possíveis erros:

 

Enviando comando para dispositivos

Os comandos podem ser disparados a partir de:

• Dashboard e widgets
• Scripts
• SDK
• Chamadas diretas de API

atenção

Clients MQTT não podem publicar diretamente para outros clients.
A comunicação ocorre exclusivamente por meio do Valeiot broker.

Caso seja necessário comunicação direta entre clients, entre em contato com o suporte da Valeiot. Disponibilizamos brokers dedicados para casos avançados.

 

Exemplo: Enviando comando utilizando o Valeiot SDK

No MQTT, todas as mensagens são trocadas por meio de topics.

O hardware deve estar inscrito (subscribed) no topic correto para receber mensagens.
No exemplo abaixo, o hardware está inscrito no topic:

{HARDWARE_ID}/SETOUT

• {HARDWARE_ID} → Identificador único do hardware (IMEI, Device ID, EUI, etc.), que normalmente é definido como o DNID (Data Source Network ID)
• SETOUT → Topic de comando (device inscrito neste topic)

Para enviar um comando programaticamente utilizando o SDK da Valeiot:

const result = await conn.mqtt.publish({
  body: {
    networkId: networkId,
    topic: `${dnid}/SETOUT`,
    payload: JSON.stringify(message),
    qos: 0,
    retain: true,
  },
});

Parameters

• networkId → Network ID do seu Data Source
• topic → MQTT topic no qual o dispositivo está inscrito
• payload → Mensagem enviada ao dispositivo (string JSON)
• qos → Nível de QoS do MQTT (0, 1 ou 2)
• retain → Se true, o broker mantém a última mensagem para novos subscribers

 

Exemplo Script completo (Comando com Dashboard Button)

O script abaixo é acionado por um button widget no dashboard.
O botão ON dispara o evento command/on e o botão OFF dispara command/off.

import {
  EventContext,
  Router,
  ScriptEvent,
  WorkspaceConn,
} from "@sibis/valeiot-sdk";

/**
 * handler
 * Creates connection and router, handles the event
 */
export async function handler(ev: ScriptEvent) {
  const conn = new WorkspaceConn();
  const router = buildRouter(conn);

  try {
    return await router.handle(ev);
  } catch (err) {
    console.error("error");
    return err;
  }
}

/**
 * buildRouter
 * Builds router with sendCommand event handler
 */
function buildRouter(conn: WorkspaceConn): Router {
  const router = new Router();
  router.use(async (ctx, _) => ctx.set("conn", conn));

  router.use(async (ctx, _) => {
    try {
      await ctx.next();
    } catch (err) {
      console.error("error", err);
    }
  });

  router.on("command/on", sendCommandHandler);
  router.on("command/off", sendCommandHandler);

  return router;
}

/**
 * sendCommandHandler
 * Triggered by button widget
 */
export async function sendCommandHandler(ctx: EventContext, ev: ScriptEvent) {
  console.log("EVENT:", JSON.stringify(ev, null, 4));
  console.log("Running Valeiot sendCommandHandler");

  const conn: WorkspaceConn = ctx.get("conn");

  const event = ev.event;
  const datasourceId = ev.content?.datasourceId || ev.content?.dss;

  // Getting networkId
  const ds = await conn.datasources.getDetails({
    datasourceId: Number(datasourceId),
  });

  const networkId = ds.network.id;
  const dnid = ds.dnid;

  let message: number;

  if (event === "command/on") {
    console.log("Event: command/on");
    message = 1;
  } else if (event === "command/off") {
    console.log("Event: command/off");
    message = 0;
  } else {
    ctx.result.setFailed();
    ctx.result.set("Error", "Unrecognized event");
    return;
  }

  try {
    const result = await conn.mqtt.publish({
      body: {
        networkId: networkId,
        topic: `${dnid}/SETOUT`,
        payload: JSON.stringify(message),
        qos: 0,
        retain: true,
      },
    });
    console.log("MQTT Publish Result:", result);
  } catch (err) {
    console.error("Error sending command via MQTT:", err);
    ctx.result.setFailed();
    ctx.result.set("Error", "Failed to send command via MQTT");
    return;
  }

  ctx.result.set(
    "Success",
    `Command ${event === "command/on" ? "ON" : "OFF"} sent successfully!`,
  );
}