Node-RED Worldmap: rastreando dispositivos GPS via MQTT

O nó worldmap do Node-RED transforma um fluxo de mensagens GPS do MQTT em marcadores em movimento em um mapa interativo em poucos minutos. Neste tutorial você vai simular três veículos, converter as posições JSON deles em marcadores do worldmap com direção e cores, sinalizar dispositivos que param de reportar e desenhar trilhas. Ao final, você terá um rastreador ao vivo funcionando, pronto para ser apontado para hardware GPS real.

Como funciona o nó worldmap do Node-RED

O pacote node-red-contrib-web-worldmap adiciona um nó worldmap que serve um mapa baseado em Leaflet em http://<node-red-host>:1880/worldmap. Cada mensagem enviada ao nó descreve um objeto:

• msg.payload.name é o ID único. Enviar uma nova posição com o mesmo nome move o marcador existente.
• msg.payload.lat e msg.payload.lon são a posição em graus decimais.
• Propriedades opcionais controlam a aparência e o comportamento.

Como qualquer propriedade extra vai parar no popup, você pode passar valores de sensores, nomes de motoristas ou níveis de bateria sem configuração adicional. Os comandos usam o mesmo nó: uma mensagem com msg.payload.command, como { "lat": 41.01, "lon": 28.97, "zoom": 12 }, move e aplica zoom no mapa.

Instale o nó worldmap

No editor, abra Manage palette → Install e procure node-red-contrib-web-worldmap. Ou instale pela linha de comando:

cd ~/.node-red
npm install node-red-contrib-web-worldmap
# depois reinicie o Node-RED

O mapa baixa os tiles de servidores de tiles online, então o navegador que o exibe precisa de acesso à internet. Se você está começando com Node-RED e MQTT, o tutorial Node-RED MQTT cobre primeiro a instalação e a configuração do broker.

Simule dispositivos GPS via MQTT

Cada veículo publica uma posição JSON em seu próprio topic: connectmq/demo/a7f3k2/fleet/<vehicle>/gps. Colocar o ID do veículo no topic, e não apenas no payload, permite que os assinantes escolham um veículo ou usem um wildcard + para todos. Este script move três veículos em voltas ao redor do centro de uma cidade e publica em broker.connectmq.com, o servidor MQTT público gratuito. Substitua a7f3k2 por uma string aleatória sua; as posições no broker público ficam visíveis para qualquer pessoa, então use apenas dados simulados ali.

# pip install "paho-mqtt>=2.0"
import json
import math
import random
import time
import uuid

import paho.mqtt.client as mqtt

PREFIX = "connectmq/demo/a7f3k2/fleet"
CENTER_LAT, CENTER_LON = 41.0082, 28.9784

vehicles = {
    "van1": {"angle": 0.0, "radius": 0.020, "speed": 0.010},
    "van2": {"angle": 2.0, "radius": 0.030, "speed": 0.007},
    "truck1": {"angle": 4.0, "radius": 0.045, "speed": 0.005},
}

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2,
                     client_id=f"gps-sim-{uuid.uuid4().hex[:8]}")
client.connect("broker.connectmq.com", 1883, keepalive=60)
client.loop_start()

try:
    while True:
        for vid, v in vehicles.items():
            v["angle"] += v["speed"] * random.uniform(0.8, 1.2)
            lat = CENTER_LAT + v["radius"] * math.sin(v["angle"])
            lon = CENTER_LON + v["radius"] * 1.3 * math.cos(v["angle"])
            # A direção é tangente ao círculo, em graus no sentido horário a partir do norte
            dlat = math.cos(v["angle"])
            dlon = -1.3 * math.sin(v["angle"])
            heading = (math.degrees(math.atan2(dlon, dlat)) + 360) % 360
            payload = {
                "lat": round(lat, 6),
                "lon": round(lon, 6),
                "heading": round(heading),
                "speed": round(random.uniform(25, 55), 1),
                "ts": int(time.time() * 1000),
            }
            client.publish(f"{PREFIX}/{vid}/gps", json.dumps(payload), qos=0)
        time.sleep(3)
