Primeros pasos con MeshCore Remote Terminal

Este wiki presentará Remote Terminal for MeshCore (RemoteTerm) para proporcionar una interfaz para que los dispositivos MeshCore transmitan mensajes. Este tutorial ofrece una configuración básica para ejecutar RemoteTerm en una Raspberry Pi usando el Seeed XIAO ESP32S3 & SX1262 Kit como radio complementaria y una Raspberry Pi Zero 2W para una solución MeshCore compacta y todo en uno para usuarios avanzados.

Introducción a RemoteTerm

RemoteTerm es una aplicación de código abierto que se ejecuta en un servidor con un dispositivo MeshCore conectado.

Proporciona una interfaz a la red MeshCore local, lo que permite que cualquier dispositivo en la misma red local (incluso si está fuera de la red eléctrica) envíe y reciba mensajes a través de la radio. RemoteTerm es extremadamente compatible con dispositivos móviles. Permite capacidades adicionales como:

• Almacenamiento en caché de todos los paquetes recibidos
• Ejecución de múltiples bots de Python
• Supervisión de contactos y canales ilimitados
• Acceso remoto a tu radio a través de tu red o VPN
• Reenvío de paquetes a MQTT, SQS, Apprise, etc.
• Visualizar el mapa de nodos de la malla

Configuración

Hardware

Kit XIAO ESP32S3 & Wio-SX1262	Raspberry Pi Zero 2W
Consigue uno ahora🖱️	Consigue uno ahora🖱️

Además del hardware principal, aquí están los accesorios necesarios:

• Tarjeta MicroSD de 16 GB o mayor
• Cable USB Micro a USB-C (para conectar la radio)
• USB Micro a USB-A o USB-C (para alimentar la Raspberry Pi)
• Fuente de alimentación fiable para la Raspberry Pi (se recomiendan 5V 2.5A)

Configuración de la radio

• Combina la placa XIAO ESP32S3 board de Seeed y el módulo SX1262 usando el acoplador B2B.
• Conecta la antena LoRa al SX1262.
• Conéctalo a tu ordenador y flashea con "Seeed Studio Xiao S3 WIO" (Serial Companion) mediante el web flasher.

tip

Este tutorial te indica cómo configurar un compañero serie. RemoteTerm también admite compañeros TCP y Bluetooth, pero son un poco más complicados de configurar.

Configuración de la Pi

• Haz clic aquí para descargar Raspberry Pi Imager
• Abre el imager y selecciona tu modelo de Raspberry Pi, y selecciona "Raspberry Pi OS Lite (64 bit)"
• Configura SSH con una contraseña, o clave si lo deseas, y configura la conexión wifi
• Conecta el ESP32 MeshCore a la Raspberry Pi

aviso

asegúrate de que el nodo ESP32 LoRa Mesh esté conectado al puerto USB, no al puerto POWER

Una instalación completa (con adaptador en ángulo recto) puede verse así:

• Conecta la alimentación al puerto POWER de la Pi
• Usa la interfaz de administración de tu router doméstico para determinar la dirección asignada a la Raspberry Pi. Considera asignar una reserva DHCP para evitar cambios de dirección IP.

Configuración de la Pi

• Abre una sesión SSH a la Raspberry Pi
• Valida que la radio aparezca. find /dev/serial/by-id -maxdepth 1 -type l -print | sort debería mostrar un listado como /dev/serial/by-id/usb-Espressif_USB_JTAG_serial_debug_unit_XX:XX:XX:XX:XX:XX-if00
• Actualiza y mejora el sistema

  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 y lanzar

  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

Recorrido por las opciones de configuración

El README y el blog proporcionan instrucciones de configuración más detalladas

Arranque del servidor

Configuración

Después de haber configurado tu dockerfile mediante el script de configuración, ejecuta

sudo docker compose up -d

para iniciar el servidor. Los siguientes comandos también pueden ser útiles:

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

aviso

RemoteTerm realiza una gestión completa de la radio, lo que significa que una vez que una radio está conectada a RemoteTerm, todos los contactos/canales se importarán y descargarán en RemoteTerm, y los contactos que realmente se sincronicen con el dispositivo estarán controlados por RemoteTerm.

nota

Configuración de hotspot (opcional)

Esto es opcional y se recomienda solo para radios que se utilizarán fuera de tu hogar. Esta configuración desconectará la radio de tu wifi doméstica pero hará que comience a emitir su propio wifi para que pueda ser accesible sin conexión a Internet.

• Configura un hotspot

  sudo nmcli device wifi hotspot ssid <hotspot name> password <hotspot password> ifname wlan0

• Probablemente tendrás que conectarte a la nueva red Wi‑Fi y hacer SSH en la Pi de nuevo. La URL de tu Pi será la "puerta de enlace predeterminada" en la configuración wifi de la nueva red cuando te conectes a ella.

