Thor Satellite

Thor Satellite is a open-source Bitfocus Companion Satellite client for physical Elgato Stream Deck devices.

Set up your VPN/LAN between your smartphone and Companion app, install the app, connect your Stream Deck to your smartphone or tablet, remotely configure Thor from within Companion's Remote tab and prosper from a truely remote Stream Deck control surface.

• Android 9+ uses Android USB Host and Elgato's documented HID protocol directly.
• iPadOS 16+ uses Elgato StreamDeckKit and the Stream Deck Connect driver.
• Each attached deck is registered as an independent advanced Companion surface.
• Companion communication is trusted-LAN-only TCP. Version 1 has no TLS, cloud account, or Internet relay.

Status: The IOS (iPadOS) code and simulator builds are implemented, but not really tested.

AI DISCLAIMER: the app's been built leveraging AI assisted programming tool. I used Codex, ChatGPT Sol and Terra 5.6 models. I did my best to prevent AI slop.

Compatibility target

Family	Documented USB PID(s) accepted	Controls
Stream Deck Classic (2017)	0060	5×3 keys, original BMP HID protocol
Stream Deck Mini	0063, 0090, 00B3	3×2 keys
Stream Deck 2019	006D	5×3 keys
Stream Deck Mk.2	0080, 00A5	5×3 keys
Stream Deck XL	006C, 008F	8×4 keys
Stream Deck Neo	009A	4×2 keys, panel, page sensors
Stream Deck +	0084	4×2 keys, 4 dials, touch window
Stream Deck + XL	00C6	9×4 keys, 6 dials, touch window

Pedal, Studio, hardware modules, and third-party clones are intentionally rejected. iPhone support is out of scope, because of very limited USB device support.

Power draw considerations

Family	100%	50%	25%	2%
Stream Deck Mini	183	146	127	109
Stream Deck Classic (2017)	340	260	229	196

The table above shows the number of mA drawn at 5V from the USB-OTG connector by Stream Decks set up at various brightness levels. The numbers are relatively high - on my test device (Motorola Edge 20 Pro smartphone) connecting the "classic" Stream Deck surface running at full brightness roughly doubles the amount of power being drawn from the battery. You can expect a few of hours of "wireless" runtime.

Stream Deck + XLs are said to draw around 900 mA at full brightness. If you observe unstable behavior try lowering the brightness. A powered hub for connecting more than one deck is likely going to be required but in my case a Mini + Classic or XL + XL combo worked fine.

Android

Download the APK from the releases/latest page or build the app yourself. To install it you will very likely need to temporarily allow installing apps from untrusted sources.

Requirements: Android 9/API 28+, USB OTG host support.

cd android
ANDROID_HOME="$HOME/Library/Android/sdk" ./gradlew testDebugUnitTest lintDebug assembleDebug

Install the debug build with adb install -r app/build/outputs/apk/debug/app-debug.apk. On first attachment Android asks for USB permission. The foreground-service notification must remain visible for reliable operation. While the bridge is enabled, Thor also holds a partial wake lock so USB, TCP, and discovery work can continue when the display sleeps; Exit app releases it and stops the service.

The app provides saved Companion profiles, mDNS advertisement settings, connected-deck and protocol status, USB/power guidance, and shareable diagnostics. The discovery REST API listens on port 9999 and the Satellite TCP connection defaults to 16622.

iPadOS

Requirements:

1. An M1-or-newer USB-C iPad running iPadOS 16+.
2. Stream Deck Connect installed and its device driver enabled in Settings.
3. A development team whose provisioning profile permits com.apple.developer.driverkit.communicates-with-drivers.
4. A powered hub for multiple or high-power devices.

Open ipad/ThorSatellite.xcodeproj, choose a development team, and run on the iPad. The app checks the Stream Deck Connect URL scheme and reports SDK entitlement/version failures. StreamDeckKit releases hardware when the app backgrounds; Thor also closes Companion and re-registers every surface on return to the foreground.

The Thor deployment target is iPadOS 16 as supported by StreamDeckKit. The current Stream Deck Connect App Store release may impose a newer OS requirement, so the installable driver determines the effective minimum on physical hardware.

Simulator/core verification:

cd ipad
swift test
xcodebuild -project ThorSatellite.xcodeproj -scheme ThorSatellite \
  -sdk iphonesimulator -configuration Debug CODE_SIGNING_ALLOWED=NO build

Companion

Thor requires Companion 4.3+ / Satellite API 1.10+. Configure the Companion machine's LAN hostname or address manually, or let Companion discover Thor's _companion-satellite._tcp advertisement and port-9999 compatibility API. Thor does not scan for or reverse-discover Companion.

For Companion 5/API 1.12, Thor requests WebP when advertised, then PNG; otherwise it uses the raw RGB fallback. Unknown protocol fields are ignored. Each surface uses LAYOUT_MANIFEST and a streamdeck:<serial> stable identifier.

See architecture.md, protocol.md, and validation.md.

Releases and signing

CI builds an unsigned debug APK and an iPad simulator app. A v* tag can publish source archives, SHA-256 checksums, and a maintainer-signed Android APK when these GitHub secrets are present:

• ANDROID_KEYSTORE_BASE64
• ANDROID_KEYSTORE_PASSWORD
• ANDROID_KEY_ALIAS
• ANDROID_KEY_PASSWORD

Signing material is never stored in this repository. Play Store and App Store distribution are outside v1 scope.

Name trivia

Thor takes its name from the satellite that began Norway's commercial fleet after Norwegian Telecom acquired the already-orbiting Marco Polo II in 1992 and renamed it THOR 1. Since Bitfocus is based in Oslo I thought it would be fun to use that name for arguably the first Android (and IOS) Companion Satellite client for directly connected physical Stream Deck hardware.

Licensed under GPL-3.0-only. See NOTICE for third-party notices.