diff --git a/.buildinfo b/.buildinfo new file mode 100644 index 000000000000..541fc1ba96d6 --- /dev/null +++ b/.buildinfo @@ -0,0 +1,4 @@ +# Sphinx build info version 1 +# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. +config: 672e07c8e9ea26d1c75940f68632e6f3 +tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/.nojekyll b/.nojekyll new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/BUG_REPORT.html b/BUG_REPORT.html new file mode 100644 index 000000000000..3a7ad7f571a7 --- /dev/null +++ b/BUG_REPORT.html @@ -0,0 +1,1079 @@ + + + + + + + + + + + + Reporting bugs — Matter documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + +
+
+
+
+ + + Ctrl+K +
+
+ + + +
+
+ +
+ + + +
+ + + + +
+ +
+
+ + + +
+
+
+
+ + +
+
+ + + + +
+ +
+ + + +
+ +
+
+ +
+
+ +
+ +
+ +
+ + +
+ +
+ +
+ + + + + + + + + + + + + + + + +
+ + +
+ + + + + + + + + + + + + +
+ +
+ +
+
+ + + +
+

Reporting bugs

+ +
+ +
+
+ + + + +
+ +
+

Reporting bugs#

+
+

Writing an effective bug report#

+

When reporting a bug, start with the question +What does a bug report need to tell the developer.

+

Generally you want the following parts covered:

+
    +

  • What is the problem

    • +

  • How can the developer reproduce the problem (to see it for themselves), to +bisect when it was introduced or to find if it got fixed already.

    • +

  • At what point does the problem occur

    • +

  • What environment did this occur in

    • +
+

Make sure the above items are covered and the bug is easy to review and parse:

+
    +

  • Title should clearly describe the problem. Bugs are often sorted from +the issue list which only contains the title

    • +

  • Logs should generally be attachments (drag & drop or click on bottom bar +when entering issue text) and not inline with the issue.

    • +

  • Reproduction steps and environment should be clearly highlighted. If +running commands reproduce the issue (very common), the commands should be +in a code block/script format.

    • +
+
+

Describing the problem#

+

Make sure the issue is obvious or provide a link explaining why the expected +result is not met.

+

Examples:

+
    +

  • (Core dump) seen is obvious since there should be no core dumps

    • +

  • Failure trying to read attribute X in cluster Y which is marked MANDATORY in the spec +references the spec and describes why attribute read should succeed.

    • +

  • Failure trying to write attribute X in cluster Y, which is enabled since cluster FeatureMap enabled X and spec describes as writable. +references the spec and explicitly states that an optional attribute is +enabled based on device status

    • +

  • Running certification test TC-A-B-C (link included) fails at step 3: test case asks for command to succeed, I get ACCESS_DENIED instead +describes a pre-defined test case that is expected to pass but fails. Note +that full link to the test description is needed (and should be covered by +‘how to reproduce’ part)

    • +
+

Unless manually curated (e.g. few lines showing the problem), logs should be +always attachments and not inlined in the bug as the make the bug report too +long.

+
+
+

Reproduction steps and when does the issue occur#

+

Include all steps needed to reproduce the problem. Link any supporting +documentation.

+

If stating something of the form TC-A-B-C step 4 fails then there should be a +link to TC-A-B-C and ideally a list of the commands of each step since test +cases may change over time.

+

The bug report should contain all the information for a developer to reproduce +the issue without needing to have access to CHIP Test case repository (not +everyone does)

+
+
+

Environment for reproduction#

+

Assume that the developer will want to reproduce the issue and will try to +mirror your environment to a reasonable degree. For this, at a minimum the +platforms on which everything is running is needed.

+

Try to provide as much information as seems relevant. At a minimum this could +look like +Failed to commission nrf board using chip-tool running on linux. Used build on SHA abcde.... +This provides basic information (use nrf board, use chip-tool on linux, default +build) to get started. Beyond that, you can refine if more items seem relevant:

+
    +

  • Tested on TE9 or Tested on interop branch xyz gives a build reference +point. Useful when branches/tags are used instead of master branch as +development happens on master branch.

    • +

  • Thread devices fail, tested with qpg and efr32 shows that this seems to be +a general thread issue and developer can investigate on multiple of them

    • +
+
    +

  • Tested with avahi-build and it passes/fails helps the developer with +information of non-default builds that pass/fail to narrow down the problem

    • +

  • Passes with darwin-framework-tool and repl but fails with chip-tool helps +the developer in narrowing down the problem

    • +
+
+
+

Additional information#

+

Providing additional information that can be helpful is encouraged. Each bug +report is different here. Some examples:

+
    +

  • This worked last week (around Jan 5) but started failing in recent master builds

    • +

  • Specification changed this attribute from optional to mandatory so this may be the cause of the issue

    • +

  • This issue may be related to #1234 as the same error is seen, however the reproduction steps seemed distinct enough that I opened a new issue

    • +

  • While running this, I observed 100% CPU before the operation finally timed out

    • +

  • While running this test, I observed device under test rebooting, logs attached.

    • +

  • This only happens intermittently - I see it about 30% of the time

    • +
+
+
+
+ + +
+ + + + + + + + +
+ + + +
+ +
+
+ Contents +
+
+ +
+ + +
+ + + +
+
+
+ + + + + + + + \ No newline at end of file diff --git a/PROJECT_FLOW.html b/PROJECT_FLOW.html new file mode 100644 index 000000000000..b476d001036e --- /dev/null +++ b/PROJECT_FLOW.html @@ -0,0 +1,1073 @@ + + + + + + + + + + + + Matter Project Flow — Matter documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + +
+
+
+
+ + + Ctrl+K +
+
+ + + +
+
+ +
+ + + +
+ + + + +
+ +
+
+ + + +
+
+
+
+ + +
+
+ + + + +
+ +
+ + + +
+ +
+
+ +
+
+ +
+ +
+ +
+ + +
+ +
+ +
+ + + + + + + + + + + + + + + + +
+ + +
+ + + + + + + + + + + + + +
+ +
+ +
+
+ + + +
+

Matter Project Flow

+ +
+ +
+
+ + + + +
+ +
+

Matter Project Flow#

+

This section is intended to cover how Matter uses GitHub Projects, Issues, +Milestones, Releases, and Branches for program/project management in the code +repository.

+
+

Issues#

+

Matter uses issues as simple problem descriptions or feature requests. In +general, all work contributed to the repository in the form of pull requests +(PR) should be under the auspices of some open issue. This may seem onerous and +in some cases duplicative, so consider these guidelines when deciding whether +you can get away with not creating an issue:

+
    +

  • Trivial fixes: issues can function as TODO lists, simple reminders that +something should be addressed. Sometimes, though, the work required to fix +is smaller than the work required to write the issue.

    • +

  • Issues intended to be addressed by a PR may not actually be fixed or may +regress.

    • +

  • Issues can span PRs (as PRs should be as small as possible, but no smaller).

    • +

  • Issues help form an important basis for release notes. Any PR that addresses +a problem that should have release visibility, please do open an issue.

    • +
+
+
+

Pull requests#

+

Pull requests should be small and address a single, specific change to the code +base. They should be easy to review, as a “yes, that’s better”. Refrain from +requesting review until all PR checks have completed successfully, lest you tire +your reviewers.

+

PR Don’ts:

+
    +

  • Don’t combine unrelated changes. E.g. if the PR addresses a bug in some C +code, an update to the top-level .gitignore doesn’t belong.

    • +

  • Don’t make stacks. E.g. if a change in a component requires a new feature or +even a small tweak in one or more of its dependencies, each dependency +change belongs in its own separate PR.

    • +
+
+
+

Milestones#

+

In Matter parlance, a milestone is simply a tag for an expected due date or +release. Milestones are intended to help contributors and their managers to +prioritize work. There are 2 types: Date-based and Release-based.

+
+

Date-based#

+

Date-based milestones are named for their due date, typically a Friday of some +week. Date-based milestones are normally assigned based on a guess about when +something’s likely to bubble up and get done based on current work load and +resourcing. They are wishes, guesses.

+
+
+

Release-based#

+

Release-based milestones are named for the release version and may have flexible +or subject-to-change due dates. Release-based milestones are intended to track +release blockers.

+

A special “Not sure when” milestone is a marker for issues whose priority, +scope, or blocking status have not been determined. Monthly review of these is a +project goal.

+

Issues without milestones are those that have yet to be considered for one of +the above. Weekly review of new issues is a project goal.

+
+
+
+

Projects#

+

Projects are collections of issues, pull requests, and notes intended to capture +larger efforts that don’t fit in issues, have multiple-subsystems involved, or +may span multiple milestones. We use projects 2 ways:

+
    +

  1. To track burn down on a larger task. When constructing such a project, it’s +important to think in terms of something that will eventually have an end, +i.e. a definite scope.

    2. +

  2. To categorize issues, denote broader efforts without a definite time scope. +These projects might reflect or show burndown or percent complete, but are +mostly used to view where effort is going.

    3. +
+

Issues can belong to any number of projects, but should generally only belong to +one of the task-tracking projects (the first type).

+
+
+

Branches, releases, and general development flow#

+

Master should always be Matter’s best branch. Release branches, once cut, are +closed for any feature work. Software fixes for release branches must first land +on master unless demonstrably infeasible.

+
+
+ + +
+ + + + + + + + +
+ + + +
+ +
+
+ Contents +
+
+ +
+ + +
+ + + +
+
+
+ + + + + + + + \ No newline at end of file diff --git a/README.html b/README.html new file mode 100644 index 000000000000..995a07592130 --- /dev/null +++ b/README.html @@ -0,0 +1,1230 @@ + + + + + + + + + + + + Matter — Matter documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + +
+
+
+
+ + + Ctrl+K +
+
+ + + +
+
+ +
+ + + +
+ + + + +
+ +
+
+ + + +
+
+
+
+ + +
+
+ + + + +
+ +
+ + + +
+ +
+
+ +
+
+ +
+ +
+ +
+ + +
+ +
+ +
+ + + + + + + + + + + + + + + + +
+ + +
+ + + + + + + + + + + + + +
+ +
+ +
+
+ + + +
+

Matter

+ +
+ +
+
+ + + + +
+ +
+

Matter#

+

Builds

+

Builds

+

Android +Ameba +ASR +BouffaloLab +Darwin +TI CC26X2X7 +TI CC32XX +EFR32 +ESP32 +Infineon +i.MX Linux +K32W with SE051 +Linux ARM +Linux Standalone +Linux Standalone +Mbed OS +MW320 +nRF Connect SDK +Open IoT SDK +QPG +STM32 +Telink +Tizen

+

Tests

+

Unit / Integration Tests +Cirque +QEMU

+

Tools

+

ZAP Templates

+

Documentation

+

Documentation Build

+ +
+
+

About#

+

Matter (formerly Project CHIP) creates more connections between more objects, +simplifying development for manufacturers and increasing compatibility for +consumers, guided by the Connectivity Standards Alliance.

+
+
+

What is Matter?#

+

Matter is a unified, open-source application-layer connectivity standard built +to enable developers and device manufacturers to connect and build reliable, and +secure ecosystems and increase compatibility among connected home devices. It is +built with market-proven technologies using Internet Protocol (IP) and is +compatible with Thread and Wi-Fi network transports. Matter was developed by a +Working Group within the Connectivity Standards Alliance (Alliance). This +Working Group develops and promotes the adoption of the Matter standard, a +royalty-free connectivity standard to increase compatibility among smart home +products, with security as a fundamental design tenet. The vision that led major +industry players to come together to build Matter is that smart connectivity +should be simple, reliable, and interoperable.

+

Matter simplifies development for manufacturers and increases compatibility for +consumers.

+

The standard was built around a shared belief that smart home devices should be +secure, reliable, and seamless to use. By building upon Internet Protocol (IP), +Matter enables communication across smart home devices, mobile apps, and cloud +services and defines a specific set of IP-based networking technologies for +device certification.

+

The Matter specification details everything necessary to implement a Matter +application and transport layer stack. It is intended to be used by implementers +as a complete specification.

+

The Alliance officially opened the Matter Working Group on January 17, 2020, and +the specification is +available +for adoption now.

+

Visit buildwithmatter.com to learn more and read +the latest news and updates about the project.

+
+
+

Project Overview#

+
+

Development Goals#

+

Matter is developed with the following goals and principles in mind:

+

Unifying: Matter is built with and on top of market-tested, existing +technologies.

+

Interoperable: The specification permits communication between any +Matter-certified device, subject to users’ permission.

+

Secure: The specification leverages modern security practices and protocols.

+

User Control: The end user controls authorization for interaction with +devices.

+

Federated: No single entity serves as a throttle or a single point of +failure for root of trust.

+

Robust: The set of protocols specifies a complete lifecycle of a device — +starting with the seamless out-of-box experience, through operational protocols, +to device and system management specifications required for proper function in +the presence of change.

+

Low Overhead: The protocols are practically implementable on low +compute-resource devices, such as MCUs.

+

Pervasive: The protocols are broadly deployable and accessible, by +leveraging IP and being implementable on low-capability devices.

+

Ecosystem-Flexible: The protocol is flexible enough to accommodate +deployment in ecosystems with differing policies.

+

Easy to Use: The protocol provides smooth, cohesive, integrated provisioning +and out-of-box experience.

+

Open: The Project’s design and technical processes are open and transparent +to the general public, including non-members wherever possible.

+
+
+

Architecture Overview#

+

Matter aims to build a universal IPv6-based communication protocol for smart +home devices. The protocol defines the application layer that will be deployed +on devices and the different link layers to help maintain interoperability. The +following diagram illustrates the normal operational mode of the stack: +Matter Architecture Overview

+

The architecture is divided into layers to help separate the different +responsibilities and introduce a good level of encapsulation among the various +pieces of the protocol stack. The vast majority of interactions flow through the +stack captured in the following Figure:

+

Matter Stack Architecture

+
    +

  1. Application: High-order business logic of a device. For example, an +application that is focused on lighting might contain logic to handle turning +on/off the bulb as well as its color characteristics.

    2. +
+
    +

  1. Data Model: The data layer corresponds to the data and verb elements that +help support the functionality of the application. The Application operates +on these data structures when there is an intent to interact with the device.

    2. +
+
    +

  1. Interaction Model: The Interaction Model layer defines a set of +interactions that can be performed between a client and server device. For +example, reading or writing attributes on a server device would correspond to +application behavior on the device. These interactions operate on the +elements defined at the data model layer.

    2. +
+
    +

  1. Action Framing: Once an action is constructed using the Interaction +Model, it is serialized into a prescribed packed binary format to encode for +network transmission.

    2. +
+
    +

  1. Security: An encoded action frame is then sent down to the Security Layer +to encrypt and sign the payload to ensure that data is secured and +authenticated by both sender and receiver of a packet.

    2. +

  2. Message Framing & Routing: With an interaction encrypted and signed, the +Message Layer constructs the payload format with required and optional header +fields; which specify the message’s properties and some routing information.

    3. +
+
    +

  1. IP Framing & Transport Management: After the final payload has been +constructed, it is sent to the underlying transport protocol for IP +management of the data.

    2. +
+
+
+
+

Current Status of Matter#

+

Matter’s design and technical processes are intended to be open and transparent +to the general public, including to Working Group non-members wherever possible. +The availability of this GitHub repository and its source code under an Apache +v2 license is an important and demonstrable step to achieving this commitment. +Matter endeavors to bring together the best aspects of market-tested +technologies and redeploy them as a unified and cohesive whole-system solution. +The overall goal of this approach is to bring the benefits of Matter to +consumers and manufacturers as quickly as possible. As a result, what you +observe in this repository is an implementation-first approach to the technical +specification, vetting integrations in practice. The Matter repository is +growing and evolving to implement the overall architecture. The repository +currently contains the security foundations, message framing and dispatch, and +an implementation of the interaction model and data model. The code examples +show simple interactions, and are supported on multiple transports – Wi-Fi and +Thread – starting with resource-constrained (i.e., memory, processing) silicon +platforms to help ensure Matter’s scalability.

+
+
+

How to Contribute#

+

We welcome your contributions to Matter. Read our contribution guidelines +here.

+
+
+

Building and Developing in Matter#

+

Instructions about how to build Matter can be found here .

+
+
+

Directory Structure#

+

The Matter repository is structured as follows:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

File/Folder

Content

build

Build system support content and built output directories

build_overrides

Build system parameter customization for different platforms

config

Project configurations

credentials

Development and test credentials

docs

Documentation, including guides. Visit the Matter SDK documentation page to read it.

examples

Example firmware applications that demonstrate use of Matter

integrations

3rd party integrations

scripts

Scripts needed to work with the Matter repository

src

Implementation of Matter

third_party

3rd party code used by Matter

zzz_generated

ZAP generated template code - Revolving around cluster information

BUILD.gn

Build file for the GN build system

CODE_OF_CONDUCT.md

Code of conduct for Matter and contribution to it

CONTRIBUTING.md

Guidelines for contributing to Matter

LICENSE

Matter license file

REVIEWERS.md

PR reviewers

gn_build.sh

Build script for specific projects such as Android, EFR32, etc.

README.md

This file

+
+
+

License#

+

Matter is released under the Apache 2.0 license.

+
+ + +
+ + + + + + +
+ +
+
+
+ +
+ + + +
+ +
+
+ Contents +
+
+ +
+ + +
+ + + +
+
+
+ + + + + + + + \ No newline at end of file diff --git a/VSCODE_DEVELOPMENT.html b/VSCODE_DEVELOPMENT.html new file mode 100644 index 000000000000..46d6cc877a17 --- /dev/null +++ b/VSCODE_DEVELOPMENT.html @@ -0,0 +1,1175 @@ + + + + + + + + + + + + Visual Studio Code Development — Matter documentation + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + + + +
+
+
+
+ + + Ctrl+K +
+
+ + + +
+
+ +
+ + + +
+ + + + +
+ +
+
+ + + +
+
+
+
+ + +
+
+ + + + +
+ +
+ + + +
+ +
+
+ +
+
+ +
+ +
+ +
+ + +
+ +
+ +
+ + + + + + + + + + + + + + + + +
+ + +
+ + + + + + + + + + + + + +
+ +
+ +
+
+ + + +
+

Visual Studio Code Development

+ +
+ +
+
+ + + + +
+ +
+

Visual Studio Code Development#

+

Visual Studio Code is a great and simple IDE +that can be used to build & develop with for Matter.

+

Matter supports the docker / remote container workflow in Visual Studio Code, +and has a container environment setup automatically. You can read more about +this workflow here.

+

Tested on:

+
    +

  • macOS 10.5

    • +

  • Windows 10 Pro + WSL + Ubuntu 18 LTS

    • +

  • Linux - Fedora Core 35 distribution

    • +
+
+

Setup Steps#

+
    +

  1. Windows Only Enable the Windows Subsystem for Linux (WSL) following +instructions here: +https://docs.microsoft.com/en-us/windows/wsl/install-win10

    2. +

  2. Windows Only Install Ubuntu from the Windows App Store here: +https://www.microsoft.com/en-us/p/ubuntu-1804-lts/9n9tngvndl3q

    3. +

  3. Install Docker for your operating system of choice +from here: https://docs.docker.com/engine/install

    4. +

  4. Install Visual Studio Code for your +operating system of choice here: https://code.visualstudio.com/Download

    5. +

  5. Install Git if you haven’t already

    6. +

  6. Windows Only Enable git to use LF instead of CLRF by default: +git config --global core.autocrlf false

    7. +

  7. Git clone the main Matter repository here: +project-chip/connectedhomeip

    8. +

  8. Launch Visual Studio Code, and open the cloned folder from above

    9. +

  9. Install the +Dev Containers +extension for Visual Studio Code, this extension allows you to use docker +containers as a development backend.

    10. +

  10. Once this is installed, you’ll be prompted to reload Visual Studio Code, do +so

    11. +

  11. At the bottom right of your Visual Studio Code window you should have a new +box prompting you to re-open the window as a container. Hit yes.

    12. +

  12. Windows Only Update your Visual Studio Code settings as documented here: +https://code.visualstudio.com/docs/editor/integrated-terminal#_configuration +to use Bash on Ubuntu (on Windows) eg: +"terminal.integrated.shell.windows": "C:\\Windows\\System32\\bash.exe"

    13. +

  13. Now your local machine is building a docker image that has all the tools +necessary to build and test Matter. This can take some time, but will +eventually complete and open up the source tree

    14. +
+
+
+

Bootstrapping your source tree (one time)#

+
    +

  1. Under the “Terminal” menu (or using another shortcut to the same tool), +select “Run Task…”

    2. +

  2. Select the “Bootstrap” task

    3. +
+
+
+

Building the Source Tree#

+
    +

  1. Under the “Terminal” menu select “Run Build Task…”

    2. +
+
+
+

Tasks#

+

Located in the tasks json file you’ll find a list of +tasks that can be run from the “Run Task…” command. Example tasks are “Clean”, +“Run Pretty Check”

+

Developers are encouraged to add tasks to the +tasks json over time to make sure everyone is using the +same base configuration and build.

+
+

Current base tasks are listed here#

+
    +

  • Main Build - Build the default configuration (i.e., Linux OpenSSL)

    • +

  • Run Unit and Functional Tests - Test the default configuration

    • +

  • Build & Test (all) - Build & Test various configurations (Linux variants, +Android, EFR32)

    • +

  • Update compilation database - Update the database used by IntelliSense +(needed for cross references, completion)

    • +

  • Bootstrap - On a clean tree, pull in the third party dependencies required

    • +

  • Clean Output - Remove build artifacts

    • +

  • Clean Tree - Full (and destructive) git clean of the tree

    • +
+
+
+
+

Launch Tasks#

+

Located in the launch json file you’ll find a list of +build & run jobs that can be run from the “Run” tab and start a run or debug +session.

+

