Guia Definitivo: Como Instalar o Zephyr RTOS Manualmente no Windows (Focado em STM32)

O Zephyr RTOS é um dos sistemas operacionais de tempo real mais robustos e modernos para sistemas embarcados. No entanto, sua instalação no Windows pode parecer intimidadora devido à quantidade de dependências.

Neste tutorial, vamos realizar a instalação manual e cirúrgica do ambiente, focando na arquitetura ARM (especificamente para microcontroladores STM32), garantindo um ecossistema limpo, otimizado e sem poluição de variáveis de ambiente globais.

1. Instalando o Chocolatey

O caminho mais limpo e automatizado para gerenciar ferramentas de compilação no Windows é utilizando o gerenciador de pacotes Chocolatey.

• Clique com o botão direito no menu Iniciar do Windows e selecione Terminal (Administrador) ou PowerShell (Administrador).
• Execute o comando abaixo para instalar o Chocolatey:

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))

• Feche o terminal e abra-o novamente (como Administrador) para garantir que o comando choco esteja ativo no seu sistema.

2. Instalando as Dependências de Compilação

Com o Chocolatey pronto, instale todas as ferramentas de compilação necessárias de uma só vez:

choco install -y cmake ninja gperf python git dtc-msys2 wget 7zip

💡 Nota: O pacote dtc-msys2 instala o Device Tree Compiler, fundamental para que o Zephyr consiga analisar a árvore de hardware e os arquivos de mapeamento de pinos do microcontrolador.

3. Instalando o West e Inicializando o Workspace

O west é a ferramenta de meta-gerenciamento que orquestra todo o ecossistema do Zephyr. Vamos instalá-lo via Python e criar a estrutura do nosso projeto.

pip3 install --user -U west

No Windows, o Python costuma instalar o executável do west dentro do diretório de scripts do usuário local. Para que o terminal reconheça o comando globalmente, precisamos adicionar esse caminho à variável de ambiente Path do usuário.

No PowerShell, você pode fazer isso de forma permanente executando o comando abaixo:

$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
$westPath = "$env:USERPROFILE\AppData\Roaming\Python\Python313\Scripts" # Verifique sua versão exata do Python (ex: Python313)
[Environment]::SetEnvironmentVariable("Path", $userPath + ";" + $westPath, "User")

⚠️ Atenção: Navegue até C:\Users\SeuUsuario\AppData\Roaming\Python\ e certifique-se do número exato da pasta da sua versão do Python antes de rodar o script acima.

Feche o terminal e abra-o novamente (agora você pode usar o Terminal normal de usuário, sem privilégios de administrador).

Navegue até a pasta onde deseja concentrar seus projetos e inicialize o Workspace dentro do diretório dedicado à STM:

cd ~
mkdir ZephyrRTOS
cd ZephyrRTOS
west init STM
cd STM

Como o foco é o desenvolvimento para microcontroladores ARM da STMicroelectronics, vamos habilitar especificamente a camada de abstração de hardware da ST (hal_st) e as dependências de arquitetura (cmsis), otimizando o tempo de download do repositório:

west config manifest.group-filter -- "+hal_st,+cmsis"
west update --narrow --fetch-opt=--depth=1

4. Instalando o Toolchain STM32 (Zephyr SDK)

Agora precisamos do compilador cruzado que transformará o código C em um binário compatível com o núcleo ARM Cortex-M. Em vez de baixar o SDK completo (que pesa gigabytes e traz compiladores para dezenas de arquiteturas), faremos uma instalação cirúrgica utilizando o pacote Minimal.

Acesse a página de Releases do Zephyr SDK e localize a versão estável mais recente.

A partir da pasta STM no terminal, volte um nível, crie a pasta toolchain e acesse-a:

cd ../
mkdir toolchain
cd toolchain

Execute a sequência de comandos abaixo para baixar, extrair o SDK Minimal e adicionar apenas o suporte ao ARM:

# 1. Baixe o SDK Minimal para Windows (Substitua a versão caso haja uma mais recente)
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v1.0.1/zephyr-sdk-1.0.1_windows-x86_64_minimal.7z -OutFile zephyr-sdk-minimal.7z

# 2. Extraia o SDK básico usando o 7-Zip
7z x zephyr-sdk-minimal.7z
cd zephyr-sdk-1.0.1

# 3. Baixe APENAS a toolchain do compilador GNU ARM
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v1.0.1/toolchain_gnu_windows-x86_64_arm-zephyr-eabi.7z -OutFile toolchain_arm.7z

# 4. Extraia a toolchain ARM diretamente dentro da estrutura do SDK
7z x toolchain_arm.7z

Agora vamos registrar a toolchain diretamente no registro do CMake do usuário. Isso evita a necessidade de criar variáveis globais complexas no Windows:

setup.cmd /t arm-zephyr-eabi

Pronto! O ecossistema do Zephyr agora sabe exatamente onde encontrar o compilador de forma isolada e elegante.

5. Estrutura de Pastas Recomendada

Sua pasta ~/ZephyrRTOS ficará organizada de forma limpa e otimizada da seguinte maneira:

