Pular para o conteúdo principal

Tutorial Prático do Código-Fonte do Firmware Meshtastic

Este tutorial é destinado a usuários que estão começando a trabalhar com o código-fonte do firmware Meshtastic. Ele inclui fluxos de trabalho comuns tanto para Windows quanto para macOS. O objetivo é direto: clonar o repositório oficial, concluir uma compilação bem-sucedida, fazer uma alteração simples na interface do usuário e gravar o firmware modificado no dispositivo para verificação.

Se você já está familiarizado com Git, Python ou PlatformIO, pode pular as seções correspondentes e ir diretamente para a parte prática.

dica

Este guia inclui comandos comuns para Windows e macOS. A maioria das capturas de tela ainda é feita em um ambiente Windows, mas o fluxo de trabalho geral no macOS é muito semelhante.

Pré-requisitos​

Antes de começar, prepare as seguintes ferramentas:

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

1. Instalar o Git​

Abra a página oficial de download do Git para Windows:

Git for Windows

O instalador geralmente começa a ser baixado automaticamente quando você abre a página. Após a conclusão do download, clique duas vezes no instalador e siga o assistente de instalação.

Durante a instalação, a etapa mais importante é Adjusting your PATH environment. Escolha:

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

Para as outras opções, os valores padrão geralmente são suficientes. Basta continuar clicando em Next.

img

Aguarde até que a instalação termine.

Após a instalação, feche todas as janelas atuais do PowerShell e terminais do VS Code, depois abra uma nova janela do PowerShell e execute:

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

img

Se um número de versão do Git for exibido, o Git foi instalado com sucesso.

Se o comando git ainda não estiver disponível

Você pode primeiro executar os seguintes comandos no PowerShell para confirmar os caminhos padrão de instalação do Git:

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

img

Em seguida, adicione manualmente o Git às variáveis de ambiente do sistema.

Etapas de correção via GUI

  1. Pressione Win
  2. Pesquise por "Edit the system environment variables"
  3. Abra e clique em Environment Variables
  4. Encontre Path em System variables
  5. Clique em Edit
  6. Clique em New e adicione os dois caminhos a seguir:
C:\Program Files\Git\cmd
C:\Program Files\Git\bin
  1. Clique em OK em todas as janelas para salvar

img

Depois de salvar, você ainda precisa:

  • Fechar todas as janelas do PowerShell
  • Abrir o PowerShell novamente

Depois execute:

git --version

img

Se um número de versão aparecer, a instalação está concluída.

Configure sua identidade do Git

Em seguida, configure suas informações de usuário do Git. Substitua os valores de exemplo pelo seu próprio nome e endereço de e-mail:

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

Depois execute:

git config --global --list

para confirmar que a configuração entrou em vigor.

2. Instalar o Python 3​

Instalar o Python pela linha de comando

Execute os seguintes comandos no terminal:

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

Se o primeiro comando conseguir encontrar o Python, o segundo normalmente deve instalá-lo diretamente.

Após a instalação, feche o terminal e abra-o novamente, depois execute:

python --version
pip --version

img

Se forem exibidos números de versão, o Python e o pip estão prontos para uso.

3. Instalar o PlatformIO​

Esta etapa pode parecer menos amigável para iniciantes porque o PlatformIO baixa muitas dependências automaticamente, e a instalação pode levar algum tempo. Se aparecerem erros durante a instalação, geralmente é melhor esperar com paciência e resolver um problema de cada vez. Usar ferramentas de IA para ajudar a inspecionar as mensagens de erro também pode economizar tempo.

Pesquise por PlatformIO no marketplace de Extensões do VS Code e instale-o.

img

Após a instalação, normalmente aparece um ícone em forma de formiga na barra de ferramentas à esquerda.

img

4. Clonar o repositório de firmware do Meshtastic​

O repositório oficial de firmware do Meshtastic é meshtastic/firmware.

Execute os seguintes comandos no terminal do seu diretório de trabalho:

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

Se o diretório do seu projeto estiver em outra unidade ou em um caminho diferente, mude para esse local primeiro.

img

img

Se a saída for semelhante às capturas de tela acima, o repositório foi clonado com sucesso.

5. Prática hands-on​

Neste estágio, não tenha pressa em editar o código. Primeiro, certifique-se de que o projeto consegue passar com sucesso por todo o processo de compilação.

