Conectar seu nó

Wi-Fi direto (MQTT): o que é

O firmware Meshtastic tem um cliente MQTT: ligado no Wi-Fi da casa, o nó entrega os próprios pacotes a um servidor MQTT (o “broker”) pela internet, sozinho. O Clima Aberto recebe esses pacotes do broker, abre só a telemetria do seu nó e grava as medidas. Nenhum computador precisa ficar ligado: o app do celular (ou o PC) só é usado uma vez, para configurar.

• Por que não precisa de PC: o nó já sabe falar MQTT; o Clima Aberto é avisado pelo broker a cada pacote. A leitura chega no intervalo da telemetria do nó: 30 min configurando pelo app (é o menor que ele oferece). 10 min só pelo computador e só num nó sem nenhum canal público: com o canal público de chave padrão em qualquer índice (primário ou secundário), o firmware força 30 min a cada boot, para proteger o tempo de ar da malha.
• Queda de internet: o nó guarda até 16 pacotes na memória e despeja ao reconectar; o servidor aceita leituras de até 3 horas atrás. Se o nó reiniciar nesse meio-tempo, a fila se perde (a série aceita buracos).
• Bluetooth: no ESP32 (Heltec), Wi-Fi ligado desliga o Bluetooth. Com o Wi-Fi do nó ligado, conecte o app pela rede (no app, a conexão por IP/TCP), ou configure pelo PC (meshtastic --host IP).
• Energia: Wi-Fi ligado gasta mais. Numa estação solar, confira o orçamento do painel e da bateria.

Passo a passo pelo app do celular (recomendado)

Foi assim que a estação de referência (um Heltec V2) foi configurada: pelo app Meshtastic do iPhone, conectado ao nó pelo Wi-Fi. O site mostra a mesma sequência abaixo, já com os seus valores e um botão copiar em cada um. Os nomes estão como o app mostra em português; entre parênteses, o nome em inglês (para quem usa o app em inglês). Alguns campos o app não traduz: “MQTT Enabled”, “Map Reporting”, “Environment Metrics Interval”, “WiFi Enabled” e “Address Mode” aparecem em inglês mesmo.

1. Conecte o app ao nó da estação O app precisa estar conectado ao nó que vai ficar no Wi-Fi (não ao nó que anda com você). Nó já no Wi-Fi? Conecte pela rede, pelo IP. Ainda não? Pelo Bluetooth — e deixe a tela Redes por último, porque ao ligar o WiFi o Bluetooth do ESP32 desliga. O ID do nó está em Nodos (Nodes) → o próprio nó → ID do Usuário (User Id), no formato !xxxxxxxx.
2. Cadastre (ou troque a forma de conexão) Estação nova: ＋ Estação → Wi-Fi direto (MQTT) → ID do nó. Estação que já existe: Editar minha estação → cole a chave da estação → Conferir → Configuração avançada → Forma de conexão → Wi-Fi direto. O botão “Configuração avançada” só libera depois que a chave confere.
3. Passo 1 da tela: guarde antes de tudo Baixar .txt (no iPhone vai para o app Arquivos) ou copiar tudo (cole nas Notas com bloqueio ou num gerenciador de senhas) e marque “Guardei”. Faça isso antes de ir ao app Meshtastic: ao trocar de app, o iPhone pode recarregar a página, e a senha e a PSK não aparecem de novo. O arquivo leva também a chave da estação. Se a cópia falhar, o site não deixa marcar “Guardei”: use o .txt.
4. Passo 2: o canal principal de HOJE No app, em Canais, olhe o cadeado do canal da 1ª linha antes de mexer: amarelo aberto = público padrão, verde fechado = privado (veja cadeados). Um canal sem nome aparece como Canal Principal (Primary Channel): aí o nome é vazio. Escolha também a Região e a Configurações (Presets) que estão na tela LoRa (ex.: “Australia / New Zealand” e “Short Range - Fast”). O site calcula a Faixa de Frequência. Para conferir: no topo da tela Canais o app mostra “… MHz · Slot N”; com a Faixa ainda em 0, esse N tem de ser o mesmo número. Mudou uma resposta depois do passo 1? O site pede para baixar o .txt de novo.
5. Tela LoRa Confira Região e Configurações (não mude). Em Avançado, ponha a Faixa de Frequência (Frequency Slot) calculada. Se ela já mostra um número diferente de 0, já está fixa: não mude.
6. Tela Canais Canal privado hoje: antes, toque em Adicionar Canal (Add Channel) e crie um canal com o mesmo Nome e a mesma chave dele (MQTT Uplink ativado e MQTT Baixa ativada desligados). Canal público hoje e quer continuar na malha da comunidade: crie o canal público como secundário — Nome do preset (ex.: ShortFast), Tamanho da Chave Padrão (Default), MQTT Uplink e Baixa desligados. Com ele, o firmware força a telemetria a no mínimo 30 min. Depois, no canal da 1ª linha: Nome ClimaAb, Tamanho da Chave (Key Size) 256 bits, campo chave (Key) = a PSK (cadeado verde), MQTT Uplink ativado ligado, MQTT Baixa ativada (Downlink) desligado, Posições Ativas (Positions Enabled) desligado. Atenção: o campo do app se chama “chave”, mas nele vai a PSK do ClimaAb, não a chave da estação do site.
7. Tela MQTT MQTT Enabled ligado; Endereço (Address), Nome de usuário (Username) e Senha (Password) da configuração; A criptografia está ativada (Encryption Enabled) ligado; JSON desligado, se aparecer; TLS ativado (TLS Enabled) ligado; Tópico Raiz (Root Topic) ca; Proxy de Cliente MQTT (MQTT Client Proxy) e Map Reporting desligados. ESP32 clássico (não S3) sem PSRAM, ex.: Heltec V2: veja o modo sem TLS (Endereço do broker público, TLS desligado, Nome de usuário e Senha vazios).
8. Tela Telemetria Medidas Ambientais Ativas (Environment Metrics Enabled) ligado e Environment Metrics Interval Trinta minutos (o menor que o app oferece). Com o canal público como secundário, o firmware força 30 min a cada boot mesmo que se ponha menos; uma malha cheia (mais de 40 nós ouvidos) ou congestionada espaça ainda mais. 10 min só pelo computador e só num nó sem nenhum canal público.
9. Tela Redes (por último) Opções de WiFi: WiFi Enabled ligado, SSID = o nome da rede de 2,4 GHz de casa, Senha = a do Wi-Fi (não é a do MQTT); Address Mode DHCP. Ao salvar, o Bluetooth do nó desliga: reconecte o app pela rede (conexão por IP; o IP do nó aparece na lista de aparelhos do roteador).
10. Aguarde a ativação Cada “Salvar” reinicia o nó (~30 s). O estado aparece no detalhe da sua estação: aguardando ativação até o administrador liberar, depois ativa e a Última leitura via MQTT. Quer rever uma tela depois? Configuração avançada → Checklist do app (sem a PSK e a senha, que ficam no seu .txt).

