Model DiscoveryCapabilitiesBitmask field (#589)

Added new DiscoveryCapabilitiesBitmask field to model
zigbee-alliance · Sep 6, 2024 · 88db99f · 88db99f
1 parent 9ceba1c
commit 88db99f
Show file tree

Hide file tree

Showing 16 changed files with 532 additions and 182 deletions.
diff --git a/docs/transactions.md b/docs/transactions.md
@@ -221,6 +221,8 @@ Not all fields can be edited (see `EDIT_MODEL`).
   - enhancedSetupFlowTCFileSize: `optional(uint32)` - enhancedSetupFlowTCFileSize SHALL indicate the total size of the Enhanced Setup Flow Terms and Conditions file in bytes, and SHALL be used to ensure the downloaded file size is within the bounds of EnhancedSetupFlowTCFileSize. This field SHALL be present if and only if the EnhancedSetupFlowOptions field has bit 0 set.
   - maintenanceUrl: `optional(string)` - maintenanceUrl SHALL identify a link to a vendor-specific URL which SHALL provide a manufacturer specific means to resolve any functionality limitations indicated by the TERMS_AND_CONDITIONS_CHANGED status code. This field SHALL be present if and only if the EnhancedSetupFlowOptions field has bit 0 set.
   - schemaVersion: `optional(uint16)` - Schema version to support backward/forward compatability. Should be equal to 0 (default 0)
+  - discoveryCapabilitiesBitmask: `optional(uint16)` - Identifies the device's available technologies for device discovery (default 0). This field SHALL be populated if CommissioningFallbackUrl is populated
+  - commissioningFallbackURL: `optional(string)` - This field SHALL identify a vendor-specific commissioning-fallback URL for the device model, which can be used by a Commissioner in case commissioning fails to direct the user to a manufacturer-provided mechanism to provide resolution to commissioning issues.
 - In State:
   - `model/Model/value/<vid>/<pid>`
   - `model/VendorProducts/value/<vid>`
@@ -237,7 +239,7 @@ dcld tx model add-model --vid=<uint16> --pid=<uint16> --deviceTypeID=<uint16> --
 ```bash
 dcld tx model add-model --vid=<uint16> --pid=<uint16> --deviceTypeID=<uint16> --productName=<string> --productLabel=<string or path> --partNumber=<string> 
     --commissioningCustomFlow=<uint8> --commissioningCustomFlowUrl=<string> --commissioningModeInitialStepsHint=<uint32> --commissioningModeInitialStepsInstruction=<string>
-    --commissioningModeSecondaryStepsHint=<uint32> --commissioningModeSecondaryStepsInstruction=<string> --userManualURL=<string> --supportURL=<string> --productURL=<string> --lsfURL=<string>
+    --commissioningModeSecondaryStepsHint=<uint32> --commissioningModeSecondaryStepsInstruction=<string> --userManualURL=<string> --supportURL=<string> --productURL=<string> --lsfURL=<string> --discoveryCapabilitiesBitmask=<uint16> --commissioningFallbackURL<string>
     --from=<account>
 ```
 
@@ -277,6 +279,7 @@ If one of EnhancedSetupFlow or MaintenanceUrl fields needs to be updated, ALL En
   - enhancedSetupFlowTCFileSize: `optional(uint32)` - enhancedSetupFlowTCFileSize SHALL indicate the total size of the Enhanced Setup Flow Terms and Conditions file in bytes, and SHALL be used to ensure the downloaded file size is within the bounds of EnhancedSetupFlowTCFileSize. This field SHALL be present if and only if the EnhancedSetupFlowOptions field has bit 0 set.
   - maintenanceUrl: `optional(string)` - maintenanceUrl SHALL identify a link to a vendor-specific URL which SHALL provide a manufacturer specific means to resolve any functionality limitations indicated by the TERMS_AND_CONDITIONS_CHANGED status code. This field SHALL be present if and only if the EnhancedSetupFlowOptions field has bit 0 set.
   - schemaVersion: `optional(uint16)` - Schema version to support backward/forward compatability. Should be equal to 0 (default 0)
+  - commissioningFallbackURL: `optional(string)` - This field SHALL identify a vendor-specific commissioning-fallback URL for the device model, which can be used by a Commissioner in case commissioning fails to direct the user to a manufacturer-provided mechanism to provide resolution to commissioning issues.
 - In State: `model/Model/value/<vid>/<pid>`
 - Who can send:
   - Vendor account associated with the same vid who has created the model

diff --git a/integration_tests/cli/model-demo.sh b/integration_tests/cli/model-demo.sh
@@ -75,9 +75,12 @@ enhancedSetupFlowTCRevision=1
 enhancedSetupFlowTCDigest="MWRjNGE0NDA0MWRjYWYxMTU0NWI3NTQzZGZlOTQyZjQ3NDJmNTY4YmU2OGZlZTI3NTQ0MWIwOTJiYjYwZGVlZA=="
 enhancedSetupFlowTCFileSize=1024
 maintenanceUrl="https://example.org"
+commissioningFallbackUrl="https://url.commissioningfallbackurl.dclmodel"
+discoveryCapabilitiesBitmask=1
 echo "Add Model with VID: $vid_with_pids PID: $pid"
 result=$(echo "test1234" | dcld tx model add-model --vid=$vid_with_pids --pid=$pid --deviceTypeID=1 --productName=TestProduct --productLabel="$productLabel" --partNumber=1 --commissioningCustomFlow=0 --enhancedSetupFlowOptions=$enhancedSetupFlowOptions_1 \
-  --enhancedSetupFlowTCUrl=$enhancedSetupFlowTCUrl --enhancedSetupFlowTCRevision=$enhancedSetupFlowTCRevision --enhancedSetupFlowTCDigest=$enhancedSetupFlowTCDigest --enhancedSetupFlowTCFileSize=$enhancedSetupFlowTCFileSize --maintenanceUrl=$maintenanceUrl --from=$vendor_account_with_pids --yes)
+  --enhancedSetupFlowTCUrl=$enhancedSetupFlowTCUrl --enhancedSetupFlowTCRevision=$enhancedSetupFlowTCRevision --enhancedSetupFlowTCDigest=$enhancedSetupFlowTCDigest --enhancedSetupFlowTCFileSize=$enhancedSetupFlowTCFileSize --maintenanceUrl=$maintenanceUrl \
+  --commissioningFallbackUrl=$commissioningFallbackUrl --discoveryCapabilitiesBitmask=$discoveryCapabilitiesBitmask --from=$vendor_account_with_pids --yes)
 result=$(get_txn_result "$result")
 check_response "$result" "\"code\": 0"
 echo "$result"
