Add support for optional clusters and modular profiling for irrigation

system

This commit adds support for optional clusters:
* OperationalState
* FlowMeasurement

Additionally, the level, operationalState, and flowSensor capabilities
are supported via modular profiling.

Author: nickolas-deboom

drivers/SmartThings/matter-switch/profiles/irrigation-system-level.yml

@@ -4,6 +4,19 @@ components:
   capabilities:
     - id: valve
       version: 1
+    - id: level
+      version: 1
+      config:
+        values:
+          - key: "level.value"
+            range: [0, 100]
+      optional: true
+    - id: flowSensor
+      version: 1
+      optional: true
+    - id: operationalState
+      version: 1
+      optional: true
     - id: firmwareUpdate
       version: 1
     - id: refresh

drivers/SmartThings/matter-switch/profiles/irrigation-system.yml

@@ -147,6 +147,11 @@ local matter_driver_template = {
         [clusters.FanControl.attributes.FanModeSequence.ID] = attribute_handlers.fan_mode_sequence_handler,
         [clusters.FanControl.attributes.PercentCurrent.ID] = attribute_handlers.percent_current_handler
       },
+      [clusters.FlowMeasurement.ID] = {
+        [clusters.FlowMeasurement.attributes.MeasuredValue.ID] = attribute_handlers.flow_attr_handler,
+        [clusters.FlowMeasurement.attributes.MinMeasuredValue.ID] = attribute_handlers.flow_attr_handler_factory(FLOW_MIN),
+        [clusters.FlowMeasurement.attributes.MaxMeasuredValue.ID] = attribute_handlers.flow_attr_handler_factory(FLOW_MAX)
+      },
       [clusters.IlluminanceMeasurement.ID] = {
         [clusters.IlluminanceMeasurement.attributes.MeasuredValue.ID] = attribute_handlers.illuminance_measured_value_handler
       },
