examples/shell/mbed/README.md - third_party/github/project-chip/connectedhomeip - Git at Google

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