(EDGE Driver-Mc) Zigbee & Z-wave devices, Custom configuration with SmartThings & drivers Mc

Developer Programs Tutorials
1

I’d like this conversation to be a tutorial on the different custom configurations for ZigBee and Zwave devices. I don’t know if and how this can be done, but I’m going to open another new conversation, linked to this one, to discuss any questions you may have. Therefore, if you want to comment on anything, please do so in that new conversation. Thank you.

I’m going to try to make and share how it works and how to customize the cluster and attribute reporting settings for ZigBee devices. I also want it to be useful for advanced users who want to try creating their own custom drivers.

In 2020, I had no idea what Zigbee, ZWave, or anything else was. I just bought some SmartThings devices and a hub. I quickly realized I needed to customize features, so I started using Groovy and customizing my DTHs. Edge came later, and I started from scratch, like everyone else.
I encourage you to learn Lua and modify and create your own drivers. SmartThings platform allows us to do, soEverything can be learned, and there’s a lot of information shared within the SmartThings community.

  1. What is attribute reporting configuration on standard ZigBee 3.0 devices in SmartThings?:
    It is a command that is sent to the device in which a variable with the fields and values ​​to be configured must be included:

Include this code in the init lifecycle function and when the doConfigure lifecycle is executed, this configuration will be sent to the device.
local config {
cluster = cluster.ID,
attribute = attributes.ID,
minimum_interval = in seconds,
maximum_interval = in secondos,
data_type = attributeData_type,
reportable_change = value variation to reported. (no need for boolean attributes). }

device:add_configured_attribute(config)

It can also be sent more easily using the default libraries, if the attribute has them defined.

device:send(cluster.id.attribute.id:configure_reporting(device, min_rep_int, max_rep_int, rep_change)))

This is the zigbee 3.0 specification and how manage minimum, maximum intervals and reportable change values:

The minimum reporting interval field is 16 bits in length and SHALL contain the minimum interval, in seconds, between issuing reports for the attribute specified in the attribute identifier field. If the minimum reporting interval has not been configured, his field SHALL contain the value 0xffff.
Maximum Reporting Interval Field
The maximum reporting interval field is 16 bits in length and SHALL contain the maximum , in seconds, between issuing reports for the attribute specified in the attribute identifier field. If the maximum reporting interval has not been configured, this field SHALL contain the value 0xffff.
If this value is set to 0x0000 and the Minimum Reporting Interval Field equals 0xffff, then device revert to its default reporting configuration. The reportable change field, if present, SHALL be set to zero.
Reportable Change Field:The reportable change field SHALL contain the minimum change to the attribute that will result in a report being issued. For attributes with Analog data type (see 2.6.2), the field has the same data type as the attribute. If the reportable change has not been configured, this field SHALL contain the invalid value for the relevant data type.
For attributes of Discrete or Composite data (see 2.6.2 chapter), this field is omitted

When all attribute reporting configuration records have been processed, the device SHALL generate the constructed Configure Reporting Response command. If there are no attribute status records in the constructed command, indicating that all attributes were configured successfully, a single attribute status record SHALL be included in the command, with the status field set to SUCCESS and the direction and attribute identifier fields omitted.

Periodic Report ing.
A report SHALL be generated when the time that has elapsed since the previous report of the same attribute A report SHALL be generated when the time that has elapsed since the previous report of the same attribute configuration is not specified.

