投稿者: hoscm

外部からのリクエストつまりboxapiで受け付けたコマンドをどのスマートデバイスで処理するかをしわ決定する仕組みです。

明示的にどのデバイスで処理するかをtgtパラメータで指定する方法もありますが、指定しない場合、デフォルトグループから処理可能なデバイスを選んで処理する仕組みです。
　グループは、複数設定することが可能で、これはGoogle Homeの部屋、グループに相当します。

■グループリスト

”グループ識別キー”には英数字のみ使えます
”グループ名”、”コメント”は２バイト文字も使用可能です

設定フォーマット：

＜グループ識別キー＞,＜グループ名＞, コメント

■ターゲットリスト

”グループ識別キー”は、グループリストの中のものを使用します。
”キャストタイプ”に使用できる文字は下の表を参照してください
下のフォーマットのように、２つの形式でターゲットを登録できます。

設定フォーマット：

＜グループ識別キー＞, ＜キャストタイプ＞ ,＜ターゲット識別キー＞ , ＜IP>,－ ,＜ターゲット名＞ , コメント 固定IPか別ネットワークの場合
＜グループ識別キー＞, ＜キャストタイプ＞ , ＜ターゲット識別キー＞ , ー,MAC ,＜ターゲット名＞ , コメント 同一ネットワーク内の浮動IPの場合

※ターゲット識別キーはグループ識別キーと完全一致する名称を使用しないこと、また重複しないこと　＊重複している場合は先に見つけたデバイスを使用します

●キャストタイプ

機器	タイプ表記	ｍｐ3 トーク	ｍｐ4	jpeg	youtube
Googlehome/mini	audio	◎1	ｘ	ｘ	ｘ
nest	cast	◎2	〇	◎	〇
Chromecast Ultra	castTV	〇	◎	〇	◎

◎1 最優先
◎2次優先
〇可能
ｘ対象外

メニューの概要とメニューファイルアップロード、ダウンロードも参照してください。
設定のベースとなるファイルは、メニューファイルのページでダウンロードしてください。

参考；初期設定（テンプレート）の例：

000,-,該当メニューはありません,トップメニュー,メニュー,-
003,010,-,001： hsboxヘルプメニュー,メニュー,-
003,020,-,002： hsbox紹介メニュー,メニュー,-
：

上の例のように、メニューファイルは１メニュー１行で、カンマ区切り、6フィールドで表記しています。
・コメント行はなく、1から1000行目までが有効な設定です。行の位置が、メニュー番号に相当します。1行目が「メニュー 0」、1000行目が「メニュー 999」に相当します。

各フィールドの内容は次の通りです
・ 1列目： 数字3桁　コマンド番号　
・2列目： 可変コマンドパラメータ
・3列目：　拡張可変コマンドパラメータ
・4列目： メニュー表示用メッセージ
・5列目： コメント（説明用メッセージ）
・6列目： 予備、 拡張用（一部は音声応答メッセージに使用）

デフォルトで使用できるコマンドと設定方法は以下の通りです。※プログラミングして追加する方法は開発者サイトで扱います。開発者サイトへはｈｓｓから入ってください。
　

■0番台　　メニュー用
000：表示用メニュー
P1：- なし
p2: 該当メニューはありません（応答メッセージ：メニューがない場合0行目のみ指定、その他はなし）
m1：メニュー　
ｍ2：メニュー
m3：-

001：無設定 ： 何も設定がない状態
P1：- なし
p2: – なし
m1：-　
ｍ2：-
m3：-

003： リンクメニュー（基本は表示メニューと同じだが、リンク先のメニューを表示）
P1：010 リンク先のメニュー番号（3桁）
p2: – なし
m1：画面表示用メニュー　
ｍ2：メニュー
m3：-

■2番台：音声制御関連
201：設定した文面の発話 （casts ）
P1：発話 文面（可変文字 使用可能）
p2: – なし 言語 （ない場合は日本語で発音）
m1：ｘｘｘｘｘｘ/ｘｘｘｘ　
ｍ2：-
m3：-

