APL Smart-Motion Extension

Use the smart-motion extension in your APL response to control a motion-capable device, such as the Echo Show 10.

Extension summary

About the smart-motion extension

The smart-motion APL extension works with devices that can rotate the display to track and follow a user. Use the smart-motion extension to do the following:

• Specify the built-in motion behavior to use when a user says the wake word as they interact with your skill.
• Run commands to move the device.
• Play pre-built choreographed motions, such as shaking the device.
• Retrieve properties with information about the motion capabilities of the device and the current state of the device.
• Use event handlers to respond to changes in the device state, such as changes in the screen position and angle.

The smart-motion extension references all angles in degrees, and velocity in degrees per second. Positive rotation is in the counter-clockwise direction with the rotational axis centered at 0 degrees.

Built-in smart-motion behavior (wake-word response)

The wake-word response determines the built-in device motion to use when the user speaks the wake word and interacts with your skill. You can choose from three options:

• turnToWakeWord: After Alexa recognizes the wake word, the device turns to face the speaker and then stops moving.
• followOnWakeWord: After Alexa recognizes the wake word, the device turns to face the speaker and continues to move to follow the same user. The device continues to follow the user until you use a command to interrupt or change the motion. The motion is best effort. If the device can't detect the user, the device doesn't move until the device is able to find the user.
• doNotMoveOnWakeWord: The device doesn't move when Alexa recognizes the wake word.

The device uses the motion defined in the wake-word response in the following scenarios:

• The user says the wake word to invoke your skill.

• The user says the wake word during the skill session to invoke an intent.

  The user must say the wake word. Invoking an intent without the wake word in this scenario doesn't trigger the built-in wake-word response motion.

A device that supports the smart-motion extension might not support a wake-word response. The wakeWordResponseSupported environment property returns true when the device supports wake-word responses.

You can set the wake-word response for your skill in multiple ways:

• Configure the wake-word response in your skill manifest. The device uses this default when rendering any APL document in your skill. For details about configuring the smart-motion extension in the manifest, see Smart-motion extension in the skill manifest.
• Set the wake-word response in your APL document, in the extension settings. This default overrides the setting provided in the skill manifest. For details about the extension settings in an APL document, see Extension settings.
• Run the SetWakeWordResponse. This command overrides the values provided in the document extension settings or skill manifest.

Control motion with commands

Use commands to control the device motion directly. You can move the device to its rest position, turn to the primary user, start following the primary user, and stop all motion. For details, see Commands.

You can also use the PlayNamedChoreo command to play pre-built choreographed motions, such as a motion that shakes the device. These pre-built motions are called choreos. Combine the PlayNamedChoreo command with other commands that change the visual or audio presentation to create engaging motion-enabled responses. The available choreos and their expected run times depend on the device. Retrieve this information with the availableChoreos environment variable.

When you run a motion command, the new command cancels any existing motion from a wake-word response or from a previous command. For example, assume that the skill uses followOnWakeWord. The device is moving to follow the user who spoke the wake word. Your skill runs the GoToRestPosition command. This command cancels the wake-word response motion and rotates the screen to the device's rest position. After the device finishes moving, no motion occurs until you either run another command or the user says the wake word again to reactivate followOnWakeWord.

Enable the smart-motion extension

How you enable the smart-motion extension depends on how you intend to use the extension in your skill.

• Set a default wake-word response for all APL documents in your skill – Add the extension and your wake-word response setting to the skill manifest autoInitializedExtensions property.

  You don't need any further configuration, if you want to use this same wake-word response for all your documents and you don't use any of the smart-motion commands, properties, or event handlers.

• Use the extension commands, properties, and event handlers to control the motion experience in your document – Do the following:

  • Add the extension to the skill manifest requestedExtensions property.
  • Optionally add the extension and a default wake-word response to the skill manifest autoInitializedExtensions. The device uses this default when rendering an APL document that doesn't explicitly set its own wake-word response.
  • Add the extension to the extensions property of the APL document to explicitly request it in the document.
  • Configure the document-level settings for the extension in the document settings property.

Smart-motion extension in the skill manifest

The ALEXA_EXTENSION interface has two properties, autoInitializedExtensions and requestedExtensions.

• autoInitializedExtensions – Add the smart-motion extension to this property and configure a wake-word response to use as a default for all APL documents in your skill.
• requestedExtensions – Add the smart-motion extension to this property when you want to use the extension commands, properties, and event handlers.

The URI for the smart-motion extension is "alexaext:smartmotion:10".