@@ -105,6 +108,8 @@ check_response "$result" "\"enhancedSetupFlowTCRevision\": $enhancedSetupFlowTCR
 check_response "$result" "\"enhancedSetupFlowTCDigest\": \"$enhancedSetupFlowTCDigest\""
 check_response "$result" "\"enhancedSetupFlowTCFileSize\": $enhancedSetupFlowTCFileSize"
 check_response "$result" "\"maintenanceUrl\": \"$maintenanceUrl\""
+check_response "$result" "\"commissioningFallbackUrl\": \"$commissioningFallbackUrl\""
+check_response "$result" "\"discoveryCapabilitiesBitmask\": $discoveryCapabilitiesBitmask"
 echo "$result"
 
 test_divider
@@ -159,9 +164,10 @@ newEnhancedSetupFlowTCRevision=2
 newEnhancedSetupFlowTCDigest="MWRjM2E0MTA0MWRjYWYxMTU0NWI3NTQzZGZlOTQyZjQ3NDJmNTY4YmU2OGZlZTI3NTQ0MWIwOTJiYjYxZGVlZA=="
 newEnhancedSetupFlowTCFileSize=2048
 newMaintenanceUrl="https://example2.org"
+newCommissioningFallbackUrl="https://url.commissioningfallbackurl2.dclmodel"
 echo "Update Model with VID: ${vid_with_pids} PID: ${pid} with new description, enhancedSetupFlowTCUrl, enhancedSetupFlowTCRevision, enhancedSetupFlowTCDigest, enhancedSetupFlowTCFileSize and maintenanceUrl"
 result=$(echo "test1234" | dcld tx model update-model --vid=$vid_with_pids --pid=$pid --from $vendor_account_with_pids --yes --productLabel "$description" --enhancedSetupFlowOptions=$enhancedSetupFlowOptions_1 \
-    --enhancedSetupFlowTCUrl=$newEnhancedSetupFlowTCUrl --enhancedSetupFlowTCRevision=$newEnhancedSetupFlowTCRevision --enhancedSetupFlowTCDigest=$newEnhancedSetupFlowTCDigest --enhancedSetupFlowTCFileSize=$newEnhancedSetupFlowTCFileSize --maintenanceUrl=$newMaintenanceUrl --from=$vendor_account_with_pids --yes)
+    --enhancedSetupFlowTCUrl=$newEnhancedSetupFlowTCUrl --enhancedSetupFlowTCRevision=$newEnhancedSetupFlowTCRevision --enhancedSetupFlowTCDigest=$newEnhancedSetupFlowTCDigest --enhancedSetupFlowTCFileSize=$newEnhancedSetupFlowTCFileSize --maintenanceUrl=$newMaintenanceUrl --commissioningFallbackUrl=$newCommissioningFallbackUrl --from=$vendor_account_with_pids --yes)
 result=$(get_txn_result "$result")
 check_response "$result" "\"code\": 0"
 echo "$result"
