How to deprecate standard capabilities when upgrading to a newer/better standard capability

Developers
1

I have a application for Fiat cars. And want to update it to better support the Homey Energy tab, as is suggested in a review of a newer version I just released.

They suggest to set the battery electricCar property to true. Which I can do without any issues. But they also suggest to add the ev_charging_state which replaces both the standard capability battery_charging_state as my custom capability fiat_vehicle_state_plugged_in.
Basically it is this change

I can deprecate the custom flows of the custom capability and make sure that it doesn’t show up in a uiComponent or in the insights. But I cannot find a way to deprecate the usage of the standard battery_charging_state.

And the main issue is that the flow for the trigger of a change to its state is visually exactly the same as the new one for the ev_charging_state .You will need to choose between these 2 flows. Where one only has options for charging/discharging and the other also has options for if the car is (not) plugged in. But there is absolutely no difference when you need to select which ones to use, which will confuse people when selecting a trigger for their flow.
image

Does anyone know how to hide flow actions and the ui component that belong to a standard capability (like battery_charging_state) without removing that capability completely and potentially breaking people’s flows?

2

A suggestion:
If you create a custom capability with the same name “ev_charging_state”,.it should overwrite the standard capability and its flows. If you don’t register your own flow triggers, there will be no flow trigger for that capability.

I will try the same for my app (Tesla)

  • use a custom capability for “ev_charging_state”
  • hide this capability in sensor screen
  • continue using the existing charging state capability becaue it has more enum states. That means the app keeps existing functionality and the new capability is only used for HomeyEnergy

That’s theory so far…haven’t testet yet.

3

I did not expect that I could create a custom capability with the same name as a default one to effectively overrule the default one. So I will try that.

But I would change it from overruling the new ev_charging_state to overruling the old battery_charging_state. Because your third remark (“becaue it has more enum states”) isn’t correct the new ev_charging state has more states and those overlap completely with the old ones.

But this would need some testing since i would also need to implement the existing flows for the battery_charging_state to make sure I can deprecate it instead of completely removing the flow cards to prevent breaking the flows of users.

I will test and keep you posted of my findings

4

Are the users already using this capability/flows? Then overruling will break these flows. Your custom capability flow definitions will get a new ID.

5

I would expected something like that to happen. But that is also why I did not expect overruling the default capability to be allowed (i thought it would create 2 different battery_charging_state capabilities)

I just tested it by adding the 2 flows of the default battery_charging_state and then updating my app from the latest app store version to a local dev version.

When I did not define flows for the overruled battery_charging_state the flows broke and the flow cards would not show up.

But when I copied the 2 flow definitions from Tutorial: Device Capabilities - Homey Apps SDK v3 battery_charging_state and marked them as deprecated. Then build a new dev version of the app. The flows seemed to be restored and the flow cards just showed up in place of the ones I created before defining battery_charging_state myself.

So I deduced that this would work as a way of deprecating an default capability and added it to my app Add the default `battery_charging_state` and it flows to deprecate it · daanleenders/homeyfiatuconnect@17056a0 · GitHub

I was just about to mark it as a new minor version and submit it like this to Homey

6

I uploaded a new version to Homey and asked them in the certification step for any guidance on how best to do this.

7

I got a response from Homey on my app submission with the deprecation as we discussed. They also provided a alternative way to deprecate but I personally feel that the alternative needs to much manual effort from the current users.

Their alternative:

But to give another option that should allow people to migrate in way that is used more often, You could add the new capability only to new pair sessions. This way the feature is available as the new standard for all new users, and if current users want to use it, they can reconnect their driver. Users who do not want to migrate can still use the current capability until they reconnect their device.

By deprecating the flow cards users can still use their current flows without breaking them, but cannot create new ones. This way people can migrate in their own pace.