Portage d'Arduboy2 pour SF32LB52¶

Qu'est-ce qu'Arduboy2-SiFli ?¶

OpenSiFli/Arduboy2-SiFli est un portage par OpenSiFli de la bibliothèque Arduboy2 vers l'environnement de développement SiFli. Arduboy2 fournit un modèle orienté application pour un petit appareil de jeu : une boucle d'images, un tampon d'affichage, des boutons, des sprites, du texte et une commande de son optionnelle. Le portage SiFli est donc utile comme expérience de compatibilité : il montre quelle part d'un jeu de style Arduboy peut être conservée lorsque la carte, l'écran, les entrées, l'audio et la chaîne de compilation sous-jacents passent à SF32.

Le dépôt est une référence logicielle, et non une console de jeu terminée ni une conception matérielle de production. Considérez son README, son arborescence source, ses exemples, l'historique de ses tickets et ses fichiers de licence comme faisant autorité pour la cible de carte exacte, la surface d'API prise en charge, les instructions de compilation et les conditions de redistribution. Cette page organise les décisions d'ingénierie autour de cette référence ; elle ne remplace pas les instructions exécutables du dépôt.

Pourquoi ce portage SF32 ?¶

Une application de style Arduboy est un moyen compact d'exercer plusieurs décisions de produit embarqué à la fois : une boucle de rendu prévisible, de petites ressources monochromes ou à basse résolution, une entrée par boutons, un minutage audio et un budget mémoire étroitement borné. Porter ce modèle sur SF32 peut fournir une référence précoce utile pour des jeux portables, des démonstrateurs d'interface, des appareils éducatifs et d'autres produits dont l'interaction est locale et déterministe.

L'intérêt n'est pas que chaque sketch Arduboy fonctionne sans modification. L'intérêt est la frontière que le portage met en évidence :

• Le jeu peut conserver sa logique de haut niveau de mise à jour, d'entrée, de dessin et de ressources tant qu'il reste dans l'API Arduboy2 prise en charge.
• Le portage doit traduire les hypothèses sur l'affichage, les boutons, l'audio, le minutage et le stockage qui étaient implicites dans le matériel d'origine.
• Tout sketch qui pilote directement des registres AVR, des broches propres à Arduboy, des transactions d'affichage, des minuteurs ou la disposition de l'EEPROM exige une adaptation délibérée et des preuves de non-régression distinctes.

Ce sont des attentes d'ingénierie, et non des déclarations de compatibilité mesurées. Confirmez-les par rapport au dépôt OpenSiFli actuel et consignez le résultat exact pour la carte et le commit retenus.

Résultat, portée et critères d'entrée¶

Cette page définit un parcours par étapes depuis la référence OpenSiFli jusqu'à un jeu ou une démo interactive SF32 reproductible. Elle n'affirme pas que le portage prend en charge toutes les fonctions d'Arduboy2, tous les jeux Arduboy, toutes les cartes SF32, ni un minutage d'affichage et d'audio de qualité production. Elle n'établit pas non plus de droits de licence sur les jeux, polices, graphiques ou autres ressources copiés depuis des dépôts tiers.

Résultat : une compilation Arduboy2-SiFli sous gestion de versions qui exécute un exemple du dépôt ou un petit sketch de test, démontre le chemin retenu pour l'affichage/les entrées/l'audio, et consigne les preuves nécessaires pour décider si un jeu plus important ou une adaptation produit se justifie.

Lecteur visé : ingénieurs firmware, matériel et produit capables d'utiliser l'outillage Arduino, d'inspecter du code C/C++, de flasher une carte SF32, de lire une sortie série et d'effectuer des mesures de base d'affichage, d'entrée et de consommation.

Avant de commencer, ayez à disposition :

