Alexa.Discovery Interface


This interface enables the Echo device to discover the following information about a gadget:

  • the details of the gadget, such as its type, manufacturer, firmware version, and so on
  • the capabilities, or interfaces, that the gadget supports

The Echo device gets this information from the gadget when they connect or reconnect over Bluetooth. To request the information, the Echo device sends the gadget a Discover directive. The gadget responds with a Discover.Response event that contains all the information.

Directives

This interface includes one directive: Discover, as described next.

Discover directive

This directive queries the gadget for its details and capabilities. The .proto file contents are as follows:

syntax = "proto3";

message DiscoverDirectiveProto {
   Directive directive = 1;
   message Directive {
      alexaDiscovery.DiscoverDirectivePayloadProto payload = 2;
      header.DirectiveHeaderProto header = 1;
   }
}

message DirectiveHeaderProto {
   string namespace = 1;
   string name = 2;
   string messageId = 3;
   string dialogRequestId = 4;      
}

message DiscoverDirectivePayloadProto {
   Scope scope = 1;
   message Scope {
      string type = 1; 
      string token = 2; 
   }
}

DiscoverDirectiveProto

The fields in this message are as follows:

Field Description Type
directive Contains a complete Discover directive. Directive

Directive

The fields of the message are as follows:

Field Description Type
header Contains the header for this directive. DirectiveHeaderProto
payload Contains the payload for this directive. DiscoverDirectivePayloadProto

DirectiveHeaderProto

The fields of the message are as follows:

Field Description Type
namespace The namespace of this directive, which is Alexa.Discovery. string
name The name of this directive, which is Discover. string
messageId An ID that uniquely defines an instance of this directive. This string can be empty. string
dialogRequestId A unique ID that correlates this directive with a specific voice interaction from a user. You can ignore this field. string

DiscoverDirectivePayloadProto

The fields of the message are as follows:

Field Description Type
scope You can ignore this message. Scope

Scope

The fields of the message are as follows:

Field Description Type
type Empty string. string
token Empty string. string

Events

This interface includes one event: Discover.Response, as described next.

Discover.Response event

This gadget uses this event to report its details and capabilities. The .proto file contents are as follows:

syntax = "proto3";

message DiscoverResponseEventProto {
   Event event = 1;
   message Event {
      alexaDiscovery.DiscoverResponseEventPayloadProto payload = 2;
      header.EventHeaderProto header = 1;
   }
}

message EventHeaderProto {
   string namespace = 1; 
   string name = 2; 
   string messageId = 3; 
}

message DiscoverResponseEventPayloadProto {
   repeated Endpoints endpoints = 1;
   message Endpoints {
      repeated Capabilities capabilities = 11;
      message Capabilities {
         Configuration configuration = 4;
         message Configuration {
            repeated SupportedTypes supportedTypes = 1;
            message SupportedTypes {
               string name = 1;
            }
         }
         string type = 1;
         string interface = 2;
         string version = 3;
      }
      AdditionalIdentification additionalIdentification = 12;
      message AdditionalIdentification {
         string modelName = 5;
         string deviceTokenEncryptionType = 3;
         string firmwareVersion = 1;
         string amazonDeviceType = 4;
         string radioAddress = 6;
         string deviceToken = 2;
      }
      string endpointId = 1;
      string manufacturerName = 4;
      string description = 3;
      string friendlyName = 2;
   }
}

DiscoverResponseEventProto

The fields in this message are as follows:

Field Description Type Required
event Contains a complete Discover.Response event. Event Yes

Event

The fields of the message are as follows:

Field Description Type Required
header Contains the header for this event. EventHeaderProto Yes
payload Contains the payload for this event. DiscoverResponseEventPayloadProto Yes

EventHeaderProto

The fields of the message are as follows:

Field Description Type Required
namespace The namespace of this event, which is Alexa.Discovery. string Yes
name The name of this event, which is Discover.Response. string Yes
messageId An ID that uniquely defines an instance of this directive. This string can be empty. string Yes

DiscoverResponseEventPayloadProto

The fields of the message are as follows:

Field Description Type Required
endpoints An array of endpoints. Each endpoint represents a gadget that is connected to the Echo device. Array of Endpoints Yes

Endpoints

The fields of the message are as follows:

Field Description Type Required
capabilities An array of capabilities of the gadget. Capabilities represent the interfaces that a gadget supports. Array of Capabilities Yes
AdditionalIdentification Additional information about the gadget, such as model name, firmware version, and so on. AdditionalIdentification Yes
endpointId A gadget identifier. This identifier must meet the requirements in Gadget ID Requirements for Alexa Gadgets. string Yes
manufacturerName The name of the device manufacturer. This value cannot exceed 128 characters. Example: "AMAZON". string Yes
description A human-readable description of the gadget. This value cannot exceed 128 characters. Example: "EchoButtons". string Yes
friendlyName The name that the user uses to identify the gadget. This name must match the friendly name of the Bluetooth device.

For BR/EDR-based gadgets, the friendlyName is a part of the Extended Inquiry Response (EIR).

For BLE gadgets, the friendlyName is either input using advertisement data, scan response data, or the GAP profile as described in Assigned numbers and GAP in the Bluetooth specification.

This value can't exceed 15 characters and shouldn't contain special characters or punctuation. Example: EchoButton1.
string Yes

Capabilities

The gadget must include a Capabilities object for every interface that it supports. To find out what to put here, see the Supporting this Interface section of the interface's API reference. As one example, see the API reference for Notifications.

The Capabilities fields are as follows:

Field Description Type Required
type Indicates the type of capability, which determines what fields the capability has. Currently, AlexaInterface is the only valid value. string Yes
interface The qualified name of the interface that describes the actions for the gadget. string Yes
version Indicates the interface version that this gadget supports. string Yes
configuration Contains additional descriptive details about the gadget. Configuration No

Configuration

The fields are as follows:

Field Description Type Required
supportedTypes The types, within the capability, that the gadget supports. SupportedTypes Yes

SupportedTypes

The fields are as follows:

Field Description Type Required
name A type, within the capability, that the gadget supports. You only need to provide this when the capability supports multiple types. For example, if a gadget supports the Alexa.Gadget.StateListener interface, see Supporting This Interface in that topic to learn that name can be alarms, timers, reminders, and so on. string Yes

AdditionalIdentification

The fields are as follows:

Field Description Type Required
modelName A general name for the type of gadget. Example: "EchoButton". string Yes
deviceTokenEncryptionType The device secret algorithm. The only valid value is currently 1, which means that the algorithm is SHA256. string Yes
firmwareVersion The version of the firmware that is running on the gadget, which is used to determine whether the gadget needs an over-the-air (OTA) update. string that contains an integer Yes
amazonDeviceType The type of gadget. This is the Amazon ID that is displayed on the gadget's product page in the developer portal. string Yes
radioAddress The MAC address of the gadget, in hexadecimal format. Example: "0123456789AB" string Yes
deviceToken A UTF-8-encoded string that contains the SHA256 of the following: the endpointId concatenated with the Alexa Gadget Secret that is shown in the developer portal after you register your gadget.

The following code shows how to calculate the device token in Python:
import hashlib def generate_token(device_id, device_token): hash_object = ( hashlib.sha256(bytes(device_id, 'utf-8') + bytes(device_token, 'utf-8')) ) hex_dig = hash_object.hexdigest() return bytes(hex_dig, 'utf-8')
string Yes

Was this page helpful?

Last updated: Mar 31, 2022