Port do Arduboy2 para SF32LB52¶

O que é Arduboy2-SiFli?¶

OpenSiFli/Arduboy2-SiFli é um port da biblioteca Arduboy2, criado pela OpenSiFli para o ambiente de desenvolvimento SiFli. A Arduboy2 oferece um modelo de aplicação para dispositivos de jogos compactos: loop de quadros, buffer de display, botões, sprites, texto e controle opcional de som. O port para SiFli serve, portanto, como teste de compatibilidade: permite avaliar quanto de um jogo no estilo Arduboy pode ser mantido ao migrar a placa, o display, as entradas, o áudio e o processo de compilação para SF32.

O repositório é uma referência de software, não um console pronto nem um projeto de hardware para produção. Consulte o README, a árvore de código-fonte, os exemplos, o histórico de issues e os arquivos de licença para confirmar a placa-alvo exata, as APIs compatíveis, as instruções de compilação e as condições de redistribuição. Esta página organiza as decisões de engenharia relacionadas à referência, mas não substitui as instruções executáveis do repositório.

Qual é o valor deste port para SF32?¶

Uma aplicação no estilo Arduboy permite testar, de forma compacta, várias decisões de um produto embarcado: loop de renderização previsível, recursos monocromáticos ou de baixa resolução, entrada por botões, temporização de áudio e orçamento de memória rigorosamente limitado. Portar esse modelo para SF32 pode servir como referência inicial para jogos portáteis, demonstradores de interface, dispositivos educacionais e outros produtos com interação local e determinística.

O valor não está em executar qualquer sketch Arduboy sem alterações, mas em deixar claros os limites do port:

• O jogo pode manter a lógica de alto nível para atualização, entradas, desenho e recursos, desde que permaneça dentro da API Arduboy2 compatível.
• O port precisa adaptar as premissas de display, botões, áudio, temporização e armazenamento que eram implícitas no hardware original.
• Qualquer sketch que controle diretamente registradores AVR, pinos específicos da Arduboy, transações de display, temporizadores ou o layout da EEPROM exige adaptação deliberada e evidências próprias de regressão.

Essas são expectativas de engenharia, não afirmações de compatibilidade confirmadas por medição. Confirme-as no repositório atual da OpenSiFli e registre o resultado exato para a placa e o commit selecionados.

Resultado, escopo e critérios de entrada¶

Esta página define etapas para transformar a referência da OpenSiFli em um jogo ou demonstração interativa reproduzível no SF32. Ela não afirma que o port oferece todos os recursos da Arduboy2, executa todos os jogos Arduboy, funciona em qualquer placa SF32 ou garante temporização de display e áudio com qualidade de produção. Também não concede direitos de licenciamento para jogos, fontes, gráficos ou outros recursos copiados de repositórios de terceiros.

Resultado esperado: uma compilação do Arduboy2-SiFli controlada por versão, que execute um exemplo do repositório ou um pequeno sketch de teste, demonstre o caminho selecionado de display/entrada/áudio e registre evidências para decidir se vale a pena desenvolver um jogo maior ou adaptar o produto.

Público-alvo: engenheiros de firmware, hardware e produto que saibam usar as ferramentas Arduino, inspecionar código C/C++, gravar firmware em uma placa SF32, ler a saída serial e realizar medições básicas de display, entrada e alimentação.

Antes de começar, tenha à disposição:

• Uma placa SF32LB52 que use a variante ArduinoCore-Zephyr sf32lb52_devkit_lcd_sf32lb525uc6, além dos periféricos externos descritos abaixo. O README informa que display, botões, EEPROM externa e áudio foram testados em hardware SF32LB52; também documenta o caminho de um LED RGB, mas não relata um resultado de teste para ele. O README não fixa a revisão física da placa nem identifica o modelo exato do módulo OLED.
• Uma instalação Arduino funcional e o pacote de placas OpenSiFli correspondente. O nome da variante define a base de software e o mapa de pinos, mas não comprova que todas as unidades SF32LB52-DevKit-LCD correspondam à fiação externa do projeto; confira o esquemático da placa física antes de conectar periféricos.
• O commit exato do Arduboy2-SiFli, a versão do core/pacote Arduino, o sistema operacional do host e a ferramenta de gravação.
• Uma conexão USB de dados e meios para capturar o log serial e observar display, botões e saída de áudio.
• Permissão para usar e redistribuir todos os jogos, imagens, fontes e sons incluídos na adaptação derivada.

Especificações de hardware e software¶

Especificação de hardware¶

Especificação de software¶

Escolher uma base de referência compatível¶

Comece pela combinação de placa e software indicada no repositório da OpenSiFli, em vez de escolher uma placa do catálogo apenas por semelhança. O pacote da placa, as conexões do display, o mapeamento das entradas, o método de gravação e as premissas da biblioteca fazem parte da base.

