Saltar al contenido principal

Tutorial práctico del código fuente del firmware de Meshtastic

Este tutorial cubre un flujo de trabajo básico del firmware Meshtastic en Windows y macOS: clonar el repositorio, compilar seeed_wio_tracker_L1, hacer un pequeño cambio en la interfaz de usuario y flashear el resultado.

Si Git, Python y PlatformIO ya están instalados, puedes pasar directamente a la sección práctica.

tip

Se proporcionan comandos tanto para Windows como para macOS. La mayoría de las capturas de pantalla usan Windows, pero el flujo de trabajo es el mismo en macOS.

Requisitos previos​

Prepara las siguientes herramientas:

  1. Git
  2. Python 3
  3. VS Code
  4. PlatformIO

1. Instalar Git​

Abre la página oficial de descarga de Git para Windows:

Git para Windows

El instalador normalmente comienza a descargarse automáticamente cuando abres la página. Una vez completada la descarga, haz doble clic en el instalador y sigue el asistente de configuración.

Durante la instalación, el paso más importante es Adjusting your PATH environment. Elige:

Git from the command line and also from 3rd-party software

Para las demás opciones, los valores predeterminados suelen estar bien. Simplemente sigue haciendo clic en Next.

img

Espera hasta que finalice la instalación.

Después de la instalación, cierra todas las ventanas actuales de PowerShell y de terminal de VS Code, luego abre una nueva ventana de PowerShell y ejecuta:

& "C:\Program Files\Git\cmd\git.exe" --version

img

Si se muestra un número de versión de Git, Git se ha instalado correctamente.

Si el comando git sigue sin estar disponible

Primero puedes ejecutar los siguientes comandos en PowerShell para confirmar las rutas de instalación predeterminadas de Git:

$gitCmd = "C:\Program Files\Git\cmd"
$gitBin = "C:\Program Files\Git\bin"
Write-Host $gitCmd
Write-Host $gitBin

img

Luego agrega manualmente Git a las variables de entorno del sistema.

Pasos de corrección mediante la GUI

  1. Pulsa Win
  2. Busca "Edit the system environment variables"
  3. Ábrelo y haz clic en Environment Variables
  4. Busca Path bajo System variables
  5. Haz clic en Edit
  6. Haz clic en New y añade las dos rutas siguientes:
C:\Program Files\Git\cmd
C:\Program Files\Git\bin
  1. Haz clic en OK en todas las ventanas para guardar

img

Después de guardar, aún necesitas:

  • Cerrar todas las ventanas de PowerShell
  • Abrir PowerShell de nuevo

Luego ejecuta:

git --version

img

Si aparece un número de versión, la instalación está completa.

Configura tu identidad de Git

A continuación, configura tu información de usuario de Git. Sustituye los valores de ejemplo por tu propio nombre y dirección de correo electrónico:

git config --global user.name "your name"
git config --global user.email "your [email protected]"

Luego ejecuta:

git config --global --list

para confirmar que la configuración ha surtido efecto.

2. Instalar Python 3​

Instalar Python desde la línea de comandos

Ejecuta los siguientes comandos en la terminal:

winget search --id Python.Python.3.13 --source winget
winget install -e --id Python.Python.3.13 --source winget

Si el primer comando puede encontrar Python, el segundo normalmente debería instalarlo directamente.

Después de la instalación, cierra la terminal y ábrela de nuevo, luego ejecuta:

python --version
pip --version

img

Si se muestran números de versión, Python y pip están listos para usarse.

3. Instalar PlatformIO​

PlatformIO descarga dependencias automáticamente durante la instalación, por lo que este paso puede llevar algo de tiempo. Si se producen errores, revísalos uno por uno.

Busca PlatformIO en el marketplace de Extensiones de VS Code e instálalo.

img

Después de la instalación, suele aparecer un icono con forma de hormiga en la barra de herramientas de la izquierda.

img

4. Clonar el repositorio de firmware de Meshtastic​

El repositorio oficial del firmware de Meshtastic es meshtastic/firmware.

Ejecuta los siguientes comandos en la terminal de tu directorio de trabajo:

git clone https://github.com/meshtastic/firmware.git
cd firmware
git submodule update --init

Si tu directorio de proyecto está en otra unidad o bajo una ruta diferente, cambia primero a esa ubicación.

img

img

Si la salida se parece a las capturas de pantalla anteriores, el repositorio se ha clonado correctamente.

5. Práctica práctica​

En esta etapa, no te apresures a editar el código. Primero, asegúrate de que el proyecto pueda ejecutar correctamente todo el proceso de compilación.

