Arduboy2-Portierung für SF32LB52¶

Was ist Arduboy2-SiFli?¶

OpenSiFli/Arduboy2-SiFli ist eine OpenSiFli-Portierung der Arduboy2-Bibliothek für die SiFli-Entwicklungsumgebung. Arduboy2 bietet ein anwendungsnahes Modell für ein kleines Spielgerät: eine Spielschleife mit Bildaktualisierung, einen Display-Puffer, Tasten, Sprites, Text und optionale Klangsteuerung. Die SiFli-Portierung eignet sich als Kompatibilitätsexperiment: Sie zeigt, wie viel von einem Spiel im Arduboy-Stil erhalten bleiben kann, wenn Board, Display, Eingabe, Audio und Build-Pfad auf SF32 umgestellt werden.

Das Repository ist eine Software-Referenz, keine fertige Spielkonsole und kein Hardware-Design für die Serienfertigung. README, Quellbaum, Beispiele, Issue-Verlauf und Lizenzdateien sind maßgeblich für das genaue Board-Ziel, den unterstützten API-Umfang, die Build-Anleitung und die Weitergabebedingungen. Diese Seite ordnet die technischen Entscheidungen rund um die Referenz; sie ersetzt nicht die ausführbaren Anweisungen des Repositorys.

Warum diese SF32-Portierung?¶

Eine Anwendung im Arduboy-Stil ist ein kompakter Weg, mehrere Entscheidungen für Embedded-Produkte gleichzeitig zu erproben: eine vorhersagbare Render-Schleife, kleine monochrome oder niedrig aufgelöste Ressourcen, Tasteneingabe, Audio-Timing und ein eng begrenztes Speicherbudget. Die Portierung dieses Modells auf SF32 kann eine nützliche frühe Referenz für Handheld-Spiele, UI-Demonstratoren, Lerngeräte und andere Produkte liefern, deren Interaktion lokal und deterministisch ist.

Entscheidend ist nicht, dass jeder Arduboy-Sketch unverändert läuft. Die Portierung macht vielmehr die Integrationsgrenzen sichtbar:

• Das Spiel kann seine übergeordnete Update-, Eingabe-, Zeichen- und Ressourcenlogik behalten, solange es innerhalb der unterstützten Arduboy2-API bleibt.
• Die Portierung muss die in der Originalhardware impliziten Annahmen zu Display, Tasten, Audio, Timing und Speicher an die SF32-Umgebung anpassen.
• Jeder Sketch, der AVR-Register, Arduboy-spezifische Pins, Display-Transaktionen, Timer oder das EEPROM-Layout direkt steuert, braucht eine bewusste Anpassung und eigene Regressionsnachweise.

Dies sind technische Erwartungen, keine gemessenen Kompatibilitätsaussagen. Bestätigen Sie sie am aktuellen OpenSiFli-Repository und halten Sie das genaue Ergebnis für das gewählte Board und den gewählten Commit fest.

Ergebnis, Umfang und Eintrittskriterien¶

Diese Seite definiert einen gestuften Weg von der OpenSiFli-Referenz zu einem reproduzierbaren SF32-Spiel oder einer interaktiven Demo. Sie behauptet nicht, dass die Portierung jede Arduboy2-Funktion, jedes Arduboy-Spiel, jedes SF32-Board oder serientaugliches Display- und Audio-Timing unterstützt. Sie begründet auch keine Lizenzrechte an Spielen, Schriften, Grafiken oder anderen Ressourcen, die aus Repositorys Dritter übernommen wurden.

Ergebnis: ein versionierter Arduboy2-SiFli-Build, der ein Beispiel aus dem Repository oder einen kleinen Testsketch ausführt, den gewählten Pfad für Display/Eingabe/Audio demonstriert und die Nachweise festhält, die nötig sind, um zu entscheiden, ob ein größeres Spiel oder eine Produktanpassung gerechtfertigt ist.

Zielgruppe: Firmware-, Hardware- und Produktingenieure, die Arduino-Werkzeuge nutzen, C/C++-Code prüfen, ein SF32-Board flashen, serielle Ausgaben lesen und einfache Messungen an Display, Eingabe und Leistungsaufnahme durchführen können.

Halten Sie vor dem Start Folgendes bereit:

