Teclado macro multifuncional SuperKey¶

O que é o SuperKey?¶

SiFliSparks/SuperKey é uma implementação de referência baseada no SF32LB52 para um teclado macro multifuncional com displays. O firmware de código aberto roda em RT-Thread e LVGL v9, controla três displays LCD GC9107 de 128 × 128, três LEDs RGB, quatro teclas físicas, um encoder rotativo e um sensor de temperatura e umidade SHT30, e se conecta ao computador como um dispositivo USB composto HID/CDC.

O SuperKey vai além de um teclado de atalhos. Ele reúne estes caminhos de produto em uma referência funcional:

• saída USB HID para teclado e controles de mídia;
• recepção, via USB CDC ou UART de 1 Mbps, de dados do computador sobre desempenho, clima, configuração e estado de energia;
• páginas exibidas nos três displays para monitorar desempenho e clima, além de mostrar relógio, utilitários, música e mapeamentos personalizados de teclas;
• aplicativo complementar SuperKeyHub, que coleta dados do computador, configura funções e inicia atualizações de firmware;
• hardware reproduzível com o projeto aberto sf32-keyboard.

Por que usar a implementação com SF32?¶

O SuperKey precisa de recursos gráficos, vários displays, um dispositivo USB composto, teclas e encoder, sensores, efeitos RGB, sistema de arquivos e áudio opcional. O SF32LB52 mantém essas tarefas em tempo real no MCU, permitindo que o dispositivo inicie a interface e ofereça funções HID básicas mesmo quando o aplicativo complementar não está em execução. O aplicativo no computador cuida da telemetria do sistema e dos dados da Internet, tarefas mais adequadas a um sistema operacional de desktop.

Essa divisão atende a controladores de desktop, teclados para fluxos de trabalho, painéis de status e HMIs compactas, mas traz dependências explícitas. A exibição de dados avançados requer o aplicativo complementar, drivers e APIs externas; as versões do firmware e do aplicativo precisam ser compatíveis; e falhas de USB, suspensão do computador e configurações corrompidas exigem testes de recuperação independentes.

Resultado, escopo e critérios de entrada¶

Resultado: reproduzir uma configuração do SuperKey com versões fixadas e validar HID, CDC, a interface nos três displays, entradas, sensores e recuperação após a suspensão; em seguida, alterar apenas uma categoria de comportamento e manter evidências de compilação, comunicação e regressão para a análise do produto.

Este artigo não atesta que a PCB aberta esteja pronta para produção nem que haja compatibilidade com todas as fontes de telemetria do computador, serviços meteorológicos, pontes seriais, hosts USB ou versões de sistema operacional. Os dados sobre ações, clima e desempenho podem depender da versão do SuperKeyHub, de APIs de terceiros, das permissões do sistema e do hardware do computador.

Antes de começar, tenha em mãos:

• hardware do SuperKey montado conforme o projeto aberto, incluindo três displays LCD GC9107, teclas, encoder e conexão USB para dados;
• um computador com Windows 10/11 para o fluxo principal documentado. O repositório do SuperKeyHub declara suporte a Windows e macOS, mas valide a gravação da placa, a comunicação CDC e a recuperação no sistema operacional escolhido;
• uma versão do SuperKeyHub compatível com o firmware;
• um ambiente SiFli-SDK, o submódulo do SDK obtido recursivamente e uma conexão funcional de gravação/recuperação;
• uma API Key, um API Host e uma configuração de cidade válidos do QWeather, caso o clima faça parte dos testes;
• um registro de testes que cubra enumeração USB, logs seriais, comportamento das teclas, estado dos displays e recuperação após suspensão.

Especificações de hardware e software¶

Especificação de hardware¶

Especificação de software¶

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

A página de releases do projeto inclui o firmware v1.4.2, que serve como ponto de partida fixo. O material citado não especifica uma versão compatível do SuperKeyHub; selecione e fixe uma versão ou commit do Hub, teste telemetria, configuração e DFU com a v1.4.2 e registre o par testado, sem presumir compatibilidade pelos números de versão.

A integração contínua do projeto usa o alvo a seguir. Instale e carregue o ambiente do SiFli-SDK antes de executar os comandos localmente:

git clone --recursive https://github.com/SiFliSparks/SuperKey.git
cd SuperKey/SiFli-SDK
./install.sh
. ./export.sh
cd ../app/project
scons --board=sf32lb52-superkey --board_search_path="../boards" -j8

No Windows, use os scripts de instalação e configuração do ambiente do SiFli-SDK para PowerShell. O paralelismo pode ser ajustado, mas o nome da placa, o caminho de busca da placa e as revisões dos submódulos devem constar do registro de compilação.

Etapas do projeto¶

Arquitetura do sistema e dependências¶

flowchart LR
    U["Usuário\nteclas e encoder rotativo"] --> F["Firmware SF32LB52\nRT-Thread + LVGL v9"]
    F --> D["Três LCDs GC9107\nLEDs RGB, SHT30 e áudio opcional"]
    F -->|"USB HID\nteclado e eventos de mídia"| P["Computador host Windows / macOS"]
    P -->|"USB CDC ou UART de 1 Mbps\ntelemetria, clima, configuração e modo de energia"| F
    H["SuperKeyHub\ncoleta, configuração e atualização"] <--> P
    H <--> A["API de clima e fontes de telemetria do computador"]
    H -->|"CDC DFU"| F

