SwitchBot WebAPI/BLE API 開発者向け情報源まとめ〜APIドキュメントからオープンソースまで
このブログ「テック大家さん」でも何度も取り上げているSwitchBot。絶賛推し活中です。
推しの理由は、以前の記事「SwitchBotでスマートホーム 選択する３つの理由」でも書きましたが、筆者が最も注目しているのは開発者向けの機能が充実していることです。
https://tech-landlord.com/articles/need-to-choice-swtichbot-...Web APIの仕様だけでなく、Bluetooth Low Energy (BLE)のプロトコル仕様までオープンになっています。
これは、スマートホームを自主開発（インテグレーション）したいマニア不動産オーナーだけでなく、一般の生活者が趣味でDIYするにも、何かと便利です。テック好きには”そそる”状態と言えましょう。
そんな、SwitchBotですが、ドキュメント化されている仕様だけなく、ソースコードとしてオープンになっている仕様があるということに最近気づきました。現在調査中なのですが、その状況も含めて少し整理をしておこうというのが本記事の意図です。
以下に整理していきます。
SwitchBot API v1.1
１つ目は、WonderLabs（公式？）のSwitchBotのWeb APIの仕様です。ドキュメントがGithubにて公開されています。
このブログでも何度か取り上げていますが、もっとも基本的な情報源です。
開発者は、この仕様通りにクライアントを作れば、SwitchBot製品が屋内・屋外問わずインターネット経由で操作できるようになります。
https://github.com/OpenWonderLabs/SwitchBotAPI当ブログでは、SwitchBot Web APIの使用方法にや仕組みに関して、以下のように、いくつかのユースケースで解説しています。
- SwitchBot Web APIで究極のDIYスマートホームの可能性を探る
- Node.jsでスマートロックを解錠する SwitchBot APIで究極のスマートホーム
- SwitchBotで赤外線リモコン Web APIでリモートから機器操作
- Fitbit Versa 4でSwitchBotを制御する Web APIでトラッカーによる充実スマートホーム体験!?
SwitchBotAPI-BLE
２つ目は、WonderLabs（公式？）のSwitchBotのBLE APIの仕様です。Bluetooth Low Energy、近距離無線通信の規格ですね。
こちらも、基本的な情報源で、ドキュメントがGithubにて公開されています。
近距離通信の規格なので、SwitchBot製品を宅内の無線通信可能な距離にある場合に操作できるようなクライアントが開発できます。
ただし、この仕様書で扱われている機器はWeb APIで扱っている機器と比較して、ごく限られたものになっています。また、プログラムできる操作もWeb APIよりも限定的です。
BLEのメリットはクライアントとSwitchBot製品が直接通信するので、ネット経由よりも遅延が少なくできる可能性がある、というところです。WiFiなどのネット環境がないところでも無線通信できるのもメリットですね。
https://github.com/OpenWonderLabs/SwitchBotAPI-BLE当ブログでも、ESP32のような組み込み機器でクライアントをつくるケースで解説を行っています。
- SwitchBot API BLEを使う スマートホームの救世主か？遅延がないから快適！
- SwitchBot BLE API で機器にBluetoothで直接コマンドを送る ESP32でスマートホームをもっと便利に
ここで、Web APIとBLEの仕組みと全体像を図示しておきます。
注意点としては、以前の解説記事にもあるように、Web APIを使う場合には操作したい機器以外に「ハブ」という製品が必要になることです。
node-switchbot
次の情報源は、node-switchbotというライブラリです。Githubでソースコードが公開されています。
こちらのライブラリは、各種SwitchBot製品とBLEで通信するためのものです。NodeJSで書かれたライブラリになっています。BLE通信には、 @abandonware/nobleというNodeJSのBluetoothライブラリを使っています。
GithubのリポジトリはWonderLabs（公式？）のものですが、unofficialのコードであると書かれています。unofficialが意味するところがよくわかりませんが、おそらく、インターフェース仕様が将来変わったとしてもサポートしませんよ、といったところでしょうか。
この情報源のポイントは、上述の「SwitchBotのBLE APIの仕様」のドキュメントにはない機能も実装されていることです。
たとえば、筆者が賃貸経営でぜひとも使ってみたいと考えているスマートロックですが、BLE仕様のドキュメントにはロックのコマンドが書かれていません。ロックが非公開なのはセキュリティの問題からなのかと想像していたのですが、node-swtichbotにはBLE経由でのロック施錠・解錠が実装されています。
すこしコードを解析してみたのですが、BLE通信は暗号化した上で通信する必要があるようです（安全性の面から、当然といえば当然ですが…）。
暗号化通信の詳細については、別の記事に詳しく書きました。こちらも併せてご覧ください。
node-swtichbot のgithub 上のリンクは以下になります。
https://github.com/OpenWonderLabs/node-switchbotpySwitchbot
次の情報源は、pySwitchbotというライブラリです。Githubでソースコードが公開されています。
こちらのライブラリも上述のnode-switchbot同様、各種SwitchBot製品とBLEで通信するためのものです。Pythonで書かれたライブラリになっています。
ただし、このリポジトリのreadmeをみても、ライブラリの使い方に関する情報が書かれていません。実装から推測して使わないといけないのではないでしょうか。
このライブラリも、node-switchbot同様に「SwitchBotのBLE APIの仕様」のドキュメントにはない機能も実装されているようです。また、スマートロックのBLE暗号通信を行うための、暗号キーを取得するコード（ツール）が実装されています。node-switchbotのライブラリで暗号通信を行う上でもこのツールが必要になります。
https://github.com/Danielhiversen/pySwitchbot暗号キーの取得に関しては、これまたドキュメントがネット上見当たらないSwitchBotのクラウドのWeb APIを使って取得しています。(Web APIとは異なる api.switchbot.netというドメインを使っている模様）
筆者は、現在BLEの暗号通信周りに関して、これらの情報源からソースコードを読んで調査しています。今後このブログで整理して記事にしていく予定です。お楽しみに！
python-host
最後は、WonderLabs（公式？）のリポジトリにある、python-hostというコマンドラインツールです。こちらは「公式」らしいです。BLE通信でSwitchBotにコマンドを送るツールで名前のとおりPythonで書かれています。
とても短いコードで作られているので参考にするには見通しがよいプログラムです。
ただし、対応しているのは非常に限られたSwitchBot製品とコマンドです。「SwitchBotのBLE APIの仕様」に書かれている内容を実装するとこうなります、というイメージで参照するようなものなのかも知れません。
https://github.com/OpenWonderLabs/python-hostまとめ
SwtichBot製品をプログラムから制御することを目的に、公開されている技術ドキュメント、オープンソースのライブラリに関する情報をまとめました。
大きく分けると、Web API を使う方法と Bluetooth Low Energy (BLE)を使う方法があります。前者は様々の名プロットフォーム・言語で使えるようなものになっています。一方、後者のBLEの方は、公開されている技術ドキュメントでは、操作できない機器があります。例えばロックなど。
筆者のように、ESP32などの小型の機器でSwitchBot製品と通信させたいと考えている場合は、オープンソースであるNodeJSやPythonのライブラリのコードを解析して、ポーティングする必要がありそう。
今後、解析できた情報を本ブログ上で公開してSwitchbot推し活を進化させる所存です。お楽しみに！
プロフィール
-
ソフトエンジニア兼不動産オーナー。
某超有名日本メーカーにおいてソフトウエア開発畑を30年近く勤務。
かつてはWindowsのアプリ開発や、組み込み機器のソフト開発を行う。プロジェクトマネジメント・オフショア開発・要件管理などの経験あり。現在は、個人開発で、JavaScript/TypeScript/React/Express、PHP/Laravel、Firebase、Google cloud、Arduino(C++)などでプログラミングを楽しむ。
サラリーマンの傍ら不動産経営を始め、現在、１棟モノの賃貸４物件を東京・神奈川に所有。夫婦でおよそ20年の賃貸経営の実績。
最近の物件では、入居者向けフリーWiFiなど、テック系の設備はDIYで自ら構築。
海外MBA取得。