@@ -189,6 +195,7 @@ check_response "$result" "\"enhancedSetupFlowTCRevision\": $newEnhancedSetupFlow
 check_response "$result" "\"enhancedSetupFlowTCDigest\": \"$newEnhancedSetupFlowTCDigest\""
 check_response "$result" "\"enhancedSetupFlowTCFileSize\": $newEnhancedSetupFlowTCFileSize"
 check_response "$result" "\"maintenanceUrl\": \"$newMaintenanceUrl\""
+check_response "$result" "\"commissioningFallbackUrl\": \"$newCommissioningFallbackUrl\""
 echo "$result"
 
 test_divider

diff --git a/integration_tests/constants/constants.go b/integration_tests/constants/constants.go
@@ -87,6 +87,8 @@ var (
 	EnhancedSetupFlowTCDigest                         = "MmNmMjRkYmE1ZmIwYTMwZTI2ZTgzYjJhYzViOWUyOWUxYjE2MWU1YzFmYTc0MjVlNzMwNDMzNjI5MzhiOTgyNA=="
 	EnhancedSetupFlowTCFileSize                       = 1
 	MaintenanceURL                                    = "https://url.maintenanceurl.dclmodel"
+	CommissioningFallbackURL                          = "https://url.commissioningfallbackurl.dclmodel"
+	DiscoveryCapabilitiesBitmask               uint32 = 0
 	LsfURL                                            = "https://url.lsfurl.dclmodel"
 	DataURL                                           = "https://url.data.dclmodel"
 	DataURL2                                          = "https://url.data.dclmodel2"

diff --git a/integration_tests/grpc_rest/model/helpers.go b/integration_tests/grpc_rest/model/helpers.go
@@ -54,16 +54,18 @@ func NewMsgCreateModel(vid int32, pid int32, signer string) *modeltypes.MsgCreat
 		CommissioningModeInitialStepsInstruction: testconstants.CommissioningModeInitialStepsInstruction,
 		CommissioningModeSecondaryStepsHint:      testconstants.CommissioningModeSecondaryStepsHint,
 		CommissioningModeSecondaryStepsInstruction: testconstants.CommissioningModeSecondaryStepsInstruction,
-		UserManualUrl:               testconstants.UserManualURL,
-		SupportUrl:                  testconstants.SupportURL,
-		ProductUrl:                  testconstants.ProductURL,
-		LsfUrl:                      testconstants.LsfURL,
-		EnhancedSetupFlowOptions:    testconstants.EnhancedSetupFlowOptions,
-		EnhancedSetupFlowTCUrl:      testconstants.EnhancedSetupFlowTCURL,
-		EnhancedSetupFlowTCRevision: int32(testconstants.EnhancedSetupFlowTCRevision),
-		EnhancedSetupFlowTCDigest:   testconstants.EnhancedSetupFlowTCDigest,
-		EnhancedSetupFlowTCFileSize: uint32(testconstants.EnhancedSetupFlowTCFileSize),
-		MaintenanceUrl:              testconstants.MaintenanceURL,
+		UserManualUrl:                testconstants.UserManualURL,
+		SupportUrl:                   testconstants.SupportURL,
+		ProductUrl:                   testconstants.ProductURL,
+		LsfUrl:                       testconstants.LsfURL,
+		EnhancedSetupFlowOptions:     testconstants.EnhancedSetupFlowOptions,
+		EnhancedSetupFlowTCUrl:       testconstants.EnhancedSetupFlowTCURL,
+		EnhancedSetupFlowTCRevision:  int32(testconstants.EnhancedSetupFlowTCRevision),
+		EnhancedSetupFlowTCDigest:    testconstants.EnhancedSetupFlowTCDigest,
+		EnhancedSetupFlowTCFileSize:  uint32(testconstants.EnhancedSetupFlowTCFileSize),
+		MaintenanceUrl:               testconstants.MaintenanceURL,
+		CommissioningFallbackUrl:     testconstants.CommissioningFallbackURL,
+		DiscoveryCapabilitiesBitmask: testconstants.DiscoveryCapabilitiesBitmask,
 	}
 }
 

