diff --git a/silabs_examples/sl-newLight/efr32/README.md b/silabs_examples/sl-newLight/efr32/README.md index f2fc205daae3f5..b954f60995634d 100644 --- a/silabs_examples/sl-newLight/efr32/README.md +++ b/silabs_examples/sl-newLight/efr32/README.md @@ -1,420 +1,122 @@ -#Matter EFR32 Template Example +# Matter EFR32 Colored Lighting Application -An example template. +A lighting app with color control and level control.
-// TODO UPDATE ME - -- [CHIP EFR32 Lighting Example](#chip-efr32-lighting-example) +- [Matter EFR32 Colored Lighting Application](#matter-EFR32-colored-lighting-application) - [Introduction](#introduction) - - [Building](#building) - - [Note](#note) - - [Flashing the Application](#flashing-the-application) - - [Viewing Logging Output](#viewing-logging-output) - - [Running the Complete Example](#running-the-complete-example) - - [Notes](#notes) - - [Running RPC console](#running-rpc-console) - - [Device Tracing](#device-tracing) - - [Memory settings](#memory-settings) - - [OTA Software Update](#ota-software-update) + - [Running the application](#running-the-application) + - [Material](#material) + - [Compiling](#compiling) + - [Building and flashing the example](#building-and-flashing-the-example) + - [Monitoring the app](#monitoring-the-app) + - [Interacting with the app](#interacting-with-the-app)
- - ## Introduction -The EFR32 lighting example provides a baseline demonstration of a Light control -device, built using CHIP and the Silicon Labs gecko SDK. It can be controlled by -a Chip controller over Openthread network.. - -The EFR32 device can be commissioned over Bluetooth Low Energy where the device -and the Chip controller will exchange security information with the Rendez-vous -procedure. Thread Network credentials are then provided to the EFR32 device -which will then join the network. - -The LCD on the Silabs WSTK shows a QR Code containing the needed commissioning -information for the BLE connection and starting the Rendez-vous procedure. - -The lighting example is intended to serve both as a means to explore the -workings of CHIP as well as a template for creating real products based on the -Silicon Labs platform. - - - -## Building - -- Download the - [Simplicity Commander](https://www.silabs.com/mcu/programming-options) - command line tool, and ensure that `commander` is your shell search path. - (For Mac OS X, `commander` is located inside - `Commander.app/Contents/MacOS/`.) - -- Download and install a suitable ARM gcc tool chain: - [GNU Arm Embedded Toolchain 9-2019-q4-major](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads) - -- Install some additional tools(likely already present for CHIP developers): - -#Linux `sudo apt-get install git libwebkitgtk-1.0-0 ninja-build` - -#Mac OS X `brew install ninja` - -- Supported hardware: - - MG12 boards: - - - BRD4161A / SLWSTK6000B / Wireless Starter Kit / 2.4GHz@19dBm - - BRD4164A / SLWSTK6000B / Wireless Starter Kit / 2.4GHz@19dBm - - BRD4166A / SLTB004A / Thunderboard Sense 2 / 2.4GHz@10dBm - - BRD4170A / SLWSTK6000B / Multiband Wireless Starter Kit / 2.4GHz@19dBm, - 915MHz@19dBm - - BRD4304A / SLWSTK6000B / MGM12P Module / 2.4GHz@19dBm - - MG21 boards: Currently not supported due to RAM limitation. - - - BRD4180A / SLWSTK6006A / Wireless Starter Kit / 2.4GHz@20dBm - - MG24 boards : - - - BRD4186A / SLWSTK6006A / Wireless Starter Kit / 2.4GHz@10dBm - - BRD4187A / SLWSTK6006A / Wireless Starter Kit / 2.4GHz@20dBm - -* Build the example application: - - ``` - cd ~/connectedhomeip - ./scripts/examples/gn_efr32_example.sh ./SILABS_examples/template/efr32/ ./out/template BRD4161A - ``` - -- To delete generated executable, libraries and object files use: - - ``` - $ cd ~/connectedhomeip - $ rm -rf ./out/ - ``` - - OR use GN/Ninja directly - - ``` - $ cd ~/connectedhomeip/SILABS_examples/template/efr32 - $ git submodule update --init - $ source third_party/connectedhomeip/scripts/activate.sh - $ export EFR32_BOARD=BRD4161A - $ gn gen out/debug - $ ninja -C out/debug - ``` - -- To delete generated executable, libraries and object files use: - - ``` - $ cd ~/connectedhomeip/SILABS_examples/template/efr32 - $ rm -rf out/ - ``` - -* Build the example as Sleepy End Device (SED) - - ``` - $ ./scripts/examples/gn_efr32_example.sh ./SILABS_examples/template/efr32/ ./out/template_SED BRD4161A --sed - ``` - - or use gn as previously mentioned but adding the following arguments: - - ``` - $ gn gen out/debug '--args=efr32_board="BRD4161A" enable_sleepy_device=true chip_openthread_ftd=false' - ``` - -* Build the example with pigweed RPC - - ``` - $ ./scripts/examples/gn_efr32_example.sh SILABS_examples/template/efr32/ out/template_app_rpc BRD4161A 'import("//with_pw_rpc.gni")' - ``` - - or use GN/Ninja Directly - - ``` - $ cd ~/connectedhomeip/SILABS_examples/template/efr32 - $ git submodule update --init - $ source third_party/connectedhomeip/scripts/activate.sh - $ export EFR32_BOARD=BRD4161A - $ gn gen out/debug --args='import("//with_pw_rpc.gni")' - $ ninja -C out/debug - ``` - - [Running Pigweed RPC console](#running-pigweed-rpc-console) - -For more build options, help is provided when running the build script without -arguments - - ``` - ./scripts/examples/gn_efr32_example.sh - ``` - - - -## Flashing the Application - -- On the command line: - - ``` - $ cd ~/connectedhomeip/SILABS_examples/template/efr32 - $ python3 out/debug/chip-efr32-lighting-example.flash.py - ``` - -- Or with the Ozone debugger, just load the .out file. - - - -## Viewing Logging Output - -The example application is built to use the SEGGER Real Time Transfer (RTT) -facility for log output. RTT is a feature built-in to the J-Link Interface MCU -on the WSTK development board. It allows bi-directional communication with an -embedded application without the need for a dedicated UART. - -Using the RTT facility requires downloading and installing the _SEGGER J-Link -Software and Documentation Pack_ -([web site](https://www.segger.com/downloads/jlink#J-LinkSoftwareAndDocumentationPack)). - -Alternatively, SEGGER Ozone J-Link debugger can be used to view RTT logs too -after flashing the .out file. - -- Download the J-Link installer by navigating to the appropriate URL and - agreeing to the license agreement. - -- [JLink_Linux_x86_64.deb](https://www.segger.com/downloads/jlink/JLink_Linux_x86_64.deb) -- [JLink_MacOSX.pkg](https://www.segger.com/downloads/jlink/JLink_MacOSX.pkg) - -* Install the J-Link software +This is a lighting application implementing Level Control and Color Control. It +allows to control the color and the intensity of an RGB LED. - ``` - $ cd ~/Downloads - $ sudo dpkg -i JLink_Linux_V*_x86_64.deb - ``` +First time using a Matter and/or EFR32 application ? Check out [The Glorious +Guide for running the BASIC Lighting App][1] for detailed information about +Building and Flashing an EFR32 application. -* In Linux, grant the logged in user the ability to talk to the development - hardware via the linux tty device (/dev/ttyACMx) by adding them to the - dialout group. +## Running the application - ``` - $ sudo usermod -a -G dialout ${USER} - ``` +In addition to the steps in [The Glorious Guide][1], here is some relevant +information to help you run Color-Light app. -Once the above is complete, log output can be viewed using the JLinkExe tool in -combination with JLinkRTTClient as follows: +### Material -- Run the JLinkExe tool with arguments to autoconnect to the WSTK board: +To set up this application, you will need: - For MG12 use: +- 1 Thunderboard Sense 2 (BRD4166A). +- 1 OT-BR running on Raspberry Pi (including its own RCP). - ``` - $ JLinkExe -device EFR32MG12PXXXF1024 -if JTAG -speed 4000 -autoconnect 1 - ``` +_This application was tested to run on a ThunderBoard Sense 2. Since this +application uses RGB Leds, level control and color control are disabled on most +boards that are not BRD4166A._ - For MG21 use: +### Compiling - ``` - $ JLinkExe -device EFR32MG21AXXXF1024 -if SWD -speed 4000 -autoconnect 1 - ``` +Follow the steps below to compile successfully Color-Light app. -- In a second terminal, run the JLinkRTTClient to view logs: +Note: You will need GSDK with version 4.1.1 or later to run this application. - ``` - $ JLinkRTTClient - ``` +#### Building and flashing the example - +**Important:** If you have followed correctly the steps in [The Glorious +Guide][1], you should now have your own way of building and flashing a Matter +EFR32 app. However, for reference, I put here the instructions that I execute in +the terminal to build Color-Light app, whenever I start from a _new, freshly +opened_ terminal. -## Running the Complete Example +1. After opening a new terminal, execute the following commands to build and + flash Color-Light app on MacBook: -- It is assumed here that you already have an OpenThread border router - configured and running. If not see the following guide - [Openthread_border_router](https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/openthread_border_router_pi.md) - for more information on how to setup a border router on a raspberryPi. + ```Bash + # Note: Starting in the root directory (i.e: "connectedhomeip/"). + # One time instructions: + export PATH="$PATH:/Applications/Commander.app/Contents/MacOS/" + export EFR32_BOARD=BRD4166A + source scripts/activate.sh + cd silabs_examples/sl-newLight/efr32 - Take note that the RCP code is available directly through - [Simplicity Studio 5](https://www.silabs.com/products/development-tools/software/simplicity-studio/simplicity-studio-5) - under File->New->Project Wizard->Examples->Thread : ot-rcp + # Excecute the following instructions everytime you need to build. + rm -rf out + gn gen out/debug + ninja -C out/debug -- User interface : **LCD** The LCD on Silabs WSTK shows a QR Code. This QR - Code is be scanned by the CHIP Tool app For the Rendez-vous procedure over - BLE - - * On devices that do not have or support the LCD Display like the BRD4166A Thunderboard Sense 2, - a URL can be found in the RTT logs. - - [SVR] Copy/paste the below URL in a browser to see the QR Code: - [SVR] https://dhrishi.github.io/connectedhomeip/qrcode.html?data=CH%3AI34NM%20-00%200C9SS0 - - **LED 0** shows the overall state of the device and its connectivity. The - following states are possible: - - - _Short Flash On (50 ms on/950 ms off)_ ; The device is in the - unprovisioned (unpaired) state and is waiting for a commissioning - application to connect. - - - _Rapid Even Flashing_ ; (100 ms on/100 ms off)_ — The device is in the - unprovisioned state and a commissioning application is connected through - Bluetooth LE. - - - _Short Flash Off_ ; (950ms on/50ms off)_ — The device is fully - provisioned, but does not yet have full Thread network or service - connectivity. - - - _Solid On_ ; The device is fully provisioned and has full Thread - network and service connectivity. - - **LED 1** Simulates the Light The following states are possible: - - - _Solid On_ ; Light is on - - _Off_ ; Light is off - - **Push Button 0** - - - _Press and Release_ : Start, or restart, BLE advertisement in fast mode. It will advertise in this mode - for 30 seconds. The device will then switch to a slower interval advertisement. - After 15 minutes, the advertisement stops. - - - _Pressed and hold for 6 s_ : Initiates the factory reset of the device. - Releasing the button within the 6-second window cancels the factory reset - procedure. **LEDs** blink in unison when the factory reset procedure is - initiated. - - **Push Button 1** Toggles the light state On/Off - -* You can provision and control the Chip device using the python controller, - Chip tool standalone, Android or iOS app - -* You can provision and control the Chip device using the python controller, - Chip tool standalone, Android or iOS app - - [CHIPTool](https://github.com/project-chip/connectedhomeip/blob/master/examples/chip-tool/README.md) - - Here is an example with the CHIPTool: - - ``` - chip-tool pairing ble-thread 1 hex: 20202021 3840 - - chip-tool onoff on 1 1 + # Execute this instruction to flash. + python3 out/debug/chip-efr32-lighting-example.flash.py ``` -### Notes - -- Depending on your network settings your router might not provide native ipv6 - addresses to your devices (Border router / PC). If this is the case, you - need to add a static ipv6 addresses on both device and then an ipv6 route to - the border router on your PC - -#On Border Router: `sudo ip addr add dev 2002::2/64` - -#On PC(Linux): `sudo ip addr add dev 2002::1/64` - -#Add Ipv6 route on PC(Linux) -`sudo ip route add /64 via 2002::2` - - - -## Running RPC console +### Monitoring the app -- As part of building the example with RPCs enabled the chip_rpc python - interactive console is installed into your venv. The python wheel files are - also created in the output folder: out/debug/chip_rpc_console_wheels. To - install the wheel files without rebuilding: - `pip3 install out/debug/chip_rpc_console_wheels/*.whl` +You can monitor the EFR32 running the Color-Light app by using JLinkRTTViewer. +For more information, refer to [The Glorious Guide][1]. -- To use the chip-rpc console after it has been installed run: - `chip-console --device /dev/tty. -b 115200 -o //pw_log.out` +### Interacting with the app -- Then you can simulate a button press or release using the following command - where : idx = 0 or 1 for Button PB0 or PB1 action = 0 for PRESSED, 1 for - RELEASE Test toggling the LED with - `rpcs.chip.rpc.Button.Event(idx=1, pushed=True)` +In order to send commands to the Color-Light app, you will need an OTBR +(OpenThread Border Router). Note that the following commands work only if you +are using "Silabs Matter Raspberry Pi Image" as an OTBR. -- You can also Get and Set the light directly using the RPCs: - `rpcs.chip.rpc.Lighting.Get()` +2. Once your OTBR is set up, run the following commands to establish + communication with the device running Color-Light and to send commands to it: - `rpcs.chip.rpc.Lighting.Set(on=True, level=128, color=protos.chip.rpc.LightingColor(hue=5, saturation=5))` + ```Bash + # These commands are executed once, everytime you power on your Raspberry Pi. + mattertool startThread + mattertool bleThread -## Device Tracing + # Commands to turn On/Off the light. + mattertool on + mattertool off -Device tracing is available to analyze the device performance. To turn on -tracing, build with RPC enabled. See Build the example with pigweed RPC. + # You need to know the Node ID, do it by executing the following command: + mattertool -h + # The node ID will now be displayed, take note of it. -Obtain tracing json file. + # Command to set the level of the light. + mattertool levelcontrol move-to-level {desired_level} 0 1 1 {node_ID} 1 -``` - $ ./{PIGWEED_REPO}/pw_trace_tokenized/py/pw_trace_tokenized/get_trace.py -d {PORT} -o {OUTPUT_FILE} \ - -t {ELF_FILE} {PIGWEED_REPO}/pw_trace_tokenized/pw_trace_protos/trace_rpc.proto -``` - -## Memory settings - -While most of the RAM usage in CHIP is static, allowing easier debugging and -optimization with symbols analysis, we still need some HEAP for the crypto and -OpenThread. Size of the HEAP can be modified by changing the value of the -`configTOTAL_HEAP_SIZE` define inside of the FreeRTOSConfig.h file of this -example. Please take note that a HEAP size smaller than 13k can and will cause a -Mbedtls failure during the BLE rendez-vous or CASE session - -To track memory usage you can set `enable_heap_monitoring = true` either in the -BUILD.gn file or pass it as a build argument to gn. This will print on the RTT -console the RAM usage of each individual task and the number of Memory -allocation and Free. While this is not extensive monitoring you're welcome to -modify `examples/platform/efr32/MemMonitoring.cpp` to add your own memory -tracking code inside the `trackAlloc` and `trackFree` function - -## OTA Software Update - -For the description of Software Update process with EFR32 example applications -see -[EFR32 OTA Software Update](../../../docs/guides/silabs_efr32_software_update.md) - -## Group Communication (Multicast) - -With this lighting example you can also use group communication to send Lighting -commands to multiples devices at once. Please refer to the -[chip-tool documentation](../../chip-tool/README.md) _Configuring the server -side for Group Commands_ and _Using the Client to Send Group (Multicast) Matter -Commands_ - -## Building options - -All of Silabs's examples within the Matter repo have all the features enabled by -default, as to provide the best end user experience. However some of those -features can easily be toggled on or off. Here is a short list of options to be -passed to the build scripts. - -### Disabling logging - -`chip_progress_logging, chip_detail_logging, chip_automation_logging` - - ``` - $ ./scripts/examples/gn_efr32_example.sh ./SILABS_examples/template/efr32 ./out/template BRD4164A "chip_detail_logging=false chip_automation_logging=false chip_progress_logging=false" + # Command to set the color of the light. + # First Set the Saturation. + mattertool colorcontrol move-to-saturation {desired_saturation} 0 1 1 {node_ID} 1 + # Now Set the Hue. + mattertool colorcontrol move-to-hue {desired_hue} 0 0 1 1 {node_ID} 1 ``` -### Debug build / release build +If you don't know what values of Hue and Saturation you need, look-up "HSV to +RGB color conversion" online. Note that "Value" is **always** 100%. -`is_debug` +For more information about levelcontrol and colorcontrol commands, please refer +to "appclusters.pdf" Section 1.6. and 3.2., respectively. - ``` - $ ./scripts/examples/gn_efr32_example.sh ./SILABS_examples/template/efr32 ./out/template BRD4164A "is_debug=false" - ``` - -### Disabling LCD - -`show_qr_code` - - ``` - $ ./scripts/examples/gn_efr32_example.sh ./SILABS_examples/template/efr32 ./out/template BRD4164A "show_qr_code=false" - ``` - -### KVS maximum entry count - -`kvs_max_entries` +###### Last modified August 1st, 2022. - ``` - Set the maximum Kvs entries that can be stored in NVM (Default 75) - Thresholds: 30 <= kvs_max_entries <= 255 - - $ ./scripts/examples/gn_efr32_example.sh ./SILABS_examples/template/efr32 ./out/template BRD4164A kvs_max_entries=50 - ``` +[1]: ../../../examples/lighting-app/efr32/README.md