Codexの助けを借りてStream Deck+にHOME Assistantの機能を設定した

HOME Assistantと連携させる機器を探していたところ、ElgatoのStream Deck+があることに気がついたので、仕舞い込んでいたElgato Stream Deck+をMac miniに接続しアプリを立ち上げたところ、HOME Assistantプラグインを導入済であったが何も設定していない状態だった。本記事では、Stream Deck+に設定した下記の4つの例について紹介する。
AIの助けを借りないと設定に手間取り、試行錯誤を繰り返すこともあった。

　① スマートプラグのON/OFF
　② 温湿度センサの温度（外気温）の表示
　③ Mac miniの音量調整
　④ TV音量調整

（注）本記事の内容は正確性を保証するものではない。

（2026年5月25日 追記）YouTube動画を追加しました。　https://youtu.be/4Eu-i0oUG8Y

---

HOME Assistant プラグインの設定要領調査

（以下、ChatGPT 5.5 Thinkingの回答（抜粋））

添付画像のプラグインは、GitHub上では cgiesche/streamdeck-homeassistant として公開されている Home Assistant 用 Stream Deck プラグインです。
Stream DeckのボタンからHome Assistantのエンティティ操作やセンサー表示ができ、汎用の Entity (generic) では状態表示やサービス呼び出しができます。(GitHub)

1. 事前確認

必要なものは次の3つです。

必要なもの	内容
Stream Deck本体	Macに接続しておく
Stream Deckアプリ	Elgato公式のStream Deckアプリをインストール
Home AssistantのURLとトークン	後で入力する

プラグイン側の説明でも、前提条件は「Stream Deckアプリがインストール済み」「Stream Deckが接続済み」とされています。(GitHub)

2. プラグインをインストールする

Stream Deckアプリで行います。

1. Macで Stream Deckアプリ を開く
2. 右上または左側の Marketplace / ストア を開く
3. 検索欄で
   Home Assistant
   と検索
4. Home Assistant プラグインを選ぶ
5. Install / Get / 入手 をクリック
6. Stream Deckアプリに Home Assistant のカテゴリが追加される

このプラグインは公式Stream Deck Storeからインストールできると案内されています。(GitHub)

3. Home Assistantで長期アクセストークンを作成する

添付画像の Access-Token に入れる文字列を作ります。

1. Home Assistantをブラウザで開く
2. 左下の自分のユーザー名、またはプロフィールアイコンをクリック
3. プロフィール / Profile を開く
4. 下の方にある Long-Lived Access Tokens を探す
5. Create Token をクリック
6. 名前を入力
   例：
   Stream Deck Mac mini
7. 表示されたトークンをコピーする

Home Assistant公式ドキュメントでも、長期アクセストークンはユーザープロフィールページで作成できると説明されています。(Home Assistant)

注意点として、トークンは一度しか表示されないことがあります。必ずすぐコピーしてください。外部に見せないようにしてください。

4. 添付画像の「Home Assistant Server URL」に入力する内容

URLの例として、

ws://localhost:8123/api/websocket

と表示されていますが、通常は localhostは使わない方がよい です。

localhost は「Stream Deckアプリが動いているMac自身」を意味します。
Home Assistantが別のMac mini、仮想マシン、Home Assistant OS上で動いている場合は、localhost では接続できないことがあります。

おすすめは、Home Assistantの実際のIPアドレスを使う方法です。

たとえば、Home Assistantを普段ブラウザで次のように開いている場合：

http://192.168.0.216:8123

Stream Deckには次のように入力します。

ws://192.168.0.216:8123/api/websocket

Home AssistantのWebSocket APIは /api/websocket で提供されています。(Home Assistant Developer Docs)

URLの変換ルール

普段開いているHome AssistantのURL	Stream Deckに入れるURL
http://192.168.0.216:8123	ws://192.168.0.216:8123/api/websocket
http://homeassistant.local:8123	ws://homeassistant.local:8123/api/websocket
https://xxxx.ui.nabu.casa	wss://xxxx.ui.nabu.casa/api/websocket
https://自分のドメイン	wss://自分のドメイン/api/websocket

