Pular para o conteúdo principal

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

Este tutorial aborda um fluxo de trabalho básico do firmware Meshtastic no Windows e macOS: clonar o repositório, compilar seeed_wio_tracker_L1, fazer uma pequena alteração na interface do usuário e gravar o resultado.

Se Git, Python e PlatformIO já estiverem instalados, você pode pular direto para a parte prática.

dica

Os comandos são fornecidos tanto para Windows quanto para macOS. A maioria das capturas de tela usa Windows, mas o fluxo de trabalho é o mesmo no macOS.

Pré‑requisitos​

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 configuração.

Durante a instalação, o passo mais importante é ajustar a variável de ambiente PATH. 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. Apenas continue 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 o Git manualmente às variáveis de ambiente do sistema.

Etapas de correção pela interface gráfica (GUI)

  1. Pressione Win
  2. Procure 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 deverá 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​

O PlatformIO baixa dependências automaticamente durante a instalação, portanto esta etapa pode levar algum tempo. Se ocorrerem erros, analise‑os um por um.

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

img

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

img

4. Clonar o repositório do firmware Meshtastic​

O repositório oficial do firmware 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 uma unidade diferente 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 prática​

Neste estágio, não tenha pressa em editar o código. Primeiro, verifique se o projeto consegue concluir todo o processo de compilação com sucesso.

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 exemplo de alvo.

img

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

Etapa 1: Confirmar que o projeto compila com sucesso

Aqui usamos a CLI do PlatformIO Core 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 costuma demorar um pouco, portanto tenha paciência.

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

Esta abordagem traz várias vantagens:

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

Depois que as dependências forem instaladas, execute:

pio run -e seeed_wio_tracker_L1 -v

img

Quando a instalação das dependências estiver concluída, execute novamente a compilação normal:

pio run -e seeed_wio_tracker_L1

img

Se a compilação for aprovada neste ponto, a saída do firmware foi gerada com sucesso.

img

Etapa 2: Modificar o código

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

Comece rastreando a implementação da tela 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, é possível 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 nem 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/

Aqui usamos um exemplo simples: adicionar um rótulo personalizado ao cabeçalho da tela inicial.

Atualize src/graphics/SharedUIDisplay.cpp com as seguintes alterações:

// 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

Essa atualização faz três coisas:

  • Registra a borda direita do texto da bateria.
  • Reserva espaço entre a área da bateria e os ícones do lado direito.
  • Desenha made by AE somente em SEEED_WIO_TRACKER_L1 quando o título está vazio.

Você pode encontrar o código completo aqui:

📎SharedUIDisplay.cpp

Etapa 3: Compilar o seu próprio firmware

Depois de concluir a modificação, volte para o diretório 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​

Após a conclusão da compilação, abra a página oficial de gravação:

Meshtastic Flasher

Na maioria dos casos, você deve realizar 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 solicitar que você instale 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

  • Primeiro, execute 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 se 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 faça o download de 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...