Introdução ao MeshCore Remote Terminal
Este wiki apresentará o Remote Terminal for MeshCore (RemoteTerm) para fornecer uma interface para dispositivos MeshCore transmitirem mensagens. Este tutorial fornece uma configuração básica para executar o RemoteTerm em um Raspberry Pi usando o Seeed XIAO ESP32S3 & SX1262 Kit como rádio auxiliar e o Raspberry Pi Zero 2W para uma solução MeshCore compacta e tudo‑em‑um para usuários avançados!
Introdução ao RemoteTerm
O RemoteTerm é um aplicativo de código aberto que é executado em um servidor com um dispositivo MeshCore conectado.
Ele fornece uma interface para a rede MeshCore local, permitindo que qualquer dispositivo na mesma rede local (mesmo fora da rede elétrica) envie e receba mensagens via rádio. O RemoteTerm é extremamente amigável para dispositivos móveis. Ele habilita capacidades adicionais, como:
- Armazenar em cache todos os pacotes recebidos
- Executar múltiplos bots em Python
- Monitorar contatos e canais ilimitados
- Acessar seu rádio remotamente pela sua rede ou VPN
- Encaminhar pacotes para MQTT, SQS, Apprise, etc.
- Visualizar o mapa de nós da malha
Configuração
Hardware
| Kit XIAO ESP32S3 & Wio-SX1262 | Raspberry Pi Zero 2W |
|---|---|
 |  |