Cadeados e Faixa de Frequência

• A frequência sai do nome do canal principal. Com a Faixa de Frequência em 0, o firmware calcula o slot pelo nome do canal da 1ª linha; no canal público sem nome, pelo nome do preset (ex.: ShortFast). Trocar o principal para ClimaAb mudaria a frequência e o nó deixaria de ouvir os outros: por isso o site fixa a Faixa de Frequência no valor de hoje.
• “Canal Principal” não é nome. É como o app mostra o canal principal sem nome (em inglês, “Primary Channel”). Se é isso que aparece, deixe o nome vazio no site: digitar “Canal Principal” daria outra frequência.
• Confira com o próprio app. No topo da tela Canais o app mostra a região e “… MHz · Slot N”. Antes de mexer em qualquer coisa (com a Faixa de Frequência ainda em 0), esse N tem de ser igual à Faixa que o site calculou; se não for, a região, a configuração (preset) ou o cadeado escolhidos não são os do nó.
• O cálculo parte do canal REAL. Caso real: o V2 estava no canal público padrão (amarelo), em ANZ · ShortFast → Faixa 16 (918,875 MHz). Calculando com o nome de um canal privado que ele não usava (“VeraCruz”), dava 28 — errado.
• Ponha a mesma Faixa nos outros nós que conversam com a estação (ex.: o que anda com você), em LoRa → Avançado → Faixa de Frequência.

Qual segredo vai onde

Chave da estação

Aparece no cadastro. Serve só no site (Editar, Configuração avançada) e na ponte. Não vai no nó. Fica guardada no navegador onde você cadastrou ou colou.

PSK do ClimaAb

No app: Canais → ClimaAb → campo chave (Key), Tamanho da Chave 256 bits. É ela que cifra as medidas e prova que o pacote é do seu nó. O campo do app se chama “chave”, mas ele recebe a PSK — não a chave da estação.

Senha do MQTT

No app: MQTT → Senha (Password), com o usuário em Nome de usuário (Username). No modo sem TLS os dois ficam vazios.

Token admin

É do administrador do Clima Aberto, para o painel dele. Você nunca precisa dele.

Problemas comuns

Casos reais da configuração da estação de referência pelo app do iPhone.

“No Editar não tem como trocar a conexão”

Fica em Editar minha estação → cole a chave → Conferir → Configuração avançada → Forma de conexão. O botão fica cinza até a chave conferir. No detalhe da estação também há o botão Configuração avançada. A forma de hoje vem marcada como atual; “Trocar” só libera quando você escolhe outra, e sair do Wi-Fi direto pede confirmação (apaga a PSK e a senha; voltar exige credenciais novas e nova ativação).

O site não mostra “Conectar o nó” / pede a chave de novo

A chave não está neste navegador: aba privada, outro aparelho ou dados do site apagados. Abra numa aba normal e cole a chave em Editar minha estação.

Fechei a tela sem guardar a senha/PSK — ou mandei print delas

Configuração avançada → Credenciais → Gerar novas credenciais: as antigas param de valer na hora. Aplique as novas no checklist (“O nó já está no ClimaAb”: só a chave do ClimaAb e a Senha) e aguarde a reativação. Só queria rever a Faixa ou uma tela? Não precisa gerar nada: Configuração avançada → Checklist do app.

A cópia não funcionou no iPhone

Se “Copiar tudo” não conseguir copiar, o site avisa e não deixa marcar “Guardei”: use Baixar .txt (vai para o app Arquivos). Para um campo só, toque no “copiar” dele; se o campo de senha do app não aceitar colar, digite olhando os blocos de 4.

Cadeados trocados

O ClimaAb amarelo = a PSK não entrou: Tamanho da Chave 256 bits e cole a PSK no campo “chave”. O canal público verde = ganhou chave própria e saiu da malha da comunidade: Tamanho da Chave Padrão (Default).

Faixa de Frequência calculada com o canal errado

O cálculo parte do canal principal de hoje (o da 1ª linha), antes de mexer. Amarelo = público (nome do preset); verde = privado (o nome dele). O app mostra “Canal Principal”? O nome é vazio. Confira com o “Slot N” do topo da tela Canais. Veja cadeados.

O canal principal de hoje já é o ClimaAb

Então o nó já passou pela primeira configuração: marque “O nó já está no ClimaAb”. O checklist mostra só a chave do ClimaAb e a Senha; não crie outro canal ClimaAb nem mude a Faixa de Frequência.

Tópico Raiz (Root Topic) msh/ANZ (ou msh/…)

É o padrão de fábrica. Tem de ser ca: a regra do servidor MQTT só aceita ca/2/e/ClimaAb/<id do nó>; com msh/… nada chega.

Senha vazia, ou colada com espaço

No servidor com TLS a senha tem de ser exatamente a da configuração (24 letras e números, maiúsculas contam, sem espaço no começo ou no fim). Se o campo do iPhone não aceitar colar, digite olhando os blocos de 4. No modo sem TLS é o contrário: Nome de usuário (Username) e Senha (Password) vazios (apague tudo).

Heltec V2 não conecta com TLS

O ESP32 clássico (não S3) sem PSRAM, como o Heltec V2, não tem memória para completar o TLS com Wi-Fi e Meshtastic rodando: não aparece nem tentativa no servidor. Use o modo sem TLS (quando o servidor oferece), a ponte, ou uma placa ESP32-S3 (ex.: Heltec V3). O V3 também não tem PSRAM, mas no firmware 2.8 ele deve completar o TLS (ainda não comprovado): confirme no log serial do nó (veja “Nada chega e nenhum descarte aparece” no Diagnóstico do Wi-Fi direto).

