An app for controlling Nintendo Switch from a Mac via Raspberry Pi.

JoyControl is a macOS app and Raspberry Pi bridge for sending controller input and JSON-based macros to a Nintendo Switch. The Mac app provides the UI, connection flow, diagnostics, and macro controls. The Raspberry Pi acts as the Bluetooth controller bridge that presents itself to the Switch as a Pro Controller.

This repository is organized so that you can publish it on GitHub without local machine paths or personal setup details.

• Fixed several connection and reconnection bugs in the macOS app
• Improved Pi-side macro loop stability and completion handling
• Added a bright, friendly system sound when a finite loop finishes normally
• Added support for forwarding input from a controller connected directly to the Mac
• Controllers such as a PS5 controller can now be used through the full chain: Mac controller -> JoyControl macOS app -> Raspberry Pi -> Nintendo Switch

JoyControl is built around two parts:

• A macOS app that manages connection flow, manual input, macro selection, and loop execution
• A Raspberry Pi bridge that runs the Bluetooth stack and forwards controller actions to the Switch

Typical flow:

1. Start the Pi bridge
2. Open the macOS app
3. Connect or re-pair with the Switch
4. Use manual controls or run a JSON macro

• Connect to a Nintendo Switch through a Raspberry Pi
• Pair and reconnect using a single macOS flow
• Manual button and stick input from the Mac
• JSON macro execution
• Loop execution for supported macros
• Built-in diagnostics for pairing and bridge issues

• work/joycontrol-macos
  • The macOS app project
• Pi
  • Raspberry Pi bridge backup and installation files
• samples
  • Example JSON macros
• README_MAC_SETUP.md
  • Additional macOS setup notes
• README_MACRO.md
  • Macro format and macro-related notes
• README_PI_BRIDGE.md
  • Older bridge notes kept for reference

• macOS
• Xcode
• A Mac with Bluetooth

• Raspberry Pi with Bluetooth support
• Raspberry Pi OS
• Python 3
• sudo access

• Nintendo Switch

The macOS app source is in work/joycontrol-macos.

1. Open work/joycontrol-macos/joycontrol-macos.xcodeproj in Xcode
2. Build and run the joycontrol-macos target
3. Make sure the Mac can use Bluetooth normally

If you want more setup details, see README_MAC_SETUP.md.

The Pi-side files prepared for publishing are in Pi.

1. Copy the Pi folder to your Raspberry Pi
2. On the Pi, move into that directory
3. Run:

./install.sh

The Pi README contains the full breakdown:

• Pi/README.md

On the Raspberry Pi:

cd ~/PokeMacro-Pi
sudo MODE=pair ./run_macro_bridge_stack.sh <SWITCH_BT_ADDR>

Then on the Switch:

1. Open Controllers
2. Open Change Grip/Order

Then in the Mac app:

1. Press 接続
2. Complete pairing
3. Confirm with A when needed

On the Raspberry Pi:

cd ~/PokeMacro-Pi
sudo MODE=reconnect ./run_macro_bridge_stack.sh <SWITCH_BT_ADDR>

Then use the same 接続 flow in the macOS app.

Example macros are included in samples and work/joycontrol-macos/samples.

Included examples:

• mash_a.json
• frlg02_startup_sync.json
• frlg02_sweet_scent_shinyhunt.json

Macro-related notes:

• README_MACRO.md

• This project uses a Raspberry Pi as the Bluetooth controller bridge
• The Switch may require removing old controller registrations before a clean re-pair
• Some automation flows depend on timing and the current game state
• Example shiny-hunt macros should be treated as automation helpers, not as guaranteed state-aware bots

• This project is not affiliated with or endorsed by Nintendo
• Use at your own risk
• Make sure Bluetooth changes on the Raspberry Pi do not interfere with other devices you rely on

This project builds on top of the excellent upstream joycontrol work:

• mart1nro/joycontrol

JoyControl

An app for controlling Nintendo Switch from a Mac via Raspberry Pi.

Macからラズパイ経由でNintendo Switchを操作するアプリです。

JoyControl は、Nintendo Switch へコントローラー入力や JSON ベースのマクロを送るための、macOS アプリと Raspberry Pi ブリッジで構成されたプロジェクトです。Mac 側は UI、接続フロー、診断、マクロ操作を担当し、Raspberry Pi 側は Pro Controller として振る舞う Bluetooth ブリッジとして動作します。