203： 指定URLの音声ファイルの、 再生 (cast mp3)
P1： URL
p2: – なし
m1： 指定URL の内容など メニュー表示文面　
ｍ2：-
m3：-

■3番台： 動画、画像制御関連
301：hsbox内の画像表示 (cast image：jpeg) nest優先
P1： パス
p2: – なし （コンテントタイプ）
m1： 指定パス の内容など メニュー表示文面　
ｍ2：-
m3：- ’TV’ といれた場合 TV優先

302：指定URL　の画像表示 (cast image：jpeg) TV優先
P1： URL
p2: – なし （コンテントタイプ）
m1： 指定URL の内容など メニュー表示文面　
ｍ2：-
m3：- ‘nest’ の場合は nest優先

303：指定URLの動画表示 ( cast image ：mp4 ) TV優先
P1： URL
p2: – なし （コンテントタイプ）
m1： 指定URL の内容など メニュー表示文面　
ｍ2：-
m3：- ‘nest’ の場合は nest優先

304：youtube パラメータ ( yt パラメータ ) TV優先
P1： パラメータ
p2: – なし
m1： 指定URL 先の内容など メニュー表示文面　
ｍ2：-
m3：- ‘nest’ の場合は nest優先

■9番台： hsbox制御用
XX0：メニュー表示用
901：メニュー表示画像の更新
P1： メニュー表示画像の更新 します（応答メッセージ）
p2: –
m1：メニュー表示用の画像ファイルを再作成します
ｍ2：Create menu image file.
m3：-

951：特殊コード（-4）呼び出し オプション設定 ユーザ指定
P1：指定なし
p2: 指定なし
m1：予約 特殊呼び出し（表示用メッセージ）
ｍ2：指定なし
m3：全角４文字のオプション設定 ※特殊コード（-4）参照

991：デフォルトグループの指定
P1：グループ
p2: デフォルトグループをｘｘｘに切り替えます（応答メッセージ）
m1：デフォルトのグループをｘｘｘに切り替える
ｍ2：チェンジグループ
m3：-

■特殊コード： 外部Webサービス等 連携用

ー3：メニューの検索呼び出し

ｗ：検索キーワード　　　（キーワードが含まれる最初に一致したメニューを実行する）

ー４：スケジューラ連携 ：音声プッシュ通知 、メニュー検索
ｗ： スケジューラ設定文字列
ｍ3オプション設定は”P●■×”固定 全角です
スケジューラ設定文字列の１文字目（マーク）とｍ３オプション設定を比較し動作を切り替える
　ｍ３：１文字目： マークが無い場合の動作指定
P： 音声読み上げ
M：メニューの検索実行
X：なにもしない
２文字目：マークがこの文字なら音声読みあげ
　　　　３文字目：マークがこの文字ならメニュー実行
４文字目：マークがこの文字なら何もしない

ｗ：通知する音声メッセージ　

※本仕様は、順次追加更新します。
強化提案等も受け付けますので、ｈｓｓの開発者サイトにて提案してください。

スマート機器のグルーピング設定を行います。また、各機器の認識状態を参照することができます。

グルーピングとグループメンバの両方が未設定の場合、上部に設定初期化ボタンが表示されています。「初期化」ボタンを押すと、hsboxと同じネットワーク上にあるGoogle Home や Chromecastなどのデバイスをスキャンし設定に反映します。すべて１つのグループ１”GRP1”にグルーピングします。下はスキャンした結果の例です。

※別ネットワークに配置されたスマートデバイスと連携するにはルータの設定やルーティング設定とあわせてターゲットリストを編集、設定してください。

■サービスAPIの起動停止操作