Recomenda-se começar com três tarefas:

  1. Abrir firmware
  2. Verificar platformio.ini
  3. Encontrar o ambiente de compilação para sua placa-alvo

Um detalhe importante: não foque apenas no platformio.ini da raiz. Ele na verdade inclui arquivos de configuração adicionais, por exemplo:

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

Isso significa que as definições reais de ambiente em nível de placa geralmente estão localizadas em variants/.../platformio.ini.

Ao identificar a placa-alvo, preste atenção especial a estes dois diretórios:

  • variants/
  • boards/

Aqui usamos Wio Tracker L1 Pro como placa-alvo de exemplo.

img

Isso mostra que, no Meshtastic, o alvo de compilação para Wio Tracker L1 / L1 Pro é seeed_wio_tracker_L1.

Resumo da modificação mínima

Se você só quiser concluir uma prática mínima de ponta a ponta, concentre-se nestas etapas principais:

  1. Instalar Git, Python 3, VS Code e PlatformIO.
  2. Clonar o repositório meshtastic/firmware e inicializar os submódulos.
  3. Usar pio run -e seeed_wio_tracker_L1 para confirmar que o projeto original compila com sucesso.
  4. Modificar a lógica de exibição em src/graphics/SharedUIDisplay.cpp.
  5. Recompilar o firmware e gravar o arquivo UF2 gerado no dispositivo para verificação.

Etapa 1: Confirmar que o projeto compila com sucesso

Aqui usamos o PlatformIO Core CLI para compilar.

img

Para a primeira compilação, recomenda-se executar o seguinte comando:

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

img

Se a interface estiver semelhante à captura de tela acima, o processo de compilação foi iniciado corretamente. A primeira compilação geralmente leva um tempo, portanto seja paciente.

Se a compilação falhar

Quando uma compilação falhar, você pode primeiro pedir ao PlatformIO para instalar as dependências exigidas pelo ambiente atual:

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

Essa abordagem tem vários benefícios:

  • Ela instala apenas as dependências, sem iniciar imediatamente uma compilação completa.
  • Ela facilita ver qual pacote está causando o problema.
  • As mensagens de erro geralmente são mais focadas e fáceis de depurar.

Depois que as dependências forem instaladas, execute:

pio run -e seeed_wio_tracker_L1 -v

img

Quando a instalação das dependências terminar, execute novamente a compilação normal:

pio run -e seeed_wio_tracker_L1

img

Se a compilação passar neste ponto, o firmware de saída foi gerado com sucesso.

img

Etapa 2: Modificar o código

Prática 1: Modificar a interface de exibição (UI)

Comece rastreando a implementação da exibição a partir da configuração em nível de placa. Você pode primeiro verificar:

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

img

A partir desses arquivos de configuração, você pode ver que o L1 define HAS_SCREEN e USE_SSD1306. Isso significa que ele usa o pipeline padrão de exibição OLED, não uma configuração sem tela e não uma solução de E-Ink.

Se você continuar rastreando a lógica de exibição, a maior parte do código relacionado está localizada em:

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

Exatamente como você o modifica depende da sua capacidade de ler o código-fonte. Aqui começamos com um exemplo bem simples: modificar a interface da tela inicial.

Alteração 1: Registrar a borda direita do texto da bateria

Before / After

// Before
int batteryX = 1;
int batteryY = HEADER_OFFSET_Y + 1;

// After
int batteryX = 1;
int batteryY = HEADER_OFFSET_Y + 1;
int batteryTextEndX = batteryX - 1;

src/graphics/SharedUIDisplay.cpp:157

Isso adiciona batteryTextEndX, que registra a posição final do texto de porcentagem da bateria. Isso facilita anexar texto personalizado após as informações da bateria mais tarde.

Alteração 2: Calcular o limite direito ao desenhar a porcentagem da bateria

// Before
if (chargePercent != 101) {
    char chargeStr[4];
    snprintf(chargeStr, sizeof(chargeStr), "%d", chargePercent);
    int chargeNumWidth = display->getStringWidth(chargeStr);
    display->drawString(batteryX, textY, chargeStr);
    display->drawString(batteryX + chargeNumWidth - 1, textY, "%");
    if (isBold) {
        display->drawString(batteryX + 1, textY, chargeStr);
        display->drawString(batteryX + chargeNumWidth, textY, "%");
    }
}

// After
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;
}

src/graphics/SharedUIDisplay.cpp:204