O app diz “broker rejected connection: Authorization Error”

Essa mensagem vem do proxy do app (Proxy de Cliente MQTT, MQTT Client Proxy), não do nó: o app iOS usa um identificador longo demais para o servidor. O proxy do app não serve para testar: deixe-o desligado e acompanhe pelo detalhe da estação (Última leitura via MQTT).

“Failed to deliver to mesh” ao mandar mensagem no canal ClimaAb

Normal. Só a sua estação tem a chave do ClimaAb: ninguém na malha repete a mensagem, então o app mostra a falha. O ClimaAb é só para a telemetria; converse no canal secundário.

O app conecta pela rede, mas nada chega ao servidor

Confira a tela Redes: Address Mode DHCP. Com Static e o gateway errado o nó fala com o celular na rede de casa, mas não sai para a internet.

Liguei o WiFi e o app perdeu o nó

Normal no ESP32 (Heltec): com o WiFi ligado, o Bluetooth desliga. Reconecte o app pela rede, por IP (o IP do nó aparece na lista de aparelhos do roteador). Por isso a tela Redes é a última do checklist.

O app não oferece 10 minutos na telemetria

O app oferece de 30 min para cima. 10 min só pelo computador (--set telemetry.environment_update_interval 600) e só num nó sem nenhum canal público. Com o canal público de chave padrão em qualquer índice (ex.: o secundário, para continuar na malha da comunidade), o firmware sobe o 600 para 1800 a cada boot: --get telemetry mostra 1800. Na Configuração avançada → Diagnóstico, diga qual intervalo está no nó (com o canal público: 30 min): o aviso de “sem leitura” se ajusta.

O nó conecta ao servidor MQTT e cai em seguida, sem parar

Uma causa possível: o firmware tenta publicar as mensagens diretas cifradas (PKI) no tópico ca/2/e/PKI/!xxxxxxxx, e o servidor MQTT só deixa o nó publicar no tópico dele do ClimaAb, então nega. Se o servidor derrubar a conexão a cada negação, o nó fica reconectando (sinais: leituras faltando ou o aviso “Sem leitura via MQTT”; no log serial do nó, “MQTT connected” repetindo). Ainda não se sabe se o servidor do Clima Aberto faz isso: as negações em si são normais. Isso não se resolve no nó: avise o administrador do Clima Aberto. A saída dele é liberar esse tópico só para o próprio nó. O preço: os dados de quem mandou para quem, e quando, dessas mensagens passam a entrar no servidor MQTT (o conteúdo continua cifrado e nunca chega ao Clima Aberto).

ID do nó errado (o do celular)

Com o app conectado ao nó que anda com você, o ID do Usuário (User Id) é o dele. O ID certo é o do nó da estação, no Wi-Fi. Corrija em Configuração avançada → Forma de conexão → Wi-Fi direto → digite o ID certo → Trocar o nó. Trocou a placa da estação (ex.: um nó novo, ainda sem Wi-Fi)? Aí o ID certo é o da placa nova, mesmo que ela esteja ligada ao celular pelo Bluetooth agora: leia o ID depois de gravar o firmware final (no firmware 2.8, apagar tudo ou o reset de fábrica do aparelho troca o ID).

Configuração avançada (no site)

Aberta pelo Editar minha estação (depois de conferir a chave) ou pelo bloco Conectar o nó do detalhe da sua estação. Tem estas partes:

• Forma de conexão: Wi-Fi direto (MQTT), cabo USB ou Bluetooth (ponte). A de hoje vem marcada como atual. Trocar para o Wi-Fi direto mostra a configuração do nó uma vez, com o checklist do app. Sair do Wi-Fi direto (ou trocar o nó dele) pede confirmação.
• Checklist do app (só no Wi-Fi direto): a Faixa de Frequência e o que pôr em cada tela do app, sem a PSK e a senha (essas ficam no seu .txt). Para rever sem gerar credenciais novas.
• Credenciais: gerar PSK e senha novas (perdeu ou vazou).
• Pelo computador (CLI): comandos sem segredo; os completos aparecem junto com credenciais novas.
• Diagnóstico: estado, última leitura, os últimos descartes do servidor e o intervalo da telemetria do nó.

Alternativa: pelo computador (CLI)

Os mesmos ajustes do app, por comandos. Na tela da configuração do nó, eles ficam em Configuração avançada · Pelo computador (CLI).

1. Ache o ID do nó que vai ficar no Wi-Fi É ! + 8 letras/números (ex.: !a1b2c3d4) do nó da estação (o que fica no Wi-Fi de casa) — não o do nó que anda com você ligado ao celular. Com Wi-Fi ligado, o Bluetooth do ESP32 desliga, então o app do celular quase sempre está conectado ao OUTRO nó. No PC, com a estação no Wi-Fi:

   meshtastic --host 192.168.x.y --info

   Nó novo, ainda sem Wi-Fi: no cabo USB, meshtastic --port COM5 --info (no Linux, /dev/ttyUSB0). Em “Nodes in mesh”, o bloco com o nome da estação (o mesmo do “Owner”) tem "id": "!xxxxxxxx". Vai gravar firmware? Leia o ID depois: no firmware 2.8, apagar tudo (full erase) ou o reset de fábrica do aparelho troca o ID. Não mande essa saída a ninguém: ela tem as senhas dos canais e do Wi-Fi.
