Usage Question (Z-Wave): What exactly does "refresh" do?

Developer Programs Writing Edge Drivers
1

The documentation is not clear about what the true purpose of the Refresh capability and what actions one should take within a device driver.

Just want to make sure that I handle it correctly.

2

Tagging @orangebucket @TAustin @Mariano_Colmenarejo @nayelyz

1 Like
3

Answering from a LAN driver perspective…

I use it to fetch the most recent values from the device, which the driver may not necessarily have if the device doesn’t automatically send them and the driver uses some kind of polling mode.

The driver will get the refresh event whenever the user does the ‘swipe-down’ gesture on the device Controls screen (and you have the refresh capability included in the device profile).

You do have to watch out because the platform can send seemingly spurious refresh commands to your driver at other times as well - like when there may be some other lifecycle event. I haven’t quite nailed down exactly when these occur, and it’s not documented, but they are sometimes issued when the driver is starting up or shutting down. In some drivers, I’ve had to add logic to purposely ignore them in certain cases to avoid duplicate updates when dealing with battery-powered devices.

1 Like
4

You as the developer decide what to do (or not). Is a capability you can choose to implement if required by your device.

1 Like
5

Hi @harobinson

The refresh is a capability that has a single command, called refresh, and has no attributes.

For zigbee, when you run the devie:refresh() function or swipe down in the details view:

  • If you have not made a custom zigbee_handler for it and use the default handlers, then execute a read of all the capabilities attributes of the device profile, which are registered in the driver or subdriver template.
  • If you have made a custom zigbee_handler, then execute the code what you have written in that handler.

For Zwave it is the same, but the equivalent function is device:default_refresh().

  • If you have not made a custom zwave_handler for it and use the default handlers, then send a Get command for all the Command Class of the capabilities of the device profile and that are registered in the template
  • If you have made a custom zwave_handler, then execute the code what you have written in that handler.

When the device responds to the reading of the attributes or Command Class it will cause the device profile capabilities to be updated

If are devices with battery, that sleep between the configured attributes reporting intervals or wake_up interval configuration, they do not respond to the attribute or command class readings of a refresh command

1 Like
6

I thought I knew what it did. Then I read this thread and suddenly got derailed.

My understanding was that the refresh capability just meant the device supported a refresh command, and that although the purpose of the command wasn’t specifically defined there was a convention that it was used for refreshing the state of devices so it probably wasn’t a good idea to diverge from that too much.

I understood that the mobile apps sent the refresh command in response to a pull down on the device details page, just like pulling down on a web page in a browser. I also seem to recollect the app going through a period of sending the refresh command whenever the device details page was opened but I thought it had stopped doing that. I also vaguely remember that there was once some discussion about the app stopping handling refresh at all, given that it was effectively attributing a meaning to refresh that it didn’t actually have.

I also thought that Edge didn’t have any default handling of the refresh capability with Zigbee or Z-Wave and that device.refresh() (Zigbee) and device.default_refresh() were built-in library functions. So a refresh command in an Edge driver might call device.refresh() or device.default_refresh() (Z-Wave) but nothing happened automagically. Now I am thinking it is a good job I don’t touch Zigbee or Z-Wave drivers.

1 Like