diff --git a/docs/QUICK_START.md b/docs/QUICK_START.md deleted file mode 100644 index 10833e0c0c1ed7..00000000000000 --- a/docs/QUICK_START.md +++ /dev/null @@ -1,52 +0,0 @@ -# Quick Start - -## Demo Overview - -The Matter reference implementation contains support for a number of examples -and platforms. - -## Wi-Fi Nodes - -|
Controller / Admin
|
Node
| Description | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [**chip-tool**](https://github.com/project-chip/connectedhomeip/blob/master/examples/chip-tool/README.md) (Linux / Mac)
Includes docs for all the cluster commands supported
| **all-clusters-app**
  • [M5Stack](https://github.com/project-chip/connectedhomeip/blob/master/examples/all-clusters-app/esp32/README.md) (ESP)
  • [Linux](https://github.com/project-chip/connectedhomeip/tree/master/examples/all-clusters-app/linux) simulation | Use the command line tool on a laptop to pair with and control an embedded Wi-Fi platform. This demo supports the “all-clusters-app”, so it provides the basic onoff light test and more. | -| [**chip-repl**](https://github.com/project-chip/connectedhomeip/blob/master/src/controller/python/README.md) | **all-clusters-app**
  • [M5Stack](https://github.com/project-chip/connectedhomeip/blob/master/examples/all-clusters-app/esp32/README.md) (ESP)
  • [Linux](https://github.com/project-chip/connectedhomeip/tree/master/examples/all-clusters-app/linux) simulation | Same as above, but uses the Python CHIP REPL as Controller Node. | - -## Thread Nodes - -Use one of the controllers listed above and then a Border Router and Node -combination listed below. - -|
    Border Router
    |
    Node
    | Description | -| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [**ot-br**](https://openthread.io/guides/border-router/build)
    Thread Border Router
  • RasPi
  • BeagleBone | **lighting-app**
  • [Nordic nRF5x](https://github.com/project-chip/connectedhomeip/tree/master/examples/lighting-app/nrfconnect/README.md)
  • [NXP K32W](https://github.com/project-chip/connectedhomeip/tree/master/examples/lighting-app/nxp/k32w/k32w0/README.md)
  • [Qorvo QPG6100](https://github.com/project-chip/connectedhomeip/tree/master/examples/lighting-app/qpg)
  • [Silicon Labs EFR32](https://github.com/project-chip/connectedhomeip/tree/master/examples/lighting-app/silabs/README.md) | The Lighting example is supported by many of the available Thread platforms. See the chip-tool controller instructions for how to actuate the light on/off cluster. | -| [**ot-br**](https://openthread.io/guides/border-router/build)
    Thread Border Router
  • RasPi
  • BeagleBone | **lock-app**
  • [Nordic nRF5x](https://github.com/project-chip/connectedhomeip/tree/master/examples/lock-app/nrfconnect/README.md)
  • [NXP K32W](https://github.com/project-chip/connectedhomeip/tree/master/examples/lock-app/nxp/k32w/k32w0/README.md)
  • [Qorvo QPG6100](https://github.com/project-chip/connectedhomeip/tree/master/examples/lock-app/qpg)
  • [Silicon Labs EFR32](https://github.com/project-chip/connectedhomeip/tree/master/examples/lock-app/efr32/README.md)
  • [TI CC13x2x7](https://github.com/project-chip/connectedhomeip/tree/master/examples/lock-app/cc13x2x7_26x2x7/README.md) | The Lock example is supported by many of the available Thread and Wi-Fi platforms. | - -## Controllers - -### chip-tool - -This section summarizes how to run some common scenarios with the -[**chip-tool**](https://github.com/project-chip/connectedhomeip/blob/master/examples/chip-tool/README.md) -controller. - -#### IP Pairing - -`chip-tool pairing onnetwork ${NODE_ID_TO_ASSIGN} 20202021` will use PASE over -IP to commission a device and assign `${NODE_ID_TO_ASSIGN}` (which must be a -decimal number or a 0x-prefixed hex number) as its node id. - -NOTE: On Linux, if the device is actually running after unit tests ran you have -to use `chip-tool pairing onnetwork desired-node-id 34567890`, because the unit -tests change the device configuration. - -NOTE: to run both the Node and Controller as separate processes on the same -Linux or Mac machine, build the all-clusters-app with Bluetooth LE disabled as -follows: - -`scripts/examples/gn_build_example.sh examples/all-clusters-app/linux out/debug/standalone/ chip_config_network_layer_ble=false` - -#### Automated CASE tests - -`chip-tool tests Test_TC_OO_1_1` will run a suite of tests that use CASE To -communicate with a paired `all-clusters-app` peer node. diff --git a/docs/README.md b/docs/README.md index e4ec9c8f3a5523..e5aad317e6d556 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,6 +2,10 @@ ## Building and Developing +- A quick start guide to building a demo application and controller is + available in the [Getting started](./getting_started/) guide +- A guide to new cluster and device type development is available in the + [New Cluster and Device Type Developement Guide](./cluster_and_device_type_dev/) - Documentation about building from the command line can be found in [the build guide](guides/BUILDING.md) - Documentation about running [cirque](https://github.com/openweave/cirque) diff --git a/docs/api/device_runner.md b/docs/api/device_runner.md deleted file mode 100644 index db9c5993eff6d8..00000000000000 --- a/docs/api/device_runner.md +++ /dev/null @@ -1,103 +0,0 @@ -# CHIP on-device testing - -_Requirements and high-level design_ - -## Background - -The ability to run tests on actual and emulated hardware is paramount in -embedded projects. CHIP is no exception. We want on-device testing to be a first -class goal of CHIP architecture. On-device testing requirements apply both to -Continuous Integration testing for main CHIP software stack development and to -eventual CHIP product certification. This document explores the requirements and -evaluates potential solutions. - -## Overview of requirements - -A good device test infrastructure is built on four pillars. - -### Pillar 1: Using a test framework - -A test framework provides a testing structure that developers can follow and -potentially reduces some of the burden of test setup and teardown (less -boilerplate). Support for state-oriented and asynchronous structuring of tests -would be beneficial. Many test frameworks leverage scripting languages such as -Python to simplify the quick development of tests and to leverage rich sets of -libraries for device/systems access and results generation. - -### Pillar 2: Dispatching tests - -Tests can run on lab machines or on the developer's local workstation. Tests can -be triggered manually by the developer or as a result of completion of a -changeset built on a continuous integration (CI) server. CHIP involves multiple -stakeholders, many of which will want to contribute to the testing efforts with -lab capacity. The infrastructure therefore must be prepared for -cross-organization test dispatch. - -To facilitate uniform dispatch of tests we will probably need a simple -request/response protocol. Potentially HTTPS based and RESTful. Due to the long -running nature of device tests the response for a test scheduling request could -be a test ID, not the test result. That ID could be used to query the test -status, subscribe for notifications on status changes and to pull the test -results. Core aspects of such a scheme include the conventions for request -artifacts contents and minimum expected results contents once the run is -complete. - -### Pillar 3: Interacting with devices - -The test host environment has to reset devices, flash images on them, issue -commands, monitor status and collect test results. It may also need to integrate -both virtual (simulated) and real devices together. This can at first be done in -an ad-hoc way per platform but eventually we can go into device access -abstraction, i.e. define a common device testing interface which CHIP-compliant -devices can expose. The test host has to be prepared for driving multiple -devices at the same time for a single test, e.g. for tests that check -communication between multiple devices. - -### Pillar 4: Collecting results - -Ideally, test results are output in standard formats and similar or analogous -results between different devices and tests are output the same way. This -ensures reusability of code that processes similar data while allowing -aggregation of results across different dimensions. Failed tests must propagate -errors from device platform layers all the way to the CHIP stack and present -errors and potential stack traces in a standard result format. As the purpose of -on-device tests is to capture bugs, it is important that the test outputs -highlight the failure reason(s) and developers don't have to browse through -thousands of lines of logs to find the one line that sheds light on why a test -failed. - -## Priorities - -In the spirit of CHIP's charter, it would be great to see something taking-off -as soon as possible, to support continuous testing of the evolving CHIP stack. -We could then improve on that first iteration, even if we have to throw away -some temporary concepts and code. - -Test dispatch (Pillar 2) arises as the highest priority, because all other -pillars can have ad-hoc solutions. The first need is an interface between a -CircleCI job and a test execution host at a participating organization. This -would enable dispatching tests to a variety of existing in-house infrastructure, -while retaining common request/response protocols to shield the CI system from -implementation details of each lab. - -The next most important goal is to provide a test framework (Pillar 1). With a -standard framework developers can start writing tests, even if those tests will -be device specific and of ad-hoc input and output format. The general structure -of tests will however be present and later the tests can be adapted to standard -interactions (Pillar 3) and result formats (Pillar 4). - -Specifying result formats (Pillar 4) for the most common outputs -(success/failure, failure reason, stack trace, memory and CPU usage time series, -pcaps of network traffic, etc.) will be an ongoing effort. The simplest output -formats can be specified together with the test framework. - -Lastly, we want to look into a common device interaction interface that would -enable reusing tests between different devices. - -## Baseline hardware platforms for CHIP - -The TSG is targeting the following platforms/boards for early bringup: - -- Nordic nRF52 board -- SiLabs `XXXX` board -- Espressif ESP32 `XXXX` board diff --git a/docs/api/device_runner_dispatch.md b/docs/api/device_runner_dispatch.md deleted file mode 100644 index fff2634b41a3fc..00000000000000 --- a/docs/api/device_runner_dispatch.md +++ /dev/null @@ -1,183 +0,0 @@ -# CHIP on-device test dispatch - -This document expands on and provides design for on-device test dispatch. The -CHIP on-device testing document states that dispatching should involve a HTTPS -based RESTful protocol that could be integrated with CircleCI. - -## Definitions - -**Test run**: Tests instantiation on a test host, consisting of host-side test -binaries and test scripts as well as one or more device-side binaries. - -**Test host**: A computing execution environment provided for the purposes of -running tests by a party participating in the scheme. - -## Scope - -The scope of this proposal is to support running tests against a known set of -canonical devices and platforms for the purposes of developing core common code -in the CHIP project GitHub repository. - -This proposal does not preclude a stakeholder running their own tests against -their own hardware or lab in any way they see fit. The goal is merely to provide -a common way for volunteer organizations to register test infrastructure and -dispatch capabilities to be used by the wider CHIP developer community. - -Authentication is not considered strictly part of the test dispatch protocol. -However it is mandated that some form of authentication takes place before any -of the test dispatch operations are issued. Throughout this document it is -assumed that proper authentication and authorization is ensured by the server -hosting the test dispatch service. - -## Objectives - -- **Provide a centralized API** for the dispatching of tests against - potentially distributed lab infrastructure, which CI systems (i.e. CircleCI) - or individual developers may not be directly configured to access. -- **Decouple test execution from the CI environment**, especially for tests - requiring complex setups, such as radio traffic capture. -- **Enable** common adoption of **aligned methodologies** for both - certification-style tests and development-support tests (pre/post-submit - testing in pull requests). - -### Certification or pre-certification tests - -Certification tests are required to have canonical test suite names. - -Here the host side test binaries and scripts are fixed and the device-side -binary can vary by device type. The objective of certification testing is to run -a known fixed set of tests against new and existing devices. Dispatching of -certification tests involves specifying the canonical test suite name and -providing the requisite arguments, such as device-side binary and device type. - -### Development support tests - -Development support test suites are required to have canonical names, but they -may, during execution, check-out the actual test script from a given PR, or from -the artifacts uploaded for the test job. - -The test is executed against a pull request and may target many device types. -Therefore, both host-side and device-side artifacts may vary and have to be -uploaded in the respective argument to test dispatch operation. Dispatching of -development support test suites therefore involves specifying a canonical test -suite name, the PR URL, pre-built artifacts (host side and device-side) and -optional test-specific arguments. - -### Common constraints for dispatch - -In order to support running tests, some common arguments are required to -determine during dispatch whether a given combination of targets can be -supported. - -These constraints include: - -- A canonical device type list to determine whether a target runner has all - the targets needed. (Note that new hardware developers may provide a - non-canonical device type for running their own certification on their own - lab. Canonical device types exist for development support tests.) -- An optional node ID (unique UUID) to force execution on a given registered - infrastructure for test purposes. - -Example of canonical test suite names: - -- RendezVousTest: loads binaries on HW, validates that assumptions about - RendezVous advertising payload are still valid. -- BasicCHIPRegression: loads binaries on HW, validates against regressions on - multiple axes of the test. Potentially runs updated tests scripts from the - PR itself. - -## Aggregator Dispatch Interface API - -We conceptualize an aggregator service where all the tests are sent to be -further dispatched to or pulled by participating infrastructure/lab providers. - -For the prototype phase the aggregator may be the same service that runs tests -as well, i.e. further dispatch/pull/registration may not happen in the -prototype. - -This is the API which CircleCI and individual test developers can use. There may -be other APIs (e.g. administrator API) to the aggregator that provide richer -functionality. For now we don't discuss those. The API for communication between -the aggregator and test labs is to be specified at a later time. - -The goal of decoupling dispatch from execution is to avoid coupling running the -tests to a given lab’s or organization’s infrastructure. The dispatch interface -API provides a separation of concerns of “what to run”/“what happened” versus -“how to run”/“where to run”. - -### Resources and operations - -/available_test_suites - Collection resource, all the canonical test suite -names. - -- GET gets the list of known canonical test suite names - -/dispatch - Collection resource, all the currently running test executions. - -- POST dispatches a new test, returning its URI with the test run identifier - 'job_id'. - Arguments - Canonical Test Suite name e.g. - "CHIP_basic_test_suite" - ZIP file upload of artifacts (device-side and, if - needed, host-side) - Some common required inputs (see section below) - - Test-suite-specific configuration/contents may also be provided for the test - suite executor to use. - Maximum time the client is willing to wait for - results (seconds) - In case of execution timed out, the test job would be - considered FAILED, due to time-out. - Maximum time the client is willing to - wait for test to start (seconds) - In case of time-out to dispatch, the test - job would be considered ABORTED in the results as opposed to FAILED - - Authentication requirements may cause a given requestor to be throttled by - internal logic. - -/status/ - Member resource, an individual test. - -- GET returns the status of the test: scheduled, running, finished, aborted. -- DELETE cancels the test. - -/status//results - Collection resource, all the files resulting from the -test run. - -- GET returns the list of (file_name, file_id) pairs. - - Only mandatory file: - - test_suite_results.json - - Normalized test results, see section below. - -/status//results/ - Member resource, and individual result -file. - -- GET returns the contents of the file. - -### /dispatch arguments - -**test_suite_name**: _Required_. Name of the test suite. - -**host_artifacts**: _Only required for development support tests_. A file (most -likely a ZIP file) corresponding to all the scripts and binaries to be run by -the test host. The test host must be able to unzip, recognize and execute -contents. - -**device_artifacts**: _Required_. A file (most likely a ZIP file) corresponding -to all the binaries to be flashed on the device. The test host must be able to -unzip, recognize and flash contents. - -**timeout_for_results_seconds**: _Required_. The maximum amount of time in -seconds the client is willing to wait for results. After this much time the test -can be killed by the test host. - -**timeout_for_start_seconds**: _Required_. The maximum amount of time in seconds -the client is willing to wait for the test to start. If after dispatch the test -does not start after this much time the test can be descheduled by the -aggregator. - -### test_suite_results.json contents - -TBD. - -### Aggregator-to-lab dispatch API - -TBD. - -### Lab Registration Interface API - -Once agreement on the dispatch API is cemented, the API to register a given -executor with certain tests and devices capabilities can be defined. - -TBD. diff --git a/docs/api/index.md b/docs/api/index.md deleted file mode 100644 index c139642dc4ed68..00000000000000 --- a/docs/api/index.md +++ /dev/null @@ -1,7 +0,0 @@ -# API - -```{toctree} -:glob: - -* -``` diff --git a/docs/testing/img/plant_uml_source.txt b/docs/cluster_and_device_type_dev/img/plant_uml_source.txt similarity index 100% rename from docs/testing/img/plant_uml_source.txt rename to docs/cluster_and_device_type_dev/img/plant_uml_source.txt diff --git a/docs/testing/img/unit_testable_clusters.png b/docs/cluster_and_device_type_dev/img/unit_testable_clusters.png similarity index 100% rename from docs/testing/img/unit_testable_clusters.png rename to docs/cluster_and_device_type_dev/img/unit_testable_clusters.png diff --git a/docs/testing/img/unit_testable_clusters_all_classes.png b/docs/cluster_and_device_type_dev/img/unit_testable_clusters_all_classes.png similarity index 100% rename from docs/testing/img/unit_testable_clusters_all_classes.png rename to docs/cluster_and_device_type_dev/img/unit_testable_clusters_all_classes.png diff --git a/docs/testing/img/unit_testable_clusters_context.png b/docs/cluster_and_device_type_dev/img/unit_testable_clusters_context.png similarity index 100% rename from docs/testing/img/unit_testable_clusters_context.png rename to docs/cluster_and_device_type_dev/img/unit_testable_clusters_context.png diff --git a/docs/testing/img/unit_testable_clusters_driver.png b/docs/cluster_and_device_type_dev/img/unit_testable_clusters_driver.png similarity index 100% rename from docs/testing/img/unit_testable_clusters_driver.png rename to docs/cluster_and_device_type_dev/img/unit_testable_clusters_driver.png diff --git a/docs/testing/img/unit_testable_clusters_logic.png b/docs/cluster_and_device_type_dev/img/unit_testable_clusters_logic.png similarity index 100% rename from docs/testing/img/unit_testable_clusters_logic.png rename to docs/cluster_and_device_type_dev/img/unit_testable_clusters_logic.png diff --git a/docs/testing/img/unit_testable_clusters_server.png b/docs/cluster_and_device_type_dev/img/unit_testable_clusters_server.png similarity index 100% rename from docs/testing/img/unit_testable_clusters_server.png rename to docs/cluster_and_device_type_dev/img/unit_testable_clusters_server.png diff --git a/docs/cluster_and_device_type_dev/index.md b/docs/cluster_and_device_type_dev/index.md index 9159cdb3e511d5..cf43d02651378c 100644 --- a/docs/cluster_and_device_type_dev/index.md +++ b/docs/cluster_and_device_type_dev/index.md @@ -14,3 +14,4 @@ types in the SDK. - [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/docs/testing/unit_testing_clusters.md b/docs/cluster_and_device_type_dev/unit_testing_clusters.md similarity index 100% rename from docs/testing/unit_testing_clusters.md rename to docs/cluster_and_device_type_dev/unit_testing_clusters.md diff --git a/docs/getting_started/index.md b/docs/getting_started/index.md index cca67e19b0c8fc..ea881141ff43ec 100644 --- a/docs/getting_started/index.md +++ b/docs/getting_started/index.md @@ -14,4 +14,3 @@ The following docs are a brief introduction to SDK development. - [Running your first example](./first_example.md) - [SDK Basics](./SDKBasics.md) - [ZAP](./zap.md) -- [Discover from a host computer](./discovery_from_a_host_computer.md) diff --git a/docs/guides/index.md b/docs/guides/index.md index 8f747ab27e684f..14d9caf7e21839 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -60,7 +60,3 @@ ti/ti_matter_overview - [Open Thread - Hardware suggestions](./openthread_rcp_nrf_dongle.md) - [Open Thread - Setting up a Raspberry Pi as a Border Router](./openthread_border_router_pi.md) - -## Troubleshooting Guides - -- [Avahi - Troubleshooting](./troubleshooting_avahi.md) diff --git a/docs/index.md b/docs/index.md index 1f8e806dc4cce9..f4b40622714eae 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,18 +5,17 @@ :caption: Contents :hidden: -QUICK_START PROJECT_FLOW VSCODE_DEVELOPMENT -api/index ci-cd/index -discussion/index getting_started/index cluster_and_device_type_dev/index guides/index style/index examples/index +product_considerations/index testing/index +tips_and_troubleshooting/index tools/index BUG_REPORT code_generation diff --git a/docs/discussion/index.md b/docs/product_considerations/index.md similarity index 100% rename from docs/discussion/index.md rename to docs/product_considerations/index.md diff --git a/docs/discussion/lwip_ipv6.md b/docs/product_considerations/lwip_ipv6.md similarity index 100% rename from docs/discussion/lwip_ipv6.md rename to docs/product_considerations/lwip_ipv6.md diff --git a/docs/testing/index.md b/docs/testing/index.md index d8ebe92da46f40..b3124f8349dc5c 100644 --- a/docs/testing/index.md +++ b/docs/testing/index.md @@ -37,7 +37,6 @@ from the global ember and message delivery layers. ![](./img/unit_tests.png) - [Unit tests](./unit_testing.md) -- [Designing clusters for unit testing and portability](./unit_testing_clusters.md) ## PICS and PIXIT diff --git a/docs/getting_started/discovery_from_a_host_computer.md b/docs/tips_and_troubleshooting/discovery_from_a_host_computer.md similarity index 100% rename from docs/getting_started/discovery_from_a_host_computer.md rename to docs/tips_and_troubleshooting/discovery_from_a_host_computer.md diff --git a/docs/tips_and_troubleshooting/index.md b/docs/tips_and_troubleshooting/index.md new file mode 100644 index 00000000000000..f2f4a7a417cb7d --- /dev/null +++ b/docs/tips_and_troubleshooting/index.md @@ -0,0 +1,8 @@ +# Tips and Troubleshooting + +```{toctree} +:glob: +:maxdepth: 1 + +* +``` diff --git a/docs/guides/troubleshooting_avahi.md b/docs/tips_and_troubleshooting/troubleshooting_avahi.md similarity index 100% rename from docs/guides/troubleshooting_avahi.md rename to docs/tips_and_troubleshooting/troubleshooting_avahi.md