@@ -158,6 +163,11 @@ local matter_driver_template = {
       [clusters.OccupancySensing.ID] = {
         [clusters.OccupancySensing.attributes.Occupancy.ID] = attribute_handlers.occupancy_handler,
       },
+      [clusters.OperationalState.ID] = {
+        [clusters.OperationalState.attributes.AcceptedCommandList.ID] = attribute_handlers.operational_state_accepted_command_list_attr_handler,
+        [clusters.OperationalState.attributes.OperationalState.ID] = attribute_handlers.operational_state_attr_handler,
+        [clusters.OperationalState.attributes.OperationalError.ID] = attribute_handlers.operational_error_attr_handler
+      },
       [clusters.OnOff.ID] = {
         [clusters.OnOff.attributes.OnOff.ID] = attribute_handlers.on_off_attr_handler,
       },
@@ -225,24 +235,34 @@ local matter_driver_template = {
     [capabilities.fanSpeedPercent.ID] = {
       clusters.FanControl.attributes.PercentCurrent
     },
+    [capabilities.flowMeasurement.ID] = {
+      clusters.FlowMeasurement.attributes.MeasuredValue,
+      clusters.FlowMeasurement.attributes.MinMeasuredValue,
+      clusters.FlowMeasurement.attributes.MaxMeasuredValue
+    },
     [capabilities.illuminanceMeasurement.ID] = {
       clusters.IlluminanceMeasurement.attributes.MeasuredValue
     },
-    [capabilities.motionSensor.ID] = {
-      clusters.OccupancySensing.attributes.Occupancy
-    },
     [capabilities.level.ID] = {
       clusters.ValveConfigurationAndControl.attributes.CurrentLevel
     },
-    [capabilities.switch.ID] = {
-      clusters.OnOff.attributes.OnOff
+    [capabilities.motionSensor.ID] = {
+      clusters.OccupancySensing.attributes.Occupancy
+    },
+    [capabilities.operationalState.ID] = {
+      clusters.OperationalState.attributes.AcceptedCommandList,
+      clusters.OperationalState.attributes.OperationalState,
+      clusters.OperationalState.attributes.OperationalError
     },
     [capabilities.powerMeter.ID] = {
       clusters.ElectricalPowerMeasurement.attributes.ActivePower
     },
     [capabilities.relativeHumidityMeasurement.ID] = {
       clusters.RelativeHumidityMeasurement.attributes.MeasuredValue
     },
+    [capabilities.switch.ID] = {
+      clusters.OnOff.attributes.OnOff
+    },
     [capabilities.switchLevel.ID] = {
       clusters.LevelControl.attributes.CurrentLevel,
       clusters.LevelControl.attributes.MaxLevel,
@@ -286,6 +306,10 @@ local matter_driver_template = {
     [capabilities.level.ID] = {
       [capabilities.level.commands.setLevel.NAME] = capability_handlers.handle_set_level
     },
+    [capabilities.operationalState.ID] = {
+      [capabilities.operationalState.commands.pause.NAME] = capability_handlers.handle_operational_state_pause,
+      [capabilities.operationalState.commands.resume.NAME] = capability_handlers.handle_operational_state_resume
+    },
     [capabilities.switch.ID] = {
       [capabilities.switch.commands.off.NAME] = capability_handlers.handle_switch_off,
       [capabilities.switch.commands.on.NAME] = capability_handlers.handle_switch_on,

drivers/SmartThings/matter-switch/src/init.lua

@@ -538,4 +538,74 @@ function AttributeHandlers.percent_current_handler(driver, device, ib, response)
   device:emit_event_for_endpoint(ib.endpoint_id, capabilities.fanSpeedPercent.percent(ib.data.value))
 end
 
+
+-- [[ OPERATIONAL STATE CLUSTER ATTRIBUTES ]] --
+
+function AttributeHandlers.operational_state_accepted_command_list_attr_handler(driver, device, ib, response)
+  local accepted_command_list = {}
+  for _, accepted_command in ipairs(ib.data.elements) do
+    local accepted_command_id = accepted_command.value
+    if fields.operational_state_command_map[accepted_command_id] ~= nil then
+      table.insert(accepted_command_list, fields.operational_state_command_map[accepted_command_id])
+    end
+  end
+  local event = capabilities.operationalState.supportedCommands(accepted_command_list, {visibility = {displayed = false}})
+  device:emit_event_for_endpoint(ib.endpoint_id, event)
+end
+
+function AttributeHandlers.operational_state_attr_handler(driver, device, ib, response)
+  if ib.data.value == clusters.OperationalState.types.OperationalStateEnum.STOPPED then
+    device:emit_event_for_endpoint(ib.endpoint_id, capabilities.operationalState.operationalState.stopped())
+  elseif ib.data.value == clusters.OperationalState.types.OperationalStateEnum.RUNNING then
+    device:emit_event_for_endpoint(ib.endpoint_id, capabilities.operationalState.operationalState.running())
+  elseif ib.data.value == clusters.OperationalState.types.OperationalStateEnum.PAUSED then
+    device:emit_event_for_endpoint(ib.endpoint_id, capabilities.operationalState.operationalState.paused())
+  end
+end
+
+function AttributeHandlers.operational_error_attr_handler(driver, device, ib, response)
+  if version.api < 10 then
+    clusters.OperationalState.types.ErrorStateStruct:augment_type(ib.data)
+  end
+  local operationalError = ib.data.elements.error_state_id.value
+  if operationalError == clusters.OperationalState.types.ErrorStateEnum.UNABLE_TO_START_OR_RESUME then
+    device:emit_event_for_endpoint(ib.endpoint_id, capabilities.operationalState.operationalState.unableToStartOrResume())
+  elseif operationalError == clusters.OperationalState.types.ErrorStateEnum.UNABLE_TO_COMPLETE_OPERATION then
+    device:emit_event_for_endpoint(ib.endpoint_id, capabilities.operationalState.operationalState.unableToCompleteOperation())
+  elseif operationalError == clusters.OperationalState.types.ErrorStateEnum.COMMAND_INVALID_IN_STATE then
+    device:emit_event_for_endpoint(ib.endpoint_id, capabilities.operationalState.operationalState.commandInvalidInCurrentState())
+  end
+end
+
+function AttributeHandlers.flow_attr_handler(driver, device, ib, response)
+  local measured_value = ib.data.value
+  if measured_value ~= nil then
+    local flow = measured_value / 10.0
+    local unit = "m^3/h"
+    device:emit_event_for_endpoint(ib.endpoint_id, capabilities.flowMeasurement.flow({value = flow, unit = unit}))
+  end
+end
+
+function AttributeHandlers.flow_attr_handler_factory(minOrMax)
+  return function(driver, device, ib, response)
+    if ib.data.value == nil then
+      return
+    end
+    local flow_bound = ib.data.value / 10.0
+    local unit = "m^3/h"
+    set_field_for_endpoint(device, FLOW_BOUND_RECEIVED..minOrMax, ib.endpoint_id, flow_bound)
+    local min = get_field_for_endpoint(device, FLOW_BOUND_RECEIVED..FLOW_MIN, ib.endpoint_id)
+    local max = get_field_for_endpoint(device, FLOW_BOUND_RECEIVED..FLOW_MAX, ib.endpoint_id)
+    if min ~= nil and max ~= nil then
+      if min < max then
+        device:emit_event_for_endpoint(ib.endpoint_id, capabilities.flowMeasurement.flowRange({ value = { minimum = min, maximum = max }, unit = unit }))
+        set_field_for_endpoint(device, FLOW_BOUND_RECEIVED..FLOW_MIN, ib.endpoint_id, nil)
+        set_field_for_endpoint(device, FLOW_BOUND_RECEIVED..FLOW_MAX, ib.endpoint_id, nil)
+      else
+        device.log.warn_with({hub_logs = true}, string.format("Device reported a min flow measurement %d that is not lower than the reported max flow measurement %d", min, max))
+      end
+    end
+  end
+end
+
 return AttributeHandlers

drivers/SmartThings/matter-switch/src/switch_handlers/attribute_handlers.lua

@@ -189,4 +189,21 @@ function CapabilityHandlers.handle_reset_energy_meter(driver, device, cmd)
   end
 end
 
+
+-- [[ OPERATIONAL STATE CAPABILITY COMMANDS ]] --
+
+function CapabilityHandlers.handle_operational_state_resume(driver, device, cmd)
+  local endpoint_id = device:component_to_endpoint(cmd.component)
+  device:send(clusters.OperationalState.server.commands.Resume(device, endpoint_id))
+  device:send(clusters.OperationalState.attributes.OperationalState:read(device, endpoint_id))
+  device:send(clusters.OperationalState.attributes.OperationalError:read(device, endpoint_id))
+end
+
+function CapabilityHandlers.handle_operational_state_pause(driver, device, cmd)
+  local endpoint_id = device:component_to_endpoint(cmd.component)
+  device:send(clusters.OperationalState.server.commands.Pause(device, endpoint_id))
+  device:send(clusters.OperationalState.attributes.OperationalState:read(device, endpoint_id))
+  device:send(clusters.OperationalState.attributes.OperationalError:read(device, endpoint_id))
+end
+
 return CapabilityHandlers

drivers/SmartThings/matter-switch/src/switch_handlers/capability_handlers.lua

@@ -158,7 +158,7 @@ function ButtonDeviceConfiguration.configure_buttons(device)
 end
 
 function ValveDeviceConfiguration.assign_profile_for_valve_ep(device, valve_ep_id)
-  local profile = "irrigation-system"
+  local profile = "water-valve"
 
   for _, ep in ipairs(device.endpoints) do
     if ep.endpoint_id == valve_ep_id then
@@ -231,21 +231,42 @@ function DeviceConfiguration.match_profile(driver, device)
 
   if is_irrigation_system then
     updated_profile = "irrigation-system"
-    table.sort(valve_ep_ids)
-    for _, ep in ipairs(device.endpoints) do
-      if ep.endpoint_id == valve_ep_ids[1] then
-        if switch_utils.find_cluster_on_ep(ep, clusters.ValveConfigurationAndControl.ID) then
-          for _, cluster in ipairs(ep.clusters) do
-            if cluster.cluster_id == clusters.ValveConfigurationAndControl.ID and
-              cluster.feature_map and (cluster.feature_map & clusters.ValveConfigurationAndControl.types.Feature.LEVEL) ~= 0 then
-              updated_profile = updated_profile .. "-level"
-              break
-            end
-          end
+    if version.api >= 14 and version.rpc >= 8 then
+      local main_component_capabilities = {}
+      local optional_supported_component_capabilities = {}
+      local MAIN_COMPONENT_IDX, CAPABILITIES_LIST_IDX = 1, 2
+
+      table.sort(valve_ep_ids)
+      local main_valve_ep = switch_utils.get_endpoint_info(device, valve_ep_ids[1])
+      for _, cluster in ipairs(main_valve_ep.clusters) do
+        if cluster.cluster_id == clusters.ValveConfigurationAndControl.ID and
+          cluster.feature_map and (cluster.feature_map & clusters.ValveConfigurationAndControl.types.Feature.LEVEL) ~= 0 then
+          table.insert(main_component_capabilities, capabilities.level.ID)
+        elseif cluster.cluster_id == clusters.OperationalState.ID then
+          table.insert(main_component_capabilities, capabilities.operationalState.ID)
+        elseif cluster.cluster_id == clusters.FlowMeasurement.ID then
+          table.insert(main_component_capabilities, capabilities.flowSensor.ID)
         end
-        break
       end
+
+      table.insert(optional_supported_component_capabilities, {"main", main_component_capabilities})
+
+      device:try_update_metadata({profile = profile_name, optional_component_capabilities = optional_supported_component_capabilities})
+
+      -- earlier modular profile gating (min api v14, rpc 8) ensures we are running >= 0.57 FW.
+      -- This gating specifies a workaround required only for 0.57 FW, which is not needed for 0.58 and higher.
+      if version.api < 15 or version.rpc < 9 then
+        -- add mandatory capabilities for subscription
+        local total_supported_capabilities = optional_supported_component_capabilities
+        table.insert(total_supported_capabilities[MAIN_COMPONENT_IDX][CAPABILITIES_LIST_IDX], capabilities.refresh.ID)
+        table.insert(total_supported_capabilities[MAIN_COMPONENT_IDX][CAPABILITIES_LIST_IDX], capabilities.firmwareUpdate.ID)
+
+        device:set_field(fields.SUPPORTED_COMPONENT_CAPABILITIES, total_supported_capabilities, { persist = true })
+      end
+    else
+      device:try_update_metadata({profile = profile_name})
     end
+
     if #valve_ep_ids > 1 then
       table.remove(valve_ep_ids, 1) -- the first valve ep is accounted for in the main irrigation system profile
       ValveDeviceConfiguration.create_child_devices(driver, device, valve_ep_ids, default_endpoint_id)

drivers/SmartThings/matter-switch/src/switch_utils/device_configuration.lua

@@ -97,6 +97,9 @@ SwitchFields.LEVEL_BOUND_RECEIVED = "__level_bound_received"
 SwitchFields.LEVEL_MIN = "__level_min"
 SwitchFields.LEVEL_MAX = "__level_max"
 SwitchFields.COLOR_MODE = "__color_mode"
+SwitchFields.FLOW_BOUND_RECEIVED = "__flow_bound_received"
+SwitchFields.FLOW_MIN = "__flow_min"
+SwitchFields.FLOW_MAX = "__flow_max"
 
 SwitchFields.updated_fields = {
   { current_field_name = "__component_to_endpoint_map_button", updated_field_name = SwitchFields.COMPONENT_TO_ENDPOINT_MAP },
@@ -191,6 +194,8 @@ SwitchFields.TRANSITION_TIME = 0 --1/10ths of a second
 SwitchFields.OPTIONS_MASK = 0x01
 SwitchFields.OPTIONS_OVERRIDE = 0x01
 
+SwitchFields.SUPPORTED_COMPONENT_CAPABILITIES = "__supported_component_capabilities"
+
 
 SwitchFields.supported_capabilities = {
   capabilities.audioMute,
@@ -206,6 +211,7 @@ SwitchFields.supported_capabilities = {
   capabilities.energyMeter,
   capabilities.fanMode,
   capabilities.fanSpeedPercent,
+  capabilities.flowSensor,
   capabilities.hdr,
   capabilities.illuminanceMeasurement,
   capabilities.imageControl,
@@ -214,6 +220,7 @@ SwitchFields.supported_capabilities = {
   capabilities.mechanicalPanTiltZoom,
   capabilities.motionSensor,
   capabilities.nightVision,
+  capabilities.operationalState,
   capabilities.powerMeter,
   capabilities.powerConsumptionReport,
   capabilities.relativeHumidityMeasurement,
@@ -308,4 +315,9 @@ SwitchFields.device_type_attribute_map = {
   }
 }
 
+SwitchFields.operational_state_command_map = {
+  [clusters.OperationalState.commands.Pause.ID] = "pause",
+  [clusters.OperationalState.commands.Resume.ID] = "resume"
+}
+
 return SwitchFields

drivers/SmartThings/matter-switch/src/switch_utils/fields.lua

@@ -23,7 +23,7 @@ local endpoints = {
 -- Mock device representing an irrigation system with 3 valve endpoints
 local mock_irrigation_system = test.mock_device.build_test_matter_device({
   label = "Matter Irrigation System",
-  profile = t_utils.get_profile_definition("irrigation-system-level.yml"),
+  profile = t_utils.get_profile_definition("irrigation-system.yml"),
   manufacturer_info = {
     vendor_id = 0x0000,
     product_id = 0x0000,
@@ -96,7 +96,7 @@ local mock_children = {}
 for i, endpoint in ipairs(mock_irrigation_system.endpoints) do
   if endpoint.endpoint_id == 3 or endpoint.endpoint_id == 4 then
     local child_data = {
-      profile = t_utils.get_profile_definition("irrigation-system-level.yml"),
+      profile = t_utils.get_profile_definition("irrigation-system.yml"),
       device_network_id = string.format("%s:%d", mock_irrigation_system.id, endpoint.endpoint_id),
       parent_device_id = mock_irrigation_system.id,
       parent_assigned_child_key = string.format("%d", endpoint.endpoint_id)
@@ -128,14 +128,14 @@ local function test_init()
     mock_irrigation_system:expect_device_create({
       type = "EDGE_CHILD",
       label = string.format("Matter Irrigation System Valve %d", i - 2),
-      profile = "irrigation-system-level",
+      profile = "water-valve-level",
       parent_device_id = mock_irrigation_system.id,
       parent_assigned_child_key = string.format("%d", i)
     })
   end
   test.socket.matter:__expect_send({mock_irrigation_system.id, subscribe_request})
   test.socket.device_lifecycle:__queue_receive({ mock_irrigation_system.id, "doConfigure" })
-  mock_irrigation_system:expect_metadata_update({ profile = "irrigation-system-level" })
+  mock_irrigation_system:expect_metadata_update({ profile = "irrigation-system" })
   mock_irrigation_system:expect_metadata_update({ provisioning_state = "PROVISIONED" })
 end
 test.set_test_init_function(test_init)