From 7b1056f6c5e1a58f173671139962f49132307d00 Mon Sep 17 00:00:00 2001 From: ATmobica Date: Tue, 20 Sep 2022 09:38:49 +0000 Subject: [PATCH] [OIS] Add Open IoT SDK platform documentation Create Open IoT SDK platform overview, commissioning approach description and common examples guide. Add README files to shell and lock-app examples. Signed-off-by: ATmobica --- .github/.wordlist.txt | 6 + docs/examples/openiotsdk_examples.md | 258 ++++++++++++++++++++ docs/guides/openiotsdk_commissioning.md | 47 ++++ docs/guides/openiotsdk_platform_overview.md | 95 +++++++ examples/lock-app/openiotsdk/README.md | 54 ++++ examples/shell/openiotsdk/README.md | 45 ++++ 6 files changed, 505 insertions(+) create mode 100644 docs/examples/openiotsdk_examples.md create mode 100644 docs/guides/openiotsdk_commissioning.md create mode 100644 docs/guides/openiotsdk_platform_overview.md create mode 100644 examples/lock-app/openiotsdk/README.md create mode 100644 examples/shell/openiotsdk/README.md diff --git a/.github/.wordlist.txt b/.github/.wordlist.txt index ca364bc513ae9c..34c4a0bf8932c4 100644 --- a/.github/.wordlist.txt +++ b/.github/.wordlist.txt @@ -301,6 +301,7 @@ contrib controllee conv CopperConcentrationMeasurement +Corstone cortexa cp cpio @@ -886,6 +887,7 @@ MyPASSWORD MySSID NAMESERVER NAMESPACE +namespaces namespacing nano natively @@ -1144,11 +1146,13 @@ rsn RSSI RST rsync +RTC rtd RTL rtld RTOS RTT +RTX RUNAS RunMain runtime @@ -1254,6 +1258,7 @@ subdirectory subfolder submodule submodules +subnet subprocess SubscribeResponse SubscriptionId @@ -1326,6 +1331,7 @@ Tizen TKIP tlsr TLV +TLS tmp tngvndl TODO diff --git a/docs/examples/openiotsdk_examples.md b/docs/examples/openiotsdk_examples.md new file mode 100644 index 00000000000000..41e8c88152b7e8 --- /dev/null +++ b/docs/examples/openiotsdk_examples.md @@ -0,0 +1,258 @@ +# 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](../../..//docs/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. + +## 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/openiotsdk_commissioning.md b/docs/guides/openiotsdk_commissioning.md new file mode 100644 index 00000000000000..596184fd27a961 --- /dev/null +++ b/docs/guides/openiotsdk_commissioning.md @@ -0,0 +1,47 @@ +# Commissioning Open IoT SDK devices + +Matter devices based on Open IoT SDK reset into a ready for commissioning state. +This allows a controller to connect to them and set configuration options before +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 + +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. + +## Device commissioning + +Run chip-device-ctrl and use the interactive prompt to commission the device. + +After the device boots, it's in ready for commissioning mode and starts the mDNS +advertisement. This can be discovered by the controller using: + +``` +discover -all +``` + +This will list the devices and their addresses. To commission the device use: + +``` +connect -ip
[] +``` + +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 commands + +If the commissioning process was successful, it is possible to send a ZCL +command to the device which initiates a certain action. + +`zcl [arguments]` + +Example: + + chip-device-ctrl > zcl LevelControl MoveWithOnOff 12344321 1 0 moveMode=1 rate=2 diff --git a/docs/guides/openiotsdk_platform_overview.md b/docs/guides/openiotsdk_platform_overview.md new file mode 100644 index 00000000000000..2c4d04754dcc4a --- /dev/null +++ b/docs/guides/openiotsdk_platform_overview.md @@ -0,0 +1,95 @@ +# Open IoT SDK platform port + +This platform is based on +[Open IoT SDK](https://gitlab.arm.com/iot/open-iot-sdk). Open IoT SDK is a +reference implementation of [Open-CMSIS-CDI](https://www.open-cmsis-cdi.org/) +which defines a common device interface for microcontroller-based devices used +in the Internet of Things. It is delivered as a framework of software components +with a set of feature-rich example applications. + +## Building + +Open IoT SDK uses CMake as its build system. To integrate with Matter's GN build +system our top level CMakeLists.txt generates GN configuration files that pass +on the required configs required by the GN build. + +## Targets + +Supported targets are the ones supported by the Open IoT SDK. Currently it ships +with support for +[Corstone-300](https://developer.arm.com/Processors/Corstone-300) and +[Corstone-310](https://developer.arm.com/Processors/Corstone-310). This platform +makes no assumption on the target and will support any targets added to Open IoT +SDK. + +## Fast model network + +The fast models of supported platforms have two network modes: + +- user mode networking - emulates a built-in IP router and DHCP server, and + routes TCP and UDP traffic between the guest and host. It uses the user mode + socket layer of the host to communicate with other hosts. See more details: + [User mode networking](https://developer.arm.com/documentation/100964/1116/Introduction-to-the-Fast-Models-Reference-Manual/User-mode-networking) + +- TAP/TUN networking mode - set fast model to host bridge component which acts + as a networking gateway to exchange Ethernet packets with the TAP device on + the host, and to forward packets to model. See more details + [TAP/TUN networking mode](https://developer.arm.com/documentation/100964/1116/Introduction-to-the-Fast-Models-Reference-Manual/TAP-TUN-networking) + +Due the user mode limitations, the **TAP/TUN networking mode** is preferred for +implementing IP communication for a Matter project. + +## RTOS + +Open IoT SDK uses +[CMSIS-RTOS2 API](https://www.keil.com/pack/doc/cmsis/RTOS2/html/group__CMSIS__RTOS.html) +as its RTOS API. It offers the choice of implementation between FreeRTOS or +CMSIS RTX but this is hidden below the API so your choice has no bearing on this +port and indeed your application may provide your own implementation entirely. + +## Connectivity + +The platform currently only offers connectivity through the Ethernet interface. +This is limited by current support for network interfaces in Open IoT SDK. + +This means that commissioning is simplified since no provisioning is required to +provide the device with network credentials. + +LWIP is used in the implementation of endpoints as the IP stack. LWIP library is +provided through the Open IoT SDK. + +## Mbed TLS + +Mbed TLS is provided through the Open IoT SDK, the Matter version is not used. +Configuration of Mbed TLS is in +[config/openiotsdk/mbedtls](../../config/openiotsdk/mbedtls). + +## Storage + +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. + +--- + +**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. + +--- + +## Clocks + +Open IoT SDK does not currently offer an RTC. Matter configuration has been set +accordingly and real time cannot be read from the system. + +Monotonic clocks are available and are based on system tick count. They are +limited by the target configuration. The current targets set the tick to 1 ms. +This becomes the lower bound for timers. + +## Drivers + +Drivers are provided by +[Reference MCU-Driver-HAL driver implementation for Arm platforms](https://gitlab.arm.com/iot/open-iot-sdk/mcu-driver-hal/mcu-driver-reference-platforms-for-arm) +which is provided by Open IoT SDK. diff --git a/examples/lock-app/openiotsdk/README.md b/examples/lock-app/openiotsdk/README.md new file mode 100644 index 00000000000000..4ff38ecc3a1445 --- /dev/null +++ b/examples/lock-app/openiotsdk/README.md @@ -0,0 +1,54 @@ +# Matter Open IoT SDK Lock-App Example Application + +The Open IoT SDK Lock Example demonstrates how to remotely control a door lock a +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 + +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). + +The example name to use in the scripts is `lock-app`. + +## Using the example + +Communication with the application goes through the active telnet session. When +the application runs these lines should be visible: + +``` +[INF] [-] Open IoT SDK lock-app example application start +... +[INF] [-] Open IoT SDK lock-app example application run +``` + +The lock-app application launched correctly and you can follow traces in the +terminal. + +### Commissioning + +Read the +[Open IoT SDK commissioning guide](../../../docs/guides/openiotsdk_commissioning.md) +to see how to use the Matter controller to commission and control the +application. + +### DoorLock cluster usage + +The application fully supports the DoorLock cluster. Use its commands to trigger +actions on the device. You can issue commands through the same Matter controller +you used to perform the commissioning step above. + +Example command: + +``` +zcl DoorLock LockDoor 1234 1 pinCode=str:12345 +``` + +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] +``` diff --git a/examples/shell/openiotsdk/README.md b/examples/shell/openiotsdk/README.md new file mode 100644 index 00000000000000..5307edf1f86cd2 --- /dev/null +++ b/examples/shell/openiotsdk/README.md @@ -0,0 +1,45 @@ +# Matter Open IoT SDK Shell Example Application + +The example exposes configuration and management APIs via a command line +interface. It parses a command line and calls the corresponding service +execution. There is a set of common shell commands which perform basic device +operations. + +For more details see +[Common shell commands](../README.md#chip-shell-command-details). + +## Build and run + +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). + +The example name to use in the scripts is `shell`. + +## Using the example + +Communication with the application goes through the active telnet session. When +the application runs these lines should be visible: + +``` +[INF] [SH] Open IoT SDK shell example application start +[INF] [SH] Open IoT SDK shell example application run +> +``` + +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 +functionalities of the device. + +For more details read: +[Common shell commands](../README.md#chip-shell-command-details) + +Example: + +``` +> echo Hello +Hello +Done +```