The following example shows the skill manifest configured with the smart-motion extension. This example sets a default wake-word response to turnToWakeWord. Any APL documents that don't explicitly request the smart-motion extension use this default. Because the manifest also includes smart motion in requestedExtensions, a given APL document can also request the extension, override the turnToWakeWord response, and use the commands, properties, and event handlers.

{
  "apis": {
    "custom": {
      "interfaces": [
        {
          "type": "ALEXA_EXTENSION",
          "requestedExtensions": [
            {
              "uri": "alexaext:smartmotion:10"
            }
          ],
          "autoInitializedExtensions": [
            {
              "uri": "alexaext:smartmotion:10",
              "settings": {
                "wakeWordResponse": "turnToWakeWord"
              }
            }
          ]
        }
      ]
    }
  }
}

For details about about APL extension settings in the skill manifest, see Request an extension in the skill manifest.

You can also configure the skill manifest in the developer console.

To configure your skill for the smart-motion extension

1. Open the developer console, locate the skill you want to configure, then and click Edit.
2. Navigate to the Build > Interfaces page.
3. Enable the Alexa Presentation Language interface.

4. To configure a default wake-word response, under Quick Start, select the option you want from the Wake Word Response list.

   When you select this option, you update the autoInitializedExtensions property in the skill manifest.

5. To use the smart-motion commands, properties, and event handlers, from the Extensions list, select Smart Motion v.10.

   When you select this option, you update the requestedExtensions property in the skill manifest.

6. Click Save Interfaces and then, to re-build your interaction model, click Build Model.

Smart-motion extension in the APL document

To use the smart-motion extension commands, event handlers, and properties in an APL document, you must request the extension in the document extensions property. This requirement is in addition to adding the extension to requestedExtensions in the skill manifest.

The URI for the smart-motion extension is "alexaext:smartmotion:10".

The following example requests the smart-motion extension and names it SmartMotion. You then use the "SmartMotion" name in your document to reference the settings, properties, commands, and event handlers.

{
  "type": "APL",
  "version": "2022.1",
  "extensions": [
    {
      "name": "SmartMotion",
      "uri": "alexaext:smartmotion:10"
    }
  ]
}

For details about requesting an APL extension in the APL document, see Request an extension in the APL document.

Verify device support for the smart-motion extension

Not all devices support the smart-motion extension. Determine whether the user's device supports the extension in your document and in your code.

Verify device support in the APL document

In your document, use environment properties to determine whether the device supports the smart-motion extension and the wake-word response.

Use the environment.extension property to determine whether the device supports the smart-motion extension. For example, assuming you used SmartMotion for the name in the extensions property, the following data-binding expression returns true when the device supports smart motion.

${environment.extension.SmartMotion}

A device might support motion, but not support the built-in wake-word response motion. Use the wakeWordResponseSupported property to determine whether the device supports the wake-word response.

For example, assuming you used SmartMotion for the name in the extensions property, the following data-binding expression returns true when the device supports the wake-word response:

${environment.extension.SmartMotion.wakeWordResponseSupported}

You can use data-binding expressions in conditional statements and with the when property.

Verify device support in your code

In your code, the request sent to your skill includes supported extensions in the context.Extensions.available property. This property contains a map in which the key for each item is the URI for the available extension.

The following example shows a request from a device that supports the smart-motion extension.

{
  "version": "1.0",
  "session": {},
  "context": {
    "Viewports": [],
    "Viewport": {},
    "Extensions": {
      "available": {
        "alexaext:smartmotion:10": {},
      }
    },
    "System": {}
  },
  "request": {}
}

The context.Extensions property includes extensions that meet both the following criteria:

• You requested the extension in the skill manifest in the requestedExtensions property.
• The device supports the extension.

Extension settings

The following table shows the settings for the smart-motion extension.

To configure these settings in your APL document, use settings.AssignedName, where AssignedName is the name you assigned the smart-motion extension in the extensions property.

The following example assigns the extension the name SmartMotion, and then sets the deviceStateName and wakeWordResponse properties in settings.SmartMotion.

{
  "type": "APL",
  "version": "2022.1",
  "extensions": [
    {
      "name": "SmartMotion",
      "uri": "alexaext:smartmotion:10"
    }
  ],
  "settings": {
    "SmartMotion": {
      "deviceStateName": "MyDeviceState",
      "wakeWordResponse": "followOnWakeWord"
    }
  },
  "mainTemplate": {}
}

deviceStateName

Set the deviceStateName property to the name you want to use to access the DeviceState properties in the global data-binding context. When deviceStateName is missing or set to an empty string, you can't access the DeviceState properties.

