From 1616004ec9d582d1dfd70d47f52e085cc9e2b1ff Mon Sep 17 00:00:00 2001 From: Artur Tynecki <77382963+ATmobica@users.noreply.github.com> Date: Mon, 22 May 2023 17:30:49 +0200 Subject: [PATCH] [OIS] Set of maintenance improvements and documentation (#26688) * [OIS] Unit-tests improvements Cleanup unit-tests project configuration - use default values. Set maximum fabrics to 5 for OIS platform. Cleanup main file. Signed-off-by: ATmobica * [OIS] Build improvement Set Release Cmake build type for non-debug build. Signed-off-by: ATmobica * [OIS] Extend KeyValueStore Manager with Shutdown function Add a Shutdown() function that deinitializes the KV store. Add Shutdown implementation to OIS KV stores. Signed-off-by: ATmobica * [OIS] Add select KVS storage type option to build script Add build script argument to select KVS storage type ps or tdb. Signed-off-by: ATmobica * [OIS] Change TF-M AN552 layout Increase TF-M non-secure partition size to 2.25 MB - adjust to the current size of the binary of examples. Reorder the TF-M memory areas in QSPI. Put the OTP / NV counters between protected storage and ITS. This will be useful for dumping memory to guarantee persistence. Signed-off-by: ATmobica * [OIS] Add KVS storage file support Add an option to pass the path to the KVS storage file which will be used to ensure persistence. Use --data and --dump FVP options to load/dump KVS storage memory to the specific file. Add description to the OIS documentation. Signed-off-by: ATmobica * [OIS] Debugging setup improvements Use the Linux Fast Models FVP package for Matter environment and install it inside the Docker container. Create helper script to setup FVP Fast Model extension with GDB plugin. Debugging setup documentation update. Signed-off-by: ATmobica * [OIS] Unit tests docs and maintenance improvements Create unit test description - setup, build, run, test and debug the unit test project. Explaining the unit testing approach. Add common list of currently supported Matter's component tests. Use it in CMake build, helper script, VSCode tasks and documentation. Update unit tests README file. Signed-off-by: ATmobica * [OIS] Update the examples docs and maintenance improvements Add setup Open IoT SDK network VScode task. Add networking setup details and default settings. Update the OIS example documentation and extend it with description of adding a new example. Update examples README files. Create the list of supported Matter examples and use it in helper script and VSCode tasks. Add specific examples of how to build/run/debug and any additional notes to be aware of. Update the OIS commissioning description - use the chip-tool as controller. Co-authored-by: ATmobica Signed-off-by: Anna Bridge * [Docs] Link OIS documentation to guides page Extend platform guides list with OIS documentation items Signed-off-by: ATmobica --------- Signed-off-by: ATmobica Signed-off-by: Anna Bridge Co-authored-by: Anna Bridge --- .github/.wordlist.txt | 1 + .vscode/launch.json | 60 +- .vscode/tasks.json | 72 +- config/openiotsdk/cmake/sdk.cmake | 6 +- docs/examples/index.md | 9 - docs/examples/openiotsdk_examples.md | 303 ------- docs/guides/README.md | 4 + docs/guides/openiotsdk_commissioning.md | 77 +- docs/guides/openiotsdk_examples.md | 766 ++++++++++++++++++ docs/guides/openiotsdk_platform_overview.md | 31 +- docs/guides/openiotsdk_unit_tests.md | 249 ++++++ examples/lock-app/openiotsdk/CMakeLists.txt | 1 - examples/lock-app/openiotsdk/README.md | 26 +- .../openiotsdk/supported_examples.txt | 2 + .../targets/an552/partition/flash_layout.h | 50 +- examples/shell/openiotsdk/README.md | 15 +- scripts/examples/openiotsdk_example.sh | 62 +- scripts/setup/openiotsdk/debugging_setup.sh | 31 + src/platform/openiotsdk/CHIPPlatformConfig.h | 4 +- .../openiotsdk/KVBlockDeviceStore.cpp | 14 + src/platform/openiotsdk/KVBlockDeviceStore.h | 1 + src/platform/openiotsdk/KVPsaPsStore.cpp | 9 + src/platform/openiotsdk/KVPsaPsStore.h | 1 + .../openiotsdk/KeyValueStoreManagerImpl.cpp | 5 + .../openiotsdk/KeyValueStoreManagerImpl.h | 1 + .../openiotsdk/SystemPlatformConfig.h | 1 + .../openiotsdk/unit-tests/CMakeLists.txt | 3 +- .../openiotsdk/unit-tests/README.md | 85 +- .../main/include/CHIPProjectConfig.h | 11 +- .../openiotsdk/unit-tests/main/main_ns.cpp | 26 +- .../{testnames.txt => test_components.txt} | 0 31 files changed, 1354 insertions(+), 572 deletions(-) delete mode 100644 docs/examples/openiotsdk_examples.md create mode 100644 docs/guides/openiotsdk_examples.md create mode 100644 docs/guides/openiotsdk_unit_tests.md create mode 100644 examples/platform/openiotsdk/supported_examples.txt create mode 100755 scripts/setup/openiotsdk/debugging_setup.sh rename src/test_driver/openiotsdk/unit-tests/{testnames.txt => test_components.txt} (100%) diff --git a/.github/.wordlist.txt b/.github/.wordlist.txt index 251fa2fee90749..25c4b7b67c9c2a 100644 --- a/.github/.wordlist.txt +++ b/.github/.wordlist.txt @@ -719,6 +719,7 @@ Jupyter jupyterlab KA kAdminister +kbd kBusy kCase Kconfig diff --git a/.vscode/launch.json b/.vscode/launch.json index 83ce3d5fe494bd..ed80ae59c95e23 100644 --- a/.vscode/launch.json +++ b/.vscode/launch.json @@ -430,8 +430,8 @@ "name": "Debug Open IoT SDK example application", "type": "cortex-debug", "request": "launch", - "cwd": "${workspaceRoot}/examples/${input:openiotsdkApp}/openiotsdk", - "executable": "./build/chip-openiotsdk-${input:openiotsdkApp}-example.elf", + "cwd": "${workspaceRoot}/examples/${input:openiotsdkExample}/openiotsdk", + "executable": "./build/chip-openiotsdk-${input:openiotsdkExample}-example.elf", "armToolchainPath": "${env:PW_ENVIRONMENT_ROOT}/cipd/packages/arm/bin/", "servertype": "external", "gdbTarget": "${input:openiotsdkRemoteHost}:31627", //GDBserver port on FVP @@ -439,7 +439,7 @@ "-enable-pretty-printing", "add-symbol-file ./build/bl2.elf 0x10000000", "add-symbol-file ./build/tfm_s.elf 0x38000400", - "add-symbol-file ./build/chip-openiotsdk-${input:openiotsdkApp}-example_ns.elf 0x28060400", + "add-symbol-file ./build/chip-openiotsdk-${input:openiotsdkExample}-example_ns.elf 0x28060400", "break main_ns.cpp:main" ], "runToEntryPoint": "main", @@ -451,7 +451,7 @@ "type": "cortex-debug", "request": "launch", "cwd": "${workspaceRoot}/src/test_driver/openiotsdk/unit-tests", - "executable": "./build/${input:openiotsdkUnittest}.elf", + "executable": "./build/${input:openiotsdkUnitTest}.elf", "armToolchainPath": "${env:PW_ENVIRONMENT_ROOT}/cipd/packages/arm/bin/", "servertype": "external", "gdbTarget": ":31627", //GDBserver port on FVP @@ -459,7 +459,7 @@ "-enable-pretty-printing", "add-symbol-file ./build/bl2.elf 0x10000000", "add-symbol-file ./build/tfm_s.elf 0x38000400", - "add-symbol-file ./build/${input:openiotsdkUnittest}_ns.elf 0x28060400", + "add-symbol-file ./build/${input:openiotsdkUnitTest}_ns.elf 0x28060400", "break main_ns.cpp:main" ], "runToEntryPoint": "main", @@ -522,11 +522,13 @@ "default": "CY8CPROTO_062_4343W" }, { - "type": "pickString", - "id": "openiotsdkApp", - "description": "What Open IoT SDK example do you want to use?", - "options": ["shell", "lock-app"], - "default": "shell" + "type": "command", + "id": "openiotsdkExample", + "command": "shellCommand.execute", + "args": { + "command": "cat examples/platform/openiotsdk/supported_examples.txt", + "description": "What Open IoT SDK example application do you want to use?" + } }, { "type": "promptString", @@ -535,37 +537,13 @@ "default": "" }, { - "type": "pickString", - "id": "openiotsdkUnittest", - "description": "What Open IoT SDK unit test do you want to use?", - "options": [ - "accesstest", - "AppTests", - "ASN1Tests", - "BDXTests", - "ChipCryptoTests", - "ControllerTests", - "CoreTests", - "CredentialsTest", - "DataModelTests", - "InetLayerTests", - "MdnsTests", - "MessagingLayerTests", - "MinimalMdnsCoreTests", - "MinimalMdnsRecordsTests", - "MinimalMdnsRespondersTests", - "PlatformTests", - "RawTransportTests", - "RetransmitTests", - "SecureChannelTests", - "SetupPayloadTests", - "SupportTests", - "SystemLayerTests", - "TestShell", - "TransportLayerTests", - "UserDirectedCommissioningTests" - ], - "default": "accesstest" + "type": "command", + "id": "openiotsdkUnitTest", + "command": "shellCommand.execute", + "args": { + "command": "cat src/test_driver/openiotsdk/unit-tests/test_components.txt", + "description": "What Open IoT SDK unit test application do you want to use?" + } } ] } diff --git a/.vscode/tasks.json b/.vscode/tasks.json index 7d02179af08b53..2fb34adb0e8423 100644 --- a/.vscode/tasks.json +++ b/.vscode/tasks.json @@ -243,6 +243,19 @@ "clear": true } }, + { + "label": "Setup Open IoT SDK network", + "type": "shell", + "command": "sudo scripts/setup/openiotsdk/network_setup.sh -n${input:openiotsdkNetworkSetupName} ${input:openiotsdkNetworkSetupCmd}", + "problemMatcher": { + "pattern": { + "regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error):\\s+(.*)$", + "file": 1, + "line": 2, + "message": 5 + } + } + }, { "label": "Build Open IoT SDK example", "type": "shell", @@ -453,6 +466,19 @@ "options": ["simple", "boot", "upgrade"], "default": "simple" }, + { + "type": "pickString", + "id": "openiotsdkNetworkSetupCmd", + "description": "Which command do you wish to use?", + "options": ["up", "down", "restart"], + "default": "up" + }, + { + "type": "promptString", + "id": "openiotsdkNetworkSetupName", + "description": "Type the network namespace name that you want to use.", + "default": "ARM" + }, { "type": "pickString", "id": "openiotsdkDebugMode", @@ -468,44 +494,22 @@ "default": "false" }, { - "type": "pickString", + "type": "command", "id": "openiotsdkExample", - "description": "What Open IoT SDK example application do you want to use?", - "options": ["shell", "lock-app"], - "default": "shell" + "command": "shellCommand.execute", + "args": { + "command": "cat examples/platform/openiotsdk/supported_examples.txt", + "description": "What Open IoT SDK example application do you want to use?" + } }, { - "type": "pickString", + "type": "command", "id": "openiotsdkUnitTest", - "description": "What unit test do you want to use?", - "options": [ - "accesstest", - "AppTests", - "ASN1Tests", - "BDXTests", - "ChipCryptoTests", - "ControllerTests", - "CoreTests", - "CredentialsTest", - "DataModelTests", - "InetLayerTests", - "MdnsTests", - "MessagingLayerTests", - "MinimalMdnsCoreTests", - "MinimalMdnsRecordsTests", - "MinimalMdnsRespondersTests", - "PlatformTests", - "RawTransportTests", - "RetransmitTests", - "SecureChannelTests", - "SetupPayloadTests", - "SupportTests", - "SystemLayerTests", - "TestShell", - "TransportLayerTests", - "UserDirectedCommissioningTests" - ], - "default": "accesstest" + "command": "shellCommand.execute", + "args": { + "command": "cat src/test_driver/openiotsdk/unit-tests/test_components.txt", + "description": "What Open IoT SDK unit test application do you want to use?" + } }, { "type": "promptString", diff --git a/config/openiotsdk/cmake/sdk.cmake b/config/openiotsdk/cmake/sdk.cmake index 7fbc7efa9561bc..61cd704a030041 100644 --- a/config/openiotsdk/cmake/sdk.cmake +++ b/config/openiotsdk/cmake/sdk.cmake @@ -194,11 +194,11 @@ if(TARGET mcu-driver-hal) DOMAIN_NS=$,1,0> ) - # Fixing the optimization issue for mcu-driver-hal target in the no-debug build. - # The default -Og optimization causes performance issues for the application. + # Fixing the optimization issue for mcu-driver-hal target in the release build. + # The default -Os optimization causes performance issues for the application. # We need to replace it with -O2 which is suitable for performance. # This fix can be removed in the future when the issue will be fixed in SDK directly. - if (NOT "${CMAKE_BUILD_TYPE}" STREQUAL "Debug") + if ("${CMAKE_BUILD_TYPE}" STREQUAL "Release") target_compile_options(mcu-driver-hal INTERFACE $<$:-O2>) target_compile_options(mcu-driver-hal INTERFACE $<$:-O2>) endif() diff --git a/docs/examples/index.md b/docs/examples/index.md index 6890ff955ec866..46482fcbe8934e 100644 --- a/docs/examples/index.md +++ b/docs/examples/index.md @@ -134,15 +134,6 @@ log-source-app/**/README minimal-mdns/README ``` -## Open IoT SDK examples - -```{toctree} -:glob: -:maxdepth: 1 - -openiotsdk_examples -``` - ## OTA Provider example ```{toctree} diff --git a/docs/examples/openiotsdk_examples.md b/docs/examples/openiotsdk_examples.md deleted file mode 100644 index 91bb27ffa9f13c..00000000000000 --- a/docs/examples/openiotsdk_examples.md +++ /dev/null @@ -1,303 +0,0 @@ -# Matter Open IoT SDK Example Application - -These examples are built using -[Open IoT SDK](https://gitlab.arm.com/iot/open-iot-sdk) and runs inside an -emulated target through the -[Arm FVP model for the Corstone-300 MPS3](https://developer.arm.com/downloads/-/arm-ecosystem-fvps). - -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](../VSCODE_DEVELOPMENT.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 -``` - -Use `--help` to get more information about the script options. - -**NOTE** - -For Docker environment users it's recommended to use the -[default bridge network](https://docs.docker.com/network/bridge/#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](https://developer.arm.com/documentation/100964/1116/Plug-ins-for-Fast-Models/GDBRemoteConnection). - -The Third-Party IP add-on package can be downloaded from ARM developer website -[Fast models](https://developer.arm.com/downloads/-/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](https://code.visualstudio.com/remote/advancedcontainers/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. - -## Configuration - -### Trusted Firmware-M - -To add [TF-M](https://tf-m-user-guide.trustedfirmware.org) 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") -``` - -### Trusted Firmware-M Protected Storage - -There is an option to add -[TF-M Protected Storage Service](https://tf-m-user-guide.trustedfirmware.org/integration_guide/services/tfm_ps_integration_guide.html) -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](#trusted-firmware-m) support. - -## 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) => -``` - -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 -``` - -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) => -``` - -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 -``` - -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 -``` - -### Commissioning - -Once booted the application can be commissioned, please refer to -[docs/guides/openiotsdk_commissioning.md](../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//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) => -``` - -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 -``` - -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 -``` - -## 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) => => (GDB target address) => (network namespace) => (network interface) => -``` - -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](#networking-setup) the GDB server runs inside -a namespace and has the same IP address as bridge interface. - -``` -${MATTER_ROOT}/scripts/run_in_ns.sh ifconfig -``` - -**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. diff --git a/docs/guides/README.md b/docs/guides/README.md index 67bb8b66001830..451a2c6d2fdff7 100644 --- a/docs/guides/README.md +++ b/docs/guides/README.md @@ -22,6 +22,10 @@ - [Silicon Labs - Building](./silabs_efr32_building.md) - [Silicon Labs - Software Update](./silabs_efr32_software_update.md) - [TI - Platform Overview](./ti_platform_overview.md) +- [Open IoT SDK - Platform Overview](./openiotsdk_platform_overview.md) +- [Open IoT SDK - Examples](./openiotsdk_examples.md) +- [Open IoT SDK - Unit Tests](./openiotsdk_unit_tests.md) +- [Open IoT SDK - Commissioning](./openiotsdk_commissioning.md) ## Development Guides diff --git a/docs/guides/openiotsdk_commissioning.md b/docs/guides/openiotsdk_commissioning.md index 596184fd27a961..520cff033d611d 100644 --- a/docs/guides/openiotsdk_commissioning.md +++ b/docs/guides/openiotsdk_commissioning.md @@ -7,41 +7,82 @@ the device becomes available on the Matter network. Open IoT SDK Matter devices, due to the connectivity setup, start already connected to the IP network and do not require credentials provisioning. -## Building and installing the Python Device Controller +## Building Matter controller -To make provisioning possible and to control the Matter device with a Python -application, you can build and run the Python controller application. Please -read the guide -[Python Device Controller guide](python_chip_controller_building.md) for further -instructions. +The [Matter controller](../../src/controller/README.md) is a client application +that allows commission and control of the Matter node. + +The [POSIX CLI chip-tool](../../examples/chip-tool/README.md) is the recommended +Matter controller to use with Open IoT SDK devices. + +To build `chip-tool` execute command: + +``` +scripts/examples/gn_build_example.sh examples/chip-tool out/chip-tool +``` ## Device commissioning -Run chip-device-ctrl and use the interactive prompt to commission the device. +Open IoT SDK examples require to setup a specific +[network environment](./openiotsdk_examples.md#networking-setup): + +``` +export TEST_NETWORK_NAME=OIStest +sudo ${MATTER_ROOT}/scripts/setup/openiotsdk/network_setup.sh -n $TEST_NETWORK_NAME restart +``` + +Both the device application and the controller should be started in a separate +terminal sessions and inside the created network namespace. Use the +`{MATTER_ROOT}/scripts/examples/scripts/run_in_ns.sh` helper script to execute +the specific shell command inside the network namespace. + +Run the application in `device terminal` and use the network namespace: + +``` +${MATTER_ROOT}/scripts/examples/scripts/run_in_ns.sh ${TEST_NETWORK_NAME}ns +${MATTER_ROOT}/scripts/examples/openiotsdk_example.sh -C run -n ${TEST_NETWORK_NAME}tap + +``` After the device boots, it's in ready for commissioning mode and starts the mDNS -advertisement. This can be discovered by the controller using: +advertisement. + +To commission the node in `client terminal` run Matter controller in the same +network namespace with pairing command: + +``` +${MATTER_ROOT}/scripts/run_in_ns.sh ${TEST_NETWORK_NAME}ns ./out/chip-tool/chip-tool pairing onnetwork-long +``` + +The `node_id` is chosen by the user. `pin_code` and `discriminator` are node +parameters printed when running the application in the `device terminal`. + +Example: ``` -discover -all +${MATTER_ROOT}/scripts/run_in_ns.sh ${TEST_NETWORK_NAME}ns ./out/chip-tool/chip-tool pairing onnetwork-long 123 20202021 3840 ``` -This will list the devices and their addresses. To commission the device use: +The application output a trace when commissioning succeeds. This trace is +displayed in the `device terminal`: ``` -connect -ip
[] +[INF] [SVR] Commissioning completed successfully ``` -The setup pin code is printed in the log of the device. The `` can be -chosen by the user, if left blank it will be automatically picked. +## Sending ZCL cluster commands -## Sending ZCL commands +Before sending cluster commands [commission](#device-commissioning) the device. -If the commissioning process was successful, it is possible to send a ZCL -command to the device which initiates a certain action. +To perform cluster action, run the Matter controller in the `client terminal` +and use the same network namespace: -`zcl [arguments]` +``` +${MATTER_ROOT}/scripts/run_in_ns.sh ${TEST_NETWORK_NAME}ns ./out/chip-tool/chip-tool [param1 param2 ...] +``` Example: - chip-device-ctrl > zcl LevelControl MoveWithOnOff 12344321 1 0 moveMode=1 rate=2 +``` +${MATTER_ROOT}/scripts/run_in_ns.sh ${TEST_NETWORK_NAME}ns ./out/chip-tool/chip-tool basicinformation read vendor-id 123 0 +``` diff --git a/docs/guides/openiotsdk_examples.md b/docs/guides/openiotsdk_examples.md new file mode 100644 index 00000000000000..2de1915f3ecf43 --- /dev/null +++ b/docs/guides/openiotsdk_examples.md @@ -0,0 +1,766 @@ +# Matter Open IoT SDK Example Application + +These examples are built using +[Open IoT SDK](https://gitlab.arm.com/iot/open-iot-sdk) and runs inside an +emulated target through the +[Arm FVP model for the Corstone-300 MPS3](https://developer.arm.com/downloads/-/arm-ecosystem-fvps). + +The list of currently supported Matter examples: + +``` +shell +lock-app +``` + +You can use these examples as a reference for creating your own applications. + +## Environment setup + +The VSCode devcontainer has all the dependencies pre-installed. It is the +recommended way to build, run and develop with the Open IoT SDK port of the +Matter Project. Please read this +[VSCode development guide](../VSCODE_DEVELOPMENT.md) for more information. + +Before building the examples, check out the Matter repository and sync Open IoT +SDK submodules using the following command: + +``` +scripts/checkout_submodules.py --shallow --recursive --platform openiotsdk +``` + +Next, bootstrap the source tree to install Pigweed (CIPD and Python packages) +components inside your environment (only once). + +To bootstrap: + +**using CLI** + +``` +$ bash scripts/bootstrap.sh +``` + +**using VSCode tasks** + +- Open the Command Palette: F1 +- Select `Tasks: Run Task` +- Select `Bootstrap` + +### Networking setup + +Running ARM Fast Model with the TAP/TUN device networking mode requires the +setting up of proper network interfaces. Special scripts were designed to make +the setup easy. In the `scripts/setup/openiotsdk` directory you can find: + +- **network_setup.sh** - script to create the specific network namespace and + Virtual Ethernet interface to connect with the host network. Both host and + namespace sides have linked IP addresses. Inside the network namespace the + TAP device interface is created and bridged with a Virtual Ethernet peer. + There is also an option to enable an Internet connection in the namespace by + forwarding traffic to the host default interface. + + To enable the Open IoT SDK networking environment: + + ``` + ${MATTER_ROOT}/scripts/setup/openiotsdk/network_setup.sh up + ``` + + To disable the Open IoT SDK networking environment: + + ``` + ${MATTER_ROOT}/scripts/setup/openiotsdk/network_setup.sh down + ``` + + To restart the Open IoT SDK networking environment: + + ``` + ${MATTER_ROOT}/scripts/setup/openiotsdk/network_setup.sh restart + ``` + + The default scripts settings are: + + - `ARM` - network base name + - `current session user` - network namespace user + - `fe00::1` - host side IPv6 address + - `fe00::2` - namespace side IPv6 address + - `10.200.1.1` - host side IPv4 address + - `10.200.1.2` - namespace side IPv4 address + - no Internet connection support to network namespace + + Example of the `OIS` network environment settings: + + ``` + ARMns namespace configuration + ARMbr: flags=4163 mtu 1500 + inet 10.200.1.2 netmask 255.255.255.0 broadcast 0.0.0.0 + inet6 fe00::2 prefixlen 64 scopeid 0x0 + inet6 fe80::1809:17ff:fe6c:f566 prefixlen 64 scopeid 0x20 + ether 1a:09:17:6c:f5:66 txqueuelen 1000 (Ethernet) + RX packets 1 bytes 72 (72.0 B) + RX errors 0 dropped 0 overruns 0 frame 0 + TX packets 0 bytes 0 (0.0 B) + TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0 + + ARMnveth: flags=4163 mtu 1500 + ether 46:66:29:a6:91:4b txqueuelen 1000 (Ethernet) + RX packets 2 bytes 216 (216.0 B) + RX errors 0 dropped 0 overruns 0 frame 0 + TX packets 3 bytes 270 (270.0 B) + TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0 + + ARMtap: flags=4419 mtu 1500 + ether 1a:09:17:6c:f5:66 txqueuelen 1000 (Ethernet) + RX packets 0 bytes 0 (0.0 B) + RX errors 0 dropped 0 overruns 0 frame 0 + TX packets 0 bytes 0 (0.0 B) + TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0 + + lo: flags=73 mtu 65536 + inet 127.0.0.1 netmask 255.0.0.0 + inet6 ::1 prefixlen 128 scopeid 0x10 + loop txqueuelen 1000 (Local Loopback) + RX packets 0 bytes 0 (0.0 B) + RX errors 0 dropped 0 overruns 0 frame 0 + TX packets 0 bytes 0 (0.0 B) + TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0 + + Host configuration + ARMhveth: flags=4163 mtu 1500 + inet 10.200.1.1 netmask 255.255.255.0 broadcast 0.0.0.0 + inet6 fe80::147c:c9ff:fe4a:c6d2 prefixlen 64 scopeid 0x20 + inet6 fe00::1 prefixlen 64 scopeid 0x0 + ether 16:7c:c9:4a:c6:d2 txqueuelen 1000 (Ethernet) + RX packets 3 bytes 270 (270.0 B) + RX errors 0 dropped 0 overruns 0 frame 0 + TX packets 2 bytes 216 (216.0 B) + TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0 + ``` + + Use `--help` to get more information about the script options. + + Open IoT SDK network setup is also supported via `VScode tasks`: + + - Open the Command Palette: F1 + - Select `Tasks: Run Task` + - Select `Setup Open IoT SDK network` + - Enter the network namespace name + - Choose command + + The VSCode task invokes `network_setup.sh` with the selected parameters. + +- **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 a 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 +``` + +Use `--help` to get more information about the script options. + +> 💡 **Notes**: +> +> For Docker environment users it's recommended to use the +> [default bridge network](https://docs.docker.com/network/bridge/>#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 the Matter application running on `FVP` model requires GDB Remote +Connection Plugin for Fast Model. More details +[GDBRemoteConnection](https://developer.arm.com/documentation/100964/1116/Plug-ins-for-Fast-Models/GDBRemoteConnection). + +The `Fast Models FVP` add-on package can be downloaded from the ARM developer +website [Fast models](https://developer.arm.com/downloads/-/fast-models). After +login in to the `ARM developer` platform search for `Fast Models`, choose +`Fast Models (FM000A)` on the list of results, then choose the revision +`r11p16-16rel0` and download the +`Third Party Add-ons for Fast Models 11.16 (Linux)` package. Then unpack the +package in the selected location on the host machine. + +Now you should add the GDB Remote Connection Plugin to your development +environment: + +- Linux host environment: + + - install Fast Model Extension package by executing the command + `./setup.bin`, and follow the installation instructions. After + installation, the GDB Remote Connection Plugin should be visible in + `/FastModelsPortfolio_11.16/plugins/Linux64_GCC-9.3` + directory. + - add GDB plugin path to environment variable as + `FAST_MODEL_PLUGINS_PATH`. + + Example: + + ``` + export FAST_MODEL_PLUGINS_PATH=/FastModelsPortfolio_11.16/plugins/Linux64_GCC-9.3 + ``` + +- Docker container environment: + + - pass the Fast Model Extension package to Docker container development + environment by mounting it into the + `/opt/FastModels_ThirdParty_IP_11-16_b16_Linux64` directory in the + container. Add a volume bound to this directory + [Add local file mount](https://code.visualstudio.com/remote/advancedcontainers/add-local-file-mount). + + You can edit the `.devcontainer/devcontainer.json` file, for example: + + ``` + ... + "mounts": [ ... + "source=/opt/FastModels_ThirdParty_IP_11-16_b16_Linux64,target=/opt/FastModels_ThirdParty_IP_11-16_b16_Linux64,type=bind,consistency=cached" + ... ], + ... + ``` + + Or if you launch the Docker container directly from CLI, use the above + arguments with `docker run` command: + + ``` + docker run ... --mount type=bind,source=/opt/FastModels_ThirdParty_IP_11-16_b16_Linux64,target=/opt/FastModels_ThirdParty_IP_11-16_b16_Linux64 ... + ``` + + - install the Fast Model Extension package via setup script inside Docker + container: + + ``` + ${MATTER_ROOT}/scripts/setup/openiotsdk/debugging_setup.sh + ``` + + - the GDB Remote Connection Plugin should be visible in + `/opt/FastModelsPortfolio_11.16/plugins/Linux64_GCC-9.3` directory. + - For `VScode devcontainer` use the environment variable + `FAST_MODEL_PLUGINS_PATH` to point to the correct directory. + - If the Docker container is directly launched remember to add the GDB + Remote Connection Plugin path to the environment variable + `FAST_MODEL_PLUGINS_PATH` inside the container: + ``` + export FAST_MODEL_PLUGINS_PATH=/opt/FastModelsPortfolio_11.16/plugins/Linux64_GCC-9.3 + ``` + +### Testing setup + +The Matter Python packages are required for the integration test suite. They are +not provided as part of the VSCode devcontainer. To install these run the +following command from the CLI: + +``` +${MATTER_ROOT}/scripts/run_in_build_env.sh './scripts/build_python.sh --install_wheel +build-env' +``` + +More information about the Python tools you can find +[here](../../src/controller/python/README.md). + +## Configuration + +### Trusted Firmware-M + +To add [TF-M](https://tf-m-user-guide.trustedfirmware.org) 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") +``` + +### Trusted Firmware-M Protected Storage + +By default, the +[Block Device storage](./openiotsdk_platform_overview.md#storage) is used for +storing Matter key-value data. + +There is an option to add +[TF-M Protected Storage Service](https://tf-m-user-guide.trustedfirmware.org/integration_guide/services/tfm_ps_integration_guide.html) +support for `key-value` storage component in the Matter examples. Set the +variable `CONFIG_CHIP_OPEN_IOT_SDK_USE_PSA_PS` to `YES` to add +`TF-M Protected Storage` support to your application. You can put it inside the +main application `CMakeLists.txt` file: + +``` +set(CONFIG_CHIP_OPEN_IOT_SDK_USE_PSA_PS YES) +``` + +or add as a Cmake command-line parameter: + +``` +cmake -G <...> -DCONFIG_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. + +> 💡 **Notes**: +> +> The `TF-M Protected Storage` option requires enabling +> [TF-M](#trusted-firmware-m) support. +> +> The `-k/--kvsstore` option in +> [Open IoT SDK build script](../../scripts/examples/openiotsdk_example.sh) +> selects key-value storage implementation for the Matter's examples. It +> demonstrates how to use the `CONFIG_CHIP_OPEN_IOT_SDK_USE_PSA_PS` variable. + +### Storing persistent memory block in external files + +The persistent storage is required to store key-value data of the Matter +examples. + +Two storage types are supported: + +- Block device storage: The memory partition is located in `non-secure SRAM` +- `TF-M` protected storage: The memory partition is located in + `secure QSPI_RAM` + +Fast models offers option to load and dump memory content. More details are +available +[here](./openiotsdk_platform_overview.md#fast-model-persistent-memory-via-files). +Depending on the storage implementation, different flags are used in the `FVP` +options. + +For block device storage use: + +``` +--dump mps3_board.sram=@0:0x0,0x100000 +--data mps3_board.sram=@0:0x0 +``` + +For `TF-M` protected storage use: + +``` +--dump mps3_board.qspi_sram=@0:0x660000,0x12000 +--data mps3_board.qspi_sram=@0:0x660000 +``` + +> 💡 **Notes**: +> +> The `file-path` must exist to use the `--data` option. + +[Open IoT SDK build script](../../scripts/examples/openiotsdk_example.sh) +provides the `-K,--kvsfile` option to use the persistence options listed above. + +## Building + +You can build examples using the dedicated VSCode task or by calling directly +the build script from the command line. + +### Building using the VSCode task + +- Open the Command Palette: F1 +- Select `Tasks: Run Task` +- Select `Build Open IoT SDK example` +- Decide on debug mode support +- Decide on LwIP debug logs support +- Choose example name + +This will call the script with the selected parameters. + +### Building using CLI + +You can call the script directly yourself. + +``` +${MATTER_ROOT}/scripts/examples/openiotsdk_example.sh +``` + +Use `--help` to get more information about the script options. + +## Running + +The application runs in the background and opens a telnet session. The telnet +client connects to the port used by the `FVP`. When the telnet process is +terminated it also terminates the `FVP` instance. + +To exit the telnet session, type CTRL + ]. This changes the command +prompt to show as: + +``` +telnet> +``` + +Back in the terminal, type in the word 'close' to terminate the session. + +``` +telnet> close +``` + +You can run an example by using a VSCode task or by calling the run script +directly from the command line. + +### Running using the VSCode task + +- Open the Command Palette: F1 +- Select `Tasks: Run Task` +- Select `Run Open IoT SDK example` +- Enter network namespace +- Enter network interface +- Choose example name + +This will call the script with the selected example name. + +### Running using CLI + +You can call the script directly yourself. + +``` +${MATTER_ROOT}/scripts/examples/openiotsdk_example.sh -C run +``` + +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 +``` + +## Testing + +Run the Pytest integration test for the specific application. + +The test result can be found in the +`src/test_driver/openiotsdk/integration-tests//test_report.json` +file. + +You can test an example by using a VSCode task or by calling the test script +directly from the command line. + +### Testing using the VSCode task + +- Open the Command Palette: F1 +- Select `Tasks: Run Task` +- Select `Test Open IoT SDK example` +- Enter network namespace +- Enter network interface +- Choose 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 +``` + +Testing an example in a 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 +``` + +## Debugging + +Before debugging ensure the following: + +1. The debug environment is correctly setup: + [debugging setup](#debugging-setup). + +2. The example is compiled with debug symbols enabled: + + For CLI: + + ``` + ${MATTER_ROOT}/scripts/examples/openiotsdk_example.sh -d true + ``` + + For the VSCode task: + + ``` + => Use debug mode (true) + ``` + +3. The test network is correctly setup (if required): see + [networking setup](#networking-setup). + +### General instructions + +- Click `Run and Debug` from the primary side menu or press + Ctrl+Shift+D +- Select `Debug Open IoT SDK example application` from the drop down list +- Click `Start Debugging`(green triangle) or press F5 +- Choose example name +- Enter GDB target address +- Enter network namespace +- Enter network interface +- Choose example name + +As soon as a debugging session starts, the `DEBUG CONSOLE` panel is displayed +and shows the debugging output. Use debug controls to debug the current +application. + +For debugging remote targets (i.e. run in other network namespaces) you need to +pass the hostname/IP address of the external GDB target that you want to connect +to (_GDB target address_). + +In the case of using the [Open IoT SDK network environment](#networking-setup) +the GDB server runs inside a namespace and has the same IP address as the bridge +interface. + +``` +${MATTER_ROOT}/scripts/run_in_ns.sh ifconfig +``` + +The network namespace name and TAP interface name are also required then. + +The application with GDB Remote Connection Plugin runs in the background and +opens a telnet session in terminal. The telnet client connects to the port used +by the `FVP`. When the telnet process is terminated it will also terminate the +`FVP` instance. + +To exit the telnet session, type CTRL + ]. This changes the command +prompt to show as: + +``` +telnet> +``` + +Back in the terminal, type in the word 'close' to terminate the session. + +``` +telnet> close +``` + +> 💡 **Notes**: +> +> 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. +> +> There are issues with debugging examples when the Docker container use the +> [network host](https://docs.docker.com/network/host/) and VPN connection is +> established. Changing routing negatively affects debugging process. It is +> recommended not to use VPN connections while debugging. + +## Specific examples + +### Build lock-app example and run it in the network namespace + +**Using CLI** + +``` +${MATTER_ROOT}/scripts/examples/openiotsdk_example.sh lock-app + +export TEST_NETWORK_NAME=OIStest + +sudo ${MATTER_ROOT}/scripts/setup/openiotsdk/network_setup.sh -n $TEST_NETWORK_NAME restart + +${MATTER_ROOT}/scripts/examples/scripts/run_in_ns.sh ${TEST_NETWORK_NAME}ns +${MATTER_ROOT}/scripts/examples/openiotsdk_example.sh -C run -n ${TEST_NETWORK_NAME}tap +lock-app +``` + +**Using the VSCode task** + +Build example: + +- Open the Command Palette: F1 +- Select `Tasks: Run Task` +- Select `Build Open IoT SDK example` +- Deny debug mode support `false` +- Deny LwIP debug logs support `false` +- Choose example name `lock-app` + +Setup network environment: + +- Open the Command Palette: F1 +- Select `Tasks: Run Task` +- Select `Setup Open IoT SDK network` +- Enter the network namespace name `OIStest` +- Choose command `restart` + +Run example: + +- Open the Command Palette: F1 +- Select `Tasks: Run Task` +- Select `Run Open IoT SDK example` +- Enter network namespace `OIStestns` +- Enter network interface `OIStesttap` +- Choose example name `lock-app` + +The example output should be seen in the terminal window. + +### Build lock-app example and execute its test in the network namespace + +**Using CLI** + +``` +${MATTER_ROOT}/scripts/examples/openiotsdk_example.sh lock-app + +export TEST_NETWORK_NAME=OIStest + +sudo ${MATTER_ROOT}/scripts/setup/openiotsdk/network_setup.sh -n $TEST_NETWORK_NAME restart + +${MATTER_ROOT}/scripts/examples/scripts/run_in_ns.sh ${TEST_NETWORK_NAME}ns +${MATTER_ROOT}/scripts/examples/openiotsdk_example.sh -C test -n ${TEST_NETWORK_NAME}tap +lock-app +``` + +**Using the VSCode task** + +Build example: + +- Open the Command Palette: F1 +- Select `Tasks: Run Task` +- Select `Build Open IoT SDK example` +- Deny debug mode support `false` +- Deny LwIP debug logs support `false` +- Choose example name `lock-app` + +Setup network environment: + +- Open the Command Palette: F1 +- Select `Tasks: Run Task` +- Select `Setup Open IoT SDK network` +- Enter the network namespace name `OIStest` +- Choose command `restart` + +Test example: + +- Open the Command Palette: F1 +- Select `Tasks: Run Task` +- Select `Test Open IoT SDK example` +- Enter network namespace `OIStestns` +- Enter network interface `OIStesttap` +- Choose example name `lock-app` + +### Build lock-app example in debug mode and debug it in the network namespace using the VSCode task + +Build example: + +- Open the Command Palette: F1 +- Select `Tasks: Run Task` +- Select `Build Open IoT SDK example` +- Confirm debug mode support `true` +- Deny LwIP debug logs support `false` +- Choose example name `lock-app` + +Setup network environment: + +- Open the Command Palette: F1 +- Select `Tasks: Run Task` +- Select `Setup Open IoT SDK network` +- Enter the network namespace name `OIStest` +- Choose command `restart` + +Debug example: + +- Click `Run and Debug` from the primary side menu or press + Ctrl+Shift+D +- Select `Debug Open IoT SDK example application` from the drop down list +- Click `Start Debugging`(green triangle) or press F5 +- Choose example name `lock-app` +- Enter GDB target address `10.200.1.2` +- Enter network namespace `OIStestns` +- Enter network interface `OIStesttap` +- Choose example name `lock-app` + +Use debug controls to debug the application. + +## Add new example + +This chapter describes how to add a new Matter example based on Open IoT SDK +platform. + +In the description below we use the placeholder `example_name` as the name of +the example to create. Replace it with the name of your example. + +> 💡 **Notes**: +> +> Remember to update the list of currently supported Matter examples at the top +> of this document. + +### Files structure + +A new example should be put into `examples//openiotsdk` directory. +It should contain: + +- application source files and headers in the `main` sub-directory +- application `CMakeLists.txt` file +- `.gitignore` file with with all sources to skip +- `README.md` file with example description +- additional directories with required configuration for used components. Use + `component_name-config` pattern, e.g `freertos-config` + +### Target name + +A new application target name should be created with +`chip-openiotsdk--example(_ns)` pattern. The `_ns` suffix is +required for [TF-M applications](#trusted-firmware-m). + +Example: + +``` +set(APP_TARGET chip-openiotsdk-new-example-example_ns) +``` + +### Example tools + +Add a new example name to the list in the +`examples/platform/openiotsdk/supported_examples.txt` file. After that the new +example is available in all necessary tools such as helper script +`scripts/examples/openiotsdk_example.sh` or VSCode tasks. + +Example: + +``` +... +example_name +... +``` + +### CI + +To add a new example to the Matter CI edit the +`.github/workflows/examples-openiotsdk.yaml` file and add the next step for +`openiotsdk` job step that build this example. + +Example: + +``` +... +- name: Build new-example example + id: build_new_example + timeout-minutes: 10 + run: | + scripts/examples/openiotsdk_example.sh new-example + .environment/pigweed-venv/bin/python3 scripts/tools/memory/gh_sizes.py \ + openiotsdk release new-example \ + examples/new-example/openiotsdk/build/chip-openiotsdk-new-example-example.elf \ + /tmp/bloat_reports/ +... +``` diff --git a/docs/guides/openiotsdk_platform_overview.md b/docs/guides/openiotsdk_platform_overview.md index 211cd1af852179..f52d18b4e65aa0 100644 --- a/docs/guides/openiotsdk_platform_overview.md +++ b/docs/guides/openiotsdk_platform_overview.md @@ -68,17 +68,42 @@ Configuration of Mbed TLS is in Storage in Open IoT SDK is provided by [TDBStore](https://gitlab.arm.com/iot/open-iot-sdk/storage) which is a simple -Key-Value Storage over a block device. +key-value storage over a block device. + +If the application uses +[Trusted Firmware-M](https://tf-m-user-guide.trustedfirmware.org) then +[TF-M Protected Storage Service](https://tf-m-user-guide.trustedfirmware.org/integration_guide/services/tfm_ps_integration_guide.html) +can be used as an alternative for persistence in secure memory. --- **NOTE** -On the Corstone targets this currently is implemented as a RAM memory region -emulating a Flash device. This does not offer persistence between launches. +On `FVP` Corstone targets, memory content is lost after the program exits. To +achieve persistence memory regions used for the key-value storage must be saved +when the execution ends. --- +### Fast model persistent memory via files + +Two command lines options can be used to achieve persistence of a specific +memory regions: + +- `--dump` store the content of a memory region into a file when the model + ends its execution +- `--data` load the content of a file into a specific memory region at startup + +Use the `--list-memory` flag to see the list of instances and memory spaces for +your `FVP` model. + +Visit the +[FVP command line documentation](https://developer.arm.com/documentation/100966/1116/Getting-Started-with-Fixed-Virtual-Platforms/FVP-command-line-options) +for more details about these flags. + +Depending on your application, choose the right memory instance, memory space, +address and size. + ## Clocks Open IoT SDK does not currently offer an RTC. Matter configuration has been set diff --git a/docs/guides/openiotsdk_unit_tests.md b/docs/guides/openiotsdk_unit_tests.md new file mode 100644 index 00000000000000..7b9bba56707870 --- /dev/null +++ b/docs/guides/openiotsdk_unit_tests.md @@ -0,0 +1,249 @@ +# Matter Open IoT SDK unit tests + +The unit testing approach is to create a separate application with Matter test +library dependence. Each Matter project component implements the set of unit +tests that are located in the `test` directory, e.g. `src/inet/tests`. Those +sources are built as a static library that can be linked to the unit test +application separately or as a monolithic test library. The common Matter test +library collects all test cases and provides the engine based on +[Nest Labs Unit Test](https://github.com/nestlabs/nlunit-test) to run them in +the application. + +The Open IoT SDK unit tests implementation are located in the +`src/test_driver/openiotsdk/unit-tests` directory. This project builds a +separate application for each Matter component that is tested. It's built using +[Open IoT SDK](https://gitlab.arm.com/iot/open-iot-sdk) and run inside an +emulated target through the +[Arm FVP model for the Corstone-300 MPS3](https://developer.arm.com/downloads/-/arm-ecosystem-fvps). + +The list of currently supported Matter's component tests: + +``` +accesstest +AppTests +ASN1Tests +BDXTests +ChipCryptoTests +CoreTests +CredentialsTest +DataModelTests +InetLayerTests +MdnsTests +MessagingLayerTests +MinimalMdnsCoreTests +MinimalMdnsRecordsTests +MinimalMdnsRespondersTests +PlatformTests +RawTransportTests +RetransmitTests +SecureChannelTests +SetupPayloadTests +SupportTests +SystemLayerTests +TestShell +TransportLayerTests +UserDirectedCommissioningTests +``` + +Each application links the specific Matter test library, executes registered +tests and prints the result which is the number of tests that failed. + +## Environment setup + +The required environment is the same as for the Matter examples. For information +on how to set it up see +[Open IoT SDK examples environment](./openiotsdk_examples.md#environment-setup). + +## Configuration + +The configuration options are the same as for the Matter examples. For +information on how to configure unit-tests applications see +[Open IoT SDK examples configuration](./openiotsdk_examples.md#configuration). + +## Building + +The build process means creating a separate executable file for each Matter +tested component. It assumes the use of all supported test libraries and +creating independent applications from them. + +You can build unit tests by using a VSCode task or by calling the build script +directly from the command line. + +### Building using the VSCode task + +- Open the Command Palette: F1 +- Select `Tasks: Run Task` +- Select `Build Open IoT SDK unit-tests` +- Decide on debug mode support +- Decide on LwIP debug logs support +- Choose crypto algorithm +- Choose socket API + +This will call the script with the selected parameters. + +### Building using CLI + +You can call the script directly yourself. + +``` +${MATTER_ROOT}/scripts/examples/openiotsdk_example.sh unit-tests +``` + +Use `--help` to get more information about the script options. + +## Running + +Unit-tests applications are run independently. It runs in the background and +opens a telnet session. The telnet client connects to the port used by the +`FVP`. When the telnet process is terminated it will also terminate the `FVP` +instance. + +To exit the telnet session, type CTRL + ]. This changes the command +prompt to show as: + +``` +telnet> +``` + +Back in the terminal, type in the word 'close' to terminate the session. + +``` +telnet> close +``` + +You can run specific unit test by using a VSCode task or by calling the run +script directly from the command line. + +### Running using the VSCode task + +- Open the Command Palette: F1 +- Select `Tasks: Run Task` +- Select `Run Open IoT SDK unit-tests` +- Choose unit test name + +This will call the script with the selected example name. + +### Running using CLI + +You can call the script directly yourself. + +``` +${MATTER_ROOT}/scripts/examples/openiotsdk_example.sh -C run unit-tests +``` + +## Testing + +Run the Pytest integration test for the specific unit test application. + +The test result can be found in the +`src/test_driver/openiotsdk/integration-tests/unit-tests/test_report_.json` +file. + +You can execute the integration test for specific unit test by using a VSCode +task or by calling the run script directly from the command line. + +### Testing using the VSCode task + +- Open the Command Palette: F1 +- Select `Tasks: Run Task` +- Select `Test Open IoT SDK unit-tests` +- Choose unit test 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 unit-tests +``` + +> 💡 **Notes**: +> +> Use `test` command without a specific test name, runs all supported unit +> tests: +> +> `${MATTER_ROOT}/scripts/examples/openiotsdk_example.sh -C test unit-tests` + +## Debugging + +Before debugging ensure the following: + +1. The debug environment is correctly setup: + [debugging setup](./openiotsdk_examples.md#debugging-setup). + +2. The unit tests are compiled with debug symbols enabled: + + For CLI: + + ``` + ${MATTER_ROOT}/scripts/examples/openiotsdk_example.sh -d true unit-tests + ``` + + For the VSCode task: + + ``` + => Use debug mode (true) + ``` + +You can debug the specific unit test by using a VSCode launch task: + +- Click `Run and Debug` from the primary side menu or press + Ctrl+Shift+D +- Select `Debug Open IoT SDK unit-tests application` from the drop down list +- Click `Start Debugging`(green triangle) or press F5 +- Choose unit test name twice + +As soon as a debugging session starts, the `DEBUG CONSOLE` panel is displayed +and shows the debugging output. Use debug controls to debug the current +application. + +The application with GDB Remote Connection Plugin runs in the background and +opens a telnet session in terminal. The telnet client connects to the port used +by the `FVP`. When the telnet process is terminated it will also terminate the +`FVP` instance. + +To exit the telnet session, type CTRL + ]. This changes the command +prompt to show as: + +``` +telnet> +``` + +Back in the terminal, type in the word 'close' to terminate the session. + +``` +telnet> close +``` + +> 💡 **Notes**: +> +> As you can see above, you will need to select the name of the unit test 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. + +## Add existing Matter's component test + +To to add an existing Matter's component test to unit tests project, extend the +list in the `src/test_driver/openiotsdk/unit-tests/test_components.txt` file +with a test name (`test_name`). After that, the new test is built and available +in all necessary tools such as helper script +`scripts/examples/openiotsdk_example.sh` or VSCode tasks. + +Example: + +``` +... +test_name +... +``` + +> 💡 **Notes**: +> +> The existing Matter's component tests are built as a separate libraries. The +> `src/BUILD.gn` GN project collects them in the target group. Make sure that +> the test you want to add is not skipped for the Open IoT SDK platform. +> +> Remember to update the list of supported Matter's component tests at the top +> of this document. diff --git a/examples/lock-app/openiotsdk/CMakeLists.txt b/examples/lock-app/openiotsdk/CMakeLists.txt index 289ecbc893fc54..492e5cb3b1f971 100644 --- a/examples/lock-app/openiotsdk/CMakeLists.txt +++ b/examples/lock-app/openiotsdk/CMakeLists.txt @@ -29,7 +29,6 @@ set(APP_TARGET chip-openiotsdk-lock-app-example_ns) set(TFM_SUPPORT YES) set(TFM_PROJECT_CONFIG_HEADER_FILE "${CMAKE_CURRENT_SOURCE_DIR}/tf-m-config/TfmProjectConfig.h") set(TFM_NS_APP_VERSION "0.0.1") -set(CONFIG_CHIP_OPEN_IOT_SDK_USE_PSA_PS YES) # Toolchain files need to exist before first call to project include(toolchain) diff --git a/examples/lock-app/openiotsdk/README.md b/examples/lock-app/openiotsdk/README.md index 4ff38ecc3a1445..69e569b9be2888 100644 --- a/examples/lock-app/openiotsdk/README.md +++ b/examples/lock-app/openiotsdk/README.md @@ -6,18 +6,17 @@ device with one basic bolt. The example behaves as a Matter accessory, device that can be paired into an existing Matter network and can be controlled by it. -## Build and run +## Build-run-test-debug -For information on how to build and run this example and further information -about the platform it is run on see -[Open IoT SDK examples](../../../docs/examples/openiotsdk_examples.md). +For information on how to build, run, test and debug this example and further +information about the platform it is run on see +[Open IoT SDK examples](../../../docs/guides/openiotsdk_examples.md). The example name to use in the scripts is `lock-app`. -## Using the example +## Example output -Communication with the application goes through the active telnet session. When -the application runs these lines should be visible: +When the example runs, these lines should be visible: ``` [INF] [-] Open IoT SDK lock-app example application start @@ -25,8 +24,8 @@ the application runs these lines should be visible: [INF] [-] Open IoT SDK lock-app example application run ``` -The lock-app application launched correctly and you can follow traces in the -terminal. +This means the lock-app application launched correctly and you can follow traces +in the terminal. ### Commissioning @@ -44,11 +43,16 @@ you used to perform the commissioning step above. Example command: ``` -zcl DoorLock LockDoor 1234 1 pinCode=str:12345 +chip-tool doorlock lock-door 123 1 --timedInteractionTimeoutMs 100 ``` In response the device will output this line to the terminal: ``` -[INF] [ZC] Lock App: specified PIN code was found in the database, setting door lock state to "Locked" [endpointId=1] +[INF] [ZCL] Door Lock App: setting door lock state to "Locked" [endpointId=1] ``` + +**NOTE** + +More details about the `chip-tool` controller can be found +[here](../../chip-tool/README.md). diff --git a/examples/platform/openiotsdk/supported_examples.txt b/examples/platform/openiotsdk/supported_examples.txt new file mode 100644 index 00000000000000..18e91e2080c38c --- /dev/null +++ b/examples/platform/openiotsdk/supported_examples.txt @@ -0,0 +1,2 @@ +shell +lock-app diff --git a/examples/platform/openiotsdk/tf-m/targets/an552/partition/flash_layout.h b/examples/platform/openiotsdk/tf-m/targets/an552/partition/flash_layout.h index 5adc3dcf35daff..68a33048e7b44b 100644 --- a/examples/platform/openiotsdk/tf-m/targets/an552/partition/flash_layout.h +++ b/examples/platform/openiotsdk/tf-m/targets/an552/partition/flash_layout.h @@ -24,30 +24,30 @@ * * QSPI SRAM S * 0x0000_0000 Secure image primary slot (384 KB) - * 0x0006_0000 Non-secure image primary slot (2 MB) - * 0x0026_0000 Secure image secondary slot (384 KB) - * 0x002C_0000 Non-secure image secondary slot (2 MB) - * 0x004C_0000 Scratch area (2 MB) - * 0x006C_0000 Protected Storage Area (64 KB) - * 0x006D_0000 Internal Trusted Storage Area (64 KB) - * 0x006E_0000 OTP / NV counters area (8 KB) - * 0x006E_2000 Unused + * 0x0006_0000 Non-secure image primary slot (2.25 MB) + * 0x002A_0000 Secure image secondary slot (384 KB) + * 0x0030_0000 Non-secure image secondary slot (2.25 MB) + * 0x0054_0000 Scratch area (1.125 MB) + * 0x0066_0000 Protected Storage Area (64 KB) + * 0x0067_0000 OTP / NV counters area (8 KB) + * 0x0067_2000 Internal Trusted Storage Area (64 KB) + * 0x0068_2000 Unused * * Flash layout on AN552 with BL2 (single image boot): * * QSPI SRAM S (part1) - * 0x0000_0000 Primary image area (2MB + 384 KB): + * 0x0000_0000 Primary image area (2.25MB + 384 KB): * 0x0000_0000 Secure image primary (384 KB) - * 0x0006_0000 Non-secure image primary (2 MB) + * 0x0006_0000 Non-secure image primary (2.25 MB) * QSPI SRAM S (part2) - * 0x0026_0000 Secondary image area (2MB + 384 KB): - * 0x0026_0000 Secure image secondary (384 KB) - * 0x002C_0000 Non-secure image secondary (384 KB) - * 0x004C_0000 Scratch area (2 MB) - * 0x006C_0000 Protected Storage Area (64 KB) - * 0x006D_0000 Internal Trusted Storage Area (64 KB) - * 0x006E_0000 OTP / NV counters area (8 KB) - * 0x006E_2000 Unused + * 0x002A_0000 Secondary image area (2.25MB + 384 KB): + * 0x002A_0000 Secure image secondary (384 KB) + * 0x0030_0000 Non-secure image secondary (2.25 KB) + * 0x0054_0000 Scratch area (1.125 MB) + * 0x0066_0000 Protected Storage Area (64 KB) + * 0x0067_0000 OTP / NV counters area (8 KB) + * 0x0067_2000 Internal Trusted Storage Area (64 KB) + * 0x0068_2000 Unused */ /* This header file is included from linker scatter file as well, where only a @@ -59,7 +59,7 @@ /* Size of a Secure and of a Non-secure image */ #define FLASH_S_PARTITION_SIZE (0x60000) /* S partition: 384 KB */ -#define FLASH_NS_PARTITION_SIZE (0x200000) /* NS partition: 2 MB */ +#define FLASH_NS_PARTITION_SIZE (0x240000) /* NS partition: 2.25 MB */ #define FLASH_MAX_PARTITION_SIZE \ ((FLASH_S_PARTITION_SIZE > FLASH_NS_PARTITION_SIZE) ? FLASH_S_PARTITION_SIZE : FLASH_NS_PARTITION_SIZE) @@ -145,16 +145,16 @@ #define FLASH_PS_AREA_OFFSET (FLASH_AREA_SCRATCH_OFFSET + FLASH_AREA_SCRATCH_SIZE) #define FLASH_PS_AREA_SIZE (0x10000) /* 64 KB */ -/* Internal Trusted Storage (ITS) Service definitions */ -#define FLASH_ITS_AREA_OFFSET (FLASH_PS_AREA_OFFSET + FLASH_PS_AREA_SIZE) -#define FLASH_ITS_AREA_SIZE (0x10000) /* 64 KB */ - /* OTP_definitions */ -#define FLASH_OTP_NV_COUNTERS_AREA_OFFSET (FLASH_ITS_AREA_OFFSET + FLASH_ITS_AREA_SIZE) +#define FLASH_OTP_NV_COUNTERS_AREA_OFFSET (FLASH_PS_AREA_OFFSET + FLASH_PS_AREA_SIZE) #define FLASH_OTP_NV_COUNTERS_AREA_SIZE (FLASH_AREA_IMAGE_SECTOR_SIZE * 2) #define FLASH_OTP_NV_COUNTERS_SECTOR_SIZE FLASH_AREA_IMAGE_SECTOR_SIZE -#if (FLASH_OTP_NV_COUNTERS_AREA_OFFSET + FLASH_OTP_NV_COUNTERS_AREA_SIZE > QSPI_SRAM_SIZE) +/* Internal Trusted Storage (ITS) Service definitions */ +#define FLASH_ITS_AREA_OFFSET (FLASH_OTP_NV_COUNTERS_AREA_OFFSET + FLASH_OTP_NV_COUNTERS_AREA_SIZE) +#define FLASH_ITS_AREA_SIZE (0x10000) /* 64 KB */ + +#if (FLASH_ITS_AREA_OFFSET + FLASH_ITS_AREA_SIZE > QSPI_SRAM_SIZE) #error "Out of QSPI SRAM memory!" #endif diff --git a/examples/shell/openiotsdk/README.md b/examples/shell/openiotsdk/README.md index 3acf66098b0094..b633fa7b0143a3 100644 --- a/examples/shell/openiotsdk/README.md +++ b/examples/shell/openiotsdk/README.md @@ -8,18 +8,17 @@ operations. For more details see [Common shell commands](../README.md#matter-shell-command-details). -## Build and run +## Build-run-test-debug -For information on how to build and run this example and further information -about the platform it is run on see -[Open IoT SDK examples](../../../docs/examples/openiotsdk_examples.md). +For information on how to build, run, test and debug this example and further +information about the platform it is run on see +[Open IoT SDK examples](../../../docs/guides/openiotsdk_examples.md). The example name to use in the scripts is `shell`. -## Using the example +## Example output -Communication with the application goes through the active telnet session. When -the application runs these lines should be visible: +When the example runs, these lines should be visible: ``` [INF] [SH] Open IoT SDK shell example application start @@ -27,7 +26,7 @@ the application runs these lines should be visible: > ``` -The shell application launched correctly. +This means the shell application launched correctly. Pass commands to the terminal and wait for the response. The application supports common Matter shell commands. They are used to control the basic diff --git a/scripts/examples/openiotsdk_example.sh b/scripts/examples/openiotsdk_example.sh index 11aeffbe08601f..6b19a8be7f04e7 100755 --- a/scripts/examples/openiotsdk_example.sh +++ b/scripts/examples/openiotsdk_example.sh @@ -41,14 +41,17 @@ TELNET_CONNECTION_PORT="" FAILED_TESTS=0 IS_UNIT_TEST=0 FVP_NETWORK="user" +KVS_STORAGE_TYPE="tdb" +KVS_STORAGE_FILE="" -readarray -t TEST_NAMES <"$CHIP_ROOT"/src/test_driver/openiotsdk/unit-tests/testnames.txt +declare -A tdb_storage_param=([instance]=sram [memspace]=0 [address]=0x0 [size]=0x100000) +declare -A ps_storage_param=([instance]=qspi_sram [memspace]=0 [address]=0x660000 [size]=0x12000) -declare -a SUPPORTED_APP_NAMES -SUPPORTED_APP_NAMES+=("shell") -SUPPORTED_APP_NAMES+=("lock-app") +readarray -t SUPPORTED_APP_NAMES <"$CHIP_ROOT"/examples/platform/openiotsdk/supported_examples.txt SUPPORTED_APP_NAMES+=("unit-tests") +readarray -t TEST_NAMES <"$CHIP_ROOT"/src/test_driver/openiotsdk/unit-tests/test_components.txt + function show_usage() { cat < Action to execute -d,--debug Build in debug mode -l,--lwipdebug Build with LwIP debug logs support + -k,--kvsstore Select KVS storage type -p,--path Build path + -K,--kvsfile Path to KVS storage file which will be used to ensure persistence -n,--network FVP network interface name Examples: @@ -77,8 +82,13 @@ EOF You run or test individual test suites of unit tests by using their names [test_name] with the specified command: EOF - cat "$CHIP_ROOT"/src/test_driver/openiotsdk/unit-tests/testnames.txt + + for test in "${TEST_NAMES[@]}"; do + echo " $test" + done + cat <&2 + echo "Error: $GDB_PLUGIN does not exist." >&2 exit 1 fi @@ -156,6 +173,18 @@ function run_fvp() { RUN_OPTIONS+=(-C mps3_board.hostbridge.interfaceName="$FVP_NETWORK") fi + if [ -n "$KVS_STORAGE_FILE" ]; then + if [[ $KVS_STORAGE_TYPE == "ps" ]]; then + declare -n storage_param=ps_storage_param + else + declare -n storage_param=tdb_storage_param + fi + if [ -f "$KVS_STORAGE_FILE" ]; then + RUN_OPTIONS+=(--data "mps3_board.${storage_param[instance]}=$KVS_STORAGE_FILE@${storage_param[memspace]}:${storage_param[address]}") + fi + RUN_OPTIONS+=(--dump "mps3_board.${storage_param[instance]}=$KVS_STORAGE_FILE@${storage_param[memspace]}:${storage_param[address]},${storage_param[size]}") + fi + echo "Running $EXAMPLE_EXE_PATH with options: ${RUN_OPTIONS[@]}" # Run the FVP @@ -239,8 +268,8 @@ function run_test() { fi } -SHORT=C:,p:,d:,l:,n:,c,s,h -LONG=command:,path:,debug:,lwipdebug:,network:,clean,scratch,help +SHORT=C:,p:,d:,l:,n:,k:,K:,c,s,h +LONG=command:,path:,debug:,lwipdebug:,network:,kvsstore:,kvsfile:,clean,scratch,help OPTS=$(getopt -n build --options "$SHORT" --longoptions "$LONG" -- "$@") eval set -- "$OPTS" @@ -271,6 +300,14 @@ while :; do LWIP_DEBUG=$2 shift 2 ;; + -k | --kvsstore) + KVS_STORAGE_TYPE=$2 + shift 2 + ;; + -K | --kvsfile) + KVS_STORAGE_FILE=$2 + shift 2 + ;; -p | --path) BUILD_PATH=$CHIP_ROOT/$2 shift 2 @@ -334,6 +371,15 @@ else EXAMPLE_PATH="$CHIP_ROOT/examples/$EXAMPLE/openiotsdk" fi +case "$KVS_STORAGE_TYPE" in + ps | tdb) ;; + *) + echo "Wrong KVS storage type definition" + show_usage + exit 2 + ;; +esac + TOOLCHAIN_PATH="toolchains/toolchain-$TOOLCHAIN.cmake" if [ -z "$BUILD_PATH" ]; then diff --git a/scripts/setup/openiotsdk/debugging_setup.sh b/scripts/setup/openiotsdk/debugging_setup.sh new file mode 100755 index 00000000000000..09a199b19fbf7b --- /dev/null +++ b/scripts/setup/openiotsdk/debugging_setup.sh @@ -0,0 +1,31 @@ +#!/bin/bash + +# +# Copyright (c) 2023 Project CHIP Authors +# +# 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. +# + +# Installing FVP Fast Model extension in /opt directory + +FAST_MODEL_EXT_DIR=/opt/FastModels_ThirdParty_IP_11-16_b16_Linux64 + +if [ ! -d "$FAST_MODEL_EXT_DIR" ]; then + echo "Fast Model Extension package directory: $FAST_MODEL_EXT_DIR does not exists. Ensure it is mounted." >&2 + exit 1 +fi + +echo "Install Fast Model extension in /opt" >&2 +cd "$FAST_MODEL_EXT_DIR" +sudo ./setup.bin --i-accept-the-license-agreement --basepath /opt +cd - diff --git a/src/platform/openiotsdk/CHIPPlatformConfig.h b/src/platform/openiotsdk/CHIPPlatformConfig.h index efc4afd358fdf6..0cf7664c30d3a9 100644 --- a/src/platform/openiotsdk/CHIPPlatformConfig.h +++ b/src/platform/openiotsdk/CHIPPlatformConfig.h @@ -30,7 +30,9 @@ // ==================== General Platform Adaptations ==================== -#define CHIP_CONFIG_EXPECTED_LOW_PROCESSING_TIME 10 +#ifndef CHIP_CONFIG_MAX_FABRICS +#define CHIP_CONFIG_MAX_FABRICS 5 +#endif // ==================== Security Adaptations ==================== diff --git a/src/platform/openiotsdk/KVBlockDeviceStore.cpp b/src/platform/openiotsdk/KVBlockDeviceStore.cpp index 3a235a0d99c61a..ef623b1f9bc2b9 100644 --- a/src/platform/openiotsdk/KVBlockDeviceStore.cpp +++ b/src/platform/openiotsdk/KVBlockDeviceStore.cpp @@ -114,6 +114,20 @@ CHIP_ERROR KVBlockDeviceStore::Init(void) return CHIP_NO_ERROR; } +CHIP_ERROR KVBlockDeviceStore::Shutdown(void) +{ + if (!tdb) + { + return CHIP_NO_ERROR; + } + + tdb->deinit(); + delete tdb; + tdb = nullptr; + + return CHIP_NO_ERROR; +} + CHIP_ERROR KVBlockDeviceStore::ReadConfigValue(Key key, bool & val) { if (Init() != CHIP_NO_ERROR) diff --git a/src/platform/openiotsdk/KVBlockDeviceStore.h b/src/platform/openiotsdk/KVBlockDeviceStore.h index 5935d599ba17a8..e817d9dde17f28 100644 --- a/src/platform/openiotsdk/KVBlockDeviceStore.h +++ b/src/platform/openiotsdk/KVBlockDeviceStore.h @@ -81,6 +81,7 @@ class KVBlockDeviceStore // Initialization static CHIP_ERROR Init(void); + static CHIP_ERROR Shutdown(void); // Config value accessors static CHIP_ERROR ReadConfigValue(Key key, bool & val); diff --git a/src/platform/openiotsdk/KVPsaPsStore.cpp b/src/platform/openiotsdk/KVPsaPsStore.cpp index 523cb37b536c2a..26215bf2e4431a 100644 --- a/src/platform/openiotsdk/KVPsaPsStore.cpp +++ b/src/platform/openiotsdk/KVPsaPsStore.cpp @@ -115,6 +115,15 @@ CHIP_ERROR KVPsaPsStore::Init(void) return CHIP_NO_ERROR; } +CHIP_ERROR KVPsaPsStore::Shutdown(void) +{ + KVSKeyMapUpdate(); + + initialized = false; + + return CHIP_NO_ERROR; +} + CHIP_ERROR KVPsaPsStore::ReadConfigValue(Key key, bool & val) { if (!ConfigValueExists(key)) diff --git a/src/platform/openiotsdk/KVPsaPsStore.h b/src/platform/openiotsdk/KVPsaPsStore.h index b66c9cf669df63..7e68bdbd32491b 100644 --- a/src/platform/openiotsdk/KVPsaPsStore.h +++ b/src/platform/openiotsdk/KVPsaPsStore.h @@ -122,6 +122,7 @@ class KVPsaPsStore static const Key kMaxMatterPsaPaKeyRegion; static CHIP_ERROR Init(void); + static CHIP_ERROR Shutdown(void); // Config value accessors. static CHIP_ERROR ReadConfigValue(Key key, bool & val); diff --git a/src/platform/openiotsdk/KeyValueStoreManagerImpl.cpp b/src/platform/openiotsdk/KeyValueStoreManagerImpl.cpp index fb5268d494139f..8cf11d2e1ffc77 100644 --- a/src/platform/openiotsdk/KeyValueStoreManagerImpl.cpp +++ b/src/platform/openiotsdk/KeyValueStoreManagerImpl.cpp @@ -46,6 +46,11 @@ CHIP_ERROR KeyValueStoreManagerImpl::Init(void) return KVStoreConfig::Init(); } +CHIP_ERROR KeyValueStoreManagerImpl::Shutdown(void) +{ + return KVStoreConfig::Shutdown(); +} + CHIP_ERROR KeyValueStoreManagerImpl::_Get(const char * key, void * value, size_t value_size, size_t * read_bytes_size, size_t offset) { diff --git a/src/platform/openiotsdk/KeyValueStoreManagerImpl.h b/src/platform/openiotsdk/KeyValueStoreManagerImpl.h index 3b13ef410444f6..f8e423b35e00fe 100644 --- a/src/platform/openiotsdk/KeyValueStoreManagerImpl.h +++ b/src/platform/openiotsdk/KeyValueStoreManagerImpl.h @@ -38,6 +38,7 @@ class KeyValueStoreManagerImpl final : public KeyValueStoreManager public: CHIP_ERROR Init(void); + CHIP_ERROR Shutdown(void); CHIP_ERROR _Get(const char * key, void * value, size_t value_size, size_t * read_bytes_size = nullptr, size_t offset = 0); CHIP_ERROR _Delete(const char * key); CHIP_ERROR _Put(const char * key, const void * value, size_t value_size); diff --git a/src/platform/openiotsdk/SystemPlatformConfig.h b/src/platform/openiotsdk/SystemPlatformConfig.h index bd2e9b39c86786..c75aef3e170f5d 100644 --- a/src/platform/openiotsdk/SystemPlatformConfig.h +++ b/src/platform/openiotsdk/SystemPlatformConfig.h @@ -33,6 +33,7 @@ #define CHIP_SYSTEM_CONFIG_MBED_LOCKING 0 #define CHIP_SYSTEM_CONFIG_NO_LOCKING 0 #define CHIP_SYSTEM_CONFIG_CMSIS_RTOS_LOCKING 1 +#define CHIP_SYSTEM_CONFIG_POOL_USE_HEAP 1 #define CHIP_SYSTEM_CONFIG_PLATFORM_PROVIDES_TIME 1 #ifndef CHIP_SYSTEM_CONFIG_USE_LWIP_MONOTONIC_TIME diff --git a/src/test_driver/openiotsdk/unit-tests/CMakeLists.txt b/src/test_driver/openiotsdk/unit-tests/CMakeLists.txt index 15bf03373d5b46..740e4e55261ee3 100644 --- a/src/test_driver/openiotsdk/unit-tests/CMakeLists.txt +++ b/src/test_driver/openiotsdk/unit-tests/CMakeLists.txt @@ -42,8 +42,7 @@ include(linker) add_subdirectory(${OPEN_IOT_SDK_EXAMPLE_COMMON}/app ./app_build) -file(STRINGS testnames.txt TEST_NAMES_FROM_FILE) -STRING(REGEX REPLACE "\n" ";" TEST_NAMES_FROM_FILE "${TEST_NAMES_FROM_FILE}") +file(STRINGS test_components.txt TEST_NAMES_FROM_FILE) target_compile_definitions(openiotsdk-startup PRIVATE diff --git a/src/test_driver/openiotsdk/unit-tests/README.md b/src/test_driver/openiotsdk/unit-tests/README.md index 584f31aea71e0d..06cd8fa8b95600 100644 --- a/src/test_driver/openiotsdk/unit-tests/README.md +++ b/src/test_driver/openiotsdk/unit-tests/README.md @@ -1,86 +1,29 @@ # Matter Open IoT Unit Tests Application The Open IoT SDK Unit Tests Application executes all supported unit tests on the -target. +`FVP Fast Model` target. The Matter unit tests are included in a set of libraries and allow to validate most of the components used by Matter examples applications. The main goal of -this application is to run registered tests on Open IoT SDK target and check the +this project is to run registered tests on Open IoT SDK target and check the results. The final result is the number of tests that failed. -## Environment setup +## Build-run-test-debug -The required environment is the same as for the Matter examples. For information -on how to setup it see -[Open IoT SDK examples](../../../../docs/examples/openiotsdk_examples.md#Environment-setup). +For information on how to setup, build, run, test and debug unit tests refer to +[Open IoT SDK unit tests](../../../../docs/guides/openiotsdk_unit_tests.md). -## Building +## Application output -The build process means creating separate executable file for each Matter tested -component. It assumes the use of all supported test libraries and creating -independent applications from them. - -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 unit-tests => (debug on/off) -``` - -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 unit-tests -``` - -Use `--help` to get more information about the script options. - -## Running - -Unit-tests applications can be run independently or as an entire set. It 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. - -Expected output of each executed test: - -``` - [ATM] Open IoT SDK unit-tests start - [ATM] Open IoT SDK unit-tests run... - ... - [ATM] Test status: 0 -``` - -### Running using vscode task - -``` -Command Palette (F1) => Run Task... => Run Open IoT SDK unit-tests => or all (to run all tests) -``` - -### Running using CLI - -You can call the script directly yourself. - -``` -${MATTER_ROOT}/scripts/examples/openiotsdk_example.sh -C run unit-tests (optional to run specific test) -``` - -## Debugging - -Debugging can be started using a VS code launch task: +Expected output of each executed test application: ``` -Run and Debug (Ctrl+Shift+D) => Debug Open IoT SDK unit-tests application => Start Debugging (F5) => => +[ATM] Open IoT SDK unit-tests start +[ATM] Open IoT SDK unit-tests run... +... +[ATM] Test status: 0 +[ATM] Open IoT SDK unit-tests completed ``` -As you can see above, you will need to select the name of the test 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. +This means the test application launched correctly and executed all registered +test cases. The `Test status` value indicates the number of tests that failed. diff --git a/src/test_driver/openiotsdk/unit-tests/main/include/CHIPProjectConfig.h b/src/test_driver/openiotsdk/unit-tests/main/include/CHIPProjectConfig.h index bb2c4755245f95..458c7c809dbb57 100644 --- a/src/test_driver/openiotsdk/unit-tests/main/include/CHIPProjectConfig.h +++ b/src/test_driver/openiotsdk/unit-tests/main/include/CHIPProjectConfig.h @@ -31,14 +31,5 @@ #define CHIP_CONFIG_ENABLE_ARG_PARSER 1 #define CHIP_CONFIG_NON_POSIX_LONG_OPT 1 -#define CHIP_SYSTEM_CONFIG_NUM_TIMERS 32 -#define CHIP_DEVICE_CONFIG_ENABLE_BOTH_COMMISSIONER_AND_COMMISSIONEE 1 - +// Enable building for unit testing #define CONFIG_BUILD_FOR_HOST_UNIT_TEST 1 - -#define CONFIG_IM_BUILD_FOR_UNIT_TEST 1 -#define CHIP_DEVICE_CONFIG_DYNAMIC_ENDPOINT_COUNT 64 -#define CHIP_CONFIG_MAX_FABRICS 16 -#define CHIP_DEVICE_CONFIG_MAX_EVENT_QUEUE_SIZE 500 - -#define CHIP_SYSTEM_CONFIG_POOL_USE_HEAP 1 diff --git a/src/test_driver/openiotsdk/unit-tests/main/main_ns.cpp b/src/test_driver/openiotsdk/unit-tests/main/main_ns.cpp index e9c8bbd208cf48..a819655c162697 100644 --- a/src/test_driver/openiotsdk/unit-tests/main/main_ns.cpp +++ b/src/test_driver/openiotsdk/unit-tests/main/main_ns.cpp @@ -19,37 +19,15 @@ #include #include +#include "openiotsdk_platform.h" +#include #include #include -#include - -#include "cmsis_os2.h" -#include "openiotsdk_platform.h" - constexpr nl_test_output_logger_t NlTestLogger::nl_test_logger; using namespace ::chip; -static void test_thread(void * argument) -{ - int status; - CHIP_ERROR err; - - if (openiotsdk_network_init(true)) - { - ChipLogAutomation("ERROR: Network initialization failed"); - goto exit; - } - - ChipLogAutomation("Open IoT SDK unit-tests run..."); - status = RunRegisteredUnitTests(); - ChipLogAutomation("Test status: %d", status); - ChipLogAutomation("Open IoT SDK unit-tests completed"); -exit: - osThreadTerminate(osThreadGetId()); -} - int main() { if (openiotsdk_platform_init()) diff --git a/src/test_driver/openiotsdk/unit-tests/testnames.txt b/src/test_driver/openiotsdk/unit-tests/test_components.txt similarity index 100% rename from src/test_driver/openiotsdk/unit-tests/testnames.txt rename to src/test_driver/openiotsdk/unit-tests/test_components.txt