From 2e983eb0d6a93cfd5dafc2e0b57c2702b778608c Mon Sep 17 00:00:00 2001 From: Grzegorz Ferenc Date: Wed, 20 Apr 2022 15:47:42 +0200 Subject: [PATCH 01/14] doc: add doc portal basics Initial commit for the doc portal framework. Signed-off-by: Grzegorz Ferenc --- .gitignore | 7 +- docs/ChipDoxygenLayout.xml | 225 --------- docs/Makefile | 21 + docs/_doxygen/logo.png | Bin 0 -> 6871 bytes docs/_extensions/doxyrunner.py | 388 +++++++++++++++ docs/_extensions/external_content.py | 176 +++++++ docs/_static/images/favicon.ico | Bin 0 -> 4281 bytes docs/_static/images/logo.png | Bin 0 -> 36520 bytes docs/api/index.md | 7 + docs/breathe.md | 6 + docs/conf.py | 67 +++ docs/discussion/index.md | 7 + .../Rendezvous/RendezvousSessionGeneral.dot | 37 -- .../dots/Rendezvous/RendezvousSessionInit.dot | 83 ---- docs/examples/index.md | 7 + docs/guides/index.md | 7 + docs/images/logo.svg | 37 -- docs/index.md | 16 + docs/make.bat | 36 ++ docs/{Doxyfile => matter.doxyfile.in} | 463 +++++++++++------- docs/namespaces.dox | 37 -- docs/requirements.txt | 4 + docs/style/README.md | 8 - docs/style/index.md | 7 + docs/{STYLE_GUIDE.md => style/style_guide.md} | 30 +- 25 files changed, 1057 insertions(+), 619 deletions(-) delete mode 100644 docs/ChipDoxygenLayout.xml create mode 100644 docs/Makefile create mode 100644 docs/_doxygen/logo.png create mode 100644 docs/_extensions/doxyrunner.py create mode 100644 docs/_extensions/external_content.py create mode 100644 docs/_static/images/favicon.ico create mode 100644 docs/_static/images/logo.png create mode 100644 docs/api/index.md create mode 100644 docs/breathe.md create mode 100644 docs/conf.py create mode 100644 docs/discussion/index.md delete mode 100644 docs/dots/Rendezvous/RendezvousSessionGeneral.dot delete mode 100644 docs/dots/Rendezvous/RendezvousSessionInit.dot create mode 100644 docs/examples/index.md create mode 100644 docs/guides/index.md delete mode 100644 docs/images/logo.svg create mode 100644 docs/index.md create mode 100644 docs/make.bat rename docs/{Doxyfile => matter.doxyfile.in} (87%) delete mode 100644 docs/namespaces.dox create mode 100644 docs/requirements.txt delete mode 100644 docs/style/README.md create mode 100644 docs/style/index.md rename docs/{STYLE_GUIDE.md => style/style_guide.md} (79%) diff --git a/.gitignore b/.gitignore index 5baec0fd0ed020..bba10433b503e3 100644 --- a/.gitignore +++ b/.gitignore @@ -47,8 +47,11 @@ __pycache__ *.pyc *.egg-info -# Doxygen outputs -docs/html +# Python venv +.venv + +# Documentation +docs/_build # VSCode java extensions .project diff --git a/docs/ChipDoxygenLayout.xml b/docs/ChipDoxygenLayout.xml deleted file mode 100644 index 68f3f9e3e703b6..00000000000000 --- a/docs/ChipDoxygenLayout.xml +++ /dev/null @@ -1,225 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000000000..7c4c49345a5544 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,21 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= -c . -d _build/doctrees +SPHINXBUILD ?= sphinx-build +SOURCEDIR = _build/src +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + mkdir -p "$(SOURCEDIR)" + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/_doxygen/logo.png b/docs/_doxygen/logo.png new file mode 100644 index 0000000000000000000000000000000000000000..196c868443ef4bcf9a59a1d40109c212220b8e85 GIT binary patch literal 6871 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 RZAbtB002ovPDHLkV1oM`AuIp@ literal 0 HcmV?d00001 diff --git a/docs/_extensions/doxyrunner.py b/docs/_extensions/doxyrunner.py new file mode 100644 index 00000000000000..7073ec16d9db5e --- /dev/null +++ b/docs/_extensions/doxyrunner.py @@ -0,0 +1,388 @@ +""" +Doxyrunner Sphinx Plugin +######################## + +Copyright (c) 2021 Nordic Semiconductor ASA +SPDX-License-Identifier: Apache-2.0 + +Introduction +============ + +This Sphinx plugin can be used to run Doxygen build as part of the Sphinx build +process. It is meant to be used with other plugins such as ``breathe`` in order +to improve the user experience. The principal features offered by this plugin +are: + +- Doxygen build is run before Sphinx reads input files +- Doxyfile can be optionally pre-processed so that variables can be inserted +- Changes in the Doxygen input files are tracked so that Doxygen build is only + run if necessary. +- Synchronizes Doxygen XML output so that even if Doxygen is run only changed, + deleted or added files are modified. + +References: + +- https://github.com/michaeljones/breathe/issues/420 + +Configuration options +===================== + +- ``doxyrunner_doxygen``: Path to the Doxygen binary. +- ``doxyrunner_doxyfile``: Path to Doxyfile. +- ``doxyrunner_outdir``: Doxygen build output directory (inserted to + ``OUTPUT_DIRECTORY``) +- ``doxyrunner_fmt``: Flag to indicate if Doxyfile should be formatted. +- ``doxyrunner_fmt_vars``: Format variables dictionary (name: value). +- ``doxyrunner_fmt_pattern``: Format pattern. +- ``doxyrunner_silent``: If Doxygen output should be logged or not. Note that + this option may not have any effect if ``QUIET`` is set to ``YES``. +""" + +import filecmp +import hashlib +from pathlib import Path +import re +import shlex +import shutil +from subprocess import Popen, PIPE, STDOUT +import tempfile +from typing import List, Dict, Optional, Any + +from sphinx.application import Sphinx +from sphinx.environment import BuildEnvironment +from sphinx.util import logging + + +__version__ = "0.1.0" + + +logger = logging.getLogger(__name__) + + +def hash_file(file: Path) -> str: + """Compute the hash (SHA256) of a file in text mode. + + Args: + file: File to be hashed. + + Returns: + Hash. + """ + + with open(file, encoding="utf-8") as f: + sha256 = hashlib.sha256(f.read().encode("utf-8")) + + return sha256.hexdigest() + +def get_doxygen_option(doxyfile: str, option: str) -> List[str]: + """Obtain the value of a Doxygen option. + + Args: + doxyfile: Content of the Doxyfile. + option: Option to be retrieved. + + Notes: + Does not support appended values. + + Returns: + Option values. + """ + + option_re = re.compile(r"^\s*([A-Z0-9_]+)\s*=\s*(.*)$") + multiline_re = re.compile(r"^\s*(.*)$") + + values = [] + found = False + finished = False + for line in doxyfile.splitlines(): + if not found: + m = option_re.match(line) + if not m or m.group(1) != option: + continue + + found = True + value = m.group(2) + else: + m = multiline_re.match(line) + if not m: + raise ValueError(f"Unexpected line content: {line}") + + value = m.group(1) + + # check if it is a multiline value + finished = not value.endswith("\\") + + # strip backslash + if not finished: + value = value[:-1] + + # split values + values += shlex.split(value.replace("\\", "\\\\")) + + if finished: + break + + return values + + +def process_doxyfile( + doxyfile: str, + outdir: Path, + silent: bool, + fmt: bool = False, + fmt_pattern: Optional[str] = None, + fmt_vars: Optional[Dict[str, str]] = None, +) -> str: + """Process Doxyfile. + + Notes: + OUTPUT_DIRECTORY, WARN_FORMAT and QUIET are overridden to satisfy + extension operation needs. + + Args: + doxyfile: Path to the Doxyfile. + outdir: Output directory of the Doxygen build. + silent: If Doxygen should be run in quiet mode or not. + fmt: If Doxyfile should be formatted. + fmt_pattern: Format pattern. + fmt_vars: Format variables. + + Returns: + Processed Doxyfile content. + """ + + with open(doxyfile) as f: + content = f.read() + + content = re.sub( + r"^\s*OUTPUT_DIRECTORY\s*=.*$", + f"OUTPUT_DIRECTORY={outdir.as_posix()}", + content, + flags=re.MULTILINE, + ) + + content = re.sub( + r"^\s*WARN_FORMAT\s*=.*$", + 'WARN_FORMAT="$file:$line: $text"', + content, + flags=re.MULTILINE, + ) + + content = re.sub( + r"^\s*QUIET\s*=.*$", + "QUIET=" + "YES" if silent else "NO", + content, + flags=re.MULTILINE, + ) + + if fmt: + if not fmt_pattern or not fmt_vars: + raise ValueError("Invalid formatting pattern or variables") + + for var, value in fmt_vars.items(): + content = content.replace(fmt_pattern.format(var), value) + + return content + + +def doxygen_input_has_changed(env: BuildEnvironment, doxyfile: str) -> bool: + """Check if Doxygen input files have changed. + + Args: + env: Sphinx build environment instance. + doxyfile: Doxyfile content. + + Returns: + True if changed, False otherwise. + """ + + # obtain Doxygen input files and patterns + input_files = get_doxygen_option(doxyfile, "INPUT") + if not input: + raise ValueError("No INPUT set in Doxyfile") + + file_patterns = get_doxygen_option(doxyfile, "FILE_PATTERNS") + if not file_patterns: + raise ValueError("No FILE_PATTERNS set in Doxyfile") + + # build a set with input files hash + cache = set() + for file in input_files: + path = Path(file) + if path.is_file(): + cache.add(hash_file(path)) + else: + for pattern in file_patterns: + for p_file in path.glob("**/" + pattern): + cache.add(hash_file(p_file)) + + # check if any file has changed + if hasattr(env, "doxyrunner_cache") and env.doxyrunner_cache == cache: + return False + + # store current state + env.doxyrunner_cache = cache + + return True + + +def process_doxygen_output(line: str, silent: bool) -> None: + """Process a line of Doxygen program output. + + This function will map Doxygen output to the Sphinx logger output. Errors + and warnings will be converted to Sphinx errors and warnings. Other + messages, if not silent, will be mapped to the info logger channel. + + Args: + line: Doxygen program line. + silent: True if regular messages should be logged, False otherwise. + """ + + m = re.match(r"(.*):(\d+): ([a-z]+): (.*)", line) + if m: + type = m.group(3) + message = f"{m.group(1)}:{m.group(2)}: {m.group(4)}" + if type == "error": + logger.error(message) + elif type == "warning": + logger.warning(message) + else: + logger.info(message) + elif not silent: + logger.info(line) + + +def run_doxygen(doxygen: str, doxyfile: str, silent: bool = False) -> None: + """Run Doxygen build. + + Args: + doxygen: Path to Doxygen binary. + doxyfile: Doxyfile content. + silent: If Doxygen output should be logged or not. + """ + + f_doxyfile = tempfile.NamedTemporaryFile("w", delete=False) + f_doxyfile.write(doxyfile) + f_doxyfile.close() + + p = Popen([doxygen, f_doxyfile.name], stdout=PIPE, stderr=STDOUT, encoding="utf-8") + while True: + line = p.stdout.readline() # type: ignore + if line: + process_doxygen_output(line.rstrip(), silent) + if p.poll() is not None: + break + + Path(f_doxyfile.name).unlink() + + if p.returncode: + raise IOError(f"Doxygen process returned non-zero ({p.returncode})") + + +def sync_doxygen(doxyfile: str, new: Path, prev: Path) -> None: + """Synchronize Doxygen output with a previous build. + + This function makes sure that only new, deleted or changed files are + actually modified in the Doxygen XML output. Latest HTML content is just + moved. + + Args: + doxyfile: Contents of the Doxyfile. + new: Newest Doxygen build output directory. + prev: Previous Doxygen build output directory. + """ + + generate_html = get_doxygen_option(doxyfile, "GENERATE_HTML") + if generate_html[0] == "YES": + html_output = get_doxygen_option(doxyfile, "HTML_OUTPUT") + if not html_output: + raise ValueError("No HTML_OUTPUT set in Doxyfile") + + new_htmldir = new / html_output[0] + prev_htmldir = prev / html_output[0] + + if prev_htmldir.exists(): + shutil.rmtree(prev_htmldir) + new_htmldir.rename(prev_htmldir) + + xml_output = get_doxygen_option(doxyfile, "XML_OUTPUT") + if not xml_output: + raise ValueError("No XML_OUTPUT set in Doxyfile") + + new_xmldir = new / xml_output[0] + prev_xmldir = prev / xml_output[0] + + if prev_xmldir.exists(): + dcmp = filecmp.dircmp(new_xmldir, prev_xmldir) + + for file in dcmp.right_only: + (Path(dcmp.right) / file).unlink() + + for file in dcmp.left_only + dcmp.diff_files: + shutil.copy(Path(dcmp.left) / file, Path(dcmp.right) / file) + + shutil.rmtree(new_xmldir) + else: + new_xmldir.rename(prev_xmldir) + + +def doxygen_build(app: Sphinx) -> None: + """Doxyrunner entry point. + + Args: + app: Sphinx application instance. + """ + + if app.config.doxyrunner_outdir: + outdir = Path(app.config.doxyrunner_outdir) + else: + outdir = Path(app.outdir) / "_doxygen" + + outdir.mkdir(exist_ok=True) + tmp_outdir = outdir / "tmp" + + logger.info("Preparing Doxyfile...") + doxyfile = process_doxyfile( + app.config.doxyrunner_doxyfile, + tmp_outdir, + app.config.doxyrunner_silent, + app.config.doxyrunner_fmt, + app.config.doxyrunner_fmt_pattern, + app.config.doxyrunner_fmt_vars, + ) + + logger.info("Checking if Doxygen needs to be run...") + changed = doxygen_input_has_changed(app.env, doxyfile) + if not changed: + logger.info("Doxygen build will be skipped (no changes)!") + return + + logger.info("Running Doxygen...") + run_doxygen( + app.config.doxyrunner_doxygen, + doxyfile, + app.config.doxyrunner_silent, + ) + + logger.info("Syncing Doxygen output...") + sync_doxygen(doxyfile, tmp_outdir, outdir) + + shutil.rmtree(tmp_outdir) + + +def setup(app: Sphinx) -> Dict[str, Any]: + app.add_config_value("doxyrunner_doxygen", "doxygen", "env") + app.add_config_value("doxyrunner_doxyfile", None, "env") + app.add_config_value("doxyrunner_outdir", None, "env") + app.add_config_value("doxyrunner_fmt", False, "env") + app.add_config_value("doxyrunner_fmt_vars", {}, "env") + app.add_config_value("doxyrunner_fmt_pattern", "@{}@", "env") + app.add_config_value("doxyrunner_silent", True, "") + + app.connect("builder-inited", doxygen_build) + + return { + "version": __version__, + "parallel_read_safe": True, + "parallel_write_safe": True, + } diff --git a/docs/_extensions/external_content.py b/docs/_extensions/external_content.py new file mode 100644 index 00000000000000..8f4acfd3d70cf7 --- /dev/null +++ b/docs/_extensions/external_content.py @@ -0,0 +1,176 @@ +""" +External content +################ + +Copyright (c) 2021 Nordic Semiconductor ASA +SPDX-License-Identifier: Apache-2.0 + +Introduction +============ + +This extension allows to import sources from directories out of the Sphinx +source directory. They are copied to the source directory before starting the +build. Note that the copy is *smart*, that is, only updated files are actually +copied. Therefore, incremental builds detect changes correctly and behave as +expected. + +Paths for external content ingluded via e.g. figure, literalinclude, etc. +are adjusted as needed. + +Configuration options +===================== + +- ``external_content_contents``: A list of external contents. Each entry is + a tuple with two fields: the external base directory and a file glob pattern. +- ``external_content_directives``: A list of directives that should be analyzed + and their paths adjusted if necessary. Defaults to ``DEFAULT_DIRECTIVES``. +- ``external_content_keep``: A list of file globs (relative to the destination + directory) that should be kept even if they do not exist in the source + directory. This option can be useful for auto-generated files in the + destination directory. +""" + +import filecmp +import os +from pathlib import Path +import re +import shutil +import tempfile +from typing import Dict, Any, List, Optional + +from sphinx.application import Sphinx + + +__version__ = "0.1.0" + + +DEFAULT_DIRECTIVES = ("figure", "image", "include", "literalinclude") +"""Default directives for included content.""" + + +def adjust_includes( + fname: Path, + basepath: Path, + directives: List[str], + encoding: str, + dstpath: Optional[Path] = None, +) -> None: + """Adjust included content paths. + + Args: + fname: File to be processed. + basepath: Base path to be used to resolve content location. + directives: Directives to be parsed and adjusted. + encoding: Sources encoding. + dstpath: Destination path for fname if its path is not the actual destination. + """ + + if fname.suffix != ".rst": + return + + dstpath = dstpath or fname.parent + + def _adjust(m): + directive, fpath = m.groups() + + # ignore absolute paths + if fpath.startswith("/"): + fpath_adj = fpath + else: + fpath_adj = Path(os.path.relpath(basepath / fpath, dstpath)).as_posix() + + return f".. {directive}:: {fpath_adj}" + + with open(fname, "r+", encoding=encoding) as f: + content = f.read() + content_adj, modified = re.subn( + r"\.\. (" + "|".join(directives) + r")::\s*([^`\n]+)", _adjust, content + ) + if modified: + f.seek(0) + f.write(content_adj) + f.truncate() + + +def sync_contents(app: Sphinx) -> None: + """Synhronize external contents. + + Args: + app: Sphinx application instance. + """ + + srcdir = Path(app.srcdir).resolve() + to_copy = [] + to_delete = set(f for f in srcdir.glob("**/*") if not f.is_dir()) + to_keep = set( + f + for k in app.config.external_content_keep + for f in srcdir.glob(k) + if not f.is_dir() + ) + + for content in app.config.external_content_contents: + prefix_src, glob = content + for src in prefix_src.glob(glob): + if src.is_dir(): + to_copy.extend( + [(f, prefix_src) for f in src.glob("**/*") if not f.is_dir()] + ) + else: + to_copy.append((src, prefix_src)) + + for entry in to_copy: + src, prefix_src = entry + dst = (srcdir / src.relative_to(prefix_src)).resolve() + + if dst in to_delete: + to_delete.remove(dst) + + if not dst.parent.exists(): + dst.parent.mkdir(parents=True) + + # just copy if it does not exist + if not dst.exists(): + shutil.copy(src, dst) + adjust_includes( + dst, + src.parent, + app.config.external_content_directives, + app.config.source_encoding, + ) + # if origin file is modified only copy if different + elif src.stat().st_mtime > dst.stat().st_mtime: + with tempfile.TemporaryDirectory() as td: + # adjust origin includes before comparing + src_adjusted = Path(td) / src.name + shutil.copy(src, src_adjusted) + adjust_includes( + src_adjusted, + src.parent, + app.config.external_content_directives, + app.config.source_encoding, + dstpath=dst.parent, + ) + + if not filecmp.cmp(src_adjusted, dst): + dst.unlink() + shutil.move(os.fspath(src_adjusted), os.fspath(dst)) + + # remove any previously copied file not present in the origin folder, + # excepting those marked to be kept. + for file in to_delete - to_keep: + file.unlink() + + +def setup(app: Sphinx) -> Dict[str, Any]: + app.add_config_value("external_content_contents", [], "env") + app.add_config_value("external_content_directives", DEFAULT_DIRECTIVES, "env") + app.add_config_value("external_content_keep", [], "") + + app.connect("builder-inited", sync_contents) + + return { + "version": __version__, + "parallel_read_safe": True, + "parallel_write_safe": True, + } diff --git a/docs/_static/images/favicon.ico b/docs/_static/images/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..16f3d88dcc98c7cbd1b1af0433bc9d47a2cca186 GIT binary patch literal 4281 zcmeHKdu&rx7{7h4U4YoJCtI_-yDoz6_CET)(v7VhqqxExi(v4P+j~#9y0*8pceI-t znE@hdTs9He1Y$s9T%3jlfq_9DiwNohF$U0}BN7xzAS#cUVCuPDH>QDQ{^4KlH0eD( z=lA`-@B4k7yRYK(n-bRabw(M6rxQ8<#0G8 z4w}Xx0*|$YMK*zlW2NH^ZV=<5fruCo!l=Z^`h-@|iNQ$6QV2yRXz!`jB%s$jH8d2G z1W3`w#G19x%Tz^(HMT_n(EwsXYm@^uYe85n9XIE>3EN0(G?>bi=Lir4Aqb1XB2p8s zBF%y*#F~ZsAitO~j0w3_VO$X}rGM;cuWWyZrxSbfx!x#wg z3~ln;S)Y%@eLOJXW)ttj9f0C+4zNC&^pm{VXG+Bd?cD;`DhVjrk2NkYaFAm{BZjrv zDB5bZ;k+Golig}I<38F%;&z{vv$2%jY^EmImPZ5d-C={1S*56W$Y{3$E6w_8oU@ZY z+)Qy6oHbcU-0%09EIhC{c)Jxtd5-Z5(GUweB@kkp0P$=DG-2r7a9l!Ah1sCG1<`r%IxCY+VuI9i z1>Dd>e{#j&_GEHhR!J3wDU#nJvlKEIk3xr3A|IO(`5Qu=!@u!jAo#?ThCA==k%(;f)91cYjgWQtNHqbm@8C zb!GW7*NMV4?pKiFg5g@>#XY+=zo4a$uQqjchlWpX9*DM3@^>#b0Qe_10N=ltCt=+HtMO@AJ6S`c1QZRlLuezp)+55bLCB~Yq0ie zf6I+dPu|f3+rF`VpfB?e8T$%9&vZUfeofx#+gSPfjrHw@(Rq>44Q~{OG9MrM=rZ$6 z<|989W(p^|M>D^?c5BsH<d pwM1{u06W^co=cbx^#74jKhpiq&i<}q-`1j$3VF{jTZfY8{{pw$$B+O3 literal 0 HcmV?d00001 diff --git a/docs/_static/images/logo.png b/docs/_static/images/logo.png new file mode 100644 index 0000000000000000000000000000000000000000..88bcee2d157f8fac7c8fa4759642f5c1fbf3d7d8 GIT binary patch literal 36520 zcmeGDcUM#2_XiFpgoNIa-m3^wq)JDkbP$kU1p(mZ$ zy?27t-}UqMJ8K@m{4=v=LDoucPWC-#_x;-YMnBe8At7WS1c5*#YN~KO5C}#L0)b8O zVZfD7*1qQ;5Z+Ya6Ju|^r+#c6FWl`NUF_Jr13c{5?ED?=K_LIxs&v=1`8E>xjn^#` z93@J&7N*eLWaejoTAyIwI=FN%|KZ~FtI$&8GB&ua`1EEgkM}a7n@i+%!DQ9Dhu7-- zcYQ+rgRdIb%xnU>tinWRgO2C?zh7U!lX4jO+GN+~>HsysaIY&KFU(5qI(OZ6 z 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 L)z4*}Q$iB}rwM~Q literal 0 HcmV?d00001 diff --git a/docs/api/index.md b/docs/api/index.md new file mode 100644 index 00000000000000..d642d6505ca432 --- /dev/null +++ b/docs/api/index.md @@ -0,0 +1,7 @@ +# API + +```{toctree} +:glob: + +* +``` \ No newline at end of file diff --git a/docs/breathe.md b/docs/breathe.md new file mode 100644 index 00000000000000..d84d7cd9e7291b --- /dev/null +++ b/docs/breathe.md @@ -0,0 +1,6 @@ +# Breathe (Doxygen) + +```{eval-rst} +.. doxygenclass:: chip::Ble::BleTransportCapabilitiesRequestMessage + :members: +``` \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000000000..5655b98a03e50f --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,67 @@ +# Configuration file for the Sphinx documentation builder. + +import os +from pathlib import Path +import sys + +# -- Paths ------------------------------------------------------------------- + +MATTER_BASE = Path(__file__).resolve().parents[1] + +sys.path.insert(0, str(MATTER_BASE / "docs" / "_extensions")) + +# -- Project information ----------------------------------------------------- + +project = "Matter" +copyright = "2021, Matter Contributors" +author = "Matter Contributors" +version = "1.0.0" + +# -- General configuration --------------------------------------------------- + +extensions = ["myst_parser", "external_content", "doxyrunner", "breathe"] +exclude_patterns = ["_build"] + + +# -- Options for HTML output ------------------------------------------------- + +html_theme = "sphinx_book_theme" +html_logo = "_static/images/logo.png" +html_favicon = "_static/images/favicon.ico" +html_static_path = ["_static"] +html_theme_options = { + "logo_only": True, + "github_url": "https://github.com/project-chip/connectedhomeip", + "repository_url": "https://github.com/project-chip/connectedhomeip", + "use_edit_page_button": True, + "repository_branch": "master", + "path_to_docs": "docs", +} + +# -- Options for external_content -------------------------------------------- + +external_content_contents = [ + (MATTER_BASE / "docs", "[!_]*"), + (MATTER_BASE, "examples/**/*.md"), +] + +# -- Options for zephyr.doxyrunner plugin ------------------------------------ + +doxyrunner_doxygen = os.environ.get("DOXYGEN_EXECUTABLE", "doxygen") +doxyrunner_doxyfile = MATTER_BASE / "docs" / "matter.doxyfile.in" +doxyrunner_outdir = MATTER_BASE / "docs" / "_build" / "doxygen" +doxyrunner_fmt = True +doxyrunner_fmt_vars = { + "MATTER_BASE": str(MATTER_BASE), + "MATTER_VERSION": version +} + +# -- Options for Breathe plugin ------------------------------------------- + +breathe_projects = {"Matter": str(doxyrunner_outdir / "xml")} +breathe_default_project = "Matter" +breathe_domain_by_extension = { + "h": "cpp", + "cpp": "cpp", + "c": "c", +} \ No newline at end of file diff --git a/docs/discussion/index.md b/docs/discussion/index.md new file mode 100644 index 00000000000000..a954e84ae1d522 --- /dev/null +++ b/docs/discussion/index.md @@ -0,0 +1,7 @@ +# Discussion + +```{toctree} +:glob: + +* +``` \ No newline at end of file diff --git a/docs/dots/Rendezvous/RendezvousSessionGeneral.dot b/docs/dots/Rendezvous/RendezvousSessionGeneral.dot deleted file mode 100644 index 8578363c69a3d0..00000000000000 --- a/docs/dots/Rendezvous/RendezvousSessionGeneral.dot +++ /dev/null @@ -1,37 +0,0 @@ -digraph RendezvousSession -{ - node [shape=box, fillcolor="white:gray", gradientangle=90, style=filled] - - # This section represents controller-only elements - subgraph cluster_controller { - label=<Controller> - - DeviceCommissioner [shape=record label=<{DeviceCommissioner|RendezvousSessionDelegate}>, URL="@ref chip::Controller::DeviceCommissioner"] - } - - # This section represents device-only elements - subgraph cluster_device { - label=<Device> - - RendezvousDeviceDelegate [shape=record label=<{RendezvousDeviceDelegate|RendezvousSessionDelegate}> URL="@ref chip::RendezvousSessionDelegate"] - } - - # This section represents elements which belongs to src/transport/ - subgraph cluster_transport { - label=<Transport> - - RendezvousSession [shape=record, label=<{RendezvousSession|SessionEstablishmentDelegate}>, URL="@ref chip::SessionEstablishmentDelegate"] - TransportBle [label="Transport::BLE", URL="@ref chip::Transport::BLE"] - TransportInet [label="Transport::?", style=dashed, color=gray] - } - - ############################# - # Main relationships - ############################# - RendezvousParameters [shape=ellipse, URL="@ref chip::RendezvousParameters"] - RendezvousParameters -> { DeviceCommissioner, RendezvousDeviceDelegate} [arrowhead=none] - - {DeviceCommissioner, RendezvousDeviceDelegate} -> RendezvousSession - RendezvousSession -> TransportBle - RendezvousSession -> TransportInet [style=dashed, color=gray] -} diff --git a/docs/dots/Rendezvous/RendezvousSessionInit.dot b/docs/dots/Rendezvous/RendezvousSessionInit.dot deleted file mode 100644 index 79983ce6e1aa1a..00000000000000 --- a/docs/dots/Rendezvous/RendezvousSessionInit.dot +++ /dev/null @@ -1,83 +0,0 @@ -digraph RendezvousSession -{ - node [fillcolor="gray", style=filled] - - # This section represents controller-only elements - subgraph cluster_controller { - label=<Controller> - node [fillcolor="white:gray", gradientangle=90] - - DeviceCommissioner [shape=record label=<{DeviceCommissioner|RendezvousSessionDelegate}>, URL="@ref chip::Controller::DeviceCommissioner"] - } - - # This section represents device-only elements - subgraph cluster_device { - label=<Device> - node [fillcolor="white:gray", gradientangle=90] - - RendezvousDeviceDelegate [shape=record label=<{RendezvousDeviceDelegate|RendezvousSessionDelegate}> URL="@ref chip::RendezvousSessionDelegate"] - } - - # This section represents elements which belongs to src/transport/ - subgraph rendezvousSession { - node [fillcolor="white:gray", gradientangle=90] - - RendezvousSession [shape=record, label=<{RendezvousSession|SessionEstablishmentDelegate}>, URL="@ref chip::SessionEstablishmentDelegate"] - } - - # This section represents methods which belongs to PASESession - subgraph cluster_securePairingSession { - label=<PASESession> - node [fillcolor="gray"] - - WaitForPairing [URL="@ref chip::PASESession::WaitForPairing"] - Pair [URL="@ref chip::PASESession::Pair"] - DeriveSecureSession [URL="@ref chip::PASESession::DeriveSecureSession"] - } - - # This section represents methods which belongs to RendezvousParameters - subgraph cluster_RendezvousParameters { - label=<RendezvousParameters> - node [fillcolor="gray"] - - HasDiscriminator [URL="@ref chip::RendezvousParameters::HasDiscriminator"] - HasConnectionObject [URL="@ref chip::RendezvousParameters::HasConnectionObject"] - } - - # This section represents callbacks which belongs to RendezvousSessionDelegate - subgraph cluster_rendezvousSessionDelegate { - label=<RendezvousSessionDelegate> - node [fillcolor="white"] - - OnRendezvousConnectionOpened [URL="@ref chip::RendezvousSessionDelegate::OnRendezvousConnectionOpened"] - OnRendezvousConnectionClosed [URL="@ref chip::RendezvousSessionDelegate::OnRendezvousConnectionClosed"] - OnRendezvousError [URL="@ref chip::RendezvousSessionDelegate::OnRendezvousError"] - } - - # This section represents callbacks which belongs to SessionEstablishmentDelegate - subgraph cluster_secureSessionEstablishmentDelegate { - label=<SessionEstablishmentDelegate> - node [fillcolor="white"] - - OnSessionEstablishmentError [URL="@ref chip::SessionEstablishmentDelegate::OnSessionEstablishmentError"] - OnSessionEstablished [URL="@ref chip::SessionEstablishmentDelegate::OnSessionEstablished"] - } - - ############################# - # Main relationships - ############################# - {DeviceCommissioner, RendezvousDeviceDelegate} -> RendezvousSession - - RendezvousSession -> HasDiscriminator - - HasDiscriminator -> DelegateConnection [label=YES] - DelegateConnection -> Pair - - HasDiscriminator -> HasConnectionObject [label=NO] - HasConnectionObject -> Pair [label=YES] - - HasConnectionObject -> WaitForPairing [label=NO] - - OnSessionEstablishmentError -> OnRendezvousError - OnSessionEstablished -> DeriveSecureSession -> OnRendezvousConnectionOpened -} diff --git a/docs/examples/index.md b/docs/examples/index.md new file mode 100644 index 00000000000000..d09baaa1c2a996 --- /dev/null +++ b/docs/examples/index.md @@ -0,0 +1,7 @@ +# Examples + +```{toctree} +:glob: + +**/README +``` \ No newline at end of file diff --git a/docs/guides/index.md b/docs/guides/index.md new file mode 100644 index 00000000000000..d446380beee25a --- /dev/null +++ b/docs/guides/index.md @@ -0,0 +1,7 @@ +# Guides + +```{toctree} +:glob: + +* +``` \ No newline at end of file diff --git a/docs/images/logo.svg b/docs/images/logo.svg deleted file mode 100644 index 7dcae9ffa48fa8..00000000000000 --- a/docs/images/logo.svg +++ /dev/null @@ -1,37 +0,0 @@ - - - - Zigbee-Alliance-logo-black - Created with Sketch. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000000000..56ad7ba3354a9b --- /dev/null +++ b/docs/index.md @@ -0,0 +1,16 @@ +# Welcome to Matter's documentation! + +```{toctree} +:maxdepth: 2 +:caption: Contents + +quick_start +project_flow +vscode_development +api/index +discussion/index +guides/index +style/index +examples/index +breathe +``` diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000000000..73ebcf03f5577d --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,36 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SPHINXOPTS=-c . -d _build\doctrees +set SOURCEDIR=_build\src +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/Doxyfile b/docs/matter.doxyfile.in similarity index 87% rename from docs/Doxyfile rename to docs/matter.doxyfile.in index 279399498d80c2..7ba503e702e8d3 100644 --- a/docs/Doxyfile +++ b/docs/matter.doxyfile.in @@ -1,4 +1,4 @@ -# Doxyfile 1.8.18 +# Doxyfile 1.9.2 # This file describes the settings to be used by the documentation system # doxygen (www.doxygen.org) for a project. @@ -32,13 +32,13 @@ DOXYFILE_ENCODING = UTF-8 # title of most generated pages and in a few other places. # The default value is: My Project. -PROJECT_NAME = $(CHIP_NAME) +PROJECT_NAME = Matter # The PROJECT_NUMBER tag can be used to enter a project or revision number. This # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = $(CHIP_VERSION) +PROJECT_NUMBER = @MATTER_VERSION@ # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a @@ -51,14 +51,14 @@ PROJECT_BRIEF = # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy # the logo to the output directory. -PROJECT_LOGO = docs/images/logo.svg +PROJECT_LOGO = @MATTER_BASE@/docs/_doxygen/logo.png # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path # into which the generated documentation will be written. If a relative path is # entered, it will be relative to the location where doxygen was started. If # left blank the current directory will be used. -OUTPUT_DIRECTORY = docs +OUTPUT_DIRECTORY = # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- # directories (in 2 levels) under the output directory of each output format and @@ -93,14 +93,6 @@ ALLOW_UNICODE_NAMES = NO OUTPUT_LANGUAGE = English -# The OUTPUT_TEXT_DIRECTION tag is used to specify the direction in which all -# documentation generated by doxygen is written. Doxygen will use this -# information to generate all generated output in the proper direction. -# Possible values are: None, LTR, RTL and Context. -# The default value is: None. - -OUTPUT_TEXT_DIRECTION = None - # If the BRIEF_MEMBER_DESC tag is set to YES, doxygen will include brief member # descriptions after the members that are listed in the file and class # documentation (similar to Javadoc). Set to NO to disable this. @@ -227,6 +219,14 @@ QT_AUTOBRIEF = NO MULTILINE_CPP_IS_BRIEF = NO +# By default Python docstrings are displayed as preformatted text and doxygen's +# special commands cannot be used. By setting PYTHON_DOCSTRING to NO the +# doxygen's special commands can be used and the contents of the docstring +# documentation blocks is shown as doxygen documentation. +# The default value is: YES. + +PYTHON_DOCSTRING = YES + # If the INHERIT_DOCS tag is set to YES then an undocumented member inherits the # documentation from any documented member that it re-implements. # The default value is: YES. @@ -250,16 +250,16 @@ TAB_SIZE = 4 # the documentation. An alias has the form: # name=value # For example adding -# "sideeffect=@par Side Effects:\n" +# "sideeffect=@par Side Effects:^^" # will allow you to put the command \sideeffect (or @sideeffect) in the # documentation, which will result in a user-defined paragraph with heading -# "Side Effects:". You can put \n's in the value part of an alias to insert -# newlines (in the resulting output). You can put ^^ in the value part of an -# alias to insert a newline as if a physical newline was in the original file. -# When you need a literal { or } or , in the value part of an alias you have to -# escape them by means of a backslash (\), this can lead to conflicts with the -# commands \{ and \} for these it is advised to use the version @{ and @} or use -# a double escape (\\{ and \\}) +# "Side Effects:". Note that you cannot put \n's in the value part of an alias +# to insert newlines (in the resulting output). You can put ^^ in the value part +# of an alias to insert a newline as if a physical newline was in the original +# file. When you need a literal { or } or , in the value part of an alias you +# have to escape them by means of a backslash (\), this can lead to conflicts +# with the commands \{ and \} for these it is advised to use the version @{ and +# @} or use a double escape (\\{ and \\}) ALIASES = @@ -304,8 +304,8 @@ OPTIMIZE_OUTPUT_SLICE = NO # extension. Doxygen has a built-in mapping, but you can override or extend it # using this tag. The format is ext=language, where ext is a file extension, and # language is one of the parsers supported by doxygen: IDL, Java, JavaScript, -# Csharp (C#), C, C++, D, PHP, md (Markdown), Objective-C, Python, Slice, VHDL, -# Fortran (fixed format Fortran: FortranFixed, free formatted Fortran: +# Csharp (C#), C, C++, Lex, D, PHP, md (Markdown), Objective-C, Python, Slice, +# VHDL, Fortran (fixed format Fortran: FortranFixed, free formatted Fortran: # FortranFree, unknown formatted Fortran: Fortran. In the later case the parser # tries to guess whether the code is fixed or free formatted code, this is the # default for Fortran type files). For instance to make doxygen treat .inc files @@ -315,7 +315,10 @@ OPTIMIZE_OUTPUT_SLICE = NO # Note: For files without extension you can use no_extension as a placeholder. # # Note that for custom extensions you also need to set FILE_PATTERNS otherwise -# the files are not read by doxygen. +# the files are not read by doxygen. When specifying no_extension you should add +# * to the FILE_PATTERNS. +# +# Note see also the list of default file extension mappings. EXTENSION_MAPPING = h=C++ @@ -449,6 +452,19 @@ TYPEDEF_HIDES_STRUCT = NO LOOKUP_CACHE_SIZE = 0 +# The NUM_PROC_THREADS specifies the number threads doxygen is allowed to use +# during processing. When set to 0 doxygen will based this on the number of +# cores available in the system. You can set it explicitly to a value larger +# than 0 to get more control over the balance between CPU load and processing +# speed. At this moment only the input processing can be done using multiple +# threads. Since this is still an experimental feature the default is set to 1, +# which effectively disables parallel processing. Please report any issues you +# encounter. Generating dot graphs in parallel is controlled by the +# DOT_NUM_THREADS setting. +# Minimum value: 0, maximum value: 32, default value: 1. + +NUM_PROC_THREADS = 1 + #--------------------------------------------------------------------------- # Build related configuration options #--------------------------------------------------------------------------- @@ -512,6 +528,13 @@ EXTRACT_LOCAL_METHODS = NO EXTRACT_ANON_NSPACES = NO +# If this flag is set to YES, the name of an unnamed parameter in a declaration +# will be determined by the corresponding definition. By default unnamed +# parameters remain unnamed in the output. +# The default value is: YES. + +RESOLVE_UNNAMED_PARAMS = YES + # If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all # undocumented members inside documented classes or files. If set to NO these # members will be included in the various overviews, but no documentation @@ -549,11 +572,18 @@ HIDE_IN_BODY_DOCS = NO INTERNAL_DOCS = NO -# If the CASE_SENSE_NAMES tag is set to NO then doxygen will only generate file -# names in lower-case letters. If set to YES, upper-case letters are also -# allowed. This is useful if you have classes or files whose names only differ -# in case and if your file system supports case sensitive file names. Windows -# (including Cygwin) ands Mac users are advised to set this option to NO. +# With the correct setting of option CASE_SENSE_NAMES doxygen will better be +# able to match the capabilities of the underlying filesystem. In case the +# filesystem is case sensitive (i.e. it supports files in the same directory +# whose names only differ in casing), the option must be set to YES to properly +# deal with such files in case they appear in the input. For filesystems that +# are not case sensitive the option should be be set to NO to properly deal with +# output files written for symbols that only differ in casing, such as for two +# classes, one named CLASS and the other named Class, and to also support +# references to files without having to specify the exact matching casing. On +# Windows (including Cygwin) and MacOS, users should typically set this option +# to NO, whereas on Linux or other Unix flavors it should typically be set to +# YES. # The default value is: system dependent. CASE_SENSE_NAMES = NO @@ -572,6 +602,12 @@ HIDE_SCOPE_NAMES = NO HIDE_COMPOUND_REFERENCE= NO +# If the SHOW_HEADERFILE tag is set to YES then the documentation for a class +# will show which file needs to be included to use the class. +# The default value is: YES. + +SHOW_HEADERFILE = YES + # If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of # the files that are included by a file in the documentation of that file. # The default value is: YES. @@ -729,13 +765,14 @@ FILE_VERSION_FILTER = # output files in an output format independent way. To create the layout file # that represents doxygen's defaults, run doxygen with the -l option. You can # optionally specify a file name after the option, if omitted DoxygenLayout.xml -# will be used as the name of the layout file. +# will be used as the name of the layout file. See also section "Changing the +# layout of pages" for information. # # Note that if you run doxygen from a directory containing a file called # DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE # tag is left empty. -LAYOUT_FILE = docs/ChipDoxygenLayout.xml +LAYOUT_FILE = @MATTER_BASE@/docs/_doxygen/DoxygenLayout.xml # The CITE_BIB_FILES tag can be used to specify one or more bib files containing # the reference definitions. This must be a list of .bib files. The .bib @@ -775,27 +812,38 @@ WARNINGS = YES WARN_IF_UNDOCUMENTED = NO # If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for -# potential errors in the documentation, such as not documenting some parameters -# in a documented function, or documenting parameters that don't exist or using -# markup commands wrongly. +# potential errors in the documentation, such as documenting some parameters in +# a documented function twice, or documenting parameters that don't exist or +# using markup commands wrongly. # The default value is: YES. WARN_IF_DOC_ERROR = YES +# If WARN_IF_INCOMPLETE_DOC is set to YES, doxygen will warn about incomplete +# function parameter documentation. If set to NO, doxygen will accept that some +# parameters have no documentation without warning. +# The default value is: YES. + +WARN_IF_INCOMPLETE_DOC = YES + # This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that # are documented, but have no documentation for their parameters or return -# value. If set to NO, doxygen will only warn about wrong or incomplete -# parameter documentation, but not about the absence of documentation. If -# EXTRACT_ALL is set to YES then this flag will automatically be disabled. +# value. If set to NO, doxygen will only warn about wrong parameter +# documentation, but not about the absence of documentation. If EXTRACT_ALL is +# set to YES then this flag will automatically be disabled. See also +# WARN_IF_INCOMPLETE_DOC # The default value is: NO. WARN_NO_PARAMDOC = NO # If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when -# a warning is encountered. +# a warning is encountered. If the WARN_AS_ERROR tag is set to FAIL_ON_WARNINGS +# then doxygen will continue running as if WARN_AS_ERROR tag is set to NO, but +# at the end of the doxygen process doxygen will return with a non-zero status. +# Possible values are: NO, YES and FAIL_ON_WARNINGS. # The default value is: NO. -WARN_AS_ERROR = YES +WARN_AS_ERROR = NO # The WARN_FORMAT tag determines the format of the warning messages that doxygen # can produce. The string should contain the $file, $line, and $text tags, which @@ -823,36 +871,25 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = README.md \ - CODE_OF_CONDUCT.md \ - CONTRIBUTING.md \ - docs/README.md \ - docs/guides/BUILDING.md \ - docs/VSCODE_DEVELOPMENT.md \ - docs/PROJECT_FLOW.md \ - docs/STYLE_GUIDE.md \ - src/ble \ - src/controller \ - src/crypto \ - src/include \ - src/inet \ - src/lib/dnssd \ - src/lib/core \ - src/lib/support \ - src/lib/shell \ - src/platform \ - src/setup_payload \ - src/system \ - src/transport \ - src/test_driver/linux-cirque/README.md - -USE_MDFILE_AS_MAINPAGE = README.md +INPUT = @MATTER_BASE@/src/ble \ + @MATTER_BASE@/src/controller \ + @MATTER_BASE@/src/crypto \ + @MATTER_BASE@/src/include \ + @MATTER_BASE@/src/inet \ + @MATTER_BASE@/src/lib/mdns \ + @MATTER_BASE@/src/lib/core \ + @MATTER_BASE@/src/lib/support \ + @MATTER_BASE@/src/lib/shell \ + @MATTER_BASE@/src/platform \ + @MATTER_BASE@/src/setup_payload \ + @MATTER_BASE@/src/system \ + @MATTER_BASE@/src/transport # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses # libiconv (or the iconv built into libc) for the transcoding. See the libiconv -# documentation (see: https://www.gnu.org/software/libiconv/) for the list of -# possible encodings. +# documentation (see: +# https://www.gnu.org/software/libiconv/) for the list of possible encodings. # The default value is: UTF-8. INPUT_ENCODING = UTF-8 @@ -865,12 +902,14 @@ INPUT_ENCODING = UTF-8 # need to set EXTENSION_MAPPING for the extension otherwise the files are not # read by doxygen. # +# Note the list of default checked file patterns might differ from the list of +# default file extension mappings. +# # If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp, # *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, -# *.hh, *.hxx, *.hpp, *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc, -# *.m, *.markdown, *.md, *.mm, *.dox (to be provided as doxygen C comment), -# *.doc (to be provided as doxygen C comment), *.txt (to be provided as doxygen -# C comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, *.f18, *.f, *.for, *.vhd, +# *.hh, *.hxx, *.hpp, *.h++, *.l, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, +# *.inc, *.m, *.markdown, *.md, *.mm, *.dox (to be provided as doxygen C +# comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, *.f18, *.f, *.for, *.vhd, # *.vhdl, *.ucf, *.qsf and *.ice. FILE_PATTERNS = *.c \ @@ -919,7 +958,7 @@ RECURSIVE = YES # Note that relative paths are relative to the directory from which doxygen is # run. -EXCLUDE = +EXCLUDE = # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded @@ -950,10 +989,10 @@ EXCLUDE_PATTERNS = NetworkProvisioningServer* \ # Note that the wildcards are matched against the file with absolute path, so to # exclude all test directories use the pattern */test/* -EXCLUDE_SYMBOLS = VerifyOrExit \ - SuccessOrExit \ - ExitNow \ - */dbus/* +EXCLUDE_SYMBOLS = VerifyOrExit \ + SuccessOrExit \ + ExitNow \ + */dbus/* # The EXAMPLE_PATH tag can be used to specify one or more files or directories # that contain example code fragments that are included (see the \include @@ -979,7 +1018,7 @@ EXAMPLE_RECURSIVE = NO # that contain images that are to be included in the documentation (see the # \image command). -IMAGE_PATH = docs/images +IMAGE_PATH = # The INPUT_FILTER tag can be used to specify a program that doxygen should # invoke to filter for each input file. Doxygen will invoke the filter program @@ -1123,6 +1162,46 @@ USE_HTAGS = NO VERBATIM_HEADERS = YES +# If the CLANG_ASSISTED_PARSING tag is set to YES then doxygen will use the +# clang parser (see: +# http://clang.llvm.org/) for more accurate parsing at the cost of reduced +# performance. This can be particularly helpful with template rich C++ code for +# which doxygen's built-in parser lacks the necessary type information. +# Note: The availability of this option depends on whether or not doxygen was +# generated with the -Duse_libclang=ON option for CMake. +# The default value is: NO. + +CLANG_ASSISTED_PARSING = NO + +# If the CLANG_ASSISTED_PARSING tag is set to YES and the CLANG_ADD_INC_PATHS +# tag is set to YES then doxygen will add the directory of each input to the +# include path. +# The default value is: YES. +# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES. + +CLANG_ADD_INC_PATHS = YES + +# If clang assisted parsing is enabled you can provide the compiler with command +# line options that you would normally use when invoking the compiler. Note that +# the include paths will already be set by doxygen for the files and directories +# specified with INPUT and INCLUDE_PATH. +# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES. + +CLANG_OPTIONS = + +# If clang assisted parsing is enabled you can provide the clang parser with the +# path to the directory containing a file called compile_commands.json. This +# file is the compilation database (see: +# http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html) containing the +# options used when the source files were built. This is equivalent to +# specifying the -p option to a clang tool, such as clang-check. These options +# will then be passed to the parser. Any options specified with CLANG_OPTIONS +# will be added as well. +# Note: The availability of this option depends on whether or not doxygen was +# generated with the -Duse_libclang=ON option for CMake. + +CLANG_DATABASE_PATH = + #--------------------------------------------------------------------------- # Configuration options related to the alphabetical class index #--------------------------------------------------------------------------- @@ -1134,13 +1213,6 @@ VERBATIM_HEADERS = YES ALPHABETICAL_INDEX = YES -# The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in -# which the alphabetical index list will be split. -# Minimum value: 1, maximum value: 20, default value: 5. -# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. - -COLS_IN_ALPHA_INDEX = 5 - # In case all classes in a project start with a common prefix, all classes will # be put under the same header in the alphabetical index. The IGNORE_PREFIX tag # can be used to specify a prefix (or a list of prefixes) that should be ignored @@ -1240,7 +1312,7 @@ HTML_EXTRA_FILES = # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen # will adjust the colors in the style sheet and background images according to -# this color. Hue is specified as an angle on a colorwheel, see +# this color. Hue is specified as an angle on a color-wheel, see # https://en.wikipedia.org/wiki/Hue for more information. For instance the value # 0 represents red, 60 is yellow, 120 is green, 180 is cyan, 240 is blue, 300 # purple, and 360 is red again. @@ -1250,7 +1322,7 @@ HTML_EXTRA_FILES = HTML_COLORSTYLE_HUE = 220 # The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors -# in the HTML output. For a value of 0 the output will use grayscales only. A +# in the HTML output. For a value of 0 the output will use gray-scales only. A # value of 255 will produce the most vivid colors. # Minimum value: 0, maximum value: 255, default value: 100. # This tag requires that the tag GENERATE_HTML is set to YES. @@ -1311,10 +1383,11 @@ HTML_INDEX_NUM_ENTRIES = 100 # If the GENERATE_DOCSET tag is set to YES, additional index files will be # generated that can be used as input for Apple's Xcode 3 integrated development -# environment (see: https://developer.apple.com/xcode/), introduced with OSX -# 10.5 (Leopard). To create a documentation set, doxygen will generate a -# Makefile in the HTML output directory. Running make will produce the docset in -# that directory and running make install will install the docset in +# environment (see: +# https://developer.apple.com/xcode/), introduced with OSX 10.5 (Leopard). To +# create a documentation set, doxygen will generate a Makefile in the HTML +# output directory. Running make will produce the docset in that directory and +# running make install will install the docset in # ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find it at # startup. See https://developer.apple.com/library/archive/featuredarticles/Doxy # genXcode/_index.html for more information. @@ -1356,8 +1429,12 @@ DOCSET_PUBLISHER_NAME = Publisher # If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three # additional HTML index files: index.hhp, index.hhc, and index.hhk. The # index.hhp is a project file that can be read by Microsoft's HTML Help Workshop -# (see: https://www.microsoft.com/en-us/download/details.aspx?id=21138) on -# Windows. +# on Windows. In the beginning of 2021 Microsoft took the original page, with +# a.o. the download links, offline the HTML help workshop was already many years +# in maintenance mode). You can download the HTML help workshop from the web +# archives at Installation executable (see: +# http://web.archive.org/web/20160201063255/http://download.microsoft.com/downlo +# ad/0/A/9/0A939EF6-E31C-430F-A3DF-DFAE7960D564/htmlhelp.exe). # # The HTML Help Workshop contains a compiler that can convert all HTML output # generated by doxygen into a single compiled HTML file (.chm). Compiled HTML @@ -1387,7 +1464,7 @@ CHM_FILE = HHC_LOCATION = # The GENERATE_CHI flag controls if a separate .chi index file is generated -# (YES) or that it should be included in the master .chm file (NO). +# (YES) or that it should be included in the main .chm file (NO). # The default value is: NO. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. @@ -1432,7 +1509,8 @@ QCH_FILE = # The QHP_NAMESPACE tag specifies the namespace to use when generating Qt Help # Project output. For more information please see Qt Help Project / Namespace -# (see: https://doc.qt.io/archives/qt-4.8/qthelpproject.html#namespace). +# (see: +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#namespace). # The default value is: org.doxygen.Project. # This tag requires that the tag GENERATE_QHP is set to YES. @@ -1440,8 +1518,8 @@ QHP_NAMESPACE = org.doxygen.Project # The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating Qt # Help Project output. For more information please see Qt Help Project / Virtual -# Folders (see: https://doc.qt.io/archives/qt-4.8/qthelpproject.html#virtual- -# folders). +# Folders (see: +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#virtual-folders). # The default value is: doc. # This tag requires that the tag GENERATE_QHP is set to YES. @@ -1449,16 +1527,16 @@ QHP_VIRTUAL_FOLDER = doc # If the QHP_CUST_FILTER_NAME tag is set, it specifies the name of a custom # filter to add. For more information please see Qt Help Project / Custom -# Filters (see: https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom- -# filters). +# Filters (see: +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom-filters). # This tag requires that the tag GENERATE_QHP is set to YES. QHP_CUST_FILTER_NAME = # The QHP_CUST_FILTER_ATTRS tag specifies the list of the attributes of the # custom filter to add. For more information please see Qt Help Project / Custom -# Filters (see: https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom- -# filters). +# Filters (see: +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom-filters). # This tag requires that the tag GENERATE_QHP is set to YES. QHP_CUST_FILTER_ATTRS = @@ -1470,9 +1548,9 @@ QHP_CUST_FILTER_ATTRS = QHP_SECT_FILTER_ATTRS = -# The QHG_LOCATION tag can be used to specify the location of Qt's -# qhelpgenerator. If non-empty doxygen will try to run qhelpgenerator on the -# generated .qhp file. +# The QHG_LOCATION tag can be used to specify the location (absolute path +# including file name) of Qt's qhelpgenerator. If non-empty doxygen will try to +# run qhelpgenerator on the generated .qhp file. # This tag requires that the tag GENERATE_QHP is set to YES. QHG_LOCATION = @@ -1515,16 +1593,28 @@ DISABLE_INDEX = NO # to work a browser that supports JavaScript, DHTML, CSS and frames is required # (i.e. any modern browser). Windows users are probably better off using the # HTML help feature. Via custom style sheets (see HTML_EXTRA_STYLESHEET) one can -# further fine-tune the look of the index. As an example, the default style -# sheet generated by doxygen has an example that shows how to put an image at -# the root of the tree instead of the PROJECT_NAME. Since the tree basically has -# the same information as the tab index, you could consider setting -# DISABLE_INDEX to YES when enabling this option. +# further fine tune the look of the index (see "Fine-tuning the output"). As an +# example, the default style sheet generated by doxygen has an example that +# shows how to put an image at the root of the tree instead of the PROJECT_NAME. +# Since the tree basically has the same information as the tab index, you could +# consider setting DISABLE_INDEX to YES when enabling this option. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. GENERATE_TREEVIEW = YES +# When both GENERATE_TREEVIEW and DISABLE_INDEX are set to YES, then the +# FULL_SIDEBAR option determines if the side bar is limited to only the treeview +# area (value NO) or if it should extend to the full height of the window (value +# YES). Setting this to YES gives a layout similar to +# https://docs.readthedocs.io with more room for contents, but less room for the +# project logo, title, and description. If either GENERATOR_TREEVIEW or +# DISABLE_INDEX is set to NO, this option has no effect. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +FULL_SIDEBAR = NO + # The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that # doxygen will group on one line in the generated HTML documentation. # @@ -1553,8 +1643,8 @@ EXT_LINKS_IN_WINDOW = NO # tool (see https://github.com/dawbarton/pdf2svg) or inkscape (see # https://inkscape.org) to generate formulas as SVG images instead of PNGs for # the HTML output. These images will generally look nicer at scaled resolutions. -# Possible values are: png The default and svg Looks nicer but requires the -# pdf2svg tool. +# Possible values are: png (the default) and svg (looks nicer but requires the +# pdf2svg or inkscape tool). # The default value is: png. # This tag requires that the tag GENERATE_HTML is set to YES. @@ -1597,11 +1687,29 @@ FORMULA_MACROFILE = USE_MATHJAX = NO +# With MATHJAX_VERSION it is possible to specify the MathJax version to be used. +# Note that the different versions of MathJax have different requirements with +# regards to the different settings, so it is possible that also other MathJax +# settings have to be changed when switching between the different MathJax +# versions. +# Possible values are: MathJax_2 and MathJax_3. +# The default value is: MathJax_2. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_VERSION = MathJax_2 + # When MathJax is enabled you can set the default output format to be used for -# the MathJax output. See the MathJax site (see: -# http://docs.mathjax.org/en/latest/output.html) for more details. +# the MathJax output. For more details about the output format see MathJax +# version 2 (see: +# http://docs.mathjax.org/en/v2.7-latest/output.html) and MathJax version 3 +# (see: +# http://docs.mathjax.org/en/latest/web/components/output.html). # Possible values are: HTML-CSS (which is slower, but has the best -# compatibility), NativeMML (i.e. MathML) and SVG. +# compatibility. This is the name for Mathjax version 2, for MathJax version 3 +# this will be translated into chtml), NativeMML (i.e. MathML. Only supported +# for NathJax 2. For MathJax version 3 chtml will be used instead.), chtml (This +# is the name for Mathjax version 3, for MathJax version 2 this will be +# translated into HTML-CSS) and SVG. # The default value is: HTML-CSS. # This tag requires that the tag USE_MATHJAX is set to YES. @@ -1614,22 +1722,29 @@ MATHJAX_FORMAT = HTML-CSS # MATHJAX_RELPATH should be ../mathjax. The default value points to the MathJax # Content Delivery Network so you can quickly see the result without installing # MathJax. However, it is strongly recommended to install a local copy of -# MathJax from https://www.mathjax.org before deployment. -# The default value is: https://cdn.jsdelivr.net/npm/mathjax@2. +# MathJax from https://www.mathjax.org before deployment. The default value is: +# - in case of MathJax version 2: https://cdn.jsdelivr.net/npm/mathjax@2 +# - in case of MathJax version 3: https://cdn.jsdelivr.net/npm/mathjax@3 # This tag requires that the tag USE_MATHJAX is set to YES. MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest # The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax # extension names that should be enabled during MathJax rendering. For example +# for MathJax version 2 (see https://docs.mathjax.org/en/v2.7-latest/tex.html +# #tex-and-latex-extensions): # MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols +# For example for MathJax version 3 (see +# http://docs.mathjax.org/en/latest/input/tex/extensions/index.html): +# MATHJAX_EXTENSIONS = ams # This tag requires that the tag USE_MATHJAX is set to YES. MATHJAX_EXTENSIONS = # The MATHJAX_CODEFILE tag can be used to specify a file with javascript pieces # of code that will be used on startup of the MathJax code. See the MathJax site -# (see: http://docs.mathjax.org/en/latest/output.html) for more details. For an +# (see: +# http://docs.mathjax.org/en/v2.7-latest/output.html) for more details. For an # example see the documentation. # This tag requires that the tag USE_MATHJAX is set to YES. @@ -1676,7 +1791,8 @@ SERVER_BASED_SEARCH = NO # # Doxygen ships with an example indexer (doxyindexer) and search engine # (doxysearch.cgi) which are based on the open source search engine library -# Xapian (see: https://xapian.org/). +# Xapian (see: +# https://xapian.org/). # # See the section "External Indexing and Searching" for details. # The default value is: NO. @@ -1689,8 +1805,9 @@ EXTERNAL_SEARCH = NO # # Doxygen ships with an example indexer (doxyindexer) and search engine # (doxysearch.cgi) which are based on the open source search engine library -# Xapian (see: https://xapian.org/). See the section "External Indexing and -# Searching" for details. +# Xapian (see: +# https://xapian.org/). See the section "External Indexing and Searching" for +# details. # This tag requires that the tag SEARCHENGINE is set to YES. SEARCHENGINE_URL = @@ -1799,29 +1916,31 @@ PAPER_TYPE = letter EXTRA_PACKAGES = -# The LATEX_HEADER tag can be used to specify a personal LaTeX header for the -# generated LaTeX document. The header should contain everything until the first -# chapter. If it is left blank doxygen will generate a standard header. See -# section "Doxygen usage" for information on how to let doxygen write the -# default header to a separate file. +# The LATEX_HEADER tag can be used to specify a user-defined LaTeX header for +# the generated LaTeX document. The header should contain everything until the +# first chapter. If it is left blank doxygen will generate a standard header. It +# is highly recommended to start with a default header using +# doxygen -w latex new_header.tex new_footer.tex new_stylesheet.sty +# and then modify the file new_header.tex. See also section "Doxygen usage" for +# information on how to generate the default header that doxygen normally uses. # -# Note: Only use a user-defined header if you know what you are doing! The -# following commands have a special meaning inside the header: $title, -# $datetime, $date, $doxygenversion, $projectname, $projectnumber, -# $projectbrief, $projectlogo. Doxygen will replace $title with the empty -# string, for the replacement values of the other commands the user is referred -# to HTML_HEADER. +# Note: Only use a user-defined header if you know what you are doing! +# Note: The header is subject to change so you typically have to regenerate the +# default header when upgrading to a newer version of doxygen. The following +# commands have a special meaning inside the header (and footer): For a +# description of the possible markers and block names see the documentation. # This tag requires that the tag GENERATE_LATEX is set to YES. LATEX_HEADER = -# The LATEX_FOOTER tag can be used to specify a personal LaTeX footer for the -# generated LaTeX document. The footer should contain everything after the last -# chapter. If it is left blank doxygen will generate a standard footer. See +# The LATEX_FOOTER tag can be used to specify a user-defined LaTeX footer for +# the generated LaTeX document. The footer should contain everything after the +# last chapter. If it is left blank doxygen will generate a standard footer. See # LATEX_HEADER for more information on how to generate a default footer and what -# special commands can be used inside the footer. -# -# Note: Only use a user-defined footer if you know what you are doing! +# special commands can be used inside the footer. See also section "Doxygen +# usage" for information on how to generate the default footer that doxygen +# normally uses. Note: Only use a user-defined footer if you know what you are +# doing! # This tag requires that the tag GENERATE_LATEX is set to YES. LATEX_FOOTER = @@ -1854,9 +1973,11 @@ LATEX_EXTRA_FILES = PDF_HYPERLINKS = YES -# If the USE_PDFLATEX tag is set to YES, doxygen will use pdflatex to generate -# the PDF file directly from the LaTeX files. Set this option to YES, to get a -# higher quality PDF documentation. +# If the USE_PDFLATEX tag is set to YES, doxygen will use the engine as +# specified with LATEX_CMD_NAME to generate the PDF file directly from the LaTeX +# files. Set this option to YES, to get a higher quality PDF documentation. +# +# See also section LATEX_CMD_NAME for selecting the engine. # The default value is: YES. # This tag requires that the tag GENERATE_LATEX is set to YES. @@ -1864,8 +1985,7 @@ USE_PDFLATEX = YES # If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \batchmode # command to the generated LaTeX files. This will instruct LaTeX to keep running -# if errors occur, instead of asking the user for help. This option is also used -# when generating formulas in HTML. +# if errors occur, instead of asking the user for help. # The default value is: NO. # This tag requires that the tag GENERATE_LATEX is set to YES. @@ -1878,16 +1998,6 @@ LATEX_BATCHMODE = NO LATEX_HIDE_INDICES = NO -# If the LATEX_SOURCE_CODE tag is set to YES then doxygen will include source -# code with syntax highlighting in the LaTeX output. -# -# Note that which sources are shown also depends on other settings such as -# SOURCE_BROWSER. -# The default value is: NO. -# This tag requires that the tag GENERATE_LATEX is set to YES. - -LATEX_SOURCE_CODE = NO - # The LATEX_BIB_STYLE tag can be used to specify the style to use for the # bibliography, e.g. plainnat, or ieeetr. See # https://en.wikipedia.org/wiki/BibTeX and \cite for more info. @@ -1968,16 +2078,6 @@ RTF_STYLESHEET_FILE = RTF_EXTENSIONS_FILE = -# If the RTF_SOURCE_CODE tag is set to YES then doxygen will include source code -# with syntax highlighting in the RTF output. -# -# Note that which sources are shown also depends on other settings such as -# SOURCE_BROWSER. -# The default value is: NO. -# This tag requires that the tag GENERATE_RTF is set to YES. - -RTF_SOURCE_CODE = NO - #--------------------------------------------------------------------------- # Configuration options related to the man page output #--------------------------------------------------------------------------- @@ -2030,7 +2130,7 @@ MAN_LINKS = NO # captures the structure of the code including all documentation. # The default value is: NO. -GENERATE_XML = NO +GENERATE_XML = YES # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of @@ -2074,15 +2174,6 @@ GENERATE_DOCBOOK = NO DOCBOOK_OUTPUT = docbook -# If the DOCBOOK_PROGRAMLISTING tag is set to YES, doxygen will include the -# program listings (including syntax highlighting and cross-referencing -# information) to the DOCBOOK output. Note that enabling this will significantly -# increase the size of the DOCBOOK output. -# The default value is: NO. -# This tag requires that the tag GENERATE_DOCBOOK is set to YES. - -DOCBOOK_PROGRAMLISTING = NO - #--------------------------------------------------------------------------- # Configuration options for the AutoGen Definitions output #--------------------------------------------------------------------------- @@ -2172,7 +2263,7 @@ SEARCH_INCLUDES = YES # preprocessor. # This tag requires that the tag SEARCH_INCLUDES is set to YES. -INCLUDE_PATH = third_party/ +INCLUDE_PATH = @MATTER_BASE@/third_party/ # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard # patterns (like *.h and *.hpp) to filter out the header-files in the @@ -2375,10 +2466,32 @@ UML_LOOK = NO # but if the number exceeds 15, the total amount of fields shown is limited to # 10. # Minimum value: 0, maximum value: 100, default value: 10. -# This tag requires that the tag HAVE_DOT is set to YES. +# This tag requires that the tag UML_LOOK is set to YES. UML_LIMIT_NUM_FIELDS = 10 +# If the DOT_UML_DETAILS tag is set to NO, doxygen will show attributes and +# methods without types and arguments in the UML graphs. If the DOT_UML_DETAILS +# tag is set to YES, doxygen will add type and arguments for attributes and +# methods in the UML graphs. If the DOT_UML_DETAILS tag is set to NONE, doxygen +# will not generate fields with class member information in the UML graphs. The +# class diagrams will look similar to the default class diagrams but using UML +# notation for the relationships. +# Possible values are: NO, YES and NONE. +# The default value is: NO. +# This tag requires that the tag UML_LOOK is set to YES. + +DOT_UML_DETAILS = NO + +# The DOT_WRAP_THRESHOLD tag can be used to set the maximum number of characters +# to display on a single line. If the actual line length exceeds this threshold +# significantly it will wrapped across multiple lines. Some heuristics are apply +# to avoid ugly line breaks. +# Minimum value: 0, maximum value: 1000, default value: 17. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_WRAP_THRESHOLD = 17 + # If the TEMPLATE_RELATIONS tag is set to YES then the inheritance and # collaboration graphs will show the relations between templates and their # instances. @@ -2483,7 +2596,7 @@ DOT_PATH = # command). # This tag requires that the tag HAVE_DOT is set to YES. -DOTFILE_DIRS = docs/dots/ +DOTFILE_DIRS = # The MSCFILE_DIRS tag can be used to specify one or more directories that # contain msc files that are included in the documentation (see the \mscfile @@ -2568,9 +2681,11 @@ DOT_MULTI_TARGETS = YES GENERATE_LEGEND = YES -# If the DOT_CLEANUP tag is set to YES, doxygen will remove the intermediate dot +# If the DOT_CLEANUP tag is set to YES, doxygen will remove the intermediate # files that are used to generate the various graphs. +# +# Note: This setting is not only used for dot files but also for msc temporary +# files. # The default value is: YES. -# This tag requires that the tag HAVE_DOT is set to YES. DOT_CLEANUP = YES diff --git a/docs/namespaces.dox b/docs/namespaces.dox deleted file mode 100644 index 1cec128e4e2db4..00000000000000 --- a/docs/namespaces.dox +++ /dev/null @@ -1,37 +0,0 @@ -/* - * - * Copyright (c) 2020 Project CHIP Authors - * Copyright (c) 2013-2017 Nest Labs, Inc. - * All rights reserved. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -/* - * Description: - * This file documents all C++ namespaces used within the CHIP - * Core SDK that are not otherwise documented in an umbrella - * header encompassing that namespace. - * - */ - -/** - * @namespace chip - * - * @brief - * This namespace is the outermost namespace for all CHIP interfaces. - * - * This namespace includes interfaces within the CHIP Core SDK - * that cover the Core stack, the Common and vendor-specific - * profiles, and the support interfaces. - */ diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000000000..a7e08d297e18ca --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,4 @@ +Sphinx +sphinx-book-theme +myst-parser +breathe diff --git a/docs/style/README.md b/docs/style/README.md deleted file mode 100644 index 7fa304cd800577..00000000000000 --- a/docs/style/README.md +++ /dev/null @@ -1,8 +0,0 @@ -# Style - -When necessary to drive into more detail about styles about specific types of -files this is where CHIP collects them - -## Specific Types - -- [Makefiles](./STYLE_MAKEFILES.md) diff --git a/docs/style/index.md b/docs/style/index.md new file mode 100644 index 00000000000000..b049b8933517a2 --- /dev/null +++ b/docs/style/index.md @@ -0,0 +1,7 @@ +# Style Guides + +```{toctree} +:glob: + +* +``` \ No newline at end of file diff --git a/docs/STYLE_GUIDE.md b/docs/style/style_guide.md similarity index 79% rename from docs/STYLE_GUIDE.md rename to docs/style/style_guide.md index b5ff308297b611..de7f44d5fa9b28 100644 --- a/docs/STYLE_GUIDE.md +++ b/docs/style/style_guide.md @@ -1,9 +1,9 @@ -# Matter Documentation Style Guide +# CHIP Documentation Style Guide -Matter documentation lives here: +CHIP documentation lives here: - **GitHub** — All guides and tutorials across the complete - [Matter organization](https://github.com/project-chip). + [Project-CHIP organization](https://github.com/project-chip). See [CONTRIBUTING.md](https://github.com/project-chip/connectedhomeip/blob/master/CONTRIBUTING.md) @@ -12,7 +12,7 @@ for general information on contributing to this project. ## Location Place all documentation contributions in the appropriate location in the -[`/docs`](../docs) directory. Most contributions should go into the +`docs` directory. Most contributions should go into the `/docs/guides` subdirectory, which covers conceptual and usage content. Current documentation structure: @@ -22,13 +22,13 @@ Current documentation structure: | `/actions` | Custom GitHub actions | | `/docs/guides` | Conceptual or usage content that doesn't fit within a subdirectory, and high-level tutorials | | `/docs/guides/images` | All images included in guide content | -| `/docs/guides/profiles` | Content describing or illustrating use of Matter profiles | -| `/docs/guides/test` | Content related to testing Matter | -| `/docs/guides/tools` | Content describing or illustrating use of Matter tools | -| `/docs/guides/primer` | Matter Primer content | -| `/docs/presentations` | PDF presentations on Matter features | -| `/docs/specs` | PDFs of Matter specifications | -| `/images` | Top-level Matter images, such as logos | +| `/docs/guides/profiles` | Content describing or illustrating use of CHIP profiles | +| `/docs/guides/test` | Content related to testing CHIP | +| `/docs/guides/tools` | Content describing or illustrating use of CHIP tools | +| `/docs/guides/primer` | CHIP Primer content | +| `/docs/presentations` | PDF presentations on CHIP features | +| `/docs/specs` | PDFs of CHIP specifications | +| `/images` | Top-level CHIP images, such as logos | If you are unsure of the best location for your contribution, create an Issue and ask, or let us know in your Pull Request. @@ -43,12 +43,10 @@ For consistency, all document links should point to the content on GitHub. The text of a link should be descriptive, so it's clear what the link is for: -> For more information, see the [Matter Style Guide](./STYLE_GUIDE.md). - ## Markdown guidelines -Use standard Markdown when authoring Matter documentation. While HTML may be -used for more complex content such as tables, use Markdown as much as possible. +Use standard Markdown when authoring CHIP documentation. While HTML may be used +for more complex content such as tables, use Markdown as much as possible. > Note: Edit this file to see the Markdown behind the examples. @@ -75,7 +73,7 @@ $ git clone https://github.com/project-chip/connectedhomeip.git ### Terminal prompts -If you need to use a full terminal prompt with username and hostname, use the +If you need use a full terminal prompt with username and hostname, use the format of `root@{hostname}{special-characters}#`. For example, when logged into a Docker container, you might have a prompt like From 786fe755c6c83aaa55872e29f75955fd96337b83 Mon Sep 17 00:00:00 2001 From: Grzegorz Ferenc Date: Tue, 26 Apr 2022 16:29:28 +0200 Subject: [PATCH 02/14] doc: add example sections Added sections to Examples doc container page. Restructured Guides landing page. Signed-off-by: Grzegorz Ferenc --- docs/examples/index.md | 198 ++++++++++++++++++++++++++++++++++++++++- docs/guides/index.md | 3 + 2 files changed, 199 insertions(+), 2 deletions(-) diff --git a/docs/examples/index.md b/docs/examples/index.md index d09baaa1c2a996..a4d72c2677cb7b 100644 --- a/docs/examples/index.md +++ b/docs/examples/index.md @@ -1,7 +1,201 @@ # Examples +The Matter SDK provides examples of Matter devices for different development platforms. + +## All clusters example + +```{toctree} +:glob: +:maxdepth: 1 + +all-clusters-app/**/README +``` + +## Bridge example + +```{toctree} +:glob: +:maxdepth: 1 + +bridge-app/**/README +``` + +## CHEF example + +```{toctree} +:glob: +:maxdepth: 1 + +chef/**/README +``` + +## CHIP Tool example + +```{toctree} +:glob: +:maxdepth: 1 + +chip-tool/README +``` + +## CHIP Tool Darwin example + +```{toctree} +:glob: +:maxdepth: 1 + +chip-tool-darwin/README +``` + +## IPv6 Only example + +```{toctree} +:glob: +:maxdepth: 1 + +ipv6only-app/**/README +``` + +## Lighting example + +```{toctree} +:glob: +:maxdepth: 1 + +lighting-app/**/README +``` + +## Light switch example + +```{toctree} +:glob: +:maxdepth: 1 + +lighting-app/**/README +``` + +## Lock example + +```{toctree} +:glob: +:maxdepth: 1 + +lock-app/**/README +``` + +## Log source example + +```{toctree} +:glob: +:maxdepth: 1 + +log-source-app/**/README +``` + +## Minimal MDNS example + +```{toctree} +:glob: +:maxdepth: 1 + +minimal-mdns/README +``` + +## OTA Provider example + +```{toctree} +:glob: +:maxdepth: 1 + +ota-provider-app/**/README +``` + +## OTA Requestor example + +```{toctree} +:glob: +:maxdepth: 1 + +ota-requestor-app/**/README +``` + +## Persistent storage example + +```{toctree} +:glob: +:maxdepth: 1 + +persistent-storage/**/README +``` + +## Pigweed example + +```{toctree} +:glob: +:maxdepth: 1 + +pigweed-app/**/README +``` + +## Pump example + +```{toctree} +:glob: +:maxdepth: 1 + +pump-app/**/README +``` + +## Pump controller example + +```{toctree} +:glob: +:maxdepth: 1 + +pump-controller-app/**/README +``` + +## Shell example + +```{toctree} +:glob: +:maxdepth: 1 + +shell/**/README +``` + +## Temperature measurement example + +```{toctree} +:glob: +:maxdepth: 1 + +temperature-measurement-app/**/README +``` + +## TV example + +```{toctree} +:glob: +:maxdepth: 1 + +tv-app/**/README +``` + +## TV casting example + +```{toctree} +:glob: +:maxdepth: 1 + +tv-casting-app/**/README +``` + +## Window example + ```{toctree} :glob: +:maxdepth: 1 -**/README -``` \ No newline at end of file +window-app/**/README +``` diff --git a/docs/guides/index.md b/docs/guides/index.md index d446380beee25a..aeebfc4f4fa335 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -1,7 +1,10 @@ # Guides +Read the following guides for general information about Matter SDK configuration and features. + ```{toctree} :glob: +:maxdepth: 1 * ``` \ No newline at end of file From 2d81ec5b48684337b5a43144ee79d55c3c7da8e9 Mon Sep 17 00:00:00 2001 From: Grzegorz Ferenc Date: Tue, 26 Apr 2022 16:30:02 +0200 Subject: [PATCH 03/14] doc: fix MD headers in example readmies Fixed Markdown header levels to improve visibility for Examples container page. Signed-off-by: Grzegorz Ferenc --- docs/guides/mbedos_add_new_target.md | 14 +- docs/guides/mbedos_commissioning.md | 34 ++--- docs/guides/mbedos_platform_overview.md | 18 +-- docs/guides/ti_platform_overview.md | 6 +- docs/style/style_guide.md | 34 ++--- .../all-clusters-app/infineon/psoc6/README.md | 4 +- examples/all-clusters-app/mbed/README.md | 36 ++--- .../lighting-app/infineon/psoc6/README.md | 4 +- examples/lighting-app/mbed/README.md | 38 ++--- examples/lighting-app/python/README.md | 2 +- examples/lock-app/efr32/README.md | 2 +- examples/lock-app/mbed/README.md | 36 ++--- examples/minimal-mdns/README.md | 4 + examples/ota-requestor-app/mbed/README.md | 36 ++--- examples/ota-requestor-app/p6/README.md | 138 ++++++++++++++++++ examples/persistent-storage/efr32/README.md | 2 +- examples/pigweed-app/efr32/README.md | 2 +- examples/pigweed-app/mbed/README.md | 30 ++-- examples/shell/mbed/README.md | 26 ++-- examples/window-app/efr32/README.md | 2 +- 20 files changed, 305 insertions(+), 163 deletions(-) create mode 100644 examples/ota-requestor-app/p6/README.md diff --git a/docs/guides/mbedos_add_new_target.md b/docs/guides/mbedos_add_new_target.md index 07d34bb3705690..8ea7c35c7049d2 100644 --- a/docs/guides/mbedos_add_new_target.md +++ b/docs/guides/mbedos_add_new_target.md @@ -1,8 +1,8 @@ ![ARM Mbed-OS logo](https://raw.githubusercontent.com/ARMmbed/mbed-os/master/logo.png) -

Mbed-OS add new hardware target

+# Mbed-OS add new hardware target -# Overview +## Overview This document shows how to add the new Mbed OS hardware target to Matter project. @@ -23,7 +23,7 @@ remember about the following requirements: Additional target component requirements are different for each of example application. Check the **Device UI** paragraph in example description. -# Example Application +## Example Application The first step to add the new target to each of example application is to modify the `examples/example_name/mbed/mbed_app.json` file. It contains the common @@ -33,7 +33,7 @@ should add the necessary components and parameters for the target there. If the new target uses the external libraries, it will be required to link it in the CMakeLists.txt file. -# Building +## Building To add the new hardware target to the build system the `scripts/examples/mbed_example.sh` script should be modify. Extend @@ -56,7 +56,7 @@ Example: "default": "CY8CPROTO_062_4343W" } -# Flashing +## Flashing Mbed OS example application flashing process uses the [Open On-Chip Debugger](http://openocd.org/). The first step is to create the @@ -83,7 +83,7 @@ Example: "default": "CY8CPROTO_062_4343W" } -# Debugging +## Debugging Debugging process of Mbed OS applications is also based on VSCode launch task. Adding the new target to it required `.vscode/launch.json` modification. Extend @@ -99,7 +99,7 @@ Example: "default": "CY8CPROTO_062_4343W" } -# CI +## CI The Matter project continue integration process is based on Github Actions tool. It uses workflow configuration files to execute actions on CI server. diff --git a/docs/guides/mbedos_commissioning.md b/docs/guides/mbedos_commissioning.md index 1e80d2552a089e..e4b5b6e11a0b06 100644 --- a/docs/guides/mbedos_commissioning.md +++ b/docs/guides/mbedos_commissioning.md @@ -1,6 +1,6 @@ ![ARM Mbed-OS logo](https://raw.githubusercontent.com/ARMmbed/mbed-os/master/logo.png) -

Matter Arm Mbed OS provisioning guide

+# Matter Arm Mbed OS provisioning guide - [Overview](#overview) - [Prerequisites](#prerequisites) @@ -21,7 +21,7 @@
-# Overview +## Overview This document provides a step-by-step guide how to commission any Matter application. For demonstration purposes the Lighting app is used. @@ -37,7 +37,7 @@ The provisioning process is composed of the following stages: BLE is only used during first phase. Afterwards, only the IP connectivity between the smartphone and the accessory device is needed to send messages. -# Prerequisites +## Prerequisites To complete all the steps in the tutorial, you need: @@ -50,9 +50,9 @@ To complete all the steps in the tutorial, you need: - Any currently supported target device (for example, a Cypress PSoC6 CY8CPROTO-062-4343W board) -# CHIPTool for Android +## CHIPTool for Android -## Building and installing +### Building and installing To make provisioning possible and to control the Matter device from your Android based smartphone, you must first build and install the CHIPTool application. @@ -85,7 +85,7 @@ After building, install the application by completing the following steps: Android CHIPTool is now ready to be used for commissioning. -## Accessory Matter device setup +### Accessory Matter device setup To prepare the accessory Matter device for commissioning (called rendezvous), complete the following steps: @@ -113,7 +113,7 @@ to the UART console. - Open URL from the console to display the QR in a web browser. -## Device commissioning for Android +### Device commissioning for Android To commission Matter device onto the network created complete the following steps: @@ -137,7 +137,7 @@ steps: - After successful completion of the process, the application returns to the main screen. -## Sending ZCL commands +### Sending ZCL commands After the accessory device has been successfully commissioned to the network, it is possible to communicate with it using IP. Matter uses Zigbee Cluster Library @@ -156,9 +156,9 @@ If **Lighting LED** is available then brightness change can be observed. > For more details about Android CHIPTool please visit > [CHIPTool](../../src/android/CHIPTool/README.md) -# POSIX CLI CHIPTool +## POSIX CLI CHIPTool -## Building +### Building To make provisioning possible and to control the Matter device from Linux-based device, you can build and run the Matter Client example application on it. @@ -166,7 +166,7 @@ device, you can build and run the Matter Client example application on it. To build the POSIX CLI CHIPTool application check the guide [POSIX CLI guide](../../examples/chip-tool/README.md). -## Device commissioning for CLI +### Device commissioning for CLI In order to send commands to a device, it must be paired with the client and connected to the network. @@ -179,7 +179,7 @@ Example: $ chip-tool pairing ble-wifi node_id_to_assign network_ssid network_password 20202021 3840 -## Sending ZCL commands +### Sending ZCL commands If the commissioning process was successful, it is possible to send a ZCL command to the device which initiate a certain action. @@ -198,9 +198,9 @@ The client will send a single command packet and then exit. > For more details about POSIX CLI CHIPTool please visit > [POSIX CLI CHIPTool](../../examples/chip-tool/README.md) -# Python Device Controller +## Python Device Controller -## Building and installing +### Building and installing To make provisioning possible and to control the Matter device with Python application, you can build and run the Python CHIP controller. @@ -208,7 +208,7 @@ application, you can build and run the Python CHIP controller. To build and install the Python Device Controller application check the guide [Python Device Controller guide](python_chip_controller_building.md). -## Device commissioning for Python Device Controller +### Device commissioning for Python Device Controller In order to send commands to a device, it must be paired with the client and connected to the network. @@ -232,7 +232,7 @@ To run the auto commissioning process via BLE: chip-device-ctrl > connect -ble 3840 20202021 1234 -## Sending ZCL commands +### Sending ZCL commands If the commissioning process was successful, it is possible to send a ZCL command to the device which initiates a certain action. @@ -243,7 +243,7 @@ Example: chip-device-ctrl > zcl LevelControl MoveWithOnOff 12344321 1 0 moveMode=1 rate=2 -### ZCL commands details +#### ZCL commands details To get the list of supported clusters run: diff --git a/docs/guides/mbedos_platform_overview.md b/docs/guides/mbedos_platform_overview.md index 95a1a3ee67f0c7..7d406b63b94f1c 100644 --- a/docs/guides/mbedos_platform_overview.md +++ b/docs/guides/mbedos_platform_overview.md @@ -11,7 +11,7 @@ runs on the top of the Mbed-OS. ![matter_mbedos_overview_simplified](images/matter_mbedos_overview_simplified.png) -# ARM Mbed-OS +## ARM Mbed-OS Arm Mbed OS is an open source embedded operating system designed specifically for the "things" in the Internet of Things. It includes all the features you @@ -47,7 +47,7 @@ Finally, Mbed OS implements the retargeting layer and boot process integration of each supported toolchain, so application development feels similar to C or C++ development for any other operating system. -# Bluetooth and IP stacks +## Bluetooth and IP stacks In the Mbed-oS platform applications, the Bluetooth LE interface is used to perform pairing and Wi-Fi network provisioning operations between the Matter @@ -70,7 +70,7 @@ network layer, special glue socket layer has been introduced to take care of adapting the Mbed socket to BSD interface which is used inside the Matter endpoints implementation. -## Matter integration +### Matter integration The Bluetooth LE and Wi-Fi used stacks provided by the Mbed-OS have been integrated with the Matter stack using a special intermediate layer. @@ -80,7 +80,7 @@ interfaces defined in the Matter stack. The application is able to use Matter's platform agnostic interfaces and no additional platform-related actions are needed to perform communication through the Matter stack. -# Matter example applications +## Matter example applications Sample Matter applications are provided for the Mbed OS platform. They can be used to speed up development: @@ -91,19 +91,19 @@ used to speed up development: - [lighting-app](../../examples/lighting-app/mbed/README.md) - [pigweed-app](../../examples/pigweed-app/mbed/README.md) -## Example configuration +### Example configuration Each of the supporting examples contains the `config.in` file which allows you to configure the application in a proper way. You can define/disable/enable application settings. Then they are propagated through Mbed-OS and Matter stack build systems. -## Matter stack configuration +### Matter stack configuration In each of supported examples, the Matter stack can be configured by modifying `CHIPProjectConfig.h` file which is placed inside the project directory. -## Mbed-OS configuration +### Mbed-OS configuration Mbed-OS gives possibility to tweak its parameters by using the [Mbed-OS configuration system](https://os.mbed.com/docs/mbed-os/latest/program-setup/advanced-configuration.html). @@ -113,7 +113,7 @@ support of the new hardware target support into the application. Mbed-OS configuration system can be accessed by modifying the `mbed_app.json` file which exists in each sample project directory. -## Build system +### Build system The Mbed-OS platform makes use of the following build systems to generate ninja build scripts: @@ -126,7 +126,7 @@ Matter's stack and platform modules are built with GN and output a library file. The application, Mbed-OS and target specific libraries are built with CMake and the Matter library file is imported during the compilation process. -## Build profiles +### Build profiles Arm Mbed OS defines three collections of toolchain flags used during the build: diff --git a/docs/guides/ti_platform_overview.md b/docs/guides/ti_platform_overview.md index 50d96f361963ee..cc0a05280cbc22 100644 --- a/docs/guides/ti_platform_overview.md +++ b/docs/guides/ti_platform_overview.md @@ -91,7 +91,7 @@ handled by the platform implementation files.
-# Matter example applications +## Matter example applications Sample Matter applications are provided for the TI platform. These can be used as reference for your own application. @@ -102,7 +102,7 @@ as reference for your own application.
-## Build system +### Build system The TI platform uses GN to generate ninja build scripts. Build files have already been written to build and link the TI specific code within the @@ -110,7 +110,7 @@ SimpleLink SDK.
-## TI Support +### TI Support For technical support, please consider creating a post on TI's [E2E forum][e2e]. Additionally, we welcome any feedback. diff --git a/docs/style/style_guide.md b/docs/style/style_guide.md index de7f44d5fa9b28..860717d6b2e213 100644 --- a/docs/style/style_guide.md +++ b/docs/style/style_guide.md @@ -1,9 +1,9 @@ -# CHIP Documentation Style Guide +# Matter Documentation Style Guide -CHIP documentation lives here: +Matter documentation lives here: - **GitHub** — All guides and tutorials across the complete - [Project-CHIP organization](https://github.com/project-chip). + [Matter organization](https://github.com/project-chip). See [CONTRIBUTING.md](https://github.com/project-chip/connectedhomeip/blob/master/CONTRIBUTING.md) @@ -17,18 +17,18 @@ Place all documentation contributions in the appropriate location in the Current documentation structure: -| Directory | Description | -| ----------------------- | -------------------------------------------------------------------------------------------- | -| `/actions` | Custom GitHub actions | -| `/docs/guides` | Conceptual or usage content that doesn't fit within a subdirectory, and high-level tutorials | -| `/docs/guides/images` | All images included in guide content | -| `/docs/guides/profiles` | Content describing or illustrating use of CHIP profiles | -| `/docs/guides/test` | Content related to testing CHIP | -| `/docs/guides/tools` | Content describing or illustrating use of CHIP tools | -| `/docs/guides/primer` | CHIP Primer content | -| `/docs/presentations` | PDF presentations on CHIP features | -| `/docs/specs` | PDFs of CHIP specifications | -| `/images` | Top-level CHIP images, such as logos | +| Directory | Description | +| ----------------------- | ---------------------------------------------------------------------------------------------- | +| `/actions` | Custom GitHub actions | +| `/docs/guides` | Conceptual or usage content that doesn't fit within a subdirectory, and high-level tutorials | +| `/docs/guides/images` | All images included in guide content | +| `/docs/guides/profiles` | Content describing or illustrating use of Matter profiles | +| `/docs/guides/test` | Content related to testing Matter | +| `/docs/guides/tools` | Content describing or illustrating use of Matter tools | +| `/docs/guides/primer` | Matter Primer content | +| `/docs/presentations` | PDF presentations on Matter features | +| `/docs/specs` | PDFs of Matter specifications | +| `/images` | Top-level Matter images, such as logos | If you are unsure of the best location for your contribution, create an Issue and ask, or let us know in your Pull Request. @@ -45,7 +45,7 @@ The text of a link should be descriptive, so it's clear what the link is for: ## Markdown guidelines -Use standard Markdown when authoring CHIP documentation. While HTML may be used +Use standard Markdown when authoring Matter documentation. While HTML may be used for more complex content such as tables, use Markdown as much as possible. > Note: Edit this file to see the Markdown behind the examples. @@ -73,7 +73,7 @@ $ git clone https://github.com/project-chip/connectedhomeip.git ### Terminal prompts -If you need use a full terminal prompt with username and hostname, use the +If you need to use a full terminal prompt with username and hostname, use the format of `root@{hostname}{special-characters}#`. For example, when logged into a Docker container, you might have a prompt like diff --git a/examples/all-clusters-app/infineon/psoc6/README.md b/examples/all-clusters-app/infineon/psoc6/README.md index c28c43d9c3f248..8fed8d3ca41148 100644 --- a/examples/all-clusters-app/infineon/psoc6/README.md +++ b/examples/all-clusters-app/infineon/psoc6/README.md @@ -1,10 +1,10 @@ -#CHIP PSoC6 All Clusters Example +# CHIP P6 All Clusters Example An example showing the use of Matter on the Infineon CY8CKIT-062S2-43012 board.
-- [Matter PSoC6 All Clusters Example](#chip-psoc6-clusters-example) +- [Matter PSoC6 All Clusters Example](#chip-p6-all-clusters-example) - [Introduction](#introduction) - [Building](#building) - [Flashing the Application](#flashing-the-application) diff --git a/examples/all-clusters-app/mbed/README.md b/examples/all-clusters-app/mbed/README.md index a08a96a9af6433..5ee74dd6ec4eaa 100644 --- a/examples/all-clusters-app/mbed/README.md +++ b/examples/all-clusters-app/mbed/README.md @@ -1,6 +1,6 @@ ![ARM Mbed-OS logo](https://raw.githubusercontent.com/ARMmbed/mbed-os/master/logo.png) -

Matter Arm Mbed OS All Clusters Example Application

+# Matter Arm Mbed OS All Clusters Example Application The Arm Mbed OS All Clusters Example demonstrates device commissioning process and all available clusters control. @@ -35,7 +35,7 @@ paired into an existing Matter network and can be controlled by this network.
-# Overview +## Overview The Matter device that runs the All Clusters application is controlled by the Matter controller device over WiFi. By default, the Matter device is @@ -43,12 +43,12 @@ disconnected, and it should be paired with Matter controller and get configuration from it. Actions required before establishing full communication are described below. -## Bluetooth Low Energy advertising +### Bluetooth Low Energy advertising To commission the device onto a Matter network, the device must be discoverable over BLE. The BLE advertising starts automatically after device boot-up. -## Bluetooth Low Energy rendezvous +### Bluetooth Low Energy rendezvous In Matter, the commissioning procedure (called rendezvous) is done over BLE between a Matter device and the Matter controller, where the controller has the @@ -58,16 +58,16 @@ To start the rendezvous, the controller must get the commissioning information from the Matter device. The data payload is encoded within a QR code, printed to the UART console. -## WiFi provisioning +### WiFi provisioning The last part of the rendezvous procedure, provisioning involves sending the network credentials from the Matter controller to the Matter device. As a result, device is able to join the network and communicate with other devices in the network. -# Run application +## Run application -## Environment setup +### Environment setup Before building the example, check out the Matter repository and sync submodules using the following command: @@ -113,7 +113,7 @@ environment: $ source ./scripts/activate.sh ``` -## Building +### Building The All Clusters application can be built in the same way as any other Matter example ported to the mbed-os platform. @@ -150,7 +150,7 @@ There are also three types of built application: _simple, boot_ and _upgrade_: When using the building script, it is possible expand the list of acceptable targets; this may be useful for rapid testing of a new mbed-targets. -## Flashing +### Flashing The All Clusters application can be flashed in the same way as any other Matter example ported to mbed-os platform. @@ -183,7 +183,7 @@ device. It is possible to connect to an external gdb-server session by using a specific **'Flash Mbed examples [remote]'** task. -## Debugging +### Debugging Debugging can be performed in the same was as with any other Matter example ported to mbed-os platform. @@ -199,9 +199,9 @@ Run and Debug (Ctrl+Shift+D) => Debug Mbed examples => Start Debugging (F5) => ( It is possible to connect to an external gdb-server session by using specific **'Debug Mbed examples [remote]'** task. -## Testing +### Testing -### Serial port terminal +#### Serial port terminal The application traces are streaming to serial output. To start communication open a terminal session and connect to the serial port of the device. You can @@ -223,30 +223,30 @@ After device reset these lines should be visible: The all-clusters-app application launched correctly and you can follow traces in the terminal. -### CHIP Tools +#### CHIP Tools Read the [MbedCommissioning](../../../docs/guides/mbedos_commissioning.md) to see how to use different CHIP tools to commission and control the application within a WiFi network. -## Supported devices +### Supported devices | Manufacturer | Hardware platform | Build target | Platform image | Status | Platform components | | ----------------------------------------------------- | ------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------ | :----------------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Cypress
Semiconductor](https://www.cypress.com/) | [CY8CPROTO-062-4343W](https://os.mbed.com/platforms/CY8CPROTO-062-4343W/) | `CY8CPROTO_062_4343W` | ![CY8CPROTO-062-4343W](https://os.mbed.com/media/cache/platforms/p6_wifi-bt_proto.png.250x250_q85.jpg) | :heavy_check_mark: |
LEDs
  • Board has only one usable LED (LED4) which corresponds to USER LED from UI.
Buttons
  • Unused
Slider
  • Unused
| -#### Notes +##### Notes - More details and guidelines about porting new hardware into the Matter project with Mbed OS can be found in [MbedNewTarget](../../../docs/guides/mbedos_add_new_target.md) - Some useful information about HW platform specific settings can be found in - `all-clusters-app/mbed/mbed_app.json`. + `all-clusters-app/mbed/mbed_app.json`. Information about this file syntax and its meaning in mbed-os project can be found here: [Mbed-Os configuration system](https://os.mbed.com/docs/mbed-os/latest/program-setup/advanced-configuration.html)) -# Device UI +## Device UI This section lists the User Interface elements that you can use to control and monitor the state of the device. These correspond to PCB components on the @@ -269,7 +269,7 @@ following states are possible: - _Solid On_ — The device is fully provisioned and has full network and service connectivity. -### Notes +#### Notes Some of the supported boards may not have sufficient number PCB components to follow above description. In that case please refer to diff --git a/examples/lighting-app/infineon/psoc6/README.md b/examples/lighting-app/infineon/psoc6/README.md index ea229f0f391029..c1da22ff7e7819 100644 --- a/examples/lighting-app/infineon/psoc6/README.md +++ b/examples/lighting-app/infineon/psoc6/README.md @@ -1,10 +1,10 @@ -#CHIP PSoC6 Lighting Example +# CHIP P6 Lighting Example An example showing the use of Matter on the Infineon CY8CKIT-062S2-43012 board.
-- [Matter PSoC6 Lighting Example](#chip-psoc6-Lighting-example) +- [Matter PSoC6 Lighting Example](#chip-p6-lighting-example) - [Introduction](#introduction) - [Building](#building) - [Flashing the Application](#flashing-the-application) diff --git a/examples/lighting-app/mbed/README.md b/examples/lighting-app/mbed/README.md index 02a41c085e68d9..ac436be68f4ced 100644 --- a/examples/lighting-app/mbed/README.md +++ b/examples/lighting-app/mbed/README.md @@ -1,6 +1,6 @@ ![ARM Mbed-OS logo](https://raw.githubusercontent.com/ARMmbed/mbed-os/master/logo.png) -

Matter Arm Mbed OS Lighting Example Application

+# Matter Arm Mbed OS Lighting Example Application The Arm Mbed OS Lighting Example demonstrates how to remotely control a dimmable white light source. The example takes advantage of the IO available on board: @@ -49,19 +49,19 @@ serial port to the device. The following RPC protocols services are available:
-# Overview +## Overview The Matter device that runs the lighting application is controlled by the Matter controller device over WiFi. By default, the Matter device is disconnected , and it should be paired with Matter controller and get configuration from it. Actions required before establishing full communication are described below. -## Bluetooth Low Energy advertising +### Bluetooth Low Energy advertising To commission the device onto a Matter network, the device must be discoverable over BLE. The BLE advertising starts automatically after device boot-up. -## Bluetooth Low Energy rendezvous +### Bluetooth Low Energy rendezvous In Matter, the commissioning procedure (called rendezvous) is done over BLE between a Matter device and the Matter controller, where the controller has the @@ -71,16 +71,16 @@ To start the rendezvous, the controller must get the commissioning information from the Matter device. The data payload is encoded within a QR code, printed to the UART console. -## WiFi provisioning +### WiFi provisioning The last part of the rendezvous procedure, provisioning involves sending the network credentials from the Matter controller to the Matter device. As a result, device is able to join the network and communicate with other devices in the network. -# Run application +## Run application -## Environment setup +### Environment setup Before building the example, check out the Matter repository and sync submodules using the following command: @@ -128,7 +128,7 @@ environment: $ source ./scripts/activate.sh ``` -## Building +### Building The Lighting application can be built in the same way as any other Matter example ported to the mbed-os platform. @@ -165,7 +165,7 @@ There are also three types of built application: _simple, boot_ and _upgrade_: When using the building script, it is possible expand the list of acceptable targets; this may be useful for rapid testing of a new mbed-targets. -## Flashing +### Flashing The Lighting application can be flashed in the same way as any other Matter example ported to mbed-os platform. @@ -198,7 +198,7 @@ device. It is possible to connect to an external gdb-server session by using specific **'Flash Mbed examples [remote]'** task. -## Debugging +### Debugging Debugging can be performed in the same was as with any other Matter example ported to mbed-os platform. @@ -214,9 +214,9 @@ Run and Debug (Ctrl+Shift+D) => Debug Mbed examples => Start Debugging (F5) => ( It is possible to connect to an external gdb-server session by using specific **'Debug Mbed examples [remote]'** task. -## Testing +### Testing -### Serial port terminal +#### Serial port terminal The application traces are streaming to serial output. To start communication open a terminal session and connect to the serial port of the device. You can @@ -238,13 +238,13 @@ After device reset these lines should be visible: The lighting-app application launched correctly and you can follow traces in the terminal. -### CHIP Tools +#### CHIP Tools Read the [MbedCommissioning](../../../docs/guides/mbedos_commissioning.md) to see how to use different CHIP tools to commission and control the application within a WiFi network. -### RPC console +#### RPC console The RPC console is an interactive Python shell console, where the different RPC command can be invoked. It is a complete solution for interacting with hardware @@ -302,7 +302,7 @@ The response from the device should contain the current lighting state: For more details about RPC console and supported services visit [CHIP RPC console](../../common/pigweed/rpc_console/README.md). -## Supported devices +### Supported devices The example supports building and running on the following mbed-enabled devices: @@ -310,18 +310,18 @@ The example supports building and running on the following mbed-enabled devices: | ----------------------------------------------------- | ------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Cypress
Semiconductor](https://www.cypress.com/) | [CY8CPROTO-062-4343W](https://os.mbed.com/platforms/CY8CPROTO-062-4343W/) | `CY8CPROTO_062_4343W` |
CY8CPROTO-062-4343WCY8CPROTO-062-4343W
| :heavy_check_mark: |
LEDs
  • Board has only one usable LED (LED4) which corresponds to USER LED from UI.
  • Lighting LED should be an external component connected to PB9_6 pin (active high).
Buttons
  • SW2 push-button is not used in this example due to its interaction with WIFI module interrupt line.
  • Button 0 corresponds to BTN0 capacitive button.
  • Button 1 corresponds to BTN1 capacitive button.
Slider
  • The board's touch slider corresponds to UI slider
| -#### Notes +##### Notes - More details and guidelines about porting new hardware into the Matter project with Mbed OS can be found in [MbedNewTarget](../../../docs/guides/mbedos_add_new_target.md) - Some useful information about HW platform specific settings can be found in - `lighting-app/mbed/mbed_app.json`. + `lighting-app/mbed/mbed_app.json`. Information about this file syntax and its meaning in mbed-os project can be found here: [Mbed-Os configuration system](https://os.mbed.com/docs/mbed-os/latest/program-setup/advanced-configuration.html)) -# Device UI +## Device UI This section lists the User Interface elements that you can use to control and monitor the state of the device. These correspond to PCB components on the @@ -371,7 +371,7 @@ dimming lighting state from the OFF state to maximum brightness corresponding to ON state. Currently the dimming resolution is set from 0-255 to satisfy ZCL 8 bit commands argument for lighting cluster. -### Notes +#### Notes Some of the supported boards may not have sufficient number PCB components to follow above description. In that case please refer to diff --git a/examples/lighting-app/python/README.md b/examples/lighting-app/python/README.md index 69487bb3b74899..8e34e59dea5847 100644 --- a/examples/lighting-app/python/README.md +++ b/examples/lighting-app/python/README.md @@ -1,4 +1,4 @@ -# Python based lighting example (bridge) device to DALI. +# Python-based lighting example (bridge) device to DALI ## Installation diff --git a/examples/lock-app/efr32/README.md b/examples/lock-app/efr32/README.md index 00dda0f6829c02..04bb8d9419130b 100644 --- a/examples/lock-app/efr32/README.md +++ b/examples/lock-app/efr32/README.md @@ -1,4 +1,4 @@ -#CHIP EFR32 Lock Example +# CHIP EFR32 Lock Example An example showing the use of CHIP on the Silicon Labs EFR32 MG12. diff --git a/examples/lock-app/mbed/README.md b/examples/lock-app/mbed/README.md index cc48cebeb68ae9..96564967fa1c49 100644 --- a/examples/lock-app/mbed/README.md +++ b/examples/lock-app/mbed/README.md @@ -1,6 +1,6 @@ ![ARM Mbed-OS logo](https://raw.githubusercontent.com/ARMmbed/mbed-os/master/logo.png) -

Matter Arm Mbed OS Lock Example Application

+# Matter Arm Mbed OS Lock Example Application The Arm Mbed OS Lock Example demonstrates how to remotely control a door lock device with one basic bolt. The example takes advantage of the IO available on @@ -39,19 +39,19 @@ paired into an existing Matter network and can be controlled by this network.
-# Overview +## Overview The Matter device that runs the lock application is controlled by the Matter controller device over WiFi. By default, the Matter device is disconnected , and it should be paired with Matter controller and get configuration from it. Actions required before establishing full communication are described below. -## Bluetooth Low Energy advertising +### Bluetooth Low Energy advertising To commission the device onto a Matter network, the device must be discoverable over BLE. The BLE advertising starts automatically after device boot-up. -## Bluetooth Low Energy rendezvous +### Bluetooth Low Energy rendezvous In Matter, the commissioning procedure (called rendezvous) is done over BLE between a Matter device and the Matter controller, where the controller has the @@ -61,16 +61,16 @@ To start the rendezvous, the controller must get the commissioning information from the Matter device. The data payload is encoded within a QR code, printed to the UART console. -## WiFi provisioning +### WiFi provisioning The last part of the rendezvous procedure, provisioning involves sending the network credentials from the Matter controller to the Matter device. As a result, device is able to join the network and communicate with other devices in the network. -# Run application +## Run application -## Environment setup +### Environment setup Before building the example, check out the Matter repository and sync submodules using the following command: @@ -116,7 +116,7 @@ environment: $ source ./scripts/activate.sh ``` -## Building +### Building The Lock application can be built in the same way as any other Matter example ported to the mbed-os platform. @@ -153,7 +153,7 @@ There are also three types of built application: _simple, boot_ and _upgrade_: When using the building script, it is possible expand the list of acceptable targets; this may be useful for rapid testing of a new mbed-targets. -## Flashing +### Flashing The Lock application can be flashed in the same way as any other Matter example ported to mbed-os platform. @@ -186,7 +186,7 @@ device. It is possible to connect to an external gdb-server session by using specific **'Flash Mbed examples [remote]'** task. -## Debugging +### Debugging Debugging can be performed in the same was as with any other Matter example ported to mbed-os platform. @@ -202,9 +202,9 @@ Run and Debug (Ctrl+Shift+D) => Debug Mbed examples => Start Debugging (F5) => ( It is possible to connect to an external gdb-server session by using specific **'Debug Mbed examples [remote]'** task. -## Testing +### Testing -### Serial port terminal +#### Serial port terminal The application traces are streaming to serial output. To start communication open a terminal session and connect to the serial port of the device. You can @@ -222,13 +222,13 @@ After device reset these lines should be visible: The lock-app application launched correctly and you can follow traces in the terminal. -### CHIP Tools +#### CHIP Tools Read the [MbedCommissioning](../../../docs/guides/mbedos_commissioning.md) to see how to use different CHIP tools to commission and control the application within a WiFi network. -### RPC console +#### RPC console The RPC console is an interactive Python shell console, where the different RPC command can be invoked. It is a complete solution for interacting with hardware @@ -276,7 +276,7 @@ The response from the device should contain the current lock state: For more details about RPC console and supported services visit [CHIP RPC console](../../common/pigweed/rpc_console/README.md). -## Supported devices +### Supported devices The example supports building and running on the following mbed-enabled devices: @@ -284,18 +284,18 @@ The example supports building and running on the following mbed-enabled devices: | ----------------------------------------------------- | ------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Cypress
Semiconductor](https://www.cypress.com/) | [CY8CPROTO-062-4343W](https://os.mbed.com/platforms/CY8CPROTO-062-4343W/) | `CY8CPROTO_062_4343W` |
CY8CPROTO-062-4343WCY8CPROTO-062-4343W
| :heavy_check_mark: |
LEDs
  • Board has only one usable LED (LED4) which corresponds to USER LED from UI.
  • Lock state LED should be an external component connected to PB9_6 pin (active high).
Buttons
  • SW2 push-button is not used in this example due to its interaction with WIFI module interrupt line.
  • Button 0 corresponds to BTN0 capacitive button.
  • Button 1 corresponds to BTN1 capacitive button.
Slider
  • Unused
| -#### Notes +##### Notes - More details and guidelines about porting new hardware into the Matter project with Mbed OS can be found in [MbedNewTarget](../../../docs/guides/mbedos_add_new_target.md) - Some useful information about HW platform specific settings can be found in - `lock-app/mbed/mbed_app.json`. + `lock-app/mbed/mbed_app.json`. Information about this file syntax and its meaning in mbed-os project can be found here: [Mbed-Os configuration system](https://os.mbed.com/docs/mbed-os/latest/program-setup/advanced-configuration.html)) -## Device UI +### Device UI This section lists the User Interface elements that you can use to control and monitor the state of the device. These correspond to PCB components on the diff --git a/examples/minimal-mdns/README.md b/examples/minimal-mdns/README.md index 8e781f852424ff..2099213c46a6a2 100644 --- a/examples/minimal-mdns/README.md +++ b/examples/minimal-mdns/README.md @@ -1,3 +1,7 @@ +# Minimal mDNS example + +This example demonstrates the multicast DNS (mDNS) protocol functionality in Matter. + ## Example server The file `server.cpp` contains an example of a mdns server that can listen on diff --git a/examples/ota-requestor-app/mbed/README.md b/examples/ota-requestor-app/mbed/README.md index 6e6fd542808811..a2a3fbafddaf78 100644 --- a/examples/ota-requestor-app/mbed/README.md +++ b/examples/ota-requestor-app/mbed/README.md @@ -1,6 +1,6 @@ ![ARM Mbed-OS logo](https://raw.githubusercontent.com/ARMmbed/mbed-os/master/logo.png) -

Matter Arm Mbed OS Lock Example Application

+# Matter Arm Mbed OS Lock Example Application The Arm Mbed OS OTA Requestor Example demonstrates how to remotely trigger update image downloading and apply it if needed. Full functionality of this @@ -41,19 +41,19 @@ paired into an existing Matter network and can be controlled by this network.
-# Overview +## Overview The Matter device that runs the lock application is controlled by the Matter controller device over WiFi. By default, the Matter device is disconnected , and it should be paired with Matter controller and get configuration from it. Actions required before establishing full communication are described below. -## Bluetooth Low Energy advertising +### Bluetooth Low Energy advertising To commission the device onto a Matter network, the device must be discoverable over BLE. The BLE advertising starts automatically after device boot-up. -## Bluetooth Low Energy rendezvous +### Bluetooth Low Energy rendezvous In Matter, the commissioning procedure (called rendezvous) is done over BLE between a Matter device and the Matter controller, where the controller has the @@ -63,16 +63,16 @@ To start the rendezvous, the controller must get the commissioning information from the Matter device. The data payload is encoded within a QR code, printed to the UART console. -## WiFi provisioning +### WiFi provisioning The last part of the rendezvous procedure, provisioning involves sending the network credentials from the Matter controller to the Matter device. As a result, device is able to join the network and communicate with other devices in the network. -# Run application +## Run application -## Environment setup +### Environment setup Before building the example, check out the Matter repository and sync submodules using the following command: @@ -118,7 +118,7 @@ environment: $ source ./scripts/activate.sh ``` -## Building +### Building The OTA Requestor application can be built in the same way as any other Matter example ported to the mbed-os platform. @@ -155,7 +155,7 @@ There are also three types of built application: _simple, boot_ and _upgrade_: When using the building script, it is possible expand the list of acceptable targets; this may be useful for rapid testing of a new mbed-targets. -## Flashing +### Flashing The Lock application can be flashed in the same way as any other Matter example ported to mbed-os platform. @@ -188,7 +188,7 @@ device. It is possible to connect to an external gdb-server session by using specific **'Flash Mbed examples [remote]'** task. -## Debugging +### Debugging Debugging can be performed in the same was as with any other Matter example ported to mbed-os platform. @@ -204,14 +204,14 @@ Run and Debug (Ctrl+Shift+D) => Debug Mbed examples => Start Debugging (F5) => ( It is possible to connect to an external gdb-server session by using specific **'Debug Mbed examples [remote]'** task. -## Testing +### Testing The provider application is required to transfer image file to OTA requestor. Mbed example is compatible with Linux version of OTA provider example. Read the [OTAProvider](../../ota-provider-app/linux/README.md) to see how to build and run the OTA provider. -### Serial port terminal +#### Serial port terminal The application traces are streaming to serial output. To start communication open a terminal session and connect to the serial port of the device. You can @@ -229,7 +229,7 @@ After device reset these lines should be visible: The ota-requestor-app application launched correctly and you can follow traces in the terminal. -### CHIP Tools +#### CHIP Tools Read the [MbedCommissioning](../../../docs/guides/mbedos_commissioning.md) to see how to use different CHIP tools to commission and control the application @@ -244,7 +244,7 @@ receiving this command OTA requestor will query for OTA image: The OTA requestor should communicate with provider, download update image and apply it. -#### Notes +##### Notes - You have to provision the OTA Provider in the same Matter network. Use the `connect -ip` command of Python Device Controller: @@ -254,7 +254,7 @@ apply it. - POSIX CLI CHIPTool can be also used for testing this example. Use the correct `chip-tool` arguments to perform above-mentioned steps. -## Supported devices +### Supported devices The example supports building and running on the following mbed-enabled devices: @@ -262,18 +262,18 @@ The example supports building and running on the following mbed-enabled devices: | ----------------------------------------------------- | ------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Cypress
Semiconductor](https://www.cypress.com/) | [CY8CPROTO-062-4343W](https://os.mbed.com/platforms/CY8CPROTO-062-4343W/) | `CY8CPROTO_062_4343W` |
CY8CPROTO-062-4343WCY8CPROTO-062-4343W
| :heavy_check_mark: |
LEDs
  • Board has only one usable LED (LED4) which corresponds to USER LED from UI.
  • Lock state LED should be an external component connected to PB9_6 pin (active high).
Buttons
  • SW2 push-button is not used in this example due to its interaction with WIFI module interrupt line.
  • Button 0 corresponds to BTN0 capacitive button.
  • Button 1 corresponds to BTN1 capacitive button.
Slider
  • Unused
| -#### Notes +##### Notes - More details and guidelines about porting new hardware into the Matter project with Mbed OS can be found in [MbedNewTarget](../../../docs/guides/mbedos_add_new_target.md) - Some useful information about HW platform specific settings can be found in - `ota-requestor-app/mbed/mbed_app.json`. + `ota-requestor-app/mbed/mbed_app.json`. Information about this file syntax and its meaning in mbed-os project can be found here: [Mbed-Os configuration system](https://os.mbed.com/docs/mbed-os/latest/program-setup/advanced-configuration.html)) -## Device UI +### Device UI This section lists the User Interface elements that you can use to control and monitor the state of the device. These correspond to PCB components on the diff --git a/examples/ota-requestor-app/p6/README.md b/examples/ota-requestor-app/p6/README.md new file mode 100644 index 00000000000000..61b941fe54c970 --- /dev/null +++ b/examples/ota-requestor-app/p6/README.md @@ -0,0 +1,138 @@ +# CHIP P6 OTA Requestor Example + +An example demonstrating the OTA Requestor cluster on a Infineon +CY8CKIT-062S2-43012 board. + +
+ +- [Matter P6 OTA Requestor Example](#chip-p6-ota-requestor-example) + - [Introduction](#introduction) + - [Building](#building) + - [Flashing the Application](#flashing-the-application) + - [Running OTA Update Process](#running-ota-update-process) + - [Notes](#notes) + +
+ + + +## Introduction + +The P6 OTA Requestor example provides a baseline demonstration of a OTA +requestor device, built using Matter and the Infineon Modustoolbox SDK. It can +be controlled by Matter controller over Wi-Fi network. + +The P6 device can be commissioned over Bluetooth Low Energy where the device and +the Matter controller will exchange security information with the Rendezvous +procedure. Wi-Fi Network credentials are then provided to the P6 device which +will then join the network. + + + +## Building + +- [Modustoolbox Software](https://www.cypress.com/products/modustoolbox) + + Refer to `integrations/docker/images/chip-build-infineon/Dockerfile` or + `scripts/examples/gn_p6_example.sh` for downloading the Software and related + tools. + +- Install some additional tools (likely already present for Matter + developers): \$ sudo apt install gcc g++ clang ninja-build python + python3-venv libssl-dev libavahi-client-dev libglib2.0-dev git cmake + python3-pip + +- Supported hardware: + [CY8CKIT-062S2-43012](https://www.cypress.com/CY8CKIT-062S2-43012) + +* The following applications must be built to demonstrate the OTA process: + + - The P6 OTA Requestor App + - The Updated P6 OTA Requestor App (or other app) + - An OTA Provider App (the Linux ota-provider app is used here) + - chip-tool + +* Build the P6 OTA Requestor application from the chip root dir: + + $ ./examples/ota-requestor-app/p6/ota_base_build.sh + +* Build the P6 OTA Update application from the chip root dir: + + $ ./examples/ota-requestor-app/p6/ota_update_build.sh + +* On a RPi4: Build the Linux OTA Provider application from the chip root dir: + + $ ./scripts/examples/gn_build_example.sh examples/ota-provider-app/linux/ out/ota_provider_debug/ chip_config_network_layer_ble=false + +* On a RPi4: Build chip-tool: + + $ ./scripts/examples/gn_build_example.sh examples/chip-tool/ out/chip-tool/ + +* Additionally a pre-compiled bootloader must be flashed to the board. This + can be found at: + + $ ./third_party/p6/p6_sdk/ota/matter-psoc6-mcuboot-bootloader.hex + + + +## Flashing the Application + +- Flash the bootloader by first putting the CY8CKIT-062S2-43012 board into + KitProg3 DAPLINK Mode by pressing the `MODE SELECT` button. + `KITPROG3 STATUS` LED will blink to indicate the the board is in the proper + mode. A drive named 'DAPLINK' should be automatically mounted. To flash + drag-and-drop matter-psoc6-mcuboot-bootloader.hex into that drive. + +- Put CY8CKIT-062S2-43012 board back into KitProg3 CMSIS-DAP Mode by pressing + the `MODE SELECT` button. `KITPROG3 STATUS` LED is ON confirms board is in + proper mode. + +- On the command line: + + $ cd ~/connectedhomeip + $ python3 out/ota_requestor_debug/chip-p6-ota-requestor-example.flash.py + + + +### Running OTA Update Process + +- Make sure the ota-requestor-app is flashed and booting on the + CY8CKIT-062S2-43012. + +- Transfer out/ota_requestor_update_debug/chip-p6-ota-requestor-example.bin to + a RPi4. + +- On the RPi: In terminal 1 run the Linux ota-provider-app as follows: + + $ ./out/ota_provider_debug/chip-ota-provider-app -f chip-p6-ota-requestor-example.bin + +- On the RPi: In terminal 2 run the following chip-tool commands + + $ ./out/chip-tool/chip-tool pairing ble-wifi 2 "" "" 20202021 3840 + + $ ./out/chip-tool/chip-tool pairing onnetwork 1 20202021 + + $ ./chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": [1, 2], "targets": [{"cluster": null, "endpoint": 0, "deviceType": null}]}]' 1 0 + + $ ./chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": [1, 2], "targets": [{"cluster": null, "endpoint": 0, "deviceType": null}]}]' 2 0 + + $ ./chip-tool otasoftwareupdaterequestor write default-ota-providers '[{"fabricIndex": 1, "providerNodeID": 1, "endpoint": 0}]' 2 0 + +- Press user button 1 on the CY8CKIT-062S2-43012. This will trigger a + query-image call from the board using the default ota provider list written + in the above commands. + +- Using a serial emulator reading from the CY8CKIT-062S2-43012, you should + observe the updated application being transferred to the board, written to + flash, and, when completed, booted into. + + + +#### Notes + +Raspberry Pi 4 BLE connection issues can be avoided by running the following +commands. These power cycle the BlueTooth hardware and disable BR/EDR mode. + + $ sudo btmgmt -i hci0 power off + $ sudo btmgmt -i hci0 bredr off + $ sudo btmgmt -i hci0 power on diff --git a/examples/persistent-storage/efr32/README.md b/examples/persistent-storage/efr32/README.md index 841a72fe82727b..2ab7374e61d993 100644 --- a/examples/persistent-storage/efr32/README.md +++ b/examples/persistent-storage/efr32/README.md @@ -1,4 +1,4 @@ -#CHIP EFR32 Persistent Storage Example +# CHIP EFR32 Persistent Storage Example An example testing and demonstrating the key value storage API. diff --git a/examples/pigweed-app/efr32/README.md b/examples/pigweed-app/efr32/README.md index 6dc285203776e7..4f168d7d0b04b9 100644 --- a/examples/pigweed-app/efr32/README.md +++ b/examples/pigweed-app/efr32/README.md @@ -1,4 +1,4 @@ -#CHIP EFR32 Pigweed Example Application +# CHIP EFR32 Pigweed Example Application The EFR32 example demonstrates the usage of Pigweed module functionalities in an application. diff --git a/examples/pigweed-app/mbed/README.md b/examples/pigweed-app/mbed/README.md index 19f9a13012dc1e..ca55e3de79c210 100644 --- a/examples/pigweed-app/mbed/README.md +++ b/examples/pigweed-app/mbed/README.md @@ -1,6 +1,6 @@ ![ARM Mbed-OS logo](https://raw.githubusercontent.com/ARMmbed/mbed-os/master/logo.png) -

Matter Arm Mbed OS Pigweed Example Application

+# Matter Arm Mbed OS Pigweed Example Application The Arm Mbed OS Pigweed Example demonstrates the usage of Pigweed module functionalities in an application. @@ -35,7 +35,7 @@ serial port to the device. The following RPC protocols services are available:
-# Overview +## Overview Pigweed libraries are built and organized in a way that enables faster and more reliable development. In the Matter project, the Pigweed module is planned to be @@ -43,9 +43,9 @@ used to create system infrastructures, for example for performing on-device tests, but considering its general functionalities, it can be useful also in other cases. -# Run application +## Run application -## Environment setup +### Environment setup Before building the example, check out the Matter repository and sync submodules using the following command: @@ -91,7 +91,7 @@ environment: $ source ./scripts/activate.sh ``` -## Building +### Building The Pigweed application can be built in the same way as any other Matter example ported to the mbed-os platform. @@ -128,7 +128,7 @@ There are also three types of built application: _simple, boot_ and _upgrade_: When using the building script, it is possible expand the list of acceptable targets; this may be useful for rapid testing of a new mbed-targets. -## Flashing +### Flashing The Pigweed application can be flashed in the same way as any other Matter example ported to mbed-os platform. @@ -161,7 +161,7 @@ device. It is possible to connect to an external gdb-server session by using specific **'Flash Mbed examples [remote]'** task. -## Debugging +### Debugging Debugging can be performed in the same was as with any other Matter example ported to mbed-os platform. @@ -177,9 +177,9 @@ Run and Debug (Ctrl+Shift+D) => Debug Mbed examples => Start Debugging (F5) => ( It is possible to connect to an external gdb-server session by using specific **'Debug Mbed examples [remote]'** task. -## Testing +### Testing -### Serial port terminal +#### Serial port terminal The application traces are streaming to serial output. To start communication open a terminal session and connect to the serial port of the device. You can @@ -197,7 +197,7 @@ After device reset these lines should be visible: The pigweed-app application launched correctly and you can follow traces in the terminal. -### RPC console +#### RPC console The RPC console is an interactive Python shell console, where the different RPC command can be invoked. It is a complete solution for interacting with hardware @@ -237,7 +237,7 @@ The response from the device should be: For more details about RPC console and supported services visit [CHIP RPC console](../../common/pigweed/rpc_console/README.md). -## Supported devices +### Supported devices The example supports building and running on the following mbed-enabled devices: @@ -245,18 +245,18 @@ The example supports building and running on the following mbed-enabled devices: | ----------------------------------------------------- | ------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Cypress
Semiconductor](https://www.cypress.com/) | [CY8CPROTO-062-4343W](https://os.mbed.com/platforms/CY8CPROTO-062-4343W/) | `CY8CPROTO_062_4343W` |
CY8CPROTO-062-4343WCY8CPROTO-062-4343W
| :heavy_check_mark: |
LEDs
  • Board has only one usable LED (LED4) which corresponds to USER LED from UI.
Buttons
  • Unused
Slider
  • Unused
| -#### Notes +##### Notes - More details and guidelines about porting new hardware into the Matter project with Mbed OS can be found in [MbedNewTarget](../../../docs/guides/mbedos_add_new_target.md) - Some useful information about HW platform specific settings can be found in - `pigweed-app/mbed/mbed_app.json`. + `pigweed-app/mbed/mbed_app.json`. Information about this file syntax and its meaning in mbed-os project can be found here: [Mbed-Os configuration system](https://os.mbed.com/docs/mbed-os/latest/program-setup/advanced-configuration.html)) -# Device UI +## Device UI This section lists the User Interface elements that you can use to control and monitor the state of the device. These correspond to PCB components on the @@ -267,7 +267,7 @@ possible: - _Solid On_ — The application was flashed and run successfully. -### Notes +#### Notes Some of the supported boards may not have sufficient number PCB components to follow above description. In that case please refer to diff --git a/examples/shell/mbed/README.md b/examples/shell/mbed/README.md index 02738126c8e0de..c15008d0d034bf 100644 --- a/examples/shell/mbed/README.md +++ b/examples/shell/mbed/README.md @@ -1,6 +1,6 @@ ![ARM Mbed-OS logo](https://raw.githubusercontent.com/ARMmbed/mbed-os/master/logo.png) -

Matter Arm Mbed OS Shell Example Application

+# Matter Arm Mbed OS Shell Example Application The Arm Mbed OS Shell Example exposes configuration and management APIs via a command line interface (CLI). Use the shell CLI to experiment with Matter @@ -28,7 +28,7 @@ supports remote access and control of device over serial port.
-# Overview +## Overview The Matter device that runs the shell application can be controlled over serial port. The shell is used to parse a command line and call the corresponding @@ -36,9 +36,9 @@ service execution. There is a set of common shell commands which performs basic device operations. Mbed OS application also supports some custom services and corresponding shell commands allow them execution. -# Run application +## Run application -## Environment setup +### Environment setup Before building the example, check out the Matter repository and sync submodules using the following command: @@ -84,7 +84,7 @@ environment: $ source ./scripts/activate.sh ``` -## Building +### Building The shell application can be built in the same way as any other Matter example ported to the mbed-os platform. @@ -121,7 +121,7 @@ There are also three types of built application: _simple, boot_ and _upgrade_: When using the building script, it is possible expand the list of acceptable targets; this may be useful for rapid testing of a new mbed-targets. -## Flashing +### Flashing The shell application can be flashed in the same way as any other Matter example ported to mbed-os platform. @@ -154,7 +154,7 @@ device. It is possible to connect to an external gdb-server session by using specific **'Flash Mbed examples [remote]'** task. -## Debugging +### Debugging Debugging can be performed in the same was as with any other Matter example ported to mbed-os platform. @@ -170,9 +170,9 @@ Run and Debug (Ctrl+Shift+D) => Debug Mbed examples => Start Debugging (F5) => ( It is possible to connect to an external gdb-server session by using specific **'Debug Mbed examples [remote]'** task. -## Testing +### Testing -### Serial port terminal +#### Serial port terminal To start communication open a serial terminal session and connect to the serial port of the device. You can use **mbed-tools** for this purpose @@ -195,7 +195,7 @@ Example: Hello Done -## Supported devices +### Supported devices The example supports building and running on the following mbed-enabled devices: @@ -203,18 +203,18 @@ The example supports building and running on the following mbed-enabled devices: | ----------------------------------------------------- | ------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Cypress
Semiconductor](https://www.cypress.com/) | [CY8CPROTO-062-4343W](https://os.mbed.com/platforms/CY8CPROTO-062-4343W/) | `CY8CPROTO_062_4343W` |
CY8CPROTO-062-4343WCY8CPROTO-062-4343W
| :heavy_check_mark: |
LEDs
  • Unused
Buttons
  • Unused
Slider
  • Unused
| -#### Notes +##### Notes - More details and guidelines about porting new hardware into the Matter project with Mbed OS can be found in [MbedNewTarget](../../../docs/guides/mbedos_add_new_target.md) - Some useful information about HW platform specific settings can be found in - `shell/mbed/mbed_app.json`. + `shell/mbed/mbed_app.json`. Information about this file syntax and its meaning in mbed-os project can be found here: [Mbed-Os configuration system](https://os.mbed.com/docs/mbed-os/latest/program-setup/advanced-configuration.html)) -# Shell commands +## Shell commands The application supports common Matter shell commands. They are used to control the basic functionalities of the device. diff --git a/examples/window-app/efr32/README.md b/examples/window-app/efr32/README.md index bcc4b2fa61944d..4cde87f3c9600c 100644 --- a/examples/window-app/efr32/README.md +++ b/examples/window-app/efr32/README.md @@ -1,4 +1,4 @@ -#CHIP EFR32 Window Covering Example +# CHIP EFR32 Window Covering Example An example showing the use of CHIP on the Silicon Labs EFR32 MG12. From ddb7b5ca6a9e4eee55fc34a940895e806403ed8c Mon Sep 17 00:00:00 2001 From: Gaute Svanes Lunde Date: Thu, 2 Jun 2022 12:09:48 +0200 Subject: [PATCH 04/14] doc: fix sphinx build warnings Fixed or removed all warnings from Sphinx when building. Fixes include: - Linking errors - Typos - ToC tree errors - Adding MyST configuration data - Modify the external_content extension to allow syntax that renders on both GitHub and Sphinx Signed-off-by: Gaute Svanes Lunde --- docs/_extensions/external_content.py | 94 ++++++++++++++----- docs/conf.py | 27 ++++-- .../PID_allocation_for_example_apps.md | 4 + docs/examples/index.md | 29 +++--- docs/guides/android_building.md | 18 ++-- docs/guides/chip_tool_guide.md | 22 ++--- docs/guides/mbedos_platform_overview.md | 4 +- .../nrfconnect_android_commissioning.md | 26 +---- .../nrfconnect_examples_configuration.md | 2 - docs/guides/nxp_imx8m_linux_examples.md | 18 ++-- docs/guides/nxp_k32w_android_commissioning.md | 48 +++------- .../python_chip_controller_advanced_usage.md | 8 +- .../guides/python_chip_controller_building.md | 20 +--- docs/guides/simulated_device_linux.md | 6 +- docs/index.md | 7 +- docs/make.bat | 1 + .../cc13x2x7_26x2x7/README.md | 11 +-- .../all-clusters-app/infineon/psoc6/README.md | 4 +- examples/all-clusters-app/mbed/README.md | 8 +- .../all-clusters-app/nrfconnect/README.md | 27 +----- examples/all-clusters-app/nxp/mw320/README.md | 7 -- .../cc13x2x7_26x2x7/README.md | 3 +- .../infineon/psoc6/README.md | 18 +--- .../all-clusters-minimal-app/mbed/README.md | 8 +- .../nrfconnect/README.md | 27 +----- examples/bridge-app/linux/README.md | 10 +- examples/chef/sample_app_util/README.md | 12 +-- examples/chip-tool/README.md | 2 +- examples/common/README.md | 4 + examples/common/pigweed/rpc_console/README.md | 4 + examples/common/screen-framework/README.md | 4 + examples/common/tracing/README.md | 4 + examples/darwin-framework-tool/README.md | 2 +- examples/light-switch-app/efr32/README.md | 15 --- examples/light-switch-app/esp32/README.md | 64 +++++++++++-- .../light-switch-app/nrfconnect/README.md | 55 ++++------- .../telink/{Readme.md => README.md} | 0 examples/lighting-app/efr32/README.md | 15 --- examples/lighting-app/esp32/README.md | 48 +++++++++- .../lighting-app/infineon/psoc6/README.md | 4 +- examples/lighting-app/linux/README.md | 10 +- examples/lighting-app/mbed/README.md | 4 +- examples/lighting-app/nrfconnect/README.md | 26 +---- .../lighting-app/nxp/k32w/k32w0/README.md | 58 +++--------- examples/lighting-app/qpg/APPLICATION.md | 2 +- .../telink/{Readme.md => README.md} | 0 examples/lock-app/cc13x2x7_26x2x7/README.md | 3 +- examples/lock-app/efr32/README.md | 13 --- examples/lock-app/infineon/psoc6/README.md | 16 ---- examples/lock-app/mbed/README.md | 6 +- examples/lock-app/nrfconnect/README.md | 25 +---- examples/lock-app/nxp/k32w/k32w0/README.md | 16 +--- examples/lock-app/qpg/APPLICATION.md | 2 +- examples/ota-provider-app/esp32/README.md | 2 +- examples/ota-requestor-app/esp32/README.md | 2 +- examples/ota-requestor-app/mbed/README.md | 4 +- examples/ota-requestor-app/p6/README.md | 10 -- examples/persistent-storage/efr32/README.md | 10 -- .../infineon/psoc6/README.md | 6 -- examples/persistent-storage/linux/README.md | 8 -- examples/pigweed-app/efr32/README.md | 4 +- examples/pigweed-app/mbed/README.md | 4 +- examples/pigweed-app/nrfconnect/README.md | 34 ++----- examples/platform/qpg/README.md | 6 +- examples/pump-app/nrfconnect/README.md | 32 ++----- .../pump-controller-app/nrfconnect/README.md | 32 ++----- examples/shell/README.md | 4 +- examples/shell/README_SERVER.md | 1 - examples/shell/mbed/README.md | 2 +- examples/tv-app/linux/README.md | 4 - examples/tv-casting-app/android/README.md | 10 -- examples/tv-casting-app/linux/README.md | 4 - examples/window-app/efr32/README.md | 16 ---- examples/window-app/nrfconnect/README.md | 25 +---- 74 files changed, 423 insertions(+), 668 deletions(-) rename examples/light-switch-app/telink/{Readme.md => README.md} (100%) rename examples/lighting-app/telink/{Readme.md => README.md} (100%) diff --git a/docs/_extensions/external_content.py b/docs/_extensions/external_content.py index 8f4acfd3d70cf7..ce3a4f68491278 100644 --- a/docs/_extensions/external_content.py +++ b/docs/_extensions/external_content.py @@ -14,16 +14,19 @@ copied. Therefore, incremental builds detect changes correctly and behave as expected. -Paths for external content ingluded via e.g. figure, literalinclude, etc. -are adjusted as needed. +Links to external content not included in the generated documentation are +transformed to external links as needed. Configuration options ===================== - ``external_content_contents``: A list of external contents. Each entry is a tuple with two fields: the external base directory and a file glob pattern. -- ``external_content_directives``: A list of directives that should be analyzed - and their paths adjusted if necessary. Defaults to ``DEFAULT_DIRECTIVES``. +- ``external_content_link_repositories``: A list of base directories out of scope. + All links to content within these directories are made external. +- ``external_content_link_extensions``: A list of file extensions in scope of + the documentation. All links to content without these file extensions are + made external. - ``external_content_keep``: A list of file globs (relative to the destination directory) that should be kept even if they do not exist in the source directory. This option can be useful for auto-generated files in the @@ -40,19 +43,19 @@ from sphinx.application import Sphinx - __version__ = "0.1.0" - -DEFAULT_DIRECTIVES = ("figure", "image", "include", "literalinclude") -"""Default directives for included content.""" +EXTERNAL_LINK_URL_PREFIX = ( + "https://github.com/project-chip/connectedhomeip/blob/master/" +) def adjust_includes( fname: Path, basepath: Path, - directives: List[str], encoding: str, + link_folders: List[str], + extensions: List[str], dstpath: Optional[Path] = None, ) -> None: """Adjust included content paths. @@ -60,35 +63,77 @@ def adjust_includes( Args: fname: File to be processed. basepath: Base path to be used to resolve content location. - directives: Directives to be parsed and adjusted. encoding: Sources encoding. + link_folders: Folders links to which are made external. + extensions: Filename extensions links to which are not made external. dstpath: Destination path for fname if its path is not the actual destination. """ - if fname.suffix != ".rst": + if fname.suffix != ".md": return dstpath = dstpath or fname.parent - def _adjust(m): - directive, fpath = m.groups() + def _adjust_links(m): + displayed, fpath = m.groups() - # ignore absolute paths - if fpath.startswith("/"): + # ignore absolute paths, section links, hyperlinks and same folder + if fpath.startswith(("/", "#", "http", "www")) or not "/" in fpath: fpath_adj = fpath else: fpath_adj = Path(os.path.relpath(basepath / fpath, dstpath)).as_posix() - return f".. {directive}:: {fpath_adj}" + return f"[{displayed}]({fpath_adj})" + + def _adjust_external(m): + displayed, folder, target = m.groups() + return f"[{displayed}]({EXTERNAL_LINK_URL_PREFIX}{folder}/{target})" + + def _adjust_filetype(m): + displayed, target, extension = m.groups() + if extension.lower() in extensions or target.startswith("http"): + return m.group(0) + + return f"[{displayed}]({EXTERNAL_LINK_URL_PREFIX}{target})" + + def _remove_section_links(m): + (file_link,) = m.groups() + return file_link + ")" + + rules = [ + # Find any links and adjust the path + (r"\[([^\[\]]*)\]\s*\((.*)\)", _adjust_links), + + # Find links that lead to an external folder and transform it + # into an external link. + ( + r"\[([^\[\]]*)\]\s*\((?:\.\./)*(" + "|".join(link_folders) + r")/(.*)\)", + _adjust_external, + ), + + # Find links that lead to a section within another file and + # remove the section part of the link. + (r"(\[[^\[\]]*\]\s*\([^)]*\.md)#.*\)", _remove_section_links), + + # Find links that lead to a non-presentable filetype and transform + # it into an external link. + ( + r"\[([^\[\]]*)\]\s*\((?:\.\./)*((?:[^()]+?/)*[^.()]+?(\.[^)/]+))\)", + _adjust_filetype, + ), + ] with open(fname, "r+", encoding=encoding) as f: content = f.read() - content_adj, modified = re.subn( - r"\.\. (" + "|".join(directives) + r")::\s*([^`\n]+)", _adjust, content - ) + modified = False + + for pattern, sub_func in rules: + content, changes_made = re.subn(pattern, sub_func, content) + modified = modified or changes_made + if modified: f.seek(0) - f.write(content_adj) + f.write(content) f.truncate() @@ -135,8 +180,9 @@ def sync_contents(app: Sphinx) -> None: adjust_includes( dst, src.parent, - app.config.external_content_directives, app.config.source_encoding, + app.config.external_content_link_repositories, + app.config.external_content_link_extensions, ) # if origin file is modified only copy if different elif src.stat().st_mtime > dst.stat().st_mtime: @@ -147,8 +193,9 @@ def sync_contents(app: Sphinx) -> None: adjust_includes( src_adjusted, src.parent, - app.config.external_content_directives, app.config.source_encoding, + app.config.external_content_link_repositories, + app.config.external_content_link_extensions, dstpath=dst.parent, ) @@ -164,8 +211,9 @@ def sync_contents(app: Sphinx) -> None: def setup(app: Sphinx) -> Dict[str, Any]: app.add_config_value("external_content_contents", [], "env") - app.add_config_value("external_content_directives", DEFAULT_DIRECTIVES, "env") app.add_config_value("external_content_keep", [], "") + app.add_config_value("external_content_link_repositories", [], "env") + app.add_config_value("external_content_link_extensions", [], "env") app.connect("builder-inited", sync_contents) diff --git a/docs/conf.py b/docs/conf.py index 5655b98a03e50f..6f9abf5deb45b0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -20,7 +20,13 @@ # -- General configuration --------------------------------------------------- extensions = ["myst_parser", "external_content", "doxyrunner", "breathe"] -exclude_patterns = ["_build"] +exclude_patterns = [ + "_build", + "**/nxp/linux-imx/imx8m/README.md", + "examples/ota-requestor-app/efr32/README.md", + "**/android/App/app/libs*", + "examples/providers/README.md", +] # -- Options for HTML output ------------------------------------------------- @@ -38,12 +44,24 @@ "path_to_docs": "docs", } +# -- Options for MyST -------------------------------------------------------- + +myst_heading_anchors = 6 +suppress_warnings = ["myst.header"] +myst_enable_extensions = ["html_image"] + + # -- Options for external_content -------------------------------------------- external_content_contents = [ (MATTER_BASE / "docs", "[!_]*"), (MATTER_BASE, "examples/**/*.md"), + (MATTER_BASE, "examples/**/*.png"), + (MATTER_BASE, "examples/**/*.jpg"), + (MATTER_BASE, "examples/**/*.JPG"), ] +external_content_link_repositories = ["src", r"\.vscode"] +external_content_link_extensions = [".md", ".png", ".jpg", ".svg"] # -- Options for zephyr.doxyrunner plugin ------------------------------------ @@ -51,10 +69,7 @@ doxyrunner_doxyfile = MATTER_BASE / "docs" / "matter.doxyfile.in" doxyrunner_outdir = MATTER_BASE / "docs" / "_build" / "doxygen" doxyrunner_fmt = True -doxyrunner_fmt_vars = { - "MATTER_BASE": str(MATTER_BASE), - "MATTER_VERSION": version -} +doxyrunner_fmt_vars = {"MATTER_BASE": str(MATTER_BASE), "MATTER_VERSION": version} # -- Options for Breathe plugin ------------------------------------------- @@ -64,4 +79,4 @@ "h": "cpp", "cpp": "cpp", "c": "c", -} \ No newline at end of file +} diff --git a/docs/examples/discussion/PID_allocation_for_example_apps.md b/docs/examples/discussion/PID_allocation_for_example_apps.md index 18e71a20698964..2ebb169e60f099 100644 --- a/docs/examples/discussion/PID_allocation_for_example_apps.md +++ b/docs/examples/discussion/PID_allocation_for_example_apps.md @@ -1,3 +1,7 @@ +--- +orphan: true +--- + # PID allocation for example apps Unless specifically overridden by the platform, example apps in this SDK use the diff --git a/docs/examples/index.md b/docs/examples/index.md index a4d72c2677cb7b..f899c0196725db 100644 --- a/docs/examples/index.md +++ b/docs/examples/index.md @@ -11,49 +11,50 @@ The Matter SDK provides examples of Matter devices for different development pla all-clusters-app/**/README ``` -## Bridge example +## All clusters minimal example ```{toctree} :glob: :maxdepth: 1 -bridge-app/**/README +all-clusters-minimal-app/**/README ``` -## CHEF example +## Bridge example ```{toctree} :glob: :maxdepth: 1 -chef/**/README +bridge-app/**/README ``` -## CHIP Tool example +## CHEF example ```{toctree} :glob: :maxdepth: 1 -chip-tool/README +chef/README* +chef/**/README ``` -## CHIP Tool Darwin example +## CHIP Tool example ```{toctree} :glob: :maxdepth: 1 -chip-tool-darwin/README +chip-tool/README ``` -## IPv6 Only example +## CHIP Tool Darwin example ```{toctree} :glob: :maxdepth: 1 -ipv6only-app/**/README +darwin-framework-tool/README ``` ## Lighting example @@ -63,6 +64,7 @@ ipv6only-app/**/README :maxdepth: 1 lighting-app/**/README +lighting-app/qpg/APPLICATION ``` ## Light switch example @@ -71,7 +73,7 @@ lighting-app/**/README :glob: :maxdepth: 1 -lighting-app/**/README +light-switch-app/**/README ``` ## Lock example @@ -81,6 +83,7 @@ lighting-app/**/README :maxdepth: 1 lock-app/**/README +lock-app/qpg/APPLICATION ``` ## Log source example @@ -126,6 +129,7 @@ ota-requestor-app/**/README :maxdepth: 1 persistent-storage/**/README +persistent-storage/**/APPLICATION ``` ## Pigweed example @@ -144,6 +148,7 @@ pigweed-app/**/README :maxdepth: 1 pump-app/**/README +pump-app/cc13x2x7_26x2x7/doc/programming* ``` ## Pump controller example @@ -153,6 +158,7 @@ pump-app/**/README :maxdepth: 1 pump-controller-app/**/README +pump-controller-app/cc13x2x7_26x2x7/doc/programming* ``` ## Shell example @@ -161,6 +167,7 @@ pump-controller-app/**/README :glob: :maxdepth: 1 +shell/README* shell/**/README ``` diff --git a/docs/guides/android_building.md b/docs/guides/android_building.md index 6ca2d91dd54a1a..c845319518673d 100644 --- a/docs/guides/android_building.md +++ b/docs/guides/android_building.md @@ -15,14 +15,14 @@ There are following Apps on Android
-- [Source files](#source) -- [Requirements for building](#requirements) - - [ABIs and TARGET_CPU](#abi) - - [Gradle & JDK Version](#jdk) -- [Preparing for build](#preparing) -- [Building Android CHIPTool from scripts](#building-scripts) -- [Building Android CHIPTool from Android Studio](#building-studio) -- [Building Android CHIPTest from scripts](#building-chiptest-scripts) +- [Source files](#source-files) +- [Requirements for building](#requirements-for-building) + - [ABIs and TARGET_CPU](#abis-and-target_cpu) + - [Gradle & JDK Version](#gradle--jdk-version) +- [Preparing for build](#preparing-for-build) +- [Building Android CHIPTool from scripts](#building-android-chiptool-from-scripts) +- [Building Android CHIPTool from Android Studio](#building-android-chiptool-from-android-studio) +- [Building Android CHIPTest from scripts](#building-android-chiptest-from-scripts)
@@ -167,7 +167,7 @@ or ## Building Android CHIPTest from scripts Currently, the CHIPTest can only be built from scripts. The steps are similar to -[building CHIPTool from scripts](#building-scripts). +[building CHIPTool from scripts](#building-android-chiptool-from-scripts). ```shell ./scripts/build/build_examples.py --target android-arm64-chip-test build diff --git a/docs/guides/chip_tool_guide.md b/docs/guides/chip_tool_guide.md index 5dbeb5f3b1b678..f1d222768281ac 100644 --- a/docs/guides/chip_tool_guide.md +++ b/docs/guides/chip_tool_guide.md @@ -8,15 +8,13 @@ the setup payload or performing discovery actions.
-- [Source files](#source) -- [Building and running the CHIP Tool](#building) -- [Using the CHIP Tool for Matter device testing](#using) -- [Supported commands and options](#commands) +- [Source files](#source-files) +- [Building and running the CHIP Tool](#building-and-running-the-chip-tool) +- [Using the CHIP Tool for Matter device testing](#using-chip-tool-for-matter-device-testing) +- [Supported commands and options](#supported-commands-and-options)
- - ## Source files You can find source files of the CHIP Tool in the `examples/chip-tool` @@ -28,8 +26,6 @@ directory.
- - ## Building and running the CHIP Tool Before you can use the CHIP Tool, you must compile it from source on Linux @@ -69,12 +65,10 @@ _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](#commands) section. +cases are described in the [Supported commands and options](#supported-commands-and-options) section.
- - ## Using CHIP Tool for Matter device testing This section describes how to use CHIP Tool to test the Matter device. The @@ -385,8 +379,6 @@ $ ./chip-tool basic
- - ## Supported commands and options This section contains a general list of various CHIP Tool commands and options, @@ -770,7 +762,7 @@ The `pairing` command supports different means regarding Matter device commissioning procedure. Thread and Wi-Fi commissioning use cases are described in the -[Using the CHIP Tool for Matter device testing](#using) section. +[Using the CHIP Tool for Matter device testing](#using-chip-tool-for-matter-device-testing) section. To list all `pairing` sub-commands, run the following command: @@ -780,7 +772,7 @@ $ ./chip-tool pairing ### Interacting with Data Model clusters -As mentioned in the [Using the CHIP Tool for Matter device testing](#using) +As mentioned in the [Using the 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: diff --git a/docs/guides/mbedos_platform_overview.md b/docs/guides/mbedos_platform_overview.md index 7d406b63b94f1c..b70d5ed89cc1ba 100644 --- a/docs/guides/mbedos_platform_overview.md +++ b/docs/guides/mbedos_platform_overview.md @@ -85,8 +85,8 @@ needed to perform communication through the Matter stack. Sample Matter applications are provided for the Mbed OS platform. They can be used to speed up development: -- [shell](../../examples/shell/mbed) -- [all-clusters-app](../../examples/all-clusters-app/mbed) +- [shell](../../examples/shell/mbed/README.md) +- [all-clusters-app](../../examples/all-clusters-app/mbed/README.md) - [lock-app](../../examples/lock-app/mbed/README.md) - [lighting-app](../../examples/lighting-app/mbed/README.md) - [pigweed-app](../../examples/pigweed-app/mbed/README.md) diff --git a/docs/guides/nrfconnect_android_commissioning.md b/docs/guides/nrfconnect_android_commissioning.md index 93c0999b26212c..af617cbae77599 100644 --- a/docs/guides/nrfconnect_android_commissioning.md +++ b/docs/guides/nrfconnect_android_commissioning.md @@ -14,16 +14,14 @@ and applications as well. - [Overview](#overview) - [Requirements](#requirements) - [Setting up Thread Border Router](#setting-up-thread-border-router) -- [Building and programming nRF Connect Example Application](#building-example) -- [Building and installing Android CHIPTool](#building-chiptool) -- [Preparing accessory device](#preparing-accessory) -- [Commissioning accessory device](#commissioning-accessory) -- [Sending Matter commands](#sending-chip-commands) +- [Building and programming nRF Connect Example Application](#building-and-programming-nrf-connect-example-application) +- [Building and installing Android CHIPTool](#building-and-installing-android-chiptool) +- [Preparing accessory device](#preparing-accessory-device) +- [Commissioning accessory device](#commissioning-accessory-device) +- [Sending Matter commands](#sending-matter-commands)
- - ## Overview The commissioning process is composed of the following main stages: @@ -53,8 +51,6 @@ applications:
- - ## Requirements You need the following hardware and software for commissioning the nRF Connect @@ -77,8 +73,6 @@ accessory using Android CHIPTool:
- - ## Setting up Thread Border Router Follow the [OpenThread Border Router](openthread_border_router_pi.md) article to @@ -88,8 +82,6 @@ or the nRF52840 Dongle acting as the
- - ## Building and programming nRF Connect Example Application Build and program the example application onto your compatible device. @@ -99,8 +91,6 @@ learn how to build and program the example onto an nRF52840 DK.
- - ## Building and installing Android CHIPTool To build the CHIPTool application for your smartphone, read the @@ -135,8 +125,6 @@ CHIPTool is now ready to be used for commissioning.
- - ## Preparing accessory device To prepare the accessory device for commissioning, complete the following steps: @@ -160,8 +148,6 @@ To prepare the accessory device for commissioning, complete the following steps:
- - ## Commissioning accessory device To commission the accessory device onto the Thread network created in the @@ -185,8 +171,6 @@ device successfully joins the Thread network.
- - ## Sending Matter commands Once the device is commissioned, the main application screen appears. diff --git a/docs/guides/nrfconnect_examples_configuration.md b/docs/guides/nrfconnect_examples_configuration.md index 119852b3929a89..de79df58430526 100644 --- a/docs/guides/nrfconnect_examples_configuration.md +++ b/docs/guides/nrfconnect_examples_configuration.md @@ -103,8 +103,6 @@ target name of the kit, for example _nrf52840dk_nrf52840_:
- - ## Configuration structure overview Zephyr RTOS and related software components, like drivers and libraries, provide diff --git a/docs/guides/nxp_imx8m_linux_examples.md b/docs/guides/nxp_imx8m_linux_examples.md index c1eabd3819910b..6b1ad2b8f6c4bd 100644 --- a/docs/guides/nxp_imx8m_linux_examples.md +++ b/docs/guides/nxp_imx8m_linux_examples.md @@ -4,11 +4,11 @@ This document describes how to build below Linux examples with the NXP embedded Linux Yocto SDK and then run the output executable files on the **NXP i.MX 8M** **Mini EVK** development board. -- [CHIP Linux All-clusters Example](../../examples/all-clusters-app/linux) -- [CHIP Linux Lighting Example](../../examples/lighting-app/linux) -- [CHIP Linux Thermostat Example](../../examples/thermostat/linux) -- [CHIP Linux CHIP-tool Example](../../examples/chip-tool) -- [CHIP Linux OTA-provider Example](../../examples/ota-provider-app/linux) +- [CHIP Linux All-clusters Example](../../examples/all-clusters-app/linux/README.md) +- [CHIP Linux Lighting Example](../../examples/lighting-app/linux/README.md) +- [CHIP Linux Thermostat Example](https://github.com/project-chip/connectedhomeip/tree/master/examples/thermostat/linux) +- [CHIP Linux CHIP-tool Example](../../examples/chip-tool/README.md) +- [CHIP Linux OTA-provider Example](../../examples/ota-provider-app/linux/README.md) This document has been tested on: @@ -30,8 +30,6 @@ Linux OS development. For more information about this project, see the
- - ## Building Before building the CHIP Linux Examples, the Yocto source code released by NXP @@ -73,7 +71,7 @@ to be generated. More information about the downloaded Yocto release can be found in the corresponding i.MX Yocto Project User’s Guide which can be found at - [NXP official website](www.nxp.com/imxlinux). + [NXP official website](https://www.nxp.com/imxlinux). Change the current directory to the top directory of the Yocto source code and execute the commands below to generate the Yocto SDK: @@ -181,8 +179,6 @@ to be generated. running the Yocto image previously generated as described in the sections above. - - ## Commandline arguments The generated executable files supports to work with below commandline argument: @@ -205,8 +201,6 @@ The generated executable files supports to work with below commandline argument: The BLE device on **i.MX 8M Mini EVK** is a module based on the NXP 88W8987 Wi-Fi/Bluetooth SoC. - - ## Running the Examples on i.MX 8M Mini EVK The steps and commands to run any of the examples are quite similar. diff --git a/docs/guides/nxp_k32w_android_commissioning.md b/docs/guides/nxp_k32w_android_commissioning.md index 751b6043a65d81..84b5f7addd2f59 100644 --- a/docs/guides/nxp_k32w_android_commissioning.md +++ b/docs/guides/nxp_k32w_android_commissioning.md @@ -3,26 +3,24 @@ This article describes how to use [CHIPTool](../../src/android/CHIPTool/README.md) for Android smartphones to commission an NXP K32W061 DK6 running -[NXP K32W Lock/Light Example Application](../../examples/lock-light-app/k32w/README.md) +[NXP K32W Lock/Light Example Application](#building-and-programming-nxp-k32w-locklight-example-application) onto a CHIP-enabled Thread network.
- [Overview](#overview) - [Requirements](#requirements) -- [Building and programming OpenThread RCP firmware](#building-rcp-firmware) -- [Configuring PC as Thread Border Router](#configuring-pc) -- [Building and programming NXP K32W Lock/Light Example Application](#building-example) -- [Building and installing Android CHIPTool](#building-chiptool) -- [Forming a Thread network on the Border Router](#form-thread) -- [Preparing accessory device](#preparing-accessory) -- [Commissioning accessory device](#commissioning-accessory) +- [Building and programming OpenThread RCP firmware](#building-and-programming-openthread-rcp-firmware) +- [Configuring PC as Thread Border Router](#configuring-pc-as-a-thread-border-router) +- [Building and programming NXP K32W Lock/Light Example Application](#building-and-programming-nxp-k32w-locklight-example-application) +- [Building and installing Android CHIPTool](#building-and-installing-android-chiptool) +- [Forming a Thread network on the Border Router](#forming-a-thread-network-on-the-border-router) +- [Preparing accessory device](#preparing-accessory-device) +- [Commissioning accessory device](#commissioning-accessory-device) - [Sending CHIP commands](#sending-chip-commands)
- - ## Overview The commissioning process is composed of the following main stages: @@ -49,12 +47,10 @@ The following diagram shows the connectivity between network components required to allow communication between devices running the CHIPTool and Lock/Light applications: -![nxp_hw_connectivity](../../examples/platform/k32w/doc/images/nxp_hw_connectivity.JPG) +![nxp_hw_connectivity](../../examples/platform/nxp/k32w/k32w0/doc/images/nxp_hw_connectivity.JPG)
- - ## Requirements You need the following hardware and software to build a Thread Border Router: @@ -77,8 +73,6 @@ using other popular operating systems.
- - ## Building and programming OpenThread RCP firmware OpenThread RCP firmware is required to allow the PC to communicate with Thread @@ -123,8 +117,6 @@ the RCP firmware onto an K32W061 DK6:
- - ## Configuring PC as a Thread Border Router To make your PC work as a Thread Border Router, complete the following tasks: @@ -353,8 +345,6 @@ To make your PC work as a Thread Border Router, complete the following tasks:
- - ## Building and programming NXP K32W Lock/Light Example Application See @@ -367,8 +357,6 @@ to learn how to build and program the light example onto an K32W061 DK6.
- - ## Building and installing Android CHIPTool To build the CHIPTool application for your smartphone, read @@ -403,8 +391,6 @@ CHIPTool is now ready to be used for commissioning.
- - ## Forming a Thread network on the Border Router 1. On the mobile phone connect to the _OT-BR_ Wi-Fi network. @@ -414,7 +400,7 @@ CHIPTool is now ready to be used for commissioning. 3. Navigate to the _Form_ tab then push the _Form_ button using the default parameters: - ![nxp_form_nwk](../../examples/platform/k32w/doc/images/form_web.JPG) + ![nxp_form_nwk](../../examples/platform/nxp/k32w/k32w0/doc/images/form_web.JPG) 4. The message _Form operation is successful_ should be display after a few seconds. @@ -448,7 +434,7 @@ To prepare the accessory device for commissioning, complete the following steps: 1. Make sure that JP4 and JP7 jumpers are in leftmost position and a mini-USB cable is connected between the LPC connector and PC - ![nxp_connectors](../../examples/platform/k32w/doc/images/k32w-dk6-connectors.jpg) + ![nxp_connectors](../../examples/platform/nxp/k32w/k32w0/doc/images/k32w-dk6-connectors.jpg) 2. Use a terminal emulator (e.g.: Putty) to connect to the UART console of the accessory device. Use a baudrate of 115200. @@ -468,12 +454,10 @@ To prepare the accessory device for commissioning, complete the following steps:
- - ## Commissioning accessory device To commission the accessory device onto the Thread network created in the -[Forming Thread network](#Forming-a-Thread-network) section, complete the +[Forming Thread network](#forming-a-thread-network-on-the-border-router) section, complete the following steps: 1. Enable _Bluetooth_ and _Location_ services on your smartphone; @@ -486,26 +470,24 @@ following steps: progress with scanning, connection, and pairing. At the end of this process, the Thread network settings screen appears. - ![chiptool_main_screen](../../examples/platform/k32w/doc/images/chiptool_main_screen.png) + ![chiptool_main_screen](../../examples/platform/nxp/k32w/k32w0/doc/images/chiptool_main_screen.png) 6. In the Thread network settings screen, use the default settings and tap the _SAVE NETWORK_ button to send a Thread provisioning message to the accessory device. You will see the "Network provisioning completed" message when the accessory device successfully joins the Thread network. - ![chiptool_credentials](../../examples/platform/k32w/doc/images/thread_credentials.png) + ![chiptool_credentials](../../examples/platform/nxp/k32w/k32w0/doc/images/thread_credentials.png)
- - ## Sending CHIP commands 1. Once the device is commissioned, the below screen appears. This means that the provisioning is completed successfully and you are connected to the device. - ![on_off_cluster.png](../../examples/platform/k32w/doc/images/on_off_cluster.png) + ![on_off_cluster.png](../../examples/platform/nxp/k32w/k32w0/doc/images/on_off_cluster.png) 2. Verify that the text box on the screen is not empty and contains the IPv6 address of the accessory device. diff --git a/docs/guides/python_chip_controller_advanced_usage.md b/docs/guides/python_chip_controller_advanced_usage.md index ca17d8ca297829..c3d3f55ddc5095 100644 --- a/docs/guides/python_chip_controller_advanced_usage.md +++ b/docs/guides/python_chip_controller_advanced_usage.md @@ -7,13 +7,11 @@ tool or Matter accessories on Linux.
-- [Bluetooth LE virtualization on Linux](#virtualization) -- [Debugging with gdb](#gdb) +- [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 @@ -76,8 +74,6 @@ interfaces working as Bluetooth LE central and peripheral, respectively.
- - ## Debugging with gdb You can run the chip-device-ctrl under GDB for debugging, however, since the diff --git a/docs/guides/python_chip_controller_building.md b/docs/guides/python_chip_controller_building.md index 693dacf3732055..a466eb4885b8ee 100644 --- a/docs/guides/python_chip_controller_building.md +++ b/docs/guides/python_chip_controller_building.md @@ -9,16 +9,14 @@ into the network and to communicate with it using the Zigbee Cluster Library
-- [Source files](#source) -- [Building Android CHIPTool](#building) -- [Running the tool](#running) -- [Using Python CHIP Controller for Matter accessory testing](#using) -- [List of commands](#commands) +- [Source files](#source-files) +- [Building Android CHIPTool](#building-and-installing) +- [Running the tool](#running-the-tool) +- [Using Python CHIP Controller for Matter accessory testing](#using-python-chip-controller-for-matter-accessory-testing) +- [List of commands](#list-of-commands)
- - ## Source files You can find source files of the Python CHIP Controller tool in the @@ -29,8 +27,6 @@ The tool uses the generic CHIP Device Controller library, available in the
- - ## Building and installing Before you can use the Python controller, you must compile it from the source on @@ -88,8 +84,6 @@ To build and run the Python CHIP controller:
- - ## Running the tool 1. Activate the Python virtual environment: @@ -113,8 +107,6 @@ To build and run the Python CHIP controller:
- - ## Using Python CHIP Controller for Matter accessory testing This section describes how to use Python CHIP controller to test the Matter @@ -302,8 +294,6 @@ chip-device-ctrl > zclread Basic SoftwareVersion 1234 1 0
- - ## List of commands ### `ble-adapter-print` diff --git a/docs/guides/simulated_device_linux.md b/docs/guides/simulated_device_linux.md index 5bbd5f2b6452cf..2594657b299cf7 100644 --- a/docs/guides/simulated_device_linux.md +++ b/docs/guides/simulated_device_linux.md @@ -2,7 +2,7 @@ This document contains instructions on how to build, run, and interact with a simulated device. All virtual accessories live in -[examples/placeholder/linux/apps](../../examples/placeholder/linux/apps). +[examples/placeholder/linux/apps](https://github.com/project-chip/connectedhomeip/tree/master/examples/placeholder/linux/apps). Each accessory needs to be hosted into a subfolder. It will be the name of the application. For example `app1` will create a binary named `chip-app1`. @@ -86,7 +86,7 @@ Now that the building the app and starting it is complete, you will be able to interact with it using chip-tool 1. Follow the instruction to build chip-tool in the - [chip-tool readme](../../examples/chip-tool). + [chip-tool readme](../../examples/chip-tool/README.md). 2. Run this command to initiate the pairing. ``` @@ -105,7 +105,7 @@ interact with it using chip-tool ./out/debug/standalone/chip-tool onoff write on-time 1 0x654321 1 ``` - See [chip-tool readme](../../examples/chip-tool) for additional commands. + See [chip-tool readme](../../examples/chip-tool/README.md) for additional commands. ## Adding simulated Tests via YAML diff --git a/docs/index.md b/docs/index.md index 56ad7ba3354a9b..2058b1df9e99c3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,13 +4,14 @@ :maxdepth: 2 :caption: Contents -quick_start -project_flow -vscode_development +QUICK_START +PROJECT_FLOW +VSCODE_DEVELOPMENT api/index discussion/index guides/index style/index examples/index breathe +BUG_REPORT ``` diff --git a/docs/make.bat b/docs/make.bat index 73ebcf03f5577d..9ae01a5a9afa4a 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -26,6 +26,7 @@ if errorlevel 9009 ( exit /b 1 ) +mkdir %SOURCEDIR% %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% goto end diff --git a/examples/all-clusters-app/cc13x2x7_26x2x7/README.md b/examples/all-clusters-app/cc13x2x7_26x2x7/README.md index fd2d0ee9c07cbb..9fbd50f9bbb560 100644 --- a/examples/all-clusters-app/cc13x2x7_26x2x7/README.md +++ b/examples/all-clusters-app/cc13x2x7_26x2x7/README.md @@ -19,14 +19,13 @@ Instruments CC13XX_26XX family of Wireless MCUs. - [Provisioning](#provisioning) - [Bluetooth LE Advertising](#bluetooth-le-advertising) - [Bluetooth LE Rendezvous](#bluetooth-le-rendezvous) - - [Matter Remote Commands](#matter-remote-commands) - [TI Support](#ti-support) --- ## Introduction -![CC1352R1_LAUNCHXL](doc/images/cc1352r1_launchxl.jpg) +![CC1352R1_LAUNCHXL](../../pump-app/cc13x2x7_26x2x7/doc/images/cc1352r1_launchxl.jpg) The CC13XX_26XX all clusters example application provides the basis to query and run commands for all currently implemented Matter clusters. This uses the @@ -212,10 +211,10 @@ fully provisioned, BLE advertising will stop. #### Bluetooth LE Rendezvous Pairing this application with `ble-thread` can be done with any of the enabled -[CHIP Controller](../../../src/controller/README.md) applications. Use the -information printed on the console to aide in pairing the device. The controller -application can also be used to control the example app with the cluster -commands. +[CHIP Controller](https://github.com/project-chip/connectedhomeip/blob/master/src/controller/README.md) +applications. Use the information printed on the console to aide in pairing the +device. The controller application can also be used to control the example app +with the cluster commands. ## TI Support diff --git a/examples/all-clusters-app/infineon/psoc6/README.md b/examples/all-clusters-app/infineon/psoc6/README.md index 8fed8d3ca41148..c347753b7a3cd1 100644 --- a/examples/all-clusters-app/infineon/psoc6/README.md +++ b/examples/all-clusters-app/infineon/psoc6/README.md @@ -1,10 +1,10 @@ -# CHIP P6 All Clusters Example +# CHIP PSoC6 All Clusters Example An example showing the use of Matter on the Infineon CY8CKIT-062S2-43012 board.
-- [Matter PSoC6 All Clusters Example](#chip-p6-all-clusters-example) +- [Matter PSoC6 All Clusters Example](#chip-psoc6-all-clusters-example) - [Introduction](#introduction) - [Building](#building) - [Flashing the Application](#flashing-the-application) diff --git a/examples/all-clusters-app/mbed/README.md b/examples/all-clusters-app/mbed/README.md index 5ee74dd6ec4eaa..fbce644ef4ae1a 100644 --- a/examples/all-clusters-app/mbed/README.md +++ b/examples/all-clusters-app/mbed/README.md @@ -95,7 +95,7 @@ its requirements. > devcontainer is the recommended way to interact with Arm Mbed-OS port of the > Matter Project.** > -> **Please read this [README.md](../../..//docs/VSCODE_DEVELOPMENT.md) for more +> **Please read this [README.md](../../../docs/VSCODE_DEVELOPMENT.md) for more > information about using VSCode in container.** To initialize the development environment, download all registered sub-modules @@ -131,7 +131,7 @@ ${MATTER_ROOT}/scripts/examples/mbed_example.sh -c=build -a=all-clusters-app -b= ``` Both approaches are limited to supported evaluation boards which are listed in -[Supported devices](#supported_devices) paragraph. +[Supported devices](#supported-devices) paragraph. Mbed OS defines three building profiles: _develop, debug_ and _release_. For more details please visit @@ -273,5 +273,5 @@ following states are possible: Some of the supported boards may not have sufficient number PCB components to follow above description. In that case please refer to -[Supported devices](#Supported-devices) section and check board's 'Platform -components' column for additional information about the limitation. +[Supported devices](#supported-devices) section and check board's 'Platform +components' column f-r additional information about the limitation. diff --git a/examples/all-clusters-app/nrfconnect/README.md b/examples/all-clusters-app/nrfconnect/README.md index 101c286e304088..52537ab2448e89 100644 --- a/examples/all-clusters-app/nrfconnect/README.md +++ b/examples/all-clusters-app/nrfconnect/README.md @@ -23,7 +23,7 @@ device works as a Thread Minimal End Device. - [Bluetooth LE advertising](#bluetooth-le-advertising) - [Bluetooth LE rendezvous](#bluetooth-le-rendezvous) - [Requirements](#requirements) - - [Supported devices](#supported_devices) + - [Supported devices](#supported-devices) - [Device UI](#device-ui) - [Setting up the environment](#setting-up-the-environment) - [Using Docker container for setup](#using-docker-container-for-setup) @@ -31,20 +31,17 @@ device works as a Thread Minimal End Device. - [Building](#building) - [Removing build artifacts](#removing-build-artifacts) - [Building with release configuration](#building-with-release-configuration) - - [Building with low-power configuration](#building-with-low-power-configuration) - [Building with Device Firmware Upgrade support](#building-with-device-firmware-upgrade-support) - [Configuring the example](#configuring-the-example) - [Example build types](#example-build-types) - [Flashing and debugging](#flashing-and-debugging) - - [Flashing on the development kits](#nrfdks_flashing) - - [Flashing on the nRF52840 Dongle](#nrf52840dongle_flashing) + - [Flashing on the development kits](#flashing-on-the-development-kits) + - [Flashing on the nRF52840 Dongle](#flashing-on-the-nrf52840-dongle) - [Testing the example](#testing-the-example) - [Testing using CHIPTool](#testing-using-chiptool)
- - ## Overview This example is running on the nRF Connect platform, which is based on Nordic @@ -85,16 +82,12 @@ with other Thread devices in the network.
- - ## Requirements The application requires a specific revision of the nRF Connect SDK to work correctly. See [Setting up the environment](#setting-up-the-environment) for more information. - - ### Supported devices The example supports building and running on the following devices: @@ -107,8 +100,6 @@ The example supports building and running on the following devices:
- - ## Device UI This section lists the User Interface elements that you can use to control and @@ -172,7 +163,7 @@ image that has the tools pre-installed. If you are a macOS user, you won't be able to use the Docker container to flash the application onto a Nordic development kit due to [certain limitations of Docker for macOS](https://docs.docker.com/docker-for-mac/faqs/#can-i-pass-through-a-usb-device-to-a-container). -Use the [native shell](#using-native-shell) for building instead. +Use the [native shell](#using-native-shell-for-setup) for building instead. ### Using Docker container for setup @@ -255,8 +246,6 @@ Now you can proceed with the [Building](#building) instruction.
- - ## Building Complete the following steps, regardless of the method used for setting up the @@ -336,8 +325,6 @@ example `nrf52840dk_nrf52840`), edit the `pm_static_dfu.yml` file located in the
- - ## Configuring the example The Zephyr ecosystem is based on Kconfig files and the settings can be modified @@ -388,15 +375,11 @@ page.
- - ## Flashing and debugging The flashing and debugging procedure is different for the development kits and the nRF52840 Dongle. - - ### Flashing on the development kits To flash the application to the device, use the west tool and run the following @@ -412,8 +395,6 @@ directory: $ west debug - - ### Flashing on the nRF52840 Dongle Visit diff --git a/examples/all-clusters-app/nxp/mw320/README.md b/examples/all-clusters-app/nxp/mw320/README.md index 95905446be40e3..581ae9bc330b49 100755 --- a/examples/all-clusters-app/nxp/mw320/README.md +++ b/examples/all-clusters-app/nxp/mw320/README.md @@ -11,12 +11,9 @@ to demonstrates device commissioning and cluster control over a low-power, WiFi - [Introduction](#introduction) - [Building](#building) - [Flashing](#flashing) -- [Testing the example](#testing-the-example)
- - ## Introduction ![MW320](../../../platform/nxp/mw320/doc/images/mw320.jpg) @@ -25,8 +22,6 @@ The example targets the [NXP MW320 WiFi Micro controller Soc](https://www.nxp.com/products/wireless/wi-fi-plus-bluetooth/88mw32x-802-11n-wi-fi-microcontroller-soc:88MW32X) development kit. - - ## Building Building the example application is quite straightforward. It can be done via @@ -59,8 +54,6 @@ In order to use the tinycrypt ecc operations, use the following build arguments: $ gn gen out/debug --args='treat_warnings_as_errors=false mbedtls_repo="//third_party/connectedhomeip/third_party/nxp/libs/mbedtls" mbedtls_use_tinycrypt=true' ``` - - ## Flashing Connect MW320 to Ubuntu USB port and open Linux text-based serial port diff --git a/examples/all-clusters-minimal-app/cc13x2x7_26x2x7/README.md b/examples/all-clusters-minimal-app/cc13x2x7_26x2x7/README.md index c23cf324afe8af..fdc2199f0b3bc2 100644 --- a/examples/all-clusters-minimal-app/cc13x2x7_26x2x7/README.md +++ b/examples/all-clusters-minimal-app/cc13x2x7_26x2x7/README.md @@ -19,14 +19,13 @@ Instruments CC13XX_26XX family of Wireless MCUs. - [Provisioning](#provisioning) - [Bluetooth LE Advertising](#bluetooth-le-advertising) - [Bluetooth LE Rendezvous](#bluetooth-le-rendezvous) - - [Matter Remote Commands](#matter-remote-commands) - [TI Support](#ti-support) --- ## Introduction -![CC1352R1_LAUNCHXL](doc/images/cc1352r1_launchxl.jpg) +![CC1352R1_LAUNCHXL](../../pump-app/cc13x2x7_26x2x7/doc/images/cc1352r1_launchxl.jpg) The CC13XX_26XX all clusters example application provides the basis to query and run commands for all currently implemented Matter clusters. This uses the diff --git a/examples/all-clusters-minimal-app/infineon/psoc6/README.md b/examples/all-clusters-minimal-app/infineon/psoc6/README.md index 1f7a40ef9b28ac..f4b65b26eb9206 100644 --- a/examples/all-clusters-minimal-app/infineon/psoc6/README.md +++ b/examples/all-clusters-minimal-app/infineon/psoc6/README.md @@ -1,10 +1,10 @@ -#CHIP PSoC6 All Clusters Example +# CHIP PSoC6 All Clusters Example An example showing the use of Matter on the Infineon CY8CKIT-062S2-43012 board.
-- [Matter PSoC6 All Clusters Example](#chip-psoc6-clusters-example) +- [Matter PSoC6 All Clusters Example](#chip-psoc6-all-clusters-example) - [Introduction](#introduction) - [Building](#building) - [Flashing the Application](#flashing-the-application) @@ -16,8 +16,6 @@ An example showing the use of Matter on the Infineon CY8CKIT-062S2-43012 board.
- - ## Introduction The PSoC6 clusters example provides a baseline demonstration of a Cluster @@ -29,8 +27,6 @@ and the Matter controller will exchange security information with the Rendezvous procedure. Wi-Fi Network credentials are then provided to the PSoC6 device which will then join the network. - - ## Building - [Modustoolbox Software](https://www.cypress.com/products/modustoolbox) @@ -61,8 +57,6 @@ will then join the network. $ cd ~/connectedhomeip $ rm -rf out/ - - ## Flashing the Application - Put CY8CKIT-062S2-43012 board on KitProg3 CMSIS-DAP Mode by pressing the @@ -74,14 +68,10 @@ will then join the network. $ cd ~/connectedhomeip $ python3 out/infineon-psoc6-all-clusters-minimal/chip-psoc6-clusters-minimal-example.flash.py - - ## Commissioning and cluster control Commissioning can be carried out using BLE. - - ### Setting up Chip tool Once PSoC6 is up and running, we need to set up chip-tool on Raspberry Pi 4 to @@ -96,8 +86,6 @@ perform commissioning and cluster control. $ ./out/debug/chip-tool - - ### Commissioning over BLE Run the built executable and pass it the discriminator and pairing code of the @@ -112,8 +100,6 @@ remote device, as well as the network credentials to use. 4. SSID : Wi-Fi SSID 5. PASSWORD : Wi-Fi Password - - #### Notes Raspberry Pi 4 BLE connection issues can be avoided by running the following diff --git a/examples/all-clusters-minimal-app/mbed/README.md b/examples/all-clusters-minimal-app/mbed/README.md index e5f0ef2233eb3c..6b50aebf72e497 100644 --- a/examples/all-clusters-minimal-app/mbed/README.md +++ b/examples/all-clusters-minimal-app/mbed/README.md @@ -1,6 +1,6 @@ ![ARM Mbed-OS logo](https://raw.githubusercontent.com/ARMmbed/mbed-os/master/logo.png) -

Matter Arm Mbed OS All Clusters Example Application

+# Matter Arm Mbed OS All Clusters Example Application The Arm Mbed OS All Clusters Example demonstrates device commissioning process and all available clusters control. @@ -95,7 +95,7 @@ its requirements. > devcontainer is the recommended way to interact with Arm Mbed-OS port of the > Matter Project.** > -> **Please read this [README.md](../../..//docs/VSCODE_DEVELOPMENT.md) for more +> **Please read this [README.md](../../../docs/VSCODE_DEVELOPMENT.md) for more > information about using VSCode in container.** To initialize the development environment, download all registered sub-modules @@ -131,7 +131,7 @@ ${MATTER_ROOT}/scripts/examples/mbed_example.sh -c=build -a=all-clusters-minimal ``` Both approaches are limited to supported evaluation boards which are listed in -[Supported devices](#supported_devices) paragraph. +[Supported devices](#supported-devices) paragraph. Mbed OS defines three building profiles: _develop, debug_ and _release_. For more details please visit @@ -273,5 +273,5 @@ following states are possible: Some of the supported boards may not have sufficient number PCB components to follow above description. In that case please refer to -[Supported devices](#Supported-devices) section and check board's 'Platform +[Supported devices](#supported-devices) section and check board's 'Platform components' column for additional information about the limitation. diff --git a/examples/all-clusters-minimal-app/nrfconnect/README.md b/examples/all-clusters-minimal-app/nrfconnect/README.md index 909b3d5b8861cd..e1e6f7a947a31a 100644 --- a/examples/all-clusters-minimal-app/nrfconnect/README.md +++ b/examples/all-clusters-minimal-app/nrfconnect/README.md @@ -23,7 +23,7 @@ device works as a Thread Minimal End Device. - [Bluetooth LE advertising](#bluetooth-le-advertising) - [Bluetooth LE rendezvous](#bluetooth-le-rendezvous) - [Requirements](#requirements) - - [Supported devices](#supported_devices) + - [Supported devices](#supported-devices) - [Device UI](#device-ui) - [Setting up the environment](#setting-up-the-environment) - [Using Docker container for setup](#using-docker-container-for-setup) @@ -31,20 +31,17 @@ device works as a Thread Minimal End Device. - [Building](#building) - [Removing build artifacts](#removing-build-artifacts) - [Building with release configuration](#building-with-release-configuration) - - [Building with low-power configuration](#building-with-low-power-configuration) - [Building with Device Firmware Upgrade support](#building-with-device-firmware-upgrade-support) - [Configuring the example](#configuring-the-example) - [Example build types](#example-build-types) - [Flashing and debugging](#flashing-and-debugging) - - [Flashing on the development kits](#nrfdks_flashing) - - [Flashing on the nRF52840 Dongle](#nrf52840dongle_flashing) + - [Flashing on the development kits](#flashing-on-the-development-kits) + - [Flashing on the nRF52840 Dongle](#flashing-on-the-nrf52840-dongle) - [Testing the example](#testing-the-example) - [Testing using CHIPTool](#testing-using-chiptool)
- - ## Overview This example is running on the nRF Connect platform, which is based on Nordic @@ -85,16 +82,12 @@ with other Thread devices in the network.
- - ## Requirements The application requires a specific revision of the nRF Connect SDK to work correctly. See [Setting up the environment](#setting-up-the-environment) for more information. - - ### Supported devices The example supports building and running on the following devices: @@ -107,8 +100,6 @@ The example supports building and running on the following devices:
- - ## Device UI This section lists the User Interface elements that you can use to control and @@ -172,7 +163,7 @@ image that has the tools pre-installed. If you are a macOS user, you won't be able to use the Docker container to flash the application onto a Nordic development kit due to [certain limitations of Docker for macOS](https://docs.docker.com/docker-for-mac/faqs/#can-i-pass-through-a-usb-device-to-a-container). -Use the [native shell](#using-native-shell) for building instead. +Use the [native shell](#using-native-shell-for-setup) for building instead. ### Using Docker container for setup @@ -255,8 +246,6 @@ Now you can proceed with the [Building](#building) instruction.
- - ## Building Complete the following steps, regardless of the method used for setting up the @@ -336,8 +325,6 @@ example `nrf52840dk_nrf52840`), edit the `pm_static_dfu.yml` file located in the
- - ## Configuring the example The Zephyr ecosystem is based on Kconfig files and the settings can be modified @@ -388,15 +375,11 @@ page.
- - ## Flashing and debugging The flashing and debugging procedure is different for the development kits and the nRF52840 Dongle. - - ### Flashing on the development kits To flash the application to the device, use the west tool and run the following @@ -412,8 +395,6 @@ directory: $ west debug - - ### Flashing on the nRF52840 Dongle Visit diff --git a/examples/bridge-app/linux/README.md b/examples/bridge-app/linux/README.md index 9960be56f504a3..83ac848871af20 100644 --- a/examples/bridge-app/linux/README.md +++ b/examples/bridge-app/linux/README.md @@ -9,14 +9,12 @@ Raspberry Pi Desktop 20.10 (aarch64)**
- [CHIP Linux Bridge Example](#chip-linux-bridge-example) - - [Theory of Operation](#operation) + - [Theory of Operation](#theory-of-operation) - [Building](#building) - - [Running the Complete Example on Raspberry Pi 4](#running-complete-example) + - [Running the Complete Example on Raspberry Pi 4](#running-the-complete-example-on-raspberry-pi-4)
- - ## Theory of Operation ### Dynamic Endpoints @@ -106,8 +104,6 @@ the `Bridged Device Basic` cluster, the `reachable` attribute is simulated. In the `Fixed Label` cluster, the `LabelList` attribute is simulated with the value/label pair `"room"`/`[light name]`. - - ## Building - Install tool chain @@ -133,8 +129,6 @@ value/label pair `"room"`/`[light name]`. $ rm -rf out/ ``` - - ## Running the Complete Example on Raspberry Pi 4 - Prerequisites diff --git a/examples/chef/sample_app_util/README.md b/examples/chef/sample_app_util/README.md index 041f9462c4232c..4a2bb989d86099 100644 --- a/examples/chef/sample_app_util/README.md +++ b/examples/chef/sample_app_util/README.md @@ -2,8 +2,6 @@ ## Overview ---- - It is convenient to follow some naming and build conventions for Chef tool due to the large volume of sample apps that may be created and the ambiguity that may result from arbitrary names. @@ -22,8 +20,6 @@ The convention proposed here should be adopted by the zap files provided in ## Limitations ---- - The largest filename that can be used on MacOS and Linux is 255 characters. If a sample app name would exceed this limit by following this convention, then the sample app should be given an arbitrary name. @@ -33,8 +29,6 @@ should rarely happen. ## Convention ---- - ### Sample App Naming Convention Sample apps should be named by concatenating the name of all endpoints in the @@ -144,7 +138,7 @@ The metadata files have a structure as follows: - : ... ``` -For an example, see [sample_zap_file.yaml](test_files/sample_zap_file.yaml) +For an example, see [sample_zap_file_hashmeta.yaml](test_files/sample_zap_file_hashmeta.yaml) which was generated from [sample_zap_file.zap](test_files/sample_zap_file.zap). Note that it is more readable in `yaml` format. Since hashes are generated from @@ -166,8 +160,6 @@ As an example, take a look at ## Utility Usage ---- - There are a few primary usage cases for the utility [sample_app_util.py](sample_app_util.py). Details are provided by using `python sample_app_util.py zap --help`. Below is a summary. @@ -180,8 +172,6 @@ There are a few primary usage cases for the utility ## Running Tests ---- - Navigate to the base directory of this README. ``` diff --git a/examples/chip-tool/README.md b/examples/chip-tool/README.md index 3385e7c7c36cdc..1666545c7863dc 100644 --- a/examples/chip-tool/README.md +++ b/examples/chip-tool/README.md @@ -5,7 +5,7 @@ An example application that uses Matter to send messages to a Matter server. --- - [Building the Example Application](#building-the-example-application) -- [Using the Client to Request an Echo](#using-the-client-to-request-an-echo) +- [Using the Client to Commission a Device](#using-the-client-to-commission-a-device) --- diff --git a/examples/common/README.md b/examples/common/README.md index 5f0f8790a26241..252f75f2732760 100644 --- a/examples/common/README.md +++ b/examples/common/README.md @@ -1,3 +1,7 @@ +--- +orphan: true +--- + # Examples common libraries ## What is this? diff --git a/examples/common/pigweed/rpc_console/README.md b/examples/common/pigweed/rpc_console/README.md index d433631b9e12d1..4b4ceed7bc1f00 100644 --- a/examples/common/pigweed/rpc_console/README.md +++ b/examples/common/pigweed/rpc_console/README.md @@ -1,3 +1,7 @@ +--- +orphan: true +--- + # CHIP RPC CONSOLE This python application provides a console for interacting with rpc-enabled chip diff --git a/examples/common/screen-framework/README.md b/examples/common/screen-framework/README.md index e4792fdc59ee5c..81e9151e3a9844 100644 --- a/examples/common/screen-framework/README.md +++ b/examples/common/screen-framework/README.md @@ -1,3 +1,7 @@ +--- +orphan: true +--- + # Simple Screen UI Framework ## Overview diff --git a/examples/common/tracing/README.md b/examples/common/tracing/README.md index 154054bf514163..9b3c5392bd4a74 100644 --- a/examples/common/tracing/README.md +++ b/examples/common/tracing/README.md @@ -1,3 +1,7 @@ +--- +orphan: true +--- + # Trace Handlers These are trace message handlers which get registered with pw_trace_chip and diff --git a/examples/darwin-framework-tool/README.md b/examples/darwin-framework-tool/README.md index 7da06958ae5ac1..4b8b2d29ac7658 100644 --- a/examples/darwin-framework-tool/README.md +++ b/examples/darwin-framework-tool/README.md @@ -8,7 +8,7 @@ found at [code-signing](https://developer.apple.com/support/code-signing/). --- - [Building the Example Application](#building-the-example-application) -- [Using the Client to Request an Echo](#using-the-client-to-request-an-echo) +- [Using the Client to Commission a Device](#using-the-client-to-commission-a-device) --- diff --git a/examples/light-switch-app/efr32/README.md b/examples/light-switch-app/efr32/README.md index b30234be2c3def..64a9a225c19175 100644 --- a/examples/light-switch-app/efr32/README.md +++ b/examples/light-switch-app/efr32/README.md @@ -7,7 +7,6 @@ An example showing the use of CHIP on the Silicon Labs EFR32 MG12. - [CHIP EFR32 Light Switch Example](#chip-efr32-light-switch-example) - [Introduction](#introduction) - [Building](#building) - - [Note](#note) - [Flashing the Application](#flashing-the-application) - [Viewing Logging Output](#viewing-logging-output) - [Running the Complete Example](#running-the-complete-example) @@ -18,8 +17,6 @@ An example showing the use of CHIP on the Silicon Labs EFR32 MG12.
- - ## Introduction The EFR32 light switch example provides a baseline demonstration of a on-off @@ -38,8 +35,6 @@ The light switch example is intended to serve both as a means to explore the workings of CHIP as well as a template for creating real products based on the Silicon Labs platform. - - ## Building - Download the @@ -130,15 +125,11 @@ Silicon Labs platform. $ gn gen out/debug --args='import("//with_pw_rpc.gni")' $ ninja -C out/debug - [Running Pigweed RPC console](#running-pigweed-rpc-console) - For more build options, help is provided when running the build script without arguments ./scripts/examples/gn_efr32_example.sh - - ## Flashing the Application - On the command line: @@ -148,8 +139,6 @@ arguments - Or with the Ozone debugger, just load the .out file. - - ## Viewing Logging Output The example application is built to use the SEGGER Real Time Transfer (RTT) @@ -198,8 +187,6 @@ combination with JLinkRTTClient as follows: $ JLinkRTTClient - - ## Running the Complete Example - It is assumed here that you already have an OpenThread border router @@ -334,8 +321,6 @@ combination with JLinkRTTClient as follows: #Add Ipv6 route on PC(Linux) \$ sudo ip route add /64 via 2002::2 - - ## Running RPC console - As part of building the example with RPCs enabled the chip_rpc python diff --git a/examples/light-switch-app/esp32/README.md b/examples/light-switch-app/esp32/README.md index 43a9d9536b75db..ab5c0b32aa2208 100644 --- a/examples/light-switch-app/esp32/README.md +++ b/examples/light-switch-app/esp32/README.md @@ -2,17 +2,69 @@ This example demonstrates the Matter Light-switch application on ESP platforms. -Please -[setup ESP-IDF and CHIP Environment](../../../docs/guides/esp32/setup_idf_chip.md) -and refer -[building and commissioning](../../../docs/guides/esp32/build_app_and_commission.md) -guides to get started. +--- + +- [Matter ESP32 Light-switch Example](#matter-esp32-light-switch-example) + - [Supported Devices](#supported-devices) + - [Building the Example Application](#building-the-example-application) + - [Commissioning over BLE using chip-tool](#commissioning-over-ble-using-chip-tool) + - [Testing the example](#testing-the-example) --- - [Testing the example](#testing-the-example) ---- + It is recommended to have Ccache installed for faster builds + + ``` + $ export IDF_CCACHE_ENABLE=1 + ``` + +- Target Set + + $ idf.py set-target esp32 + or + $ idf.py set-target esp32c3 + or + $ idf.py set-target esp32s3 + +- To build the demo application. + + $ idf.py build + +- After building the application, to flash it outside of VSCode, connect your + device via USB. Then run the following command to flash the demo application + onto the device and then monitor its output. If necessary, replace + `/dev/tty.SLAB_USBtoUART`(MacOS) with the correct USB device name for your + system(like `/dev/ttyUSB0` on Linux). Note that sometimes you might have to + press and hold the `boot` button on the device while it's trying to connect + before flashing. + + $ idf.py -p /dev/tty.SLAB_USBtoUART flash monitor + + Note: Some users might have to install the + [VCP driver](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers) + before the device shows up on `/dev/tty`. + +- Quit the monitor by hitting `Ctrl+]`. + + Note: You can see a menu of various monitor commands by hitting + `Ctrl+t Ctrl+h` while the monitor is running. + +- If desired, the monitor can be run again like so: + + $ idf.py -p /dev/tty.SLAB_USBtoUART monitor + +## Commissioning over BLE using chip-tool + +- Please build the standalone chip-tool as described [here](../../chip-tool/README.md) +- Commissioning the Lighting device + + $ ./out/debug/chip-tool pairing ble-wifi 12344321 20202021 3840 + +- Commissioning the Lighting-switch device + + $ ./out/debug/chip-tool pairing ble-wifi 12344320 20202021 3840 ## Testing the example diff --git a/examples/light-switch-app/nrfconnect/README.md b/examples/light-switch-app/nrfconnect/README.md index a40ed845742c0c..b4092936eed53d 100644 --- a/examples/light-switch-app/nrfconnect/README.md +++ b/examples/light-switch-app/nrfconnect/README.md @@ -8,10 +8,8 @@ switch uses buttons to test changing the lighting application example LED state and works as a brightness dimmer. You can use this example as a reference for creating your own application. -

- Nordic Semiconductor logo - nRF52840 DK -

+Nordic Semiconductor logo +nRF52840 DK The example is based on [Matter](https://github.com/project-chip/connectedhomeip) and Nordic @@ -29,7 +27,7 @@ device works as a Thread Sleepy End Device. - [Bluetooth LE rendezvous](#bluetooth-le-rendezvous) - [Device Firmware Upgrade](#device-firmware-upgrade) - [Requirements](#requirements) - - [Supported devices](#supported_devices) + - [Supported devices](#supported-devices) - [Device UI](#device-ui) - [LEDs](#leds) - [Buttons](#buttons) @@ -40,19 +38,16 @@ device works as a Thread Sleepy End Device. - [Building](#building) - [Removing build artifacts](#removing-build-artifacts) - [Building with release configuration](#building-with-release-configuration) - - [Building with low-power configuration](#building-with-low-power-configuration) - [Building with Device Firmware Upgrade support](#building-with-device-firmware-upgrade-support) - [Configuring the example](#configuring-the-example) - [Example build types](#example-build-types) - [Flashing and debugging](#flashing-and-debugging) - [Testing the example](#testing-the-example) - - [Binding process](#binding-process) + - [Binding process](#binding-cluster-and-endpoints) - [Testing Device Firmware Upgrade](#testing-device-firmware-upgrade)
- - ## Overview This example is running on the nRF Connect platform, which is based on Nordic @@ -189,16 +184,12 @@ section to learn how to change MCUboot and flash configuration in this example.
- - ## Requirements The application requires a specific revision of the nRF Connect SDK to work correctly. See [Setting up the environment](#setting-up-the-environment) for more information. - - ### Supported devices The example supports building and running on the following devices: @@ -222,8 +213,6 @@ CHIP Tool.
- - ## Device UI This section lists the User Interface elements that you can use to control and @@ -285,11 +274,11 @@ platform image. **Button 2** can be used for the following purposes: - _Pressed once_ — Changes the light state to the opposite one on a - bound lighting bulb device ([lighting-app](../../lighting-app/nrfconnect/) + bound lighting bulb device ([lighting-app](../../lighting-app/nrfconnect/README.md) example). - _Pressed for more than 2 s_ — Changes the brightness of the light on a - bound lighting bulb device ([lighting-app](../../lighting-app/nrfconnect/) + bound lighting bulb device ([lighting-app](../../lighting-app/nrfconnect/README.md) example) (dimmer functionality). The brightness is changing from 0% to 100% with 1% increments every 300 milliseconds as long as **Button 2** is pressed. @@ -356,7 +345,7 @@ image that has the tools pre-installed. If you are a macOS user, you won't be able to use the Docker container to flash the application onto a Nordic development kit due to [certain limitations of Docker for macOS](https://docs.docker.com/docker-for-mac/faqs/#can-i-pass-through-a-usb-device-to-a-container). -Use the [native shell](#using-native-shell) for building instead. +Use the [native shell](#using-native-shell-for-setup) for building instead. ### Using Docker container for setup @@ -439,8 +428,6 @@ Now you can proceed with the [Building](#building) instruction.
- - ## Building Complete the following steps, regardless of the method used for setting up the @@ -529,8 +516,6 @@ example `nrf52840dk_nrf52840`), edit the `pm_static_dfu.yml` file located in the
- - ## Configuring the example The Zephyr ecosystem is based on Kconfig files and the settings can be modified @@ -579,8 +564,6 @@ page.
- - ## Flashing and debugging To flash the application to the device, use the west tool and run the following @@ -598,13 +581,11 @@ directory:
- - ## Testing the example After building and flashing the example, you can test its functionalities. For this purpose, you need to prepare a second device that is programmed with the -[Lighting Example](../../lighting-app/nrfconnect/), perform the binding process, +[Lighting Example](../../lighting-app/nrfconnect/README.md), perform the binding process, and add Access Control Lists (ACLs). ### Commissioning the lighting device @@ -619,12 +600,14 @@ communicate with each other. To perform binding, you need a controller that can write the binding table to the light switch device and write proper ACL to the endpoint light bulb on the -[Lighting Example application](../../lighting-app/nrfconnect/)). For example, -you can use the [CHIP Tool for Windows or Linux](../../chip-tool/README.md) as -the controller. The ACL should contain information about all clusters that can -be called by the light switch application. See the section about -[interacting with ZCL clusters](../../../docs/guides/chip_tool_guide.md#interacting-with-zcl-clusters) -in the CHIP Tool's user guide for more information about ACLs. +[Lighting Example application](../../lighting-app/nrfconnect/README.md)). For +example, you can use the +[CHIP Tool for Windows or Linux](../../chip-tool/README.md) as the controller. +The ACL should contain information about all clusters that can +be called by the light switch application. See the section about interacting +with ZCL clusters in the +[CHIP Tool's user guide](../../../docs/guides/chip_tool_guide.md#interacting-with-zcl-clusters) +for more information about ACLs. You can perform the binding process to a single remote endpoint (unicast binding) or to a group of remote endpoints (group multicast). @@ -644,7 +627,7 @@ To perform the unicast binding process, complete the following steps: [CHIP Tool user guide](../../../docs/guides/chip_tool_guide.md#building). 2. Go to the CHIP Tool build directory. 3. Add an ACL to the development kit that is programmed with the - [Lighting Application Example](../../lighting-app/nrfconnect/) by running + [Lighting Application Example](../../lighting-app/nrfconnect/README.md) by running the following command: chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": [2], "targets": [{"cluster": 6, "endpoint": 1, "deviceType": null}, {"cluster": 8, "endpoint": 1, "deviceType": null}]}]' 1 0 @@ -681,7 +664,7 @@ The group multicast binding lets you control more than one lighting device at a time using a single light switch. The group multicast binding targets all development kits that are programmed -with the [Lighting Application Example](../../lighting-app/nrfconnect/) and +with the [Lighting Application Example](../../lighting-app/nrfconnect/README.md) and added to the same multicast group. After the binding is established, the light switch device can send multicast requests, and all of the devices in the bound groups can run the received command. @@ -695,7 +678,7 @@ To perform the unicast binding process, complete the following steps: 1. Build the CHIP Tool according to the steps from the [CHIP Tool user guide](../../../docs/guides/chip_tool_guide.md#building). 2. Go to the CHIP Tool build directory. -3. Add an ACL to the [lighting endpoint](../../lighting-app/nrfconnect/) +3. Add an ACL to the [lighting endpoint](../../lighting-app/nrfconnect/README.md) permissions by running the following command: chip-tool accesscontrol write acl '[{"fabricIndex": 1, "privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"fabricIndex": 1, "privilege": 3, "authMode": 2, "subjects": [2], "targets": [{"cluster": 6, "endpoint": 1, "deviceType": null}, {"cluster": 8, "endpoint": 1, "deviceType": null}]}]' 1 0 diff --git a/examples/light-switch-app/telink/Readme.md b/examples/light-switch-app/telink/README.md similarity index 100% rename from examples/light-switch-app/telink/Readme.md rename to examples/light-switch-app/telink/README.md diff --git a/examples/lighting-app/efr32/README.md b/examples/lighting-app/efr32/README.md index 7cb0ea4878f601..d4d815f18c60f1 100644 --- a/examples/lighting-app/efr32/README.md +++ b/examples/lighting-app/efr32/README.md @@ -7,7 +7,6 @@ An example showing the use of CHIP on the Silicon Labs EFR32 MG12. - [CHIP EFR32 Lighting Example](#chip-efr32-lighting-example) - [Introduction](#introduction) - [Building](#building) - - [Note](#note) - [Flashing the Application](#flashing-the-application) - [Viewing Logging Output](#viewing-logging-output) - [Running the Complete Example](#running-the-complete-example) @@ -19,8 +18,6 @@ An example showing the use of CHIP on the Silicon Labs EFR32 MG12.
- - ## Introduction The EFR32 lighting example provides a baseline demonstration of a Light control @@ -39,8 +36,6 @@ The lighting example is intended to serve both as a means to explore the workings of CHIP as well as a template for creating real products based on the Silicon Labs platform. - - ## Building - Download the @@ -123,15 +118,11 @@ Silicon Labs platform. $ gn gen out/debug --args='import("//with_pw_rpc.gni")' $ ninja -C out/debug - [Running Pigweed RPC console](#running-pigweed-rpc-console) - For more build options, help is provided when running the build script without arguments ./scripts/examples/gn_efr32_example.sh - - ## Flashing the Application - On the command line: @@ -141,8 +132,6 @@ arguments - Or with the Ozone debugger, just load the .out file. - - ## Viewing Logging Output The example application is built to use the SEGGER Real Time Transfer (RTT) @@ -191,8 +180,6 @@ combination with JLinkRTTClient as follows: $ JLinkRTTClient - - ## Running the Complete Example - It is assumed here that you already have an OpenThread border router @@ -278,8 +265,6 @@ combination with JLinkRTTClient as follows: - Add Ipv6 route on PC(Linux) `sudo ip route add /64 via 2002::2` - - ## Running RPC console - As part of building the example with RPCs enabled the chip_rpc python diff --git a/examples/lighting-app/esp32/README.md b/examples/lighting-app/esp32/README.md index b84deeaf9d3fbd..ae6700b413d132 100644 --- a/examples/lighting-app/esp32/README.md +++ b/examples/lighting-app/esp32/README.md @@ -13,7 +13,53 @@ guides to get started. - [Cluster Control](#cluster-control) - [Matter OTA guide](../../../docs/guides/esp32/ota.md) ---- +- After building the application, to flash it outside of VSCode, connect your + device via USB. Then run the following command to flash the demo application + onto the device and then monitor its output. If necessary, replace + `/dev/tty.SLAB_USBtoUART`(MacOS) with the correct USB device name for your + system(like `/dev/ttyUSB0` on Linux). Note that sometimes you might have to + press and hold the `boot` button on the device while it's trying to connect + before flashing. + + $ idf.py -p /dev/tty.SLAB_USBtoUART flash monitor + + Note: Some users might have to install the + [VCP driver](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers) + before the device shows up on `/dev/tty`. + +- Quit the monitor by hitting `Ctrl+]`. + + Note: You can see a menu of various monitor commands by hitting + `Ctrl+t Ctrl+h` while the monitor is running. + +- If desired, the monitor can be run again like so: + + $ idf.py -p /dev/tty.SLAB_USBtoUART monitor + +- Commissioning over ble after flashing script, change the passcode, replace + `20202021` with `99663300`. + +## Commissioning over BLE using chip-tool + +- Please build the standalone chip-tool as described [here](../../chip-tool/README.md) +- Commissioning the WiFi Lighting devices(ESP32, ESP32C3, ESP32S3) + + $ ./out/debug/chip-tool pairing ble-wifi 12345 20202021 3840 + +- For ESP32-H2, firstly start OpenThread Border Router, you can either use + [Raspberry Pi OpenThread Border Router](https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/openthread_border_router_pi.md) + OR + [ESP32 OpenThread Border Router](https://github.com/espressif/esp-idf/tree/master/examples/openthread/ot_br) +- Get the active operational dataset. + + $ ot-ctl> dataset active -x + +- Commissioning the Thread Lighting device(ESP32H2) + + $ ./out/debug/chip-tool pairing ble-thread 12345 hex: 20202021 3840 + + NOTE: If using ESP32 factory data provider then commission the device using + discriminator and passcode provided while building the factory NVS binary. ### Cluster Control diff --git a/examples/lighting-app/infineon/psoc6/README.md b/examples/lighting-app/infineon/psoc6/README.md index c1da22ff7e7819..ea229f0f391029 100644 --- a/examples/lighting-app/infineon/psoc6/README.md +++ b/examples/lighting-app/infineon/psoc6/README.md @@ -1,10 +1,10 @@ -# CHIP P6 Lighting Example +#CHIP PSoC6 Lighting Example An example showing the use of Matter on the Infineon CY8CKIT-062S2-43012 board.
-- [Matter PSoC6 Lighting Example](#chip-p6-lighting-example) +- [Matter PSoC6 Lighting Example](#chip-psoc6-Lighting-example) - [Introduction](#introduction) - [Building](#building) - [Flashing the Application](#flashing-the-application) diff --git a/examples/lighting-app/linux/README.md b/examples/lighting-app/linux/README.md index 001c214ea6f5ed..f41a351da1bebb 100644 --- a/examples/lighting-app/linux/README.md +++ b/examples/lighting-app/linux/README.md @@ -13,15 +13,13 @@ To cross-compile this example on x64 host and run on **NXP i.MX 8M Mini** - [CHIP Linux Lighting Example](#chip-linux-lighting-example) - [Building](#building) - - [Commandline Arguments](#command-line-args) - - [Running the Complete Example on Raspberry Pi 4](#running-complete-example) + - [Commandline Arguments](#commandline-arguments) + - [Running the Complete Example on Raspberry Pi 4](#running-the-complete-example-on-raspberry-pi-4) - [Running RPC console](#running-rpc-console) - [Device Tracing](#device-tracing)
- - ## Building - Install tool chain @@ -49,8 +47,6 @@ To cross-compile this example on x64 host and run on **NXP i.MX 8M Mini** $ gn gen out/debug --args='import("//with_pw_rpc.gni")' $ ninja -C out/debug - - ## Commandline arguments - `--wifi` @@ -70,8 +66,6 @@ To cross-compile this example on x64 host and run on **NXP i.MX 8M Mini** `hciconfig` command, for example, `--ble-device 1` means using `hci1` interface. Default: `0`. - - ## Running the Complete Example on Raspberry Pi 4 > If you want to test Echo protocol, please enable Echo handler diff --git a/examples/lighting-app/mbed/README.md b/examples/lighting-app/mbed/README.md index ac436be68f4ced..01535651a62c75 100644 --- a/examples/lighting-app/mbed/README.md +++ b/examples/lighting-app/mbed/README.md @@ -146,7 +146,7 @@ ${MATTER_ROOT}/scripts/examples/mbed_example.sh -c=build -a=lighting-app -b= - - ## Overview This example is running on the nRF Connect platform, which is based on Nordic @@ -151,16 +149,12 @@ section to learn how to change MCUboot and flash configuration in this example.
- - ## Requirements The application requires a specific revision of the nRF Connect SDK to work correctly. See [Setting up the environment](#setting-up-the-environment) for more information. - - ### Supported devices The example supports building and running on the following devices: @@ -173,8 +167,6 @@ The example supports building and running on the following devices:
- - ## Device UI This section lists the User Interface elements that you can use to control and @@ -267,7 +259,7 @@ image that has the tools pre-installed. If you are a macOS user, you won't be able to use the Docker container to flash the application onto a Nordic development kit due to [certain limitations of Docker for macOS](https://docs.docker.com/docker-for-mac/faqs/#can-i-pass-through-a-usb-device-to-a-container). -Use the [native shell](#using-native-shell) for building instead. +Use the [native shell](#using-native-shell-for-setup) for building instead. ### Using Docker container for setup @@ -362,8 +354,6 @@ Now you can proceed with the [Building](#building) instruction.
- - ## Building Complete the following steps, regardless of the method used for setting up the @@ -479,8 +469,6 @@ example `nrf52840dk_nrf52840`), edit the `pm_static_dfu.yml` file located in the
- - ## Configuring the example The Zephyr ecosystem is based on Kconfig files and the settings can be modified @@ -534,15 +522,11 @@ page.
- - ## Flashing and debugging The flashing and debugging procedure is different for the development kits and the nRF52840 Dongle. - - ### Flashing on the development kits To flash the application to the device, use the west tool and run the following @@ -562,8 +546,6 @@ directory: $ west debug ``` - - ### Flashing on the nRF52840 Dongle Visit diff --git a/examples/lighting-app/nxp/k32w/k32w0/README.md b/examples/lighting-app/nxp/k32w/k32w0/README.md index 6b638d0660447a..37a54b16c10a1d 100644 --- a/examples/lighting-app/nxp/k32w/k32w0/README.md +++ b/examples/lighting-app/nxp/k32w/k32w0/README.md @@ -16,31 +16,27 @@ network.
-- [CHIP K32W061 Lighting Example Application](#chip-k32w-lighting-example-application) - +- [CHIP K32W061 Lighting Example Application](#chip-k32w061-lighting-example-application) - - [Introduction](#introduction) - [Bluetooth LE Advertising](#bluetooth-le-advertising) - [Bluetooth LE Rendezvous](#bluetooth-le-rendezvous) - [Device UI](#device-ui) - [Building](#building) -- [Flashing and debugging](#flashdebug) -- [Pigweed Tokenizer](#tokenizer) - - [Detokenizer script](#detokenizer) - - [Notes](#detokenizer-notes) - - [Known issues](#detokenizer-known-issues) -- [Tinycrypt ECC operations](#tinycrypt) - - [Building steps](#tinycrypt-building-steps) +- [Flashing and debugging](#flashing-and-debugging) +- [Pigweed Tokenizer](#pigweed-tokenizer) + - [Detokenizer script](#detokenizer-script) + - [Notes](#notes) + - [Known issues](#known-issues) +- [Tinycrypt ECC operations](#tinycrypt-ecc-operations) + - [Building steps](#building-steps) - [OTA](#ota) - - - [Writing the SSBL](#ssbl) - - [Writing the PSECT](#psect) - - [Writing the application](#appwrite) - - [OTA Testing](#otatesting) - - [Known issues](#otaissues) - + - [Writing the SSBL](#writing-the-ssbl) + - [Writing the PSECT](#writing-the-psect) + - [Writing the application](#writing-the-application) + - [OTA Testing](#ota-testing) + - [Known issues](#known-issues-1) - - ## Introduction ![K32W061 DK6](../../../../platform/nxp/k32w/k32w0/doc/images/k32w-dk6.jpg) @@ -167,8 +163,6 @@ DS3, which can be found on the DK6 board. Also, by long pressing the **USERINTERFACE** button, the factory reset action will be initiated. - - ## Building In order to build the Project CHIP example, we recommend using a Linux @@ -227,8 +221,6 @@ pycryptodome 3.9.8 The resulting output file can be found in out/debug/chip-k32w0x-light-example. - - ## Flashing and debugging Program the firmware using the official @@ -238,8 +230,6 @@ All you have to do is to replace the Openthread binaries from the above documentation with _out/debug/chip-k32w0x-light-example.bin_ if DK6Programmer is used or with _out/debug/chip-k32w0x-light-example_ if MCUXpresso is used. - - ## Pigweed tokenizer The tokenizer is a pigweed module that allows hashing the strings. This greatly @@ -247,8 +237,6 @@ reduces the flash needed for logs. The module can be enabled by building with the gn argument _chip_pw_tokenizer_logging=true_. The detokenizer script is needed for parsing the hashed scripts. - - ### Detokenizer script The python3 script detokenizer.py is a script that decodes the tokenized logs @@ -277,8 +265,6 @@ where the decoded logs will be stored. This parameter is required for file usage and optional for serial usage. If not provided when used with serial port, it will show the decoded log only at the stdout and not save it to file. - - ### Notes The token database is created automatically after building the binary if the @@ -293,8 +279,6 @@ detokenizer script to see logs of a lighting app: python3 ../../../../../examples/platform/nxp/k32w/k32w0/scripts/detokenizer.py serial -i /dev/ttyACM0 -d out/debug/chip-k32w0x-light-example-database.bin -o device.txt ``` - - ### Known issues The building process will not update the token database if it already exists. In @@ -312,12 +296,8 @@ If run, closed and rerun with the serial option on the same serial port, the detokenization script will get stuck and not show any logs. The solution is to unplug and plug the board and then rerun the script. - - ## Tinycrypt ECC operations - - ### Building steps Note: This solution is temporary. @@ -332,8 +312,6 @@ To disable tinycrypt ecc operations, simply build with _chip_crypto=\"mbedtls\"_ and with or without _mbedtls_repo_. If used with _mbedtls_repo_ the mbedtls implementation from `NXPmicro/mbedtls` library will be used. - - ## OTA The internal flash needs to be prepared for the OTA process. First 16K of the @@ -342,8 +320,6 @@ related data while the last 8.5K of flash space is holding image directory related data (PSECT). The space between these two zones will be filled by the application. - - ### Writing the SSBL The SSBL can ge generated from one of the SDK demo examples. The SDK demo @@ -373,8 +349,6 @@ k32w061dk6_ssbl.bin must be written at address 0 in the internal flash: DK6Programmer.exe -V2 -s -P 1000000 -Y -p FLASH@0x00="k32w061dk6_ssbl.bin" ``` - - ### Writing the PSECT First, image directory 0 must be written: @@ -407,8 +381,6 @@ CD04 -> 0x4CD pages of 512-bytes (= 614,5kB) 01 -> image type for the application ``` - - ### Writing the application DK6Programmer can be used for flashing the application: @@ -422,8 +394,6 @@ application. Please make sure that the application is written at address 0x4000: ![FLASH_LOCATION](../../../../platform/nxp/k32w/k32w0/doc/images/flash_location.JPG) - - ### OTA Testing The OTA topology used for OTA testing is illustrated in the figure below. @@ -501,8 +471,6 @@ Start the OTA process: doru@computer1:~/connectedhomeip$ : ./out/chip-tool-app/chip-tool otasoftwareupdaterequestor announce-ota-provider 1 0 0 0 2 0 ``` - - ## Known issues - SRP cache on the openthread border router needs to flushed each time a new diff --git a/examples/lighting-app/qpg/APPLICATION.md b/examples/lighting-app/qpg/APPLICATION.md index b3034c6389344d..e417a124f11c82 100644 --- a/examples/lighting-app/qpg/APPLICATION.md +++ b/examples/lighting-app/qpg/APPLICATION.md @@ -15,4 +15,4 @@ More detailed information on the Qorvo SDK can be found in the ## More information For more information on our product line and support options, please visit -[www.qorvo.com](www.qorvo.com) or contact us at +[www.qorvo.com](https://www.qorvo.com) or contact us at diff --git a/examples/lighting-app/telink/Readme.md b/examples/lighting-app/telink/README.md similarity index 100% rename from examples/lighting-app/telink/Readme.md rename to examples/lighting-app/telink/README.md diff --git a/examples/lock-app/cc13x2x7_26x2x7/README.md b/examples/lock-app/cc13x2x7_26x2x7/README.md index 6c457b0fabe281..3cf7acf4f68332 100644 --- a/examples/lock-app/cc13x2x7_26x2x7/README.md +++ b/examples/lock-app/cc13x2x7_26x2x7/README.md @@ -19,14 +19,13 @@ Instruments CC13XX_26XX family of Wireless MCUs. - [Provisioning](#provisioning) - [Bluetooth LE Advertising](#bluetooth-le-advertising) - [Bluetooth LE Rendezvous](#bluetooth-le-rendezvous) - - [Matter Remote Commands](#matter-remote-commands) - [TI Support](#ti-support) --- ## Introduction -![CC1352R1_LAUNCHXL](doc/images/cc1352r1_launchxl.jpg) +![CC1352R1_LAUNCHXL](../../pump-app/cc13x2x7_26x2x7/doc/images/cc1352r1_launchxl.jpg) The CC13XX_26XX lock example application provides a working demonstration of a connected door lock device. This uses the open-source Matter implementation and diff --git a/examples/lock-app/efr32/README.md b/examples/lock-app/efr32/README.md index 04bb8d9419130b..04e704f6b2d619 100644 --- a/examples/lock-app/efr32/README.md +++ b/examples/lock-app/efr32/README.md @@ -7,7 +7,6 @@ An example showing the use of CHIP on the Silicon Labs EFR32 MG12. - [CHIP EFR32 Lock Example](#chip-efr32-lock-example) - [Introduction](#introduction) - [Building](#building) - - [Note](#note) - [Flashing the Application](#flashing-the-application) - [Viewing Logging Output](#viewing-logging-output) - [Running the Complete Example](#running-the-complete-example) @@ -17,8 +16,6 @@ An example showing the use of CHIP on the Silicon Labs EFR32 MG12.
- - ## Introduction The EFR32 lock example provides a baseline demonstration of a door lock control @@ -37,8 +34,6 @@ The lighting example is intended to serve both as a means to explore the workings of CHIP as well as a template for creating real products based on the Silicon Labs platform. - - ## Building - Download the @@ -137,8 +132,6 @@ Silicon Labs platform. $ ninja -C out/debug ``` - [Running Pigweed RPC console](#running-pigweed-rpc-console) - For more build options, help is provided when running the build script without arguments @@ -146,8 +139,6 @@ arguments ./scripts/examples/gn_efr32_example.sh ``` - - ## Flashing the Application - On the command line: @@ -159,8 +150,6 @@ arguments - Or with the Ozone debugger, just load the .out file. - - ## Viewing Logging Output The example application is built to use the SEGGER Real Time Transfer (RTT) @@ -219,8 +208,6 @@ combination with JLinkRTTClient as follows: $ JLinkRTTClient ``` - - ## Running the Complete Example - It is assumed here that you already have an OpenThread border router diff --git a/examples/lock-app/infineon/psoc6/README.md b/examples/lock-app/infineon/psoc6/README.md index 5046ce5c0343c7..99d35715942980 100644 --- a/examples/lock-app/infineon/psoc6/README.md +++ b/examples/lock-app/infineon/psoc6/README.md @@ -17,8 +17,6 @@ An example showing the use of Matter on the Infineon CY8CKIT-062S2-43012 board.
- - ## Introduction The PSoC6 lock example provides a demonstration of a door lock control device, @@ -30,8 +28,6 @@ and the Matter controller will exchange security information with the Rendezvous procedure. Wi-Fi Network credentials are then provided to the PSoC6 device which will then join the network. - - ## Building - [Modustoolbox Software](https://www.cypress.com/products/modustoolbox) @@ -58,8 +54,6 @@ will then join the network. $ cd ~/connectedhomeip $ rm -rf out/ - - ## Flashing the Application - Put CY8CKIT-062S2-43012 board on KitProg3 CMSIS-DAP Mode by pressing the @@ -71,14 +65,10 @@ will then join the network. $ cd ~/connectedhomeip $ python3 out/infineon-psoc6-lock/chip-psoc6-lock-example.flash.py - - ## Commissioning and cluster control Commissioning can be carried out using BLE. - - ### Setting up Chip tool Once PSoC6 is up and running, we need to set up chip-tool on Raspberry Pi 4 to @@ -93,8 +83,6 @@ perform commissioning and cluster control. $ ./out/debug/chip-tool - - ### Commissioning over BLE Run the built executable and pass it the discriminator and pairing code of the @@ -109,8 +97,6 @@ remote device, as well as the network credentials to use. 4. SSID : Wi-Fi SSID 5. PASSWORD : Wi-Fi Password - - #### Notes Raspberry Pi 4 BLE connection issues can be avoided by running the following @@ -120,8 +106,6 @@ commands. These power cycle the BlueTooth hardware and disable BR/EDR mode. $ sudo btmgmt -i hci0 bredr off $ sudo btmgmt -i hci0 power on - - ### Cluster control - After successful commissioning, use the OnOff cluster command to toggle diff --git a/examples/lock-app/mbed/README.md b/examples/lock-app/mbed/README.md index 96564967fa1c49..5e30074bfe3e2f 100644 --- a/examples/lock-app/mbed/README.md +++ b/examples/lock-app/mbed/README.md @@ -98,7 +98,7 @@ its requirements. > devcontainer is the recommended way to interact with Arm Mbed-OS port of the > Matter Project.** > -> **Please read this [README.md](../../..//docs/VSCODE_DEVELOPMENT.md) for more +> **Please read this [README.md](../../../docs/VSCODE_DEVELOPMENT.md) for more > information about using VSCode in container.** To initialize the development environment, download all registered sub-modules @@ -134,7 +134,7 @@ ${MATTER_ROOT}/scripts/examples/mbed_example.sh -c=build -a=lock-app -b= - Nordic Semiconductor logo - nRF52840 DK -

+Nordic Semiconductor logo +nRF52840 DK The example is based on [Matter](https://github.com/project-chip/connectedhomeip) and Nordic @@ -26,7 +24,7 @@ device works as a Thread Sleepy End Device. - [Bluetooth LE rendezvous](#bluetooth-le-rendezvous) - [Device Firmware Upgrade](#device-firmware-upgrade) - [Requirements](#requirements) - - [Supported devices](#supported_devices) + - [Supported devices](#supported-devices) - [Device UI](#device-ui) - [Setting up the environment](#setting-up-the-environment) - [Using Docker container for setup](#using-docker-container-for-setup) @@ -34,7 +32,6 @@ device works as a Thread Sleepy End Device. - [Building](#building) - [Removing build artifacts](#removing-build-artifacts) - [Building with release configuration](#building-with-release-configuration) - - [Building with low-power configuration](#building-with-low-power-configuration) - [Building with Device Firmware Upgrade support](#building-with-device-firmware-upgrade-support) - [Configuring the example](#configuring-the-example) - [Example build types](#example-build-types) @@ -45,8 +42,6 @@ device works as a Thread Sleepy End Device.
- - ## Overview This example is running on the nRF Connect platform, which is based on Nordic @@ -149,16 +144,12 @@ section to learn how to change MCUboot and flash configuration in this example.
- - ## Requirements The application requires a specific revision of the nRF Connect SDK to work correctly. See [Setting up the environment](#setting-up-the-environment) for more information. - - ### Supported devices The example supports building and running on the following devices: @@ -170,8 +161,6 @@ The example supports building and running on the following devices:
- - ## Device UI This section lists the User Interface elements that you can use to control and @@ -251,7 +240,7 @@ image that has the tools pre-installed. If you are a macOS user, you won't be able to use the Docker container to flash the application onto a Nordic development kit due to [certain limitations of Docker for macOS](https://docs.docker.com/docker-for-mac/faqs/#can-i-pass-through-a-usb-device-to-a-container). -Use the [native shell](#using-native-shell) for building instead. +Use the [native shell](#using-native-shell-for-setup) for building instead. ### Using Docker container for setup @@ -334,8 +323,6 @@ Now you can proceed with the [Building](#building) instruction.
- - ## Building Complete the following steps, regardless of the method used for setting up the @@ -424,8 +411,6 @@ example `nrf52840dk_nrf52840`), edit the `pm_static_dfu.yml` file located in the
- - ## Configuring the example The Zephyr ecosystem is based on Kconfig files and the settings can be modified @@ -474,8 +459,6 @@ page.
- - ## Flashing and debugging To flash the application to the device, use the west tool and run the following diff --git a/examples/lock-app/nxp/k32w/k32w0/README.md b/examples/lock-app/nxp/k32w/k32w0/README.md index 9c1ef8ef3170f2..7a7e43db8bad0c 100644 --- a/examples/lock-app/nxp/k32w/k32w0/README.md +++ b/examples/lock-app/nxp/k32w/k32w0/README.md @@ -16,14 +16,14 @@ network.
-- [CHIP K32W0 Lock Example Application](#chip-k32w-lock-example-application) - +- [CHIP K32W0 Lock Example Application](#chip-k32w061-lock-example-application) - - [Introduction](#introduction) - [Bluetooth LE Advertising](#bluetooth-le-advertising) - [Bluetooth LE Rendezvous](#bluetooth-le-rendezvous) - [Device UI](#device-ui) - [Building](#building) -- [Flashing and debugging](#flashdebug) -- [Known Issues](#knownissues) +- [Flashing and debugging](#flashing-and-debugging) +- [Known Issues](#known-issues) - [Testing the example](#testing-the-example) - [Pigweed Tokenizer](#tokenizer) - [Detokenizer script](#detokenizer) @@ -35,8 +35,6 @@ network. - - ## Introduction ![K32W061 DK6](../../../../platform/nxp/k32w/k32w0/doc/images/k32w-dk6.jpg) @@ -165,8 +163,6 @@ DS3, which can be found on the DK6 board. Also, by long pressing the **USERINTERFACE** button, the factory reset action will be initiated. - - ## Building In order to build the Project CHIP example, we recommend using a Linux @@ -218,8 +214,6 @@ pycryptodome 3.9.8 The resulting output file can be found in out/debug/chip-k32w0x-lock-example. - - ## Flashing and debugging Program the firmware using the official @@ -229,8 +223,6 @@ All you have to do is to replace the Openthread binaries from the above documentation with _out/debug/chip-k32w0x-lock-example.bin_ if DK6Programmer is used or with _out/debug/chip-k32w0x-lock-example_ if MCUXpresso is used. - - ## Low power The example also offers the possibility to run in low power mode. This means @@ -272,7 +264,7 @@ professional tools must be used if exact power consumption needs to be known. The app can be deployed against any generic OpenThread Border Router. See the guide -[Commissioning NXP K32W using Android CHIPTool](../../../docs/guides/nxp_k32w_android_commissioning.md) +[Commissioning NXP K32W using Android CHIPTool](../../../../../docs/guides/nxp_k32w_android_commissioning.md) for step-by-step instructions. ## Video demo diff --git a/examples/lock-app/qpg/APPLICATION.md b/examples/lock-app/qpg/APPLICATION.md index da70eea728e3e1..c54bc77a1347e9 100644 --- a/examples/lock-app/qpg/APPLICATION.md +++ b/examples/lock-app/qpg/APPLICATION.md @@ -15,4 +15,4 @@ More detailed information on the Qorvo SDK can be found in the ## More information For more information on our product line and support options, please visit -[www.qorvo.com](www.qorvo.com) or contact us at +[www.qorvo.com](https://www.qorvo.com) or contact us at diff --git a/examples/ota-provider-app/esp32/README.md b/examples/ota-provider-app/esp32/README.md index aa2ead1d25816b..2102aabd1a714d 100644 --- a/examples/ota-provider-app/esp32/README.md +++ b/examples/ota-provider-app/esp32/README.md @@ -81,4 +81,4 @@ privileges to all nodes for the OTA Provider cluster (0x0029) on every endpoint --- Once OTA provider is commissioned then head over to -[OTA Requestor Example](../../ota-requestor-app/esp32). +[OTA Requestor Example](../../ota-requestor-app/esp32/README.md). diff --git a/examples/ota-requestor-app/esp32/README.md b/examples/ota-requestor-app/esp32/README.md index ac61c1ecde8be0..228e38bb3a7c56 100644 --- a/examples/ota-requestor-app/esp32/README.md +++ b/examples/ota-requestor-app/esp32/README.md @@ -38,7 +38,7 @@ application of OTA image. ### ESP32 OTA Requestor with Linux OTA Provider -- Build the [Linux OTA Provider](../../ota-provider-app/linux) +- Build the [Linux OTA Provider](../../ota-provider-app/linux/README.md) - Run the Linux OTA Provider with OTA image. ``` diff --git a/examples/ota-requestor-app/mbed/README.md b/examples/ota-requestor-app/mbed/README.md index a2a3fbafddaf78..95a3e9ff8ec672 100644 --- a/examples/ota-requestor-app/mbed/README.md +++ b/examples/ota-requestor-app/mbed/README.md @@ -136,7 +136,7 @@ ${MATTER_ROOT}/scripts/examples/mbed_example.sh -c=build -a=ota-requestor-app -b ``` Both approaches are limited to supported evaluation boards which are listed in -[Supported devices](#supported_devices) paragraph. +[Supported devices](#supported-devices) paragraph. Mbed OS defines three building profiles: _develop, debug_ and _release_. For more details please visit @@ -319,5 +319,5 @@ BLE advertising. Some of the supported boards may not have sufficient number PCB components to follow above description. In that case please refer to -[Supported devices](#Supported-devices) section and check board's 'Platform +[Supported devices](#supported-devices) section and check board's 'Platform components' column for additional information about the limitation. diff --git a/examples/ota-requestor-app/p6/README.md b/examples/ota-requestor-app/p6/README.md index 61b941fe54c970..cfe189e66fb9c6 100644 --- a/examples/ota-requestor-app/p6/README.md +++ b/examples/ota-requestor-app/p6/README.md @@ -14,8 +14,6 @@ CY8CKIT-062S2-43012 board.
- - ## Introduction The P6 OTA Requestor example provides a baseline demonstration of a OTA @@ -27,8 +25,6 @@ the Matter controller will exchange security information with the Rendezvous procedure. Wi-Fi Network credentials are then provided to the P6 device which will then join the network. - - ## Building - [Modustoolbox Software](https://www.cypress.com/products/modustoolbox) @@ -73,8 +69,6 @@ will then join the network. $ ./third_party/p6/p6_sdk/ota/matter-psoc6-mcuboot-bootloader.hex - - ## Flashing the Application - Flash the bootloader by first putting the CY8CKIT-062S2-43012 board into @@ -92,8 +86,6 @@ will then join the network. $ cd ~/connectedhomeip $ python3 out/ota_requestor_debug/chip-p6-ota-requestor-example.flash.py - - ### Running OTA Update Process - Make sure the ota-requestor-app is flashed and booting on the @@ -126,8 +118,6 @@ will then join the network. observe the updated application being transferred to the board, written to flash, and, when completed, booted into. - - #### Notes Raspberry Pi 4 BLE connection issues can be avoided by running the following diff --git a/examples/persistent-storage/efr32/README.md b/examples/persistent-storage/efr32/README.md index 2ab7374e61d993..25d8a4f054d7ce 100644 --- a/examples/persistent-storage/efr32/README.md +++ b/examples/persistent-storage/efr32/README.md @@ -13,8 +13,6 @@ An example testing and demonstrating the key value storage API.
- - ## Introduction This example serves to both test the key value storage implementation and API as @@ -24,14 +22,10 @@ to use the API. In the future this example can be moved into a unit test when available on all platforms. - - ## EFR32 The EFR32 platform KVS is fully implemented - - ### Building - Download the @@ -87,8 +81,6 @@ OR use GN/Ninja directly $ cd ~/connectedhomeip/examples/persistent-storage/efr32 $ rm -rf out/ - - ### Flashing the Application - On the command line: @@ -98,8 +90,6 @@ OR use GN/Ninja directly - Or with the Ozone debugger, just load the .out file. - - ### Viewing Logging Output The example application is built to use the SEGGER Real Time Transfer (RTT) diff --git a/examples/persistent-storage/infineon/psoc6/README.md b/examples/persistent-storage/infineon/psoc6/README.md index 19a32c60c85acf..9a6ca8139f272c 100644 --- a/examples/persistent-storage/infineon/psoc6/README.md +++ b/examples/persistent-storage/infineon/psoc6/README.md @@ -12,8 +12,6 @@ An example testing and demonstrating the key value storage API.
- - ## Introduction This example serves to both test the key value storage implementation and API as @@ -30,8 +28,6 @@ platforms. The Infineon PSoC6 platform KVS is fully implemented, the KVS is enabled and configured by providing a file during the init call. - - ### Building - Build the example application: @@ -40,8 +36,6 @@ configured by providing a file during the init call. $ source third_party/connectedhomeip/scripts/activate.sh $ ./scripts/examples/gn_psoc6_example.sh examples/persistent-storage/infineon/psoc6 out/persistent_storage_app_psoc6 - - ### Flashing the Application - Put CY8CKIT-062S2-43012 board on KitProg3 CMSIS-DAP Mode by pressing the diff --git a/examples/persistent-storage/linux/README.md b/examples/persistent-storage/linux/README.md index 196c2230573d48..f21f259783f6fa 100644 --- a/examples/persistent-storage/linux/README.md +++ b/examples/persistent-storage/linux/README.md @@ -12,8 +12,6 @@ An example testing and demonstrating the key value storage API.
- - ## Introduction This example serves to both test the key value storage implementation and API as @@ -23,15 +21,11 @@ to use the API. In the future this example can be moved into a unit test when available on all platforms. - - ## Linux The Linux platform KVS is fully implemented, the KVS is enabled and configured by providing a file during the init call. - - ### Building - Install tool chain @@ -46,8 +40,6 @@ by providing a file during the init call. $ gn gen out/debug $ ninja -C out/debug - - ### Running - Run Linux Example diff --git a/examples/pigweed-app/efr32/README.md b/examples/pigweed-app/efr32/README.md index 4f168d7d0b04b9..b584ff37eaeff2 100644 --- a/examples/pigweed-app/efr32/README.md +++ b/examples/pigweed-app/efr32/README.md @@ -21,9 +21,9 @@ following features are available: --- -- [CHIP EFR32 Pigweed Example Application](#chip-EFR32-pigweed-example-application) +- [CHIP EFR32 Pigweed Example Application](#chip-efr32-pigweed-example-application) - [Building the Example Application](#building-the-example-application) - - [To build the application, follow these steps:](#to-build-the-application-follow-these-steps) + - [Flashing the Application](#flashing-the-application) - [Testing the Example Application](#testing-the-example-application) --- diff --git a/examples/pigweed-app/mbed/README.md b/examples/pigweed-app/mbed/README.md index ca55e3de79c210..7bbabeb86d149d 100644 --- a/examples/pigweed-app/mbed/README.md +++ b/examples/pigweed-app/mbed/README.md @@ -109,7 +109,7 @@ ${MATTER_ROOT}/scripts/examples/mbed_example.sh -c=build -a=pigweed-app -b= - Nordic Semiconductor logo - nRF52840 DK -

+Nordic Semiconductor logo +nRF52840 DK The example is based on [Matter](https://github.com/project-chip/connectedhomeip), the @@ -29,7 +27,7 @@ the following features are available: - [Overview](#overview) - [Requirements](#requirements) - - [Supported devices](#supported_devices) + - [Supported devices](#supported-devices) - [Device UI](#device-ui) - [Setting up the environment](#setting-up-the-environment) - [Using Docker container for setup](#using-docker-container-for-setup) @@ -37,14 +35,12 @@ the following features are available: - [Building](#building) - [Configuring the example](#configuring-the-example) - [Flashing and debugging](#flashing-and-debugging) - - [Flashing on the nRF52840 DK](#nrf52840dk_flashing) - - [Flashing on the nRF52840 Dongle](#nrf52840dongle_flashing) + - [Flashing on the nRF52840 DK](#flashing-on-the-nrf52840-dk) + - [Flashing on the nRF52840 Dongle](#flashing-on-the-nrf52840-dongle) - [Testing the example](#testing-the-example)
- - ## Overview This example is running on the nRF Connect platform, which is based on the @@ -61,16 +57,12 @@ other cases.
- - ## Requirements The application requires a specific revision of the nRF Connect SDK to work correctly. See [Setting up the environment](#setting-up-the-environment) for more information. - - ### Supported devices The example supports building and running on the following devices: @@ -82,8 +74,6 @@ The example supports building and running on the following devices:
- - ## Device UI This section lists the User Interface elements that you can use to control and @@ -124,7 +114,7 @@ image that has the tools pre-installed. If you are a macOS user, you won't be able to use the Docker container to flash the application onto a Nordic development kit due to [certain limitations of Docker for macOS](https://docs.docker.com/docker-for-mac/faqs/#can-i-pass-through-a-usb-device-to-a-container). -Use the [native shell](#using-native-shell) for building instead. +Use the [native shell](#using-native-shell-for-setup) for building instead. ### Using Docker container for setup @@ -207,8 +197,6 @@ Now you can proceed with the [Building](#building) instruction.
- - ## Building Complete the following steps, regardless of the method used for setting up the @@ -245,8 +233,6 @@ following command:
- - ## Configuring the example The Zephyr ecosystem is highly configurable and allows you to modify many @@ -285,15 +271,11 @@ page.
- - ## Flashing and debugging The flashing and debugging procedure is different for the nRF52840 DK and the nRF52840 Dongle. - - ### Flashing on the nRF52840 DK To flash the application to the device, use the west tool and run the following @@ -309,8 +291,6 @@ directory: $ west debug - - ### Flashing on the nRF52840 Dongle Visit @@ -319,8 +299,6 @@ to read more about flashing on the nRF52840 Dongle.
- - ## Testing the example Run the following command to start an interactive Python shell, where the Echo diff --git a/examples/platform/qpg/README.md b/examples/platform/qpg/README.md index 1ac9c22b4f9035..9a20005ce0e1a8 100644 --- a/examples/platform/qpg/README.md +++ b/examples/platform/qpg/README.md @@ -1,3 +1,7 @@ +--- +orphan: true +--- + # Matter QPG6105 SDK ## Qorvo SDK @@ -8,4 +12,4 @@ More detailed information on the Qorvo SDK can be found in the ## More information For more information on our product line and support options, please visit -[www.qorvo.com](www.qorvo.com) or contact us at +[www.qorvo.com](https://www.qorvo.com) or contact us at diff --git a/examples/pump-app/nrfconnect/README.md b/examples/pump-app/nrfconnect/README.md index 5d53db56f22af6..0a3dc8496c9b28 100644 --- a/examples/pump-app/nrfconnect/README.md +++ b/examples/pump-app/nrfconnect/README.md @@ -6,10 +6,8 @@ state and device states and LEDs to show the state of these changes. This example is inherited from the "lock-app" example but modified to simulate a pump device and can be used as a reference for creating your own pump application. -

- Nordic Semiconductor logo - nRF52840 DK -

+Nordic Semiconductor logo +nRF52840 DK The example is based on [Matter](https://github.com/project-chip/connectedhomeip) and Nordic @@ -27,7 +25,7 @@ device works as a Thread Minimal End Device. - [Bluetooth LE rendezvous](#bluetooth-le-rendezvous) - [Device Firmware Upgrade](#device-firmware-upgrade) - [Requirements](#requirements) - - [Supported devices](#supported_devices) + - [Supported devices](#supported-devices) - [Device UI](#device-ui) - [Setting up the environment](#setting-up-the-environment) - [Using Docker container for setup](#using-docker-container-for-setup) @@ -41,8 +39,6 @@ device works as a Thread Minimal End Device.
- - ## Overview This example is running on the nRF Connect platform, which is based on Nordic @@ -145,29 +141,23 @@ section to learn how to change MCUboot and flash configuration in this example.
- - ## Requirements The application requires a specific revision of the nRF Connect SDK to work correctly. See [Setting up the environment](#setting-up-the-environment) for more information. - - ### Supported devices The example supports building and running on the following devices: -| Hardware platform | Build target | Platform image | -| ----------------------------------------------------------------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| [nRF52840 DK](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52840-DK) | `nrf52840dk_nrf52840` |
nRF52840 DKnRF52840 DK
| -| [nRF5340 DK](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF5340-DK) | `nrf5340dk_nrf5340_cpuapp` |
nRF5340 DKnRF5340 DK
| +| Hardware platform | Build target | Platform image | +| ----------------------------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| [nRF52840 DK](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52840-DK) | `nrf52840dk_nrf52840` |
nRF52840 DKnRF52840 DK
| +| [nRF5340 DK](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF5340-DK) | `nrf5340dk_nrf5340_cpuapp` |
nRF5340 DKnRF5340 DK
|
- - ## Device UI This section lists the User Interface elements that you can use to control and @@ -244,7 +234,7 @@ image that has the tools pre-installed. If you are a macOS user, you won't be able to use the Docker container to flash the application onto a Nordic development kit due to [certain limitations of Docker for macOS](https://docs.docker.com/docker-for-mac/faqs/#can-i-pass-through-a-usb-device-to-a-container). -Use the [native shell](#using-native-shell) for building instead. +Use the [native shell](#using-native-shell-for-setup) for building instead. ### Using Docker container for setup @@ -327,8 +317,6 @@ Now you can proceed with the [Building](#building) instruction.
- - ## Building Complete the following steps, regardless of the method used for setting up the @@ -420,8 +408,6 @@ example `nrf52840dk_nrf52840`), edit the `pm_static_dfu.yml` file located in the
- - ## Configuring the example The Zephyr ecosystem is based on Kconfig files and the settings can be modified @@ -470,8 +456,6 @@ page.
- - ## Flashing and debugging To flash the application to the device, use the west tool and run the following diff --git a/examples/pump-controller-app/nrfconnect/README.md b/examples/pump-controller-app/nrfconnect/README.md index d3111c769a5353..c9aa53187bc589 100644 --- a/examples/pump-controller-app/nrfconnect/README.md +++ b/examples/pump-controller-app/nrfconnect/README.md @@ -7,10 +7,8 @@ these changes. This example is inherited from the "lock-app" example but modified to simulate a pump device and can be used as a reference for creating your own pump application. -

- Nordic Semiconductor logo - nRF52840 DK -

+Nordic Semiconductor logo +nRF52840 DK The example is based on [Matter](https://github.com/project-chip/connectedhomeip) and Nordic @@ -28,7 +26,7 @@ device works as a Thread Minimal End Device. - [Bluetooth LE rendezvous](#bluetooth-le-rendezvous) - [Device Firmware Upgrade](#device-firmware-upgrade) - [Requirements](#requirements) - - [Supported devices](#supported_devices) + - [Supported devices](#supported-devices) - [Device UI](#device-ui) - [Setting up the environment](#setting-up-the-environment) - [Using Docker container for setup](#using-docker-container-for-setup) @@ -42,8 +40,6 @@ device works as a Thread Minimal End Device.
- - ## Overview This example is running on the nRF Connect platform, which is based on Nordic @@ -146,29 +142,23 @@ section to learn how to change MCUboot and flash configuration in this example.
- - ## Requirements The application requires a specific revision of the nRF Connect SDK to work correctly. See [Setting up the environment](#setting-up-the-environment) for more information. - - ### Supported devices The example supports building and running on the following devices: -| Hardware platform | Build target | Platform image | -| ----------------------------------------------------------------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| [nRF52840 DK](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52840-DK) | `nrf52840dk_nrf52840` |
nRF52840 DKnRF52840 DK
| -| [nRF5340 DK](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF5340-DK) | `nrf5340dk_nrf5340_cpuapp` |
nRF5340 DKnRF5340 DK
| +| Hardware platform | Build target | Platform image | +| ----------------------------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| [nRF52840 DK](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF52840-DK) | `nrf52840dk_nrf52840` |
nRF52840 DKnRF52840 DK
| +| [nRF5340 DK](https://www.nordicsemi.com/Software-and-Tools/Development-Kits/nRF5340-DK) | `nrf5340dk_nrf5340_cpuapp` |
nRF5340 DKnRF5340 DK
|
- - ## Device UI This section lists the User Interface elements that you can use to control and @@ -244,7 +234,7 @@ image that has the tools pre-installed. If you are a macOS user, you won't be able to use the Docker container to flash the application onto a Nordic development kit due to [certain limitations of Docker for macOS](https://docs.docker.com/docker-for-mac/faqs/#can-i-pass-through-a-usb-device-to-a-container). -Use the [native shell](#using-native-shell) for building instead. +Use the [native shell](#using-native-shell-for-setup) for building instead. ### Using Docker container for setup @@ -327,8 +317,6 @@ Now you can proceed with the [Building](#building) instruction.
- - ## Building Complete the following steps, regardless of the method used for setting up the @@ -420,8 +408,6 @@ example `nrf52840dk_nrf52840`), edit the `pm_static_dfu.yml` file located in the
- - ## Configuring the example The Zephyr ecosystem is based on Kconfig files and the settings can be modified @@ -470,8 +456,6 @@ page.
- - ## Flashing and debugging To flash the application to the device, use the west tool and run the following diff --git a/examples/shell/README.md b/examples/shell/README.md index 4b76af87e5d89c..4fc7ae9795ac0b 100644 --- a/examples/shell/README.md +++ b/examples/shell/README.md @@ -34,9 +34,9 @@ Done - [exit](#exit) - [help](#help) - [otcli](README_OTCLI.md) -- [ping](#ping) +- ping - [rand](#rand) -- [server](README_SERVER.md) +- server - [version](#version) ## Matter Shell Command Details diff --git a/examples/shell/README_SERVER.md b/examples/shell/README_SERVER.md index 4b1133ea1cf6af..93af1bb7884e36 100644 --- a/examples/shell/README_SERVER.md +++ b/examples/shell/README_SERVER.md @@ -7,7 +7,6 @@ The all-clusters-app server may be invoked and managed via the Matter Shell CLI. - [help](#help) - [clusters](#clusters) - [endpoints](#endpoints) -- [exchanges](#exchanges) - [port](#port) - [sessions](#sessions) - [start](#start) diff --git a/examples/shell/mbed/README.md b/examples/shell/mbed/README.md index c15008d0d034bf..c6b686c678f6dd 100644 --- a/examples/shell/mbed/README.md +++ b/examples/shell/mbed/README.md @@ -102,7 +102,7 @@ ${MATTER_ROOT}/scripts/examples/mbed_example.sh -c=build -a=shell -b= - - ## Building - Install tool chain @@ -37,8 +35,6 @@ Desktop 20.10 (aarch64)** $ cd ~/connectedhomeip/examples/tv-app/linux $ rm -rf out/ - - ## Exercising Commissioning - Regular Commissioning diff --git a/examples/tv-casting-app/android/README.md b/examples/tv-casting-app/android/README.md index 28069c854ab8e5..87e7fa109b3e7a 100644 --- a/examples/tv-casting-app/android/README.md +++ b/examples/tv-casting-app/android/README.md @@ -18,8 +18,6 @@ the TV.
- - ## Requirements for building You need Android SDK 21 & NDK downloaded to your machine. Set the @@ -27,8 +25,6 @@ You need Android SDK 21 & NDK downloaded to your machine. Set the `$ANDROID_NDK_HOME` environment variable to point to where the NDK package is downloaded. - - ### ABIs and TARGET_CPU `TARGET_CPU` can have the following values, depending on your smartphone CPU @@ -41,8 +37,6 @@ architecture: | x86 | x86 | | x86_64 | x64 | - - ### Gradle & JDK Version We are using Gradle 7.1.1 for all android project which does not support Java 17 @@ -57,8 +51,6 @@ export JAVA_HOME=/Applications/Android\ Studio.app/Contents/jre/Contents/Home/
- - ## Preparing for build Complete the following steps to prepare the Matter build: @@ -71,8 +63,6 @@ Complete the following steps to prepare the Matter build: source scripts/bootstrap.sh ``` - - ## Building & Installing the app This is the simplest option. In the command line, run the following command from diff --git a/examples/tv-casting-app/linux/README.md b/examples/tv-casting-app/linux/README.md index e821878d2668cd..8cd5df4d297c2a 100644 --- a/examples/tv-casting-app/linux/README.md +++ b/examples/tv-casting-app/linux/README.md @@ -14,8 +14,6 @@ commissioned. Then it allows the user to send CHIP commands to the TV.
- - ## Building - Install tool chain @@ -35,8 +33,6 @@ commissioned. Then it allows the user to send CHIP commands to the TV. $ cd ~/connectedhomeip/examples/tv-casting-app/linux $ rm -rf out/ - - ## Running the Complete Example on Linux - Pre-requisite: Build and run the tv-app diff --git a/examples/window-app/efr32/README.md b/examples/window-app/efr32/README.md index 4cde87f3c9600c..8306384759d0ac 100644 --- a/examples/window-app/efr32/README.md +++ b/examples/window-app/efr32/README.md @@ -8,18 +8,14 @@ An example showing the use of CHIP on the Silicon Labs EFR32 MG12. - [Introduction](#introduction) - [Building](#building) - - [Note](#note) - [Flashing the Application](#flashing-the-application) - [Viewing Logging Output](#viewing-logging-output) - [Running the Complete Example](#running-the-complete-example) - [Notes](#notes) - - [Running Pigweed RPC console](#running-pigweed-rpc-console) - [OTA Software Update](#ota-software-update)
- - ## Introduction The EFR32 window-covering example provides a baseline demonstration of a Window @@ -40,8 +36,6 @@ The window-covering example is intended to serve both as a means to explore the workings of CHIP as well as a template for creating real products based on the Silicon Labs platform. - - ## Building - Download the @@ -126,15 +120,11 @@ Silicon Labs platform. $ gn gen out/debug --args='import("//with_pw_rpc.gni")' $ ninja -C out/debug - [Running Pigweed RPC console](#running-pigweed-rpc-console) - For more build options, help is provided when running the build script without arguments ./scripts/examples/gn_efr32_example.sh - - ## Flashing the Application - On the command line: @@ -144,8 +134,6 @@ arguments - Or with the Ozone debugger, just load the .out file. - - ## Viewing Logging Output The example application is built to use the SEGGER Real Time Transfer (RTT) @@ -194,8 +182,6 @@ combination with JLinkRTTClient as follows: $ JLinkRTTClient - - ## Running the Complete Example - It is assumed here that you already have an OpenThread border router @@ -325,8 +311,6 @@ combination with JLinkRTTClient as follows: # Add Ipv6 route on PC (Linux) $ sudo ip route add /64 via 2002::2 - - ## OTA Software Update For the description of Software Update process with EFR32 example applications diff --git a/examples/window-app/nrfconnect/README.md b/examples/window-app/nrfconnect/README.md index 8fbabd6f23f2b5..b56787e011c73a 100644 --- a/examples/window-app/nrfconnect/README.md +++ b/examples/window-app/nrfconnect/README.md @@ -5,10 +5,8 @@ window shutter device. It uses buttons to test changing cover position and device states and LEDs to show the state of these changes. You can use this example as a reference for creating your own application. -

- Nordic Semiconductor logo - nRF52840 DK -

+Nordic Semiconductor logo +nRF52840 DK The example is based on [Matter](https://github.com/project-chip/connectedhomeip) and Nordic @@ -25,7 +23,7 @@ into an existing Matter network and can be controlled by this network. - [Bluetooth LE rendezvous](#bluetooth-le-rendezvous) - [Device Firmware Upgrade](#device-firmware-upgrade) - [Requirements](#requirements) - - [Supported devices](#supported_devices) + - [Supported devices](#supported-devices) - [Device UI](#device-ui) - [Setting up the environment](#setting-up-the-environment) - [Using Docker container for setup](#using-docker-container-for-setup) @@ -33,7 +31,6 @@ into an existing Matter network and can be controlled by this network. - [Building](#building) - [Removing build artifacts](#removing-build-artifacts) - [Building with release configuration](#building-with-release-configuration) - - [Building with low-power configuration](#building-with-low-power-configuration) - [Building with Device Firmware Upgrade support](#building-with-device-firmware-upgrade-support) - [Configuring the example](#configuring-the-example) - [Example build types](#example-build-types) @@ -44,8 +41,6 @@ into an existing Matter network and can be controlled by this network.
- - ## Overview This example is running on the nRF Connect platform, which is based on Nordic @@ -143,16 +138,12 @@ section to learn how to change MCUboot and flash configuration in this example.
- - ## Requirements The application requires a specific revision of the nRF Connect SDK to work correctly. See [Setting up the environment](#setting-up-the-environment) for more information. - - ### Supported devices The example supports building and running on the following devices: @@ -164,8 +155,6 @@ The example supports building and running on the following devices:
- - ## Device UI This section lists the User Interface elements that you can use to control and @@ -266,7 +255,7 @@ image that has the tools pre-installed. If you are a macOS user, you won't be able to use the Docker container to flash the application onto a Nordic development kit due to [certain limitations of Docker for macOS](https://docs.docker.com/docker-for-mac/faqs/#can-i-pass-through-a-usb-device-to-a-container). -Use the [native shell](#using-native-shell) for building instead. +Use the [native shell](#using-native-shell-for-setup) for building instead. ### Using Docker container for setup @@ -349,8 +338,6 @@ Now you can proceed with the [Building](#building) instruction.
- - ## Building Complete the following steps, regardless of the method used for setting up the @@ -441,8 +428,6 @@ example `nrf52840dk_nrf52840`), edit the `pm_static_dfu.yml` file located in the
- - ## Configuring the example The Zephyr ecosystem is based on Kconfig files and the settings can be modified @@ -491,8 +476,6 @@ page.
- - ## Flashing and debugging To flash the application to the device, use the west tool and run the following From 56773cb87d302079e4f0251e7f24432f5b8bab7e Mon Sep 17 00:00:00 2001 From: Gaute Svanes Lunde Date: Thu, 9 Jun 2022 15:25:16 +0200 Subject: [PATCH 05/14] doc: changed :heavy_check_mark: to ascii symbol MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Changed the GitHub rendered emoji :heavy_check_mark: to the ascii symbol ✔ so that it renders with Sphinx. Signed-off-by: Gaute Svanes Lunde --- examples/all-clusters-app/mbed/README.md | 2 +- examples/all-clusters-minimal-app/mbed/README.md | 2 +- examples/lighting-app/mbed/README.md | 2 +- examples/lock-app/mbed/README.md | 2 +- examples/ota-requestor-app/mbed/README.md | 2 +- examples/pigweed-app/mbed/README.md | 2 +- examples/shell/mbed/README.md | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) diff --git a/examples/all-clusters-app/mbed/README.md b/examples/all-clusters-app/mbed/README.md index fbce644ef4ae1a..a3bdcad281a69f 100644 --- a/examples/all-clusters-app/mbed/README.md +++ b/examples/all-clusters-app/mbed/README.md @@ -233,7 +233,7 @@ within a WiFi network. | Manufacturer | Hardware platform | Build target | Platform image | Status | Platform components | | ----------------------------------------------------- | ------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------ | :----------------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Cypress
Semiconductor](https://www.cypress.com/) | [CY8CPROTO-062-4343W](https://os.mbed.com/platforms/CY8CPROTO-062-4343W/) | `CY8CPROTO_062_4343W` | ![CY8CPROTO-062-4343W](https://os.mbed.com/media/cache/platforms/p6_wifi-bt_proto.png.250x250_q85.jpg) | :heavy_check_mark: |
LEDs
  • Board has only one usable LED (LED4) which corresponds to USER LED from UI.
Buttons
  • Unused
Slider
  • Unused
| +| [Cypress
Semiconductor](https://www.cypress.com/) | [CY8CPROTO-062-4343W](https://os.mbed.com/platforms/CY8CPROTO-062-4343W/) | `CY8CPROTO_062_4343W` | ![CY8CPROTO-062-4343W](https://os.mbed.com/media/cache/platforms/p6_wifi-bt_proto.png.250x250_q85.jpg) | ✔ |
LEDs
  • Board has only one usable LED (LED4) which corresponds to USER LED from UI.
Buttons
  • Unused
Slider
  • Unused
| ##### Notes diff --git a/examples/all-clusters-minimal-app/mbed/README.md b/examples/all-clusters-minimal-app/mbed/README.md index 6b50aebf72e497..91d16d7ebc0050 100644 --- a/examples/all-clusters-minimal-app/mbed/README.md +++ b/examples/all-clusters-minimal-app/mbed/README.md @@ -233,7 +233,7 @@ within a WiFi network. | Manufacturer | Hardware platform | Build target | Platform image | Status | Platform components | | ----------------------------------------------------- | ------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------ | :----------------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Cypress
Semiconductor](https://www.cypress.com/) | [CY8CPROTO-062-4343W](https://os.mbed.com/platforms/CY8CPROTO-062-4343W/) | `CY8CPROTO_062_4343W` | ![CY8CPROTO-062-4343W](https://os.mbed.com/media/cache/platforms/p6_wifi-bt_proto.png.250x250_q85.jpg) | :heavy_check_mark: |
LEDs
  • Board has only one usable LED (LED4) which corresponds to USER LED from UI.
Buttons
  • Unused
Slider
  • Unused
| +| [Cypress
Semiconductor](https://www.cypress.com/) | [CY8CPROTO-062-4343W](https://os.mbed.com/platforms/CY8CPROTO-062-4343W/) | `CY8CPROTO_062_4343W` | ![CY8CPROTO-062-4343W](https://os.mbed.com/media/cache/platforms/p6_wifi-bt_proto.png.250x250_q85.jpg) | ✔ |
LEDs
  • Board has only one usable LED (LED4) which corresponds to USER LED from UI.
Buttons
  • Unused
Slider
  • Unused
| #### Notes diff --git a/examples/lighting-app/mbed/README.md b/examples/lighting-app/mbed/README.md index 01535651a62c75..16705e5c401308 100644 --- a/examples/lighting-app/mbed/README.md +++ b/examples/lighting-app/mbed/README.md @@ -308,7 +308,7 @@ The example supports building and running on the following mbed-enabled devices: | Manufacturer | Hardware platform | Build target | Platform image | Status | Platform components | | ----------------------------------------------------- | ------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Cypress
Semiconductor](https://www.cypress.com/) | [CY8CPROTO-062-4343W](https://os.mbed.com/platforms/CY8CPROTO-062-4343W/) | `CY8CPROTO_062_4343W` |
CY8CPROTO-062-4343WCY8CPROTO-062-4343W
| :heavy_check_mark: |
LEDs
  • Board has only one usable LED (LED4) which corresponds to USER LED from UI.
  • Lighting LED should be an external component connected to PB9_6 pin (active high).
Buttons
  • SW2 push-button is not used in this example due to its interaction with WIFI module interrupt line.
  • Button 0 corresponds to BTN0 capacitive button.
  • Button 1 corresponds to BTN1 capacitive button.
Slider
  • The board's touch slider corresponds to UI slider
| +| [Cypress
Semiconductor](https://www.cypress.com/) | [CY8CPROTO-062-4343W](https://os.mbed.com/platforms/CY8CPROTO-062-4343W/) | `CY8CPROTO_062_4343W` |
CY8CPROTO-062-4343WCY8CPROTO-062-4343W
| ✔ |
LEDs
  • Board has only one usable LED (LED4) which corresponds to USER LED from UI.
  • Lighting LED should be an external component connected to PB9_6 pin (active high).
Buttons
  • SW2 push-button is not used in this example due to its interaction with WIFI module interrupt line.
  • Button 0 corresponds to BTN0 capacitive button.
  • Button 1 corresponds to BTN1 capacitive button.
Slider
  • The board's touch slider corresponds to UI slider
| ##### Notes diff --git a/examples/lock-app/mbed/README.md b/examples/lock-app/mbed/README.md index 5e30074bfe3e2f..49c380c632acf8 100644 --- a/examples/lock-app/mbed/README.md +++ b/examples/lock-app/mbed/README.md @@ -282,7 +282,7 @@ The example supports building and running on the following mbed-enabled devices: | Manufacturer | Hardware platform | Build target | Platform image | Status | Platform components | | ----------------------------------------------------- | ------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Cypress
Semiconductor](https://www.cypress.com/) | [CY8CPROTO-062-4343W](https://os.mbed.com/platforms/CY8CPROTO-062-4343W/) | `CY8CPROTO_062_4343W` |
CY8CPROTO-062-4343WCY8CPROTO-062-4343W
| :heavy_check_mark: |
LEDs
  • Board has only one usable LED (LED4) which corresponds to USER LED from UI.
  • Lock state LED should be an external component connected to PB9_6 pin (active high).
Buttons
  • SW2 push-button is not used in this example due to its interaction with WIFI module interrupt line.
  • Button 0 corresponds to BTN0 capacitive button.
  • Button 1 corresponds to BTN1 capacitive button.
Slider
  • Unused
| +| [Cypress
Semiconductor](https://www.cypress.com/) | [CY8CPROTO-062-4343W](https://os.mbed.com/platforms/CY8CPROTO-062-4343W/) | `CY8CPROTO_062_4343W` |
CY8CPROTO-062-4343WCY8CPROTO-062-4343W
| ✔ |
LEDs
  • Board has only one usable LED (LED4) which corresponds to USER LED from UI.
  • Lock state LED should be an external component connected to PB9_6 pin (active high).
Buttons
  • SW2 push-button is not used in this example due to its interaction with WIFI module interrupt line.
  • Button 0 corresponds to BTN0 capacitive button.
  • Button 1 corresponds to BTN1 capacitive button.
Slider
  • Unused
| ##### Notes diff --git a/examples/ota-requestor-app/mbed/README.md b/examples/ota-requestor-app/mbed/README.md index 95a3e9ff8ec672..89aeece1e0fc15 100644 --- a/examples/ota-requestor-app/mbed/README.md +++ b/examples/ota-requestor-app/mbed/README.md @@ -260,7 +260,7 @@ The example supports building and running on the following mbed-enabled devices: | Manufacturer | Hardware platform | Build target | Platform image | Status | Platform components | | ----------------------------------------------------- | ------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Cypress
Semiconductor](https://www.cypress.com/) | [CY8CPROTO-062-4343W](https://os.mbed.com/platforms/CY8CPROTO-062-4343W/) | `CY8CPROTO_062_4343W` |
CY8CPROTO-062-4343WCY8CPROTO-062-4343W
| :heavy_check_mark: |
LEDs
  • Board has only one usable LED (LED4) which corresponds to USER LED from UI.
  • Lock state LED should be an external component connected to PB9_6 pin (active high).
Buttons
  • SW2 push-button is not used in this example due to its interaction with WIFI module interrupt line.
  • Button 0 corresponds to BTN0 capacitive button.
  • Button 1 corresponds to BTN1 capacitive button.
Slider
  • Unused
| +| [Cypress
Semiconductor](https://www.cypress.com/) | [CY8CPROTO-062-4343W](https://os.mbed.com/platforms/CY8CPROTO-062-4343W/) | `CY8CPROTO_062_4343W` |
CY8CPROTO-062-4343WCY8CPROTO-062-4343W
| ✔ |
LEDs
  • Board has only one usable LED (LED4) which corresponds to USER LED from UI.
  • Lock state LED should be an external component connected to PB9_6 pin (active high).
Buttons
  • SW2 push-button is not used in this example due to its interaction with WIFI module interrupt line.
  • Button 0 corresponds to BTN0 capacitive button.
  • Button 1 corresponds to BTN1 capacitive button.
Slider
  • Unused
| ##### Notes diff --git a/examples/pigweed-app/mbed/README.md b/examples/pigweed-app/mbed/README.md index 7bbabeb86d149d..8776799c6cab4d 100644 --- a/examples/pigweed-app/mbed/README.md +++ b/examples/pigweed-app/mbed/README.md @@ -243,7 +243,7 @@ The example supports building and running on the following mbed-enabled devices: | Manufacturer | Hardware platform | Build target | Platform image | Status | Platform components | | ----------------------------------------------------- | ------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Cypress
Semiconductor](https://www.cypress.com/) | [CY8CPROTO-062-4343W](https://os.mbed.com/platforms/CY8CPROTO-062-4343W/) | `CY8CPROTO_062_4343W` |
CY8CPROTO-062-4343WCY8CPROTO-062-4343W
| :heavy_check_mark: |
LEDs
  • Board has only one usable LED (LED4) which corresponds to USER LED from UI.
Buttons
  • Unused
Slider
  • Unused
| +| [Cypress
Semiconductor](https://www.cypress.com/) | [CY8CPROTO-062-4343W](https://os.mbed.com/platforms/CY8CPROTO-062-4343W/) | `CY8CPROTO_062_4343W` |
CY8CPROTO-062-4343WCY8CPROTO-062-4343W
| ✔ |
LEDs
  • Board has only one usable LED (LED4) which corresponds to USER LED from UI.
Buttons
  • Unused
Slider
  • Unused
| ##### Notes diff --git a/examples/shell/mbed/README.md b/examples/shell/mbed/README.md index c6b686c678f6dd..4a0a2702721ec6 100644 --- a/examples/shell/mbed/README.md +++ b/examples/shell/mbed/README.md @@ -201,7 +201,7 @@ The example supports building and running on the following mbed-enabled devices: | Manufacturer | Hardware platform | Build target | Platform image | Status | Platform components | | ----------------------------------------------------- | ------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Cypress
Semiconductor](https://www.cypress.com/) | [CY8CPROTO-062-4343W](https://os.mbed.com/platforms/CY8CPROTO-062-4343W/) | `CY8CPROTO_062_4343W` |
CY8CPROTO-062-4343WCY8CPROTO-062-4343W
| :heavy_check_mark: |
LEDs
  • Unused
Buttons
  • Unused
Slider
  • Unused
| +| [Cypress
Semiconductor](https://www.cypress.com/) | [CY8CPROTO-062-4343W](https://os.mbed.com/platforms/CY8CPROTO-062-4343W/) | `CY8CPROTO_062_4343W` |
CY8CPROTO-062-4343WCY8CPROTO-062-4343W
| ✔ |
LEDs
  • Unused
Buttons
  • Unused
Slider
  • Unused
| ##### Notes From 0ed4c6e6554e361313c7c889ea813986590b051d Mon Sep 17 00:00:00 2001 From: Gaute Svanes Lunde Date: Thu, 23 Jun 2022 13:55:05 +0200 Subject: [PATCH 06/14] workflow: add docbuild workflow Add a workflow for building the documentation with Sphinx and deploy the generated html to the `gh-pages` branch. Signed-off-by: Gaute Svanes Lunde --- .github/workflows/docbuild.yaml | 53 +++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 .github/workflows/docbuild.yaml diff --git a/.github/workflows/docbuild.yaml b/.github/workflows/docbuild.yaml new file mode 100644 index 00000000000000..296aa95fcff674 --- /dev/null +++ b/.github/workflows/docbuild.yaml @@ -0,0 +1,53 @@ +name: Documentation Build + +on: + push: + branches: + - master + +permissions: + contents: write + +jobs: + build-and-deploy: + runs-on: ubuntu-latest + + steps: + - name: Checkout the code + uses: actions/checkout@v2 + with: + path: matter + fetch-depth: 0 + - name: Install Python + uses: actions/setup-python@v2 + with: + python-version: 3.8 + - name: cache-pip + uses: actions/cache@v1 + with: + path: ~/.cache/pip + key: ${{ runner.os }}-doc-pip + - name: Install packages + run: | + sudo apt update + DOXYGEN_VERSION=1.9.4 + wget --no-verbose https://downloads.sourceforge.net/project/doxygen/rel-${DOXYGEN_VERSION}/doxygen-${DOXYGEN_VERSION}.linux.bin.tar.gz + tar xf doxygen-${DOXYGEN_VERSION}.linux.bin.tar.gz + echo "${PWD}/doxygen-${DOXYGEN_VERSION}/bin" >> $GITHUB_PATH + - name: Install base dependencies + working-directory: matter + run: | + sudo pip3 install -U pip + pip3 install -r docs/requirements.txt + - name: Build documentation + working-directory: matter/docs + run: | + mkdir -p _build/src + make html + touch _build/html/.nojekyll + - name: Deploy to gh-pages + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: matter/docs/_build/html + destination_dir: docs From 6fb27b991d044a4eebe35fafdb460371d91a713d Mon Sep 17 00:00:00 2001 From: Gaute Svanes Lunde Date: Wed, 29 Jun 2022 15:23:40 +0200 Subject: [PATCH 07/14] sphinx: remove doxygen and add landing page The incomplete API page has been removed, and doxygen disabled. The landing page is now set to the top level `README.md`, and the external_content extension is updated to transform specific prefixes and links to folders into external links. Signed-off-by: Gaute Svanes Lunde --- docs/Makefile | 2 +- docs/README.md | 2 +- docs/_extensions/external_content.py | 51 ++++++++++++------- docs/breathe.md | 6 --- docs/conf.py | 12 +++-- .../nrfconnect_factory_data_configuration.md | 22 +++----- docs/index.md | 7 ++- docs/make.bat | 2 +- examples/lock-app/cc32xx/README.md | 6 +-- 9 files changed, 60 insertions(+), 50 deletions(-) delete mode 100644 docs/breathe.md diff --git a/docs/Makefile b/docs/Makefile index 7c4c49345a5544..30826e465ad549 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -3,7 +3,7 @@ # You can set these variables from the command line, and also # from the environment for the first two. -SPHINXOPTS ?= -c . -d _build/doctrees +SPHINXOPTS ?= -W -c . -d _build/doctrees SPHINXBUILD ?= sphinx-build SOURCEDIR = _build/src BUILDDIR = _build diff --git a/docs/README.md b/docs/README.md index dcb17c3552e56c..e4ec9c8f3a5523 100644 --- a/docs/README.md +++ b/docs/README.md @@ -24,7 +24,7 @@ ## Style Guide - Documentation about style is documented in - [the style guide](./STYLE_GUIDE.md) + [the style guide](./style/style_guide.md) - Additional documentation about more specific files are in the [style folder](./style/) diff --git a/docs/_extensions/external_content.py b/docs/_extensions/external_content.py index ce3a4f68491278..a4018c7d577b99 100644 --- a/docs/_extensions/external_content.py +++ b/docs/_extensions/external_content.py @@ -22,8 +22,8 @@ - ``external_content_contents``: A list of external contents. Each entry is a tuple with two fields: the external base directory and a file glob pattern. -- ``external_content_link_repositories``: A list of base directories out of scope. - All links to content within these directories are made external. +- ``external_content_link_prefixes``: A list of link prefixes out of scope. + All links to content with these prefixes are made external. - ``external_content_link_extensions``: A list of file extensions in scope of the documentation. All links to content without these file extensions are made external. @@ -45,6 +45,9 @@ __version__ = "0.1.0" +DIRECTIVES = ("figure", "image", "include", "literalinclude") +"""Default directives for included content.""" + EXTERNAL_LINK_URL_PREFIX = ( "https://github.com/project-chip/connectedhomeip/blob/master/" ) @@ -54,7 +57,7 @@ def adjust_includes( fname: Path, basepath: Path, encoding: str, - link_folders: List[str], + link_prefixes: List[str], extensions: List[str], dstpath: Optional[Path] = None, ) -> None: @@ -64,7 +67,7 @@ def adjust_includes( fname: File to be processed. basepath: Base path to be used to resolve content location. encoding: Sources encoding. - link_folders: Folders links to which are made external. + link_prefixes: Prefixes of links that are made external. extensions: Filename extensions links to which are not made external. dstpath: Destination path for fname if its path is not the actual destination. """ @@ -74,20 +77,20 @@ def adjust_includes( dstpath = dstpath or fname.parent - def _adjust_links(m): - displayed, fpath = m.groups() - + def _adjust_path(path): # ignore absolute paths, section links, hyperlinks and same folder - if fpath.startswith(("/", "#", "http", "www")) or not "/" in fpath: - fpath_adj = fpath - else: - fpath_adj = Path(os.path.relpath(basepath / fpath, dstpath)).as_posix() + if path.startswith(("/", "#", "http", "www")) or not "/" in path: + return path + return Path(os.path.relpath(basepath / path, dstpath)).as_posix() + def _adjust_links(m): + displayed, fpath = m.groups() + fpath_adj = _adjust_path(fpath) return f"[{displayed}]({fpath_adj})" def _adjust_external(m): - displayed, folder, target = m.groups() - return f"[{displayed}]({EXTERNAL_LINK_URL_PREFIX}{folder}/{target})" + displayed, target = m.groups() + return f"[{displayed}]({EXTERNAL_LINK_URL_PREFIX}{target})" def _adjust_filetype(m): displayed, target, extension = m.groups() @@ -100,6 +103,11 @@ def _remove_section_links(m): (file_link,) = m.groups() return file_link + ")" + def _adjust_image_link(m): + prefix, fpath, postfix = m.groups() + fpath_adj = _adjust_path(fpath) + return f"{prefix}{fpath_adj}{postfix}" + rules = [ # Find any links and adjust the path (r"\[([^\[\]]*)\]\s*\((.*)\)", _adjust_links), @@ -107,7 +115,7 @@ def _remove_section_links(m): # Find links that lead to an external folder and transform it # into an external link. ( - r"\[([^\[\]]*)\]\s*\((?:\.\./)*(" + "|".join(link_folders) + r")/(.*)\)", + r"\[([^\[\]]*)\]\s*\((?:\.\./)*((?:" + "|".join(link_prefixes) + r")[^)]*)\)", _adjust_external, ), @@ -121,6 +129,15 @@ def _remove_section_links(m): r"\[([^\[\]]*)\]\s*\((?:\.\./)*((?:[^()]+?/)*[^.()]+?(\.[^)/]+))\)", _adjust_filetype, ), + + # Find links that lead to a folder and transform it into an external link. + ( + r"\[([^\[\]]*)\]\s*\((?:\.\./)*((?:[^()]+?/)+[^).#/]+)(\))", + _adjust_filetype, + ), + + # Find image links in img tags and adjust them + (r"(]*src=[\"'])([^ >]+)([\"'][^>]*>)", _adjust_image_link) ] with open(fname, "r+", encoding=encoding) as f: @@ -181,7 +198,7 @@ def sync_contents(app: Sphinx) -> None: dst, src.parent, app.config.source_encoding, - app.config.external_content_link_repositories, + app.config.external_content_link_prefixes, app.config.external_content_link_extensions, ) # if origin file is modified only copy if different @@ -194,7 +211,7 @@ def sync_contents(app: Sphinx) -> None: src_adjusted, src.parent, app.config.source_encoding, - app.config.external_content_link_repositories, + app.config.external_content_link_prefixes, app.config.external_content_link_extensions, dstpath=dst.parent, ) @@ -212,7 +229,7 @@ def sync_contents(app: Sphinx) -> None: def setup(app: Sphinx) -> Dict[str, Any]: app.add_config_value("external_content_contents", [], "env") app.add_config_value("external_content_keep", [], "") - app.add_config_value("external_content_link_repositories", [], "env") + app.add_config_value("external_content_link_prefixes", [], "env") app.add_config_value("external_content_link_extensions", [], "env") app.connect("builder-inited", sync_contents) diff --git a/docs/breathe.md b/docs/breathe.md deleted file mode 100644 index d84d7cd9e7291b..00000000000000 --- a/docs/breathe.md +++ /dev/null @@ -1,6 +0,0 @@ -# Breathe (Doxygen) - -```{eval-rst} -.. doxygenclass:: chip::Ble::BleTransportCapabilitiesRequestMessage - :members: -``` \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 6f9abf5deb45b0..d446c99a2c1ccb 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -19,7 +19,12 @@ # -- General configuration --------------------------------------------------- -extensions = ["myst_parser", "external_content", "doxyrunner", "breathe"] +extensions = [ + "myst_parser", + "external_content", + # "doxyrunner", + # "breathe", +] exclude_patterns = [ "_build", "**/nxp/linux-imx/imx8m/README.md", @@ -54,13 +59,14 @@ # -- Options for external_content -------------------------------------------- external_content_contents = [ - (MATTER_BASE / "docs", "[!_]*"), + (MATTER_BASE / "docs", "[!_R]*"), + (MATTER_BASE, "README.md"), (MATTER_BASE, "examples/**/*.md"), (MATTER_BASE, "examples/**/*.png"), (MATTER_BASE, "examples/**/*.jpg"), (MATTER_BASE, "examples/**/*.JPG"), ] -external_content_link_repositories = ["src", r"\.vscode"] +external_content_link_prefixes = ["src/", r"\.vscode/", "CONTRIBUTING"] external_content_link_extensions = [".md", ".png", ".jpg", ".svg"] # -- Options for zephyr.doxyrunner plugin ------------------------------------ diff --git a/docs/guides/nrfconnect_factory_data_configuration.md b/docs/guides/nrfconnect_factory_data_configuration.md index 3dc71cd58ddd92..aef2de4a607a89 100644 --- a/docs/guides/nrfconnect_factory_data_configuration.md +++ b/docs/guides/nrfconnect_factory_data_configuration.md @@ -28,15 +28,13 @@ data secure by applying hardware write protection. > is the hardware flash protection driver, and we used it to ensure write > protection of the factory data partition in internal flash memory. -

- Nordic Semiconductor logo - nRF52840 DK -

+Nordic Semiconductor logo +nRF52840 DK
- [Overview](#overview) - - [Factory data components](#factory-data-components) + - [Factory data components](#factory-data-component-table) - [Factory data format](#factory-data-format) - [Enabling factory data support](#enabling-factory-data-support) - [Generating factory data](#generating-factory-data) @@ -46,7 +44,7 @@ data secure by applying hardware write protection. - [Option 2: Using a website validator](#option-2-using-a-website-validator) - [Option 3: Using the nRF Connect Python script](#option-3-using-the-nrf-connect-python-script) - [Preparing factory data partition on a device](#preparing-factory-data-partition-on-a-device) - - [Creating the factory data partition with the second script](#creating-the-factory-data-partition-with-the-second-script) + - [Creating the factory data partition with the second script](#creating-a-factory-data-partition-with-the-second-script) - [Building an example with factory data](#building-an-example-with-factory-data) - [Providing factory data parameters as a build argument list](#providing-factory-data-parameters-as-a-build-argument-list) - [Setting factory data parameters using interactive Kconfig interfaces](#setting-factory-data-parameters-using-interactive-kconfig-interfaces) @@ -55,8 +53,6 @@ data secure by applying hardware write protection.
- - ## Overview You can implement the factory data set described in the @@ -154,7 +150,6 @@ In the factory data set, the following formats are used: [X.509](https://www.itu.int/rec/T-REC-X.509-201910-I/en) format.
- ## Enabling factory data support @@ -185,7 +180,7 @@ partition into the device's flash memory. You can use the second script without invoking the first one by providing a JSON file written in another way. To make sure that the JSON file is correct and the device is able to read out parameters, verify the file using the -[JSON schema](#verifying-using-a-json-schema). +[JSON schema](#verifying-using-the-json-schema-tool). ### Creating factory data JSON file with the first script @@ -331,7 +326,7 @@ JSON file is verified using the prepared JSON Schema. If the script finishes successfully, go to the location you provided with the `-o` argument. Use the JSON file you find there when -[generating the factory data partition](#generating_factory_data_partition). +[generating the factory data partition](#generating-factory-data). > Note: Generating the SPAKE2+ verifier is optional and requires providing a > path to the `spake2p` executable. To get it, complete the following steps: @@ -536,7 +531,6 @@ reason, it can be programmed directly to the device using a programmer (for example, `nrfjprog`).
- ## Building an example with factory data @@ -616,7 +610,6 @@ snippet: > [Kconfig docummentation](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/zephyr/build/kconfig/menuconfig.html).
- ## Programming factory data @@ -680,13 +673,12 @@ $ west flash ```
- ## Using own factory data implementation The [factory data generation process](#generating-factory-data) described above is only an example valid for the nRF Connect platform. You can well create a HEX -file containing all [factory data components](#factory-data-components) in any +file containing all [factory data components](#factory-data-component-table) in any format and then implement a parser to read out all parameters and pass them to a provider. Each manufacturer can implement a factory data set on its own by implementing a parser and a factory data accessor inside the Matter stack. Use diff --git a/docs/index.md b/docs/index.md index 2058b1df9e99c3..e5e7e279718e71 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,6 +3,7 @@ ```{toctree} :maxdepth: 2 :caption: Contents +:hidden: QUICK_START PROJECT_FLOW @@ -12,6 +13,10 @@ discussion/index guides/index style/index examples/index -breathe BUG_REPORT ``` + +```{include} README.md +:start-line: 2 +:end-before: Building and Developing in Matter +``` diff --git a/docs/make.bat b/docs/make.bat index 9ae01a5a9afa4a..18f214815d661a 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -7,7 +7,7 @@ REM Command file for Sphinx documentation if "%SPHINXBUILD%" == "" ( set SPHINXBUILD=sphinx-build ) -set SPHINXOPTS=-c . -d _build\doctrees +set SPHINXOPTS=-W -c . -d _build\doctrees set SOURCEDIR=_build\src set BUILDDIR=_build diff --git a/examples/lock-app/cc32xx/README.md b/examples/lock-app/cc32xx/README.md index c1474a096a6b25..4cd77f6faeb235 100644 --- a/examples/lock-app/cc32xx/README.md +++ b/examples/lock-app/cc32xx/README.md @@ -5,7 +5,7 @@ Instruments CC32XX family of Wireless MCUs. --- -- [Matter CC32XX Lock Example Application](#matter-cc32xx-lock-example-application) +- [Matter CC32XX Lock Example Application](#matter-cc32xxsf-lock-example-application) - [Introduction](#introduction) - [Device UI](#device-ui) - [Building](#building) @@ -13,19 +13,15 @@ Instruments CC32XX family of Wireless MCUs. - [Compilation](#compilation) - [Programming](#programming) - [Code Composer Studio](#code-composer-studio) - - [UniFlash](#uniflash) - [Viewing Logging Output](#viewing-logging-output) - [Running the Example](#running-the-example) - [Provisioning](#provisioning) - - [Matter Remote Commands](#matter-remote-commands) - [TI Support](#ti-support) --- ## Introduction -![CC3235SF_LAUNCHXL](doc/images/cc3235sf_launchxl.jpg) - The CC32XX lock example application provides a working demonstration of a connected door lock device. This uses the open-source CHIP implementation and the Texas Instruments SimpleLink™ Wi-Fi® CC32xx software development kit. From 98667c78e75492abf9a1cbd5af3c8a13fdf4a94f Mon Sep 17 00:00:00 2001 From: Gaute Svanes Lunde Date: Wed, 29 Jun 2022 15:42:30 +0200 Subject: [PATCH 08/14] workflows: expand markdown fences in spellchecker Expand the markdown fences to include MyST for Sphinx syntax like the following: ```{include} my/file.md ``` Signed-off-by: Gaute Svanes Lunde --- .spellcheck.yml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/.spellcheck.yml b/.spellcheck.yml index 225ab2ed951c8f..31535866750a72 100644 --- a/.spellcheck.yml +++ b/.spellcheck.yml @@ -46,7 +46,11 @@ matrix: # ```python # content # ``` - - open: '(?s)^(?P *`{3,})[a-z]*$' + # + # Allow MyST extended syntax like: + # ```{include} my/file.md + # ``` + - open: '(?s)^(?P *`{3,})([a-z]*$|{[a-z]*?}\s*[^\n]*?$)' close: '^(?P=open)$' # Ignore text between inline back ticks - open: '(?P`+)' From fe7e1c966b5a2c664c90bab1bbd0c254f714a7a2 Mon Sep 17 00:00:00 2001 From: Gaute Svanes Lunde Date: Thu, 30 Jun 2022 10:18:09 +0200 Subject: [PATCH 09/14] workflow: publish Sphinx output to external repo Push the Sphinx generated documentation output to the connectedhomeip-doc repository to be used by github.io. Signed-off-by: Gaute Svanes Lunde --- .github/workflows/docbuild.yaml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docbuild.yaml b/.github/workflows/docbuild.yaml index 296aa95fcff674..2f7a91af252dab 100644 --- a/.github/workflows/docbuild.yaml +++ b/.github/workflows/docbuild.yaml @@ -48,6 +48,8 @@ jobs: - name: Deploy to gh-pages uses: peaceiris/actions-gh-pages@v3 with: - github_token: ${{ secrets.GITHUB_TOKEN }} + deploy_key: ${{ secrets.DOXYGEN_DEPLOY_KEY }} + external_repository: project-chip/connectedhomeip-doc publish_dir: matter/docs/_build/html - destination_dir: docs + # Keep only the latest version of the documentation + force_orphan: true \ No newline at end of file From 4f7fed1a18779c116bc4d4e6c8371b0bd96d3c5f Mon Sep 17 00:00:00 2001 From: Gaute Svanes Lunde Date: Thu, 30 Jun 2022 17:00:47 +0200 Subject: [PATCH 10/14] sphinx: revert doxygen to previous state No longer include doxygen, Breathe or doxyrunner in the Sphinx build process. Signed-off-by: Gaute Svanes Lunde --- .github/workflows/docbuild.yaml | 9 +- docs/ChipDoxygenLayout.xml | 225 ++ docs/Doxyfile | 2576 +++++++++++++++++ docs/_doxygen/logo.png | Bin 6871 -> 0 bytes docs/_extensions/doxyrunner.py | 388 --- docs/conf.py | 23 +- .../Rendezvous/RendezvousSessionGeneral.dot | 37 + .../dots/Rendezvous/RendezvousSessionInit.dot | 83 + docs/index.md | 9 +- docs/namespaces.dox | 37 + examples/shell/README.md | 1 - 11 files changed, 2969 insertions(+), 419 deletions(-) create mode 100644 docs/ChipDoxygenLayout.xml create mode 100644 docs/Doxyfile delete mode 100644 docs/_doxygen/logo.png delete mode 100644 docs/_extensions/doxyrunner.py create mode 100644 docs/dots/Rendezvous/RendezvousSessionGeneral.dot create mode 100644 docs/dots/Rendezvous/RendezvousSessionInit.dot create mode 100644 docs/namespaces.dox diff --git a/.github/workflows/docbuild.yaml b/.github/workflows/docbuild.yaml index 2f7a91af252dab..f5edaa67ea5746 100644 --- a/.github/workflows/docbuild.yaml +++ b/.github/workflows/docbuild.yaml @@ -27,16 +27,10 @@ jobs: with: path: ~/.cache/pip key: ${{ runner.os }}-doc-pip - - name: Install packages - run: | - sudo apt update - DOXYGEN_VERSION=1.9.4 - wget --no-verbose https://downloads.sourceforge.net/project/doxygen/rel-${DOXYGEN_VERSION}/doxygen-${DOXYGEN_VERSION}.linux.bin.tar.gz - tar xf doxygen-${DOXYGEN_VERSION}.linux.bin.tar.gz - echo "${PWD}/doxygen-${DOXYGEN_VERSION}/bin" >> $GITHUB_PATH - name: Install base dependencies working-directory: matter run: | + sudo apt update sudo pip3 install -U pip pip3 install -r docs/requirements.txt - name: Build documentation @@ -46,6 +40,7 @@ jobs: make html touch _build/html/.nojekyll - name: Deploy to gh-pages + if: github.repository == 'project-chip/connectedhomeip' uses: peaceiris/actions-gh-pages@v3 with: deploy_key: ${{ secrets.DOXYGEN_DEPLOY_KEY }} diff --git a/docs/ChipDoxygenLayout.xml b/docs/ChipDoxygenLayout.xml new file mode 100644 index 00000000000000..68f3f9e3e703b6 --- /dev/null +++ b/docs/ChipDoxygenLayout.xml @@ -0,0 +1,225 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/Doxyfile b/docs/Doxyfile new file mode 100644 index 00000000000000..9cb29526498d3c --- /dev/null +++ b/docs/Doxyfile @@ -0,0 +1,2576 @@ +# Doxyfile 1.8.18 + +# This file describes the settings to be used by the documentation system +# doxygen (www.doxygen.org) for a project. +# +# All text after a double hash (##) is considered a comment and is placed in +# front of the TAG it is preceding. +# +# All text after a single hash (#) is considered a comment and will be ignored. +# The format is: +# TAG = value [value, ...] +# For lists, items can also be appended using: +# TAG += value [value, ...] +# Values that contain spaces should be placed between quotes (\" \"). + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- + +# This tag specifies the encoding used for all characters in the configuration +# file that follow. The default is UTF-8 which is also the encoding used for all +# text before the first occurrence of this tag. Doxygen uses libiconv (or the +# iconv built into libc) for the transcoding. See +# https://www.gnu.org/software/libiconv/ for the list of possible encodings. +# The default value is: UTF-8. + +DOXYFILE_ENCODING = UTF-8 + +# The PROJECT_NAME tag is a single word (or a sequence of words surrounded by +# double-quotes, unless you are using Doxywizard) that should identify the +# project for which the documentation is generated. This name is used in the +# title of most generated pages and in a few other places. +# The default value is: My Project. + +PROJECT_NAME = $(CHIP_NAME) + +# The PROJECT_NUMBER tag can be used to enter a project or revision number. This +# could be handy for archiving the generated documentation or if some version +# control system is used. + +PROJECT_NUMBER = $(CHIP_VERSION) + +# Using the PROJECT_BRIEF tag one can provide an optional one line description +# for a project that appears at the top of each page and should give viewer a +# quick idea about the purpose of the project. Keep the description short. + +PROJECT_BRIEF = + +# With the PROJECT_LOGO tag one can specify a logo or an icon that is included +# in the documentation. The maximum height of the logo should not exceed 55 +# pixels and the maximum width should not exceed 200 pixels. Doxygen will copy +# the logo to the output directory. + +PROJECT_LOGO = docs/images/logo.svg + +# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path +# into which the generated documentation will be written. If a relative path is +# entered, it will be relative to the location where doxygen was started. If +# left blank the current directory will be used. + +OUTPUT_DIRECTORY = docs + +# If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- +# directories (in 2 levels) under the output directory of each output format and +# will distribute the generated files over these directories. Enabling this +# option can be useful when feeding doxygen a huge amount of source files, where +# putting all generated files in the same directory would otherwise causes +# performance problems for the file system. +# The default value is: NO. + +CREATE_SUBDIRS = NO + +# If the ALLOW_UNICODE_NAMES tag is set to YES, doxygen will allow non-ASCII +# characters to appear in the names of generated files. If set to NO, non-ASCII +# characters will be escaped, for example _xE3_x81_x84 will be used for Unicode +# U+3044. +# The default value is: NO. + +ALLOW_UNICODE_NAMES = NO + +# The OUTPUT_LANGUAGE tag is used to specify the language in which all +# documentation generated by doxygen is written. Doxygen will use this +# information to generate all constant output in the proper language. +# Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Catalan, Chinese, +# Chinese-Traditional, Croatian, Czech, Danish, Dutch, English (United States), +# Esperanto, Farsi (Persian), Finnish, French, German, Greek, Hungarian, +# Indonesian, Italian, Japanese, Japanese-en (Japanese with English messages), +# Korean, Korean-en (Korean with English messages), Latvian, Lithuanian, +# Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese, Romanian, Russian, +# Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish, Swedish, Turkish, +# Ukrainian and Vietnamese. +# The default value is: English. + +OUTPUT_LANGUAGE = English + +# The OUTPUT_TEXT_DIRECTION tag is used to specify the direction in which all +# documentation generated by doxygen is written. Doxygen will use this +# information to generate all generated output in the proper direction. +# Possible values are: None, LTR, RTL and Context. +# The default value is: None. + +OUTPUT_TEXT_DIRECTION = None + +# If the BRIEF_MEMBER_DESC tag is set to YES, doxygen will include brief member +# descriptions after the members that are listed in the file and class +# documentation (similar to Javadoc). Set to NO to disable this. +# The default value is: YES. + +BRIEF_MEMBER_DESC = YES + +# If the REPEAT_BRIEF tag is set to YES, doxygen will prepend the brief +# description of a member or function before the detailed description +# +# Note: If both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the +# brief descriptions will be completely suppressed. +# The default value is: YES. + +REPEAT_BRIEF = YES + +# This tag implements a quasi-intelligent brief description abbreviator that is +# used to form the text in various listings. Each string in this list, if found +# as the leading text of the brief description, will be stripped from the text +# and the result, after processing the whole list, is used as the annotated +# text. Otherwise, the brief description is used as-is. If left blank, the +# following values are used ($name is automatically replaced with the name of +# the entity):The $name class, The $name widget, The $name file, is, provides, +# specifies, contains, represents, a, an and the. + +ABBREVIATE_BRIEF = "The $name class" \ + "The $name widget" \ + "The $name file" \ + is \ + provides \ + specifies \ + contains \ + represents \ + a \ + an \ + the + +# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then +# doxygen will generate a detailed section even if there is only a brief +# description. +# The default value is: NO. + +ALWAYS_DETAILED_SEC = NO + +# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all +# inherited members of a class in the documentation of that class as if those +# members were ordinary class members. Constructors, destructors and assignment +# operators of the base classes will not be shown. +# The default value is: NO. + +INLINE_INHERITED_MEMB = NO + +# If the FULL_PATH_NAMES tag is set to YES, doxygen will prepend the full path +# before files name in the file list and in the header files. If set to NO the +# shortest path that makes the file name unique will be used +# The default value is: YES. + +FULL_PATH_NAMES = YES + +# The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path. +# Stripping is only done if one of the specified strings matches the left-hand +# part of the path. The tag can be used to show relative paths in the file list. +# If left blank the directory from which doxygen is run is used as the path to +# strip. +# +# Note that you can specify absolute paths here, but also relative paths, which +# will be relative from the directory where doxygen is started. +# This tag requires that the tag FULL_PATH_NAMES is set to YES. + +STRIP_FROM_PATH = src + +# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the +# path mentioned in the documentation of a class, which tells the reader which +# header file to include in order to use a class. If left blank only the name of +# the header file containing the class definition is used. Otherwise one should +# specify the list of include paths that are normally passed to the compiler +# using the -I flag. + +STRIP_FROM_INC_PATH = src + +# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but +# less readable) file names. This can be useful is your file systems doesn't +# support long names like on DOS, Mac, or CD-ROM. +# The default value is: NO. + +SHORT_NAMES = NO + +# If the JAVADOC_AUTOBRIEF tag is set to YES then doxygen will interpret the +# first line (until the first dot) of a Javadoc-style comment as the brief +# description. If set to NO, the Javadoc-style will behave just like regular Qt- +# style comments (thus requiring an explicit @brief command for a brief +# description.) +# The default value is: NO. + +JAVADOC_AUTOBRIEF = YES + +# If the JAVADOC_BANNER tag is set to YES then doxygen will interpret a line +# such as +# /*************** +# as being the beginning of a Javadoc-style comment "banner". If set to NO, the +# Javadoc-style will behave just like regular comments and it will not be +# interpreted by doxygen. +# The default value is: NO. + +JAVADOC_BANNER = NO + +# If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first +# line (until the first dot) of a Qt-style comment as the brief description. If +# set to NO, the Qt-style will behave just like regular Qt-style comments (thus +# requiring an explicit \brief command for a brief description.) +# The default value is: NO. + +QT_AUTOBRIEF = NO + +# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make doxygen treat a +# multi-line C++ special comment block (i.e. a block of //! or /// comments) as +# a brief description. This used to be the default behavior. The new default is +# to treat a multi-line C++ comment block as a detailed description. Set this +# tag to YES if you prefer the old behavior instead. +# +# Note that setting this tag to YES also means that rational rose comments are +# not recognized any more. +# The default value is: NO. + +MULTILINE_CPP_IS_BRIEF = NO + +# If the INHERIT_DOCS tag is set to YES then an undocumented member inherits the +# documentation from any documented member that it re-implements. +# The default value is: YES. + +INHERIT_DOCS = YES + +# If the SEPARATE_MEMBER_PAGES tag is set to YES then doxygen will produce a new +# page for each member. If set to NO, the documentation of a member will be part +# of the file/class/namespace that contains it. +# The default value is: NO. + +SEPARATE_MEMBER_PAGES = NO + +# The TAB_SIZE tag can be used to set the number of spaces in a tab. Doxygen +# uses this value to replace tabs by spaces in code fragments. +# Minimum value: 1, maximum value: 16, default value: 4. + +TAB_SIZE = 4 + +# This tag can be used to specify a number of aliases that act as commands in +# the documentation. An alias has the form: +# name=value +# For example adding +# "sideeffect=@par Side Effects:\n" +# will allow you to put the command \sideeffect (or @sideeffect) in the +# documentation, which will result in a user-defined paragraph with heading +# "Side Effects:". You can put \n's in the value part of an alias to insert +# newlines (in the resulting output). You can put ^^ in the value part of an +# alias to insert a newline as if a physical newline was in the original file. +# When you need a literal { or } or , in the value part of an alias you have to +# escape them by means of a backslash (\), this can lead to conflicts with the +# commands \{ and \} for these it is advised to use the version @{ and @} or use +# a double escape (\\{ and \\}) + +ALIASES = + +# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources +# only. Doxygen will then generate output that is more tailored for C. For +# instance, some of the names that are used will be different. The list of all +# members will be omitted, etc. +# The default value is: NO. + +OPTIMIZE_OUTPUT_FOR_C = NO + +# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or +# Python sources only. Doxygen will then generate output that is more tailored +# for that language. For instance, namespaces will be presented as packages, +# qualified scopes will look different, etc. +# The default value is: NO. + +OPTIMIZE_OUTPUT_JAVA = NO + +# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran +# sources. Doxygen will then generate output that is tailored for Fortran. +# The default value is: NO. + +OPTIMIZE_FOR_FORTRAN = NO + +# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL +# sources. Doxygen will then generate output that is tailored for VHDL. +# The default value is: NO. + +OPTIMIZE_OUTPUT_VHDL = NO + +# Set the OPTIMIZE_OUTPUT_SLICE tag to YES if your project consists of Slice +# sources only. Doxygen will then generate output that is more tailored for that +# language. For instance, namespaces will be presented as modules, types will be +# separated into more groups, etc. +# The default value is: NO. + +OPTIMIZE_OUTPUT_SLICE = NO + +# Doxygen selects the parser to use depending on the extension of the files it +# parses. With this tag you can assign which parser to use for a given +# extension. Doxygen has a built-in mapping, but you can override or extend it +# using this tag. The format is ext=language, where ext is a file extension, and +# language is one of the parsers supported by doxygen: IDL, Java, JavaScript, +# Csharp (C#), C, C++, D, PHP, md (Markdown), Objective-C, Python, Slice, VHDL, +# Fortran (fixed format Fortran: FortranFixed, free formatted Fortran: +# FortranFree, unknown formatted Fortran: Fortran. In the later case the parser +# tries to guess whether the code is fixed or free formatted code, this is the +# default for Fortran type files). For instance to make doxygen treat .inc files +# as Fortran files (default is PHP), and .f files as C (default is Fortran), +# use: inc=Fortran f=C. +# +# Note: For files without extension you can use no_extension as a placeholder. +# +# Note that for custom extensions you also need to set FILE_PATTERNS otherwise +# the files are not read by doxygen. + +EXTENSION_MAPPING = h=C++ + +# If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments +# according to the Markdown format, which allows for more readable +# documentation. See https://daringfireball.net/projects/markdown/ for details. +# The output of markdown processing is further processed by doxygen, so you can +# mix doxygen, HTML, and XML commands with Markdown formatting. Disable only in +# case of backward compatibilities issues. +# The default value is: YES. + +MARKDOWN_SUPPORT = YES + +# When the TOC_INCLUDE_HEADINGS tag is set to a non-zero value, all headings up +# to that level are automatically included in the table of contents, even if +# they do not have an id attribute. +# Note: This feature currently applies only to Markdown headings. +# Minimum value: 0, maximum value: 99, default value: 5. +# This tag requires that the tag MARKDOWN_SUPPORT is set to YES. + +TOC_INCLUDE_HEADINGS = 5 + +# When enabled doxygen tries to link words that correspond to documented +# classes, or namespaces to their corresponding documentation. Such a link can +# be prevented in individual cases by putting a % sign in front of the word or +# globally by setting AUTOLINK_SUPPORT to NO. +# The default value is: YES. + +AUTOLINK_SUPPORT = YES + +# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want +# to include (a tag file for) the STL sources as input, then you should set this +# tag to YES in order to let doxygen match functions declarations and +# definitions whose arguments contain STL classes (e.g. func(std::string); +# versus func(std::string) {}). This also make the inheritance and collaboration +# diagrams that involve STL classes more complete and accurate. +# The default value is: NO. + +BUILTIN_STL_SUPPORT = YES + +# If you use Microsoft's C++/CLI language, you should set this option to YES to +# enable parsing support. +# The default value is: NO. + +CPP_CLI_SUPPORT = NO + +# Set the SIP_SUPPORT tag to YES if your project consists of sip (see: +# https://www.riverbankcomputing.com/software/sip/intro) sources only. Doxygen +# will parse them like normal C++ but will assume all classes use public instead +# of private inheritance when no explicit protection keyword is present. +# The default value is: NO. + +SIP_SUPPORT = NO + +# For Microsoft's IDL there are propget and propput attributes to indicate +# getter and setter methods for a property. Setting this option to YES will make +# doxygen to replace the get and set methods by a property in the documentation. +# This will only work if the methods are indeed getting or setting a simple +# type. If this is not the case, or you want to show the methods anyway, you +# should set this option to NO. +# The default value is: YES. + +IDL_PROPERTY_SUPPORT = YES + +# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC +# tag is set to YES then doxygen will reuse the documentation of the first +# member in the group (if any) for the other members of the group. By default +# all members of a group must be documented explicitly. +# The default value is: NO. + +DISTRIBUTE_GROUP_DOC = NO + +# If one adds a struct or class to a group and this option is enabled, then also +# any nested class or struct is added to the same group. By default this option +# is disabled and one has to add nested compounds explicitly via \ingroup. +# The default value is: NO. + +GROUP_NESTED_COMPOUNDS = NO + +# Set the SUBGROUPING tag to YES to allow class member groups of the same type +# (for instance a group of public functions) to be put as a subgroup of that +# type (e.g. under the Public Functions section). Set it to NO to prevent +# subgrouping. Alternatively, this can be done per class using the +# \nosubgrouping command. +# The default value is: YES. + +SUBGROUPING = YES + +# When the INLINE_GROUPED_CLASSES tag is set to YES, classes, structs and unions +# are shown inside the group in which they are included (e.g. using \ingroup) +# instead of on a separate page (for HTML and Man pages) or section (for LaTeX +# and RTF). +# +# Note that this feature does not work in combination with +# SEPARATE_MEMBER_PAGES. +# The default value is: NO. + +INLINE_GROUPED_CLASSES = NO + +# When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and unions +# with only public data fields or simple typedef fields will be shown inline in +# the documentation of the scope in which they are defined (i.e. file, +# namespace, or group documentation), provided this scope is documented. If set +# to NO, structs, classes, and unions are shown on a separate page (for HTML and +# Man pages) or section (for LaTeX and RTF). +# The default value is: NO. + +INLINE_SIMPLE_STRUCTS = NO + +# When TYPEDEF_HIDES_STRUCT tag is enabled, a typedef of a struct, union, or +# enum is documented as struct, union, or enum with the name of the typedef. So +# typedef struct TypeS {} TypeT, will appear in the documentation as a struct +# with name TypeT. When disabled the typedef will appear as a member of a file, +# namespace, or class. And the struct will be named TypeS. This can typically be +# useful for C code in case the coding convention dictates that all compound +# types are typedef'ed and only the typedef is referenced, never the tag name. +# The default value is: NO. + +TYPEDEF_HIDES_STRUCT = NO + +# The size of the symbol lookup cache can be set using LOOKUP_CACHE_SIZE. This +# cache is used to resolve symbols given their name and scope. Since this can be +# an expensive process and often the same symbol appears multiple times in the +# code, doxygen keeps a cache of pre-resolved symbols. If the cache is too small +# doxygen will become slower. If the cache is too large, memory is wasted. The +# cache size is given by this formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range +# is 0..9, the default is 0, corresponding to a cache size of 2^16=65536 +# symbols. At the end of a run doxygen will report the cache usage and suggest +# the optimal cache size from a speed point of view. +# Minimum value: 0, maximum value: 9, default value: 0. + +LOOKUP_CACHE_SIZE = 0 + +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- + +# If the EXTRACT_ALL tag is set to YES, doxygen will assume all entities in +# documentation are documented, even if no documentation was available. Private +# class members and static file members will be hidden unless the +# EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES. +# Note: This will also disable the warnings about undocumented members that are +# normally produced when WARNINGS is set to YES. +# The default value is: NO. + +EXTRACT_ALL = YES + +# If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will +# be included in the documentation. +# The default value is: NO. + +EXTRACT_PRIVATE = NO + +# If the EXTRACT_PRIV_VIRTUAL tag is set to YES, documented private virtual +# methods of a class will be included in the documentation. +# The default value is: NO. + +EXTRACT_PRIV_VIRTUAL = NO + +# If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal +# scope will be included in the documentation. +# The default value is: NO. + +EXTRACT_PACKAGE = NO + +# If the EXTRACT_STATIC tag is set to YES, all static members of a file will be +# included in the documentation. +# The default value is: NO. + +EXTRACT_STATIC = YES + +# If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined +# locally in source files will be included in the documentation. If set to NO, +# only classes defined in header files are included. Does not have any effect +# for Java sources. +# The default value is: YES. + +EXTRACT_LOCAL_CLASSES = YES + +# This flag is only useful for Objective-C code. If set to YES, local methods, +# which are defined in the implementation section but not in the interface are +# included in the documentation. If set to NO, only methods in the interface are +# included. +# The default value is: NO. + +EXTRACT_LOCAL_METHODS = NO + +# If this flag is set to YES, the members of anonymous namespaces will be +# extracted and appear in the documentation as a namespace called +# 'anonymous_namespace{file}', where file will be replaced with the base name of +# the file that contains the anonymous namespace. By default anonymous namespace +# are hidden. +# The default value is: NO. + +EXTRACT_ANON_NSPACES = NO + +# If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all +# undocumented members inside documented classes or files. If set to NO these +# members will be included in the various overviews, but no documentation +# section is generated. This option has no effect if EXTRACT_ALL is enabled. +# The default value is: NO. + +HIDE_UNDOC_MEMBERS = NO + +# If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all +# undocumented classes that are normally visible in the class hierarchy. If set +# to NO, these classes will be included in the various overviews. This option +# has no effect if EXTRACT_ALL is enabled. +# The default value is: NO. + +HIDE_UNDOC_CLASSES = NO + +# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend +# declarations. If set to NO, these declarations will be included in the +# documentation. +# The default value is: NO. + +HIDE_FRIEND_COMPOUNDS = NO + +# If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any +# documentation blocks found inside the body of a function. If set to NO, these +# blocks will be appended to the function's detailed documentation block. +# The default value is: NO. + +HIDE_IN_BODY_DOCS = NO + +# The INTERNAL_DOCS tag determines if documentation that is typed after a +# \internal command is included. If the tag is set to NO then the documentation +# will be excluded. Set it to YES to include the internal documentation. +# The default value is: NO. + +INTERNAL_DOCS = NO + +# If the CASE_SENSE_NAMES tag is set to NO then doxygen will only generate file +# names in lower-case letters. If set to YES, upper-case letters are also +# allowed. This is useful if you have classes or files whose names only differ +# in case and if your file system supports case sensitive file names. Windows +# (including Cygwin) ands Mac users are advised to set this option to NO. +# The default value is: system dependent. + +CASE_SENSE_NAMES = NO + +# If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with +# their full class and namespace scopes in the documentation. If set to YES, the +# scope will be hidden. +# The default value is: NO. + +HIDE_SCOPE_NAMES = NO + +# If the HIDE_COMPOUND_REFERENCE tag is set to NO (default) then doxygen will +# append additional text to a page's title, such as Class Reference. If set to +# YES the compound reference will be hidden. +# The default value is: NO. + +HIDE_COMPOUND_REFERENCE= NO + +# If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of +# the files that are included by a file in the documentation of that file. +# The default value is: YES. + +SHOW_INCLUDE_FILES = YES + +# If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each +# grouped member an include statement to the documentation, telling the reader +# which file to include in order to use the member. +# The default value is: NO. + +SHOW_GROUPED_MEMB_INC = NO + +# If the FORCE_LOCAL_INCLUDES tag is set to YES then doxygen will list include +# files with double quotes in the documentation rather than with sharp brackets. +# The default value is: NO. + +FORCE_LOCAL_INCLUDES = NO + +# If the INLINE_INFO tag is set to YES then a tag [inline] is inserted in the +# documentation for inline members. +# The default value is: YES. + +INLINE_INFO = YES + +# If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the +# (detailed) documentation of file and class members alphabetically by member +# name. If set to NO, the members will appear in declaration order. +# The default value is: YES. + +SORT_MEMBER_DOCS = YES + +# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief +# descriptions of file, namespace and class members alphabetically by member +# name. If set to NO, the members will appear in declaration order. Note that +# this will also influence the order of the classes in the class list. +# The default value is: NO. + +SORT_BRIEF_DOCS = NO + +# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the +# (brief and detailed) documentation of class members so that constructors and +# destructors are listed first. If set to NO the constructors will appear in the +# respective orders defined by SORT_BRIEF_DOCS and SORT_MEMBER_DOCS. +# Note: If SORT_BRIEF_DOCS is set to NO this option is ignored for sorting brief +# member documentation. +# Note: If SORT_MEMBER_DOCS is set to NO this option is ignored for sorting +# detailed member documentation. +# The default value is: NO. + +SORT_MEMBERS_CTORS_1ST = NO + +# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy +# of group names into alphabetical order. If set to NO the group names will +# appear in their defined order. +# The default value is: NO. + +SORT_GROUP_NAMES = NO + +# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by +# fully-qualified names, including namespaces. If set to NO, the class list will +# be sorted only by class name, not including the namespace part. +# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. +# Note: This option applies only to the class list, not to the alphabetical +# list. +# The default value is: NO. + +SORT_BY_SCOPE_NAME = NO + +# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to do proper +# type resolution of all parameters of a function it will reject a match between +# the prototype and the implementation of a member function even if there is +# only one candidate or it is obvious which candidate to choose by doing a +# simple string match. By disabling STRICT_PROTO_MATCHING doxygen will still +# accept a match between prototype and implementation in such cases. +# The default value is: NO. + +STRICT_PROTO_MATCHING = NO + +# The GENERATE_TODOLIST tag can be used to enable (YES) or disable (NO) the todo +# list. This list is created by putting \todo commands in the documentation. +# The default value is: YES. + +GENERATE_TODOLIST = YES + +# The GENERATE_TESTLIST tag can be used to enable (YES) or disable (NO) the test +# list. This list is created by putting \test commands in the documentation. +# The default value is: YES. + +GENERATE_TESTLIST = YES + +# The GENERATE_BUGLIST tag can be used to enable (YES) or disable (NO) the bug +# list. This list is created by putting \bug commands in the documentation. +# The default value is: YES. + +GENERATE_BUGLIST = YES + +# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or disable (NO) +# the deprecated list. This list is created by putting \deprecated commands in +# the documentation. +# The default value is: YES. + +GENERATE_DEPRECATEDLIST= YES + +# The ENABLED_SECTIONS tag can be used to enable conditional documentation +# sections, marked by \if ... \endif and \cond +# ... \endcond blocks. + +ENABLED_SECTIONS = + +# The MAX_INITIALIZER_LINES tag determines the maximum number of lines that the +# initial value of a variable or macro / define can have for it to appear in the +# documentation. If the initializer consists of more lines than specified here +# it will be hidden. Use a value of 0 to hide initializers completely. The +# appearance of the value of individual variables and macros / defines can be +# controlled using \showinitializer or \hideinitializer command in the +# documentation regardless of this setting. +# Minimum value: 0, maximum value: 10000, default value: 30. + +MAX_INITIALIZER_LINES = 30 + +# Set the SHOW_USED_FILES tag to NO to disable the list of files generated at +# the bottom of the documentation of classes and structs. If set to YES, the +# list will mention the files that were used to generate the documentation. +# The default value is: YES. + +SHOW_USED_FILES = YES + +# Set the SHOW_FILES tag to NO to disable the generation of the Files page. This +# will remove the Files entry from the Quick Index and from the Folder Tree View +# (if specified). +# The default value is: YES. + +SHOW_FILES = YES + +# Set the SHOW_NAMESPACES tag to NO to disable the generation of the Namespaces +# page. This will remove the Namespaces entry from the Quick Index and from the +# Folder Tree View (if specified). +# The default value is: YES. + +SHOW_NAMESPACES = YES + +# The FILE_VERSION_FILTER tag can be used to specify a program or script that +# doxygen should invoke to get the current version for each file (typically from +# the version control system). Doxygen will invoke the program by executing (via +# popen()) the command command input-file, where command is the value of the +# FILE_VERSION_FILTER tag, and input-file is the name of an input file provided +# by doxygen. Whatever the program writes to standard output is used as the file +# version. For an example see the documentation. + +FILE_VERSION_FILTER = + +# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed +# by doxygen. The layout file controls the global structure of the generated +# output files in an output format independent way. To create the layout file +# that represents doxygen's defaults, run doxygen with the -l option. You can +# optionally specify a file name after the option, if omitted DoxygenLayout.xml +# will be used as the name of the layout file. +# +# Note that if you run doxygen from a directory containing a file called +# DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE +# tag is left empty. + +LAYOUT_FILE = docs/ChipDoxygenLayout.xml + +# The CITE_BIB_FILES tag can be used to specify one or more bib files containing +# the reference definitions. This must be a list of .bib files. The .bib +# extension is automatically appended if omitted. This requires the bibtex tool +# to be installed. See also https://en.wikipedia.org/wiki/BibTeX for more info. +# For LaTeX the style of the bibliography can be controlled using +# LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the +# search path. See also \cite for info how to create references. + +CITE_BIB_FILES = + +#--------------------------------------------------------------------------- +# Configuration options related to warning and progress messages +#--------------------------------------------------------------------------- + +# The QUIET tag can be used to turn on/off the messages that are generated to +# standard output by doxygen. If QUIET is set to YES this implies that the +# messages are off. +# The default value is: NO. + +QUIET = NO + +# The WARNINGS tag can be used to turn on/off the warning messages that are +# generated to standard error (stderr) by doxygen. If WARNINGS is set to YES +# this implies that the warnings are on. +# +# Tip: Turn warnings on while writing the documentation. +# The default value is: YES. + +WARNINGS = YES + +# If the WARN_IF_UNDOCUMENTED tag is set to YES then doxygen will generate +# warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag +# will automatically be disabled. +# The default value is: YES. + +WARN_IF_UNDOCUMENTED = NO + +# If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for +# potential errors in the documentation, such as not documenting some parameters +# in a documented function, or documenting parameters that don't exist or using +# markup commands wrongly. +# The default value is: YES. + +WARN_IF_DOC_ERROR = YES + +# This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that +# are documented, but have no documentation for their parameters or return +# value. If set to NO, doxygen will only warn about wrong or incomplete +# parameter documentation, but not about the absence of documentation. If +# EXTRACT_ALL is set to YES then this flag will automatically be disabled. +# The default value is: NO. + +WARN_NO_PARAMDOC = NO + +# If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when +# a warning is encountered. +# The default value is: NO. + +WARN_AS_ERROR = YES + +# The WARN_FORMAT tag determines the format of the warning messages that doxygen +# can produce. The string should contain the $file, $line, and $text tags, which +# will be replaced by the file and line number from which the warning originated +# and the warning text. Optionally the format may contain $version, which will +# be replaced by the version of the file (if it could be obtained via +# FILE_VERSION_FILTER) +# The default value is: $file:$line: $text. + +WARN_FORMAT = "$file:$line: $text" + +# The WARN_LOGFILE tag can be used to specify a file to which warning and error +# messages should be written. If left blank the output is written to standard +# error (stderr). + +WARN_LOGFILE = + +#--------------------------------------------------------------------------- +# Configuration options related to the input files +#--------------------------------------------------------------------------- + +# The INPUT tag is used to specify the files and/or directories that contain +# documented source files. You may enter file names like myfile.cpp or +# directories like /usr/src/myproject. Separate the files or directories with +# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING +# Note: If this tag is empty the current directory is searched. + +INPUT = README.md \ + CODE_OF_CONDUCT.md \ + CONTRIBUTING.md \ + docs/README.md \ + docs/guides/BUILDING.md \ + docs/VSCODE_DEVELOPMENT.md \ + docs/PROJECT_FLOW.md \ + docs/style/style_guide.md \ + src/ble \ + src/controller \ + src/crypto \ + src/include \ + src/inet \ + src/lib/dnssd \ + src/lib/core \ + src/lib/support \ + src/lib/shell \ + src/platform \ + src/setup_payload \ + src/system \ + src/transport \ + src/test_driver/linux-cirque/README.md + +USE_MDFILE_AS_MAINPAGE = README.md + +# This tag can be used to specify the character encoding of the source files +# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses +# libiconv (or the iconv built into libc) for the transcoding. See the libiconv +# documentation (see: https://www.gnu.org/software/libiconv/) for the list of +# possible encodings. +# The default value is: UTF-8. + +INPUT_ENCODING = UTF-8 + +# If the value of the INPUT tag contains directories, you can use the +# FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp and +# *.h) to filter out the source-files in the directories. +# +# Note that for custom extensions or not directly supported extensions you also +# need to set EXTENSION_MAPPING for the extension otherwise the files are not +# read by doxygen. +# +# If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp, +# *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, +# *.hh, *.hxx, *.hpp, *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc, +# *.m, *.markdown, *.md, *.mm, *.dox (to be provided as doxygen C comment), +# *.doc (to be provided as doxygen C comment), *.txt (to be provided as doxygen +# C comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, *.f18, *.f, *.for, *.vhd, +# *.vhdl, *.ucf, *.qsf and *.ice. + +FILE_PATTERNS = *.c \ + *.cc \ + *.cxx \ + *.cpp \ + *.c++ \ + *.d \ + *.java \ + *.ii \ + *.ixx \ + *.ipp \ + *.i++ \ + *.inl \ + *.h \ + *.hh \ + *.hxx \ + *.hpp \ + *.h++ \ + *.idl \ + *.odl \ + *.cs \ + *.php \ + *.php3 \ + *.inc \ + *.m \ + *.mm \ + *.dox \ + *.py \ + *.f90 \ + *.f \ + *.for \ + *.vhd \ + *.vhdl + +# The RECURSIVE tag can be used to specify whether or not subdirectories should +# be searched for input files as well. +# The default value is: NO. + +RECURSIVE = YES + +# The EXCLUDE tag can be used to specify files and/or directories that should be +# excluded from the INPUT source files. This way you can easily exclude a +# subdirectory from a directory tree whose root is specified with the INPUT tag. +# +# Note that relative paths are relative to the directory from which doxygen is +# run. + +EXCLUDE = + +# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or +# directories that are symbolic links (a Unix file system feature) are excluded +# from the input. +# The default value is: NO. + +EXCLUDE_SYMLINKS = NO + +# If the value of the INPUT tag contains directories, you can use the +# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude +# certain files from those directories. +# +# Note that the wildcards are matched against the file with absolute path, so to +# exclude all test directories for example use the pattern */test/* + +EXCLUDE_PATTERNS = NetworkProvisioningServer* \ + */tests/* \ + */dbus/* \ + */gen/* \ + */zap-generated/* + +# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names +# (namespaces, classes, functions, etc.) that should be excluded from the +# output. The symbol name can be a fully qualified name, a word, or if the +# wildcard * is used, a substring. Examples: ANamespace, AClass, +# AClass::ANamespace, ANamespace::*Test +# +# Note that the wildcards are matched against the file with absolute path, so to +# exclude all test directories use the pattern */test/* + +EXCLUDE_SYMBOLS = VerifyOrExit \ + SuccessOrExit \ + ExitNow \ + */dbus/* + +# The EXAMPLE_PATH tag can be used to specify one or more files or directories +# that contain example code fragments that are included (see the \include +# command). + +EXAMPLE_PATH = + +# If the value of the EXAMPLE_PATH tag contains directories, you can use the +# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and +# *.h) to filter out the source-files in the directories. If left blank all +# files are included. + +EXAMPLE_PATTERNS = * + +# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be +# searched for input files to be used with the \include or \dontinclude commands +# irrespective of the value of the RECURSIVE tag. +# The default value is: NO. + +EXAMPLE_RECURSIVE = NO + +# The IMAGE_PATH tag can be used to specify one or more files or directories +# that contain images that are to be included in the documentation (see the +# \image command). + +IMAGE_PATH = docs/images + +# The INPUT_FILTER tag can be used to specify a program that doxygen should +# invoke to filter for each input file. Doxygen will invoke the filter program +# by executing (via popen()) the command: +# +# +# +# where is the value of the INPUT_FILTER tag, and is the +# name of an input file. Doxygen will then use the output that the filter +# program writes to standard output. If FILTER_PATTERNS is specified, this tag +# will be ignored. +# +# Note that the filter must not add or remove lines; it is applied before the +# code is scanned, but not when the output code is generated. If lines are added +# or removed, the anchors will not be placed correctly. +# +# Note that for custom extensions or not directly supported extensions you also +# need to set EXTENSION_MAPPING for the extension otherwise the files are not +# properly processed by doxygen. + +INPUT_FILTER = + +# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern +# basis. Doxygen will compare the file name with each pattern and apply the +# filter if there is a match. The filters are a list of the form: pattern=filter +# (like *.cpp=my_cpp_filter). See INPUT_FILTER for further information on how +# filters are used. If the FILTER_PATTERNS tag is empty or if none of the +# patterns match the file name, INPUT_FILTER is applied. +# +# Note that for custom extensions or not directly supported extensions you also +# need to set EXTENSION_MAPPING for the extension otherwise the files are not +# properly processed by doxygen. + +FILTER_PATTERNS = + +# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using +# INPUT_FILTER) will also be used to filter the input files that are used for +# producing the source files to browse (i.e. when SOURCE_BROWSER is set to YES). +# The default value is: NO. + +FILTER_SOURCE_FILES = NO + +# The FILTER_SOURCE_PATTERNS tag can be used to specify source filters per file +# pattern. A pattern will override the setting for FILTER_PATTERN (if any) and +# it is also possible to disable source filtering for a specific pattern using +# *.ext= (so without naming a filter). +# This tag requires that the tag FILTER_SOURCE_FILES is set to YES. + +FILTER_SOURCE_PATTERNS = + +# If the USE_MDFILE_AS_MAINPAGE tag refers to the name of a markdown file that +# is part of the input, its contents will be placed on the main page +# (index.html). This can be useful if you have a project on for instance GitHub +# and want to reuse the introduction page also for the doxygen output. + +USE_MDFILE_AS_MAINPAGE = + +#--------------------------------------------------------------------------- +# Configuration options related to source browsing +#--------------------------------------------------------------------------- + +# If the SOURCE_BROWSER tag is set to YES then a list of source files will be +# generated. Documented entities will be cross-referenced with these sources. +# +# Note: To get rid of all source code in the generated output, make sure that +# also VERBATIM_HEADERS is set to NO. +# The default value is: NO. + +SOURCE_BROWSER = NO + +# Setting the INLINE_SOURCES tag to YES will include the body of functions, +# classes and enums directly into the documentation. +# The default value is: NO. + +INLINE_SOURCES = NO + +# Setting the STRIP_CODE_COMMENTS tag to YES will instruct doxygen to hide any +# special comment blocks from generated source code fragments. Normal C, C++ and +# Fortran comments will always remain visible. +# The default value is: YES. + +STRIP_CODE_COMMENTS = YES + +# If the REFERENCED_BY_RELATION tag is set to YES then for each documented +# entity all documented functions referencing it will be listed. +# The default value is: NO. + +REFERENCED_BY_RELATION = NO + +# If the REFERENCES_RELATION tag is set to YES then for each documented function +# all documented entities called/used by that function will be listed. +# The default value is: NO. + +REFERENCES_RELATION = NO + +# If the REFERENCES_LINK_SOURCE tag is set to YES and SOURCE_BROWSER tag is set +# to YES then the hyperlinks from functions in REFERENCES_RELATION and +# REFERENCED_BY_RELATION lists will link to the source code. Otherwise they will +# link to the documentation. +# The default value is: YES. + +REFERENCES_LINK_SOURCE = YES + +# If SOURCE_TOOLTIPS is enabled (the default) then hovering a hyperlink in the +# source code will show a tooltip with additional information such as prototype, +# brief description and links to the definition and documentation. Since this +# will make the HTML file larger and loading of large files a bit slower, you +# can opt to disable this feature. +# The default value is: YES. +# This tag requires that the tag SOURCE_BROWSER is set to YES. + +SOURCE_TOOLTIPS = YES + +# If the USE_HTAGS tag is set to YES then the references to source code will +# point to the HTML generated by the htags(1) tool instead of doxygen built-in +# source browser. The htags tool is part of GNU's global source tagging system +# (see https://www.gnu.org/software/global/global.html). You will need version +# 4.8.6 or higher. +# +# To use it do the following: +# - Install the latest version of global +# - Enable SOURCE_BROWSER and USE_HTAGS in the configuration file +# - Make sure the INPUT points to the root of the source tree +# - Run doxygen as normal +# +# Doxygen will invoke htags (and that will in turn invoke gtags), so these +# tools must be available from the command line (i.e. in the search path). +# +# The result: instead of the source browser generated by doxygen, the links to +# source code will now point to the output of htags. +# The default value is: NO. +# This tag requires that the tag SOURCE_BROWSER is set to YES. + +USE_HTAGS = NO + +# If the VERBATIM_HEADERS tag is set the YES then doxygen will generate a +# verbatim copy of the header file for each class for which an include is +# specified. Set to NO to disable this. +# See also: Section \class. +# The default value is: YES. + +VERBATIM_HEADERS = YES + +#--------------------------------------------------------------------------- +# Configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- + +# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index of all +# compounds will be generated. Enable this if the project contains a lot of +# classes, structs, unions or interfaces. +# The default value is: YES. + +ALPHABETICAL_INDEX = YES + +# The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in +# which the alphabetical index list will be split. +# Minimum value: 1, maximum value: 20, default value: 5. +# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. + +COLS_IN_ALPHA_INDEX = 5 + +# In case all classes in a project start with a common prefix, all classes will +# be put under the same header in the alphabetical index. The IGNORE_PREFIX tag +# can be used to specify a prefix (or a list of prefixes) that should be ignored +# while generating the index headers. +# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. + +IGNORE_PREFIX = + +#--------------------------------------------------------------------------- +# Configuration options related to the HTML output +#--------------------------------------------------------------------------- + +# If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output +# The default value is: YES. + +GENERATE_HTML = YES + +# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. +# The default directory is: html. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_OUTPUT = html + +# The HTML_FILE_EXTENSION tag can be used to specify the file extension for each +# generated HTML page (for example: .htm, .php, .asp). +# The default value is: .html. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_FILE_EXTENSION = .html + +# The HTML_HEADER tag can be used to specify a user-defined HTML header file for +# each generated HTML page. If the tag is left blank doxygen will generate a +# standard header. +# +# To get valid HTML the header file that includes any scripts and style sheets +# that doxygen needs, which is dependent on the configuration options used (e.g. +# the setting GENERATE_TREEVIEW). It is highly recommended to start with a +# default header using +# doxygen -w html new_header.html new_footer.html new_stylesheet.css +# YourConfigFile +# and then modify the file new_header.html. See also section "Doxygen usage" +# for information on how to generate the default header that doxygen normally +# uses. +# Note: The header is subject to change so you typically have to regenerate the +# default header when upgrading to a newer version of doxygen. For a description +# of the possible markers and block names see the documentation. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_HEADER = + +# The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each +# generated HTML page. If the tag is left blank doxygen will generate a standard +# footer. See HTML_HEADER for more information on how to generate a default +# footer and what special commands can be used inside the footer. See also +# section "Doxygen usage" for information on how to generate the default footer +# that doxygen normally uses. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_FOOTER = + +# The HTML_STYLESHEET tag can be used to specify a user-defined cascading style +# sheet that is used by each HTML page. It can be used to fine-tune the look of +# the HTML output. If left blank doxygen will generate a default style sheet. +# See also section "Doxygen usage" for information on how to generate the style +# sheet that doxygen normally uses. +# Note: It is recommended to use HTML_EXTRA_STYLESHEET instead of this tag, as +# it is more robust and this tag (HTML_STYLESHEET) will in the future become +# obsolete. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_STYLESHEET = + +# The HTML_EXTRA_STYLESHEET tag can be used to specify additional user-defined +# cascading style sheets that are included after the standard style sheets +# created by doxygen. Using this option one can overrule certain style aspects. +# This is preferred over using HTML_STYLESHEET since it does not replace the +# standard style sheet and is therefore more robust against future updates. +# Doxygen will copy the style sheet files to the output directory. +# Note: The order of the extra style sheet files is of importance (e.g. the last +# style sheet in the list overrules the setting of the previous ones in the +# list). For an example see the documentation. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_EXTRA_STYLESHEET = + +# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or +# other source files which should be copied to the HTML output directory. Note +# that these files will be copied to the base HTML output directory. Use the +# $relpath^ marker in the HTML_HEADER and/or HTML_FOOTER files to load these +# files. In the HTML_STYLESHEET file, use the file name only. Also note that the +# files will be copied as-is; there are no commands or markers available. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_EXTRA_FILES = + +# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen +# will adjust the colors in the style sheet and background images according to +# this color. Hue is specified as an angle on a colorwheel, see +# https://en.wikipedia.org/wiki/Hue for more information. For instance the value +# 0 represents red, 60 is yellow, 120 is green, 180 is cyan, 240 is blue, 300 +# purple, and 360 is red again. +# Minimum value: 0, maximum value: 359, default value: 220. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE_HUE = 220 + +# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors +# in the HTML output. For a value of 0 the output will use grayscales only. A +# value of 255 will produce the most vivid colors. +# Minimum value: 0, maximum value: 255, default value: 100. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE_SAT = 100 + +# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to the +# luminance component of the colors in the HTML output. Values below 100 +# gradually make the output lighter, whereas values above 100 make the output +# darker. The value divided by 100 is the actual gamma applied, so 80 represents +# a gamma of 0.8, The value 220 represents a gamma of 2.2, and 100 does not +# change the gamma. +# Minimum value: 40, maximum value: 240, default value: 80. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE_GAMMA = 80 + +# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML +# page will contain the date and time when the page was generated. Setting this +# to YES can help to show when doxygen was last run and thus if the +# documentation is up to date. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_TIMESTAMP = YES + +# If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML +# documentation will contain a main index with vertical navigation menus that +# are dynamically created via JavaScript. If disabled, the navigation index will +# consists of multiple levels of tabs that are statically embedded in every HTML +# page. Disable this option to support browsers that do not have JavaScript, +# like the Qt help browser. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_DYNAMIC_MENUS = YES + +# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML +# documentation will contain sections that can be hidden and shown after the +# page has loaded. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_DYNAMIC_SECTIONS = NO + +# With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries +# shown in the various tree structured indices initially; the user can expand +# and collapse entries dynamically later on. Doxygen will expand the tree to +# such a level that at most the specified number of entries are visible (unless +# a fully collapsed tree already exceeds this amount). So setting the number of +# entries 1 will produce a full collapsed tree by default. 0 is a special value +# representing an infinite number of entries and will result in a full expanded +# tree by default. +# Minimum value: 0, maximum value: 9999, default value: 100. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_INDEX_NUM_ENTRIES = 100 + +# If the GENERATE_DOCSET tag is set to YES, additional index files will be +# generated that can be used as input for Apple's Xcode 3 integrated development +# environment (see: https://developer.apple.com/xcode/), introduced with OSX +# 10.5 (Leopard). To create a documentation set, doxygen will generate a +# Makefile in the HTML output directory. Running make will produce the docset in +# that directory and running make install will install the docset in +# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find it at +# startup. See https://developer.apple.com/library/archive/featuredarticles/Doxy +# genXcode/_index.html for more information. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_DOCSET = NO + +# This tag determines the name of the docset feed. A documentation feed provides +# an umbrella under which multiple documentation sets from a single provider +# (such as a company or product suite) can be grouped. +# The default value is: Doxygen generated docs. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_FEEDNAME = "Doxygen generated docs" + +# This tag specifies a string that should uniquely identify the documentation +# set bundle. This should be a reverse domain-name style string, e.g. +# com.mycompany.MyDocSet. Doxygen will append .docset to the name. +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_BUNDLE_ID = org.doxygen.Project + +# The DOCSET_PUBLISHER_ID tag specifies a string that should uniquely identify +# the documentation publisher. This should be a reverse domain-name style +# string, e.g. com.mycompany.MyDocSet.documentation. +# The default value is: org.doxygen.Publisher. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_PUBLISHER_ID = org.doxygen.Publisher + +# The DOCSET_PUBLISHER_NAME tag identifies the documentation publisher. +# The default value is: Publisher. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_PUBLISHER_NAME = Publisher + +# If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three +# additional HTML index files: index.hhp, index.hhc, and index.hhk. The +# index.hhp is a project file that can be read by Microsoft's HTML Help Workshop +# (see: https://www.microsoft.com/en-us/download/details.aspx?id=21138) on +# Windows. +# +# The HTML Help Workshop contains a compiler that can convert all HTML output +# generated by doxygen into a single compiled HTML file (.chm). Compiled HTML +# files are now used as the Windows 98 help format, and will replace the old +# Windows help format (.hlp) on all Windows platforms in the future. Compressed +# HTML files also contain an index, a table of contents, and you can search for +# words in the documentation. The HTML workshop also contains a viewer for +# compressed HTML files. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_HTMLHELP = NO + +# The CHM_FILE tag can be used to specify the file name of the resulting .chm +# file. You can add a path in front of the file if the result should not be +# written to the html output directory. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +CHM_FILE = + +# The HHC_LOCATION tag can be used to specify the location (absolute path +# including file name) of the HTML help compiler (hhc.exe). If non-empty, +# doxygen will try to run the HTML help compiler on the generated index.hhp. +# The file has to be specified with full path. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +HHC_LOCATION = + +# The GENERATE_CHI flag controls if a separate .chi index file is generated +# (YES) or that it should be included in the master .chm file (NO). +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +GENERATE_CHI = NO + +# The CHM_INDEX_ENCODING is used to encode HtmlHelp index (hhk), content (hhc) +# and project file content. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +CHM_INDEX_ENCODING = + +# The BINARY_TOC flag controls whether a binary table of contents is generated +# (YES) or a normal table of contents (NO) in the .chm file. Furthermore it +# enables the Previous and Next buttons. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +BINARY_TOC = NO + +# The TOC_EXPAND flag can be set to YES to add extra items for group members to +# the table of contents of the HTML help documentation and to the tree view. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. + +TOC_EXPAND = NO + +# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and +# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated that +# can be used as input for Qt's qhelpgenerator to generate a Qt Compressed Help +# (.qch) of the generated HTML documentation. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_QHP = NO + +# If the QHG_LOCATION tag is specified, the QCH_FILE tag can be used to specify +# the file name of the resulting .qch file. The path specified is relative to +# the HTML output folder. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QCH_FILE = + +# The QHP_NAMESPACE tag specifies the namespace to use when generating Qt Help +# Project output. For more information please see Qt Help Project / Namespace +# (see: https://doc.qt.io/archives/qt-4.8/qthelpproject.html#namespace). +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_NAMESPACE = org.doxygen.Project + +# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating Qt +# Help Project output. For more information please see Qt Help Project / Virtual +# Folders (see: https://doc.qt.io/archives/qt-4.8/qthelpproject.html#virtual- +# folders). +# The default value is: doc. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_VIRTUAL_FOLDER = doc + +# If the QHP_CUST_FILTER_NAME tag is set, it specifies the name of a custom +# filter to add. For more information please see Qt Help Project / Custom +# Filters (see: https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom- +# filters). +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_CUST_FILTER_NAME = + +# The QHP_CUST_FILTER_ATTRS tag specifies the list of the attributes of the +# custom filter to add. For more information please see Qt Help Project / Custom +# Filters (see: https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom- +# filters). +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_CUST_FILTER_ATTRS = + +# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this +# project's filter section matches. Qt Help Project / Filter Attributes (see: +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#filter-attributes). +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHP_SECT_FILTER_ATTRS = + +# The QHG_LOCATION tag can be used to specify the location of Qt's +# qhelpgenerator. If non-empty doxygen will try to run qhelpgenerator on the +# generated .qhp file. +# This tag requires that the tag GENERATE_QHP is set to YES. + +QHG_LOCATION = + +# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files will be +# generated, together with the HTML files, they form an Eclipse help plugin. To +# install this plugin and make it available under the help contents menu in +# Eclipse, the contents of the directory containing the HTML and XML files needs +# to be copied into the plugins directory of eclipse. The name of the directory +# within the plugins directory should be the same as the ECLIPSE_DOC_ID value. +# After copying Eclipse needs to be restarted before the help appears. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_ECLIPSEHELP = NO + +# A unique identifier for the Eclipse help plugin. When installing the plugin +# the directory name containing the HTML and XML files should also have this +# name. Each documentation set should have its own identifier. +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_ECLIPSEHELP is set to YES. + +ECLIPSE_DOC_ID = org.doxygen.Project + +# If you want full control over the layout of the generated HTML pages it might +# be necessary to disable the index and replace it with your own. The +# DISABLE_INDEX tag can be used to turn on/off the condensed index (tabs) at top +# of each HTML page. A value of NO enables the index and the value YES disables +# it. Since the tabs in the index contain the same information as the navigation +# tree, you can set this option to YES if you also set GENERATE_TREEVIEW to YES. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +DISABLE_INDEX = NO + +# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index +# structure should be generated to display hierarchical information. If the tag +# value is set to YES, a side panel will be generated containing a tree-like +# index structure (just like the one that is generated for HTML Help). For this +# to work a browser that supports JavaScript, DHTML, CSS and frames is required +# (i.e. any modern browser). Windows users are probably better off using the +# HTML help feature. Via custom style sheets (see HTML_EXTRA_STYLESHEET) one can +# further fine-tune the look of the index. As an example, the default style +# sheet generated by doxygen has an example that shows how to put an image at +# the root of the tree instead of the PROJECT_NAME. Since the tree basically has +# the same information as the tab index, you could consider setting +# DISABLE_INDEX to YES when enabling this option. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +GENERATE_TREEVIEW = YES + +# The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that +# doxygen will group on one line in the generated HTML documentation. +# +# Note that a value of 0 will completely suppress the enum values from appearing +# in the overview section. +# Minimum value: 0, maximum value: 20, default value: 4. +# This tag requires that the tag GENERATE_HTML is set to YES. + +ENUM_VALUES_PER_LINE = 1 + +# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be used +# to set the initial width (in pixels) of the frame in which the tree is shown. +# Minimum value: 0, maximum value: 1500, default value: 250. +# This tag requires that the tag GENERATE_HTML is set to YES. + +TREEVIEW_WIDTH = 250 + +# If the EXT_LINKS_IN_WINDOW option is set to YES, doxygen will open links to +# external symbols imported via tag files in a separate window. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +EXT_LINKS_IN_WINDOW = NO + +# If the HTML_FORMULA_FORMAT option is set to svg, doxygen will use the pdf2svg +# tool (see https://github.com/dawbarton/pdf2svg) or inkscape (see +# https://inkscape.org) to generate formulas as SVG images instead of PNGs for +# the HTML output. These images will generally look nicer at scaled resolutions. +# Possible values are: png The default and svg Looks nicer but requires the +# pdf2svg tool. +# The default value is: png. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_FORMULA_FORMAT = png + +# Use this tag to change the font size of LaTeX formulas included as images in +# the HTML documentation. When you change the font size after a successful +# doxygen run you need to manually remove any form_*.png images from the HTML +# output directory to force them to be regenerated. +# Minimum value: 8, maximum value: 50, default value: 10. +# This tag requires that the tag GENERATE_HTML is set to YES. + +FORMULA_FONTSIZE = 10 + +# Use the FORMULA_TRANSPARENT tag to determine whether or not the images +# generated for formulas are transparent PNGs. Transparent PNGs are not +# supported properly for IE 6.0, but are supported on all modern browsers. +# +# Note that when changing this option you need to delete any form_*.png files in +# the HTML output directory before the changes have effect. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +FORMULA_TRANSPARENT = YES + +# The FORMULA_MACROFILE can contain LaTeX \newcommand and \renewcommand commands +# to create new LaTeX commands to be used in formulas as building blocks. See +# the section "Including formulas" for details. + +FORMULA_MACROFILE = + +# Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see +# https://www.mathjax.org) which uses client side JavaScript for the rendering +# instead of using pre-rendered bitmaps. Use this if you do not have LaTeX +# installed or if you want to formulas look prettier in the HTML output. When +# enabled you may also need to install MathJax separately and configure the path +# to it using the MATHJAX_RELPATH option. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +USE_MATHJAX = NO + +# When MathJax is enabled you can set the default output format to be used for +# the MathJax output. See the MathJax site (see: +# http://docs.mathjax.org/en/latest/output.html) for more details. +# Possible values are: HTML-CSS (which is slower, but has the best +# compatibility), NativeMML (i.e. MathML) and SVG. +# The default value is: HTML-CSS. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_FORMAT = HTML-CSS + +# When MathJax is enabled you need to specify the location relative to the HTML +# output directory using the MATHJAX_RELPATH option. The destination directory +# should contain the MathJax.js script. For instance, if the mathjax directory +# is located at the same level as the HTML output directory, then +# MATHJAX_RELPATH should be ../mathjax. The default value points to the MathJax +# Content Delivery Network so you can quickly see the result without installing +# MathJax. However, it is strongly recommended to install a local copy of +# MathJax from https://www.mathjax.org before deployment. +# The default value is: https://cdn.jsdelivr.net/npm/mathjax@2. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest + +# The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax +# extension names that should be enabled during MathJax rendering. For example +# MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_EXTENSIONS = + +# The MATHJAX_CODEFILE tag can be used to specify a file with javascript pieces +# of code that will be used on startup of the MathJax code. See the MathJax site +# (see: http://docs.mathjax.org/en/latest/output.html) for more details. For an +# example see the documentation. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_CODEFILE = + +# When the SEARCHENGINE tag is enabled doxygen will generate a search box for +# the HTML output. The underlying search engine uses javascript and DHTML and +# should work on any modern browser. Note that when using HTML help +# (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets (GENERATE_DOCSET) +# there is already a search function so this one should typically be disabled. +# For large projects the javascript based search engine can be slow, then +# enabling SERVER_BASED_SEARCH may provide a better solution. It is possible to +# search using the keyboard; to jump to the search box use + S +# (what the is depends on the OS and browser, but it is typically +# , /