2. Cadastre ou troque a forma de conexão Estação nova: ＋ Estação → em “Como o nó vai mandar os dados?”, Wi-Fi direto (MQTT) → ID do nó. Estação que já existe (usava a ponte): Editar minha estação → chave → Configuração avançada → Forma de conexão (ou, no detalhe da estação, Trocar para Wi-Fi direto (MQTT)).
3. Guarde a configuração — ela aparece uma única vez Servidor (host), usuário, senha e a PSK do canal ClimaAb. No passo 1 da tela: baixar .txt ou copiar tudo (o arquivo é gerado no seu navegador) e “Guardei”. O servidor guarda tudo cifrado e nunca mais mostra a PSK; perdeu? Configuração avançada → Credenciais → gerar novas.
4. Aguarde a ativação O estado começa em aguardando ativação: o administrador do Clima Aberto cria o seu usuário no servidor MQTT (é manual, no plano gratuito do broker). Você pode aplicar os comandos antes: o nó fica tentando e começa a publicar quando a ativação sair. O estado aparece no detalhe da sua estação (botão atualizar).
5. Aplique os comandos pelo PC Na tela da configuração, abra Configuração avançada · Pelo computador (CLI): o gerador roda só no seu navegador (faça no PC onde vai rodar os comandos) e usa o cadeado, a região e o preset do passo 2. Rode antes meshtastic --host IP --info (nó ainda sem Wi-Fi: meshtastic --port COM5 --info, no cabo USB) e informe: como o PC fala com o nó (pela rede, com o IP, ou pelo cabo USB, com a porta; vazio = o CLI acha sozinho), a região e o preset (no bloco "lora" do --info, por nome; no --get lora a região aparece só como número — ANZ = 6, BR_902 = 26 — e o LongFast não aparece), se o seu canal primário de hoje é privado (nome e PSK próprios) ou o padrão público, e — no privado — o nome e a PSK dele (obrigatória: sem ela o gerador não mostra os passos que mexem nos canais, porque o seu canal seria apagado). Ele calcula a frequência e monta, na ordem: backup (backup_a1b2c3d4.yaml, um arquivo por nó, com o ID dele sem o !), conferência, frequência fixa, seu canal no índice 1, o ClimaAb no índice 0, a telemetria a cada 10 min, o MQTT, a conferência final, pelo cabo USB o Wi-Fi por último (o nome e a senha da rede você troca no terminal, dentro das aspas simples, no PowerShell; ao ligar o Wi-Fi o Bluetooth desliga, a USB continua) e o mesmo slot nos seus outros nós. Pelo computador o canal público não volta como secundário (para manter a malha da comunidade, faça a tela Canais pelo app; pelo cabo USB, antes do passo do Wi-Fi, enquanto o app ainda conecta pelo Bluetooth). Os 10 min só valem assim, sem nenhum canal público: com o público de volta, o firmware força 30 min a cada boot. Precisa do CLI oficial:

   py -m pip install "meshtastic[cli]==2.7.11"

   Espere ~30 s entre um comando e outro: o nó reinicia a cada mudança. Erro de conexão (o nó ainda reiniciando)? Espere e rode o mesmo comando de novo. Qualquer outro erro: pare e não rode o próximo — o gerador mostra o comando de desfazer (ex.: meshtastic --host IP --configure backup_a1b2c3d4.yaml, que volta o backup do passo 1 daquele nó).
6. Veja no mapa Depois da ativação, a primeira leitura aparece no intervalo da telemetria. O detalhe da sua estação mostra Última leitura via MQTT; a Configuração avançada → Diagnóstico mostra por que pacotes foram descartados. Pode desligar a ponte, se usava.

O que vai para o servidor MQTT (e o que o Clima Aberto abre)

• O Clima Aberto só abre telemetria do próprio nó: confere que o pacote é do seu nó, em broadcast, cifrado com a PSK da sua estação; só então decifra. Se não for telemetria (texto, posição, nodeinfo), descarta sem abrir o conteúdo. Grava só as medidas ambientais e de energia — a API pública nunca mostra o ID do nó, a PSK, o usuário ou a senha.
• Mensagens diretas cifradas (PKI) que o nó envia ou escuta podem ser repassadas ao broker pelo firmware, em ca/2/e/PKI/!xxxxxxxx (não há opção para desligar, nem na 2.7.26 nem na 2.8); a regra do broker só deixa o seu usuário publicar no próprio tópico do ClimaAb e barra o resto. Elas nunca chegam ao Clima Aberto. Se o broker derrubar o nó a cada negação, veja Problemas comuns (“conecta e cai em seguida”).
• TLS sem conferir certificado: o firmware cifra a conexão (porta 8883), mas não confere quem é o servidor. Por isso o Clima Aberto ainda aplica limites de plausibilidade, descarta pacotes repetidos e limita a 30 leituras a cada 10 min por estação.
• Segredos no servidor (PSK e senha) ficam cifrados. A senha some do servidor quando o administrador ativa a conexão.

Por que trocar o canal primário e fixar a frequência

• A telemetria sempre sai no canal 0 (o primário) e o MQTT só sobe canais com envio ligado. Então o ClimaAb vira o primário (índice 0, com envio) e o seu canal de hoje (ex.: VeraCruz) vai para o índice 1, sem envio. As mensagens entre os seus nós continuam funcionando pelo rádio, e não sobem para a internet.
• O nome do primário escolhe a frequência. Com lora.channel_num 0, o firmware calcula o slot a partir do nome do canal primário. Trocar o primário de “VeraCruz” para “ClimaAb” mudaria a frequência (em ANZ/LongFast: do slot 28, 921,875 MHz, para o 43, 925,625 MHz) e o nó deixaria de ouvir os outros. Por isso o gerador fixa lora.channel_num no slot de hoje — e você põe o mesmo número nos seus outros nós (ex.: o que anda com você), pelo CLI ou pelo app (LoRa → Frequency slot).
• Se a região ou o preset forem outros, o gerador recalcula: confira no bloco "lora" do meshtastic --host IP --info ("region", "modemPreset" e "channelNum", por nome). Se o channelNum já for diferente de 0, a frequência já está fixa: pule os passos de fixar o slot.
• Canal de hoje sem nome, mas com PSK própria: é privado. Ele vai para o índice 1 com o nome que o firmware já usa no cálculo (ex.: LongFast) e a mesma PSK, então os outros nós continuam conversando com este.
• Canal de hoje é o padrão público (LongFast, PSK AQ==): ele não é recolocado, e o nó sai do canal público (recolocá-lo traria de volta o piso de 30 min da telemetria).
• Quer ver a telemetria da estação em outro nó seu pelo rádio (ex.: o que anda com você)? Opcional: adicione o ClimaAb nesse outro nó (nunca na estação, que já tem o ClimaAb no índice 0) num índice livre, sem envio (--ch-index 2 --ch-set name ClimaAb --ch-set psk base64:… --ch-set uplink_enabled false). Nunca com --ch-add-url.

Diagnóstico do Wi-Fi direto (códigos)

A Configuração avançada → Diagnóstico da sua estação mostra os últimos descartes. O que cada um quer dizer:

estacao_pendente