まずは自宅LAN内で使うと思いますので、最初は IPアドレス方式 が一番分かりやすいです。

5. Stream Deck側に入力する

添付画像の画面で、次のように入力します。

Home Assistant Server URL

例：

ws://192.168.0.216:8123/api/websocket

Access-Token

Home Assistantで作成した長期アクセストークンをそのまま貼り付けます。

入力後、下にある

Save and (re)connect

をクリックします。

接続に成功すると、下の設定欄で Home Assistant のドメインやエンティティを選べるようになります。
プラグインの説明でも、Home Assistant設定を保存すると自動的に接続を試み、成功するとエンティティ設定ができるようになるとされています。(GitHub)

6. 最初に試すおすすめ設定：スマートプラグのON/OFF（①のボタンを設定する方法）

まずは、分かりやすい switch や light で試すのがおすすめです。

1. Stream Deckアプリで、左側の Home Assistant から
   Entity (generic) をボタンにドラッグ
2. 画面下の設定で、上記のURLとトークンを保存
3. 接続できたら、下の Entity Settings を設定

例：スマートプラグを切り替える場合

項目	設定例
Domain	switch
Entity	操作したいスマートプラグ
Service	toggle
Service long press	空欄、または turn_off
Service Data JSON	通常は空欄でよい

最後に Save Configuration を押します。

これで、Stream Deckのボタンを押すと、そのスマートプラグがON/OFF切り替えされるはずです。

7. センサー値を表示する場合（②のボタンを設定する方法）

温度、湿度、電力などをStream Deckに表示することもできます。

例：

項目	設定例
Domain	sensor
Entity	sensor.xxx_temperature など
Service	空欄でよい
Custom Title	有効化
Title Template	{{state}}{{unit_of_measurement}}

プラグインは、温度、湿度、電力、電圧、バッテリー、天気などの表示にも対応しています。(GitHub)

8. うまくいかない場合の確認ポイント

1. localhost を使っていないか

Home AssistantとStream Deckアプリが完全に同じMac上で動いている場合以外は、次のようなIPアドレス指定にしてください。

ws://192.168.0.xxx:8123/api/websocket

2. Home Assistantをブラウザで開けるか

Stream Deckアプリを動かしているMacで、ブラウザから次を開けるか確認します。

http://192.168.0.xxx:8123

これが開けない場合、Stream Deckプラグインも接続できません。

3. トークンを途中で欠けさせていないか

長期アクセストークンは非常に長い文字列です。前後に空白が入ったり、一部が欠けたりすると接続できません。

4. URLの ws / wss を間違えていないか

Home Assistantの接続方式	Stream Deck側
http://	ws://
https://	wss://

5. 操作するサービスが合っているか

たとえば、

エンティティ	よく使うサービス
switch.xxx	toggle, turn_on, turn_off
light.xxx	toggle, turn_on, turn_off
script.xxx	turn_on
automation.xxx	trigger, turn_on, turn_off
scene.xxx	turn_on

最初は switch または light の toggle でテストするのが安全です。

まず入力する内容の例

Home Assistantのアドレスが仮に 192.168.0.216 の場合、添付画像の画面には次のように入れます。

Home Assistant Server URL:
ws://192.168.0.216:8123/api/websocket

Access-Token:
Home Assistantで作成した長期アクセストークン

その後、Save and (re)connect を押してください。
成功したら、まず switch か light を選んで toggle を設定するのがよいです。

Stream Deckの設定を行うには、事前にStream Deckのアプリのアップデートだけでなく、下図の通り、プラグイン（今回の場合は「HOME Assistantのプラグイン」）のアップデートも行っておいた方がよい。アップデートしていないと、ChatGPTの回答に含まれるメニューの項目と、実際のメニューの項目が違っていたりして混乱する。

---

Stream Deck 設定（① スマートプラグのON/OFF）

