Semantics and Metadata for Alexa Skill


(Dan Cunningham) #1

When we started version 3 (v3) of the Alexa skill, we introduced a new tagging scheme based on the metadata feature of ESH.

During this time there was a very long and lengthy discussion around officially supported semantics which can be manually set on items or auto generated through the use of item tags, which you can read about here https://github.com/eclipse/smarthome/pull/6288.

I am trying to avoid having to support item tags, Alexa specific metadata and the new semantic metadata. Curious if @Kai or @ysc has an opinion here about how these should be used with something like Alexa (or google home, or apple homekit).

For reference the current v3 Alexa tags look something like

Switch LightSwitch "Light Switch" {alexa="PowerController.powerState"}

A more complicated group metadata might look like

  Number Temperature   "Temperature [%.0f F]"    (Thermostat)   {alexa="TemperatureSensor.temperature" [scale="Fahrenheit"]}
  Number HeatSetpoint  "Heat Setpoint [%.0f F]"  (Thermostat)   {alexa="ThermostatController.upperSetpoint" [scale="Fahrenheit"]}
  Number CoolSetpoint  "Cool Setpoint [%.0f F]"  (Thermostat)   {alexa="ThermostatController.lowerSetpoint" [scale="Fahrenheit"]}
  Number Mode          "Mode [%s]"               (Thermostat)   {alexa="ThermostatController.thermostatMode" [OFF=0,HEAT=1,COOL=2,AUTO=3"]}

where we use the “Alexa” name space to set specific meta data that can be read by the skill. See https://github.com/openhab/openhab-alexa/blob/v3/README.md#version-3-v3-item-mapping for more info.

In OH the semantic data is auto generated for certain tags:

for example, an item with a simple tag

Color F2_Lamp_Color "Lamp" (F2_Bedroom) ["Light"]{channel="hue:0000000000:color"}

produces this meta data:

    "semantics": {
      "value": "Point_Control",
      "config": {
        "relatesTo": "Property_Light"
      }
    }
  }

Thanks!


(Alex) #2

@digitaldan

Many thanks for a really detailed documentation, here.

I read it all. Good job! :slight_smile:

Have a question to:

ThermostatController.thermostatMode

I’m using thermostats of max binding.

There are totally different modes, and they are not considerated. Modes: MANUAL, AUTOMATIC and BOOST (OFF=4.5 degrees Celsius, ON=30 degrees Celsius.)

At the moment I use rules to switch them with Alexa.

How will it work with parameters for:

ThermostatController.thermostatMode

referring to your example:

binding=max [OFF=4.5, HEAT=???, COOL=???, AUTO=AUTOMATIC]

Are customized values also possible?

Thanks a lot! :slight_smile:


(Dan Cunningham) #3

First thing is that metadata has to be separated from the binding/channel with a comma, like:

{ binding=max, alexa="ThermostatController.thermostatMode" [OFF=4.5,HEAT=???,COOL=???,AUTO=???]}

You can replace ??? with whatever you want, that will be sent when the Key (like OFF) is spoken. Alexa originally let you specify custom Keys/Voice commands, but then deprecated and removed it from the skill. So only those are allowed.


(Alex) #4

@digitaldan

That’s a pitty.

For example one map it as follows:

 { binding=max, alexa="ThermostatController.thermostatMode"  [OFF=4.5, HEAT=BOOST, COOL=MANUAL, AUTO=AUTOMATIC] }`

But when I speak to Alexa there will be no natural speaking:

“Alexa set heating to cooling mode”, but it means actually “to MANUAL mode”. How could my old mother ever learn this?


(Dan Cunningham) #5

So we are very off topic from my original post, but what you are asking is not anything we can control, this is a limitation of the Smart Home Skill API from Amazon. Rules + a Switch/Scene is probably best.


(Alex) #6

@digitaldan

Ok. I’m going to use my rules again! :slight_smile:


(Alex) #7

@digitaldan
When will the new skill be available?


(Yannick Schaus) #8

The goal of those semantics (including tags, the synonyms namespace and possibly other services in the future) is indeed to try to find common ground for all platforms who need to query items semantically - natural language assistants being the most obvious candidates - so that they could be defined once, in a generic way, avoiding platform-specific configuration whenever possible.

I think the first step would be to try to translate all types in https://github.com/openhab/openhab-alexa/blob/v3/README.md#supported-item-mapping-metadata into a combination of (unambigous) Equipment and Point/Property tags - if at all possible! The model (current version illustrated here) hasn’t been tried much so it would likely be needed to expand it.
Something like:

  • PowerController.powerState > [Power, Status]
  • BrightnessController.brightness > [Light, Lightbulb] (there is no Brightness tag, I don’t remember why but I remember it was discussed and it’s potentially on purpose)
  • ThermostatController.targetSetpoint > [HVAC, Setpoint]

etc.

Now for the additional properties, I don’t have a solution - HABot has some too and they’re still in the habot metadata namespace, the “main” value being required but useless (it’s been replaced by semantic tags), it’s a little ugly now - note the empty string: https://github.com/openhab/openhab-distro/blob/4fd8a69d370868d0ad0e0544d5740d2ba968ca65/features/distro-resources/src/main/resources/items/demo.items#L130


(Dan Cunningham) #9

Thanks @ysc , thats helpful. I’ll go back through and see how we could better support the newer tags introduced , I don’t think that should be too hard.