Linux tv-casting-app: simplified Endpoints APIs and post-connection flow (#30940)

Author: sharadb-amazon

examples/tv-casting-app/APIs.md

@@ -38,8 +38,8 @@ Commissioner. In the context of the
 [Matter Video Player architecture](https://github.com/CHIP-Specifications/connectedhomeip-spec/blob/master/src/app_clusters/media/VideoPlayerArchitecture.adoc),
 a `CastingPlayer` would map to
 [Casting "Video" Player](https://github.com/CHIP-Specifications/connectedhomeip-spec/blob/master/src/app_clusters/media/VideoPlayerArchitecture.adoc#1-introduction).
-The `CastingPlayer` is expected to be hosting one or more `Endpoints` (similar
-to
+The `CastingPlayer` is expected to be hosting one or more `Endpoints` (some of
+which can represent
 [Content Apps](https://github.com/CHIP-Specifications/connectedhomeip-spec/blob/master/src/app_clusters/media/VideoPlayerArchitecture.adoc#1-introduction)
 in the Matter Video Player architecture) that support one or more Matter Media
 `Clusters`.
@@ -73,7 +73,10 @@ The Casting Client is expected to consume the Matter TV Casting library built
 for its respective platform which implements the APIs described in this
 document. Refer to the tv-casting-app READMEs for [Linux](linux/README.md),
 Android and [iOS](darwin/TvCasting/README.md) to understand how to build and
-consume each platform's specific libraries.
+consume each platform's specific libraries. The libraries MUST be built with the
+client's specific values for `CHIP_DEVICE_CONFIG_DEVICE_VENDOR_ID` and
+`CHIP_DEVICE_CONFIG_DEVICE_PRODUCT_ID` updated in the
+[CHIPProjectAppConfig.h](tv-casting-common/include/CHIPProjectAppConfig.h) file.
 
 ### Initialize the Casting Client
 
@@ -474,19 +477,33 @@ to a `CastingPlayer`, once the Casting client has been commissioned by it. After
 that, the Casting client is able to skip the full UDC process by establishing
 CASE with the `CastingPlayer` directly. Once connected, the `CastingPlayer`
 object will contain the list of available Endpoints on that `CastingPlayer`.
+Optionally, the following arguments may also be passed in. The optional
+`commissioningWindowTimeoutSec` indicates how long to keep the commissioning
+window open, if commissioning is required. And `DesiredEndpointFilter` specifies
+the attributes, such as Vendor ID and Product ID of the `Endpoint`, the Casting
+client desires to interact with after connecting. This forces the Matter TV
+Casting library to go through the full UDC process in search of the desired
+Endpoint, in cases where it is not available in the Casting client's cache.
 
 On Linux, the Casting Client can connect to a `CastingPlayer` by successfully
 calling `VerifyOrEstablishConnection` on it.
 
 ```c
+
+const uint16_t kDesiredEndpointVendorId = 65521;
+
 void ConnectionHandler(CHIP_ERROR err, matter::casting::core::CastingPlayer * castingPlayer)
 {
     ChipLogProgress(AppServer, "ConnectionHandler called with %" CHIP_ERROR_FORMAT, err.Format());
 }
 
 ...
 // targetCastingPlayer is a discovered CastingPlayer
-targetCastingPlayer->VerifyOrEstablishConnection(ConnectionHandler);
+matter::casting::core::EndpointFilter desiredEndpointFilter;
+desiredEndpointFilter.vendorId = kDesiredEndpointVendorId;
+targetCastingPlayer->VerifyOrEstablishConnection(ConnectionHandler,
+                                                    matter::casting::core::kCommissioningWindowTimeoutSec,
+                                                    desiredEndpointFilter);
 ...
 ```
 

examples/tv-casting-app/linux/simple-app-helper.cpp

@@ -16,6 +16,8 @@
  */
 #include "simple-app-helper.h"
 
+#include "clusters/ContentLauncherCluster.h"
+
 #include "app/clusters/bindings/BindingManager.h"
 #include <inttypes.h>
 #include <lib/core/CHIPCore.h>
@@ -27,6 +29,9 @@
 #include <lib/support/CodeUtils.h>
 #include <platform/CHIPDeviceLayer.h>
 
+// VendorId of the Endpoint on the CastingPlayer that the CastingApp desires to interact with after connection
+const uint16_t kDesiredEndpointVendorId = 65521;
+
 DiscoveryDelegateImpl * DiscoveryDelegateImpl::_discoveryDelegateImpl = nullptr;
 
 DiscoveryDelegateImpl * DiscoveryDelegateImpl::GetInstance()
@@ -102,7 +107,11 @@ CHIP_ERROR CommandHandler(int argc, char ** argv)
         VerifyOrReturnValue(0 <= index && index < castingPlayers.size(), CHIP_ERROR_INVALID_ARGUMENT,
                             ChipLogError(AppServer, "Invalid casting player index provided: %lu", index));
         std::shared_ptr<matter::casting::core::CastingPlayer> targetCastingPlayer = castingPlayers.at(index);
-        targetCastingPlayer->VerifyOrEstablishConnection(ConnectionHandler);
+
+        matter::casting::core::EndpointFilter desiredEndpointFilter;
+        desiredEndpointFilter.vendorId = kDesiredEndpointVendorId;
+        targetCastingPlayer->VerifyOrEstablishConnection(ConnectionHandler, matter::casting::core::kCommissioningWindowTimeoutSec,
+                                                         desiredEndpointFilter);
         return CHIP_NO_ERROR;
     }
     if (strcmp(argv[0], "print-bindings") == 0)

examples/tv-casting-app/linux/simple-app-helper.h

@@ -21,7 +21,6 @@
 #include "core/CastingPlayer.h"
 #include "core/CastingPlayerDiscovery.h"
 #include "core/Types.h"
-
 #include <platform/CHIPDeviceLayer.h>
 
 /**

examples/tv-casting-app/tv-casting-common/BUILD.gn

@@ -93,19 +93,27 @@ chip_data_model("tv-casting-common") {
 
   # Add simplified casting API files here
   sources += [
+    "clusters/ContentLauncherCluster.h",
+    "clusters/MediaPlaybackCluster.h",
+    "clusters/TargetNavigatorCluster.h",
+    "core/Attribute.h",
     "core/CastingApp.cpp",
     "core/CastingApp.h",
     "core/CastingPlayer.cpp",
     "core/CastingPlayer.h",
     "core/CastingPlayerDiscovery.cpp",
     "core/CastingPlayerDiscovery.h",
+    "core/Cluster.h",
+    "core/Endpoint.h",
     "core/Types.h",
     "support/AppParameters.h",
     "support/CastingStore.cpp",
     "support/CastingStore.h",
     "support/ChipDeviceEventHandler.cpp",
     "support/ChipDeviceEventHandler.h",
     "support/DataProvider.h",
+    "support/EndpointListLoader.cpp",
+    "support/EndpointListLoader.h",
   ]
 
   deps = [

examples/tv-casting-app/tv-casting-common/clusters/ContentLauncherCluster.h

@@ -0,0 +1,44 @@
+/*
+ *
+ *    Copyright (c) 2023 Project CHIP Authors
+ *    All rights reserved.
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ */
+
+#pragma once
+
+#include "core/Endpoint.h"
+#include "core/Types.h"
+
+#include "lib/support/logging/CHIPLogging.h"
+
+namespace matter {
+namespace casting {
+namespace clusters {
+
+class ContentLauncherCluster : public core::BaseCluster
+{
+private:
+protected:
+public:
+    ContentLauncherCluster(memory::Weak<core::Endpoint> endpoint) : core::BaseCluster(endpoint) {}
+
+    // TODO:
+    // LaunchURL(const char * contentUrl, const char * contentDisplayStr,
+    //       chip::Optional<chip::app::Clusters::ContentLauncher::Structs::BrandingInformationStruct::Type> brandingInformation);
+};
+
+}; // namespace clusters
+}; // namespace casting
+}; // namespace matter

examples/tv-casting-app/tv-casting-common/clusters/MediaPlaybackCluster.h

@@ -0,0 +1,42 @@
+/*
+ *
+ *    Copyright (c) 2023 Project CHIP Authors
+ *    All rights reserved.
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ */
+
+#pragma once
+
+#include "core/Endpoint.h"
+#include "core/Types.h"
+
+#include "lib/support/logging/CHIPLogging.h"
+
+namespace matter {
+namespace casting {
+namespace clusters {
+
+class MediaPlaybackCluster : public core::BaseCluster
+{
+private:
+protected:
+public:
+    MediaPlaybackCluster(memory::Weak<core::Endpoint> endpoint) : core::BaseCluster(endpoint) {}
+
+    // TODO: add commands
+};
+
+}; // namespace clusters
+}; // namespace casting
+}; // namespace matter

examples/tv-casting-app/tv-casting-common/clusters/TargetNavigatorCluster.h

@@ -0,0 +1,42 @@
+/*
+ *
+ *    Copyright (c) 2023 Project CHIP Authors
+ *    All rights reserved.
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ */
+
+#pragma once
+
+#include "core/Endpoint.h"
+#include "core/Types.h"
+
+#include "lib/support/logging/CHIPLogging.h"
+
+namespace matter {
+namespace casting {
+namespace clusters {
+
+class TargetNavigatorCluster : public core::BaseCluster
+{
+private:
+protected:
+public:
+    TargetNavigatorCluster(memory::Weak<core::Endpoint> endpoint) : core::BaseCluster(endpoint) {}
+
+    // TODO: add commands
+};
+
+}; // namespace clusters
+}; // namespace casting
+}; // namespace matter

examples/tv-casting-app/tv-casting-common/core/Attribute.h

@@ -0,0 +1,76 @@
+/*
+ *
+ *    Copyright (c) 2023 Project CHIP Authors
+ *    All rights reserved.
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ */
+
+#pragma once
+
+#include "Cluster.h"
+#include "Types.h"
+
+#include "lib/support/logging/CHIPLogging.h"
+
+namespace matter {
+namespace casting {
+namespace core {
+
+enum ReadAttributeError
+{
+    READ_ATTRIBUTE_NO_ERROR
+};
+
+enum WriteAttributeError
+{
+    WRITE_ATTRIBUTE_NO_ERROR
+};
+
+template <typename ValueType>
+using ReadAttributeCallback = std::function<void(Optional<ValueType> before, ValueType after, ReadAttributeError)>;
+
+using WriteAttributeCallback = std::function<void(WriteAttributeError)>;
+
+class BaseCluster;
+
+template <typename ValueType>
+class Attribute
+{
+private:
+    memory::Weak<BaseCluster> cluster;
+    ValueType value;
+
+public:
+    Attribute(memory::Weak<BaseCluster> cluster) { this->cluster = cluster; }
+
+    ~Attribute() {}
+
+    Attribute()                       = delete;
+    Attribute(Attribute & other)      = delete;
+    void operator=(const Attribute &) = delete;
+
+protected:
+    memory::Strong<BaseCluster> GetCluster() const { return cluster.lock(); }
+
+public:
+    ValueType GetValue();
+    void Read(ReadAttributeCallback<ValueType> onRead);
+    void Write(ValueType value, WriteAttributeCallback onWrite);
+    bool SubscribeAttribute(AttributeId attributeId, ReadAttributeCallback<ValueType> callback);
+    bool UnsubscribeAttribute(AttributeId attributeId, ReadAttributeCallback<ValueType> callback);
+};
+
+}; // namespace core
+}; // namespace casting
+}; // namespace matter