Sphaira Connect — Switch Installer for macOS
A reverse-engineered USB protocol, hours-long blocking transfers, and a hardware exploit, neatly packaged into a native app with a queue, live progress, and a Liquid Glass interface
July 2026
Project
Sphaira Connect —
Switch Installer for macOS
Technologies Used
Challenge
The Switch homebrew app Sphaira installs titles over USB, but with its 1.0 release it swapped its old, Tinfoil-compatible protocol for one of its own. Overnight, the established tools stopped working, and all that remained was a bundled Python script as the only supported path. A script that needs a Python environment, has no queue, and stays silent about progress.
As a Mac user and tinkerer, I wanted to do this properly: a real macOS app that accepts multiple titles as a queue, shows speed and remaining time, keeps a log, and that you simply open instead of reaching for a terminal. No intermediate step, no Python.
Two things made this challenging:
- The new USB protocol isn't documented anywhere; it had to be reverse-engineered from the Python script and the console's behavior
- USB bulk transfers block, for minutes to hours with multi-gigabyte titles, and must do so without stalling the reactive interface of a native app or losing the ability to cancel
Solution
The result is a native SwiftUI app with four strictly separated layers whose dependencies point in only one direction. This separation is not a stylistic choice but written down in a contract that every module was built against individually. Four aspects carried the project.
Rebuilding the protocol
Sphaira and the app exchange nothing but 24-byte packets: six little-endian UInt32 values, guarded by CRC32C, followed by the raw payload. The argument fields have no fixed meaning; they are read differently depending on direction and the state machine's current state. I reconstructed exactly this format from the Python script and rebuilt it as a cleanly tested Swift implementation, packet layout, checksum, and installation flow included.
Hours-long transfers without a frozen UI
Swift's modern concurrency puts everything on the MainActor by default, exactly the wrong preset for an app whose core job is hours of blocking USB calls. That's why the protocol and USB layers are deliberately nonisolated, the session runs in a detached task, and every piece of feedback comes back to the interface through exactly one ordered AsyncStream. Cancellation doesn't go through task cancellation but through a lock-guarded flag that the blocking loops poll between two USB timeouts.
Second mode: unlocking the console first
Many consoles aren't unlocked for homebrew at all yet. For those, the app has a second, completely independent mode: manual RCM payload injection via the Fusée Gelée hardware exploit for older, unpatched devices. With built-in presets for Hekate and Fusée that fetch their official releases straight from GitHub and verify them via SHA-256 before every injection. Injection happens exclusively at the press of a button, never automatically. The two modes share only the UI shell; at the transport and session level they are separate USB devices, separate models, separate loops.
Testability as an architectural principle
The boundary between the pure core layer and the USB layer is driven by testability: the test target links the core logic directly via symlink, so protocol, checksums, and progress calculation are verified without real hardware, with more than sixty tests. The interface follows a Liquid Glass design system with one clear rule: no glass on glass. The window shifts its mood with the phase of the transfer.
Code Examples
Results
Sphaira Connect is open source (GPL-3.0), published on GBAtemp, and in active use. A terminal script became an app you simply use:
- Native macOS instead of a Python script: titles via drag and drop, a queue, live speed, remaining time, and a log
- Reverse-engineered SPH0 USB protocol rebuilt as a tested Swift implementation, guarded by CRC32C
- Hours-long blocking transfers without a frozen UI, cleanly cancellable at any time
- Second mode for RCM payload injection (Fusée Gelée) with Hekate/Fusée presets straight from GitHub
- More than sixty tests against the core logic without real hardware, bilingual (DE/EN)
This project is my favorite example of how tinkering curiosity and clean engineering come together: an undocumented protocol, a hardware exploit, and the hard reality of blocking hardware I/O, in the end packaged into an app that feels like a single, coherent whole.
Insights
A queue of multiple titles, a running USB transfer with speed, remaining time, and per-file progress.
