Firmware de teclado ZMK no SF32¶

O que é o ZMK no SF32?¶

ZMK Firmware é um firmware de teclado sob licença MIT, desenvolvido sobre o Zephyr. O projeto principal do ZMK fornece o modelo de aplicação usado por muitos teclados com e sem fio, inclusive os divididos em duas metades: varredura da matriz, mapas de teclas e camadas, comportamentos de tecla, HID por USB e Bluetooth, configurações persistentes e definições extensíveis de placas/shields.

OpenSiFli/zmk é um repositório derivado (fork) do ZMK, mantido pela OpenSiFli. A versão analisada acrescenta:

• uma variante de placa sf32lb52_devkit_lcd/sf32lb525uc6/zmk;
• integração do SoC SF32LB52 à árvore da aplicação ZMK;
• configurações para placa única, teclado dividido, ZMK Studio e o shield urchin_sf32lb52;
• um backend CherryUSB adaptado ao SF32;
• uma partição NVS de 256 KB para armazenar configurações e suporte à persistência das configurações Bluetooth;
• um mapa de teclas do teclado dividido Urchin com três camadas, controles de perfil Bluetooth e atalhos de desbloqueio do ZMK Studio.

Esta é uma adaptação em desenvolvimento, não uma versão de produto ZMK para SF32 identificada por uma tag de lançamento. O README na raiz do repositório derivado ainda é o README genérico do projeto principal ZMK e não oferece um guia de início rápido específico para SF32. Use a placa, o shield, o manifesto, o código-fonte e o commit como referência executável. Antes de adaptar, reúna evidências próprias de compilação limpa, gravação, funcionamento e recuperação.

Por que usar a implementação SF32?¶

A adaptação para SF32 demonstra como executar o modelo de teclado do ZMK no SF32LB52 mantendo as convenções do Zephyr para a árvore de dispositivos (devicetree), Kconfig, west, mapas de teclas, shields e teclados divididos em duas metades. A referência urchin_sf32lb52 distribui um layout de 38 teclas entre as metades. A configuração esquerda exerce a função central: habilita CherryUSB e ZMK Studio e pode disponibilizar HID por USB ao computador anfitrião. A configuração direita exerce a função periférica. O ZMK BLE é habilitado nas duas metades.

Esse repositório derivado é útil para avaliar um teclado sem fio dividido em duas metades, um dispositivo de entrada USB/Bluetooth para desktop, um teclado macro programável ou um produto HMI personalizado com SF32. A contrapartida é o nível de maturidade das dependências: o manifesto west fixa um ramo personalizado do Zephyr (v4.3+sf32-zmk_fixes), uma revisão específica do SiFli HAL e o ramo personalizado zephyr-adapt do CherryUSB. Essas dependências fazem parte dos limites de compatibilidade da adaptação. Não as substitua pelas versões mais recentes do projeto principal sem uma migração completa e uma rodada de regressão.

Resultado, escopo e critérios de entrada¶

Resultado esperado: compilar e gravar imagens Urchin com versões fixadas para os lados esquerdo e direito; validar toda a matriz de teclas, as camadas, HID por USB, o link BLE entre metades e os caminhos até o host, a persistência das configurações, o limite do ZMK Studio e a recuperação; depois, fazer uma alteração controlada no mapa de teclas ou no hardware, com evidências reproduzíveis.

Esta página não afirma paridade completa de recursos com o projeto principal do ZMK, compatibilidade com qualquer shield ZMK, autonomia de bateria pronta para produção, desempenho de rádio comprovado ou suporte à migração para outra revisão do Zephyr/ZMK. Também não define uma PCB de teclado pronta para produção: a configuração Urchin do repositório associa uma matriz de referência aos pinos do SF32LB52-DevKit-LCD; essa associação precisa ser adaptada deliberadamente para cada projeto de hardware personalizado.

Antes de começar, prepare:

• duas placas SF32LB52-DevKit-LCD compatíveis com a variante sf32lb525uc6/zmk do repositório derivado;
• um gabarito de teste para teclado dividido de 38 teclas, ligado exatamente conforme as sobreposições de configuração (overlays) urchin_sf32lb52_left e urchin_sf32lb52_right, ou um shield de teste menor e documentado para as verificações iniciais da adaptação;
• um host com ambiente Zephyr/ZMK west funcional e espaço de armazenamento suficiente para os módulos fixados no repositório derivado;
• conexões de gravação, console serial e recuperação verificadas para cada metade antes de testar a comunicação entre elas;
• um cabo USB de dados para a metade esquerda/central e um meio independente de alimentar e recuperar a metade direita/periférica;
• um host Bluetooth, um host compatível com ZMK Studio se esse recurso estiver no escopo e um método para medir a corrente de cada metade;
• um registro do commit do repositório derivado, das revisões do manifesto, dos identificadores da placa e do shield, dos registros de compilação e gravação, dos resultados dos testes de teclas, dos vínculos Bluetooth, do estado das configurações e das medições de corrente.

