Semantics and Metadata for Alexa Skill

Development
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!

1 Like
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:

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.

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?

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.

6

@digitaldan

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

7

@digitaldan
When will the new skill be available?

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: openhab-distro/features/distro-resources/src/main/resources/items/demo.items at 4fd8a69d370868d0ad0e0544d5740d2ba968ca65 · openhab/openhab-distro · GitHub

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.

10

Hi @digitaldan, I finally got the openHab v3 skill working using v2 tags. Thank you for all the hard work!

What I’m having trouble understanding is how to use the v3 tags and likely missing something quite basic.

For example I have the Office Light defined as:

Dimmer OfficeLight "Office Light" <Light> ["Lighting"] {channel="zwave:device:c912238a:node2:switch_dimmer"}

What I can’t figure out from the Usage documentation is how any of the items “link” back to the device channel. I copied the example into my alexa.items file and alexa was able to discover and control it but obviously there is no physical device associated with it.

Dimmer LightSwitch "Light Switch" {alexa="PowerController.powerState,BrightnessController.brightness"}

Thanks, Glenn

11

Meta data is included in the item configuration like this:

Dimmer OfficeLight "Office Light" <Light>  {channel="zwave:device:c912238a:node2:switch_dimmer", alexa="PowerController.powerState,BrightnessController.brightness"}
1 Like
12

Thanks @digitaldan!

13

I recently read about the new (v3) semantics and metadata with alexa, so i thought i’d update my items.

what i have done:

  • logged in to my alexa account and deleted all smart home devices
  • created a test item
Dimmer	LED_SZ	"Schlafzimmer Licht" <slider>	(gXXXXX) { channel="hue:0100:xxx:brightness" , alexa="Lighting" }
  • restarted my openhab docker container
  • searched for new devices in alexa, result: nothing
  • changed the test item to be
Dimmer	LED_SZ	"Schlafzimmer Licht"  <slider>   (gXXXXX) { channel="hue:0100:xxx" , alexa="PowerController.powerState,BrightnessController.brightness" [category="LIGHT"]" }
  • restarted and searched again, result: nothing
  • deleted all of the alexa= definitions, added ["Lighting"] after the group definitions
  • restarted and searched again, result: voila the item has been discoverd

Can anyone point me in the direction what i did wrong?

Regards,
Raven

14

Hi @Raven , we are in the process of submitting the v3 version of the skill, so right now this only works with dev hosted versions. I merged the v3 branch into master last week which is why the usage page now refers to v3 in the main repo. I will try to hasten our submission !

15

@digitaldan thx for the fast answer. so i’ll stick with my old tags a little longer.
any place to “follow” when the merge is done? like “watch” on github or something similar?

16

Is it possible to have multiple instances of the same Endpoint, say Thermostat or Fan in the same file?

In my case I want to control 2 Fans and 2 Split Unit AC’s. If the items file contains only 1 Endpoint,it gets discovered.If I add more than 1,nothing shows up.

Here is my mapping file

Group gAC1LR “Living Room AC” {alexa= “Endpoint.Thermostat”}
Group gAC1LRFan “Living Room Blower” {alexa= “Endpoint.Fan”}
Dimmer LivingroomAC1Fan “Speed” (gAC1LRFan) {channel = “mqtt:topic:livingRoom:ac1_fan”, alexa=“RangeController.rangeValue” [supportedRange=“0:6:1”,presets=“0=Off,1=@Value.Minimum:@Value.Low:Lowest,2=@Value.Medium,3=@Value.Maximum:@Value.High,4=@Value.Maximum:Highest,5=Auto,6=Quiet”,friendlyNames="@Setting.FanSpeed,Speed"]}
Number LivingroomAC1Sensor “Current Temperature” (gAC1LR) {channel = “mqtt:topic:livingRoom:ac1_sensorTemp”, alexa=“TemperatureSensor.temperature”}
String LivingroomAC1Mode “Mode” (gAC1LR) {channel = “mqtt:topic:livingRoom:ac1_mode”, alexa=“ThermostatController.thermostatMode” [OFF=“OFF”,COOL=“COOL”,ECO=“ECO”,AUTO=“AUTO”]}
Number LivingroomAC1Temp “Temperature” (gAC1LR) {channel = “mqtt:topic:livingRoom:ac1_temp”, alexa=“ThermostatController.targetSetpoint” [setpointRange=“16:30”]}

Group gAC2LR “Dining Room AC” {alexa= “Endpoint.Thermostat”}
Group gAC2LRFan “Dining Room Blower” {alexa= “Endpoint.Fan”}
Dimmer DiningroomAC2Fan “Speed” (gAC2LRFan) {channel = “mqtt:topic:livingRoom:ac2_fan”, alexa=“RangeController.rangeValue” [supportedRange=“0:6:2”,presets=“0=Off,2=@Value.Minimum:@Value.Low:Lowest,2=@Value.Medium,3=@Value.Maximum:@Value.High,4=@Value.Maximum:Highest,5=Auto,6=Quiet”,friendlyNames="@Setting.FanSpeed,Speed"]}
Number DiningroomAC2Sensor “Current Temperature” (gAC2LR) {channel = “mqtt:topic:livingRoom:ac2_sensorTemp”, alexa=“TemperatureSensor.temperature”}
String DiningroomAC2Mode “Mode” (gAC2LR) {channel = “mqtt:topic:livingRoom:ac2_mode”, alexa=“ThermostatController.thermostatMode” [OFF=“OFF”,COOL=“COOL”,ECO=“ECO”,AUTO=“AUTO”]}
Number DiningroomAC2Temp “Temperature” (gAC2LR) {channel = “mqtt:topic:livingRoom:ac2_temp”, alexa=“ThermostatController.targetSetpoint” [setpointRange=“26:30”]}

gAC1LR & gAC1LRFan show up as Thermostat and Fan on Alexa , when gAC2LR & gAC2LRFan
dont exist in the items file. If it does,then it wont discover any devices

17

Have you looked at your server logs for any errors when you added your second endpoint? Make sure to go over the troubleshooting guide.

As a side note, your should use code fencing when pasting your item definition. Also, you may want to start a new topic in Amazon Alexa section.

18

Thank you for your reply. I was about to edit and re post in Code Fence format, but then you’d already replied. I’ve managed to get it working now. I just renamed everything using a bit more meaningful names and it works. I think there were some name conflicts before.

Thank you for this amazing skill.