The maximum reporting interval of an attribute may be reduced, as it SHOULD not normally cause a problem to devices to receive reports more frequently than expected typical reporting intervals are seconds to minutes.
Minimum values are generally used to reduce network traffic, but this is less important than ensuring that the application timing needs are satisfied.

  1. When is the configuration sent to the device in smartthings?:
    Sent during device installation in lifeCycle doConfigure
    Smartthings never reconfigures or modifies these settings, even if you change the driver for the device.

  2. Does Zigbee 3.0 allow you to dynamically modify device settings?:
    Yes, it is allowed, but some circumstances must be taken into account:
    The device must be online and awake, that is, if it is a battery-powered device that sleeps between reporting intervals, to save battery, it must be woken up so that it listens for the configuration command, executes it, and responds to the Hub with the result (success, failure, etc.).

  3. Can Zigbee device settings be modified or customized with SmartThings?:
    Yes, it is possible using custom edge drivers (Edge MC drivers and other community or manufacturer drivers)
    Settings can be customized using the device preferences, visible in the App-device-settings
    Preferences are encoded and managed in the driver using the lifeCycle InfoChange.
    Advanced users can see examples of how to code and handle preferences with Mc drivers on my public github.

  4. How to successfully change ZigBee settings in SmartThings without having to uninstall and reinstall the device?:
    Since SmartThings doesn’t allow for changing the configuration made during device installation, it doesn’t have a specific procedure defined in its libraries for doing so.For zwave devices smartthings have it in its libraries.
    Non-battery powered devices and IR Moes allow configuration changes dynamically, as they are always awake.
    You just have to change the custom values ​​in the device preferences, with the App-device-settings menu and save it.

  5. I’m going to describe a procedure that allows you to successfully change the reporting configuration on battery-powered devices that are normally asleep. Samjin (now Aeotec), Motion, Button, Water Leak, and Contact devices don’t need this procedure, because don’t sleep deeply and have one ear always listening, so they consume slightly more battery than other devices that sleep deeply.

The procedure I’m going to describe allows me to modify the configuration of a battery-powered device using App functions and implementing custom code in my Mc drivers in the doConfigure and nit lifecycles.
Step 1: With the App open the device and go to the settings menu
Step 2: Modify the report configuration values ​​in each preference, changing them one by one and clicking Save.

Screenshot_20250920-152345
Screenshot_20250920-152345864×1920 116 KB

Screenshot_20250920-151959
Screenshot_20250920-151959864×1920 152 KB

Step 3: On the device to be modified, put it into pairing mode.
Step 4: In the app, tap Add Device and select Search Nearby.
Step 5: The app will find your device, with the same name and driver, it will perform the doConfigure lifecycle, reconfiguring the device, now with the custom values ​​you modified in preferences.
All routines and other settings remain as they were.
The configuration process can be viewed using the CLI and logcat, and you can check whether commands were sent to the device correctly and whether confirmations were received, whether the device was successful, or if there was some kind of failure.

  1. What can cause an error and prevent the configuration from being changed?
    Some manufacturers don’t strictly follow the ZigBee standard and use a different data type for some attributes. I’ve seen cases with Tuya devices.
    The device may have failed. The configuration values ​​are stored in flash memory, and it may be very old and have exceeded the write cycle limit, or the memory may simply be broken. I have had a case involving a Lidl power strip and a Tuya switch.
    Some messages may have been missed due to Zigbee network congestion at the time.

Smartthings Removing the health check feature from stock drivers, then makes it easier to customize attribute settings, as this feature uses the configured intervals to ensure devices are reporting correctly. If not, it sends a read commands to determine if the device is active on the network or disconnected, and then try recover the device before hub marking it as offline.
This requires that if the intervals are changed, the table used by health check be updated to know the new reporting intervals for each attribute.
On my Mc drivers the health check function is still maintained on drivers with devices NOT powered by batteries-

I’ll be editing post to add any important details I’ve forgotten or errors.
I’ll be adding, in separate posts to this conversation, how to modify and what reasons might require customizing the custom reporting intervals, their advantages and disadvantages, based on my experience of using them for almost two years now.

4

In this post, I’m going to explain another type of cluster and attribute configuration enabled by the ZigBee 3.0 specification. This configuration determines the different operating modes or options that the manufacturer has defined for their device. For example, what you want the device to do in the event of a power loss, the desired sensitivity for a motion sensor, or how to select specific functions on a thermostat, etc.

