Web API Smart-Motion Extension

Alexa-enabled devices with smart-motion capabilities can rotate the device screen to turn toward and follow engaged users. When you use the smart-motion extension, you can do the following:

  • Specify the built-in motion behavior to use when a user says the wake word to interact with your skill.
  • Get information about the motion capabilities and the current state of the device.
  • Move the device.
  • Play pre-built choreographed motions, such as shaking the device.
  • Respond to changes in the device state, such as changes in the position and angle of the screen.

Built-in smart-motion behavior

Motion-capable devices provide built-in motion behavior in response to the wake word. You can override any device default for automatic motion with one of the following settings:

  • turnToWakeWord: When Alexa recognizes the wake word, the device turns to face the speaker, and then stops moving.
  • followOnWakeWord: When Alexa recognizes the wake word, the device turns to face the speaker, and then continues to follow the same user until another motion method interrupts the movement. The motion is best effort. If the user exits the field of view, the device doesn't move. As soon as the device rediscovers the user, the follow resumes.
  • doNotMoveOnWakeWord: The device provides no motion response when Alexa recognizes the wake word.

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

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 default wake-word response for your skill in the skill manifest and override the default with the setWakeWordResponse interface. For details, see Set wake-word response.

Control motion with your app

You can use the smart-motion interfaces to control the device motion directly. You can center the device, turn to the primary user, start following the primary user, and stop all motion. For details, see Smart-motion interfaces. The primary user represents the user who is most engaged with the device.

You can also play choreographed motions, such as a motion that shakes the device. These motions are called choreos. Combine choreos with other methods 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.

When you invoke a motion API, the new motion command cancels the motion resulting from any motion API previously invoked by your game or the motion started in response to the wake word. The wakeWordResponse behavior resumes the next time the user speaks the wake word. For example, assume that the skill uses the followOnWakeWord setting and the device is moving to follow the user who spoke the wake word. Your app invokes gotToCenter. This action cancels the wakeWordResponse motion and rotates the screen to the center. No further motion occurs until you use another API or the user says the wake word again to reactivate followOnWakeWord.

Enable the smart-motion extension in your skill

To enable the smart-motion extension in your skill, you must:

  • Add the smart-motion extension in the skill manifest requestedExtensions property.
  • (Optionally) add the extension and a default wake-word response to the skill manifest autoInitializedExtensions property. The device uses this default when a web app doesn't explicitly set its own wake-word response.

You can add the extension in the skill manifest by using the ASK Command Line Interface (CLI) or the developer console. For details about how to add extensions to the skill manifest, see Add extensions to your skill.

Add the extension by using the CLI

To enable the smart-motion extension, add the ALEXA_EXTENSION interface to the skill manifest JSON file. The ALEXA_EXTENSION interface has two properties, autoInitializedExtensions and requestedExtensions. Add the smart-motion extension to the requestedExtensions property and the default wake-word response in the autoInitializedExtensions property.

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 followOnWakeWord. Any web app that doesn't explicitly set the wake-word response can use this default. Because the manifest also includes smart motion in requestedExtensions, you can override the followOnWakeWord response with setWakeWordResponse in your app. For details, sees Set wake-word response.

div id="example-skillmanifest" markdown="block">

Copied to clipboard.

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

</div>

After you save your manifest file, use the Alexa Skills Kit Command Line Interface to deploy the changed manifest.

Add the extension in the developer console

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, and then click Edit.
  2. Navigate to the Build > Interfaces page.
  3. Enable the Alexa Web API for Games interface.
  4. To configure a default wake-word response, select the option you want from the Wake Word Response list under Smart Motion Policy.
    When you select this option, you update the autoInitializedExtensions property in the skill manifest.
  5. From the Alexa Extensions list, select the Smart Motion v.10.
    When you select this option, you add the ALEXA_EXTENSION interface and the requestedExtensions property in the skill manifest.
  6. Click Save Interfaces, and then, to re-build your interaction model, click Build Model.