このリポジトリは、ローカル環境の絶対パスや個人向けメモを含めず、そのまま GitHub で公開しやすいように整理しています。

• macOS アプリ側の接続・再接続まわりの不具合を修正
• Pi 実行マクロのループ安定性と完了処理を改善
• 有限ループが正常完了したときに、明るくやさしいシステム音を鳴らすように対応
• Mac に直接つないだゲームコントローラー入力の転送に対応
• これにより、PS5 コントローラーなどを Macコントローラー -> JoyControl macOSアプリ -> Raspberry Pi -> Nintendo Switch の流れで使えるようになりました

JoyControl は次の 2 つで構成されています。

• 接続、手動操作、マクロ選択、ループ実行を担当する macOS アプリ
• Bluetooth スタックを動かし、Switch へ入力を送る Raspberry Pi ブリッジ

基本的な流れは次の通りです。

1. Pi ブリッジを起動する
2. macOS アプリを開く
3. Switch と接続または再ペアする
4. 手動操作または JSON マクロを実行する

• Raspberry Pi 経由で Nintendo Switch に接続
• macOS 側の単一フローでペアリングと再接続に対応
• Mac からの手動ボタン操作とスティック操作
• JSON マクロ実行
• 対応マクロのループ実行
• ペアリングや bridge 問題のための診断機能

• work/joycontrol-macos
  • macOS アプリ本体
• Pi
  • Raspberry Pi bridge のバックアップとインストール用ファイル
• samples
  • 例として使える JSON マクロ
• README_MAC_SETUP.md
  • macOS セットアップ補足
• README_MACRO.md
  • マクロ形式やマクロ関連メモ
• README_PI_BRIDGE.md
  • 旧 bridge メモ

• macOS
• Xcode
• Bluetooth が使える Mac

• Bluetooth 対応 Raspberry Pi
• Raspberry Pi OS
• Python 3
• sudo 権限

• Nintendo Switch

macOS アプリ本体は work/joycontrol-macos にあります。

1. work/joycontrol-macos/joycontrol-macos.xcodeproj を Xcode で開く
2. joycontrol-macos ターゲットをビルドして実行する
3. Mac の Bluetooth が通常通り使えることを確認する

セットアップ詳細は README_MAC_SETUP.md を参照してください。

公開用にまとめた Pi 側ファイルは Pi にあります。

1. Pi フォルダを Raspberry Pi にコピーする
2. Pi 上でそのディレクトリへ移動する
3. 次を実行する

./install.sh

詳細は次を参照してください。

• Pi/README.md

Raspberry Pi 上で:

cd ~/PokeMacro-Pi
sudo MODE=pair ./run_macro_bridge_stack.sh <SWITCH_BT_ADDR>

その後 Switch 側で:

1. Controllers を開く
2. Change Grip/Order を開く

その後 Mac アプリで:

1. 接続 を押す
2. ペアリングを完了する
3. 必要に応じて A で確定する

Raspberry Pi 上で:

cd ~/PokeMacro-Pi
sudo MODE=reconnect ./run_macro_bridge_stack.sh <SWITCH_BT_ADDR>

その後、macOS アプリで同じ 接続 フローを使います。

サンプルマクロは samples と work/joycontrol-macos/samples に入っています。

含まれている例:

• mash_a.json
• frlg02_startup_sync.json
• frlg02_sweet_scent_shinyhunt.json

マクロ関連の補足:

• README_MACRO.md

• このプロジェクトでは Raspberry Pi を Bluetooth コントローラーブリッジとして使います
• Switch 側に古いコントローラー登録が残っていると、再ペアが必要になることがあります
• 一部の自動化フローはタイミングやゲーム内状態に依存します
• 色違い厳選系のサンプルは補助用であり、完全な状態認識付きボットではありません

• このプロジェクトは Nintendo とは無関係であり、承認も受けていません
• 使用は自己責任でお願いします
• Pi 側で Bluetooth を再起動するため、他の Bluetooth 機器への影響に注意してください

このプロジェクトは、優れた upstream joycontrol をベースにしています。

• mart1nro/joycontrol

JoyControl

An app for controlling Nintendo Switch from a Mac via Raspberry Pi.