except KeyboardInterrupt:
    pass
finally:
    client.loop_stop()
    client.disconnect()

QoS 0 é uma escolha razoável para posições frequentes: se uma atualização se perder, a próxima chega alguns segundos depois. Use QoS 1 para eventos que você não pode perder, como alarmes de cerca virtual. O guia de rastreamento de veículos com MQTT discute com mais profundidade o projeto de topics e payloads para frotas, e o tutorial de rastreador GPS com ESP32 mostra o lado do dispositivo com hardware real.

Monte o fluxo do worldmap no Node-RED

Passo 1: assinar todos os veículos

Adicione um nó mqtt in com uma configuração de broker apontando para broker.connectmq.com:1883 e um client ID único. Defina o topic como connectmq/demo/a7f3k2/fleet/+/gps e a saída como "a parsed JSON object".

Passo 2: converter payloads MQTT em marcadores

Adicione um nó function entre o nó mqtt in e um nó worldmap:

// Nó function "gps to worldmap marker"
const p = msg.payload;
const lat = Number(p.lat);
const lon = Number(p.lon);

// Rejeita coordenadas ausentes ou impossíveis (e o clássico 0,0 de "sem fix")
if (!Number.isFinite(lat) || !Number.isFinite(lon) ||
    Math.abs(lat) > 90 || Math.abs(lon) > 180 || (lat === 0 && lon === 0)) {
    return null;
}

// connectmq/demo/a7f3k2/fleet/van1/gps -> van1
const id = msg.topic.split("/")[4];
const isTruck = id.startsWith("truck");
const speed = Number(p.speed) || 0;

msg.payload = {
    name: id,
    lat: lat,
    lon: lon,
    bearing: Number(p.heading) || 0,
    icon: isTruck ? "fa-truck" : "car",
    iconColor: speed > 50 ? "orange" : "green",
    layer: isTruck ? "Trucks" : "Vans",
    label: id,
    speed: speed + " km/h",
    lastSeen: new Date(p.ts || Date.now()).toLocaleTimeString(),
    ttl: 120
};
return msg;

Faça o deploy e abra http://localhost:1880/worldmap. Três marcadores aparecem e se movem a cada três segundos. Clique em um para ver a velocidade e o horário da última atualização no popup. Se um veículo parar de publicar, o marcador dele desaparece depois de dois minutos por causa do ttl.

Passo 3: centralizar o mapa na inicialização

Adicione um nó inject configurado para inject once after 1 second com o payload JSON {"command": {"lat": 41.0082, "lon": 28.9784, "zoom": 12}} e ligue-o ao mesmo nó worldmap. Observe que os comandos são aplicados quando chegam; um navegador que se conecta depois começa na visão padrão, a menos que você reenvie o comando na conexão. O nó worldmap in emite um evento de conexão que você pode usar para isso.

Passo 4: desenhar trilhas

O pacote também inclui um nó worldmap tracks. Coloque-o entre o seu nó function e o nó worldmap e defina o número de pontos a manter, por exemplo 50. Ele adiciona uma linha atrás de cada marcador em movimento, o que deixa rotas e voltas evidentes num relance.

Tratando dispositivos inativos e offline

Remover marcadores com ttl é simples, mas muitas vezes é melhor manter o marcador e mostrar que ele está desatualizado. Dois padrões funcionam bem:

1. Cor pela idade. Guarde a última mensagem de cada veículo no contexto de fluxo, rode um inject a cada 30 segundos e reenvie cada veículo com iconColor: "grey" se o timestamp dele for mais antigo que um limite.
2. Use Last Will and Testament. Cada dispositivo define uma mensagem de will retained, como offline, em .../fleet/<vehicle>/status. Se a conexão cair, o broker publica o will, e um segundo nó mqtt in atualiza o marcador. Um status retained significa que um Node-RED recém-iniciado sabe na hora quais veículos estão offline.

