Per-Interface Settings


Device settings may change as a result of numerous different types of causes, including user voice requests, companion apps interactions, on-device GUI affordances, and physical device buttons. Each setting defines several messages (events and directives) following a standard approach, described in this document.

Individual settings and their messages are defined in interfaces that are logically related to that setting. For example, settings related to wake words have their events and directives defined in the SpeechRecognizer interface.

This approach to settings depends on version 2.0 or higher of the System interface.

Workflow summary

There are three principal workflows that an individual setting under this paradigm may participate in:

  1. cloud-initiated change
    When a change is first propagated to the device from Alexa, the following messages are exchanged:
    • Alexa sends a Set{SettingName} or Adjust{SettingName} directive to the device.
    • The device responds with a {SettingName}Report event.
  2. device-initiated change
    When a change is first propagated to Alexa from the device, the following message is sent:
    • The device sends a {SettingName}Changed event.
  3. synchronization
    From time to time, Alexa may want to validate that the cloud-side store of settings for a device are consistent with those on the device itself. In that case, the following messages are exchanged:

Cloud-Initiated Changes

Alexa may become aware of setting changes before the device does.

One common scenario is a change made by a user in the Alexa companion app. In that case, the app communicates with Alexa, and Alexa propagates that change to the device through the appropriate directive.

Another common scenario is a change made by a user by voice. In that case, even though the device sends up the user's utterance in a Recognize event, the device is unaware of the substance of the utterance until Alexa processes it and sends the corresponding directive instructing the device to change the setting.

In this workflow, the change is communicated through the following message exchange:

  1. Alexa sends a Set{SettingName} or Adjust{SettingName} directive to the device.
    • Set{SettingName} directives are used when an attribute must be set to an explicit, absolute value.
      For example, the SetTimeZone directive explicitly sets the time zone to a value such as America/Chicago.
    • Adjust{SettingName} directives are used when an attribute's existing value has a delta or modifier applied to it.
      For example, the AdjustBrightness directive may instruct the device to increase the current 0-100 brightness by a specified percentage, such as 20.
  2. The device responds with a {SettingName}Report event.
    This event must be sent both in cases of success and failure, reporting the value actually set on the device after processing the corresponding directive.
Example: Setting Time Zone through Alexa Companion App

1. The user selects the time zone corresponding to Chicago in the Alexa companion app.
2. The Alexa companion app informs Alexa of the change.
3. Alexa sends the SetTimeZone directive to the device with America/Chicago as the timeZone value.
4. The device processes the directive and sends the TimeZoneReport event.

Device-Initiated Changes

The device may become aware of changes before Alexa does.

One common scenario is a GUI affordance on the device itself that allows direct modification of a setting. In that case, the device propagates the change to Alexa through the appropriate event.

Another common scenario is a change made through your companion app. Because companion apps do not communicate directly with Alexa on behalf of a particular device, informing Alexa of changes to device settings must be proxied by the device . In this case, your companion app communicates with the device through a communications mechanism you determine and build, and the device propagates the change to Alexa through the appropriate event.

In this workflow, a single {SettingName}Changed event communicates the change.

Example: Setting Time Zone through Third-Party Companion App

1. The user selects the time zone corresponding to Chicago in your companion app.
2. The companion app informs the device of the change, and the device applies the change.
3. The device sends the TimeZoneChanged event with America/Chicago as the timeZone value.

Synchronization

Under certain circumstances, Alexa may need to validate that the settings set on the device are in sync with the values stored for it in the cloud. This may come after a period of disconnectivity or in other circumstances in which Alexa may not have confidence that messages were correctly processed. This synchronization mechanism enables a comprehensive communication of values for all settings that follow this paradigm.

In this workflow, two centralized messages in the System interface achieve the synchronization:

  1. Alexa sends the ReportState directive to the device.
  2. The device responds with the StateReport event, populating its states list with the event object from each participating {SettingName}Report event.
    The {SettingName}Report event's documentation will indicate whether its event object must be included in this list.

Was this page helpful?

Last updated: Nov 27, 2023