Developers are encouraged to add tasks to the +launch json over time to make sure everyone is using +the same base debugging setup.

+
+
+

Submitting a Pull Request - Practical Advice#

+
+

Before submitting a PR, make sure these commands run and succeed#

+
    +

  • Run task: “Build & Test (all)”

    • +
+
+
+
+

Common Issues#

+ +
+
+

Docker FAQ#

+
+

DNS problem: can’t resolve archive.ubuntu.com#

+

A common problem encountered is that a container can’t resolve +archive.ubuntu.com and can’t install anything via apt-get, during the +creation of the container image, resulting in an error like:

+
E: Package 'locales' has no installation candidate
+The command '/bin/sh -c apt-get install -y locales && localedef -i en_US -c -f UTF-8 -A /usr/share/locale/locale.alias en_US.UTF-8' returned a non-zero code: 100
+
+
+

Most common reason for this is that the DNS for docker daemon has not been set +up correctly and is simply using a default: 8.8.8.8, which in many corporate or +more secure environments is not accessible. A typical solution for this is to +put a following key/value into your system-wide docker daemon.json (Typically +located under /etc/docker/daemon.json on a Linux system):

+
"dns": ["<<IP ADDRESS OF YOUR NAMESERVER>>", "8.8.8.8"]
+
+
+

You can obtain the address you should put into that line of your nameserver by +running:

+
nmcli dev show | grep 'IP4.DNS'
+
+
+

After you update the dns, you should restart docker, specific to your system. On +a typical Linux workstation, you do this via:

+
sudo service docker restart
+
+
+

Alternatively, you can also pass the --dns argument to your docker daemon, but +creating a daemon.json and following the above method will solve the problem +system-wide.

+
+
+
+

Visual Studio Code FAQ#