The following example shows how to set the deviceStateName to MyDeviceState, and then access a DeviceState property.

{
  "type": "APL",
  "version": "2022.1",
  "extensions": [
    {
      "name": "SmartMotion",
      "uri": "alexaext:smartmotion:10"
    }
  ],
  "settings": {
    "SmartMotion": {
      "deviceStateName": "MyDeviceState"
    }
  },
  "mainTemplate": {
    "item": {
      "type": "Text",
      "id": "MyTextBox",
      "text": "Device angle is ${MyDeviceState.poise.absoluteAngle}"
    }
  }
}

wakeWordResponse

The wakeWordResponse property sets the built-in motion response to use when the user says the wake word. For details about how the wake-word response works, see Built-in smart-motion behavior (wake-word response).

The following example configures the document to follow the user who last said the wake word.

{
  "type": "APL",
  "version": "2022.1",
  "theme": "dark",
  "extensions": [
    {
      "name": "SmartMotion",
      "uri": "alexaext:smartmotion:10"
    }
  ],
  "settings": {
    "SmartMotion": {
      "wakeWordResponse": "followOnWakeWord"
    }
  },
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "items": [
      {
        "type": "Text",
        "height": "100%",
        "text": "This document sets the wake-word response to <code>followOnWakeWord</code>.",
        "textAlign": "center",
        "textAlignVertical": "center"
      }
    ]
  }
}

The value you set for wakeWordResponse in an APL document overrides the wake-word response setting configured in the skill manifest.

Environment properties (static)

The smart-motion extension adds the following static environment properties.

Access these properties in the data binding context in environment.extension.AssignedName where AssignedName is the name you assigned the smart-motion extension in the extensions property.

For example, ${environment.extension.SmartMotion.defaultWakeWordResponse} returns the default wake-word response for the device, assuming you assigned the extension the name SmartMotion.

For more about the environment.extension property in the data binding context, see extension.

version

Returns the smart-motion extension version.

defaultWakeWordResponse

Returns the default wake-word response in effect if you don't explicitly set a wake-word response in your skill. For details about how the wake-word response works, see Built-in smart-motion behavior (wake-word response).

This property returns an undefined value on devices that don't support wake-word responses. Use the wakeWordResponseSupported property to determine whether the device supports the wake-word response.

{
  "type": "Text",
  "text": "The default wake-word response is set to ${environment.extension.SmartMotion.defaultWakeWordResponse}."
}

wakeWordResponseSupported

The wakeWordResponseSupported environment property returns true when the device supports a wake-word response.

When the device doesn't support a wake-word response, this property returns false. The device ignores any wake-word response you configure in the skill manifest, APL document, and SetWakeWordResponse command.

A device can support motion and, at the same time, not support the wake-word response. To determine the status of the other motion features, use the environment.extension property.

availableChoreos

Returns the collection of named choreos available on a device. The availableChoreos property is a map containing an object for each available choreo. Use the PlayNamedChoreo to play a choreo.

choreo

The choreo object describes a choreo available on the device. The following table shows the properties of the choreo object.

Live data properties

The smart-motion extension adds live data properties to the data-binding context. Live data properties are data objects that can change during the lifecycle of the APL document.

The smart-motion extension adds the following live data objects to the data-binding context.

For more about live data, see Extension live data.

DeviceState

The DeviceState live data object represents the current device physical state and the device capabilities.

To access DeviceState, you must set the deviceStateName property in the extension settings. The DeviceState isn't available when deviceStateName is missing or contains an empty string.

The following table shows the DeviceState properties.

A complete DeviceState data binding context has the structure shown in the following example.

{
  "error": "",
  "errorCode": 0,
  "motionLimit": {
    "minAngle": -20,
    "maxAngle": 30
  },
  "poise": {
    "absoluteAngle": 0,
    "angularVelocity": 0
  },
  "screenAngle": 0
}

error, errorCode

The DeviceState.error and DeviceState.errorCode properties provide information about motion-related device errors.

When an error occurs, errorCode reports a nonzero code and error provides descriptive text about the error. When the device is operating without any errors, errorCode returns 0 and error returns an empty string.

Errors often occur when the motor experiences an active external force in opposition to the intended motion, or mechanical failure. Common causes of an error are physical obstruction or the device tipping over.

The device has limited capabilities when errorCode is nonzero. The motor controller shuts down when it detects an errorCode event and periodically checks to see if the errorCode condition has cleared. After the errorCode condition is clear, normal motor controller operations resume.

Changes in errorCode values trigger an OnDeviceStateChanged event.