• Une carte de développement SF32LB52 utilisant la variante ArduinoCore-Zephyr sf32lb52_devkit_lcd_sf32lb525uc6, ainsi que les périphériques externes décrits ci-dessous. Le README indique que les chemins d'affichage, de boutons, d'EEPROM externe et d'audio ont été exercés sur du matériel SF32LB52 ; il documente un chemin de LED RVB mais n'indique aucun résultat de test pour celui-ci. Le README ne fixe pas de révision de carte physique et n'identifie pas le module OLED exact.
• Une installation Arduino fonctionnelle et le paquet de carte OpenSiFli correspondant. Le nom de la variante est une base logicielle et de correspondance des broches, et non la preuve que chaque assemblage SF32LB52-DevKit-LCD correspond au câblage externe du projet ; vérifiez le schéma de la carte physique avant de brancher des périphériques.
• Le commit exact d'Arduboy2-SiFli, la version du cœur/paquet Arduino, le système d'exploitation hôte et l'outil de téléversement.
• Une connexion USB de données et un moyen de capturer le journal série et d'observer l'affichage, les boutons et la sortie audio.
• L'autorisation d'utiliser et de redistribuer chaque jeu, image, police et ressource sonore inclus dans une adaptation en aval.

Spécifications matérielles et logicielles¶

Spécification matérielle¶

Spécification logicielle¶

Choisir une configuration de référence prise en charge¶

Commencez par la combinaison de carte et de logiciel nommée dans le dépôt OpenSiFli plutôt que de choisir une carte du catalogue produit par similarité. Le paquet de carte, le câblage de l'écran, la correspondance des entrées, la méthode de téléversement et les hypothèses de la bibliothèque font partie de la configuration de référence.

Le dépôt Arduboy2-SiFli ne fournit pas la correspondance des broches de la carte dans un fichier distinct : son README publie le tableau de correspondance des E/S SiFli. Les définitions de broches logiques de la bibliothèque se trouvent dans pins_sifli.h, tandis que le routage propre à la carte figure dans la surcouche Devicetree d'ArduinoCore-Zephyr. Ces sources définissent une base logicielle, et non un assemblage physique validé ; vérifiez la révision réelle de la carte et son schéma avant le câblage.

Le dépôt identifie une variante logicielle de carte et une correspondance des broches des périphériques, et indique que les chemins d'affichage, de boutons, d'EEPROM externe et d'audio ont été exercés sur du matériel SF32LB52. Il documente un chemin de LED RVB externe mais n'indique pas qu'il ait été testé. Le dépôt n'identifie ni la révision de la carte physique, ni le module/contrôleur OLED exact, ni un assemblage complet d'accessoires. Avant de câbler ou d'affirmer une base matérielle reproductible, rapprochez la correspondance des broches de la variante du schéma de la carte réelle et consignez les composants et révisions utilisés. Ne comblez aucune lacune restante avec des correspondances de broches ou des adresses copiées d'un autre projet SF32.

Étapes du projet¶

Utilisez les étapes comme des points de décision, et non comme une liste de fonctions à cocher.

Architecture système et dépendances¶

flowchart LR
    G["Sketch du jeu\nmise à jour, entrées, dessin, ressources"] --> A["Arduboy2-SiFli\ncouche de compatibilité"]
    A --> C["Cœur Arduino\npaquet de carte et exécution"]
    C --> S["SiFli-SDK / SF32\nGPIO, affichage, minuteurs, stockage, audio"]
    S --> H["Carte SF32 retenue\naffichage, boutons, haut-parleur, USB"]
    A --> R["Tests de référence\njournal série et contrôles visuels"]

Ceci est un modèle de décision, et non l'affirmation que le dépôt emploie exactement ces noms de modules internes. Confirmez les frontières réelles du code source avant de modifier le portage. Les chemins produit importants sont :

