Rework nRF Connect documentation (#4042)
* Extract README CLI section to separate guide
Co-authored-by: Grzegorz Ferenc <grzegorz.ferenc@nordicsemi.no>
* Created example configuration section.
* Restyled by prettier-markdown
* Reworked Intro/Overview/Device UI sections of examples's READMEs.
* Rework Building section
* Restyled by prettier-markdown
* Tech writer review: CLI and configuration page review
Signed-off-by: Grzegorz Ferenc <grzegorz.ferenc@nordicsemi.no>
Co-authored-by: Kamil Kasperczyk <kamil.kasperczyk@nordicsemi.no>
* Tech writer review: apply some comments from Damian
Signed-off-by: Grzegorz Ferenc <grzegorz.ferenc@nordicsemi.no>
* Fixed description in the configuration structure overview section.
* Tech writer review: review apps
Edited the docs for lighting and lock app.
Signed-off-by: Grzegorz Ferenc <grzegorz.ferenc@nordicsemi.no>
* Added nRF Connect platform overview guide.
* Tech writer review
Reworked figure. Reviewed doc.
Signed-off-by: Grzegorz Ferenc <grzegorz.ferenc@nordicsemi.no>
* Final review of READMEs
- Clarify some sections
- Remove redundant sections
- Fix some paths used in the docs
- Use nRF52840 DK board image encoded as jpg instead of png
- Fix after rebase to master
* Restyled by prettier-markdown
* Restyled by prettier-markdown
Co-authored-by: Grzegorz Ferenc <grzegorz.ferenc@nordicsemi.no>
Co-authored-by: Kamil Kasperczyk <kamil.kasperczyk@nordicsemi.no>
Co-authored-by: Restyled.io <commits@restyled.io>
diff --git a/examples/lock-app/nrfconnect/README.md b/examples/lock-app/nrfconnect/README.md
index 207b033..9fbf6d8 100644
--- a/examples/lock-app/nrfconnect/README.md
+++ b/examples/lock-app/nrfconnect/README.md
@@ -1,306 +1,347 @@
-# CHIP nRF Connect nRF52840 Lock Example Application
+# CHIP nRF Connect Lock Example Application
-An example application showing the use
-[CHIP](https://github.com/project-chip/connectedhomeip) on the Nordic nRF52840.
+The nRF Connect Lock Example demonstrates how to remotely control a door lock
+device with one basic bolt. It uses buttons to test changing the lock and device
+states and LEDs to show the state of these changes. You can use this example as
+a reference for creating your own application.
+
+The example is based on [CHIP](https://github.com/project-chip/connectedhomeip)
+and the nRF Connect platform, and supports remote access and control of a
+simulated door lock over a low-power, 802.15.4 Thread network.
+
+The example behaves as a CHIP accessory, that is a device that can be paired
+into an existing CHIP network and can be controlled by this network.
<hr>
-- [CHIP nRF52840 Lock Example Application](#chip-nrf52840-lock-example-application)
- - [Introduction](#introduction)
- - [Device UI](#device-ui)
- - [Building](#building)
- - [Using Docker container](#using-docker-container)
- - [Using Native shell](#using-native-shell)
- - [Supported nRF Connect SDK versions](#supported-nrf-connect-sdk-versions)
- - [Building minimal binary](#building-minimal-binary)
- - [Configuring the example](#configuring-the-example)
- - [Flashing and debugging](#flashing-and-debugging)
- - [Accessing the command line](#accessing-the-command-line)
+- [Overview](#overview)
+ - [Bluetooth LE advertising](#bluetooth-le-advertising)
+ - [Bluetooth LE rendezvous](#bluetooth-le-rendezvous)
+- [Requirements](#requirements)
+- [Device UI](#device-ui)
+- [Setting up the environment](#setting-up-the-environment)
+ - [Using Docker container for setup](#using-docker-container-for-setup)
+ - [Using native shell for setup](#using-native-shell-for-setup)
+- [Building](#building)
+- [Configuring the example](#configuring-the-example)
+- [Flashing and debugging](#flashing-and-debugging)
+- [Testing the example](#testing-the-example)
<hr>
-<a name="intro"></a>
+<a name="overview"></a>
-## Introduction
+## Overview
-
+This example is running on the nRF Connect platform, which is based on the
+[nRF Connect SDK](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/index.html)
+and [Zephyr RTOS](https://zephyrproject.org/). Visit CHIP's
+[nRF Connect platform overview](../../../docs/guides/nrfconnect_platform_overview.md)
+to read more about the platform structure and dependencies.
-The nRF52840 lock example application provides a working demonstration of a
-connected door lock device, built using CHIP, and the Nordic nRF Connect. The
-example supports remote access and control of a simulated door lock over a
-low-power, 802.15.4 Thread network. It is capable of being paired into an
-existing CHIP network along with other CHIP-enabled devices. The example targets
-the
-[Nordic nRF52840 DK](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52840-DK)
-development kit, but is readily adaptable to other nRF52840-based hardware.
+The CHIP device that runs the lock application is controlled by the CHIP
+controller device over the Thread protocol. By default, the CHIP device has
+Thread disabled, and it should be paired with CHIP controller and get
+configuration from it. Some actions required before establishing full
+communication are described below.
-The lock example is intended to serve both as a means to explore the workings of
-CHIP, as well as a template for creating real products based on the Nordic
-platform.
+The example also comes with a test mode, which allows to start Thread with the
+default settings by pressing button manually. However, this mode does not
+guarantee that the device will be able to communicate with the CHIP controller
+and other devices.
-The example makes use of the CMake build system to generate the ninja build
-script. The build system takes care of invoking the CHIP library build with all
-necessary flags exported from the Zephyr environment.
+### Bluetooth LE advertising
+
+To commission the device onto a CHIP network, the device must be discoverable
+over Bluetooth LE. For security reasons, you must start Bluetooth LE advertising
+manually after powering up the device by pressing **Button 4**.
+
+### Bluetooth LE rendezvous
+
+In CHIP, the commissioning procedure (called rendezvous) is done over Bluetooth
+LE between a CHIP device and the CHIP controller, where the controller has the
+commissioner role.
+
+To start the rendezvous, the controller must get the commissioning information
+from the CHIP device. The data payload is encoded within a QR code, printed to
+the UART console, and shared using an NFC tag.
+
+#### Thread provisioning
+
+Last part of the rendezvous procedure, the provisioning operation involves
+sending the Thread network credentials from the CHIP controller to the CHIP
+device. As a result, device is able to join the Thread network and communicate
+with other Thread devices in the network.
+
+<hr>
+
+<a name="requirements"></a>
+
+## Requirements
+
+The application requires the nRF Connect SDK v1.4.0 to work correctly.
+
+The example supports building and running on the following devices:
+
+| Board name | Board platform build name |
+| ----------------------------------------------------------------------------------------- | ------------------------- |
+| [nRF52840 DK](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52840-DK) | `nrf52840dk_nrf52840` |
+
+<hr>
<a name="device-ui"></a>
## Device UI
-The example application provides a simple UI that depicts the state of the
-device and offers basic user control. This UI is implemented via the
-general-purpose LEDs and buttons built in to the nRF52840 DK dev board.
+This section lists the User Interface elements that you can use to control and
+monitor the state of the device. All these elements can be located on the
+following board picture:
-**LED #1** shows the overall state of the device and its connectivity. Four
-states are depicted:
+
-- _Short Flash On (50ms on/950ms off)_ — The device is in an
+**LED 1** shows the overall state of the device and its connectivity. The
+following states are possible:
+
+- _Short Flash On (50 ms on/950 ms off)_ — The device is in the
unprovisioned (unpaired) state and is waiting for a commissioning
application to connect.
-* _Rapid Even Flashing (100ms on/100ms off)_ — The device is in an
- unprovisioned state and a commissioning application is connected via BLE.
+- _Rapid Even Flashing (100 ms on/100 ms off)_ — The device is in the
+ unprovisioned state and a commissioning application is connected through
+ Bluetooth LE.
- _Short Flash Off (950ms on/50ms off)_ — The device is fully
- provisioned, but does not yet have full network (Thread) or service
+ provisioned, but does not yet have full Thread network or service
connectivity.
-* _Solid On_ — The device is fully provisioned and has full network and
- service connectivity.
+- _Solid On_ — The device is fully provisioned and has full Thread
+ network and service connectivity.
-**Button #1** can be used to initiate a OTA software update as well as to reset
-the device to a default state.
+**LED 2** simulates the lock bolt and shows the state of the lock. The following
+states are possible:
-Pressing and holding Button #1 for 6 seconds initiates a factory reset. After an
-initial period of 3 seconds, all four LED will flash in unison to signal the
-pending reset. Holding the button past 6 seconds will cause the device to reset
-its persistent configuration and initiate a reboot. The reset action can be
-cancelled by releasing the button at any point before the 6 second limit.
+- _Solid On_ — The bolt is extended and the door is locked.
-**LED #2** shows the state of the simulated lock bolt. When the LED is lit the
-bolt is extended (i.e. door locked); when not lit, the bolt is retracted (door
-unlocked). The LED will flash whenever the simulated bolt is in motion from one
-position to another.
+- _Off_ — The bolt is retracted and the door is unlocked.
-**Button #2** can be used to change the state of the simulated bolt. This can be
-used to mimick a user manually operating the lock. The button behaves as a
-toggle, swapping the state every time it is pressed.
+- _Rapid Even Flashing (100 ms on/100 ms off during 2 s)_ — The
+ simulated bolt is in motion from one position to another.
-**Button #3** can be used to start Thread networking using default configuration
-which was selected to match OpenThread Border Router default settings and
-network credentials.
+**Button 1** can be used for the following purposes:
-**Button #4** can be used to start BLE advertisement, which is disabled by
-default.
+- _Pressed for 6 s_ — Initiates the factory reset of the device.
+ Releasing the button within the 6-second window cancels the factory reset
+ procedure. **LEDs 1-4** blink in unison when the factory reset procedure is
+ initiated.
-The remaining two LEDs (#3 and #4) are unused.
+- _Pressed for less than 3 s_ — Initiates the OTA software update
+ process. This feature is not currently supported.
-**NFC** can be used to scan shared tag and get information about device
-necessary to perform rendezvous and network provisioning operation.
+**Button 2** — Pressing the button once changes the lock state to the
+opposite one.
-Tag can be read by bringing NFC poller e.g. smartphone supporting NFC close to
-the nRF52840's NFC antenna. Moreover in the reaction on sensing field from the
-smartphone CHIP device will start BLE advertisement, what is an alternative way
-to trigger this from manually pressing Button 4.
+**Button 3** — Pressing the button once starts the Thread networking in
+the test mode using the default configuration.
+
+**Button 4** — Pressing the button once starts the Bluetooth LE
+advertising for the predefined period of time.
+
+**SEGGER J-Link USB port** can be used to get logs from the device or
+communicate with it using the
+[command line interface](../../../docs/guides/nrfconnect_examples_cli.md).
+
+**NFC port with antenna attached** can be used to start the
+[rendezvous](#bluetooth-le-rendezvous) by providing the commissioning
+information from the CHIP device in a data payload that can be shared using NFC.
+
+<hr>
+
+## Setting up the environment
+
+Before building the example, check out the CHIP repository and sync submodules
+using the following command:
+
+ $ git submodule update --init
+
+The example requires the nRF Connect SDK v1.4.0. You can either install it along
+with the related tools directly on your system or use a Docker image that has
+the tools pre-installed.
+
+If you are a macOS user, you won't be able to use the Docker container to flash
+the application onto a Nordic board due to
+[certain limitations of Docker for macOS](https://docs.docker.com/docker-for-mac/faqs/#can-i-pass-through-a-usb-device-to-a-container).
+Use the [native shell](#using-native-shell) for building instead.
+
+### Using Docker container for setup
+
+To use the Docker container for setup, complete the following steps:
+
+1. If you do not have the nRF Connect SDK installed yet, create a directory for
+ it by running the following command:
+
+ $ mkdir ~/nrfconnect
+
+2. Download the latest version of the nRF Connect SDK Docker image by running
+ the following command:
+
+ $ docker pull nordicsemi/nrfconnect-chip
+
+3. Start Docker with the downloaded image by running the following command,
+ customized to your needs as described below:
+
+ $ docker run --rm -it -e RUNAS=$(id -u) -v ~/nrfconnect:/var/ncs -v ~/connectedhomeip:/var/chip \
+ -v /dev/bus/usb:/dev/bus/usb --device-cgroup-rule "c 189:* rmw" nordicsemi/nrfconnect-chip
+
+ In this command:
+
+ - _~/nrfconnect_ can be replaced with an absolute path to the nRF Connect
+ SDK source directory.
+ - _~/connectedhomeip_ must be replaced with an absolute path to the CHIP
+ source directory.
+ - _-v /dev/bus/usb:/dev/bus/usb --device-cgroup-rule "c 189:_ rmw"\*
+ parameters can be omitted if you are not planning to flash the example
+ onto hardware. These parameters give the container access to USB devices
+ connected to your computer such as the nRF52840 DK.
+ - _--rm_ can be omitted if you do not want the container to be
+ auto-removed when you exit the container shell session.
+ - _-e RUNAS=\$(id -u)_ is needed to start the container session as the
+ current user instead of root.
+
+4. Check out or update the nRF Connect SDK to the recommended `v1.4.0` version
+ by running the following command in the Docker container:
+
+ $ setup --ncs v1.4.0
+ /var/ncs repository is empty. Do you wish to check out nRF Connect SDK sources [v1.4.0]? [Y/N] y
+ ...
+ /var/chip repository is initialized, skipping...
+
+Now you can proceed with the [Building](#building) instruction.
+
+### Using native shell for setup
+
+To use the native shell for setup, complete the following steps:
+
+1. Download and install the following additional software:
+
+ - [nRF Command Line Tools](https://www.nordicsemi.com/Software-and-Tools/Development-Tools/nRF-Command-Line-Tools)
+ - [GN meta-build system](https://gn.googlesource.com/gn/)
+
+2. Depending on whether you have the nRF Connect SDK installed:
+
+ - Follow the
+ [guide](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/gs_assistant.html#)
+ in the nRF Connect SDK documentation to install the nRF Connect SDK
+ v1.4.0. Since command-line tools will be used for building the example,
+ installing SEGGER Embedded Studio is not required.
+
+ - If you have an older version of the SDK installed, use the following
+ commands to update it to the recommended version. Replace
+ _nrfconnect-dir_ with the path to your nRF Connect SDK installation
+ directory.
+
+ $ cd nrfconnect-dir/nrf
+ $ git fetch origin
+ $ git checkout v1.4.0
+ $ west update
+
+3. Initialize environment variables referred to by the CHIP and the nRF Connect
+ SDK build scripts. Replace _nrfconnect-dir_ with the path to your nRF
+ Connect SDK installation directory, and _toolchain-dir_ with the path to GNU
+ Arm Embedded Toolchain.
+
+ $ source nrfconnect-dir/zephyr/zephyr-env.sh
+ $ export ZEPHYR_TOOLCHAIN_VARIANT=gnuarmemb
+ $ export GNUARMEMB_TOOLCHAIN_PATH=toolchain-dir
+
+Now you can proceed with the [Building](#building) instruction.
+
+<hr>
<a name="building"></a>
## Building
-### Using Docker container
+Complete the following steps, regardless of the method used for setting up the
+environment:
-> **Important**:
->
-> Due to
-> [certain limitations of Docker for MacOS](https://docs.docker.com/docker-for-mac/faqs/#can-i-pass-through-a-usb-device-to-a-container)
-> it is impossible to use the Docker container to communicate with a USB device
-> such as nRF 52840 DK. Therefore, MacOS users are advised to follow the
-> [Using Native shell](#using-native-shell) instruction.
+1. Navigate to the example's directory:
-The easiest way to get started with the example is to use nRF Connect SDK Docker
-image for CHIP applications. Run the following commands to start a Docker
-container:
+ $ cd examples/lock-app/nrfconnect
- $ mkdir ~/nrfconnect
- $ mkdir ~/connectedhomeip
- $ docker pull nordicsemi/nrfconnect-chip
- $ docker run --rm -it -e RUNAS=$(id -u) -v ~/nrfconnect:/var/ncs -v ~/connectedhomeip:/var/chip \
- -v /dev/bus/usb:/dev/bus/usb --device-cgroup-rule "c 189:* rmw" nordicsemi/nrfconnect-chip
+2. Run the following command to build the example, with _board-name_ replaced
+ with the name of the Nordic Semiconductor's board you own, for example
+ `nrf52840dk_nrf52840`:
-> **Note**:
->
-> - `~/nrfconnect` can be replaced with an absolute path to nRF Connect SDK
-> source directory in case you have it already installed.
-> - Likewise, `~/connectedhomeip` can be replaced with an absolute path to
-> CHIP source directory.
-> - `-v /dev/bus/usb:/dev/bus/usb --device-cgroup-rule 'c 189:* rmw`
-> parameters can be omitted if you're not planning to flash the example onto
-> hardware. The parameters give the container access to USB devices
-> connected to your computer such as the nRF52840 DK.
-> - `--rm` flag can be omitted if you don't want the container to be
-> auto-removed when you exit the container shell session.
-> - `-e RUNAS=$(id -u)` is needed to start the container session as the
-> current user instead of root.
+ $ west build -b board-name
-If you use the container for the first time and you don't have nRF Connect SDK
-and CHIP sources downloaded yet, run `setup` command in the container to pull
-the sources into directories mounted as `/var/ncs` and `/var/chip`,
-respectively:
+ You only need to specify the board name on the first build. See
+ [Requirements](#requirements) for the names of compatible boards.
- $ setup --ncs v1.4.0
- /var/ncs repository is empty. Do you wish to check out nRF Connect SDK sources [v1.4.0]? [Y/N] y
- ...
- /var/chip repository is empty. Do you wish to check out Project CHIP sources [master]? [Y/N] y
- ...
+The output `zephyr.hex` file will be available in the `build/zephyr/` directory.
-Now you may build the example by running the commands below in the Docker
-container:
+### Removing build artifacts
- $ cd /var/chip/examples/lock-app/nrfconnect
- $ west build -b nrf52840dk_nrf52840
+If you're planning to build the example for a different board or make changes to
+the configuration, remove all build artifacts before building. To do so, use the
+following command:
-If the build succeeds, the binary will be available under
-`/var/chip/examples/lock-app/nrfconnect/build/zephyr/zephyr.hex`. Note that
-other operations described in this document like flashing or debugging can also
-be done in the container.
+ $ rm -r build
-### Using native shell
+### Building with release configuration
-Before building the example,
-[download the nRF Connect SDK and install all requirements](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/gs_installing.html).
-Please read the
-[Supported nRF Connect SDK versions](#supported-nrf-connect-sdk-versions)
-section to learn which version to use to avoid unexpected compatibility issues.
+To build the example with release configuration that disables the diagnostic
+features like logs and command-line interface, run the following command:
-If you don't want to use SEGGER Embedded Studio, you may skip the part about
-installing and configuring it.
+ $ west build -b board-name -- -DOVERLAY_CONFIG=third_party/connectedhomeip/config/nrfconnect/release.conf
-Download and install the
-[nRF Command Line Tools](https://www.nordicsemi.com/Software-and-Tools/Development-Tools/nRF-Command-Line-Tools).
+Remember to replace _board-name_ with the name of the Nordic Semiconductor's
+board you own.
-Download and install [GN meta-build system](https://gn.googlesource.com/gn/).
-
-Make sure that you source the following file:
-
- $ source <ncs-dir>/zephyr/zephyr-env.sh
-
-> **Note:**
->
-> Ensure that `$ZEPHYR_BASE`, `$GNUARMEMB_TOOLCHAIN_PATH`, and
-> `$ZEPHYR_TOOLCHAIN_VARIANT` environment variables are set in your current
-> terminal before building. `$GNUARMEMB_TOOLCHAIN_PATH` and
-> `$ZEPHYR_TOOLCHAIN_VARIANT` must be set manually.
-
-After your environment is set up, you are ready to build the example. The
-recommended tool for building and flashing the device is
-[west](https://docs.zephyrproject.org/latest/guides/west/).
-
-The following commands will build the `lock-app` example:
-
- $ cd ~/connectedhomeip/examples/lock-app/nrfconnect
-
- # If this is a first time build or if `build` directory was deleted
- $ west build -b nrf52840dk_nrf52840
-
- # Any subsequent build
- $ west build
-
-After a successful build, the binary will be available under
-`<example-dir>/build/zephyr/zephyr.hex`
-
-### Supported nRF Connect SDK versions
-
-It is recommended to use the nRF Connect version which is being verified as a
-part of CHIP Continuous Integration testing, which happens to be `v1.4.0` at the
-moment. You may verify that the revision is used in
-[chip-build-nrf-platform](https://github.com/project-chip/connectedhomeip/blob/master/integrations/docker/images/chip-build-nrf-platform/Dockerfile)
-Docker image in case of doubt.
-
-Please refer to
-[this section](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/gs_installing.html#updating-the-repositories)
-in the user guide to learn how to update nRF Connect SDK repository. For example
-to checkout given `v1.4.0` revision the following commands should be called:
-
- # Phrase <nrfconnect-dir> should be replaced with an absolute path to nRF Connect SDK source directory.
- $ cd <nrfconnect-dir>/nrf
-
- $ git fetch origin
- $ git checkout v1.4.0
- $ west update
-
-Alternatively, if you use the docker container, you may execute the following
-command instead:
-
- $ setup --ncs v1.4.0
-
-### Building minimal binary
-
-In order to build the example with no diagnostic features like UART console or
-application logs, which should result in significantly smaller binary, run the
-following commands:
-
- # Delete the build directory to make sure that no settings are cached
- $ rm -rf build/
-
- # Build the example using release config overlay
- $ west build -b nrf52840dk_nrf52840 -- -DOVERLAY_CONFIG=third_party/connectedhomeip/config/nrfconnect/release.conf
+<hr>
<a name="configuring"></a>
## Configuring the example
-The Zephyr ecosystem is higly configurable and allows the user to modify many
-aspects of the application. The configuration system is based on `Kconfig` and
-the settings can be modified using the `menuconfig` utility.
+The Zephyr ecosystem is based on Kconfig files and the settings can be modified
+using the menuconfig utility.
-To open the configuration menu, do the following:
+To open the menuconfig utility, run the following command from the example
+directory:
- $ cd <example-dir>
- # First time build
- $ west build -b nrf52840dk_nrf52840 -t menuconfig
+ $ west build -b board-name -t menuconfig
- # Any subsequent build
- $ west build -t menuconfig
+Remember to replace _board-name_ with the name of the Nordic Semiconductor's
+board you own.
- # Running menuconfig with ninja
- $ cd <example-dir>/build
- $ ninja menuconfig
+Changes done with menuconfig will be lost if the `build` directory is deleted.
+To make them persistent, save the configuration options in the `prj.conf` file.
+For more information, see the
+[Configuring nRF Connect SDK examples](../../../docs/guides/nrfconnect_examples_configuration.md)
+page.
-Changes done with `menuconfig` will be lost, if the `build` directory is
-deleted. To make them persistent, save the configuration options in `prj.conf`
-file.
+<hr>
<a name="flashing"></a>
## Flashing and debugging
-The example application is designed to run on the
-[Nordic nRF52840 DK](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52840-DK)
-development kit.
+To flash the application to the device, use the west tool and run the following
+command from the example directory:
-To flash the application to the device, use the `west` tool:
-
- $ cd <example-dir>
$ west flash
-If you have multiple nRF52840 DK boards connected, `west` will prompt you to
-pick the correct one.
+If you have multiple nRF52840 DK boards connected, west will prompt you to pick
+the correct one.
-To debug the application on target:
+To debug the application on target, run the following command from the example
+directory:
- $ cd <example-dir>
$ west debug
-<a name="accessing-the-command-line"></a>
+<hr>
-## Accessing the command line
+## Testing the example
-The application includes a command line interface with support for logs and the
-OpenThread commands.
-
-To access it, use any serial terminal program you like, for example `minicom` or
-`GNU screen`.
-
-The UART interface is configured for `115200` baud rate.
-
-All OpenThread commands must be prefixed with `ot`, for example
-`ot thread start`.
+Check the [CLI tutorial](../../../docs/guides/nrfconnect_examples_cli.md) to
+learn how to use command-line interface of the application.
