Restyle [Mbed] Mbed platform documentation

docs/guides/mbedos_add_new_target.md

@@ -0,0 +1,115 @@
+<p align="center">
+ <img src="https://raw.githubusercontent.com/ARMmbed/mbed-os/master/logo.png" alt="ARM Mbed-OS logo"/>
+</p>
+
+<h1> Mbed-OS add new hardware target </h1>
+
+# Overview
+
+This document shows how to add the new Mbed OS hardware target to Matter
+project.
+
+Please check the list of supported
+[development boards](https://os.mbed.com/platforms/) which are compatible with
+Mbed OS.
+
+In order to adapt the new hardware target to the Matter project, you need to
+remember about the following requirements:
+
+- Bluetooth Low Energy support.
+- Wireless communication module with WiFi or Thread network support (IPv6
+ protocol is required).
+- Serial port support
+- On-chip debug with OpenOCD support
+
+Additional target component requirements are different for each of example
+application. Check the **Device UI** paragraph in example description.
+
+# Example Application
+
+The first step to add the new target to each of example application is to modify
+the `examples/example_name/mbed/mbed_app.json` file. It contains the common
+project settings and override the default values for supported boards. You
+should add the necessary components and parameters for the target there.
+
+If the new target uses the external libraries, it will be required to link it in
+the CMakeLists.txt file.
+
+# Building
+
+To add the new hardware target to the build system the
+`scripts/examples/mbed_example.sh` script should be modify. Extend
+**SUPPORTED_TARGET_BOARD** variable with a new target name.
+
+Example:
+
+ SUPPORTED_TARGET_BOARD=(CY8CPROTO_062_4343W NEW_TARGET_NAME)
+
+The next step is add the target name to build task in `.vscode/task.json` file.
+Extend the **options** variable in **mbedTarget** input setting.
+
+Example:
+
+ {
+ "type": "pickString",
+ "id": "mbedTarget",
+ "description": "What mbed target do you want to use?",
+ "options": ["CY8CPROTO_062_4343W", "NEW_TARGET_NAME"],
+ "default": "CY8CPROTO_062_4343W"
+ }
+
+# Flashing
+
+Mbed OS example application flashing process uses the
+[Open On-Chip Debugger](http://openocd.org/). The first step is to create the
+target configuration file inside `config/mbed/scripts` directory. The file name
+should be the same as target and the extension should be **.tcl**. The target
+CPU and programming interface definitions are essential parts of the
+configuration file.
+
+The next steps are the same as for building process. Adding the name of the
+target to `scripts/examples/mbed_example.sh` and `.vscode/task.json` files
+allows the use of available flashing processes.
+
+Additional flashing option is based on VSCode launch task. Adding the new target
+to it required `.vscode/launch.json` modification. Extend the **options**
+variable in **mbedTarget** input setting.
+
+Example:
+
+ {
+ "type": "pickString",
+ "id": "mbedTarget",
+ "description": "What mbed target do you want to use?",
+ "options": ["CY8CPROTO_062_4343W", "NEW_TARGET_NAME"],
+ "default": "CY8CPROTO_062_4343W"
+ }
+
+# Debugging
+
+Debugging process of Mbed OS applications is also based on VSCode launch task.
+Adding the new target to it required `.vscode/launch.json` modification. Extend
+the **options** variable in **mbedTarget** input setting.
+
+Example:
+
+ {
+ "type": "pickString",
+ "id": "mbedTarget",
+ "description": "What mbed target do you want to use?",
+ "options": ["CY8CPROTO_062_4343W", "NEW_TARGET_NAME"],
+ "default": "CY8CPROTO_062_4343W"
+ }
+
+# CI
+
+The Matter project continue integration process is based on Github Actions tool.
+It uses workflow configuration files to execute actions on CI server.
+
+To add the new target to the validation process of building Mbed OS applications
+you need to modify the `.gtihub/workflows.examples-mbed.yaml` file. Extend the
+job's environment variable **APP_TARGET** with the target name.
+
+Example:
+
+ APP_TARGET: [CY8CPROTO_062_4343W, NEW_TARGET_NAME]

docs/guides/mbedos_commissioning.md

@@ -0,0 +1,276 @@
+<p align="center">
+ <img src="https://raw.githubusercontent.com/ARMmbed/mbed-os/master/logo.png" alt="ARM Mbed-OS logo"/>
+</p>
+
+<h1> Matter Arm Mbed OS provisioning guide </h1>
+
+- [Overview](#overview)
+- [Prerequisites](#prerequisites)
+- [CHIPTool for Android](#chiptool-for-android)
+ - [Building and installing](#building-and-installing)
+ - [Accessory Matter device setup](#accessory-matter-device-setup)
+ - [Device commisioning for Android](#device-commisioning-for-android)
+ - [Sending ZCL commands](#sending-zcl-commands)
+- [POSIX CLI CHIPTool](#posix-cli-chiptool)
+ - [Building](#building)
+ - [Device commisioning for CLI](#device-commisioning-for-cli)
+ - [Sending ZCL commands](#sending-zcl-commands-1)
+- [Python Device Controller](#python-device-controller)
+ - [Building and installing](#building-and-installing-1)
+ - [Device commisioning for Python Device Controller](#device-commisioning-for-python-device-controller)
+ - [Sending ZCL commands](#sending-zcl-commands-2)
+ - [ZCL commands details](#zcl-commands-details)
+
+<hr>
+
+# Overview
+
+This document provides a step-by-step guide how to commission any Matter
+application. For demonstration purposes the Lighting app is used.
+
+The provisioning process is composed of the following stages:
+
+- CHIPTool discovers a Matter accessory device over Bluetooth Low Energy
+ (BLE).
+
+- CHIPTool establishes a secure channel to the device over BLE, and sends
+ network credentials data.
+
+BLE is only used during first phase. Afterwards, only the IP connectivity
+between the smartphone and the accessory device is needed to send messages.
+
+# Prerequisites
+
+To complete all the steps in the tutorial, you need:
+
+- A smartphone with Android 8+ or PC with Ubuntu 20.04 and Bluetooth
+ connectivity
+
+- A WiFi Access Point (smartphone router, standalone AP, wireless router or
+ PC)
+
+- Any currently supported target device (for example, a Cypress PSoC6
+ CY8CPROTO-062-4343W board)
+
+# CHIPTool for Android
+
+## Building and installing
+
+To make provisioning possible and to control the Matter device from your Android
+based smartphone, you must first build and install the CHIPTool application.
+
+To build the CHIPTool application for your smartphone, read
+[Android building guide](android_building.md).
+
+After building, install the application by completing the following steps:
+
+1. Install the Android Debug Bridge (adb) package by running the following
+ command:
+
+ $ sudo apt install android-tools-adb
+
+2. Enable **USB debugging** on your smartphone. See the
+ [Configure on-device developer options](https://developer.android.com/studio/debug/dev-options)
+ guide on the Android Studio hub for detailed information.
+3. If the **Install via USB** option is supported for your Android version,
+ turn it on.
+4. Plug your smartphone into a USB port on your PC.
+5. Run the following command to install the application, with _matter-dir_
+ replaced with the path to the Matter source directory:
+
+ $ adb install out/android-$TARGET_CPU-chip-tool/outputs/apk/debug/app-debug.apk
+
+6. Navigate to settings on your smartphone and grant **Camera** and
+ **Location** permissions to CHIPTool.
+
+Android CHIPTool is now ready to be used for commissioning.
+
+## Accessory Matter device setup
+
+To prepare the accessory Matter device for commissioning (called rendezvous),
+complete the following steps:
+
+- Open a serial terminal session to connect to the UART console of the
+ accessory 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
+
+To start the rendezvous, CHIPTool must get the commissioning information from
+the Matter device. The data payload is encoded within a QR code and is printed
+to the UART console.
+
+- Reset the device.
+
+- Find a message similar to the following one in the application logs:
+
+ [INFO][CHIP]: [SVR]Copy/paste the below URL in a browser to see the QR Code:
+ [INFO][CHIP]: [SVR]https://dhrishi.github.io/connectedhomeip/qrcode.html?data=MT%3AYNJV7VSC00CMVH7SR00
+
+- Open URL from the console to display the QR in a web browser.
+
+## Device commisioning for Android
+
+To commission Matter device onto the network created complete the following
+steps:
+
+- Enable Bluetooth and Location services on your smartphone.
+
+- Connect the smartphone to the WiFi Network
+
+- Open the CHIPTool application on your smartphone.
+
+- Tap the 'PROVISION CHIP DEVICE WITH WI-FI' button and scan the commissioning
+ QR code.
+
+- Go through the the paring and connecting Bluetooth on your smartphone (you
+ will see a few pop-up messages appear as the commissioning progresses.
+ Finally, the network settings screen appears.
+
+- In the network setitngs screen enter the Wi-Fi credentials and tap the Save
+ Network button to send a WiFi provisioning message to the accessory device.
+
+- After successful completion of the process, the application returns to the
+ main screen.
+
+## Sending ZCL commands
+
+After the accessory device has been successfully commissioned to the network, it
+is possible to communicate with it using IP. Matter uses Zigbee Cluster Library
+(ZCL) protocol which defines common means for applications to communicate.
+
+Communication with the device via ZCL commands is possible by using buttons of
+the main screen.
+
+For example, selecting the 'LIGHT ON/OFF & LEVEL CLUSTER' button opens the
+screen which allows controlling the light dimming. Tap either the ON or the OFF
+button to toggle between min and max brightness. Use the slider to modify the
+brightness between 0-255.
+
+If **Lighting LED** is available then brightness change can be observed.
+
+> For more details about Android CHIPTool please visit
+> [CHIPTool](../../src/android/CHIPTool/README.md)
+
+# POSIX CLI CHIPTool
+
+## Building
+
+To make provisioning possible and to control the Matter device from Linux-based
+device, you can build and run the Matter Client example application on it.
+
+To build the POSIX CLI CHIPTool application check the guide
+[POSIX CLI guide](../../examples/chip-tool/README.md).
+
+## Device commisioning for CLI
+
+In order to send commands to a device, it must be paired with the client and
+connected to the network.
+
+To run the commisioning process via BLE, run the built executable and pass it
+the network ssid and password, fabric id, discriminator and pairing code of the
+remote device.
+
+Example:
+
+ $ chip-tool pairing ble-wifi network_ssid network_password 0 20202021 3840
+
+## Sending ZCL commands
+
+If the commissioning process was successful, it is possible to send a ZCL
+command to the device which initiate a certain action.
+
+To send a ZCL commands, run the executable and pass it the target cluster name,
+the target command name as well as an endpoint id.
+
+The endpoint id must be between 1 and 240.
+
+For example:
+
+ $ chip-tool onoff on 1
+
+The client will send a single command packet and then exit.
+
+> For more details about POSIX CLI CHIPTool please visit
+> [POSIX CLI CHIPTool](../../examples/chip-tool/README.md)
+
+# Python Device Controller
+
+## Building and installing
+
+To make provisioning possible and to control the Matter device with Python
+application, you can build and run the Python CHIP controller.
+
+To build and install the Python Device Controller application check the guide
+[Python Device Controller guide](python_chip_controller_building.md).
+
+## Device commisioning for Python Device Controller
+
+In order to send commands to a device, it must be paired with the client and
+connected to the network.
+
+To run the commisioning process via BLE:
+
+- Run Device Controller:
+
+ chip-device-ctrl
+
+- Scan BLE devices:
+
+ chip-device-ctrl > ble-scan
+
+- Connect the device via BLE (provide the accessory device discriminator,
+ setup pin code and node ID):
+
+ chip-device-ctrl > connect -ble 3840 20202021 1234
+
+- Pass the Wi-Fi credentials to the device:
+
+ chip-device-ctrl > zcl NetworkCommissioning AddWiFiNetwork 1234 0 0 ssid=str:TESTSSID credentials=str:P455W4RD breadcrumb=0 timeoutMs=1000
+
+- Enable the Wi-Fi interface:
+
+ chip-device-ctrl > zcl NetworkCommissioning EnableNetwork 1234 0 0 networkID=str:TESTSSID breadcrumb=0 timeoutMs=1000
+
+- Close BLE connectino:
+
+ chip-device-ctrl > zcl NetworkCommissioning EnableNetwork 1234 0 0 networkID=str:TESTSSID breadcrumb=0 timeoutMs=1000
+
+- Discover IP address of the device (address is cached in the controller for
+ later usage). You should provide the fabric and node ID:
+
+ chip-device-ctrl > resolve 5544332211 1234
+
+## 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 <Cluster> <Command> <NodeId> <EndpointId> <GroupId> [arguments]`
+
+Example:
+
+ chip-device-ctrl > zcl LevelControl MoveWithOnOff 12344321 1 0 moveMode=1 rate=2
+
+### ZCL commands details
+
+To get the list of supported clusters run:
+
+ chip-device-ctrl > zcl ?
+
+To get the list of available commands in cluster run:
+
+ chip-device-ctrl > zcl ? <Cluster>
+
+**Format of arguments**
+
+For any integer and char string (null terminated) types, just use `key=value`,
+for example: `rate=2`, `string=123`, `string_2="123 456"`
+
+For byte string type, use `key=encoding:value`, currectly, we support `str` and
+`hex` encoding, the `str` encoding will encode a NULL terminated string. For
+example, `networkId=hex:0123456789abcdef` (for
+`[0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef]`), `ssid=str:Test` (for
+`['T', 'e', 's', 't', 0x00]`).
+
+For boolean type, use `key=True` or `key=False`