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 |
Last updated: Mar 31, 2022