Update subscription_command callbacks

tomasmcguinness · tomasmcguinness · commit d87aea1b8428 · 2026-03-05T09:42:50.000Z
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -1,3 +1,8 @@
+# 5-Mar-2026
+### API Changes
+- In `subscribe_command`, `subscribe_done_cb_t` has been renamed to `subscribe_terminated_cb_t` to align better with the terminology.
+- In `subscribe_command` a new callback `subscription_established_cb_t` has been added to report successfully subscription commands. 
+
 # 4-Feb-2026
 ### API Changes
 - Removed APIs: `plugin_init_callback_common()`, `add_bounds_callback_common()` and `delegate_init_callback_common()`.
diff --git a/components/esp_matter_controller/commands/esp_matter_controller_subscribe_command.cpp b/components/esp_matter_controller/commands/esp_matter_controller_subscribe_command.cpp
@@ -159,6 +159,11 @@ void subscribe_command::OnSubscriptionEstablished(chip::SubscriptionId subscript
     m_subscription_id = subscriptionId;
     m_resubscribe_retries = 0;
     ESP_LOGI(TAG, "Subscription 0x%" PRIx32 " established", subscriptionId);
+
+    if (subscription_established_cb) {
+        // This will be called when the subscription is established.
+        subscription_established_cb(m_node_id, m_subscription_id);
+    }
 }
 
 CHIP_ERROR subscribe_command::OnResubscriptionNeeded(ReadClient *apReadClient, CHIP_ERROR aTerminationCause)