Além do hardware principal, aqui estão os acessórios necessários:
- Cartão MicroSD de 16 GB ou maior
- Cabo USB Micro para USB-C (para conectar o rádio)
- USB Micro para USB-A ou USB-C (para alimentar o Raspberry Pi)
- Fonte de alimentação confiável para o Raspberry Pi (5V 2,5A recomendado)
Configuração do rádio
- Combine a placa XIAO ESP32S3 da Seeed e o módulo SX1262 usando o conector B2B.
- Conecte a antena LoRa ao SX1262.
- Conecte ao seu computador e faça o flash com "Seeed Studio Xiao S3 WIO" (Serial Companion) via web flasher.
Este tutorial orienta você a configurar um serial companion. Companions TCP e Bluetooth são suportados pelo RemoteTerm, mas são um pouco mais complicados de configurar.
Configuração do Pi
- Clique aqui para baixar o Raspberry Pi Imager
- Abra o Imager e selecione o modelo do seu Raspberry Pi e selecione "Raspberry Pi OS Lite (64 bit)"
- Configure o SSH com uma senha, ou chave se desejar, e configure a conexão Wi‑Fi
- Conecte o ESP32 MeshCore ao Raspberry Pi
garantindo que o nó ESP32 LoRa Mesh esteja conectado à porta USB, não à porta POWER
Uma instalação completa (com adaptador em ângulo reto) pode se parecer com isto:
- Conecte a alimentação à porta
POWERdo Pi - Use a interface de administração do roteador da sua casa para determinar o endereço atribuído ao Raspberry Pi. Considere alocar uma reserva de DHCP para evitar mudanças de endereço IP.
Configuração do Pi
- Abra uma sessão SSH para o Raspberry Pi
- Valide se o rádio aparece.
find /dev/serial/by-id -maxdepth 1 -type l -print | sortdeve mostrar uma listagem como/dev/serial/by-id/usb-Espressif_USB_JTAG_serial_debug_unit_XX:XX:XX:XX:XX:XX-if00 - Atualizar e fazer upgrade
sudo apt update # update package repositories
sudo apt upgrade -y # upgrade packages
sudo apt-get install -y git # install git
curl -fsSL https://get.docker.com | sh # install docker - Clonar e iniciar
git clone https://github.com/jkingsman/Remote-Terminal-for-MeshCore.git
cd Remote-Terminal-for-MeshCore/
# configure the docker setup
./scripts/setup/install_docker.sh
Passo a passo das opções de configuração
O README e o blog fornecem instruções de configuração mais detalhadas
Inicializando o servidor
Configuração
Depois de configurar seu dockerfile por meio do script de configuração, execute
sudo docker compose up -d
para iniciar o servidor. Os seguintes comandos também podem ser úteis:
sudo docker compose up -d # start RemoteTerm in the background
sudo docker compose logs -f # follow the container logs live
sudo docker compose down # stop and remove the running container
sudo docker compose restart # restart the container without changing the image
sudo docker compose pull && sudo docker compose up -d # upgrade to the latest published image and restart
O RemoteTerm faz o gerenciamento completo do rádio, o que significa que, uma vez que um rádio é conectado ao RemoteTerm, todos os contatos/canais serão importados e descarregados para o RemoteTerm, e os contatos realmente sincronizados com o dispositivo serão controlados pelo RemoteTerm.
Configuração de hotspot (opcional)
Isto é opcional e recomendado apenas para rádios que serão usados longe da sua casa. Esta configuração desconectará o rádio do Wi‑Fi da sua casa, mas o configurará para começar a transmitir seu próprio Wi‑Fi para que ele possa ser acessado sem uma conexão com a internet.
-
Configurar um hotspot
sudo nmcli device wifi hotspot ssid <hotspot name> password <hotspot password> ifname wlan0 -
Você provavelmente precisará se conectar à nova rede Wi‑Fi e fazer SSH no Pi novamente. A URL do seu Pi será o "gateway padrão" na configuração de Wi‑Fi da nova rede quando você se conectar a ela.
-
Configurar o hotspot para transmitir na inicialização
nmcli connection
# grab the UUID of the Hotspot connection
sudo nmcli connection modify <hotspot UUID> connection.autoconnect yes connection.autoconnect-priority 100
Introdução ao RemoteTerm
Tela principal
A tela principal do RemoteTerm mostra uma lista de canais, repetidores e servidores de sala conhecidos, com um espaço para Favoritos na parte superior. Clique em qualquer contato ou canal para começar a enviar mensagens ou clique em um repetidor para fazer login e visualizar a interface de administração. Você pode adicionar canais ou contatos com o botão verde na parte superior.
Acima da lista de contatos há um conjunto de ferramentas:
| Item geral | Função |
|---|---|
| Packet Feed | Uma exibição de pacotes brutos recebidos à medida que chegam |
| Node Map | Visualizar a localização dos nós |
| Mesh Visualizer | Uma representação 3D personalizável de nós e tráfego em tempo real |
| Trace | Executar rastreamentos multi‑hop entre repetidores para obter informações de intensidade de sinal |
| Message Search | Pesquisar o histórico de canais e mensagens por palavras ou frases |
| Channel Finder | O localizador de canais encontra nomes de canais para pacotes ouvidos mas não descriptografados |
Mensagens (Canais)
Para criar ou entrar em um canal, clique no botão 'Add Channel/Contact” no canto superior esquerdo do menu principal do aplicativo. Canais privados, identificados apenas pela sua chave, ou canais Hashtag, identificados pelo seu nome como uma #hashtag, podem ser acessados a partir do menu que aparece.
O canal Public é adicionado automaticamente a todas as novas instâncias do RemoteTerm. Sua malha local provavelmente terá sua cota de canais ativos: Public, #test ou #testing, e #bots ou #bot podem ser bons lugares para começar ou encontrar pessoas que possam apontar para boas salas locais para iniciantes.
Quando um canal é selecionado, a tela ficará parecida com isto:
Na barra de status:
| Ícone | Função |
|---|---|
 | Configura notificações, seja como notificações na área de trabalho (que exigem que o navegador esteja aberto) ou Web Push (que podem ser entregues mesmo quando o navegador está fechado). Isso requer um contexto HTTPS confiável (os certificados snakeoil disponíveis no instalador podem ou não ser suficientes para permitir notificações, dependendo do seu sistema operacional e navegador) |
 | Habilita substituições de roteamento regionais, que limitam o escopo regional do rádio quando ele envia mensagens apenas neste canal. Usuários com configurações de região correspondentes ou diferentes poderão ver ou ignorar automaticamente suas mensagens, respectivamente |
 | Permite substituições de largura de salto por canal, separadas do padrão do seu rádio |
 | Adiciona ou remove um canal dos seus favoritos |
 | Exclui o canal, mas mantém as mensagens históricas se você optar por adicioná‑lo novamente depois |