C:\Users\SeuUsuario\ZephyrRTOS\
├── STM/                 <-- Seu Workspace Zephyr (Core + HAL ST + Seus Projetos)
│   ├── zephyr/
│   │   └── samples/
│   ├── .west/           <-- Pasta de controle criada pelo comando west init
│   └── meu_projeto/     <-- Pasta base com seu projeto customizado
└── toolchain/           <-- O compilador de forma isolada
    └── zephyr-sdk-1.0.1/
        ├── arm-zephyr-eabi/  <-- Único compilador instalado (Cortex-M)
        └── setup.cmd

📌 Importante: Ao criar um novo projeto, a pasta raiz dele (como meu_projeto) deve ficar posicionada obrigatoriamente no mesmo nível da pasta oculta .west dentro do diretório STM.

6. Compilando o Projeto (Build)

Com o código-fonte estruturado, você pode realizar a compilação do firmware utilizando a ferramenta West. Use o comando de exemplo abaixo:

west build -b weact_stm32g431_core/stm32g431xx

Entenda o papel de cada parâmetro nesse fluxo:

1. west: A ferramenta guarda-chuva que orquestra todo o ecossistema (Git, CMake, Ninja, GCC).
2. build: Invoca o CMake e o Ninja para analisar o código (src/), configurações da aplicação (prj.conf), árvore de dispositivos (app.overlay) e gerar o binário final.
3. -b (ou --board): Informa ao Zephyr qual placa/hardware é o alvo da compilação.
4. weact_stm32g431_core/stm32g431xx: O identificador exato da placa de desenvolvimento seguido da variante do SoC (System on Chip).

6.1 Como Identificar o Nome Exato da sua Placa

Como a árvore de alvos do Zephyr é atualizada constantemente, a melhor fonte da verdade é o próprio terminal. Aqui estão as três melhores maneiras de encontrar a string correta para o parâmetro -b:

Método 1: O Comando west boards

A forma mais rápida de listar as placas suportadas no seu workspace atual filtrando por um fabricante ou arquitetura (usando o Select-String do PowerShell):

cd ~\ZephyrRTOS\STM\zephyr
west boards | Select-String "stm32" | Select-String "weact"

O terminal retornará exatamente a string que você deve passar ao comando, como weact_stm32g431_core/stm32g431xx.

Método 2: Inspecionando a Árvore de Diretórios

Os nomes mapeados refletem a estrutura de pastas do repositório do Zephyr. Você pode listar os fabricantes e modelos diretamente:

Get-ChildItem ~\ZephyrRTOS\STM\zephyr\boards\weact\

Dentro da pasta do modelo escolhido, existirá o arquivo board.yml, onde são definidas as variantes de chips suportadas pela placa.

Método 3: Forçando um Erro Amigável

Se você esquecer a sintaxe, digite um nome de placa inválido de propósito ao tentar buildar. O West interromperá o processo e listará as opções válidas mais próximas:

west build -b placa_errada samples\basic\blinky

Saída esperada no terminal:

FATAL ERROR: board 'placa_errada' not found.
Valid boards include:
  - nucleo_g431rb
  - weact_stm32g431_core
  ...

7. Gravando o Firmware (Flash)

Após o build bem-sucedido, conecte o gravador no microcontrolador e execute o comando abaixo para transferir o binário:

west flash -d build -r openocd --config ./openocd_hla.cfg

Análise dos parâmetros de gravação:

• flash: Subcomando encarregado de transferir o binário compilado para a memória Flash do microcontrolador.
• -d build: Aponta para o diretório onde os metadados do runner (runners.yaml) e os arquivos compactados (zephyr.hex ou zephyr.bin) foram gerados.
• -r openocd: Define o utilitário OpenOCD (Open On-Chip Debugger) como o runner responsável por gerenciar a comunicação através do ST-Link.
• --config ./openocd_hla.cfg: Passa um argumento customizado diretamente para o OpenOCD, instruindo-o a ler um arquivo local de configuração em vez das definições padrão do Zephyr.

7.1 O arquivo openocd_hla.cfg

Se você utiliza gravadores ST-Link v2 genéricos (clones de baixo custo), o uso de configurações padrão pode falhar. Criar um arquivo chamado openocd_hla.cfg na raiz do seu diretório de build contendo as linhas abaixo garante uma comunicação estável em modo de alto nível (hla_swd) e velocidade controlada:

source [find interface/stlink.cfg]
transport select hla_swd
source [find target/stm32g4x.cfg]
adapter speed 500

8. Conclusão

A instalação manual do Zephyr RTOS no Windows oferece um ambiente de desenvolvimento profissional, limpo e totalmente sob o seu controle. Ao optar pelo uso do West combinado com o SDK Minimal focado estritamente na arquitetura ARM, eliminamos o desperdício de armazenamento em disco e evitamos conflitos de caminhos globais no Windows.

Com o ecossistema devidamente estruturado, o seu ambiente está pronto para extrair a máxima performance e confiabilidade em projetos com a linha STM32.