• Configura el hotspot para que se emita al arrancar

  nmcli connection
  # grab the UUID of the Hotspot connection
  sudo nmcli connection modify <hotspot UUID> connection.autoconnect yes connection.autoconnect-priority 100

Primeros pasos con RemoteTerm

Pantalla principal

La pantalla principal de RemoteTerm muestra una lista de canales, repetidores y servidores de sala conocidos, con un espacio para Favoritos en la parte superior. Haz clic en cualquier contacto o canal para empezar a enviar mensajes, o haz clic en un repetidor para iniciar sesión y ver la interfaz de administración. Puedes añadir canales o contactos con el botón verde de la parte superior.

Encima de la lista de contactos hay un conjunto de herramientas:

Elemento general	Función
Packet Feed	Una visualización de los paquetes entrantes en bruto a medida que llegan
Node Map	Visualizar la ubicación de los nodos
Mesh Visualizer	Una representación 3D personalizable de los nodos y el tráfico en tiempo real
Trace	Ejecutar trazas de múltiples saltos entre repetidores para obtener información de intensidad de señal
Message Search	Buscar en el historial de canales y mensajes palabras o frases
Channel Finder	Channel finder encuentra nombres de canales para paquetes escuchados pero no descifrados

Mensajería (Canales)

Para crear o unirte a un canal, haz clic en el botón 'Add Channel/Contact” en la esquina superior izquierda del menú principal de la aplicación. Los canales privados, identificados solo por su clave, o los canales Hashtag, identificados por su nombre como un #hashtag, se pueden unir desde el menú que aparece.

El canal Public se añade automáticamente a todas las nuevas instancias de RemoteTerm. Es probable que tu malla local tenga su parte de canales activos: Public, #test o #testing, y #bots o #bot pueden ser buenos lugares para comenzar o encontrar personas que puedan indicarte buenas salas locales para recién llegados.

Cuando se selecciona un canal, la pantalla se verá algo así:

En la barra de estado:

Icono	Función
	Configura las notificaciones, ya sea como notificaciones de escritorio (que requieren que el navegador esté abierto) o Web Push (que pueden entregarse incluso cuando el navegador está cerrado). Estas requieren un contexto HTTPS de confianza (los certificados snakeoil disponibles desde el instalador pueden o no ser suficientes para permitir notificaciones, dependiendo de tu sistema operativo y navegador)
	Habilita anulaciones de enrutamiento regional, que limitan el alcance regional de la radio cuando envía mensajes solo en este canal. Los usuarios con configuraciones de región correspondientes o diferentes podrán ver o autoignorar tus mensajes, respectivamente
	Permite anulaciones de ancho de salto por canal separadas del valor predeterminado de tu radio
	Añade o elimina un canal de tus favoritos
	Elimina el canal, pero conserva los mensajes históricos si decides añadirlo de nuevo más tarde
Room Key	Proporciona la clave MeshCore para la sala dada

En la esquina superior izquierda está el nombre del canal con un icono de información; puedes hacer clic en él para ver información sobre el canal, como qué tan activo es, quién está enviando mensajes y su clave (que también puedes ver haciendo clic en el texto "Show key" en la barra de estado superior):

Mensajería (Mensajes Directos)

Enviar mensajes directos funciona de forma similar a los mensajes de canal, con algunas opciones diferentes.

Icono	Función
	Envía una sonda enrutada al contacto para descubrir una ruta de enrutamiento más ideal para que sigan los mensajes
	Envía un rastreo directo al contacto, con datos de SNR remotos y locales
	Configura las notificaciones, ya sea como notificaciones de escritorio (que requieren que el navegador esté abierto) o Web Push (que pueden entregarse incluso cuando el navegador está cerrado). Estas requieren un contexto HTTPS de confianza (los certificados snakeoil disponibles desde el instalador pueden o no ser suficientes para permitir notificaciones, dependiendo de tu sistema operativo y navegador)
	Añade o elimina un contacto de tus favoritos
	Elimina la conversación, pero conserva los mensajes históricos si decides añadirla de nuevo más tarde
Clave de contacto	Proporciona la clave MeshCore para el contacto dado e información sobre cuándo se le escuchó por última vez (anuncio, mensaje, etc.), y el método (directo, o qué ruta siguió el paquete)

De forma similar a los canales, puedes hacer clic en el icono de información o en el nombre en la barra superior de un contacto seleccionado para ver analíticas del contacto

MQTT y Automatización

RemoteTerm destaca al proporcionar integraciones ricas para sistemas automatizados. Las integraciones realizan acciones cuando se escuchan paquetes de ciertos tipos (por ejemplo, cuando se envía un mensaje en un canal o se recibe un MD). Estas incluyen:

• MQTT, reenviando paquetes sobre MQTT a:
  • Brokers privados
  • Agregadores comunitarios
  • Home Assistant