Elgato Stream Deck+のアプリを立ち上げ、下記のプラグイン「Entity (generic)」を、設定したいボタンにドラッグし、「Server Settings」として「HOME Assistant Server URL」と「Access-Token」を入力し、[Save and reconnect]をクリックする。正しい値が入力されていれば、それらの入力欄に「☑️」が付く。

サーバーとの接続が成功したら、DJIポータブル電源用のスマートプラグ「DJIプラグ」のボタンの設定を行う。
単押し（Short Press）に、下図の通り、ON/OFFのトグル動作、Entityを設定し、[Save configuration]をクリックして設定を保存する。（図示していないが、長押し（Long Press）の設定も可能）

---

Stream Deck 設定（② 温湿度センサの温度（外気温）の表示）

①のボタンを複写し、② のボタンとして設定を行う。このようにすることにより、「HOME Assistant Server URL」と「Access-Token」の情報が引き継がれたボタン「外気温」を作成することができ、あとは、下図のように「Keypad appearance」のEntityを設定し保存するだけで設定が完了した。

---

Stream Deck 設定（③ Mac miniの音量調整）

Sream Deck+には、ダイヤル式操作ノブ（回転と押し込み操作が可能）が4個あるので、その1つに「Mac miniの音量調整」を割り当てた。この設定は、HOME Assistantのプラグインを使わなくても、下図の通り、「システム：ホットキー」という機能を割り当てることで実現できた。YouTube動画再生中は、このノブの押し込みにより、再生・停止のトグル動作が行われる。

---

Stream Deck 設定（④ TV音量調整）

この設定に手間取り、ChatGPTやCodexの力を借りることになった。というのも、まず、TV音量に関連する設定（domainとservice）を見つける必要があった。下図の通り、RotationのDomainには「media_player」という項目があったので、それを選択し、次にServiceを探したが、音量調整に対応するものは見つからなかった。とりあえず、「volume_level」を選択した状態でCodexに相談した。（途中の会話省略）

（以下、Codexの回答（抜粋））

はい、その理解で合っています。
volume_set は 「何%にするか」 が必要なので、つまみの変化量を volume_level に渡す必要があります。

まず試すなら、Service Data JSON にこれを入れてください。

{
  "volume_level": "{{ rotationPercent / 100 }}"
}

これで、つまみの位置が

40% → volume_level 0.40
50% → volume_level 0.50

として送られるはずです。

もう一つの候補はこれです。

{
  "volume_level": "{{ rotationAbsolute / 255 }}"
}

rotationPercent は 0〜100、rotationAbsolute は 0〜255 なので、どちらも Home Assistant の volume_level 用に 0.0〜1.0 へ変換しています。

{{ ticks }} は「今回どれだけ回したか」です。これは volume_set にはそのまま使いにくいです。
まずは rotationPercent / 100 で試すのが一番よいです。

設定はこの形です。

Rotation
Domain: media_player
Service: volume_set
Entity: Marantz
Service Data JSON:

{
  "volume_level": "{{ rotationPercent / 100 }}"
}

これでも動かない場合は、プラグインがJSON内の計算式を評価していない可能性があります。
その場合は次に volume_up / volume_down 方式に切り替えるのがよいです。

はい。Home Assistant側に「つまみを回した分だけ Marantz の音量を上下するスクリプト」を作ります。

1. スクリプトを新規作成

Home Assistantで:

設定 → 自動化とシーン → スクリプト → スクリプトを作成

右上メニューから YAMLで編集 を選び、下記を入れてください。

alias: Marantz 音量調整 Stream Deck
mode: restart
fields:
  ticks:
    name: ticks
    description: Stream Deck+ の回転量
    required: true
    selector:
      number:
        min: -100
        max: 100
        step: 1

sequence:
  - variables:
      current: "{{ state_attr('media_player.theater_2', 'volume_level') | float(0.38) }}"
      step: 0.01
      next_volume: "{{ [0.0, [0.8, current + ((ticks | float(0)) * step)] | min] | max }}"

  - action: media_player.volume_set
    target:
      entity_id: media_player.theater_2
    data:
      volume_level: "{{ next_volume }}"

保存してください。