IFTTTなどのクラウドサービスからイベントを受け付けるAPIを操作します。デフォルトではこのサービスAPIは動作していません。 設定を”有効”にして「設定変更」ボタンを押してください。サービスポートが起動するまでに１分程度時間がかかることがあります。　ポート番号は、hsbox内の他のサービスと競合しない範囲で変更可能です。
　boxapiキーはクラウドサービスから次のようにアクセスする際のURLに使用します。
http://<ホストIP>:＜ポート＞/boxapi/hsx.php?bkey=＜boxapiキー＞&m=＜メニュー番号＞[＆tgt=＜ターゲットID＞]
上の例では、http://host:28655/boxapi/hsx.php?bkey=545drgy5464&m=0
　このリクエストのより、0番のメニューが起動します。
boxapiキーはデフォルトでランダムな値が設定されています。boxapiキーは任意の値に変更可能です。

■スマートサービス連携メニュー設定

メニューは、0~999番までの数字で指定する、 1000個のコマンドを設定することができます。
メニューは次のように番号で指定する方式で、番号を覚えていなくても画面表示に従って目的のメニューまでたどることができます。

※メニューの設定方法は、「メニューファイルの書き方」を参照してください。

■スマホ向けボタンメニューファイルのアップロード/ダウンロード

hsbox1.01.03.01より追加したスマホ向けボタンメニューをファイルで管理することができます。
ボタンメニューのファイル名は”boxmenu_btn.txt”です。
メニューファイルの各行の形式は既存のメニューファイルの形式に準拠しています。上の行から順にボタン形式でメニュー表示します。

クイックスタートガイドは、スマートサービス連携を利用し始めるまでの最短の手順です。
事前に、つぎの準備ができているものとします。これらがまだ準備できていない場合は準備してください。

●Google HomeなどのスマートスピーカーやChromecastなどのキャストデバイスを利用できること。
●スマートスピーカーとIFTTTなどのクラウドサービスの連携設定ができていること。
●hsboxのライセンス登録が完了し、トップ画面にログインできること。

■スマートサービス連携設定

「スマートサービス連携」を行う最短手順です。

①hsboxの設定：boxapiの起動

　boxapiを起動します。起動方法の詳細はこちら
起動したboxapiのポート番号と、boxapiキーを記録してください。②の作業で使用します。

②クラウドサービス（IFTTTなど）の設定：boxapi呼び出しアプレット起動

IFTTTなどのクラウドサービスでboxapiの呼び出しアプレットを設定します。
　以下は、IFTTTでの設定例です。ほかのサービスでも同様に設定可能です。

「if」で、Google Assistantを選択し、下のように「数を含めたフレーズ」で設定します

「then that」で、”Webhooks”を選択して、つぎのようにboxapi呼び出し設定をします

URLは http://<ホスト名>：ポート番号/boxapi/hsx.php?bkey=＜boxapiキー＞&m=＜IFTTTなどから渡される変数＞ の形式です。

※”tgt”パラメータは特定のターゲットを操作する場合に使用します。通常は不要です。
※ホスト名、ポート番号にはインターネット側からアクセスできる値にしてください。一般的に家庭内LANの機器をインターネット側から見たIPは、動的に変わります。動的に名前解決できるDDNSと組み合わせることで、設定が楽になります。
※クラウドと家庭内LANの境界上のルータで、アクセスポート番号を変換するなど工夫してください。

③LAN内スマートデバイスの認識

スマートデバイスを認識させます。
「グループ設定」で、グループメンバの設定を行います。「初期化」ボタンで簡単に設定をすることができます。ただし、hsboxと同一のネットワーク上にあるスマートデバイスしか認識できません。

※別のネットワーク上にある機器を使用するには、ルータの設定、ルーティング設定が必要です。また、グループ設定でグループメンバを手動で追加してください。

④動作確認

Google homeなどに、「メニュー ゼロ」と発話して、テレビ、Google Nestなどにhsboxのトップメニューが表示されれば連携設定成功です。　あとは、メニューに表示された番号をたどって順に発話していけばすべてのメニュー（コマンド）を呼び出せます。また、番号を直接呼び出したり、シングルワードでの個別のメニュー番号を指定し実行することも可能です。