• Image et minutage : la boucle de jeu doit se mettre à jour et produire le rendu à une cadence répétable, et tout comportement audio ou d'entrée sensible au minutage doit être mesuré sur la carte cible.
• Affichage : la couche de compatibilité doit faire correspondre le tampon et la géométrie du jeu au contrôleur d'affichage, au format de pixel, à l'orientation et au chemin de rafraîchissement retenus.
• Entrées : les noms des boutons, la polarité, l'anti-rebond, les appuis simultanés et le comportement de réveil/réinitialisation doivent être vérifiés par rapport au câblage de la carte.
• Audio : la génération de tonalité, la propriété des minuteurs, la connexion du haut-parleur, le volume et le comportement de mise en sourdine doivent être traités comme propres à la carte tant qu'ils ne sont pas vérifiés.
• Ressources et stockage : les polices, sprites, données sonores, disposition de la flash et utilisation de la RAM doivent être mesurés après l'édition de liens du jeu retenu.
• Récupération : conservez un chemin de téléversement et de récupération connu avant d'expérimenter des changements de minutage, de mémoire ou de basse consommation.

Les principaux domaines de défaillance sont la compatibilité application/API, la configuration de l'affichage, le câblage des entrées, le comportement audio/minuteurs, la mémoire et le placement des ressources, ainsi que le téléversement/la récupération. Une défaillance dans un domaine ne doit pas être simplement signalée comme « le portage ne fonctionne pas ».

Étape 1 — Établir la référence intacte¶

Objectif : prouver que la base documentée du dépôt est réelle avant de modifier la bibliothèque ou un jeu.

1. Lisez les instructions du dépôt, consignez la branche par défaut ou la version, et inspectez ses exemples, sa configuration de carte, ses dépendances et ses fichiers de licence.
2. Installez le cœur/paquet Arduino et les outils exacts exigés par le dépôt. Consignez le système d'exploitation hôte et les versions des outils.
3. Compilez et téléversez le plus petit exemple ou sketch de test documenté.
4. Capturez la sortie série et consignez ce qui apparaît à l'écran, quels boutons répondent et si l'exemple utilise l'audio.

Preuves à conserver : commit du dépôt, versions des dépendances/paquets, révision de la carte, référence du câblage ou du schéma, sortie de compilation, journal de téléversement, journal série et court relevé fonctionnel.

Critère de sortie du point de contrôle 1 : la référence intacte se compile et se téléverse sur la carte retenue, et son comportement documenté est répétable après une réinitialisation ou un cycle d'alimentation.

Étape 2 — Valider les frontières des périphériques et du minutage¶

Objectif : distinguer une compilation réussie d'une base d'appareil de jeu utilisable.

1. Exercez l'effacement de l'écran, la mise à jour d'image complète, le rendu de sprites ou de bitmaps, le chemin du texte et toutes les hypothèses de géométrie/d'orientation utilisées par l'exemple.
2. Exercez chaque entrée utilisée par le projet, y compris le relâchement, les appuis simultanés, les appuis rapides et, le cas échéant, le comportement de réinitialisation ou de réveil.
3. Si l'audio est inclus, vérifiez le démarrage/l'arrêt de la tonalité, l'interaction avec les minuteurs, la mise en sourdine et l'effet de l'activité d'affichage et d'entrée sur le chemin sonore.
4. Interrompez le flux normal par une réinitialisation, un débranchement/rebranchement et une séquence d'entrée invalide ou incomplète. Consignez si la carte revient à un état utilisable de téléversement et d'exécution.

Preuves à conserver : résultats d'affichage visuels ou capturés, matrice des entrées, observations de minutage, observations audio, journal de réinitialisation/récupération, et tout courant ou toute latence mesurés qui influencent la décision produit.

Critère de sortie du point de contrôle 2 : le chemin de périphériques retenu est assez bien compris pour distinguer les bogues applicatifs des problèmes de configuration de la carte, de minutage ou d'alimentation.

Étape 3 — Construire une base source reproductible¶

Objectif : rendre le portage reproductible plutôt que dépendant d'une machine de développement ou d'un binaire fourni.

1. Partez d'une extraction propre et initialisez chaque dépendance requise par le dépôt.
2. Consignez le paquet de carte, la version d'Arduino IDE/CLI, les versions du compilateur et des outils, les fichiers de configuration et toutes les ressources générées.
3. Compilez depuis un répertoire propre, enregistrez l'image obtenue ainsi que les informations de carte d'implantation mémoire (fichier map) et de taille lorsqu'elles sont disponibles, et consignez la commande de téléversement ou la sortie de l'outil.
4. Répétez sur une seconde machine ou après suppression du répertoire de compilation.