O repositório Arduboy2-SiFli não fornece o mapa de pinos da placa em um arquivo separado: a tabela detalhada está no README, em SiFli IO mapping. As definições lógicas de pinos da biblioteca ficam em pins_sifli.h, enquanto o roteamento específico da placa é definido no overlay Devicetree do ArduinoCore-Zephyr. Essas fontes descrevem uma base de software, não uma montagem física validada; antes de conectar os periféricos, confira a revisão real da placa e seu esquemático.

O repositório identifica uma variante de placa de software e o mapa de pinos dos periféricos, e informa que display, botões, EEPROM externa e áudio foram testados em hardware SF32LB52. Também documenta o caminho de um LED RGB externo, mas não afirma que ele foi testado. A revisão física da placa, o modelo/controlador exato do OLED e um conjunto completo de acessórios não são identificados. Antes de conectar os componentes ou declarar a base de hardware reproduzível, compare o mapa de pinos da variante com o esquemático da placa física e registre os componentes e suas revisões. Não preencha as lacunas restantes com mapas de pinos ou endereços copiados de outro projeto SF32.

Etapas do projeto¶

Use as etapas como pontos de decisão, não como uma lista de recursos.

Arquitetura do sistema e dependências¶

flowchart LR
    G["Sketch do jogo\natualização, entrada, desenho, recursos"] --> A["Arduboy2-SiFli\ncamada de compatibilidade"]
    A --> C["Core Arduino\npacote da placa e runtime"]
    C --> S["SiFli-SDK / SF32\nGPIO, display, temporizadores, armazenamento, áudio"]
    S --> H["Placa SF32 selecionada\ndisplay, botões, alto-falante, USB"]
    A --> R["Testes de referência\nlog serial e inspeção visual"]

Este é um modelo de decisão, não uma afirmação de que o repositório usa exatamente esses nomes de módulos internos. Confirme os limites reais no código-fonte antes de modificar o port. Os principais aspectos do produto a considerar são:

• Quadros e temporização: o loop do jogo deve atualizar e renderizar em intervalos reproduzíveis; qualquer comportamento de áudio ou entrada sensível à temporização precisa ser medido na placa-alvo.
• Display: a camada de compatibilidade deve mapear o buffer e a geometria do jogo para o controlador de display, formato de pixel, orientação e método de atualização selecionados.
• Entradas: nomes e polaridade dos botões, debounce, pressionamentos simultâneos e comportamento de despertar/reset devem ser conferidos com as conexões da placa.
• Áudio: geração de tons, uso do temporizador, conexão do alto-falante, volume e silenciamento devem ser considerados específicos da placa até serem verificados.
• Recursos e armazenamento: fontes, sprites, dados de som, layout da flash e uso de RAM devem ser medidos após a link-edição do jogo selecionado.
• Recuperação: mantenha um caminho de gravação e recuperação conhecido como funcional antes de experimentar alterações de temporização, memória ou baixo consumo.

As principais áreas de falha são compatibilidade da aplicação/API, configuração do display, conexões das entradas, comportamento de áudio/temporizadores, memória e posicionamento de recursos, além de gravação/recuperação. Uma falha em uma dessas áreas não deve ser resumida a “o port não funciona”.

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

Objetivo: comprovar que a base documentada pelo repositório funciona antes de alterar a biblioteca ou o jogo.

1. Leia as instruções do repositório, registre a branch padrão ou versão e examine os exemplos, a configuração da placa, as dependências e os arquivos de licença.
2. Instale exatamente o core/pacote Arduino e as ferramentas exigidas pelo repositório. Registre o sistema operacional do host e as versões das ferramentas.
3. Compile e grave o menor exemplo documentado ou sketch de teste.
4. Capture a saída serial e registre o que aparece no display, quais botões respondem e se o exemplo usa áudio.

Evidências a preservar: commit do repositório, versões de dependências/pacotes, revisão da placa, conexões ou referência ao esquemático, saída da compilação, logs de gravação e serial e um breve registro funcional.

Critério de saída do ponto de controle 1: a referência sem alterações compila e é gravada na placa selecionada, e o comportamento documentado se repete após reset ou ciclo de alimentação.

Etapa 2 — Valide os limites dos periféricos e da temporização¶

Objetivo: distinguir uma compilação bem-sucedida de uma base realmente utilizável para o dispositivo de jogos.

1. Teste a limpeza do display, a atualização de quadros completos, a renderização de sprites ou bitmaps, o texto e as premissas de geometria/orientação usadas pelo exemplo.
2. Teste todas as entradas usadas pelo projeto, incluindo soltar os botões, pressionamentos simultâneos e rápidos e, quando aplicável, o comportamento de reset ou despertar.
3. Se houver áudio, verifique início/parada dos tons, interação com temporizadores, silenciamento e efeito da atividade do display e das entradas sobre o áudio.
4. Interrompa o fluxo normal com reset, desconexão/reconexão e uma sequência de entrada inválida ou incompleta. Registre se a placa retorna a um estado funcional de gravação e execução.