Especificações de hardware e software¶

Especificação de hardware¶

Especificação de software¶

Escolher uma configuração de referência suportada¶

A base OpenSiFli analisada é o commit fd4d5843065f, de 27/05/2026. Ela inclui a atualização do shield Urchin e da configuração da placa disponível nesse commit, mas não é uma versão ZMK para SF32 identificada por tag. Fixe esse commit para a reprodução inicial ou registre e revise explicitamente qualquer commit mais recente.

Os comandos a seguir combinam o fluxo de trabalho west do repositório derivado com os identificadores exatos da placa SF32 e dos shields Urchin. Mantenha separados os dois diretórios de compilação para não confundir as imagens:

git clone https://github.com/OpenSiFli/zmk.git
cd zmk
git checkout fd4d5843065f

west init -l app
west update --fetch-opt=--filter=tree:0
west zephyr-export

west build -s app -p always -d build-left \
  -b sf32lb52_devkit_lcd/sf32lb525uc6/zmk -- \
  -DSHIELD=urchin_sf32lb52_left

west build -s app -p always -d build-right \
  -b sf32lb52_devkit_lcd/sf32lb525uc6/zmk -- \
  -DSHIELD=urchin_sf32lb52_right

Registre o west list final, o Kconfig e o devicetree gerados, os hashes dos artefatos, as etiquetas que identificam a imagem e a metade correspondente e o procedimento real de gravação. Não inicie os testes do teclado dividido até conseguir recuperar cada placa de forma independente.

Etapas do projeto¶

Arquitetura do sistema e dependências¶

flowchart LR
    KL["Matriz esquerda\n19 posições"] --> L["SF32LB52 esquerdo\nCentral ZMK"]
    KR["Matriz direita\n19 posições"] --> R["SF32LB52 direito\nPeriférico ZMK"]
    R -->|"Link BLE dividido do ZMK"| L
    L -->|"USB HID\nCherryUSB"| H["Computador host"]
    L -->|"Bluetooth HID"| H
    H <-->|"ZMK Studio\nsomente na imagem de firmware da metade esquerda"| L
    NL["Configurações NVS\nvínculos e configuração"] --> L
    NR["Configurações NVS\nestado persistente"] --> R
    M["Manifesto west da OpenSiFli\nZephyr + HAL + CherryUSB personalizados"] --> L
    M --> R

Trate cada falha como um domínio distinto: matriz e fiação física, comunicação da metade direita para a esquerda, USB do lado esquerdo, Bluetooth do host, vínculos e configurações armazenados, ZMK Studio, gravação e recuperação da placa e conjunto de dependências fixadas. Se uma tecla não chegar ao host, a falha pode ocorrer antes da varredura, durante a comunicação entre metades, no mapa de teclas central ou no destino HID selecionado. Diagnostique o caminho nessa ordem.

Etapa 1 — Estabeleça a base da adaptação sem alterações¶

Objetivo: comprovar a referência exata da OpenSiFli antes de alterar o mapa de teclas, um overlay ou uma dependência.

1. Registre as revisões das duas placas e ligue os gabaritos exatamente de acordo com os overlays Urchin esquerdo e direito. Identifique placas e cabos USB/de gravação conforme a função.
2. Compile as duas imagens no commit fixado, salve west list e inspecione a configuração gerada para confirmar a placa, o shield, a função de cada metade, BLE, CherryUSB, ZMK Studio e NVS esperados.
3. Grave cada imagem usando o caminho de recuperação previamente verificado para aquela placa. Registre a inicialização a frio e o comportamento do console antes de parear as metades ou o host.
4. Estabeleça o link BLE entre as metades e verifique as 38 posições nas camadas default, lower e raise. Teste deliberadamente a seleção/limpeza de perfis Bluetooth e os atalhos de desbloqueio do Studio para evitar acioná-los por acidente durante os testes de digitação.
5. Valide USB HID e ZMK Studio na metade esquerda e, depois, Bluetooth HID no host escolhido. Repita após uma inicialização a frio.

Evidências a guardar: registros das placas e da fiação, revisões do repositório derivado e do manifesto, configurações geradas, hashes das imagens, registros de gravação e inicialização, matriz completa de posições das teclas, resultados por camada, destino HID selecionado e versões do host/Studio.

Critério de saída do ponto de controle 1: duas inicializações a frio reproduzem as 38 posições, as três camadas, a comunicação da metade direita para a esquerda e pelo menos um destino HID do host; as duas metades continuam recuperáveis de forma independente.

