Skip to content

Matter Ikea Scroll: Aggregate multiple responses into one event, add global bounds checking, remove InitialPress handling during scroll #3014

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
hcarter-775 wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Matter Ikea Scroll: Aggregate multiple responses into one event, add global bounds checking, remove InitialPress handling during scroll #3014

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1a3d840
aggregate multiple responses into one event, add global bounds checking
hcarter-775 May 21, 2026
1fa21e3
ignore InitialPress
hcarter-775 Jun 5, 2026
2325f60
move constant variables to fields file
hcarter-775 Jun 10, 2026
94eac72
fix tests to ignore InitialPress
hcarter-775 Jun 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 35 additions & 19 deletions .../SmartThings/matter-switch/src/sub_drivers/ikea_scroll/scroll_handlers/event_handlers.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,55 +6,71 @@ local capabilities = require "st.capabilities"
local switch_utils = require "switch_utils.utils"
local generic_event_handlers = require "switch_handlers.event_handlers"
local scroll_fields = require "sub_drivers.ikea_scroll.scroll_utils.fields"
local event_utils = require "sub_drivers.ikea_scroll.scroll_utils.event_utils"

local IkeaScrollEventHandlers = {}

local function rotate_amount_event_helper(device, endpoint_id, num_presses_to_handle)
if num_presses_to_handle <= 0 then return end

-- to cut down on checks, we can assume that if the endpoint is not in ENDPOINTS_UP_SCROLL, it is in ENDPOINTS_DOWN_SCROLL
local scroll_direction = switch_utils.tbl_contains(scroll_fields.ENDPOINTS_UP_SCROLL, endpoint_id) and 1 or -1
local scroll_amount = st_utils.clamp_value(scroll_direction * scroll_fields.PER_SCROLL_EVENT_ROTATION * num_presses_to_handle, -100, 100)
device:emit_event_for_endpoint(endpoint_id, capabilities.knob.rotateAmount(scroll_amount, {state_change = true}))

if event_utils.is_valid_scroll_amount(device, scroll_amount) then
device:emit_event_for_endpoint(endpoint_id, capabilities.knob.rotateAmount(scroll_amount, {state_change = true}))
end
end

-- Used by ENDPOINTS_UP_SCROLL and ENDPOINTS_DOWN_SCROLL, not ENDPOINTS_PUSH
function IkeaScrollEventHandlers.multi_press_ongoing_handler(driver, device, ib, response)
if switch_utils.tbl_contains(scroll_fields.ENDPOINTS_PUSH, ib.endpoint_id) then
-- Ignore MultiPressOngoing events from push endpoints.
device.log.debug("Received MultiPressOngoing event from push endpoint, ignoring.")
else
local cur_num_presses_counted = ib.data and ib.data.elements and ib.data.elements.current_number_of_presses_counted.value or 0
local num_presses_to_handle = cur_num_presses_counted - (device:get_field(scroll_fields.LATEST_NUMBER_OF_PRESSES_COUNTED) or 0)
if num_presses_to_handle > 0 then
device:set_field(scroll_fields.LATEST_NUMBER_OF_PRESSES_COUNTED, cur_num_presses_counted)
rotate_amount_event_helper(device, ib.endpoint_id, num_presses_to_handle)
local cur_num_presses_counted = ib.data.elements and ib.data.elements.current_number_of_presses_counted.value or 0

@tpmanley tpmanley Jun 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a reason to remove the ib.data and from this line?

@hcarter-775 hcarter-775 Jun 15, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The existence of ib.data is ensured at the table creation level in the lua libs, something I wasn't thinking about when I first wrote this code.

local cur_multi_press_count = cur_num_presses_counted
if #response.info_blocks > 1 then

@tpmanley tpmanley Jun 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there something that prevents adding unit tests for this?

@hcarter-775 hcarter-775 Jun 15, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, the current test request block logic only allows one info block per request. Thus, multi-event response blocks cannot be explicitly tested via unit test today without semi-significant Integration Test reworks for Matter.