Add the extension to your web app

To load the Alexa JavaScript extension library, include the URL in a script tag on your HTML page, as shown in the following example.

Copied to clipboard.

<head>
      <script src="https://cdn.html.games.alexa.a2z.com/extensions/smart-motion/v10/smart-motion.js"></script>
</head>

Use the following code to initialize the smart-motion extension client to allow the app to talk to the device. Not all devices support motion. You can determine whether the device supports the extension by checking the alexa.capabilities object, as shown in the following example.

Copied to clipboard.

Alexa.create({version: "1.1"})
    .then(async ({alexa, message, createExtensionsMessageProvider}) => {
        if(alexa.capabilities.extensions['alexaext:smartmotion:10']) {
            smartMotion = await SmartMotion.create(createExtensionsMessageProvider);
        }
    }); 

Smart-motion objects

deviceState

You can use the deviceState object to get live information about the device, including the range of motion and details about the current device position, speed, angle, etc. Data changes during the lifecycle of your game as the device moves. Use the deviceState interface to get updates. For details, see Get live device state.

The deviceState object references 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.

deviceState object details

Property Description Type
motionLimit The functional range of motion of the device. A motionLimit object.
poise The current position and velocity of the device. A poise object.
screenAngle The vertical orientation of the screen in degrees.
A value of 0 degrees represents a screen position that's upright (perpendicular to the ground). A positive value represents a screen position that's facing upwards.
number
error A text string that describes the error value found in the errorCode property, if an error exists.
This value is an empty string when the device is operating as expected.
string
errorCode The functional state of device motion.
This value is 0 when the device is operating as expected and non-zero when the device is experiencing a motion error. The errorCode values are device-specific.
number

The error and errorCode properties provide information about motion-related device errors. When an error occurs, errorCode reports a non-zero value and error provides descriptive text about the error. Errors often occur when the motor is experiencing an active external force in opposition to the intended motion or during mechanical failure. Common causes of an error are physical obstruction or the device tips over. Expect the device to have limited capabilities when the errorCode is non-zero. When the device detects an error, it periodically checks to see if the error condition has cleared. After the condition is clear, normal motion operations resume.

The following errorCode and corresponding error values are available on Alexa devices. The error description and errorCode values are device-specific, so a given device might provide additional values. The error string isn't localized.

errorCode error
0
1 Motion is blocked due to user interaction.
2 Commands are disabled due to wake word acknowledgment.

For example, this error occurs when the user says the wake word and your app invokes a motion command at the same time. In this situation, the wake-word response overrides the command.
3 Commands are disabled due to system-initiated motion.
4 Smart motion is disabled by the user.

Use error and errorCode values for game logic and debug purposes. Your web app should not display the error or errorCode value to the user.

motionLimit

The motionLimit object describes the functional range of motion for the device. The physical environment might limit the device from achieving its full range. For example, when the user places the device next to a wall, the wall might prevent the device from achieving complete range of motion.

motionLimit object details

Property Description Type
minAngle The lower bound of motion range in degrees. number
maxAngle The upper bound of motion range in degrees. number

poise

The poise object represents the current angular position and velocity of the device screen. The poise object references angles in degrees and velocity in degrees per second.

poise object details

Property Description Type
absoluteAngle The current angular position of the device screen. number
angularVelocity The current motion velocity in degrees per second of the device screen. number

environment

The environment object defines the static properties of the device.

environment object details

Property Description Type
version The smart-motion extension version. string
defaultWakeWordResponse The default wake-word response set in the skill manifest.
If the device doesn't support motion on wake word, this property isn't set.
string
wakeWordResponseSupported True when the device supports a wake-word response.
False when the device doesn't support wake-word responses. The device ignores the wake-word response you configure in the skill manifest and set using setWakeWordResponse in your app.
boolean
availableChoreos The named choreos available on this device. A choreos object.