O nó já publica, mas a conexão ainda aguarda ativação. Normal até o administrador ativar. Se você gerou credenciais novas, aplique também a PSK e a senha novas no nó (no checklist: “O nó já está no ClimaAb”): com as antigas ele não volta.

no_id_divergente

O broker recebeu o seu usuário, mas de um nó com outro ID: o ID do cadastro é de outro nó (quase sempre o do nó ligado ao celular). Use Configuração avançada → Forma de conexão → Wi-Fi direto com o ID do Usuário (User Id) do nó que está no Wi-Fi → Trocar o nó.

estacao_revogada

A conexão foi revogada pelo administrador: tudo é descartado. Para pedir de novo, Configuração avançada → Credenciais → gerar novas (o administrador decide a reativação).

erro_cofre

O servidor não consegue abrir a PSK guardada (a chave do cofre dele mudou). Gere novas credenciais (Configuração avançada → Credenciais), aplique as novas e avise o administrador.

usuario_divergente ou clientid_divergente

O nó entrou no broker com outro usuário, ou o pacote não veio do nó cadastrado. Confira o Nome de usuário (Username) na tela MQTT (o da configuração, começa com ca).

limite_estacao

Mais de 30 leituras em 10 min: o excesso é descartado. Confira o intervalo da telemetria (600 s; ou 1800 s, com o canal público).

hash_do_canal ou decifra_falhou

A PSK configurada no nó não confere com a do cadastro. No app: Canais → ClimaAb → campo “chave” (Key), cole a PSK da configuração (Tamanho da Chave 256 bits). Gerou credenciais novas? A PSK antiga não vale mais.

gateway_divergente

O canal 0 do nó não se chama exatamente ClimaAb, ou o ID não confere.

em_claro

O nó está mandando sem cifra: ligue “A criptografia está ativada” (Encryption Enabled) na tela MQTT (ou --set mqtt.encryption_enabled true).

fora_da_janela

Relógio do nó fora: o nó pega a hora pelo Wi-Fi (NTP). Leituras com mais de 3 h de atraso ou adiantadas são recusadas. Confira se o nó tem internet de verdade.

sem_medida

A telemetria chegou sem nenhuma medida válida: sensor solto (BME280 não detectado no boot) ou valor fora do plausível.

nao_e_telemetria, pacote_de_terceiro, nao_broadcast, duplicado, estacao_mudou

Normais: mensagens, posições e nodeinfo descartados sem abrir, pacotes de outros nós, repetidos depois de uma reconexão, e pacotes que chegaram bem na hora de uma troca de credenciais.

Nada chega e nenhum descarte aparece

O nó não está conectando ao broker: confira o Wi-Fi (só 2,4 GHz, DHCP), MQTT ligado, o Endereço, o Nome de usuário e a Senha (meshtastic --host IP --get mqtt), o Tópico Raiz ca, e se a ativação já saiu. Heltec V2 com TLS ligado não conecta (veja o modo sem TLS). Heltec V3 (ou outro ESP32-S3): olhe o log serial do nó (monitor USB). “MQTT connected” = conectou. “SSL - Memory allocation failed” ou “start_ssl_client: connect failed: -32512”, seguidas de “MQTT server connect failed” = faltou memória para o TLS: use o modo sem TLS ou a ponte. “MQTT server connect failed” sem nenhuma linha de ssl_client = o TLS passou e o servidor recusou (confira Nome de usuário, Senha e se a ativação saiu) ou o Endereço não resolveu. Confira também a telemetria (app: Telemetria → Environment Metrics ligado; ou meshtastic --host IP --get telemetry mostrando telemetry.environment_measurement_enabled: True): no padrão ela vem desligada. Mais casos em Problemas comuns.

Voltar para a ponte

Configuração avançada → Forma de conexão → Cabo USB ou Bluetooth (as credenciais do Wi-Fi direto são apagadas). No nó: app → MQTT → MQTT Enabled desligado (ou meshtastic --host IP --set mqtt.enabled false). O backup do primeiro comando do computador guarda a configuração de antes.

Alternativa: a ponte (USB, Bluetooth ou Wi-Fi local)

Sem Wi-Fi no nó — ou preferindo não usar um servidor MQTT —, um computador ligado ao nó faz o envio. O rádio conversa com outros rádios (LoRa) e com um cliente conectado nele por USB, Wi-Fi ou Bluetooth — normalmente o app do celular.

A ponte é um programa pequeno, um arquivo só (ponte.py), que faz o papel desse cliente: fica ligada ao nó, separa a telemetria de ambiente e energia e envia ao Clima Aberto por HTTPS, com a chave da sua estação.

Ligado direto no nó, o cliente recebe uma leitura a cada ~1 minuto (e mais uma a cada envio pela malha). A ponte manda a primeira assim que chega a leitura de ambiente (em até ~1 minuto, para o mapa já mostrar) e depois junta as leituras e envia 1 vez a cada 5 minutos (mude com --intervalo SEG). Sem internet, ou com o servidor acordando, as leituras esperam numa fila no computador e seguem quando ele voltar.

Nó no Wi-Fi de casa e nenhum computador sobrando? O Wi-Fi direto (MQTT) dispensa a ponte. No mapa, a forma de conexão da estação se troca em Editar minha estação → Configuração avançada → Forma de conexão (ou no bloco Conectar o nó do detalhe).

O que você precisa

• Um nó Meshtastic com sensor — por exemplo BME280 (temperatura, umidade, pressão) e INA219 (tensão e corrente da bateria) — com a telemetria de ambiente ligada (Configurar o nó).
• A estação cadastrada no mapa e a chave de edição dela (mostrada uma vez no cadastro e guardada no navegador onde você cadastrou).
• Um computador sempre ligado, com internet, para rodar a ponte: PC com Windows, Raspberry Pi / Linux, ou um Android antigo com Termux (só via Wi-Fi).
• Esse computador ligado ao nó da estação (cabo USB ou Wi-Fi) ou a qualquer nó do mesmo canal que ouça a estação pelo rádio (modo gateway).
• Python 3.10 a 3.14 e a biblioteca meshtastic 2.7.11 (a versão testada com a ponte).

Windows, passo a passo

