doc: group major guides in one directory (project-chip#8992)

* doc: group major guides in one directory Moved major guides to one directory without removing files. Moved images for guides to the guides directory. This makes it easier to find information and use cross-linking. Signed-off-by: Grzegorz Ferenc <Grzegorz.Ferenc@nordicsemi.no> * Restyled by prettier-markdown Co-authored-by: Restyled.io <commits@restyled.io>
greg-fer · Aug 16, 2021 · 8a4f2f1 · 8a4f2f1
1 parent 9c48524
commit 8a4f2f1
Show file tree

Hide file tree

Showing 18 changed files with 759 additions and 675 deletions.
diff --git a/README.md b/README.md
@@ -161,22 +161,22 @@ Instructions about how to build Project Connected Home over IP can be found
 
 The Connected Home over IP repository is structured as follows:
 
-| File / Folder                        | Contents                                                                                 |
-| ------------------------------------ | ---------------------------------------------------------------------------------------- |
-| `build/`                             | Build system support content and build output directories                                |
-| [BUILDING.md](./docs/BUILDING.md)    | More detailed information on configuring and building Project CHIP for different targets |
-| `CODE_OF_CONDUCT.md`                 | Code of Conduct for Project CHIP, and contributions to it                                |
-| [CONTRIBUTING.md](./CONTRIBUTING.md) | Guidelines for contributing to Project CHIP                                              |
-| `docs/`                              | Documentation                                                                            |
-| `examples/`                          | Example firmware applications that demonstrate use of Project CHIP technology            |
-| `integrations/`                      | Third party integrations related to this project                                         |
-| `integrations/docker/`               | Docker scripts and Dockerfiles                                                           |
-| `LICENSE`                            | Project CHIP [License file](./LICENSE) (Apache 2.0)                                      |
-| `BUILD.gn`                           | Top level GN build file                                                                  |
-| `README.md`                          | This file                                                                                |
-| `src/`                               | Implementation of Project CHIP                                                           |
-| `third_party/`                       | Third-party code used by Project CHIP                                                    |
-| `scripts/`                           | Scripts needed to work with the Project CHIP repo                                        |
+| File / Folder                          | Contents                                                                                 |
+| -------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `build/`                               | Build system support content and build output directories                                |
+| [BUILDING.md](docs/guides/BUILDING.md) | More detailed information on configuring and building Project CHIP for different targets |
+| `CODE_OF_CONDUCT.md`                   | Code of Conduct for Project CHIP, and contributions to it                                |
+| [CONTRIBUTING.md](./CONTRIBUTING.md)   | Guidelines for contributing to Project CHIP                                              |
+| `docs/`                                | Documentation, including [guides](./docs/guides)                                         |
+| `examples/`                            | Example firmware applications that demonstrate use of Project CHIP technology            |
+| `integrations/`                        | Third party integrations related to this project                                         |
+| `integrations/docker/`                 | Docker scripts and Dockerfiles                                                           |
+| `LICENSE`                              | Project CHIP [License file](./LICENSE) (Apache 2.0)                                      |
+| `BUILD.gn`                             | Top level GN build file                                                                  |
+| `README.md`                            | This file                                                                                |
+| `src/`                                 | Implementation of Project CHIP                                                           |
+| `third_party/`                         | Third-party code used by Project CHIP                                                    |
+| `scripts/`                             | Scripts needed to work with the Project CHIP repo                                        |
 
 # License
 

diff --git a/docs/Doxyfile b/docs/Doxyfile
@@ -827,7 +827,7 @@ INPUT                  = README.md \
                          CODE_OF_CONDUCT.md \
                          CONTRIBUTING.md \
                          docs/README.md \
-                         docs/BUILDING.md \
+                         docs/guides/BUILDING.md \
                          docs/VSCODE_DEVELOPMENT.md \
                          docs/PROJECT_FLOW.md \
                          docs/STYLE_GUIDE.md \

diff --git a/docs/README.md b/docs/README.md
@@ -3,7 +3,7 @@
 ## Building and Developing
 
 -   Documentation about building from the command line can be found in
-    [the build guide](./BUILDING.md)
+    [the build guide](guides/BUILDING.md)
 -   Documentation about running [cirque](https://github.com/openweave/cirque)
     tests can be found in
     [the cirque test guide](src/test_driver/linux-cirque/README.md)

diff --git a/docs/BUILDING.md → docs/guides/BUILDING.md b/docs/BUILDING.md → docs/guides/BUILDING.md
@@ -1,8 +1,8 @@
-## Build Documentation
+# Building Matter
 
-CHIP 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/).
+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:
 
@@ -19,9 +19,9 @@ Build system features:
 -   Introspection: `gn desc`
 -   Automatic formatting: `gn format`
 
-### Checking out the Code
+## Checking out the Matter code
 
-To check out the CHIP repository:
+To check out the Matter repository:
 
 ```
 git clone --recurse-submodules git@github.com:project-chip/connectedhomeip.git
@@ -33,11 +33,11 @@ If you already have a checkout, run the following command to sync submodules:
 git submodule update --init
 ```
 
-### Prerequisites
+## Prerequisites
 
 Before building, you'll need to install a few OS specific dependencies.
 
-#### How to install prerequisites on Linux
+### Installing prerequisites on Linux
 
 On Debian-based Linux distributions such as Ubuntu, these dependencies can be
 satisfied with the following:
@@ -48,7 +48,7 @@ sudo apt-get install git gcc g++ python pkg-config libssl-dev libdbus-1-dev \
      python3-pip unzip libgirepository1.0-dev libcairo2-dev
 ```
 
-#### How to install prerequisites on macOS
+### Installing prerequisites on macOS
 
 On macOS, first install Xcode from the Mac App Store. The remaining dependencies
 can be installed and satisfied using [Brew](https://brew.sh/):
@@ -71,7 +71,7 @@ OpenSSL installed by Brew.
 Note: If using MacPorts, `port install openssl` is sufficient to satisfy this
 dependency.
 
-#### How to install prerequisites on Raspberry Pi 4
+### Installing prerequisites on Raspberry Pi 4
 
 Using `rpi-imager`, install the Ubuntu _21.04_ 64-bit _server_ OS for arm64
 architectures on a micro SD card. This release will have bluez 5.55 or newer
@@ -89,8 +89,8 @@ sudo apt-get install pi-bluetooth
 You need to reboot your RPi after install `pi-bluetooth`.
 
 By default, wpa_supplicant is not allowed to update (overwrite) configuration,
-if you want chip app to be able to store the configuration changes permanently,
-we need to make the following changes.
+if you want the Matter app to be able to store the configuration changes
+permanently, we need to make the following changes.
 
 1. Edit the dbus-fi.w1.wpa_supplicant1.service file to use configuration file
    instead.
@@ -120,7 +120,7 @@ update_config=1
 
 Finally, reboot your RPi.
 
-### Build Preparation
+## Prepare for building
 
 Before running any other build command, the `scripts/activate.sh` environment
 setup script should be sourced at the top level. This script takes care of
@@ -141,7 +141,7 @@ source scripts/bootstrap.sh
 The `scripts/bootstrap.sh` script re-creates the environment from scratch, which
 is expensive, so avoid running it unless the environment is out of date.
 
-### Build for the Host OS (Linux or macOS)
+## Build for the host OS (Linux or macOS)
 
 This will build all sources, libraries, and tests for the host platform:
 
@@ -188,7 +188,7 @@ ninja: no work to do
 
 that means that the tests passed in a previous build.
 
-### Build Custom configuration
+## Build custom configuration
 
 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
@@ -213,10 +213,10 @@ gn gen out/custom
 gn args --list out/custom
 ```
 
-### Build Examples
+## Build examples
 
-Examples can be built in two ways, as separate projects that add CHIP in the
-third_party directory, or in the top level CHIP project.
+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.
 
 To build the `chip-shell` example as a separate project:
 
@@ -228,7 +228,7 @@ ninja -C out/debug
 
 To build it at the top level, see below under "Unified Builds".
 
-### Unified Builds
+## Unified builds
 
 To build a unified configuration that approximates the set of continuous builds:
 
@@ -282,7 +282,7 @@ Simplelink cc13x2_26x2 examples to the unified build, install the
 gn gen out/unified --args="target_os=\"all\" enable_ti_simplelink_builds=true ti_simplelink_sdk_root=\"/path/to/sdk\" ti_sysconfig_root=\"/path/to/sysconfig\""
 ```
 
-### Getting Help
+## Getting help
 
 GN has builtin help via
 
@@ -301,7 +301,7 @@ gn help toolchain
 Also see the
 [quick start guide](https://gn.googlesource.com/gn/+/master/docs/quick_start.md).
 
-### Introspection
+## Introspection
 
 GN has various introspection tools to help examine the build configuration.
 
@@ -352,7 +352,7 @@ gn desc out/host //src/lib outputs
 gn desc out/host //src/lib --format=json
 ```
 
-## Maintaining CHIP
+## 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.
diff --git a/docs/guides/android_chiptool_building.md b/docs/guides/android_chiptool_building.md
@@ -0,0 +1,87 @@
+# Building Android CHIPTool
+
+Android CHIPTool is an application for Android for commissioning and controlling
+CHIP accessory devices.
+
+CHIPTool offers the following features:
+
+-   Scan a CHIP QR code and display payload information to the user
+-   Read the NFC tag containing CHIP onboarding information
+-   Commission a CHIP device
+-   Send echo requests to the CHIP echo server
+-   Send on/off cluster requests to a CHIP device
+
+<hr>
+
+-   [Source files](#source)
+-   [Requirements for building](#requirements)
+    -   [ABIs and TARGET_CPU](#abi)
+-   [Building Android CHIPTool](#building)
+
+<hr>
+
+<a name="source"></a>
+
+## Source files
+
+You can find source files of the Android CHIPTool application in the
+`src/android/CHIPTool` directory.
+
+<hr>
+
+<a name="requirements"></a>
+
+## Requirements for building
+
+You need Android SDK 21 & NDK downloaded to your machine. Set the
+`$ANDROID_HOME` environment variable to where the SDK is downloaded and the
+`$ANDROID_NDK_HOME` environment variable to point to where the NDK package is
+downloaded.
+
+<a name="abi"></a>
+
+### ABIs and TARGET_CPU
+
+`TARGET_CPU` can have the following values, depending on your smartphone CPU
+architecture:
+
+| ABI         | TARGET_CPU |
+| ----------- | ---------- |
+| armeabi-v7a | arm        |
+| arm64-v8a   | arm64      |
+| x86         | x86        |
+| x86_64      | x64        |
+
+<hr>
+
+<a name="building"></a>
+
+## Building Android CHIPTool
+
+Complete the following steps to build CHIPTool:
+
+1. Check out the CHIP repository.
+
+2. In the command line, run the following command from the top CHIP directory:
+
+    ```shell
+    TARGET_CPU=arm64 ./scripts/examples/android_app.sh
+    ```
+
+    See the table above for other values of `TARGET_CPU`.
+
+3. Open the project in Android Studio and run **Sync Project with Gradle
+   Files**.
+
+4. Use one of the following options to build an Android package:
+
+    - Click **Make Project** in Android Studio.
+    - Run the following command in the command line:
+
+        ```shell
+        cd src/android/CHIPTool
+        ./gradlew build
+        ```
+
+The debug Android package `app-debug.apk` will be generated at
+`src/android/CHIPTool/app/build/outputs/apk/debug/`.
diff --git a/docs/images/CHIPTool_device_commissioned.jpg → ...s/images/CHIPTool_device_commissioned.jpg b/docs/images/CHIPTool_device_commissioned.jpg → ...s/images/CHIPTool_device_commissioned.jpg
diff --git a/...s/chip_nrfconnect_overview_simplified.svg → ...s/chip_nrfconnect_overview_simplified.svg b/...s/chip_nrfconnect_overview_simplified.svg → ...s/chip_nrfconnect_overview_simplified.svg
diff --git a/...mages/nrfconnect_android_connectivity.svg → ...mages/nrfconnect_android_connectivity.svg b/...mages/nrfconnect_android_connectivity.svg → ...mages/nrfconnect_android_connectivity.svg
diff --git a/docs/guides/nrfconnect_android_commissioning.md b/docs/guides/nrfconnect_android_commissioning.md
@@ -4,11 +4,10 @@ You can use [CHIPTool](../../src/android/CHIPTool/README.md) for Android
 smartphones to commission a Nordic Semiconductor device running an nRF Connect
 platform example onto a CHIP-enabled Thread network.
 
-This guide references the nRF52840 DK and the
-[nRF Connect Lock Example Application](../../examples/lock-app/nrfconnect/README.md),
-but the instructions are also valid for the
-[nRF Connect Lighting Example Application](../../examples/lighting-app/nrfconnect/README.md)
-and can be adapted to other applications as well.
+This guide references the nRF52840 DK and the door lock example application
+based on the nRF Connect platform, but the instructions are also valid for the
+nRF Connect lighting example application and can be adapted to other platforms
+and applications as well.
 
 <hr>
 
@@ -50,7 +49,7 @@ The following diagram shows the connectivity between network components required
 to allow communication between devices running the CHIPTool and Lock
 applications:
 
-<img src="../images/nrfconnect_android_connectivity.svg" alt="CHIP nodes connectivity" width="600" />
+<img src="./images/nrfconnect_android_connectivity.svg" alt="CHIP nodes connectivity" width="600" />
 
 <hr>
 
@@ -95,18 +94,17 @@ or the nRF52840 Dongle acting as the
 
 Build and program the example application onto your compatible device.
 
-For this guide, see
-[nRF Connect Lock Example Application README](../../examples/lock-app/nrfconnect/README.md)
-to learn how to build and program the example onto an nRF52840 DK.
+For this guide, see the documentation for the door lock example application to
+learn how to build and program the example onto an nRF52840 DK.
 
 <hr>
 
 <a name="building-chiptool"></a>
 
 ## Building and installing Android CHIPTool
 
-To build the CHIPTool application for your smartphone, read
-[Android CHIPTool README](../../src/android/CHIPTool/README.md).
+To build the CHIPTool application for your smartphone, read the
+[Building Android CHIPTool](android_chiptool_building.md) guide.
 
 After building, install the application by completing the following steps:
 
@@ -143,16 +141,18 @@ To prepare the accessory device for commissioning, complete the following steps:
     device. For details, see the
     [Using CLI in nRF Connect examples](nrfconnect_examples_cli.md) guide. This
     will grant you access to the application logs.
-2.  Hold **Button 1** on the accessory device for more than 6 s to trigger the
-    factory reset of the device.
+2.  Hold the appropriate button on the accessory device for more than 6 s to
+    trigger the factory reset of the device. See the user interface section in
+    the example documentation to check the button number.
 3.  Find a message similar to the following one in the application logs:
 
         I: 615 [SVR]Copy/paste the below URL in a browser to see the QR Code:
         I: 621 [SVR]https://dhrishi.github.io/connectedhomeip/qrcode.html?data=MT%3AW0GU2OTB00KA0648G00
 
 4.  Open the URL in a web browser to have the commissioning QR code generated.
-5.  Press **Button 4** on the device (or **Button 1** on a Thingy device) to
-    start the Bluetooth LE advertising.
+5.  Press 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.
 
 <hr>
 
@@ -187,7 +187,7 @@ device successfully joins the Thread network.
 
 Once the device is commissioned, the following screen appears:
 
-![CHIPTool device control screen](../../docs/images/CHIPTool_device_commissioned.jpg)
+![CHIPTool device control screen](./images/CHIPTool_device_commissioned.jpg)
 
 The two textboxes at the top contain **Fabric ID** and **Node ID** of the last
 commissioned device.
@@ -200,8 +200,8 @@ Check the IPv6 connectivity with the device using the following steps:
    be it the address or an error message, will be displayed at the bottom of the
    screen.
 
-2. Tap the following buttons to change the lock state of the nRF Connect Lock
-   Example Application referenced in this guide:
+2. Tap the following buttons to change the lock state of the nRF Connect door
+   lock example application referenced in this guide:
 
     - **ON** and **OFF** buttons lock and unlock the door, respectively.
     - **TOGGLE** changes the lock state to the opposite.

diff --git a/docs/guides/nrfconnect_examples_cli.md b/docs/guides/nrfconnect_examples_cli.md
@@ -1,15 +1,8 @@
 # Using CLI in nRF Connect examples
 
-The following 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):
-
--   [CHIP nRF Connect Lock Example Application](../../examples/lock-app/nrfconnect/README.md)
--   [CHIP nRF Connect Lighting Example Application](../../examples/lighting-app/nrfconnect/README.md)
-
-The
-[CHIP nRF Connect Pigweed Example Application](../../examples/pigweed-app/nrfconnect/README.md)
-does not support CLI.
+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