openHAB Skill for Amazon Alexa: New Device-Centric Metadata Syntax

Dear all,

We are pleased to announce a complete rework of the openHAB skill for Amazon Alexa, which introduces a new device-centric metadata syntax in line with the other voice assistant integrations, and simplifies the configuration of basic functionalities, while staying backward compatible to ease the transition, is now live.

New Metadata Syntax

The new metadata syntax acts as a new layer on top of the previous API capability-centric syntax, giving us the ability to create new custom pre-configured capabilities that aren’t supported natively by the Alexa Smart Home API.

Therefore, to take full advantage of the latest improvements, it is highly recommended for existing users to migrate their configuration to the new syntax.

New Main UI Integration

Along with this release, a much improved openHAB 3 Main UI integration supporting the new metadata syntax is now available in openHAB 3.2. It provides a much better visibility across group endpoints, and tailors the configuration based on item properties and metadata parameters.

While the metadata syntax is backward compatible, the new UI integration isn’t. Therefore, starting from openHAB 3.2, the only way to maintain the old syntax configuration in the Main UI will be via the Alexa metadata code tab editor.

For users running openHAB 3.0 and 3.1, the existing UI integration will be compatible as part of the syntax backward compatibility. To use the new syntax configuration in the Main UI, either upgrade to 3.2, or use the Alexa metadata code tab editor.

Breaking Changes

  • Tags are no longer supported with openHAB 3.0 and above to prevent conflicts with semantic tagging. Anyone still running openHAB 2.5 and below will not be affected.

  • Rollershutter items are now inverted by default. This affects such items previously configured with the PercentageController and RangeController interfaces.

  • Item sensor concept for decoupling an item receiving commands and providing states was deprecated at the general level. Only the new lock and open states attributes now support such ability.

  • Channel mappings for the channel capability are not backward compatible as these were moved into a new single metadata parameter.

  • Pin codes integration and errors handling for security panel arm state capability are not backward compatible. Provided pin codes are now verified by the skill and arm state errors have separate attributes.

Latest Changes

  • New device capabilities for camera, door/window covering, fan, networking and vacuum
  • Existing capabilities updates:
    • Improve security arm state errors handling
    • Support for input custom mappings
    • Support for playback stop requests
    • Support for thermostat hold setting and thermostat fan mode
    • Improve Dimmer/Rollershutter support for range value generic capability
  • New custom asset ids added
  • New custom semantic extensions

Known issues

  • A new custom unique id is now included on each discovered device. This unfortunately can result in duplicate devices being discovered. If you experienced such issue, delete all your existing Alexa devices/scenes and trigger a discovery.

  • Window covering position state no longer showing a control page in the Alexa app. Controls by voice aren’t affected.


The new documentation can be find here.




A new minor release 3.1.1 has been rolled out to the live skill.

New Features

  • The skill is now officially available for Arabic (SA).

  • Supported item types for the range value attribute has been extended to all Number with dimension items.

  • For color temperature customer integration, its item state (Number only) can now be configured to be reset on set color requests.

  • Support for string-based channel has been introduced. This now requires String item to include the channel mappings which breaks the previous integration for such item.

  • Support for channel step adjustment mimicking up/down arrow keys has been added.

  • Support for volume and mute step adjustments have been revamped in line with the new channel step attribute. This new implementation is breaking the previous step speaker integration backward compatibility.

Bug Fixes

  • Window covering devices are now showing the proper control page in the Alexa app. (#417)

Main UI

All the changes listed above will not be reflected in the openHAB 3.2 UI requiring to use the code tab until 3.3 is released. However, these will be available in the 3.3 snapshot shortly.


As usual, the documentation can be find here.


This topic was automatically closed 41 days after the last reply. New replies are no longer allowed.