Discussion: openHAB Google Assistant v4 - Breaking changes incoming

Dear users of the openHAB Google Assistant integration,

in the next few weeks, we would like to release an update that contains some breaking changes. For some items, users will need to adjust their configuration. A new SYNC will also be required.

For this reason, we would first like to collect feedback and then announce a fixed date for publishing the changes so that everyone can prepare their setup.

Please let us know if you see any issues with that plan and the announced changes.

:warning: Breaking Changes

  • After the update the group members will be stored in customData. This means existing (group) devices will only work after a new SYNC.
  • The modes configuration for Thermostats will be renamed to thermostatModes - users will have to adjust their configuration.
  • The speeds configuration for Fans will be renamed to fanSpeeds - users will have to adjust their configuration.
  • As item types of group members will then be validated, users might see devices disappearing in Google Home if they used an unsupported item within a group device. (Documentation is updated accordingly)

:gear: More details and other changes

  • Item names for group members will be stored in customData to save a query request to openHAB when executing commands.

    • For commands that need the current state the query request is still needed (thermostat commands or relative volume).
    • Also some other configuration options are stored in customData.
    • Item types of group members will now be validated.
    • There is no change on the user’s side required but they will need to do a SYNC.
  • Add a lot of new functionality to Fan devices (AirPurifier, Fan, Hood)

    • OnOff (separate power switch if used as a group)
    • FanSpeed (separate fan speed if used as a group)
    • Modes (yes, for the first time modes are available)
    • SensorState (for FilterLifeTime and PM2.5 - no clue how to query those)
  • Add AC Unit device

    • Basically just a combination of the extended Fan and the Thermostat with all control and config options of both

:question: Potential Issues

PR Reference: Rework device matching | Store members in customData | Add AC Unit & Extended Fan by michikrug · Pull Request #405 · openhab/openhab-google-assistant · GitHub

This change will break a lot of my things. I have not time to address this in a timely manner due to work commitments. I will not be home so family will have to use their fingers to control things like the dark ages.

Everything can be controlled multiple so while it will break the integration all devices will still be able to be operated locally.

Thankyou for the notice and for the update.
Thankyou for the work you have done to improve the integration.

Thanks for letting us know. Can you specify which release will be impacted? Like which openHAB milestone release?

Agreed, thanks for your ongoing work, @michikrug!

I’d suggest three things:

  1. A callout in the GA documentation to state when the change took place, leading to a section with very specific quick fixes (e.g. replace this word with this word) for the breaking changes. If possible, it would be great to also add a note on the home page of myopenhab.org for people who look there first.

The last time we had a breaking change to GA, regular visitors to the OH community were prepared, but others were not. On the assumption this will happen again, we should try and make it super easy for them to get working again as quickly as possible. This will save a ton of frustration and hopefully reduce the number of “GA stopped working” posts we get in the community.

The good thing is that the break will be immediate. When we dropped support for tags, people’s systems kept going for as much as two years before GA broke (when they tried to add or change new devices).

  1. Wait until late January to roll out the change.

December is a high-stress and high-travel time for a lot of people, so we should avoid intentionally causing friction. We risk springing it on them while they’re in the middle of holiday madness, or having them return from vacations to find that openHAB doesn’t work.

  1. Add an opt-in field in the myopenhab account that grants permission to email the user.

I think we should have the ability to email myopenhab users whenever there are cloud issues and breaking changes. Without permission to email users, we can’t be proactive and have to wait for frustrated users to show up in the community.

If we could build this into myopenhab before the update is launched, we could get all of the existing GA users to opt in and be better prepared for the next time.

The integration is completely detached from any openHAB release.

It is an standalone service that is only communicating with openHAB through the myopenHAB cloud service.
This means, no matter what openHAB version you are running, you will be affected.

1 Like

Thanks a lot for the suggestions.

  1. I very much agree with the idea regarding documentation. As I have nothing to do with the myopenhab service myself, the second suggestion will require the involvement of other people.

  2. I am very open to setting a release date. So it’s fine for me to wait until the beginning of next year.

  3. Again, as I have no connection to myopenhab myself, we need to find other people if we want to pursue this idea.

1 Like

I’m guessing the myopenhab suggestions would have to go to @digitaldan for consideration?

I don’t think the myopenhab.org home page is going to be a help here, the majority of users are using mobile, voice assistants, etc… with the service, not really so much logging in to the myopenhab Web administration. Its not somewhere i would expect to get news about the Google Home Integration.

We can however pin something to the forum so its visible here as a banner, or top topic. This is where i would expect most people to look first, and where we generally direct people with questions. Happy to help if you want to post/pin an announcement.

1 Like

Fair enough. Would it be possible and of interest to do an opt-in on myopenhab accounts to notify people by email? I’m thinking that would be similar to any other online service.

I just hate the idea of waiting for people to come to us after breaking changes, since it’s out of their control.

No, i don’t think we want to email people from myopenhab, we have only done this once in 10 years, and that was b/c we actually shut down the old service and moved myopenhab to a completely different domain with a different user agreement (and completely deleted the old service and data) . Starting to email people becomes a tricky business with privacy, opt in, email providers, spam, etc… I don’t think this warrants that effort. I have pinned the announcement so its visible for the next 2 weeks.

Sounds good. I’d still favour doing it in January.

1 Like

Great with upgrades so openhab keeps it position.

Is this upgrade going to bring back structure hint to life?

I did not change anything in that regard.
Are there issues that I am not aware of and might require some investigation?

[EDIT] Looked in the latest docs…

structureHint is not (anymore) listed in “action.devices.SYNC” Cloud-to-cloud  |  Google Home Developers
but somehow still in “Method: devices.sync” Method: devices.sync  |  Cloud-to-cloud  |  Google Home Developers


I had been having troubles with structurehint for almost a year or so. Maybe google disabled it or changed method for it. It seems odd if they totaly disabled it hence you could add new homes and rooms i google home. However structurehint stopped working for med so I had to make different prefixes to the rooms instead of using different homes. Is there a way to verify what theyvreally mean in the docs.

Happy new year everyone!

We now entered January… any preferences on how to continue?

Set a date and prepare some more docs?

Happy new year!

I think you’ve covered the changes pretty well in your initial post. We could add some specific examples for the breaking changes to thermostat modes and fan speeds (UI and text-config), so that people will know exactly what to do and can make the edits quickly. I know it’s pretty simple, but examples will just make it crystal clear for people who haven’t touched their configs in a long time.

In the banner announcement, I suggest emphasizing that this change significantly improves the control users have over HVAC items in their homes.

Can users make the changes in advance, or do we have to wait for it to break and then fix it?

Good point. With the current state, things will either break before - if you change the config already or afterwards.
I might introduce an intermediate release, that already provides support for the changed configuration values.


I’m always in favor of having a transition period, even if it’s only brief.


Ditto. I would be inclined to say 4-6 weeks for the intermediate release. We’re still going to have people caught unawares, but then they can’t say we didn’t give ample warning in the community.

I have subscribed to the announcement topic of this forum. This emails me instantly when a topic is posted in the announcement category of this forum and since the replies are locked out, the emails are minimal and always of interest. No need to create a new way when one already exists, but maybe that could be promoted more as a way to stay informed?