Add the ability to print help text for clusters to chip-tool. (#26392)

* Add the ability to print help text for clusters to chip-tool.

Also moves the "subscriptions" commands, which are not dependent on ZAP in any
way, out of generated stuff.

* Fix tv-casting-app build

* Also show help text in the cluster-specific help.

examples/chip-tool/commands/clusters/SubscriptionsCommands.h

@@ -94,7 +94,7 @@ class ShutdownAllSubscriptions : public CHIPCommand
 private:
 };
 
-void registerClusterSubscriptions(Commands & commands, CredentialIssuerCommands * credsIssuerConfig)
+void registerCommandsSubscriptions(Commands & commands, CredentialIssuerCommands * credsIssuerConfig)
 {
     const char * clusterName = "Subscriptions";
 
@@ -104,5 +104,5 @@ void registerClusterSubscriptions(Commands & commands, CredentialIssuerCommands
         make_unique<ShutdownAllSubscriptions>(credsIssuerConfig),     //
     };
 
-    commands.Register(clusterName, clusterCommands);
+    commands.Register(clusterName, clusterCommands, "Commands for shutting down subscriptions.");
 }

examples/chip-tool/commands/common/Commands.cpp

@@ -119,11 +119,12 @@ static void DetectAndLogMismatchedDoubleQuotes(int argc, char ** argv)
 
 } // namespace
 
-void Commands::Register(const char * clusterName, commands_list commandsList)
+void Commands::Register(const char * clusterName, commands_list commandsList, const char * helpText)
 {
+    mClusters[clusterName].second = helpText;
     for (auto & command : commandsList)
     {
-        mClusters[clusterName].push_back(std::move(command));
+        mClusters[clusterName].first.push_back(std::move(command));
     }
 }
 
@@ -186,7 +187,6 @@ int Commands::RunInteractive(const char * command)
 
 CHIP_ERROR Commands::RunCommand(int argc, char ** argv, bool interactive)
 {
-    std::map<std::string, CommandsVector>::iterator cluster;
     Command * command = nullptr;
 
     if (argc <= 1)
@@ -196,29 +196,32 @@ CHIP_ERROR Commands::RunCommand(int argc, char ** argv, bool interactive)
         return CHIP_ERROR_INVALID_ARGUMENT;
     }
 
-    cluster = GetCluster(argv[1]);
-    if (cluster == mClusters.end())
+    auto clusterIter = GetCluster(argv[1]);
+    if (clusterIter == mClusters.end())
     {
         ChipLogError(chipTool, "Unknown cluster: %s", argv[1]);
         ShowClusters(argv[0]);
         return CHIP_ERROR_INVALID_ARGUMENT;
     }
 
+    auto & commandList = clusterIter->second.first;
+    auto * clusterHelp = clusterIter->second.second;
+
     if (argc <= 2)
     {
         ChipLogError(chipTool, "Missing command name");
-        ShowCluster(argv[0], argv[1], cluster->second);
+        ShowCluster(argv[0], argv[1], commandList, clusterHelp);
         return CHIP_ERROR_INVALID_ARGUMENT;
     }
 
     bool isGlobalCommand = IsGlobalCommand(argv[2]);
     if (!isGlobalCommand)
     {
-        command = GetCommand(cluster->second, argv[2]);
+        command = GetCommand(commandList, argv[2]);
         if (command == nullptr)
         {
             ChipLogError(chipTool, "Unknown command: %s", argv[2]);
-            ShowCluster(argv[0], argv[1], cluster->second);
+            ShowCluster(argv[0], argv[1], commandList, clusterHelp);
             return CHIP_ERROR_INVALID_ARGUMENT;
         }
     }
@@ -227,15 +230,15 @@ CHIP_ERROR Commands::RunCommand(int argc, char ** argv, bool interactive)
         if (argc <= 3)
         {
             ChipLogError(chipTool, "Missing event name");
-            ShowClusterEvents(argv[0], argv[1], argv[2], cluster->second);
+            ShowClusterEvents(argv[0], argv[1], argv[2], commandList);
             return CHIP_ERROR_INVALID_ARGUMENT;
         }
 
-        command = GetGlobalCommand(cluster->second, argv[2], argv[3]);
+        command = GetGlobalCommand(commandList, argv[2], argv[3]);
         if (command == nullptr)
         {
             ChipLogError(chipTool, "Unknown event: %s", argv[3]);
-            ShowClusterEvents(argv[0], argv[1], argv[2], cluster->second);
+            ShowClusterEvents(argv[0], argv[1], argv[2], commandList);
             return CHIP_ERROR_INVALID_ARGUMENT;
         }
     }