The Zigbee 3.0 specification categorizes these attribute options as:

  • Mandatory (M): All manufacturers must include this attribute configuration in their devices. This ensures a minimum level of standardization.
  • Optional (O): Manufacturers may or may not include this attribute in their device to improve its performance and allow it to be customized by the user.
  • Allows the use of manufacturer-specific clusters and attributes: This allows manufacturers to add special features and configurations that differentiate them from other products and make them more attractive in the market. This requires using the manufacturer’s code to modify that cluster or attribute.

These custom configurations are made by sending the WriteAttribute command with the values ​​that the manufacturer has defined as options for that attribute.

This command is handled very well using the Hub libraries, but I’ve incorporated them as a module in my MC drivers, making them even easier for me to manage. They’re just a few lines of code that barely consume any Hub resources.

Ideally, these settings would be available in the device preferences in the app, but most of these settings are only made once, to define how I want my device to work, and are rarely touched again.

in smartthings drivers, which manage many different devices, zigbee switch, motion sensor, etc… it would make the drivers excessively complex and large, which would consume much more memory from the Hub and would cause us more problems than benefits.

Therefore, we must find a compromise and include only the most common and useful ones in the drive.

For the remaining configurable optional attributes, I developed a tool, a “Zigbee Device Config Mc” driver, that allows you to modify any cluster and attribute that the manufacturer has included in the device. All we need is:

  • Install the Zigbee Device Config Mc driver on our Hub
  • Make a temporary driver change to configure our device
  • We need to know all the values ​​needed for the WriteAttribute command by searching in the manual or on the internet.
  • If it is a battery-powered device, it must be awake when the writeAttribute command is sent.
  • Once the device is configured, we will switch back to the original working driver and the customized configuration will remain on the device until we perform a factory reset.

This is the link to Zigbee Device Config Mc thread

This conversation shows how to use the Zigbee configuration driver.

Just a thought:
I think the Matter specification for clusters and attributes is based on what already existed and worked: Zigbee.
Therefore, mandatory, optional, and manufacturer-specific clusters and attributes continue to exist; no manufacturer is going to give up on differentiating themselves from others in their own apps and platforms.

SmartThings platform could also customize devices, but since drivers are constantly evolving and there are already a monster of drivers, let’s see who dares to create community drivers and keep them updated. :rofl: :man_facepalming:

I will continue editing the post to finish it

5

Zwave devices, how to configure the device with the SmartThings platform:

