Merge pull request #562 from zigbee-alliance/bugfix/522-comissioning-model-initial-step-hints

Set CommissioningModeInitialStepsHint to 1 by default for standard flow

Author: akarabashov

docs/transactions.md

@@ -203,7 +203,7 @@ Not all fields can be edited (see `EDIT_MODEL`).
   - partNumber: `optional(string)` -  stock keeping unit
   - commissioningCustomFlow: `optional(uint8)` - 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, the commissioner SHOULD attempt to obtain a URL which MAY be used to provide an end user with the necessary details for how to configure the product for initial commissioning
   - commissioningCustomFlowURL: `optional(string)` - commissioningCustomFlowURL SHALL identify a vendor specific commissioning URL for the device model when the commissioningCustomFlow field is set to '2'
-  - commissioningModeInitialStepsHint: `optional(uint32)` - commissioningModeInitialStepsHint SHALL identify a hint for the steps that can be used to put into commissioning mode a device that has not yet been commissioned. This field is a bitmap with values defined in the Pairing Hint Table. For example, a value of 1 (bit 0 is set) indicates that a device that has not yet been commissioned will enter Commissioning Mode upon a power cycle.
+  - commissioningModeInitialStepsHint: `optional(uint32)` - commissioningModeInitialStepsHint SHALL identify a hint for the steps that can be used to put into commissioning mode a device that has not yet been commissioned. This field is a bitmap with values defined in the Pairing Hint Table. For example, a value of 1 (bit 0 is set) indicates that a device that has not yet been commissioned will enter Commissioning Mode upon a power cycle (default 1).
   - commissioningModeInitialStepsInstruction: `optional(string)` - commissioningModeInitialStepsInstruction SHALL contain text which relates to specific values of CommissioningModeInitialStepsHint. Certain values of CommissioningModeInitialStepsHint, as defined in the Pairing Hint Table, indicate a Pairing Instruction (PI) dependency, and for these values the commissioningModeInitialStepsInstruction SHALL be set
   - commissioningModeSecondaryStepsHint: `optional(uint32)` - commissioningModeSecondaryStepsHint SHALL identify a hint for steps that can be used to put into commissioning mode a device that has already been commissioned. This field is a bitmap with values defined in the Pairing Hint Table. For example, a value of 4 (bit 2 is set) indicates that a device that has already been commissioned will require the user to visit a current CHIP Administrator to put the device into commissioning mode.
   - commissioningModeSecondaryStepInstruction: `optional(string)` - commissioningModeSecondaryStepInstruction SHALL contain text which relates to specific values of commissioningModeSecondaryStepsHint. Certain values of commissioningModeSecondaryStepsHint, as defined in the Pairing Hint Table, indicate a Pairing Instruction (PI) dependency, and for these values the commissioningModeSecondaryStepInstruction SHALL be set
@@ -260,7 +260,8 @@ All non-edited fields remain the same.
   - productURL: `optional(string)` - URL that contains product specific web page that contains details for the device model.  
   - lsfURL: `optional(string)` - URL to the Localized String File of this product.
   - schemaVersion: `optional(uint16)` - Schema version to support backward/forward compatability(default 0)
-- lsfRevision: `optional(uint32)` - LsfRevision is a monotonically increasing positive integer indicating the latest available version of Localized String File.
+  - lsfRevision: `optional(uint32)` - LsfRevision is a monotonically increasing positive integer indicating the latest available version of Localized String File.
+  - commissioningModeInitialStepsHint: `optional(uint32)` - commissioningModeInitialStepsHint SHALL identify a hint for the steps that can be used to put into commissioning mode a device that has not yet been commissioned. This field is a bitmap with values defined in the Pairing Hint Table. For example, a value of 1 (bit 0 is set) indicates that a device that has not yet been commissioned will enter Commissioning Mode upon a power cycle. Note that this value cannot be updated to 0.
 - In State: `model/Model/value/<vid>/<pid>`
 - Who can send:
   - Vendor account associated with the same vid who has created the model