• Webhooks, enviando solicitudes GET o POST a una URL específica con datos del mensaje
• Apprise, una herramienta flexible de distribución de notificaciones que puede reenviar a Discord, Telegram, SMS, correo electrónico, etc.
• Encolar paquetes o mensajes en colas Amazon SQS
• Bots en Python

Configuración para Mapeo de Malla Comunitaria

Mostrar la ubicación de los nodos MeshCore, los patrones de flujo de mensajes y desgloses de conectividad, etc., puede ser útil para la comunidad al construir la red MeshCore. Para proporcionar esta vista de depuración, los agregadores comunitarios ingieren un flujo de paquetes sin procesar de observadores.

RemoteTerm facilita usar la misma radio que utilizas para enviar y recibir mensajes para contribuir a estos esfuerzos comunitarios de mapeo y visibilidad como un nodo observador.

aviso

MeshCore no permite que los mensajes entren en la malla a través de nodos MQTT; los esfuerzos de observabilidad comunitaria son de solo lectura.

Existen muchas plataformas comunitarias de observadores, pero LetsMesh es una de las más populares, y es la que configuraremos.

1. Haz clic aquí para visitar LetsMesh e iniciar sesión en el analizador LetsMesh.
2. En RemoteTerm, ve a "Settings" y luego haz clic en "MQTT & Automation".
3. Haz clic en "Add Integration" y elige "LetsMesh (US)" de la lista de la izquierda.

4. Haz clic en "Create".
5. Rellena el mismo correo electrónico que usaste para registrarte en LetsMesh e introduce el código IATA del aeropuerto más cercano
6. Haz clic en "Save as Enabled".

Deberías ver un punto verde y un estado "Connected"; una integración saludable debería verse así:

Si en su lugar ves un punto ámbar, haz clic en el símbolo "ⓘ" junto al botón Edit para ver el error.

Ahora, navega a este enlace. En unos 15 minutos, deberías ver tu radio aparecer en verde allí, ¡y tu propia telemetría y paquetes siendo reenviados a LetsMesh!

Bot

RemoteTerm proporciona una interfaz para programar tus propios bots. Los bots consisten en código Python sencillo que se ejecuta cada vez que se recibe un mensaje de un contacto o canal.

aviso

Los bots generan tráfico automatizado en respuesta a otros mensajes. Esto significa que es tu responsabilidad asegurarte de que los bots estén escritos cuidadosamente para evitar saturar la malla o crear bucles infinitos.

Configurar un Bot Sencillo de Lanzamiento de Dados

Aquí tienes un tutorial que te guía para crear un bot con capacidades sencillas de lanzamiento de dados, solicitado en forma estándar (por ejemplo, "3d6" significa lanzar 3 dados de seis caras). Estos son los pasos sencillos:

1. En RemoteTerm, ve a "Settings" y luego haz clic en "MQTT & Automation".
2. Haz clic en "Add Integration" y elige "Python Bot" de la lista de la izquierda.
3. Haz clic en "Create".
4. Ponle al bot un nombre descriptivo, como "Dice Bot".
5. Borra el código del editor y pega en su lugar el siguiente código:

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)}"

6. Haz clic en "Save as Enabled".

Usando otra radio, navega a la sala #bot y solicita una tirada de dados (por ejemplo, "3d6"). La salida debería verse algo así:

Si no ves la respuesta como esperas, puedes revisar los registros del servidor desde tu contenedor Docker para ver si se informa de algún error cuando se ejecuta el código Python.

Configurar un Bot de Ancho de Ruta

El firmware MeshCore v1.14+ trajo grandes cambios en cómo los mensajes atraviesan la malla; los paquetes que atraviesan routers compatibles ahora pueden llevar identificadores de salto multibyte.

Podemos crear un bot para ayudar a las personas a determinar si una ruta multibyte está asociada con su mensaje. Este script utiliza la capacidad de enviar múltiples mensajes en respuesta proporcionando un mensaje de ancho de salto y los propios datos de saltos del paquete.

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 ''}"]

Reenviar Mensajes de Canal MeshCore a Discord

Apprise es un servicio de notificaciones flexible compatible con RemoteTerm. Apprise te permite elegir uno o varios de cientos de servicios de notificación a los que enviar mensajes de canal o directos, desde Discord hasta Telegram, SMS, correo electrónico y mucho más.

Como ejemplo, usaremos Apprise para reenviar todos los mensajes en un canal MeshCore concreto a Discord a través de RemoteTerm.

1. Abre Discord en un canal en el que tengas privilegios de administrador.
2. Haz clic derecho en el nombre del canal y haz clic en "Edit Channel".
3. Haz clic en "Integrations" en el menú de la izquierda y luego haz clic en "Create Webhook".
4. Nombra el webhook de forma adecuada y copia la URL del webhook. El webhook debería tener la forma https://discord.com/api/webhooks/<WebhookID>/<WebhookToken>

