Como conectar seus dispositivos LoRaWAN ao TagoIO usando The Things Network

O The Things Network (TTN) é um dos network servers LoRaWAN mais usados no mundo, rodando sobre o The Things Stack v3. Ele cuida do registro de dispositivos, da comunicação na camada MAC do LoRaWAN e do roteamento de payload. O TTN é excelente na camada de rede, mas não é uma plataforma de aplicação. Ele não armazena seus dados a longo prazo, não cria dashboards e não dispara alertas com base nos valores dos sensores.

O TagoIO é a plataforma de aplicação que completa o stack. Ele armazena dados de séries temporais, alimenta dashboards interativos, dispara alertas, roda scripts de análise serverless e expõe uma API REST completa.

Conectar o TTN ao TagoIO é uma integração limpa e bem suportada. O TagoIO tem um connector nativo para o TTN v3 que cuida do webhook automaticamente.

O que você precisa antes de começar

Uma conta no TagoIO (plano gratuito disponível)
Uma conta no TTN em console.cloud.thethings.network
Pelo menos um end device registrado em uma aplicação no TTN
Um gateway LoRaWAN funcionando com cobertura do TTN

Visão geral da arquitetura

[sensores LoRaWAN] → [gateway LoRaWAN] → [TTN v3 LNS] → (webhook HTTPS) → [TagoIO]

Cada uplink passa pelo network server do TTN, que o autentica e entrega o payload da aplicação ao webhook que você configurou. O TagoIO recebe esse payload, roda seu parser e armazena as variáveis resultantes.

Passo 1: Crie um device no TagoIO usando o connector do TTN

Faça login em admin.tago.io.
Clique em Devices → Add Device.
Procure por The Things Network v3 no catálogo de connectors.
Dê ao device um nome que corresponda ao seu end device no TTN.
Clique em Create Device.

O TagoIO mostra uma Webhook URL e um Authorization Token. Copie os dois.

Documentação de devices: docs.tago.io/docs/tagoio/devices

Passo 2: Configure o webhook do TagoIO no TTN

Na sua aplicação do TTN, vá em Integrations → Webhooks.
Clique em + Add webhook → Custom webhook.
Defina a Base URL com a Webhook URL do TagoIO.
Em Headers, adicione: Authorization: YOUR_TAGOIO_TOKEN
Ative os eventos de Uplink message.
Salve.

Passo 3: Escreva um Payload Parser

O TTN envia um objeto JSON a cada uplink. O TagoIO espera as variáveis no seu formato padrão:

[{"variable": "temperature", "value": 22.5, "unit": "C"}]

Opção A: Use o payload formatter do TTN (decoded_payload)

Se o TTN estiver decodificando seu payload, mapeie os campos decodificados:

const decoded = payload.uplink_message.decoded_payload;
if (!decoded) { payload = []; return; }
payload = Object.entries(decoded).map(([key, value]) => ({
  variable: key, value: value
}));

Opção B: Decodifique os bytes brutos no TagoIO

Para payloads brutos em base64 (exemplo com Cayenne LPP):

const raw = Buffer.from(payload.uplink_message.frm_payload, "base64");
const temperature = raw.readInt16BE(2) / 10;
const humidity = raw.readUInt8(5) / 2;
payload = [
  { variable: "temperature", value: temperature, unit: "C" },
  { variable: "humidity", value: humidity, unit: "%" }
];

Adicionando metadados de RF:

const rxMeta = payload.uplink_message.rx_metadata?.[0] || {};
payload.push({ variable: "rssi", value: rxMeta.rssi });
payload.push({ variable: "snr", value: rxMeta.snr });

Documentação do Payload Parser: docs.tago.io/docs/tagoio/devices/payload-parser

Passo 4: Verifique no Live Inspector

Abra o Live Inspector na página do seu device e confirme que as variáveis decodificadas chegam no próximo uplink.

Documentação do Live Inspector: docs.tago.io/docs/tagoio/devices/live-inspector

Passo 5: Escale para uma frota

Para frotas grandes, crie um device no TagoIO para cada end device do TTN, ou use uma única integração catch-all no TagoIO com um script de Analysis que roteia os dados recebidos pelo dev_eui.

Para dashboards com vários dispositivos, os Blueprint Dashboards aplicam um único layout a todos os devices automaticamente, por meio de tags.

Documentação de Analysis: docs.tago.io/docs/tagoio/analysis

Enviando downlinks do TagoIO para o TTN

Use um script de Analysis no TagoIO para fazer POST de downlinks pela API do TTN v3:

const axios = require("axios");
await axios.post(
  `https://eu1.cloud.thethings.network/api/v3/as/applications/${APP_ID}/devices/${DEVICE_ID}/down/push`,
  { downlinks: [{ f_port: 1, frm_payload: Buffer.from([0x01]).toString("base64"), priority: "NORMAL" }] },
  { headers: { Authorization: `Bearer ${TTN_API_KEY}` } }
);

Isso permite enviar comandos aos dispositivos: alterar o intervalo de envio, acionar um relé, solicitar leituras sob demanda.

Indo além com IA

O servidor MCP do TagoIO conecta assistentes de IA como o Claude aos dados dos seus dispositivos. Pergunte: “Quais dispositivos não enviaram dados nas últimas 6 horas?” ou “Qual a temperatura média de todos os nós no Prédio B?”

Documentação do MCP: docs.tago.io/docs/tagoio/getting-started/tagoio-mcp-ai-powered-iot-data-integration

Resumo

A integração TTN-TagoIO usa o connector nativo do TagoIO para o TTN v3. Registre o device no TagoIO, adicione o webhook no TTN, escreva um payload parser, e seus dados LoRaWAN passam a fluir para o armazenamento de longo prazo, com todos os recursos de dashboard e alertas.