integration_tests/cli/model-demo.sh

@@ -126,11 +126,12 @@ echo "$result"
 
 test_divider
 
-echo "Update Model with VID: ${vid} PID: ${pid} with new description and commissionerRemoteUiFlowURL"
+echo "Update Model with VID: ${vid} PID: ${pid} with new description, commissionerRemoteUiFlowURL and commissioningModeInitialStepsHint"
 description="New Device Description"
 schema_version_3=3
 newCommissionerRemoteUiFlowURL="https://commissionerRemoteUiFlowURL.dclmodel.updated"
-result=$(echo "test1234" | dcld tx model update-model --vid=$vid --pid=$pid --from $vendor_account --yes --productLabel "$description" --schemaVersion=$schema_version_3 --commissionerRemoteUiFlowURL="$newCommissionerRemoteUiFlowURL")
+newCommissioningModeInitialStepsHint=8
+result=$(echo "test1234" | dcld tx model update-model --vid=$vid --pid=$pid --from $vendor_account --yes --productLabel "$description" --schemaVersion=$schema_version_3 --commissionerRemoteUiFlowURL="$newCommissionerRemoteUiFlowURL" --commissioningModeInitialStepsHint="$newCommissioningModeInitialStepsHint")
 check_response "$result" "\"code\": 0"
 echo "$result"
 
@@ -150,6 +151,7 @@ check_response "$result" "\"pid\": $pid"
 check_response "$result" "\"productLabel\": \"$description\""
 check_response "$result" "\"schemaVersion\": $schema_version_3"
 check_response "$result" "\"commissionerRemoteUiFlowUrl\": \"$newCommissionerRemoteUiFlowURL\""
+check_response "$result" "\"commissioningModeInitialStepsHint\": $newCommissioningModeInitialStepsHint"
 echo "$result"
 
 test_divider
@@ -167,6 +169,7 @@ result=$(dcld query model get-model --vid=$vid --pid=$pid)
 check_response "$result" "\"vid\": $vid"
 check_response "$result" "\"pid\": $pid"
 check_response "$result" "\"supportUrl\": \"$supportURL\""
+check_response "$result" "\"commissioningModeInitialStepsHint\": $newCommissioningModeInitialStepsHint"
 echo "$result"
 
 test_divider

integration_tests/grpc_rest/model/helpers.go