if event_utils.is_last_valid_info_block(ib.event_id, cur_num_presses_counted, response.info_blocks) then
local aggregated_presses = event_utils.aggregate_scroll_amount_for_info_blocks(device, response.info_blocks) or {}
cur_num_presses_counted = aggregated_presses.total_presses or 0
cur_multi_press_count = aggregated_presses.presses_in_current_chain or 0
else
device.log.debug("Received MultiPressOngoing event that is not the last valid info block, ignoring.")
return
end
end
local num_presses_to_handle = cur_num_presses_counted - (device:get_field(scroll_fields.LATEST_NUMBER_OF_PRESSES_HANDLED) or 0)
device:set_field(scroll_fields.LATEST_NUMBER_OF_PRESSES_HANDLED, cur_multi_press_count)
rotate_amount_event_helper(device, ib.endpoint_id, num_presses_to_handle)
end
end

function IkeaScrollEventHandlers.multi_press_complete_handler(driver, device, ib, response)
if switch_utils.tbl_contains(scroll_fields.ENDPOINTS_PUSH, ib.endpoint_id) then
generic_event_handlers.multi_press_complete_handler(driver, device, ib, response)
else
local total_num_presses_counted = ib.data and ib.data.elements and ib.data.elements.total_number_of_presses_counted.value or 0
local num_presses_to_handle = total_num_presses_counted - (device:get_field(scroll_fields.LATEST_NUMBER_OF_PRESSES_COUNTED) or 0)
if num_presses_to_handle > 0 then
rotate_amount_event_helper(device, ib.endpoint_id, num_presses_to_handle)
local total_num_presses_counted = ib.data.elements and ib.data.elements.total_number_of_presses_counted.value or 0
if #response.info_blocks > 1 then
if event_utils.is_last_valid_info_block(ib.event_id, total_num_presses_counted, response.info_blocks) then
local aggregated_presses = event_utils.aggregate_scroll_amount_for_info_blocks(device, response.info_blocks) or {}
total_num_presses_counted = aggregated_presses.total_presses or 0
else
device.log.debug("Received MultiPressComplete event that is not the last valid info block, ignoring.")
return
end
end
-- reset the LATEST_NUMBER_OF_PRESSES_COUNTED to nil at the end of a MultiPress chain.
device:set_field(scroll_fields.LATEST_NUMBER_OF_PRESSES_COUNTED, nil)
local num_presses_to_handle = total_num_presses_counted - (device:get_field(scroll_fields.LATEST_NUMBER_OF_PRESSES_HANDLED) or 0)
rotate_amount_event_helper(device, ib.endpoint_id, num_presses_to_handle)
-- always reset the LATEST_NUMBER_OF_PRESSES_HANDLED to nil at the end of a handled MultiPress chain.
device:set_field(scroll_fields.LATEST_NUMBER_OF_PRESSES_HANDLED, nil)
end
end

function IkeaScrollEventHandlers.initial_press_handler(driver, device, ib, response)
if switch_utils.tbl_contains(scroll_fields.ENDPOINTS_PUSH, ib.endpoint_id) then
generic_event_handlers.initial_press_handler(driver, device, ib, response)
else
-- the magic number "1" occurs in this handler since the InitialPress event represents the first press.
local latest_presses_counted = device:get_field(scroll_fields.LATEST_NUMBER_OF_PRESSES_COUNTED) or 0
if latest_presses_counted == 0 then
device:set_field(scroll_fields.LATEST_NUMBER_OF_PRESSES_COUNTED, 1)
rotate_amount_event_helper(device, ib.endpoint_id, 1)
end
device.log.debug("Received InitialPress event from scroll endpoint, ignoring.")

@tpmanley tpmanley Jun 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you either break this change into its own PR or update the title and description to include this? It's pretty significant and I think it's just not sufficiently called out currently.

@hcarter-775 hcarter-775 Jun 15, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

added to title/desc!

end
end

Expand Down
76 changes: 76 additions & 0 deletions drivers/SmartThings/matter-switch/src/sub_drivers/ikea_scroll/scroll_utils/event_utils.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
-- Copyright © 2026 SmartThings, Inc.
-- Licensed under the Apache License, Version 2.0