1. Instale o Python Baixe o Python 3.12, 3.13 ou 3.14 em python.org e instale. O comando py (o lançador do Python) vem junto e é o que usamos abaixo.
2. Instale a biblioteca meshtastic (e o keyring) Abra o Prompt de Comando ou o PowerShell e rode:

   py -m pip install "meshtastic==2.7.11" keyring

   O keyring é opcional: com ele a ponte guarda a chave no Gerenciador de Credenciais do Windows, em vez de pedir toda vez.
3. Baixe a ponte Baixar ponte.py
   O botão salva em Downloads. Melhor guardar numa pasta fixa, por exemplo C:\clima — pelo terminal, já baixando lá:

   mkdir C:\clima
   cd C:\clima
   curl.exe -O https://clima-aberto.pages.dev/ponte.py

   No PowerShell escreva curl.exe (com .exe): lá, curl sozinho pode ser outro comando. Baixou pelo botão? Mova o arquivo para C:\clima, ou troque cd C:\clima por cd $HOME\Downloads nos passos abaixo.
4. Ache a porta COM do nó Ligue o nó no USB e abra o Gerenciador de Dispositivos → Portas (COM e LPT). O Heltec aparece como algo parecido com Silicon Labs CP210x USB to UART Bridge (COM3) — o número pode ser outro. Tire e ponha o cabo para ver qual entrada some e volta.
5. Feche o que usa a porta App Meshtastic conectado nesse nó, o CLI meshtastic, monitores seriais (Arduino, PlatformIO…).
6. Confira o nó (opcional) Sempre a partir da pasta onde está o ponte.py. Lista os nós que o rádio conhece (id, nome, última leitura) — nada vai para a internet:

   cd C:\clima
   py ponte.py --serial COM3 --listar

   E para ver exatamente o que seria enviado, sem enviar e sem pedir a chave (espera a primeira leitura de ambiente do nó, até ~1 min):

   py ponte.py --estacao SEU-ID --serial COM3 --seco -v --uma-vez

7. Rode a ponte Troque SEU-ID pelo id da estação no Clima Aberto (o comando pronto está no mapa, no bloco Conectar o nó da sua estação):

   cd C:\clima
   py ponte.py --estacao SEU-ID --serial COM3

   Na primeira vez a ponte pede a chave: no mapa, toque em copiar minha chave e cole no terminal (Ctrl+V ou botão direito) e tecle Enter uma vez só. Nada aparece enquanto você cola — é de propósito. Ela avisa “Conferindo a chave…” (até ~1 min se o servidor estava dormindo) e pergunta se pode guardá-la: com o keyring do passo 2, no cofre do sistema — Enter = sim; sem ele, num arquivo — responda s. Para parar: Ctrl+C. Sem a porta (--serial sozinho) a ponte tenta achá-la sozinha.
8. Deixe rodando A janela precisa ficar aberta e o PC não pode dormir: em Configurações → Sistema → Energia, ponha a suspensão em Nunca.

Bluetooth (ponte)

Com a estação cadastrada como Bluetooth (ponte), o comando do bloco Conectar o nó troca --serial por --ble e o nome Bluetooth do nó:

py ponte.py --estacao SEU-ID --ble Meshtastic_ab12

• O nome aparece no app Meshtastic na hora de parear e na tela do nó: Meshtastic_ab12 ou, se você trocou o nome curto, NomeCurto_ab12 (as 4 letras/números finais vêm do endereço do rádio). Também vale o endereço Bluetooth.
• O Wi-Fi do nó precisa estar desligado: no ESP32, Wi-Fi configurado desliga o Bluetooth.
• Um cliente Bluetooth por vez: desconecte o app do celular desse nó. O computador fica a poucos metros do nó.

Linux / Raspberry Pi

Num Raspberry Pi (ou qualquer Linux) a ponte roda como serviço, sozinha, desde o boot. Use um ambiente virtual (o Raspberry Pi OS recente não deixa instalar pacotes com pip fora de um):

python3 -m venv ~/clima
~/clima/bin/pip install "meshtastic==2.7.11"
cd ~/clima && curl -O https://clima-aberto.pages.dev/ponte.py
ls /dev/ttyUSB* /dev/ttyACM*        # a porta do nó (Heltec: normalmente /dev/ttyUSB0)
sudo usermod -aG dialout $USER      # permissão na porta serial: saia e entre de novo
~/clima/bin/python ~/clima/ponte.py --estacao SEU-ID --serial /dev/ttyUSB0

Na primeira vez ela pede a chave. Num Raspberry sem tela normalmente não há cofre do sistema: aceite guardar no arquivo ~/.clima_aberto_ponte_chaves.json (texto puro, só o seu usuário lê). O serviço abaixo roda com o mesmo usuário e acha a chave lá.

Agora vire serviço. Crie /etc/systemd/system/clima-ponte.service (troque pi pelo seu usuário e SEU-ID pelo id da estação):

[Unit]
Description=Clima Aberto - ponte Meshtastic
After=network-online.target
Wants=network-online.target

[Service]
User=pi
WorkingDirectory=/home/pi/clima
ExecStart=/home/pi/clima/bin/python /home/pi/clima/ponte.py --estacao SEU-ID --serial /dev/ttyUSB0
Restart=always
RestartSec=30

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now clima-ponte
journalctl -u clima-ponte -f         # acompanhar (Ctrl+C sai; o serviço continua)

Prefere variável de ambiente? A ponte lê CLIMA_CHAVE_SEU_ID (o id em maiúsculas, com _ no lugar de -; ex.: CLIMA_CHAVE_VERA_CRUZ). Ponha num arquivo com chmod 600 e aponte com EnvironmentFile= — nunca escreva a chave direto no .service, que todos os usuários conseguem ler.

Android antigo (Termux) — só via Wi-Fi

Um celular parado na tomada gasta pouco e serve de ponte, com ressalvas:

• USB não funciona no Termux (limite documentado pelo próprio Meshtastic) e Bluetooth não é viável. O que funciona é o nó no Wi-Fi da casa e a ponte falando com ele pela rede (TCP, porta 4403).
• A documentação oficial chama esse modo de “em desenvolvimento”: trate como experimental.
• Ligue o Wi-Fi do nó antes (veja abaixo). No ESP32, Wi-Fi ligado desliga o Bluetooth.

