From e011c7e9824b268fbf5e7f4c0e9a6f2795f44291 Mon Sep 17 00:00:00 2001 From: "Restyled.io" Date: Tue, 7 Mar 2023 15:45:27 +0000 Subject: [PATCH] Restyled by prettier-markdown --- docs/guides/BUILDING.md | 121 +++++++++-------- docs/guides/access-control-guide.md | 122 +++++++++++------- docs/guides/chip_tool_guide.md | 8 +- docs/guides/nrfconnect_examples_cli.md | 4 +- .../nrfconnect_examples_configuration.md | 96 ++++++++------ .../nrfconnect_examples_software_update.md | 23 ++-- .../nrfconnect_factory_data_configuration.md | 65 +++++----- docs/guides/nrfconnect_platform_overview.md | 45 ++++--- 8 files changed, 284 insertions(+), 200 deletions(-) diff --git a/docs/guides/BUILDING.md b/docs/guides/BUILDING.md index 4fedf6c0df3355..78ad0ecd0d6e0a 100644 --- a/docs/guides/BUILDING.md +++ b/docs/guides/BUILDING.md @@ -33,7 +33,8 @@ git clone --recurse-submodules git@github.com:project-chip/connectedhomeip.git ## Synchronizing submodules -If you already have the Matter code checked out, run the following command to synchronize submodules: +If you already have the Matter code checked out, run the following command to +synchronize submodules: ``` git submodule update --init @@ -63,12 +64,11 @@ On macOS, install Xcode from the Mac App Store. Complete the following steps: 1. Using `rpi-imager`, install the Ubuntu _22.04_ 64-bit _server_ OS for arm64 -architectures on a micro SD card. + architectures on a micro SD card. 1. Boot the SD card. -1. Log in with the default user account "ubuntu" and password -"ubuntu" +1. Log in with the default user account "ubuntu" and password "ubuntu" 1. Proceed with -[Installing prerequisites on Linux](#installing-prerequisites-on-linux). + [Installing prerequisites on Linux](#installing-prerequisites-on-linux). 1. Install some Raspberry Pi specific dependencies: ``` @@ -90,7 +90,8 @@ permanently, you need to make the following changes: sudo nano /etc/systemd/system/dbus-fi.w1.wpa_supplicant1.service ``` -1. Run the following command to change the wpa_supplicant start parameters to the provided values: +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 @@ -113,9 +114,10 @@ permanently, you need to make the following changes: ## Installing ZAP tool -`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. +`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. ### Linux ARM @@ -148,12 +150,14 @@ 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. + - Use this if you are developing ZAP locally and would like to run ZAP + with your changes. - `$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`. + - 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`. @@ -172,8 +176,8 @@ source scripts/activate.sh ### Updating the environment -If the script says the environment is out of date, you can update it by -running the following command: +If the script says the environment is out of date, you can update it by running +the following command: ``` source scripts/bootstrap.sh @@ -184,7 +188,8 @@ is expensive, so avoid running it unless the environment is out of date. ## Build for the host OS (Linux or macOS) -Run the following commands to 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 @@ -194,7 +199,8 @@ gn gen out/host ninja -C out/host ``` -These commands generate 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' @@ -202,11 +208,11 @@ gn gen out/host --args='is_debug=false' ninja -C out/host ``` -> **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`. +> **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 the following command: @@ -220,7 +226,8 @@ 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:** The build system caches passing tests, so you may see the following message: +> **Note:** The build system caches passing tests, so you may see the following +> message: > > ``` > ninja: no work to do @@ -230,13 +237,15 @@ ninja -C out/host src/inet/tests:tests_run ## Build custom configuration -The build is configured by setting build arguments. These you can set in one of the following manners: +The build is configured by setting build arguments. These you can set in one of +the following manners: -- Passing the `--args` option to `gn gen`. -- Running `gn args` on the output directory. -- Editing `args.gn` in the output directory. +- Passing the `--args` option to `gn gen`. +- Running `gn args` on the output directory. +- Editing `args.gn` in the output directory. -To configure a new build or edit the arguments to existing build, run the following command: +To configure a new build or edit the arguments to existing build, run the +following command: ``` source scripts/activate.sh @@ -262,7 +271,9 @@ You can build examples in two ways. ### 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`): +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 @@ -272,12 +283,13 @@ ninja -C out/debug ### 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. +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, run the following commands: +To build a unified configuration that approximates the set of continuous builds, +run the following commands: ``` source scripts/activate.sh @@ -287,7 +299,10 @@ gn gen out/unified --args='is_debug=true target_os="all"' ninja -C out/unified all ``` -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. +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 expensive to build everything for every edit. To save time, you can name the @@ -301,8 +316,7 @@ 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 with arguments. -For example: +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' @@ -318,10 +332,10 @@ 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 +> **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: > @@ -331,7 +345,7 @@ gn desc out/unified '//src/controller(//build/toolchain/host:linux_x64_clang)' ## Getting help -GN has integrated help that you can access with the ``gn help`` command. +GN has integrated help that you can access with the `gn help` command. Make sure to check the following recommended topics: @@ -349,43 +363,43 @@ Also see the GN has various introspection tools to help you examine the build configuration. The following examples use the `out/host` output directory as example: -- Show all of the targets in an output directory: +- Show all of the targets in an output directory: ``` gn ls out/host ``` -- Show all of the files that will be built: +- Show all of the files that will be built: ``` gn outputs out/host '*' ``` -- Show the GN representation of a configured target: +- Show the GN representation of a configured target: ``` gn desc out/host //src/inet --all ``` -- 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 ``` -- Show the dependency tree: +- Show the dependency tree: ``` gn desc out/host //:all deps --tree --all ``` -- Find dependency paths: +- Find dependency paths: ``` gn path out/host //src/transport/tests:tests //src/system ``` -- List useful information for linking against `libCHIP`: +- List useful information for linking against `libCHIP`: ``` gn desc out/host //src/lib include_dirs @@ -398,10 +412,10 @@ The following examples use the `out/host` output directory as example: ## Coverage -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. +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: @@ -409,8 +423,10 @@ Run the following command to initiate the script: ./scripts/build_coverage.sh ``` -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: +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. @@ -429,4 +445,5 @@ Also, see the up-to-date unit testing coverage report of the Matter SDK ## 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 38314ed5a289f5..6aa20e032825d5 100644 --- a/docs/guides/access-control-guide.md +++ b/docs/guides/access-control-guide.md @@ -1,12 +1,19 @@ # Access Control Guide -All Interaction Model operations in Matter must be verified by the the Access Control mechanism. +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. +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`). +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. +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.
@@ -34,7 +41,8 @@ group messaging. ## Access Control Lists -Access Control Lists (ACLs) are fabric-scoped data structures with the following fields: +Access Control Lists (ACLs) are fabric-scoped data structures with the following +fields: - `Privilege` - `AuthMode` @@ -50,14 +58,15 @@ The `Privilege` can be of the following types: - Manage - Administer -> **Note:** 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. -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. +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. 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 @@ -74,7 +83,8 @@ The ACL applies only to subjects using that authentication mode. ### Subjects field -The `Subjects` field 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 `AuthMode` - Group ID for Group `AuthMode` @@ -86,7 +96,8 @@ applies to any subjects using the authentication mode. ### Targets field -The `Targets` field 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 @@ -96,12 +107,13 @@ 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. -- If device type is present, the ACL is targeted to just endpoints which contain -that device type (as reported by the Descriptor Cluster). +- 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). -> **Note:** 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. @@ -192,15 +204,16 @@ cluster on endpoint 2. ### Usage -The following sections describe the requirements for managing ACLs using the CHIP-Tool. +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. -> **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. +> **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. The write operation may employ multiple messages, making it unreliable. In any case, ACLs are updated as they are processed, and take effect immediately. @@ -231,41 +244,44 @@ When reading ACLs, the proper fabric index is shown. The tool requires numerical values for enums and identifiers. -- Privilege values: +- Privilege values: - - View: 1 - - Operate: 3 - - Manage: 4 - - Administer: 5 + - View: 1 + - Operate: 3 + - Manage: 4 + - Administer: 5 -- AuthMode values: +- AuthMode values: - - CASE: 2 - - Group: 3 + - CASE: 2 + - Group: 3 -- Values for 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 -This section provides examples of commands and ACL output for different operations with the CHIP-Tool. +This section provides examples of commands and ACL output for different +operations with the CHIP-Tool. #### 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: +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: +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 @@ -282,7 +298,8 @@ 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: +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 @@ -315,7 +332,8 @@ 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: +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 @@ -376,17 +394,22 @@ Endpoint: 0 Cluster: 0x0000_001F Attribute 0x0000_0000DataVersion: 2578401041 ### Usage -This section provides examples of commands and ACL output for different operations with the CHIP-repl. +This section provides examples of commands and ACL output for different +operations with the CHIP-repl. #### Entire List -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. +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. -This means that the following entry is acceptable: `Target(cluster=6, endpoint=Null, deviceType=Null)`. Just as the following one: `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. @@ -395,15 +418,15 @@ normally the case. The `ACL` attribute is fabric-scoped, so each ACL has a fabric index. -The CHIP-repl ignores it when performing the actual write. Because null fields can be -omitted, simply do not provide it when writing ACLs. +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 CHIP-repl accepts numerical values for enums and identifiers, but it also accepts -strongly typed values: +The CHIP-repl accepts numerical values for enums and identifiers, but it also +accepts strongly typed values: The privileges are: @@ -428,7 +451,8 @@ Some typical clusters: ### Examples -This section provides examples of commands and ACL output for different operations with the CHIP-repl. +This section provides examples of commands and ACL output for different +operations with the CHIP-repl. #### Automatically Installed ACL diff --git a/docs/guides/chip_tool_guide.md b/docs/guides/chip_tool_guide.md index 920f0a1e496a32..7989c5b927818f 100644 --- a/docs/guides/chip_tool_guide.md +++ b/docs/guides/chip_tool_guide.md @@ -164,8 +164,8 @@ I: 278 [DL] Manufacturing Date: (not set) I: 281 [DL] Device Type: 65535 (0xFFFF) ``` -In this printout, the _discriminator_ is `3840 (0xF00)` and the _setup PIN -code_ is equal to `20202021`. +In this printout, the _discriminator_ is `3840 (0xF00)` and the _setup PIN code_ +is equal to `20202021`. ### Step 6: Commission Matter device into an existing IP network @@ -190,8 +190,8 @@ following log: Secure Session to Device Established ``` -This log message means that the PASE (Password-Authenticated Session Establishment) -session using SPAKE2+ protocol has been established. +This log message means that the PASE (Password-Authenticated Session +Establishment) session using SPAKE2+ protocol has been established. ##### Commissioning into a Thread network over Bluetooth LE diff --git a/docs/guides/nrfconnect_examples_cli.md b/docs/guides/nrfconnect_examples_cli.md index 8ad154a355ca12..91b633287db737 100644 --- a/docs/guides/nrfconnect_examples_cli.md +++ b/docs/guides/nrfconnect_examples_cli.md @@ -80,8 +80,7 @@ available options for the given command. ## Using OpenThread commands [OpenThread commands](https://github.com/openthread/openthread/blob/master/src/cli/README.md) -are accessible from the shell, but they must preceded by `ot`. For -example: +are accessible from the shell, but they must preceded by `ot`. For example: ```shell uart:~$ ot masterkey @@ -142,6 +141,7 @@ QRCode: MT:W0GU2OTB00KA0648G00 QRCodeUrl: https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3AW0GU2OTB00KA0648G00 ManualPairingCode: 34970112332 ``` + #### `none qrcode` subcommand Prints the device diff --git a/docs/guides/nrfconnect_examples_configuration.md b/docs/guides/nrfconnect_examples_configuration.md index 133c5114b7d227..14170f46d480d0 100644 --- a/docs/guides/nrfconnect_examples_configuration.md +++ b/docs/guides/nrfconnect_examples_configuration.md @@ -3,23 +3,30 @@ 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 -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 -building process. +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 building +process.
## Configuring application -Changing the default application configuration can be done either temporarily or permanently. +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 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. +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 @@ -27,7 +34,9 @@ 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. +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: @@ -38,13 +47,18 @@ Complete the following steps: ``` 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. + 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. @@ -54,16 +68,23 @@ 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 -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. +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: @@ -138,19 +159,21 @@ 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. +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, 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. -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. +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. +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 @@ -219,14 +242,15 @@ software version or related features). Only some part of these features can be configured using Kconfig options: -- `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` - 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` - 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 - device. +- `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` - 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` - 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 device. diff --git a/docs/guides/nrfconnect_examples_software_update.md b/docs/guides/nrfconnect_examples_software_update.md index d28f543cfeb0f8..608c29f444fd70 100644 --- a/docs/guides/nrfconnect_examples_software_update.md +++ b/docs/guides/nrfconnect_examples_software_update.md @@ -22,14 +22,15 @@ protocols: 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. +- 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. +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. To test the DFU over Matter, you need to complete the following steps: @@ -57,6 +58,7 @@ To test the DFU over Matter, you need to complete the following steps: 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: ``` @@ -113,14 +115,15 @@ To test the DFU over Matter, you need to complete the following steps: Once the device is made aware of the OTA Provider node, it automatically queries the OTA Provider for a new firmware image. -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 a smartphone -To upgrade your device firmware over Bluetooth LE using a smartphone, complete the -following steps: +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: diff --git a/docs/guides/nrfconnect_factory_data_configuration.md b/docs/guides/nrfconnect_factory_data_configuration.md index 2a502f7b664451..5dd555a0256c35 100644 --- a/docs/guides/nrfconnect_factory_data_configuration.md +++ b/docs/guides/nrfconnect_factory_data_configuration.md @@ -78,8 +78,8 @@ 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 -> yet for this feature. +> **Note:** Encryption and security of the factory data partition is not +> provided yet for this feature. ### Factory data component table @@ -178,7 +178,8 @@ 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 tool](#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 the factory data JSON file with the first script @@ -237,8 +238,9 @@ To use this script, complete the following steps: --chip_cert_path ``` - > **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. + > **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: @@ -322,9 +324,9 @@ If the script finishes successfully, go to the location you provided with the `-o` argument. Use the JSON file you find there when [generating factory data](#generating-factory-data). -> **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: +> **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: > > 1. Navigate to the `connectedhomeip` root directory. > 2. In a terminal, run the command: @@ -333,8 +335,8 @@ 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 -> that you cannot create a new JSON file with the same name in the exact +> **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. @@ -587,16 +589,16 @@ to generate the factory data partition: 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: @@ -763,12 +765,13 @@ $ west flash The [factory data generation process](#generating-factory-data) described above 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 -the [nRF Connect Provider](../../src/platform/nrfconnect/FactoryDataProvider.h) -and [FactoryDataParser](../../src/platform/nrfconnect/FactoryDataParser.h) as +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 the +[nRF Connect Provider](../../src/platform/nrfconnect/FactoryDataProvider.h) and +[FactoryDataParser](../../src/platform/nrfconnect/FactoryDataParser.h) as examples. You can read the factory data set from the device's flash memory in different @@ -825,11 +828,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 - ``` \ No newline at end of file + ``` diff --git a/docs/guides/nrfconnect_platform_overview.md b/docs/guides/nrfconnect_platform_overview.md index 18e7047c7eb6d6..ed04f302d72e71 100644 --- a/docs/guides/nrfconnect_platform_overview.md +++ b/docs/guides/nrfconnect_platform_overview.md @@ -42,22 +42,23 @@ implementation of the Thread stack. ## Bluetooth LE stack In the nRF Connect platform applications, the Bluetooth LE interface is used to -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 or Wi-Fi network. +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 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 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) +- [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)
@@ -71,24 +72,31 @@ network layer functionalities provided by the Zephyr. 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) +- [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). +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 or Wi-Fi stacks provided -by the nRF Connect SDK and Zephyr must be integrated with the Matter stack using -a special intermediate layer. +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. In practice, this layer contains platform-specific implementations of abstract manager interfaces (such as Bluetooth LE Manager or Thread Stack Manager) @@ -96,7 +104,9 @@ 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. +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.
@@ -114,4 +124,7 @@ 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. +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.