local st_utils = require "st.utils"
local clusters = require "st.matter.clusters"
local scroll_fields = require "sub_drivers.ikea_scroll.scroll_utils.fields"

local IkeaScrollEventUtils = {}


function IkeaScrollEventUtils.requeue_clear_scroll_state(device)
-- cancel any previously queued clear state actions to prevent unintended clears
if device:get_field(scroll_fields.CLEAR_STATE_TIMER) then
device.thread:cancel_timer(device:get_field(scroll_fields.CLEAR_STATE_TIMER))
end
local new_timer = device.thread:call_with_delay(scroll_fields.CLEAR_STATE_DELAY_S, function()
device:set_field(scroll_fields.GLOBAL_ROTATE_AMOUNT_STATE, 0)
end)
device:set_field(scroll_fields.CLEAR_STATE_TIMER, new_timer)
end

function IkeaScrollEventUtils.is_valid_scroll_amount(device, scroll_amount)
local global_rotate_amount_state = device:get_field(scroll_fields.GLOBAL_ROTATE_AMOUNT_STATE) or 0
local is_rotate_amount_state_at_bounds = (scroll_amount < 0 and global_rotate_amount_state <= -100) or (scroll_amount > 0 and global_rotate_amount_state >= 100)
if is_rotate_amount_state_at_bounds then
return false
end

device:set_field(scroll_fields.GLOBAL_ROTATE_AMOUNT_STATE, st_utils.clamp_value(global_rotate_amount_state + scroll_amount, -100, 100))
IkeaScrollEventUtils.requeue_clear_scroll_state(device)
return true
end

-- inspect all info blocks to find the last one that is not an InitialPress event. We will
-- only try to emit a rotateAmount event if the current info block being handled is that last one.
function IkeaScrollEventUtils.is_last_valid_info_block(cur_info_block_event_id, cur_info_block_value, info_blocks)
local last_valid_emission_idx = #info_blocks
-- Ignore all InitialPress events in a multi-response block
while (last_valid_emission_idx > 1) and (info_blocks[last_valid_emission_idx].info_block.event_id == clusters.Switch.events.InitialPress.ID) do
last_valid_emission_idx = last_valid_emission_idx - 1
end

-- Because the info block does not include the unique_key Matter defined event number, this
-- logic is a best guess at matching the current info block to the last valid info block.
local emission_ib = info_blocks[last_valid_emission_idx].info_block
if emission_ib.event_id ~= cur_info_block_event_id then
return false
elseif emission_ib.event_id == clusters.Switch.events.MultiPressComplete.ID then
local last_valid_ib_value = emission_ib.data.elements and emission_ib.data.elements.total_number_of_presses_counted.value or 0
return last_valid_ib_value == cur_info_block_value
elseif emission_ib.event_id == clusters.Switch.events.MultiPressOngoing.ID then
local last_valid_ib_value = emission_ib.data.elements and emission_ib.data.elements.current_number_of_presses_counted.value or 0
return last_valid_ib_value == cur_info_block_value
elseif last_valid_emission_idx == 1 then -- aka, all ib's are InitialPress
return true
end

return false
end

function IkeaScrollEventUtils.aggregate_scroll_amount_for_info_blocks(device, info_blocks)
local total_presses = 0
local presses_in_current_chain = 0
for _, ib in ipairs(info_blocks) do
if ib.info_block.event_id == clusters.Switch.events.MultiPressOngoing.ID then
presses_in_current_chain = presses_in_current_chain + (ib.info_block.data.elements and ib.info_block.data.elements.current_number_of_presses_counted.value or 0)

@tpmanley tpmanley Jun 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If the message contains multiple MultiPressOngoing events I think we want to take the current_number_of_presses_counted from the last one and not add the value reported in each one. For example, say we receive a message that has MultiPressOngoing events with current_number_of_presses_counted values of 3, 6 and 12. We want the result to be 12, not 3 + 6 + 12.

@hcarter-775 hcarter-775 Jun 15, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ah, yeah that's very true. Will make that update!