Se recomienda comenzar con tres tareas:

  1. Abrir firmware
  2. Comprobar platformio.ini
  3. Encontrar el entorno de compilación para tu placa de destino

Un detalle importante: no te centres solo en el platformio.ini raíz. En realidad incluye archivos de configuración adicionales, por ejemplo:

extra_configs =
    variants/*/*.ini
    variants/*/*/platformio.ini
    variants/*/diy/*/platformio.ini

Esto significa que las definiciones reales de entornos a nivel de placa suelen estar ubicadas bajo variants/.../platformio.ini.

Al identificar la placa de destino, presta especial atención a estos dos directorios:

  • variants/
  • boards/

Aquí usamos Wio Tracker L1 Pro como la placa de destino de ejemplo.

img

Esto muestra que, en Meshtastic, el objetivo de compilación para Wio Tracker L1 / L1 Pro es seeed_wio_tracker_L1.

Paso 1: Confirmar que el proyecto compila correctamente

Aquí usamos la CLI de PlatformIO Core para compilar.

img

Para la primera compilación, se recomienda ejecutar el siguiente comando:

cd D:\workplace\firmware  # Adjust to your actual project path
pio run -e seeed_wio_tracker_L1

img

Si la interfaz se ve similar a la captura de pantalla anterior, el proceso de compilación se ha iniciado correctamente. La primera compilación suele tardar un rato, así que ten paciencia.

Si la compilación falla

Cuando una compilación falla, primero puedes pedirle a PlatformIO que instale las dependencias requeridas por el entorno actual:

cd D:\workplace\firmware  # Adjust to your actual project path
pio pkg install -e seeed_wio_tracker_L1

Este enfoque tiene varias ventajas:

  • Instala solo las dependencias, sin iniciar inmediatamente una compilación completa.
  • Facilita ver qué paquete está causando el problema.
  • Los mensajes de error suelen ser más concretos y fáciles de depurar.

Después de instalar las dependencias, ejecuta:

pio run -e seeed_wio_tracker_L1 -v

img

Una vez completada la instalación de dependencias, vuelve a ejecutar la compilación normal:

pio run -e seeed_wio_tracker_L1

img

Si la compilación se completa en este punto, tu firmware se habrá generado correctamente.

img

Paso 2: Modificar el código

Práctica 1: Modificar la visualización de la interfaz

Empieza siguiendo la implementación de la pantalla desde la configuración a nivel de placa. Primero puedes comprobar:

  • variants/nrf52840/seeed_wio_tracker_L1/platformio.ini
  • variants/nrf52840/seeed_wio_tracker_L1/variant.h

img

A partir de estos archivos de configuración, puedes ver que L1 define HAS_SCREEN y USE_SSD1306. Eso significa que utiliza la canalización estándar de pantalla OLED, no una configuración sin pantalla y no una solución de tinta electrónica.

Si sigues rastreando la lógica de la pantalla, la mayor parte del código relacionado se encuentra en:

  • src/graphics/
  • src/graphics/draw/

Aquí usamos un ejemplo sencillo: añadir una etiqueta personalizada al encabezado de la pantalla de inicio.

Actualiza src/graphics/SharedUIDisplay.cpp con los siguientes cambios:

// Track the end of the battery text
int batteryX = 1;
int batteryY = HEADER_OFFSET_Y + 1;
int batteryTextEndX = batteryX - 1;

// Update the boundary while drawing the battery percentage
if (chargePercent != 101) {
    char chargeStr[4];
    snprintf(chargeStr, sizeof(chargeStr), "%d", chargePercent);
    int chargeNumWidth = display->getStringWidth(chargeStr);
    int percentWidth = display->getStringWidth("%");
    display->drawString(batteryX, textY, chargeStr);
    display->drawString(batteryX + chargeNumWidth - 1, textY, "%");
    if (isBold) {
        display->drawString(batteryX + 1, textY, chargeStr);
        display->drawString(batteryX + chargeNumWidth, textY, "%");
    }
    batteryTextEndX = batteryX + chargeNumWidth + percentWidth - 1 + (isBold ? 1 : 0);
} else {
    batteryTextEndX = batteryX - 1;
}

// In the branch that displays time
int iconRightEdge = timeX - 2;
int headerLabelRight = timeX - 4;