@@ -985,14 +985,17 @@ func Demo(suite *utils.TestSuite) {
 	require.Equal(suite.T, createSecondModelMsg.Pid, vendorModels.Products[1].Pid)
 
 	// Update second model
+	newCommissioningModeInitialStepsHint := uint32(8)
 	updateSecondModelMsg := NewMsgUpdateModel(createSecondModelMsg.Vid, createSecondModelMsg.Pid, vendorAccount.Address)
+	updateSecondModelMsg.CommissioningModeInitialStepsHint = newCommissioningModeInitialStepsHint
 	_, err = suite.BuildAndBroadcastTx([]sdk.Msg{updateSecondModelMsg}, vendorName, vendorAccount)
 	require.NoError(suite.T, err)
 
 	// Check second model is updated
 	receivedModel, err = GetModel(suite, createSecondModelMsg.Vid, createSecondModelMsg.Pid)
 	require.NoError(suite.T, err)
 	require.Equal(suite.T, updateSecondModelMsg.ProductLabel, receivedModel.ProductLabel)
+	require.Equal(suite.T, newCommissioningModeInitialStepsHint, receivedModel.CommissioningModeInitialStepsHint)
 
 	// add new model version
 	createModelVersionMsg := NewMsgCreateModelVersion(createFirstModelMsg.Vid, createFirstModelMsg.Pid, 1, "1", vendorAccount.Address)

proto/model/tx.proto

@@ -63,6 +63,7 @@ message MsgUpdateModel {
   int32 lsfRevision = 14 [(gogoproto.moretags) = "validate:\"gte=0,lte=65535\""];
   uint32 schemaVersion = 15 [(gogoproto.moretags) = "validate:\"gte=0,lte=65535\""];
   string commissionerRemoteUiFlowUrl = 16 [(gogoproto.moretags) = "validate:\"omitempty,url,startsnotwith=http:,max=256\""];
+  uint32 commissioningModeInitialStepsHint = 17;
 }
 message MsgUpdateModelResponse {}
 

vue/src/store/generated/zigbee-alliance/distributed-compliance-ledger/zigbeealliance.distributedcomplianceledger.model/module/types/model/tx.ts

@@ -45,6 +45,7 @@ export interface MsgUpdateModel {
   lsfRevision: number
   schemaVersion: number
   commissionerRemoteUiFlowUrl: string
+  commissioningModeInitialStepsHint: number
 }
 
 export interface MsgUpdateModelResponse {}
@@ -541,7 +542,8 @@ const baseMsgUpdateModel: object = {
   lsfUrl: '',
   lsfRevision: 0,
   schemaVersion: 0,
-  commissionerRemoteUiFlowUrl: ''
+  commissionerRemoteUiFlowUrl: '',
+  commissioningModeInitialStepsHint: 0
 }
 
 export const MsgUpdateModel = {
@@ -594,6 +596,9 @@ export const MsgUpdateModel = {
     if (message.commissionerRemoteUiFlowUrl !== '') {
       writer.uint32(130).string(message.commissionerRemoteUiFlowUrl)
     }
+    if (message.commissioningModeInitialStepsHint !== 0) {
+      writer.uint32(136).uint32(message.commissioningModeInitialStepsHint)
+    }
     return writer
   },
 
@@ -652,6 +657,9 @@ export const MsgUpdateModel = {
         case 16:
           message.commissionerRemoteUiFlowUrl = reader.string()
           break
+        case 17:
+          message.commissioningModeInitialStepsHint = reader.uint32()
+          break
         default:
           reader.skipType(tag & 7)
           break
@@ -742,6 +750,11 @@ export const MsgUpdateModel = {
     } else {
       message.commissionerRemoteUiFlowUrl = ''
     }
+    if (object.commissioningModeInitialStepsHint !== undefined && object.commissioningModeInitialStepsHint !== null) {
+      message.commissioningModeInitialStepsHint = Number(object.commissioningModeInitialStepsHint)
+    } else {
+      message.commissioningModeInitialStepsHint = 0
+    }
     return message
   },
 
@@ -765,6 +778,7 @@ export const MsgUpdateModel = {
     message.lsfRevision !== undefined && (obj.lsfRevision = message.lsfRevision)
     message.schemaVersion !== undefined && (obj.schemaVersion = message.schemaVersion)
     message.commissionerRemoteUiFlowUrl !== undefined && (obj.commissionerRemoteUiFlowUrl = message.commissionerRemoteUiFlowUrl)
+    message.commissioningModeInitialStepsHint !== undefined && (obj.commissioningModeInitialStepsHint = message.commissioningModeInitialStepsHint)
     return obj
   },
 
@@ -850,6 +864,11 @@ export const MsgUpdateModel = {
     } else {
       message.commissionerRemoteUiFlowUrl = ''
     }
+    if (object.commissioningModeInitialStepsHint !== undefined && object.commissioningModeInitialStepsHint !== null) {
+      message.commissioningModeInitialStepsHint = object.commissioningModeInitialStepsHint
+    } else {
+      message.commissioningModeInitialStepsHint = 0
+    }
     return message
   }
 }

x/model/client/cli/tx_model.go

@@ -100,12 +100,12 @@ the necessary details for how to configure the product for initial commissioning
 	cmd.Flags().StringVar(&commissioningCustomFlowURL, FlagCommissioningCustomFlowURL, "",
 		`commissioningCustomFlowURL SHALL identify a vendor specific commissioning URL for the 
 device model when the commissioningCustomFlow field is set to '2'`)
