From 0062c5d6f3c1eee6a14696132f3e5b7b8f6744ee Mon Sep 17 00:00:00 2001 From: Andrei Litvin Date: Thu, 2 Mar 2023 12:20:44 -0500 Subject: [PATCH] Add instructions on setting up zap for ARM linux (#25431) * 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 --- README.md | 2 +- docs/Makefile | 2 +- docs/conf.py | 9 +++++-- docs/examples/openiotsdk_examples.md | 2 +- docs/guides/BUILDING.md | 25 +++++++++++++++++++ docs/guides/mbedos_commissioning.md | 12 ++++----- .../nxp/k32w/k32w0/README.md | 16 ++++++------ .../light-switch-app/nrfconnect/README.md | 10 ++++---- .../lighting-app/nxp/k32w/k32w0/README.md | 12 ++++----- examples/lock-app/nxp/k32w/k32w0/README.md | 12 ++++----- 10 files changed, 66 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 5cee1dc72ded9a..03e41c39f2b448 100644 --- 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 index 0d2d810e4769da..aca7a0f6cbd7de 100644 --- 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 index c43a62c4e9399b..63bfb3ee050384 100644 --- 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 index 6cdca9c5a8fdf1..91bb27ffa9f13c 100644 --- 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 index 9c32da51038047..662ccebdf4c763 100644 --- 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 index 16a047f8d8b394..8b6987878aacb8 100644 --- 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)
@@ -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 index 3b2e2612f0126b..61fae7101ca5a3 100644 --- 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 index 4c3f7bcfa21b6d..a446c2b3bc42b8 100644 --- 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 index 61bc38f96fa920..a4e59c92352b15 100644 --- 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) ## 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 index 85a99f8e4e8554..e08b43baf5e48f 100644 --- 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) @@ -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.