| Room Key | Fornece a chave MeshCore para a sala em questão |
No canto superior esquerdo está o nome do canal com um ícone de informações; você pode clicar nele para ver informações sobre o canal, como quão ativo ele é, quem está enviando mensagens e sua chave (que você também pode ver clicando no texto "Show key" na barra de status superior):
Mensagens (Mensagens Diretas)
O envio de mensagens diretas funciona de forma semelhante às mensagens de canal, com algumas opções diferentes.
| Ícone | Função |
|---|---|
 | Envia uma sonda roteada para o contato para descobrir um caminho de roteamento mais ideal para as mensagens seguirem |
 | Envia um rastreamento direto para o contato, com dados de SNR remoto e local |
| Configura notificações, seja como notificações de desktop (que exigem que o navegador esteja aberto) ou Web Push (que podem ser entregues mesmo quando o navegador está fechado). Isso requer um contexto HTTPS confiável (os certificados snakeoil disponíveis no instalador podem ou não ser suficientes para permitir notificações, dependendo do seu sistema operacional e navegador) |
| Adiciona ou remove um contato dos seus favoritos |
| Exclui a conversa, mas mantém as mensagens históricas se você optar por adicioná-la novamente depois |
| Chave do Contato | Fornece a chave MeshCore para o contato em questão e informações sobre quando ele foi ouvido pela última vez (anúncio, mensagem, etc.) e o método (direto, ou qual caminho o pacote percorreu) |
De forma semelhante aos canais, você pode clicar no ícone de informações ou no nome na barra superior de um contato selecionado para ver análises do contato
MQTT e Automação
RemoteTerm se destaca ao fornecer integrações ricas para sistemas automatizados. As integrações executam ações quando pacotes de certos tipos são ouvidos (por exemplo, quando uma mensagem é enviada em um canal ou uma DM é recebida). Isso inclui:
- MQTT, encaminhando pacotes via MQTT para:
- Brokers privados
- Agregadores da comunidade
- Home Assistant
- Webhooks, enviando requisições GET ou POST para uma URL específica com dados da mensagem
- Apprise, uma ferramenta flexível de distribuição de notificações que pode encaminhar para Discord, Telegram, SMS, e-mail etc.
- Colocar pacotes ou mensagens em filas Amazon SQS
- Bots em Python
Configurar para Mapeamento de Malha da Comunidade
Mostrar a localização dos nós MeshCore, padrões de fluxo de mensagens e quebras de conectividade, etc. — pode ser útil para a comunidade na construção da rede MeshCore. Para fornecer essa visualização de depuração, agregadores da comunidade ingerem um fluxo de pacotes brutos de observadores.
RemoteTerm facilita o uso do mesmo rádio que você usa para enviar e receber mensagens para contribuir com esses esforços comunitários de mapeamento e visibilidade como um nó observador.
MeshCore não permite que mensagens entrem na malha por meio de nós MQTT; os esforços de observabilidade da comunidade são somente leitura.
Existem muitas plataformas de observadores da comunidade, mas a LetsMesh é uma das mais populares, e é isso que vamos configurar.
- Clique aqui para visitar o LetsMesh e fazer login no analisador LetsMesh.
- No RemoteTerm, navegue até "Settings" e clique em "MQTT & Automation".
- Clique em "Add Integration" e escolha "LetsMesh (US)" na lista à esquerda.
- Clique em "Create".
- Preencha com o mesmo e-mail que você usou para se cadastrar no LetsMesh e insira o código IATA do aeroporto mais próximo
- Clique em "Save as Enabled".
Você deverá ver um ponto verde e o status "Connected"; uma integração saudável deve se parecer com isto:
Se em vez disso você vir um ponto âmbar, clique no símbolo "ⓘ" ao lado do botão Edit para ver o erro.
Agora, navegue para este link. Em cerca de 15 minutos, você deverá ver seu rádio aparecer em verde lá, e sua própria telemetria e pacotes sendo encaminhados para o LetsMesh!
Bot
RemoteTerm fornece uma interface para programar seus próprios bots. Bots consistem em código Python simples que é executado sempre que uma mensagem é recebida de um contato ou canal.
Bots geram tráfego automatizado em resposta a outras mensagens. Isso significa que é sua responsabilidade garantir que os bots sejam cuidadosamente escritos para evitar inundar a malha ou entrar em loop infinito.
Configurar um Bot Simples de Rolagem de Dados
Aqui está um tutorial guiando você a construir um bot com capacidades simples de rolagem de dados, solicitado em forma padrão (por exemplo, "3d6" significa rolar 3 dados de seis lados). Aqui estão os passos simples:
- No RemoteTerm, navegue até "Settings" e clique em "MQTT & Automation".
- Clique em "Add Integration" e escolha "Python Bot" na lista à esquerda.
- Clique em "Create".
- Dê ao bot um nome descritivo, como "Dice Bot".
- Apague o código do editor e cole o seguinte código em seu lugar:
import random
import re
def bot(**kwargs) -> str | list[str] | None:
"""Dice roller — responds to !dice NdS in #bot only."""
sender_name = kwargs.get("sender_name")
message_text = kwargs.get("message_text", "")
channel_name = kwargs.get("channel_name")
is_outgoing = kwargs.get("is_outgoing", False)
if is_outgoing or channel_name != "#bot":
return None
match = re.match(r"^!dice\s+(\d+)d(\d+)$", message_text.strip())
if not match:
return None
count, sides = int(match.group(1)), int(match.group(2))
if count < 1 or count > 20 or sides < 2 or sides > 100:
return "I don't know how to roll that! [1-20]d[2-100]"
rolls = [random.randint(1, sides) for _ in range(count)]
parts = " + ".join(str(r) for r in rolls)
name = sender_name or "Someone"
return f"@[{name}] rolled {parts} = {sum(rolls)}"
- Clique em "Save as Enabled".
Usando outro rádio, navegue até a sala #bot e solicite uma rolagem de dados (por exemplo, "3d6"). A saída deve se parecer com isto:
Se você não vir a resposta como esperado, pode verificar os logs do servidor do seu contêiner Docker para ver se há algum erro relatado quando o código Python é executado.
Configurar um Bot de Largura de Caminho
O firmware MeshCore v1.14+ trouxe grandes mudanças em como as mensagens atravessam a malha; pacotes que atravessam roteadores compatíveis agora podem carregar identificadores de salto multibyte.
Podemos criar um bot para ajudar as pessoas a determinar se um caminho multibyte está associado à sua mensagem. Este script usa a capacidade de enviar várias mensagens em resposta, fornecendo uma mensagem de largura de salto e os próprios dados de salto do pacote.
def bot(**kwargs) -> str | list[str] | None:
"""Report the sender's path hop width in #bot."""
sender_name = kwargs.get("sender_name")
message_text = kwargs.get("message_text", "")
channel_name = kwargs.get("channel_name")
is_outgoing = kwargs.get("is_outgoing", False)
path = kwargs.get("path")
path_bytes_per_hop = kwargs.get("path_bytes_per_hop")
if is_outgoing or channel_name != "#bot":
return None
if "!hopwidth" not in message_text.lower():
return None
name = sender_name or "Someone"
if path_bytes_per_hop is None or not path:
return f"@[{name}]'s hop width is unknown (no path data)"
hop_count = (len(path) // 2) // path_bytes_per_hop
if path_bytes_per_hop == 1:
msg = f"@[{name}]'s hops are 1 byte wide; they might not be on 1.14+ or there may be incompatible repeaters in the path."
else:
msg = f"@[{name}]'s hops are {path_bytes_per_hop} bytes wide; they are using firmware v1.14+!"
return [msg, f"Heard via {hop_count} hop{'s' if hop_count != 1 else ''}"]
Encaminhar Mensagens de Canal MeshCore para o Discord
Apprise é um serviço de notificação flexível suportado pelo RemoteTerm. O Apprise permite que você escolha um ou muitos entre centenas de serviços de notificação para os quais enviar mensagens de canal ou diretas, desde Discord até Telegram, SMS, e-mail e muito mais.
Como exemplo, usaremos o Apprise para encaminhar todas as mensagens em um canal MeshCore específico para o Discord via RemoteTerm.
- Abra o Discord em um canal no qual você tenha privilégios de administrador.
- Clique com o botão direito no nome do canal e clique em "Edit Channel".
- Clique em "Integrations" no menu à esquerda e depois clique em "Create Webhook".
- Dê um nome apropriado ao webhook e copie a URL do webhook. O webhook deve ter o formato
https://discord.com/api/webhooks/<WebhookID>/<WebhookToken>
- No RemoteTerm, navegue até "Settings" e clique em "MQTT & Automation".
- Clique em "Add Integration" e escolha "Apprise" na lista à esquerda.
- Clique em "Create".
- Adicione uma URL de notificação na entrada. De acordo com a documentação do Discord do Apprise, ela deve ter o formato
discord://{WebhookID}/{WebhookToken}/. Use o WebhookID e o WebhookToken da URL copiada. - Escolha se deseja preservar a identidade do usuário usando o nome e o avatar configurados quando disponíveis.
- Escolha se deseja incluir dados de rota no caminho na mensagem (recomendado desativar)
- Selecione os contatos/canais que você gostaria de encaminhar para o Discord e clique em "Save as Enabled".
Depois de ativado, você deverá começar a ver as mensagens fluindo! Se tiver problemas ou não vir as mensagens que espera, verifique os logs do servidor em busca de erros relatados ou tente ativar todos os canais para garantir que pelo menos o vínculo RemoteTerm ↔ Discord esteja funcionando.
Integrar o RemoteTerm com o Home Assistant
Home Assistant fornece uma estrutura para automação residencial poderosa e fácil de usar. O RemoteTerm oferece integração com o Home Assistant por meio da integração MQTT integrada. Com essa integração, você pode acionar automações com base em mensagens, monitorar repetidores e telemetria de rádio local e rastrear contatos via GPS em seus anúncios.
Para aproveitar o rastreamento de telemetria de repetidores, você precisará inscrever os repetidores desejados na busca automática de telemetria. Depois de inscritos, o RemoteTerm solicitará telemetria em um intervalo configurável, mantendo valores históricos e tornando os valores atualizados visíveis no Home Assistant.
A busca automatizada de telemetria de repetidores tem um intervalo personalizável; você pode escolher uma frequência que varia de uma vez por hora a uma vez por dia, com a restrição de que buscas automatizadas não podem exceder 24 em um período de 24 horas.
Depois de configurar seus repetidores rastreados conforme desejado e o MQTT Discovery estiver ativado no Home Assistant, você poderá configurar uma integração no RemoteTerm para iniciar o fluxo de dados.
- No RemoteTerm, navegue até "Settings" e clique em "MQTT & Automation".
- Clique em "Add Integration" e escolha "Home Assistant MQTT Discovery" na lista à esquerda.
- Clique em "Create".
- Insira as informações do seu broker MQTT, incluindo host e porta, e configuração de nome de usuário/senha/TLS, se aplicável.
- Escolha os contatos a serem rastreados via localização GPS de anúncios no Home Assistant.
- Selecione os repetidores com telemetria rastreada que você deseja ver no Home Assistant.
- Escolha o escopo de mensagens para gatilhos dentro do Home Assistant.
- Clique em "Save as Enabled".
Observe que a tela de configuração de integração do RemoteTerm fornece os tópicos/entidades exatos criados nos menus suspensos "What gets created in Home Assistant" e "Published Topic Summary".
Contatos e repetidores rastreados criarão entidades no Home Assistant; você pode querer limitar sua seleção apenas aos contatos que lhe interessam para evitar poluir o Home Assistant.
Eventos de mensagem não criam entidades e são usados apenas para gatilhos; em geral, não há problema em permitir que todas as mensagens fluam para o Home Assistant.
Para visualizar as novas entidades, faça login na interface web do Home Assistant. Clique em Settings, depois em Devices & Services e, em seguida, em MQTT. Você deverá ver suas entidades rastreadas exibidas.
Clique nelas para ver suas métricas disponíveis. Para repetidores, serão exibidas as métricas mais recentes disponíveis e não obsoletas; se você tiver ativado recentemente a busca automatizada de telemetria, talvez seja necessário aguardar até oito horas para que todos os campos de telemetria de repetidores e rádios sejam preenchidos no Home Assistant.
Para orientações adicionais de configuração, consulte o arquivo README_HA.md no repositório do RemoteTerm. Por exemplo, seguir as instruções em "Full monitoring dashboard with message feed" fornecerá um dashboard como este:
Próximas etapas
Mantenha-se atualizado com o desenvolvimento do RemoteTerm ou tire dúvidas entrando no Discord oficial do MeshCore e acompanhando o tópico de desenvolvimento do RemoteTerm. A base de código é atualizada com frequência e você pode encontrar a versão mais recente no Changelog e, claro, o RemoteTerm é gratuito, sem anúncios e open source para sempre — dê uma estrela para ele no GitHub.