Both the configuration of Command Class reports and the configuration of the device’s operating customization options are performed with the same command:
device:send(Configuration:Set({parameter_number, size, configuration_value))

  • parameter_number: It is an integer between 1 and 255 (x00 and xFF)
    The parameter_number and what this parameter sets is decided by the manufacturer, i.e. parameter 1 of one device does not have to be the same in another device.
    The parameters defined for a ZWave device are published in the device’s manual, which is usually published on ZWave Alliance or the manufacturer’s website.
  • Size: The size of the parameter value in bytes. 1 byte = 8 binary bits (x00 to xFF). I e. The parameter value for 1 byte must be 0 to 255 to be accepted.
  • configuration_value: This is the value that is sent and the device knows what each value means. The value can be positive or negative.
    ZWave libraries have an issue with older devices, where the parameter always has a positive value and a full range of the defined size. For example:
    The old fibaro relay parameter 4 (auto off time) has a value range between 0 sec and 6553.5 sec and a size=2 bytes, which for smartthings libraries with range (-32768 to 32767).
    Attempting to set a value greater than 32767 results in an overflow error, visible in CLI-logcat, and the configuration command is not sent.
    The solution, which I shared with the smartthings team, is to send the complement to 2 of the value, when it is greater than 32767.
    SmarTThings has not implemented it, because they say it complies with the ZWave specification and it is a manufacturer issue and they fixed one in the stock ZWave sensor, I think, by removing the preference.
    Indeed, on identical but more modern devices, size now is = 4 Bytes for the same parameter.
    It was implemented in the ZWave MC drivers, as they integrate several older devices. This is the code implemented in the ZWave MC drivers:
 if preferences then
    local did_configuration_change = false
    for id, value in pairs(device.preferences) do
      if args.old_st_store.preferences[id] ~= value and preferences[id] then
        print("Preference Changed >>>", id,"Old Value >>>>>>>>>",args.old_st_store.preferences[id], "New Value >>", value)
        local new_parameter_value = preferencesMap.to_numeric_value(device.preferences[id])
        --2's complement value if needed
        if preferences[id].size == 4 and new_parameter_value > 2147483647 then
          new_parameter_value = new_parameter_value - 4294967296
        elseif preferences[id].size == 2 and new_parameter_value > 32767 then
          new_parameter_value = new_parameter_value - 65536
        elseif preferences[id].size == 1 and new_parameter_value > 127 then
          new_parameter_value = new_parameter_value - 256
        end
        print("new_parameter_value Sent >>>>",new_parameter_value)
          device:send(Configuration:Set({parameter_number = preferences[id].parameter_number, size = preferences[id].size, configuration_value = new_parameter_value}))

  end
end
  • The SmartThings ZWave hub libraries and stock drivers implement two functions for battery-powered devices, allowing configuration parameters to be modified from the device’s preferences without having to wake them up. When they wake up at their scheduled interval, the function is executed and any configuration commands changed in preferences and pending are sent.
    A function is in the init lifecycle and it is this one:
    device:set_update_preferences_fn(preferences.update_preferences)
    The other one is in the infoChange lifecycle and it is this one:
    preferences.update_preferences(driver, device, args)

The ZWave MC drivers have a preference, which allows you to send the configuration command automatically when the device wakes up or wake it up manually and change the preference at that time:

- name: "parameterSendDelay"
    title: "New Preference Parameter Send"
    description: "Send New Device parameter Immediately or When device wakes up. Default: When device wakes up"
    required: true
    preferenceType: enumeration
    definition:
      options:
        "NoDelay": "Immediately"
        "Delay": "When device wakes up"
      default: "Delay"

in smartthings drivers, which manage many different devices, zwave switch, zwave sensor, etc… it would make the drivers excessively complex and large, which would consume much more memory from the Hub and would cause us more problems than benefits.
Therefore, we must find a compromise and include only the most common and useful ones in the driver.
For the remaining configurable optional attributes, I developed a tool, a Zwave Device Config Mc.

This driver allows you to view and configure parameters, view and perform device associations, and configure wakeup intervals on battery-powered devices.

Screenshot_20250922-220209
Screenshot_20250922-220209864×1920 119 KB

All we need is:
If you use Z-Wave Sensor and Child Thermostat Mc o Z-Wave Switch and Child Mc drivers, They have one preference to create a child device for device configuration:
In App- device- settings and active the preference “create Device Config- Association.
A new child device will be created with which you can fully configure your device.
We need to know all the values ​​needed for the configuration command by searching in the manual or on the internet.
If it is a battery-powered device, it must be awake when the configuration command
Once the device is configured, we will delete the child device and the customized configuration will remain on the device until we perform a factory reset.

Screenshot_20250922-202832
Screenshot_20250922-202832864×1920 133 KB

If you use any other zwave driver, stock or Mc:
Install the Zwave Device Config Mc driver on our Hub
Make a temporary driver change to configure our device
We need to know all the values ​​needed for the configuration command by searching in the manual or on the internet.
If it is a battery-powered device, it must be awake when the configuration command is sent.
Once the device is configured, we will switch back to the original working driver and the customized configuration will remain on the device until we perform a factory reset

This is the link to the launch thread for the Zwave Device Config Mc Driver. The first post contains links to subsequent posts with the latest features. I don’t think it’s worth merging them into a single post.
In the thread describes how to use it. The driver itself had help with the steps to perform each function in HTML format, but SmartThings removed the HTML format from the app without offering us an alternative for displaying explanatory text. They have in App text description box, but they don’t share how the rest of us can use it. SmartThings stuff!