@@ -175,9 +180,9 @@ CHIP_ERROR subscribe_command::OnResubscriptionNeeded(ReadClient *apReadClient, C
 void subscribe_command::OnDone(ReadClient *apReadClient)
 {
     ESP_LOGI(TAG, "Subscription 0x%" PRIx32 " Done for remote node 0x%" PRIx64, m_subscription_id, m_node_id);
-    if (subscribe_done_cb) {
+    if (subscription_terminated_cb) {
         // This will be called when the subscription is terminated.
-        subscribe_done_cb(m_node_id, m_subscription_id);
+        subscription_terminated_cb(m_node_id, m_subscription_id);
     }
     chip::Platform::Delete(this);
 }
@@ -207,7 +212,7 @@ esp_err_t send_subscribe_attr_command(uint64_t node_id, ScopedMemoryBufferWithSi
 
     subscribe_command *cmd = chip::Platform::New<subscribe_command>(
                                  node_id, std::move(attr_paths), std::move(event_paths), min_interval, max_interval, auto_resubscribe, nullptr,
-                                 nullptr, nullptr, nullptr, keep_subscription);
+                                 nullptr, nullptr, nullptr, nullptr, keep_subscription);
     if (!cmd) {
         ESP_LOGE(TAG, "Failed to alloc memory for subscribe_command");
         return ESP_ERR_NO_MEM;
@@ -240,7 +245,7 @@ esp_err_t send_subscribe_event_command(uint64_t node_id, ScopedMemoryBufferWithS
 
     subscribe_command *cmd = chip::Platform::New<subscribe_command>(
                                  node_id, std::move(attr_paths), std::move(event_paths), min_interval, max_interval, auto_resubscribe, nullptr,
-                                 nullptr, nullptr, nullptr, keep_subscription);
+                                 nullptr, nullptr, nullptr, nullptr, keep_subscription);
     if (!cmd) {
         ESP_LOGE(TAG, "Failed to alloc memory for subscribe_command");
         return ESP_ERR_NO_MEM;
diff --git a/components/esp_matter_controller/commands/esp_matter_controller_subscribe_command.h b/components/esp_matter_controller/commands/esp_matter_controller_subscribe_command.h
@@ -45,7 +45,31 @@ class subscribe_command : public ReadClient::Callback {
     subscribe_command(uint64_t node_id, ScopedMemoryBufferWithSize<AttributePathParams> &&attr_paths,
                       ScopedMemoryBufferWithSize<EventPathParams> &&event_paths, uint16_t min_interval,
                       uint16_t max_interval, bool auto_resubscribe = true, attribute_report_cb_t attribute_cb = nullptr,
-                      event_report_cb_t event_cb = nullptr, subscribe_done_cb_t done_cb = nullptr,
+                      event_report_cb_t event_cb = nullptr, subscription_established_cb_t established_cb = nullptr,
+                      subscription_terminated_cb_t terminated_cb = nullptr, subscribe_failure_cb_t connect_failure_cb = nullptr, bool keep_subscription = true)
+        : m_node_id(node_id)
+        , m_min_interval(min_interval)
+        , m_max_interval(max_interval)
+        , m_auto_resubscribe(auto_resubscribe)
+        , m_keep_subscription(keep_subscription)
+        , m_buffered_read_cb(*this)
+        , m_attr_paths(std::move(attr_paths))
+        , m_event_paths(std::move(event_paths))
+        , on_device_connected_cb(on_device_connected_fcn, this)
+        , on_device_connection_failure_cb(on_device_connection_failure_fcn, this)
+        , attribute_data_cb(attribute_cb)
+        , event_data_cb(event_cb)
+        , subscription_established_cb(established_cb)
+        , subscription_terminated_cb(terminated_cb)
+        , subscribe_failure_cb(connect_failure_cb)
+    {
+    }
+
+    /** Constructor for command with multiple paths**/
+    subscribe_command(uint64_t node_id, ScopedMemoryBufferWithSize<AttributePathParams> &&attr_paths,
+                      ScopedMemoryBufferWithSize<EventPathParams> &&event_paths, uint16_t min_interval,
+                      uint16_t max_interval, bool auto_resubscribe = true, attribute_report_cb_t attribute_cb = nullptr,
+                      event_report_cb_t event_cb = nullptr, subscription_terminated_cb_t terminated_cb = nullptr,
                       subscribe_failure_cb_t connect_failure_cb = nullptr, bool keep_subscription = true)
         : m_node_id(node_id)
         , m_min_interval(min_interval)
@@ -59,9 +83,46 @@ class subscribe_command : public ReadClient::Callback {
         , on_device_connection_failure_cb(on_device_connection_failure_fcn, this)
         , attribute_data_cb(attribute_cb)
         , event_data_cb(event_cb)
-        , subscribe_done_cb(done_cb)
+        , subscription_terminated_cb(terminated_cb)
+        , subscribe_failure_cb(connect_failure_cb)
+    {
+    }
+
+    /** Constructor for command with single path.
+     * @note 0xFFFF could be used as wildcard EndpointId
+     * @note 0xFFFFFFFF could be used as wildcard ClusterId/AttributeId/EventId
+     */
+    subscribe_command(uint64_t node_id, uint16_t endpoint_id, uint32_t cluster_id, uint32_t attribute_or_event_id,
+                      subscribe_command_type_t command_type, uint16_t min_interval, uint16_t max_interval,
+                      bool auto_resubscribe = true, attribute_report_cb_t attribute_cb = nullptr,
+                      event_report_cb_t event_cb = nullptr, subscription_established_cb_t established_cb = nullptr,
+                      subscription_terminated_cb_t terminated_cb = nullptr, subscribe_failure_cb_t connect_failure_cb = nullptr,
+                      bool keep_subscription = true)
+        : m_node_id(node_id)
+        , m_min_interval(min_interval)
+        , m_max_interval(max_interval)
+        , m_auto_resubscribe(auto_resubscribe)
+        , m_keep_subscription(keep_subscription)
+        , m_buffered_read_cb(*this)
+        , on_device_connected_cb(on_device_connected_fcn, this)
+        , on_device_connection_failure_cb(on_device_connection_failure_fcn, this)
+        , attribute_data_cb(attribute_cb)
+        , event_data_cb(event_cb)
+        , subscription_established_cb(established_cb)
+        , subscription_terminated_cb(terminated_cb)
         , subscribe_failure_cb(connect_failure_cb)
     {
+        if (command_type == SUBSCRIBE_ATTRIBUTE) {
+            m_attr_paths.Alloc(1);
+            if (m_attr_paths.Get()) {
+                m_attr_paths[0] = AttributePathParams(endpoint_id, cluster_id, attribute_or_event_id);
+            }
+        } else if (command_type == SUBSCRIBE_EVENT) {
+            m_event_paths.Alloc(1);
+            if (m_event_paths.Get()) {
+                m_event_paths[0] = EventPathParams(endpoint_id, cluster_id, attribute_or_event_id);
+            }
+        }
     }
 
     /** Constructor for command with single path.
@@ -71,7 +132,7 @@ class subscribe_command : public ReadClient::Callback {
     subscribe_command(uint64_t node_id, uint16_t endpoint_id, uint32_t cluster_id, uint32_t attribute_or_event_id,
                       subscribe_command_type_t command_type, uint16_t min_interval, uint16_t max_interval,
                       bool auto_resubscribe = true, attribute_report_cb_t attribute_cb = nullptr,
-                      event_report_cb_t event_cb = nullptr, subscribe_done_cb_t done_cb = nullptr,
+                      event_report_cb_t event_cb = nullptr, subscription_terminated_cb_t terminated_cb = nullptr,
                       subscribe_failure_cb_t connect_failure_cb = nullptr, bool keep_subscription = true)
         : m_node_id(node_id)
         , m_min_interval(min_interval)
@@ -83,7 +144,7 @@ class subscribe_command : public ReadClient::Callback {
         , on_device_connection_failure_cb(on_device_connection_failure_fcn, this)
         , attribute_data_cb(attribute_cb)
         , event_data_cb(event_cb)
-        , subscribe_done_cb(done_cb)
+        , subscription_terminated_cb(terminated_cb)
         , subscribe_failure_cb(connect_failure_cb)
     {
         if (command_type == SUBSCRIBE_ATTRIBUTE) {
@@ -145,7 +206,8 @@ class subscribe_command : public ReadClient::Callback {
     chip::Callback::Callback<chip::OnDeviceConnectionFailure> on_device_connection_failure_cb;
     attribute_report_cb_t attribute_data_cb;
     event_report_cb_t event_data_cb;
-    subscribe_done_cb_t subscribe_done_cb;
+    subscription_established_cb_t subscription_established_cb;
+    subscription_terminated_cb_t subscription_terminated_cb;
     subscribe_failure_cb_t subscribe_failure_cb;
 };
 
diff --git a/components/esp_matter_controller/core/esp_matter_controller_utils.h b/components/esp_matter_controller/core/esp_matter_controller_utils.h
@@ -31,7 +31,8 @@ using attribute_report_cb_t = void (*)(uint64_t remote_node_id, const chip::app:
                                        chip::TLV::TLVReader *data);
 using event_report_cb_t = void (*)(uint64_t remote_node_id, const chip::app::EventHeader &header,
                                    chip::TLV::TLVReader *data);
-using subscribe_done_cb_t = void (*)(uint64_t remote_node_id, uint32_t subscription_id);
+using subscription_established_cb_t = void (*)(uint64_t remote_node_id, uint32_t subscription_id);
+using subscription_terminated_cb_t = void (*)(uint64_t remote_node_id, uint32_t subscription_id);
 using subscribe_failure_cb_t = void (*)(void *subscribe_command);
 using read_done_cb_t = void (*)(uint64_t remote_node_id,
                                 const ScopedMemoryBufferWithSize<AttributePathParams> &attr_paths,
diff --git a/docs/en/controller.rst b/docs/en/controller.rst
@@ -36,10 +36,10 @@ The controller should support the following features:
 The ``invoke-cmd`` command is used for sending cluster commands to the end-devices. It utilizes a ``cluster_command`` class to establish the sessions and send the command packets. The class constructor function could accept two callback inputs:
 
 - **Success callback**:
-  This callback will be called upon the reception of the success response. It could be used to handle the response data for the command that requires a reponse. Now the default success callback will print the response data for GroupKeyManagement, Groups, Scenes, Thermostat, and DoorLock clusters. If you want to handle the response data in your example, you can register your success callback when creating the ``cluster_command`` object.
+  This callback will be called upon the reception of the success response. It could be used to handle the response data for the command that requires a response. Now the default success callback will print the response data for GroupKeyManagement, Groups, Scenes, Thermostat, and DoorLock clusters. If you want to handle the response data in your example, you can register your success callback when creating the ``cluster_command`` object.
 
 - **Error callback**:
-  This callback will be called upon the reception of the failure response or reponse timeout.
+  This callback will be called upon the reception of the failure response or response timeout.
 
 ^^^^^^^^^^^^^^^^
 
@@ -169,11 +169,11 @@ inputs:
 - **Event report callback**:
   This callback will be invoked upon the reception of the event report for subscribe-event commands.
 
-- **Subscribe done callback**:
-  This callback will be invoked when the subscription is terminated or shutdown.
+- **Subscription established callback**:
+  This callback will be invoked when the subscription is established successfully.
 
-- **Subscribe failure callback**:
-  This callback will be invoked upon the failure of establishing CASE session.
+- **Subscription terminated callback**:
+  This callback will be invoked when the subscription is terminated or shutdown.
 
 1.4.1 Subscribe attribute commands
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
