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.
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.
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 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:
./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.
To add TF-M support to Matter example you need to set TFM_SUPPORT variable inside main application CMakeLists.txt file.
set(TFM_SUPPORT YES)
This causes the Matter example to be built as non-secure application in Non-secure Processing Environment (NSPE). The bootloader and the secure part are also built from TF-M sources. All components are merged into a single executable file at the end of the building process.
You can also provide the own version of Matter example by setting TFM_NS_APP_VERSION variable.
set(TFM_NS_APP_VERSION "0.0.1")
There is an option to add TF-M Protected Storage Service support for key-value storage component in Matter examples. You need to set CONFIG_CHIP_OPEN_IOT_SDK_USE_PSA_PS variable inside main application CMakeLists.txt fi
set(CONFIG_CHIP_OPEN_IOT_SDK_USE_PSA_PS YES)
This option causes key-value objects will be stored in a secure part of flash memory and the Protected Storage Service takes care of their encryption and authentication.
NOTE
The TF-M Protected Storage option requires enabling TF-M support.
You build using a vscode task or call the script directly from the command line.
Command Palette (F1) => Run Task... => Build Open IoT SDK example => (debug on/off) => <example name>
This will call the scripts with the selected parameters.
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.
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.
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.
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>
Once booted the application can be commissioned, please refer to docs/guides/openiotsdk_commissioning.md for further instructions.
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.
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.
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 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.