↓ メインコンテンツへスキップ
Tech Yoshiki

SwitchBot API v1.1 入門ガイド

·317 文字·2 分
Switchbot Python IoT スマートホーム API

はじめに
#

SwitchBotは、照明、カーテン、エアコンなどを制御できる人気のスマートホームプラットフォームです。あまり知られていませんが、SwitchBotはオープンAPIを提供しており、デバイスをプログラムで制御できます。

この記事では、PythonでSwitchBot API v1.1をセットアップする方法を解説します。

前提条件
#

  • SwitchBotアカウント（デバイスが1台以上あること）
  • Python 3.8以上
  • requests と python-dotenv パッケージ
pip install requests python-dotenv

ステップ1：APIクレデンシャルの取得
#

  1. スマートフォンでSwitchBotアプリを開く
  2. プロフィール → 設定 に移動
  3. アプリバージョンを10回タップして開発者オプションを有効化
  4. 開発者オプションに移動
  5. トークンとシークレットキーをコピー

ステップ2：クレデンシャルの安全な保管
#

プロジェクトディレクトリに .env ファイルを作成：

SWITCHBOT_TOKEN=あなたのトークン
SWITCHBOT_SECRET=あなたのシークレットキー

重要: このファイルは絶対にgitにコミットしないこと！.gitignore に .env を追加してください。

ステップ3：認証
#

SwitchBot API v1.1はHMAC-SHA256を使用して認証します。すべてのリクエストには、トークン、タイムスタンプ、ノンス、署名を含むヘッダーが必要です。

認証関数：

import hashlib
import hmac
import base64
import time
import uuid
import os
import requests
from dotenv import load_dotenv

load_dotenv()

API_BASE = "https://api.switch-bot.com/v1.1"
TOKEN = os.getenv("SWITCHBOT_TOKEN", "")
SECRET = os.getenv("SWITCHBOT_SECRET", "")

def generate_headers(token: str, secret: str) -> dict:
    """SwitchBot API v1.1の認証ヘッダーを生成"""
    nonce = str(uuid.uuid4())
    t = str(int(time.time() * 1000))
    string_to_sign = f"{token}{t}{nonce}"
    sign = base64.b64encode(
        hmac.new(
            secret.encode("utf-8"),
            string_to_sign.encode("utf-8"),
            hashlib.sha256,
        ).digest()
    ).decode("utf-8")

    return {
        "Authorization": token,
        "sign": sign,
        "nonce": nonce,
        "t": t,
        "Content-Type": "application/json; charset=utf8",
    }

仕組み：
#

  1. ランダムなノンス（UUID）とタイムスタンプ（ミリ秒）を生成
  2. 文字列を作成：トークン + タイムスタンプ + ノンス
  3. シークレットキーでHMAC-SHA256署名
  4. 署名をBase64エンコード
  5. すべての値をリクエストヘッダーに含めて送信

ステップ4：デバイス一覧の取得
#

def get_devices(token: str, secret: str) -> dict:
    """すべてのSwitchBotデバイスを取得"""
    headers = generate_headers(token, secret)
    response = requests.get(f"{API_BASE}/devices", headers=headers)
    response.raise_for_status()
    return response.json()

# 全デバイスを表示
result = get_devices(TOKEN, SECRET)
for device in result["body"]["deviceList"]:
    print(f"{device['deviceName']} ({device['deviceType']}) - {device['deviceId']}")

出力例：

リビング照明 (Color Bulb) - ABCDEF123456
寝室カーテン (Curtain3) - 123456ABCDEF

ステップ5：デバイスステータスの取得
#

def get_device_status(token: str, secret: str, device_id: str) -> dict:
    """特定デバイスのステータスを取得"""
    headers = generate_headers(token, secret)
    response = requests.get(
        f"{API_BASE}/devices/{device_id}/status", headers=headers
    )
    response.raise_for_status()
    return response.json()

status = get_device_status(TOKEN, SECRET, "デバイスID")
print(status)

ステップ6：コマンドの送信
#

def send_device_command(token: str, secret: str, device_id: str,
                        command: str, parameter: str = "default",
                        command_type: str = "command") -> dict:
    """デバイスにコマンドを送信"""
    headers = generate_headers(token, secret)
    payload = {
        "command": command,
        "parameter": parameter,
        "commandType": command_type,
    }
    response = requests.post(
        f"{API_BASE}/devices/{device_id}/commands",
        headers=headers,
        json=payload,
    )
    response.raise_for_status()
    return response.json()

# 照明をオンにする
send_device_command(TOKEN, SECRET, "DEVICE_ID", "turnOn")

# 明るさを50%に設定
send_device_command(TOKEN, SECRET, "DEVICE_ID", "setBrightness", "50")

# 色を設定（RGB）
send_device_command(TOKEN, SECRET, "DEVICE_ID", "setColor", "255:100:0")

よく使うデバイスコマンド
#

デバイスタイプコマンドパラメータ
Color BulbturnOn / turnOffdefault
Color BulbsetBrightness1-100
Color BulbsetColorR:G:B (0-255)
カーテンturnOn（開）/ turnOff（閉）default
カーテンsetPosition0-100
BotturnOn / turnOff / pressdefault

次のステップ
#

次回の記事では以下を解説予定です：

  • Webhookを使ったリアルタイムデバイス更新の受信
  • TkinterでGUIコントローラーを構築
  • APIによるシーンとオートメーションの作成

ソースコードはGitHubで公開しています。

Happy automating！