From 10898751b2e2c069569facbf8a1f1a301143e620 Mon Sep 17 00:00:00 2001 From: mkardous-silabs <84793247+mkardous-silabs@users.noreply.github.com> Date: Fri, 5 Jan 2024 20:38:43 -0500 Subject: [PATCH] [Silabs] Adds new Silabs guides (#31261) * Creation of new Silabs documentation * restyle * FIx misspells * fix TOC * restyle table * fix typo * Restyled by prettier-markdown --------- Co-authored-by: Restyled.io --- .github/.wordlist.txt | 19 +- docs/guides/README.md | 5 +- docs/guides/darwin.md | 2 +- docs/guides/images/silabs_logo.png | Bin 0 -> 4619 bytes docs/guides/index.md | 5 +- docs/guides/silabs_cli_guide.md | 232 +++++++++++++++++++ docs/guides/silabs_common_app_behavior.md | 141 ++++++++++++ docs/guides/silabs_efr32_building.md | 30 --- docs/guides/silabs_getting_started.md | 267 ++++++++++++++++++++++ 9 files changed, 661 insertions(+), 40 deletions(-) create mode 100644 docs/guides/images/silabs_logo.png create mode 100644 docs/guides/silabs_cli_guide.md create mode 100644 docs/guides/silabs_common_app_behavior.md delete mode 100644 docs/guides/silabs_efr32_building.md create mode 100644 docs/guides/silabs_getting_started.md diff --git a/.github/.wordlist.txt b/.github/.wordlist.txt index cb8e31e28b2d23..44470a612f42c7 100644 --- a/.github/.wordlist.txt +++ b/.github/.wordlist.txt @@ -130,6 +130,7 @@ BarrierControl BasicCHIPRegression BasicInformation baudrate +BCM BD BDX BDXDownloader @@ -248,6 +249,7 @@ CKIT CLA clapre CLI +CLIs cloudbuild CLRF clusterAttrs @@ -264,6 +266,7 @@ CMS CMSIS CMVH cn +COAP codeaurora codebase codegen @@ -298,8 +301,8 @@ connstring conntype const ContentApp -ContentAppPlatform ContentApp's +ContentAppPlatform ContentLaunch ContentLauncher continuousHinting @@ -655,13 +658,13 @@ iaszone ibb ICA ICD +ICDs iCloud ICMP IDF IDL IDLs idt -IDT idx ifconfig ifdef @@ -793,7 +796,6 @@ LightingColor LightingState LinkSoftwareAndDocumentationPack lladdr -LLADDR LocalConfigDisabled localedef localhost @@ -914,6 +916,7 @@ namespacing nano natively navpad +NCP ncs nding NDK @@ -1021,6 +1024,7 @@ PairDevice PAIs PAKE palletsprojects +PANID pankore param params @@ -1157,8 +1161,8 @@ REPL repo req Requestor -RequestorCanConsent Requestor's +RequestorCanConsent Requestors responder RestrictedEvent @@ -1213,8 +1217,8 @@ SDB SDC SDHC SDK -sdkconfig SDK's +sdkconfig SDKs SDKTARGETSYSROOT sdl @@ -1227,6 +1231,7 @@ SendNewInputEvent sendto seqdiag SERIALDEVICE +serialno SerialNumber ServiceId SetDns @@ -1336,12 +1341,14 @@ systime sysv TargetNavigator TBD +tbody tcl TCP teardown Telink TemperatureMeasurement templating +Tera testability TestArray TestCluster @@ -1470,6 +1477,7 @@ utils UUID ux validator +vcom VCP Vectorcall VendorID @@ -1497,6 +1505,7 @@ WantedBy watchdogTimeout watchOS webpage +wf wg wget whde diff --git a/docs/guides/README.md b/docs/guides/README.md index a643a0e846d7cb..30356c72273747 100644 --- a/docs/guides/README.md +++ b/docs/guides/README.md @@ -19,9 +19,10 @@ - [nRF Connect - Software Update](./nrfconnect_examples_software_update.md) - [NXP - Android Commissioning](./nxp_k32w_android_commissioning.md) - [NXP - Linux Examples](./nxp_imx8m_linux_examples.md) -- [Silicon Labs - Documentation](https://github.com/SiliconLabs/matter#readme) -- [Silicon Labs - Building](./silabs_efr32_building.md) +- [Silicon Labs - Documentation](https://siliconlabs.github.io/matter/latest/index.html) +- [Silicon Labs - Getting Started](./silabs_getting_started.md) - [Silicon Labs - Software Update](./silabs_efr32_software_update.md) +- [Silicon Labs - CLI Guide](./silabs_cli_guide.md) - [STMicroelectronics (STM32)](./stm32_getting_started_guide.md) - [TI - Platform Overview](./ti/ti_platform_overview.md) - [Open IoT SDK - Platform Overview](./openiotsdk_platform_overview.md) diff --git a/docs/guides/darwin.md b/docs/guides/darwin.md index 74ed819c9f875f..0b312807e3457f 100644 --- a/docs/guides/darwin.md +++ b/docs/guides/darwin.md @@ -264,7 +264,7 @@ Example: - [Infineon CYW30739 Lighting](/examples/lighting-app/infineon/cyw30739/README.md) - [Infineon PSoC6](/examples/all-clusters-app/infineon/psoc6/README.md) - [Qorvo](/examples/lighting-app/qpg/README.md) -- [SiliconLabs](./silabs_efr32_building.md) +- [Silicon Labs](./silabs_getting_started.md) - [Simulated Linux](./simulated_device_linux.md) - [Telink](/examples/lighting-app/telink/README.md) - [TI Platform](./ti/ti_platform_overview.md) diff --git a/docs/guides/images/silabs_logo.png b/docs/guides/images/silabs_logo.png new file mode 100644 index 0000000000000000000000000000000000000000..85cfcceb7434e157f96b4c4e3eb06011bce94fc9 GIT binary patch literal 4619 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 literal 0 HcmV?d00001 diff --git a/docs/guides/index.md b/docs/guides/index.md index 2119b46059a8c0..8813376f7e3e81 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -37,9 +37,10 @@ ti/ti_platform_overview - [NXP - Android Commissioning](./nxp_k32w_android_commissioning.md) - [NXP - Linux Examples](./nxp_imx8m_linux_examples.md) - [NXP - Manufacturing Data](./nxp_manufacturing_flow.md) -- [Silicon Labs - Documentation](https://github.com/SiliconLabs/matter#readme) -- [Silicon Labs - Building](./silabs_efr32_building.md) +- [Silicon Labs - Documentation](https://siliconlabs.github.io/matter/latest/index.html) +- [Silicon Labs - Getting Started](./silabs_getting_started.md) - [Silicon Labs - Software Update](./silabs_efr32_software_update.md) +- [Silicon Labs - CLI Guide](./silabs_cli_guide.md) - [TI - Platform Overview](./ti/ti_platform_overview.md) ## Tool Guides diff --git a/docs/guides/silabs_cli_guide.md b/docs/guides/silabs_cli_guide.md new file mode 100644 index 00000000000000..8a368f093cfd38 --- /dev/null +++ b/docs/guides/silabs_cli_guide.md @@ -0,0 +1,232 @@ +# Silabs CLI Guide + +## Introduction + +The guide discusses the different CLIs that can be enabled with the Silabs +sample apps. The CLIs expose configuration and management APIs via a command +line interface (CLI). For OpenThread devices, the OpenThread CLI can be used +with or without the Matter CLI. For Wi-Fi devices, only the Matter CLI is +available. + +- [Introduction](#introduction) +- [Enable the CLI interfaces](#enable-the-cli-interfaces) + - [Matter CLI](#matter-cli) + - [OpenThread CLI](#openthread-cli) +- [Connecting to the device](#connecting-to-the-device) + - [Screen Utility](#screen-utility) + - [Tera Term](#tera-term) +- [Command List](#command-list) +- [Application Specific Commands](#application-specific-commands) + +## Enable the CLI Interfaces + +### Matter CLI + +To enable the Matter CLI, the `chip_build_libshell=true` argument can be added. +This build argument can be added to OpenThread and Wi-Fi build commands. Here is +an example of the build command with the Matter CLI enabled. + +```sh +./scripts/examples/gn_silabs_example.sh ./examples/lighting-app/silabs/ ./out/lighting-app BRD4187C chip_build_libshell=true +``` + +### OpenThread CLI + +The OpenThread CLI is enabled by default on all OpenThread builds. To disable +the OpenThread CLI, the `enable_openthread_cli=false` argument can be added. +Here is an example of the build command to disable the OpenThread CLI. + +```sh +./scripts/examples/gn_silabs_example.sh ./examples/lighting-app/silabs/ ./out/lighting-app BRD4187C enable_openthread_cli=false +``` + +## Connecting to the Device + +The different CLIs are provided through the UART interface. The following table +exposes the UART configurations to connect to the different CLIs. + +| Configuration | Value | +| :--------------: | :----- | +| Baudrate (speed) | 115200 | +| Data | 8 bit | +| Parity | None | +| Stop Bit | 1 bit | +| Flow Control | None | + +Any serial terminal emulator will permit to connect to the device. For MacOS and +Linux, the screen utility can be used. For Windows, Tera Term can be used. + +### Screen Utility + +To use the Screen utility, we first need to find the vcom port. For MacOS, it +will be formatted as `/dev/cu.usbmodem...` and for Linux it will be formatted as +`/dev/ttyACM...`.
Here is an example command connecting to the device with +the screen utility. + +```sh +screen /dev/cu.usbmodem0004403048491 115200 8-N-1 +``` + +### Tera Term + +See the +[Tera Term guide](https://siliconlabs.github.io/matter/latest/wifi/MATTER_SHELL.html) +on how to connect to the device on Windows. + +## Command List + +When the prompt `matterCli>` is printed, the device is ready for a command. + +> **Note**: When the OpenThread CLI is used without the Matter CLI, the prompt +> is `>`. + +- [help](#help) +- [base64](#base64) +- [exit](#exit) +- [version](#version) +- [ble](#ble) +- [config](#config) +- [device](#device) +- [onboardingcodes](#onboardingcodes) +- [dns](#dns) +- [dns](#dns) +- [ota](#ota) +- [stat](#stat) +- [echo](#echo) +- [log](#log) +- [rand](#rand) +- [otcli](#otcli) + +### help + +Prints the list of commands and their description. + +```bash +matterCli> help + base64 Base64 encode / decode utilities + exit Exit the shell application + help List out all top level commands + version Output the software version + ble BLE transport commands + config Manage device configuration. Usage to dump value: config [param_name] and to set some values (discriminator): config [param_name] [param_value]. + device Device management commands + onboardingcodes Dump device onboarding codes. Usage: onboardingcodes none|softap|ble|onnetwork [qrcode|qrcodeurl|manualpairingcode] + dns Dns client commands + ota OTA commands + stat Statistics commands + echo Echo back provided inputs + log Logging utilities + rand Random number utilities + otcli Dispatch OpenThread CLI command +``` + +### base64 + +Base64 encode / decode utilities + +```bash +matterCli>base64 help + help Usage: base64 + encode Encode a hex sting as base64. Usage: base64 encode + decode Decode a base64 sting as hex. Usage: base64 decode +``` + +### exit + +Exit the application + +> **Note**: Application will not respond until reset. + +### version + +Output the software version + +### ble + +BLE transport commands + +```bash +matterCli> ble help + help Usage: ble + adv Enable or disable advertisement. Usage: ble adv +``` + +### config + +Manage device configuration. Usage to dump value: config [param_name] and to set +some values (discriminator): config [param_name][param_value]. + +```bash +matterCli> config help + help Usage: config + vendorid Get VendorId. Usage: config vendorid + productid Get ProductId. Usage: config productid + hardwarever Get HardwareVersion. Usage: config hardwarever + pincode Get commissioning pincode. Usage: config pincode + discriminator Get/Set commissioning discriminator. Usage: config discriminator [value] +``` + +### device + +Device management commands + +```bash +matterCli> device + factoryreset Performs device factory reset +``` + +### onboardingcodes + +Dump device onboarding codes. Usage: onboardingcodes none|softap|ble|onnetwork +[qrcode|qrcodeurl|manualpairingcode] + +### dns + +Dns client commands + +```bash +matterCli> dns + resolve Resolve the DNS service. Usage: dns resolve (e.g. dns resolve 5544332211 1) + browse Browse DNS services published by Matter nodes. Usage: dns browse +``` + +### ota + +OTA commands + +```bash +matterCli> ota + query Query for a new image. Usage: ota query + apply Apply the current update. Usage: ota apply + notify Notify the new image has been applied. Usage: ota notify + state Gets state of a current image update process. Usage: ota state + progress Gets progress of a current image update process. Usage: ota progress +``` + +### stat + +Statistics commands + +### echo + +Echo back provided inputs + +### log + +Logging utilities + +### rand + +Random number utilities + +### otcli + +See the official OpenThread CLI +[documentation](https://github.com/openthread/openthread/blob/main/src/cli/README.md) +for the list of commands. + +## Application Specific Commands + +Samples apps may adds example specific commands to enhance the testable feature +set of the sample. See the sample app documentation for more information on +application specific commands. diff --git a/docs/guides/silabs_common_app_behavior.md b/docs/guides/silabs_common_app_behavior.md new file mode 100644 index 00000000000000..06354b77a6a127 --- /dev/null +++ b/docs/guides/silabs_common_app_behavior.md @@ -0,0 +1,141 @@ +# Standard Application Behavior Guide + +## Introduction + +This section discusses the application behavior that is common to all Silabs +sample apps. The source files that implement the common functionality can be +found in the [example platform](../../examples/platform/silabs/) directory. + +- [Introduction](#introduction) +- [LCD Screens](#lcd-screens) + - [QR Code](#qr-code) + - [Application UI](#application-ui) + - [Status Screen](#status-screen) +- [Buttons](#buttons) + - [Operation Button](#operation-button) + - [Application Button](#application-button) +- [LEDs](#leds) + - [Status LED](#status-led) + - [Application LED](#application-led) + +## LCD Screens + +When using a development kit that supports the LCD, the application has three +distinct windows. You can cycle between the three windows by pressing `BTN0`. +When the application UI is updated while on another window, the LCD will +automatically switch to it. + +### QR Code + +[QR Code](https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3A6FCJ142C00KA0648G00) +is the default QR code that can be used to commission the device over BLE and +when using the Basic Commissioning Mode. See the Matter specification to +understand what is encoded in the QR code. + +> **Note**: The Basic Commissioning Mode is not recommended since it is less +> secure than the Enhanced Commissioning Mode. See the Matter specification for +> more details. + +### Application UI + +Each sample has an application UI that helps visualize the sample's app state. +See the sample app documentation for more information. + +### Status Screen + +The status screen is used to visualize the state of the device. + +> **Note:** The support of the status screen for ICDs is yet to be done. + +The following list describes the information that is common for OpenThread and +Wi-Fi devices. + +| LCD UI | Description | +| :---------: | :----------------------------------------------------------------------------- | +| # fabrics | Indicates the number of commissioned fabrics on the device | +| Connected | Indicates if the device is connected to the OpenThread or Wi-Fi network | +| Advertising | Indicates if the devices is currently advertising an open commissioning window | +| Is ICD | Indicates if the device is an Intermittently Connected device | + +The following list describes the information that is unique to OpenThread +devices. + +| LCD UI | Description | +| :-----: | :------------------------------------------------------- | +| PANID | Indicates the PANID of the configured openthread network | +| OT Type | Indicates the openthread device type (FTD / MTD) | + +> **Note:** The PANID information is not yet printed on the LCD. + +The following list describes the information that is unique to Wi-Fi devices. | +LCD UI | Description | | :----: | :---------- | | SSID | SSID of the connected +Wi-Fi network | + +> **Note:** The SSID information is not yet printed on the LCD. + +## Buttons + +All sample applications are designed to work with two buttons: the application +button and the operation button. Button 0, **BTN0**, is the operation button and +Button 1, **BTN1**, is the application button. + +> **Note:** Sparkfun dev kit (BRD2704A) does not have any buttons. + +### Operation Button + +The following list describes all the actions that can be executed with the +operation button. + + + + + + + + + + + + + + +
ExecutionDescription
Press and Release +
    +
  • If the device is not already commissioned, it will start advertising in fast mode for 30 seconds.
    After 30 seconds, the device will then switch to a slower interval advertisement After 15 minutes, the advertisement stops.
    • +
  • Prints initial and BCM commissioning QR code in the Logs
    • +
+
Press and hold for 6 seconds +
    +
  • Factory Reset device
    • +
+
+ +### Application Button + +See the sample app documentation for more information on the application button. + +## LEDs + +All sample applications are designed to work with two LEDs: the application LED +and the status LED. **LED0** is the status LED and the **LED1** is the +application LED. + +> **Note:** Some dev kits can only support the buttons or the LEDs. The button +> support is the default configuration.
For dev kits with only LED, the +> application LED is the default configuration. + +### Status LED + +The following list describes all the states of the status LED. + +| State | Description | +| :----------------------------------------: | :------------------------------------------------------------------------------------------------------------- | +| Short Flash On (50ms on / 950ms off) | The device is in the unprovisioned (unpaired) state and is waiting for a commissioning application to connect. | +| Rapid Even Flashing (100ms on / 100ms 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. | +| Long Even Flashing (500ms on / 500ms off) | Factory Reset procedure has been started. | + +### Application LED + +See the sample app documentation for more information on the application LED. diff --git a/docs/guides/silabs_efr32_building.md b/docs/guides/silabs_efr32_building.md deleted file mode 100644 index a3e4ed8ed0c0be..00000000000000 --- a/docs/guides/silabs_efr32_building.md +++ /dev/null @@ -1,30 +0,0 @@ -# Building Silicon Labs EFR32 examples - -Developers can start prototyping with Matter today. Silicon Labs offers a number -of examples using Matter, such as -[smart locks](https://github.com/project-chip/connectedhomeip/tree/master/examples/lock-app/efr32), -[smart lights](https://github.com/project-chip/connectedhomeip/tree/master/examples/lighting-app/efr32), -and -[window coverings](https://github.com/project-chip/connectedhomeip/tree/master/examples/window-app/efr32). -Matter simplifies the developer experience by maximizing the interoperability of -IoT devices across different vendors, so developers can focus on innovating. - -The full list of examples can be found -[here](https://github.com/project-chip/connectedhomeip/tree/master/examples). -The GitHub repository also includes tools for testing your Matter project. - -## Silicon Labs Matter Github - -Silicon Laboratories now maintains a public matter GitHub repo with frequent -releases thoroughly tested and validated. Developers looking to develop matter -products with silabs hardware are encouraged to use our latest release with -added tools and documentation. -[Silabs Matter Github](https://github.com/SiliconLabs/matter/releases) - -The complete Silabs documentation can be found here -[Silabs Matter Github Documentation](https://github.com/SiliconLabs/matter#readme) - -## Getting Started with Matter on EFR32 - -Developers can find more resources on -[Silicon Labs Matter Community Page](https://community.silabs.com/s/article/connected-home-over-ip-chip-faq?language=en_US). diff --git a/docs/guides/silabs_getting_started.md b/docs/guides/silabs_getting_started.md new file mode 100644 index 00000000000000..89fb71d8d533ce --- /dev/null +++ b/docs/guides/silabs_getting_started.md @@ -0,0 +1,267 @@ +# Silicon Labs Matter Solution Guide + +## Introduction + +The Silabs Matter Solution Guide explains how to use the Silabs Matter offering. +It explains how to set up the development environment, build and flash a Silabs +sample app. + +![Silabs logo](./images/silabs_logo.png) + +> **NOTE:** Silicon Laboratories now maintains a public Matter GitHub repo with +> frequent releases thoroughly tested and validated. Developers looking to +> develop matter products with silabs hardware are encouraged to use our latest +> release with added tools and documentation. +> [Silabs Matter Github](https://github.com/SiliconLabs/matter/releases) +> +> Developers can find more resources on the +> [Silicon Labs Matter Community Page](https://community.silabs.com/s/article/connected-home-over-ip-chip-faq?language=en_US). + +- [Introduction](#introduction) +- [Requirements](#requirements) + - [Hardware Requirements](#hardware-requirements) + - [Software Requirements](#software-requirements) + - [Software Artifacts](#software-artifacts) +- [Building](#building) + - [Build Script](#build-script) + - [Build Arguments](#build-arguments) +- [Flashing](#flashing) + - [Flasher Arguments](#flasher-arguments) +- [Standard Application Behavior](#standard-application-behavior) + +## Requirements + +### Hardware Requirements + +For the list of hardware requirements, see the official +[Silicon Labs Matter HW requirements](https://siliconlabs.github.io/matter/latest/general/HARDWARE_REQUIREMENTS.html) +documentation. + +### Software Requirements + +For the list of software requirements, see the official +[Silicon Labs Matter Software requirements](https://siliconlabs.github.io/matter/latest/general/SOFTWARE_REQUIREMENTS.html) +documentation. + +#### Software Artifacts + +For pre-built binaries for the latest Silicon Labs Matter release, see the +official +[Silicon Labs Matter Software Artifacts](https://siliconlabs.github.io/matter/latest/general/ARTIFACTS.html#matter-software-artifacts). +This includes all necessary binaries to run a Silicon Labs sample app. + +## Building + +Silicon Labs currently supports the following list of sample apps in the main +Matter SDK. Every sample has its own documentation explaining its unique +features and functionalities. The examples in the `CSA Matter Repository` column +are supported in the main Matter SDK. Additionally, the +[Silabs Matter Repository](https://github.com/SiliconLabs/matter) offers extra +sample applications for different device-types + + + + + + + + + + + + +
CSA Matter Repository Silabs Matter Repository
+ + + +
+ +### Build Script + +To build a Silicon Labs sample apps, we provide the `gn_silabs_examples.sh` +scripts that can be found in the `./scripts/examples` directory. The build +script can be used to build all of the Silabs supported examples. The command +structure is as follows when called from the root of the repository: + +```shell +./scripts/examples/gn_silabs_example.sh +``` + +To build the lighting app as an OpenThread SoC, the default build command for +the BRD4187C DK is + +```shell +./scripts/examples/gn_silabs_example.sh ./examples/lighting-app/silabs/ ./out/lighting-app BRD4187C +``` + +To build the lighting app as an Wi-Fi MG24 + RS9116 NCP, the default build +command for the BRD4187C is + +```shell +./scripts/examples/gn_silabs_example.sh examples/lighting-app/silabs/ out/lighting-app_rs9116 BRD4187C use_external_flash=false chip_enable_ble_rs911x=true --wifi rs9116 +``` + +> **Note**: The build argument `--wifi rs9116` is necessary to build the +> BRD4187C image with the necessary code for the NCP combo. +> `chip_enable_ble_rs911x=true` enables the RS9116 NCP bluetooth. The MG24 + +> RS9116 NCP combo does not yet support external flash. + +To build the lighting app as an Wi-Fi MG24 + SiWx917 NCP, the default build +command for the BRD4187C is + +```shell +./scripts/examples/gn_silabs_example.sh examples/lighting-app/silabs/ out/lighting-app_siwx917 BRD4187C use_external_flash=false chip_enable_ble_rs911x=true --wifi SiWx917 +``` + +> **Note**: The build argument `--wifi SiWx917` is necessary to build BRD4187C +> image with the necessary code for the NCP combo. `chip_enable_ble_rs911x=true` +> enables the RS9116 NCP bluetooth. The MG24 + SiWx917 NCP combo does not yet +> support external flash. + +To build the lighting app as an Wi-Fi MG24 + wf200 NCP, the default build +command for the BRD4187C is + +```shell +$ ./scripts/examples/gn_silabs_example.sh examples/lighting-app/silabs/ out/lighting-app_wf200 BRD4187C --wifi wf200 +``` + +> **Note**: The build argument `--wifi wf200` is necessary to build the BRD4187C +> image with the necessary code for the NCP combo. + +#### Build Arguments + +The ``gn_silabs_examples.sh` script takes two types of build arguments. The +first type are macros processed within the script itself and the second are GN +arguments. The Macros encapsulate multiple GN arguments to simplify enabling or +disabled specific features. + +> **Note**: Executing the build script without any arguments will print a helper +> with the command structure, the list of supported boards, and a list of +> supported macros and arguments +> +> ```sh +> ./scripts/examples/gn_silabs_examples.sh +> ``` + +Here is a list of some the supported macros and their GN argument equivalent. + +| Macro Name | Description | GN equivalent | +| :---------------------------: | :----------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- | +| --wifi | Configures an sample app as a Wi-Fi devices.
This macro requires rs9116 or SiWx917 or wf200. | --wifi rs9116 : use_rs9116=true
--wifi SiWx917 : use_SiWx917=true
--wifi wf200 : use_wf200=true
| +| --icd | Configures the device as an ICD | chip_enable_icd_server=true chip_openthread_ftd=false | +| --low-power | Configures the most power efficient build.
This is used in tandem with the `--icd` macro | chip_build_libshell=false enable_openthread_cli=false show_qr_code=false disable_lcd=true | +| --chip_enable_wifi_ipv4 | Enables IPv4 support on Wi-fi configured builds | chip_enable_wifi_ipv4=true chip_inet_config_enable_ipv4=true | +| --clean | Cleans the output directory before building | NA | +| --additional_data_advertising | Enable additional data advertising and rotating device ID | chip_enable_additional_data_advertising=true chip_enable_rotating_device_id=true | +| --use_ot_lib | Builds the sample app with the Silabs certified OpenThread libraries | use_silabs_thread_lib=true chip_openthread_target=\$SILABS_THREAD_TARGET openthread_external_platform=\"""\" | +| --use_ot_coap_lib | Builds the sample app with the Silabs certified OpenThread COAP libraries | use_silabs_thread_lib=true chip_openthread_target=\$SILABS_THREAD_TARGET openthread_external_platform=\"""\" use_thread_coap_lib=true | +| --release | Remove all logs and debugs features (including the LCD).
Yields the smallest image size possible | is_debug=false disable_lcd=true chip_build_libshell=false enable_openthread_cli=false use_external_flash=false chip_logging=false silabs_log_enabled=false | +| --bootloader | Adds a bootloader to the built image | NA | +| --uart_log | Forwards logs to uart instead of RTT | sl_uart_log_output=true | + +Here is a list of some of the GN arguments that can be added to the build +command. + +> **Note**: All GN arguments can be added to the build. +> `gn args --list ` can be used to list all GN arguments. + +| GN argument | Description | Default Value | +| :--------------------: | :------------------------------------------------------------------------------------------------------------------------------ | :----------------------------- | +| chip_build_libshell | Enables the Matter Shell | false | +| chip_openthread_ftd | Defines if the OpenThread device is an FTD (true) or an MTD (false) | true | +| efr32_sdk_root | Location for an alternate Gecko SDK | ./third_party/silabs/gecko_sdk | +| enable_heap_monitoring | Monitor & log memory usage at runtime | false | +| enable_openthread_cli | Enables the OpenThread cli | true | +| kvs_max_entries | Set the maximum KVS entries that can be stored in NVM
Thresholds: 30 <= kvs_max_entries <= 255 | 255 | +| chip_enable_icd_server | Configure device as an intermittently connected device
For Thread builds, chip_openthread_ftd must also be set to false. | false | +| disable_lcd | Disable the LCD on devices with an LCD | false | +| show_qr_code | Enables QR code on LCD for devices with an LCD | true | + +On top of the GN arguments specified here, each sample app will specify, if need +be, the GN arguments specific to it. + +## Flashing + +The Matter SDK provides a standard way of flashing a sample app binary onto +hardware. After completing a build, a python script is generated that can be +used to flash the binary. The naming structure of the file is + +```sh +matter-silabs--example.flash.py +``` + +For example, the lighting-app flasher script will be named + +```py +matter-silabs-lighting-example.flash.py +``` + +To execute the script, the following command can be used: + +```sh +python3 /matter-silabs-lighting-example.flash.py +``` + +where `` is the path to the output directory used in the build script. + +> **Note**: It is also possible to flash the built binary with commander +> directly. The commander command is +> `commander flash /matter-silabs-lighting-example.`
The +> `.s37` binaries are used with the MGM24 and EFR32 families while the `.rps` +> binaries are only used for the SiWx917 SoC family. + +### Flasher Arguments + +The flashing script provides configuration arguments and operation arguments. +The configuration arguments are used to configure the operation arguments. + +Here is a list of the configuration arguments that can be added to the flasher +script. + +| Argument | Description | +| :-------------------: | :------------------------------------------------------------------------------------------------------------------------- | +| --verbose, -v | Report more verbosely | +| --commander FILE | Path to the commander executable | +| --device, -d DEVICE | Device family or platform to target (EFR32, MGM24, 917) | +| --serialno, -s SERIAL | Serial number of device to flash.
This argument is necessary when multiple boards of the same family are connected. | +| --ip, -a ADDRESS | IP Address of the device to flash | + +Here is a list of the operations arguments that can be added to the flasher +script. + +| Argument | Description | Commander equivalent | +| :------------------: | :------------------------------------------------------------------------------------------------------------------ | :--------------------------- | +| --erase | Erase the devices flash.
This options completely wipes the devices flash including factory data. | `commander device masserase` | +| --application FILE | Specify which binary to flash.
The flasher script provides a default path to the binary that was just built. | `commander flash` | +| --reset | Reset device after flashing | `commander device reset` | +| --skip-reset | Do not reset device after flashing | `commander flash --noreset` | +| --verify-application | Verify the image after flashing | `commander verify` | + +Executing the flasher scripts with the `--help / -h` arguments will print a help +menu with all the possible arguments. + +> **Note**: For a wider range of features, the commander tool can be used +> directly. Running `commander --help / -h` will list all the available options +> of the tool. + +## Standard Application Behavior + +See the [Standard Application documentation](./silabs_common_app_behavior.md) +for behaviors that are common to all sample apps. + +## Silabs CLI + +See the [Silabs CLI documentation](./silabs_cli_guide.md) for more information +on the provided cli commands.