Add instructions on setting up zap for ARM linux (project-chip#25431)

andy31415 · web-flow · commit 0062c5d6f3c1 · 2023-03-02T12:20:44.000-05:00
* Add instructions on setting up zap for ARM linux

* Fix typo

* Restyle

* Make links real links

* Restyle

* Add full traceback flag for sphinx to debug doc build issues

* Fix the flag location

* Add icon_links to options ... not sure why they are required, but at least build should not fail

* Disable turn-warnings-to-errors in the doc build

* Fix several readme.md cross reference links with new new myst

* More selectively suppress warnings. Still not ideal as the wrong reference is probably the most useful warning by far

* Restyle

* Remove extra comment

* Fix final errors: remove some bracketing, add top level as an external link prefix
diff --git a/README.md b/README.md
@@ -174,7 +174,7 @@ We welcome your contributions to Matter. Read our contribution guidelines
 
 # Building and Developing in Matter
 
-Instructions about how to build Matter can be found [here](./docs/README.md).
+Instructions about how to build Matter can be found [here](./docs/README.md) .
 
 # Directory Structure
 
diff --git a/docs/Makefile b/docs/Makefile
@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?= -W --keep-going -c . -d _build/doctrees
+SPHINXOPTS    ?= -W -T --keep-going -c . -d _build/doctrees
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = _build/src
 BUILDDIR      = _build
diff --git a/docs/conf.py b/docs/conf.py
@@ -30,6 +30,7 @@
     "**/android/App/app/libs*",
     "examples/providers/README.md",
     "examples/thermostat/nxp/linux-se05x/README.md",
+    "examples/common/m5stack-tft/repo",
 ]
 
 
@@ -40,18 +41,21 @@
 html_favicon = "_static/images/favicon.ico"
 html_static_path = ["_static"]
 html_theme_options = {
-    "logo_only": True,
     "github_url": "https://github.com/project-chip/connectedhomeip",
     "repository_url": "https://github.com/project-chip/connectedhomeip",
     "use_edit_page_button": True,
     "repository_branch": "master",
     "path_to_docs": "docs",
+    "icon_links": [],
 }
 
 # -- Options for MyST --------------------------------------------------------
 
 myst_heading_anchors = 6
-suppress_warnings = ["myst.header", "myst.anchor"]
+suppress_warnings = [
+    "myst.header",
+    "myst.anchor",
+]
 myst_enable_extensions = ["html_image"]
 
 
