投稿者: 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のトップメニューが表示されれば連携設定成功です。　あとは、メニューに表示された番号をたどって順に発話していけばすべてのメニュー（コマンド）を呼び出せます。また、番号を直接呼び出したり、シングルワードでの個別のメニュー番号を指定し実行することも可能です。

hsboxのスマートサービス連携は、スーマート機器だけでなく家庭内LAN内の非スマート対応機器とクラウド上のスマートサービスを連携します。メニュー形式での応用設定や追加モジュールでの拡張など、利用者自身が容易に応用や拡張・強化できます。hsbox1.01.02.02で提供する基本機能は次の通りです。これらを組み合わせて設定することができます。
・連携用WebAPI(boxapi)_{※Webコンソールと異なる専用ポートを使用}
・メニュー形式での1000件※の連携コマンドを設定
※件数はコマンド実装等で拡張可能
・メニューのアップロード、ダウンロード
・配信先のスマート機器の管理とグルーピング機能※
※Google Homeの「部屋とグループ」と同等機能
・メニューで実行可能なコマンド群とコマンドのプログラミングの仕組みと拡張API
　　デフォルトで提供しているコマンドは次の通り
– 文字列の読み上げ（プッシュ通知）
– 指定URLの動画ファイル（ｍｐ4）再生
– 指定URLの音声ファイル（ｍｐ3）再生
– Youtube再生（パラメータ指定）
– 指定URLの画像ファイル（jpeg）表示
– デフォルトグループの指定、切り替え
– メニュー表示画像の更新

■スマートサービス連携 クイックスタートガイド

■スマートサービス連携API用ポート と メニューファイルのアップロード、ダウンロード

■スマート機器とグルーピング設定