Etapa 2 — Valide entrada, transporte, configurações e recuperação¶

Objetivo: comprovar que falhas realistas do teclado são visíveis e recuperáveis sem reconstruir a partir de um estado desconhecido.

Critério de saída do ponto de controle 2: cada falha aplicável tem um resultado repetível de detecção e recuperação; nenhum teste deixa um estado HID preso; configurações ou vínculos podem voltar à base registrada sem substituir arquivos fora de controle de versão.

Etapa 3 — Crie uma configuração de referência reproduzível a partir do código-fonte¶

Objetivo: permitir que outro engenheiro gere novamente as duas imagens e repita a Etapa 2 a partir de fontes limpas.

1. Comece com uma cópia de trabalho limpa do repositório derivado no commit registrado e execute west init, west update e west zephyr-export sem substituir módulos localmente.
2. Salve west list, as versões do compilador e das ferramentas, o .config e o devicetree gerados, a saída de memória, os registros de compilação e os hashes dos dois artefatos.
3. Grave as imagens identificadas como esquerda e direita nas metades correspondentes e repita todos os testes da Etapa 2.
4. Compare os artefatos e a configuração com o registro original; explique qualquer diferença não reproduzível antes de prosseguir.

Critério de saída do ponto de controle 3: um segundo ambiente gera imagens corretamente identificadas e aprovadas na Etapa 2, sem overlays fora de controle de versão, resultados de compilação obsoletos ou revisões flutuantes de dependências.

Etapa 4 — Adapte um limite do teclado por vez¶

Objetivo: fazer uma alteração de produto preservando a adaptação comprovadamente funcional e os caminhos de recuperação independentes.

Critério de saída do ponto de controle 4: a alteração foi revisada, as imagens e configurações originais podem ser restauradas e todos os testes aplicáveis de matriz, camadas, comunicação entre metades, USB, BLE, Studio, alimentação e recuperação foram aprovados.

Etapa 5 — Revisão de prontidão do produto¶

Antes de projetar uma PCB de teclado personalizada ou um protótipo com bateria, responda:

• Quem mantém o repositório derivado ZMK da OpenSiFli, o ramo personalizado do Zephyr, a revisão do SiFli HAL, a adaptação CherryUSB e as futuras atualizações de segurança ou compatibilidade?
• Quais recursos do projeto principal do ZMK foram realmente exercitados no SF32 e quais apenas existem na árvore herdada?
• Como serão controlados na fabricação e na assistência a identificação das imagens esquerda/direita, a revisão da placa, o mapa de teclas, a configuração, os vínculos e o estado de restauração de fábrica?
• Quais são as correntes medidas de cada metade nos estados ativo, em repouso conectado, desconectado e em suspensão, incluindo a taxa de varredura, o comportamento de reconexão e a proteção da bateria?
• Quais hosts, sistemas operacionais, controladores USB, pilhas Bluetooth, caminhos de despertar, casos de rollover e condições de interferência foram testados?
• É possível recuperar o produto sem abri-lo ou descartá-lo após falha em atualização de dependência, alteração do Studio, gravação de configuração ou atualização em campo?
• As licenças ZMK/Zephyr, os arquivos da PCB e do gabinete, o conteúdo do mapa de teclas, logotipos, fontes e configurações incluídas são compatíveis com a distribuição pretendida?

Critério de saída do ponto de controle 5: cada risco residual tem um responsável, evidências e uma decisão de tratamento; a equipe decidiu explicitamente prosseguir, adiar ou interromper.

Transição para o projeto do produto¶

Leve adiante o modelo exato do componente SF32 e sua memória, as funções e o transporte das metades, o mapa de linhas/colunas/entradas diretas, a orientação dos diodos, a conexão USB, as premissas de antena e gabinete, a política NVS/configurações, as interfaces de gravação e recuperação, o orçamento de energia por metade, os gabaritos de teste, a identificação das imagens e o manifesto fixado. Continue com SF32LB52-DevKit-LCD, os limites da plataforma Zephyr, a arquitetura Bluetooth, o guia de projeto de hardware do SF32LB52x e Projeto para produção.

Fontes de referência¶

• Repositório derivado OpenSiFli/zmk para SF32
• Commit analisado do OpenSiFli/zmk
• Variante de placa ZMK SF32LB52 no commit revisado
• Shield dividido Urchin SF32LB52 no commit revisado
• Manifesto west do ZMK OpenSiFli no commit revisado
• Projeto principal zmkfirmware/zmk
• Documentação do ZMK
• Documentação do projeto Zephyr

Última atualização: 2026-10-21