# SmartMouse

> スマートフォンのブラウザからWindows PCのマウス・キーボードを操作できるツール。

- 制作: [ワカメ](https://wakame.dev/)（個人で企画・開発）
- ステータス: 公開中（v0.5.4）
- 制作期間: 継続アップデート中
- カテゴリ: Tool, Python, Web
- 使用技術: Python, FastAPI, Uvicorn, WebSocket, TypeScript, Vite, PyInstaller, Bonjour, QRコード
- 担当: アイデア設計, 通信プロトコル設計, Windows受信アプリ開発, ブラウザ版クライアント開発, exe化・配布設計, 配布後の不具合対応

## 概要

手元にマウスがない環境でもPCを操作できるようにするため、個人で企画・開発したツールです。Windows側の受信アプリ（Receiver）はPythonとFastAPI / Uvicornで実装し、PyInstallerでexe化して配布しています。スマホ側はアプリのインストールが不要なブラウザ版（TypeScript / Vite）で、Receiverに同梱して配信しています。Receiver画面のQRコードをスマホの標準カメラで読むだけで接続できます。接続にはReceiver起動ごとに変わる128bitのトークン認証を導入し、Bonjourによる自動検出と自動再接続にも対応。カーソル移動・クリック・スクロールに加えて、文字入力の送信やコピー／貼り付けまで実装しています。タスクトレイ常駐での運用や、Windows Defenderに誤検知されたときの対処など、「実際に配布したときに起きる問題」まで踏み込んで解決しました。

## 「インストールしてもらう」を諦めた

手元にマウスが無い場面で使うツールなので、使いたい瞬間にアプリストアからのインストールを挟むと、その時点で目的を果たせません。そこでスマホ側の本命をブラウザ版にして、Windows側の受信アプリ（Receiver）に同梱・配信する形にしました。使う人がやることは、Receiverの画面に出たQRコードを標準のカメラアプリで読むことだけです。

一方で、Bonjourによる自動検出や触覚フィードバックなど、ブラウザでは扱えない機能を使いたい場合に向けてSwiftUI製のiOSアプリ版も用意しています。QRコードは両方で共通で、iOSアプリ側がURLをWebSocketのアドレスに読み替えて接続します。

## 合言葉とプロトコル番号で、つながらない事故を減らす

同じWi-Fiにいる誰でも繋がってしまうと、他人のPCのカーソルが動かせることになります。そのためReceiverは起動ごとに変わる合言葉（token）を要求し、合言葉なしのアドレスは拒否します。接続先の入手経路は、QRコード・Bonjourの自動検出・Receiver画面の表示の3通りです。

配布を続けるうちに問題になったのがバージョンの食い違いです。クライアントはReceiverがプロトコル2を返すことを要求するため、初期の配布版（v0.1.0、プロトコル1）では接続時に更新を促されて繋がりません。やっかいなのは、配布パッケージのファイル名に付くバージョンとコード側のバージョン値が独立していて、ファイル名だけでは判断できないことです。そこで稼働中のReceiverに直接問い合わせて実際の値を確認できるヘルスチェック用のURLを用意し、切り分けをそこに寄せました。

## 再接続を「使う人が何も考えなくていい」状態にする

一度読み取った接続先は保存され、Receiverが起動したままならアプリを開き直すだけで自動的に繋がります。Receiverを再起動して合言葉が変わった場合は、Bonjourで新しいReceiverを見つけ次第つなぎ直し、それでも見つからないときにだけQRコードの読み取りを案内します。

「まずQRを読んでください」と毎回出す作りは実装は簡単ですが、日常的に使うツールとしては煩わしいので、案内を出すのを最後の手段にしました。

## マウスの代わりではなく、片手で完結する入力装置にする

カーソルを動かせるだけでは、結局PCの前まで行くことになります。そこで操作を増やし、スマホ側だけで一通りの作業が終わる形にしました。

- 1本指ドラッグでカーソル移動、タップで左クリック、ダブルタップでダブルクリック
- 2本指タップで右クリック、2本指の上下ドラッグでスクロール（右端のスクロールバーでも可）
- 長押しドラッグと「つかむ／離す」で、左ボタンを押したままの移動に対応
- 文字入力欄から文章をWindowsへ貼り付け、エンターまで送信。⌫は入力欄が空ならWindows側へBackspaceを送る
- Windows側のコピー／貼り付けをスマホのボタンから実行
- 亀〜兎のスライダーでカーソル感度を0.5〜3.0倍に調整

## LAN内限定という割り切りと、配布後に出た問題

この仕組みはLAN内の接続専用で、Receiverをインターネットへ公開しない前提で設計しています。外から使える利便性より、他人にカーソルを奪われない安全側を取りました。

また、PyInstallerでexe化した配布物はWindows Defenderに誤検知されることがあります。動かない理由が分からないまま諦められてしまうため、検知されたときの対処まで配布物の説明に含めました。実装が終わってからが本番になる部分です。

Receiverはタスクトレイに常駐し、ウィンドウを閉じてもWindows右下のアイコンからQRコードを再表示できます。

## 成果

- Windows向けアプリとしてGitHubで公開・配布
- インストール不要のブラウザ版クライアントをReceiverに同梱
- トークン認証と自動再接続を実装（プロトコル2）
- 公開から7日間で8回リリース（v0.1.0 → v0.5.4）
- 配布時のWindows Defender誤検知に対応

## リンク

- [ダウンロード](https://github.com/bluewakame/SmartMouse/releases)
- [GitHub](https://github.com/bluewakame/SmartMouse)

## 関連動画

- [【Windows】あなたのスマホがマウスになるソフトSmartMouse](https://www.youtube.com/watch?v=EScS3ujs2-4): マウスが壊れてもスマホがあれば大丈夫。PC画面のQRコードをスマホのカメラで読むだけでマウスとして使える「SmartMouse」の紹介動画です。

## このサイトについて

- [ワカメの詳細プロフィール](https://wakame.dev/ai-profile/index.html.md)
- [llms.txt](https://wakame.dev/llms.txt)