Connect a Guitar Amplifier to Alexa

The following shows an example of how to use the capability interfaces to connect a smart guitar amplifier to Alexa. The device in this example is fictional, but provides an example for how to connect any device to Alexa. As with other devices, this example chooses the most specific capability whenever possible, and leverages the flexibility of the ToggleController, ModeController, RangeController, and CustomIntent capabilities to ensure complete coverage of all its functions.

Capabilities

The smart guitar amplifier declares the following capabilities.

Capability Purpose Example utterance

PowerController

Allows a customer to turn the device on or off.

"Turn on the Guitar Amp"

Speaker

Allows a customer to set, adjust, or mute/unmute the volume of the device.

"Set the volume of the Guitar Amp to 6"

EqualizerController

Allows a customer to set and adjust the bass, mid, and treble.

"Set the bass on the Guitar Amp to 3"

ToggleController "Overdrive"

Allows a customer to turn the overdrive feature of the amplifier on or off.

"Turn on overdrive on the Guitar Amp."

RangeController "Gain"

Allows a customer to control the gain, or "drive", of the amplifier.

"Set the gain on the Guitar amp to 4."

ModeController "Preset"

Allows a customer to select pre-defined or customer-saved preset.

"Set the Guitar Amp to Metal."

EndpointHealth

Enables in-depth reporting of the state of the device to the customer through experiences like the Alexa app.

Not applicable.

Alexa

Contains directives and events related to state and error reporting. Make sure to explicitly include this interface and the supported version in the discovery response.

Not applicable.

CustomIntent

Allows a customer to use additional utterances with this device, as defined in your custom model. This smart amplifier example provides three additional intents: BoostIntent, ChangeSoundIntent, and HelpIntent for additional voice functionality.

Note: This feature is available in preview. To request access to these features in preview, fill out this survey.

"Alexa, boost the gain." "Alexa, make me sound like Pearl Jam" "Alexa, what do all these dials do?"

Discovery

This smart amplifier provides the following AddOrUpdateReport.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "AddOrUpdateReport",
      "payloadVersion": "3",
      "messageId": "00000000-0000-0000-0000-000000000000"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "appliance-001",
          "friendlyName": "Guitar Amp",
          "description": "A smart amplifier by Sample Manufacturer",
          "manufacturerName": "Sample Manufacturer",
          "displayCategories": [
            "OTHER"
          ],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.PowerController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "powerState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.Speaker",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "volume"
                  },
                  {
                    "name": "muted"
                  }
                ]
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.EqualizerController",
              "version": "3",
              "configurations": {
                "bands": {
                  "supported": [
                    {
                      "name": "BASS"
                    },
                    {
                      "name": "MIDRANGE"
                    },
                    {
                      "name": "TREBLE"
                    }
                  ],
                  "range": {
                    "minimum": 1,
                    "maximum": 10
                  }
                }
              },
              "properties": {
                "supported": [
                  {
                    "name": "bands"
                  }
                ]
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ToggleController",
              "version": "3",
              "instance": "SampleManufacturer.Amp.OverDrive",
              "capabilityResources": {
                "friendlyNames": [
                  {
                    "@type": "text",
                    "value": {
                      "text": "Overdrive",
                      "locale": "en-US"
                    }
                  },
                  {
                    "@type": "text",
                    "value": {
                      "text": "Over Drive",
                      "locale": "en-US"
                    }
                  }
                ]
              },
              "properties": {
                "proactivelyReported": true,
                "retrievable": true,
                "supported": [
                  {
                    "name": "toggleState"
                  }
                ]
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.RangeController",
              "version": "3",
              "instance": "SampleManufacturer.Amp.Gain",
              "capabilityResources": {
                "friendlyNames": [
                  {
                    "@type": "text",
                    "value": {
                      "text": "Gain",
                      "locale": "en-US"
                    }
                  },
                  {
                    "@type": "text",
                    "value": {
                      "text": "Drive",
                      "locale": "en-US"
                    }
                  }
                ]
              },
              "properties": {
                "supported": [
                  {
                    "name": "rangeValue"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              },
              "configuration": {
                "supportedRange": {
                  "minimumValue": 1,
                  "maximumValue": 10,
                  "precision": 1
                },
                "presets": []
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ModeController",
              "version": "3",
              "instance": "SampleManufacturer.Amp.Presets",
              "capabilityResources": {
                "friendlyNames": [
                  {
                    "@type": "text",
                    "value": {
                      "text": "Preset",
                      "locale": "en-US"
                    }
                  },
                  {
                    "@type": "text",
                    "value": {
                      "text": "Effect",
                      "locale": "en-US"
                    }
                  }
                ]
              },
              "properties": {
                "supported": [
                  {
                    "name": "mode"
                  }
                ],
                "retrievable": true,
                "proactivelyReported": true
              },
              "configuration": {
                "ordered": false,
                "supportedModes": [
                  {
                    "value": "Preset.Normal",
                    "modeResources": {
                      "friendlyNames": [
                        {
                          "@type": "text",
                          "value": {
                            "text": "Normal",
                            "locale": "en-US"
                          }
                        },
                        {
                          "@type": "text",
                          "value": {
                            "text": "Standard",
                            "locale": "en-US"
                          }
                        }
                      ]
                    }
                  },
                  {
                    "value": " Preset.LowGain",
                    "modeResources": {
                      "friendlyNames": [
                        {
                          "@type": "text",
                          "value": {
                            "text": "Low Gain",
                            "locale": "en-US"
                          }
                        }
                      ]
                    }
                  },
                  {
                    "value": " Preset.LeadBoost",
                    "modeResources": {
                      "friendlyNames": [
                        {
                          "@type": "text",
                          "value": {
                            "text": "Lead Boost",
                            "locale": "en-US"
                          }
                        }
                      ]
                    }
                  },
                  {
                    "value": " Preset.Metal",
                    "modeResources": {
                      "friendlyNames": [
                        {
                          "@type": "text",
                          "value": {
                            "text": "Metal",
                            "locale": "en-US"
                          }
                        }
                      ]
                    }
                  }
                ]
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.EndpointHealth",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "connectivity"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.CustomIntent",
              "version": "3",
              "configuration": {
                "supportedIntents": [
                  {
                    "name": "ChangeSoundIntent"
                  },
                  {
                    "name": "BoostIntent"
                  },
                  {
                    "name": "HelpIntent"
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  }
}

For information about building a smart home skill for entertainment devices, see Build Smart Home Skills for Entertainment Devices.

For more details on state reporting, see Understand State Reporting for a Smart Home Skill.

If the device has additional capabilities, you can add other capability interfaces.