@@ -66,6 +70,7 @@
     (MATTER_BASE, "examples/**/*.JPG"),
 ]
 external_content_link_prefixes = [
+    ".",
     "src/",
     r"\.vscode/",
     "CONTRIBUTING",
diff --git a/docs/examples/openiotsdk_examples.md b/docs/examples/openiotsdk_examples.md
@@ -241,7 +241,7 @@ ${MATTER_ROOT}/scripts/run_in_ns.sh ARMns ${MATTER_ROOT}/scripts/examples/openio
 ### Commissioning
 
 Once booted the application can be commissioned, please refer to
-[docs/guides/openiotsdk_commissioning.md](/../guides/openiotsdk_commissioning.md)
+[docs/guides/openiotsdk_commissioning.md](../guides/openiotsdk_commissioning.md)
 for further instructions.
 
 ## Testing
diff --git a/docs/guides/BUILDING.md b/docs/guides/BUILDING.md
@@ -107,6 +107,31 @@ Finally, reboot your RPi.
 If you want to install/use a different version, you may download one from the
 zap project [Releases](https://github.com/project-chip/zap/releases)
 
+### Linux ARM
+
+Zap does not provide binary releases for arm. Rosetta solves this for Darwin,
+however for linux arm you will have to use a local ZAP, generally through
+setting `$ZAP_DEVELOPMENT_PATH` (see the section `Which zap to use` below).
+
+The file `scripts/setup/zap.json` contains the version that CIPD would download,
+so you can download a compatible version from the zap project
+[Releases](https://github.com/project-chip/zap/releases). To checkout as source
+code the corresponding tag should exist in the zap
+[repository tags](https://github.com/project-chip/zap/tags) list.
+
+Example commands:
+
+```sh
+RUN set -x \
+    && mkdir -p /opt/zap-${ZAP_VERSION} \
+    && git clone https://github.com/project-chip/zap.git /opt/zap-${ZAP_VERSION} \
+    && cd /opt/zap-${ZAP_VERSION} \
+    && git checkout ${ZAP_VERSION} \
+    && npm config set user 0 \
+    && npm ci
+ENV ZAP_DEVELOPMENT_PATH=/opt/zap-${ZAP_VERSION}
+```
+
 ### Which ZAP to use
 
 ZAP scripting uses the following detection, in order:
diff --git a/docs/guides/mbedos_commissioning.md b/docs/guides/mbedos_commissioning.md
@@ -8,15 +8,15 @@
     -   [Building and installing](#building-and-installing)
     -   [Accessory Matter device setup](#accessory-matter-device-setup)
     -   [Device commissioning for Android](#device-commissioning-for-android)
-    -   [Sending ZCL commands](#sending-zcl-commands)
+    -   [Sending ZCL commands](#sending-zcl-commands-android)
 -   [POSIX CLI CHIPTool](#posix-cli-chiptool)
     -   [Building](#building)
     -   [Device commissioning for CLI](#device-commissioning-for-cli)
-    -   [Sending ZCL commands](#sending-zcl-commands-1)
+    -   [Sending ZCL commands](#sending-zcl-commands-posix)
 -   [Python Device Controller](#python-device-controller)
     -   [Building and installing](#building-and-installing-1)
     -   [Device commissioning for Python Device Controller](#device-commissioning-for-python-device-controller)
-    -   [Sending ZCL commands](#sending-zcl-commands-2)
+    -   [Sending ZCL commands](#sending-zcl-commands-python)
         -   [ZCL commands details](#zcl-commands-details)
 
 <hr>
@@ -137,7 +137,7 @@ steps:
 -   After successful completion of the process, the application returns to the
     main screen.
 
-### Sending ZCL commands
+### Sending ZCL commands Android
 
 After the accessory device has been successfully commissioned to the network, it
 is possible to communicate with it using IP. Matter uses Zigbee Cluster Library
@@ -179,7 +179,7 @@ Example:
 
     $ chip-tool pairing ble-wifi node_id_to_assign network_ssid network_password 20202021 3840
 
-### Sending ZCL commands
+### Sending ZCL commands POSIX
 
 If the commissioning process was successful, it is possible to send a ZCL
 command to the device which initiate a certain action.
@@ -232,7 +232,7 @@ To run the auto commissioning process via BLE:
 
         chip-device-ctrl > connect -ble 3840 20202021 1234
 
-### Sending ZCL commands
+### Sending ZCL commands Python
 
 If the commissioning process was successful, it is possible to send a ZCL
 command to the device which initiates a certain action.
diff --git a/examples/contact-sensor-app/nxp/k32w/k32w0/README.md b/examples/contact-sensor-app/nxp/k32w/k32w0/README.md
@@ -20,13 +20,13 @@ network.
     -   [Bluetooth LE Rendezvous](#bluetooth-le-rendezvous)
 -   [Device UI](#device-ui)
 -   [Building](#building)
-    -   [Known issues](#known-issues)
+    -   [Known issues buiulding](#known-issues-building)
 -   [Manufacturing data](#manufacturing-data)
 -   [Flashing and debugging](#flashing-and-debugging)
 -   [Pigweed Tokenizer](#pigweed-tokenizer)
     -   [Detokenizer script](#detokenizer-script)
     -   [Notes](#notes)
-    -   [Known issues](#known-issues-1)
+    -   [Known issues tokenizer](#known-issues-tokenizer)
 -   [NXP Ultrafast P256 ECC Library](#nxp-ultrafast-p256-ecc-library)
     -   [Building steps](#building-steps)
 -   [Tinycrypt ECC library](#tinycrypt-ecc-library)
@@ -36,10 +36,10 @@ network.
     -   [Writing the PSECT](#writing-the-psect)
     -   [Writing the application](#writing-the-application)
     -   [OTA Testing](#ota-testing)
-    -   [Known issues](#known-issues-2)
+    -   [Known issues ota](#known-issues-ota)
 -   [Low power](#low-power)
 
-    -   [Known issues](#known-issues-3)
+    -   [Known issues power](#known-issues-low-power)
 
 -   [Removing SSBL Upgrade region](#removing-ssbl-upgrade-region)
 
@@ -233,7 +233,7 @@ pycryptodome           3.9.8
 
 The resulting output file can be found in out/debug/chip-k32w0x-contact-example.
 
-## Known issues
+### Known issues building
 
 -   When using Secure element and cross-compiling on Linux, log messages from
     the Plug&Trust middleware stack may not echo to the console.
@@ -325,7 +325,7 @@ detokenizer script to see logs of a contact-sensor app:
 python3 ../../../../../examples/platform/nxp/k32w/k32w0/scripts/detokenizer.py serial -i /dev/ttyACM0 -d out/debug/chip-k32w0x-contact-example-database.bin -o device.txt
 ```
 
-### Known issues
+### Known issues tokenizer
 
 The building process will not update the token database if it already exists. In
 case that new strings are added and the database already exists in the output
@@ -531,7 +531,7 @@ Start the OTA process:
 user@computer1:~/connectedhomeip$ : ./out/chip-tool-app/chip-tool otasoftwareupdaterequestor announce-ota-provider 1 0 0 0 2 0
 ```
 
-## Known issues
+### Known issues ota
 
 -   SRP cache on the openthread border router needs to flushed each time a new
     commissioning process is attempted. For this, factory reset the device, then
@@ -595,7 +595,7 @@ below:
 Please note that that the Power Measurement Tool is not very accurate and
 professional tools must be used if exact power consumption needs to be known.
 
-## Known issues
+### Known issues low power
 
 -   Power Measurement Tool may not work correctly in MCUXpresso versions greater
     that 11.0.1.
diff --git a/examples/light-switch-app/nrfconnect/README.md b/examples/light-switch-app/nrfconnect/README.md
@@ -319,13 +319,13 @@ platform image.
 
     -   If pressed for less than 0.5 seconds, it changes the light state to the
         opposite one on the bound lighting device
-        ([lighting-app](../../lighting-app/nrfconnect/README.md))
+        [lighting-app](../../lighting-app/nrfconnect/README.md)
 
     -   If pressed for more than 0.5 seconds, it changes the brightness of the
         light on the bound lighting bulb device
-        ([lighting-app](../../lighting-app/nrfconnect/README.md)). The
-        brightness is changing from 0% to 100% with 1% increments every 300
-        milliseconds as long as **Button 2** is pressed.
+        [lighting-app](../../lighting-app/nrfconnect/README.md). The brightness
+        is changing from 0% to 100% with 1% increments every 300 milliseconds as
+        long as **Button 2** is pressed.
 
 -   On nRF7002 DK:
 
@@ -665,7 +665,7 @@ communicate with each other.
 
 To perform binding, you need a controller that can write the binding table to
 the light switch device and write proper ACL to the endpoint light bulb on the
-[Lighting Example application](../../lighting-app/nrfconnect/README.md)). For
+[Lighting Example application](../../lighting-app/nrfconnect/README.md). For
 example, you can use the
 [CHIP Tool for Windows or Linux](../../chip-tool/README.md) as the controller.
 The ACL should contain information about all clusters that can be called by the
diff --git a/examples/lighting-app/nxp/k32w/k32w0/README.md b/examples/lighting-app/nxp/k32w/k32w0/README.md
@@ -22,13 +22,13 @@ network.
     -   [Bluetooth LE Rendezvous](#bluetooth-le-rendezvous)
 -   [Device UI](#device-ui)
 -   [Building](#building)
-    -   [Known issues](#known-issues)
+    -   [Known issues](#known-issues-building)
 -   [Manufacturing data](#manufacturing-data)
 -   [Flashing and debugging](#flashing-and-debugging)
 -   [Pigweed Tokenizer](#pigweed-tokenizer)
     -   [Detokenizer script](#detokenizer-script)
     -   [Notes](#notes)
-    -   [Known issues](#known-issues-1)
+    -   [Known issues](#known-issues-tokenizer)
 -   [NXP Ultrafast P256 ECC Library](#nxp-ultrafast-p256-ecc-library)
     -   [Building steps](#building-steps)
 -   [Tinycrypt ECC library](#tinycrypt-ecc-library)
@@ -38,7 +38,7 @@ network.
     -   [Writing the PSECT](#writing-the-psect)
     -   [Writing the application](#writing-the-application)
     -   [OTA Testing](#ota-testing)
-    -   [Known issues](#known-issues-2)
+    -   [Known issues](#known-issues-ota)
         </hr>
 
 ## Introduction
@@ -246,7 +246,7 @@ pycryptodome           3.9.8
 
 The resulting output file can be found in out/debug/chip-k32w0x-light-example.
 
-## Known issues
+## Known issues building
 
 -   When using Secure element and cross-compiling on Linux, log messages from
     the Plug&Trust middleware stack may not echo to the console.
@@ -338,7 +338,7 @@ detokenizer script to see logs of a lighting app:
 python3 ../../../../../examples/platform/nxp/k32w/k32w0/scripts/detokenizer.py serial -i /dev/ttyACM0 -d out/debug/chip-k32w0x-light-example-database.bin -o device.txt
 ```
 
-### Known issues
+### Known issues tokenizer
 
 The building process will not update the token database if it already exists. In
 case that new strings are added and the database already exists in the output
@@ -544,7 +544,7 @@ Start the OTA process:
 user@computer1:~/connectedhomeip$ : ./out/chip-tool-app/chip-tool otasoftwareupdaterequestor announce-ota-provider 1 0 0 0 2 0
 ```
 
-## Known issues
+## Known issues ota
 
 -   SRP cache on the openthread border router needs to flushed each time a new
     commissioning process is attempted. For this, factory reset the device, then
diff --git a/examples/lock-app/nxp/k32w/k32w0/README.md b/examples/lock-app/nxp/k32w/k32w0/README.md
@@ -22,20 +22,20 @@ network.
     -   [Bluetooth LE Rendezvous](#bluetooth-le-rendezvous)
 -   [Device UI](#device-ui)
 -   [Building](#building)
-    -   [Known issues](#known-issues)
+    -   [Known issues](#known-issues-building)
 -   [Manufacturing data](#manufacturing-data)
 -   [Flashing and debugging](#flashing-and-debugging)
 -   [Pigweed Tokenizer](#pigweed-tokenizer)
     -   [Detokenizer script](#detokenizer-script)
     -   [Notes](#notes)
-    -   [Known issues](#known-issues-1)
+    -   [Known issues](#known-issues-tokenizer)
 -   [NXP Ultrafast P256 ECC Library](#nxp-ultrafast-p256-ecc-library)
     -   [Building steps](#building-steps)
 -   [Tinycrypt ECC library](#tinycrypt-ecc-library)
     -   [Building steps](#building-steps-1)
 -   [Low power](#low-power)
 
-    -   [Known issues](#known-issues-2)
+    -   [Known issues](#known-issues-low-power)
 
     </hr>
 
@@ -219,7 +219,7 @@ pycryptodome           3.9.8
 
 The resulting output file can be found in out/debug/chip-k32w0x-lock-example.
 
-## Known issues
+## Known issues building
 
 -   When using Secure element and cross-compiling on Linux, log messages from
     the Plug&Trust middleware stack may not echo to the console.
@@ -311,7 +311,7 @@ detokenizer script to see logs of a lock app:
 python3 ../../../../../examples/platform/nxp/k32w/k32w0/scripts/detokenizer.py serial -i /dev/ttyACM0 -d out/debug/chip-k32w0x-lock-example-database.bin -o device.txt
 ```
 
-### Known issues
+### Known issues tokenizer
 
 The building process will not update the token database if it already exists. In
 case that new strings are added and the database already exists in the output
@@ -382,7 +382,7 @@ below:
 Please note that that the Power Measurement Tool is not very accurate and
 professional tools must be used if exact power consumption needs to be known.
 
-## Known issues
+## Known issues low power
 
 -   Power Measurement Tool may not work correctly in MCUXpresso versions greater
     that 11.0.1.
