question

Chris avatar image
Chris asked ·

Differences between PercentageController, PowerLevelController, BrightnessController?

What functional differences are there between PercentageController, PowerLevelController, and BrightnessController in the Smart Home v3 API? The docs recommend:

 In general, you should implement the most specific interface possible.

Are there different Alexa interactions that can be used for each controller type? I am currently using PowerLevelController on a dimmer switch that controls some lights - will I lose out on brightness functionality if BrightnessController is not used?

skillalexa smart homeapi
10 |2000 characters needed characters left characters exceeded

Up to 2 attachments (including images) can be used with a maximum of 512.0 KiB each and 1.0 MiB total.

Jenn@amazon avatar image
Jenn@amazon answered ·

It depends on what the device supports. "Brightness" is like a more refined version of "Percentage".

From the Alexa.BrightnessController Docs:

The Alexa.BrightnessController interface describes messages used to control and report on the brightness of an endpoint such as a light bulb. You should use this interface for appliances that you know support the brightness control over the more general Alexa.PercentageController interface. If you want to handle requests specific to the power level of an endpoint such as a dimmer switch, see Alexa.PowerLevelController.

1 comment
10 |2000 characters needed characters left characters exceeded

Up to 2 attachments (including images) can be used with a maximum of 512.0 KiB each and 1.0 MiB total.

> Brightness is like a more refined version of Percentage

Is this just a semantic difference or a technical one? In the case of Brightness and PowerLevel controllers, they seem to have the exact same interface (for `powerLevel` and `brightness` values):

integer from 0-100, inclusive.

The BrightnessController doc describes the Alexa phrases it responds to:

“Alexa, set the device to ##%”

But I do not see anything mentioned like that in the PowerLevelController doc.

In my tests using PowerLevelController, it seems to respond to the same phrases.

I am still confused which is appropriate for my scenario using an in-wall dimmer switch that controls a bulb:

  • Use PowerLevelController since the controlling device is a dimmer switch.
  • Use BrightnessController since the downstream device from the dimmer switch is a bulb.
0 Likes 0 ·
newuser-d69ee4c7-c2e3-4ea6-a906-c83dd103c0ec avatar image
newuser-d69ee4c7-c2e3-4ea6-a906-c83dd103c0ec answered ·

Still confused as well, even when the Discovery response is returned as below with the powerLevel, the Alexa APP is still showing "Brightness is set to xx%"

On top of that, sending a successful "ChangeReport" will not change anything in the app?

DIMMER_CAPABILITIES = [
    {
        "type": "AlexaInterface",
        "interface": "Alexa.PowerController",
        "version": "3",
        "properties": {
            "supported": [
                { "name": "powerState" }
            ],
            "proactivelyReported": True,
            "retrievable": True
        }
    },
    {
        "type": "AlexaInterface",
        "interface": "Alexa.PowerLevelController",
        "version": "3",
        "properties": {
            "supported": [
                { "name": "powerLevel" }
            ],
            "proactivelyReported": True,
            "retrievable": True
        }
    }
]


img-2881.png (140.6 KiB)
10 |2000 characters needed characters left characters exceeded

Up to 2 attachments (including images) can be used with a maximum of 512.0 KiB each and 1.0 MiB total.