Preuves à conserver : révision des sources, révisions des dépendances, manifeste de l'hôte et des outils, journal de compilation, binaire ou autre artefact, rapport de taille, journal de téléversement et journal série.

Critère de sortie du point de contrôle 3 : une extraction propre reproduit une image qui réussit les contrôles des périphériques de l'étape 2 sans fichiers locaux non documentés ni modifications manuelles.

Étape 4 — Adapter un jeu de façon délibérée¶

Objectif : prouver la frontière de compatibilité par une modification produit contrôlée.

Commencez par un petit sketch ou jeu dont les besoins en affichage, entrées, audio et ressources sont visibles. Gardez l'image de référence intacte disponible et ne modifiez qu'une classe de comportement à la fois :

Ne copiez pas d'accès aux registres AVR, d'hypothèses de broches d'origine d'Arduboy ni d'adresses de stockage dans le projet SF32 sans décision de conception étayée par des sources. Conservez les licences des jeux et ressources tiers à côté du code source adapté, et retirez tout élément dont les conditions de redistribution ne sont pas claires.

Preuves à conserver : diff relu, provenance des ressources, image avant/après, journaux de compilation et de téléversement, résultats de non-régression et image de retour arrière.

Critère de sortie du point de contrôle 4 : le jeu adapté réussit les contrôles de référence des périphériques, et ses limites de mémoire, de minutage, de récupération et de licence sont consignées.

Étape 5 — Revue de maturité produit¶

Ne passez pas d'une démonstration de portage à du matériel sur mesure ou à un essai sur le terrain tant que l'équipe ne peut pas répondre aux questions suivantes :

• Quelles cartes SF32, écrans, boutons, haut-parleurs et sources d'alimentation exacts sont pris en charge, et lesquels restent des hypothèses ?
• Quels débit d'images, latence d'entrée, comportement audio, temps de démarrage et profil de courant ont été mesurés sur la base produit visée ?
• Quelle quantité de flash et de RAM consomment le jeu, les ressources, les polices et l'environnement d'exécution, y compris pour un contenu dans le pire cas ?
• Que se passe-t-il après une réinitialisation, une chute de tension, une coupure d'alimentation pendant la sauvegarde, des ressources corrompues, un téléversement échoué ou une mise à jour incomplète ?
• Quelles parties du portage sont maintenues par l'équipe produit, OpenSiFli, SiFli ou la communauté Arduboy2 d'origine ?
• Chaque licence de jeu, de police, d'image, de son et de bibliothèque est-elle compatible avec le modèle de distribution prévu ?

Critère de sortie du point de contrôle 5 : les risques restants ont des responsables nommés et des preuves ; chaque élément fait l'objet d'une atténuation, d'un report explicite ou d'une décision d'arrêt.

Passage à la conception du produit¶

Reportez le composant SF32 retenu, l'architecture d'affichage et d'entrées, le plan audio/minuteurs, la disposition de la flash et des ressources, les mesures de puissance, la méthode de récupération et les hypothèses de test en production dans la section Matériel. Utilisez le sélecteur de produits SF32 lorsque les exigences d'affichage, de mémoire, de boîtier, de consommation ou de connectivité du jeu modifient la présélection de composants. Pour la base logicielle, commencez par Prise en main d'Arduino, puis poursuivez avec la vue d'ensemble de la plateforme Arduino.

La référence a rempli son rôle pour le développement du produit lorsqu'un autre ingénieur peut reconstruire le portage, reproduire les résultats des périphériques, expliquer chaque adaptation propre à la carte et relire les preuves avant l'approbation d'une carte sur mesure ou d'une bibliothèque de jeux étendue.

Sources de référence¶

• OpenSiFli/Arduboy2-SiFli
• MLXXXp/Arduboy2
• OpenSiFli/ArduinoCore-zephyr
• Prise en main d'Arduino sur SF32
• Vue d'ensemble de la plateforme Arduino
• Sélecteur de produits SF32

Dernière mise à jour: 2026-10-21