5. En RemoteTerm, ve a "Settings" y luego haz clic en "MQTT & Automation".
6. Haz clic en "Add Integration" y elige "Apprise" de la lista de la izquierda.
7. Haz clic en "Create".
8. Añade una URL de notificación en la entrada. Según la documentación de Discord de Apprise, esta debe tener la forma discord://{WebhookID}/{WebhookToken}/. Usa el WebhookID y el WebhookToken de la URL copiada.
9. Elige si deseas preservar la identidad del usuario utilizando su nombre y avatar configurados cuando estén disponibles.
10. Elige si deseas incluir los datos de la ruta de enrutamiento en el mensaje (se sugiere deshabilitarlo)
11. Selecciona los contactos/canales que te gustaría reenviar a Discord y haz clic en "Save as Enabled".

Una vez habilitado, ¡deberías empezar a ver fluir los mensajes! Si tienes problemas o no ves los mensajes que esperas, revisa los registros del servidor para ver si hay errores reportados, o intenta habilitar todos los canales para asegurarte de que al menos el enlace RemoteTerm ↔ Discord esté funcionando.

Integra RemoteTerm con Home Assistant

Home Assistant proporciona un marco para una automatización del hogar potente y fácil de usar. RemoteTerm ofrece integración con Home Assistant mediante la integración MQTT incorporada. Con esta integración, puedes activar automatizaciones basadas en mensajes, monitorizar repetidores y telemetría de radio local, y rastrear contactos mediante GPS en sus anuncios.

Para aprovechar el seguimiento de telemetría de repetidores, deberás inscribir los repetidores deseados en la obtención automática de telemetría. Una vez inscritos, RemoteTerm solicitará telemetría a un intervalo configurable, conservando valores históricos y haciendo visibles los valores actualizados en Home Assistant.

tip

La obtención automática de telemetría de repetidores tiene un intervalo personalizable; puedes elegir una frecuencia que vaya desde una vez por hora hasta una vez al día, con la restricción de que las obtenciones automáticas no pueden exceder 24 en un período de 24 horas.

Una vez que hayas configurado tus repetidores rastreados como desees y MQTT Discovery esté habilitado en Home Assistant, puedes configurar una integración en RemoteTerm para iniciar el flujo de datos.

1. En RemoteTerm, ve a "Settings" y luego haz clic en "MQTT & Automation".
2. Haz clic en "Add Integration" y elige "Home Assistant MQTT Discovery" de la lista de la izquierda.
3. Haz clic en "Create".
4. Introduce la información de tu broker MQTT, incluyendo host y puerto, y configuración de nombre de usuario/contraseña/TLS, si corresponde.
5. Elige los contactos que se rastrearán mediante la ubicación GPS de anuncios en Home Assistant.
6. Selecciona los repetidores con telemetría rastreada que deseas ver en Home Assistant.
7. Elige el alcance de los mensajes para los disparadores dentro de Home Assistant.
8. Haz clic en "Save as Enabled".

Ten en cuenta que la pantalla de configuración de integración de RemoteTerm proporciona los temas/entidades creados exactamente en los menús desplegables "What gets created in Home Assistant" y "Published Topic Summary".

aviso

Los contactos y repetidores rastreados crearán entidades en Home Assistant; es posible que desees limitar tu selección solo a los contactos que te interesan para evitar saturar Home Assistant.

Los eventos de mensajes no crean entidades y solo se utilizan para disparadores; en general, no hay problema en permitir que todos los mensajes fluyan hacia Home Assistant.

Para ver las nuevas entidades, inicia sesión en la interfaz web de Home Assistant. Haz clic en Settings, luego en Devices & Services y luego en MQTT. Deberías ver tus entidades rastreadas mostradas.

Haz clic en ellas para ver sus métricas disponibles. Para los repetidores, se mostrarán las métricas no obsoletas más recientes disponibles; si solo has habilitado recientemente la obtención automática de telemetría, es posible que debas esperar hasta ocho horas para que todos los campos de telemetría de repetidores y radios se completen dentro de Home Assistant.

Para obtener orientación adicional sobre la configuración, revisa README_HA.md en el repositorio de RemoteTerm. Por ejemplo, seguir las instrucciones en "Full monitoring dashboard with message feed" proporcionará un panel como este:

Próximos pasos

Mantente al día con el desarrollo de RemoteTerm o haz preguntas uniéndote al Discord oficial de MeshCore y luego siguiendo el hilo de desarrollo de RemoteTerm. La base de código se actualiza con frecuencia y puedes encontrar la última versión en el Changelog y, por supuesto, RemoteTerm es gratuito, sin anuncios y de código abierto para siempre: dale una estrella en GitHub.