pkg install python
pip install --no-deps meshtastic==2.7.11
pip install protobuf pypubsub pyserial requests tabulate packaging
curl -O https://clima-aberto.pages.dev/ponte.py
termux-wake-lock                     # impede a CPU de dormir
python ponte.py --estacao SEU-ID --tcp 192.168.x.y

O --no-deps pula a parte de Bluetooth da biblioteca (que tentaria compilar no celular e não serve no Android); a ponte não precisa dela. A chave pode ficar no arquivo que a ponte oferece na primeira vez. Deixe o celular carregando.

Configurar o nó

Estes comandos usam o CLI oficial (py -m pip install "meshtastic[cli]==2.7.11"). Troque COM3 pela sua porta (no Linux, /dev/ttyUSB0). Cada --set reinicia o nó, por isso junte tudo num comando só. Feche a ponte antes (a porta é uma só).

1. Telemetria de ambiente (obrigatório)

meshtastic --port COM3 --set telemetry.environment_measurement_enabled true --set telemetry.environment_update_interval 600
meshtastic --port COM3 --get telemetry

• Ponha o intervalo sempre explícito. Com 0, o firmware 2.7 usa 1 hora (a documentação fala em 30 min).
• O INA219 já vai junto no pacote de ambiente (tensão em V e corrente em mA). A telemetria de energia não é necessária — deixe desligada, ela só gera mais um pacote no ar:

  meshtastic --port COM3 --set telemetry.power_measurement_enabled false

• Não use power.device_battery_ina_address: ele faz a tensão do INA virar a “bateria do nó” e calcula a porcentagem com a curva de uma célula de lítio — errado para bateria de 12 V.
• Não ligue power.is_power_saving se a ponte usa a USB, o Wi-Fi ou o Bluetooth da estação: ele desliga Bluetooth, serial e Wi-Fi.
• Unidades: temperatura em °C, umidade em %, pressão em hPa medida no local (sem correção para o nível do mar).
• Para conferir, meshtastic --port COM3 --noproto mostra no terminal as linhas Send: barometric_pressure=…, temperature=… a cada leitura (Ctrl+C sai).

2. Leituras a cada 10 min: só sem nenhum canal público

Com o canal padrão público (ex.: LongFast, chave padrão) em qualquer índice, primário ou secundário, o firmware impõe a cada boot um piso de 30 min à telemetria, para proteger o tempo de ar da malha pública. Com um canal primário próprio (nome e senha seus) e nenhum canal público no nó, os 600 s valem:

meshtastic --port COM3 --ch-set name MeuCanal --ch-set psk random --ch-index 0

Já tem canal privado? Pule. Senão, troque MeuCanal por um nome seu. A senha (psk random) é nova: os outros nós da sua malha precisam recebê-la pela URL do canal.

3. Wi-Fi (para TCP: Termux, NOMAD ou PC em outro cômodo)

meshtastic --port COM3 --set network.wifi_enabled true --set network.wifi_ssid "NomeDaRede" --set network.wifi_psk "senha"
meshtastic --host 192.168.x.y --nodes --show-fields user.id,user.shortName

• Só rede de 2,4 GHz.
• No ESP32 o Bluetooth desliga com o Wi-Fi configurado — mesmo se a senha estiver errada. Para corrigir, use a USB.
• Reserve o IP do nó no roteador (DHCP). Com um nó só na rede, Meshtastic.local também funciona.
• Um cliente TCP por vez: quem conecta derruba o anterior.
• Wi-Fi ligado gasta mais energia — confira o orçamento do painel solar.
• Com Wi-Fi o nó acerta o relógio pela internet (NTP).

Estação longe: só no rádio, com um nó em casa

A estação fica lá fora, no solar, só no LoRa. Em casa, outro nó (por exemplo um Heltec V3) fica no USB ou no Wi-Fi do computador da ponte e ouve a estação pelo rádio. Funciona: o nó de casa entrega ao cliente a telemetria que ouve dos outros nós.

Condições: mesma região, mesmo preset e mesmo canal primário (nome e senha). O jeito exato é copiar a URL do canal da estação — ela leva os canais e a configuração de rádio:

meshtastic --port COM3 --qr                # na estação: mostra a URL do canal
meshtastic --port COM4 --seturl "URL"      # no nó de casa (substitui os canais dele)
meshtastic --port COM4 --get lora          # confira região e preset

Depois rode a ponte no nó de casa dizendo qual é o nó da estação — a ponte aceita só a telemetria dele (o nó de casa ouve outros nós e pode ter sensor próprio):

py ponte.py --estacao SEU-ID --serial COM4 --no !a1b2c3d4

• Para achar o id do nó da estação (! + 8 letras/números): no nó de casa, py ponte.py --serial COM4 --listar mostra os nós que ele já ouviu (id, nome, última leitura; nada vai para a internet). O id certo é o de uma linha sem * — a linha com * é o próprio nó de casa (com --no dele, a ponte publicaria a temperatura de dentro de casa). Se você rodar sem --no e o rádio ouvir temperatura de outro nó, a ponte avisa qual id usar. Ou, na própria estação, meshtastic --port COM3 --nodes --show-fields user.id,user.longName,user.shortName,hopsAway,lastHeard (lista sem posições). Se o nome nunca foi trocado, “Meshtastic ab12” corresponde a um id terminado em ab12.
• Nesse modo a ponte recebe só os envios pela malha (a cada 10 min); a leitura de 1 em 1 minuto fica na estação. Por isso --uma-vez espera até 11 min.
• Use canal primário privado (senha própria). Telemetria pelo rádio não é assinada: no canal com a senha padrão, qualquer rádio poderia se passar pela estação — a ponte avisa se for o caso. Pacotes que chegam pela internet (MQTT) são ignorados.
• O nó de casa sai da malha pública LongFast. Para levá-lo a campo (POTA, por exemplo), ele precisa voltar ao canal público.

Privacidade: o que a ponte envia e o que nunca envia

• O horário de cada leitura vem do relógio do computador: sem GPS ou internet, o relógio do nó conta a partir do boot (dá 1970).
• Tudo o que chega vira dado aberto (CC0) no mapa e na API. A posição da estação é a do cadastro, arredondada (~1 km).
• Qualquer programa conectado ao nó (o app, o CLI, a ponte) recebe a configuração inteira, com senhas. Sem --no, a ponte conecta pedindo o mínimo (só o próprio nó, sem a lista de nós da malha). No modo gateway (--no) e no --listar ela precisa da lista de nós, com nomes e posições: fica só na memória enquanto roda e nunca é enviada. Em todos os casos ignora o resto e não grava nem imprime senhas nem posições.
• Quer conferir? ponte.py é um arquivo de texto: abra e leia.