#if defined(SEEED_WIO_TRACKER_L1) && !defined(SEEED_WIO_TRACKER_L1_EINK)
if (titleStr && titleStr[0] == '\0') {
    static const char *yclLabel = "made by AE";
    int labelWidth = display->getStringWidth(yclLabel);
    int labelLeft = batteryTextEndX + 4;
    if (labelLeft + labelWidth <= headerLabelRight) {
        int labelX = labelLeft + ((headerLabelRight - labelLeft) - labelWidth) / 2;
        display->drawString(labelX, textY, yclLabel);
        if (isBold)
            display->drawString(labelX + 1, textY, yclLabel);
    }
}
#endif

// In the branch that does not display time
int iconRightEdge = screenW - xOffset;
int headerLabelRight = screenW - xOffset - 2;

#if defined(SEEED_WIO_TRACKER_L1) && !defined(SEEED_WIO_TRACKER_L1_EINK)
if (titleStr && titleStr[0] == '\0') {
    static const char *yclLabel = "made by AE";
    int labelWidth = display->getStringWidth(yclLabel);
    int labelLeft = batteryTextEndX + 4;
    if (labelLeft + labelWidth <= headerLabelRight) {
        int labelX = labelLeft + ((headerLabelRight - labelLeft) - labelWidth) / 2;
        display->drawString(labelX, textY, yclLabel);
        if (isBold)
            display->drawString(labelX + 1, textY, yclLabel);
    }
}
#endif

Esta actualización hace tres cosas:

  • Registra el borde derecho del texto de la batería.
  • Reserva espacio entre el área de la batería y los iconos del lado derecho.
  • Dibuja made by AE solo en SEEED_WIO_TRACKER_L1 cuando el título está vacío.

Puedes encontrar el código completo aquí:

📎SharedUIDisplay.cpp

Paso 3: Compila tu propio firmware

Después de terminar la modificación, vuelve a la raíz del proyecto y compila de nuevo el mismo objetivo:

cd D:\workplace\firmware  # Adjust to your actual project path
pio run -e seeed_wio_tracker_L1

La lógica de la pantalla ha cambiado, pero el objetivo de compilación sigue siendo el mismo:

seeed_wio_tracker_L1

Después de una compilación exitosa, la salida suele encontrarse en:

D:\workplace\firmware\.pio\build\seeed_wio_tracker_L1\

El archivo que debes confirmar que se ha actualizado es:

firmware-seeed_wio_tracker_L1-*.uf2

6. Flashear el firmware​

Después de que la compilación haya finalizado, abre la página oficial de flasheo:

Meshtastic Flasher

En la mayoría de los casos, primero deberías realizar una operación de borrado.

img

Luego selecciona el archivo de firmware que acabas de compilar y flashea el dispositivo.

img

img

En este punto, el ejercicio práctico del código fuente de Meshtastic ha finalizado. Has pasado por todo el flujo de trabajo: configuración del entorno, clonación del repositorio, descubrimiento de la configuración de la placa, compilación del firmware, modificación de la lógica de visualización y verificación final del flasheo.

Si quieres ir más lejos, puedes seguir explorando estas direcciones:

  1. Modificar más elementos en la pantalla de inicio
  2. Ajustar el comportamiento de los botones, el GPS, Bluetooth y otros módulos
  3. Añadir un variant independiente para tu propia placa
  4. Seguir rastreando las relaciones entre src/, variants/ y boards/

Problemas comunes​

El comando git no está disponible

  • En Windows, primero comprueba si Git se ha añadido a PATH.
  • En macOS, ejecuta primero git --version. Si el sistema te pide que instales las Command Line Tools, sigue las indicaciones.

python3 o pip3 no están disponibles

  • En Windows, confirma que Python se añadió a PATH, o vuelve a abrir la terminal e inténtalo de nuevo.
  • En macOS, primero comprueba si python3 / pip3 ya existen, e instala Python con Homebrew solo si es necesario.

El comando pio no está disponible

  • Primero ejecuta pio --version.
  • Si el comando sigue sin estar disponible, reinicia VS Code y la terminal, y luego inténtalo de nuevo.
  • Si es necesario, vuelve a instalar la extensión PlatformIO y confirma que PlatformIO Core se haya inicializado correctamente.

El código sigue pareciendo incompleto después de git submodule update --init

  • Primero asegúrate de estar en el directorio raíz del repositorio firmware.
  • Si la conexión de red es inestable, inténtalo de nuevo con:
git submodule update --init --recursive

La primera compilación tarda demasiado

  • Es normal que la primera compilación descargue muchas dependencias.
  • Si parece quedarse atascada demasiado tiempo, intenta instalar primero los paquetes por separado:
pio pkg install -e seeed_wio_tracker_L1

Luego ejecuta la compilación de nuevo.

Loading Comments...