@@ -244,15 +247,15 @@ CHIP_ERROR Commands::RunCommand(int argc, char ** argv, bool interactive)
         if (argc <= 3)
         {
             ChipLogError(chipTool, "Missing attribute name");
-            ShowClusterAttributes(argv[0], argv[1], argv[2], cluster->second);
+            ShowClusterAttributes(argv[0], argv[1], argv[2], commandList);
             return CHIP_ERROR_INVALID_ARGUMENT;
         }
 
-        command = GetGlobalCommand(cluster->second, argv[2], argv[3]);
+        command = GetGlobalCommand(commandList, argv[2], argv[3]);
         if (command == nullptr)
         {
             ChipLogError(chipTool, "Unknown attribute: %s", argv[3]);
-            ShowClusterAttributes(argv[0], argv[1], argv[2], cluster->second);
+            ShowClusterAttributes(argv[0], argv[1], argv[2], commandList);
             return CHIP_ERROR_INVALID_ARGUMENT;
         }
     }
@@ -271,7 +274,7 @@ CHIP_ERROR Commands::RunCommand(int argc, char ** argv, bool interactive)
     return interactive ? command->RunAsInteractive() : command->Run();
 }
 
-std::map<std::string, Commands::CommandsVector>::iterator Commands::GetCluster(std::string clusterName)
+Commands::ClusterMap::iterator Commands::GetCluster(std::string clusterName)
 {
     for (auto & cluster : mClusters)
     {
@@ -342,14 +345,21 @@ void Commands::ShowClusters(std::string executable)
         std::transform(clusterName.begin(), clusterName.end(), clusterName.begin(),
                        [](unsigned char c) { return std::tolower(c); });
         fprintf(stderr, "  | * %-82s|\n", clusterName.c_str());
+        ShowHelpText(cluster.second.second);
     }
     fprintf(stderr, "  +-------------------------------------------------------------------------------------+\n");
 }
 