この設定では、つまみ1刻みで音量が 0.01、つまり約1%ずつ変わります。
最大音量は安全のため 0.8 にしています。

2. スクリプトの entity_id を確認

保存後、スクリプト一覧で作成したスクリプトを開き、entity_id を確認します。

たぶん以下のような名前になります。

script.marantz_yin_liang_diao_zheng_stream_deck

または似た名前になります。

3. Stream Deck+ 側の設定

Deck+ の Rotation に以下を設定します。

Domain: script
Service: 作成したスクリプト名
Entity: 空欄でOK

もし Entity を求められる場合は、作成したスクリプト entity を選びます。

Service Data JSON にはこれを入れます。

{
  "ticks": "{{ ticks }}"
}

これで、Stream Deckアプリ起動直後につまみ位置が0でも、現在のMarantz音量から相対的に上下します。

音量変化が大きすぎる場合は、スクリプト内のここを小さくします。

step: 0.01

たとえば細かくしたいなら:

step: 0.005

まずは 0.01 で試すのがよいです。

対策として、まず スクリプトをもっと単純な形式で保存してください。
画像の表示は「保存はされたが、セットアップ反映がタイムアウトした」という意味なので、YAMLの形式が少し重い/合っていない可能性があります。

Home Assistant のスクリプト編集画面で、いったん下記だけにしてください。

alias: Marantz 音量調整 Stream Deck
mode: restart
fields:
  ticks:
    name: ticks

sequence:
  - variables:
      current: "{{ state_attr('media_player.theater_2', 'volume_level') | float(0.38) }}"
      next_volume: "{{ [0.0, [0.8, current + ((ticks | float(0)) * 0.01)] | min] | max }}"

  - action: media_player.volume_set
    target:
      entity_id: media_player.theater_2
    data:
      volume_level: "{{ next_volume }}"

前回のものから、selector: などを外しています。まずこれで保存してください。

保存後に同じ表示が出た場合は、次を試してください。

1. その画面で少し待つ
2. キャンセルで閉じる
3. 設定 → 自動化とシーン → スクリプト を開き直す
4. 作成したスクリプトが表示されるか確認
5. 表示されない場合は 開発者ツール → YAML → スクリプトを再読み込み

それでもダメなら、原因確認はここです。

設定 → システム → ログ

ここに script や configuration.yaml のエラーが出ているはずです。

Stream Deck側は、保存できたあとにこう設定します。

Domain: script
Service: 作成したスクリプト

Service Data JSON:
{
  "ticks": "{{ ticks }}"
}

もしこの簡略版でも保存できない場合は、Home Assistant側で私が直接スクリプト登録できるか確認します。
今のエラーは、スクリプト内容というより「UIのセットアップ反映待ち」の問題っぽいです。

この設定により、ノブの回転によって、現状の音量から変化するようになった。
最終的な設定内容は下図の通り。また、単押し（Short Press）には「volume_level:40」をセットし、長押し（Long Press）には「volume_level:20」をセットしたので、単押しで初期値40に戻り、長押しでほぼミュート状態にすることができた。

下記の記事で紹介した通り、CodexがMCPを通じてHOME Assistantの情報を取得できるので、音量調整に関連するEntity（上図のMarantzやMarantz（media_player）など）の候補を回答してもらい、どれが正解の可能性が高いかを調べてもらうことができたので、MCPを使ってCodexとHOME Assistantを連携させることは、HOME Assistantの設定を行う上で有効である。

また、Stream Deckでも「Elgato MCP」というElgato公式のMCPやサードパーティのMCPがあるようなので、それらのMCPとも連携させれば、CodexがStream DeckとHOME Assistantの両方の情報を取得することができ、設定がより容易に行える可能性があるので試してみたい。

CodexはHOME Assistantのオートメーションの設定をすることができたので、このTV音量調整の設定もCodexに依頼することができたかもしれないが、一気に処理され何が行われたのか分からなくなると、後からのトレースが困難になるので、今回のように質問しながら手動で設定する方法の方が安心で設定の勉強にもなった。事例によってはこの方法の方がよい。