Skip to content

Commit

Permalink
Better documentation for chip-tool "any" reporting commands. (#18717)
Browse files Browse the repository at this point in the history 
It's not widely known that these commands support multi-path
read/subscribe or how wildcards work.
  • Loading branch information
@bzbarsky-apple @pull
bzbarsky-apple authored and pull[bot] committed Aug 1, 2022
1 parent 15c5219 commit 3368011
Show file tree
Hide file tree
Showing 2 changed files with 67 additions and 31 deletions.
17 changes: 14 additions & 3 deletions examples/chip-tool/commands/clusters/ModelCommand.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,17 +25,27 @@
class ModelCommand : public CHIPCommand
{
public:
ModelCommand(const char * commandName, CredentialIssuerCommands * credsIssuerConfig) :
ModelCommand(const char * commandName, CredentialIssuerCommands * credsIssuerConfig, bool supportsMultipleEndpoints = false) :
CHIPCommand(commandName, credsIssuerConfig), mOnDeviceConnectedCallback(OnDeviceConnectedFn, this),
mOnDeviceConnectionFailureCallback(OnDeviceConnectionFailureFn, this)
mOnDeviceConnectionFailureCallback(OnDeviceConnectionFailureFn, this), mSupportsMultipleEndpoints(supportsMultipleEndpoints)
{}

void AddArguments()
{
AddArgument(
"destination-id", 0, UINT64_MAX, &mDestinationId,
"64-bit node or group identifier.\n Group identifiers are detected by being in the 0xFFFF'FFFF'FFFF'xxxx range.");
AddArgument("endpoint-id-ignored-for-group-commands", 0, UINT16_MAX, &mEndPointId);
if (mSupportsMultipleEndpoints)
{
AddArgument("endpoint-ids", 0, UINT16_MAX, &mEndPointId,
"Comma-separated list of endpoint ids (e.g. \"1\" or \"1,2,3\").\n Allowed to be 0xFFFF to indicate a "
"wildcard endpoint.");
}
else
{
AddArgument("endpoint-id-ignored-for-group-commands", 0, UINT16_MAX, &mEndPointId,
"Endpoint the command is targeted at.");
}
AddArgument("timeout", 0, UINT16_MAX, &mTimeout);
}

Expand All @@ -61,4 +71,5 @@ class ModelCommand : public CHIPCommand

chip::Callback::Callback<chip::OnDeviceConnected> mOnDeviceConnectedCallback;
chip::Callback::Callback<chip::OnDeviceConnectionFailure> mOnDeviceConnectionFailureCallback;
const bool mSupportsMultipleEndpoints;
};
81 changes: 53 additions & 28 deletions examples/chip-tool/commands/clusters/ReportCommand.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ class ReportCommand : public InteractionModelReports, public ModelCommand, publi
{
public:
ReportCommand(const char * commandName, CredentialIssuerCommands * credsIssuerConfig) :
InteractionModelReports(this), ModelCommand(commandName, credsIssuerConfig)
InteractionModelReports(this), ModelCommand(commandName, credsIssuerConfig, /* supportsMultipleEndpoints = */ true)
{}

virtual void OnSubscription(){};
Expand Down Expand Up @@ -120,19 +120,19 @@ class ReadAttribute : public ReportCommand
public:
ReadAttribute(CredentialIssuerCommands * credsIssuerConfig) : ReportCommand("read-by-id", credsIssuerConfig)
{
AddArgument("cluster-id", 0, UINT32_MAX, &mClusterIds);
AddArgument("attribute-id", 0, UINT32_MAX, &mAttributeIds);
AddArgument("fabric-filtered", 0, 1, &mFabricFiltered);
AddArgument("data-version", 0, UINT32_MAX, &mDataVersion);
AddArgument("cluster-ids", 0, UINT32_MAX, &mClusterIds,
"Comma-separated list of cluster ids to read from (e.g. \"6\" or \"8,0x201\").\n Allowed to be 0xFFFFFFFF to "
"indicate a wildcard cluster.");
AddAttributeIdArgument();
AddCommonArguments();
ReportCommand::AddArguments();
}

ReadAttribute(chip::ClusterId clusterId, CredentialIssuerCommands * credsIssuerConfig) :
ReportCommand("read-by-id", credsIssuerConfig), mClusterIds(1, clusterId)
{
AddArgument("attribute-id", 0, UINT32_MAX, &mAttributeIds);
AddArgument("fabric-filtered", 0, 1, &mFabricFiltered);
AddArgument("data-version", 0, UINT32_MAX, &mDataVersion);
AddAttributeIdArgument();
AddCommonArguments();
ReportCommand::AddArguments();
}

Expand All @@ -142,8 +142,7 @@ class ReadAttribute : public ReportCommand
mClusterIds(1, clusterId), mAttributeIds(1, attributeId)
{
AddArgument("attr-name", attributeName);
AddArgument("fabric-filtered", 0, 1, &mFabricFiltered);
AddArgument("data-version", 0, UINT32_MAX, &mDataVersion);
AddCommonArguments();
ReportCommand::AddArguments();
}

Expand All @@ -155,6 +154,21 @@ class ReadAttribute : public ReportCommand
}

private:
void AddAttributeIdArgument()
{
AddArgument("attribute-ids", 0, UINT32_MAX, &mAttributeIds,
"Comma-separated list of attribute ids to read (e.g. \"0\" or \"1,0xFFFC,0xFFFD\").\n Allowed to be "
"0xFFFFFFFF to indicate a wildcard attribute.");
}

void AddCommonArguments()
{
AddArgument("fabric-filtered", 0, 1, &mFabricFiltered,
"Boolean indicating whether to do a fabric-filtered read. Defaults to true.");
AddArgument("data-version", 0, UINT32_MAX, &mDataVersion,
"Comma-separated list of data versions for the clusters being read.");
}

std::vector<chip::ClusterId> mClusterIds;
std::vector<chip::AttributeId> mAttributeIds;
chip::Optional<bool> mFabricFiltered;
Expand All @@ -166,25 +180,19 @@ class SubscribeAttribute : public ReportCommand
public:
SubscribeAttribute(CredentialIssuerCommands * credsIssuerConfig) : ReportCommand("subscribe-by-id", credsIssuerConfig)
{
AddArgument("cluster-id", 0, UINT32_MAX, &mClusterIds);
AddArgument("attribute-id", 0, UINT32_MAX, &mAttributeIds);
AddArgument("min-interval", 0, UINT16_MAX, &mMinInterval);
AddArgument("max-interval", 0, UINT16_MAX, &mMaxInterval);
AddArgument("fabric-filtered", 0, 1, &mFabricFiltered);
AddArgument("data-version", 0, UINT32_MAX, &mDataVersion);
AddArgument("keepSubscriptions", 0, 1, &mKeepSubscriptions);
AddArgument("cluster-ids", 0, UINT32_MAX, &mClusterIds,
"Comma-separated list of cluster ids to subscribe to (e.g. \"6\" or \"8,0x201\").\n Allowed to be 0xFFFFFFFF "
"to indicate a wildcard cluster.");
AddAttributeIdArgument();
AddCommonArguments();
ReportCommand::AddArguments();
}

SubscribeAttribute(chip::ClusterId clusterId, CredentialIssuerCommands * credsIssuerConfig) :
ReportCommand("subscribe-by-id", credsIssuerConfig), mClusterIds(1, clusterId)
{
AddArgument("attribute-id", 0, UINT32_MAX, &mAttributeIds);
AddArgument("min-interval", 0, UINT16_MAX, &mMinInterval);
AddArgument("max-interval", 0, UINT16_MAX, &mMaxInterval);
AddArgument("fabric-filtered", 0, 1, &mFabricFiltered);
AddArgument("data-version", 0, UINT32_MAX, &mDataVersion);
AddArgument("keepSubscriptions", 0, 1, &mKeepSubscriptions);
AddAttributeIdArgument();
AddCommonArguments();
ReportCommand::AddArguments();
}

Expand All @@ -194,11 +202,7 @@ class SubscribeAttribute : public ReportCommand
mClusterIds(1, clusterId), mAttributeIds(1, attributeId)
{
AddArgument("attr-name", attributeName);
AddArgument("min-interval", 0, UINT16_MAX, &mMinInterval);
AddArgument("max-interval", 0, UINT16_MAX, &mMaxInterval);
AddArgument("fabric-filtered", 0, 1, &mFabricFiltered);
AddArgument("data-version", 0, UINT32_MAX, &mDataVersion);
AddArgument("keepSubscriptions", 0, 1, &mKeepSubscriptions);
AddCommonArguments();
ReportCommand::AddArguments();
}

Expand Down Expand Up @@ -228,6 +232,27 @@ class SubscribeAttribute : public ReportCommand
}

