![ARM Mbed-OS logo](https://raw.githubusercontent.com/ARMmbed/mbed-os/master/logo.png) # Matter Arm Mbed OS Shell Example Application The Arm Mbed OS Shell Example exposes configuration and management APIs via a command line interface (CLI). Use the shell CLI to experiment with Matter interactively, which can also be used with additional application code. You can use this example as a reference for creating your own application. The example is based on [Matter](https://github.com/project-chip/connectedhomeip) and Arm Mbed OS, and supports remote access and control of device over serial port.
- [Overview](#overview) - [Run application](#run-application) - [Environment setup](#environment-setup) - [Building](#building) - [Flashing](#flashing) - [Debugging](#debugging) - [Testing](#testing) - [Serial port terminal](#serial-port-terminal) - [Supported devices](#supported-devices) - [Notes](#notes) - [Shell commands](#shell-commands)
## Overview The Matter device that runs the shell application can be controlled over serial port. The shell is used to parse a command line and call the corresponding service execution. There is a set of common shell commands which performs basic device operations. Mbed OS application also supports some custom services and corresponding shell commands allow them execution. ## Run application ### Environment setup Before building the example, check out the Matter repository and sync submodules using the following command: $ git submodule update --init Building the example application requires the use of **ARM Mbed-OS** sources and the **arm-none-gnu-eabi** toolchain. The Cypress OpenOCD package is required for flashing purpose. Install the Cypress OpenOCD and set env var `OPENOCD_PATH` before calling the flashing script. ``` cd ~ wget https://github.com/Infineon/openocd/releases/download/release-v4.3.0/openocd-4.3.0.1746-linux.tar.gz tar xzvf openocd-4.3.0.1746-linux.tar.gz export OPENOCD_PATH=$HOME/openocd ``` Some additional packages may be needed, depending on selected build target and its requirements. > **The VSCode devcontainer has these components pre-installed. Using the VSCode > devcontainer is the recommended way to interact with Arm Mbed-OS port of the > Matter Project.** > > **Please read this [README.md](../../..//docs/VSCODE_DEVELOPMENT.md) for more > information about using VSCode in container.** To initialize the development environment, download all registered sub-modules and activate the environment: ``` $ source ./scripts/bootstrap.sh $ source ./scripts/activate.sh ``` If packages are already installed then you just need to activate the development environment: ``` $ source ./scripts/activate.sh ``` ### Building The shell application can be built in the same way as any other Matter example ported to the mbed-os platform. - **by using generic vscode task**: ``` Command Palette (F1) => Run Task... => Run Mbed Application => build => shell => (board name) => (build profile) => (build type) ``` - **by calling explicitly building script:** ``` ${MATTER_ROOT}/scripts/examples/mbed_example.sh -c=build -a=shell -b= -p= -T= ``` Both approaches are limited to supported evaluation boards which are listed in [Supported devices](#supported-devices) paragraph. Mbed OS defines three building profiles: _develop, debug_ and _release_. For more details please visit [ARM Mbed OS build profiles](https://os.mbed.com/docs/mbed-os/latest/program-setup/build-profiles-and-rules.html). There are also three types of built application: _simple, boot_ and _upgrade_: - **simple** - standalone application, mainly for developing and testing purpose (all building profiles are supported) - **boot** - signed application + bootloader, it supports booting process and can be use for firmware update (only _release_ building profiles is supported) - **update** - signed application, application image can be used for firmware update (only _release_ building profiles is supported) When using the building script, it is possible expand the list of acceptable targets; this may be useful for rapid testing of a new mbed-targets. ### Flashing The shell application can be flashed in the same way as any other Matter example ported to mbed-os platform. The [Open On-Chip Debugger](http://openocd.org/) is used to upload a binary image and reset the device. - **by using VSCode task**: ``` Command Palette (F1) => Run Task... -> Run Mbed Application => flash => shell => (board name) => (build profile) ``` - **by calling explicitly building script:** ``` ${MATTER_ROOT}/scripts/examples/mbed_example.sh -c=flash -a=shell -b= -p= ``` - **by using VSCode launch task**: ``` Run and Debug (Ctrl+Shift+D) => Flash Mbed examples => Start Debugging (F5) => (board name) => shell => (build profile) ``` The last option uses the Open On-Chip Debugger to open and manage the gdb-server session. Then gdb-client (arm-none-eabi-gdb) upload binary image and reset device. It is possible to connect to an external gdb-server session by using specific **'Flash Mbed examples [remote]'** task. ### Debugging Debugging can be performed in the same was as with any other Matter example ported to mbed-os platform. The [Open On-Chip Debugger](http://openocd.org/) is used to to open and manage the gdb-server session. Then gdb-client (arm-none-eabi-gdb) connect the server to upload binary image and control debugging. ``` Run and Debug (Ctrl+Shift+D) => Debug Mbed examples => Start Debugging (F5) => (board name) => shell => (build profile) ``` It is possible to connect to an external gdb-server session by using specific **'Debug Mbed examples [remote]'** task. ### Testing #### Serial port terminal To start communication open a serial terminal session and connect to the serial port of the device. You can use **mbed-tools** for this purpose ([mbed-tools](https://github.com/ARMmbed/mbed-tools)): mbed-tools sterm -p /dev/ttyACM0 -b 115200 -e off After device reset these lines should be visible: [INFO][CHIP]: [-]Mbed shell example application start ... [INFO][CHIP]: [-]Mbed shell example application run The shell application launched correctly. Send commands and wait for the response [Shell commands](#shell-commands). Example: > echo Hello Hello Done ### Supported devices The example supports building and running on the following mbed-enabled devices: | Manufacturer | Hardware platform | Build target | Platform image | Status | Platform components | | ----------------------------------------------------- | ------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Cypress
Semiconductor](https://www.cypress.com/) | [CY8CPROTO-062-4343W](https://os.mbed.com/platforms/CY8CPROTO-062-4343W/) | `CY8CPROTO_062_4343W` |
CY8CPROTO-062-4343WCY8CPROTO-062-4343W
| ✔ |
LEDs
  • Unused
Buttons
  • Unused
Slider
  • Unused
| ##### Notes - More details and guidelines about porting new hardware into the Matter project with Mbed OS can be found in [MbedNewTarget](../../../docs/platforms/mbedos/mbedos_add_new_target.md) - Some useful information about HW platform specific settings can be found in `shell/mbed/mbed_app.json`. Information about this file syntax and its meaning in mbed-os project can be found here: [Mbed-Os configuration system](https://os.mbed.com/docs/mbed-os/latest/program-setup/advanced-configuration.html)) ## Shell commands The application supports common Matter shell commands. They are used to control the basic functionalities of the device. For more details visit: [Common shell commands](../README.md#matter-shell-command-details)