The following table shows the errorCode and corresponding error properties that are available on Alexa devices. The error description and errorCode values are device specific. Therefore, a given device might provide additional values.

Use these error values for debugging purposes. The error string isn't localized. Therefore, don't display the error or errorCode value to the user.

motionLimit

The DeviceState.motionLimit property returns an object that describes the range of motion for the device motor. The object has the following properties.

The physical environment might limit the device from achieving its theoretical full range. For example, suppose that the user positions the device against a wall. The wall might prevent the motor from achieving the complete range of motion.

Changes in motionLimit values trigger an OnDeviceStateChanged event.

poise

The DeviceState.poise property returns an object that describes the position of the display. The following table shows the properties of the poise object.

The poise.absoluteAngle represents the angular position of the device in degrees. The poise.angularVelocity represents the current motion velocity, if any, of the device in degrees per second.

Changes in poise values don't trigger the OnDeviceStateChanged event.

screenAngle

The DeviceState.screenAngle property returns the orientation of the screen in degrees. A screen angle of 0 degrees represents a screen position perpendicular to the ground. A screen rotated backward, facing directly upward, has a screenAngle of 45 degrees.

Changes in screenAngle trigger an OnDeviceStateChanged event.

Commands

The smart-motion extension adds new extension commands.

To run a smart-motion command, set the type property for the command to AssignedName:CommandName, where AssignedName is the name you assigned the smart-motion extension in the extensions property. For example, if you assigned the extension the name SmartMotion, you could run the GoToRestPosition command with SmartMotion:GoToRestPosition.

FollowPrimaryUser

Directs the device to follow the most engaged user, if any. The most engaged user is the PrimaryUser.

When the device assigns a new PrimaryUser, the FollowPrimaryUser command follows the new user. In the absence of a PrimaryUser, the device continues to look for the user until another motion command or the wakeWordResponse cancels the motion.

FollowPrimaryUser cancels any current motion that resulted from running previous motion commands, including the wakeWordResponse.

The FollowPrimaryUser command doesn't have any parameters.

The following example runs the FollowPrimaryUser command when the user selects the "Lets Play Chase!" button.

{
  "type": "APL",
  "version": "2022.1",
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.2.0"
    }
  ],
  "extensions": [
    {
      "name": "SmartMotion",
      "uri": "alexaext:smartmotion:10"
    }
  ],
  "settings": {
    "SmartMotion": {
      "wakeWordResponse": "doNotMoveOnWakeWord",
      "deviceStateName": "MyDeviceState"
    }
  },
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "items": [
      {
        "type": "Container",
        "justifyContent": "center",
        "item": {
          "type": "AlexaButton",
          "alignSelf": "center",
          "buttonText": "Let's Play Chase!",
          "primaryAction": [
            {
              "type": "SmartMotion:FollowPrimaryUser"
            }
          ]
        }
      }
    ]
  }
}

GoToRestPosition

Moves the device to the device's rest position. The rest position is device-specific.

GoToRestPosition cancels any current motion that resulted from running previous motion commands, including the wakeWordResponse.

The GoToRestPosition command doesn't require any parameters.

The following example moves the device to the rest position when the user selects the "Press to start the game" text.

{
  "type": "APL",
  "version": "2022.1",
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.5.0"
    }
  ],
  "extensions": [
    {
      "name": "SmartMotion",
      "uri": "alexaext:smartmotion:10"
    }
  ],
  "settings": {
    "SmartMotion": {
      "wakeWordResponse": "followOnWakeWord",
      "deviceStateName": "MyDeviceState"
    }
  },
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "item": {
      "type": "Container",
      "justifyContent": "center",
      "item": {
        "type": "AlexaButton",
        "alignSelf": "center",
        "buttonText": "Press to start the game",
        "primaryAction": [
          {
            "type": "SmartMotion:GoToRestPosition"
          }
        ]
      }
    }
  }
}

GoToCenter (deprecated)

SetWakeWordResponse

Changes the current built-in wake-word response motion behavior of the device. This command overrides any wake-word response set in the skill manifest or in the extension settings. For details about the wake-word response, see Built-in smart-motion behavior (wake-word response)

After you run this command, the new wake-word response remains in effect for the lifecycle of the document, unless you run the command again.

SetWakeWordResponse has no effect if the value you provide in the wakeWordResponse property of the command matches the current response behavior.

When you run a motion command, the new command cancels any existing motion from a wake-word response or from a previous command. The setting persists, and the behavior resumes the next time the user says the wake word.

The SetWakeWordResponse command has a single property.

