diff --git a/docs/guides/BUILDING.md b/docs/guides/BUILDING.md
index 9c32da51038047..4d0d9fa8a596db 100644
--- a/docs/guides/BUILDING.md
+++ b/docs/guides/BUILDING.md
@@ -4,16 +4,20 @@ Matter supports configuring the build with
[GN](https://gn.googlesource.com/gn/), a fast and scalable meta-build system
that generates inputs to [ninja](https://ninja-build.org/).
-Tested on:
+## Tested Operating Systems
+
+The build system has been tested on the following Operating Systems:
- macOS 10.15
- Debian 11 (64 bit required)
- Ubuntu 22.04 LTS
-Build system features:
+## Build system features
+
+The Matter build system has the following features:
- Very fast and small footprint
-- Cross-platform handling: (Linux, Darwin, embedded arm, etc.)
+- Cross-platform handling: Linux, Darwin, Embedded Arm, among others
- Multiple toolchains & cross toolchain dependencies
- Integrates automated testing framework: `ninja check`
- Introspection: `gn desc`
@@ -21,13 +25,15 @@ Build system features:
## Checking out the Matter code
-To check out the Matter repository:
+To check out the Matter repository, run the following command:
```
git clone --recurse-submodules git@github.com:project-chip/connectedhomeip.git
```
-If you already have a checkout, run the following command to sync submodules:
+## Synchronizing submodules
+
+If you already have the Matter code checked out, run the following command to synchronize submodules:
```
git submodule update --init
@@ -35,12 +41,12 @@ git submodule update --init
## Prerequisites
-Before building, you'll need to install a few OS specific dependencies.
+Before building, you must install a few OS specific dependencies.
### Installing prerequisites on Linux
On Debian-based Linux distributions such as Ubuntu, these dependencies can be
-satisfied with the following:
+satisfied with the following command:
```
sudo apt-get install git gcc g++ pkg-config libssl-dev libdbus-1-dev \
@@ -54,70 +60,77 @@ On macOS, install Xcode from the Mac App Store.
### Installing prerequisites on Raspberry Pi 4
-Using `rpi-imager`, install the Ubuntu _22.04_ 64-bit _server_ OS for arm64
-architectures on a micro SD card.
+Complete the following steps:
-Boot the SD card, login with the default user account "ubuntu" and password
-"ubuntu", then proceed with
+1. Using `rpi-imager`, install the Ubuntu _22.04_ 64-bit _server_ OS for arm64
+architectures on a micro SD card.
+1. Boot the SD card.
+1. Log in with the default user account "ubuntu" and password
+"ubuntu"
+1. Proceed with
[Installing prerequisites on Linux](#installing-prerequisites-on-linux).
+1. Install some Raspberry Pi specific dependencies:
-Finally, install some Raspberry Pi specific dependencies:
+ ```
+ sudo apt-get install pi-bluetooth avahi-utils
+ ```
-```
-sudo apt-get install pi-bluetooth avahi-utils
-```
+1. Reboot your Raspberry Pi after installing `pi-bluetooth`.
-You need to reboot your RPi after install `pi-bluetooth`.
+#### Configuring wpa_supplicant for storing permanent changes
-By default, wpa_supplicant is not allowed to update (overwrite) configuration,
-if you want the Matter app to be able to store the configuration changes
-permanently, we need to make the following changes.
+By default, wpa_supplicant is not allowed to update (overwrite) configuration.
+If you want the Matter application to be able to store the configuration changes
+permanently, you need to make the following changes:
-1. Edit the dbus-fi.w1.wpa_supplicant1.service file to use configuration file
- instead.
+1. Edit the `dbus-fi.w1.wpa_supplicant1.service` file to use configuration file
+ instead by running the following command:
-```
-sudo nano /etc/systemd/system/dbus-fi.w1.wpa_supplicant1.service
-```
+ ```
+ sudo nano /etc/systemd/system/dbus-fi.w1.wpa_supplicant1.service
+ ```
-Change the wpa_supplicant start parameters to:
+1. Run the following command to change the wpa_supplicant start parameters to the provided values:
-```
-ExecStart=/sbin/wpa_supplicant -u -s -i wlan0 -c /etc/wpa_supplicant/wpa_supplicant.conf
-```
+ ```
+ ExecStart=/sbin/wpa_supplicant -u -s -i wlan0 -c /etc/wpa_supplicant/wpa_supplicant.conf
+ ```
-2. Add the wpa-supplicant configuration file
+1. Add the `wpa-supplicant` configuration file by running the following command:
-```
-sudo nano /etc/wpa_supplicant/wpa_supplicant.conf
-```
+ ```
+ sudo nano /etc/wpa_supplicant/wpa_supplicant.conf
+ ```
-And add the following content to the file:
+1. Add the following content to the `wpa-supplicant` file:
-```
-ctrl_interface=DIR=/run/wpa_supplicant
-update_config=1
-```
+ ```
+ ctrl_interface=DIR=/run/wpa_supplicant
+ update_config=1
+ ```
-Finally, reboot your RPi.
+1. Reboot your Raspberry Pi.
-## Installing ZAP
+## Installing ZAP tool
-`bootstrap.sh` will download a compatible zap version and set it up in `$PATH`.
-If you want to install/use a different version, you may download one from the
-zap project [Releases](https://github.com/project-chip/zap/releases)
+`bootstrap.sh` will download a compatible ZAP tool version and set it up in `$PATH`.
+If you want to install or use a different version of the tool, you may download one from the
+ZAP project's [Releases](https://github.com/project-chip/zap/releases) page.
### Which ZAP to use
-ZAP scripting uses the following detection, in order:
+The ZAP tool scripting uses the following detection, in order of importance:
-- `$ZAP_DEVELOPMENT_PATH` to point to a zap checkout. Use this if you are
- developing zap locally and would like to run zap with your changes
+- `$ZAP_DEVELOPMENT_PATH` to point to a ZAP checkout.
-- `$ZAP_INSTALL_PATH` to point to where `zap-linux.zip`/`zap-mac.zip` was
- unpacked. This allows you to not need to place zap/zap-cli in `$PATH`
+ - Use this if you are developing ZAP locally and would like to run ZAP with your changes.
-- Otherwise scripts assume `zap-cli` or `zap` is available in `$PATH`
+- `$ZAP_INSTALL_PATH` to point to where `zap-linux.zip` or `zap-mac.zip` was
+ unpacked.
+
+ - This allows you to not need to place `zap` or `zap-cli` (or both) in `$PATH`.
+
+- Otherwise, the scripts assume `zap-cli` or `zap` is available in `$PATH`.
## Prepare for building
@@ -126,12 +139,16 @@ setup script should be sourced at the top level. This script takes care of
downloading GN, ninja, and setting up a Python environment with libraries used
to build and test.
+Run the following command:
+
```
source scripts/activate.sh
```
-If this script says the environment is out of date, it can be updated by
-running:
+### Updating the environment
+
+If the script says the environment is out of date, you can update it by
+running the following command:
```
source scripts/bootstrap.sh
@@ -142,7 +159,7 @@ is expensive, so avoid running it unless the environment is out of date.
## Build for the host OS (Linux or macOS)
-This will build all sources, libraries, and tests for the host platform:
+Run the following commands to build all sources, libraries, and tests for the host platform:
```
source scripts/activate.sh
@@ -152,8 +169,7 @@ gn gen out/host
ninja -C out/host
```
-This generates a configuration suitable for debugging. To configure an optimized
-build, specify `is_debug=false`:
+These commands generate a configuration suitable for debugging. To configure an optimized build, specify `is_debug=false`:
```
gn gen out/host --args='is_debug=false'
@@ -161,38 +177,41 @@ gn gen out/host --args='is_debug=false'
ninja -C out/host
```
-The directory name `out/host` can be any directory, although it's conventional
-to build within the `out` directory. This example uses `host` to emphasize that
-we're building for the host system. Different build directories can be used for
-different configurations, or a single directory can be used and reconfigured as
-necessary via `gn args`.
+> **Note:** The directory name `out/host` can be any directory, although it's conventional
+> to build within the `out` directory. This example uses `host` to emphasize
+> building for the host system. Different build directories can be used for
+> different configurations, or a single directory can be used and reconfigured as
+> necessary via `gn args`.
-To run all tests, run:
+To run all tests, run the following command:
```
ninja -C out/host check
```
-To run only the tests in `src/inet/tests`, you can run:
+To run only the tests in `src/inet/tests`, you can run the following command:
```
ninja -C out/host src/inet/tests:tests_run
```
-Note that the build system caches passing tests, so if you see
+> **Note:** The build system caches passing tests, so you may see the following message:
+>
+> ```
+> ninja: no work to do
+> ```
+>
+> This means that the tests passed in a previous build.
-```
-ninja: no work to do
-```
+## Build custom configuration
-that means that the tests passed in a previous build.
+The build is configured by setting build arguments. These you can set in one of the following manners:
-## Build custom configuration
+- Passing the `--args` option to `gn gen`.
+- Running `gn args` on the output directory.
+- Editing `args.gn` in the output directory.
-The build is configured by setting build arguments. These are set by passing the
-`--args` option to `gn gen`, by running `gn args` on the output directory, or by
-hand editing `args.gn` in the output directory. To configure a new build or edit
-the arguments to existing build, run:
+To configure a new build or edit the arguments to existing build, run the following command:
```
source scripts/activate.sh
@@ -202,10 +221,10 @@ gn args out/custom
ninja -C out/custom
```
-Two key builtin build arguments are `target_os` and `target_cpu`, which control
-the OS & CPU of the build.
+Two key built-in build arguments are `target_os` and `target_cpu`, which control
+the OS and CPU of the build, respectively.
-To see help for all available build arguments:
+To see help for all available build arguments, run the following command:
```
gn gen out/custom
@@ -214,10 +233,11 @@ gn args --list out/custom
## Build examples
-Examples can be built in two ways, as separate projects that add Matter in the
-third_party directory, or in the top level Matter project.
+You can build examples in two ways.
-To build the `chip-shell` example as a separate project:
+### Build examples as separate projects
+
+To build examples as separate projects that add Matter in the `third_party directory`, run the following command with the correct path to the example (here, `chip-shell`):
```
cd examples/shell
@@ -225,11 +245,14 @@ gn gen out/debug
ninja -C out/debug
```
-To build it at the top level, see below under "Unified Builds".
+### Build examples at the top level
+
+You can build examples at the top level of the Matter project.
+See the following "Unified builds" section for details.
## Unified builds
-To build a unified configuration that approximates the set of continuous builds:
+To build a unified configuration that approximates the set of continuous builds, run the following commands:
```
source scripts/activate.sh
@@ -239,11 +262,9 @@ gn gen out/unified --args='is_debug=true target_os="all"'
ninja -C out/unified all
```
-This can be used prior to change submission to configure, build, and test the
-gcc, clang, mbedtls, & examples configurations all together in one parallel
-build. Each configuration has a separate subdirectory in the output dir.
+You can use this set of commands before changing a submission to configure, build, and test the GCC, Clang, MbedTLS, and examples configurations all together in one parallel build. Each configuration has a separate subdirectory in the output directory.
-This unified build can be used for day to day development, although it's more
+This unified build can be used for day-to-day development, although it's more
expensive to build everything for every edit. To save time, you can name the
configuration to build:
@@ -255,7 +276,8 @@ ninja -C out/unified check_host_gcc
Replace `host_gcc` with the name of the configuration, which is found in the
root `BUILD.gn`.
-You can also fine tune the configurations generated via arguments such as:
+You can also fine tune the configurations generated with arguments.
+For example:
```
gn gen out/unified --args='is_debug=true target_os="all" enable_host_clang_build=false'
@@ -263,7 +285,7 @@ gn gen out/unified --args='is_debug=true target_os="all" enable_host_clang_build
For a full list, see the root `BUILD.gn`.
-Note that in the unified build, targets have multiple instances and need to be
+In the unified build, targets have multiple instances and need to be
disambiguated by adding a `(toolchain)` suffix. Use `gn ls out/debug` to list
all of the target instances. For example:
@@ -271,26 +293,22 @@ all of the target instances. For example:
gn desc out/unified '//src/controller(//build/toolchain/host:linux_x64_clang)'
```
-Note: Some platforms that can be built as part of the unified build require
-downloading additional tools. To add these to the build, the location must be
-provided as a build argument. For example, to add the Simplelink cc13x2_26x2
-examples to the unified build, install
-[SysConfig](https://www.ti.com/tool/SYSCONFIG) and add the following build
-arguments:
-
-```
-gn gen out/unified --args="target_os=\"all\" enable_ti_simplelink_builds=true ti_sysconfig_root=\"/path/to/sysconfig\""
-```
+> **Note:** Some platforms that can be built as part of the unified build require
+> downloading additional tools. To add these to the build, the location must be
+> provided as a build argument. For example, to add the Simplelink cc13x2_26x2
+> examples to the unified build, install
+> [SysConfig](https://www.ti.com/tool/SYSCONFIG) and add the following build
+> arguments:
+>
+> ```
+> gn gen out/unified --args="target_os=\"all\" enable_ti_simplelink_builds=true > ti_sysconfig_root=\"/path/to/sysconfig\""
+> ```
## Getting help
-GN has builtin help via
-
-```
-gn help
-```
+GN has integrated help that you can access with the ``gn help`` command.
-Recommended topics:
+Make sure to check the following recommended topics:
```
gn help execution
@@ -303,70 +321,71 @@ Also see the
## Introspection
-GN has various introspection tools to help examine the build configuration.
+GN has various introspection tools to help you examine the build configuration.
+The following examples use the `out/host` output directory as example:
-To show all of the targets in an output directory:
+- Show all of the targets in an output directory:
-```
-gn ls out/host
-```
+ ```
+ gn ls out/host
+ ```
-To show all of the files that will be built:
+- Show all of the files that will be built:
-```
-gn outputs out/host '*'
-```
+ ```
+ gn outputs out/host '*'
+ ```
-To show the GN representation of a configured target:
+- Show the GN representation of a configured target:
-```
-gn desc out/host //src/inet --all
-```
+ ```
+ gn desc out/host //src/inet --all
+ ```
-To dump the GN representation of the entire build as JSON:
+- Dump the GN representation of the entire build as JSON:
-```
-gn desc out/host/ '*' --all --format=json
-```
+ ```
+ gn desc out/host/ '*' --all --format=json
+ ```
-To show the dependency tree:
+- Show the dependency tree:
-```
-gn desc out/host //:all deps --tree --all
-```
+ ```
+ gn desc out/host //:all deps --tree --all
+ ```
-To find dependency paths:
+- Find dependency paths:
-```
-gn path out/host //src/transport/tests:tests //src/system
-```
+ ```
+ gn path out/host //src/transport/tests:tests //src/system
+ ```
-To list useful information for linking against libCHIP:
+- List useful information for linking against `libCHIP`:
-```
-gn desc out/host //src/lib include_dirs
-gn desc out/host //src/lib defines
-gn desc out/host //src/lib outputs
+ ```
+ gn desc out/host //src/lib include_dirs
+ gn desc out/host //src/lib defines
+ gn desc out/host //src/lib outputs
-# everything as JSON
-gn desc out/host //src/lib --format=json
-```
+ # everything as JSON
+ gn desc out/host //src/lib --format=json
+ ```
## Coverage
-Code coverage scripts generate a report that details how much of the Matter SDK
-source code has been executed, it also gives information on how often the Matter
-SDK executes segments of code and produces a copy of the source file, annotated
+The code coverage script generates a report that details how much of the Matter SDK
+source code has been executed. It also provides information on how often the Matter
+SDK executes segments of the code and produces a copy of the source file, annotated
with execution frequencies.
+Run the following command to initiate the script:
+
```
./scripts/build_coverage.sh
```
-By default, Code coverage is performed at the unit testing level. Unit tests are
-created by developers, thus giving them the best vantage from which to decide
-what tests to include in unit testing. But you can extend the coverage test by
-scope and ways of execution with the following parameters:
+By default, the code coverage script is performed at the unit testing level. Unit tests are
+created by developers, thus giving them the best overview of what tests to include in unit testing. You can extend the coverage test by scope and ways of execution with the following parameters:
```
-c, --code Specify which scope to collect coverage data.
@@ -379,11 +398,10 @@ scope and ways of execution with the following parameters:
'all': Run unit & yaml test to drive the coverage check.
```
-Also see the up-to-date unit testing coverage report of the Matter SDK
+Also, see the up-to-date unit testing coverage report of the Matter SDK
(collected daily) at:
[matter coverage](https://matter-build-automation.ue.r.appspot.com).
## Maintaining Matter
-If you make any change to the GN build system, the next build will regenerate
-the ninja files automatically. No need to do anything.
+If you make any change to the GN build system, the next build will regenerate the ninja files automatically. No need to do anything.
diff --git a/docs/guides/access-control-guide.md b/docs/guides/access-control-guide.md
index d82ec309b8b8b9..38314ed5a289f5 100644
--- a/docs/guides/access-control-guide.md
+++ b/docs/guides/access-control-guide.md
@@ -1,8 +1,14 @@
# Access Control Guide
-All Interaction Model operations (read attribute, write attribute, invoke
-command, read event) are governed by access control, and will be denied (status
-0x7E Access Denied) if sufficient privilege for the operation is not obtained.
+All Interaction Model operations in Matter must be verified by the the Access Control mechanism.
+
+Whenever a client device and a server device want to interact with one another by reading (or subscribing) attributes or events, writing attributes, or invoking commands, the Access Control mechanism must verify that the client has sufficient privileges to perform the operation on the server device.
+
+If no sufficient privilege is obtained, the operation cannot take place and it is denied (status `0x7E Access Denied`).
+
+This guide describes how the Access Control mechanism works and how it is implemented, and provides examples of Access Control Lists (ACLs) for different use cases.
+
+
## Overview
@@ -24,30 +30,32 @@ node. It is these ACLs that govern which Interaction Model operations are
allowed or denied on that server node, for subjects on the fabric, via CASE and
group messaging.
-## ACLs
+
-ACLs are fabric-scoped data structures with the following fields:
+## Access Control Lists
-- Privilege
-- AuthMode
-- Subjects
-- Targets
+Access Control Lists (ACLs) are fabric-scoped data structures with the following fields:
-### Privilege
+- `Privilege`
+- `AuthMode`
+- `Subjects`
+- `Targets`
-Privileges are:
+### Privilege field
+
+The `Privilege` can be of the following types:
- View
- Operate
- Manage
- Administer
-An additional `ProxyView` privilege is not yet supported in the Matter SDK.
+> **Note:** An additional `ProxyView` privilege is not yet supported in the Matter SDK.
By default, the `View` privilege is required to read attributes or events, and
the `Operate` privilege is required to write attributes or invoke commands.
-However, clusters may require stricter privileges for certain operations on
+Clusters may also require stricter privileges for certain operations on
certain endpoints. For example, the Access Control Cluster requires the
`Administer` privilege for all its operations.
@@ -55,30 +63,30 @@ If applicable, the ACL grants the privilege, and all less strict privileges
subsumed by it. Therefore an ACL for `Manage` privilege will work for operations
which require `Operate` or `View` privilege (but not `Administer` privilege).
-### AuthMode
+### AuthMode field
-Authentication modes are:
+The `AuthMode`, that is authentication modes, can be as follow:
- CASE
- Group
The ACL applies only to subjects using that authentication mode.
-### Subjects
+### Subjects field
-Subjects is a list containing zero, one, or more subject identifiers, which are:
+The `Subjects` field is a list containing zero, one, or more subject identifiers, which are:
-- Node ID for CASE auth mode
-- Group ID for Group auth mode
+- Node ID for CASE `AuthMode`
+- Group ID for Group `AuthMode`
A CASE subject may be a CAT, which has its own tag and version mechanism.
The ACL applies only to the listed subjects; if no subjects are listed, the ACL
applies to any subjects using the authentication mode.
-### Targets
+### Targets field
-Targets is a list containing zero, one, or more structured entries with fields:
+The `Targets` field is a list containing zero, one, or more structured entries with fields:
- Cluster
- Endpoint
@@ -86,20 +94,20 @@ Targets is a list containing zero, one, or more structured entries with fields:
All fields are nullable, but at least one must be present, and the endpoint and
device type fields are mutually exclusive (only one of those two may be
-present).
-
-If cluster is present, the ACL is targeted to just that cluster.
-
-If endpoint is present, the ACL is targeted to just that endpoint.
+present):
-If device type is present, the ACL is targeted to just endpoints which contain
+- If cluster is present, the ACL is targeted to just that cluster.
+- If endpoint is present, the ACL is targeted to just that endpoint.
+- If device type is present, the ACL is targeted to just endpoints which contain
that device type (as reported by the Descriptor Cluster).
-Specifying device type in targets is not yet supported in the Matter SDK.
+> **Note:** Specifying device type in targets is not yet supported in the Matter SDK.
The ACL applies only to the listed targets; if no targets are listed, the ACL
applies to any targets on the server node.
+
+
## Limitations and Restrictions
The Matter Specification states that a Matter implementation must support at
@@ -120,8 +128,12 @@ can be configured globally in `CHIPConfig.h` or per-app in
- CHIP_CONFIG_EXAMPLE_ACCESS_CONTROL_MAX_SUBJECTS_PER_ENTRY
- CHIP_CONFIG_EXAMPLE_ACCESS_CONTROL_MAX_TARGETS_PER_ENTRY
+
+
## Case Studies
+This section provides use case examples for different ACL scenarios.
+
### Single Administrator
A single controller commissions a server node, providing its own CASE node ID
@@ -174,15 +186,19 @@ Members of groups 123 and 456 are granted `Operate` privilege for the on/off
cluster on any endpoint, any cluster on endpoint 1, and the level control
cluster on endpoint 2.
-## Managing ACLs Using Chip-Tool
+
+
+## Managing ACLs using CHIP-Tool
### Usage
+The following sections describe the requirements for managing ACLs using the CHIP-Tool.
+
#### Entire List
The Access Control Cluster's `ACL` attribute is a list.
-Currently, list operations for single entries (append, update, delete) are not
+> **Note:** Currently, list operations for single entries (append, update, delete) are not
yet supported in the Matter SDK, so the entire list must be written to the
attribute to change any ACL.
@@ -215,38 +231,42 @@ When reading ACLs, the proper fabric index is shown.
The tool requires numerical values for enums and identifiers.
-The privileges are:
+- Privilege values:
-- View: 1
-- Operate: 3
-- Manage: 4
-- Administer: 5
+ - View: 1
+ - Operate: 3
+ - Manage: 4
+ - Administer: 5
-The authentication modes are:
+- AuthMode values:
-- CASE: 2
-- Group: 3
+ - CASE: 2
+ - Group: 3
-Some typical clusters:
+- Values for some typical clusters:
-- On/Off: 6
-- Level Control: 8
-- Descriptor: 29
-- Binding: 30
-- Access Control: 31
-- Basic: 40
+ - On/Off: 6
+ - Level Control: 8
+ - Descriptor: 29
+ - Binding: 30
+ - Access Control: 31
+ - Basic: 40
### Examples
-#### Automatically Installed ACL
+This section provides examples of commands and ACL output for different operations with the CHIP-Tool.
-After commissioning with chip-tool, assuming `CaseAdminNode` is 112233, the
-automatically installed ACL is:
+#### Verification of the Automatically Installed ACL
+
+During commissioning with the CHIP-Tool, an ACL that assigns Administer rights to the commissioner is automatically installed on the commissionee. This can be verified using the following command:
```
out/debug/standalone/chip-tool accesscontrol read acl 1 0
```
+Assuming the `CaseAdminNode` value is `112233`, the
+ACL command output for this case is the following:
+
```
Endpoint: 0 Cluster: 0x0000_001F Attribute 0x0000_0000 DataVersion: 2578401031
ACL: 1 entries
@@ -262,10 +282,14 @@ Endpoint: 0 Cluster: 0x0000_001F Attribute 0x0000_0000 DataVersion: 2578401031
#### Installing a CASE ACL
+The following command example requests the installation of a CASE ACL through a write interaction:
+
```
out/debug/standalone/chip-tool accesscontrol write acl '[{"fabricIndex": 0, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 0, "privilege": 1, "authMode": 2, "subjects": [4444, 5555, 6666], "targets": null}]' 1 0
```
+The resulting ACL command output for this case can look like the following one:
+
```
Endpoint: 0 Cluster: 0x0000_001F Attribute 0x0000_0000 DataVersion: 2578401034
ACL: 2 entries
@@ -291,10 +315,14 @@ Endpoint: 0 Cluster: 0x0000_001F Attribute 0x0000_0000 DataVersion: 2578401034
#### Installing a Group ACL
+The following command example requests the installation of a Group ACL through a write interaction:
+
```
out/debug/standalone/chip-tool accesscontrol write acl '[{"fabricIndex": 0, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 0, "privilege": 1, "authMode": 2, "subjects": [4444, 5555, 6666], "targets": null}, {"fabricIndex": 0, "privilege": 3, "authMode": 3, "subjects": [123, 456], "targets": [{"cluster": 6, "endpoint": null, "deviceType": null}, {"cluster": null, "endpoint": 1, "deviceType": null}, {"cluster": 8, "endpoint": 2, "deviceType": null}]}]' 1 0
```
+The resulting ACL command output for this case can look like the following one:
+
```
Endpoint: 0 Cluster: 0x0000_001F Attribute 0x0000_0000DataVersion: 2578401041
ACL: 3 entries
@@ -342,22 +370,23 @@ Endpoint: 0 Cluster: 0x0000_001F Attribute 0x0000_0000DataVersion: 2578401041
}
```
-## Managing ACLs Using Chip-Repl
+
+
+## Managing ACLs Using Chip-repl
### Usage
+This section provides examples of commands and ACL output for different operations with the CHIP-repl.
+
#### Entire List
-See the important notes in the chip-tool section, as they also apply to
-chip-repl.
+See the important notes in the [Managing ACLs using CHIP-Tool](#managing-acls-using-chip-tool) section, as they also apply to the CHIP-repl.
### Null Fields
Null fields may be omitted.
-OK: `Target(cluster=6, endpoint=Null, deviceType=Null)`
-
-Also OK: `Target(cluster=6)`
+This means that the following entry is acceptable: `Target(cluster=6, endpoint=Null, deviceType=Null)`. Just as the following one: `Target(cluster=6)`.
The above assumes Target and Null are defined at global scope, which is not
normally the case.
@@ -366,14 +395,14 @@ normally the case.
The `ACL` attribute is fabric-scoped, so each ACL has a fabric index.
-The REPL ignores it when performing the actual write. Because null fields can be
+The CHIP-repl ignores it when performing the actual write. Because null fields can be
omitted, simply do not provide it when writing ACLs.
When reading ACLs, the proper fabric index is shown.
#### Enums and Identifiers
-The REPL accepts numerical values for enums and identifiers, but it also accepts
+The CHIP-repl accepts numerical values for enums and identifiers, but it also accepts
strongly typed values:
The privileges are:
@@ -399,6 +428,8 @@ Some typical clusters:
### Examples
+This section provides examples of commands and ACL output for different operations with the CHIP-repl.
+
#### Automatically Installed ACL
After commissioning with chip-repl, assuming `CaseAdminNode` is 1, the
diff --git a/docs/guides/chip_tool_guide.md b/docs/guides/chip_tool_guide.md
index 220c850e90bb40..920f0a1e496a32 100644
--- a/docs/guides/chip_tool_guide.md
+++ b/docs/guides/chip_tool_guide.md
@@ -8,13 +8,6 @@ the setup payload or performing discovery actions.
-- [Source files](#source-files)
-- [Building and running the CHIP Tool](#building-and-running-the-chip-tool)
-- [Using the CHIP Tool for Matter device testing](#using-chip-tool-for-matter-device-testing)
-- [Supported commands and options](#supported-commands-and-options)
-
-
-
## Source files
You can find source files of the CHIP Tool in the `examples/chip-tool`
@@ -110,9 +103,9 @@ such as Thread or Wi-Fi.
The Matter specification does not define the preferred way of how the network
credentials are to be obtained by controller. In this guide, we are going to
-obtain Thread network credentials.
+provide steps for obtaining Thread and Wi-Fi network credentials.
-#### Thread network credentials
+#### Obtaining Thread network credentials
Fetch and store the current Active Operational Dataset from the Thread Border
Router. This step may vary depending on the Thread Border Router implementation.
@@ -140,10 +133,10 @@ If you are using
For Thread, you might also use a different out-of-band method to fetch the
network credentials.
-#### Wi-Fi network credentials
+#### Obtaining Wi-Fi network credentials
You must get the following Wi-Fi network credentials to commission the Matter
-device to the Wi-Fi network in the following steps:
+device to the Wi-Fi network:
- Wi-Fi SSID
- Wi-Fi password
@@ -171,10 +164,10 @@ I: 278 [DL] Manufacturing Date: (not set)
I: 281 [DL] Device Type: 65535 (0xFFFF)
```
-In above printout, the _discriminator_ is `3840 (0xF00)` and the _setup PIN
+In this printout, the _discriminator_ is `3840 (0xF00)` and the _setup PIN
code_ is equal to `20202021`.
-### Step 6: Commission Matter device into existing IP network
+### Step 6: Commission Matter device into an existing IP network
Before communicating with the Matter device, first it must join an existing IP
network.
@@ -190,17 +183,17 @@ protocol.
This section describes how your device can join the existing IP network over
Bluetooth LE and then be commissioned into a Matter network.
-After connecting the device over Bluetooth LE, the controller will print the
+After connecting the device over Bluetooth LE, the controller prints the
following log:
```
Secure Session to Device Established
```
-This log will mean that the PASE (Password-Authenticated Session Establishment)
+This log message means that the PASE (Password-Authenticated Session Establishment)
session using SPAKE2+ protocol has been established.
-##### Commissioning into Thread network over Bluetooth LE
+##### Commissioning into a Thread network over Bluetooth LE
To commission the device to the existing Thread network, use the following
command pattern:
@@ -218,7 +211,7 @@ In this command:
the
[step 5](#step-5-determine-matter-devices-discriminator-and-setup-pin-code).
-##### Commissioning into Wi-Fi network over Bluetooth LE
+##### Commissioning into a Wi-Fi network over Bluetooth LE
To commission the device to the existing Wi-Fi network, use the following
command pattern:
@@ -695,15 +688,15 @@ Here, __ is the ID of the payload to be parsed.
- Setup QR code payload:
- ```
- $ ./chip-tool payload parse-setup-payload MT:6FCJ142C00KA0648G00
- ```
+ ```
+ $ ./chip-tool payload parse-setup-payload MT:6FCJ142C00KA0648G00
+ ```
- Manual pairing code:
- ```
- $ ./chip-tool payload parse-setup-payload 34970112332
- ```
+ ```
+ $ ./chip-tool payload parse-setup-payload 34970112332
+ ```
### Parsing additional data payload
diff --git a/docs/guides/images/chip_nrfconnect_overview_simplified.svg b/docs/guides/images/chip_nrfconnect_overview_simplified.svg
deleted file mode 100644
index 63c5139b38dc48..00000000000000
--- a/docs/guides/images/chip_nrfconnect_overview_simplified.svg
+++ /dev/null
@@ -1,278 +0,0 @@
-
-
-
-
diff --git a/docs/guides/images/matter_nrfconnect_overview_simplified_ncs.svg b/docs/guides/images/matter_nrfconnect_overview_simplified_ncs.svg
new file mode 100644
index 00000000000000..21316c04f125fc
--- /dev/null
+++ b/docs/guides/images/matter_nrfconnect_overview_simplified_ncs.svg
@@ -0,0 +1,314 @@
+
+
+
+
diff --git a/docs/guides/nrfconnect_examples_cli.md b/docs/guides/nrfconnect_examples_cli.md
index ecd31d28bbf965..8ad154a355ca12 100644
--- a/docs/guides/nrfconnect_examples_cli.md
+++ b/docs/guides/nrfconnect_examples_cli.md
@@ -4,18 +4,22 @@ Some Matter examples for the development kits from Nordic Semiconductor include
a command-line interface that allows access to application logs and
[Zephyr shell](https://docs.zephyrproject.org/1.13.0/subsystems/shell.html).
+
+
## Accessing the CLI console
To access the CLI console, use a serial terminal emulator of your choice, like
Minicom or GNU Screen. Use the baud rate set to `115200`.
+### Example: Starting the CLI console with Minicom
+
For example, to start using the CLI console with Minicom, run the following
command with `/dev/ttyACM0` replaced with the device node name of your
development kit:
- ```
- minicom -D /dev/ttyACM0 -b 115200
- ```
+```
+minicom -D /dev/ttyACM0 -b 115200
+```
When you reboot the kit, you will see the boot logs in the console, similar to
the following messages:
@@ -51,6 +55,8 @@ Threads:
...
```
+
+
## Listing all commands
To list all available commands, use the Tab key, which is normally used for the
@@ -69,10 +75,12 @@ uart:~$
Pressing the Tab key with a command entered in the command line cycles through
available options for the given command.
+
+
## Using OpenThread commands
[OpenThread commands](https://github.com/openthread/openthread/blob/master/src/cli/README.md)
-are also accessible from the shell. However, they must preceded by `ot`. For
+are accessible from the shell, but they must preceded by `ot`. For
example:
```shell
@@ -81,6 +89,8 @@ uart:~$ ot masterkey
Done
```
+
+
## Using Matter-specific commands
The nRF Connect examples let you use several Matter-specific CLI commands.
@@ -94,12 +104,12 @@ Every invoked command must be preceded by the `matter` prefix.
See the following subsections for the description of each Matter-specific
command.
-### device
+### `device` command group
Handles a group of commands that are used to manage the device. You must use
this command together with one of the additional subcommands listed below.
-#### factoryreset
+#### `factoryreset` subcommand
Performs device factory reset that is hardware reset preceded by erasing of the
whole Matter settings stored in a non-volatile memory.
@@ -109,20 +119,22 @@ uart:~$ matter device factoryreset
Performing factory reset ...
```
-### onboardingcodes
+### `onboardingcodes` command group
Handles a group of commands that are used to view information about device
onboarding codes. The `onboardingcodes` command takes one required parameter for
the rendezvous type, then an optional parameter for printing a specific type of
onboarding code.
-The full format of the command is:
+The full format of the command is as follows:
```
onboardingcodes none|softap|ble|onnetwork [qrcode|qrcodeurl|manualpairingcode]
```
-To print all the onboardingcodes:
+#### `none` subcommand
+
+Prints all onboarding codes. For example:
```shell
uart:~$ matter onboardingcodes none
@@ -130,10 +142,7 @@ QRCode: MT:W0GU2OTB00KA0648G00
QRCodeUrl: https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3AW0GU2OTB00KA0648G00
ManualPairingCode: 34970112332
```
-
-To print a specific type of onboarding code:
-
-#### qrcode
+#### `none qrcode` subcommand
Prints the device
[onboarding QR code payload](https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/nrfconnect_android_commissioning.md#preparing-accessory-device).
@@ -144,7 +153,7 @@ uart:~$ matter onboardingcodes none qrcode
MT:W0GU2OTB00KA0648G00
```
-#### qrcodeurl
+#### `none qrcodeurl` subcommand
Prints the URL to view the
[device onboarding QR code](https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/nrfconnect_android_commissioning.md#preparing-accessory-device)
@@ -155,7 +164,7 @@ uart:~$ matter onboardingcodes none qrcodeurl
https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3AW0GU2OTB00KA0648G00
```
-#### manualpairingcode
+#### `none manualpairingcode` subcommand
Prints the pairing code for the manual onboarding of a device. Takes no
arguments.
@@ -165,13 +174,14 @@ uart:~$ matter onboardingcodes none manualpairingcode
34970112332
```
-### config
+### `config` command group
Handles a group of commands that are used to view device configuration
information. You can use this command without any subcommand to print all
available configuration data or to add a specific subcommand.
```shell
+uart:~$ matter config
VendorId: 65521 (0xFFF1)
ProductId: 32768 (0x8000)
HardwareVersion: 1 (0x1)
@@ -183,7 +193,7 @@ DeviceId:
The `config` command can also take the subcommands listed below.
-#### pincode
+#### `pincode` subcommand
Prints the PIN code for device setup. Takes no arguments.
@@ -192,7 +202,7 @@ uart:~$ matter config pincode
020202021
```
-#### discriminator
+#### `discriminator` subcommand
Prints the device setup discriminator. Takes no arguments.
@@ -201,7 +211,7 @@ uart:~$ matter config discriminator
f00
```
-#### vendorid
+#### `vendorid` subcommand
Prints the vendor ID of the device. Takes no arguments.
@@ -210,7 +220,7 @@ uart:~$ matter config vendorid
65521 (0xFFFF1)
```
-#### productid
+#### `productid` subcommand
Prints the product ID of the device. Takes no arguments.
@@ -219,7 +229,7 @@ uart:~$ matter config productid
32768 (0x8000)
```
-#### hardwarever
+#### `hardwarever` subcommand
Prints the hardware version of the device. Takes no arguments.
@@ -228,23 +238,23 @@ uart:~$ matter config hardwarever
1 (0x1)
```
-#### deviceid
+#### `deviceid` subcommand
Prints the device identifier. Takes no arguments.
-#### fabricid
+#### `fabricid` subcommand
Prints the fabric identifier. Takes no arguments.
-### ble
+### `ble` command group
Handles a group of commands that are used to control the device Bluetooth LE
transport state. You must use this command together with one of the additional
subcommands listed below.
-#### help
+#### `help` subcommand
-Prints help information about `ble` commands group.
+Prints help information about the `ble` command group.
```shell
uart:~$ matter ble help
@@ -252,7 +262,7 @@ uart:~$ matter ble help
adv Enable or disable advertisement. Usage: ble adv
```
-#### adv start
+#### `adv start` subcommand
Enables Bluetooth LE advertising.
@@ -261,7 +271,7 @@ uart:~$ matter ble adv start
Starting BLE advertising
```
-#### adv stop
+#### `adv stop` subcommand
Disables Bluetooth LE advertising.
@@ -270,7 +280,7 @@ uart:~$ matter ble adv stop
Stopping BLE advertising
```
-#### adv status
+#### `adv status` subcommand
Prints the information about the current Bluetooth LE advertising status.
@@ -280,13 +290,13 @@ BLE advertising is disabled
```
-### nfc
+### `nfc` command group
Handles a group of commands that are used to control the device NFC tag
emulation state. You must use this command together with one of the additional
subcommands listed below.
-#### start
+#### `start` subcommand
Starts the NFC tag emulation.
@@ -295,7 +305,7 @@ uart:~$ matter nfc start
NFC tag emulation started
```
-#### stop
+#### `stop` subcommand
Stops the NFC tag emulation.
@@ -304,7 +314,7 @@ uart:~$ matter nfc stop
NFC tag emulation stopped
```
-#### state
+#### `state` subcommand
Prints the information about the NFC tag emulation status.
@@ -313,13 +323,13 @@ uart:~$ matter nfc state
NFC tag emulation is disabled
```
-### dns
+### `dns` command group
Handles a group of commands that are used to trigger performing DNS queries. You
must use this command together with one of the additional subcommands listed
below.
-#### browse
+#### `browse` subcommand
Browses for DNS services of `_matterc_udp` type and prints the received
response. Takes no argument.
@@ -339,13 +349,13 @@ DNS browse succeeded:
fd08:b65e:db8e:f9c7:2cc2:2043:1366:3b31
```
-#### resolve
+#### `resolve` subcommand
-Resolves the specified Matter node service given by the and
-.
+Resolves the specified Matter node service given by the _fabric-id_ and
+_node-id_.
```shell
-uart:~$ matter dns resolve
+uart:~$ matter dns resolve fabric-id node-id
Resolving ...
DNS resolve for 000000014A77CBB3-0000000000BC5C01 succeeded:
IP address: fd08:b65e:db8e:f9c7:8052:1a8e:4dd4:e1f3
diff --git a/docs/guides/nrfconnect_examples_configuration.md b/docs/guides/nrfconnect_examples_configuration.md
index 5a31f3357da74a..133c5114b7d227 100644
--- a/docs/guides/nrfconnect_examples_configuration.md
+++ b/docs/guides/nrfconnect_examples_configuration.md
@@ -1,7 +1,9 @@
# Configuring nRF Connect examples
The nRF Connect example applications all come with a default configuration for
-building. Check the information on this page if you want to modify the
+building.
+
+Check the information on this page if you want to modify the
application configuration or add new functionalities to build your own
application based on the provided example. This page also contains information
about the configuration structure, which can be useful to better understand the
@@ -11,22 +13,21 @@ building process.
## Configuring application
-Changing the default application configuration can be done either temporarily or
-permanently. Changing configuration temporarily is useful for testing the impact
-of changes on the application behavior. Making permanent changes is better if
-you want to develop your own application, as it helps avoid repeating the
-configuration process.
+Changing the default application configuration can be done either temporarily or permanently.
-
+- Changing configuration temporarily is useful for testing the impact
+of changes on the application behavior.
+- Making permanent changes is better if you want to develop your own application, as it helps avoid repeating the configuration process.
+
+Regardless of the option, you will need to rebuild your application. This will require you to provide the build target name of the kit you are using. You can find the build target names in the Requirements section of the example you are building or on the [Board support](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/app_dev/board_support/index.html) page in the nRF Connect SDK documentation.
### Temporary changes to configuration
You can change the configuration temporarily by editing the `.config` file in
the `build/zephyr/` directory, which stores all configuration options for the
-application generated as a result of the build process. As long as you do not
-remove the current build directory or delete this file, your changes will be
-kept. However, if you do a clean build, your changes are gone, so it is not
-possible to save changes permanently this way.
+application generated as a result of the build process.
+
+As long as you do not remove the current build directory or delete this file, your changes will be kept. However, if you do a clean build, your changes are gone, so it is not possible to save changes permanently this way.
Complete the following steps:
@@ -34,21 +35,16 @@ Complete the following steps:
directory, with _build-target_ replaced with the build target name of the
kit, for example _nrf52840dk_nrf52840_:
- ```
- west build -b build-target
- ```
+ ```
+ west build -b build-target
+ ```
+2. Run the terminal-based interface called menuconfig by typing the following command:
-2. Run the terminal-based interface called menuconfig by typing the following
- command:
-
- ```
- west build -t menuconfig
- ```
-
- The menuconfig terminal window appears, in which you can navigate using
- arrow keys and other keys, based on the description at the bottom of the
- window.
+ ```
+ west build -t menuconfig
+ ```
+ The menuconfig terminal window appears, in which you can navigate using arrow keys and other keys, based on the description at the bottom of the window.
3. Make the desired changes by following the menuconfig terminal instructions.
4. Press `Q` to save and quit.
5. Rebuild the application.
@@ -56,27 +52,18 @@ Complete the following steps:
At this point, the configuration changes are applied to the output file and it
can be flashed to the device.
-
-
### Permanent changes to configuration
-The permanent solution is based on modifying the Kconfig configuration files,
-which are used as components of the building process. This makes the changes
-persistent across builds.
+The permanent solution is based on modifying the Kconfig configuration files, which are used as components of the building process. This makes the changes persistent across builds.
-The best practice to make permanent changes is to edit the main application
-configuration file `prj.conf`, which is located in the example directory. This
-will result in overriding the existing configuration values.
+The best practice to make permanent changes is to edit the main application configuration file `prj.conf`, which is located in the example directory. This will result in overriding the existing configuration values.
-This method is valid for the majority of cases. If you are interested in
-understanding the big picture of the configuration process, read the
-[Configuration structure overview](#configuration-structure-overview) section
+This method is valid for the majority of cases. If you are interested in understanding the big picture of the configuration process, read the [Configuration structure overview](#configuration-structure-overview) section
below.
#### Assigning values to Kconfig options
-Assigning value to a configuration option is done by typing its full name
-preceded by the `CONFIG_` prefix, and adding the `=` mark and the value.
+You can assigning a value to a configuration option by typing its full name preceded by the `CONFIG_` prefix, and adding the `=` mark and the value.
Configuration options have different types and it is only possible to assign
them values of proper type. Few examples:
@@ -97,9 +84,9 @@ that you rebuild your application after editing them by typing the following
command in the example directory, with _build-target_ replaced with the build
target name of the kit, for example _nrf52840dk_nrf52840_:
- ```
- west build -b build-target
- ```
+```
+west build -b build-target
+```
@@ -151,25 +138,26 @@ structure.
## Configuring Matter in nRF Connect platform
+When configuring Matter support using the nRF Connect platform, some configuration options are required, while other are optional and depend on what application behavior you want to achieve.
+
### Mandatory configuration
-To use the Matter protocol, you need to set the `CONFIG_CHIP` Kconfig option.
+To use the Matter protocol, complete the following steps:
+
+1. Set the `CONFIG_CHIP` Kconfig option.
Setting this option enables the Matter protocol stack and other associated
Kconfig options, including `CONFIG_CHIP_ENABLE_DNSSD_SRP` that is required for
the Matter device to be discoverable using DNS-SD.
-
-After that, make sure to set the `CONFIG_CHIP_PROJECT_CONFIG` Kconfig option and
+2. Set the `CONFIG_CHIP_PROJECT_CONFIG` Kconfig option and
define the path to the configuration file that specifies Vendor ID, Product ID,
and other project-specific Matter settings.
-
-
### Optional configuration
After enabling the Matter protocol and defining the path to the Matter
configuration file, you can enable additional options in Kconfig.
-**Sleepy End Device support**
+#### Sleepy End Device support
You can enable the support for Thread Sleepy End Device in Matter by setting the
following Kconfig options:
@@ -183,7 +171,7 @@ intervals:
- `CONFIG_CHIP_SED_IDLE_INTERVAL`
- `CONFIG_CHIP_SED_ACTIVE_INTERVAL`
-**Commissioning with NFC support**
+#### Commissioning with NFC support
You can configure the Matter protocol to use an NFC tag for commissioning,
instead of using a QR code, which is the default configuration.
@@ -191,7 +179,7 @@ instead of using a QR code, which is the default configuration.
To enable NFC for commissioning and share the onboarding payload in an NFC tag,
set the `CONFIG_CHIP_NFC_COMMISSIONING` option.
-**Factory reset behavior**
+#### Factory reset behavior
By default, the factory reset procedure implemented in the Matter stack removes
Matter-related settings only. If your application does not depend on any
@@ -200,7 +188,7 @@ device-lifelong data stored in the non-volatile storage, set the
the factory reset. This approach is more robust and regains the original NVS
performance in case it has been polluted with unwanted entries.
-**Logging**
+#### Logging
You can enable logging for both the stack and Zephyr’s
[Logging](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/zephyr/reference/logging/index.html#logging-api)
@@ -214,31 +202,30 @@ one of the available options:
- `CONFIG_MATTER_LOG_LEVEL_INFO`
- `CONFIG_MATTER_LOG_LEVEL_DBG`
-**Shell**
+#### Shell
You can enable the Matter shell library using the `CONFIG_CHIP_LIB_SHELL`
Kconfig option. This option lets you use the Matter specific shell commands. See
[Using CLI in nRF Connect examples](nrfconnect_examples_cli.md) for the list of
available Matter shell commands.
-**Matter device identification**
+#### Matter device identification
Matter has many mandatory and optional ways to identify a specific device. These
can be used for various purposes, such as dividing devices into groups (by
-function, by vendor or by location), device commissioning or vendor-specific
+function, by vendor, or by location), device commissioning or vendor-specific
cases before the device was commissioned (for example, identifying factory
software version or related features).
-Only some part of these features can be configured using Kconfig options and
-only those were listed below:
+Only some part of these features can be configured using Kconfig options:
-- `CONFIG_CHIP_DEVICE_TYPE` - type of device that uses the Matter Device Type
+- `CONFIG_CHIP_DEVICE_TYPE` - This option specifies the type of device that uses the Matter Device Type
Identifier, for example Door Lock (0x000A) or Dimmable Light Bulb (0x0101).
-- `CONFIG_CHIP_COMMISSIONABLE_DEVICE_TYPE` - enables including optional device
+- `CONFIG_CHIP_COMMISSIONABLE_DEVICE_TYPE` - This option enables including optional device
type subtype in the commissionable node discovery record, which allows
filtering of the discovery results to find the nodes that match the device
type.
-- `CONFIG_CHIP_ROTATING_DEVICE_ID` - enables rotating device identifier, an
+- `CONFIG_CHIP_ROTATING_DEVICE_ID` - This option enables the rotating device identifier, an
optional feature that provides an additional unique identifier for each
device. This identifier is similar to the serial number, but it additionally
changes at predefined times to protect against long-term tracking of the
diff --git a/docs/guides/nrfconnect_examples_software_update.md b/docs/guides/nrfconnect_examples_software_update.md
index fcd402cb96136f..d28f543cfeb0f8 100644
--- a/docs/guides/nrfconnect_examples_software_update.md
+++ b/docs/guides/nrfconnect_examples_software_update.md
@@ -6,11 +6,13 @@ protocols:
- Matter-compliant OTA update protocol that uses the Matter operational
network for querying and downloading a new firmware image.
-- [Simple Management Protocol](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/zephyr/guides/device_mgmt/index.html#device-mgmt)
+- [Simple Management Protocol](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/zephyr/services/device_mgmt/smp_protocol.html)
over Bluetooth LE. In this case, the DFU can be done either using a
smartphone application or a PC command line tool. Note that this protocol is
not part of the Matter specification.
+
+
## Device Firmware Upgrade over Matter
> **_NOTE:_** The procedure presented below requires that you have OpenThread
@@ -18,11 +20,14 @@ protocols:
> [Setup OpenThread Border Router on Raspberry Pi](openthread_border_router_pi.md)
> to learn how to install the OTBR on a Raspberry Pi.
-The DFU over Matter involves two kinds of nodes: OTA Provider and OTA Requestor.
-An OTA Provider is a node that can respond to the OTA Requestors' queries about
-available software updates and share the update packages with them. An OTA
-Requestor is any node that needs to be updated and can communicate with the OTA
-Provider to fetch applicable software updates. In the procedure described below,
+The DFU over Matter involves two kinds of nodes:
+
+- OTA Provider - This is a node that can respond to the OTA Requestors' queries about
+available software updates and share the update packages with them.
+- OTA Requestor - This is any node that needs to be updated and can communicate with the OTA
+Provider to fetch applicable software updates.
+
+In the procedure described below,
the OTA Provider will be a Linux application and the example running on the
Nordic Semiconductor's board will work as the OTA Requestor.
@@ -31,58 +36,59 @@ To test the DFU over Matter, you need to complete the following steps:
1. Navigate to the CHIP root directory.
2. Build the OTA Provider application for Linux:
- ```
- scripts/examples/gn_build_example.sh examples/ota-provider-app/linux out/provider chip_config_network_layer_ble=false
- ```
+ ```
+ scripts/examples/gn_build_example.sh examples/ota-provider-app/linux out/provider chip_config_network_layer_ble=false
+ ```
3. Build chip-tool for Linux:
- ```
- scripts/examples/gn_build_example.sh examples/chip-tool out/chiptool 'chip_mdns="platform"'
- ```
+ ```
+ scripts/examples/gn_build_example.sh examples/chip-tool out/chiptool 'chip_mdns="platform"'
+ ```
4. Run OTA Provider application with _matter.ota_ replaced with the path to the
Matter OTA image which you wish to provide to the Matter device. Note that
the Matter OTA image is, by default, generated at _zephyr/matter.ota_ in the
example's build directory:
- $ out/provider/chip-ota-provider-app -f matter.ota
+ ```
+ $ out/provider/chip-ota-provider-app -f matter.ota
+ ```
Keep the application running and use another terminal for the remaining
steps.
+5. Commission the OTA Provider into the Matter network using Node ID 1:
-5. Commission the OTA Provider into the Matter network using Node Id 1:
-
- ```
- ./out/chiptool/chip-tool pairing onnetwork 1 20202021
- ```
+ ```
+ ./out/chiptool/chip-tool pairing onnetwork 1 20202021
+ ```
6. Use the OTBR web interface to form a new Thread network using the default
network settings.
-7. Commission the Matter device into the same Matter network using Node Id 2.
+7. Commission the Matter device into the same Matter network using Node ID 2.
The parameter starting with the _hex:_ prefix is the Thread network's Active
Operational Dataset. It can be retrieved from the OTBR in case you have
changed the default network settings when forming the network.
- ```
- ./out/chiptool/chip-tool pairing ble-thread 2 hex:000300000f02081111111122222222051000112233445566778899aabbccddeeff01021234 20202021 3840
- ```
+ ```
+ ./out/chiptool/chip-tool pairing ble-thread 2 hex:000300000f02081111111122222222051000112233445566778899aabbccddeeff01021234 20202021 3840
+ ```
8. Configure the Matter device with the default OTA Provider by running the
- following command. The last two arguments are Requestor Node Id and
- Requestor Endpoint Id, respectively:
+ following command (the last two arguments are Requestor Node ID and
+ Requestor Endpoint ID, respectively):
- ```
- ./out/chiptool/chip-tool otasoftwareupdaterequestor write default-ota-providers '[{"fabricIndex": 1, "providerNodeID": 1, "endpoint": 0}]' 2 0
- ```
+ ```
+ ./out/chiptool/chip-tool otasoftwareupdaterequestor write default-ota-providers '[{"fabricIndex": 1, "providerNodeID": 1, "endpoint": 0}]' 2 0
+ ```
9. Configure the OTA Provider with the access control list (ACL) that grants
_Operate_ privileges to all nodes in the fabric. This is necessary to allow
the nodes to send cluster commands to the OTA Provider:
- ```
- ./out/chiptool/chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": null, "targets": null}]' 1 0
- ```
+ ```
+ ./out/chiptool/chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": null, "targets": null}]' 1 0
+ ```
10. Initiate the DFU procedure in one of the following ways:
@@ -91,53 +97,56 @@ To test the DFU over Matter, you need to complete the following steps:
option, which enables Matter shell commands, run the following command
on the device shell:
- ```
- matter ota query
- ```
+ ```
+ matter ota query
+ ```
- Otherwise, use chip-tool to send the Announce OTA Provider command to
- the device. The numeric arguments are Provider Node Id, Provider Vendor
- Id, Announcement Reason, Provider Endpoint Id, Requestor Node Id and
- Requestor Endpoint Id, respectively.
+ the device (the numeric arguments are Provider Node ID, Provider Vendor
+ ID, Announcement Reason, Provider Endpoint ID, Requestor Node ID and
+ Requestor Endpoint ID, respectively):
- ```
- ./out/chiptool/chip-tool otasoftwareupdaterequestor announce-ota-provider 1 0 0 0 2 0
- ```
+ ```
+ ./out/chiptool/chip-tool otasoftwareupdaterequestor announce-ota-provider 1 0 0 0 2 0
+ ```
Once the device is made aware of the OTA Provider node, it automatically
queries the OTA Provider for a new firmware image.
-11. When the firmware image download is complete, the device is automatically
- rebooted to apply the update.
+When the firmware image download is complete, the device is automatically rebooted to apply the update.
-## Device Firmware Upgrade over Bluetooth LE using smartphone
+
-To upgrade your device firmware over Bluetooth LE using smartphone, complete the
+## Device Firmware Upgrade over Bluetooth LE using a smartphone
+
+To upgrade your device firmware over Bluetooth LE using a smartphone, complete the
following steps:
-1. Install one of the following applications on your smartphone:
+1. Install _one_ of the following applications on your smartphone:
- [nRF Connect for Mobile](https://www.nordicsemi.com/Software-and-Tools/Development-Tools/nRF-Connect-for-mobile)
- [nRF Toolbox](https://www.nordicsemi.com/Software-and-Tools/Development-Tools/nRF-Toolbox)
2. Push the appropriate button on the device to enable the software update
functionality (if it is not enabled by default) and start the Bluetooth LE
- advertising of SMP service. See the user interface section in the example
+ advertising of the SMP service. See the user interface section in the example
documentation to check the button number.
3. Push the appropriate button on the device to start the Bluetooth LE
advertising. See the user interface section in the example documentation to
check the button number.
4. Follow the instructions about downloading the new image to a device on the
- [FOTA upgrades](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/ug_nrf52.html#fota-upgrades)
+ [FOTA upgrades](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/working_with_nrf/nrf52/developing.html#fota-updates)
page in the nRF Connect SDK documentation.
-## Device Firmware Upgrade over Bluetooth LE using PC command line tool
+
+
+## Device Firmware Upgrade over Bluetooth LE using a PC command line tool
To upgrade your device firmware over Bluetooth LE, you can use the PC command
line tool provided by the [mcumgr](https://github.com/zephyrproject-rtos/mcumgr)
project.
-> **_WARNING:_**
+> **_IMPORTANT:_**
>
> - The mcumgr tool using Bluetooth LE is available only for Linux and macOS
> systems. On Windows, there is no support for Device Firmware Upgrade over
@@ -170,9 +179,9 @@ Complete the following steps to perform DFU using mcumgr:
4. Upload the application firmware image to the device by running the following
command in your example directory:
- ```
- sudo mcumgr --conntype ble --hci ble-hci-number --connstring peer_name='ble-device-name' image upload build/zephyr/app_update.bin -n 0 -w 1
- ```
+ ```
+ sudo mcumgr --conntype ble --hci ble-hci-number --connstring peer_name='ble-device-name' image upload build/zephyr/app_update.bin -n 0 -w 1
+ ```
The operation can take a few minutes. Wait until the progress bar reaches
100%.
@@ -180,54 +189,54 @@ Complete the following steps to perform DFU using mcumgr:
5. Obtain the list of images present in the device memory by running following
command:
- ```
- sudo mcumgr --conntype ble --hci ble-hci-number --connstring peer_name='ble-device-name' image list
- ```
+ ```
+ sudo mcumgr --conntype ble --hci ble-hci-number --connstring peer_name='ble-device-name' image list
+ ```
The displayed output contains the old image in slot 0 that is currently
active and the new image in slot 1, which is not active yet (flags field
empty):
- ```
- Images:
- image=0 slot=0
- version: 0.0.0
- bootable: true
- flags: active confirmed
- hash: 7bb0e909a846e833465cbb44c581cf045413a5446c6953a30a3dcc2c3ad51764
- image=0 slot=1
- version: 0.0.0
- bootable: true
- flags:
- hash: cbd58fc3821e749d3abfb00b3069f98c078824735f1b2a333e8a1579971e7de1
- Split status: N/A (0)
- ```
+ ```
+ Images:
+ image=0 slot=0
+ version: 0.0.0
+ bootable: true
+ flags: active confirmed
+ hash: 7bb0e909a846e833465cbb44c581cf045413a5446c6953a30a3dcc2c3ad51764
+ image=0 slot=1
+ version: 0.0.0
+ bootable: true
+ flags:
+ hash: cbd58fc3821e749d3abfb00b3069f98c078824735f1b2a333e8a1579971e7de1
+ Split status: N/A (0)
+ ```
6. Swap the firmware images by calling the following method with `image-hash`
replaced by the image present in the slot 1 hash (for example,
`cbd58fc3821e749d3abfb00b3069f98c078824735f1b2a333e8a1579971e7de1`):
- ```
- sudo mcumgr --conntype ble --hci ble-hci-number --connstring peer_name='ble-device-name' image test image-hash
- ```
+ ```
+ sudo mcumgr --conntype ble --hci ble-hci-number --connstring peer_name='ble-device-name' image test image-hash
+ ```
You can observe that the `flags:` field in the image for slot 1 changes
value to `pending`:
- ```
- Images:
- image=0 slot=0
- version: 0.0.0
- bootable: true
- flags: active confirmed
- hash: 7bb0e909a846e833465cbb44c581cf045413a5446c6953a30a3dcc2c3ad51764
- image=0 slot=1
- version: 0.0.0
- bootable: true
- flags: pending
- hash: cbd58fc3821e749d3abfb00b3069f98c078824735f1b2a333e8a1579971e7de1
- Split status: N/A (0)
- ```
+ ```
+ Images:
+ image=0 slot=0
+ version: 0.0.0
+ bootable: true
+ flags: active confirmed
+ hash: 7bb0e909a846e833465cbb44c581cf045413a5446c6953a30a3dcc2c3ad51764
+ image=0 slot=1
+ version: 0.0.0
+ bootable: true
+ flags: pending
+ hash: cbd58fc3821e749d3abfb00b3069f98c078824735f1b2a333e8a1579971e7de1
+ Split status: N/A (0)
+ ```
7. If you are using the nRF5340DK board, which supports multi-image device
firmware upgrade, complete the following substeps. If you are not using one,
@@ -236,9 +245,9 @@ Complete the following steps to perform DFU using mcumgr:
a. Upload the network core firmware image to the device by running the
following command in your example directory:
- ```
- sudo mcumgr --conntype ble --hci ble-hci-number --connstring peer_name='ble-device-name' image upload build/zephyr/net_core_app_update.bin -n 1 -w 1
- ```
+ ```
+ sudo mcumgr --conntype ble --hci ble-hci-number --connstring peer_name='ble-device-name' image upload build/zephyr/net_core_app_update.bin -n 1 -w 1
+ ```
The operation can take a few minutes. Wait until the progress bar reaches
100%.
@@ -246,83 +255,83 @@ Complete the following steps to perform DFU using mcumgr:
b. Obtain the list of images present in the device memory by running
following command:
- ```
- sudo mcumgr --conntype ble --hci ble-hci-number --connstring peer_name='ble-device-name' image list
- ```
+ ```
+ sudo mcumgr --conntype ble --hci ble-hci-number --connstring peer_name='ble-device-name' image list
+ ```
The displayed output contains the old application image in slot 0 that is
currently active, the new application image in slot 1 in pending state, and
the new network image which is in slot 1 and not active yet (flags field
empty):
- ```
- Images:
- image=0 slot=0
- version: 0.0.0
- bootable: true
- flags: active confirmed
- hash: 7bb0e909a846e833465cbb44c581cf045413a5446c6953a30a3dcc2c3ad51764
- image=0 slot=1
- version: 0.0.0
- bootable: true
- flags: pending
- hash: cbd58fc3821e749d3abfb00b3069f98c078824735f1b2a333e8a1579971e7de1
- image=1 slot=1
- version: 0.0.0
- bootable: true
- flags:
- hash: d9e31e73cb7a959c26411250c2b3028f3510ae88a4549ae3f2f097c3e7530f48
- Split status: N/A (0)
- ```
+ ```
+ Images:
+ image=0 slot=0
+ version: 0.0.0
+ bootable: true
+ flags: active confirmed
+ hash: 7bb0e909a846e833465cbb44c581cf045413a5446c6953a30a3dcc2c3ad51764
+ image=0 slot=1
+ version: 0.0.0
+ bootable: true
+ flags: pending
+ hash: cbd58fc3821e749d3abfb00b3069f98c078824735f1b2a333e8a1579971e7de1
+ image=1 slot=1
+ version: 0.0.0
+ bootable: true
+ flags:
+ hash: d9e31e73cb7a959c26411250c2b3028f3510ae88a4549ae3f2f097c3e7530f48
+ Split status: N/A (0)
+ ```
c. Swap the firmware images by calling the following method with
`image-hash` replaced by the image present in the slot 1 hash (for example,
`d9e31e73cb7a959c26411250c2b3028f3510ae88a4549ae3f2f097c3e7530f48`):
- ```
- sudo mcumgr --conntype ble --hci ble-hci-number --connstring peer_name='ble-device-name' image test image-hash
- ```
+ ```
+ sudo mcumgr --conntype ble --hci ble-hci-number --connstring peer_name='ble-device-name' image test image-hash
+ ```
You can observe that the `flags:` field in the image for slot 1 changes
value to `pending`:
- ```
- Images:
- image=0 slot=0
- version: 0.0.0
- bootable: true
- flags: active confirmed
- hash: 7bb0e909a846e833465cbb44c581cf045413a5446c6953a30a3dcc2c3ad51764
- image=0 slot=1
- version: 0.0.0
- bootable: true
- flags: pending
- hash: cbd58fc3821e749d3abfb00b3069f98c078824735f1b2a333e8a1579971e7de1
- image=1 slot=1
- version: 0.0.0
- bootable: true
- flags: pending
- hash: d9e31e73cb7a959c26411250c2b3028f3510ae88a4549ae3f2f097c3e7530f48
- Split status: N/A (0)
- ```
+ ```
+ Images:
+ image=0 slot=0
+ version: 0.0.0
+ bootable: true
+ flags: active confirmed
+ hash: 7bb0e909a846e833465cbb44c581cf045413a5446c6953a30a3dcc2c3ad51764
+ image=0 slot=1
+ version: 0.0.0
+ bootable: true
+ flags: pending
+ hash: cbd58fc3821e749d3abfb00b3069f98c078824735f1b2a333e8a1579971e7de1
+ image=1 slot=1
+ version: 0.0.0
+ bootable: true
+ flags: pending
+ hash: d9e31e73cb7a959c26411250c2b3028f3510ae88a4549ae3f2f097c3e7530f48
+ Split status: N/A (0)
+ ```
8. Reset the device with the following command to let the bootloader swap
images:
- ```
- sudo mcumgr --conntype ble --hci ble-hci-number --connstring peer_name='ble-device-name' reset
- ```
+ ```
+ sudo mcumgr --conntype ble --hci ble-hci-number --connstring peer_name='ble-device-name' reset
+ ```
The device is reset and the following notifications appear in its console:
- ```
- *** Booting Zephyr OS build zephyr-v2.5.0-1101-ga9d3aef65424 ***
- I: Starting bootloader
- I: Primary image: magic=good, swap_type=0x2, copy_done=0x1, image_ok=0x1
- I: Secondary image: magic=good, swap_type=0x2, copy_done=0x3, image_ok=0x3
- I: Boot source: none
- I: Swap type: test
- ```
+```
+*** Booting Zephyr OS build zephyr-v2.5.0-1101-ga9d3aef65424 ***
+I: Starting bootloader
+I: Primary image: magic=good, swap_type=0x2, copy_done=0x1, image_ok=0x1
+I: Secondary image: magic=good, swap_type=0x2, copy_done=0x3, image_ok=0x3
+I: Boot source: none
+I: Swap type: test
+```
Swapping operation can take some time, and after it completes, the new firmware
is booted.
diff --git a/docs/guides/nrfconnect_factory_data_configuration.md b/docs/guides/nrfconnect_factory_data_configuration.md
index ef3c14b6801a20..2a502f7b664451 100644
--- a/docs/guides/nrfconnect_factory_data_configuration.md
+++ b/docs/guides/nrfconnect_factory_data_configuration.md
@@ -22,23 +22,20 @@ For the nRF Connect platform, the factory data is stored by default in a
separate partition of the internal flash memory. This helps to keep the factory
data secure by applying hardware write protection.
-> Note: Due to hardware limitations, in the nRF Connect platform, protection
+> **Note:** Due to hardware limitations, in the nRF Connect platform, protection
> against writing can be applied only to the internal memory partition. The
> [Fprotect](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/libraries/others/fprotect.html)
> is the hardware flash protection driver, and we used it to ensure write
> protection of the factory data partition in internal flash memory.
-
-
-
- [Overview](#overview)
- - [Factory data components](#factory-data-component-table)
+ - [Factory data component table](#factory-data-component-table)
- [Factory data format](#factory-data-format)
- [Enabling factory data support](#enabling-factory-data-support)
- [Generating factory data](#generating-factory-data)
- - [Creating factory data JSON file with the first script](#creating-factory-data-json-file-with-the-first-script)
+ - [Creating the factory data JSON file with the first script](#creating-the-factory-data-json-file-with-the-first-script)
- [How to set user data](#how-to-set-user-data)
- [How to handle user data](#how-to-handle-user-data)
- [Verifying using the JSON Schema tool](#verifying-using-the-json-schema-tool)
@@ -46,7 +43,7 @@ data secure by applying hardware write protection.
- [Option 2: Using a website validator](#option-2-using-a-website-validator)
- [Option 3: Using the nRF Connect Python script](#option-3-using-the-nrf-connect-python-script)
- [Preparing factory data partition on a device](#preparing-factory-data-partition-on-a-device)
- - [Creating the factory data partition with the second script](#creating-a-factory-data-partition-with-the-second-script)
+ - [Creating a factory data partition with the second script](#creating-a-factory-data-partition-with-the-second-script)
- [Building an example with factory data](#building-an-example-with-factory-data)
- [Providing factory data parameters as a build argument list](#providing-factory-data-parameters-as-a-build-argument-list)
- [Setting factory data parameters using interactive Kconfig interfaces](#setting-factory-data-parameters-using-interactive-kconfig-interfaces)
@@ -81,7 +78,7 @@ For more information about preparing a factory data accessor, see the section
about
[using own factory data implementation](#using-own-factory-data-implementation).
-> Note: Encryption and security of the factory data partition is not provided
+> **Note:** Encryption and security of the factory data partition is not provided
> yet for this feature.
### Factory data component table
@@ -181,10 +178,9 @@ partition into the device's flash memory.
You can use the second script without invoking the first one by providing a JSON
file written in another way. To make sure that the JSON file is correct and the
-device is able to read out parameters, verify the file using the
-[JSON schema](#verifying-using-the-json-schema-tool).
+device is able to read out parameters, [verify the file using the JSON schema tool](#verifying-using-the-json-schema-tool).
-### Creating factory data JSON file with the first script
+### Creating the factory data JSON file with the first script
A Matter device needs a proper factory data partition stored in the flash memory
to read out all required parameters during startup. To simplify the factory data
@@ -199,9 +195,9 @@ To use this script, complete the following steps:
2. Run the script with `-h` option to see all possible options:
-```
-$ python scripts/tools/nrfconnect/generate_nrfconnect_chip_factory_data.py -h
-```
+ ```
+ $ python scripts/tools/nrfconnect/generate_nrfconnect_chip_factory_data.py -h
+ ```
3. Prepare a list of arguments:
@@ -237,18 +233,18 @@ $ python scripts/tools/nrfconnect/generate_nrfconnect_chip_factory_data.py -h
- Automatic:
- ```
- --chip_cert_path
- ```
+ ```
+ --chip_cert_path
+ ```
- > Note: To generate new certificates, you need the `chip-cert` executable.
+ > **Note:** To generate new certificates, you need the `chip-cert` executable.
> See the note at the end of this section to learn how to get it.
- Manual:
- ```
- --dac_cert .der --dac_key .der --pai_cert .der
- ```
+ ```
+ --dac_cert .der --dac_key .der --pai_cert .der
+ ```
e. (optional) Add the new unique ID for rotating device ID using one of the
following options:
@@ -289,9 +285,9 @@ $ python scripts/tools/nrfconnect/generate_nrfconnect_chip_factory_data.py -h
4. Run the script using the prepared list of arguments:
-```
-$ python generate_nrfconnect_chip_factory_data.py
-```
+ ```
+ $ python generate_nrfconnect_chip_factory_data.py
+ ```
For example, a final invocation of the Python script can look similar to the
following one:
@@ -324,9 +320,9 @@ JSON file is verified using the prepared JSON Schema.
If the script finishes successfully, go to the location you provided with the
`-o` argument. Use the JSON file you find there when
-[generating the factory data partition](#generating-factory-data).
+[generating factory data](#generating-factory-data).
-> Note: Generating new certificates is optional if default vendor and product
+> **Note:** Generating new certificates is optional if default vendor and product
> IDs are used and requires providing a path to the `chip-cert` executable. To
> get it, complete the following steps:
>
@@ -337,7 +333,7 @@ If the script finishes successfully, go to the location you provided with the
> 3. Add the `connectedhomeip/src/tools/chip-cert/out/chip-cert` path as an
> argument of `--chip_cert_path` for the Python script.
-> Note: By default, overwriting the existing JSON file is disabled. This means
+> **Note:** By default, overwriting the existing JSON file is disabled. This means
> that you cannot create a new JSON file with the same name in the exact
> location as an existing file. To allow overwriting, add the `--overwrite`
> option to the argument list of the Python script.
@@ -407,23 +403,23 @@ cast the result to your own purpose.
The code example of how to read all fields from the JSON example one by one can
look like follows:
- ```
- chip::DeviceLayer::FactoryDataProvider factoryDataProvider;
+```
+chip::DeviceLayer::FactoryDataProvider factoryDataProvider;
- factoryDataProvider.Init();
+factoryDataProvider.Init();
- uint8_t user_name[12];
- size_t name_len = sizeof(user_name);
- factoryDataProvider.GetUserKey("name", user_name, name_len);
+uint8_t user_name[12];
+size_t name_len = sizeof(user_name);
+factoryDataProvider.GetUserKey("name", user_name, name_len);
- int32_t version;
- size_t version_len = sizeof(version);
- factoryDataProvider.GetUserKey("version", &version, version_len);
+int32_t version;
+size_t version_len = sizeof(version);
+factoryDataProvider.GetUserKey("version", &version, version_len);
- uint8_t revision[5];
- size_t revision_len = sizeof(revision);
- factoryDataProvider.GetUserKey("revision", revision, revision_len);
- ```
+uint8_t revision[5];
+size_t revision_len = sizeof(revision);
+factoryDataProvider.GetUserKey("revision", revision, revision_len);
+```
### Verifying using the JSON Schema tool
@@ -439,17 +435,17 @@ machine, complete the following steps:
1. Install the `php-json-schema` package:
-```
-$ sudo apt install php-json-schema
-```
+ ```
+ $ sudo apt install php-json-schema
+ ```
2. Run the following command, with __ and
__ replaced with the paths to the JSON file and the
Schema file, respectively:
-```
-$ validate-json
-```
+ ```
+ $ validate-json
+ ```
The tool returns empty output in case of success.
@@ -488,11 +484,11 @@ as an additional argument. To do this, complete the following steps:
2. Run the following command (remember to replace the __
variable):
-```
-$ python generate_nrfconnect_chip_factory_data.py --schema
-```
+ ```
+ $ python generate_nrfconnect_chip_factory_data.py --schema
+ ```
-> Note: To learn more about the JSON schema, visit
+> **Note:** To learn more about the JSON schema, visit
> [this unofficial JSON Schema tool usage website](https://json-schema.org/understanding-json-schema/).
### Preparing factory data partition on a device
@@ -585,22 +581,22 @@ to generate the factory data partition:
1. Navigate to the _connectedhomeip_ root directory
2. Run the following command pattern:
-```
-$ python scripts/tools/nrfconnect/nrfconnect_generate_partition.py -i -o --offset --size
-```
+ ```
+ $ python scripts/tools/nrfconnect/nrfconnect_generate_partition.py -i -o --offset --size
+ ```
-In this command:
+ In this command:
-- __ is a path to the JSON file containing appropriate
- factory data.
-- __ is a path to an output file without any prefix. For
- example, providing `/build/output` as an argument will result in creating
- `/build/output.hex` and `/build/output.bin`.
-- __ is an address in the device's persistent
- storage area where a partition data set is to be stored.
-- __ is a size of partition in the device's persistent storage
- area. New data is checked according to this value of the JSON data to see if
- it fits the size.
+ - __ is a path to the JSON file containing appropriate
+ factory data.
+ - __ is a path to an output file without any prefix. For
+ example, providing `/build/output` as an argument will result in creating
+ `/build/output.hex` and `/build/output.bin`.
+ - __ is an address in the device's persistent
+ storage area where a partition data set is to be stored.
+ - __ is a size of partition in the device's persistent storage
+ area. New data is checked according to this value of the JSON data to see if
+ it fits the size.
To see the optional arguments for the script, use the following command:
@@ -694,7 +690,7 @@ snippet:
(91a9c12a7c80700a31ddcfa7fce63e44) A rotating device id unique i
```
-> Note: To get more information about how to use the interactive Kconfig
+> **Note:** To get more information about how to use the interactive Kconfig
> interfaces, read the
> [Kconfig docummentation](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/zephyr/build/kconfig/menuconfig.html).
@@ -766,8 +762,8 @@ $ west flash
## Using own factory data implementation
The [factory data generation process](#generating-factory-data) described above
-is only an example valid for the nRF Connect platform. You can well create a HEX
-file containing all [factory data components](#factory-data-component-table) in
+is only an example valid for the nRF Connect platform. You can also create a HEX
+file containing all components from the [factory data component table](#factory-data-component-table) in
any format and then implement a parser to read out all parameters and pass them
to a provider. Each manufacturer can implement a factory data set on its own by
implementing a parser and a factory data accessor inside the Matter stack. Use
@@ -780,7 +776,7 @@ ways, depending on the purpose and the format. In the nRF Connect example, the
factory data is stored in the CBOR format. The device uses the
[Factory Data Parser](../../src/platform/nrfconnect/FactoryDataParser.h) to read
out raw data, decode it, and store it in the `FactoryData` structure. The
-[Factor Data Provider](../../src/platform/nrfconnect/FactoryDataProvider.c)
+[Factor Data Provider](../../src/platform/nrfconnect/FactoryDataProvider.cpp)
implementation uses this parser to get all needed factory data parameters and
provide them to the Matter core.
@@ -794,7 +790,7 @@ override the inherited classes, complete the following steps:
1. Override the following methods:
-```
+ ```
// ===== Members functions that implement the DeviceAttestationCredentialsProvider
CHIP_ERROR GetCertificationDeclaration(MutableByteSpan & outBuffer) override;
CHIP_ERROR GetFirmwareInformation(MutableByteSpan & out_firmware_info_buffer) override;
@@ -821,7 +817,7 @@ override the inherited classes, complete the following steps:
CHIP_ERROR GetHardwareVersion(uint16_t & hardwareVersion) override;
CHIP_ERROR GetHardwareVersionString(char * buf, size_t bufSize) override;
CHIP_ERROR GetRotatingDeviceIdUniqueId(MutableByteSpan & uniqueIdSpan) override;
-```
+ ```
2. Move the newly created parser and provider files to your project directory.
3. Add the files to the `CMakeList.txt` file.
@@ -829,11 +825,11 @@ override the inherited classes, complete the following steps:
factory data providers to start using your own implementation of factory data
parser and provider. This can be done in one of the following ways:
-- Add `CONFIG_FACTORY_DATA_CUSTOM_BACKEND=y` Kconfig setting to `prj.conf`
- file.
-- Build an example with following option (replace __ with your
- board name, for example `nrf52840dk_nrf52840`):
+ - Add `CONFIG_FACTORY_DATA_CUSTOM_BACKEND=y` Kconfig setting to `prj.conf`
+ file.
+ - Build an example with following option (replace __ with your
+ board name, for example `nrf52840dk_nrf52840`):
-```
- $ west build -b -- -DCONFIG_FACTORY_DATA_CUSTOM_BACKEND=y
-```
+ ```
+ $ west build -b -- -DCONFIG_FACTORY_DATA_CUSTOM_BACKEND=y
+ ```
\ No newline at end of file
diff --git a/docs/guides/nrfconnect_platform_overview.md b/docs/guides/nrfconnect_platform_overview.md
index 626c2d746b2056..18e7047c7eb6d6 100644
--- a/docs/guides/nrfconnect_platform_overview.md
+++ b/docs/guides/nrfconnect_platform_overview.md
@@ -5,10 +5,10 @@ The nRF Connect platform is a
Nordic Semiconductor's nRF Connect SDK.
The following diagram shows a simplified structure of a Matter application that
-runs on the nRF Connect platform and uses BLE and Thread stacks for
+runs on the nRF Connect platform and uses Bluetooth® LE and Thread stacks for
communication purposes:
-
+
> **Note**: For readability, the diagram does not show all projects components,
> only the most important ones for a typical Matter application.
@@ -23,13 +23,14 @@ allows to build a range of applications, including cellular IoT (LTE-M and
NB-IoT), Bluetooth Low Energy, Thread, Zigbee, and Bluetooth mesh. The SDK
contains samples, libraries and a full set of drivers for Nordic Semiconductor's
[nRF9160](https://www.nordicsemi.com/Products/Low-power-cellular-IoT/nRF9160),
+[nRF7002](https://www.nordicsemi.com/Products/nRF7002),
[nRF5340](https://www.nordicsemi.com/Software-and-tools/Development-Kits/nRF5340-PDK),
and
[nRF52 Series](https://www.nordicsemi.com/Products/Low-power-short-range-wireless)
devices.
The nRF Connect SDK is based around [Zephyr RTOS](https://zephyrproject.org/),
-which is a scalable real-time operating system dedicated for the connected,
+which is a scalable Real-Time Operating System dedicated for the connected,
resource-constrained devices. Zephyr supports multiple hardware platforms and
provides hardware drivers, application protocols, protocol stacks, and more.
Besides Zephyr, the nRF Connect SDK also integrates other projects like crypto
@@ -38,18 +39,29 @@ implementation of the Thread stack.
-## Bluetooth LE and Thread stacks
+## Bluetooth LE stack
In the nRF Connect platform applications, the Bluetooth LE interface is used to
-perform pairing and Thread network provisioning operations between the Matter
+perform pairing and Thread or Wi-Fi network provisioning operations between the Matter
device and the Matter controller. Afterwards, the fully provisioned device is
-able to communicate with other devices inside the Thread network.
+able to communicate with other devices inside the Thread or Wi-Fi network.
For the Bluetooth LE communication purposes, the nRF Connect platform
application is using the Bluetooth LE stack, in which the Bluetooth LE Host part
-is provided by the Zephyr RTOS and the
-[SoftDevice Controller](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrfxlib/softdevice_controller/README.html)
-is implemented in the nRF Connect SDK's driver.
+is provided by the Zephyr RTOS and the SoftDevice Controller is implemented
+in the nRF Connect SDK's driver.
+
+The nRF Connect SDK's Multiprotocol Service Layer (MPSL) driver allows running
+Bluetooth LE concurrently with other stacks on the same radio chip.
+
+Read more in the nRF Connect SDK documentation:
+
+- [SoftDevice Controller](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrfxlib/softdevice_controller/README.html)
+- [Multiprotocol Service Layer](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrfxlib/mpsl/README.html)
+
+
+
+## Thread stack
For the Thread communication purposes, the nRF Connect platform application is
using the Thread stack, which consists of several layers implemented in
@@ -57,15 +69,24 @@ different projects. The core of the Thread stack is OpenThread, but it also
requires the IEEE 802.15.4 radio driver provided by the nRF Connect SDK and the
network layer functionalities provided by the Zephyr.
-The nRF Connect SDK's Multiprotocol Service Layer (MPSL) driver allows running
-Bluetooth LE and Thread concurrently on the same radio chip.
+Read more in the nRF Connect SDK documentation:
+
+- [Multiprotocol Service Layer](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrfxlib/mpsl/README.html)
+- [nRF 802.15.4 Radio Driver](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrfxlib/nrf_802154/README.html)
+- [OpenThread integration](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/protocols/thread/overview/ot_integration.html)
+
+
+
+## Wi-Fi stack
+
+For the Wi-Fi communication purposes, the nRF Connect platform applications are using the [Zephyr port of Host AP and WPA Supplicant](https://github.com/nrfconnect/sdk-hostap/) and the [Wi-Fi driver from the nRF Connect SDK](https://github.com/nrfconnect/sdk-nrf/tree/main/drivers/wifi/nrf700x) that implements the communication between the host MCU and the nRF7002 companion integrated circuit over SPI or QSPI bus. The nRF7002 companion integrated circuit is compliant with IEEE 802.11ax (Wi-Fi 6).
## Matter integration
Matter is located on the top application layer of the presented model, looking
-from the networking point of view. The Bluetooth LE and Thread stacks provided
+from the networking point of view. The Bluetooth LE and Thread or Wi-Fi stacks provided
by the nRF Connect SDK and Zephyr must be integrated with the Matter stack using
a special intermediate layer.
@@ -75,6 +96,8 @@ defined in the Matter stack. The application is able to use Matter's platform
agnostic interfaces and no additional platform-related actions are needed to
perform communication through the Matter stack.
+For more information, see the [Matter integration in the nRF Connect SDK](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/protocols/matter/overview/integration.html) page in the SDK documentation.
+
## Build system
@@ -90,3 +113,5 @@ As a result, Matter's stack and platform modules are built with GN (see the
overview diagram) and the output is used to generate the library file. The
application, nRF Connect SDK, and Zephyr are built with CMake and the Matter
library file is imported during the compilation process.
+
+For more information about the build system in Zephyr and the nRF Connect SDK, see the [Build and configuration system](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/app_dev/build_and_config_system/index.html) page in the SDK documentation.
-
-