Add Readme #2
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,102 @@ | ||
| # Device Support Matrix / 対応デバイス一覧 | ||
|
|
||
| This table lists all device and appliance types mentioned in `SwitchBotApiDocuments.md` (API v1.1) and their support status in this app. | ||
| この表は、`SwitchBotApiDocuments.md`（SwitchBot API v1.1）に記載されているデバイス・家電カテゴリと、本アプリでの対応状況をまとめたものです。 | ||
|
|
||
| > Note / 備考: | ||
| > For now, all devices are marked as `?` (unknown / 未検証). | ||
|
|
||
| ## Status legend / ステータス凡例 | ||
|
|
||
| - `〇`: Fully supported (major features implemented) | ||
| 完全対応（主要な操作・表示に対応） | ||
| - `△`: Partially supported (only some operations or views) | ||
| 一部対応（一部の操作・表示のみ対応） | ||
| - `?`: Unknown / not yet verified | ||
| 未検証（対応未確認） | ||
| - `×`: Not supported | ||
| 非対応 | ||
|
|
||
| ## Device list / デバイス一覧 | ||
|
|
||
| | Device | Status | Notes / メモ | | ||
| |--------|--------|-------------| | ||
| | Air Conditioner | △ | | | ||
| | Air Purifier | ? | | | ||
| | Air Purifier PM2.5 | ? | | | ||
| | Air Purifier Table PM2.5 | ? | | | ||
| | Air Purifier Table VOC | ? | | | ||
| | Air Purifier VOC | ? | | | ||
| | Battery Circulator Fan | ? | | | ||
| | Blind Tilt | ? | | | ||
| | Bot | 〇 | | | ||
| | Camera | ? | | | ||
| | Ceiling Light | ? | | | ||
| | Ceiling Light Pro | 〇 | | | ||
| | Circulator Fan | ? | | | ||
| | Color Bulb | ? | | | ||
| | Contact Sensor | ? | | | ||
| | Curtain | 〇 | | | ||
| | Curtain 3 | ? | | | ||
| | DVD Player | ? | | | ||
| | Evaporative Humidifier | 〇 | | | ||
| | Evaporative Humidifier (Auto-refill) | ? | | | ||
| | Fan | ? | | | ||
| | Floor Cleaning Robot S10 | ? | | | ||
| | Floor Lamp | ? | | | ||
| | Garage Door Opener | ? | | | ||
| | Hub | ? | | | ||
| | Hub 2 | ? | | | ||
| | Hub 3 | ? | | | ||
| | Hub Mini | ? | | | ||
| | Hub Plus | ? | | | ||
| | Humidifier | 〇 | | | ||
| | K10+ Pro Combo | ? | | | ||
| | K11+ | ? | | | ||
| | K20+ Pro | ? | | | ||
| | Keypad | ? | | | ||
| | Keypad Touch | ? | | | ||
| | Keypad Vision | ? | | | ||
| | Light | ? | | | ||
| | Lock | ? | | | ||
| | Lock Lite | ? | | | ||
| | Lock Pro | ? | | | ||
| | Lock Ultra | ? | | | ||
| | Meter | 〇? | | | ||
|
There was a problem hiding this comment. The status |
||
| | Meter Plus (JP) | ? | | | ||
| | Meter Plus (US) | ? | | | ||
| | Meter Pro | ? | | | ||
| | Meter Pro CO2 | ? | | | ||
| | Mini Robot Vacuum K10+ | ? | | | ||
| | Mini Robot Vacuum K10+ Pro | ? | | | ||
| | Motion Sensor | ? | | | ||
| | Others | ? | | | ||
| | Outdoor Meter | ? | | | ||
| | Plug | 〇 | | | ||
| | Plug Mini (EU) | ? | | | ||
| | Plug Mini (JP) | 〇 | | | ||
| | Plug Mini (US) | ? | | | ||
| | Projector | ? | | | ||
| | RGBIC Neon Wire Rope Light | ? | | | ||
| | RGBICWW Floor Lamp | ? | | | ||
| | RGBICWW Strip Light | ? | | | ||
| | Relay Switch 1 | ? | | | ||
| | Relay Switch 1PM | ? | | | ||
| | Relay Switch 2PM | ? | | | ||
| | Robot Vacuum Cleaner | ? | | | ||
| | Robot Vacuum Cleaner S1 | ? | | | ||
| | Robot Vacuum Cleaner S1 Plus | ? | | | ||
| | Roller Shade | ? | | | ||
| | S20 | ? | | | ||
| | Set Top Box | ? | | | ||
| | Smart Fan | ? | | | ||
| | Smart Radiator Thermostat | ? | | | ||
| | Speaker | ? | | | ||
| | Streamer | ? | | | ||
| | Strip Light | ? | | | ||
| | Strip Light 3 | ? | | | ||
| | TV | ? | | | ||
| | Video Doorbell | ? | | | ||
| | Water Heater | ? | | | ||
| | Water Leak Detector | ? | | | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,90 @@ | ||
| # SwitchBot Controller | ||
|
|
||
| [English README is here](README_en.md) | ||
|
|
||
| Electron デスクトップクライアントで SwitchBot Cloud API を操作し、デバイスの状態確認・操作・シーン実行を行うアプリです。React (Vite) + MUI + Redux Toolkit を採用し、英語/日本語 UI に対応しています。 | ||
|
|
||
| 本アプリのコードの約 99% は AI によって自動生成されており、人間による完全な動作確認やコードレビューは行われていません。 | ||
| 本アプリの利用により、お使いのコンピュータ、SwitchBot デバイス、アカウント、ネットワーク環境などにいかなる不具合・損害が発生した場合でも、作者は一切の責任を負いません。自己責任でご利用ください。 | ||
|
|
||
| ## 主な機能 | ||
| - デバイス一覧表示と絞り込み、詳細画面でのステータス確認 | ||
| - デバイスごとの操作パネル（物理デバイスの状態取得、赤外線リモコンのカスタムコマンド実行） | ||
| - シーン一覧の取得とワンクリック実行 | ||
| - API トークン / シークレットの保存・検証、ポーリング間隔やテーマ (light/dark/system)・言語 (en/ja) 設定 | ||
| - 前回開いていた画面の復元とデバイスステータスの自動ポーリング | ||
|
|
||
| ## 対応デバイス一覧 | ||
|
|
||
| 公式 SwitchBot API ドキュメント（`SwitchBotApiDocuments.md`）に記載されているデバイスと、本アプリにおける対応状況（`〇` / `△` / `?` / `×`）の一覧は、[Device Support Matrix / 対応デバイス一覧](DEVICE_SUPPORT_MATRIX.md) を参照してください。 | ||
|
|
||
| ## アプリの使い方（エンドユーザー向け） | ||
| 1. SwitchBot 公式モバイルアプリから Cloud API の **Open Token** と **Secret Key** を取得します。 | ||
| （「クラウドサービス」→ 開発者向けメニュー。詳しくは SwitchBot の公式ドキュメントを参照してください。） | ||
| 2. アプリを起動します。 | ||
| - パッケージ済みバイナリをお持ちの場合：インストーラ等から通常のデスクトップアプリとしてインストール・起動します。 | ||
| - ソースコードから起動する場合は、後述の「開発者向けセットアップ」を参照してください。 | ||
| 3. 画面上部のタブから `Settings` を開きます。 | ||
| 4. **Open Token** と **Secret Key** を入力し、`Validate and Save` ボタンを押します。 | ||
| - 検証に成功すると、認証情報がローカルに保存され、アプリから SwitchBot Cloud API にアクセスできるようになります。 | ||
| - `Clear Stored Credentials` で保存済みの認証情報を削除できます。 | ||
| 5. 必要に応じて以下を設定します。 | ||
| - **Polling Interval**：物理デバイスのステータスを定期的に取得する間隔（秒）。`0` にするとポーリングを無効化。 | ||
| - **Theme**：`Light` / `Dark` / `Follow System`（OS のテーマに追従）。 | ||
| - **Language**：`English` / `Japanese`。 | ||
| 6. `Devices` タブを開きます。 | ||
| - デバイス一覧からステータスを確認し、詳細画面を開いてより詳細な情報を確認できます。 | ||
| - 対応している物理デバイスでは、ON/OFF や位置・モード変更などの操作が可能です。 | ||
| - 赤外線リモコンについては、登録済みのカスタムコマンドを UI から実行できます。 | ||
| 7. `Scenes` タブでは： | ||
| - SwitchBot Cloud 上のシーン一覧を取得し、 | ||
| - ワンクリックでシーンを実行できます。 | ||
|
|
||
| ## 開発者向けセットアップガイド | ||
|
|
||
| ### 1. リポジトリのクローンと依存関係のインストール | ||
| ```bash | ||
| git clone https://github.com/0suu/SwitchBotController.git | ||
| cd SwitchBotController | ||
| npm install | ||
| ``` | ||
|
|
||
| ### 2. 開発サーバーの起動（ホットリロード） | ||
| ```bash | ||
| npm run dev | ||
| ``` | ||
| Vite (renderer) と Electron (main) が並行起動します。 | ||
| 起動後、Settings 画面から API Token / Secret を登録・検証してください。 | ||
|
|
||
| ### 3. テスト | ||
| ```bash | ||
| npm test # 単体テスト | ||
| npm run test:coverage | ||
| ``` | ||
|
|
||
| ### 4. ビルド & パッケージング | ||
| ```bash | ||
| npm run build # renderer と main のビルド | ||
| npm run package # 各プラットフォーム向けインストーラを release/ に出力 | ||
| ``` | ||
| macOS / Linux 向けビルドでは `assets/icon.icns` と `assets/icon.png` が必要です（存在しない場合は独自のアイコンに差し替えてください）。 | ||
|
|
||
| Electron Builder の設定 (`package.json` の `build` フィールド) により、アプリ ID や配布ターゲット、アイコンなどが制御されます。 | ||
|
|
||
| ## 必要環境 | ||
| - Node.js 20 以上推奨（Electron 36 ベース） | ||
| - npm | ||
| - SwitchBot アカウントの API Token / Secret（アプリ内「Settings」で入力・検証） | ||
|
|
||
| ## 主要ディレクトリ | ||
| - `src/main/` … Electron メインプロセス。SwitchBot API への IPC ハンドラと `electron-store` による設定・認証情報の保存を行います。 | ||
| - `src/preload/` … コンテキスト分離された bridge (`electronStore` / `switchBotBridge`) を公開します。 | ||
| - `src/renderer/` … React + Vite フロントエンド。デバイス一覧 / 詳細 / シーン / 設定画面を実装しています。 | ||
| - `src/api/` … SwitchBot API の型定義とラッパー。 | ||
|
|
||
| ## セキュリティの注意 | ||
| `electron-store` で API トークンとシークレットを保存しています。 | ||
| デフォルトでは暗号化されずローカルユーザーが読み取れるため、配布時は `src/main/main.ts` の `encryptionKey` を設定するか、OS キーチェーンを利用するなど、安全な秘匿方法を検討してください。 | ||
|
|
||
| ## ライセンス | ||
| ISC License |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,99 @@ | ||||||
| # SwitchBot Controller | ||||||
|
|
||||||
| [日本語のREADMEはこちら](README.md) | ||||||
|
|
||||||
| Electron-based desktop client for controlling your SwitchBot devices via the official SwitchBot Cloud API. | ||||||
| Built with React (Vite) + MUI + Redux Toolkit, and supports both English and Japanese UI. | ||||||
|
|
||||||
| Approximately 99% of this app’s source code was generated by AI, and it has not undergone thorough manual testing or code review by humans. | ||||||
| The author assumes no responsibility or liability for any issues, malfunctions, or damages affecting your computer, SwitchBot devices, account, or network environment that may arise from using this software. Use it entirely at your own risk. | ||||||
|
|
||||||
| ## Features | ||||||
| - List all devices with filtering and detail view | ||||||
| - Control supported physical devices (status retrieval, on/off, position, etc.) | ||||||
| - Send custom commands to infrared remote devices registered in SwitchBot | ||||||
| - List and execute scenes with a single click | ||||||
| - Store and validate API Token / Secret, configure polling interval, theme (light/dark/system), and language (en/ja) | ||||||
| - Restore last opened screen and automatically poll device status in the background | ||||||
|
|
||||||
| ## Supported Devices | ||||||
|
|
||||||
| See [Device Support Matrix / 対応デバイス一覧](DEVICE_SUPPORT_MATRIX.md) for the full list of devices from the official SwitchBot API documentation and their support status (`〇` / `△` / `?` / `×`) in this app. | ||||||
|
|
||||||
| ## Requirements | ||||||
| - Node.js 20 or later (recommended, Electron 36 based) | ||||||
| - npm | ||||||
| - A SwitchBot account and Cloud API **Open Token** and **Secret Key** (configured inside the app under `Settings`) | ||||||
|
|
||||||
| ## How to Use the App (End Users) | ||||||
| 1. Get your SwitchBot Cloud API **Open Token** and **Secret Key** from the official SwitchBot mobile app | ||||||
| (Cloud Services → Developer options; see the official SwitchBot documentation for details). | ||||||
| 2. Start the app: | ||||||
| - If you have a packaged build (installer / AppImage / dmg): install and launch it as a normal desktop application. | ||||||
| - If you are running from source, see the “Developer Setup” section below and run `npm run dev` or `npm run start`. | ||||||
|
There was a problem hiding this comment. The instructions mention running
Suggested change
|
||||||
| 3. Open the `Settings` tab in the top app bar. | ||||||
| 4. Enter your **Open Token** and **Secret Key**, then click `Validate and Save`. | ||||||
| - If validation succeeds, the app stores the credentials locally and automatically starts using them. | ||||||
| - You can clear stored credentials at any time using `Clear Stored Credentials`. | ||||||
| 5. (Optional) Configure: | ||||||
| - **Polling Interval**: how often physical device statuses are refreshed (seconds). Set `0` to disable polling. | ||||||
| - **Theme**: `Light`, `Dark`, or `Follow System`. | ||||||
| - **Language**: `English` or `Japanese`. | ||||||
| 6. Switch to the `Devices` tab: | ||||||
| - Check device status in the list and open details to view more properties. | ||||||
| - For supported devices, use the control panel to perform operations (e.g., on/off, mode change). | ||||||
| - For infrared remotes, execute registered commands from the UI. | ||||||
| 7. Switch to the `Scenes` tab: | ||||||
| - Load scenes from your SwitchBot Cloud account. | ||||||
| - Execute scenes with one click. | ||||||
|
|
||||||
| ## Developer Setup Guide | ||||||
|
|
||||||
| ### 1. Clone and install | ||||||
| ```bash | ||||||
| git clone https://github.com/0suu/SwitchBotController.git | ||||||
| cd SwitchBotController | ||||||
| npm install | ||||||
| ``` | ||||||
|
|
||||||
| ### 2. Development run (hot reload) | ||||||
| ```bash | ||||||
| npm run dev | ||||||
| ``` | ||||||
| This starts Vite (renderer) and Electron (main) in parallel. | ||||||
| After startup, open the `Settings` screen and register / validate your API Token and Secret. | ||||||
|
|
||||||
| ### 3. Tests | ||||||
| ```bash | ||||||
| npm test # Run unit tests | ||||||
| npm run test:coverage | ||||||
| ``` | ||||||
|
|
||||||
| ### 4. Build & packaging | ||||||
| ```bash | ||||||
| npm run build # Build renderer and main | ||||||
| npm run package # Generate platform-specific installers into release/ | ||||||
| ``` | ||||||
| On macOS / Linux builds, make sure the following assets exist (replace with your own if necessary): | ||||||
| - `assets/icon.icns` | ||||||
| - `assets/icon.png` | ||||||
|
|
||||||
| Electron Builder uses the configuration defined in `package.json` (`build` field) for app ID, product name, and targets. | ||||||
|
|
||||||
| ## Project Structure (Overview) | ||||||
| - `src/main/` – Electron main process. Exposes IPC handlers for SwitchBot API and manages `electron-store` for settings and credentials. | ||||||
| - `src/preload/` – Preload scripts that bridge the main process and renderer (e.g., `electronStore`, `switchBotBridge`). | ||||||
| - `src/renderer/` – React + Vite frontend implementing device list/detail, scenes, and settings screens. | ||||||
| - `src/api/` – SwitchBot API type definitions, helpers, and request wrappers. | ||||||
|
|
||||||
| ## Security Notes | ||||||
| - API Token and Secret Key are stored using `electron-store`. | ||||||
| By default these values are not encrypted and can be read by the local OS user. | ||||||
| - For production distribution, consider: | ||||||
| - Setting an `encryptionKey` in `src/main/main.ts`, or | ||||||
| - Using a platform-specific secure storage mechanism (e.g., OS keychain). | ||||||
|
|
||||||
| Handle and distribute builds with the same level of care as any application that stores API credentials. | ||||||
|
|
||||||
| ## License | ||||||
| ISC License | ||||||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The note states that "all devices are marked as
?", but the table below lists several devices with〇(Fully supported) or△(Partially supported). This is contradictory and could confuse users. Please update the note to accurately reflect the status of the device support documentation.