A chave: onde fica

• A chave de edição é o único segredo. O servidor guarda só uma impressão digital dela (hash SHA-256), nunca o texto.
• No mapa: fica no navegador onde você cadastrou (no aparelho, não no servidor). O botão copiar minha chave copia sem mostrar na tela; testar chave confere com o servidor sem gravar nada.
• Na ponte: ela procura a chave nesta ordem — variável de ambiente CLIMA_CHAVE_SEU_ID; cofre do sistema (Gerenciador de Credenciais do Windows / Chaveiro, se o keyring estiver instalado); o arquivo .clima_aberto_ponte_chaves.json na pasta do seu usuário (texto puro, só se você aceitar); senão, pergunta. Tudo fica só neste computador. Para apagar: py ponte.py --estacao SEU-ID --esquecer-chave.
• Ela viaja só no cabeçalho X-Chave-Edicao e só por HTTPS (http só para testes no próprio computador). Nunca vai na URL e nunca aparece no log.
• No Wi-Fi direto a chave serve para editar a estação, ver o estado da conexão e abrir a Configuração avançada (forma de conexão, credenciais novas, comandos e diagnóstico): o botão só libera depois que o site confere a chave com o servidor. A senha do MQTT e a PSK nunca ficam guardadas no navegador: aparecem uma vez e somem quando você fecha a janela.
• Aba privada do Safari apaga a chave ao fechar a aba: use uma aba normal. Sem a chave neste navegador, cole-a em Editar minha estação (ela fica guardada de novo).

Hoje não há troca de chave: se ela vazar, exclua e recadastre a estação.

Problemas da ponte

Para o Wi-Fi direto e o app do celular, veja Problemas comuns.

Nada aparece no mapa

Telemetria de ambiente desligada ou intervalo 0 (= 1 hora): veja Configurar o nó. Com o canal padrão público no nó (primário ou secundário) o mínimo é 30 min. Confira o id da estação (é o do Clima Aberto, como vera-cruz, não o do nó). No modo gateway: id do nó errado, ou o nó de casa sem o mesmo canal primário e região. E feche o app do celular nesse nó (ele divide as leituras). Se nada chegar do nó por 30 min, a própria ponte avisa (Sem telemetria da estacao ha …) e reconecta. Para ver cada pacote aceito ou ignorado, rode com -v.

A primeira leitura demora ~1 minuto

O servidor gratuito dorme depois de 15 min sem acesso e leva ~50 s para acordar. Normal: a ponte espera, tenta de novo e guarda as leituras na fila enquanto isso; os envios seguintes são rápidos.

Só aparece a bateria, sem temperatura

O BME280 não foi detectado no boot do nó (cabo ou endereço 0x76). Confira e reinicie o nó. O --uma-vez espera a leitura de ambiente e avisa se só chegaram dados da placa.

“O relogio deste computador e o do no diferem…” / “horario da leitura no futuro”

O horário das leituras vem do computador. Acerte a hora do Windows (Configurações → Hora e idioma → Sincronizar agora). Enquanto isso a ponte corrige pela hora do servidor e não perde leituras.

Bateria em ~1 V ou valor sem sentido

Ligue o negativo da bateria ao GND do Heltec/INA219 (sem terra comum a tensão “flutua”).

“Nao consegui abrir a porta COM3: ela nao existe ou esta em uso”

Porta errada (confira no Gerenciador de Dispositivos), ou ocupada pelo app, pelo CLI ou por um monitor serial.

“Nenhum radio encontrado na USB”

Com --serial sozinho: cabo só de carga (sem dados), driver CP210x faltando, ou nó desligado. Informe a porta: --serial COM3.

can't open file '...\ponte.py': [Errno 2] No such file or directory

O terminal não está na pasta do arquivo. Vá até ela antes: cd C:\clima (ou cd $HOME\Downloads, se baixou pelo botão). Ou rode com o caminho completo: py C:\clima\ponte.py …

“Python nao foi encontrado; executar sem argumentos para instalar do Microsoft Store”

No Windows use py, não python (o python cai num atalho da Loja).

“A chave nao confere” (403) / estação inexistente (404)

A ponte confere a chave ao iniciar. 403: a chave não é desta estação — use testar chave no mapa, copie de novo e, se havia uma guardada, rode antes py ponte.py --estacao SEU-ID --esquecer-chave. 404: a estação não existe (id errado ou excluída). 401: faltou a chave. Se isso acontecer com a ponte já rodando, ela pausa a estação (as leituras ficam na fila), confere a chave de novo a cada 30 min e volta sozinha quando valer. Erros passageiros do servidor (404 de página, 408, 5xx) só fazem a ponte esperar e tentar de novo.

422

Uma leitura com valor fora do plausível (sensor com defeito?) foi recusada. As próximas seguem normalmente.

429

Mais de 120 leituras em 10 min para a mesma estação. A ponte já espaça os envios; se aparecer, veja se há duas pontes rodando para a mesma estação.

Instalou meshtastic 2.3.11

Python 3.15. Use o 3.12, 3.13 ou 3.14 e o comando com "meshtastic==2.7.11".

Wi-Fi do nó não conecta

Só rede de 2,4 GHz. Com senha errada o Bluetooth também fica desligado: corrija pela USB.

Próximos passos

Servidor MQTT próprio

O Wi-Fi direto usa o servidor MQTT do Clima Aberto (plano gratuito, com ativação manual). Uma rede maior pode ter o seu próprio (por exemplo Mosquitto no NOMAD), com um programa sempre ligado repassando ao Clima Aberto. Nunca use o servidor MQTT público do Meshtastic para isso: lá os pacotes ficam à vista de todos, e muitos abrem com a senha padrão.

NOMAD

O servidor offline de casa pode rodar a ponte; sem internet, as leituras esperam na fila dela e seguem depois (a API aceita horário antigo). No Windows, o Docker (WSL2) não enxerga a USB sem o usbipd-win — prefira o nó no Wi-Fi (TCP). Guarde a chave fora da interface e de volumes expostos.