Evidências a preservar: resultados visuais ou capturas do display, matriz de entradas, observações de temporização e áudio, log de reset/recuperação e medições de corrente ou latência que afetem a decisão sobre o produto.

Critério de saída do ponto de controle 2: o caminho dos periféricos está suficientemente compreendido para distinguir bugs da aplicação de problemas de configuração da placa, temporização ou alimentação.

Etapa 3 — Crie uma base reproduzível do código-fonte¶

Objetivo: tornar o port reproduzível, sem depender de uma única máquina de desenvolvimento ou de um binário fornecido.

1. Comece com um checkout limpo e inicialize todas as dependências exigidas pelo repositório.
2. Registre o pacote da placa, a versão do Arduino IDE/CLI, as versões do compilador e das ferramentas, os arquivos de configuração e os recursos gerados.
3. Compile em um diretório limpo, salve a imagem resultante e, quando disponíveis, as informações de mapa/tamanho; registre também o comando ou a saída da ferramenta de gravação.
4. Repita o processo em uma segunda máquina ou após remover o diretório de compilação.

Evidências a preservar: revisão do código-fonte e das dependências, manifesto do host/ferramentas, log da compilação, binário ou outro artefato, relatório de tamanho e logs de gravação e serial.

Critério de saída do ponto de controle 3: um checkout limpo reproduz uma imagem que passa nas verificações de periféricos da Etapa 2, sem arquivos locais não documentados nem edições manuais.

Etapa 4 — Adapte um jogo de forma controlada¶

Objetivo: comprovar os limites de compatibilidade por meio de uma alteração controlada no produto.

Comece com um sketch ou jogo pequeno, cujos requisitos de display, entradas, áudio e recursos sejam conhecidos. Mantenha disponível a imagem da referência sem alterações e mude uma classe de comportamento por vez:

Não copie acesso a registradores AVR, premissas de pinos da Arduboy original ou endereços de armazenamento para o projeto SF32 sem uma decisão de projeto respaldada por fontes. Mantenha junto ao código adaptado as licenças de jogos e recursos de terceiros e remova qualquer item cujas condições de redistribuição não estejam claras.

Evidências a preservar: diff revisado, procedência dos recursos, imagens antes/depois, logs de compilação e gravação, resultados de regressão e uma imagem para reversão.

Critério de saída do ponto de controle 4: o jogo adaptado passa nas verificações de periféricos da referência, e seus limites de memória, temporização, recuperação e licenciamento estão registrados.

Etapa 5 — Revise a prontidão do produto¶

Não avance de uma demonstração de port para hardware próprio ou teste de campo antes que a equipe consiga responder:

• Quais modelos exatos de placa SF32, display, botões, alto-falante e fonte de alimentação são compatíveis, e quais ainda são apenas premissas?
• Que taxa de quadros, latência de entrada, comportamento de áudio, tempo de inicialização e perfil de corrente foram medidos na base prevista para o produto?
• Quanta flash e RAM o jogo, os recursos, as fontes e o runtime consomem, inclusive com o conteúdo de pior caso?
• O que acontece após reset, subtensão, perda de alimentação durante o salvamento, corrupção de recursos, falha na gravação ou atualização incompleta?
• Quais partes do port são mantidas pela equipe do produto, pela OpenSiFli, pela SiFli ou pela comunidade original Arduboy2?
• As licenças de todos os jogos, fontes, imagens, sons e bibliotecas são compatíveis com o modelo de distribuição previsto?

Critério de saída do ponto de controle 5: os riscos restantes têm responsáveis e evidências; cada item conta com mitigação, adiamento explícito ou decisão de interromper.

Transição para o projeto do produto¶

Leve para a seção Hardware a seleção do dispositivo SF32, a arquitetura de display e entrada, o plano de áudio e temporização, a organização da flash e dos recursos, as medições de consumo, o método de recuperação e as premissas dos testes de produção. Consulte o Seletor de produtos SF32 quando os requisitos de display, memória, encapsulamento, alimentação ou conectividade do jogo alterarem a lista de dispositivos candidatos. Para definir a base de software, comece pelo guia de introdução ao Arduino e depois consulte a visão geral da plataforma Arduino.

A referência cumpriu seu objetivo de desenvolvimento de produto quando outro engenheiro consegue reconstruir o port, reproduzir os resultados dos periféricos, explicar cada adaptação específica da placa e revisar as evidências antes da aprovação de uma placa própria ou de uma biblioteca maior de jogos.

Fontes de referência¶

• OpenSiFli/Arduboy2-SiFli
• MLXXXp/Arduboy2
• OpenSiFli/ArduinoCore-zephyr
• Primeiros passos com Arduino no SF32
• Visão geral da plataforma Arduino
• Seletor de produtos SF32

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