When you set the wakeWordResponse to followOnWakeWord, the device attempts to begin following the last user who spoke the wake word. When you set the wakeWordResponse to turnToWakeWord, the device waits for the next utterance of the wake word to turn.

StopMotion

Cancels any current motion resulting from running previous motion commands, including the wake-word response.

TurnToPrimaryUser

Directs the device to turn to face the most engaged user, if any. The most engaged user is the PrimaryUser. A user might be the PrimaryUser even if they haven't said the wake word.

The device moves toward the PrimaryUser and stops when the device display is in alignment with the user's poise. If the user is moving, motion continues until the device aligns with the user. The precision for alignment is device specific.

This command stops immediately when there is no PrimaryUser.

TurnToPrimaryUser cancels any current motion that resulted from running previous motion commands, including the wakeWordResponse.

The TurnToPrimaryUser command doesn't have any parameters.

The following example runs the TurnToPrimaryUser command when the document loads, after a two-second delay.

{
  "type": "APL",
  "version": "2022.1",
  "extensions": [
    {
      "name": "SmartMotion",
      "uri": "alexaext:smartmotion:10"
    }
  ],
  "settings": {
    "SmartMotion": {
      "wakeWordResponse": "doNotMoveOnWakeWord",
      "deviceStateName": "MyDeviceState"
    }
  },
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "item": {
      "type": "Text",
      "id": "MyTextBox",
      "text": "Welcome to the Game.",
      "textAlign": "center",
      "textAlignVertical": "center"
    }
  },
  "onMount": [
    {
      "type": "SmartMotion:TurnToPrimaryUser",
      "delay": 2000
    }
  ]
}

PlayNamedChoreo

Plays the specified choreographed motion ("choreo"). Verify that the choreo exists on the user's device before you run this command. You can get the list of available choreos with the availableChoreos environment property.

All choreographed motions start relative to the current position of the device. If the device is near its motion limit when you run this command, the device first moves away from that limit so that the device can perform the choreo's full range of motion. When the choreo finishes, the device returns to its original start position.

Playing a choreo cancels any ongoing motion. You can't play multiple choreos at the same time. Therefore, if you run PlayNamedChoreo multiple times, the last instance cancels the previously running choreo.

The following table shows the properties of the PlayNamedChoreo command in addition to the standard command properties.

name

The name of the choreo to play.

Available choreos

The following named choreos are available.

The named choreo to play. The following named choreos are available.

Event handlers

The smart-motion extension adds new extension event handlers. To respond to events generated by the smart-motion extension, add the handler to the top-level properties in your APL document. For the handler name, use AssignedName:EventHandlerName, where AssignedName is the name you assigned the smart-motion extension in the extensions property and EventHandlerName is the name of the handler.

For example, assuming you named the extension SmartMotion, you would use SmartMotion:OnDeviceStateChanged to respond to events from the OnDeviceStateChanged handler.

OnDeviceStateChanged

Invoked when the state of the device has changed. Changes to any device properties except poise trigger an OnDeviceStateChanged event.

The following table shows the properties that the OnDeviceStateChanged handler adds to the event context.

For the list of DeviceState properties, see DeviceState.

The event generated has the following form.

{
  "event": {
    "changed": {
        // All of the changed state properties
    },
    "current": {
        // All of the current state properties
    },
    "source": {
      "type": "Document",
      "handler": "OnDeviceStateChanged",
      "id": null,
      "uid": null,
      "value": null
    }
  }
}

The following example shows an OnDeviceStateChanged handler that updates a property bound to a Text component when the errorCode property changes.

{
  "type": "APL",
  "version": "2022.1",
  "extensions": [
    {
      "name": "SmartMotion",
      "uri": "alexaext:smartmotion:10"
    }
  ],
  "settings": {
    "SmartMotion": {
      "wakeWordResponse": "followOnWakeWord",
      "deviceStateName": "DeviceState"
    }
  },
  "SmartMotion:OnDeviceStateChanged": [
    {
      "type": "SetValue",
      "componentId": "mainContainerId",
      "property": "FaultStatus",
      "value": "${event.changed.errorCode != 0 ? 'FAULTED' : 'NORMAL'}"
    }
  ],
  "mainTemplate": {
    "item": {
      "type": "Container",
      "id": "mainContainerId",
      "bind": [
        {
          "name": "FaultStatus",
          "value": ""
        }
      ],
      "items": [
        {
          "type": "Text",
          "text": "The current device status is: ${FaultStatus}"
        }
      ]
    }
  }
}

The commands in this event handler always run in fast mode.

Image filters

The smart-motion extension doesn't add any new image filters.

Related topics

• APL Extensions
• APL Entity-sensing Extension