• Ein SF32LB52-Entwicklungsboard mit der Variante sf32lb52_devkit_lcd_sf32lb525uc6 von ArduinoCore-Zephyr sowie die unten beschriebenen externen Peripheriegeräte. Das README berichtet, dass Display, Tasten, externes EEPROM und Audiopfade auf SF32LB52-Hardware erprobt wurden; es dokumentiert einen RGB-LED-Pfad, nennt dafür aber kein Testergebnis. Das README legt keine physische Board-Revision fest und benennt das genaue OLED-Modul nicht.
• Eine funktionierende Arduino-Installation und das passende OpenSiFli-Board-Paket. Der Variantenname ist eine Basis für Software und Pin-Zuordnung, kein Beweis, dass jede SF32LB52-DevKit-LCD-Bestückung der externen Verdrahtung des Projekts entspricht; prüfen Sie den Schaltplan des physischen Boards, bevor Sie Peripherie anschließen.
• Den genauen Commit von Arduboy2-SiFli, die Version von Arduino-Core/-Paket, das Host-Betriebssystem und das Upload-Werkzeug.
• Eine USB-Datenverbindung und eine Möglichkeit, das serielle Log aufzuzeichnen sowie Display, Tasten und Audioausgabe zu beobachten.
• Die Erlaubnis, jedes in einer nachgelagerten Anpassung enthaltene Spiel, Bild, jede Schrift und jede Klangressource zu verwenden und weiterzugeben.

Hardware- und Software-Spezifikationen¶

Hardware-Spezifikation¶

Software-Spezifikation¶

Unterstützte Referenzkonfiguration auswählen¶

Beginnen Sie mit der Kombination aus Board und Software, die das OpenSiFli-Repository nennt, statt ein Board nach Ähnlichkeit aus dem Produktkatalog zu wählen. Board-Paket, Display-Verdrahtung, Eingabezuordnung, Upload-Methode und Annahmen der Bibliothek gehören zur Basis.

Das Repository Arduboy2-SiFli liefert die Pin-Zuordnung des Boards nicht als separate Datei: Sein README veröffentlicht die SiFli-I/O-Zuordnungstabelle. Die logischen Pin-Definitionen der Bibliothek stehen in pins_sifli.h, das boardspezifische Routing im Devicetree-Overlay von ArduinoCore-Zephyr. Diese Quellen definieren eine Software-Basis, keine validierte physische Bestückung; prüfen Sie vor der Verdrahtung die tatsächliche Board-Revision und den Schaltplan.

Das Repository benennt eine Software-Board-Variante und eine Pin-Zuordnung der Peripherie und berichtet, dass Display, Tasten, externes EEPROM und Audiopfade auf SF32LB52-Hardware erprobt wurden. Es dokumentiert einen externen RGB-LED-Pfad, gibt aber nicht an, dass dieser getestet wurde. Das Repository benennt weder die physische Board-Revision noch das genaue OLED-Modul/den Controller noch eine vollständige Zubehör-Bestückung. Gleichen Sie die Pin-Zuordnung der Variante vor der Verdrahtung oder vor der Behauptung einer reproduzierbaren Hardware-Basis mit dem Schaltplan des tatsächlichen Boards ab und halten Sie die verwendeten Teile und Revisionen fest. Schließen Sie verbleibende Lücken nicht mit Pin-Zuordnungen oder Adressen aus einem anderen SF32-Projekt.

Projektphasen und Entscheidungspunkte¶

Verwenden Sie die Phasen als Kontrollpunkte und nicht als Funktions-Checkliste.

Systemarchitektur und Abhängigkeiten¶

flowchart LR
    G["Spiel-Sketch\nUpdate, Eingabe, Zeichnen, Ressourcen"] --> A["Arduboy2-SiFli\nKompatibilitätsschicht"]
    A --> C["Arduino-Core\nBoard-Paket und Laufzeit"]
    C --> S["SiFli-SDK / SF32\nGPIO, Display, Timer, Speicher, Audio"]
    S --> H["Gewähltes SF32-Board\nDisplay, Tasten, Lautsprecher, USB"]
    A --> R["Referenztests\nSerielles Log und Sichtprüfungen"]

Dies ist ein Entscheidungsmodell und keine Behauptung, dass das Repository genau diese internen Modulnamen verwendet. Bestätigen Sie die tatsächlichen Quellgrenzen, bevor Sie die Portierung ändern. Die wichtigen Produktpfade sind:

• Bildaktualisierung und Timing: Die Spielschleife muss Bilder in einem wiederholbaren Takt aktualisieren und rendern. Zeitkritisches Audio- oder Eingabeverhalten muss auf dem Ziel-Board gemessen werden.
• Display: Die Kompatibilitätsschicht muss den Puffer und die Geometrie des Spiels auf den gewählten Display-Controller, das Pixelformat, die Ausrichtung und den Aktualisierungspfad abbilden.
• Eingabe: Tastennamen, Polarität, Entprellung, gleichzeitiges Drücken sowie Aufwach-/Reset-Verhalten müssen anhand der Board-Verdrahtung geprüft werden.
• Audio: Tonerzeugung, Timer-Zuständigkeit, Lautsprecheranschluss, Lautstärke und Stummschaltung gelten bis zur Verifikation als boardspezifisch.
• Ressourcen und Speicher: Schriften, Sprites, Klangdaten, Flash-Layout und RAM-Nutzung müssen gemessen werden, nachdem das gewählte Spiel gelinkt wurde.
• Wiederherstellung: Bewahren Sie einen bekannten Upload- und Wiederherstellungsweg, bevor Sie mit Timing-, Speicher- oder Low-Power-Änderungen experimentieren.

