Merge branch 'master' into doc/esp32_vscode_development

.github/workflows/recent_fail_summary.yaml

@@ -0,0 +1,39 @@
+# Copyright (c) 2020 Project CHIP Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: Recent Fail Summary
+on:
+ schedule:
+ - cron: "0 0 * * *"
+ workflow_dispatch:
+
+concurrency:
+ group: ${{ github.workflow }}
+
+jobs:
+ list_workflows:
+ name: Summarize Recent Workflow Failures
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v3
+ - name: Setup
+ run: |
+ gh run list -b master -s failure --json displayTitle,workflowName > runlist.json
+ pip install pandas
+ env:
+ GH_TOKEN: ${{ github.token }}
+ - name: Run Summarization Script
+ run: python scripts/tools/summarize_fail.py
+

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,276 @@ $ ./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.
+
+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.
+
+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:
+
+```
+$ ./chip-tool doorlock set-user <operation-type> <user-index> <user-name> <user-unique-id> <user-status> <user-type> <credential-rule> <destination-id> <endpoint-id> --timedInteractionTimeoutMs <ms_value>
+```
+
+In this command:
+
+- _<operation-type\>_ is one of the available types of operation for the user:
+
+ - `Add` - This operation sets a new user in the slot at _<user-index\>_.
+ - `Clear` - This operation removes an existing user from the slot at
+ _<user-index\>_.
+ - `Modify` - This operation modifies an existing user at the slot at
+ _<user-index\>_.
+
+- _<user-index\>_ 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.
+- _<user-name\>_ is the name of the user, which can have maximum 10 bytes of
+ size. Can be set to `null`.
+- _<user-unique-id\>_ is a 4-byte number that describes the unique user ID.
+ Can be set to `null`.
+- _<user-status\>_ can be set to `null` or to one of the following values:
+
+ - `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.
+
+- _<user-type\>_ 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`.
+- _<credential-rule\>_ 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.
+ - `1` (Dual) - Two credential types are required to unlock.
+ - `2` (Triple) - Three credential types are required to unlock.
+
+- _<destination-id\>_ is the node ID of the door lock device.
+- _<endpoint-id\>_ is the ID of the endpoint on the door lock device.
+- `--timedInteractionTimeoutMs` is the duration in milliseconds (_<ms_value>_)
+ 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`) 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.
+
+### 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 <operation-type> <{Credential}> <credential-data> <user-index> <user-status> <user-type> <destination-id> <endpoint-id> --timedInteractionTimeoutMs <ms_value>
+```
+
+In this command:
+
+- _<operation-type\>_ 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
+ _<user-index\>_.
+ - `Clear` - This operation removes an existing credential from the user at
+ the slot at _<user-index\>_.
+ - `Modify` - This operation modifies an existing credential for the user
+ at the slot at _<user-index\>_.
+
+- _<{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:
+
+ - `0` - Programming PIN
+ - `1` - PIN
+ - `2` - RFID
+ - `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`
+ 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.
+
+- _<credential-data\>_ is an octet string parameter with the secret credential
+ data. For example, the PIN code value (`12345` in the example below).
+- _<user-index\>_ is the index of the user that will be associated with the
+ credential. Can be set to `null` to create a new user.
+- _<user-status\>_ 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`.
+- _<user-type\>_ 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`.
+- _<destination-id\>_ is the node ID of the door lock device.
+- _<endpoint-id\>_ is the ID of the endpoint on the door lock device.
+- `--timedInteractionTimeoutMs` is the duration in milliseconds (_<ms_value>_)
+ 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
+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 <user-index> <destination-id> <endpoint-id>
+ ```
+
+ This command returns the status of the user at the specified _<user-index\>_
+ 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>
+ ```
+
+ 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 <user-index> <destination-id> <endpoint-id> --timedInteractionTimeoutMs <ms_value>
+ ```
+
+ This command cleans the slot containing the specified _<user-index\>_ at the
+ specified _<destination-id\>_ and _<endpoint-id\>_.
+
+- Cleaning the credential:
+
+ ```
+ $ ./chip-tool doorlock clear-credential <{Credential}> <destination-id> <endpoint-id> --timedInteractionTimeoutMs <ms_value>
+ ```
+
+ 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 _<credential-type\>_ 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>
+ ```
+
+ 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 <ms_value> --PinCode 12345
+ ```
+
+ In this command, you need to provide `--PinCode` corresponding to the PIN
+ code you set with _<credential-data\>_ (for example `12345`).
+
+- Opening the door lock with the PIN code:
+
+ ```
+ $ ./chip-tool doorlock unlock-door <destination-id> <endpoint-id> --timedInteractionTimeoutMs <ms_value> --PinCode 12345
+ ```
+
+ In this command, you need to provide `--PinCode` corresponding to the PIN
+ code you set with _<credential-data\>_ (for example `12345`).

examples/virtual-device-app/android/BUILD.gn

@@ -27,6 +27,8 @@ shared_library("jni") {
  "java/AppImpl.cpp",
  "java/AppImpl.h",
  "java/ClusterChangeAttribute.cpp",
+ "java/ColorControlManager.cpp",
+ "java/ColorControlManager.h",
  "java/DeviceApp-JNI.cpp",
  "java/JNIDACProvider.cpp",
  "java/JNIDACProvider.h",
@@ -65,6 +67,7 @@ android_library("java") {
 
  sources = [
  "java/src/com/matter/virtual/device/app/Clusters.java",
+ "java/src/com/matter/virtual/device/app/ColorControlManager.java",
  "java/src/com/matter/virtual/device/app/DACProvider.java",
  "java/src/com/matter/virtual/device/app/DeviceApp.java",
  "java/src/com/matter/virtual/device/app/DeviceAppCallback.java",