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 <[email protected]>
project-chip · Jul 21, 2023 · 1447333 · 1447333
1 parent 9878128
commit 1447333
Showing 1 changed file with 179 additions and 2 deletions.
diff --git a/docs/guides/chip_tool_guide.md b/docs/guides/chip_tool_guide.md
@@ -1249,7 +1249,7 @@ The steps are the same as for the `subscribe` or `subscribe-event` commands.
 
 <hr>
 
-## 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
@@ -1320,7 +1320,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:
@@ -1393,3 +1393,180 @@ $ ./chip-tool any read-by-id <cluster-ids> <attribute-ids> <destination-id> <end
     ```
     ./chip-tool any read-by-id 0xFFFFFFFF 0xFFFFFFFF 1 0xFFFF
     ```
+
+<hr>
+
+## 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 <OperationType> <UserIndex> <UserName> <UserUniqueID> <UserStatus> <UserType> <CredentialRule> <destination-id> <endpoint-id> --timedInteractionTimeoutMs 1000
+```
+
+In this command:
+
+-   _<OperationType\>_ is one of the available types of operation for the user:
+
+    - `Add` - This operation adds a new user to the slot at _<UserIndex\>_.
+    - `Clear` - This operation removes an existing user from the slot at _<UserIndex\>_.
+    - `Modify` - This operation modifies an existing user at the slot at _<UserIndex\>_.
+
+-   _<UserIndex\>_ 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.
+-   _<UserName\>_ is the name of the user, which can have maximum 10 bytes of size.
+-   _<UserUniqueID\>_ is a 4-byte number that describes the unique user ID.
+-   _<UserStatus\>_ 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.
+
+-   _<CredentialRule\>_ 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.
+
+-   _<destination-id\>_ is the ID of the door lock device.
+-   _<endpoint-id\>_ 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 <OperationType> <{Credential}> <CredentialData> <UserIndex> <UserStatus> <UserType> <destination-id> <endpoint-id> --timedInteractionTimeoutMs 1000
+```
+In this command:
+
+-   _<OperationType\>_ 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 _<UserIndex\>_.
+    - `Clear` - This operation removes an existing credential from the user at the slot at _<UserIndex\>_.
+    - `Modify` - This operation modifies an existing credential for the user at the slot at _<UserIndex\>_.
+
+-   _<{Credential}\>_ is a JSON parameter with two fields:
+
+    - _<CredentialType\>_ 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
+
+    - _<CredentialIndex\>_ 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.
+
+-   _<CredentialData\>_ is a string parameter with the secred credential data. For example, the PIN code value (`12345` in the example below).
+-   _<UserIndex\>_ is the index of the user that will be associated with the credential.
+-   _<UserStatus\>_ 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).
+-   _<destination-id\>_ is the ID of the door lock device.
+-   _<endpoint-id\>_ 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 <UserIndex> <destination-id> <endpoint-id> --timedInteractionTimeoutMs 1000
+    ```
+
+  This command returns the status of the user at the specified _<UserIndex\>_ at the specified _<destination-id\>_ and _<endpoint-id\>_.
+
+- Reading the status of the credential:
+
+    ```
+    $ ./chip-tool doorlock get-credential-status <{Credential}> <destination-id> <endpoint-id> --timedInteractionTimeoutMs 1000
+    ```
+
+   This command returns the status of the credential of the specified _<{Credential}\>_ at the specified _<destination-id\>_ and _<endpoint-id\>_.
+
+- Cleaning the user:
+
+    ```
+    $ ./chip-tool doorlock clear-user <UserIndex> <destination-id> <endpoint-id> --timedInteractionTimeoutMs 1000
+    ```
+
+   This command cleans the slot containing the specified _<UserIndex\>_ at the specified _<destination-id\>_ and _<endpoint-id\>_.
+
+- Cleaning the credential:
+
+    ```
+    $ ./chip-tool doorlock clear-credential <{Credential}> <destination-id> <endpoint-id> --timedInteractionTimeoutMs 1000
+    ```
+
+   This command cleans the slot containing the specified _<{Credential}\>_ at the specified _<destination-id\>_ and _<endpoint-id\>_.
+
+### Operations with user PIN code
+
+If you set the _<CredentialType\>_ 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 <destination-id> <endpoint-id> --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 <destination-id> <endpoint-id>
+    ```
+
+  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 <destination-id> <endpoint-id> --timedInteractionTimeoutMs 2000 --PinCode 12345
+    ```
+
+   In this command, you need to provide `--PinCode` corresponding to the PIN code you set with _<CredentialData\>_ (for example `12345`).
+
+- Opening the door lock with the PIN code:
+
+    ```
+    $ ./chip-tool doorlock unlock-door <destination-id> <endpoint-id> --timedInteractionTimeoutMs 2000 --PinCode 12345
+    ```
+
+   In this command, you need to provide `--PinCode` corresponding to the PIN code you set with _<CredentialData\>_ (for example `12345`).