Die wesentlichen Fehlerdomänen sind Anwendungs-/API-Kompatibilität, Display-Konfiguration, Eingabeverdrahtung, Audio-/Timer-Verhalten, Speicher- und Ressourcenplatzierung sowie Upload/Wiederherstellung. Ein Fehler in einer Domäne sollte nicht einfach als „die Portierung funktioniert nicht“ gemeldet werden.

Phase 1 — Die unveränderte Referenz herstellen¶

Ziel: Nachweisen, dass die dokumentierte Basis des Repositorys real ist, bevor Bibliothek oder Spiel geändert werden.

1. Lesen Sie die Anweisungen des Repositorys, erfassen Sie den Standard-Branch bzw. das Release und prüfen Sie Beispiele, Board-Konfiguration, Abhängigkeiten und Lizenzdateien.
2. Installieren Sie genau den Arduino-Core bzw. das Paket und die Werkzeuge, die das Repository verlangt. Erfassen Sie Host-Betriebssystem und Werkzeugversionen.
3. Bauen Sie das kleinste dokumentierte Beispiel oder den Testsketch und laden Sie es hoch.
4. Zeichnen Sie die serielle Ausgabe auf und notieren Sie, was auf dem Display erscheint, welche Tasten reagieren und ob das Beispiel Audio nutzt.

Aufzubewahrende Nachweise: Commit des Repositorys, Abhängigkeits-/Paketversionen, Board-Revision, Verdrahtung oder Schaltplanreferenz, Build-Ausgabe, Upload-Log, serielles Log und ein kurzes Funktionsprotokoll.

Abnahmekriterium für Kontrollpunkt 1: Die unveränderte Referenz lässt sich auf dem gewählten Board bauen und hochladen; ihr dokumentiertes Verhalten ist nach einem Reset oder Aus- und Einschalten wiederholbar.

Phase 2 — Grenzen von Peripherie und Timing validieren¶

Ziel: Eine erfolgreiche Kompilierung von einer brauchbaren Basis für ein Spielgerät trennen.

1. Prüfen Sie das Leeren des Displays, die Aktualisierung des gesamten Bildes, die Darstellung von Sprites oder Bitmaps, die Textausgabe sowie alle vom Beispiel vorausgesetzten Geometrie- und Ausrichtungseinstellungen.
2. Prüfen Sie alle vom Projekt verwendeten Eingaben: Loslassen, gleichzeitiges und schnelles Drücken sowie gegebenenfalls das Verhalten nach Reset oder beim Aufwachen.
3. Prüfen Sie bei enthaltenem Audio Tonstart/-stopp, Timer-Interaktion, Stummschaltung und den Einfluss von Display- und Eingabeaktivität auf den Tonpfad.
4. Unterbrechen Sie den normalen Ablauf durch Reset, Trennen/Wiederverbinden und eine ungültige oder unvollständige Eingabefolge. Halten Sie fest, ob das Board in einen nutzbaren Upload- und Ausführungszustand zurückkehrt.

Aufzubewahrende Nachweise: Sicht- oder aufgezeichnete Display-Ergebnisse, Eingabematrix, Timing-Beobachtungen, Audio-Beobachtungen, Reset-/Wiederherstellungs-Log sowie gemessener Strom oder gemessene Latenz, die die Produktentscheidung beeinflussen.

Abnahmekriterium für Kontrollpunkt 2: Der gewählte Peripheriepfad ist so gut verstanden, dass sich Anwendungsfehler von Problemen der Board-Konfiguration, des Timings oder der Versorgung unterscheiden lassen.

Phase 3 — Eine reproduzierbare Quellbasis aufbauen¶

Ziel: Die Portierung reproduzierbar machen, statt von einem Entwicklungsrechner oder einem gelieferten Binary abzuhängen.

1. Beginnen Sie mit einem sauberen Checkout und initialisieren Sie jede vom Repository benötigte Abhängigkeit.
2. Erfassen Sie Board-Paket, Version von Arduino IDE/CLI, Compiler-/Werkzeugversionen, Konfigurationsdateien und alle erzeugten Ressourcen.
3. Bauen Sie aus einem sauberen Verzeichnis, sichern Sie das entstandene Image sowie Map-/Größeninformationen, soweit verfügbar, und erfassen Sie den Upload-Befehl bzw. die Werkzeugausgabe.
4. Wiederholen Sie dies auf einem zweiten Rechner oder nach dem Entfernen des Build-Verzeichnisses.