+ +
+ +
+ + +
+ + + + + + + + +
+ + + +
+ +
+
+ Contents +
+
+ +
+ + +
+ + + +
+
+
+ + + + + + + + \ No newline at end of file diff --git a/_images/CHIPTool_device_commissioned.png b/_images/CHIPTool_device_commissioned.png new file mode 100644 index 000000000000..8756b4dbf6b0 Binary files /dev/null and b/_images/CHIPTool_device_commissioned.png differ diff --git a/_images/IMX-RT1170-EVK-TOP.jpg b/_images/IMX-RT1170-EVK-TOP.jpg new file mode 100644 index 000000000000..a5dc1619edca Binary files /dev/null and b/_images/IMX-RT1170-EVK-TOP.jpg differ diff --git a/_images/Logo_RGB_H-small.png b/_images/Logo_RGB_H-small.png new file mode 100644 index 000000000000..d9f2c9570c14 Binary files /dev/null and b/_images/Logo_RGB_H-small.png differ diff --git a/_images/MIMXRT1060-EVKB-TOP.png b/_images/MIMXRT1060-EVKB-TOP.png new file mode 100644 index 000000000000..1e9fbff94c97 Binary files /dev/null and b/_images/MIMXRT1060-EVKB-TOP.png differ diff --git a/_images/Matter_Arch_Overview.png b/_images/Matter_Arch_Overview.png new file mode 100644 index 000000000000..6521fa71ad45 Binary files /dev/null and b/_images/Matter_Arch_Overview.png differ diff --git a/_images/Matter_Layered_Arch.png b/_images/Matter_Layered_Arch.png new file mode 100644 index 000000000000..38ad03ef437f Binary files /dev/null and b/_images/Matter_Layered_Arch.png differ diff --git a/_images/RVC_app_state_diagram.png b/_images/RVC_app_state_diagram.png new file mode 100644 index 000000000000..dcef2ed731f1 Binary files /dev/null and b/_images/RVC_app_state_diagram.png differ diff --git a/_images/SDK_layers.png b/_images/SDK_layers.png new file mode 100644 index 000000000000..84ecda721535 Binary files /dev/null and b/_images/SDK_layers.png differ diff --git a/_images/cc13x4_memmap.png b/_images/cc13x4_memmap.png new file mode 100644 index 000000000000..4442c6352efb Binary files /dev/null and b/_images/cc13x4_memmap.png differ diff --git a/_images/chiptool_main_screen.png b/_images/chiptool_main_screen.png new file mode 100644 index 000000000000..5720467a5c0a Binary files /dev/null and b/_images/chiptool_main_screen.png differ diff --git a/_images/cluster_attribute_read.png b/_images/cluster_attribute_read.png new file mode 100644 index 000000000000..5f073aca8067 Binary files /dev/null and b/_images/cluster_attribute_read.png differ diff --git a/_images/cluster_commands.png b/_images/cluster_commands.png new file mode 100644 index 000000000000..7df7a8a75412 Binary files /dev/null and b/_images/cluster_commands.png differ diff --git a/_images/cluster_initialization.png b/_images/cluster_initialization.png new file mode 100644 index 000000000000..9cf980e3f727 Binary files /dev/null and b/_images/cluster_initialization.png differ diff --git a/_images/debug0.png b/_images/debug0.png new file mode 100644 index 000000000000..6a594f4e0129 Binary files /dev/null and b/_images/debug0.png differ diff --git a/_images/debug01.png b/_images/debug01.png new file mode 100644 index 000000000000..e5b02cfe13f9 Binary files /dev/null and b/_images/debug01.png differ diff --git a/_images/debug1.png b/_images/debug1.png new file mode 100644 index 000000000000..b5a9ee59f3a5 Binary files /dev/null and b/_images/debug1.png differ diff --git a/_images/debug_k32w1.jpg b/_images/debug_k32w1.jpg new file mode 100644 index 000000000000..407c781220c4 Binary files /dev/null and b/_images/debug_k32w1.jpg differ diff --git a/_images/endpoint1_edit_pencil.png b/_images/endpoint1_edit_pencil.png new file mode 100644 index 000000000000..d10e63688229 Binary files /dev/null and b/_images/endpoint1_edit_pencil.png differ diff --git a/_images/endpoint_edit_type.png b/_images/endpoint_edit_type.png new file mode 100644 index 000000000000..10e0b78c6893 Binary files /dev/null and b/_images/endpoint_edit_type.png differ diff --git a/_images/esp-thread-border-router-board.png b/_images/esp-thread-border-router-board.png new file mode 100644 index 000000000000..fb2db7db60e5 Binary files /dev/null and b/_images/esp-thread-border-router-board.png differ diff --git a/_images/factory_data_overview.png b/_images/factory_data_overview.png new file mode 100644 index 000000000000..f2718ce708f8 Binary files /dev/null and b/_images/factory_data_overview.png differ diff --git a/_images/flash_driver.png b/_images/flash_driver.png new file mode 100644 index 000000000000..0e5ab136918c Binary files /dev/null and b/_images/flash_driver.png differ diff --git a/_images/flash_driver1.png b/_images/flash_driver1.png new file mode 100644 index 000000000000..610acab9043f Binary files /dev/null and b/_images/flash_driver1.png differ diff --git a/_images/form_web.JPG b/_images/form_web.JPG new file mode 100644 index 000000000000..a7b12111564d Binary files /dev/null and b/_images/form_web.JPG differ diff --git a/_images/frdm-mcxw71.jpg b/_images/frdm-mcxw71.jpg new file mode 100644 index 000000000000..a54f70f062c6 Binary files /dev/null and b/_images/frdm-mcxw71.jpg differ diff --git a/_images/gdbdebugger.png b/_images/gdbdebugger.png new file mode 100644 index 000000000000..ace1ff8c9bc9 Binary files /dev/null and b/_images/gdbdebugger.png differ diff --git a/_images/import-local-repository.png b/_images/import-local-repository.png new file mode 100644 index 000000000000..630e9f9545eb Binary files /dev/null and b/_images/import-local-repository.png differ diff --git a/_images/import-sdk-git.png b/_images/import-sdk-git.png new file mode 100644 index 000000000000..440db4359503 Binary files /dev/null and b/_images/import-sdk-git.png differ diff --git a/_images/import_demo.jpg b/_images/import_demo.jpg new file mode 100644 index 000000000000..6016c448a48e Binary files /dev/null and b/_images/import_demo.jpg differ diff --git a/_images/installed_sdks.jpg b/_images/installed_sdks.jpg new file mode 100644 index 000000000000..be3ad84380a8 Binary files /dev/null and b/_images/installed_sdks.jpg differ diff --git a/_images/integration_tests.png b/_images/integration_tests.png new file mode 100644 index 000000000000..dd83695cf201 Binary files /dev/null and b/_images/integration_tests.png differ diff --git a/_images/iwx612_2EL.jpg b/_images/iwx612_2EL.jpg new file mode 100644 index 000000000000..1482efefbc2f Binary files /dev/null and b/_images/iwx612_2EL.jpg differ diff --git a/_images/k32w-dk6-connectors.jpg b/_images/k32w-dk6-connectors.jpg new file mode 100644 index 000000000000..c4018fbd9bca Binary files /dev/null and b/_images/k32w-dk6-connectors.jpg differ diff --git a/_images/k32w-dk6.jpg b/_images/k32w-dk6.jpg new file mode 100644 index 000000000000..7c547b69a575 Binary files /dev/null and b/_images/k32w-dk6.jpg differ diff --git a/_images/k32w-se.jpg b/_images/k32w-se.jpg new file mode 100644 index 000000000000..691bffd8d395 Binary files /dev/null and b/_images/k32w-se.jpg differ diff --git a/_images/k32w1-evk.jpg b/_images/k32w1-evk.jpg new file mode 100644 index 000000000000..550f27433678 Binary files /dev/null and b/_images/k32w1-evk.jpg differ diff --git a/_images/matter_fabric_synchronization.png b/_images/matter_fabric_synchronization.png new file mode 100644 index 000000000000..95c99c4fe150 Binary files /dev/null and b/_images/matter_fabric_synchronization.png differ diff --git a/_images/matter_mbedos_overview_simplified.png b/_images/matter_mbedos_overview_simplified.png new file mode 100644 index 000000000000..065a5b7a44e1 Binary files /dev/null and b/_images/matter_mbedos_overview_simplified.png differ diff --git a/_images/matter_nrfconnect_overview_simplified_ncs.svg b/_images/matter_nrfconnect_overview_simplified_ncs.svg new file mode 100644 index 000000000000..21316c04f125 --- /dev/null +++ b/_images/matter_nrfconnect_overview_simplified_ncs.svg @@ -0,0 +1,314 @@ + + + + + + + + Page-1 + + Sheet.3186 + User application + + User application + + Sheet.3188 + Thread stack (OpenThread) + + Thread stack (OpenThread) + + Sheet.3189 + + + + Sheet.3192 + Zephyr integration + + Zephyr integration + + Sheet.3194 + nRF IEEE 802.15.4 radio driver + + nRF IEEE 802.15.4 radio driver + + Sheet.3195 + + + + Sheet.3196 + + + + Sheet.3197 + Zephyr network layer + + Zephyr network layer + + Sheet.3198 + UDP + + UDP + + Sheet.3200 + TCP + + TCP + + Sheet.3202 + IPv6 + + IPv6 + + Sheet.3203 + + + + Sheet.3204 + Drivers and modules + + Drivers and modules + + Sheet.3205 + Crypto backends + + Crypto backends + + Sheet.3206 + NFC + + NFC + + Sheet.3207 + DFU + + DFU + + Sheet.3208 + Partition Manager + + Partition Manager + + Sheet.3209 + Zephyr APIs + + Zephyr APIs + + Sheet.3210 + Driver API + + Driver API + + Sheet.3211 + Crypto API + + Crypto API + + Sheet.3212 + Zephyr RTOS kernel + + Zephyr RTOS kernel + + Sheet.3213 + MCU bootloader + + MCU bootloader + + Sheet.3214 + mbedTLS + + mbedTLS + + Sheet.3226 + + + + Sheet.3228 + SoftDevice Controller + + SoftDevice Controller + + Sheet.3235 + Bluetooth® LE stack + + Bluetooth® LE stack + + Sheet.3241 + Matter stack + + Matter stack + + Sheet.3242 + Zephyr integration layer + + Zephyr integration layer + + Sheet.3227 + Zephyr host + + Zephyr host + + Sheet.3229 + L2CAP + + L2CAP + + Sheet.3230 + GATT + + GATT + + Sheet.3231 + ATT + + ATT + + Sheet.3232 + GAP + + GAP + + Sheet.3233 + + + + Sheet.3234 + SMP + + SMP + + Nordic Light Grey + + + + Sheet.3290 + + Sheet.3271 + + + + Sheet.3282 + Matter (built with GN) + + Matter (built with GN) + + + Sheet.3293 + + Sheet.3220 + + + + Sheet.3278 + Nordic component + + Nordic component + + + Sheet.3294 + + Sheet.3222 + + + + Sheet.3276 + Zephyr + + Zephyr + + + Sheet.3295 + + Sheet.3223 + + + + Sheet.3274 + nRF Connect SDK + + nRF Connect SDK + + + Sheet.3298 + + + + Sheet.3319 + + + + Sheet.3308 + Wi-Fi driver + + Wi-Fi driver + + Sheet.3318 + + + + Sheet.3309 + wpa_supplicant + + wpa_supplicant + + Sheet.3311 + + Sheet.3312 + + + + Sheet.3313 + Third-party + + Third-party + + + Sheet.3314 + Wi-Fi host + + Wi-Fi host + + Sheet.3317 + + + + Sheet.3190 + Multiprotocol Service Layer (MPSL) + + Multiprotocol Service Layer (MPSL) + + Sheet.3321 + + + + Sheet.3320 + + + + diff --git a/_images/mcu-set.PNG b/_images/mcu-set.PNG new file mode 100644 index 000000000000..1904593a66a8 Binary files /dev/null and b/_images/mcu-set.PNG differ diff --git a/_images/mcu-set.png b/_images/mcu-set.png new file mode 100644 index 000000000000..a3d83783d7d5 Binary files /dev/null and b/_images/mcu-set.png differ diff --git a/_images/mcu-set1.png b/_images/mcu-set1.png new file mode 100644 index 000000000000..27bc4d910a36 Binary files /dev/null and b/_images/mcu-set1.png differ diff --git a/_images/mcxw71_debug.jpg b/_images/mcxw71_debug.jpg new file mode 100644 index 000000000000..21bd041ebd3f Binary files /dev/null and b/_images/mcxw71_debug.jpg differ diff --git a/_images/mcxw71_installed_sdks.jpg b/_images/mcxw71_installed_sdks.jpg new file mode 100644 index 000000000000..22ce6ccbdbb8 Binary files /dev/null and b/_images/mcxw71_installed_sdks.jpg differ diff --git a/_images/murata_usd-M2_adapter.jpg b/_images/murata_usd-M2_adapter.jpg new file mode 100644 index 000000000000..0d8166707b47 Binary files /dev/null and b/_images/murata_usd-M2_adapter.jpg differ diff --git a/_images/murata_usd-m2_connections_1.jpg b/_images/murata_usd-m2_connections_1.jpg new file mode 100644 index 000000000000..01febd90b557 Binary files /dev/null and b/_images/murata_usd-m2_connections_1.jpg differ diff --git a/_images/murata_usd-m2_connections_2.jpg b/_images/murata_usd-m2_connections_2.jpg new file mode 100644 index 000000000000..91bae4b5f55b Binary files /dev/null and b/_images/murata_usd-m2_connections_2.jpg differ diff --git a/_images/mw320.jpg b/_images/mw320.jpg new file mode 100644 index 000000000000..bb76a6f6cb82 Binary files /dev/null and b/_images/mw320.jpg differ diff --git a/_images/mw320_console.jpg b/_images/mw320_console.jpg new file mode 100644 index 000000000000..c0067814c9f2 Binary files /dev/null and b/_images/mw320_console.jpg differ diff --git a/_images/nRF52840-DK-small.png b/_images/nRF52840-DK-small.png new file mode 100644 index 000000000000..729687fb21be Binary files /dev/null and b/_images/nRF52840-DK-small.png differ diff --git a/_images/nRF52840_DK_info-medium.jpg b/_images/nRF52840_DK_info-medium.jpg new file mode 100644 index 000000000000..03f60e925325 Binary files /dev/null and b/_images/nRF52840_DK_info-medium.jpg differ diff --git a/_images/nRF52840_Dongle-medium.jpg b/_images/nRF52840_Dongle-medium.jpg new file mode 100644 index 000000000000..3e7ec9adfc17 Binary files /dev/null and b/_images/nRF52840_Dongle-medium.jpg differ diff --git a/_images/nRF5340_DK_info-medium.jpg b/_images/nRF5340_DK_info-medium.jpg new file mode 100644 index 000000000000..d7b8f0bdfde2 Binary files /dev/null and b/_images/nRF5340_DK_info-medium.jpg differ diff --git a/_images/nRF7002-DK_Front-small.png b/_images/nRF7002-DK_Front-small.png new file mode 100644 index 000000000000..fbf84407fc3e Binary files /dev/null and b/_images/nRF7002-DK_Front-small.png differ diff --git a/_images/new_project.jpg b/_images/new_project.jpg new file mode 100644 index 000000000000..ce34586229bd Binary files /dev/null and b/_images/new_project.jpg differ diff --git a/_images/nrfconnect_android_connectivity.png b/_images/nrfconnect_android_connectivity.png new file mode 100644 index 000000000000..76138cb316ad Binary files /dev/null and b/_images/nrfconnect_android_connectivity.png differ diff --git a/_images/nxp_hw_connectivity.JPG b/_images/nxp_hw_connectivity.JPG new file mode 100644 index 000000000000..80e19b30dfc6 Binary files /dev/null and b/_images/nxp_hw_connectivity.JPG differ diff --git a/_images/on_off_cluster.png b/_images/on_off_cluster.png new file mode 100644 index 000000000000..4a2b9af6869a Binary files /dev/null and b/_images/on_off_cluster.png differ diff --git a/_images/ota_topology.JPG b/_images/ota_topology.JPG new file mode 100644 index 000000000000..75fc40a70e3b Binary files /dev/null and b/_images/ota_topology.JPG differ diff --git a/_images/ota_topology1.JPG b/_images/ota_topology1.JPG new file mode 100644 index 000000000000..75fc40a70e3b Binary files /dev/null and b/_images/ota_topology1.JPG differ diff --git a/_images/power_conf.JPG b/_images/power_conf.JPG new file mode 100644 index 000000000000..2c03e812c8f6 Binary files /dev/null and b/_images/power_conf.JPG differ diff --git a/_images/power_view.JPG b/_images/power_view.JPG new file mode 100644 index 000000000000..c7a33b80c873 Binary files /dev/null and b/_images/power_view.JPG differ diff --git a/_images/rt1060_evkc_IW612_hw_rework.jpg b/_images/rt1060_evkc_IW612_hw_rework.jpg new file mode 100644 index 000000000000..fd7c303cfaf6 Binary files /dev/null and b/_images/rt1060_evkc_IW612_hw_rework.jpg differ diff --git a/_images/rt1060_evkc_IW612_hw_rework_detail.jpg b/_images/rt1060_evkc_IW612_hw_rework_detail.jpg new file mode 100644 index 000000000000..c5a43e6f4ac7 Binary files /dev/null and b/_images/rt1060_evkc_IW612_hw_rework_detail.jpg differ diff --git a/_images/rt1060_k32w061_pin_settings.jpg b/_images/rt1060_k32w061_pin_settings.jpg new file mode 100644 index 000000000000..ed616ee5a5cb Binary files /dev/null and b/_images/rt1060_k32w061_pin_settings.jpg differ diff --git a/_images/select-sdk.png b/_images/select-sdk.png new file mode 100644 index 000000000000..335a05035e18 Binary files /dev/null and b/_images/select-sdk.png differ diff --git a/_images/select-sdk1.png b/_images/select-sdk1.png new file mode 100644 index 000000000000..412731cc9885 Binary files /dev/null and b/_images/select-sdk1.png differ diff --git a/_images/select_enabled_clusters.png b/_images/select_enabled_clusters.png new file mode 100644 index 000000000000..92f41577dad2 Binary files /dev/null and b/_images/select_enabled_clusters.png differ diff --git a/_images/silabs_logo.png b/_images/silabs_logo.png new file mode 100644 index 000000000000..85cfcceb7434 Binary files /dev/null and b/_images/silabs_logo.png differ diff --git a/_images/startup.png b/_images/startup.png new file mode 100644 index 000000000000..cd9a8ad90fd8 Binary files /dev/null and b/_images/startup.png differ diff --git a/_images/startup1.png b/_images/startup1.png new file mode 100644 index 000000000000..c805bc53b050 Binary files /dev/null and b/_images/startup1.png differ diff --git a/_images/thread_credentials.png b/_images/thread_credentials.png new file mode 100644 index 000000000000..29d89c684831 Binary files /dev/null and b/_images/thread_credentials.png differ diff --git a/_images/toolchain.JPG b/_images/toolchain.JPG new file mode 100644 index 000000000000..068ebfb35e1e Binary files /dev/null and b/_images/toolchain.JPG differ diff --git a/_images/toolchain1.JPG b/_images/toolchain1.JPG new file mode 100644 index 000000000000..068ebfb35e1e Binary files /dev/null and b/_images/toolchain1.JPG differ diff --git a/_images/toolchain2.JPG b/_images/toolchain2.JPG new file mode 100644 index 000000000000..068ebfb35e1e Binary files /dev/null and b/_images/toolchain2.JPG differ diff --git a/_images/unit_testable_clusters.png b/_images/unit_testable_clusters.png new file mode 100644 index 000000000000..61f6c51f59b7 Binary files /dev/null and b/_images/unit_testable_clusters.png differ diff --git a/_images/unit_testable_clusters_all_classes.png b/_images/unit_testable_clusters_all_classes.png new file mode 100644 index 000000000000..6cd8f903b60a Binary files /dev/null and b/_images/unit_testable_clusters_all_classes.png differ diff --git a/_images/unit_testable_clusters_context.png b/_images/unit_testable_clusters_context.png new file mode 100644 index 000000000000..3a42eca37be2 Binary files /dev/null and b/_images/unit_testable_clusters_context.png differ diff --git a/_images/unit_testable_clusters_driver.png b/_images/unit_testable_clusters_driver.png new file mode 100644 index 000000000000..bf97434fb579 Binary files /dev/null and b/_images/unit_testable_clusters_driver.png differ diff --git a/_images/unit_testable_clusters_logic.png b/_images/unit_testable_clusters_logic.png new file mode 100644 index 000000000000..9ebed283777b Binary files /dev/null and b/_images/unit_testable_clusters_logic.png differ diff --git a/_images/unit_testable_clusters_server.png b/_images/unit_testable_clusters_server.png new file mode 100644 index 000000000000..d8632e73a323 Binary files /dev/null and b/_images/unit_testable_clusters_server.png differ diff --git a/_images/unit_tests.png b/_images/unit_tests.png new file mode 100644 index 000000000000..95b29b415c96 Binary files /dev/null and b/_images/unit_tests.png differ diff --git a/_images/workflow_of_casting_video_player.png b/_images/workflow_of_casting_video_player.png new file mode 100644 index 000000000000..7b8abeb30e40 Binary files /dev/null and b/_images/workflow_of_casting_video_player.png differ diff --git a/_images/zap1.png b/_images/zap1.png new file mode 100644 index 000000000000..4356cda98e85 Binary files /dev/null and b/_images/zap1.png differ diff --git a/_images/zap2.png b/_images/zap2.png new file mode 100644 index 000000000000..cd73e0417c25 Binary files /dev/null and b/_images/zap2.png differ diff --git a/_images/zap3.png b/_images/zap3.png new file mode 100644 index 000000000000..018778c7dcee Binary files /dev/null and b/_images/zap3.png differ diff --git a/_images/zap4.png b/_images/zap4.png new file mode 100644 index 000000000000..92ab5cce5186 Binary files /dev/null and b/_images/zap4.png differ diff --git a/_images/zap5.png b/_images/zap5.png new file mode 100644 index 000000000000..5ca690814470 Binary files /dev/null and b/_images/zap5.png differ diff --git a/_images/zap6.png b/_images/zap6.png new file mode 100644 index 000000000000..0901e225fbff Binary files /dev/null and b/_images/zap6.png differ diff --git a/_images/zap_compiler.png b/_images/zap_compiler.png new file mode 100644 index 000000000000..68c1e09395a0 Binary files /dev/null and b/_images/zap_compiler.png differ diff --git a/_sources/BUG_REPORT.md b/_sources/BUG_REPORT.md new file mode 100644 index 000000000000..1d290a400289 --- /dev/null +++ b/_sources/BUG_REPORT.md @@ -0,0 +1,109 @@ +# Reporting bugs + +## Writing an effective bug report + +When reporting a bug, start with the question +`What does a bug report need to tell the developer`. + +Generally you want the following parts covered: + +- What is the problem + +- How can the developer reproduce the problem (to see it for themselves), to + bisect when it was introduced or to find if it got fixed already. + +- At what point does the problem occur + +- What environment did this occur in + +Make sure the above items are covered and the bug is easy to review and parse: + +- **Title** should clearly describe the problem. Bugs are often sorted from + the issue list which only contains the title + +- **Logs** should generally be attachments (drag & drop or click on bottom bar + when entering issue text) and not inline with the issue. + +- **Reproduction steps** and **environment** should be clearly highlighted. If + running commands reproduce the issue (very common), the commands should be + in a code block/script format. + +### Describing the problem + +Make sure the issue is obvious or provide a link explaining why the expected +result is not met. + +Examples: + +- `(Core dump) seen` is obvious since there should be no core dumps + +- `Failure trying to read attribute X in cluster Y which is marked MANDATORY in the spec` + references the spec and describes why attribute read should succeed. + +- `Failure trying to write attribute X in cluster Y, which is enabled since cluster FeatureMap enabled X and spec describes as writable.` + references the spec and explicitly states that an optional attribute is + enabled based on device status + +- `Running certification test TC-A-B-C (link included) fails at step 3: test case asks for command to succeed, I get ACCESS_DENIED instead` + describes a pre-defined test case that is expected to pass but fails. Note + that full link to the test description is needed (and should be covered by + 'how to reproduce' part) + +Unless manually curated (e.g. few lines showing the problem), logs should be +always attachments and not inlined in the bug as the make the bug report too +long. + +### Reproduction steps and when does the issue occur + +Include all steps needed to reproduce the problem. Link any supporting +documentation. + +If stating something of the form `TC-A-B-C step 4 fails` then there should be a +link to TC-A-B-C and ideally a list of the commands of each step since test +cases may change over time. + +The bug report should contain all the information for a developer to reproduce +the issue without needing to have access to CHIP Test case repository (not +everyone does) + +### Environment for reproduction + +Assume that the developer will want to reproduce the issue and will try to +mirror your environment to a reasonable degree. For this, at a minimum the +platforms on which everything is running is needed. + +Try to provide as much information as seems relevant. At a minimum this could +look like +`Failed to commission nrf board using chip-tool running on linux. Used build on SHA abcde...`. +This provides basic information (use nrf board, use chip-tool on linux, default +build) to get started. Beyond that, you can refine if more items seem relevant: + +- `Tested on TE9` or `Tested on interop branch xyz` gives a build reference + point. Useful when branches/tags are used instead of master branch as + development happens on master branch. + +- `Thread devices fail, tested with qpg and efr32` shows that this seems to be + a general thread issue and developer can investigate on multiple of them + +* `Tested with avahi-build and it passes/fails` helps the developer with + information of non-default builds that pass/fail to narrow down the problem + +* `Passes with darwin-framework-tool and repl but fails with chip-tool` helps + the developer in narrowing down the problem + +### Additional information + +Providing additional information that can be helpful is encouraged. Each bug +report is different here. Some examples: + +- `This worked last week (around Jan 5) but started failing in recent master builds` + +- `Specification changed this attribute from optional to mandatory so this may be the cause of the issue` + +- `This issue may be related to #1234 as the same error is seen, however the reproduction steps seemed distinct enough that I opened a new issue` + +- `While running this, I observed 100% CPU before the operation finally timed out` + +- `While running this test, I observed device under test rebooting, logs attached.` + +- `This only happens intermittently - I see it about 30% of the time` diff --git a/_sources/PROJECT_FLOW.md b/_sources/PROJECT_FLOW.md new file mode 100644 index 000000000000..d8579a4e9621 --- /dev/null +++ b/_sources/PROJECT_FLOW.md @@ -0,0 +1,85 @@ +## Matter Project Flow + +This section is intended to cover how Matter uses GitHub Projects, Issues, +Milestones, Releases, and Branches for program/project management in the code +repository. + +### Issues + +Matter uses issues as simple problem descriptions or feature requests. In +general, all work contributed to the repository in the form of pull requests +(PR) should be under the auspices of some open issue. This may seem onerous and +in some cases duplicative, so consider these guidelines when deciding whether +you can get away with not creating an issue: + +- Trivial fixes: issues can function as TODO lists, simple reminders that + something should be addressed. Sometimes, though, the work required to fix + is smaller than the work required to write the issue. +- Issues intended to be addressed by a PR may not actually be fixed or may + regress. +- Issues can span PRs (as PRs should be as small as possible, but no smaller). +- Issues help form an important basis for release notes. Any PR that addresses + a problem that should have release visibility, please do open an issue. + +### Pull requests + +Pull requests should be small and address a single, specific change to the code +base. They should be easy to review, as a "yes, that's better". Refrain from +requesting review until all PR checks have completed successfully, lest you tire +your reviewers. + +PR Don'ts: + +- Don't combine unrelated changes. E.g. if the PR addresses a bug in some C + code, an update to the top-level .gitignore doesn't belong. +- Don't make stacks. E.g. if a change in a component requires a new feature or + even a small tweak in one or more of its dependencies, each dependency + change belongs in its own separate PR. + +### Milestones + +In Matter parlance, a milestone is simply a tag for an expected due date or +release. Milestones are intended to help contributors and their managers to +prioritize work. There are 2 types: Date-based and Release-based. + +#### Date-based + +Date-based milestones are named for their due date, typically a Friday of some +week. Date-based milestones are normally assigned based on a guess about when +something's likely to bubble up and get done based on current work load and +resourcing. They are wishes, guesses. + +#### Release-based + +Release-based milestones are named for the release version and may have flexible +or subject-to-change due dates. Release-based milestones are intended to track +release blockers. + +A special "Not sure when" milestone is a marker for issues whose priority, +scope, or blocking status have not been determined. Monthly review of these is a +project goal. + +Issues without milestones are those that have yet to be considered for one of +the above. Weekly review of new issues is a project goal. + +### Projects + +Projects are collections of issues, pull requests, and notes intended to capture +larger efforts that don't fit in issues, have multiple-subsystems involved, or +may span multiple milestones. We use projects 2 ways: + +1. To track burn down on a larger task. When constructing such a project, it's + important to think in terms of something that will eventually have an end, + i.e. a definite scope. +2. To categorize issues, denote broader efforts without a definite time scope. + These projects might reflect or show burndown or percent complete, but are + mostly used to view where effort is going. + +Issues can belong to any number of projects, but should generally only belong to +one of the task-tracking projects (the first type). + +### Branches, releases, and general development flow + +Master should always be Matter's best branch. Release branches, once cut, are +closed for any feature work. Software fixes for release branches must first land +on master unless demonstrably infeasible. diff --git a/_sources/README.md b/_sources/README.md new file mode 100644 index 000000000000..7d7c889a2f34 --- /dev/null +++ b/_sources/README.md @@ -0,0 +1,228 @@ +# Matter + +[![Builds](https://github.com/project-chip/connectedhomeip/workflows/Builds/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/build.yaml) + +**Builds** + +[![Android](https://github.com/project-chip/connectedhomeip/workflows/Android/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/android.yaml) +[![Ameba](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20Ameba/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-ameba.yaml) +[![ASR](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20ASR/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-asr.yaml) +[![BouffaloLab](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20BouffaloLab/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-bouffalolab.yaml) +[![Darwin](https://github.com/project-chip/connectedhomeip/workflows/Darwin/badge.svg)](https://github.com/project-chip/connectedhomeip/blob/master/.github/workflows/darwin.yaml) +[![TI CC26X2X7](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20TI%20CC13XX_26XX/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-cc13xx_26xx.yaml) +[![TI CC32XX](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20TI%20CC32XX/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-cc32xx.yaml) +[![EFR32](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20EFR32/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-efr32.yaml) +[![ESP32](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20ESP32/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-esp32.yaml) +[![Infineon](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-infineon.yaml/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-infineon.yaml) +[![i.MX Linux](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20i.MX%20Linux/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-linux-imx.yaml) +[![K32W with SE051](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20K32W%20with%20SE051/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-k32w.yaml) +[![Linux ARM](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20Linux%20ARM/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-linux-arm.yaml) +[![Linux Standalone](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20Linux%20Standalone/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-linux-standalone.yaml) +[![Linux Standalone](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20Linux%20Standalone/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-linux-standalone.yaml) +[![Mbed OS](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20Mbed%20OS/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-mbed.yaml) +[![MW320](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20MW320/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-mw320.yaml) +[![nRF Connect SDK](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20nRF%20Connect%20SDK/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-nrfconnect.yaml) +[![Open IoT SDK](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20Open%20IoT%20SDK/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-openiotsdk.yaml) +[![QPG](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20QPG/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-qpg.yaml) +[![STM32](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20stm32/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-stm32.yaml) +[![Telink](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20Telink/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-telink.yaml) +[![Tizen](https://github.com/project-chip/connectedhomeip/workflows/Build%20example%20-%20Tizen/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/examples-tizen.yaml) + +**Tests** + +[![Unit / Integration Tests](https://github.com/project-chip/connectedhomeip/workflows/Unit%20/%20Integration%20Tests/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/unit_integration_test.yaml) +[![Cirque](https://github.com/project-chip/connectedhomeip/workflows/Cirque/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/cirque.yaml) +[![QEMU](https://github.com/project-chip/connectedhomeip/workflows/QEMU/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/qemu.yaml) + +**Tools** + +[![ZAP Templates](https://github.com/project-chip/connectedhomeip/workflows/ZAP/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/zap_templates.yaml) + +**Documentation** + +[![Documentation Build](https://github.com/project-chip/connectedhomeip/actions/workflows/docbuild.yaml/badge.svg)](https://github.com/project-chip/connectedhomeip/actions/workflows/docbuild.yaml) + +- [Matter SDK documentation page](https://project-chip.github.io/connectedhomeip-doc/index.html) + +# About + +Matter (formerly Project CHIP) creates more connections between more objects, +simplifying development for manufacturers and increasing compatibility for +consumers, guided by the Connectivity Standards Alliance. + +# What is Matter? + +Matter is a unified, open-source application-layer connectivity standard built +to enable developers and device manufacturers to connect and build reliable, and +secure ecosystems and increase compatibility among connected home devices. It is +built with market-proven technologies using Internet Protocol (IP) and is +compatible with Thread and Wi-Fi network transports. Matter was developed by a +Working Group within the Connectivity Standards Alliance (Alliance). This +Working Group develops and promotes the adoption of the Matter standard, a +royalty-free connectivity standard to increase compatibility among smart home +products, with security as a fundamental design tenet. The vision that led major +industry players to come together to build Matter is that smart connectivity +should be simple, reliable, and interoperable. + +Matter simplifies development for manufacturers and increases compatibility for +consumers. + +The standard was built around a shared belief that smart home devices should be +secure, reliable, and seamless to use. By building upon Internet Protocol (IP), +Matter enables communication across smart home devices, mobile apps, and cloud +services and defines a specific set of IP-based networking technologies for +device certification. + +The Matter specification details everything necessary to implement a Matter +application and transport layer stack. It is intended to be used by implementers +as a complete specification. + +The Alliance officially opened the Matter Working Group on January 17, 2020, and +the specification is +[available](https://csa-iot.org/developer-resource/specifications-download-request/) +for adoption now. + +Visit [buildwithmatter.com](https://buildwithmatter.com) to learn more and read +the latest news and updates about the project. + +# Project Overview + +## Development Goals + +Matter is developed with the following goals and principles in mind: + +**Unifying:** Matter is built with and on top of market-tested, existing +technologies. + +**Interoperable:** The specification permits communication between any +Matter-certified device, subject to users’ permission. + +**Secure:** The specification leverages modern security practices and protocols. + +**User Control:** The end user controls authorization for interaction with +devices. + +**Federated:** No single entity serves as a throttle or a single point of +failure for root of trust. + +**Robust:** The set of protocols specifies a complete lifecycle of a device — +starting with the seamless out-of-box experience, through operational protocols, +to device and system management specifications required for proper function in +the presence of change. + +**Low Overhead:** The protocols are practically implementable on low +compute-resource devices, such as MCUs. + +**Pervasive:** The protocols are broadly deployable and accessible, by +leveraging IP and being implementable on low-capability devices. + +**Ecosystem-Flexible:** The protocol is flexible enough to accommodate +deployment in ecosystems with differing policies. + +**Easy to Use:** The protocol provides smooth, cohesive, integrated provisioning +and out-of-box experience. + +**Open:** The Project’s design and technical processes are open and transparent +to the general public, including non-members wherever possible. + +## Architecture Overview + +Matter aims to build a universal IPv6-based communication protocol for smart +home devices. The protocol defines the application layer that will be deployed +on devices and the different link layers to help maintain interoperability. The +following diagram illustrates the normal operational mode of the stack: +![Matter Architecture Overview](images/Matter_Arch_Overview.png) + +The architecture is divided into layers to help separate the different +responsibilities and introduce a good level of encapsulation among the various +pieces of the protocol stack. The vast majority of interactions flow through the +stack captured in the following Figure: + +![Matter Stack Architecture](images/Matter_Layered_Arch.png) + +1. **Application:** High-order business logic of a device. For example, an + application that is focused on lighting might contain logic to handle turning + on/off the bulb as well as its color characteristics. + +2) **Data Model:** The data layer corresponds to the data and verb elements that + help support the functionality of the application. The Application operates + on these data structures when there is an intent to interact with the device. + +3. **Interaction Model:** The Interaction Model layer defines a set of + interactions that can be performed between a client and server device. For + example, reading or writing attributes on a server device would correspond to + application behavior on the device. These interactions operate on the + elements defined at the data model layer. + +4) **Action Framing:** Once an action is constructed using the Interaction + Model, it is serialized into a prescribed packed binary format to encode for + network transmission. + +5. **Security:** An encoded action frame is then sent down to the Security Layer + to encrypt and sign the payload to ensure that data is secured and + authenticated by both sender and receiver of a packet. + +6. **Message Framing & Routing:** With an interaction encrypted and signed, the + Message Layer constructs the payload format with required and optional header + fields; which specify the message's properties and some routing information. + +7) **IP Framing & Transport Management:** After the final payload has been + constructed, it is sent to the underlying transport protocol for IP + management of the data. + +# Current Status of Matter + +Matter’s design and technical processes are intended to be open and transparent +to the general public, including to Working Group non-members wherever possible. +The availability of this GitHub repository and its source code under an Apache +v2 license is an important and demonstrable step to achieving this commitment. +Matter endeavors to bring together the best aspects of market-tested +technologies and redeploy them as a unified and cohesive whole-system solution. +The overall goal of this approach is to bring the benefits of Matter to +consumers and manufacturers as quickly as possible. As a result, what you +observe in this repository is an implementation-first approach to the technical +specification, vetting integrations in practice. The Matter repository is +growing and evolving to implement the overall architecture. The repository +currently contains the security foundations, message framing and dispatch, and +an implementation of the interaction model and data model. The code examples +show simple interactions, and are supported on multiple transports -- Wi-Fi and +Thread -- starting with resource-constrained (i.e., memory, processing) silicon +platforms to help ensure Matter’s scalability. + +# How to Contribute + +We welcome your contributions to Matter. Read our contribution guidelines +[here](https://github.com/project-chip/connectedhomeip/blob/master/CONTRIBUTING.md). + +# Building and Developing in Matter + +Instructions about how to build Matter can be found [here](https://github.com/project-chip/connectedhomeip/blob/master/README.md) . + +# Directory Structure + +The Matter repository is structured as follows: + +| File/Folder | Content | +| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| build | Build system support content and built output directories | +| build_overrides | Build system parameter customization for different platforms | +| config | Project configurations | +| credentials | Development and test credentials | +| docs | Documentation, including guides. Visit the [Matter SDK documentation page](https://project-chip.github.io/connectedhomeip-doc/index.html) to read it. | +| examples | Example firmware applications that demonstrate use of Matter | +| integrations | 3rd party integrations | +| scripts | Scripts needed to work with the Matter repository | +| src | Implementation of Matter | +| third_party | 3rd party code used by Matter | +| zzz_generated | ZAP generated template code - Revolving around cluster information | +| BUILD.gn | Build file for the GN build system | +| CODE_OF_CONDUCT.md | Code of conduct for Matter and contribution to it | +| CONTRIBUTING.md | Guidelines for contributing to Matter | +| LICENSE | Matter license file | +| REVIEWERS.md | PR reviewers | +| gn_build.sh | Build script for specific projects such as Android, EFR32, etc. | +| README.md | This file | + +# License + +Matter is released under the [Apache 2.0 license](https://github.com/project-chip/connectedhomeip/blob/master/../LICENSE). diff --git a/_sources/VSCODE_DEVELOPMENT.md b/_sources/VSCODE_DEVELOPMENT.md new file mode 100644 index 000000000000..4bb79d380904 --- /dev/null +++ b/_sources/VSCODE_DEVELOPMENT.md @@ -0,0 +1,159 @@ +# Visual Studio Code Development + +[Visual Studio Code](https://code.visualstudio.com/) is a great and simple IDE +that can be used to build & develop with for Matter. + +Matter supports the docker / remote container workflow in Visual Studio Code, +and has a container environment setup automatically. You can read more about +this workflow [here](https://code.visualstudio.com/docs/remote/containers). + +Tested on: + +- macOS 10.5 +- Windows 10 Pro + WSL + Ubuntu 18 LTS +- Linux - Fedora Core 35 distribution + +## Setup Steps + +1. _Windows Only_ Enable the Windows Subsystem for Linux (WSL) following + instructions here: + +1. _Windows Only_ Install Ubuntu from the Windows App Store here: + +1. Install [Docker](https://www.docker.com/) for your operating system of choice + from here: +1. Install [Visual Studio Code](https://code.visualstudio.com/) for your + operating system of choice here: +1. Install [Git](https://git-scm.com/) if you haven't already +1. _Windows Only_ Enable git to use LF instead of CLRF by default: + `git config --global core.autocrlf false` +1. Git clone the main Matter repository here: + +1. Launch Visual Studio Code, and open the cloned folder from above +1. Install the + [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) + extension for Visual Studio Code, this extension allows you to use docker + containers as a development backend. +1. Once this is installed, you'll be prompted to reload Visual Studio Code, do + so +1. At the bottom right of your Visual Studio Code window you should have a new + box prompting you to re-open the window as a container. Hit yes. +1. _Windows Only_ Update your Visual Studio Code settings as documented here: + https://code.visualstudio.com/docs/editor/integrated-terminal#_configuration + to use Bash on Ubuntu (on Windows) eg: + `"terminal.integrated.shell.windows": "C:\\Windows\\System32\\bash.exe"` +1. Now your local machine is building a docker image that has all the tools + necessary to build and test Matter. This can take some time, but will + eventually complete and open up the source tree + +## Bootstrapping your source tree (one time) + +1. Under the "Terminal" menu (or using another shortcut to the same tool), + select "Run Task..." +1. Select the "Bootstrap" task + +## Building the Source Tree + +1. Under the "Terminal" menu select "Run Build Task..." + +## Tasks + +Located in the [tasks json](https://github.com/project-chip/connectedhomeip/blob/master/.vscode/tasks.json) file you'll find a list of +tasks that can be run from the "Run Task..." command. Example tasks are "Clean", +"Run Pretty Check" + +Developers are encouraged to add tasks to the +[tasks json](https://github.com/project-chip/connectedhomeip/blob/master/.vscode/tasks.json) over time to make sure everyone is using the +same base configuration and build. + +### Current base tasks are listed here + +- Main Build - Build the default configuration (i.e., Linux OpenSSL) +- Run Unit and Functional Tests - Test the default configuration +- Build & Test (all) - Build & Test various configurations (Linux variants, + Android, EFR32) +- Update compilation database - Update the database used by IntelliSense + (needed for cross references, completion) +- Bootstrap - On a clean tree, pull in the third party dependencies required +- Clean Output - Remove build artifacts +- Clean Tree - Full (and destructive) git clean of the tree + +## Launch Tasks + +Located in the [launch json](https://github.com/project-chip/connectedhomeip/blob/master/.vscode/launch.json) file you'll find a list of +build & run jobs that can be run from the "Run" tab and start a run or debug +session. + +Developers are encouraged to add tasks to the +[launch json](https://github.com/project-chip/connectedhomeip/blob/master/.vscode/launch.json) over time to make sure everyone is using +the same base debugging setup. + +## Submitting a Pull Request - Practical Advice + +### Before submitting a PR, make sure these commands run and succeed + +- Run task: "Build & Test (all)" + +## Common Issues + +- [Missing Git credential](https://code.visualstudio.com/docs/remote/containers#_sharing-git-credentials-with-your-container) +- [Missing Git SSH keys](https://code.visualstudio.com/docs/remote/containers#_sharing-git-credentials-with-your-container) +- [Using GPG signing keys](https://github.com/microsoft/vscode-remote-release/issues/72) + +## Docker FAQ + +### DNS problem: can't resolve archive.ubuntu.com + +A common problem encountered is that a container can't resolve +`archive.ubuntu.com` and can't install anything via `apt-get`, during the +creation of the container image, resulting in an error like: + +``` +E: Package 'locales' has no installation candidate +The command '/bin/sh -c apt-get install -y locales && localedef -i en_US -c -f UTF-8 -A /usr/share/locale/locale.alias en_US.UTF-8' returned a non-zero code: 100 +``` + +Most common reason for this is that the DNS for docker daemon has not been set +up correctly and is simply using a default: 8.8.8.8, which in many corporate or +more secure environments is not accessible. A typical solution for this is to +put a following key/value into your system-wide docker `daemon.json` (Typically +located under `/etc/docker/daemon.json` on a Linux system): + +``` +"dns": ["<>", "8.8.8.8"] +``` + +You can obtain the address you should put into that line of your nameserver by +running: + +``` +nmcli dev show | grep 'IP4.DNS' +``` + +After you update the dns, you should restart docker, specific to your system. On +a typical Linux workstation, you do this via: + +``` +sudo service docker restart +``` + +Alternatively, you can also pass the `--dns` argument to your docker daemon, but +creating a `daemon.json` and following the above method will solve the problem +system-wide. + +## Visual Studio Code FAQ + +- _Highly_ recommend you read through + [this page](https://code.visualstudio.com/docs/getstarted/settings) to learn + how to configure Visual Studio Code to suit your style: + +- Great primer set of videos + [here](https://code.visualstudio.com/docs/getstarted/introvideos) + + +## Visual Studio Code Recommended Settings + +- Configure the editor to format on save, in your Visual Studio Code Settings: + `"editor.formatOnSave": true` +- Configure the clang-format extension `@ext:xaver.clang-format`, it is + installed in the docker container. Make sure all languages are enabled diff --git a/_sources/ci-cd/index.md b/_sources/ci-cd/index.md new file mode 100644 index 000000000000..e659abb315f8 --- /dev/null +++ b/_sources/ci-cd/index.md @@ -0,0 +1,48 @@ +# CI/CD Documentation + +```{toctree} +:glob: + +tools/* +``` + +## Project Information + +- [Build Guide](../guides/BUILDING.md) +- Sphinx documentation framework + - New directories and individual files must be added to the + [tree](https://github.com/project-chip/connectedhomeip/blob/master/docs/index.md) + - New files under directories must be added to the tree in the index file; + see above. Glob and regular expressions may be used to include all + - The + [documentation page](https://project-chip.github.io/connectedhomeip-doc/) + is the end product + - Links can be relative; links ending in ".md" in the code will be + reflected as ".html" on that page +- Pull Requests + - Built in style and spelling checks must be satisfied + - Larger changes should go through an approval process; reviewers are + automatically added + - Smaller specific changes like ones to this file may be expedited with + the "fast track" label + +Work In Progress + +## Tasks + +- [Issues List](https://github.com/project-chip/connectedhomeip/labels/CI%2FCD%20improvements) + +## Tools + +- [Daily Fail Summary](tools/daily_fail_summary.md) +- Spellcheck + - Uses + [`rojopolis`/spellcheck-github-actions](https://github.com/marketplace/actions/github-spellcheck-action#configuration), + a PySpelling-based spellchecker + - This tool utilizes the definitions in .spellcheck.yml and + .github/`.wordlist.txt` to check all documentation files. + .spellcheck.yml defines the settings while `.wordlist.txt` is a + dictionary of words to skip checking (brand names, technical jargon, + acronyms) + +## General Improvement Ideas diff --git a/_sources/ci-cd/tools/daily_fail_summary.md b/_sources/ci-cd/tools/daily_fail_summary.md new file mode 100644 index 000000000000..290dfc313929 --- /dev/null +++ b/_sources/ci-cd/tools/daily_fail_summary.md @@ -0,0 +1,34 @@ +### Daily Fail Summary + +#### Source + +Workflow: + + +Script: + + +Fail Definitions: + + +#### Summary + +Runs once per day; takes inventory of the previous day's workflow runs and +parses them for fail statistics. Creates temporarily cached artifacts for easy +data parsing. Also saves a daily pass percentage list of all workflows at +. +Fail definitions can be added to the file defined above to allow fast root cause +determination of any fail with an error message. + +#### To Do + +- Keep fail signature list updated to track causes of all common fails +- Include Darwin Test fail definitions in fail summary script - for starters, + Test Reliable Message Protocol + +#### Improvement Ideas + +- Make script artifact more known and accessible so it can be easily shared + and used by everyone +- Deliver daily fail summaries in short form through a Slack bot for easy + access diff --git a/_sources/cluster_and_device_type_dev/cluster_and_device_type_dev.md b/_sources/cluster_and_device_type_dev/cluster_and_device_type_dev.md new file mode 100644 index 000000000000..1981e9e78cee --- /dev/null +++ b/_sources/cluster_and_device_type_dev/cluster_and_device_type_dev.md @@ -0,0 +1,254 @@ +# Implementing New Clusters & Device Types + +The goal of new cluster and device type development is to + +1. write the cluster implementations +2. write the code and supporting material that will allow zap to generate the + appropriate ember layers +3. write the unit tests, test plans and automation scripts that prove the code + correctness and allow these new features to be certified + +Unit tests, test plans and certification tests are covered in the testing +section. This document will concentrate on implementing clusters and device +types in the SDK. + +- Cluster Definition + - XML + - Describes the structures, enums, attributes, commands, events etc. + - Direct translation of the spec into code + - [src/app/zap-templates/zcl/data-model/chip/](https://github.com/project-chip/connectedhomeip/tree/master/src/app/zap-templates/zcl/data-model/chip) +- Cluster Implementation + + - Client side - codegen, you write the glue + - Server side - cpp implementation through Ember and / or + [AttributeAccessInterface](https://github.com/project-chip/connectedhomeip/blob/master/src/app/AttributeAccessInterface.h) + and + [CommandHandlerInterface](https://github.com/project-chip/connectedhomeip/blob/master/src/app/CommandHandlerInterface.h) + - src/app/clusters/ + - build file: + [src/app/chip_data_model.gni](https://github.com/project-chip/connectedhomeip/blob/master/src/app/chip_data_model.gni) + - build file uses data from the codegen to auto-populate the cluster + list. + - Follow examples in there to get your code building into the image + when selected in zap + +- Device Type Definitions + - XML defines conformance + - [src/app/zap-templates/zcl/data-model/chip/matter-devices.xml](https://github.com/project-chip/connectedhomeip/blob/master/src/app/zap-templates/zcl/data-model/chip/matter-devices.xml) + +See [How To Add New Device Types & Clusters](how_to_add_new_dts_and_clusters.md) +for a detailed description of how and where to add cluster and device type +definitions so they are picked up properly by ZAP/ember and the SDK. + +Note that the output should also be verified against the spec using the +[.matter parser tools](https://project-chip.github.io/connectedhomeip-doc/guides/matter_idl_tooling.html). + +## ZAP, Ember and Overrides + +- Goal: get zap to understand the new cluster so it can be used on devices + (XML and glue) + +![](../zap_and_codegen/img/zap_compiler.png) + +### Cluster definitions and ZAP + +Please see [ZAP](../zap_and_codegen/zap_intro.md) for an introduction to ZAP. + +After implementing the changes outlined in the wiki article, your cluster and +device type should show up in zap. you can check this by running zaptool with +any zap file. + +./scripts/tools/zap/run_zaptool.sh + +To ensure the cluster and device type are correctly implemented for ZAP, open +the endpoint configuration and ensure the device type appears in the device type +list. + +![](../zap_and_codegen/img/zap3.png) + +Next, check your cluster. The "domain" parameter in the XML controls which group +the cluster is in. It should have all the expected attributes, commands and +events. + +![](../zap_and_codegen/img/zap4.png) + +Last, ensure that your attributes have the storage option set appropriately. + +![](../zap_and_codegen/img/zap5.png) + +### Cluster implementation - Ember and overrides + +- Ember: layer used to setup/access the endpoints / attributes / commands etc. + on the device + + - The build generates the Ember function signatures and defaults + - The Cluster server code implements callbacks for initialization, + commands, attribute access and event generation + - Interaction Model layer will call ember functions when it receives + incoming interactions for your cluster + +- Overrides + - Ember layer is _generated_ at compile time whereas overrides are + _installed_ at run time + - Overrides are called before the ember layer for attribute access or + command handling + - AttributeAccessInterface & CommandHandlerInterface + - Allow significantly more control, but are more complex + - **UNIT TESTABLE** + - Both allow fall through to the ember layer (if setup in zap) + +#### Cluster Server Initialization + +The following diagram shows the flow of messages coming into the Matter core and +ending in the cluster initialization code. + +![](img/cluster_initialization.png) + +EmberAfInitializeAttributes - ember attribute storage - for all attributes +marked as “RAM” in the zap, sets defaults in the storage +MatterPluginServerCallback - .h is a generated file, .cpp impl is done +in the server cluster code. Use this to setup the cluster and setup overrides in +chip::app::AttributeAccessInterfaceRegistry::Instance().Register - use this if +you want to handle attribute reads and writes externally + +Blue sections can be overridden. + +#### Cluster Server Attributes + +**Two mechanisms** + +- Ember layer +- Override + +**ZAP files and implementation** + +- For attributes marked as **“RAM”** storage in the zap file + - Storage allocated automatically, Ember handles read/write + - Generated “Get” and “Set” functions for each attribute in Accessors.h + (generated file) + - You _CAN_ register an override on the cluster. If you don’t try to + encode the attribute in the override, it will fall through to the + storage. + - If you _DO_ always encode the attribute in the access override + function, you’re wasting space. +- For attributes marked as **“External”** storage in the zap file + - NO storage is allocated, no fall through to ember storage + - NEED to register an access override for these to work + +##### Cluster Server Attributes via Override (read) + +![](img/cluster_attribute_read.png) + +[AttributeAccessInterface::Read()](https://github.com/project-chip/connectedhomeip/blob/master/src/app/AttributeAccessInterface.h#L424) + +``` +CHIP_ERROR Read(const ConcreteReadAttributePath & aPath, + AttributeValueEncoder & aEncoder) +{ + // Parse aPath to determine the requested attribute + switch (aPath.mAttributeId) + { + case SomeAttribute::Id: + // Just encode the value + aEncoder.Encode(mSomeValue); + break; + } + // Beware of lists - the need to use EncodeList to have + // chunking handled properly + return CHIP_NO_ERROR; +``` + +#### Cluster Server Attributes via override (write) + +Write are handled using the same path as read, but land in the “Write” function +of the AttributeAccessInterface. + +[AttributeAccessInterface::Write()](https://github.com/project-chip/connectedhomeip/blob/master/src/app/AttributeAccessInterface.h#444) + +The attribute handler is responsible for constraint checking and Attribute +persistence + +##### Attribute Persistence + +- When using AttributeAccessInterface, you need to manage any Attributes that + require Persistence. +- This can be done by using GetSafeAttributePersistenceProvider() +- This provides a useful API for Reading & Writing values of any type to the + default Persistence Store + - [src/app/SafeAttributePersistenceProvider.h](https://github.com/project-chip/connectedhomeip/blob/master/src/app/SafeAttributePersistenceProvider.h) + +#### Ember layer read / write + +In the ember layer functions, the ember layer handles the encode and decode. +This can work for simple attributes, but is can be challenging for complex +attribute interactions. The ember layer is also VERY difficult to unit test. + +The ember layer provides callbacks for attribute changes so you can handle them + +``` +void MatterPostAttributeChangeCallback(const chip::app::ConcreteAttributePath & attributePath, + uint8_t type, uint16_t size, uint8_t * value) + +``` + +Take care when using this that the callbacks are implemented in a way that can +be used across examples + +#### Cluster Server Commands + +- As with Attributes, there is an ember layer option, and an override option +- **Override** + - Registered at runtime + - InteractionModelEngine::RegisterCommandHandler + - Implement CommandHandlerInterface +- **Ember** + - static + - emberAfCallback + +![](img/cluster_commands.png) + +##### Command Handler Code + +- [CommandHandlerInterface](https://github.com/project-chip/connectedhomeip/blob/master/src/app/CommandHandlerInterface.h) + - Can use HandleCommand function for convenience (sets handled) + - If not, need to set whether the command was handled + - if no, falls through to ember by default + - If entirely handled by this interface, add to + src/app/common/templates/config-data.yaml to disable ember +- Ember interface + - Return true if the command was handled, false to have an invalid command + response returned +- For both + - Need to handle the return to the caller using either AddResponse or + AddStatus in the command handler + - Need to handle constraints checking and return the appropriate status or + response per the spec + +The +[config-data.yaml](https://github.com/project-chip/connectedhomeip/blob/master/src/app/common/templates/config-data.yaml) +file is used to turn off ember command callback generation for clusters with +pure CommandHandlerInterface implementations. + +#### Events and Attribute Subscriptions + +- **Attribute** change reporting + - If you go through the ember storage layer (generated Get/Set functions + on the attribute), this is handled for you + - If you are using an AttributeAccessInterface, you need to tell the + reporting engine that the attribute has changed + - **MatterReportingAttributeChangeCallback** +- **Events** + - No direct ember support + - Call LogEvent function in EventLogging.h. Caller has to either lock the + Matter stack lock or queue the event to the Matter event queue when + using LogEvent. + +#### A note on Dynamic Endpoints + +- Dynamic endpoint registration + - ZAP configs are static at compile time + - Can also use dynamic endpoint registration at runtime + - common for bridges + - **emberAfSetDynamicEndpoint** + - If you have your own storage for attributes etc, need to account for + dynamic endpoints as well as static diff --git a/_sources/cluster_and_device_type_dev/how_to_add_new_dts_and_clusters.md b/_sources/cluster_and_device_type_dev/how_to_add_new_dts_and_clusters.md new file mode 100644 index 000000000000..58ab781cbecf --- /dev/null +++ b/_sources/cluster_and_device_type_dev/how_to_add_new_dts_and_clusters.md @@ -0,0 +1,247 @@ +# Adding new clusters and device types to the codegen + +This document outlines the process needed to add a new Matter device type and +related clusters. Obviously, the steps below assume that the related Matter +specifications were properly reviewed and approved. + +## Add the cluster definitions to the SDK + +The following steps should be followed to add new cluster definitions to the +SDK. + +**Add your new cluster definition to an appropriately-name file in this +directory:** +[src/app/zap-templates/zcl/data-model/chip](https://github.com/project-chip/connectedhomeip/tree/master/src/app/zap-templates/zcl/data-model/chip) + +**Add references to each new cluster definition to these files:** + +1. [.github/workflows/tests.yaml](https://github.com/project-chip/connectedhomeip/tree/master/.github/workflows/tests.yaml) +2. [scripts/rules.matterlint](https://github.com/project-chip/connectedhomeip/tree/master/scripts/rules.matterlint) +3. [src/app/zap-templates/zcl/zcl-with-test-extensions.json](https://github.com/project-chip/connectedhomeip/tree/master/src/app/zap-templates/zcl/zcl-with-test-extensions.json) +4. [src/app/zap-templates/zcl/zcl.json](https://github.com/project-chip/connectedhomeip/tree/master/src/app/zap-templates/zcl/zcl.json) +5. If it is a derived cluster, add a reference to the base cluster definition. + (e.g. in mode-base-cluster.xml you may need to add cluster codes - otherwise + you may get strange exceptions which aren't clear when running regen_all.py) + + > ``` + > + > + > + > + > ``` + +6. [src/controller/python/chip/clusters/\_\_init\_\_.py](https://github.com/project-chip/connectedhomeip/tree/master/src/controller/python/chip/clusters/__init__.py) + +**Enable your new cluster in the Python and Android clients** in +[src/controller/data_model/controller-clusters.zap](https://github.com/project-chip/connectedhomeip/blob/master/src/controller/data_model/controller-clusters.zap) + +You will need the ZAP tool to edit the ZAP file. + +- Unless you already have the tool installed, you can use one of the + [nightly builds](https://github.com/project-chip/zap/releases) +- [ZAP tool info](https://developers.home.google.com/matter/tools/zap) +- [ZAP tool repo](https://github.com/project-chip/zap) + +Use the ZAP GUI tool to edit the file above: + +1. From the command line, navigate to the directory containing + [controller-clusters.zap](https://github.com/project-chip/connectedhomeip/blob/master/src/controller/data_model) +2. Run zap: `../../../scripts/tools/zap/run_zaptool.sh controller-clusters.zap`. + Alternatively, run the zap tool and navigate to the zap file that you wish to + open, or run as + `./scripts/tools/zap/run_zaptool.sh src/controller/data_model/controller-clusters.zap`. +3. In the gui, select `Endpoint-1` from the left pane. +4. Open the cluster group, for example, `Appliances`. +5. Find the cluster to be enabled, e.g. `Dishwasher Control`. +6. In the Enable column, select "Client" from the drop-down box. +7. Click `File->Save` to save the configuration. +8. Close the GUI. + +**Add entries for your new cluster to +[BUILD.gn](https://github.com/project-chip/connectedhomeip/blob/master/cluster_and_device_type_dev/c/src/controller/data_model/BUILD.gn)** in the outputs section of the +java-jni-generate bits. The entries should look like +"jni/YourClusterNameClient-InvokeSubscribeImpl.cpp" and +"jni/YourClusterNameClient-ReadImpl.cpp". + +**Add an entry to the ClientDirectories** section of +[src/app/zap_cluster_list.json](https://github.com/project-chip/connectedhomeip/blob/master/src/app/zap_cluster_list.json). + +**Update `chip-tool`** + +1. Regenerate all zap generated code using `./scripts/tools/zap_regen_all.py` +2. Rebuild chip-tool and it will have new cluster support: + `./scripts/examples/gn_build_example.sh examples/chip-tool SOME-PATH/` + +## Add the device type definition to the SDK + +1. Add the XML definition of the device to + [matter-devices.xml](https://github.com/project-chip/connectedhomeip/blob/master/src/app/zap-templates/zcl/data-model/chip/matter-devices.xml) +2. Implement the incoming command behaviors common to all applications. The + parsing of the payload from TLV to a C++ struct is done by code + auto-generated from the XML (see + [zap-generated](https://github.com/project-chip/connectedhomeip/blob/master/zzz_generated/app-common/app-common/zap-generated)) + The rest of the functionality must be manually implemented. Note: for the + auto-generated code run one of the following: + 1. for everything: `./scripts/tools/zap_regen_all.py` + 2. just for the app-common part: + `./scripts/tools/zap/generate.py -t src/app/common/templates/templates.json -o zzz_generated/app-common/app-common/zap-generated src/controller/data_model/controller-clusters.zap` +3. Implement the read/write/storage operations for the attributes of any type, + list, or struct which are not the global attributes present in all clusters. + For example, there's no need to implement CommandList, AttributeList etc. For + the attributes which are not list of struct type, the handling code is + implemented generically so most likely no work is needed for them. +4. Implement any attribute spec requirements that are common to all + applications. For example: code to enforce specific ranges, code for handling + the interactions between attributes etc. + +## Implement Code and Tests + +Implement the clusters, the example cluster server application and add the +related SDK tests. + +1. Implement new clusters here: + [src/app/clusters](https://github.com/project-chip/connectedhomeip/tree/master/src/app/clusters) +2. Implement tests here: + [src/app/tests/suites](https://github.com/project-chip/connectedhomeip/tree/master/src/app/tests/suites) +3. Implement the example cluster server application: + 1. The YAML tests will run against this server + 2. Depending on the clusters, there are two options: + 1. Enable them in the all-clusters-app and use that as the example + cluster server app. If choosing this option, consider adding an + example application that has just the relevant clusters enabled; this + part is a nice to have. + 2. If the clusters have complicated global application requirements + consider using a separate example app. see the door lock, bridge, TV, + OTA clusters. + 3. NOTES: If adding a new cluster derived from `mode-base` into + [examples/all-clusters-app/](https://github.com/project-chip/connectedhomeip/tree/master/examples/all-clusters-app/) + (Assume your new cluster is called `XZYMode`): + 1. Create your new `xyz-mode-cluster.xml` in + [src/app/zap-templates/zcl/data-model/chip](https://github.com/project-chip/connectedhomeip/tree/master/src/app/zap-templates/zcl/data-model/chip) + (as above). Note that this is a much cut down cluster definition + compared to normal clusters, since it derives from + [mode-base-cluster.xml](https://github.com/project-chip/connectedhomeip/tree/master/src/app/zap-templates/zcl/data-model/chip/mode-base-cluster.xml). + See + [dishwasher-mode-cluster.xml](https://github.com/project-chip/connectedhomeip/tree/master/src/app/zap-templates/zcl/data-model/chip/dishwasher-mode-cluster.xml) + as an example. Note you should review if you need the `StartUpMode` + and `OnMode` attributes based on the spec. + 2. Check that you have added your cluster code into + [mode-base-cluster.xml](https://github.com/project-chip/connectedhomeip/tree/master/src/app/zap-templates/zcl/data-model/chip/mode-base-cluster.xml) + 1. ` ` - replace + `XXXX` with your cluster ID + 2. ` ` - + replace `XXXX` with your cluster ID + 3. ` ` - + replace `XXXX` with your cluster ID + 3. Add your new Mode definitions in `xyz-mode.h`. In this header you + define the modes / labels and tags. See + [dishwasher-mode.h](https://github.com/project-chip/connectedhomeip/tree/master/examples/all-clusters-app/all-clusters-common/include/dishwasher-mode.h) + as an example. + 4. Add your new stub to instantiate the mode. See + [dishwasher-mode.cpp](https://github.com/project-chip/connectedhomeip/tree/master/examples/all-clusters-app/all-clusters-common/src/dishwasher-mode.cpp) + as an example. + 5. In + [examples/all-clusters-app/linux/main-common.cpp](https://github.com/project-chip/connectedhomeip/tree/master/examples/all-clusters-app/linux/main-common.cpp): + 1. Add `#include "xyz-mode.h"` + 2. In `ApplicationShutdown()`, add a call to your + `Clusters::XYZMode::Shutdown();`. + 6. In + [examples/all-clusters-app/linux/BUILD.gn](https://github.com/project-chip/connectedhomeip/tree/master/examples/all-clusters-app/linux/BUILD.gn), + add the `xyz-mode.cpp` file to the `sources` section. + 7. In + [src/app/common/templates/config-data.yaml](https://github.com/project-chip/connectedhomeip/blob/master/src/app/common/templates/config-data.yaml): + 1. Add a `::ModeTag` to the `EnumsNotUsedAsTypeInXML` + section. + 2. Add an `XYZ Mode` entry to the + `CommandHandlerInterfaceOnlyClusters` section. + 8. In + [src/app/util/util.cpp](https://github.com/project-chip/connectedhomeip/blob/master/src/app/util/util.cpp), + in the `// Cluster Init Functions...` section, add a void + `MatterXYZModePluginServerInitCallback() {}` definition. + 9. In + [src/app/zap-templates/zcl/zcl-with-test-extensions.json](https://github.com/project-chip/connectedhomeip/blob/master/src/app/zap-templates/zcl/zcl-with-test-extensions.json): + 1. Add the `xyz-mode-cluster.xml` to the `xmlFile` list + 2. In the `attributeAccessInterfaceAttributes` entry, add your new + entry + `"XYZ Mode": [ "SupportedModes", "CurrentMode", "FeatureMap" ]` - + this will mean ZAP won't generate code to handle these attributes + 10. In + [src/app/zap_cluster_list.json](https://github.com/project-chip/connectedhomeip/blob/master/src/app/zap_cluster_list.json): + 1. Add your `XYZ_MODE_CLUSTER: []` to `ClientDirectories: { }` + object + 2. Add your `"XYZ_MODE_CLUSTER": ["mode-base-server"]` to + `"ServerDirectories": { }` + 4. The code under + [src/app/tests/suites/certification](https://github.com/project-chip/connectedhomeip/blob/master/src/app/tests/suites/certification) + for YAML or + [src/python_testing](https://github.com/project-chip/connectedhomeip/tree/master/src/python_testing) + for Python should ideally implement the test plan (section 4 below). + 5. A test under + [src/app/tests/suites](https://github.com/project-chip/connectedhomeip/blob/master/src/app/tests/suites) + (not certification) can test anything, in addition to, or preceding the + official YAML representing the official test plan. +4. Add the test plan, using the templates below: + + 1. [cluster_test_plan_template.adoc](https://github.com/CHIP-Specifications/chip-test-plans/blob/master/src/template/cluster_test_plan_template.adoc) + 2. [test_plan_template.adoc](https://github.com/CHIP-Specifications/chip-test-plans/blob/master/src/template/test_plan_template.adoc) + + Also, ask to be added to the private `csg-tt-test-plans` Slack channel. + +5. Note: the CHIP-Tool reference client is generated from XML +6. If applicable, add tests: + 1. For relatively simple tests, add YAML tests here: + [src/app/tests/suites/certification](https://github.com/project-chip/connectedhomeip/blob/master/src/app/tests/suites/certification). + Remember to update this file: + [src/app/tests/suites/certification/PICS.yaml](https://github.com/project-chip/connectedhomeip/blob/master/src/app/tests/suites/certification/PICS.yaml) + 2. For more complex tests, add Python tests here: + [src/python_testing](https://github.com/project-chip/connectedhomeip/tree/master/src/python_testing) + 3. To add tests to CI, if applicable: + 1. Add the Python tests here: + [.github/workflows/tests.yaml](https://github.com/project-chip/connectedhomeip/tree/master/.github/workflows/tests.yaml). + Remember to provide all arguments required for each Python script, + such as the endpoint PIXIT. + 2. Add the YAML tests by editing this file: + [src/app/tests/suites/ciTests.json](https://github.com/project-chip/connectedhomeip/tree/master/src/app/tests/suites/ciTests.json) + 1. Create a section ("MyDevice") which lists all YAML tests for your + device + 2. Add the section's name to the list of items named "collection" + 3. Do a ZAP code regen: `./scripts/tools/zap_regen_all.py`. +7. Add the device type spec to the test plan tools: + + 1. [tools/device_type_requirements](https://github.com/CHIP-Specifications/chip-test-plans/tree/master/tools/device_type_requirements) + 2. The file above is used by + [src/app/tests/suites/certification/Test_TC_DESC_2_1.yaml](https://github.com/project-chip/connectedhomeip/blob/master/src/app/tests/suites/certification/Test_TC_DESC_2_1.yaml) + + Note: the plan is to make the DM tools generate the device type requirements + data based on the spec, so the above will become obsolete. + +8. Add the device type to Chef: + [examples/chef/devices](https://github.com/project-chip/connectedhomeip/tree/master/examples/chef/devices) + +## Q & A + +**Q1**: What kind of devices can be used for the test events? Can one of them be +the example cluster server app running on a RasPI? Do the independent +realizations need to run on vendor hardware or can they also run on generic +hardware, such as ESP32 or RasPI? + +**A1**: one realization can be the test harness + the all clusters example app + +RasPI. the two independent realizations need to run on target hardware, which +may be mock-ups, prototypes etc + +**Q2**: How can the Chef tool be used for any of the deliverables above? + +**A2**: TBD + +**Q3**: What is the process for using the Zap tool in order to auto-generate +code and to commit the results to the git repo? + +**A3**: Search for zap_regen above. Add all the changed files to the repo after. + +**Q4**: Where can the older cluster definitions be found? + +**A4**: src/app/zap-templates/zcl/data-model/silabs/general.xml + +**Q5**: Where can I find ZAP documentation? + +**A5**: https://github.com/project-chip/zap/blob/master/README.md diff --git a/_sources/cluster_and_device_type_dev/index.md b/_sources/cluster_and_device_type_dev/index.md new file mode 100644 index 000000000000..e84d222c7519 --- /dev/null +++ b/_sources/cluster_and_device_type_dev/index.md @@ -0,0 +1,17 @@ +# Cluster and Device Type development + +The following docs present a guide on how to develop new clusters and device +types in the SDK. + +```{toctree} +:glob: +:maxdepth: 1 +:hidden: + +* + +``` + +- [Cluster and device type development](./cluster_and_device_type_dev.md) +- [How To Add New Device Types & Clusters](./how_to_add_new_dts_and_clusters.md) +- [Cluster Server design](./unit_testing_clusters.md) diff --git a/_sources/cluster_and_device_type_dev/unit_testing_clusters.md b/_sources/cluster_and_device_type_dev/unit_testing_clusters.md new file mode 100644 index 000000000000..374fa6184993 --- /dev/null +++ b/_sources/cluster_and_device_type_dev/unit_testing_clusters.md @@ -0,0 +1,172 @@ +# Designing Clusters for Testing and Portability + +## Unit Testable, Modular Cluster Design + +When designing new clusters, consider the following approach: + +- Separate the cluster logic from the on-the-wire data model + - Server vs. ClusterLogic + - Makes the cluster logic unit-testable without generating TLV. +- Separate the basic cluster logic from code that is platform- or + device-specific. + - ClusterLogic uses a ClusterDriver + - Makes the cluster logic portable between platforms / manufacturers + - Removes necessity of overriding global singleton functions like + PostAttributeChangeCallback. + +General approach: + +![](./img/unit_testable_clusters.png) + +Class proposal: + +![](./img/unit_testable_clusters_all_classes.png) + +### ClusterServer + +![](./img/unit_testable_clusters_server.png) + +The ClusterServerClass is a **Very** light wrapper over ClusterLogic. It +translates Interaction Model wire format handling into API calls for cluster +logic methods. + +This class implements both the AttributeAccessInterface and the CommandHandler +interfaces so ClusterLogic properly handles data dependencies between commands +and attributes. + +An example code snippet showing the translation of the TLV into API calls to the +ClusterLogic class: + +``` +CHIP_ERROR DiscoBallServer::Read(const ConcreteReadAttributePath & aPath, + AttributeValueEncoder & aEncoder) +{ + DiscoBallClusterLogic * cluster = FindEndpoint(aPath.mEndpointId); + VerifyOrReturnError(cluster != nullptr, CHIP_IM_GLOBAL_STATUS(UnsupportedEndpoint)); + + switch (aPath.mAttributeId) + { + case Clusters::DiscoBall::Attributes::Run::Id: + return aEncoder.Encode(cluster->GetRunAttribute()); + … + } +} +``` + +### ClusterLogic + +![](./img/unit_testable_clusters_logic.png) + +The ClusterLogic class is for all the code that is SHARED between platforms. It +does NOT include any TLV parsing or direct calls to Ember/IM/LogEvent etc. + +The class should include attribute getters/setters and handlers for all +commands. + +The class receives “plain data” Matter requests from ClusterServer class, +performs required common actions, and calls driver class to perform platform- or +hardware-specific actions. It also receives driver updates (e.g. +application-driven value changes) from the ClusterDriver class and updates state +as appropriate. + +The class should handle spec-requirements for: + + - Range checking (CONSTRAINT_ERROR) + - Attribute and metadata storage (persistent or in-memory) + - Data dependencies between commands and attributes + - Event generation / dirty attributes (callback to server) + - Calling driver when platform or hardware interactions are required + +API recommendation: + + - Maintain all cluster state in a separate data-only class. + - Provider getters/setters for application logic to use. + - Implement handlers for all commands, conditional on features. + - Let the caller provide (inject) dependencies. Avoid explicit memory + management. + +### ClusterDriver + +Implements hardware or platform-specific actions required on cluster +interactions or when application wants to report state changes. + +![](./img/unit_testable_clusters_driver.png) + +### MatterContext + +The ClusterLogic class must not directly use global resource because they cannot +be isolated for testing. Instead, the MatterContext holds pointers to Matter +stack objects, which can be be injected / faked for testing. This includes - +Wrapper over IM Engine interface functions for marking attributes dirty, and +logging events. - Storage - Anything you would normally access with +Server::GetInstance() + +![](./img/unit_testable_clusters_context.png) + +### ClusterDriver + +The ClusterDriver is called by the ClusterLogic class and is used to translate +attribute changes and commands into application actions. It also reports +external changes back to the ClusterLogic class. + +The API design for this class will vary by the cluster, but it is generally +recommended to use a generic API where possible, so the API ports easily to +other platforms, for example an attribute changed callback with the changes +listed. It is important to be careful about the design and revisit this early if +issues arise. + +## Unit testing with the modular cluster design + +### ClusterLogic class + +The unit test instantiates the ClusterLogic, provides MatterContext and +ClusterDriver instance with fakes/mocks for testing. + +Unit test against the API, and check the fakes/mocks to ensure they are being +called as appropriate. + +As with all unit tests, prefer testing for behavior rather than implementation +details. + +Important tests to consider: + +- Initialization and initial attribute correctness. +- Errors for out-of-range on all attribute setters and command handlers. +- All spec-defined error conditions, especially ones that are difficult to + trigger. +- Data dependencies between commands and attributes. +- Incoming actions in different states (stopped, running, etc). +- Calls out to storage for persistent attributes. +- Calls out to driver for changes as appropriate. +- Driver error reporting. +- Event generation and dirty attribute marking, including attributes that are + changed from the driver side. +- Others - very dependent on the cluster. + +# Unit testing ClusterServer + +- Best to have the lightest wrapping possible + - If the wrapper is light, the code can be covered by integration or unit + tests, or a combination. + - Correctness can mostly be validated by inspection if it’s trivial. +- Important tests + - Errors when ClusterLogic instances aren’t properly registered. + - Flow through to ClusterLogic for all reads/writes/commands. +- Can unit test this class by generating the TLV / path for input, parsing the + TLV output. + +# Unit testing existing clusters + +- Important for clusters where there are multiple configurations that cannot + easily be represented with example apps +- Option 1 + - Refactor the cluster logic to be unit-testable. +- Option 2 + - Test at AttributeAccessInterface boundary. + - Instantiate or access the cluster server instance in the test. + - Read / Write TLV and use TLV encode/decode functions to verify + correctness. + - See TestPowerSourceCluster for an example of how to do this +- Additional test coverage on clusters, especially for hard to trigger + conditions, is important. However, **don’t let perfection be the enemy of + progress** . diff --git a/_sources/data_model/README.md b/_sources/data_model/README.md new file mode 100644 index 000000000000..83f0037572cc --- /dev/null +++ b/_sources/data_model/README.md @@ -0,0 +1,31 @@ +--- +orphan: true +--- + +## Contents + +This folder contains a machine-readable representation of matter clusters. + +The XML files inside `clusters` are generated by a `scraper` script out of the +original specification `AsciiDoc` files. + +## How to update + +The matter specification is not currently public. As such, as script exists to +update the spec XML files, however this is not done automatically. + +You will require access to the following tools locally: + +- `scraper`. A binary copy generally available + [here](https://github.com/csa-data-model/projects/tree/main/DM-Editor/bin/scrape) +- Specification repository checkout from + https://github.com/CHIP-Specifications/connectedhomeip-spec + +Example usage: + +```sh +./scripts/spec_xml/generate_spec_xml.py \ + --scraper ~/Downloads/scrape-adoc-linux \ + --spec-root ~/work/connectedhomeip-spec \ + --output-dir data_model +``` diff --git a/_sources/development_controllers/chip-repl/index.md b/_sources/development_controllers/chip-repl/index.md new file mode 100644 index 000000000000..cb25e24c0fd0 --- /dev/null +++ b/_sources/development_controllers/chip-repl/index.md @@ -0,0 +1,15 @@ +# chip-repl + +```{toctree} +:glob: +:maxdepth: 1 +:hidden: + +* +``` + +- [Matter REPL](./matter-repl.md) +- [Intro](https://github.com/project-chip/connectedhomeip/blob/master/./Matter_REPL_Intro.ipynb) +- [Access Control](https://github.com/project-chip/connectedhomeip/blob/master/./Matter_Access_Control.ipynb) +- [Basic interactions](https://github.com/project-chip/connectedhomeip/blob/master/./Matter_Basic_Interactions.ipynb) +- [Fabric Commissioning](https://github.com/project-chip/connectedhomeip/blob/master/./Matter_Multi_Fabric_Commissioning.ipynb) diff --git a/_sources/development_controllers/chip-repl/matter-repl.md b/_sources/development_controllers/chip-repl/matter-repl.md new file mode 100644 index 000000000000..72c4151e3052 --- /dev/null +++ b/_sources/development_controllers/chip-repl/matter-repl.md @@ -0,0 +1,271 @@ +# Matter Python REPL + +The Matter Python REPL is a native IPython shell environment loaded with a +Python-wrapped version of the C++ Matter stack to permit interacting as a +controller to other Matter-compliant devices. + +You can interact with the REPL in a one of three ways: + +1. Through an IPython shell built from source +2. Through a locally built 'REPL Playground', which is a Jupyter Lab environment + that supports launching both a native IPython shell as well as Guide + Notebooks. +3. Through a cloud-hosted REPL Playground that has pre-built versions of the + REPL that can be interacted with through a browser. + +This guide provides instructions on how to utilize its various features. + +### + +## Source files + +You can find source files of the Python CHIP Controller tool in the +`src/controller/python` directory. + +The tool uses the generic CHIP Device Controller library, available in the +`src/controller` directory. + +## Building + +Please follow the instructions +[here](./python_chip_controller_building.md#building-and-installing) to build +the Python virtual environment. + +### Building for `arm64` e.g. for Raspberry Pi + +Matter code relies on code generation for cluster-specific data types and +callbacks. A subset of code generation is done at compile time by `zap-cli`. ZAP +is generally installed as a third-party tool via CIPD during the build +environment bootstrap. However, zap packages are currently NOT available for +`arm64` (like when compiling on Raspberry PI.). In this case, you have 2 +choices. + +1. You could check out zap from source as described in + [Code Generation - Installing zap and environment variables](https://github.com/project-chip/connectedhomeip/blob/master/docs/code_generation.md#Installing-zap-and-environment-variables) + and proceed with the + [instructions](./python_chip_controller_building.md#building-and-installing) + to build the Python virtual environment. + +2. When compile-time code generation is not desirable, then pre-generated output + code can be used. To understand about code generation and pre-generating + matter code see. + [Code generation - Pre-generation](https://github.com/project-chip/connectedhomeip/blob/master/docs/code_generation.md#Pre-generation). + To build and install the Python CHIP controller with pre-generated files use + the -z argument that points to the directory of pre-generated code: + + ``` + scripts/build_python.sh -m platform -i out/python_env -z "/some/pregen/dir" + ``` + + > Note: To get more details about available build configurations, run the + > following command: `scripts/build_python.sh --help` + +## Launching the REPL + +1. Activate the Python virtual environment: + + ``` + source out/python_env/bin/activate + ``` + +2. Launch the REPL. + + ``` + sudo out/python_env/bin/chip-repl + ``` + +> By default, the REPL points to `/tmp/repl-storage.json` for persistent +> storage. You can over-ride that location by passing in `--storagepath ` +> to the above invocation. + +## REPL Playground + +The REPL playground is a Jupyter Lab instance that allows you to interact with +the REPL from a web browser (or a Jupyter Notebook client of your choice!). It +contains the entire REPL encapsulated as an IPython kernel. + +### Locally Hosted + +The locally hosted version requires you to follow the build instructions below +to initially setup your Python environment. + +Then: + +1. Install + [Jupyter Lab](https://jupyterlab.readthedocs.io/en/stable/getting_started/installation.html) + (not within the virtualenv!) + +``` +pip3 install jupyterlab ipykernel +``` + +2. Install the [Python LSP](https://github.com/jupyter-lsp/jupyterlab-lsp) + extension for better code autocompletion in the playground. + +``` +pip3 install jupyterlab-lsp +pip3 install python-lsp-server +``` + +3. Every virtual env needs to be installed as a 'kernel' in Jupyter Lab. To do + so, activate the virtual env and run: + +``` +python -m ipykernel install +``` + +4. Navigate to the SDK root folder and launch Jupyter Lab (not from within + virtual env!) + +``` +jupyter-lab +``` + +This will automatically launch the playground on your browser. + +5. (Optional) To enable live code completions, in the Jupyter Lab Interface, go + to "Settings" → "Advanced Settings Editor" → "Code Completion". In the "User + Preferences" section, add the following: + +``` +{ + "continuousHinting": true, + "showDocumentation": true, + "theme": 'material' +} +``` + +Now, when you type, it should auto complete functions/objects/etc. + +For more details, go to the +[Python LSP](https://github.com/jupyter-lsp/jupyterlab-lsp) page. + +### Cloud Hosted + +A pre-built version of the REPL playground is made available through the cloud. +This is ideal if you're new to the REPL and want to try it out without having to +follow the build and launch instructions below. You can also use this to +prototype various bits of logic in Python as well as interact with +all-clusters-app from a browser. + +The playground can be accessed [here](http://35.236.121.59/). + +> **NOTE:** You have to create a user ID when accessing the above for the first +> time (password can be blank). That creates a sandboxed environment for you to +> play in. There-after, you'll always be re-directed straight to the Jupyter Lab +> landing page. + +> **NOTE:** The sandbox is temporary. After an hour of inactivity, the sandbox +> is deleted and your saved contents will be lost. + +For more information on Jupyter Lab, check out +[these](https://jupyterlab.readthedocs.io/en/stable/user/interface.html) docs. + +### IPython REPL + +Going through the above isn't terribly useful, since all you'll be able to do is +launch the REPL environment itself through the IPython shell. + +To launch the IPython REPL, launch "matter-env" from the "Console" tab in the +Launcher. + +### Guide Notebooks + +A number of Jupyter Notebooks have been written that serve as both guides for +interacting with the REPL _as well as_ being launchable directly into the +cloud-hosted playground. + +The following icon is present at the top of applicable guides that can be +launched into the playground: + +![Launch playground icon](https://i.ibb.co/hR3yWsC/launch-playground.png") +