Esse código fica dentro da lógica de desenho da porcentagem da bateria. Além de exibir o nível da bateria normalmente, ele também calcula o limite direito da área de texto para que rótulos personalizados possam ser colocados após as informações da bateria.

Alteração 3: Reservar um limite para a área de ícones à direita

// Before
int iconRightEdge = timeX - 2;

// After
int iconRightEdge = timeX - 2;
int headerLabelRight = timeX - 4;

src/graphics/SharedUIDisplay.cpp:263

Esta parte lida com a área usada pelos ícones de hora, e-mail, mudo e outros ícones no lado direito. Eu adicionei headerLabelRight para limitar o limite máximo à direita do texto central e evitar sobreposição com o conteúdo do lado direito.

Alteração 4: Desenhar um rótulo personalizado quando o título estiver vazio

// Newly added core logic
#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

src/graphics/SharedUIDisplay.cpp:350

Esta é a lógica central da modificação. Ela se aplica apenas a SEEED_WIO_TRACKER_L1 e exclui explicitamente a variante de E-Ink. Ela centraliza o texto made by AE no espaço em branco entre as informações da bateria e a exibição da hora.

Alteração 5: Tratar o ramo em que nenhuma hora é exibida

// Add the same boundary control for the no-time branch
int iconRightEdge = screenW - xOffset;
int headerLabelRight = screenW - xOffset - 2;

src/graphics/SharedUIDisplay.cpp:377

Este é o ramo usado quando nenhum valor de hora é exibido. O mesmo controle de limite precisa ser adicionado aqui também.

#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

src/graphics/SharedUIDisplay.cpp:426

Esta é a implementação para desenhar made by AE no ramo sem hora.

Você pode encontrar o código completo aqui:

📎SharedUIDisplay.cpp

Etapa 3: Compilar o seu próprio firmware

Depois de terminar a modificação, volte para a raiz do projeto e compile o mesmo alvo novamente:

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

A lógica de exibição foi alterada, mas o alvo de compilação ainda é o mesmo:

seeed_wio_tracker_L1

Após uma compilação bem-sucedida, a saída geralmente fica localizada em:

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

O arquivo que você deve confirmar que foi atualizado é:

firmware-seeed_wio_tracker_L1-*.uf2

6. Gravar o firmware​

Depois que a compilação estiver concluída, abra a página oficial de gravação:

Meshtastic Flasher

Na maioria dos casos, você deve executar primeiro uma operação de apagamento.

img

Em seguida, selecione o arquivo de firmware que você acabou de compilar e grave-o no dispositivo.

img

img

Neste ponto, o exercício prático com o código-fonte do Meshtastic está concluído. Você passou por todo o fluxo de trabalho: configuração do ambiente, clonagem do repositório, descoberta da configuração da placa, compilação do firmware, modificação da lógica de exibição e verificação final da gravação.

Se quiser ir além, você pode continuar explorando estas direções:

  1. Modificar mais elementos na tela inicial
  2. Ajustar o comportamento dos botões, GPS, Bluetooth e outros módulos
  3. Adicionar um variant independente para a sua própria placa
  4. Continuar rastreando as relações entre src/, variants/ e boards/

Problemas comuns​

O comando git não está disponível

  • No Windows, primeiro verifique se o Git foi adicionado ao PATH.
  • No macOS, execute primeiro git --version. Se o sistema pedir para instalar as Command Line Tools, siga a instrução.

python3 ou pip3 não está disponível

  • No Windows, confirme se o Python foi adicionado ao PATH ou reabra o terminal e tente novamente.
  • No macOS, primeiro verifique se python3 / pip3 já existem e instale o Python com o Homebrew somente se necessário.

O comando pio não está disponível

  • Execute primeiro pio --version.
  • Se o comando ainda não estiver disponível, reinicie o VS Code e o terminal e tente novamente.
  • Se necessário, reinstale a extensão PlatformIO e confirme que o PlatformIO Core foi inicializado corretamente.

O código ainda parece incompleto após git submodule update --init

  • Primeiro, certifique-se de que você está no diretório raiz do repositório firmware.
  • Se a conexão de rede estiver instável, tente novamente com:
git submodule update --init --recursive

A primeira compilação leva muito tempo

  • É normal que a primeira compilação baixe muitas dependências.
  • Se parecer travado por muito tempo, tente instalar os pacotes separadamente primeiro:
pio pkg install -e seeed_wio_tracker_L1

Em seguida, execute a compilação novamente.

Loading Comments...