Combinar os dois dá aos operadores um quadro claro: marcadores verdes em movimento estão saudáveis, os cinza estão atrasados e os marcados como offline perderam a conexão. Rotear essas mensagens de status é um bom trabalho para o switch node do Node-RED.

Incorporando o mapa no Dashboard 2.0

O worldmap tem a própria página, mas você também pode exibi-lo dentro de um dashboard. No Dashboard 2.0, adicione um widget ui-template cujo template contenha um iframe apontando para /worldmap, dimensionado para o grupo. Assim o mapa fica ao lado de gauges e alertas em uma única tela. O tutorial do Dashboard 2.0 explica grupos e layout.

Checklist de solução de problemas

1. Nenhum marcador. Confirme com um nó debug que as mensagens chegam; verifique se name, lat e lon existem e são números, e não strings.
2. Os marcadores pulam para o Golfo da Guiné. Essa é a posição 0,0, uma saída típica de "sem fix de GPS". A função acima a filtra.
3. Todos os veículos compartilham um único marcador. Todas as mensagens têm o mesmo name. Derive-o do topic ou de um ID de dispositivo.
4. O mapa fica cinza e vazio. O navegador não alcança o servidor de tiles; verifique o acesso à internet ou as configurações de proxy.
5. Os ícones não giram. Só ícones direcionais respeitam bearing; troque para um ícone de veículo como car.
6. As posições ficam atrasadas em relação à realidade. Verifique o intervalo de publicação e o keep-alive dos dispositivos e evite enfileirar posições antigas com QoS 2 em mapas ao vivo.

Levando o rastreamento GPS para produção

Dados de localização são dados pessoais em muitos contextos (no Brasil, sujeitos à LGPD), então nunca devem trafegar por um broker público em produção. Mova os dispositivos e o Node-RED para um broker privado com TLS na porta 8883 e credenciais por dispositivo. Com a ConnectMQ, o portal gera um nome de usuário, uma senha e um client ID por broker, e repetidas falhas de login a partir de um IP levam ao bloqueio dele, o que ajuda contra tentativas de adivinhar credenciais em dispositivos de campo. Dispositivos em conexões celulares, como os de uma frota de logística ou de máquinas agrícolas, se beneficiam de um broker MQTT gerenciado com um endpoint público estável, já que eles só se conectam para fora. Se quiser comparar opções de hospedagem antes, leia o que um broker MQTT faz e como os brokers diferem em autenticação e limites.

Rastreie seus dispositivos na ConnectMQ

Cadastre-se em app.connectmq.com e comece com o plano Serverless gratuito, sem cartão de crédito. Crie um broker, grave as credenciais nos seus rastreadores, aponte o nó de configuração do Node-RED para a porta 8883 com TLS, e o seu worldmap estará no ar com um feed privado e criptografado. O explorador de topics ao vivo da ConnectMQ é uma forma rápida de confirmar que o topic GPS de cada veículo está sendo atualizado.

Perguntas frequentes

Qual URL o worldmap do Node-RED usa?

Por padrão, o mapa é servido em http://<node-red-host>:1880/worldmap. O caminho pode ser alterado nas configurações do nó worldmap.

Como movo um marcador em vez de criar um novo?

Envie uma nova mensagem com o mesmo name. O nó worldmap trata name como o ID do marcador e atualiza a posição e as propriedades dele.

Como removo um veículo do mapa?

Envie uma mensagem com o name do veículo e deleted: true, ou defina ttl para que os marcadores desapareçam automaticamente quando as atualizações pararem.

O worldmap pode mostrar outros dados além da posição GPS?

Sim. Quaisquer propriedades extras no payload, como velocidade, bateria ou temperatura, aparecem no popup do marcador, e a propriedade layer permite agrupar os marcadores por tipo.