Matter Open IoT SDK Example Application#

These examples are built using Open IoT SDK and runs inside an emulated target through the Arm FVP model for the Corstone-300 MPS3.

You can use these example as a reference for creating your own applications.

Environment setup#

Before building the examples, check out the Matter repository and sync submodules using the following command:

$ git submodule update --init

The VSCode devcontainer has all dependencies pre-installed. Using the VSCode devcontainer is the recommended way to interact with Open IoT SDK port of the Matter Project. Please read this README.md for more information.

Networking setup#

Running ARM Fast Model with TAP/TUN device networking mode requires setup proper network interfaces. Special scripts were designed to make setup easy. In scripts/setup/openiotsdk directory you can find:

  • network_setup.sh - script to create the specific network namespace and Virtual Ethernet interface to connect with host network. Both host and namespace sides have linked IP addresses. Inside the network namespace the TAP device interface is created and bridged with Virtual Ethernet peer. There is also option to enable Internet connection in namespace by forwarding traffic to host default interface.

    To enable Open IoT SDK networking environment:

    ${MATTER_ROOT}/scripts/setup/openiotsdk/network_setup.sh up

    To disable Open IoT SDK networking environment:

    ${MATTER_ROOT}/scripts/setup/openiotsdk/network_setup.sh down

    Use --help to get more information about the script options.

  • connect_if.sh - script that connects specified network interfaces with the default route interface. It creates a bridge and links all interfaces to it. The bridge becomes the default interface.

    Example:

    ${MATTER_ROOT}/scripts/setup/openiotsdk/connect_if.sh ARMhveth

    Use --help to get more information about the script options.

Open IoT SDK network setup scripts contain commands that require root permissions. Use sudo to run the scripts in user account with root privileges.

After setting up the Open IoT SDK network environment the user will be able to run Matter examples on FVP in an isolated network namespace in TAP device mode.

To execute a command in a specific network namespace use the helper script scripts/run_in_ns.sh.

Example:

${MATTER_ROOT}/scripts/run_in_ns.sh ARMns <command to run>

Use --help to get more information about the script options.

NOTE

For Docker environment users it’s recommended to use the default bridge network for a running container. This guarantees full isolation of the Open IoT SDK network from host settings.

Debugging setup#

Debugging Matter application running on FVP model requires GDB Remote Connection Plugin for Fast Model. More details GDBRemoteConnection.

The Third-Party IP add-on package can be downloaded from ARM developer website Fast models. Currently required version is 11.16.

To install Fast Model Third-Party IP package:

  • unpack the installation package in a temporary location

  • execute the command ./setup.bin (Linux) or Setup.exe (Windows), and follow the installation instructions.

After installation the GDB Remote Connection Plugin should be visible in FastModelsPortfolio_11.16/plugins directory.

Then add the GDB plugin to your development environment:

  • host environment - add GDB plugin path to environment variable as FAST_MODEL_PLUGINS_PATH.

    Example

    export FAST_MODEL_PLUGINS_PATH=/opt/FastModelsPortfolio_11.16/plugins/Linux64_GCC-9.3

  • Docker container environment - mount the Fast Model Third-Party IP directory into the /opt/FastModelsPortfolio_11.16 directory in container.

    The Vscode devcontainer users should add a volume bound to this directory Add local file mount.

    You can edit the .devcontainer/devcontainer.json file, for example:

    ...
"mounts": [
    ...
    "source=/opt/FastModelsPortfolio_11.16,target=/opt/FastModelsPortfolio_11.16,type=bind,consistency=cached"
    ...
],
...

    In this case, the FAST MODEL PLUGINS PATH environment variable is already created.

    If you launch the Docker container directly from CLI, use the above arguments with docker run command. Remember add GDB plugin path to environment variable as FAST_MODEL_PLUGINS_PATH inside container.

Building#

You build using a vscode task or call the script directly from the command line.

Building using vscode task#

Command Palette (F1) => Run Task... => Build Open IoT SDK example => (debug on/off) => <example name>

This will call the scripts with the selected parameters.

Building using CLI#

You can call the script directly yourself.

${MATTER_ROOT}/scripts/examples/openiotsdk_example.sh <example name>

Use --help to get more information about the script options.

Running#

The application runs in the background and opens a telnet session. The script will open telnet for you and connect to the port used by the FVP. When the telnet process is terminated it will also terminate the FVP instance.

You can run the application script from a vscode task or call the script directly.

Running using vscode task#

Command Palette (F1) => Run Task... => Run Open IoT SDK example => (network namespace) => (network interface) => <example name>

This will call the scripts with the selected example name.

Running using CLI#

You can call the script directly yourself.

${MATTER_ROOT}/scripts/examples/openiotsdk_example.sh -C run <example name>

Run example in specific network namespace with TAP device mode:

${MATTER_ROOT}/scripts/run_in_ns.sh ARMns ${MATTER_ROOT}/scripts/examples/openiotsdk_example.sh -C run -n ARMtap <example name>

Commissioning#

Once booted the application can be commissioned, please refer to docs/guides/openiotsdk_commissioning.md for further instructions.

Testing#

Run the Pytest integration test for specific application.

The test result can be found in src/test_driver/openiotsdk/integration-tests/<example name>/test_report.json file.

You run testing using a vscode task or call the script directly from the command line.

Testing using vscode task#

Command Palette (F1) => Run Task... => Test Open IoT SDK example => (network namespace) => (network interface) => <example name>

This will call the scripts with the selected example name.

Testing using CLI#

You can call the script directly yourself.

${MATTER_ROOT}/scripts/examples/openiotsdk_example.sh -C test <example name>

Test example in specific network namespace with TAP device mode:

${MATTER_ROOT}/scripts/run_in_ns.sh ARMns ${MATTER_ROOT}/scripts/examples/openiotsdk_example.sh -C test -n ARMtap <example name>

Debugging#

Debugging can be started using a VS code launch task:

Run and Debug (Ctrl+Shift+D) => Debug Open IoT SDK example application => Start
Debugging (F5) => <example name> => (GDB target address) => (network namespace) => (network interface) => <example name>

For debugging remote targets (i.e. run in other network namespaces) you need to pass hostname/IP address of external GDB target that you want to connect to (GDB target address). In case of using the Open IoT SDK network environment the GDB server runs inside a namespace and has the same IP address as bridge interface.

${MATTER_ROOT}/scripts/run_in_ns.sh <namespace_name> ifconfig <bridge_name>

NOTE

As you can see above, you will need to select the name of the example twice. This is because the debug task needs to launch the run task and currently VS code has no way of passing parameters between tasks.