-void Commands::ShowCluster(std::string executable, std::string clusterName, CommandsVector & commands)
+void Commands::ShowCluster(std::string executable, std::string clusterName, CommandsVector & commands, const char * helpText)
 {
     fprintf(stderr, "Usage:\n");
     fprintf(stderr, "  %s %s command_name [param1 param2 ...]\n", executable.c_str(), clusterName.c_str());
+
+    if (helpText)
+    {
+        fprintf(stderr, "\n%s\n", helpText);
+    }
+
     fprintf(stderr, "\n");
     fprintf(stderr, "  +-------------------------------------------------------------------------------------+\n");
     fprintf(stderr, "  | Commands:                                                                           |\n");
@@ -399,23 +409,7 @@ void Commands::ShowCluster(std::string executable, std::string clusterName, Comm
         if (shouldPrint)
         {
             fprintf(stderr, "  | * %-82s|\n", command->GetName());
-            const char * helpText = command->GetHelpText();
-            if (command->GetHelpText())
-            {
-                // We leave 82 chars for command names.  The help text starts
-                // two chars further to the right, so there are 80 chars left
-                // for it.
-                if (strlen(helpText) > 80)
-                {
-                    // Add "..." at the end to indicate truncation, and only
-                    // show the first 77 chars, since that's what will fit.
-                    fprintf(stderr, "  |   - %.77s...|\n", helpText);
-                }
-                else
-                {
-                    fprintf(stderr, "  |   - %-80s|\n", helpText);
-                }
-            }
+            ShowHelpText(command->GetHelpText());
         }
     }
     fprintf(stderr, "  +-------------------------------------------------------------------------------------+\n");
@@ -541,16 +535,18 @@ bool Commands::DecodeArgumentsFromBase64EncodedJson(const char * json, std::vect
     auto commandName = jsonValue[kJsonCommandKey].asString();
     auto arguments   = jsonValue[kJsonArgumentsKey].asString();
 
-    auto cluster = GetCluster(clusterName);
-    VerifyOrReturnValue(cluster != mClusters.end(), false,
+    auto clusterIter = GetCluster(clusterName);
+    VerifyOrReturnValue(clusterIter != mClusters.end(), false,
                         ChipLogError(chipTool, "Cluster '%s' is not supported.", clusterName.c_str()));
 
-    auto command = GetCommand(cluster->second, commandName);
+    auto & commandList = clusterIter->second.first;
+
+    auto command = GetCommand(commandList, commandName);
 
     if (jsonValue.isMember(kJsonCommandSpecifierKey) && IsGlobalCommand(commandName))
     {
         auto commandSpecifierName = jsonValue[kJsonCommandSpecifierKey].asString();
-        command                   = GetGlobalCommand(cluster->second, commandName, commandSpecifierName);
+        command                   = GetGlobalCommand(commandList, commandName, commandSpecifierName);
     }
     VerifyOrReturnValue(nullptr != command, false, ChipLogError(chipTool, "Unknown command."));
 
@@ -602,3 +598,25 @@ bool Commands::DecodeArgumentsFromStringStream(const char * command, std::vector
 
     return true;
 }
+
+void Commands::ShowHelpText(const char * helpText)
+{
+    if (helpText == nullptr)
+    {
+        return;
+    }
+
+    // We leave 82 chars for command/cluster names.  The help text starts
+    // two chars further to the right, so there are 80 chars left
+    // for it.
+    if (strlen(helpText) > 80)
+    {
+        // Add "..." at the end to indicate truncation, and only
+        // show the first 77 chars, since that's what will fit.
+        fprintf(stderr, "  |   - %.77s...|\n", helpText);
+    }
+    else
+    {
+        fprintf(stderr, "  |   - %-80s|\n", helpText);
+    }
+}

examples/chip-tool/commands/common/Commands.h

@@ -30,22 +30,24 @@ class Commands
 public:
     using CommandsVector = ::std::vector<std::unique_ptr<Command>>;
 
-    void Register(const char * clusterName, commands_list commandsList);
+    void Register(const char * clusterName, commands_list commandsList, const char * helpText = nullptr);
     int Run(int argc, char ** argv);
     int RunInteractive(const char * command);
 
 private:
+    using ClusterMap = std::map<std::string, std::pair<CommandsVector, const char *>>;
+
     CHIP_ERROR RunCommand(int argc, char ** argv, bool interactive = false);
 
-    std::map<std::string, CommandsVector>::iterator GetCluster(std::string clusterName);
+    ClusterMap::iterator GetCluster(std::string clusterName);
     Command * GetCommand(CommandsVector & commands, std::string commandName);
     Command * GetGlobalCommand(CommandsVector & commands, std::string commandName, std::string attributeName);
     bool IsAttributeCommand(std::string commandName) const;
     bool IsEventCommand(std::string commandName) const;
     bool IsGlobalCommand(std::string commandName) const;
 
     void ShowClusters(std::string executable);
-    void ShowCluster(std::string executable, std::string clusterName, CommandsVector & commands);
+    void ShowCluster(std::string executable, std::string clusterName, CommandsVector & commands, const char * helpText);
     void ShowClusterAttributes(std::string executable, std::string clusterName, std::string commandName, CommandsVector & commands);
     void ShowClusterEvents(std::string executable, std::string clusterName, std::string commandName, CommandsVector & commands);
     void ShowCommand(std::string executable, std::string clusterName, Command * command);
@@ -54,7 +56,10 @@ class Commands
     bool DecodeArgumentsFromBase64EncodedJson(const char * encodedData, std::vector<std::string> & args);
     bool DecodeArgumentsFromStringStream(const char * command, std::vector<std::string> & args);
 
-    std::map<std::string, CommandsVector> mClusters;
+    // helpText may be null, in which case it's not shown.
+    static void ShowHelpText(const char * helpText);
+
+    ClusterMap mClusters;
 #ifdef CONFIG_USE_LOCAL_STORAGE
     PersistentStorage mStorage;
 #endif // CONFIG_USE_LOCAL_STORAGE

examples/chip-tool/main.cpp

@@ -19,6 +19,7 @@
 #include "commands/common/Commands.h"
 #include "commands/example/ExampleCredentialIssuerCommands.h"
 
+#include "commands/clusters/SubscriptionsCommands.h"
 #include "commands/delay/Commands.h"
 #include "commands/discover/Commands.h"
 #include "commands/group/Commands.h"
@@ -45,6 +46,7 @@ int main(int argc, char * argv[])
     registerCommandsTests(commands, &credIssuerCommands);
     registerCommandsGroup(commands, &credIssuerCommands);
     registerClusters(commands, &credIssuerCommands);
+    registerCommandsSubscriptions(commands, &credIssuerCommands);
     registerCommandsStorage(commands);
 
     return commands.Run(argc, argv);

examples/chip-tool/templates/commands.zapt

@@ -10,7 +10,6 @@
 #include <commands/clusters/ComplexArgument.h>
 #include <commands/clusters/ClusterCommand.h>
 #include <commands/clusters/ReportCommand.h>
-#include <commands/clusters/SubscriptionsCommands.h>
 #include <commands/clusters/WriteAttributeCommand.h>
 
 {{> clusters_header}}
@@ -146,5 +145,4 @@ void registerClusters(Commands & commands, CredentialIssuerCommands * credsIssue
 {{#zcl_clusters}}
     registerCluster{{asUpperCamelCase name}}(commands, credsIssuerConfig);
 {{/zcl_clusters}}
-    registerClusterSubscriptions(commands, credsIssuerConfig);
 }

examples/tv-casting-app/linux/main.cpp

@@ -161,7 +161,7 @@ int main(int argc, char * argv[])
     }
 
     registerClusters(gCommands, &gCredIssuerCommands);
-    registerClusterSubscriptions(gCommands, &gCredIssuerCommands);
+    registerCommandsSubscriptions(gCommands, &gCredIssuerCommands);
 
     if (argc > 1)
     {