elseif ib.info_block.event_id == clusters.Switch.events.MultiPressComplete.ID then
total_presses = total_presses + (ib.info_block.data.elements and ib.info_block.data.elements.total_number_of_presses_counted.value or 0)
presses_in_current_chain = 0
end
end
total_presses = total_presses + presses_in_current_chain -- aggregate any presses to the total from the current chain
return { total_presses = total_presses, presses_in_current_chain = presses_in_current_chain }
end

return IkeaScrollEventUtils
20 changes: 13 additions & 7 deletions drivers/SmartThings/matter-switch/src/sub_drivers/ikea_scroll/scroll_utils/fields.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
-- Copyright © 2025 SmartThings, Inc.
-- Licensed under the Apache License, Version 2.0

local st_utils = require "st.utils"
local clusters = require "st.matter.clusters"

local IkeaScrollFields = {}
Expand All @@ -18,14 +17,21 @@ IkeaScrollFields.ENDPOINTS_UP_SCROLL = {1, 4, 7}
-- Generic Switch Endpoints used for Down Scroll functionality
IkeaScrollFields.ENDPOINTS_DOWN_SCROLL = {2, 5, 8}

-- Maximum number of presses at a time
IkeaScrollFields.MAX_SCROLL_PRESSES = 18

-- Amount to rotate per scroll event
IkeaScrollFields.PER_SCROLL_EVENT_ROTATION = st_utils.round(1 / IkeaScrollFields.MAX_SCROLL_PRESSES * 100)
-- 6 == st_utils.round(1/18 * 100), where 18 is the maximum number of presses that can be pressed at a time
IkeaScrollFields.PER_SCROLL_EVENT_ROTATION = 6

-- Field to track the latest number of presses handled during a single scroll event sequence
IkeaScrollFields.LATEST_NUMBER_OF_PRESSES_HANDLED = "__latest_number_of_presses_handled"

-- Field to track the global rotate amount state for the device to ensure no scroll events mapped outside of state bounds are emitted
IkeaScrollFields.GLOBAL_ROTATE_AMOUNT_STATE = "__global_rotate_amount_state"

-- Stores a timer object, which is required to cancel a timer early
IkeaScrollFields.CLEAR_STATE_TIMER = "__clear_state_timer"

-- Field to track the latest number of presses counted during a single scroll event sequence
IkeaScrollFields.LATEST_NUMBER_OF_PRESSES_COUNTED = "__latest_number_of_presses_counted"
-- Delay in seconds to wait before clearing the global rotate amount state after the last scroll event
IkeaScrollFields.CLEAR_STATE_DELAY_S = 8

