![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.

<hr>

-   [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)

<hr>

## 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=<board name> -p=<build profile> -T=<build type>
```

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=<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](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<br> Semiconductor](https://www.cypress.com/) | [CY8CPROTO-062-4343W](https://os.mbed.com/platforms/CY8CPROTO-062-4343W/) | `CY8CPROTO_062_4343W` | <details><summary>CY8CPROTO-062-4343W</summary><img src="https://os.mbed.com/media/cache/platforms/p6_wifi-bt_proto.png.250x250_q85.jpg" alt="CY8CPROTO-062-4343W"/></details> |   ✔    | <details><summary>LEDs</summary><ul><li>Unused</li></ul></details> <details><summary>Buttons</summary><ul><li>Unused</li></ul></details> <details><summary>Slider</summary><ul><li>Unused</li></ul></details> |

##### Notes

-   More details and guidelines about porting new hardware into the Matter
    project with Mbed OS can be found in
    [MbedNewTarget](../../../docs/guides/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)