diff --git a/proto/zigbeealliance/distributedcomplianceledger/model/model.proto b/proto/zigbeealliance/distributedcomplianceledger/model/model.proto
@@ -32,6 +32,8 @@ message Model {
   string enhancedSetupFlowTCDigest = 23 [(gogoproto.moretags) = "validate:\"required_if_bit_0_set=EnhancedSetupFlowOptions,omitempty,max=128\""];
   uint32 enhancedSetupFlowTCFileSize = 24 [(gogoproto.moretags) = "validate:\"required_with=EnhancedSetupFlowTCUrl\""];;
   string maintenanceUrl = 25 [(gogoproto.moretags) = "validate:\"required_if_bit_0_set=EnhancedSetupFlowOptions,omitempty,url,startswith=https:,max=256\""];
+  uint32 discoveryCapabilitiesBitmask = 26 [(gogoproto.moretags) = "validate:\"gte=0,lte=14\""];
+  string commissioningFallbackUrl = 27 [(gogoproto.moretags) = "validate:\"omitempty,url,startsnotwith=http:,max=256\""];
 
 }
 
diff --git a/proto/zigbeealliance/distributedcomplianceledger/model/tx.proto b/proto/zigbeealliance/distributedcomplianceledger/model/tx.proto
@@ -47,6 +47,8 @@ message MsgCreateModel {
   string enhancedSetupFlowTCDigest = 22 [(gogoproto.moretags) = "validate:\"required_if_bit_0_set=EnhancedSetupFlowOptions,omitempty,max=128\""];
   uint32 enhancedSetupFlowTCFileSize = 23 [(gogoproto.moretags) = "validate:\"required_with=EnhancedSetupFlowTCUrl\""];;
   string maintenanceUrl = 24 [(gogoproto.moretags) = "validate:\"required_if_bit_0_set=EnhancedSetupFlowOptions,omitempty,url,startswith=https:,max=256\""];
+  uint32 discoveryCapabilitiesBitmask = 25 [(gogoproto.moretags) = "validate:\"gte=0,lte=14\""];
+  string commissioningFallbackUrl = 26 [(gogoproto.moretags) = "validate:\"omitempty,url,startsnotwith=http:,max=256\""];
 }
 message MsgCreateModelResponse {}
 