+ +## Guides + +[REPL Basics](https://deepnote.com/viewer/github/project-chip/connectedhomeip/blob/master/docs/guides/repl/Matter_REPL_Intro.ipynb) + +[Using the IM](https://deepnote.com/viewer/github/project-chip/connectedhomeip/blob/master/docs/guides/repl/Matter_Basic_Interactions.ipynb) + +[Multi Fabric Commissioning](https://deepnote.com/viewer/github/project-chip/connectedhomeip/blob/master/docs/guides/repl/Matter_Multi_Fabric_Commissioning.ipynb) + +[Access Control](https://deepnote.com/viewer/github/project-chip/connectedhomeip/blob/master/docs/guides/repl/Matter_Access_Control.ipynb) + +## Testing + +We also provide `mobile-device-test.py` for testing your accessories, you can +run it manually or using a wrapper script. + +### Usage + +mobile-device-test.py provides the following options for running the tests: + +``` + --controller-nodeid INTEGER NodeId of the controller. + --device-nodeid INTEGER NodeId of the device. + -a, --address TEXT Skip commissionee discovery, commission the + device with the IP directly. + + -t, --timeout INTEGER The program will return with timeout after + specified seconds. + + --discriminator INTEGER Discriminator of the device. + --setup-pin INTEGER Setup pincode of the device. + --enable-test TEXT The tests to be executed. By default, all + tests will be executed, use this option to + run a specific set of tests. Use --print- + test-list for a list of applicable tests. + + --disable-test TEXT The tests to be excluded from the set of + enabled tests. Use --print-test-list for a + list of applicable tests. + + --log-level [ERROR|WARN|INFO|DEBUG] + The log level of the test. + --log-format TEXT Override logging format + --print-test-list Print a list of test cases and test sets + that can be toggled via --enable-test and + --disable-test, then exit + + --help Show this message and exit. +``` + +By default, all tests will be executed, however, you can exclude one or more +tests or only include a few tests if you want. + +For example, if you are working for commissioning, then you may want to exclude +the data model test cases by adding `--disable-test datamodel` to disable all +data model tests. + +Some tests provides the option to exclude them. For example, you can use +`--disable-test ClusterObjectTests.TestTimedRequestTimeout` to exclude the +"TestTimedRequestTimeout" test case. + +It is recommended to use the test wrapper to run mobile-device-test.py, for +example, you can run: + +```shell +./scripts/tests/run_python_test.py --app chip-all-clusters-app --factory-reset +``` + +It provides some extra options, for example: + +``` +optional arguments: + -h, --help show this help message and exit + --app APP Path to local application to use, omit to use external apps. + --factory-reset Remove app config and repl configs (/tmp/chip* and /tmp/repl*) before running the tests. + --app-args APP_ARGS The extra parameters passed to the device side app. + --script SCRIPT Path to the test script to use, omit to use the default test script (mobile-device-test.py). + --script-args SCRIPT_ARGS Arguments for the REPL test script +``` + +You can pass your own flags for mobile-device-test.py by appending them to the +command line with two dashes, for example: + +```shell +./scripts/tests/run_python_test.py --app out/linux-x64-all-clusters-no-ble-no-wifi-tsan-clang/chip-all-clusters-app --factory-reset --script-args "-t 90 --disable-test ClusterObjectTests.TestTimedRequestTimeout" +``` + +will pass `-t 90 --disable-test ClusterObjectTests.TestTimedRequestTimeout` to +`mobile-device-test.py` diff --git a/_sources/development_controllers/chip-repl/python_chip_controller_advanced_usage.md b/_sources/development_controllers/chip-repl/python_chip_controller_advanced_usage.md new file mode 100644 index 000000000000..25aa2ae2fa13 --- /dev/null +++ b/_sources/development_controllers/chip-repl/python_chip_controller_advanced_usage.md @@ -0,0 +1,270 @@ +# Using Python CHIP Controller advanced features + +This document extends the +[basic documentation](python_chip_controller_building.md) of the Python CHIP +Controller with the useful information when developing Python CHIP Controller +tool or Matter accessories on Linux. + +
+ +- [Using Python CHIP Controller advanced features](#using-python-chip-controller-advanced-features) + - [Bluetooth LE virtualization on Linux](#bluetooth-le-virtualization-on-linux) + - [Debugging with gdb](#debugging-with-gdb) + +
+ +## Bluetooth LE virtualization on Linux + +Commissioning over Bluetooth LE can be tested even if the controller and the +device run on the same machine. To that end, you will need to set up two virtual +interfaces working as Bluetooth LE central and peripheral, respectively. + +1. Build `bluez` project from sources by completing the following steps: + + ``` + sudo apt-get update + sudo apt-get install libtool m4 automake autotools-dev libudev-dev libical-dev libreadline-dev + + git clone https://github.com/bluez/bluez.git + + cd bluez + ./bootstrap + ./configure --prefix=/usr --mandir=/usr/share/man --sysconfdir=/etc --localstatedir=/var --enable-experimental --with-systemdsystemunitdir=/lib/systemd/system --with-systemduserunitdir=/usr/lib/systemd --enable-deprecated --enable-testing --enable-tools + make + ``` + +2. Run bluetoothd: + + ``` + sudo ./src/bluetoothd --experimental --debug & + ``` + +3. Bring up two virtual Bluetooth LE interfaces: + + ``` + sudo ./emulator/btvirt -L -l2 + ``` + + You can find the virtual interface by running `hciconfig` command: + + ``` + $ hciconfig + + hci2: Type: Primary Bus: Virtual + BD Address: 00:AA:01:01:00:24 ACL MTU: 192:1 SCO MTU: 0:0 + UP RUNNING + RX bytes:0 acl:95 sco:0 events:205 errors:0 + TX bytes:2691 acl:95 sco:0 commands:98 errors:0 + + hci1: Type: Primary Bus: Virtual + BD Address: 00:AA:01:00:00:23 ACL MTU: 192:1 SCO MTU: 0:0 + UP RUNNING + RX bytes:0 acl:95 sco:0 events:208 errors:0 + TX bytes:3488 acl:95 sco:0 commands:110 errors:0 + ``` + +4. Run the Python CHIP Controller REPL with Bluetooth LE adapter defined from a + command line: + + For example, add `--ble-adapter=2` to use the virtual interface `hci2` + listed above. + + ``` + chip-repl --ble-adapter=2 + ``` + +
+ +## Debugging with gdb + +You can run the chip-repl under GDB for debugging, however, since the Matter SDK +library is a dynamic library, you cannot read the symbols unless it is fully +loaded. + +The following block is a example debug session using GDB: + +``` +# GDB cannot run scripts directly +# so you need to run Python3 with the path of device controller REPL +# Here, we use the feature from bash to get the path of chip-repl without typing it. +$ gdb --args python3 `which chip-repl` +GNU gdb (GDB) 14.2 +Copyright (C) 2023 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +Type "show copying" and "show warranty" for details. +This GDB was configured as "x86_64-pc-linux-gnu". +Type "show configuration" for configuration details. +For bug reporting instructions, please see: +. +Find the GDB manual and other documentation resources online at: + . + +For help, type "help". +Type "apropos word" to search for commands related to "word"... +Reading symbols from python3... + +This GDB supports auto-downloading debuginfo from the following URLs: + +Enable debuginfod for this session? (y or [n]) n +Debuginfod has been disabled. +To make this setting permanent, add 'set debuginfod enabled off' to .gdbinit. +(No debugging symbols found in python3) +(gdb) +``` + +The Python will create lots of threads due to main loop, so you may want to +suppress thread related outputs first by running the following command: + +``` +(gdb) set print thread-events off +``` + +We cannot set breakpoints here, since the GDB knows nothing about the Matter +library, let run the Matter device controller first. + +``` +(gdb) run +Starting program: /home/sag/projects/project-chip/connectedhomeip/out/venv/bin/python3 /home/sag/projects/project-chip/connectedhomeip/out/venv/bin/chip-repl +[Thread debugging using libthread_db enabled] +Using host libthread_db library "/usr/lib/libthread_db.so.1". +Python 3.11.9 (main, Apr 29 2024, 11:59:58) [GCC 13.2.1 20240417] +Type 'copyright', 'credits' or 'license' for more information +IPython 8.24.0 -- An enhanced Interactive Python. Type '?' for help. +[1716395111.775747][364405:364405] CHIP:CTL: Setting attestation nonce to random value +[1716395111.776196][364405:364405] CHIP:CTL: Setting CSR nonce to random value +InitBLE 0[1716395111.776809][364405:364405] CHIP:DL: writing settings to file (/tmp/chip_counters.ini-T7hX27) +[1716395111.776854][364405:364405] CHIP:DL: renamed tmp file to file (/tmp/chip_counters.ini) +[1716395111.776860][364405:364405] CHIP:DL: NVS set: chip-counters/reboot-count = 9 (0x9) +[1716395111.777261][364405:364405] CHIP:DL: Got Ethernet interface: eno2 +[1716395111.777555][364405:364405] CHIP:DL: Found the primary Ethernet interface:eno2 +[1716395111.777868][364405:364405] CHIP:DL: Got WiFi interface: wlp7s0 +[1716395111.777877][364405:364405] CHIP:DL: Failed to reset WiFi statistic counts +────────────────────────────────────────────────────────────────────────────────────────────────────────── Matter REPL ────────────────────────────────────────────────────────────────────────────────────────────────────────── + + + + Welcome to the Matter Python REPL! + + For help, please type matterhelp() + + To get more information on a particular object/class, you can pass + that into matterhelp() as well. + + +───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── +2024-05-22 18:25:11 allenwind PersistentStorage[364405] WARNING Initializing persistent storage from file: /tmp/repl-storage.json +2024-05-22 18:25:11 allenwind PersistentStorage[364405] WARNING Loading configuration from /tmp/repl-storage.json... +2024-05-22 18:25:11 allenwind CertificateAuthorityManager[364405] WARNING Loading certificate authorities from storage... +2024-05-22 18:25:11 allenwind CertificateAuthority[364405] WARNING New CertificateAuthority at index 1 +2024-05-22 18:25:11 allenwind CertificateAuthority[364405] WARNING Loading fabric admins from storage... +2024-05-22 18:25:11 allenwind FabricAdmin[364405] WARNING New FabricAdmin: FabricId: 0x0000000000000001, VendorId = 0xFFF1 +2024-05-22 18:25:11 allenwind FabricAdmin[364405] WARNING Allocating new controller with CaIndex: 1, FabricId: 0x0000000000000001, NodeId: 0x000000000001B669, CatTags: [] + + +The following objects have been created: + certificateAuthorityManager: Manages a list of CertificateAuthority instances. + caList: The list of CertificateAuthority instances. + caList: A specific FabricAdmin object at index m for the nth CertificateAuthority instance. + + +Default CHIP Device Controller (NodeId: 112233): has been initialized to manage caList[0].adminList[0](FabricId = 1), and is available as devCtrl + +In [1]: +``` + +The prompt `In [1]:` indicates that the Matter SDK library has been loaded and +initialized by the Python Controller REPL, you can browse the symbols in the +Matter core library, setting breakpoints on functions and many other functions +provided by GDB. + +You can use `Ctrl-Z` to send `SIGTSTP` to the Python 3 REPL process anytime you +want so you can set breakpoints (unfortunately Ctrl+C seems to be captured by +the REPL). + +In [1]: (`Ctrl-Z` pressed here.) + +``` +Thread 1 "python3" received signal SIGTSTP, Stopped (user). +0x00007ffff7650ceb in kill () from /usr/lib/libc.so.6 +(gdb) +``` + +For example, you can break on `DeviceCommissioner::PairDevice` by using `break` +command in GDB (`b` for short) + +``` +(gdb) b DeviceCommissioner::PairDevice +Breakpoint 1 at 0x7fffed453943: DeviceCommissioner::PairDevice. (4 locations) +(gdb) +``` + +Type `signal SIGCONT` to continue the device controller after stopping it with +signal stop, you may need another hit of `Enter` to see the prompt. + +``` +(gdb) signal SIGCONT +Continuing with signal SIGCONT. +In [1]: +``` + +Let do pairing over IP to see the effect of the breakpoint we just set. + +``` +In [1]: devCtrl.CommissionWithCode("MT:-24J0AFN00KA0648G00", 1234) + +Thread 5 "python3" hit Breakpoint 1.1, chip::Controller::DeviceCommissioner::PairDevice (this=0x7fffd8003a90, remoteDeviceId=1234, setUpCode=0x7ffff453d490 "MT:-24J0AFN00KA0648G00", params=..., + discoveryType=chip::Controller::DiscoveryType::kAll, resolutionData=...) at ../../src/controller/CHIPDeviceController.cpp:646 +646 { +(gdb) +``` + +You can find the `this` pointer, and value of arguments passed to this function, +then you can use `bt` (for `backtrace`) to see the backtrace of the call stack. + +``` +(gdb) bt +(gdb) bt +#0 chip::Controller::DeviceCommissioner::PairDevice + (this=0x7fffd8003a90, remoteDeviceId=1234, setUpCode=0x7fffef2555d0 "MT:-24J0AFN00KA0648G00", params=..., discoveryType=chip::Controller::DiscoveryType::kAll, resolutionData=...) + at ../../src/controller/CHIPDeviceController.cpp:646 +#1 0x00007fffed040825 in pychip_DeviceController_ConnectWithCode (devCtrl=0x7fffd8003a90, onboardingPayload=0x7fffef2555d0 "MT:-24J0AFN00KA0648G00", nodeid=1234, discoveryType=2 '\002') + at ../../src/controller/python/ChipDeviceController-ScriptBinding.cpp:395 +#2 0x00007ffff6ad5596 in ??? () at /usr/lib/libffi.so.8 +#3 0x00007ffff6ad200e in ??? () at /usr/lib/libffi.so.8 +#4 0x00007ffff6ad4bd3 in ffi_call () at /usr/lib/libffi.so.8 +#5 0x00007ffff6aeaffc in ??? () at /usr/lib/python3.11/lib-dynload/_ctypes.cpython-311-x86_64-linux-gnu.so +#6 0x00007ffff6aeb4b4 in ??? () at /usr/lib/python3.11/lib-dynload/_ctypes.cpython-311-x86_64-linux-gnu.so +#7 0x00007ffff794a618 in _PyObject_MakeTpCall () at /usr/lib/libpython3.11.so.1.0 +#8 0x00007ffff78f3d03 in _PyEval_EvalFrameDefault () at /usr/lib/libpython3.11.so.1.0 +#9 0x00007ffff7adef90 in ??? () at /usr/lib/libpython3.11.so.1.0 +#10 0x00007ffff79ebc0b in _PyObject_FastCallDictTstate () at /usr/lib/libpython3.11.so.1.0 +#11 0x00007ffff79ebe02 in _PyObject_Call_Prepend () at /usr/lib/libpython3.11.so.1.0 +#12 0x00007ffff79ec114 in ??? () at /usr/lib/libpython3.11.so.1.0 +#13 0x00007ffff794a618 in _PyObject_MakeTpCall () at /usr/lib/libpython3.11.so.1.0 +#14 0x00007ffff78f3d03 in _PyEval_EvalFrameDefault () at /usr/lib/libpython3.11.so.1.0 +#15 0x00007ffff7adef90 in ??? () at /usr/lib/libpython3.11.so.1.0 +#16 0x00007ffff7955b97 in PyObject_Vectorcall () at /usr/lib/libpython3.11.so.1.0 +#17 0x00007ffff6aea174 in ??? () at /usr/lib/python3.11/lib-dynload/_ctypes.cpython-311-x86_64-linux-gnu.so +#18 0x00007ffff6aea28c in ??? () at /usr/lib/python3.11/lib-dynload/_ctypes.cpython-311-x86_64-linux-gnu.so +#19 0x00007ffff6ad5152 in ??? () at /usr/lib/libffi.so.8 +#20 0x00007ffff6ad57b8 in ??? () at /usr/lib/libffi.so.8 +#21 0x00007fffed5de848 in chip::DeviceLayer::Internal::GenericPlatformManagerImpl::_DispatchEvent + (this=0x7fffed88dc90 , event=0x7fffe6fffe30) at ../../src/include/platform/internal/GenericPlatformManagerImpl.ipp:304 +#22 0x00007fffed5dd90d in chip::DeviceLayer::PlatformManager::DispatchEvent (this=0x7fffed88dc80 , event=0x7fffe6fffe30) at ../../src/include/platform/PlatformManager.h:503 +#23 0x00007fffed5df45b in chip::DeviceLayer::Internal::GenericPlatformManagerImpl_POSIX::ProcessDeviceEvents + (this=0x7fffed88dc90 ) at ../../src/include/platform/internal/GenericPlatformManagerImpl_POSIX.ipp:185 +#24 0x00007fffed5dee64 in chip::DeviceLayer::Internal::GenericPlatformManagerImpl_POSIX::_RunEventLoop (this=0x7fffed88dc90 ) +--Type for more, q to quit, c to continue without paging-- + at ../../src/include/platform/internal/GenericPlatformManagerImpl_POSIX.ipp:227 +#25 0x00007fffed5dd888 in chip::DeviceLayer::PlatformManager::RunEventLoop (this=0x7fffed88dc80 ) at ../../src/include/platform/PlatformManager.h:403 +#26 0x00007fffed5df3fe in chip::DeviceLayer::Internal::GenericPlatformManagerImpl_POSIX::EventLoopTaskMain (arg=0x7fffed88dc90 ) + at ../../src/include/platform/internal/GenericPlatformManagerImpl_POSIX.ipp:256 +#27 0x00007ffff76a6ded in ??? () at /usr/lib/libc.so.6 +#28 0x00007ffff772a0dc in ??? () at /usr/lib/libc.so.6 +(gdb) +``` + +The frame #0 and frame #1 are the function frames in the CHIP C++ library, the +other frames live in the Python interpreter so you can ignore it. diff --git a/_sources/development_controllers/chip-repl/python_chip_controller_building.md b/_sources/development_controllers/chip-repl/python_chip_controller_building.md new file mode 100644 index 000000000000..7181802b9d45 --- /dev/null +++ b/_sources/development_controllers/chip-repl/python_chip_controller_building.md @@ -0,0 +1,411 @@ +# Working with Python CHIP Controller + +The Python CHIP controller is a library that allows to create a Matter fabric +and commission Matter devices with it. + +The `chip-repl` is a REPl which sets up a Python CHIP Controller and allows to +explore the Python CHIP Controller API and communicate with devices from the +command line. + +
+ +- [Source files](#source-files) +- [Building Python CHIP Controller](#building-and-installing) +- [Running the CHIP REPL](#running-the-chip-repl) +- [Using Python CHIP Controller REPL for Matter accessory testing](#using-python-chip-controller-repl-for-matter-accessory-testing) +- [Example usage of the Python CHIP Controller REPL](#example-usage-of-the-python-chip-controller-repl) +- [Explore Clusters, Attributes and Commands](#explore-clusters-attributes-and-commands) + +
+ +## Source files + +You can find source files of the Python CHIP Controller tool in the +`src/controller/python` directory. + +The tool uses the generic CHIP Device Controller library, available in the +`src/controller` directory. + +
+ +## Building and installing + +Before you can use the Python controller, you must compile it from the source on +Linux (amd64 / aarch64) or macOS. + +> To ensure compatibility, build the Python CHIP controller and the Matter +> device from the same revision of the connectedhomeip repository. + +To build and run the Python CHIP controller: + +1. Install all necessary packages and prepare the build system. For more + details, see the [Building Matter](../../guides/BUILDING.md) documentation: + + ``` + sudo apt-get update + sudo apt-get upgrade + + sudo apt-get install git gcc g++ python pkg-config libssl-dev libdbus-1-dev libglib2.0-dev libavahi-client-dev ninja-build python3-venv python3-dev python3-pip unzip libgirepository1.0-dev libcairo2-dev bluez + ``` + + If the Python CHIP controller is built on a Raspberry Pi, install additional + packages and reboot the device: + + ``` + sudo apt-get install pi-bluetooth + sudo reboot + ``` + +2. Clone the Project CHIP repository: + + ``` + git clone https://github.com/project-chip/connectedhomeip.git + ``` + +3. Enter the `connectedhomeip` directory: + + ``` + cd connectedhomeip + ``` + +4. Initialize the git submodules: + + ``` + git submodule update --init + ``` + +5. Build and install the Python CHIP controller: + + ``` + scripts/build_python.sh -m platform -i out/python_env + source out/python_env/bin/activate + ``` + + > Note: This builds the Python CHIP Controller along with the CHIP REPL as + > Python wheels and installs it into a separate Python virtual environment. + > To get more details about available build configurations, run the + > following command: `scripts/build_python.sh --help` + +
+ +## Running the CHIP REPL + +1. Activate the Python virtual environment with the Python CHIP Controller + installed: + + ``` + source out/python_env/bin/activate + ``` + +2. Run the CHIP REPL to explore the API of the Python CHIP controller: + + ``` + chip-repl + ``` + +
+ +## Using Python CHIP Controller REPL for Matter accessory testing + +This section describes how to use Python CHIP controller to test the Matter +accessory. Below steps depend on the application clusters that you implemented +on the device side and may be different for your accessory. + +### Step 1: Prepare the Matter accessory. + +This tutorial is using the Matter Light Bulb example with the Bluetooth LE +commissioning. However, you can adapt this procedure to other available Matter +examples. + +Build and program the device with the Matter accessory firmware by following the +example's documentation. + +### Step 2: Enable Bluetooth LE advertising on Matter accessory device. + +Some examples are configured to advertise automatically on boot. Other examples +require physical trigger, for example pushing a button. Follow the documentation +of the Matter accessory example to learn how Bluetooth LE advertising is enabled +for the given example. + +### Step 3: Discover commissionable Matter accessory device + +An uncommissioned accessory device advertises over Bluetooth LE or via mDNS if +already on the network. Run the following command to scan all advertised Matter +devices: + +``` +devCtrl.DiscoverCommissionableNodes() +``` + +### Step 4: Set network pairing credentials + +You must provide the controller with network credentials that will be further +used in the device commissioning procedure to configure the device with a +network interface, such as Thread or Wi-Fi. + +#### Setting Thread network credentials + +1. Fetch and store the current Active Operational Dataset from the Thread Border + Router. Depending on if the Thread Border Router is running on Docker or + natively on Raspberry Pi, execute the following commands: + + - For Docker: + + ``` + sudo docker exec -it otbr sh -c "sudo ot-ctl dataset active -x" + 0e080000000000010000000300001335060004001fffe002084fe76e9a8b5edaf50708fde46f999f0698e20510d47f5027a414ffeebaefa92285cc84fa030f4f70656e5468726561642d653439630102e49c0410b92f8c7fbb4f9f3e08492ee3915fbd2f0c0402a0fff8 + Done + ``` + + - For native installation: + + ``` + sudo ot-ctl dataset active -x + 0e080000000000010000000300001335060004001fffe002084fe76e9a8b5edaf50708fde46f999f0698e20510d47f5027a414ffeebaefa92285cc84fa030f4f70656e5468726561642d653439630102e49c0410b92f8c7fbb4f9f3e08492ee3915fbd2f0c0402a0fff8 + Done + ``` + + Matter specification does not define how the Thread or Wi-Fi credentials are + obtained by Controller. For example, for Thread, instead of fetching + datasets directly from the Thread Border Router, you might also use a + different out-of-band method. + +2. Set the previously obtained Active Operational Dataset as a byte array using + the following command: + + ``` + thread_dataset = bytes.fromhex("0e080000000000010000000300001335060004001fffe002084fe76e9a8b5edaf50708fde46f999f0698e20510d47f5027a414ffeebaefa92285cc84fa030f4f70656e5468726561642d653439630102e49c0410b92f8c7fbb4f9f3e08492ee3915fbd2f0c0402a0fff8") + devCtrl.SetThreadOperationalDataset(thread_dataset) + ``` + +#### Setting Wi-Fi network credentials + +Assuming your Wi-Fi SSID is _TESTSSID_, and your Wi-Fi password is _P455W4RD_, +set the credentials to the controller by executing the following command: + +``` +devCtrl.SetWiFiCredentials(, ) +``` + +### Step 5: Commission the Matter accessory device over Bluetooth LE + +The controller uses a 12-bit value called **discriminator** to discern between +multiple commissionable device advertisements, as well as a 27-bit **setup PIN +code** to authenticate the device. You can find these values in the logging +terminal of the device (for example, UART). For example: + +``` +I: 254 [DL]Device Configuration: +I: 257 [DL] Serial Number: TEST_SN +I: 260 [DL] Vendor Id: 65521 (0xFFF1) +I: 263 [DL] Product Id: 32768 (0x8000) +I: 267 [DL] Hardware Version: 1 +I: 270 [DL] Setup Pin Code: 20202021 +I: 273 [DL] Setup Discriminator: 3840 (0xF00) +I: 278 [DL] Manufacturing Date: (not set) +I: 281 [DL] Device Type: 65535 (0xFFFF) +``` + +Run the following command to establish the secure connection over Bluetooth LE, +with the following assumptions for the Matter accessory device: + +- The discriminator of the device is _3840_ +- The setup pin code of the device is _20202021_ +- The temporary Node ID is _1234_ + +``` +devCtrl.ConnectBLE(3840, 20202021, 1234) +``` + +You can skip the last parameter, the Node ID, in the command. If you skip it, +the controller will assign it randomly. In that case, note down the Node ID, +because it is required later in the configuration process. + +It is also possible to use the QR setup code instead. It typically is shown on +the terminal of the device as well. For example: + +``` +CHIP:SVR: SetupQRCode: [MT:-24J0AFN00KA0648G00] +``` + +Use the following command to commission the device with the QR code: + +``` +devCtrl.CommissionWithCode("MT:-24J0AFN00KA0648G00", 1234) +``` + +After connecting the device over Bluetooth LE, the controller will go through +the following stages: + +- Establishing a secure connection that completes the PASE + (Password-Authenticated Session Establishment) session using SPAKE2+ + protocol and results in printing the following log: + + ``` + Secure Session to Device Established + ``` + +- Providing the device with a network interface using ZCL Network + Commissioning cluster commands, and the network pairing credentials set in + the previous step. +- Discovering the IPv6 address of the Matter accessory using the SRP (Service + Registration Protocol) for Thread devices, or the mDNS (Multicast Domain + Name System) protocol for Wi-Fi or Ethernet devices. It results in printing + log that indicates that the node address has been updated. The IPv6 address + of the device is cached in the controller for later usage. +- Closing the Bluetooth LE connection, as the commissioning process is + finished and the Python CHIP controller is now using only the IPv6 traffic + to reach the device. + +### Step 6: Control application clusters. + +For the light bulb example, execute the following command to toggle the LED +state: + +``` +await devCtrl.SendCommand(1234, 1, Clusters.OnOff.Commands.Toggle()) +``` + +To change the brightness of the LED, use the following command, with the level +value somewhere between 0 and 255. + +``` +commandToSend = LevelControl.Commands.MoveToLevel(level=50, transitionTime=Null, optionsMask=0, optionsOverride=0) +await devCtrl.SendCommand(1234, 1, commandToSend) +``` + +### Step 7: Read basic information out of the accessory. + +Every Matter accessory device supports a Basic Information Cluster, which +maintains collection of attributes that a controller can obtain from a device, +such as the vendor name, the product name, or software version. Use +`ReadAttribute()` command to read those values from the device: + +``` +attributes = [ + (0, Clusters.BasicInformation.Attributes.VendorName), + (0, Clusters.BasicInformation.Attributes.ProductName), + (0, Clusters.BasicInformation.Attributes.SoftwareVersion), +] +await devCtrl.ReadAttribute(1234, attributes) +``` + +> In REPL, you can type `Clusters.BasicInformation.Attributes.` and then use the +> TAB key. + +
+ +## Example usage of the Python CHIP Controller REPL + +These section covers a few useful commands of the Python CHIP Controller along +with examples demonstrating how they can be called from the REPL. + +The +[CHIP Device Controller API documentation offer](https://project-chip.github.io/connectedhomeip-doc/testing/ChipDeviceCtrlAPI.html#chip-chipdevicectrl) +the full list of available commands. + +### `SetThreadOperationalDataset()` + +Provides the controller with Thread network credentials that will be used in the +device commissioning procedure to configure the device with a Thread interface. + +``` +thread_dataset = bytes.fromhex("0e080000000000010000000300001335060004001fffe002084fe76e9a8b5edaf50708fde46f999f0698e20510d47f5027a414ffeebaefa92285cc84fa030f4f70656e5468726561642d653439630102e49c0410b92f8c7fbb4f9f3e08492ee3915fbd2f0c0402a0fff8") +devCtrl.SetThreadOperationalDataset(thread_dataset) +``` + +### `SetWiFiCredentials(: str, : str)` + +Provides the controller with Wi-Fi network credentials that will be used in the +device commissioning procedure to configure the device with a Wi-Fi interface. + +``` +devCtrl.SetWiFiCredentials('TESTSSID', 'P455W4RD') +``` + +### `CommissionWithCode(: str, : int, : DiscoveryType)` + +Commission with the given nodeid from the setupPayload. setupPayload may be a QR +or the manual setup code. + +``` +devCtrl.CommissionWithCode("MT:-24J0AFN00KA0648G00", 1234) +``` + +### `SendCommand(: int, : int, Clusters..Commands.())` + +Send a Matter command to the device. For example: + +```python +commandToSend = Clusters.LevelControl.Commands.MoveWithOnOff(moveMode=1, rate=2, optionsMask=0, optionsOverride=0) +await devCtrl.SendCommand(1234, 1, commandToSend) +``` + +To see available arguments just create a command object without argument: + +``` +Clusters.LevelControl.Commands.MoveWithOnOff() +``` + +Shows which arguments are available: + +``` +MoveWithOnOff( +│ moveMode=0, +│ rate=Null, +│ optionsMask=0, +│ optionsOverride=0 +) +``` + +### `ReadAttribute(: int, [(: int, Clusters..Attributes.)])` + +Read the value of an attribute. For example: + +```python +await devCtrl.ReadAttribute(1234, [(0, Clusters.BasicInformation.Attributes.VendorName)]) +``` + +### `WriteAttribute(: int, [(: int, Clusters..Attributes.(value=))])` + +Write a value to an attribute. For example: + +```python +await devCtrl.WriteAttribute(1234, [(1, Clusters.UnitTesting.Attributes.Int8u(value=1))]) +await devCtrl.WriteAttribute(1234, [(1, Clusters.UnitTesting.Attributes.Boolean(value=True))]) +await devCtrl.WriteAttribute(1234, [(1, Clusters.UnitTesting.Attributes.OctetString(value=b'123123\x00'))]) +await devCtrl.WriteAttribute(1234, [(1, Clusters.UnitTesting.Attributes.CharString(value='233233'))]) +``` + +### `ReadAttribute(: int, [(: int, Clusters..Attributes.)], reportInterval=(: int, : int))` + +Configure Matter attribute reporting settings. For example: + +```python +await devCtrl.ReadAttribute(1234, [(1, Clusters.OccupancySensing.Attributes.Occupancy)], reportInterval=(10, 20)) +``` + +To shutdown an existing attribute subscription use the `Shutdown()` function on +the returned subscription object: + +```python +sub = await devCtrl.ReadAttribute(1234, [(1, Clusters.OccupancySensing.Attributes.Occupancy)], reportInterval=(10, 20)) +sub.Shutdown() +``` + +## Explore Clusters, Attributes and Commands + +In the Python REPL the Clusters and Attributes are classes. The `Clusters` +module contains all clusters. Tab completion can be used to explore available +clusters, attributes and commands. + +For example, to get a list of Clusters, type `Clusters.` and hit tab. Continue +to hit tab to cycle through the available Clusters. Pressing return will select +the Cluster. + +To explore Attributes, use the same technique but with the Attributes sub-class +of the Clusters class, for example, type `Clusters.(cluster name).Attributes.` +and hit tab. + +The same is true for Commands, use the Commands sub-class. type +`Clusters.(cluster name).Commands.` and hit tab. diff --git a/_sources/development_controllers/chip-tool/chip_tool_guide.md b/_sources/development_controllers/chip-tool/chip_tool_guide.md new file mode 100644 index 000000000000..82c71eab6b8b --- /dev/null +++ b/_sources/development_controllers/chip-tool/chip_tool_guide.md @@ -0,0 +1,1869 @@ +# Working with the CHIP Tool + +The CHIP Tool (`chip-tool`) is a Matter controller implementation that allows to +commission a Matter device into the network and to communicate with it using +Matter messages, which may encode Data Model actions, such as cluster commands. + +The tool also provides other utilities specific to Matter, such as parsing of +the setup payload or performing discovery actions. + +
+ +## Installation + +On Linux distributions +[running snapd](https://snapcraft.io/docs/installing-snapd), such as Ubuntu, the +CHIP Tool can be installed using the +[chip-tool snap](https://snapcraft.io/chip-tool). To do this, run: + +``` +sudo snap install chip-tool +``` + +## Building from source + +The source files of the CHIP Tool are available in the `examples/chip-tool` +directory. + +The source can be compiled on Linux (amd64/aarch64) or macOS. If you want to run +it on Raspberry Pi, you must use a 64-bit OS. + +> **Note:** To ensure compatibility, always build the CHIP Tool and the Matter +> device from the same revision of the `connectedhomeip` repository. + +To build the CHIP Tool: + +1. Install all required packages for Matter and prepare the source code and the + build system. Read the [Building Matter](../../guides/BUILDING.md) guide for + instructions. +2. Open a command prompt in the `connectedhomeip` directory. +3. Run the following command: + + ``` + ./scripts/examples/gn_build_example.sh examples/chip-tool BUILD_PATH + ``` + + In this command, `BUILD_PATH` specifies where the target binaries are to be + placed. + +## Running the CHIP Tool + +If you installed the CHIP Tool as a snap, the command to run it would be: + +``` +$ chip-tool +``` + +If you compiled the CHIP Tool from source, it can be executed with the following +command from the `BUILD_PATH` directory: + +``` +$ ./chip-tool +``` + +As a result, the CHIP Tool starts in the default +[single-command mode](#single-command-mode-default) and prints all available +commands. These are called _clusters_ in this context, but not all listed +commands correspond to the _clusters_ in the Data Model (for example, pairing or +discover commands). Each listed command can however become the root of the new +more complex command by appending it with sub-commands. Examples of specific +commands and their use cases are described in the +[Supported commands and options](#supported-commands-and-options) section. + +> **Note:** The CHIP Tool caches the configuration state in the +> `/tmp/chip_tool_config.ini` file. Deleting this and other `.ini` files in the +> `/tmp` directory can sometimes resolve issues related to stale configuration. +> To make the configuration persistent you can change the directory where CHIP +> Tool caches its configuration by using the command line option +> `--storage-directory` + +
+ +## CHIP Tool modes + +The CHIP Tool can run in one of the following modes: + +### Single-command mode (default) + +In this mode, the CHIP Tool will exit with a timeout error if any single command +does not complete within a certain timeout period. + +The timeout error will look similar to the following one: + +``` +[1650992689511] [32397:1415601] CHIP: [TOO] Run command failure: ../../../examples/chip-tool/commands/common/CHIPCommand.cpp:392: CHIP Error 0x00000032: Timeout +``` + +Moreover, when using the single-command mode, the CHIP Tool will establish a new +CASE session with every command sent. + +#### Modifying timeout duration in single-command mode + +This timeout can be modified for any command execution by supplying the optional +`--timeout` parameter, which takes a value in seconds, with the maximum being +65535 seconds. + +**Example of command:** + +``` +$ ./chip-tool otasoftwareupdaterequestor subscribe-event state-transition 5 10 0x1234567890 0 --timeout 65535 +``` + +### Interactive mode + +In this mode, a command will terminate with an error if it does not complete +within the timeout period. However, the CHIP Tool will not be terminated and it +will not terminate processes that previous commands have started. Moreover, when +using the interactive mode, the CHIP Tool will establish a new CASE session only +when there is no session available yet. On the following commands, it will use +the existing session. + +#### Starting the interactive mode + +For commands such as event subscriptions that need to run for an extended period +of time, the CHIP Tool can be started in interactive mode first before running +the command. + +To start the interactive mode, run the following command: + +``` +$ ./chip-tool interactive start +``` + +In this mode, you can subscribe to events or attributes. For detailed steps, see +[Subscribing to events or attributes](#subscribing-to-events-or-attributes). + +
+ +## Using CHIP Tool for Matter device testing + +The following steps depend on the application clusters that you implemented on +the device. + +The steps are using the +[Matter Lighting Application Example](https://github.com/project-chip/connectedhomeip/tree/master/examples/lighting-app) +with the Bluetooth LE commissioning method support. You can use other Matter +examples and still follow this procedure. If you use a different example, the +[Step 7](#step-7-control-application-data-model-clusters) may vary depending on +the clusters implemented in your application. + +### Step 1: Prepare the Matter device + +Build and program the device with the Matter device firmware by following the +[Matter Lighting Application Example](https://github.com/project-chip/connectedhomeip/tree/master/examples/lighting-app) +documentation. + +### Step 2: Enable Bluetooth LE advertising on Matter device + +Some examples are configured to advertise automatically on boot. Other examples +require physical trigger, for example pushing a button. Follow the documentation +of the Matter device example for the chosen platform to learn how Bluetooth LE +advertising is enabled for the given example. + +### Step 3: Set up the IP network + +To follow the next steps, the IP network must be up and running. For instance, +the Thread network can be established using +[OpenThread Border Router](https://openthread.io/codelabs/openthread-border-router#0). + +### Step 4: Determine network pairing credentials + +You must provide the CHIP Tool with network credentials that will be used in the +device commissioning procedure to configure the device with a network interface, +such as Thread or Wi-Fi. + +The Matter specification does not define the preferred way of how the network +credentials are to be obtained by controller. In this guide, we are going to +provide steps for obtaining Thread and Wi-Fi network credentials. + +#### Obtaining Thread network credentials + +Fetch and store the current Active Operational Dataset from the Thread Border +Router. This step may vary depending on the Thread Border Router implementation. + +If you are using +[OpenThread Border Router](https://openthread.io/codelabs/openthread-border-router#0) +(OTBR), retrieve this information using one of the following commands: + +- For OTBR running in Docker: + + ``` + sudo docker exec -it otbr sh -c "sudo ot-ctl dataset active -x" + 0e080000000000010000000300001335060004001fffe002084fe76e9a8b5edaf50708fde46f999f0698e20510d47f5027a414ffeebaefa92285cc84fa030f4f70656e5468726561642d653439630102e49c0410b92f8c7fbb4f9f3e08492ee3915fbd2f0c0402a0fff8 + Done + ``` + +- For OTBR native installation: + + ``` + sudo ot-ctl dataset active -x + 0e080000000000010000000300001335060004001fffe002084fe76e9a8b5edaf50708fde46f999f0698e20510d47f5027a414ffeebaefa92285cc84fa030f4f70656e5468726561642d653439630102e49c0410b92f8c7fbb4f9f3e08492ee3915fbd2f0c0402a0fff8 + Done + ``` + +For Thread, you might also use a different out-of-band method to fetch the +network credentials. + +#### Obtaining Wi-Fi network credentials + +You must get the following Wi-Fi network credentials to commission the Matter +device to the Wi-Fi network: + +- Wi-Fi SSID +- Wi-Fi password + +The steps required to determine the SSID and password may vary depending on the +setup. For instance, you might need to contact your local Wi-Fi network +administrator. + +### Step 5: Determine Matter device's discriminator and setup PIN code + +Matter uses the following values: + +- Discriminator - A 12-bit value used to discern between multiple + commissionable device advertisements. +- Setup PIN code - A 27-bit value used to authenticate the device. + +You can find these values in the logging terminal of the device (for instance +UART) when the device boots up. For example: + +``` +I: 254 [DL]Device Configuration: +I: 257 [DL] Serial Number: TEST_SN +I: 260 [DL] Vendor Id: 65521 (0xFFF1) +I: 263 [DL] Product Id: 32768 (0x8000) +I: 267 [DL] Hardware Version: 1 +I: 270 [DL] Setup Pin Code: 20202021 +I: 273 [DL] Setup Discriminator: 3840 (0xF00) +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 +`20202021`. + +### Step 6: Commission Matter device into an existing IP network + +Before communicating with the Matter device, first it must join an existing IP +network. + +Matter devices can use different commissioning channels: + +- Devices that are not yet connected to the target IP network use Bluetooth LE + as the commissioning channel. +- Devices that have already joined an IP network only need to use the IP + protocol for commissioning to the Matter network. + +#### Commissioning over Bluetooth LE + +In this case, your device can join the existing IP network over Bluetooth LE and +then be commissioned into a Matter network. + +Different scenarios are available for Thread and Wi-Fi networks, as described in +the following subsections. + +After connecting the device over Bluetooth LE, the controller prints the +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. + +##### Commissioning into a Thread network over Bluetooth LE + +To commission the device to the existing Thread network, use the following +command pattern: + +``` +$ ./chip-tool pairing ble-thread hex: +``` + +In this command: + +- __ is the user-defined ID of the node being commissioned. +- __ is the Operational Dataset determined in the + [step 4](#step-4-determine-network-pairing-credentials). +- __ and __ are device-specific keys determined in + the + [step 5](#step-5-determine-matter-devices-discriminator-and-setup-pin-code). + +##### Commissioning into a Wi-Fi network over Bluetooth LE + +To commission the device to the existing Wi-Fi network, use the following +command pattern: + +``` +$ ./chip-tool pairing ble-wifi +``` + +In this command: + +- __ is the user-defined ID of the node being commissioned. +- __ and __ are credentials determined in the step 3. +- __ and __ are device-specific keys determined in + the + [step 5](#step-5-determine-matter-devices-discriminator-and-setup-pin-code). + +If you prefer the hexadecimal format, use the `hex:` prefix. For example: + +``` +$ ./chip-tool pairing ble-wifi hex: hex: +``` + +> **Note:** The __ can be provided as a hexadecimal value with the `0x` +> prefix. + +#### Commissioning into a network over IP + +This option is available when the Matter device is already present in an IP +network, but it has not been commissioned to a Matter network yet. + +To commission the device, you can use either the setup PIN code or the setup PIN +code and the discriminator, both of which you obtained in the +[step 5](#step-5-determine-matter-devices-discriminator-and-setup-pin-code). +Alternatively, you can also use a QR code payload. + +##### Commissioning with setup PIN code + +To discover devices and try to pair with one of them using the provided setup +code, use the following command pattern: + +``` +$ ./chip-tool pairing onnetwork +``` + +The command keeps trying devices until pairing with one of them succeeds or +until it runs out of pairing possibilities. In this command: + +- __ is the user-defined ID of the node being commissioned. +- __ is device specific _setup PIN code_ determined in the + [step 5](#step-5-determine-matter-devices-discriminator-and-setup-pin-code) + and used to discover the device. + +##### Commissioning with long discriminator + +To discover devices with a long discriminator and try to pair with one of them +using the provided setup code, use the following command pattern: + +``` +$ ./chip-tool pairing onnetwork-long +``` + +The command keeps trying devices until pairing with one of them succeeds or +until it runs out of pairing possibilities. In this command: + +- __ is the user-defined ID of the node being commissioned. +- __ and __ are device specific keys determined in + the + [step 5](#step-5-determine-matter-devices-discriminator-and-setup-pin-code). + +##### Commissioning with QR code payload or manual pairing code + +Matter devices log the QR code payload and manual pairing code when they boot. + +To discover devices based on the given QR code payload or manual pairing code +and try to pair with one of them, use the following command pattern: + +``` +$ ./chip-tool pairing code +``` + +The command keeps trying devices until pairing with one of them succeeds or +until it runs out of pairing possibilities. In this command: + +- __ is the user-defined ID of the node being commissioned. +- __ is the QR code payload ID, for example + `MT:Y.K9042C00KA0648G00`, or a manual pairing code like + `749701123365521327694`. + +#### Forgetting the already-commissioned device + +In case commissioning needs to be retested, the following command removes the +device with the given node ID from the list of commissioned Matter devices: + +``` +$ ./chip-tool pairing unpair +``` + +In this command, __ is the user-defined ID of the node which is going +to be forgotten by the CHIP Tool. + +### Step 7: Control application Data Model clusters + +Having completed all previous steps, you have the Matter device successfully +commissioned to the network. You can now test the device by interacting with +Data Model clusters. + +#### Example: Matter Lighting Application Example + +In case of the Matter Lighting Application Example we referenced in step 1, the +application implements the On/Off and Level Control clusters. This means that +you can test it by toggling the bulb (using the `onoff` cluster commands) or by +manipulating its brightness (using the `levelcontrol` cluster commands): + +- Use the following command pattern to toggle the OnOff attribute state (e.g. + visualized by the LED state): + + ``` + $ ./chip-tool onoff toggle + ``` + + In this command: + + - __ is the user-defined ID of the commissioned node. + - __ is the ID of the endpoint with OnOff cluster + implemented. + +- Use the following command pattern to change the value of the CurrentLevel + attribute (e.g. visualized by the LED brightness): + + ``` + $ ./chip-tool levelcontrol move-to-level + ``` + + In this command: + + - __ is the brightness level encoded between `0` and `254`, unless + a custom range is configured in the cluster. + - __ is the transition time. + - __ is the option mask. + - __ is the option override. + - __ is the user-defined ID of the commissioned node. + - __ is the ID of the endpoint with LevelControl cluster + implemented. + +### Step 8: Read basic information from the Matter device + +Every Matter device supports the Basic Information cluster, which maintains the +collection of attributes that a controller can obtain from a device. These +attributes can include the vendor name, the product name, or the software +version. + +Use the CHIP Tool's `read` command on the `basicinformation` cluster to read +those values from the device: + +``` +$ ./chip-tool basicinformation read vendor-name +$ ./chip-tool basicinformation read product-name +$ ./chip-tool basicinformation read software-version +``` + +In these commands: + +- __ is the user-defined ID of the commissioned node. +- __ is the ID of the endpoint with Basic Information cluster + implemented. + +You can also use the following command to list all available commands for the +Basic Information cluster: + +``` +$ ./chip-tool basicinformation +``` + +
+ +## Supported commands and options + +This section contains a general list of various CHIP Tool commands and options, +not limited to commissioning procedure and cluster interaction. + +### Printing all supported clusters + +To print all clusters supported by the CHIP Tool, run the following command: + +``` +$ ./chip-tool +``` + +**Example of output:** + +```bash + +[1647346057.900626][394605:394605] CHIP:TOO: Missing cluster name +Usage: + ./chip-tool cluster_name command_name [param1 param2 ...] + + +-------------------------------------------------------------------------------------+ + | Clusters: | + +-------------------------------------------------------------------------------------+ + | * accesscontrol | + | * accountlogin | + | * administratorcommissioning | + | * alarms | + | * any | + | * appliancecontrol | + | * applianceeventsandalert | + | * applianceidentification | + | * appliancestatistics | + | * applicationbasic | + +``` + +
+ +### Getting the list of commands supported for a specific cluster + +To print the list of commands supported by a specific cluster, use the following +command pattern: + +``` +$ ./chip-tool +``` + +In this command: + +- __ is one of the available clusters (listed with + `chip-tool`). + +**Example of command:** + +``` +$ ./chip-tool onoff +``` + +**Example of output:** + +```bash +[1647417645.182824][404411:404411] CHIP:TOO: Missing command name +Usage: + ./chip-tool onoff command_name [param1 param2 ...] + + +-------------------------------------------------------------------------------------+ + | Commands: | + +-------------------------------------------------------------------------------------+ + | * command-by-id | + | * off | + | * on | + | * toggle | + | * off-with-effect | + | * on-with-recall-global-scene | + | * on-with-timed-off | + | * read-by-id | + | * read | + | * write-by-id | + | * write | + | * subscribe-by-id | + | * subscribe | + | * read-event-by-id | + | * subscribe-event-by-id | + +-------------------------------------------------------------------------------------+ +[1647417645.183836][404411:404411] CHIP:TOO: Run command failure: ../../examples/chip-tool/commands/common/Commands.cpp:84: Error 0x0000002F + +``` + +
+ +### Getting the list of attributes supported for a specific cluster + +To get the list of attributes for a specific cluster, use the following command +pattern: + +``` +$ ./chip-tool read +``` + +In this command: + +- __ is one of the available clusters (listed with + `chip-tool`). + +**Example of command:** + +``` +$ ./chip-tool onoff read +``` + +**Example of output:** + +```bash +[1647417857.913942][404444:404444] CHIP:TOO: Missing attribute name +Usage: + ./chip-tool onoff read attribute-name [param1 param2 ...] + + +-------------------------------------------------------------------------------------+ + | Attributes: | + +-------------------------------------------------------------------------------------+ + | * on-off | + | * global-scene-control | + | * on-time | + | * off-wait-time | + | * start-up-on-off | + | * server-generated-command-list | + | * client-generated-command-list | + | * attribute-list | + | * feature-map | + | * cluster-revision | + +-------------------------------------------------------------------------------------+ +[1647417857.914110][404444:404444] CHIP:TOO: Run command failure: ../../examples/chip-tool/commands/common/Commands.cpp:120: Error 0x0000002F +``` + +
+ +### Getting the list of command options + +To get the list of parameters for a specific command, use the following command +pattern: + +``` +$ ./chip-tool +``` + +In this command: + +- __ is one of the available clusters (listed with + `chip-tool`). +- __ is one of the target command names. + +**Example of command:** + +``` +$ ./chip-tool onoff on +``` + +**Example of output:** + +```bash +[1647417976.556313][404456:404456] CHIP:TOO: InitArgs: Wrong arguments number: 0 instead of 2 +Usage: + ./chip-tool onoff on node-id/group-id endpoint-id-ignored-for-group-commands [--paa-trust-store-path] [--commissioner-name] [--trace_file] [--trace_log] [--ble-adapter] [--timedInteractionTimeoutMs] [--suppressResponse] +[1647417976.556362][404456:404456] CHIP:TOO: Run command failure: ../../examples/chip-tool/commands/common/Commands.cpp:135: Error 0x0000002F + +``` + +#### Selected command options + +This section lists selected options that can be used to configure the input +command. + +##### Choosing the Bluetooth adapter + +To choose the Bluetooth adapter used by the CHIP Tool, use the following command +pattern: + +``` +--ble-adapter +``` + +In this command: + +- __ is the ID of HCI device. + +**Example of usage:** + +``` +$ ./chip-tool pairing ble-thread 1 hex:0e080000000000010000000300001335060004001fffe002084fe76e9a8b5edaf50708fde46f999f0698e20510d47f5027a414ffeebaefa92285cc84fa030f4f70656e5468726561642d653439630102e49c0410b92f8c7fbb4f9f3e08492ee3915fbd2f0c0402a0fff8 20202021 3840 --ble-adapter 0 +``` + +##### Using message tracing + +Message tracing allows capturing CHIP Tool secure messages that can be used for +test automation. The tracing uses several types of flags that control where the +traces should go. + +The following flags are available: + +- Trace file flag: + + ``` + --trace_file + ``` + + Here, __ is the name of the file where the trace data is stored. + It can be appended to a command in the following way: + + ``` + $ ./chip-tool pairing --trace_file + ``` + +- Trace log flag: + + ``` + --trace_log + ``` + + Here, __ is a `[0/1]` flag, which when set to `1` prints the trace + data with automation logs to the console. + +
+ +##### Changing storage directory + +By default, CHIP Tool stores its configuration into the `/tmp` directory. You +can change the storage directory by using the `--storage-directory` flag. + +Usage: + +``` +--storage-directory +``` + +Here, __ is the path to the directory where the configuration is +stored. + +**Example of usage:** + +``` +$ ./chip-tool pairing ble-wifi --storage-directory +$ ./chip-tool temperaturemeasurement read measured-value --storage-directory + +``` + +
+ +### Commissioner name and ID flags + +All CHIP Tool commands can be used together with the following +commissioner-related flags: + +- `--commissioner-name` +- `--commissioner-nodeid` + +These flags let you control which fabric and node ID are used for the CHIP Tool +when interacting with devices. They are especially useful in scenarios where you +are working with more than one fabric, but you can also use them with a single +CHIP Tool node identity. + +#### `--commissioner-name` flag + +This flag lets you control which fabric is used by selecting a specific fabric +commissioner. + +As per the CHIP Tool implementation, the commissioners are required to have the +following names: `alpha` for the first one, `beta` for the second one, `gamma` +for the third one, `4` for the fourth one, `5` for the fifth one, and so on. + +If you don't use this flag, the CHIP Tool assumes that the command is meant for +the `alpha` commissioner and hence for the fabric associated with this +commissioner. + +**Example of commands:** + +``` +$ ./chip-tool any subscribe-by-id '0x0028,0x0028,0x0101,0x0028,0x0028,0x0028' '5,6,0,1,2,4' 100 1000 1 '0,0,1,0,0,0' --keepSubscriptions true +$ ./chip-tool any subscribe-by-id '0x0028,0x0028,0x0101,0x0028,0x0028,0x0028' '5,6,0,1,2,4' 100 1000 2 '0,0,1,0,0,0' --keepSubscriptions true --commissioner-name beta +$ ./chip-tool any subscribe-by-id '0x0028,0x0028,0x0101,0x0028,0x0028,0x0028' '5,6,0,1,2,4' 100 1000 3 '0,0,1,0,0,0' --keepSubscriptions true --commissioner-name gamma +``` + +#### `--commissioner-nodeid` flag + +This flag lets you select the node ID to use on the fabric specified with the +`--commissioner-name` flag. + +If you don't use this flag, the CHIP Tool assumes that the command is sent with +the ID value that the CHIP Tool has in storage. If there's none, the CHIP Tool +sends the command with the default fallback node ID `112233`. + +> **Note:** If the device has been already commissioned with a specific +> `--commissioner-nodeid`, you must always provide the `--commissioner-nodeid` +> flag with the CHIP Tool commands or update the Access Control List (ACL) on +> the device. Otherwise, the default fallback node ID `112233` is used and the +> communication will fail. + +**Example of commands:** + +``` +$ ./chip-tool pairing code-thread 1 hex:000030000150208562618342348532605109bd31cda6908667addca8789211addac0102c4a9 34970112332 --commissioner-name alpha --commissioner-nodeid 999999 +``` + +``` +$ ./chip-tool basicinformation read vendor-id --commissioner-name alpha --commissioner-nodeid 999999 +``` + +
+ +### Running a test suite against a paired peer device + +The CHIP Tool allows to run a set of tests, already compiled in the tool, +against a paired Matter device. + +- To get the list of available tests, run the following command: + + ``` + $ ./chip-tool tests + ``` + +- To execute a particular test against the paired device, use the following + command pattern: + + ``` + $ ./chip-tool tests + ``` + + In this command: + + - __ is the name of the particular test. + +See the [Examples](#running-testclusters-test) section for an example of how to +run a test from the test suite. + +
+ +### Parsing the setup payload + +The CHIP Tool offers a utility for parsing the Matter onboarding setup payload +and printing it in a readable form. For example, the payload can be printed on +the device console during boot. + +To parse the setup code, use the `payload` command with the +`parse-setup-payload` sub-command, as in the following command pattern: + +``` +$ ./chip-tool payload parse-setup-payload +``` + +Here, __ is the ID of the payload to be parsed. + +**Examples of commands:** + +- Setup QR code payload: + + ``` + $ ./chip-tool payload parse-setup-payload MT:6FCJ142C00KA0648G00 + ``` + +- Manual pairing code: + + ``` + $ ./chip-tool payload parse-setup-payload 34970112332 + ``` + +
+ +### Parsing additional data payload + +To parse additional data payload, use the following command pattern: + +``` +$ ./chip-tool payload parse-additional-data-payload +``` + +In this command: + +- __ is the ID of the payload with additional data to be parsed. + +
+ +### Discover actions + +The `discover` command can be used to resolve node ID and discover available +Matter devices. + +Use the following command to print the available sub-commands of the `discover` +command: + +``` +$ ./chip-tool discover +``` + +#### Resolving node name + +To resolve the DNS-SD name corresponding with the given Node ID and update the +address of the node in the device controller, use the following command pattern: + +``` +$ ./chip-tool discover resolve +``` + +In this command: + +- __ is the ID of node to be resolved. +- __ is the ID of the Matter fabric to which the node belongs. + +#### Discovering available Matter devices + +To discover all Matter commissionables available in the operation area, run the +following command: + +``` +$ ./chip-tool discover commissionables +``` + +#### Discovering available Matter commissioners + +To discover all Matter commissioners available in the operation area, run the +following command: + +``` +$ ./chip-tool discover commissioners +``` + +
+ +### Pairing + +The `pairing` command supports different methods for Matter device commissioning +procedure. The recommended methods are the following: + +- `code-thread` - For Thread commissioning. +- `code-wifi` - For Wi-Fi commissioning. +- `code` - For commissioning the device when it is already present in an IP + network. + +Alternatively, you can also use the following methods described in the +[Using CHIP Tool for Matter device testing](#using-chip-tool-for-matter-device-testing) +section: + +- `ble-thread` - For Thread commissioning; described under + [Commissioning into a Thread network over Bluetooth LE](#commissioning-into-a-thread-network-over-bluetooth-le). +- `ble-wifi` - For Wi-Fi commissioning; described under + [Commissioning into a Wi-Fi network over Bluetooth LE](#commissioning-into-a-wi-fi-network-over-bluetooth-le) +- `onnetwork` - For commissioning the device when it is already present in an + IP network; described under + [Commissioning with setup PIN code](#commissioning-with-setup-pin-code) + +To list all `pairing` sub-commands and commissioning methods, run the following +command: + +``` +$ ./chip-tool pairing +``` + +**Example of commands:** + +The following command commissions the Thread device with the node ID `1` to the +Matter fabric. The `hex:...` parameter is the operational dataset that contains +information about the Thread network to which the device is going to be +commissioned. The onboarding dataset payload `34970112332` (short manual pairing +code) is used to discover and commission the device. + +``` +$ ./chip-tool pairing code-thread 1 hex:000030000150208562618342348532605109bd31cda6908667addca8789211addac0102c4a9 34970112332 +``` + +The following command commissions the Wi-Fi device with the node ID `1` to the +Matter fabric The SSID `wifi_test` and the password `admin123` is the required +information about the Wi-Fi network to which the device is going to be +commissioned. The onboarding dataset payload `34970112332` (short manual pairing +code) is used to discover and commission the device. + +``` +$ ./chip-tool pairing code-wifi 1 wifi_test admin123 34970112332 +``` + +The following command commissions the device with the node ID `1` to the Matter +fabric. The onboarding dataset payload `MT:8IXS142C00KA0648G00` (QR code +payload) is used to discover and commission the device. + +``` +$ ./chip-tool pairing code 1 MT:8IXS142C00KA0648G00 +``` + +#### Attestation-related flags + +The `pairing` commissioning command can be run with several flags that allow you +to modify attestation-related settings: + +- `--paa-trust-store-path` - Use to provide the path to the directory that + contains the information about Product Attestation Authority (PAA) + certificates. The path can be absolute or relative to the current working + directory. With this flag, the CHIP Tool looks for the PAA certificate that + matches the PAI and the DAC certificates programmed on the device. Without + this flag, the CHIP Tool uses the built-in test PAA certificate. + +- `--cd-trust-store-path` - Use to provide the path to the directory + containing the key that is used to validate the device's Certification + Declaration. The path can be absolute or relative to the current working + directory. With this flag, the CHIP tool looks for additional public keys, + in addition to the well-known built-in public keys (built-in public keys + `src/credentials/attestation_verifier/DefaultDeviceAttestationVerifier.cpp`), + to be used to validate Certification Declaration signatures. + +* `--only-allow-trusted-cd-keys` - Use to only allow the keys from + `--cd-trust-store-path` and not the built-in test key. If the flag is not + provided or it is provided with the value `false`, untrusted CD verifying + keys are allowed. If it is provided with the value `true` + (`--only-allow-trusted-cd-keys true`), test keys are disallowed and CD + signed with the test key will not be accepted. + +* `--bypass-attestation-verifier` - Use to bypass the attestation verifier. If + the flag is not provided or it is provided with the value `false`, the + attestation verifier is not bypassed. If it is provided with the value + `true` (`--bypass-attestation-verifier true`), the commissioning will + continue in case of the attestation verification failure. The failure can be + caused by errors in Certification Declaration, PAA or PAI certificates, or + in the Device Attestation Certificate. This option can be helpful if you + want to quickly commission a device with PAI and DAC certificates based on + an unknown PAA and/or with a Certification Declaration signed by an unknown + key. + +
+ +### Interacting with Data Model clusters + +As mentioned in the +[Using CHIP Tool for Matter device testing](#using-chip-tool-for-matter-device-testing) +section, executing the `chip-tool` command with a particular cluster name lists +all operations supported for this cluster, as in the following command pattern: + +``` +$ ./chip-tool +``` + +**Example of command:** + +``` +$ ./chip-tool binding +``` + +**Example of output:** + +```bash +[1647502596.396184][411686:411686] CHIP:TOO: Missing command name +Usage: + ./chip-tool binding command_name [param1 param2 ...] + + +-------------------------------------------------------------------------------------+ + | Commands: | + +-------------------------------------------------------------------------------------+ + | * command-by-id | + | * read-by-id | + | * read | + | * write-by-id | + | * write | + | * subscribe-by-id | + | * subscribe | + | * read-event-by-id | + | * subscribe-event-by-id | + +-------------------------------------------------------------------------------------+ +[1647502596.396299][411686:411686] CHIP:TOO: Run command failure: ../../examples/chip-tool/commands/common/Commands.cpp:84: Error 0x0000002F +``` + +According to this list, the `binding` cluster supports operations such as read +or write. Attributes from that cluster can also be subscribed by the controller, +which means that the CHIP Tool will receive notifications, for instance when the +attribute value is changed or a specific event happens. + +#### Examples + +This section lists examples of the CHIP Tool commands dedicated to specific use +cases. + +##### Writing ACL to the `accesscontrol` cluster + +The Access Control List concept allows to govern all Data Model interactions +(such as read attribute, write attribute, invoke command). For more information +about ACL, see +[Access Control Guide](https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/access-control-guide.md). + +To write ACL to the `accesscontrol` cluster, use the following command pattern: + +``` +$ ./chip-tool accesscontrol write acl +``` + +In this command: + +- __ is the ACL data formatted as a JSON array. +- __ is the ID of the node that is going to receive ACL. +- __ is the ID of the endpoint on which the `accesscontrol` + cluster is implemented. + +##### Adding a binding table to the `binding` cluster + +Binding describes a relationship between the device that contains the binding +cluster and the end device. The proper ACL must be added to allow the end device +to receive commands from the bonded device. After the binding process, the +bonded device contains information about connected device, such as IPv6 address +and the route to the endpoint in the Matter network. + +To add a binding table to the `binding` cluster, use the following command +pattern: + +``` +$ ./chip-tool binding write binding +``` + +In this command: + +- __ is the binding data formatted as a JSON array. +- __ is the ID of the node that is going to receive the binding. +- __ is the ID of the endpoint on which the `binding` cluster is + implemented. + +##### Running `TestClusters` test + +Complete the following steps to +[run one test from the test suite](#running-a-test-suite-against-a-paired-peer-device): + +1. Clean the initialization of state using the following command: + ``` + rm -fr /tmp/chip_* + ``` +1. In a shell window, start the DUT device: + ``` + ./out/debug/standalone/chip-all-clusters-app + ``` +1. In a second shell window, pair the DUT with the CHIP Tool: + ``` + ./out/debug/standalone/chip-tool pairing onnetwork 333221 20202021 + ``` +1. Run the test with the following command: + ``` + ./out/debug/standalone/chip-tool tests TestCluster --nodeId 333221 + ``` + +Read the [CHIP Test Suits](https://github.com/project-chip/connectedhomeip/blob/master/src/app/tests/suites/README.md) page for more +information about how the test suite is structured. + +
+ +### Multi-admin scenario + +Multi-admin feature allows you to join Matter device to several Matter fabrics +and have several different Matter administrators administer it. + +Complete the steps mentioned in the following sections. + +#### Step 1: Commission to fabric + +Commission the Matter device to first fabric following the +[Using CHIP Tool for Matter device testing](#using-chip-tool-for-matter-device-testing) +section. + +#### Step 2: Open the commissioning window + +Make sure the administrator from the first fabric opens the commissioning window +for a new administrator from another fabric. + +Open the commissioning window on the paired Matter device by using the following +command pattern: + +``` +$ ./chip-tool pairing open-commissioning-window