choreos

The choreos object is a map of the named choreos available on the device. Use playNamedChoreo to play a choreo. For details, see Play choreographed motions

ScreenImpactCenter choreo details

The ScreenImpactCenter choreo invokes a shaking motion that moves the device from side to side rapidly. The motion starts relative to the current position of the device

Property Description Type
approximateDuration (number) The approximate duration in milliseconds the choreo plays.
The number isn't static and might change based on the device position. Use this value to roughly synchronize on-screen visuals to the choreo motion.
number

Smart-motion interfaces

Get device properties

You can get the static properties of the device by checking the environment object. The following example reads the device properties and checks for choreo support.

Copied to clipboard.

    let environment = smartMotion.environment;
    // Check support for the ScreenImpactCenter choreo
    let availableChoreos = environment.availableChoreos;
    if (availableChoreos.ScreenImpactCenter) {
        duration = availableChoreos.ScreenImpactCenter.approximateDuration;
    }     

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. The following example checks for the wake-word response motion support for a device that supports motion.

Copied to clipboard.

    let environment = smartMotion.environment;
    // Check support for built-in wake-word response motion
    if (environment.wakeWordResponseSupported) {
        defaultResponse = environment.defaultWakeWordResponse;
    }     

Get live device state

Get live information about the range of motion and details about the current device position, speed, angle, etc. This interface returns the deviceState, as shown in the following example.

Copied to clipboard.

    let deviceState = smartMotion.deviceState; 

Follow primary user

Direct the device to follow the most engaged user, as shown in the following example.

Copied to clipboard.

    smartMotion.followPrimaryUser(); 

The most engaged user is the primary user.

When the device assigns a new primary user after the invocation of followPrimaryUser, the device follows the new user. In the absence of a detected user or when the user leaves the field of view, the device continues to look for a user until another motion command or the wakeWordResponse cancels the motion.

This action cancels any motion currently in progress, including motion started by the wake-word.

Go to center

Move the device to the center position, as shown in the following example.

Copied to clipboard.

    smartMotion.goToCenter(); 

The center position is device-specific. This action cancels any motion currently in progress, including motion started by the wake-word.

Play choreographed motions

Instruct the device to play the specified choreographed motion (choreo), as shown in the following example.

Copied to clipboard.

    smartMotion.playNamedChoreo({name}); 

The playNamedChoreoOptions object defines the choreographed motion.

Property Description Type
name The name of the choreographed motion.
Valid values are defined by the choreos object. For example, "ScreenImpactCenter."
string

Playing a choreo cancels any ongoing motion. You can't play multiple choreos at the same time. If you do invoke playNamedChoreo multiple times, the last instance cancels the previously running choreo.

Set wake-word response

Set the device built-in motion response to the wake word, as shown in the following example. This action overrides the current setting.

Copied to clipboard.

    smartMotion.setWakeWordResponse({wakeWordResponse}); 

The wakeWordResponseOptions object defines the device response to hearing the wake word.

Property Description Type
wakeWordResponse The response option set for the device.
Valid values are doNotMoveOnWakeWord, followOnWakeWord, turnToWakeWord.
string

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. For wakeWordResponse details, see Built-in motion behavior.

Stop motion

Cancel any motion currently in progress, including motion started by the wake word, as shown in the following example.

Copied to clipboard.

    smartMotion.stopMotion(); 

Turn to primary user

Direct the device to turn to face the most engaged user, as shown in the following example.

Copied to clipboard.

    smartMotion.turnToPrimaryUser(); 

The most engaged user is the primary user.

The device turns toward the primary user and stops when the device display is aligned with the user poise. If the user is moving, motion continues until the device aligns with the user. The precision of the alignment is device-specific. Motion stops when the user leaves the field of view or when the device doesn't detect a user.

This action cancels any motion currently in progress, including motion started by the wake word.