@@ -74,6 +76,7 @@ message MsgUpdateModel {
   string enhancedSetupFlowTCDigest = 20 [(gogoproto.moretags) = "validate:\"required_if_bit_0_set=EnhancedSetupFlowOptions,omitempty,max=128\""];
   uint32 enhancedSetupFlowTCFileSize = 21 [(gogoproto.moretags) = "validate:\"required_with=EnhancedSetupFlowTCUrl\""];;
   string maintenanceUrl = 22 [(gogoproto.moretags) = "validate:\"required_if_bit_0_set=EnhancedSetupFlowOptions,omitempty,url,startswith=https:,max=256\""];
+  string commissioningFallbackUrl = 23 [(gogoproto.moretags) = "validate:\"omitempty,url,startsnotwith=http:,max=256\""];
 }
 message MsgUpdateModelResponse {}
 

diff --git a/x/model/client/cli/flags.go b/x/model/client/cli/flags.go
@@ -10,6 +10,7 @@ const (
 	FlagProductLabel                               = "productLabel"
 	FlagProductLabelShortcut                       = "d"
 	FlagPartNumber                                 = "partNumber"
+	FlagDiscoveryCapabilitiesBitmask               = "discoveryCapabilitiesBitmask"
 	FlagCommissioningCustomFlow                    = "commissioningCustomFlow"
 	FlagCommissioningCustomFlowURL                 = "commissioningCustomFlowURL"
 	FlagCommissioningModeInitialStepsHint          = "commissioningModeInitialStepsHint"
@@ -27,6 +28,7 @@ const (
 	FlagEnhancedSetupFlowTCDigest                  = "enhancedSetupFlowTCDigest"
 	FlagEnhancedSetupFlowTCFileSize                = "enhancedSetupFlowTCFileSize"
 	FlagMaintenanceURL                             = "maintenanceUrl"
+	FlagCommissioningFallbackURL                   = "commissioningFallbackUrl"
 	// Flags for ModelVersion.
 	FlagSoftwareVersion              = "softwareVersion"
 	FlagSoftwareVersionShortcut      = "v"

diff --git a/x/model/client/cli/tx_model.go b/x/model/client/cli/tx_model.go
@@ -19,6 +19,7 @@ func CmdCreateModel() *cobra.Command {
 		productName                                string
 		productLabel                               string
 		partNumber                                 string
+		discoveryCapabilitiesBitmask               uint32
 		commissioningCustomFlow                    int32
 		commissioningCustomFlowURL                 string
 		commissioningModeInitialStepsHint          uint32
@@ -35,6 +36,7 @@ func CmdCreateModel() *cobra.Command {
 		enhancedSetupFlowTCDigest                  string
 		enhancedSetupFlowTCFileSize                uint32
 		maintenanceURL                             string
+		commissioningFallbackURL                   string
 		schemaVersion                              uint32
 	)
 
@@ -43,6 +45,13 @@ func CmdCreateModel() *cobra.Command {
 		Short: "Add new Model",
 		Args:  cobra.ExactArgs(0),
 		RunE: func(cmd *cobra.Command, args []string) (err error) {
+			isCommissioningFallbackURLSpecified := cmd.Flags().Changed(FlagCommissioningFallbackURL)
+			isDiscoveryCapabilitiesBitmaskSpecified := cmd.Flags().Changed(FlagDiscoveryCapabilitiesBitmask)
+
+			if isCommissioningFallbackURLSpecified && !isDiscoveryCapabilitiesBitmaskSpecified {
+				return types.ErrFallbackURLRequiresBitmask
+			}
+
 			clientCtx, err := client.GetClientTxContext(cmd)
 			if err != nil {
 				return err
@@ -61,6 +70,7 @@ func CmdCreateModel() *cobra.Command {
 				productName,
 				productLabel,
 				partNumber,
+				discoveryCapabilitiesBitmask,
 				commissioningCustomFlow,
 				commissioningCustomFlowURL,
 				commissioningModeInitialStepsHint,
@@ -78,6 +88,7 @@ func CmdCreateModel() *cobra.Command {
 				enhancedSetupFlowTCDigest,
 				enhancedSetupFlowTCFileSize,
 				maintenanceURL,
+				commissioningFallbackURL,
 			)
 
 			// validate basic will be called in GenerateOrBroadcastTxCLI
@@ -102,6 +113,9 @@ func CmdCreateModel() *cobra.Command {
 		"Model description (string or path to file containing data)")
 	cmd.Flags().StringVar(&partNumber, FlagPartNumber, "",
 		"Model Part Number (or sku)")
+	cmd.Flags().Uint32Var(&discoveryCapabilitiesBitmask, FlagDiscoveryCapabilitiesBitmask, 0,
+		`This field identifies the device's available technologies for device discovery. 
+This field SHALL be populated if CommissioningFallbackUrl is populated`)
 	cmd.Flags().Int32Var(&commissioningCustomFlow, FlagCommissioningCustomFlow, 0,
 		`A value of 1 indicates that user interaction with the device (pressing a button, for example) is 
 required before commissioning can take place. When CommissioningCustomflow is set to a value of 2, 
@@ -153,6 +167,8 @@ and for these values the commissioningModeSecondaryStepInstruction SHALL be set`
 		"enhancedSetupFlowTCFileSize SHALL indicate the total size of the Enhanced Setup Flow Terms and Conditions file in bytes, and SHALL be used to ensure the downloaded file size is within the bounds of EnhancedSetupFlowTCFileSize. This field SHALL be present if and only if the EnhancedSetupFlowOptions field has bit 0 set.")
 	cmd.Flags().StringVar(&maintenanceURL, FlagMaintenanceURL, "",
 		"maintenanceURL SHALL identify a link to a vendor-specific URL which SHALL provide a manufacturer specific means to resolve any functionality limitations indicated by the TERMS_AND_CONDITIONS_CHANGED status code. This field SHALL be present if and only if the EnhancedSetupFlowOptions field has bit 0 set.")
+	cmd.Flags().StringVar(&commissioningFallbackURL, FlagCommissioningFallbackURL, "",
+		"This field SHALL identify a vendor-specific commissioning-fallback URL for the device model, which can be used by a Commissioner in case commissioning fails to direct the user to a manufacturer-provided mechanism to provide resolution to commissioning issues.")
 
 	_ = cmd.MarkFlagRequired(FlagVid)
 	_ = cmd.MarkFlagRequired(FlagPid)
@@ -186,6 +202,7 @@ func CmdUpdateModel() *cobra.Command {
 		enhancedSetupFlowTCDigest                  string
 		enhancedSetupFlowTCFileSize                uint32
 		maintenanceURL                             string
+		commissioningFallbackURL                   string
 	)
 
 	cmd := &cobra.Command{
@@ -226,6 +243,7 @@ func CmdUpdateModel() *cobra.Command {
 				enhancedSetupFlowTCDigest,
 				enhancedSetupFlowTCFileSize,
 				maintenanceURL,
+				commissioningFallbackURL,
 			)
 
 			// validate basic will be called in GenerateOrBroadcastTxCLI
@@ -289,6 +307,8 @@ will enter Commissioning Mode upon a power cycle. Note that this value cannot be
 		"enhancedSetupFlowTCFileSize SHALL indicate the total size of the Enhanced Setup Flow Terms and Conditions file in bytes, and SHALL be used to ensure the downloaded file size is within the bounds of EnhancedSetupFlowTCFileSize. This field SHALL be present if and only if the EnhancedSetupFlowOptions field has bit 0 set.")
 	cmd.Flags().StringVar(&maintenanceURL, FlagMaintenanceURL, "",
 		"maintenanceURL SHALL identify a link to a vendor-specific URL which SHALL provide a manufacturer specific means to resolve any functionality limitations indicated by the TERMS_AND_CONDITIONS_CHANGED status code. This field SHALL be present if and only if the EnhancedSetupFlowOptions field has bit 0 set.")
+	cmd.Flags().StringVar(&commissioningFallbackURL, FlagCommissioningFallbackURL, "",
+		"This field SHALL identify a vendor-specific commissioning-fallback URL for the device model, which can be used by a Commissioner in case commissioning fails to direct the user to a manufacturer-provided mechanism to provide resolution to commissioning issues.")
 
 	cli.AddTxFlagsToCmd(cmd)