はじめに
Alexaの首振りデバイスである、Echo Show 10 が日本でも発売されたので、プライマリーユーザーを追尾（首振り）するモーションAPIを試してみた。
センシングAPIとは
Echo Show 10などのスクリーンが自動的に回転する、センシング対応のデバイスを制御するためのAPIで、APL Extensions で制御する。Extensionsは、APLランタイムに追加のデータソース、コマンド、イベントハンドラーを提供する拡張機能で、APL 1.4 以上で使用可能となっている。
スキルマニフェストとAPLドキュメントの双方に設定が必要。
どんな事ができるのか
- ユーザーを検出したかどうかを判断するためのプロパティを取得する。（ライブデータプロパティ）
- デバイスを基準としたユーザーの位置を把握する。（ライブデータプロパティ）
- イベントハンドラーを使用して、デバイスの状態の変化を検知する。
注意
以下のような場合、デバイスが検出を行えない。
- 物理的な障害物がある。
- 光が少ない。
- Echoデバイスが「おやすみモード」になっている。
- Echoデバイスのカメラレンズが閉じられている。
Entity Sensing extension を有効にするには
skill.json の interfaces に追加する。
このExtentionは autoInitializedExtensions プロパティで設定する項目はない。
"interfaces": [
{
"type": "ALEXA_PRESENTATION_APL"
},
{
"type": "ALEXA_EXTENSION",
"requestedExtensions": [
{
"uri": "alexaext:entitysensing:10"
}
]
}
]
Alexa Developer Console で設定する場合は、メニューから ビルド スロットタイプ インターフェース と辿り Alexa Extensions で、使用するエクステンションをチェックする。
APLドキュメントの記述
Smart Motion extension はAPLで制御するため、スキルにAPLを追加する必要がある。
extensions
まず、extensions で Entity Sensing extension を使用できるようにする。
以下の例では EntitySensing という名前（任意）を割り当てたので、以降の操作は EntitySensing に対して行うことになる。
{
"type": "APL",
"version": "1.5",
"theme": "dark",
"extensions": [
{
"name": "EntitySensing",
"uri": "alexaext:entitysensing:10"
}
],
settings
settings には、entitySensingStateName と primaryUserName が設定できる。設定方法は以下。
settings.AssignedName
AssignedName は、extensionsで Entity Sensing extension に割り当てた名前。ここではEntitySensingがそれ。この EntitySensing にプロパティentitySensingStateName および primaryUserName を設定することで情報を取得できるようになる。
"settings": {
"EntitySensing": { ←--- AssignedName
"entitySensingStateName": "MyEntitySensingState", ←--- データバインディングコンテキスト（※1）
"primaryUserName": "MyPrimaryUser" ←--- データバインディングコンテキスト（※1）
}
},
※1 Entity Sensing extension では、データバインディングコンテキストに、それぞれライブデータオブジェクト EntitySensingState と PrimaryUser が追加される。 EntitySensingStateは、デバイスの現在のEntity Sensing機能を表すオブジェクト。PrimaryUserは、検出されたユーザーのうち、デバイスとのエンゲージメントが最も高いユーザーが格納されるオブジェクトで、EntitySensingState と PrimaryUser に含まれるプロパティがライブデータプロパティである
entitySensingStateName に名前（任意）を設定することで、EntitySensingStateにアクセス可能となる。この設定そのものが無かったっり、設定値が""の場合は、ライブデータプロパティにはアクセスできないので注意。ライブデータプロパティは、APLドキュメントのライフサイクル中に変更できるデータオブジェクト。
EntitySensingStateプロパティ
| No. | プロパティ名 | 型 | 動作 |
|---|---|---|---|
| 1. | error | 文字 | 読み取り可能なエラーメッセージ。エラーがない場合は""。 |
| 2. | errorCode | 数値 | エラーコード。エラーがない場合は0。 |
primaryUserName に名前（任意）を設定することで、PrimaryUserにアクセス可能となる。条件はentitySensingStateName と同じ。
PrimaryUserプロパティ
| No. | プロパティ名 | 型 | 動作 |
|---|---|---|---|
| 1. | id | 文字 | デバイス割り当てのエンティティID。ユーザーが検出されない場合、文字列は空です。 |
| 2. | isActive | ブール値 | ユーザーがウェイクワードを発話したことを示します。 |
| 3. | isSeen | ブール値 | デバイスがユーザーを検出したことを示します。 |
| 4. | poise | オブジェクト | ユーザーの位置。 |
APL Extensionのライブデータ
APL Extensionsは、ドキュメントのグローバルデータバインディングコンテキストに、カスタムの「ライブ」データオブジェクトを追加できます。ドキュメント読み込み時のextensionの静的な状態のみを報告するenvironment.extension環境プロパティと異なり、これらの「ライブ」データオブジェクトは、ドキュメントのライフサイクルを通じ、extensionのユースケースに応じて変化します。
データバインディングコンテキスト
データバインディングを目的としてAPLドキュメントで使用できるデータソースとデータのコレクションです。データはキーと値のペアで構成され、APLドキュメント、デバイスのviewportに関する情報（viewport.widthなど）、デバイスの機能、環境情報（environment.aplVersionなど）に付随するデータソースを含みます。
イベントハンドラー
イベントハンドラーには OnEntitySensingStateChanged と OnPrimaryUserChanged が設定できる。 それぞれEntitySensingState と PrimaryUser に変化があった場合に実行される。
AssignedName:EventHandlerName
AssignedName には、extensionsで設定した名前 EntitySensing を設定し、EventHandlerNameにはハンドラーの名前OnEntitySensingStateChanged を設定し EntitySensing:OnEntitySensingStateChanged とする。イベントが発生した時に "SetValue" 等で値を変更する。その際 "componentId" で対象のコンポーネントと関連づけ、"property" で値を紐づける。
| No. | ハンドラ名 | 動作 |
|---|---|---|
| 1. | OnEntitySensingStateChanged | EntitySensingStateのプロパティが変更された。 |
| 2. | OnPrimaryUserChanged | PrimaryUserプロパティが変更された（Poiseを除く）。新しいPrimaryUserを検出し割り当てた。既存のPrimaryUserを検出しなくなった。 |
"EntitySensing:OnEntitySensingStateChanged": [ ←--- ハンドラ
{
"type": "SetValue",
"componentId": "mainContainerId", ←--- コンポーネントID
"property": "SensingStatus", ←--- プロパティ
"value": "${event.changed.errorCode == 0 ? 'Active' : 'Faulted'}"
}
],
"EntitySensing:OnPrimaryUserChanged": [ ←--- ハンドラ
{
"type": "SetValue",
"componentId": "mainContainerId", ←--- コンポーネントID
"property": "UserStatus", ←--- プロパティ
"value": "${event.changed.id}"
}
],
"mainTemplate": {
"items": [
{
"type": "Container",
"id": "mainContainerId", ←--- コンポーネントID
"bind": [
{
"name": "SensingStatus", ←--- プロパティ
"value": ""
},
{
"name": "UserStatus", ←--- プロパティ
"value": ""
}
],
}
イベントオブジェクトの構造はこんな感じ。
{
"event": {
"changed": {
//変更されたプロパティのみ
},
"current": {
//現在のすべてのプロパティ
},
"source": {
"type": "Document",
"handler": "OnPrimaryUserChanged",
"id": null,
"uid": null,
"value": null
}
}
}
イベントオブジェクトの使い方。
"when": "${event.changed.errorCode != 0}"
コマンド
Entity Sensing extension には、extensionコマンドは追加されていない。
Entity Sensing Extensionの仕組み
使い方
APL Smart Motion extension との組み合わせで使用するのがメインで、センシングAPIで捉えて、モーションAPIで動かすみたいな使い方になる。
おわりに
動作はしていてほぼ期待どおりの動きにななっているものの、センシングの動きがいまいちわからない。event.changed に期待したタイミングで値が入ってくれないような気がするので、もう少し遊ん理解を深めたいと思う。