From f8bb46e1582e786d79141ac7fe3db2a7761beb1e Mon Sep 17 00:00:00 2001 From: Grzegorz Ferenc Date: Mon, 3 Jul 2023 13:32:11 +0200 Subject: [PATCH 01/10] doc: chip_tool_guide: doorlock user & credentials Added a new section about setting up doorlock users and credentials and interacting with them. Signed-off-by: Grzegorz Ferenc --- docs/guides/chip_tool_guide.md | 181 ++++++++++++++++++++++++++++++++- 1 file changed, 179 insertions(+), 2 deletions(-) diff --git a/docs/guides/chip_tool_guide.md b/docs/guides/chip_tool_guide.md index ca958716de9f58..c7a79cd14ff29b 100644 --- a/docs/guides/chip_tool_guide.md +++ b/docs/guides/chip_tool_guide.md @@ -1247,7 +1247,7 @@ The steps are the same as for the `subscribe` or `subscribe-event` commands.
-## Using wildcards +### Using wildcards The CHIP Tool supports command wildcards for parameter values for clusters, attributes or events, or endpoints, or any combination of these. With the @@ -1318,7 +1318,7 @@ In this command: $ ./chip-tool doorlock read-by-id 0xFFFFFFFF 1 0xFFFF ``` -### Using wildcards with `any` command +#### Using wildcards with `any` command Using the `any` command lets you use wildcards also for the cluster names. The `any` command can be combined with the following commands: @@ -1391,3 +1391,180 @@ $ ./chip-tool any read-by-id + +## Saving users and credentials on door lock devices + +Matter door lock devices can store pools of users and credentials that allow you to configure different access scenarios. Each user and credential in the pool has an index value. Additionally, each user has a list of Occupied Credentials. + +By default, each door lock device comes with no user or credential defined, but it reserves several slots in both pools that can be populated with new users and credentials, up to the value specified in the the `NumberOfTotalUsersSupported` attribute and the `NumberOfCredentialsSupportedPerUser` attribute, respectively. + +For security reasons, all communication between users and credentials happens only using their respective index values. No other information is shared between both pools. + +The CHIP Tool lets you add users and credentials on door lock devices and securely match their indexes to one another. This is an optional feature available only when working with devices that implement the `doorlock` cluster. + +> **Note:** +> Users and credentials can only be modified by whoever has the right permissions, as specified in the Access Control List. + +Complete the following steps: + +1. Set up a user on the device. +1. Assign a credential for the newly created user. + +### Step 1: Set up a user + +To set up a user on a door lock device with the CHIP Tool, use the following command pattern: + +``` +$ ./chip-tool doorlock set-user --timedInteractionTimeoutMs 1000 +``` + +In this command: + +- __ is one of the available types of operation for the user: + + - `Add` - This operation adds a new user to the slot at __. + - `Clear` - This operation removes an existing user from the slot at __. + - `Modify` - This operation modifies an existing user at the slot at __. + +- __ is the index value of the user, between `1` and the maximum value you set in the `NumberOfTotalUsersSupported` attribute. Setting the user index to `0` will cause an error. +- __ is the name of the user, which can have maximum 10 bytes of size. +- __ is a 4-byte number that describes the unique user ID. +- __ can be set to one of the following values: + + - Available (`0`) - This status indicates that the given user slot is available for modification on the device. + - Occupied (`1`) - This status indicates that the given user slot is used and active. + +- __ is the number of credentials that must be used to unlock the door lock. This parameter can have the following values: + + - `0` (Single) - One credential type is required to unlock. + - `1` (Dual) - Two credential types are required to unlock. + - `2` (Tri) - Three credential types are required to unlock. + +- __ is the ID of the door lock device. +- __ is the ID of the endpoint on the door lock device. +- `--timedInteractionTimeoutMs` is the timeout duration for the interaction, in milliseconds. This should allow enough time for the interaction to complete. + +**Example of command:** + +``` +$ ./chip-tool doorlock set-user 0 1 AAA 6452 1 0 0 1 1 --timedInteractionTimeoutMs 1000 +``` + +### Step 2: Assign a credential + +Once you have a user created on the door lock device, use the following command pattern to assign a credential to it: + +``` +$ ./chip-tool doorlock set-credential <{Credential}> --timedInteractionTimeoutMs 1000 +``` +In this command: + +- __ is one of the available types of operation for the credential: + + - `Add` - This operation adds a new credential to a user at the slot at __. + - `Clear` - This operation removes an existing credential from the user at the slot at __. + - `Modify` - This operation modifies an existing credential for the user at the slot at __. + +- _<{Credential}\>_ is a JSON parameter with two fields: + + - __ is the type of the credential. It can have one of the following values: + + - `0` - Programming PIN + - `1` - PIN + - `2` - RFID + - `3` - Fingerprint + - `4` - Finger vein + + - __ is the index of the credential, between `1` and the maximum value you set in the `NumberOfCredentialsSupportedPerUser` attribute (see the section 5.2.3.20 of the Matter Application Cluters specification for details). Setting the credential index to `0` will cause an error. + +- __ is a string parameter with the secred credential data. For example, the PIN code value (`12345` in the example below). +- __ is the index of the user that will be associated with the credential. +- __ is the status of the user that will be associated with the credential. See the description of this parameter in [Set up a user](#step-1-set-up-a-user). +- __ is the ID of the door lock device. +- __ is the ID of the endpoint on the door lock device. +- `--timedInteractionTimeoutMs` is the timeout duration for the interaction, in milliseconds. This should allow enough time for the interaction to complete. + +**Example of command:** + +``` +$ ./chip-tool doorlock set-credential 0 '{ "credentialType": 1, "credentialIndex": 1 }' "12345" 1 null null 1 1 --timedInteractionTimeoutMs 1000 +``` + +### Operations on users and credentials + +After you set up users and credentials on your door lock device, you can use several CHIP Tool commands to interact with them. + +All commands reuse the parameters explained earlier in this section. The following command patterns are available: + +- Reading the status of the user: + + ``` + $ ./chip-tool doorlock get-user --timedInteractionTimeoutMs 1000 + ``` + + This command returns the status of the user at the specified __ at the specified __ and __. + +- Reading the status of the credential: + + ``` + $ ./chip-tool doorlock get-credential-status <{Credential}> --timedInteractionTimeoutMs 1000 + ``` + + This command returns the status of the credential of the specified _<{Credential}\>_ at the specified __ and __. + +- Cleaning the user: + + ``` + $ ./chip-tool doorlock clear-user --timedInteractionTimeoutMs 1000 + ``` + + This command cleans the slot containing the specified __ at the specified __ and __. + +- Cleaning the credential: + + ``` + $ ./chip-tool doorlock clear-credential <{Credential}> --timedInteractionTimeoutMs 1000 + ``` + + This command cleans the slot containing the specified _<{Credential}\>_ at the specified __ and __. + +### Operations with user PIN code + +If you set the __ to PIN when [assigning credentials](#step-2-assign-a-credential), you can use the following command patterns to verify if it works and invoke it to open or close the door lock: + +- Verifying the PIN code: + + ``` + $ ./chip-tool doorlock read require-pinfor-remote-operation --timedInteractionTimeoutMs 1000 + ``` + + This command returns either `false` or `true`: + + - `false` indicates that providing the PIN code is not required to close or open the door lock. + - `true` indicates that the PIN code is required to close or open the door lock. + +- Changing the requirement for the PIN code usage: + + ``` + $ ./chip-tool doorlock write require-pinfor-remote-operation true + ``` + + This command modifies the setting of `require-pinfor-remote-operation` to `true`. After you run it, you will have to use the PIN code to lock or unlock the door. + +- Closing the door lock with the PIN code: + + ``` + $ ./chip-tool doorlock lock-door --timedInteractionTimeoutMs 2000 --PinCode 12345 + ``` + + In this command, you need to provide `--PinCode` corresponding to the PIN code you set with __ (for example `12345`). + +- Opening the door lock with the PIN code: + + ``` + $ ./chip-tool doorlock unlock-door --timedInteractionTimeoutMs 2000 --PinCode 12345 + ``` + + In this command, you need to provide `--PinCode` corresponding to the PIN code you set with __ (for example `12345`). From 0b4e3da87550e7357f162a62ef97ae60642df045 Mon Sep 17 00:00:00 2001 From: Grzegorz Ferenc Date: Wed, 12 Jul 2023 10:40:36 +0200 Subject: [PATCH 02/10] edits from Arek and Boris Signed-off-by: Grzegorz Ferenc --- docs/guides/chip_tool_guide.md | 55 ++++++++++++++++++---------------- 1 file changed, 30 insertions(+), 25 deletions(-) diff --git a/docs/guides/chip_tool_guide.md b/docs/guides/chip_tool_guide.md index c7a79cd14ff29b..507c69aca250e7 100644 --- a/docs/guides/chip_tool_guide.md +++ b/docs/guides/chip_tool_guide.md @@ -1400,14 +1400,14 @@ Matter door lock devices can store pools of users and credentials that allow you By default, each door lock device comes with no user or credential defined, but it reserves several slots in both pools that can be populated with new users and credentials, up to the value specified in the the `NumberOfTotalUsersSupported` attribute and the `NumberOfCredentialsSupportedPerUser` attribute, respectively. -For security reasons, all communication between users and credentials happens only using their respective index values. No other information is shared between both pools. +All communication between users and credentials happens only using their respective index values. No other information is shared between both pools. The CHIP Tool lets you add users and credentials on door lock devices and securely match their indexes to one another. This is an optional feature available only when working with devices that implement the `doorlock` cluster. > **Note:** > Users and credentials can only be modified by whoever has the right permissions, as specified in the Access Control List. -Complete the following steps: +To save credentials and users, you need to complete the following steps, described in detail in the following sections: 1. Set up a user on the device. 1. Assign a credential for the newly created user. @@ -1417,47 +1417,52 @@ Complete the following steps: To set up a user on a door lock device with the CHIP Tool, use the following command pattern: ``` -$ ./chip-tool doorlock set-user --timedInteractionTimeoutMs 1000 +$ ./chip-tool doorlock set-user --timedInteractionTimeoutMs ``` In this command: - __ is one of the available types of operation for the user: - - `Add` - This operation adds a new user to the slot at __. + - `Add` - This operation sets a new user in the slot at __. - `Clear` - This operation removes an existing user from the slot at __. - `Modify` - This operation modifies an existing user at the slot at __. - __ is the index value of the user, between `1` and the maximum value you set in the `NumberOfTotalUsersSupported` attribute. Setting the user index to `0` will cause an error. -- __ is the name of the user, which can have maximum 10 bytes of size. -- __ is a 4-byte number that describes the unique user ID. -- __ can be set to one of the following values: +- __ is the name of the user, which can have maximum 10 bytes of size. Can be set to `null`. +- __ is a 4-byte number that describes the unique user ID. Can be set to `null`. +- __ can be set to `null` or to one of the following values: - - Available (`0`) - This status indicates that the given user slot is available for modification on the device. - - Occupied (`1`) - This status indicates that the given user slot is used and active. + - `0` (Available) - This status indicates that the given user slot is available for modification on the device. This value is selected is you set `null` for the variable. + - `1` (OccupiedEnabled) - This status indicates that the given user slot is used and active. + - `3` (OccupiedDisabled) - This status indicates that the given user slot is used, but disabled. Unlike `0` and `1`, supporting this status is optional. -- __ is the number of credentials that must be used to unlock the door lock. This parameter can have the following values: +- __ is the number of credentials that must be used to unlock the door lock. This parameter can be set to `null` or to one of the following values: - - `0` (Single) - One credential type is required to unlock. + - `0` (Single) - One credential type is required to unlock. This value is selected is you set `null` for the variable. - `1` (Dual) - Two credential types are required to unlock. - `2` (Tri) - Three credential types are required to unlock. - __ is the ID of the door lock device. - __ is the ID of the endpoint on the door lock device. -- `--timedInteractionTimeoutMs` is the timeout duration for the interaction, in milliseconds. This should allow enough time for the interaction to complete. +- `--timedInteractionTimeoutMs` is the timeout duration for the interaction, in milliseconds (__). This should allow enough time for the interaction to complete. -**Example of command:** +**Examples of command:** ``` $ ./chip-tool doorlock set-user 0 1 AAA 6452 1 0 0 1 1 --timedInteractionTimeoutMs 1000 ``` +``` +$ ./chip-tool doorlock set-user 0 1 null null null null null 1 1 --timedInteractionTimeoutMs 1000 +``` + ### Step 2: Assign a credential Once you have a user created on the door lock device, use the following command pattern to assign a credential to it: ``` -$ ./chip-tool doorlock set-credential <{Credential}> --timedInteractionTimeoutMs 1000 +$ ./chip-tool doorlock set-credential <{Credential}> --timedInteractionTimeoutMs ``` In this command: @@ -1467,7 +1472,7 @@ In this command: - `Clear` - This operation removes an existing credential from the user at the slot at __. - `Modify` - This operation modifies an existing credential for the user at the slot at __. -- _<{Credential}\>_ is a JSON parameter with two fields: +- _<{Credential}\>_ is a parameter in the JSON format, with the following two fields: - __ is the type of the credential. It can have one of the following values: @@ -1480,11 +1485,11 @@ In this command: - __ is the index of the credential, between `1` and the maximum value you set in the `NumberOfCredentialsSupportedPerUser` attribute (see the section 5.2.3.20 of the Matter Application Cluters specification for details). Setting the credential index to `0` will cause an error. - __ is a string parameter with the secred credential data. For example, the PIN code value (`12345` in the example below). -- __ is the index of the user that will be associated with the credential. -- __ is the status of the user that will be associated with the credential. See the description of this parameter in [Set up a user](#step-1-set-up-a-user). +- __ is the index of the user that will be associated with the credential. Can be set to `null`. +- __ is the status of the user that will be associated with the credential. See the description of this parameter in [Set up a user](#step-1-set-up-a-user). Can be set to `null`. - __ is the ID of the door lock device. - __ is the ID of the endpoint on the door lock device. -- `--timedInteractionTimeoutMs` is the timeout duration for the interaction, in milliseconds. This should allow enough time for the interaction to complete. +- `--timedInteractionTimeoutMs` is the timeout duration for the interaction, in milliseconds (__). This should allow enough time for the interaction to complete. **Example of command:** @@ -1501,7 +1506,7 @@ All commands reuse the parameters explained earlier in this section. The followi - Reading the status of the user: ``` - $ ./chip-tool doorlock get-user --timedInteractionTimeoutMs 1000 + $ ./chip-tool doorlock get-user --timedInteractionTimeoutMs ``` This command returns the status of the user at the specified __ at the specified __ and __. @@ -1509,7 +1514,7 @@ All commands reuse the parameters explained earlier in this section. The followi - Reading the status of the credential: ``` - $ ./chip-tool doorlock get-credential-status <{Credential}> --timedInteractionTimeoutMs 1000 + $ ./chip-tool doorlock get-credential-status <{Credential}> --timedInteractionTimeoutMs ``` This command returns the status of the credential of the specified _<{Credential}\>_ at the specified __ and __. @@ -1517,7 +1522,7 @@ All commands reuse the parameters explained earlier in this section. The followi - Cleaning the user: ``` - $ ./chip-tool doorlock clear-user --timedInteractionTimeoutMs 1000 + $ ./chip-tool doorlock clear-user --timedInteractionTimeoutMs ``` This command cleans the slot containing the specified __ at the specified __ and __. @@ -1525,7 +1530,7 @@ All commands reuse the parameters explained earlier in this section. The followi - Cleaning the credential: ``` - $ ./chip-tool doorlock clear-credential <{Credential}> --timedInteractionTimeoutMs 1000 + $ ./chip-tool doorlock clear-credential <{Credential}> --timedInteractionTimeoutMs ``` This command cleans the slot containing the specified _<{Credential}\>_ at the specified __ and __. @@ -1537,7 +1542,7 @@ If you set the __ to PIN when [assigning credentials](#step-2-a - Verifying the PIN code: ``` - $ ./chip-tool doorlock read require-pinfor-remote-operation --timedInteractionTimeoutMs 1000 + $ ./chip-tool doorlock read require-pinfor-remote-operation --timedInteractionTimeoutMs ``` This command returns either `false` or `true`: @@ -1556,7 +1561,7 @@ If you set the __ to PIN when [assigning credentials](#step-2-a - Closing the door lock with the PIN code: ``` - $ ./chip-tool doorlock lock-door --timedInteractionTimeoutMs 2000 --PinCode 12345 + $ ./chip-tool doorlock lock-door --timedInteractionTimeoutMs --PinCode 12345 ``` In this command, you need to provide `--PinCode` corresponding to the PIN code you set with __ (for example `12345`). @@ -1564,7 +1569,7 @@ If you set the __ to PIN when [assigning credentials](#step-2-a - Opening the door lock with the PIN code: ``` - $ ./chip-tool doorlock unlock-door --timedInteractionTimeoutMs 2000 --PinCode 12345 + $ ./chip-tool doorlock unlock-door --timedInteractionTimeoutMs --PinCode 12345 ``` In this command, you need to provide `--PinCode` corresponding to the PIN code you set with __ (for example `12345`). From 0d0119b54a2a16f3a0768f3afa98600d84826530 Mon Sep 17 00:00:00 2001 From: "Restyled.io" Date: Wed, 12 Jul 2023 10:24:31 +0000 Subject: [PATCH 03/10] Restyled by prettier-markdown --- docs/guides/chip_tool_guide.md | 193 +++++++++++++++++++++------------ 1 file changed, 126 insertions(+), 67 deletions(-) diff --git a/docs/guides/chip_tool_guide.md b/docs/guides/chip_tool_guide.md index 507c69aca250e7..bc91699538c0eb 100644 --- a/docs/guides/chip_tool_guide.md +++ b/docs/guides/chip_tool_guide.md @@ -1396,25 +1396,35 @@ $ ./chip-tool any read-by-id **Note:** -> Users and credentials can only be modified by whoever has the right permissions, as specified in the Access Control List. +> **Note:** Users and credentials can only be modified by whoever has the right +> permissions, as specified in the Access Control List. -To save credentials and users, you need to complete the following steps, described in detail in the following sections: +To save credentials and users, you need to complete the following steps, +described in detail in the following sections: 1. Set up a user on the device. 1. Assign a credential for the newly created user. ### Step 1: Set up a user -To set up a user on a door lock device with the CHIP Tool, use the following command pattern: +To set up a user on a door lock device with the CHIP Tool, use the following +command pattern: ``` $ ./chip-tool doorlock set-user --timedInteractionTimeoutMs @@ -1424,28 +1434,44 @@ In this command: - __ is one of the available types of operation for the user: - - `Add` - This operation sets a new user in the slot at __. - - `Clear` - This operation removes an existing user from the slot at __. - - `Modify` - This operation modifies an existing user at the slot at __. - -- __ is the index value of the user, between `1` and the maximum value you set in the `NumberOfTotalUsersSupported` attribute. Setting the user index to `0` will cause an error. -- __ is the name of the user, which can have maximum 10 bytes of size. Can be set to `null`. -- __ is a 4-byte number that describes the unique user ID. Can be set to `null`. + - `Add` - This operation sets a new user in the slot at __. + - `Clear` - This operation removes an existing user from the slot at + __. + - `Modify` - This operation modifies an existing user at the slot at + __. + +- __ is the index value of the user, between `1` and the maximum + value you set in the `NumberOfTotalUsersSupported` attribute. Setting the + user index to `0` will cause an error. +- __ is the name of the user, which can have maximum 10 bytes of + size. Can be set to `null`. +- __ is a 4-byte number that describes the unique user ID. Can + be set to `null`. - __ can be set to `null` or to one of the following values: - - `0` (Available) - This status indicates that the given user slot is available for modification on the device. This value is selected is you set `null` for the variable. - - `1` (OccupiedEnabled) - This status indicates that the given user slot is used and active. - - `3` (OccupiedDisabled) - This status indicates that the given user slot is used, but disabled. Unlike `0` and `1`, supporting this status is optional. + - `0` (Available) - This status indicates that the given user slot is + available for modification on the device. This value is selected is you + set `null` for the variable. + - `1` (OccupiedEnabled) - This status indicates that the given user slot + is used and active. + - `3` (OccupiedDisabled) - This status indicates that the given user slot + is used, but disabled. Unlike `0` and `1`, supporting this status is + optional. -- __ is the number of credentials that must be used to unlock the door lock. This parameter can be set to `null` or to one of the following values: +- __ is the number of credentials that must be used to unlock + the door lock. This parameter can be set to `null` or to one of the + following values: - - `0` (Single) - One credential type is required to unlock. This value is selected is you set `null` for the variable. - - `1` (Dual) - Two credential types are required to unlock. - - `2` (Tri) - Three credential types are required to unlock. + - `0` (Single) - One credential type is required to unlock. This value is + selected is you set `null` for the variable. + - `1` (Dual) - Two credential types are required to unlock. + - `2` (Tri) - Three credential types are required to unlock. - __ is the ID of the door lock device. - __ is the ID of the endpoint on the door lock device. -- `--timedInteractionTimeoutMs` is the timeout duration for the interaction, in milliseconds (__). This should allow enough time for the interaction to complete. +- `--timedInteractionTimeoutMs` is the timeout duration for the interaction, + in milliseconds (__). This should allow enough time for the + interaction to complete. **Examples of command:** @@ -1459,37 +1485,55 @@ $ ./chip-tool doorlock set-user 0 1 null null null null null 1 1 --timedInteract ### Step 2: Assign a credential -Once you have a user created on the door lock device, use the following command pattern to assign a credential to it: +Once you have a user created on the door lock device, use the following command +pattern to assign a credential to it: ``` $ ./chip-tool doorlock set-credential <{Credential}> --timedInteractionTimeoutMs ``` -In this command: - -- __ is one of the available types of operation for the credential: - - - `Add` - This operation adds a new credential to a user at the slot at __. - - `Clear` - This operation removes an existing credential from the user at the slot at __. - - `Modify` - This operation modifies an existing credential for the user at the slot at __. -- _<{Credential}\>_ is a parameter in the JSON format, with the following two fields: - - - __ is the type of the credential. It can have one of the following values: - - - `0` - Programming PIN - - `1` - PIN - - `2` - RFID - - `3` - Fingerprint - - `4` - Finger vein - - - __ is the index of the credential, between `1` and the maximum value you set in the `NumberOfCredentialsSupportedPerUser` attribute (see the section 5.2.3.20 of the Matter Application Cluters specification for details). Setting the credential index to `0` will cause an error. +In this command: -- __ is a string parameter with the secred credential data. For example, the PIN code value (`12345` in the example below). -- __ is the index of the user that will be associated with the credential. Can be set to `null`. -- __ is the status of the user that will be associated with the credential. See the description of this parameter in [Set up a user](#step-1-set-up-a-user). Can be set to `null`. +- __ is one of the available types of operation for the + credential: + + - `Add` - This operation adds a new credential to a user at the slot at + __. + - `Clear` - This operation removes an existing credential from the user at + the slot at __. + - `Modify` - This operation modifies an existing credential for the user + at the slot at __. + +- _<{Credential}\>_ is a parameter in the JSON format, with the following two + fields: + + - __ is the type of the credential. It can have one of + the following values: + + - `0` - Programming PIN + - `1` - PIN + - `2` - RFID + - `3` - Fingerprint + - `4` - Finger vein + + - __ is the index of the credential, between `1` and the + maximum value you set in the `NumberOfCredentialsSupportedPerUser` + attribute (see the section 5.2.3.20 of the Matter Application Cluters + specification for details). Setting the credential index to `0` will + cause an error. + +- __ is a string parameter with the secred credential data. + For example, the PIN code value (`12345` in the example below). +- __ is the index of the user that will be associated with the + credential. Can be set to `null`. +- __ is the status of the user that will be associated with the + credential. See the description of this parameter in + [Set up a user](#step-1-set-up-a-user). Can be set to `null`. - __ is the ID of the door lock device. - __ is the ID of the endpoint on the door lock device. -- `--timedInteractionTimeoutMs` is the timeout duration for the interaction, in milliseconds (__). This should allow enough time for the interaction to complete. +- `--timedInteractionTimeoutMs` is the timeout duration for the interaction, + in milliseconds (__). This should allow enough time for the + interaction to complete. **Example of command:** @@ -1499,77 +1543,92 @@ $ ./chip-tool doorlock set-credential 0 '{ "credentialType": 1, "credentialIndex ### Operations on users and credentials -After you set up users and credentials on your door lock device, you can use several CHIP Tool commands to interact with them. +After you set up users and credentials on your door lock device, you can use +several CHIP Tool commands to interact with them. -All commands reuse the parameters explained earlier in this section. The following command patterns are available: +All commands reuse the parameters explained earlier in this section. The +following command patterns are available: -- Reading the status of the user: +- Reading the status of the user: ``` $ ./chip-tool doorlock get-user --timedInteractionTimeoutMs ``` - This command returns the status of the user at the specified __ at the specified __ and __. + This command returns the status of the user at the specified __ + at the specified __ and __. -- Reading the status of the credential: +- Reading the status of the credential: ``` $ ./chip-tool doorlock get-credential-status <{Credential}> --timedInteractionTimeoutMs ``` - This command returns the status of the credential of the specified _<{Credential}\>_ at the specified __ and __. + This command returns the status of the credential of the specified + _<{Credential}\>_ at the specified __ and __. -- Cleaning the user: +- Cleaning the user: ``` $ ./chip-tool doorlock clear-user --timedInteractionTimeoutMs ``` - This command cleans the slot containing the specified __ at the specified __ and __. + This command cleans the slot containing the specified __ at the + specified __ and __. -- Cleaning the credential: +- Cleaning the credential: ``` $ ./chip-tool doorlock clear-credential <{Credential}> --timedInteractionTimeoutMs ``` - This command cleans the slot containing the specified _<{Credential}\>_ at the specified __ and __. + This command cleans the slot containing the specified _<{Credential}\>_ at + the specified __ and __. ### Operations with user PIN code -If you set the __ to PIN when [assigning credentials](#step-2-assign-a-credential), you can use the following command patterns to verify if it works and invoke it to open or close the door lock: +If you set the __ to PIN when +[assigning credentials](#step-2-assign-a-credential), you can use the following +command patterns to verify if it works and invoke it to open or close the door +lock: -- Verifying the PIN code: +- Verifying the PIN code: ``` $ ./chip-tool doorlock read require-pinfor-remote-operation --timedInteractionTimeoutMs ``` - This command returns either `false` or `true`: + This command returns either `false` or `true`: - - `false` indicates that providing the PIN code is not required to close or open the door lock. - - `true` indicates that the PIN code is required to close or open the door lock. + - `false` indicates that providing the PIN code is not required to close + or open the door lock. + - `true` indicates that the PIN code is required to close or open the door + lock. -- Changing the requirement for the PIN code usage: +- Changing the requirement for the PIN code usage: ``` $ ./chip-tool doorlock write require-pinfor-remote-operation true ``` - This command modifies the setting of `require-pinfor-remote-operation` to `true`. After you run it, you will have to use the PIN code to lock or unlock the door. + This command modifies the setting of `require-pinfor-remote-operation` to + `true`. After you run it, you will have to use the PIN code to lock or + unlock the door. -- Closing the door lock with the PIN code: +- Closing the door lock with the PIN code: ``` $ ./chip-tool doorlock lock-door --timedInteractionTimeoutMs --PinCode 12345 ``` - In this command, you need to provide `--PinCode` corresponding to the PIN code you set with __ (for example `12345`). + In this command, you need to provide `--PinCode` corresponding to the PIN + code you set with __ (for example `12345`). -- Opening the door lock with the PIN code: +- Opening the door lock with the PIN code: ``` $ ./chip-tool doorlock unlock-door --timedInteractionTimeoutMs --PinCode 12345 ``` - In this command, you need to provide `--PinCode` corresponding to the PIN code you set with __ (for example `12345`). + In this command, you need to provide `--PinCode` corresponding to the PIN + code you set with __ (for example `12345`). From 3ac6a90f71952624680fbf3d80609d080fc2e744 Mon Sep 17 00:00:00 2001 From: Grzegorz Ferenc Date: Fri, 14 Jul 2023 12:08:07 +0200 Subject: [PATCH 04/10] fix spelling Signed-off-by: Grzegorz Ferenc --- .github/.wordlist.txt | 10 ++++++++++ docs/guides/chip_tool_guide.md | 6 +++--- 2 files changed, 13 insertions(+), 3 deletions(-) diff --git a/.github/.wordlist.txt b/.github/.wordlist.txt index 33d3b335cfc2d6..574c5aaeee917e 100644 --- a/.github/.wordlist.txt +++ b/.github/.wordlist.txt @@ -316,6 +316,10 @@ CPROTO cpuapp cpython CQM +CredentialData +CredentialIndex +CredentialRule +CredentialType crypto cryptographic CSA @@ -945,6 +949,8 @@ nwk NXP objcopy OccupancySensing +OccupiedDisabled +OccupiedEnabled OctetString OECORE ol @@ -966,6 +972,7 @@ OpenThreadDemo openweave OperationalCredentials operationalDataset +OperationType opkg optionMask optionOverride @@ -1434,9 +1441,12 @@ uscif UserConsentNeeded userConsentState userguide +UserIndex USERINTERFACE UserLabel usermod +UserStatus +UserUniqueID usr UTF util diff --git a/docs/guides/chip_tool_guide.md b/docs/guides/chip_tool_guide.md index bc91699538c0eb..95340eea6bc551 100644 --- a/docs/guides/chip_tool_guide.md +++ b/docs/guides/chip_tool_guide.md @@ -1465,7 +1465,7 @@ In this command: - `0` (Single) - One credential type is required to unlock. This value is selected is you set `null` for the variable. - `1` (Dual) - Two credential types are required to unlock. - - `2` (Tri) - Three credential types are required to unlock. + - `2` (Triple) - Three credential types are required to unlock. - __ is the ID of the door lock device. - __ is the ID of the endpoint on the door lock device. @@ -1518,11 +1518,11 @@ In this command: - __ is the index of the credential, between `1` and the maximum value you set in the `NumberOfCredentialsSupportedPerUser` - attribute (see the section 5.2.3.20 of the Matter Application Cluters + attribute (see the section 5.2.3.20 of the Matter Application Clusters specification for details). Setting the credential index to `0` will cause an error. -- __ is a string parameter with the secred credential data. +- __ is a string parameter with the secret credential data. For example, the PIN code value (`12345` in the example below). - __ is the index of the user that will be associated with the credential. Can be set to `null`. From e0e172a3e76cab8b0de3b23e5c5a7cc3613fbd74 Mon Sep 17 00:00:00 2001 From: Grzegorz Ferenc Date: Fri, 28 Jul 2023 08:32:46 +0200 Subject: [PATCH 05/10] update wordlist and reword additions Signed-off-by: Grzegorz Ferenc --- .github/.wordlist.txt | 10 ------ docs/guides/chip_tool_guide.md | 60 +++++++++++++++++----------------- 2 files changed, 30 insertions(+), 40 deletions(-) diff --git a/.github/.wordlist.txt b/.github/.wordlist.txt index 574c5aaeee917e..33d3b335cfc2d6 100644 --- a/.github/.wordlist.txt +++ b/.github/.wordlist.txt @@ -316,10 +316,6 @@ CPROTO cpuapp cpython CQM -CredentialData -CredentialIndex -CredentialRule -CredentialType crypto cryptographic CSA @@ -949,8 +945,6 @@ nwk NXP objcopy OccupancySensing -OccupiedDisabled -OccupiedEnabled OctetString OECORE ol @@ -972,7 +966,6 @@ OpenThreadDemo openweave OperationalCredentials operationalDataset -OperationType opkg optionMask optionOverride @@ -1441,12 +1434,9 @@ uscif UserConsentNeeded userConsentState userguide -UserIndex USERINTERFACE UserLabel usermod -UserStatus -UserUniqueID usr UTF util diff --git a/docs/guides/chip_tool_guide.md b/docs/guides/chip_tool_guide.md index 95340eea6bc551..b80f84cd5d4c83 100644 --- a/docs/guides/chip_tool_guide.md +++ b/docs/guides/chip_tool_guide.md @@ -1427,38 +1427,38 @@ To set up a user on a door lock device with the CHIP Tool, use the following command pattern: ``` -$ ./chip-tool doorlock set-user --timedInteractionTimeoutMs +$ ./chip-tool doorlock set-user --timedInteractionTimeoutMs ``` In this command: -- __ is one of the available types of operation for the user: +- __ is one of the available types of operation for the user: - - `Add` - This operation sets a new user in the slot at __. + - `Add` - This operation sets a new user in the slot at __. - `Clear` - This operation removes an existing user from the slot at - __. + __. - `Modify` - This operation modifies an existing user at the slot at - __. + __. -- __ is the index value of the user, between `1` and the maximum +- __ is the index value of the user, between `1` and the maximum value you set in the `NumberOfTotalUsersSupported` attribute. Setting the user index to `0` will cause an error. -- __ is the name of the user, which can have maximum 10 bytes of +- __ is the name of the user, which can have maximum 10 bytes of size. Can be set to `null`. -- __ is a 4-byte number that describes the unique user ID. Can +- __ is a 4-byte number that describes the unique user ID. Can be set to `null`. -- __ can be set to `null` or to one of the following values: +- __ can be set to `null` or to one of the following values: - - `0` (Available) - This status indicates that the given user slot is + - `0` (`Available`) - This status indicates that the given user slot is available for modification on the device. This value is selected is you set `null` for the variable. - - `1` (OccupiedEnabled) - This status indicates that the given user slot + - `1` (`OccupiedEnabled`) - This status indicates that the given user slot is used and active. - - `3` (OccupiedDisabled) - This status indicates that the given user slot + - `3` (`OccupiedDisabled`) - This status indicates that the given user slot is used, but disabled. Unlike `0` and `1`, supporting this status is optional. -- __ is the number of credentials that must be used to unlock +- __ is the number of credentials that must be used to unlock the door lock. This parameter can be set to `null` or to one of the following values: @@ -1489,25 +1489,25 @@ Once you have a user created on the door lock device, use the following command pattern to assign a credential to it: ``` -$ ./chip-tool doorlock set-credential <{Credential}> --timedInteractionTimeoutMs +$ ./chip-tool doorlock set-credential <{Credential}> --timedInteractionTimeoutMs ``` In this command: -- __ is one of the available types of operation for the +- __ is one of the available types of operation for the credential: - `Add` - This operation adds a new credential to a user at the slot at - __. + __. - `Clear` - This operation removes an existing credential from the user at - the slot at __. + the slot at __. - `Modify` - This operation modifies an existing credential for the user - at the slot at __. + at the slot at __. - _<{Credential}\>_ is a parameter in the JSON format, with the following two fields: - - __ is the type of the credential. It can have one of + - __ is the type of the credential. It can have one of the following values: - `0` - Programming PIN @@ -1516,17 +1516,17 @@ In this command: - `3` - Fingerprint - `4` - Finger vein - - __ is the index of the credential, between `1` and the + - __ is the index of the credential, between `1` and the maximum value you set in the `NumberOfCredentialsSupportedPerUser` attribute (see the section 5.2.3.20 of the Matter Application Clusters specification for details). Setting the credential index to `0` will cause an error. -- __ is a string parameter with the secret credential data. +- __ is a string parameter with the secret credential data. For example, the PIN code value (`12345` in the example below). -- __ is the index of the user that will be associated with the +- __ is the index of the user that will be associated with the credential. Can be set to `null`. -- __ is the status of the user that will be associated with the +- __ is the status of the user that will be associated with the credential. See the description of this parameter in [Set up a user](#step-1-set-up-a-user). Can be set to `null`. - __ is the ID of the door lock device. @@ -1552,10 +1552,10 @@ following command patterns are available: - Reading the status of the user: ``` - $ ./chip-tool doorlock get-user --timedInteractionTimeoutMs + $ ./chip-tool doorlock get-user --timedInteractionTimeoutMs ``` - This command returns the status of the user at the specified __ + This command returns the status of the user at the specified __ at the specified __ and __. - Reading the status of the credential: @@ -1570,10 +1570,10 @@ following command patterns are available: - Cleaning the user: ``` - $ ./chip-tool doorlock clear-user --timedInteractionTimeoutMs + $ ./chip-tool doorlock clear-user --timedInteractionTimeoutMs ``` - This command cleans the slot containing the specified __ at the + This command cleans the slot containing the specified __ at the specified __ and __. - Cleaning the credential: @@ -1587,7 +1587,7 @@ following command patterns are available: ### Operations with user PIN code -If you set the __ to PIN when +If you set the __ to PIN when [assigning credentials](#step-2-assign-a-credential), you can use the following command patterns to verify if it works and invoke it to open or close the door lock: @@ -1622,7 +1622,7 @@ lock: ``` In this command, you need to provide `--PinCode` corresponding to the PIN - code you set with __ (for example `12345`). + code you set with __ (for example `12345`). - Opening the door lock with the PIN code: @@ -1631,4 +1631,4 @@ lock: ``` In this command, you need to provide `--PinCode` corresponding to the PIN - code you set with __ (for example `12345`). + code you set with __ (for example `12345`). From dc4eae2477cd0e266b686c8260fb316109d12c79 Mon Sep 17 00:00:00 2001 From: "Restyled.io" Date: Fri, 28 Jul 2023 06:34:25 +0000 Subject: [PATCH 06/10] Restyled by prettier-markdown --- docs/guides/chip_tool_guide.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/guides/chip_tool_guide.md b/docs/guides/chip_tool_guide.md index 800307482543aa..bfe5f2bd681fb9 100644 --- a/docs/guides/chip_tool_guide.md +++ b/docs/guides/chip_tool_guide.md @@ -1447,8 +1447,8 @@ In this command: user index to `0` will cause an error. - __ is the name of the user, which can have maximum 10 bytes of size. Can be set to `null`. -- __ is a 4-byte number that describes the unique user ID. Can - be set to `null`. +- __ is a 4-byte number that describes the unique user ID. + Can be set to `null`. - __ can be set to `null` or to one of the following values: - `0` (`Available`) - This status indicates that the given user slot is @@ -1456,12 +1456,12 @@ In this command: set `null` for the variable. - `1` (`OccupiedEnabled`) - This status indicates that the given user slot is used and active. - - `3` (`OccupiedDisabled`) - This status indicates that the given user slot - is used, but disabled. Unlike `0` and `1`, supporting this status is - optional. + - `3` (`OccupiedDisabled`) - This status indicates that the given user + slot is used, but disabled. Unlike `0` and `1`, supporting this status + is optional. -- __ is the number of credentials that must be used to unlock - the door lock. This parameter can be set to `null` or to one of the +- __ is the number of credentials that must be used to + unlock the door lock. This parameter can be set to `null` or to one of the following values: - `0` (Single) - One credential type is required to unlock. This value is @@ -1518,8 +1518,8 @@ In this command: - `3` - Fingerprint - `4` - Finger vein - - __ is the index of the credential, between `1` and the - maximum value you set in the `NumberOfCredentialsSupportedPerUser` + - __ is the index of the credential, between `1` and + the maximum value you set in the `NumberOfCredentialsSupportedPerUser` attribute (see the section 5.2.3.20 of the Matter Application Clusters specification for details). Setting the credential index to `0` will cause an error. From 6153966e1503d54a50539297650a84a0f64e021a Mon Sep 17 00:00:00 2001 From: Grzegorz Ferenc Date: Thu, 10 Aug 2023 11:26:16 +0200 Subject: [PATCH 07/10] comments from Boris Signed-off-by: Grzegorz Ferenc --- docs/guides/chip_tool_guide.md | 76 +++++++++++++++++++++++----------- 1 file changed, 51 insertions(+), 25 deletions(-) diff --git a/docs/guides/chip_tool_guide.md b/docs/guides/chip_tool_guide.md index bfe5f2bd681fb9..21b67855dd4f4f 100644 --- a/docs/guides/chip_tool_guide.md +++ b/docs/guides/chip_tool_guide.md @@ -1442,8 +1442,8 @@ In this command: - `Modify` - This operation modifies an existing user at the slot at __. -- __ is the index value of the user, between `1` and the maximum - value you set in the `NumberOfTotalUsersSupported` attribute. Setting the +- __ is the index value of the user, between `1` and the + value of the `NumberOfTotalUsersSupported` attribute. Setting the user index to `0` will cause an error. - __ is the name of the user, which can have maximum 10 bytes of size. Can be set to `null`. @@ -1452,39 +1452,52 @@ In this command: - __ can be set to `null` or to one of the following values: - `0` (`Available`) - This status indicates that the given user slot is - available for modification on the device. This value is selected is you - set `null` for the variable. + available for modification on the device. - `1` (`OccupiedEnabled`) - This status indicates that the given user slot is used and active. - `3` (`OccupiedDisabled`) - This status indicates that the given user slot is used, but disabled. Unlike `0` and `1`, supporting this status is optional. +- __ is the type of the user, which can have one of the values specified + in the Matter Application Clusters specification for the `doorlock` cluster + (see section "5.2.9.16. UserTypeEnum"). Can be set to `null`. - __ is the number of credentials that must be used to unlock the door lock. This parameter can be set to `null` or to one of the following values: - - `0` (Single) - One credential type is required to unlock. This value is - selected is you set `null` for the variable. + - `0` (Single) - One credential type is required to unlock. - `1` (Dual) - Two credential types are required to unlock. - `2` (Triple) - Three credential types are required to unlock. -- __ is the ID of the door lock device. +- __ is the node ID of the door lock device. - __ is the ID of the endpoint on the door lock device. -- `--timedInteractionTimeoutMs` is the timeout duration for the interaction, - in milliseconds (__). This should allow enough time for the - interaction to complete. +- `--timedInteractionTimeoutMs` is the duration in milliseconds (__) + of the time window for receiving a request on the server side. + This should allow enough time for receiving the request. **Examples of command:** +The following command runs the `set-user` command that adds (`0`) a user at the index `1`; +the user has the name `AAA` and the unique ID `6452`. The user's status is set to `OccupiedEnabled` +(`1`), the user type is set to `UnrestrictedUser` (`0`), the credential rule is set to single (`0`), +the targeted node ID of the destination door lock device is `1` and the targeted `doorlock` +cluster's endpoint ID on that device is `1`. The `--timedInteractionTimeoutMs` has a custom value. + ``` $ ./chip-tool doorlock set-user 0 1 AAA 6452 1 0 0 1 1 --timedInteractionTimeoutMs 1000 ``` +The following command mirrors the action of the command above, but it targets an empty user name +(`null`) with the `0xFFFF` user unique ID (`null`). The user status defaults to `OccupiedEnabled`, +the user type defaults to `UnrestrictedUser`, and the credential rule defaults to single. + ``` $ ./chip-tool doorlock set-user 0 1 null null null null null 1 1 --timedInteractionTimeoutMs 1000 ``` +For more use cases for this command, see the "5.2.7.34. Set User Command" section in the Matter Application Clusters specification. + ### Step 2: Assign a credential Once you have a user created on the door lock device, use the following command @@ -1506,11 +1519,11 @@ In this command: - `Modify` - This operation modifies an existing credential for the user at the slot at __. -- _<{Credential}\>_ is a parameter in the JSON format, with the following two +- _<{Credential}\>_ is a JSON object, with the following two fields: - - __ is the type of the credential. It can have one of - the following values: + - `"credentialType"` is the key field for the type of the credential. + It can have one of the following values: - `0` - Programming PIN - `1` - PIN @@ -1518,31 +1531,44 @@ In this command: - `3` - Fingerprint - `4` - Finger vein - - __ is the index of the credential, between `1` and - the maximum value you set in the `NumberOfCredentialsSupportedPerUser` + - `"credentialIndex"` is the key field for the index of the credential, between `1` and + the value of the `NumberOfCredentialsSupportedPerUser` attribute (see the section 5.2.3.20 of the Matter Application Clusters - specification for details). Setting the credential index to `0` will + specification for details). `0` is required for the Programming PIN. + In other cases, setting the credential index to `0` will cause an error. -- __ is a string parameter with the secret credential data. +- __ is an octet string parameter with the secret credential data. For example, the PIN code value (`12345` in the example below). - __ is the index of the user that will be associated with the - credential. Can be set to `null`. + credential. Can be set to `null` to create a new user. - __ is the status of the user that will be associated with the credential. See the description of this parameter in [Set up a user](#step-1-set-up-a-user). Can be set to `null`. -- __ is the ID of the door lock device. +- __ is the type of the user, which can have one of the values specified + in the Matter Application Clusters specification for the `doorlock` cluster + (see section "5.2.9.16. UserTypeEnum"). Can be set to `null`. +- __ is the node ID of the door lock device. - __ is the ID of the endpoint on the door lock device. -- `--timedInteractionTimeoutMs` is the timeout duration for the interaction, - in milliseconds (__). This should allow enough time for the - interaction to complete. +- `--timedInteractionTimeoutMs` is the duration in milliseconds (__) + of the time window for receiving a request on the server side. + This should allow enough time for receiving the request. **Example of command:** +The following command runs the `set-credential` command that adds (`0`) a PIN credential (type `1`) +at the index `1`. The credential data is set to `12345` (PIN code value). This credential is +associated with the user at the index `1`. The `null` parameters for the user status +and the user type indicate that the credentials are added to an existing user. +The targeted node ID of the destination door lock device is `1` and the targeted `doorlock` +cluster's endpoint ID on that device is `1`. The `--timedInteractionTimeoutMs` has a custom value. + ``` $ ./chip-tool doorlock set-credential 0 '{ "credentialType": 1, "credentialIndex": 1 }' "12345" 1 null null 1 1 --timedInteractionTimeoutMs 1000 ``` +For more use cases for this command, see the "5.2.7.40. Set Credential Command" section in the Matter Application Clusters specification. + ### Operations on users and credentials After you set up users and credentials on your door lock device, you can use @@ -1554,7 +1580,7 @@ following command patterns are available: - Reading the status of the user: ``` - $ ./chip-tool doorlock get-user --timedInteractionTimeoutMs + $ ./chip-tool doorlock get-user ``` This command returns the status of the user at the specified __ @@ -1563,7 +1589,7 @@ following command patterns are available: - Reading the status of the credential: ``` - $ ./chip-tool doorlock get-credential-status <{Credential}> --timedInteractionTimeoutMs + $ ./chip-tool doorlock get-credential-status <{Credential}> ``` This command returns the status of the credential of the specified @@ -1597,7 +1623,7 @@ lock: - Verifying the PIN code: ``` - $ ./chip-tool doorlock read require-pinfor-remote-operation --timedInteractionTimeoutMs + $ ./chip-tool doorlock read require-pinfor-remote-operation ``` This command returns either `false` or `true`: From 0b310245f515203ee319bbdfa13df3b16fc43e99 Mon Sep 17 00:00:00 2001 From: Grzegorz Ferenc Date: Mon, 14 Aug 2023 14:38:00 +0200 Subject: [PATCH 08/10] comments from Boris Signed-off-by: Grzegorz Ferenc --- docs/guides/chip_tool_guide.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/guides/chip_tool_guide.md b/docs/guides/chip_tool_guide.md index 21b67855dd4f4f..503b5c15e26179 100644 --- a/docs/guides/chip_tool_guide.md +++ b/docs/guides/chip_tool_guide.md @@ -1451,8 +1451,6 @@ In this command: Can be set to `null`. - __ can be set to `null` or to one of the following values: - - `0` (`Available`) - This status indicates that the given user slot is - available for modification on the device. - `1` (`OccupiedEnabled`) - This status indicates that the given user slot is used and active. - `3` (`OccupiedDisabled`) - This status indicates that the given user @@ -1489,7 +1487,7 @@ $ ./chip-tool doorlock set-user 0 1 AAA 6452 1 0 0 1 1 --timedInteractionTimeout ``` The following command mirrors the action of the command above, but it targets an empty user name -(`null`) with the `0xFFFF` user unique ID (`null`). The user status defaults to `OccupiedEnabled`, +(`null`) and has `null` for the unique ID. The user status defaults to `OccupiedEnabled`, the user type defaults to `UnrestrictedUser`, and the credential rule defaults to single. ``` @@ -1531,7 +1529,8 @@ In this command: - `3` - Fingerprint - `4` - Finger vein - - `"credentialIndex"` is the key field for the index of the credential, between `1` and + - `"credentialIndex"` is the key field for the index of the credential. If `"credentialType"` + is not "Programming PIN", `"credentialIndex"` must be between `1` and the value of the `NumberOfCredentialsSupportedPerUser` attribute (see the section 5.2.3.20 of the Matter Application Clusters specification for details). `0` is required for the Programming PIN. From 62c90800985df8732af4b79caf267d3b95b7da6b Mon Sep 17 00:00:00 2001 From: Grzegorz Ferenc Date: Mon, 14 Aug 2023 14:39:05 +0200 Subject: [PATCH 09/10] misspell term update Signed-off-by: Grzegorz Ferenc --- docs/guides/chip_tool_guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/chip_tool_guide.md b/docs/guides/chip_tool_guide.md index 503b5c15e26179..ef7e9670c04469 100644 --- a/docs/guides/chip_tool_guide.md +++ b/docs/guides/chip_tool_guide.md @@ -1459,7 +1459,7 @@ In this command: - __ is the type of the user, which can have one of the values specified in the Matter Application Clusters specification for the `doorlock` cluster - (see section "5.2.9.16. UserTypeEnum"). Can be set to `null`. + (see section "5.2.9.16. `UserTypeEnum`"). Can be set to `null`. - __ is the number of credentials that must be used to unlock the door lock. This parameter can be set to `null` or to one of the following values: @@ -1546,7 +1546,7 @@ In this command: [Set up a user](#step-1-set-up-a-user). Can be set to `null`. - __ is the type of the user, which can have one of the values specified in the Matter Application Clusters specification for the `doorlock` cluster - (see section "5.2.9.16. UserTypeEnum"). Can be set to `null`. + (see section "5.2.9.16. `UserTypeEnum`"). Can be set to `null`. - __ is the node ID of the door lock device. - __ is the ID of the endpoint on the door lock device. - `--timedInteractionTimeoutMs` is the duration in milliseconds (__) From 678de0ab5391c2afb2521f9b5a17ad9198428065 Mon Sep 17 00:00:00 2001 From: "Restyled.io" Date: Mon, 14 Aug 2023 12:49:57 +0000 Subject: [PATCH 10/10] Restyled by prettier-markdown --- docs/guides/chip_tool_guide.md | 89 ++++++++++++++++++---------------- 1 file changed, 48 insertions(+), 41 deletions(-) diff --git a/docs/guides/chip_tool_guide.md b/docs/guides/chip_tool_guide.md index ef7e9670c04469..1d9cf524f677de 100644 --- a/docs/guides/chip_tool_guide.md +++ b/docs/guides/chip_tool_guide.md @@ -1442,9 +1442,9 @@ In this command: - `Modify` - This operation modifies an existing user at the slot at __. -- __ is the index value of the user, between `1` and the - value of the `NumberOfTotalUsersSupported` attribute. Setting the - user index to `0` will cause an error. +- __ is the index value of the user, between `1` and the value of + the `NumberOfTotalUsersSupported` attribute. Setting the user index to `0` + will cause an error. - __ is the name of the user, which can have maximum 10 bytes of size. Can be set to `null`. - __ is a 4-byte number that describes the unique user ID. @@ -1457,9 +1457,10 @@ In this command: slot is used, but disabled. Unlike `0` and `1`, supporting this status is optional. -- __ is the type of the user, which can have one of the values specified - in the Matter Application Clusters specification for the `doorlock` cluster - (see section "5.2.9.16. `UserTypeEnum`"). Can be set to `null`. +- __ is the type of the user, which can have one of the values + specified in the Matter Application Clusters specification for the + `doorlock` cluster (see section "5.2.9.16. `UserTypeEnum`"). Can be set to + `null`. - __ is the number of credentials that must be used to unlock the door lock. This parameter can be set to `null` or to one of the following values: @@ -1471,30 +1472,34 @@ In this command: - __ is the node ID of the door lock device. - __ is the ID of the endpoint on the door lock device. - `--timedInteractionTimeoutMs` is the duration in milliseconds (__) - of the time window for receiving a request on the server side. - This should allow enough time for receiving the request. + of the time window for receiving a request on the server side. This should + allow enough time for receiving the request. **Examples of command:** -The following command runs the `set-user` command that adds (`0`) a user at the index `1`; -the user has the name `AAA` and the unique ID `6452`. The user's status is set to `OccupiedEnabled` -(`1`), the user type is set to `UnrestrictedUser` (`0`), the credential rule is set to single (`0`), -the targeted node ID of the destination door lock device is `1` and the targeted `doorlock` -cluster's endpoint ID on that device is `1`. The `--timedInteractionTimeoutMs` has a custom value. +The following command runs the `set-user` command that adds (`0`) a user at the +index `1`; the user has the name `AAA` and the unique ID `6452`. The user's +status is set to `OccupiedEnabled` (`1`), the user type is set to +`UnrestrictedUser` (`0`), the credential rule is set to single (`0`), the +targeted node ID of the destination door lock device is `1` and the targeted +`doorlock` cluster's endpoint ID on that device is `1`. The +`--timedInteractionTimeoutMs` has a custom value. ``` $ ./chip-tool doorlock set-user 0 1 AAA 6452 1 0 0 1 1 --timedInteractionTimeoutMs 1000 ``` -The following command mirrors the action of the command above, but it targets an empty user name -(`null`) and has `null` for the unique ID. The user status defaults to `OccupiedEnabled`, -the user type defaults to `UnrestrictedUser`, and the credential rule defaults to single. +The following command mirrors the action of the command above, but it targets an +empty user name (`null`) and has `null` for the unique ID. The user status +defaults to `OccupiedEnabled`, the user type defaults to `UnrestrictedUser`, and +the credential rule defaults to single. ``` $ ./chip-tool doorlock set-user 0 1 null null null null null 1 1 --timedInteractionTimeoutMs 1000 ``` -For more use cases for this command, see the "5.2.7.34. Set User Command" section in the Matter Application Clusters specification. +For more use cases for this command, see the "5.2.7.34. Set User Command" +section in the Matter Application Clusters specification. ### Step 2: Assign a credential @@ -1517,11 +1522,10 @@ In this command: - `Modify` - This operation modifies an existing credential for the user at the slot at __. -- _<{Credential}\>_ is a JSON object, with the following two - fields: +- _<{Credential}\>_ is a JSON object, with the following two fields: - - `"credentialType"` is the key field for the type of the credential. - It can have one of the following values: + - `"credentialType"` is the key field for the type of the credential. It + can have one of the following values: - `0` - Programming PIN - `1` - PIN @@ -1529,44 +1533,47 @@ In this command: - `3` - Fingerprint - `4` - Finger vein - - `"credentialIndex"` is the key field for the index of the credential. If `"credentialType"` - is not "Programming PIN", `"credentialIndex"` must be between `1` and - the value of the `NumberOfCredentialsSupportedPerUser` + - `"credentialIndex"` is the key field for the index of the credential. If + `"credentialType"` is not "Programming PIN", `"credentialIndex"` must be + between `1` and the value of the `NumberOfCredentialsSupportedPerUser` attribute (see the section 5.2.3.20 of the Matter Application Clusters - specification for details). `0` is required for the Programming PIN. - In other cases, setting the credential index to `0` will - cause an error. + specification for details). `0` is required for the Programming PIN. In + other cases, setting the credential index to `0` will cause an error. -- __ is an octet string parameter with the secret credential data. - For example, the PIN code value (`12345` in the example below). +- __ is an octet string parameter with the secret credential + data. For example, the PIN code value (`12345` in the example below). - __ is the index of the user that will be associated with the credential. Can be set to `null` to create a new user. - __ is the status of the user that will be associated with the credential. See the description of this parameter in [Set up a user](#step-1-set-up-a-user). Can be set to `null`. -- __ is the type of the user, which can have one of the values specified - in the Matter Application Clusters specification for the `doorlock` cluster - (see section "5.2.9.16. `UserTypeEnum`"). Can be set to `null`. +- __ is the type of the user, which can have one of the values + specified in the Matter Application Clusters specification for the + `doorlock` cluster (see section "5.2.9.16. `UserTypeEnum`"). Can be set to + `null`. - __ is the node ID of the door lock device. - __ is the ID of the endpoint on the door lock device. - `--timedInteractionTimeoutMs` is the duration in milliseconds (__) - of the time window for receiving a request on the server side. - This should allow enough time for receiving the request. + of the time window for receiving a request on the server side. This should + allow enough time for receiving the request. **Example of command:** -The following command runs the `set-credential` command that adds (`0`) a PIN credential (type `1`) -at the index `1`. The credential data is set to `12345` (PIN code value). This credential is -associated with the user at the index `1`. The `null` parameters for the user status -and the user type indicate that the credentials are added to an existing user. -The targeted node ID of the destination door lock device is `1` and the targeted `doorlock` -cluster's endpoint ID on that device is `1`. The `--timedInteractionTimeoutMs` has a custom value. +The following command runs the `set-credential` command that adds (`0`) a PIN +credential (type `1`) at the index `1`. The credential data is set to `12345` +(PIN code value). This credential is associated with the user at the index `1`. +The `null` parameters for the user status and the user type indicate that the +credentials are added to an existing user. The targeted node ID of the +destination door lock device is `1` and the targeted `doorlock` cluster's +endpoint ID on that device is `1`. The `--timedInteractionTimeoutMs` has a +custom value. ``` $ ./chip-tool doorlock set-credential 0 '{ "credentialType": 1, "credentialIndex": 1 }' "12345" 1 null null 1 1 --timedInteractionTimeoutMs 1000 ``` -For more use cases for this command, see the "5.2.7.40. Set Credential Command" section in the Matter Application Clusters specification. +For more use cases for this command, see the "5.2.7.40. Set Credential Command" +section in the Matter Application Clusters specification. ### Operations on users and credentials