Classifique as falhas em cinco domínios: hardware e displays do dispositivo; entrada HID; canal de dados CDC/UART; aplicativo complementar e permissões do sistema; e serviços externos de dados. Uma tela de clima vazia não indica necessariamente uma falha no firmware: a API Key, o API Host, a configuração da cidade ou o envio dos dados podem ser a causa.

Etapa 1 — Estabeleça a base de referência sem alterações¶

Objetivo: comprovar o funcionamento de todo o caminho de referência antes de alterar o código.

1. Siga as instruções de montagem do projeto para conferir a orientação dos cabos LCD, as chaves, o encoder, o gabinete e o conector USB; registre as revisões da placa e do firmware.
2. Instale uma versão compatível do SuperKeyHub. Confirme a enumeração do dispositivo e, em seguida, teste HID e CDC separadamente.
3. Configure as credenciais de clima, a porta e a comunicação serial a 1 Mbps. Registre o comportamento sem o aplicativo complementar; depois, conecte-o e habilite o envio de dados.
4. Verifique a navegação da interface nos três displays, o mapeamento das teclas, o controle de mídia, o encoder, os dados do SHT30, os efeitos dos LEDs e um ciclo completo de atualização da telemetria.
5. Faça uma inicialização a frio e repita os testes. Salve fotos da interface, logs do aplicativo e do dispositivo e o resultado da consulta de versão.

Evidências a manter: revisão do hardware, tag/commit do firmware, commit do SDK, versão do aplicativo complementar, sistema operacional, configurações de porta e API, enumeração USB, logs, fotos dos displays e registro das entradas.

Critério de saída do ponto de controle 1: duas inicializações a frio concluem a entrada HID, a atualização de dados via CDC e a interação com os três displays; cada domínio de falha pode ser distinguido pelos logs ou por um estado observável.

Etapa 2 — Valide os limites de falha e recuperação¶

Objetivo: comprovar que interrupções comuns em um computador desktop não deixam o dispositivo em um estado de demonstração que exija regravação do firmware.

Critério de saída do ponto de controle 2: cada falha aplicável tem um resultado reproduzível de detecção e recuperação, sem depender de reparos manuais de estado não documentados.

Etapa 3 — Crie uma base de código reproduzível¶

Objetivo: permitir que outro engenheiro compile, grave a imagem e repita a Etapa 2 a partir de um checkout limpo.

1. Clone o repositório recursivamente e registre os commits do SuperKey e do SiFli-SDK.
2. Faça uma compilação limpa usando o alvo sf32lb52-superkey e o caminho de busca ../boards.
3. Guarde o log de compilação, a saída de memória/partições, o script de gravação, as imagens geradas e o log serial.
4. Repita a compilação em outro computador ou após apagar o diretório de build; grave a imagem no mesmo hardware e repita os principais testes de regressão.

Critério de saída do ponto de controle 3: a imagem aprovada na Etapa 2 pode ser gerada sem arquivos não rastreados, artefatos antigos ou substituições manuais de binários.

Etapa 4 — Adapte uma variável do produto por vez¶

Objetivo: validar os limites da alteração sem comprometer a referência aprovada.

Critério de saída do ponto de controle 4: a alteração foi revisada, a imagem original pode ser restaurada e os testes de HID, CDC, displays, entradas, suspensão e recuperação foram aprovados.

Etapa 5 — Revise a prontidão para o produto¶

Antes de desenvolver hardware próprio ou montar um lote piloto, a equipe deve responder:

• O produto continuará dependendo do SuperKeyHub, de privilégios de administrador e de um serviço de clima de terceiros? Quem será responsável por essas dependências?
• Como serão gerenciadas as versões do firmware, do aplicativo complementar e do protocolo, e como serão bloqueadas combinações incompatíveis?
• Quais combinações de computadores, hubs USB, cabos, políticas de suspensão e softwares de segurança foram testadas?
• Qual é o uso de memória, a temperatura e a corrente com os três displays, os dados USB, os LEDs, os sensores e o áudio opcional operando ao mesmo tempo?
• Como recuperar as configurações, os mapeamentos de teclas e o estado da atualização após uma queda de energia ou dano ao armazenamento?
• As licenças da placa aberta, do gabinete, das fontes, dos ícones, da música e das APIs de terceiros permitem a distribuição planejada?

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

Transição para o projeto do produto¶

Leve adiante a seleção do SF32 e da memória, os descritores USB HID/CDC, as conexões dos três displays e da retroiluminação, as interfaces de entrada e dos sensores, a política de energia e suspensão, o sistema de arquivos e as partições de atualização, o protocolo do aplicativo complementar, os pontos de teste de produção e o caminho de recuperação validado. Consulte SF32LB52x, o guia de projeto de hardware do SF32LB52x, Compilar, gravar e monitorar com o SiFli-SDK e Projeto para produção para continuar.

Fontes de referência¶

• Repositório do firmware SiFliSparks/SuperKey
• Lançamento SuperKey v1.4.2
• Repositório do aplicativo complementar SiFliSparks/SuperKeyHub
• Documentação do projeto SuperKey
• Hardware aberto sf32-keyboard
• OpenSiFli/SiFli-SDK

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