Aufzubewahrende Nachweise: Quellrevision, Revisionen der Abhängigkeiten, Host-/Werkzeug-Manifest, Build-Log, Binary oder anderes Artefakt, Größenbericht, Upload-Log und serielles Log.

Abnahmekriterium für Kontrollpunkt 3: Ein sauberer Checkout erzeugt ohne undokumentierte lokale Dateien oder manuelle Änderungen ein Image, das die Peripherieprüfungen aus Phase 2 besteht.

Phase 4 — Ein Spiel gezielt anpassen¶

Ziel: Die Kompatibilitätsgrenze mit einer kontrollierten Produktänderung nachweisen.

Beginnen Sie mit einem kleinen Sketch oder Spiel, bei dem die Anforderungen an Display, Eingabe, Audio und Ressourcen klar erkennbar sind. Halten Sie das unveränderte Referenz-Image bereit und ändern Sie jeweils nur eine Verhaltensklasse:

Übernehmen Sie keinen AVR-Registerzugriff, keine ursprünglichen Arduboy-Pin-Annahmen und keine Speicheradressen in das SF32-Projekt, ohne eine durch Quellen gestützte Designentscheidung. Bewahren Sie Lizenzen von Spielen und Ressourcen Dritter neben dem angepassten Quellcode auf und entfernen Sie alles, dessen Weitergabebedingungen nicht eindeutig sind.

Aufzubewahrende Nachweise: Geprüfter Diff, Herkunft der Ressourcen, Vorher-/Nachher-Bild, Build- und Upload-Logs, Regressionsergebnisse und ein Rollback-Image.

Abnahmekriterium für Kontrollpunkt 4: Das angepasste Spiel besteht die Referenz-Peripherieprüfungen; seine Grenzen bei Speicher, Timing, Wiederherstellung und Lizenzierung sind dokumentiert.

Phase 5 — Prüfung der Produktreife¶

Gehen Sie von einer Portierungsdemonstration erst dann zu eigener Hardware oder einem Feldtest über, wenn das Team Folgendes beantworten kann:

• Welches genaue SF32-Board, Display, welche Tasten, welcher Lautsprecher und welche Stromquelle werden unterstützt, und was sind noch Annahmen?
• Welche Bildrate, Eingabelatenz, welches Audioverhalten, welche Startzeit und welches Stromprofil wurden auf der vorgesehenen Produktbasis gemessen?
• Wie viel Flash und RAM verbrauchen Spiel, Ressourcen, Schriften und Laufzeit, einschließlich Inhalten im ungünstigsten Fall?
• Was geschieht nach Reset, Brownout, Stromausfall während des Speicherns, beschädigten Ressourcen, fehlgeschlagenem Upload oder unvollständigem Update?
• Welche Teile der Portierung werden vom Produktteam, von OpenSiFli, SiFli oder der ursprünglichen Arduboy2-Community gepflegt?
• Sind alle Lizenzen für Spiele, Schriften, Bilder, Klänge und Bibliotheken mit dem vorgesehenen Vertriebsmodell vereinbar?

Abnahmekriterium für Kontrollpunkt 5: Für verbleibende Risiken gibt es benannte Verantwortliche und Nachweise; für jeden Punkt ist eine Gegenmaßnahme, eine ausdrückliche Zurückstellung oder eine Stopp-Entscheidung festgehalten.

Übergabe an das Produktdesign¶

Übernehmen Sie das gewählte SF32-Gerät, die Architektur von Display und Eingabe, den Plan für Audio/Timer, Flash- und Ressourcen-Layout, Leistungsmessungen, Wiederherstellungsmethode und die Annahmen zum Produktionstest in den Bereich Hardware. Nutzen Sie den SF32-Produktwähler, wenn Anforderungen des Spiels an Display, Speicher, Gehäuse, Energiebedarf oder Konnektivität die Auswahlliste der Bauteile verändern. Für die Software-Basis beginnen Sie mit Erste Schritte mit Arduino und fahren mit der Übersicht zur Arduino-Plattform fort.

Die Referenz hat ihren Zweck für die Produktentwicklung erfüllt, wenn ein anderer Ingenieur die Portierung neu bauen, die Peripherieergebnisse reproduzieren, jede boardspezifische Anpassung erklären und die Nachweise prüfen kann, bevor ein eigenes Board oder eine erweiterte Spielebibliothek freigegeben wird.

Maßgebliche Quellen¶

• OpenSiFli/Arduboy2-SiFli
• MLXXXp/Arduboy2
• OpenSiFli/ArduinoCore-zephyr
• Erste Schritte mit Arduino auf SF32
• Übersicht zur Arduino-Plattform
• SF32-Produktwähler

Zuletzt aktualisiert: 2026-10-21