-- Required Events for the ENDPOINTS_PUSH.
IkeaScrollFields.switch_press_subscribed_events = {
Expand Down
72 changes: 16 additions & 56 deletions drivers/SmartThings/matter-switch/src/test/test_ikea_scroll.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -249,12 +249,7 @@ test.register_message_test(
)
},
},
{
channel = "capability",
direction = "send",
message = mock_ikea_scroll:generate_test_message("main",
capabilities.knob.rotateAmount(6, {state_change = true}))
},
-- ignore InitialPress events during scroll
{
channel = "matter",
direction = "receive",
Expand All @@ -269,7 +264,7 @@ test.register_message_test(
channel = "capability",
direction = "send",
message = mock_ikea_scroll:generate_test_message("main",
capabilities.knob.rotateAmount(6, {state_change = true}))
capabilities.knob.rotateAmount(12, {state_change = true}))
},
{
channel = "matter",
Expand Down Expand Up @@ -307,12 +302,7 @@ test.register_message_test(
)
},
},
{
channel = "capability",
direction = "send",
message = mock_ikea_scroll:generate_test_message("main",
capabilities.knob.rotateAmount(6, {state_change = true}))
},
-- ignore InitialPress events during scroll
{
channel = "matter",
direction = "receive",
Expand All @@ -327,7 +317,7 @@ test.register_message_test(
channel = "capability",
direction = "send",
message = mock_ikea_scroll:generate_test_message("main",
capabilities.knob.rotateAmount(6, {state_change = true}))
capabilities.knob.rotateAmount(12, {state_change = true}))
},
{
channel = "matter",
Expand Down Expand Up @@ -373,12 +363,7 @@ test.register_message_test(
)
},
},
{
channel = "capability",
direction = "send",
message = mock_ikea_scroll:generate_test_message("main",
capabilities.knob.rotateAmount(-6, {state_change = true}))
},
-- ignore InitialPress events during scroll
{
channel = "matter",
direction = "receive",
Expand All @@ -393,7 +378,7 @@ test.register_message_test(
channel = "capability",
direction = "send",
message = mock_ikea_scroll:generate_test_message("main",
capabilities.knob.rotateAmount(-6, {state_change = true}))
capabilities.knob.rotateAmount(-12, {state_change = true}))
},
{
channel = "matter",
Expand Down Expand Up @@ -431,12 +416,7 @@ test.register_message_test(
)
},
},
{
channel = "capability",
direction = "send",
message = mock_ikea_scroll:generate_test_message("main",
capabilities.knob.rotateAmount(-6, {state_change = true}))
},
-- ignore InitialPress events during scroll
{
channel = "matter",
direction = "receive",
Expand All @@ -451,7 +431,7 @@ test.register_message_test(
channel = "capability",
direction = "send",
message = mock_ikea_scroll:generate_test_message("main",
capabilities.knob.rotateAmount(-6, {state_change = true}))
capabilities.knob.rotateAmount(-12, {state_change = true}))
},
{
channel = "matter",
Expand Down Expand Up @@ -497,12 +477,7 @@ test.register_message_test(
)
},
},
{
channel = "capability",
direction = "send",
message = mock_ikea_scroll:generate_test_message("group2",
capabilities.knob.rotateAmount(6, {state_change = true}))
},
-- ignore InitialPress events during scroll
{
channel = "matter",
direction = "receive",
Expand All @@ -517,7 +492,7 @@ test.register_message_test(
channel = "capability",
direction = "send",
message = mock_ikea_scroll:generate_test_message("group2",
capabilities.knob.rotateAmount(6, {state_change = true}))
capabilities.knob.rotateAmount(12, {state_change = true}))
},
{
channel = "matter",
Expand Down Expand Up @@ -553,12 +528,7 @@ test.register_message_test(
)
},
},
{
channel = "capability",
direction = "send",
message = mock_ikea_scroll:generate_test_message("group2",
capabilities.knob.rotateAmount(-6, {state_change = true}))
},
-- ignore InitialPress events during scroll
{
channel = "matter",
direction = "receive",
Expand All @@ -573,7 +543,7 @@ test.register_message_test(
channel = "capability",
direction = "send",
message = mock_ikea_scroll:generate_test_message("group2",
capabilities.knob.rotateAmount(-6, {state_change = true}))
capabilities.knob.rotateAmount(-12, {state_change = true}))
},
{
channel = "matter",
Expand Down Expand Up @@ -609,12 +579,7 @@ test.register_message_test(
)
},
},
{
channel = "capability",
direction = "send",
message = mock_ikea_scroll:generate_test_message("group3",
capabilities.knob.rotateAmount(6, {state_change = true}))
},
-- ignore InitialPress events during scroll
{
channel = "matter",
direction = "receive",
Expand All @@ -629,7 +594,7 @@ test.register_message_test(
channel = "capability",
direction = "send",
message = mock_ikea_scroll:generate_test_message("group3",
capabilities.knob.rotateAmount(6, {state_change = true}))
capabilities.knob.rotateAmount(12, {state_change = true}))
},
{
channel = "matter",
Expand Down Expand Up @@ -665,12 +630,7 @@ test.register_message_test(
)
},
},
{
channel = "capability",
direction = "send",
message = mock_ikea_scroll:generate_test_message("group3",
capabilities.knob.rotateAmount(-6, {state_change = true}))
},
-- ignore InitialPress events during scroll
{
channel = "matter",
direction = "receive",
Expand All @@ -685,7 +645,7 @@ test.register_message_test(
channel = "capability",
direction = "send",
message = mock_ikea_scroll:generate_test_message("group3",
capabilities.knob.rotateAmount(-6, {state_change = true}))
capabilities.knob.rotateAmount(-12, {state_change = true}))
},
{
channel = "matter",
Expand Down
Loading