-	cmd.Flags().Uint32Var(&commissioningModeInitialStepsHint, FlagCommissioningModeInitialStepsHint, 0,
+	cmd.Flags().Uint32Var(&commissioningModeInitialStepsHint, FlagCommissioningModeInitialStepsHint, 1,
 		`commissioningModeInitialStepsHint SHALL 
 identify a hint for the steps that can be used to put into commissioning mode a device that 
 has not yet been commissioned. This field is a bitmap with values defined in the Pairing Hint Table. 
 For example, a value of 1 (bit 0 is set) indicates 
-that a device that has not yet been commissioned will enter Commissioning Mode upon a power cycle.`)
+that a device that has not yet been commissioned will enter Commissioning Mode upon a power cycle (default 1).`)
 	cmd.Flags().StringVar(&commissioningModeInitialStepsInstruction, FlagCommissioningModeInitialStepsInstruction, "",
 		`commissioningModeInitialStepsInstruction SHALL contain text which relates to specific 
 values of commissioningModeSecondaryStepsHint. Certain values of CommissioningModeInitialStepsHint, 
@@ -160,6 +160,7 @@ func CmdUpdateModel() *cobra.Command {
 		lsfURL                                     string
 		lsfRevision                                int32
 		schemaVersion                              uint32
+		commissioningModeInitialStepsHint          uint32
 	)
 
 	cmd := &cobra.Command{
@@ -194,6 +195,7 @@ func CmdUpdateModel() *cobra.Command {
 				lsfURL,
 				lsfRevision,
 				schemaVersion,
+				commissioningModeInitialStepsHint,
 			)
 
 			// validate basic will be called in GenerateOrBroadcastTxCLI
@@ -241,6 +243,12 @@ and for these values the commissioningModeSecondaryStepInstruction SHALL be set`
 	cmd.Flags().Int32Var(&lsfRevision, FlagLsfRevision, 0,
 		"LsfRevision is a monotonically increasing positive integer indicating the latest available version of Localized String File")
 	cmd.Flags().Uint32Var(&schemaVersion, common.FlagSchemaVersion, 0, "Schema version")
+	cmd.Flags().Uint32Var(&commissioningModeInitialStepsHint, FlagCommissioningModeInitialStepsHint, 0,
+		`commissioningModeInitialStepsHint SHALL 
+identify a hint for the steps that can be used to put into commissioning mode a device that 
+has not yet been commissioned. This field is a bitmap with values defined in the Pairing Hint Table. 
+For example, a value of 1 (bit 0 is set) indicates that a device that has not yet been commissioned 
+will enter Commissioning Mode upon a power cycle. Note that this value cannot be updated to 0. (default 1).`)
 
 	cli.AddTxFlagsToCmd(cmd)
 

x/model/handler_test.go

@@ -170,7 +170,47 @@ func TestHandler_AddModel(t *testing.T) {
 	require.Equal(t, msgCreateModel.Vid, receivedModel.Vid)
 	require.Equal(t, msgCreateModel.Pid, receivedModel.Pid)
 	require.Equal(t, msgCreateModel.DeviceTypeId, receivedModel.DeviceTypeId)
-	require.Equal(t, testconstants.SchemaVersion, receivedModel.SchemaVersion)
+}
+
+func TestHandler_AddModel_CheckCommissioningModeInitialStepsHintHandling(t *testing.T) {
+	cases := []struct {
+		name                                      string
+		commissioningModeInitialStepsHint         uint32
+		expectedCommissioningModeInitialStepsHint uint32
+	}{
+		{
+			name:                              "CommissioningModeInitialStepsHint=0 Sets Default 1",
+			commissioningModeInitialStepsHint: 0,
+			expectedCommissioningModeInitialStepsHint: 1,
+		},
+		{
+			name:                              "CommissioningModeInitialStepsHint=2 Remains 2",
+			commissioningModeInitialStepsHint: 2,
+			expectedCommissioningModeInitialStepsHint: 2,
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			setup := Setup(t)
+
+			// add new model
+			msgCreateModel := NewMsgCreateModel(setup.Vendor)
+			msgCreateModel.CommissioningModeInitialStepsHint = tc.commissioningModeInitialStepsHint
+			_, err := setup.Handler(setup.Ctx, msgCreateModel)
+			require.NoError(t, err)
+
+			// query model
+			receivedModel, err := queryModel(setup, msgCreateModel.Vid, msgCreateModel.Pid)
+			require.NoError(t, err)
+
+			// check
+			require.Equal(t, msgCreateModel.Vid, receivedModel.Vid)
+			require.Equal(t, msgCreateModel.Pid, receivedModel.Pid)
+			require.Equal(t, msgCreateModel.DeviceTypeId, receivedModel.DeviceTypeId)
+			require.Equal(t, tc.expectedCommissioningModeInitialStepsHint, receivedModel.CommissioningModeInitialStepsHint)
+		})
+	}
 }
 
 func TestHandler_UpdateModel(t *testing.T) {
@@ -194,7 +234,9 @@ func TestHandler_UpdateModel(t *testing.T) {
 
 	// update existing model
 	var newSchemaVersion uint32 = 2
+	var newCommissioningModeInitialStepsHint uint32 = 8
 	msgUpdateModel.SchemaVersion = newSchemaVersion
+	msgUpdateModel.CommissioningModeInitialStepsHint = newCommissioningModeInitialStepsHint
 	_, err = setup.Handler(setup.Ctx, msgUpdateModel)
 	require.NoError(t, err)
 
@@ -208,6 +250,7 @@ func TestHandler_UpdateModel(t *testing.T) {
 	require.Equal(t, msgUpdateModel.Vid, receivedModel.Vid)
 	require.Equal(t, msgUpdateModel.Pid, receivedModel.Pid)
 	require.Equal(t, msgUpdateModel.ProductLabel, receivedModel.ProductLabel)
+	require.Equal(t, newCommissioningModeInitialStepsHint, receivedModel.CommissioningModeInitialStepsHint)
 	require.Equal(t, newSchemaVersion, receivedModel.SchemaVersion)
 }
 

x/model/keeper/msg_server_model.go

@@ -57,6 +57,12 @@ func (k msgServer) CreateModel(goCtx context.Context, msg *types.MsgCreateModel)
 		model.LsfRevision = 1
 	}
 
+	// If CommissioningModeInitialStepsHint is 0, then set it to the default value of 1
+	// Relevant issue: https://github.com/zigbee-alliance/distributed-compliance-ledger/issues/522
+	if model.CommissioningModeInitialStepsHint == 0 {
+		model.CommissioningModeInitialStepsHint = 1
+	}
+
 	// store new model
 	k.SetModel(
 		ctx,
@@ -158,6 +164,10 @@ func (k msgServer) UpdateModel(goCtx context.Context, msg *types.MsgUpdateModel)
 		}
 	}
 
+	if msg.CommissioningModeInitialStepsHint != 0 {
+		model.CommissioningModeInitialStepsHint = msg.CommissioningModeInitialStepsHint
+	}
+
 	// store updated model
 	k.SetModel(ctx, model)
 

x/model/types/messages_model.go

@@ -114,6 +114,7 @@ func NewMsgUpdateModel(
 	lsfURL string,
 	lsfRevision int32,
 	schemaVersion uint32,
+	commissioningModeInitialStepsHint uint32,
 ) *MsgUpdateModel {
 	return &MsgUpdateModel{
 		Creator:                                  creator,
@@ -132,6 +133,7 @@ func NewMsgUpdateModel(
 		LsfUrl:                                     lsfURL,
 		LsfRevision:                                lsfRevision,
 		SchemaVersion:                              schemaVersion,
+		CommissioningModeInitialStepsHint:          commissioningModeInitialStepsHint,
 	}
 }