Sphaira Connect — Switch-Installer für macOS
Ein reverse-engineertes USB-Protokoll, stundenlange Blocking-Transfers und ein Hardware-Exploit, sauber verpackt in eine native App mit Warteschlange, Live-Fortschritt und Liquid-Glass-Oberfläche
PROJEKT
Sphaira Connect —
Switch-Installer für macOS
TECHNOLOGIEN
Herausforderung
Die Switch-Homebrew-App Sphaira installiert Titel per USB, doch mit ihrem 1.0-Release hat sie ihr altes, Tinfoil-kompatibles Protokoll gegen ein eigenes ausgetauscht. Über Nacht funktionierten die etablierten Tools nicht mehr, und übrig blieb ein mitgeliefertes Python-Skript als einziger unterstützter Weg. Ein Skript, das eine Python-Umgebung braucht, keine Warteschlange kennt und beim Fortschritt schweigt.
Als Mac-Nutzer und Bastler wollte ich das ordentlich: eine echte macOS-App, die mehrere Titel als Queue annimmt, Geschwindigkeit und Restzeit anzeigt, ein Log führt, und die man einfach öffnet, statt ein Terminal zu bemühen. Kein Zwischenschritt, kein Python.
Zwei Dinge machten das anspruchsvoll:
- Das neue USB-Protokoll ist nirgends dokumentiert, es musste aus dem Python-Skript und dem Verhalten der Konsole reverse-engineert werden
- USB-Bulk-Transfers blockieren, bei mehreren GB großen Titeln über Minuten bis Stunden, ohne die reaktive Oberfläche einer nativen App auszubremsen oder abbrechbar zu bleiben
Lösung
Entstanden ist eine native SwiftUI-App mit vier strikt getrennten Schichten, deren Abhängigkeiten nur in eine Richtung zeigen. Diese Trennung ist kein Stilmittel, sondern in einem Contract festgeschrieben, gegen den jedes Modul einzeln gebaut wurde. Vier Aspekte trugen das Projekt.
Das Protokoll neu aufgebaut
Sphaira und die App tauschen nichts als 24-Byte-Pakete aus: sechs Little-Endian-UInt32-Werte, abgesichert per CRC32C, gefolgt von den rohen Nutzdaten. Die Argument-Felder haben keine feste Bedeutung, sondern werden je nach Richtung und Zustand der State-Machine anders gelesen. Genau dieses Format habe ich aus dem Python-Skript rekonstruiert und als sauber getestete Swift-Implementierung neu gebaut, Paket-Layout, Prüfsumme und Installations-Ablauf inklusive.
Stundenlange Transfers ohne eingefrorene UI
Swifts moderne Nebenläufigkeit stellt per Default alles auf den MainActor, für eine App, deren Kernaufgabe stundenlange blockierende USB-Aufrufe sind, genau die falsche Voreinstellung. Deshalb sind die Protokoll- und USB-Schichten bewusst nonisolated, die Session läuft in einem detached Task, und jede Rückmeldung kommt über exakt einen geordneten AsyncStream zurück in die Oberfläche. Abbrechen läuft nicht über Task-Cancellation, sondern über ein Lock-gesichertes Flag, das die blockierenden Schleifen zwischen zwei USB-Timeouts abfragen.
Zweiter Modus: Konsole erst öffnen
Viele Konsolen sind noch gar nicht für Homebrew freigeschaltet. Dafür hat die App einen zweiten, komplett eigenständigen Modus: manuelle RCM-Payload-Injektion über den Fusée-Gelée-Hardware-Exploit für ältere, unpatchte Geräte. Mit eingebauten Presets für Hekate und Fusée, die ihre offiziellen Releases direkt von GitHub laden und vor jeder Injektion per SHA-256 gegenprüfen. Injiziert wird ausschließlich auf Knopfdruck, nie automatisch. Beide Modi teilen sich nur die UI-Hülle, auf Transport- und Session-Ebene sind es getrennte USB-Geräte, getrennte Modelle, getrennte Schleifen.
Testbarkeit als Architekturprinzip
Die Grenze zwischen der reinen Core-Schicht und der USB-Schicht ist von der Testbarkeit getrieben: Das Test-Target bindet die Core-Logik per Symlink direkt ein, sodass Protokoll, Prüfsummen und Fortschrittsberechnung ohne echte Hardware geprüft werden, mit über sechzig Tests. Die Oberfläche folgt einem Liquid-Glass-Designsystem mit einer klaren Regel: kein Glas auf Glas. Das Fenster wechselt seine Stimmung mit der Phase des Transfers.
Code-Beispiele
Ergebnisse
Sphaira Connect ist quelloffen (GPL-3.0), auf GBAtemp veröffentlicht und im Einsatz. Aus einem Terminal-Skript wurde eine App, die man einfach benutzt:
- Natives macOS statt Python-Skript: Titel per Drag-and-drop, Warteschlange, Live-Geschwindigkeit, Restzeit und Log
- Reverse-engineertes SPH0-USB-Protokoll als getestete Swift-Implementierung neu aufgebaut, mit CRC32C-Absicherung
- Stundenlange Blocking-Transfers ohne eingefrorene UI, jederzeit sauber abbrechbar
- Zweiter Modus für RCM-Payload-Injektion (Fusée Gelée) mit Hekate-/Fusée-Presets direkt von GitHub
- Über sechzig Tests gegen die Core-Logik ohne echte Hardware, zweisprachig (DE/EN)
Das Projekt ist mein liebstes Beispiel dafür, wie Bastel-Neugier und sauberes Engineering zusammenkommen: ein undokumentiertes Protokoll, ein Hardware-Exploit und die harte Realität blockierender Hardware-I/O, am Ende verpackt in eine App, die sich anfühlt wie aus einem Guss.
Visuelle Eindrücke
Warteschlange mehrerer Titel, laufender USB-Transfer mit Geschwindigkeit, Restzeit und Fortschritt pro Datei.