private:
void AddAttributeIdArgument()
{
AddArgument("attribute-ids", 0, UINT32_MAX, &mAttributeIds,
"Comma-separated list of attribute ids to subscribe to (e.g. \"0\" or \"1,0xFFFC,0xFFFD\").\n Allowed to be "
"0xFFFFFFFF to indicate a wildcard attribute.");
}

void AddCommonArguments()
{
AddArgument("min-interval", 0, UINT16_MAX, &mMinInterval,
"Server should not send a new report if less than this number of seconds has elapsed since the last report.");
AddArgument("max-interval", 0, UINT16_MAX, &mMaxInterval,
"Server must send a report if this number of seconds has elapsed since the last report.");
AddArgument("fabric-filtered", 0, 1, &mFabricFiltered,
"Boolean indicating whether to do a fabric-filtered subscription. Defaults to true.");
AddArgument("data-version", 0, UINT32_MAX, &mDataVersion,
"Comma-separated list of data versions for the clusters being subscribed to.");
AddArgument("keepSubscriptions", 0, 1, &mKeepSubscriptions,
"Boolean indicating whether to keep existing subscriptions when creating the new one. Defaults to false.");
}

std::vector<chip::ClusterId> mClusterIds;
std::vector<chip::AttributeId> mAttributeIds;

Expand Down

0 comments on commit 3368011

Please sign in to comment.