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:

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

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 more 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 return the device to the rest position, turn to the primary user, start following the primary user, and stop all motion. For more 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. Combine these prebuilt motions, called 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 any motion in progress. 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 gotToRestPosition. This action cancels the wakeWordResponse motion and rotates the screen to the rest position. No further motion occurs until you use another API or the user says the wake word again to reactivate followOnWakeWord. The wakeWordResponse behavior resumes the next time the user speaks the wake word.

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 Alexa Skills Kit (ASK) Command Line Interface (CLI) or the developer console. For more 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 more details, sees Set wake-word response.

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

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.

<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.

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. This information includes 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 more 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

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. A given device might provide additional values. The error string isn't localized.

Use error and errorCode values for game logic and debug purposes. Don't 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

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

Environment

The Environment object defines the static properties of the device.

Environment object details

Choreos

The Choreos object is a map of the named choreos available on the device. Use playNamedChoreo to play a choreographed motion. For valid choreo names, see Available choreos.

choreo details

Smart-motion interfaces

Get device properties

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

    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.

    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.

    let deviceState = smartMotion.deviceState;

Follow primary user

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

    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 in progress, including motion started by the wake-word.

Go to center

Go to rest position

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

    smartMotion.goToRestPosition();

The rest position is device-specific. This action cancels any current motion that resulted from invoking previous motion commands, including motion started by the wake-word.

Play choreographed motions

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

    smartMotion.playNamedChoreo(playNamedChoreoOptions);
    const playNamedChoreoOptions = {
        name: "ScreenImpactCenter"
    }

The PlayNamedChoreoOptions object defines the choreographed motion.

All choreos start the motion 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. If you do invoke playNamedChoreo multiple times, the last instance cancels a running choreo.

Available choreos

The Smart-Motion extension supports the following named choreos.

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.

    smartMotion.setWakeWordResponse({wakeWordResponseOptions});
    const wakeWordResponseOptions = {
        wakeWordResponse: "turnToWakeWord"
    }    

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

When you set the wakeWordResponse property 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 in progress, including motion started by the wake word, as shown in the following example.

    smartMotion.stopMotion();

Turn to primary user

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

    smartMotion.turnToPrimaryUser();

The most engaged user is the primary user.

The device turns toward the primary user and stops when the device display aligns 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 in progress, including motion started by the wake word.

Related topics

• About Alexa Web API for Games
• Build Your Web App with Web API for Games
• Web API for Games Reference
• Web API Extensions for Games Overview
• Alexa HTML SDK

Last updated: May 01, 2024