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 and Arm Mbed OS, and supports remote access and control of device over serial port.

• Overview
• Run application
  • Environment setup
  • Building
  • Flashing
  • Debugging
  • Testing
    • Serial port terminal
  • Supported devices
    • Notes
• 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 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=<board name> -p=<build profile> -T=<build type>

Both approaches are limited to supported evaluation boards which are listed in Supported devices paragraph.

Mbed OS defines three building profiles: develop, debug and release. For more details please visit ARM Mbed OS build profiles.

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 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=<board name> -p=<build profile>

• 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 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):

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.

Example:

> echo Hello
Hello
Done

Supported devices

The example supports building and running on the following mbed-enabled devices:

Notes

• More details and guidelines about porting new hardware into the Matter project with Mbed OS can be found in MbedNewTarget
• 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)

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