Silicon Labs documentation on Simplicity Studio 5 Users Guide version 5.11.2. Documentation source: https://docs.silabs.com/simplicity-studio-5-users-guide/5.11.2 # Simplicity Studio 5 Users Guide ## Visual Studio Code Enablement With the Simplicity Studio 5 (SSv5) 5.6.0.0 release, Silicon Labs introduced support for using Visual Studio Code (VS Code) in combination with Simplicity Studio. To enable this support, a VS Code extension is required. It can be either downloaded directly from the VS Code marketplace or with this [link to marketplace](https://marketplace.visualstudio.com/publishers/silabs). The preferred method of installation is to download it from the marketplace within the VS Code application itself. Simplicity Studio is still needed to create the initial project and to make project changes with the Project Configurator GUIs. However, when you are using the Visual Studio Code compatible project generator, all editing, building, and debugging of the project should be done in VS Code. In other words, do not try to build the project in both Simplicity Studio and in VS Code. ### Enabling a Project for Use Within VS Code In order to operate on a Silicon Labs project from within VS Code, the correct project generator must be used. This can be set from within an existing project or at initial project creation. For new projects, you can set the target generator in the new project wizard on step 1 as shown below. ![Select VSCode NewPrj Generator](/ss-5-users-guide-vscode-ide/0.3/images/newproj1-updated.png) For existing projects, from the Project Configurator Overview tab, click **Change Target/SDK/Generators** and select the VS Code generator. ![Select VSCode Generator 1](/ss-5-users-guide-vscode-ide/0.3/images/generator01-sized.png) ![Select VSCode Generator 2](/ss-5-users-guide-vscode-ide/0.3/images/generator02-sized.png) ![Select VSCode Generator 3](/ss-5-users-guide-vscode-ide/0.3/images/generator03-sized.png) Once you have set your project to generate for VS Code, and generation is complete, you will notice new files in the Project Explorer view. This includes new files to support development in VS Code and enable CMake and Ninja. If a popup dialog appears asking what to do with some project configuration files, leave the setting at the default “Keep my file” and click **OK**. The new VS Code support files are: - Folder: _cmake - .cmake - CMakeLists.txt - CMakePresets.json - toolchain.cmake - vscode.conf. ![VSCode generation files](/ss-5-users-guide-vscode-ide/0.3/images/vscode-project-files-updated.png) You can make any other project configurator changes, such as adding a component, to the project from within Simplicity Studio. From there, the project can be continued in VS Code. Once you begin using VS Code for development, it is not recommended to build the project in Simplicity Studio. However, before any changes have been made in VS Code, you can verify that it builds in Simplicity Studio before continuing development in VS Code. The VS Code generator is Gecko SDK Suite (GSDK)-independent. This means it can be used with any 4.x.x GSDK. For details on installation and use, refer to the [Simplicity Studio Extension for VS Code](https://docs.silabs.com/ss-vscode/latest/ss-vscode-start/). ## Overview ### Simplicity Studio® 5 User's Guide Simplicity Studio is the core development environment designed to support the Silicon Labs IoT portfolio of system-on-chips (SoCs) and modules. It provides access to target device-specific web and SDK resources; software and hardware configuration tools; an integrated development environment (IDE) featuring industry-standard code editors, compilers and debuggers; and advanced, value-add tools for network analysis and code-correlated energy profiling. ![The Launcher perspective with a part selected](/ss-5-users-guide-overview/1.7/images/launcher-selected.png) Simplicity Studio is designed to simplify developer workflow. It intelligently recognizes all evaluation and development kit parts released by Silicon Labs and, based on the selected development target, presents appropriate software development kits (SDKs) and other development resources. Simplicity Studio 5 (SSv5) focuses on developer experience, leveraging feedback from customers, employees and competitive reviews. Developers of all experience levels will benefit from an optimized workflow that supports them through the development journey and produces quicker project progression and device configuration. The _Simplicity Studio 5 User's Guide_ pages are organized into the following groups. - [Getting Started](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-getting-started) describes how to install SSv5 and the relevant development resources, and provides general overviews of using the SSv5 interface and of developing projects in SSv5. If you are new to SSv5, start here. - [About the Launcher](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-about-the-launcher) is a reference guide to the features and functions available when you first open SSv5. This is a general reference, although some items may not be applicable to all devices. - [About the Simplicity IDE](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-about-the-simplicity-ide) is a reference guide to the features and functions in the Simplicity integrated development environment. This is a general reference, although some items may not be applicable to all devices. - [Developing for 32-Bit Devices](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-32bit-devices-overview) provides instructions and reference material for 32-bit device development in the two development environments: Project Configurator and AppBuilder. - [Developing for 8-Bit Devices](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-for-8bit-devices) provides instructions and reference material for 8-bit device development using the Hardware Configurator. - [Building and Flashing](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-building-and-flashing) describes how to compile and flash images to various device types. - [Companion IDEs: Visual Studio Code](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-vscode-ide) discusses how to generate project code in Simplicity Studio 5 to then be used in the VS Code IDE. - [Testing and Debugging](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-testing-and-debugging) outlines tools and strategies for testing your applications on Silicon Labs devices. - [Using the Tools](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-tools-overview) is a reference guide to the various tools packaged with SSv5. Not all tools are applicable to every development path. Their specific use is described in the individual **Developing for** pages. ### New Features #### Simplicity Studio® 5 version 5.11.2 released Sept 24, 2025 This release includes the following key features: - Support for Simplicity SDK 2025.6.2 - Support for new device products: SixG301 The SixG301 devices are only supported with CMake/GCC (no IAR support). Refer to the [Known Issues and Limitations section](https://docs.silabs.com/sisdk-release-notes/2025.6.2/sisdk-platform-release-notes/) for additional details. - **Matter**: On Windows, Matter projects from Matter SDK 2.7.0-1.4 (CSA Matter 1.4.2), released with SiSDK 2025.6.2, fail during compilation due to a known GCC 12.x bug related to long command line length. Refer to this [Knowledge Article](https://community.silabs.com/s/article/Matter-2-7-0-CSA-Matter-1-4-2-and-SiSDK-2025-6-2-Windows-builds-issue-workarounds?language=en_US) for Studio 5 workaround. #### Simplicity Studio® 5 version 5.11.1 released July 24, 2025 This release includes the following key feature: - Support for Simplicity SDK 2025.6.1 #### Simplicity Studio® 5 version 5.11.0 released June 16, 2025 This release includes the following key features: - Support for Simplicity SDK 2025.6.0 - Support for new device products: EFR32BG22L, EFR32BG24L, EFR32xG29 - New Wi-Fi Power Estimator Tool v1.0.0 GUI tool supporting SiWx917 device development - Wi-Fi Commander: AP mode updated; added Client mode and MQTT Client connection support - CS Analyzer: Added support of PBR+RTT methodology #### Simplicity Studio® 5 version 5.10.3 released April 1, 2025 This release includes the following key feature: - Support for SiSDK 2024.12.2 #### Simplicity Studio® 5 version 5.10.2.1 released Feb 27, 2025 This release includes the following key feature: - Patch to resolve incompatibilities with ZAP custom templates. #### Simplicity Studio® 5 version 5.10.1 released Feb 7, 2025 This release includes the following key features: - Support for Simplicity SDK 2024.12.1. - Fixed “Preferred SDK” selection bug, so the setting defaults to the latest SDK version installed. #### Simplicity Studio® 5 version 5.10.0 released December 17, 2024 This release includes the following key features: - Support for Simplicity SDK 2024.12.0. - Improvements to the SDK Installer update flows. - New Studio [Project Retargeting](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-with-project-configurator/project-retargeting) feature for supporting development on Custom Boards. - New Simplicity Studio and SLC-CLI [CMake build exporter](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-getting-started/start-a-project) for IAR compiler. - Studio Matter Provisioning GUI tool version 1.1.0 released. Moved to General Availability (GA) quality, see Tool’s Release Notes for further details. - New Simplicity Studio [SBOM generation tool](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-building-and-flashing/sbom-generation), for Simplicity SDK 2024.12.0 or newer. - New Wi-Fi Commander v1.0.0 GUI tool released supporting SiWx91x device development, see Tool’s Release Notes for further details. - New Wi-Fi Memory Calculator v1.0.0 released supporting SiWx91x device development. #### Simplicity Studio® 5 version 5.9.1.0 released June 18, 2024 This release includes the following key features: - Support for Simplicity SDK 2024.6.0. - Enable Solutions (CMake) to work with the VS Code IDE. - Improvements to Radio Configurator. - Extend BTMesh tools to work with 917. - New Connectivity firmware update UI for 917 devices. - SLC workspaces for IAR. - SLC workspaces for CMake. #### Simplicity Studio® 5 version 5.8.0.0 released December 13, 2023 This release includes the following key features: - Two new project generators have been officially released. - Visual Studio Code Project (utilizing CMake and Ninja) - CMake - Matter Provisioning Tool 1.0.0 (Beta) has been released. - Requires GSDK 4.4 and Matter Extension 2.2 or newer - Documentation will be coming in a future patch release - Improvements for computers using MAC M1 Hardware. #### Simplicity Studio® 5 version 5.7.0.0 released June 7, 2023 This release includes the following key features: - [Amazon Sidewalk](https://www.silabs.com/ecosystems/extend-iot-device-range-with-amazon-sidewalk?guide-tab=start_configure): Can now be installed as an extension directly in Simplicity Studio. - [Amazon Sidewalk](https://www.silabs.com/ecosystems/extend-iot-device-range-with-amazon-sidewalk?guide-tab=start_configure): Protocol Configurator released. - [Pin Tool](https://docs.silabs.com/simplicity-studio-5-users-guide/latest/ss-5-users-guide-developing-with-project-configurator/pin-tool): Now supports Analog pin configuration. #### Simplicity Studio® 5 version 5.6.3.0 released March 10, 2023 This release includes the following key features: - [Solutions](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-with-project-configurator/project-solutions): Enhanced support for TrustZone applications. - [Post-Build Editor](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-building-and-flashing/post-build-editor): Removes the requirements for manually editing the yaml output files. #### Simplicity Studio® 5 version 5.6.2.0 released February 14, 2023 This release includes the following key features: - [Pin Tool](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-with-project-configurator/pin-tool): The user interface is redesigned. - [Bluetooth NCP Commander](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-tools-bluetooth-ncp-commander/): Updates in support of Bluetooth mesh functionality. #### Simplicity Studio® 5 version 5.6.0.0 released December 14, 2022 This release includes the following key features: - [Project Configuration Report Generator](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-start-a-project#project-configurator-projects): Provides a report including - Target hardware device - Target hardware device pin mapping - Target SDK - Software extensions used in the build - Installed application, utility, and platform software components - [Post-Build Editor](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-building-and-flashing/post-build-editor): Allows for ease of post-build image creation: - YAML file is modified to include steps. - YAML file can be provided to Simplicity Commander to create an OTA upgrade image. - [Support for Visual Studio Code as a Companion IDE](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-vscode-ide): Basic IDE functionality within VS Code using a Silicon Labs Extension. - Build - Flash - Debug - Extended Matter Enablement Package support to cover example project configuration, build, and debug. #### Simplicity Studio® 5 version 5.5.0.0 released September 7, 2022 This release includes the following key features: - Introduction of Matter Support: - Pre-built Matter demos now supported within the Simplicity Studio Launcher perspective. - Matter Enablement Package now available from the [Installation Manager](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-getting-started/install-sdk-extensions). - Integrated [Wireshark Launching](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-testing-and-debugging/using-wireshark) from the Debug Adapters view. - Usability improvements to the Package Manager. #### Simplicity Studio® 5 version 5.4.2.0 released August 17, 2022 - Support for the EFR32xG24 Explorer Kit. #### Simplicity Studio® 5 version 5.4.0.0 released June 8, 2022 This release includes the following key features: - Eclipse upgraded to [v4.23](https://www.eclipse.org/eclipse/news/4.23/), featuring several bug fixes and improvements, including improved support for the latest MacOS versions. - Logic Analyzer view added to Energy Profiler for use with the general-purpose logic analyzer input pins of the Wireless Pro Kit mainboard (e.g. [xG24-PK6009A](https://www.silabs.com/development-tools/wireless/efr32xg24-pro-kit-10-dbm) featuring BRD4002A). - New [Wi-SUN Configurator](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-with-project-configurator/wi-sun-configurator) tool available, providing easy graphical configuration of the main Wi-SUN application settings. - New filters added to [Launcher -> Example Projects & Demos view](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-about-the-launcher/welcome-and-device-tabs#example-projects-demos-tab) to help users filter by wireless technology, device type, level/difficulty, quality, and more. - New "Quick Links" view added to the [SLC Project Configurator](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-with-project-configurator/project-configurator). - Bluetooth Direction Finding (AoA) tool suite update with new playback and visualization features. - Support for SDK Extensions as defined by the [SLC Specification](https://siliconlabs.github.io/slc-specification). - Improvements to the Linux installation dependencies and scripts. #### Simplicity Studio® 5 version 5.3.0.0 released December 15, 2021 This release includes the following key features: - NCP Commander enhancements - Bluetooth LE Direction Finding tools suite v1.0 - Installation of GSDKs published on GitHub - Dynamic GATT Configuration - IDE Dark Theme improvements - Multi-Project [Solutions](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-with-project-configurator/project-solutions) #### Simplicity Studio® 5 version 5.2.0.0 released June 16, 2021 This release includes the following key features: - Support for upgrading SLC projects to a newer SDK - NCP Commander updates: - Advertiser improvements including ability to build custom advertisement data packets, fine tune the TX Power, and export to incorporate settings into firmware. - Devices discovery improvements: ability to favorite devices and new filter by device name, address, RSSI, raw advertising data or favorite devices. - RF Regulatory Tests: ability to add CTE to DTM packets - Standalone version with access to all system COM ports may be launched through Tools dialog or Compatible Tools tab (see the [Bluetooth NCP Commander](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-tools-bluetooth-ncp-commander) page for more information) - Bluetooth Mesh Configurator updates - New warnings if Device Composition Data does not comply with the specification - Various bug fixes and improvements to validate model rules - Upgrade to support integrations with IAR Embedded Workbench v8.50.9 - Upgraded default GCC compiler to version Arm GCC v10.2 #### Simplicity Studio® 5 version 5.1.0.0 released December 9, 2020 This release includes the following key features: - [Beta release of GNU Debugger (GDB) support](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-testing-and-debugging/using-the-debugger) Simplicity Studio 5.1 includes Beta-level support for a GDB client and SEGGER's GDB server. - [GitHub integration for access to software example repositories](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-about-the-launcher/welcome-and-device-tabs#example-projects-demos-tab) Starting in Simplicity Studio 5.1, developers may clone sample projects from within the Gecko SDK or within compatible GitHub repos. - [Bluetooth Mesh support](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-with-project-configurator/bluetooth-mesh-configurator) Starting in Simplicity Studio 5.1 and Gecko SDK 3.1, Bluetooth Mesh is supported in the new Project Configurator workflow. Studio 5.1 introduces the all-new Bluetooth Mesh Configurator tool for configuring a Bluetooth Mesh node's Device Composition Data (DCD). - [Bluetooth NCP Commander](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-tools-bluetooth-ncp-commander) Bluetooth NCP Commander is a new Simplicity Studio 5 interactive console tool for sending BGAPI commands to a Bluetooth NCP application connected to a development host machine. #### Simplicity Studio® 5 version 5.0.0.0 released July 29, 2020 The initial release of SSv5 includes the following key features: - Launcher - Fresh, clean user interface - Automatic detection of connected development boards - Context-aware development board and target device developer resources - SDK download and update manager - Easy programming of pre-built demo apps - Simple cloning of software examples - Quick access to software and hardware documentation with search and filter capabilities - Software creation & management tools - Support for Gecko SDK Suite 3.0 and later - Creation of projects for - The integrated Simplicity Studio IDE - IAR Embedded Workbench - Command-line GNU toolchain (GNU makefiles) - Searchable library of device-relevant software making it easy to add software components to projects - Configure software components in a GUI or text (C source) editor - Configurable peripheral initialization, drivers, middleware, kernels and utilities - Built-in software configuration error-checking - Software dependency manager simplifies porting from - SDK to SDK - Silicon Labs development kits to custom hardware designs - Graphical configuration tools - Pin tool to assign pin and peripheral hardware resources - Proprietary radio configurator tool - Editor for Bluetooth LE Generic Attribute Profile (GATT) - Source/Project management and revision control - Option to copy or link SDK source - No hard-coded paths - Clear separation between SDK and customer source code - Easy transfer of projects (share/import/export of projects) - Source code management and software engineering workflows - Development Tools - Powerful integrated development environment (IDE) - Built on latest Eclipse framework (v4.14 and newer) - C/C++ Development Tooling (CDT, v9.10 and newer) - Eclipse marketplace to enhance and customize - Valuable insights with Silicon Labs analysis tools - Wireless network traffic capture and analysis - Test and analyze the traffic of your wireless devices and networks - Data collected directly from devices under test - Includes signal strength, LQI (Link Quality Indicator) and filtering information (unique to Silicon Labs) - Capture and display energy usage - Monitor single device or multiple nodes on a wireless network - Code-correlated energy data – identify where your embedded application is consuming energy and design power-optimized applications - Advanced trigger and search functions locate power events ### Known Issues #### Simplicity Studio® Version 5.9.1 |ID|Issue|Workaround| |---|---|---| |1320466|The error 'java.lang.NullPointerException: Cannot invoke "java.util.List.stream()"' appears when opening a project's .slcp file.|Close Simplicity Studio and use a file manager to delete the .projectlinkstore file from the project directory. The default quicklinks for the project will then be used the next time the .slcp file is opened.| #### Simplicity Studio® Version 5.8.0 |ID|Issue|Workaround| |---|---|---| |758963|The Navigation Buttons (back, forward, etc) will not be displayed if Simplicity Studio starts up on the Simplicity IDE perspective.|Change to a different perspective such as the Launcher perspective and then back to the Simplicity IDE perspective.| |1095792|Changing the Target Part in Project Configurator does not work correctly on custom hardware.|Either create a new software example for the desired target part and port in code changes or manually change the component ID in the .slcp and .slps files with a text editor and then open the Project configurator and do a Force Generation.| |1113960|GDB Debug Session Launch fails with "Error in final launch sequence" popup.|Typically, the debug session will launch successfully the next time or after a Simplicity Studio restart. If the issue persists, edit the debug configuration **Run > Debug configurations…** and uncheck the 'Continue' box on the Startup tab. The debug session will stop before `main()`, but clicking **Resume** will run to `main()`.| |1156776|Custom Network Analyzer Decoders no longer work starting with version 5.7.0.0.|JavaScript custom decoders need to be converted to LUA decoders. See [Custom Decoders](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-tools-network-analyzer/project-upgrade-new-gsdk-version).| |1209674|IAR Toolchain linker command line length can exceed Windows line limit.|When the IAR toolchain is used to compile projects from the Simplicity Studio IDE under Windows, it is possible to get linker errors if the linker line length exceeds the Windows limit of 30,000 characters.

The work around is to edit the project properties [C/C++ Build] > [Settings] > [IAR Linker for ARM] [Expert settings] and to use this command line: `@echo "$(OBJS) $(USER_OBJS)" > linker_file.xcl; ${COMMAND} -f linker_file.xcl $(LIBS) ${OUTPUT_FLAG}${OUTPUT_PREFIX}${OUTPUT} ${FLAGS}`| |1225683|Blank Project Wizard or Log In windows seen with MacOS Ventura or later.|When running Simplicity Studio under MacOS Ventura or later, if blank windows are seen for the new project wizard, login page or other windows, the internal browser used by Simplicity Studio might not have permissions to make changes to the system.

The work around is to go to the MacOS System Settings -> Privacy & Security -> App Management and to add Simplicity Studio as an application that can update or delete other applications.| ### Revision History #### Revision 5.8.0 released December 13, 2023 - Overview: Update new features and known issues - Getting Started: Add Extension upgrades to Upgrade an Existing Project - Companion IDEs: Update VSCode Project Generation - Tools: Network Analyzer: Update custom decoders #### Revision 5.7.2 released October 9, 2023 - Overview: Update known issues - Getting Started: Update the Zigbee Cluster Configurator to ZCL Advanced Platform - Developing with Project Configurator: Zigbee Cluster Configurator - Rename to ZCL Advanced Platform - Update user interface illustrations - Add information on use with Matter #### Revision 5.7.1 released August 17, 2023 - Overview: Update known issues #### Revision 5.7.0 released June 7, 2023 - Overview: Update known issues and new features - Getting Started: Updated first page to reflect that extensions are now installed as part of the normal install process, also update images and the Extensions section - Developing with Project Configurator: Update Proprietary Radio Configurator - Companion IDEs - VS Code: Update for current interface and functionality #### Revision 5.6.3 released March 16, 2023 - Overview: - Add release dates to New Features - Update Known Issues - Getting Started: Restructure and update Solutions and Memory Editor content - Developing with Project Configurator: - Update Pin Tool to reflect new interface - Update Solutions section - Add Memory Editor section - Using the Tools: NCP Commander - Update Bluetooth mesh section - Tips and Tricks: - Place a Project Under Source Control (update) - Discover Networked Devices (new) #### Revision 5.6.0 released December 14, 2022 - Getting Started: - Generate project report - Software Components tab: quality dropdown, PIN tool button - Configurator updates - Developing with Project Configurator: - Update Zigbee Cluster Configurator to include Matter projects - Update Wi-SUN Configurator for Fan 1.1 changes - Building and Flashing: Add new post-build editor section - Add new _Companion IDEs: Visual Studio Code_ section. - Tips & Tricks: Added a new tip about getting an updated Simplicity Commander tool. #### Revision 5.5.0 released September 7, 2022 - Getting Started: - Changed Update and Install SDK Software to reflect the modification for the Matter extension. - Updated for the new approach to installing extensions. - Added a section on updating a project to a newer GSDK version. - About the Launcher: - Revised the Toolbar > Install section, SDK tab to show the new interface for updating or adding SDKs. - Changed Preferred SDK information in the Welcome and Device tabs section. - Testing and Debugging: - Changed to reflect that the GNU Debugger is now the default. - Added a section on using the Wireshark Packet Analyzer. #### Revision 5.4.2 released August 17, 2022 - Getting Started: Updated the New Project Wizard interface, removed outdated content; documented the IDE / toolchain options when creating a new project. - Using the Tools: - Updated the Bluetooth Direction Finding Tool Suite section. - Added a logic analyzer section to Energy Profiler - Tips and Tricks: Added instructions for placing a project under source control - Throughout - Clarified that AppBuilder is a legacy tool. #### Revision 5.4.0 released June 8, 2022 - Getting Started: Updated Project Configurator Overview tab; added summary sections for Wi-SUN Configurator and beta Memory Editor. - About the Launcher: Documented new filter options for example applications. - Project Configurator: Updated Overview tab; added new Wi-SUN Configurator section. - Testing and Debugging: GNU Debugger support is now GA. - Tips and Tricks: Added a tip for installing all parts of an upgrade. #### Revision 5.3.2 released March 9, 2022 - Getting Started: Added more information about linking sources in a new project. - About the Launcher: Clarified the interface overview, with new information about the perspectives menu; added instructions on adding an SDK to the list shown on the General Information card. - NCP Commander: Added information about the scripting feature. - Tips and Tricks: Added a tip about working with custom radio boards. #### Revision 5.3.1 released January 26, 2022 - Getting Started: Updated Start a Project to reflect other project types available - NCP Commander: Updated to include Bluetooth mesh functionality - Using the tools: New section on the Bluetooth Direction Finding Tool Suite - Various maintenance updates. #### Revision 5.3.0 released December 15, 2021 - Installation instructions reflect installing the Gecko SDK from GitHub. - Project migration text includes newer migration options. - New SDK Extensions section. - New Solutions section. - Project Configurator now supports Zigbee, Bootloader, and Z-Wave. - New Zigbee Cluster Configurator tool. - NCP Commander enhanced with dynamic GATT database interactions. - Tips and Tricks updated with new installation information. #### Revision 5.2.0 released June 16, 2021 - Version changed to correlate with Simplicity Studio 5. - Tools: Standalone NCP Commander documented. - Getting Started: Linux installation instructions added. - Energy Profiler: Code correlation software setup instructions updated. - Tips and Tricks: Links added at the top of the page; tip on changing from GCC to IAR compiler added. - Various maintenance updates. #### Revision 1.1.0 released December 9, 2020 - General updates for Simplicity Studio 5.1. - Launcher perspective (Getting Started, About the Launcher): - Software Examples and Demos tabs combined into a single tab, enhanced filtering options. - Examples from GitHub repositories. - New security firmware update option for Series 2 devices. - Developing for 32-Bit Devices: - Project Configurator now supports Bluetooth Mesh and 32-Bit MCU SDKs. - New Project Configurator Configuration Tools tab. - New Bluetooth Mesh Node Configurator tool. - Pin Tool, new 'Add Component' functionality. - Testing & Debugging: - New Beta quality GNU Debugger. - Tools: - New Bluetooth NCP Commander tool. - Tips & Tricks: - Update protocol locations for Bluetooth Mesh. - New 'Capture a Simplicity Studio 5 Thread Dump' tip. #### Revision 1.0.0 released July 29, 2020 - Initial release ### For Users of Previous Versions If you are migrating from Simplicity Studio 4 to SSv5, or if you are transitioning from AppBuilder projects to the component-based architecture, see [Project Migration](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-getting-started/migrate-from-ss-4) for additional information. ## Getting Started ### Getting Started To get started with Simplicity Studio® 5 (SSv5): 1. [Install SSv5 and development software](install-ss-5-and-software) 2. [Explore the main features of SSv5](explore-ss-5) 3. [Start a project](start-a-project) You do not need hardware to install SSv5 and the relevant software packages or, for 32-bit devices, to explore the project configuration interface for a particular SDK. However, having your target hardware connected during installation ensures that your SSv5 installation is configured precisely for your environment. You should also have an account set up in the Silicon Labs Customer Support Portal. Access to some software packages is controlled by your customer profile. See [Prerequisites](prerequisites) for more information. ### Prerequisites To streamline your Simplicity Studio® 5 (SSv5) installation: - Connect [development hardware](#hardware) to your PC. - Log in to your [customer account](#customer-account). #### SSv5 System Requirements **Operating Systems** |Operating System|Version| |---|---| |Windows|Windows 10 64 bits (x64), and Windows 11 64 bits (x64), Windows on ARM is NOT supported| |macOS|11 Big Sur, 12 Monterey, 13 Ventura, 14 Sonoma| |Linux|Ubuntu 22.04.1 LTS| **Hardware** |Hardware Component|Item| |---|---| |CPU|1 GHZ or better| |Memory|1 GB RAM minimum, 8 GB recommended for Wireless Protocol development| |Disk Space|600 MB disk space for minimum FFD installation; 7 GB for Wireless Dynamic Protocol support| #### Hardware A Silicon Labs development kit is not required to get started with Simplicity Studio. However, if Simplicity Studio detects an official development kit, it can be used to help select the appropriate software and tools for installation. If you don't have a development kit, you can explore the available options [here](https://www.silabs.com/development-tools.p-microcontrollers.p-wireless). ##### EFR32 Kits If you have a Silicon Labs Wireless Starter Kit (WSTK) or Pro Kit, mount a radio board on the mainboard and connect the mainboard to your PC using the USB cable supplied with the kit. **Note:** For best performance in SSv5, be sure that the power switch on the mainboard is in the Advanced Energy Monitoring or **AEM** position. ![WSTK mainboard with the power switch in the AEM position](/ss-5-users-guide-getting-started/1.7/images/install-wstk-switch.png) #### Customer Account If you do not already have one, create an account on the Silicon Labs Customer Support portal. Be sure to record your account username and password as you will use it to log in through SSv5. Your account properties determine not only what software components you can download, but also what notifications you will receive. To review or change your notification subscriptions, log in to the portal, click **HOME** to go to the portal home page, and then click the **Manage Notifications** tile. Make sure that **Software/Security Advisory Notices & Product Change Notices (PCNs)** is checked, and that you are subscribed at minimum for your platform and protocol. Silicon Labs strongly recommends that you receive these notifications. Click **Save** to save any changes. ### Install SSv5 and Software This section discusses [how to install SSv5](#install-ssv5) and, once SSv5 is installed, [how to install software](#install-software). **NOTE:** Depending on your corporate environment, you may encounter installation problems. For example, if you cannot log in to Simplicity Studio® 5 (SSv5) but know you are entering your Customer Account username and password correctly, or if you get an error about connecting to the update server and your computer is definitely connected to the Internet, see [SDK installation or updates are not working](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-tips-and-tricks#sdk-installation-or-updates-are-not-working) for possible causes and solutions. #### Install SSv5 Instructions for installation [on Windows and MacOS](#on-windows-and-macos) and [on Linux](#on-linux) are provided. ##### On Windows and MacOS 1. Download the SSv5 installation package from the Silicon Labs website. The Windows package is an '.iso' disk image. After the package finishes downloading, double-click it to mount the iso image as a drive and then double-click the setup.exe file inside the drive to launch the installer. 2. When the SSv5 installer first launches, it presents a Simplicity Studio License Agreement dialog. Accept the terms of the agreement and click **Next >**. ![SSv5 License agreement with default do not accept selected](/ss-5-users-guide-getting-started/1.7/images/install-license-1.png) 3. Choose a destination location, click **Next >**, and then click **Install**. 4. When SSv5 launches, you are presented with one or more additional license agreements. You can accept them individually or all at once. Click **DONE** when finished. ![Review Licenses Dialog showing the Eclipse Foundation Software User Agreement](/ss-5-users-guide-getting-started/1.7/images/install-eclipse-license.png) 5. Next, you are invited to log in. Log in using your Silicon Labs account username and password. **NOTE**: Although you can skip log in here, you must be logged in to access some restricted access software packages. ![Welcome to Simplicity Studio log in dialog](/ss-5-users-guide-getting-started/1.7/images/install-login.png) 6. Before login completes, you must agree to Experience Tracking. You can change the status later in SSv5 Preferences >> Simplicity Studio >> User Experience. ![The experience tracking dialog with the OK control only](/ss-5-users-guide-getting-started/1.7/images/install-experience-tracking.png) 7. If you have hardware connected, depending on your operating system and security settings, you may need to allow SSv5 to make changes to your system. SSv5 prompts you to install the Device Inspector. Click **Yes**. ![Device inspector dialog](/ss-5-users-guide-getting-started/1.7/images/install-device-inspector.png) ##### On Linux Simplicity Studio for Linux® OS is only officially supported on Ubuntu® LTS distributions. Simplicity Studio might work on other distributions, but it is only tested and verified to work with Ubuntu® LTS. The base Simplicity Studio platform (not an installer) is delivered in a tar file that should be expanded into the desired installation directory. The recommended installation directory is the user's root directory (`/home/USERNAME/SimplicityStudio_v5`). This directory must be one that can be updated without root permissions. Before launching Simplicity Studio the first time, execute the following: ```c++ sudo apt-get update sudo apt-get upgrade cd SimplicityStudio_v5 sudo ./setup.sh ``` See Notices for more information on the setup.sh script. When the Simplicity Studio executable 'studio' is launched, it starts a first-time installation process to add support either by a [connected debug adapter](#install-software-by-connecting-devices) or by [technology type](#install-software-by-technology-type). ###### Notices **setup.sh** will: 1. Attempt to install dev rules for USB device connectivity 2. Install missing packages (libraries) through your system's package manager. setup.sh will only install required external Linux® packages on Ubuntu® distributions. For other distributions, the setup.sh script should be examined for a list of possible packages that will need to be installed for Simplicity Studio to work. If **the Wayland display protocol** is being used, start Simplicity Studio from a terminal window with `./studiowayland.sh`. **JxBrowser**: Simplicity Studio uses the third party product JxBrowser to render several windows, including the installation window, Launcher perspective and Project Configurator windows. By default JxBrowser expands the Chromium browser into the /tmp folder. If this is not a good option because of file permissions of the /tmp folder, the location can be changed by adding a line to the studio.ini file specifying a different path such as: `-Djxbrowser.chromium.dir=/home/USERNAME/.jxbrowser` #### Install Software After SSv5 installation is complete, you are prompted to install software packages, such as the Gecko SDK (GSDK). SSv5 offers two options: - [Install by Connecting Device(s)](#install-software-by-connecting-devices) - [Install by Technology Type](#install-software-by-technology-type) You do not need to have a target device connected to install by Technology Type. ![Installation Manager dialog with Install by connecting device(s) selected](/ss-5-users-guide-getting-started/1.7/images/install-method.png) ##### Install Software by Connecting Devices 1. Make sure you have a device connected and click **Install by Connecting Devices**. The connected devices are shown. ![Select Products dialog with one device shown](/ss-5-users-guide-getting-started/1.7/images/install-by-device.png) If you do not see a connected device, or if you connect a device after this dialog is presented, click **Refresh**. If you do not have a device connected you cannot continue. ![Select Products dialog with no devices found](/ss-5-users-guide-getting-started/1.7/images/install-by-device-no-devices.png) 2. Select the device(s) to use. If you select more than one device with different software compatibilities, Studio will download any package that is compatible with any of the devices. Click **NEXT**. 3. You have two installation options, **Auto** and **Advanced**. ![Package installation options dialog with Auto selected](/ss-5-users-guide-getting-started/1.7/images/install-package-options.png) - Select **Auto** to have SSv5 automatically download all packages that are compatible with the connected hardware and to which you have permissions based on your login. - Select **Advanced** to select which packages you want to install or to specify an installation location for the Gecko SDK. If you selected **Advanced**, all 'Required' packages must be installed. **NOTE**: Do not exclude packages unless you understand the full effect of the decision. Click **Read More** to see release notes for each item. Optionally change the default installation location for the Gecko SDK (GSDK). The GSDK installs as a clone of a GitHub repository. Do not select an existing folder with other content already in it, as your cloned repository will no longer be clean. The Matter Enablement Package is automatically selected when you select the GSDK. ![Select Development Packages dialog with all recommended packages selected](/ss-5-users-guide-getting-started/1.7/images/install-package-advanced-device.png) 4. Before package installation begins, accept one or more software license agreements. ![Review Licenses dialog showing the Master software license agreement](/ss-5-users-guide-getting-started/1.7/images/install-software-license.png) 5. Once you click **NEXT**, installation begins. ![Installation dialog with video and progress bar](/ss-5-users-guide-getting-started/1.7/images/install-status.png) Depending upon your selections, installation may take some time. The progress bar may pause at points where large files are being installed, but will resume as they complete. If there is a problem during installation, SSv5 displays an error. You must restart SSv5 to resume. 6. When installation is complete, click **CLOSE**. ![installation dialog with installation complete notice](/ss-5-users-guide-getting-started/1.7/images/install-complete-first.png) 7. Click **RESTART** to begin working with projects. ![installation complete with restart control](/ss-5-users-guide-getting-started/1.7/images/install-complete-restart.png) ##### Install Software by Technology Type 1. Click **Install by Technology Type** 2. Select the technology(s) to install and click **NEXT**. To install the Gecko SDK Suite, select **32-Bit and Wireless MCUs**. The Matter Enablement Package is automatically selected when you select the GSDK. ![Select technology type dialog with GSDK selected](/ss-5-users-guide-getting-started/1.7/images/install-by-technology.png) 3. You have two installation options, **Auto** and **Advanced**. ![Package installation options dialog with Auto selected](/ss-5-users-guide-getting-started/1.7/images/install-package-options.png) - Select **Auto** to have SSv5 automatically download all packages related to the selected technologies and to which you have permissions based on your login. - Select **Advanced** to select which packages you want to install. If you selected **Advanced**, all 'Required' packages must be installed. **NOTE**: Do not exclude packages unless you understand the full effect of the decision. Click **Read More** to see release notes for each item. Optionally change the default installation location for the Gecko SDK. The GSDK installs as a clone of a GitHub repository. Do not select an existing folder with other content already in it, as your cloned repository will no longer be clean. The Matter Enablement Package is automatically selected when you select the GSDK. ![Select Development Packages dialog with all recommended packages selected](/ss-5-users-guide-getting-started/1.7/images/install-package-advanced-technology.png) 4. Before installation begins, accept one or more software license agreements. ![Review Licenses dialog showing the Master software license agreement](/ss-5-users-guide-getting-started/1.7/images/install-software-license.png). 5. Once you click **NEXT**, installation begins. ![Installation dialog with video and progress bar](/ss-5-users-guide-getting-started/1.7/images/install-status.png) Depending upon your selections, installation may take some time. The progress bar may pause at points where large files are being installed, but will resume as they complete. If there is a problem during installation, SSv5 displays an error. You must restart SSv5 to resume. 6. When installation is complete, click **CLOSE**. ![installation dialog with installation complete notice](/ss-5-users-guide-getting-started/1.7/images/install-complete-first.png) 7. Click **RESTART** to begin working with projects. ![installation complete with restart control](/ss-5-users-guide-getting-started/1.7/images/install-complete-restart.png) ### Explore SSv5 When Simplicity Studio® 5 (SSv5) opens, the first screen is the Welcome page within the Launcher perspective. A "perspective" is an Eclipse term for an arrangement of views and an editor area. This page provides an overview of the Launcher perspective's main parts. A detailed reference to all of the functions accessed through the Launcher perspective can be found in the [About the Launcher](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-about-the-launcher) reference section. ![Launcher perspective with editor and views numbered](/ss-5-users-guide-getting-started/1.7/images/launcher-start-numbered.png) 1 - **Editor**. The editor begins in Welcome mode. Here you get started by selecting a part, and then find resources and create projects based on that part. Note that, when you drop down the Learn and Support area, you have access to technical support, the Silicon Labs Community, and educational resources. 2 - **Debug Adapters view**: Shows devices physically connected to your computer with a debug adapter, or detected on a local network. Select a device to begin a project 3 - **My Product view**: Here you can add devices, boards, or kits and select them just like a connected kit. You can then explore resources or create and configure projects for the selected (target) device. 4 - **Menu** and **Toolbar**: Many of the main functions of interest are provided on the toolbar. ![Launcher Toolbar - Home, Recent, Tools, Install, Preferences](/ss-5-users-guide-getting-started/1.7/images/launcher-toolbar.png) - **Welcome** returns you to the Launcher Welcome page. - **Recent** shows you a list of recent projects. Select one to go to that project in the Simplicity IDE Project Explorer view. - **Tools** provides a list of available tools. - **Install** brings you to a menu where you can install or uninstall software packages and tools, or review available updates. - **Preferences** is a shortcut to the list of preferences also available through the menu selection Window > Preferences. Throughout SSv5, the contents of the launcher and other perspectives depends on the device you have selected as your development target, as well as your software environment. When you first open SSv5, the Launcher perspective does not have a target device context. When you connect a kit, it appears both in the the Debug Adapters view and in the device selector in the **Get Started** editor area. ![The selected device area of the Get Started editor showing a connected device](/ss-5-users-guide-getting-started/1.7/images/launcher-part-selected-focus.png) If you don’t have a Silicon Labs kit to connect, but would like to explore more of SSv5’s functions, click **All Products**, and enter a part number for a kit, board, or device. As you type you will be presented with a list. Use the checkboxes to filter the list. ![The selected device area of the Get Started editor showing all products](/ss-5-users-guide-getting-started/1.7/images/launcher-virtual-part-focus.png) You can also add products to the My Products view, and select a target device there. If you have added a product under **Get Started**, once you click **Start** the selected product is added to the My Products view for easy access in the Welcome page or other Launcher perspective views. Once you have connected or selected a target device, click **Start** to move to the Launcher perspective's OVERVIEW tab, showing the details about that device. ![launcher perspective with device-specific functions](/ss-5-users-guide-getting-started/1.7/images/launcher-selected.png) You'll find several "cards" on the OVERVIEW tab. The first is the **General Information** card where you can update the debug adapter firmware of your Silicon Labs kits, change the mode of the debug adapter, manage the security settings of the target device (if applicable), and change the active/preferred SDK. ​The **Recommended Quick Start Guides** card highlights some of the getting-started resources available for the selected target device. Click **All Quick-Start Guides** to quickly go to the DOCUMENTATION tab, pre-filtered for quick-start guides. ​ Cards are also available for each board and device of the selected target. The **View Documents** drop-down list on each hardware card provides a filtered view of hardware documentation for that item. You can start a project with the **Create New Project** control. See [Start a Project](start-a-project) for an introduction to creating projects. The EXAMPLE PROJECTS & DEMOS tab shows a list of example projects and demos compatible with the selected device. A demo is a prebuilt software example that can be loaded into a compatible device and used to show and test application functionality. Every demo comes with an associated example project. See the Quick Start Guide for your SDK for more information about the examples and demos provided. Use the checkboxes and search box to filter the list. A number of different filter categories are available. The categories and filters displayed depend on your selected device. Click **RUN** on any demo to install it on a target device. Click **CREATE** on any project to create it. This is equivalent to creating a project from the OVERVIEW tab, except that the project is already selected. ![the demos & example projects tab with technology filter applied](/ss-5-users-guide-getting-started/1.7/images/launcher-tab-demos-and-examples.png) The DOCUMENTATION tab shows all documentation compatible with the selected device. Use the checkboxes or text filter field to find a resource of interest. The technology filter corresponding to your development environment will show you most software documents relevant to that environment. ![the documentation tab with no filters applied](/ss-5-users-guide-getting-started/1.7/images/launcher-tab-documentation.png) The COMPATIBLE TOOLS tab shows the tools compatible with the selected device. The Tools button on the toolbar shows all tools unfiltered. ![the compatible tools tab](/ss-5-users-guide-getting-started/1.7/images/launcher-tab-tools.png) ### Start a Project Simplicity Studio® 5 (SSv5) supports several different project types, which can be created through **File > New**. These include: - Silicon Labs Project Wizard (creates Project Configurator projects, as described in this section) - Solution... (creates a combination of two or more projects) - Project... (opens the New Project Wizards dialog) - Other (combines all of the above selections with other, rarely used options) Select **Files > New > Project** to open the New Project Wizards dialog. ![New project wizards](/ss-5-users-guide-getting-started/1.7/images/new-project-wizards.png) Most notably: - Silicon Labs Project Wizard (two instances) and also Silicon Labs MCU Project Wizard: Creates Project Configurator projects, as described in this section. - AppBuilder Project Wizard: Creates a legacy [AppBuilder Project](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-with-appbuilder) This page focuses on Project Configurator (*.slcp) projects, as well as Solutions, or combinations of Project Configurator projects. On this page: - [Configurator Project Creation](#project-creation) - [Target, SDK, and Toolchain Selection](#target-sdk-and-toolchain-selection) - [Examples](#examples) - [Configuration](#configuration) - [About Project Configurator Projects](#project-configurator-projects) - [Pin Tool](#pin-tool) - [Bluetooth GATT Configurator](#bluetooth-gatt-configurator) - [Bluetooth Mesh Configurator](#bluetooth-mesh-configurator) - [Proprietary Radio Configurator](#proprietary-radio-configurator) - [Wi-SUN Configurator](#wi-sun-configurator) - [ZCL Advanced Platform](#zcl-advanced-platform) - [About Solutions](#solutions) - [About AppBuilder Projects](#app-builder-projects) #### Project Creation New Simplicity Studio® 5 (SSv5) projects are created through a sequence of three dialogs: - [Target, SDK, and Toolchain](#target-sdk-and-toolchain-selection) - [Examples](#examples) - [Configuration](#configuration) ![The three project creation dialogs in sequence](/ss-5-users-guide-getting-started/1.7/images/new-project-3-dialogs-bigger.png) An indicator at the top of the dialog shows you where you are. ![the sequence indicator positioned on target SDK](/ss-5-users-guide-getting-started/1.7/images/new-project-place-indicator.png) You can start a project from three different locations in the Launcher Perspective. Where you start determines which of the three dialogs you will land on. Click **BACK** to move to an earlier dialog, if you need to make a change. - **From the OVERVIEW tab:** Click **Create New Project**. Starts on the Examples dialog. - **From the EXAMPLE PROJECTS tab:** Use the filters as needed, select a project, and click **CREATE**. Starts on the Project Configuration dialog. - **From the file menu**: Select New >> Silicon Labs Project Wizard. Starts on the Target, SDK, and Toolchain Selection dialog. While you are getting started, you can leave the default values in place. ##### Target, SDK, and Toolchain Selection If you have connected or selected a target, all information is pre-populated. Otherwise you can select target parts here. Click **NEXT**. ![Target, SDK, and Toolchain selection dialog, with the default GNU ARM toolchain](/ss-5-users-guide-getting-started/1.7/images/new-project-target.png) **IDE / Toolchain** has several options, not all of which are used within the Simplicity IDE. In those cases the project still shows up in the Simplicity IDE Project Explorer view, but you use the IDE for which the project was created to build and debug the project. - Simplicity IDE / GNU ARM vn.n.n: This is the default toolchain used when Simplicity Studio is first installed. The Simplicity IDE is used for all project operations - editing source files, building the project, debugging the project. If multiple version of the GNU ARM Toolchain are installed, there are options for each version. - Simplicity IDE / IAR ARM vn.n.n.n: Similar to the first option, but builds use the IAR ARM toolchain. The IAR ARM toolchain requires installation of IAR Embedded Workbench (EW) external to Simplicity Studio and a license for IAR EW must be purchased from IAR. All project operations are still performed inside the Simplicity IDE. - Makefile IDE (use Simplicity Studio tools to configure and, with a manual step, to debug the project but use 'make' to build the project): This option creates a project without a Simplicity IDE build configuration and [No toolchain] will be reported. Instead, PROJECTNAME.Makefile and PROJECTNAME.project.mak files are created. They are used from a command prompt or terminal prompt with 'make -f PROJECTNAME.Makefile' to build the project. The Project Configurator (.slcp file) can be used to add / configure / remove software components and the various Advanced Configurators, such as Pintool, Bluetooth Gatt Configurator, or ZCL Advanced Platform, can also be used to configure and generate the project. It just cannot be built from within Simplicity Studio. Also the project cannot be automatically debugged within Simplicity Studio. You must manually create a debug configuration that points to the build .out file. - Visual Studio Code: This option allows you to use Visual Studio Code in combination with Simplicity Studio. Use Simplicity Studio to create the initial project and to make project changes with the Component Editor and various Advanced Configurators. Then do all editing, building, and debugging of the project in VS Code. See the [Visual Studio Code](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-vscode-ide) page for more information. - CMake: This option creates both the Simplicity Studio .slcp file and a CMake build configuration during project generation. It is designed to be built from the command line. It will generate CMake support for both the GCC compiler and the IAR compiler by default, in separate directories. The dependent compiler must be present on the system. Studio can install the GCC compiler. The IAR compiler must be purchased and installed separately. The Project Configurator (.slcp file) can be used to add / configure / remove software components and the various Advanced Configurators, such as Pintool, Bluetooth Gatt Configurator, or ZCL Advanced Platform, can also be used to configure and generate the project. - IAR Embedded Workbench (use Simplicity Studio tools to configure the project but IAR EW to build and debug the project): This option creates a project with the IAR EW projects files but without a Simplicity IDE build configuration and [No toolchain] will be reported. As with the Makefile IDE, the Project Configurator (.slcp file) can be used to add / configure / remove software components and the various Advanced Configurators can also be used to configure and generate the project. After that, double-click the .eww file to launch IAR EW for building and debugging the project. Project options should be set in IAR EW. You cannot use the Simplicity IDE and IAR EW interchangeably. All operations except project configuration should be done in IAR EW. ##### Examples Use the checkboxes or keywords to find the example of interest, then select it and click **NEXT**. ![New Project examples filtered by Proprietary Flex](/ss-5-users-guide-getting-started/1.7/images/new-project-examples.png) ##### Configuration Rename your project if you want. The three selections under "With project files" control which sources are copied and which are linked. If a linked source is modified, the changes apply to any other project linking to that source. - Link to sources: The project links both to the SDK files and to project files such as app.c. - Link SDK and copy project sources (default): Project sources are copied to your workspace. Note that the SDK folder structure is created but if you drill down you will see that all folders are empty. - Copy contents: Both project files and the SDK files are copied to your workspace. Click **FINISH**. ![New project configuration linking to the sdk and copying project source](/ss-5-users-guide-getting-started/1.7/images/new-project-config.png) Once you finish project creation, the Simplicity IDE perspective opens. There may be a slight delay for initial configuration. For details on all the features and functions available in this perspective, see [About the Simplicity IDE](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-about-the-simplicity-ide). ![simplicity IDE with editor and views numbered](/ss-5-users-guide-getting-started/1.7/images/new-project-ide-numbered.png) 1 - **Editor area** (depends on the project). 2 - **Project Explorer** view: Lists the projects and solutions available in your workspace. 3 - **Debug Adapters** view: Lists the kits or SEGGER J-Links connected to your computer via USB or detected on a local network. 4 - **Developer** views: A set of views of use during the development process. The editor in the Simplicity IDE perspective depends on the project: - [Project Configurator](#project-configurator-projects): Used for all Gecko SDK protocols and tools beginning with Gecko SDK 4.0; Project files end in .slcp. - [8-bit Hardware Configurator](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-for-8bit-devices/using-hardware-configurator): Used for 8-bit device applications. - [AppBuilder](#app-builder-projects): Legacy tool used for Zigbee EmberZNet and Gecko Bootloader in Gecko SDK 3.2 and lower; Project files end in .isc. #### Project Configurator Projects As well as introducing Project Configurator projects, this page also introduces - The [Pin Tool](#pin-tool) - Bluetooth and Bluetooth Mesh SDK's [GATT Configurator](#bluetooth-gatt-configurator) - Bluetooth Mesh SDK's [Bluetooth Mesh Configurator](#bluetooth-mesh-configurator) - Proprietary SDK's [Radio Configurator](#proprietary-radio-configurator) - Zigbee EmberZNet and Matter SDK's [ZCL Advanced Platform](#zcl-advanced-platform) - Wi-SUN SDK's [Wi-SUN Configurator](#wi-sun-configurator) Project Configurator projects are defined in **.slcp** (Silicon Labs Configurator project) files. Users can modify the project by adding, removing, and configuring components on the Software Components tab. See [Developing with Project Configurator](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-with-project-configurator) for details. NOTE: Beginning with Simplicity Studio version 5.3, you can create a project in the Simplicity IDE by importing an .slcp file. See [Import and Export](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-about-the-simplicity-ide/import-and-export) for more information. The project opens, generally either on a README tab containing an example project description, or on an OVERVIEW tab. ![Project configurator with overview tab selected.](/ss-5-users-guide-getting-started/1.7/images/new-project-project-config-general.png) The OVERVIEW tab has three cards with information, some with settings that may be changed: - **Target and Tool Settings**, where you can change your development target, SDK, and project generators. Scroll down and click **Change Target/SDK/Generators** to edit these settings. The Project Generators configuration determines the IDE or build system project files that SSv5 generates as you configure your project. (Note: The compiler / toolchain used by Simplicity IDE is configurable in **Project > Build Configurations**. The default IDE is configurable in **Preferences > Simplicity Studio > Preferred IDE**.) - **Project Details**, where you can rename the project, change the project source import mode, generate a project report and, if necessary, force the generation of project and source files (in the _autogen_ folder). - **Generate Project Report** creates a PDF, available through a link immediately above the control, that provides details on: - Target hardware device - Target hardware device pin mapping - Target SDK - Software extensions used in the build - Installed application, utility, and platform software components - **Import mode** controls which resources are copied and which are linked. If you modify a linked source, your changes apply to any other project linking to that source. - **Force Generation** (available through the **...** drop-down menu) can be used in rare cases when auto-generation is not triggered, usually because of some change made outside of SSv5 such as editing the .slcp file. - **Quick Links** provides links to the tools commonly used to modify the project or lower-level configurations such as radio or peripheral connections. The links vary based on the SDK and target device. ![Project Configurator Overview tab with the three cards](/ss-5-users-guide-getting-started/1.7/images/new-project-project-config-general-edit.png) To configure the project through the component library, click the SOFTWARE COMPONENTS tab. A number of filters as well as a keyword search are available to help you explore the various component categories. The **SDK Extensions** filter is only enabled if you have an extension installed. Note that components for all installed SDKs are presented. ![Project Configurator with Software Components tab open](/ss-5-users-guide-getting-started/1.7/images/new-project-project-config-components.png) Expand a component category\subcategory to see individual components. Components installed in the project are checked (1), and can be uninstalled. Configurable components are indicated by a gear symbol (2). ![Software Components tab with a checked project and a configurable project in the left panel indicated by numbers](/ss-5-users-guide-getting-started/1.7/images/new-project-project-config-component-detail.png) Click the gear symbol next to the component name or **Configure** in the configurable component description to open the Component Editor. Here you can change parameters or edit the component source directly. You can also go from the component to the [Pin Tool](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-with-project-configurator/pin-tool) ![Component editor open on the Bluetooth Core component](/ss-5-users-guide-getting-started/1.7/images/new-project-project-config-component-editor.png) Changes are autosaved in the Component Editor. ![Component editor with saved changes](/ss-5-users-guide-getting-started/1.7/images/new-project-config-component-saved.png) As you make changes in the Project Configurator, for example installing or uninstalling a component, project output files are autogenerated. Progress is shown in the lower right of the Perspective. ![Generation and indexing progress bars](/ss-5-users-guide-getting-started/1.7/images/new-project-generate.png) Speed varies depending on your system. Be sure that generation is complete before building the application image. Build the application image and flash it to your target device as described in [Building and Flashing](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-building-and-flashing). A CONFIGURATION TOOLS tab provides an easy way to open a tool when the tool's tab is not already open, as an alternative to the Quick Links card on the general tab. It shows configuration tools relevant to the project type. For example, a Bluetooth Mesh project shows a number of tools, while an OpenThread project might only show the Pin Tool. Click **Open** on the tool's card to open it in a separate tab. ![Project Configurator Configuration tools tab](/ss-5-users-guide-getting-started/1.7/images/new-project-project-config-configuration-tools.png) ##### Pin Tool The [Pin Tool](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-with-project-configurator/pin-tool) lets you modify the target device's pin use and parameters. As well as opening the Pin Tool through the CONFIGURATION TOOLS tab, you can also double-click the .pintool file in the Project Explorer view. ![Pin tool tab](/ss-5-users-guide-getting-started/1.7/images/new-project-pin-tool.png) Double-click a Software Component to open the Component Editor and configure that function. Pin Tool does not autosave. ##### Bluetooth GATT Configurator Bluetooth and Bluetooth Mesh projects are also configured with the [Bluetooth GATT Configurator](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-with-project-configurator/bluetooth-gatt-configurator). ![GATT configurator tab](/ss-5-users-guide-getting-started/1.7/images/new-project-gatt-configurator.png) The Bluetooth GATT configurator menu allows you to add and remove services and characteristics. ![GATT configurator menu with numbered controls](/ss-5-users-guide-getting-started/1.7/images/new-project-gatt-configurator-menu.png) 1. Add an item. 2. Duplicate the selected item. 3. Move the selected item up. 4. Move the selected item down. 5. Import a Bluetooth GATT database. 6. Add Predefined. 7. Delete the selected item. To add a custom service, click **Profile (Custom BLE GATT)**, and then click **Add** (1). To add a custom characteristic, select a service and then click **Add** (1). To add a predefined service/characteristic click **Add Predefined** (6). ##### Bluetooth Mesh Configurator Bluetooth Mesh project Device Composition Data is configured through the [Bluetooth Mesh Configurator](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-with-project-configurator/bluetooth-mesh-configurator). The Device Composition Data is presented in three areas: device information, elements, and models. ![Mesh configurator tab](/ss-5-users-guide-getting-started/1.7/images/new-project-mesh-configurator.png) Device information is determined by the company selected in the first field. Each node has at minimum a primary element. To add more elements click the green + symbol in the bottom right. The Bluetooth Mesh Configurator has editors for both SIG-adopted models and vendor models. SIG-adopted model components are provided but cannot be edited. You can, however, delete those models, and then add models to meet your needs. To delete a model, select it and click the red X symbol. To add a SIG-adopted model, drag the model from the left model pool to the SIG Models table in the correct element. A list of all the SIG-adopted models is displayed, and you can choose the one you want. ![SIG-Adopted Model Editor](/ss-5-users-guide-getting-started/1.7/images/mesh-conf-sig-adopted-model-editor.png) Vendor models give you more flexibility when developing products not covered by the SIG-adopted models. Vendors can define their own specification in these vendor models, including states, messages, and the associated behaviors. The vendor model editor is shown in the following figure. ![Vendor Model Editor](/ss-5-users-guide-getting-started/1.7/images/mesh-conf-vendor-model.png) ##### Proprietary Radio Configurator The [Radio Configurator](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-with-project-configurator/proprietary-radio-configurator) is provided as part of the Proprietary SDK. Use the Radio Configurator to create standard or custom radio configurations for your RAIL-based radio applications. ![Configuration tools tab with Radio Configurator](/ss-5-users-guide-getting-started/1.7/images/radio-conf-start.png) The parameters in the Radio Configurator are arranged in cards, some of which are grouped together. Different radio profiles offer different views and parameter sets. ![Radio Configurator showing general settings and channels overview cards](/ss-5-users-guide-getting-started/1.7/images/radio-conf-parameter-tiles.png) 1. In the General Settings card, select a radio profile in the **Select radio profile** drop-down menu. A radio profile may be any supported radio link technology. These technologies can be bound by standards (for example the Sigfox or WMBus protocols) or can be fully customized. The fully customizable profile is called the "Base Profile". 2. Select a radio PHY (radio configuration) in the **Select a radio PHY** dropdown list. Each profile has "built-in" configurations ready to use. 3. Review and update the profile options. By default, no changes are allowed; fields are grayed out. To enable customization, use the **Customized** switch on the General Settings card. This allows access to all the parameters defined by the profile. ![General settings card showing the customized switch](/ss-5-users-guide-getting-started/1.7/images/radio-conf-customize-slider.png) ##### Wi-SUN Configurator The [Wi-SUN Configurator](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-with-project-configurator/wi-sun-configurator) is provided as part of the Wi-SUN SDK. Use it to configure the main settings of the Wi-SUN application through three panels: Application, Security, and Radio. For some projects only the Radio panel is available. The Wi-SUN Configurator tab is available when a project is created or can be displayed by opening the project file /config/wisun/wisun_settings.wisunconf. ![Wi-SUN Configurator application tab](/ss-5-users-guide-getting-started/1.7/images/new-project-wisun-configurator.png) ##### ZCL Advanced Platform The [ZCL Advanced Platform (ZAP)](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-with-project-configurator/zigbee-cluster-configurator) is provided as a configuration tool for both Zigbee and Matter projects. Use it to manage endpoints, clusters, and commands. The interface, which differs slightly for Matter and Zigbee, is based on adding or modifying endpoints. Click an endpoint to open the configuration editor. ![Zigbee Cluster Configurator with an endpoint selected](/ss-5-users-guide-getting-started/1.7/images/zap-with-clusters.png) You can add and configure clusters as needed. Configuration changes made through the Zigbee Cluster Configurator for a Zigbee project are saved to \config\zcl\zcl_config.zap. For a Matter project the configuration is saved to \config\zap\.zap. When you save the file, the Zigbee Cluster Configurator not only saves the .zap file into your project, but also automatically generates all the files required for your application. #### Solutions A [Solution](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-with-project-configurator/project-solutions) is a combinations of projects that can be compiled, debugged, and flashed together. Solutions are also called workspaces in some contexts. The projects in a solution can be configured individually. When the solution is built, the [Post-Build Editor](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-building-and-flashing/post-build-editor) is used to combine the project images into a single downloadable .s37 image. Applications that make use of the Series 2 TrustZone feature use solutions to combined the secure and non-secure TrustZone projects. Solutions can also be used to debug an application and its bootloader together. The [Memory Editor](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-with-project-configurator/memory-editor) is a graphical tool for editing the flash and RAM memory layout of the applications in a solution. Not all example projects have default settings included at this time, which results in a warning when you open the editor. Save the default values that the tool calculates as your starting point. ![Memory Editor RAM view](/ss-5-users-guide-getting-started/1.7/images/new-project-memory-editor.png) #### AppBuilder Projects AppBuilder Projects are configured by modifying parameters in various tabs, especially the PLUGINS tab. See [Developing with AppBuilder](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-with-appbuilder) for details. ![Simplicity IDE with the AppBuilder editor](/ss-5-users-guide-getting-started/1.7/images/new-project-appbuilder.png) When you have configured the project, click **Generate** to create project files. Build the application image and flash it to your target device as in [Building and Flashing](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-building-and-flashing). ![AppBuilder editor with Generate control highlighted](/ss-5-users-guide-getting-started/1.7/images/new-project-appbuilder-generate.png) To modify the target device's pin use and parameters, use the [Hardware Configurator](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-with-appbuilder/configuring-peripherals) available on the HAL tab. Note that, although the interface is similar to the 8-bit Hardware Configurator, this is a different tool. ![general tab with Hardware Configurator Interface highlighted](/ss-5-users-guide-getting-started/1.7/images/new-project-hardware-configurator.png) Changes made through the Hardware Configurator are stored in a board-specific .hwconf file. ### Install SDK Extensions An SDK Extension is an entity specific to developing for 32-bit devices using Project Configurator and other Silicon Labs Configurator (SLC)-based tools. It is a collection of components and other items, such as example files. The SDK extension has dependencies on the parent SDK, which must be installed first. SDK extensions can be used to control access to certain functions, or to contain customer-created components and other items to be maintained separately from the Silicon Labs SDK. SDK extensions are installed as part of the GSDK through the standard installation dialog. ![Select technology type dialog with GSDK selected](/ss-5-users-guide-getting-started/1.7/images/install-by-technology.png) If you already have a GSDK installed but did not installed the extension, you can install it by clicking **Install** on the toolbar, and then clicking **Manage Installed Packages**. Open the SDK tab, and click **Install** next to the extension name. ![Package Manager SDK tab showing the Matter Enablement Package tile](/ss-5-users-guide-getting-started/1.7/images/launcher-package-manager-tab-sdks.png) See update information in [About the Launcher](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-about-the-launcher/toolbar#install) for additional details. Once you have added an SDK extension, SSv5 treats it like any other SDK, such as showing it in the filter for example projects. ![Matter highlighted on the preferences dialog](/ss-5-users-guide-getting-started/1.7/images/sdk-extension-filter.png) If you have been given an extension package that is not yet part of the standard installation, you can install it using using the following procedure. 1. Open Preferences > Simplicity Studio > SDKs either from Preferences on the toolbar or by selecting **Manage SDKs** from the Launcher perspective OVERVIEW tab. Select the parent SDK and click **Add Extensions**. ![Add extensions highlighted on the preferences dialog](/ss-5-users-guide-getting-started/1.7/images/sdk-extension-preferences.png) 2. In the Add SDK Extensions dialog, browse to the extension directory. If it has a valid SDK extension, SSv5 detects it. Click **OK**. ![Add extensions dialog with a valid extension](/ss-5-users-guide-getting-started/1.7/images/sdk-extension-add.png) 3. You may be asked to trust the SDK extension. If you do, click **Trust**. ![Trust extension dialog](/ss-5-users-guide-getting-started/1.7/images/sdk-extension-trust.png) 4. The extension is now displayed under the GSDK, and in the list of GSDK components. Click **Apply and Close**. ![HomeKit highlighted on the preferences dialog](/ss-5-users-guide-getting-started/1.7/images/sdk-extension-apply.png) ### Upgrading a Project to a New Software Version #### Upgrading to a New GSDK If a project was created with an older GSDK, and a new GSDK version is installed, the upgrade process starts differently depending on if the existing GSDK itself was upgraded to the latest version or if the latest GSDK was installed as a separate GSDK instance. 1. If a parallel instance of the new GSDK was installed, then the project upgrade must be started from the Project Configurator Overview tab, Target and Tool Settings card. Click **Change Target/SDK/Generators**. Click the **CHANGE SDK** drop down and select the desired GSDK. ![Upgrading with a second instance](/ss-5-users-guide-getting-started/1.7/images/upgrade-project-with-second-instance.png) A Verify SDK dialog is displayed. ![Upgrading with a second instance](/ss-5-users-guide-getting-started/1.7/images/upgrade-project-with-second-instance-verify.png) 2. If the GSDK was upgraded to the latest version, when the project's .slcp file is opened the Verify SDK dialog is displayed immediately. ![verify upgrading SDK](/ss-5-users-guide-getting-started/1.7/images/upgrade-project-with-old-sdk.png) From this point the process is the same. The displayed preferred Gecko SDK is the latest version. Click **Verify**. The Gecko SDK and Advanced configurator upgrade scripts (if any exist) are run and then a dialog something like the following is displayed. The dialog may include additional messages and warnings. ![upgrade analysis](/ss-5-users-guide-getting-started/1.7/images/upgrade-project-project-is-upgradable.png) Click **Upgrade**. The results of the upgrade are displayed. After the upgrade finishes, build the project and then manually resolve any issues that occur due to SDK changes. Reviewing the release notes for the SDK and Gecko Platform is recommended to see what new features are available. These are available through the Launcher perspective's Documentation tab (filter on Release Notes) or on silabs.com at [https://www.silabs.com/developers/gecko-software-development-kit](https://www.silabs.com/developers/gecko-software-development-kit). #### Upgrading to a New Extension Simplicity Studio also checks if there are any missing extensions required by the project. If so, Simplicity Studio presents a similar dialog to the GSDK verify dialog with either an available upgradeable extension or an error if no upgradeable extension can be found. Extensions can be upgraded independently of the GSDK. All available extensions will appear in the Software Components tab. When viewing a newer extension, Simplicity Studio will check if you can upgrade to it and presents an Upgrade Extension notification instead of the standard Install Extension. If selected, this will launch the Extension Upgrade dialog. ![extension upgrade](/ss-5-users-guide-getting-started/1.7/images/sdk-extension-upgrade.png) If you click **UPGRADE EXTENSION**, a verification dialog is displayed similar to that for the SDK. ### Project Migration #### Moving to the Component-Based Architecture In SSv5 version 5.3, the Gecko Bootloader, Zigbee, and Z-Wave changed to the Silicon Labs Configurator component-based architecture. For more information on transitioning these projects from earlier versions of SSv5 see: - Zigbee [AN1301: Transitioning from Zigbee EmberZNet SDK 6.x to SDK 7.x](https://www.silabs.com/documents/public/application-notes/an1301-zigbee-v6x-to-v7x-transition-guide.pdf) - Gecko Bootloader [AN1326: Transitioning to the Updated Gecko Bootloader in GSDK 4.0 and Higher](https://www.silabs.com/documents/public/application-notes/an1326-gecko-bootloader-transitioning-guide.pdf) #### Migrate from Simplicity Studio 4 to Simplicity Studio 5 The process to migrate a project from Simplicity Studio® 4 (SSv4) to SSv5 depends on the type of project. If you are migrating a [Bootloader, EFM32, or EFM8 project](#bootloader-efm32-and-efm8-projects), use the **Migrate Project** tool. If you are migrating a [Z-Wave](#z-wave-projects), [Bluetooth/Bluetooth Mesh, Proprietary Flex, or Zigbee project](#zigbee-flex-and-bluetooth-bluetooth-mesh-projects), follow the instructions in the specified documents. ##### Bootloader, EFM32, and EFM8 Projects **Bootloader note**: Use this procedure as a first step in migration. Click the **Tools** toolbar button to open the Tools dialog. Select **Migrate Projects** and click **OK**. Select the project to be migrated and click **Next**. ![migrate start](/ss-5-users-guide-getting-started/1.7/images/migrate-start.png) Verify the information displayed and click **Next**. ![migrate verify](/ss-5-users-guide-getting-started/1.7/images/migrate-verify.png) Decide if you want to copy the project (recommended) and click **Finish**. ![migrate copy](/ss-5-users-guide-getting-started/1.7/images/migrate-copy.png) The project is migrated from SSv4 to SSv5. ![migrate success](/ss-5-users-guide-getting-started/1.7/images/migrate-success.png) ##### Z-Wave Projects (Through Simplicity Studio 5.2) Follow the instructions in the knowledge base article [Migrating a Z-Wave project from GSDK 2.7.6 to GSDK 3.0.0](https://www.silabs.com/community/software/simplicity-studio/knowledge-base.entry.html/2020/07/17/migrating_a_z-waveprojectfromgsdk276togsdk-opdc). ##### Zigbee, Flex, and Bluetooth/Bluetooth Mesh Projects These projects cannot be migrated using the tool. Instead, refer to the following documents: - Zigbee (Through Simplicity Studio 5.2): [QSG106: Getting Started with EmberZNet PRO](https://www.silabs.com/documents/public/quick-start-guides/qsg106-efr32-zigbee-pro.pdf) - Flex: [AN1254: Transitioning from the v2.x to the v3.x Proprietary Flex SDK](https://www.silabs.com/documents/public/application-notes/an1254-transitioning-from-proprietary-flex-sdk-v2-to-v3.pdf) - Bluetooth: [AN1255: Transitioning from the v2.x to the v3.x Bluetooth SDK](https://www.silabs.com/documents/public/application-notes/an1255-transitioning-from-bluetooth-sdk-v2-to-v3.pdf) - Bluetooth Mesh: [AN1298: Transitioning from the v1.x to the v2.x Bluetooth Mesh SDK](https://www.silabs.com/documents/public/application-notes/an1298-transitioning-from-bluetooth-mesh-1x-to-2x.pdf) If you try using the tool, in most cases the tool will point you to the documentation for the migration process. ![migrate incompatible](/ss-5-users-guide-getting-started/1.7/images/migrate-incompatible.png) ## About the Launcher ### About the Launcher This section provides a reference to the functionality available in Simplicity Studio® 5 (SSv5) when you first open the application. This first perspective is called the **Launcher perspective**. A "perspective" is an Eclipse term for an initial arrangement of views and an editor area. ![Launcher perspective with numbered views and areas](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-start-numbered.png) 1 - [Welcome and Device-Specific Tabs](welcome-and-device-tabs): The Welcome page includes a Get Started section to help with target kit, board, or device selection. The Learn and Support section may be expanded to show some of the reference and support resources available. Once a device is connected and/or selected, device-specific tabs provide access to example projects, documentation, and so on. 2 - [Debug Adapters](debug-adapters): Silicon Labs kits and supported debug adapters (for example, SEGGER J-Link products). The icon to the left of the debug adapter item indicates if it is connected over USB or Ethernet. 3 - [My Products](my-products): Shows an editable list of products that you may want to use as target devices to set the Launcher's context. Use this view to select target devices when you don't have a kit available. 4 - A top-level [menu](menu) provides access to a number of functions, including configuration options and help. A [toolbar](toolbar) offers access to tools and functions on the left and shortcuts to different perspectives on the right. 5 - The Launcher perspective also provides additional functions across the bottom of the perspective: ![Launcher bottom bar with login menu open and garbage collection on the right](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-bottom-menu.png) - Log in menu. Here you can: - Log in or out - Register a software development kit. - Change users - Clear stored credentials - Garbage collection status and clear function. Click the trash can to run the garbage collector. This releases memory that may not have been released automatically. You should not need to use this function during normal operation. To turn the display off, go to **Preferences > General** and uncheck **Show heap status**. 6 - A perspectives tool bar in the top right shows open perspectives and allows you to open others. Click **Open Perspective** to see a list of available perspectives. The perspectives list is similar to that available through the **Window > Perspective** menu selection. Right-click an open perspective to see the context menu. While you can customize the perspective through the **Customize** menu option (see **Help > Help Contents > Workbench User Guide** for more information), you can also customize a perspective by dragging views and opening and closing views. These changes are persistent and survive closing and reopening a perspective. Click **Reset** to restore the perspective to its default settings. ![The list of perspectives on the left and the launcher context menu on the right](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-perspectives-menu.png) Not all functions available through the Launcher perspective are relevant to developing for all target devices. The **Developing for ...** pages highlight the key pieces for each device category. ### Welcome and Device Tabs This page describes the functionality available on the [Welcome page](#welcome) and the [tabbed interface](#device-specific-tabs) that is displayed once you connect or selected a devices. Tabs include: - [Overview](#overview-tab) - [Example Projects & Demos](#example-projects-demos-tab) - [Documentation](#documentation-tab) - [Compatible Tools](#compatible-tools-tab) #### Welcome Simplicity Studio® 5 (SSv5) opens to a Welcome page. ![The SSv5 Welcome page](/ss-5-users-guide-about-the-launcher/0.9/images/welcome-screen.png) To return to the Welcome page at any time, click **Welcome** on the tool bar. ![welcome icon](/ss-5-users-guide-about-the-launcher/0.9/images/welcome-icon.png) On the Welcome Page you can: - [Select a target device](#select-a-target-device) - [Start a new project](#start-a-new-project) - [Access educational and support resources](#learn-and-support) ##### Select a Target Device SSv5’s purpose is to provide a development environment directed toward a specific target device. Therefore, one of the first things to do is to define that target device. Once a target device is selected, a tabbed interface to features specific to that device is available, starting on the [Overview tab](#overview-tab). The device can be a physical piece of hardware, or a virtual part. **Physical** If you have one or more devices physically connected, either on a development kit or on customer hardware with a supported debug adapter, they are displayed in the [Debug Adapters](debug-adapters) view, where you can get started simply by clicking a device to selected it. They are also displayed in the Get Started area’s **Connected Devices** drop down. Clicking a device to select it, then click **Start**. **Virtual** If you do not have a physical device, but would like to explore some of SSv5’s functions, or get started with developing for a part you will receive later, select a virtual device either in the My Products view or in the Get Started area. In the [My Products](my-products) view, start typing a product name and select the product of interest. Under Get Started, click **All Products**. Use the checkboxes to limit the search list to kits, boards, or parts. Click in the search products field and start typing. When you see the target, select it and click **Start**. The next time you return to the Welcome page, that device will be shown in the My Products view. ![welcome all products](/ss-5-users-guide-about-the-launcher/0.9/images/welcome-all-products.png) ##### Start a New Project You can start a new project from the Welcome page, but you must immediately select a target device. See [Start a Project](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-getting-6/start-a-project) for more information. ![welcome new project](/ss-5-users-guide-about-the-launcher/0.9/images/welcome-new-project.png) ##### Learn and Support Expand the Learn and Support section for access to a variety of resources related to developing for a Silicon Labs target. ![welcome learn and support](/ss-5-users-guide-about-the-launcher/0.9/images/welcome-learn-and-support.png) #### Device-Specific Tabs Device-Specific tabs include: - [Overview](#overview-tab) - [Example Projects](#example-projects-demos-tab) - [Documentation](#documentation-tab) - [Compatible Tools](#compatible-tools-tab) ##### Overview Tab Once you have selected a target device, the Launcher perspective editor area changes to the OVERVIEW tab specific to that part. For a physically-connected device you have [general device information](#general-device-information), as well as details about the hardware components. Each hardware component is pictured in a card and has a **View Documents** drop down where you can see related hardware documentation. Finally, links to recommended quick start guides from compatible protocol SDKs are provided. ![launcher tab overview physical](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-tab-overview-physical.png) SSv5 displays similar information for virtual devices (selected in the My Products view) and devices connected to a supported debug adapter (for example, SEGGER J-Link or a Wireless Starter Kit mainboard in debug OUT mode). The settings in the General Information card vary depending on the target device. ![launcher tab overview virtual](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-tab-overview-virtual.png) ###### General Device Information **Configure Connection** Device Connection shows how the device is connected to SSv5. Click **Configure** to explore or modify connection parameters. If your device firmware is not up to date, you will be invited to update it. ![launcher device firmware update](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-device-firmware-update.png) If you are targeting an EFR32-based Silicon Labs kit, you will almost certainly also see the following question: ![launcher device ctune](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-device-ctune.png) The CTUNE value is used to tune the external crystal capacitors to hit the exact frequency they are intended to hit. Because this varies from board to board, in production Silicon Labs measures it during board tests and programs a unique CTUNE value for each board into the EEPROM. Each SDK also has a default CTUNE value programmed in a manufacturing token. This message asks if you want to overwrite the default CTUNE value with the one found in the EEPROM. Because the EEPROM value is more accurate, Silicon Labs recommends you click **Yes**. The default CTUNE value will also work, but could under some circumstances, such as temperature extremes, bring the radio frequency out of spec. **Debug Mode** The Debug Mode controls the interface to the wireless starter kit mainboard onboard debugger. Changing Debug Mode opens the Adapter Configuration tab of the J-Link Configuration tool. The debug modes are: - **Onboard Device (MCU)** (default): The debugger built into the development board is connected to the on-board target device. - **External Device (OUT)**: The on-board debugger is configured for connection to an external device such as your custom hardware. - **External Debugger (IN)**: An external debugger is connected to the device on the development board. See your kit's User’s Guide for more information on the debug modes available. ![Launcher general information Debug Mode](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-device-adapter-configuration.png) **Adapter Firmware** This shows the firmware version running on the debug controller of your Silicon Labs development kit and whether or not an update is available. Silicon Labs strongly recommends that you update adapter firmware to the current version. The Changelog shows the firmware release notes. ![Launcher general information adapter firmware](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-device-firmware.png) When you update adapter firmware SSv5 will ask you to confirm before proceeding. When firmware is up to date the interface says **Latest**. ![Launcher general information adapter firmware after update](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-overview-tab-adapter-firmware-after-update.png) **Secure Firmware** Series 2 devices contain a Secure Element, a tamper-resistant component used to securely store sensitive data and keys, and to execute cryptographic functions and secure services. The Secure Element firmware can also be updated. When you have a Series 2 device connected, the General Information card includes a **Secure FW** line. This shows the firmware version running on the Secure Element and whether or not an update is available. Silicon Labs strongly recommends that you update firmware to the current version. The Changelog shows the firmware release notes. ![Launcher general information Secure firmware](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-tab-overview-firmware-update-project-config.png) When you update, you are warned that user software, including any factory-installed applications such as RangeTest, will be deleted. ![Launcher general information Secure firmware confirm update](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-tab-overview-firmware-update-warning.png) After upgrade, the installed and available versions are the same. ![Launcher general information Secure firmware after update](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-tab-overview-firmware-after-update.png) **Preferred SDK** Some developers may have more than one GSDK version installed. The preferred SDK shows the currently selected SDK. Click **Manage SDKs** to see other options. ![launcher general information preferred SDK](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-device-preferred-sdk.png) The options shown are those selected in Preferences > Simplicity Studio > SDKs. To add an installed SDK to the list, click **Add SDK** and browse to the installed location. SSv5 autodetects SDKs in the location folder. Select the SDK to add, and click **OK**. Make sure the new SDK is selected in the list, and click **Apply and Close**. You should now be able to select it in the Preferred SDK list. ![SDK list in Preferences](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-sdk-add.png) The same dialog is used to [install SDK extensions](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-getting-started/install-sdk-extensions.md). ##### Example Projects & Demos Tab The EXAMPLE PROJECTS & DEMOS tab shows a list of example projects and demos compatible with the selected device. A demo is a prebuilt software example that can be loaded into a compatible device and used to show and test application functionality. Every demo comes with an associated example project. See the Quick Start Guide for your SDK for more information about the examples and demos provided. Click **RUN** on any demo to install it on a target device. Click **CREATE** on any project to create it. This is equivalent to creating a project from the OVERVIEW tab, except that the project is already selected. By default, the tab enables showing both demos and examples. Demos have a blue tag in the upper left of the card. To see only one type of file, disable the other type. ![launcher Example Projects & demos tab](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-tab-demos-and-examples.png) Use the switches, checkboxes and search box to filter the list. Note: Solutions are combinations of projects on which certain operations can be performed at the same time. This is a new feature and support is still being added for it. No example solutions are provided in this release, but you can create your own. See [Solutions](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-with-project-configurator/project-solutions) for more information. The checkboxes displayed depend on your selected device. Checkbox categories include: - Wireless Technology - Device Type - MCU - Capability - Project Difficulty - Quality - Provider **Provider** includes the checkbox **Peripheral Examples**. These examples are provided from the Silicon Labs GitHub repository **peripheral-examples**, are specific to your connected or selected board, and allow you to exercise various peripheral functions. ![launcher Example Projects & demos tab](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-tab-demos-examples-peripheral.png) SSv5 allows you to add other GitHub repositories containing examples. To add a GitHub repository, go to **Preferences > Simplicity Studio > External Repos**. Here you can add, edit, and delete repos, and select from repos that are already added. Adding a repo is done in two steps: cloning and then selecting the branch, tag, or commit to add. The default branch is Master. **application_examples** and **peripheral_examples** are official Silicon Labs repos and may not be edited or deleted. ![Adding a github repo](/ss-5-users-guide-about-the-launcher/0.9/images/github-add.png) You must be connected to the Internet to create a project from an example in a remote GitHub repository. Projects created from GitHub repositories are created in the location specified in the project creation dialog. The cloned project does not have any Git-related information in it. You cannot sync/checkout/pull code from Git. If you specify a repository installed locally, SSv5 will not synchronize the repo and all Git-related interface items will not be presented. ##### Documentation Tab The DOCUMENTATION tab shows all documentation compatible with the selected part. Use the checkboxes or text filter field to find a resource of interest. The technology filter corresponding to your development environment will show you most software documents relevant to that environment. ![launcher documentation tab](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-tab-documentation.png) ##### Compatible Tools Tab The COMPATIBLE TOOLS tab shows the tools compatible with the selected product. The Tools button on the toolbar shows all tools unfiltered. ![launcher tab tools](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-tab-tools.png) ### Debug Adapters The Simplicity Studio® 5 (SSv5) Debug Adapters view shows connected hardware adapters and displays kits, board, and devices. ![launcher debug adapter view](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-debug-adapter-view.png) The Debug Adapters view menu functions are: ![launcher debug adapter menu](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-debug-adapter-menu.png) - Refresh the list of detected kits and debuggers - Clear and refresh the list of detected kits and debuggers - Create a group to help organize multiple adapters - Rename a group - Delete a group - Device Configuration (equivalent to [Configure Connection](welcome-and-device-tabs#general-device-information)) - Preferences (provides shortcuts to three of the options available in Preferences from the toolbar or **Window > Preferences**. - Device Manager (Simplicity Studio > Device Manager) - Discovery (Simplicity Studio > Device Manager > TCP/IP Adapters) - Stack (Network Analyzer > Decoding > Stack Versions) - Toggle properties (shows or hides the adapter properties) ![launcher-debug adapter properties](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-debug-adapter-properties.png) - Toggle device label detail ![launcher debug adapter label](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-debug-adapter-label.png) - Collapse all - Expand all Finally, right-clicking on a debug adapter brings up a menu of functions. The availability varies depending on the context. ![launcher debug adapter right menu](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-debug-adapter-right-menu.png) ### My Products The Simplicity Studio® 5 (SSv5) My Products view provides you with a convenient way to save and organize a list of kits, boards, and devices for quick access. Use the search function to locate and add products to the view. Products selected here set the target device context and allow you to explore the relevant resources and to start projects. ![launcher my products view](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-my-products-view.png) Start typing a part number or key word to see kits, boards, and parts. Once you select an item, it is added to a folder called 'My Products 1'. The My Products view menu provides functions to help manage parts selected in this view. ![launcher my products menu](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-my-products-menu.png) - Make a new folder (rename a folder by right-clicking it) - Add a product (opens a dialog where you can add and remove more than one part at a time) ![launcher my products add](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-my-products-add.png) - Remove the selected part - Remove all content - Collapse all - Expand all ### Menu The perspective menu is available on all Simplicity Studio® 5 (SSv5) perspectives. The options available under each vary depending on the context. ![launcher menu](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-menu.png) ### Toolbar The Simplicity Studio toolbar contains functions that are generally useful throughout Simplicity Studio® 5 (SSv5). ![launcher toolbar](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-toolbar.png) - Welcome returns you to the Launcher Welcome configuration. - Recent shows you a list of recent projects. Select one to go to that project in the Simplicity IDE Project Explorer view. - [Tools](#tools) provides a list of available tools. This list may have more selections than are available in the Launcher perspective Tools tab. - [Install](#install) brings you to a menu where you can install or uninstall software packages and review available updates. - [Preferences](#preferences) is a shortcut to the list of preferences also available through the menu selection Window > Preferences. In addition, the section [About Update Frequency](#about-update-frequency) describes how to manage the frequency with which Simplicity Studio checks for updates. #### Tools The Tools button opens a dialog where you can select a tool to open it, and also add and remove tools. ![launcher toolbar tool](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-toolbar-tools.png) The Add/Remove Tools link opens the Installation Manager. Click **Manage Installed Packages** and go to the Tools tab, where you can add and remove tools. ![launcher package manager tab tools](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-package-manager-tab-tools.png) #### Install The Install button (red when updates are available) opens the Installation Manager. ![install method three](/ss-5-users-guide-about-the-launcher/0.9/images/install-method-three.png) Because available items are often controlled through your Silicon Labs account, it is recommended that you be logged in while using the Installation Manager. **Install by connecting device(s)** and **Install by technology type** are both described in [Install SSv5 and Software](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-getting-started/install-ss-5-and-software). This section describes the **Manage installed packages** functionality. Click **Manage installed packages** to open a tabbed interface where you can install and uninstall a variety of SSv5 components. Note that you can have more than one instance of some items, such as SDKs. You can use the Installation Manager to install additional instances as well as updates. The interface opens on the Product Updates tab. Updates are grouped by type. If Product Updates are available these typically must be installed before you can install a new SDK. ![launcher package manager tab-updates](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-package-manager-tab-updates.png) The SDKs tab supports installing and uninstalling SDKs and extensions. ![launcher package manager tab sdks](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-package-manager-tab-sdks.png) Click **Add ...** to install another version or instance of the SDK. The dialog displays what is available as well as what is currently installed. Click **Browse** to select an installation location other than the default. Click **Default** to select the default location (\Users\USERNAME\SimplicityStudio\SDKs\gecko_sdk<_n>, where _n is added for the second and incremented for subsequent installations). Hover over the release notes to get a scroll control. ![launcher package manager tab sdks](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-package-manager-tab-sdks-add-sdk.png) Click **...** next to an SDK version to install an update to it, change the version, or uninstall that version. ![launcher package manager tab update sdks](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-package-manager-tab-sdks-update.png) The Early Access tab is used to provide limited access for some customers, usually for beta testing. The Tools tab shows available and installed tools, regardless of your connected or selected hardware. Summary release notes are provided. ![launcher package manager tab tools](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-package-manager-tab-tools.png) The Toolchains tab shows available and installed toolchains. ![launcher package manager tab toolchains](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-package-manager-tab-toolchains.png) The Assets tab shows available assets. Assets include items such as documents, photographs, code, and so on. Check the item(s) of interest and click **Install**. The default view is filtered by connected product. ![launcher package manager tab assets filtered](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-package-manager-tab-assets-filtered.png) The unfiltered view provides a much larger set of options. ![launcher package manager tab assets unfiltered](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-package-manager-tab-assets-unfiltered.png) After you install or uninstall items, for example as a result of an update or because you want to manage your SDK installations, SSv5 determines if a restart is required. #### About Update Frequency By default, SSv5 checks for updates when you first open it. You can manage update frequency through Preferences > Install/Update > Automatic Updates. ![launcher update frequency](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-update-frequency.png) - Automatically find new updates and notify me (default: On): When selected, SSv5 automatically searches for update, as defined by the update schedule. - Update schedule (default: On startup): Look for updates on each startup, or once a day or some day a week, at a predefined time. - Download options (default: Search and Notify): Choose if SSv5 will search for updates and notify you of them once they are available or automatically download new updates and ask you to install them. - When updates are found (default: Once): Choose to be notified about new updates only once, or to receive reminders until the updates are installed. If you have turned automatic updates off, you can check for updates by clicking **Install** on the toolbar, then **Manage Installed Packages**, and then **Check for Updates** on the Product Updates tab. #### Preferences The Preferences button is a shortcut to the Windows > Preferences dialog (App menu on macOS). ![launcher toolbar preferences](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-toolbar-preferences.png) Frequently used preferences are discussed in context of their use cases. Context-sensitive help is available for most preferences. ![launcher toolbar preferences help](/ss-5-users-guide-about-the-launcher/0.9/images/launcher-toolbar-preferences-help.png) The arrow controls in the upper-right enable navigation through previously viewed pages. To return to a page after viewing several pages, click the drop-down arrow to display a list of recently viewed pages. If you have made changes in preferences and wish to move them to a different installation, use the Import and Export controls in the lower left. ## About the Simplicity IDE ### About the Simplicity IDE The Simplicity Studio® 5 (SSv5) **Simplicity Integrated Development Environment (IDE)** perspective is designed to support code editing, downloading, and debugging for EFR32 devices and modules and EFM32, EFM8, and 8051 devices. These pages review the [Simplicity IDE User Interface](user-interface-review), discuss how to [import and export projects](import-and-export), and explore the features supporting [code editing](code-editing). ### User Interface Review The Simplicity IDE perspective is made up of three views areas, the editor area, and a toolbar. ![simp ide start](/ss-5-users-guide-about-the-simplicity-ide/0.7/images/simp-ide-start.png) 1. [Project Explorer View](#project-explorer-view) 2. [Debug Adapters View](#debug-adapters-view) 3. [Other Views](#other-views) 4. [Toolbar](#toolbar) 5. Editor area The Editor area is populated with whatever tool is appropriate for the device and project, such as [Project Configurator](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-with-project-configurator) or the 8-bit device [Hardware Configurator](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-for-8bit-devices). #### Project Explorer View The Project Explorer view shows project files in the current workspace. ![simp ide project explorer](/ss-5-users-guide-about-the-simplicity-ide/0.7/images/simp-ide-project-explorer.png) A workspace is a directory that includes some hidden metadata, and must be created through SSv5. The default Windows workspace is: \Users\\SimplicityStudio\v5_workspace\ Maintaining separate workspaces for different GSDK versions or compiler versions may be necessary in some cases or may help improve SSv5 Performance. See [Tips and Tricks](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-tips-and-tricks/#use-different-workspaces-for-different-gsdk-versions-or-compilers) for more information. Each SSv5 session has a single default workspace. To change workspaces or to create a new workspace, use the **File > Switch Workspace** function. To create a new workspace click **Browse** and add a new directory. After you add or switch, SSv5 restarts. ![simp ide workspace select](/ss-5-users-guide-about-the-simplicity-ide/0.7/images/simp-ide-workspace-select.png) Right-click a project directory for a context menu of project-level functions. ![simp ide project menu](/ss-5-users-guide-about-the-simplicity-ide/0.7/images/simp-ide-project-menu.png) The Filter functionality available through the view toolbar can be used to limit the files shown. ![simp ide project explorer filter](/ss-5-users-guide-about-the-simplicity-ide/0.7/images/simp-ide-project-explorer-filter.png) #### Debug Adapters View The debug adapters tab in this view is the same as that in the Launcher perspective. ![simp ide debug adapters menu](/ss-5-users-guide-about-the-simplicity-ide/0.7/images/simp-ide-debug-adapters-menu.png) When the adapter is disconnected, an **Upload application** option is available. This has the advantage of allowing you to flash both an application image and a bootloader image at the same time, and also to see the various pre-compiled images available based on the installed SDKs, along with their compatible hardware. ![simp ide debug adapters upload application](/ss-5-users-guide-about-the-simplicity-ide/0.7/images/simp-ide-debug-adapters-upload-application.png) When you connect to an adapter, the icons turn blue. ![simp ide debug adapters connected](/ss-5-users-guide-about-the-simplicity-ide/0.7/images/simp-ide-debug-adapters-connected.png) Once you have connected, **Start capture** and **Start capture with options** open the Network Analyzer interface for that device. For many devices, **Launch console** opens up a console in the editor area, where you can interact with the device. This option is not available with EFM8 / C8051 starter or development kits (STKs or DKs). ![simp ide debug adapters console](/ss-5-users-guide-about-the-simplicity-ide/0.7/images/simp-ide-debug-adapters-console.png) #### Other Views Other views are available in the pane below the editor area. ![simp ide other views](/ss-5-users-guide-about-the-simplicity-ide/0.7/images/simp-ide-other-views.png) - **Problems** shows any problems detected in an open file or a process. - **Search** shows the results of the most recent search. The toolbar allows you to retrieve previous searches. - **Call Hierarchy** shows the results of Open Call Hierarchy when using the IDE for [code development](code-editing#call-hierarchy). - **Console** shows activity such as flashing an image to the device and build results. #### Toolbar The Simplicity IDE toolbar offers debug and other code and file options. ![simp ide toolbar](/ss-5-users-guide-about-the-simplicity-ide/0.7/images/simp-ide-toolbar.png) **1 Debug** builds an image in debug mode, flashes it, and opens the [debugger](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-testing-and-debugging/using-the-debugger). **2 Profile as** opens the [Energy Profiler](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-tools-energy-profiler). **3 New** opens a menu where you can create a variety of items, including a new project (equivalent to **File > New > Project**). **4 Save** saves a changed file. **5 Save all** saves all changed files. **6 Mode** allows change between debug and release mode for the applicable toolchain. **7 Build** builds the selected project file in the default mode (debug or release). When working with code files, **8 Next** and **9 Previous annotation** allow you to select the type of annotation and move to them. **10 Edit last location** opens the last file you had selected. **11 Back and 12 Forward to file** allow you to move to the previous or next file, or to select a file from a list. **13 Pin editor** links the selection in the Project Explorer view to its editor tab. **14 Flash programmer** opens the [Flash programmer](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-building-and-flashing/flashing) tool, also available through the Tools menu. ### Import and Export Simplicity Studio® 5 (SSv5) [File > Import](#import) allows you to import a project from Keil® µVision4®, IAR Embedded Workbench, or the 8-bit Silicon Labs IDE into Simplicity IDE. You can also import a Silicon Labs Configurator project (.slcp) file to create a project in the Simplicity IDE, or a Silicon Labs export (.sls) file to import a project or a solution. [File > Export](#export) allows you to export a project or solution in a variety of formats. #### Import Place the file to be imported in a folder. Select **File > Import**, and locate the folder with the project or solution to be imported. ![simp ide import](/ss-5-users-guide-about-the-simplicity-ide/0.7/images/simp-ide-import.png) Select the project and click **Next**. If anything about the project is unresolved you can resolve it. ![simp ide import unresolved](/ss-5-users-guide-about-the-simplicity-ide/0.7/images/simp-ide-import-unresolved.png) ![simp ide import resolved](/ss-5-users-guide-about-the-simplicity-ide/0.7/images/simp-ide-import-resolved.png) If you are importing a solution, you can see the projects that are included in the solution. ![Import a solution](/ss-5-users-guide-about-the-simplicity-ide/0.7/images/simp-ide-import-solution.png) Click **Next**. Name the project or solution and click **Finish**. #### Export Select **File > Export**, and select the file(s) and/or solution(s) to be exported. ![simp ide export](/ss-5-users-guide-about-the-simplicity-ide/0.7/images/simp-ide-export.png) The default export format is an .sls file, which can easily be re-imported into SSv5. However, other options are available. Click **More export options...** and select a wizard. ![simp ide export options](/ss-5-users-guide-about-the-simplicity-ide/0.7/images/simp-ide-export-options.png) ### Code Editing Simplicity Studio® 5 (SSv5)'s Simplicity IDE is a code editing and development environment. The editor includes context highlighting, reference searching, and standard features found in any modern editor. ![simp-ide-code-start](/ss-5-users-guide-about-the-simplicity-ide/0.7/images/simp-ide-code-start.png) Note that the Outline view tab in the Debug Adapters area provides a code outline and a toolbar to control what shows in the Outline view. This page includes information on: - [Open Declaration](#open-declaration) - [Content Assist](#content-assist) - [Link with Editor](#link-with-editor) - [Symbol Expansion](#symbol-expansion) - [Task View](#task-view) - [Quick-Access Console](#quick-access-console) - [Call Hierarchy](#call-hierarchy) #### Open Declaration In addition to the basic features, Simplicity IDE supports many advanced code-editing features. For example, the IDE automatically indexes all code within the project to support symbol lookup. The code does not have to build completely for the indexer to work, though certain features may not be available if, for example, the `main()` routine is not declared. In this example, the **Open Declaration** (F3 shortcut) feature quickly finds symbol declarations. 1. Open the file of interest by double-clicking it in the Project Explorer view. 2. Right-click the desired symbol to display the context menu. 3. Click **Open Declaration** to quickly navigate to the definition of the symbol. 4. SSv5 automatically opens the file and highlights the line containing the declaration of the symbol. ![simp ide code open declaration](/ss-5-users-guide-about-the-simplicity-ide/0.7/images/simp-ide-code-open-declaration.png) #### Content Assist Simplicity Studio also supports code completion, a feature called **Content Assist**. Content Assist requires that the appropriate header files be included in the file so that the symbols are available. To use Content Assist, type the first few letters of a symbol or include file and press **Ctrl+Space** to display a list of symbols that match. For example, to use [Content Assist] to display a list of symbols starting with the characters PC: 1. Type `PC` and press **Ctrl-Space** to display the Content Assist list. 2. Use the arrow keys or page up and down keys to look through the list of matching symbols. 3. Press **Enter** to replace the typed characters with the selected symbol. ![simp ide code content assist](/ss-5-users-guide-about-the-simplicity-ide/0.7/images/simp-ide-code-content-assist.png) #### Link with Editor In the Project Explorer view, click **Link with Editor** in the toolbar. Then, if you have multiple files open, selecting a file in Project Explorer makes the associated editor tab active. #### Symbol Expansion Hover over a function or macro in the editor to display a hover window with expanded information. ![simp ide code symbol expansion](/ss-5-users-guide-about-the-simplicity-ide/0.7/images/simp-ide-code-symbol-expansion.png) #### Task View The Tasks view automatically picks up any comments with `TODO` or `FIXME` in the line. For example: 1. Type `TODO` in a comment line with the desired text and save the file 2. Select **Window > Show View > Other** , type `Tasks`, and press **Open**. The TODO or FIXME lines are highlighted by a clipboard icon to the left of the line in the editor. Double-click on a line in the Tasks view to open the relevant file with that line selected. ![simp ide code tasks](/ss-5-users-guide-about-the-simplicity-ide/0.7/images/simp-ide-code-tasks.png) **Note:** To reset the perspective to its original layout, right-click the perspective button in the toolbar and select **Reset**. #### Quick-Access Console Press **Ctrl+3** to open a quick-access console for locating any menu or view within the IDE. For example, press **Ctrl+3** and type `Preferences`. This lists all of the Preferences menus available within SSv5. Then, select an option to open the menu. ![simp ide code tasks](/ss-5-users-guide-about-the-simplicity-ide/0.7/images/simp-ide-code-quick-access.png) #### Call Hierarchy The IDE includes a call hierarchy that can help find where functions are called. To find the call hierarchy for a function in development mode, right-click the function and select **Open Call Hierarchy**. ![simp ide code call hierarchy](/ss-5-users-guide-about-the-simplicity-ide/0.7/images/simp-ide-code-call-hierarchy.png) ## Developing for 32-Bit Devices ### Developing For 32-Bit Devices - Overview These pages describe how to customize projects developed in Simplicity Studio® 5 (SSv5) for 32-bit target devices. If you have not yet installed SSv5 or are not familiar with its features, [Getting Started](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-getting-started) guides you through installing SSv5 and your Silicon Labs protocol software development kit (SDK). This section assumes you have installed studio, have your development hardware connected, and are generally familiar with the SSv5 [Launcher Perspective](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-about-the-launcher) and with the [Simplicity IDE](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-about-the-simplicity-ide). Each Silicon Labs SDK comes with example projects. The easiest way to start development is to modify the configuration of an example project. The various paths to creating a project based on an example are described in [Start a Project](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-getting-started/start-a-project). The development tools you will use depend on the example chosen as a starting point. The most commonly used tools are described in [Developing with Project Configurator](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-with-project-configurator). In general, Project Configurator is used with Gecko Bootloader and all other protocol projects created with GSDK version 4.0 and higher, as well as Bluetooth, Bluetooth Mesh, OpenThread, Wi-SUN, and Proprietary applications created with Gecko SDK 3.x. These projects share a common infrastructure, called Silicon Labs Configurator (SLC). As of SSv5 version 5.3, a legacy tool called [AppBuilder](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-with-appbuilder) is only used with Zigbee EmberZNet and Gecko Bootloader projects that were created with GSDKs version 3.2 and lower. After you have created your project files, compile an application image and flash it to your device as described in [Building and Flashing](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-building-and-flashing). When you are ready to test your project, whether on Silicon Labs hardware or your own custom device, SSv5 provides a number of tools to help with testing and debugging. An overview is provided in [Testing and Debugging](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-testing-and-debugging). ### Developing with Project Configurator #### Developing with Project Configurator Simplicity Studio® 5 (SSv5) introduced new and improved tools for configuring project code, designed to work on the project's component-based architecture. SSv5 includes project configuration tools that provide an enhanced level of software component discoverability, configurability, and dependency management. These include: - [Project Configurator](project-configurator) to install and uninstall components, - [Component Editor](component-editor) to change component parameters, - [Pin Tool](pin-tool) to configure peripherals. Other tools are protocol-specific: - For Bluetooth and Bluetooth Mesh projects, use the [Bluetooth GATT Configurator](bluetooth-gatt-configurator) to customize the Bluetooth GATT database. - For Bluetooth Mesh projects, use the [Bluetooth Mesh Configurator](bluetooth-mesh-configurator) to customize a node's Device Configuration Data (DCD). - For Proprietary RAIL projects, use the [Radio Configurator](proprietary-radio-configurator) to define and manage proprietary radio protocols and channel groups - For Wi-SUN projects, use the [Wi-SUN Configurator](wi-sun-configurator) to configure application settings, security, and radio. - For Zigbee and Matter projects, use the [ZCL Advanced Platform (ZAP)](zigbee-cluster-configurator) to manage and configure endpoints. Once you have finishing customizing your project, [build and flash it](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-testing-and-debugging/overview-and-resources) and [test and debug it](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-testing-and-debugging). Beginning with Simplicity Studio 5.3, you can combine projects into [solutions](project-solutions). Solutions can be built, debugged, and flashed together. #### Project Configurator When you create a component-based project (.slcp), the Project Configurator automatically opens an [OVERVIEW](#overview-tab) tab in the Editor area of the Simplicity IDE perspective. A [SOFTWARE COMPONENTS](#software-components-tab) tab provides access to a library of software components and their configuration functions. A [CONFIGURATION TOOLS](#configuration-tools-tab) tab allows for quick access to project-specific tools. Open the Project Configurator for an existing project by double-clicking the _.slcp_ file in the Project Explorer view. ![proj conf overview](/ss-5-users-guide-developing-with-project-configurator/1.0/images/proj-conf-overview.png) ##### Overview Tab The OVERVIEW tab has three cards: - [Target and Tool Settings](#target-and-tool-settings), where you can change your development target, SDK, and project generators. - [Project Details](#project-details), where you can rename the project, change the Import mode and, in rare cases, force generation. - [Quick Links](#quick-links), where you can change the files SSv5 generates for your project. ###### Target and Tool Settings Click **Change Target/SDK/Generators** to change the device for which the project is developed, the SDK version to be used in development, or the files that will be generated for the project. Changes made here do not apply to the project until you save changes. ![proj conf target sdk](/ss-5-users-guide-developing-with-project-configurator/1.0/images/proj-conf-target-sdk.png) Search for target hardware by part number. If you select a different part, it replaces the part already selected, or you can delete the part and then add a new one. If you have more than one Gecko SDK Suite (GSDK) version installed, you can select it here. If you do not see a version that you expect to see, click **Manage SDKs** to open the SDK Preferences. ![proj conf sdk prefs](/ss-5-users-guide-developing-with-project-configurator/1.0/images/proj-conf-sdk-prefs.png) Here you can search for SDKs that might be installed outside of SSv5. Note that, if you have more than one SDK protocol installed in the same GSDK version, for example Bluetooth and Zigbee, you cannot change between them. You can only choose among GSDK versions. The options for the files that are generated by Project Configurator are: - GCC Makefile - [Visual Studio Code Compatible Project (Beta)](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-vscode-ide) - IAR Embedded Workbench Project - Simplicity IDE project The options that are available for selection and the default vary depending on the SDK and toolchain you selected when you created the project. Note that changing the project generator does not change the project toolchain. The compiler / toolchain used by Simplicity IDE is configurable in **Project > Build Configurations**. The default IDE is configurable in **Preferences > Simplicity Studio > Preferred IDE**. ###### Project Details Project details include a description of the example on which the project is based, the category of the example, the versions of SDK included in the currently selected GSDK version, and the import mode. Here you can: - Edit the project name - Change the import mode - Generate a project report - (If necessary) Force project generation ![proj conf proj details](/ss-5-users-guide-developing-with-project-configurator/1.0/images/proj-conf-proj-details.png) Click the pen icon to edit the project name. The import mode determines what resources are copied into your project and what are linked. If you change the import mode, the change is autosaved and your project files are regenerated. - **Link to sources** means all project and SDK resources are linked. Only generated files are saved with the project. - **Link SDK and copy project sources** (default) means that all the example project sources are copied, but SDK libraries are linked. If you update the SDK and regenerate the project files, the project will change. - **Copy contents** means that all resources are copied with the project. You can update SDK or load an updated example project and your project will not change. **Generate Project Report** creates a PDF, available through a link immediately above the control, that provides details on: - Target hardware device - Target hardware device pin mapping - Target SDK - Software extensions used in the build - Installed application, utility, and platform software components ![proj conf generate report](/ss-5-users-guide-developing-with-project-configurator/1.0/images/proj-conf-generate-report.png) Force Generation, available through the **...** menu, is used only in rare cases when autogeneration is not triggered, usually because of some change made outside of SSv5. It will run all available generators (slcp, radio config, gatt, and so on). Note for Simplicity Studio 4/AppBuilder users: Because many project configurator files are autogenerated, Project Configurator does not include a **Generate** control like the one in AppBuilder. **Force Generation** is not a replacement for that control. ###### Quick Links Quick links are shortcuts to tools and other information of interest while developing a project of this type. The links available vary based on the protocol and device. For example, a Connect project includes a Radio Configurator quick link. ![proj conf quick links card](/ss-5-users-guide-developing-with-project-configurator/1.0/images/proj-conf-quick-links.png) ##### Software Components Tab Projects are configured by installing and uninstalling components, and configuring installed components. The SOFTWARE COMPONENTS tab displays categories of components on the left, and details about the selected component on the right. ![proj conf components](/ss-5-users-guide-developing-with-project-configurator/1.0/images/proj-conf-components.png) A number of filters as well as a keyword search are available to help you explore the various component categories. Note that components for all installed SDKs are presented. Expand a component category\subcategory to see individual components. Select a component to see its details. Components that were included in the original project or installed by the user are checked (1), and can be uninstalled. Configurable components are indicated by a gear symbol (2). Configurable components must be installed before their configuration can be changed. ![new project project config component detail](/ss-5-users-guide-developing-with-project-configurator/1.0/images/new-project-project-config-component-detail.png) For any component you can see see the components on which this component depends, and components dependent on it. You can also link to additional documentation, if available. When you install a component, the installation process will: 1. Copy the corresponding SDK files from the SDK folder into the project folder. 2. Copy all the dependencies of the given component into the project folder. 3. Add new include directories to the project settings. 4. Copy the configurations files into the /config folder. 5. Modify the corresponding auto-generated files (in the _autogen_ folder) to integrate the component into the application. Additionally, "init" type software components will implement the initialization code for a given component, utilizing their corresponding configuration file as input. Some software components will fully integrate into the application to perform a specific task without the need of any additional code, while other components provide an API to be used in the application. ##### Configuration Tools Tab This tab provides an easy way to open a tool when the tool's tab is not open. The tab shows configuration tools relevant to the project type. A Bluetooth Mesh project shows a number of tools, while an OpenThread project might only show the Pin Tool. Click **Open** on the tool's card to open it in a separate tab. ![proj conf configuration tools](/ss-5-users-guide-developing-with-project-configurator/1.0/images/proj-conf-configuration-tools.png) #### Component Editor Click the gear symbol next to an installed configurable component name, or **Configure** on the component description to open the Component Editor. ![proj conf component editor start](/ss-5-users-guide-developing-with-project-configurator/1.0/images/proj-conf-component-editor-start.png) The Component Editor opens in a new tab. The changes you can make depend on the component. ![proj conf component editor](/ss-5-users-guide-developing-with-project-configurator/1.0/images/proj-conf-component-editor.png) Changes made here are autosaved in native source format in the associated source files. ![proj conf component editor autosave](/ss-5-users-guide-developing-with-project-configurator/1.0/images/proj-conf-component-editor-autosave.png) Click **View Source** to open an editor on the configuration file. If a component has multiple configuration files, the control is **View Source Files** ![proj conf component editor source](/ss-5-users-guide-developing-with-project-configurator/1.0/images/proj-conf-component-editor-source.png) #### Pin Tool Simplicity Studio® 5 (SSv5) offers a Pin tool that allows you to easily configure new peripherals or change the properties of existing ones. In the Project Configurator, open the CONFIGURATION TOOLS tab and open the Pin Tool. Alternatively, double-click the file .pintool in the Project Explorer view. The graphical view differs based on the chip. ![pintool start](/ss-5-users-guide-developing-with-project-configurator/1.0/images/pintool-start.png) For more complex layouts, you can use the zoom controls above the graphic to see detail and the rotate controls to rotate the image. ![pintool zoom](/ss-5-users-guide-developing-with-project-configurator/1.0/images/pintool-zoom.png) Right-click anywhere on the image or click the Additional Functions icon in the upper right of the image to open a menu where you can: - Save Diagram as Picture: Saves the graphic as a .png file - Module Configuration Report: Produces an .htm file showing modules with signals assigned to pins. If a module has a signal assigned to a pin, the module and signal/pin assignment appear in the report. - Pin Configuration Report: Produces an .htm file showing all the user modifiable pins of the chip and the current signal assignment, if any. Click a pin on the graphic to select it. The corresponding row is checked in the right pane's tabbed interface. The pin, function, and peripheral tabs in the configuration pane provide different modes of access. A search function also provided ![pintool pin tab](/ss-5-users-guide-developing-with-project-configurator/1.0/images/pintool-pin-tab.png) ![pintool function tab](/ss-5-users-guide-developing-with-project-configurator/1.0/images/pintool-function-tab.png) ![pintool peripheral tab](/ss-5-users-guide-developing-with-project-configurator/1.0/images/pintool-peripheral-tab.png) ##### Modifying Pin Configurations Use the Pin Tool to modify the pin configuration of the device. Software components control behavior in the project but must be associated with a peripheral, and generally need pin or function assignments. These pin or function assignments are most easily edited in the Component Editor for that component. The Pin Tool allows you to assign functions to pins. On all three dialogs, click **EDIT** next to a software component to go directly to the Component Editor for that component. Click **NEW** to go to the Project Configurator's SOFTWARE COMPONENTS tab, where you can install a component in the project so that it can be selected in the dialog. When you are finished with the configuration, click **APPLY** or **APPLY AND CLOSE** to save changes. Configuration code changes are automatically generated. ###### The Pins Tab Click on any pin's row to open the Edit Pin dialog. - The function assigned to the pin: To apply a function or change a function, drop down the function list and select. - The Custom Pin Name (optional): Add or edit the custom pin name. - The Software Component: The component associated with the function is shown. ![Edit Pin dialog](/ss-5-users-guide-developing-with-project-configurator/1.0/images/pintool-edit-pin-existing.png) ###### The Functions Tab Click on any function's row to open the Edit Function dialog. - The pin to which the function is assigned: Select a pin, or disable. - The Custom Pin Name (optional): Add or edit the custom pin name. - The Software Component: The component associated with the function is shown. A pin must be selected. ![Edit Function dialog](/ss-5-users-guide-developing-with-project-configurator/1.0/images/pintool-edit-function.png) ###### The Peripherals Tab Click on any peripheral's row to open the Edit Peripherals dialog. - The Custom Peripheral Name: Add or edit the custom peripheral name. - The Software Component: The component associated with the peripheral. ![Edit Function dialog](/ss-5-users-guide-developing-with-project-configurator/1.0/images/pintool-edit-peripheral.png) #### Bluetooth GATT Configurator The Simplicity Studio® 5 (SSv5) Bluetooth GATT Configurator is a simple-to-use tool to help build a customized Bluetooth GATT database for Bluetooth projects. It is accessed through the Advanced Configurators software component group on the Project Configurator SOFTWARE COMPONENTS tab, or by double-clicking the project file _config > btconf > gatt_configuration.btconf_. The Bluetooth GATT Configurator is composed of a Custom GATT editor on the left, showing a list of project Profiles/Services/Characteristics/Descriptors, and a Settings editor on the right. A SIG selector allows you to add standard elements to the profile. An options menu is provided at the top of the Custom GATT editor. The Custom GATT editor is always visible, and the Settings editor opens by default. ![gatt configurator start](/ss-5-users-guide-developing-with-project-configurator/1.0/images/gatt-config-start.png) The Bluetooth GATT Configurator menu is: ![new project gatt configurator menu](/ss-5-users-guide-developing-with-project-configurator/1.0/images/new-project-gatt-configurator-menu.png) 1. Add an item. 2. Duplicate the selected item. 3. Move the selected item up. 4. Move the selected item down. 5. Import a Bluetooth GATT database. 6. Add Predefined (opens the SIG editor). 7. Delete the selected item. ##### SIG Selector Click the Add Predefined menu button (6) to open the SIG selector. The SIG Selector displays a list of predefined Profiles, Services, Characteristics, and Descriptors. These items can be filtered, using the filter pane. Tabs allow you to switch between different lists. As shown in the following figure, the pane on the right side of the list displays textual information about the latest selection. To add an item to the Custom GATT editor, mouse over it and click **+** on the right. The item can then be edited in the Settings section. The selected SIG service/characteristic/descriptor will be added under the highlighted profile/service/characteristic. Click **< BACK** to return to the Setting Editor. Click **View Manual** to see more information about Bluetooth GATT database items. ![gatt config sig](/ss-5-users-guide-developing-with-project-configurator/1.0/images/gatt-config-sig.png) The GATT Configurator does not automatically save changes. An asterisk next to the configuration file name indicates unsaved changes in the configuration. Database generation happens automatically when the configuration is saved. The generated source files can be found in the _autogen_ directory: ![gatt config files](/ss-5-users-guide-developing-with-project-configurator/1.0/images/gatt-config-files.png) ##### Custom GATT Editor The Custom GATT Editor in the right pane of the GATT Configurator displays the items present in the current configuration file. This includes a Custom GATT Profile, Services, Characteristics, and Descriptors displayed as a hierarchical list. The order of items shown reflects the order in which they exist in the GATT database. When the Settings Editor is open, you can select an item to see its properties and configuration. ![gatt config custom editor](/ss-5-users-guide-developing-with-project-configurator/1.0/images/gatt-config-custom-editor.png) **Note:** The Generic Attribute Service is not listed in the Custom GATT database structure. This is a special service that is maintained by the stack, and can be added by enabling the Generic Attribute Service slider in the settings of the Custom BLE GATT profile. Once enabled, the service will be part of the database. It still will not appear in the Custom GATT database structure or on iOS devices, as iOS hides this service, but you may see it on Android devices for example. ![gatt config generic attribute service](/ss-5-users-guide-developing-with-project-configurator/1.0/images/gatt-config-generic-attribute-service.png) Some services are listed in the configurator as "contributed items". This means that their content is defined in other components, and they cannot be edited from this view. ##### Settings Editor The Settings editor allows you to configure the properties of items such as Profiles, Services, Characteristics and Descriptors that are present in the Custom GATT editor. Selecting an item populates the relevant configuration options such as the name, ID, properties and capabilities. Any changes made in this section are reflected immediately for the selected item. You can minimize the Custom GATT editor while working in the Settings editor, as shown in the following figure. All Characteristics for a Service are included in the same Settings editor pane. ![gatt config settings editor](/ss-5-users-guide-developing-with-project-configurator/1.0/images/gatt-config-settings-editor.png) ##### Additional Information For more information on specific use cases in the GATT Configurator, see _UG438: GATT Configurator User's Guide in Bluetooth SDK 3.x_. #### Bluetooth Mesh Configurator The Bluetooth Mesh Configurator provides access to a Bluetooth Mesh node's Device Composition Data (DCD). This contains information about the elements it includes and the supported models. DCD exposes the node information to a configuration client so that it knows the potential functionalities the node supports and, based on that, can configure the node. Configuring DCD through the Bluetooth Mesh Configurator is only one part of configuring a Bluetooth Mesh node. For details see _UG472: Bluetooth® Mesh Node Configurator User's Guide for SDK v2.x_. When you create a Bluetooth Mesh project in Simplicity Studio 5, three tabs open automatically: the [GATT Configurator](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-with-project-configurator/bluetooth-gatt-configurator) (gatt_configuration.btconf), .the slcp or [Project Configurator](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-with-project-configurator/project-configurator) .slcp, and the Bluetooth Mesh Configurator (dcd_config.btmeshconf). If the example has documentation, the project opens on a readme tab. ![Bluetooth Mesh Configuration Tools](/ss-5-users-guide-developing-with-project-configurator/1.0/images/mesh-conf-tabs.png) Click the dcd_config.btmeshconf tab to open the Bluetooth Mesh Configurator. If the tab is closed, you can open it from the Project Configurator's CONFIGURATION TOOLS tab. The Device Composition Data is presented in three areas: device information, elements, and models. ![Bluetooth Mesh Configuration Tools](/ss-5-users-guide-developing-with-project-configurator/1.0/images/mesh-conf-start.png) ##### Device Information The device information card contains four fields. Changing the Company changes the next three fields. ![Device information](/ss-5-users-guide-developing-with-project-configurator/1.0/images/mesh-conf-device-info.png) Device configuration information includes: - Company: Selected from a list of company names. - Company ID: 16-bit company identifier assigned by the Bluetooth SIG. A list of companies and their identifiers may be found on the [Bluetooth SIG site](https://www.bluetooth.com/specifications/assigned-numbers/company-Identifiers). - Product ID: 16-bit vendor-assigned product identifier, vendor-specific. - Version Number: 16-bit vendor-assigned product version identifier, vendor-specific. ##### Elements An element is an addressable entity within a node. Each node can have one or more elements, the first called the primary element and the others called secondary elements. Each element is assigned a unicast address during provisioning so that it can be used to identify which node is transmitting or receiving a message. The primary element is addressed using the first unicast address assigned to the node, and the secondary elements are addressed using the subsequent addresses. Both primary and secondary elements have a dedicated card, such as that shown in the following figure, through which they can be configured. Click the green plus symbol to add an element or select an element and click the red X symbol to remove it. ![Primary Element Card](/ss-5-users-guide-developing-with-project-configurator/1.0/images/mesh-conf-primary-element.png) ##### Models A model defines the basic functionality of a node, and a node may include multiple models. A model defines the required states, the messages that act upon those states, and any associated behaviors. Models may be defined and adopted by the Bluetooth SIG and may also be defined by vendors. Models defined by the Bluetooth SIG are known as SIG-adopted models, and models defined by vendors are known as vendor models. SIG-adopted models are identified by a 16-bit model identifier and vendor models are identified by a 16-bit vendor identifier and a 16-bit model identifier. Model specifications are designed to be very small and self-contained. At specification definition time, a model can require other models that must also be instantiated within the same node. This is called extending, which means a model adds functionality on top of other models. Models that do not extend other models are referred to as root models. Model specifications are immutable. In other words, it is not possible to remove or add behavior to a model, whether the desired behavior is optional behavior or mandatory. Models are not versioned and have no feature bits. If additional behavior is required in a model, then a new extended model is defined that exposes the required behavior and can be implemented alongside the original model. Therefore, knowledge of the models supported by an element determines the exact behavior exposed by that element. The Bluetooth Mesh Configurator supports configuring both SIG-adopted models and vendor models through separate editors. ###### SIG-Adopted Model Editor If you are using the provided model components that automatically bring in the source/header files, libraries, and configurations to the project, and also contribute the model to the DCD, you cannot edit or delete the model from the DCD manually. The model is greyed out, as shown in the following figure. In this case, all the model implementations will be generated to the project. You can modify the callbacks to adjust the application to your use case. ![SIG-Adopted Model Editor With Components](/ss-5-users-guide-developing-with-project-configurator/1.0/images/mesh-conf-sig-model-editor.png) The drawback to using components is that you cannot edit the DCD and model information, because the models added by components are greyed out. If you want to build the DCD from scratch, for example to add a specific model to an element, uninstall all the model components. Then you can edit the DCD manually. To delete a model, select it and click the red X symbol. To add a SIG-adopted model, drag the model from the left model pool to the SIG Models table in the correct element. A list of all the SIG-adopted models is displayed, and you can choose the one you want, as shown in the following figure. Note that, although all the SIG-adopted models are listed, not all of them are currently supported by the Bluetooth Mesh SDK. For the information on the supported models, see the SDK release notes. ![SIG-Adopted Model Editor](/ss-5-users-guide-developing-with-project-configurator/1.0/images/mesh-conf-sig-adopted-model-editor.png) Due to the extension mechanism of models mentioned above, attention is needed when adding models to your project. See _UG472: Bluetooth® Mesh Node Configurator User's Guide for SDK v2.x_ for more information. ###### Vendor Models Editor Vendor models give you more flexibility when developing products not covered by the SIG-adopted models. Vendors can define their own specification in these vendor models, including states, messages, and the associated behaviors. The vendor model editor is shown in the following figure. The ID field contains the 32-bit vendor identifier and model identifier. The two least significant bytes of the ID are the vendor ID and the two most significant bytes are the model ID. In the following figure, 0x02FF is the vendor ID for Silicon Labs, and 0x0021 and 0x0022 is the model ID. Click the plus symbol to add a vendor model, or select a model and click the red X symbol to remove it. ![Vendor Model Editor](/ss-5-users-guide-developing-with-project-configurator/1.0/images/mesh-conf-vendor-model.png) #### Proprietary Radio Configurator The Simplicity Studio® 5 (SSv5) Radio Configurator is provided as part of the Proprietary SDK. Use the Radio Configurator to create standard or custom radio configurations for your RAIL-based radio applications. The Radio Configurator is accessed through the through the Platform group's **Custom Radio Configuration for simple rail singlephy application** component, on the Project Configurator SOFTWARE COMPONENTS tab and can be accessed on the CONFIGURATION TOOLS tab. (For some examples, the Radio Configurator might open on project creation). All radio configurator settings are stored in _config/rail/radio_settings.radioconf_. Changes made with Radio Configurator are not automatically saved. ![radio conf start](/ss-5-users-guide-developing-with-project-configurator/1.0/images/radio-conf-start.png) All the parameters in the Radio Configurator are arranged in cards, some of which are grouped together. Each card contains entries that logically go together. Different radio profiles (as described under [Protocol](#protocol)) offer different views and parameter sets, as a profile is a high-level view of the parameter set valid for and describing a given radio link. ![radio conf parameter tiles](/ss-5-users-guide-developing-with-project-configurator/1.0/images/radio-conf-parameter-tiles.png) A radio configuration has two hierarchical levels: Protocol level and Channel Group level. A radio configuration can contain multiple protocols and a protocol can have multiple channel groups defined. ##### Protocol Protocols are complete radio configurations that can be switched using the `RAIL_ConfigChannels()` API, or can be used in Dynamic Multiprotocol applications. For Channel Group definitions see [Channel Groups](#channel-groups). To configure a protocol, first **select a predefined PHY** configuration, then **customize** it to meet your needs. First, look at the **General Settings** card. Select a radio profile in the **Select radio profile** drop-down menu. A radio profile may be any supported radio link technology. These technologies can be bound by standards (for example the Sigfox or WMBus protocols) or can be fully customized. The fully customizable profile is called the **"Base Profile"**. Once the radio profile has been selected, the next step is to select a radio PHY (radio configuration) in the **Select a radio PHY** dropdown list. Each profile has "built-in" configurations ready to use. Once the radio profile and radio PHY have been selected, users can review the **profile options**. By default, no changes are allowed, fields are grayed out. To enable customization, use the **Customized** switch on the **General Settings** card. This allows access to all the parameters defined by the profile. ![radio conf customize slider](/ss-5-users-guide-developing-with-project-configurator/1.0/images/radio-conf-customize-slider.png) **Important notes:** 1. If you select a "built-in" PHY, and then switch to "Customized", the Radio Configurator retains the property values of the "built-in" PHY. You can edit the values, but can also revert to the defaults. 2. If you switch to “Customized” mode, Silicon Labs **recommends unchecking all "Advanced"** properties, as those are fine-tuned for the "built-in" PHY, and may not be the optimal choice for the modified PHY. This way those parameters get auto-calculated, and you can experiment with the fine tuning starting with the calculated values. To keep the improved performance achieved by the original optimization, only minor changes should be made. For example, <100 MHz change in carrier frequency, or a different frame length configuration. 3. If you switch customization off, your **modifications will be reverted** to the property values of the "built-in" PHY. 4. Each menu item in the Navigation pane (on the left) is represented by a card in the main editor panel (on the right). **Cards can be hidden** by clicking the corresponding "eye" icon on the Navigation panel. Based on the selected radio profile, customizable options may be restricted. For example, if a radio profile is selected that is bound by a standard, the profile options only allow users to set the base frequency. All other options are preset according to the standard. ##### Channel Groups Each protocol configuration includes one or more channel group configurations. Channel groups define one or more (sequential) channels, with a constant channel spacing between them. Channel groups can differ in the radio configuration both from each other and from the parent protocol. By default, a channel group configuration includes only the **General Settings** and **Channel Configuration** cards. Additional parameters defined by the Protocol can be accessed for customization on a channel group basis by sliding the **Customized** switch on the corresponding card. Channel groups can also be completely overridden to a predefined PHY by checking the **Select radio PHY** box. ![Select radio PHY](/ss-5-users-guide-developing-with-project-configurator/1.0/images/radio-config-select-phy.png) RAIL automatically detects when hopping to a new channel requires hopping between channel groups. The configured property values defined by the channel group will be applied automatically for the new channel. This enables users to define virtual channels to the same physical frequency, but with different configuration settings. The order of the channel groups will be the same in the `RAIL_ChannelConfigEntry_t` array as shown in the Radio Configurator. Channel group order can be used to override channels in channel groups, as RAIL will always load the channel from the first channel group in which it is defined. For more on Multi-PHY configuration, see the example in [AN1253: EFR32 Radio Configurator Guide for Simplicity Studio 5](https://www.silabs.com/documents/public/application-notes/an1253-efr32-radio-configurator-guide-for-ssv5.pdf). ##### Finalizing a Configuration When a parameter is modified from its pre-loaded value, small pictograms show up next to the property field on the card. These pictograms symbolize the differences against the originally selected PHY configurations. A "C" means a difference from the original Channel Group property, and a "P" means a difference from the original Protocol Configuration. ![radio conf pictograms](/ss-5-users-guide-developing-with-project-configurator/1.0/images/radio-conf-pictograms.png) Each input field has an **Information** icon next to it, which opens the embedded version of [AN1253: EFR32 Radio Configurator Guide for Simplicity Studio 5](https://www.silabs.com/documents/public/application-notes/an1253-efr32-radio-configurator-guide-for-ssv5.pdf) at the relevant section. You can also reach the documentation by clicking **View Manual** in the top right corner of the perspective. ![radio conf information icon](/ss-5-users-guide-developing-with-project-configurator/1.0/images/radio-conf-information-icon.png) On save the Radio Configurator generates _rail_config.c_ and _rail_config.h_ in the project's _autogen_ directory. These files are also generated when a project is created. #### Wi-SUN Configurator When you create a new Wi-SUN project, a Wi-SUN Configurator is added to it by default. The Wi-SUN Configurator provides an interface to the Wi-SUN application's main settings through three panels: Application, Security, and Radio. For some examples, the Wi-SUN Configurator only displays the Radio panel. These examples do not have the application and security infrastructure. The Wi-SUN Configurator tab can be displayed by opening /config/wisun/wisun_settings.wisunconf. For more information, click **View Manual**. ##### Application Panel The Application panel exposes multiple Wi-SUN stack settings associated with the application, such as: - The network name the device will try to connect to - The network size setting - The device’s TX output power - The unicast dwell interval ![Wi-SUN configurator application panel](/ss-5-users-guide-developing-with-project-configurator/1.0/images/wi-sun-application.png) The MAC address filtering feature provides a way to force a topology on a Wi-SUN network. It is a simpler alternative to spacing out the Wi-SUN devices to achieve the desired topology. A device either does or does not interact with other Wi-SUN devices on the list, depending on the allow/deny option. ##### Security Panel The Security panel displays the private key and certificates used by the device to authenticate itself when connecting to a Wi-SUN network. By default, it uses the Silicon Labs demonstration samples. They can be modified to use a distinct certificate infrastructure aligned with the border router or authenticator certificate. ![Wi-SUN configurator security panel](/ss-5-users-guide-developing-with-project-configurator/1.0/images/wi-sun-security.png) ##### Radio Panel The Radio panel is an interface to configure the radio profiles included in a Wi-SUN application. It provides a user interface to access any specified Wi-SUN FAN 1.0 or FAN 1.1 PHY. A radio button allows the user to choose between the FAN 1.0 or FAN 1.1 context. The complete list can be filtered to help you find the right PHY configuration. An application can embed several PHYs from different regions and different specification versions. ![Wi-SUN configurator radio panel](/ss-5-users-guide-developing-with-project-configurator/1.0/images/wi-sun-radio.png) The **Application’s Default PHY** input defines the PHY that the application starts with. The default value depends on the EFR32 radio board used to create the project. For example, a BRD4163A radio board supporting the 868 MHz band defaults to the mandatory Wi-SUN PHY for the European region (that is, Wi-SUN FAN EU - 1 – 1a). On the other hand, a BRD4164A radio board supporting the 915 MHz band defaults to the North America mandatory Wi-SUN PHY (that is, Wi-SUN FAN NA - 1 – 1b). The user can always open the dropdown list and select another default PHY. Every selected Wi-SUN PHY can be edited in the Radio Configurator by clicking the pen icon. This action opens the Radio Configurator user interface on the selected Wi-SUN PHY. Moreover, non Wi-SUN FAN PHY are listed under “Other Custom Profile” for information. #### ZCL Advanced Platform (ZAP) The ZCL Advanced Platform (ZAP) is a tool used to configure endpoints for Zigbee and Matter. When you open ZAP, it launches in a new tab next to the .slcp tab. A Zigbee or Matter application can have multiple endpoints. Each endpoint contains a device configuration made up of Clusters on that end-point. The cluster groups differ depending on whether you re configuring a Zigbee or a Matter project, and the interface differs slightly. ZAP for Zigbee: ![ZAP with Zigbee skin](/ss-5-users-guide-developing-with-project-configurator/1.0/images/zap-with-clusters.png) ZAP for Matter: ![ZAP with the Matter skin](/ss-5-users-guide-developing-with-project-configurator/1.0/images/zap-matter.png) This section is illustrated with a Zigbee project, but the information applies to Matter as well. For more details about using ZAP with Matter, see [Matter References: Using ZAP, the ZCL Advanced Platform](https://docs.silabs.com/matter/latest/matter-references/matter-zap). At any point click Tutorial in the menu for an interactive tutorial. Click **ADD ENDPOINT** to add a new endpoint. ![ZAP opening tab with one endpoint](/ss-5-users-guide-developing-with-project-configurator/1.0/images/zap-new-gui.png) In the next dialog, select a device type for the endpoint, and optionally change the endpoint number. Click **CREATE** to create the endpoint. ![ZAP creation dialog](/ss-5-users-guide-developing-with-project-configurator/1.0/images/zap-create-cluster.png) To modify an endpoint, select it in the left panel. ![Zigbee Cluster Configurator with endpoint selected](/ss-5-users-guide-developing-with-project-configurator/1.0/images/zap-select-cluster.png) The Filter dropdown in the upper right filters the clusters shown. To see only clusters that are enabled on the endpoint, select 'Enabled Clusters'. ![The Show dropdown](/ss-5-users-guide-developing-with-project-configurator/1.0/images/zap-enabled-cluster-filter.png) Settings in the Enable column enable either the Client or Server (or both) sides of a cluster. Depending on the changes you make, you may be notified that components have been added to your project. To remove the cluster entirely from the configuration, select 'Not Enabled'. ![The selection available in the Enable column](/ss-5-users-guide-developing-with-project-configurator/1.0/images/zap-clusters2.png) Click the Gear icon next to a cluster to enable or disable attributes, manage how they are stored, manage attribute reporting, and also manage the handling of commands on that cluster. The cluster configuration interface consists of three tabs: - Attributes - Attribute Reporting - Commands ![Configuring a cluster](/ss-5-users-guide-developing-with-project-configurator/1.0/images/zap-attribute-reporting.png) Configuration changes made through the Zigbee Cluster Configurator for a Zigbee project are saved to \config\zcl\zcl_config.zap. For a Matter project the configuration is saved to \config\zap\.zap. The .zap file is the backing data file for the Zigbee Cluster Configurator configuration for your application. When you save the file, the Zigbee Cluster Configurator not only saves the .zap file into your project, but also automatically generates all the files required for your application. For Zigbee, the files are placed in the project's _autogen_ folder and all start with the 'zap' prefix. For Matter, the files are placed in the project's _autogen > zap-generated_ folder. For additional details about cluster configuration and adding a custom cluster, see the Zigbee-focused _AN1325: Zigbee Cluster Configurator User's Guide_. #### Solutions A solution is a construct that combines two or more projects such that they can be compiled, debugged, and flashed together. The solution is defined by a metadata .solutions file. Solutions can be local or shared. In a local solution, the .solutions file is stored in the Simplicity Studio Workspace. In a shared solution, the file is stored in the project specified when the shared solution is created. Shared solutions are easier to place under source control, and they can be exported to other Workspaces. Solution examples are available on the Example Projects and Demos tab or you can create your own through **File > New > Solution** or **Projects > Manage Solutions > New**. The resulting dialog shows available projects in the current Workspace. Name the solution, select the projects to be included in it, and click **Finish**. ![Create new solution](/ss-5-users-guide-developing-with-project-configurator/1.0/images/solutions-new.png) **Note: The generic term for the construct that combines multiple projects is a workspace. However, in Simplicity Studio a Workspace is a special directory into which projects (and solutions) are created. Therefore, whenever possible, Simplicity Studio documentation uses the term 'solution' for this construct.** ##### Create a Solution from an Example When you create a solution based on an example, the configuration dialog allows you to edit the name of the projects in the solution as well as the solution. ![Project Configuration dialog for a solution](/ss-5-users-guide-developing-with-project-configurator/1.0/images/solution-example-create.png) Each project in the solution then opens individually. Project Explorer view shows the solution as a separate folder, and projects in the Workspace folder that are not included in the solution as 'Other Projects'. ![Project Explorer view with one solution and Other Projects](/ss-5-users-guide-developing-with-project-configurator/1.0/images/solutions-project-view.png) Configure the projects in the solution as you would other project. Select the solution folder and click **Build** to build all projects in the solution. Project- and solution-level post-build script files (.slpb) are provided with the examples, and will combine the individual projects into a downloadable .s37 image. Double-click an *.slpb file to open the [Post-Build Editor](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-building-and-flashing/post-build-editor) to see how the script is configured. ![Solution level post-build editor](/ss-5-users-guide-developing-with-project-configurator/1.0/images/solution-post-build-editor.png) While the default memory use in the example solutions is fine for development and debugging, you can use [Memory Editor](memory-editor) to finalize the application memory layouts. Rebuild the solution to update the memory configurations. Solutions are required for applications to take advantage of the EFR32 Series 2 TrustZone security feature. See [AN1374: Series 2 TrustZone](https://www.silabs.com/documents/public/application-notes/an1374-trustzone.pdf) for a discussion of both the feature and how solutions are used to implement it. ##### Manage Solutions Right-click the Solution in Project Explorer view, and click **Solutions** on the context menu to open the Manage Solutions dialog, set the active Configuration or sync solution configurations. With **Manage Solutions** (also available on the Project menu) you can create, edit, and remove solutions. ![Manage solutions with one project](/ss-5-users-guide-developing-with-project-configurator/1.0/images/solutions-manage.png) Click **Edit...** to rename a solution, add or remove projects from a solution, or save a local solution as a shared solution. You must specify the project to contain the solution metadata. If the projects have multiple build configurations and the solution also has multiple build configurations, click **Sync Solution Configuration** to set the active build configuration of each project to match the solution's active build configuration. #### Memory Editor The Memory Editor is a graphical tool for editing the flash and RAM memory layout of the applications in a solution. It can be opened from the Project Configurator Configuration Tools tab or the Quick Links card on the Overview tab. Memory Editor shows the Flash and RAM memory map for the projects in the solution. The default memory settings in the example solutions are good enough for software development and debugging, but with the Memory Editor you can fine-tune memory use based on your needs. ![Memory Editor RAM tab](/ss-5-users-guide-developing-with-project-configurator/1.0/images/memory-editor-ram.png) ![Memory Editor RAM tab](/ss-5-users-guide-developing-with-project-configurator/1.0/images/memory-editor-ram.png) When you alter memory used by changing either or both applications' start or end location or size and save the changes, Memory Editor updates the linker file in the project autogen folder with the custom settings. Rebuild the projects to use the new memory configurations in the linker files. Memory Editor displays a warning if your changes cause the applications' memory use to overlap. This is a beta implementation. Not all example projects have default settings included at this time, which results in a warning when you open the editor. Save the default values that the tool calculates as your starting point. #### Retarget Project Workflow Most developers begin their evaluations and firmware development with our development boards but eventually transition to custom hardware. To support this, Silicon Labs provides developers with tools and resources to seamlessly retarget example applications for their own custom boards based on the same or similar device OPN. - For developers aiming to run a Silicon Labs SDK example application on their custom board. - For developers who have prototyped an application using a Silicon Labs development kit and wish to migrate their project to a custom board with the same or a similar target device. ![Retarget Project workflow](/ss-5-users-guide-developing-with-project-configurator/1.0/images/retarget-project-workflow.jpg) 1. Search for a Silicon Labs Development Kit based on the same or similar target device as what’s on the custom board. Silicon Labs boards are typically designed with superset target devices to maximize coverage, providing developers access to features such as additional pins, increased memory, enhanced peripherals, and expanded system capabilities. For custom board designs using devices within the same device family, the retargeting workflow supports transitions between superset and subset devices. 2. Create a project based on the desired example for the Silicon Labs Development Kit. 3. From Studio Project Configurator, retarget the board and target device. - Retargeting projects from Silicon Labs board examples utilizes the board configuration, software components, and drivers (e.g., LEDs, buttons, HFXO, LFXO, RF front-end, sensors) inherited from the original Silicon Labs board. This approach carries over the board support configuration to the custom board project, eliminating the need for manual BSP creation with the Pintool, provided the custom board's pin configuration matches the Silicon Labs board. If the pin configuration differs, such as an LED being assigned to a different pin, the developer must update the configuration using the Pintool based on the custom board's schematics. 4. Resolve any misconfigurations (e.g. pin definitions) that may have resulted from the migration. - When retargeting to a target device with a different pinout (fewer or additional pins), the developer must resolve the pin differences based on the custom board schematic. - When retargeting to a target device with the same hardware features (e.g., peripherals, power modes, and memory), the configuration from the original example is retained. However, when retargeting to a device with fewer hardware features, resulting in the loss of a peripheral, the developer must manually address unsupported components to prevent build failures. - When retargeting to a target device with different memory density, the project configurator will modify and define the Linker file accordingly. The example app's system behavior and performance should remain consistent with the original, provided the custom board's hardware matches that of the Silicon Labs board. Developers can generate a Project Configuration Report to summarize installed board components and verify the project's configuration. ### Developing with AppBuilder #### Developing with AppBuilder Simplicity Studio® 5 (SSv5)'s AppBuilder is a graphical tool used to create configurations and build Application Framework files. The AppBuilder configuration files indicate which features and functions you would like for your compiled binary image. By using AppBuilder along with an application framework, you can quickly create an application that includes all of the required functionality for the image's purpose. AppBuilder must be used in conjunction with one of the Silicon Labs application frameworks, which are shipped as part of the SDK. All of the code that will be compiled into the binary image is included in the SDK distribution. AppBuilder creates configuration and build files that tell the application framework which portions of the code to include in, and which to exclude from, the compiled binary image. With the exception of a few header (.h) files, AppBuilder does not generate the C source code for the application. All of the source code that ultimately will be included in the binary image is provided in the Application Framework. In general, to develop an application using AppBuilder: 1. Create an application based on one of the AppBuilder examples, such as Z3Switch. 2. Customize the application on the various AppBuilder tabs. Functions can be added by enabling and configuring plugins. 3. Click **Generate** to create application files. 4. Optionally, add your own code to the application. Once you have finishing customizing your project, [build and flash it](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-building-and-flashing), and then [test and debug it](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-testing-and-debugging/overview-and-resources). #### Configuring a Project Simplicity Studio® 5 (SSv5)'s AppBuilder provides a tabbed interface. Each tab provides customization options. - [**General**](#general) - Configure global values for your application like the Device Name and Generation Directory - [**ZCL Clusters**](#zcl-clusters) - Choose the specific combination of clusters to include - [**Zigbee Stack**](#zigbee-stack) - Configure stack-specific settings - [**Printing and CLI**](#printing-and-cli) - Configure debug printing and CLI options - [**HAL**](#hal) - Configure bootloader and board header file options, and access the Hardware Configurator tool to manage peripheral configurations - [**Plugins**](#plugins) - Include or exclude plugins, where a plugin is a specific implementation of a cluster or some other functionality - [**Callbacks**](#callbacks) - Select from a set of predefined callbacks - [**Includes**](#includes) - Include any external files into the generated project - [**Other Options**](#other-options) - Configure PHY support, plugin services, and other options - [**Bluetooth GATT**](#bluetooth-gatt) - For use with dynamic multiprotocol applications, provides a direct interface to the GATT configurator ##### General The General tab provides information about the example used as a foundation for the project, and lets you change project level information, such as the toolchain used. ![ab general](/ss-5-users-guide-developing-with-appbuilder/0.6/images/ab-general.png) **Generation directory** shows where project files will be generated. By default this is a directory in the default SSv5 workspace. Click **Edit Architecture** to change the target device or the toolchain. ![ab general architecture](/ss-5-users-guide-developing-with-appbuilder/0.6/images/ab-general-architecture.png) ##### ZCL Clusters The ZCL Clusters tab provides functionality to manage endpoints and their cluster configuration. ![ab zcl clusters](/ss-5-users-guide-developing-with-appbuilder/0.6/images/ab-zcl-clusters.png) **Multiple Endpoint Configuration Table** The Multiple Endpoint Configuration Table allows you to configure the endpoints on your device. Click **New** to add an endpoint. **Endpoint**: Change the endpoint on which your device will be hosted by clicking the number in the Endpoint column. The number field becomes editable. Change the endpoint to any of the valid Zigbee endpoints available. **Configuration**: Each endpoint implements a specific configuration. The configuration is not a Zigbee construct. It is a name created for Simplicity Studio AppBuilder so that multiple endpoints that implement the same application can share the metadata associated with that application. This conserves the use of flash within the device. By default, each new endpoint will implement the configuration named "Primary." Change the configuration by selecting the endpoint row and then clicking on the "Configuration" column. A button appears to the right of the Configuration name. Click the button to launch the configuration dialog. Once you have created a new configuration, the application for that configuration can be implemented on as many endpoints as you like without using any more memory on your device for metadata storage. Each endpoint still needs to have its own attribute storage to contain the endpoint-specific values. AppBuilder and the application framework take care of this for you. **Network**: By default, the first endpoint belongs to the network named "Primary." When new endpoints are created, they will belong to the same network as the first endpoint. On platforms that support multi-network, you may choose the network for a specific endpoint. New networks can be created and configured in the Zigbee Stack tab. **ZCL Device Type**: Select from a set of pre-defined ZCL Device Types. AppBuilder then populates the cluster table with the clusters appropriate to that device type as defined by the Zigbee Cluster Library specification. In addition to these pre-defined device types, you also have the option to create a custom device type. With this option, you can choose from any of the available Zigbee clusters included within the Application Framework. **Cluster Table** The Cluster Table displays which clusters will be included as part of each endpoint type.In the case of a custom device implemented on any endpoint, you have the option to choose the clusters to include and their client/server role. **Attribute Table** When you click a specific cluster, its attributes display in the Attribute Table. Configure the device's behavior by configuring the attributes in this table. ![ab zcl clusters attribute table](/ss-5-users-guide-developing-with-appbuilder/0.6/images/ab-zcl-clusters-attribute-table.png) **External Attribute storage**: By default, all attributes are stored in a RAM buffer provided by the application framework. Storing some attributes may not make sense, however, since they are either already stored somewhere else in the system or are not stored at all but read from some external piece of hardware. In this case you may indicate that the attribute is externally stored. When the application framework needs to interact with the attribute it will use the external attribute callbacks. By implementing these callbacks and marking the attribute as externally stored, the attribute storage is removed from the framework and placed into the domain of the application. The metadata used to represent the attribute on the network is still stored inside the framework so that the framework can respond to ZDO requests and so on. **Persistent attribute storage**: By default, all attributes are stored in RAM. As a result, attribute data does not survive a reboot of the device. If you want to maintain state for an attribute across reboots, the attribute must be stored in persistent memory on the device. To store a specific attribute in persistent memory, check the checkbox in the F column. **Singleton attribute storage**: Most attributes are stored as a separate value for each endpoint on which they are implemented. This does not make sense for some attributes that may exist across endpoints. For instance, it makes little sense to store multiple copies of the Basic Cluster's ZCL Version since the version pertains to the entire application and not to each individual endpoint. Attribute values may be shared across endpoints by indicating that the attribute is a "singleton." **Bounding attributes to their Min and Max values**: By default, the application framework allows you to write any value (within the limits of the size of the attribute) into the attribute table. However, you may request that the application framework reject any attribute value outside the Min and Max defined by the Zigbee specification by checking the checkbox in the B column. The application framework then stores the min and max values for the chosen attribute in the attribute table and rejects any write request, whether from the CLI or an external device, that is outside the attribute value range. ##### Zigbee Stack Here you can configure networks and add custom clusters. ![ab zigbee stack](/ss-5-users-guide-developing-with-appbuilder/0.6/images/ab-zigbee-stack.png) ##### Printing and CLI Here you can enable and configure debug printing, and enable/disable CLI functionality. ![ab print cli](/ss-5-users-guide-developing-with-appbuilder/0.6/images/ab-print-cli.png) **Debug printing** The application framework can output application and stack debug information over the serial port. To choose the information to include in the debug output, select from the serial printing checkboxes. If you are not concerned with debug output, and/or would prefer to conserve the flash and RAM associated with debugging, turn off the serial printing options by deselecting them. **Command Line Interface (CLI) Options** AppBuilder can output either a "Legacy" or "Generated" command line interface. **Use Legacy CLI**: If checked, AppBuilder uses the hard coded CLI interface included in the application framework. Otherwise AppBuilder generates a Command Line Interface along with other generated files based on the CLI interface options selected in the CLI configuration window. **Add Custom CLI Sub-menu**: Adds the ability to include user-defined CLI commands into the Command Line Interface. **Include Command and ...**: Includes a description for each command or argument into the Command Line Interface. Turning this on will increase the size of your application but will make it easier to use the Command Line Interface since all commands will be self-described when a command is not recognized by the application. **Use Command Set**: Makes it possible to turn the command line interface on and off and choose a pre-defined subset of the CLI for use in your application **CLI Configuration Table**: Select exactly what CLI commands are supported in the application. By default, the Full command line interface command set selects all General commands and all cluster and plugin commands supported by clusters and plugins included in the application. ##### HAL Use the HAL tab to configure hardware-specific options for your device. ![ab hal](/ss-5-users-guide-developing-with-appbuilder/0.6/images/ab-hal.png) For EFR32 devices, most hardware configuration is done through the [Hardware Configurator](configuring-peripherals). Under **Hardware Configurator Interface** click **Open Hardware Configurator**. **Bootloader** - Select the type of bootloader to use. See [UG103.6: Bootloader Fundamentals](https://www.silabs.com/documents/public/user-guides/ug103-06-fundamentals-bootloading.pdf) as a starting point to learn more about bootloaders. ##### Plugins Use the Plugins tab to include, exclude, and configure the functional implementations called plugins. ![ab plugins](/ss-5-users-guide-developing-with-appbuilder/0.6/images/ab-plugins.png) Include/exclude plugins by checking/unchecking them. Select a plugin to see information about it and configurable parameters, if any. Some plugins provide access to the Hardware Configurator peripheral settings. These plugins have a Hardware Configurator Dependent Options pane. You may need to scroll down in that pane to see all options. Enabling/disabling plugins can also enable and disable Hardware Configurator modules and their dependent peripherals. When a plugin with Hardware Configurator dependencies is enabled/disabled, a pop-up dialog box shows which Hardware Configurator modules and peripherals are being enabled/disabled. Also, when a plugin that shares Hardware Configurator modules/peripherals with another plugin is enabled/disabled, a similar warning shows which peripherals are being affected behind the scenes in the Hardware Configurator. See [Configuring Peripherals](configuring-peripherals) for information on using the Hardware Configurator directly. For more details on both plugin and tool access, see [AN1115: Configuring Peripherals for 32-Bit Devices using Hardware Configurator](https://www.silabs.com/documents/public/application-notes/an1115-32-bit-device-peripheral-configuration-in-simplicity-studio.pdf). ##### Callbacks Use the Callbacks tab to add or remove callbacks, and to see the callbacks that are required by plugins or other code. Select a callback to see its code and other information about it. ![ab plugins](/ss-5-users-guide-developing-with-appbuilder/0.6/images/ab-plugins.png) Enabled callbacks must be implemented in application code, otherwise you will get linker errors. Callbacks are grouped into logical sections in the callbacks tab for ease of navigation. Callbacks implemented by an included plugin have the plug symbol. All of the custom application framework callbacks are included in the "Non-cluster related" section. All of the other callbacks are grouped by cluster. Many of the cluster-specific callbacks are intended for command handling. When a command comes in, it is passed off to a cluster-specific callback for processing. If the callback returns TRUE then the internal handler for that command will not be called. Cluster-related callbacks are also only implemented for those client and server clusters that are included in the application. If a cluster is not included, the application is not expected to parse that cluster's commands. The application framework returns a default response of UNSUPPORTED_COMMAND. **Callback generation**: The first time you generate your application from AppBuilder, it automatically generates a callbacks.c file with the name _callbacks.c. When you regenerate files in the future, AppBuilder protects your generated callbacks file from being overwritten by asking if you want to overwrite it. By default, AppBuilder will not overwrite any previously created callbacks file. If you choose to overwrite the file, AppBuilder backs up the previous version to the file _callbacks.bak. ##### Includes Use the includes tab to manage information included in the application. ![ab includes](/ss-5-users-guide-developing-with-appbuilder/0.6/images/ab-includes.png) **Additional .c and .h files** When you generate a project file from AppBuilder, you often need to modify the project to include your own source files into the application image. This is a problem if the project file needs to be re-generated, since the newly generated project file will overwrite the old one, thereby removing any files that have been included. Any files that you would like to compile along with your application can be included in the file include table. To include a new file, click **New**. Navigate to the location of the file you wish to include and click **OK**. The file will be included inside the generated project file with an absolute path to the location of the file. **Token Configuration** To implement attributes in tokens, the application framework places its own token file into the generated APPLICATION_TOKEN_HEADER #define within the generated project file. The application framework's token header file, located at app/framework/util/tokens.h, includes a spot where you may place a relative path to your own token header. The token header files are chained off one another with the application framework's token header at the top of the chain. To include your own token header within your application, provide absolute or relative path inside the appropriate Token Configuration path field. **Additional Macros** Much of the configuration for the application framework and the stack is done using macros documented within the API. Any additional macros that you wish to define, either for compile time or for run time, should be provided here. Compile-time macros should include the "-D" option. These macros will be included in the compiler and linker definition sections in the generated project file. Any macros which do not include the "-D" option will be included in the generated application header file. **Event Configuration** You can include custom application events into the application framework's event system. These events are run in the same manner as the application framework's own events as well as all cluster events implemented by the cluster plugins. To include a custom event, click **Add New**. Your custom event will be automatically included in the event configuration section of the generated _endpoint_configuration.c_ file. Stubs for your event function and event control will be generated into the _callbacks.c_ file. You may also change the name of the generated event control value and function to whatever you desire. For more information on how events work [UG391: Zigbee Application Framework Developer’s Guide](https://www.silabs.com/documents/public/user-guides/ug391-zigbee-app-framework-dev-guide.pdf) . ##### Other Options Use the Other Options tab to configure PHY support, stack protection, and to manage plugin-provided services. ![ab other options](/ss-5-users-guide-developing-with-appbuilder/0.6/images/ab-other-options.png) ##### Bluetooth GATT For Dynamic Multiprotocol applications, use the Bluetooth GATT tab to configure the GATT database for the Bluetooth application. ![ab gatt](/ss-5-users-guide-developing-with-appbuilder/0.6/images/ab-gatt.png) For more information about Bluetooth GATT database configuration see [UG365: GATT Configurator User's Guide for Bluetooth SDK v2.x](https://www.silabs.com/documents/public/user-guides/ug365-gatt-configurator-users-guide.pdf). #### Configuring Peripherals Simplicity Studio® 5 (SSv5)'s AppBuilder HAL tab provides access to a **Hardware Configurator** that you can use to configure pins and peripherals. Access to specific configuration options is also available through various peripheral [plugins](configuring-a-project#plugins). To open the Hardware Configurator for an open project, double-click the _.hwconf_ file in Project Explorer, click **Open Hardware Configurator** on the HAL tab, or select **Hardware Configurator** from the Tools menu and then select the target project. The Hardware Configurator has two views, accessed through the two DefaultMode tabs at the bottom of the center pane: - [Port I/O](#port-i-o): Used to configure the pin locations and port pins - [Peripherals](#peripherals): Used to configure modules such as Timers, USARTs, and HAL peripherals. Most configuration changes can be made through this tab. ![ab hdw conf port io](/ss-5-users-guide-developing-with-appbuilder/0.6/images/ab-hdw-conf-port-io.png) ##### Port I/O The Port I/O tab displays a package drawing for the selected device. This drawing updates to display changed pin assignments. Hover the cursor over a pin to see its definition. White = unused, blue = assigned, orange = two or more signals going to the pin, conflict allowed, and red = two or more signals going to the pin, conflict not allowed. While you can make some changes to the peripheral associated with a given pin, Silicon Labs recommends changing peripheral configuration through the Peripheral tab. Use this configuration for pin customizations such as renaming the pin. Some changes must be made in both the Port I/O and Peripherals tab. For example: - A route can be selected in Port I/O and an APORT channel can be selected in the peripherals properties. - ACMP output can be selected on the Port IO route selection and ACMP inputs can be configured in the Peripherals section. A printable report can be generated by right-clicking on the pinout diagram and selecting Pin Configuration Report. This opens a report as a webpage in a browser that can be saved, printed, or archived. The Module Configuration Report option generates a similar set of tables organized by module rather than by pin order. Note: To share information about the hardware configurations for a device Silicon Labs recommends sharing the .hwconf file itself. ##### Peripherals The Peripherals tab contains boxes, each of which represents either a hardware peripheral or a software concept that is HAL-related but not physically on the chip. Peripheral boxes are organized into groups. Collapse or expand a group by clicking the arrow icon on the upper right of the group. Hover your cursor over a box to see information about the peripheral. ![ab hdw conf peripherals](/ss-5-users-guide-developing-with-appbuilder/0.6/images/ab-hdw-conf-peripherals.png) Click on a box to see its properties in the Properties pane. Properties can either have a drop-down menu with the available selections or a text input box for a numeric or text field. After making a selection for a property, click away from the property or press **Enter** to ensure the property value change occurs. If you cannot disable a peripheral it may be owned by another peripheral. Go to the settings for that peripheral to free up any dependent peripherals. Note: The defines for the peripheral are only generated if the checkbox on the peripheral box is checked. For example, the interface for a project based on the Silicon Labs Zigbee Z3LightSoc example has a HAL group with a Button peripheral. Click on that peripheral to see its properties. ![ab hdw conf peripherals detail](/ss-5-users-guide-developing-with-appbuilder/0.6/images/ab-hdw-conf-peripherals-detail.png) ## Developing for 8-Bit Devices ### Developing for 8‑Bit Devices Hardware Configurator (Configurator) for 8-bit devices is part of Simplicity Studio® 5 (SSv5) and greatly simplifies EFM8 and C8051 MCU peripheral initialization by presenting peripherals and peripheral properties in a graphical user interface. The 8051 SDK contains an extensive and nearly comprehensive set of examples for 8-bit MCU peripherals for each supported device family. These examples show simple use cases for each peripheral, and can be used as building blocks for larger systems incorporating multiple peripherals, or as a starting place for applications requiring each peripheral. Projects based on these examples are customized by changing code as described in [About Projects](about-projects) and by updating peripheral configuration using the 8-bit [Hardware Configurator](using-hardware-configurator). In Hardware Configurator, most of the initialization firmware can be generated by selecting peripherals and property values from combo boxes or entering register values in text boxes. Some peripherals provide calculators, such as baud rate, timer overflow rate, and SPI clock rate, that can be used to automatically confirm the necessary reload register value to generate the specified clock rate. Hardware Configurator also provides real-time property validation to ensure that a configuration is valid before downloading code to the MCU. ### About Projects Create a Simplicity Studio® 5 (SSv5) project for an 8-bit target by selecting a target device, and then selecting an example, as described in [Project Creation](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-getting-started/start-a-project#project-creation). An extensive list of examples is provided for most Silicon Labs EFM8 and C8051 devices. These examples contain configurations specific to each target device. ![8 bit examples](/ss-5-users-guide-developing-for-8bit-devices/0.6/images/8bit-examples.png) The [Simplicity IDE perspective](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-about-the-simplicity-ide) opens with the project directory highlighted in Project Explorer view. Expand the directory and double-click the project source to see or modify the code. ![8 bit code start](/ss-5-users-guide-developing-for-8bit-devices/0.6/images/8bit-code-start.png) Open Hardware Configurator by double-clicking the _.hwconf_ file in Project Explorer, or by selecting **Hardware Configurator** from the Tools menu, and selecting the project. ![8 bit hwconf tool start](/ss-5-users-guide-developing-for-8bit-devices/0.6/images/8bit-hwconf-tool-start.png) Use Hardware Configurator to customize the configuration and functionality as desired. Modifications to the device configuration can be saved to the _.hwconf_ file. Hardware Configurator generates output in the form of generated code in multiple files, as described in [Using Hardware Configurator](using-hardware-configurator). Build and debug the application as described in [Building](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-building-and-flashing/building) and [Using the Debugger](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-testing-and-debugging/using-the-debugger). ### Using Hardware Configurator Simplicity Studio® 5 (SSv5)'s Hardware Configurator for 8-bit devices uses the **Configurator** perspective. This perspective is tailored specifically for use with Hardware Configurator to initialize MCU peripherals. Special views in this perspective allow peripheral registers to be configured. The available editors in a Configurator project are as follows: - [**Peripherals**](#peripherals): Used to configure hardware peripherals such as ADCs, Timers, LEUART, PCAs, and so on. - [**Port I/O**](#port-i-o): Used to configure the pin locations, crossbar, and port pins. This editor is open by default for a new project. - [**Mode Transitions**](#mode-transitions): Used to define different MCU peripheral initialization states, such as DefaultMode, RESET, and other optional modes (example: LowPower mode). This editor can also be used to define transitions between states. The Hardware Configurator automatically validates register configuration values. Occasionally changes to the configuration can cause [errors or warnings](#errors-and-warnings). These clear as soon as the cause is addressed. #### Peripherals Use the Peripherals tab to configure hardware peripherals like the ADC, comparators, or timers. To configure a peripheral, click the peripheral icon. This selects the peripheral and opens it in the Properties view. Properties can either have a drop-down menu with the available selections or a text input box for a numeric or text field. Properties that are grayed out are read-only. These properties typically provide more information about the configuration of a peripheral. After making a selection for a property, click away from the property or press **Enter** to ensure the property value change occurs. ![8 bit hwconf peripherals](/ss-5-users-guide-developing-for-8bit-devices/0.6/images/8bit-hwconf-peripherals.png) For example, click the Timers peripheral to display the timer properties in a tabbed view. The Timer 3 tab has several properties that can be modified, like **Clock Source**, **Mode**, and **Target Overflow Frequency**. Modifying any of these properties will update the **Timer Reload Overflow Period** and **Timer Reload Overflow Frequency** read-only properties, which display the calculated overflow time based on the **Target Overflow Frequency** and the **Clock Source** settings. These read-only fields and calculators depend on the Mode and Run Control state. Calculators for reload value are for auto-reload mode. ![8 bit hwconf peripherals properties](/ss-5-users-guide-developing-for-8bit-devices/0.6/images/8bit-hwconf-peripherals-properties.png) Note: Peripherals will not have [code generation](#code-generation) enabled unless the peripheral checkbox is checked. #### Port I/O The Port I/O tab displays a package drawing for the selected device. This drawing updates to display pin assignments as peripherals are enabled on the crossbar or peripherals with fixed pin assignments are enabled. For fixed pin assignments, the associated peripheral must be enabled in order for the fixed pin function to appear on the Port I/O tab. Changes are shown in blue until the file is saved. ![8 bit hwconf portio](/ss-5-users-guide-developing-for-8bit-devices/0.6/images/8bit-hwconf-portio.png) For example, on the Peripherals tab make sure the ADC0 module is checked. On the port I/O tab, in the Outline view select ADC0, in Properties change **Enable ADC** to `Enabled`, and select a **Positive Input pin** (in this example P1.3). This displays the ADC_IN fixed signal on the selected pin in the drawing. ![8 bit hwconf portio adcin](/ss-5-users-guide-developing-for-8bit-devices/0.6/images/8bit-hwconf-portio-adcin.png) To enable a peripheral on the crossbar, on the Peripherals tab enable a peripheral for code generation (in this case Clock Control). On the Port I/O tab, in the Outline view click CROSSBAR0, and in the Port I/O Mapping view check the corresponding signal. This changes the corresponding property to `Enabled`. ![8 bit hwconf portio sysclk](/ss-5-users-guide-developing-for-8bit-devices/0.6/images/8bit-hwconf-portio-sysclk.png) To configure a pin’s properties, click the pin in the package drawing and select the desired pin property settings. If configuring a device with a crossbar, a pin can be skipped by right-clicking the pin and selecting **Skip** in the context menu or changing the Skip property setting. ![8 bit hwconf portio pinconf](/ss-5-users-guide-developing-for-8bit-devices/0.6/images/8bit-hwconf-portio-pinconf.png) Similarly, I/O mode can be selected by right-clicking the pin and selecting **IOMode** or changing the IOMode property setting. On all devices, multiple pins can be selected by holding Ctrl or Shift and selecting the desired pins or holding the left mouse button and dragging over a group of pins. With multiple pins selected, the property changes made in the Properties view or context menu apply to all pins. To reset a pin to its default state, right-click the pin and select **Reset**. #### Mode Transitions Modes define different states of peripheral configurations. For example, an application may use two configurations of the ADC and Timer 2 with different input pins and sampling rates. These two configurations can be treated as separate modes with separate initialization sequences. The movements between these modes are called transitions. By default, each project contains one **DefaultMode** mode. The reset state exists only to indicate the transition from RESET to DefaultMode and is not a full mode. ![8 bit hwconf mode trans](/ss-5-users-guide-developing-for-8bit-devices/0.6/images/8bit-hwconf-mode-trans.png) To add a new mode, right-click either the Mode Transitions tab or the Outline view and select **Create Mode from Reset**. Right-clicking an existing mode also enables cloning that mode with the **Clone Mode** option. To add a transition from one mode to another, hover over one of the four white handles on a mode until the mouse cursor changes, hold down left mouse button, and drag to the end mode of the transition. A Peripherals and Port I/O pair of tabs are added for each mode in the project. ![8 bit hwconf mode trans adding](/ss-5-users-guide-developing-for-8bit-devices/0.6/images/8bit-hwconf-mode-trans-adding.png) After reset, call the mode transition `enter_DefaultMode_from_RESET()` to apply the DefaultMode settings. In most cases this will be the first transition in the application code. Adding a transition generates a corresponding function that application firmware can call to initiate the transition between modes. For example, with DefaultMode as the originating mode going to Mode2: `enter_Mode2_from_DefaultMode(void)` This function then calls all of the functions that configure the peripherals for the mode. Hardware Configurator generates only the transitional code from peripheral to peripheral between modes. For example, if only the timer reload value and ADC input mux selection differ, then those are the only two properties touched by the transition code. To see the differences between two modes, right-click the mode transition and select **Show Differences**. This provides a report of all the different property values between the modes on a module-by-module basis. ![8 bit hwconf mode trans report](/ss-5-users-guide-developing-for-8bit-devices/0.6/images/8bit-hwconf-mode-trans-report.png) Transitions can be added in both directions using the same method as the original mode transition. To delete a mode transition, select the arrow and press Delete or right-click the arrow and select **Delete transition**. Transition functions will not modify the state of the global interrupt enable (EA) on EFM8 or C8051 devices. Transitions assume that interrupts are disabled (that is, global interrupt enable bit EA = 0) or that any enabled interrupts will not interact with any changes made during the transition. Transition functions do not clear interrupt flags, to ensure that no information is lost during reconfiguration. If having these flags set will cause an issue in firmware operation, firmware must clear these interrupt flags before calling the transition function. Transition functions also assume that any peripherals being updated are not active. For example, firmware should stop a timer before calling a transition function that changes the timer configuration and restart the timer after the transition completes. It is possible to change the configuration order of a set of peripherals by creating multiple modes with multiple transitions. For example, to configure Timer 2 before the ADC during a mode transition that would normally put the ADC first, create a mode to handle the Timer 2 changes and a mode to handle the ADC changes. Firmware can then call the Timer2 mode transition function first, followed by the ADC transition function. #### Errors and Warnings The Hardware Configurator automatically validates register configuration values and displays any errors, warnings, or information items in the Problems view. Double-clicking an entry displays the property that raised the problem in the Properties view. Any peripherals that contain a warning or error are highlighted in yellow (warning) or red (error), and the associated property has a corresponding warning or error icon. ![8 bit hwconf errors](/ss-5-users-guide-developing-for-8bit-devices/0.6/images/8bit-hwconf-errors.png) Once the highlighted property is updated, the associated warning or error will disappear from the Problems view, indicating that the problem has been solved. All newly created projects will have a warning regarding the Watchdog Timer, since it’s enabled after a reset and must be handled in application code or disabled. If a warning or error doesn’t apply to the project, it can be temporarily deleted from the project by right-clicking the entry in the Problems view and selecting **Delete**. Closing and reopening the _.hwconf_ file regenerates any deleted warnings or errors. #### Code Generation To generate code for a peripheral, check the checkbox for that peripheral in the Peripherals tab. Saving the project automatically generates code for all selected peripherals and port pins. This code generates into the _InitDevice.c_, _InitDevice.h_, and _Interrupts.c_ files. Each hardware register has a section in the _InitDevice.c_ file tagged with the register name and register description. For example, the P1 register area is as follows: ```c# // $[P1 - Port 1 Pin Latch] // [P1 - Port 1 Pin Latch]$ ``` These tags indicate that everything in between is automatically generated, so any code added manually between these tags will be deleted on the next Hardware Configurator project save. Code can be added in between these tags, however, and this code will not be overwritten. ```c# // $[P1 - Port 1 Pin Latch] P1 = 0x00; // This code is not safe, and Configurator will overwrite it // [P1 - Port 1 Pin Latch]$ P1 = 0x00; // This code is safe from Configurator automatic code generation // $[P1MASK - Port 1 Mask] // [P1MASK - Port 1 Mask]$ ``` For registers that are modified from their reset value or the value in the previous mode, the tags include comments that update based on the settings for the register. For example, setting P1.0 to push-pull on an EFM8 or 8-bit MCU generates the following: ```c# // $[P1MDOUT - Port 1 Output Mode] /* // B0 (Port 1 Bit 0 Output Mode) = PUSH_PULL // (P1.0 output is push-pull.) // B1 (Port 1 Bit 1 Output Mode) = OPEN_DRAIN // (P1.1 output is open-drain.) // B2 (Port 1 Bit 2 Output Mode) = OPEN_DRAIN // (P1.2 output is open-drain.) // B3 (Port 1 Bit 3 Output Mode) = OPEN_DRAIN // (P1.3 output is open-drain.) // B4 (Port 1 Bit 4 Output Mode) = OPEN_DRAIN // (P1.4 output is open-drain.) // B5 (Port 1 Bit 5 Output Mode) = OPEN_DRAIN // (P1.5 output is open-drain.) // B6 (Port 1 Bit 6 Output Mode) = OPEN_DRAIN // (P1.6 output is open-drain.) // B7 (Port 1 Bit 7 Output Mode) = OPEN_DRAIN // (P1.7 output is open-drain.) */ P1MDOUT = P1MDOUT_B0 PUSH_PULL | P1MDOUT_B1 OPEN_DRAIN | P1MDOUT_B2 OPEN_DRAIN | P1MDOUT_B3 OPEN_DRAIN | P1MDOUT_B4 OPEN_DRAIN | P1MDOUT_B5 OPEN_DRAIN | P1MDOUT_B6 OPEN_DRAIN | P1MDOUT_B7 OPEN_DRAIN; // [P1MDOUT - Port 1 Output Mode]$ ``` #### Interrupts The Hardware Configurator creates an _interrupts.c_ file containing interrupt prototypes whenever interrupts are enabled and the project is saved. Hardware Configurator generates the prototype if it is not present, but does not overwrite existing prototypes. This protects any application code written in the prototypes from being accidentally modified or deleted. The comments above the prototypes list any flags in the modules that may need to be cleared by application code after the interrupt triggers. ![8 bit hwconf interrupt](/ss-5-users-guide-developing-for-8bit-devices/0.6/images/8bit-hwconf-interrupt.png) ## Building and Flashing ### Building and Flashing These pages describe: - How to [compile or build](building) software into a binary image - How to configure additional build steps using the [Post-Build Editor](post-build-editor) to make customized binary images - How to [load or flash](flashing) that application image onto a connected device - The [Software Bill of Materials (SBOM)](sbom-generation) generation tool ### Building Simplicity Studio® 5 (SSv5) offers two convenient ways to compile or 'build' projects: - [Simple build](#simple-build) - [Debug build and flash](#debug-build-and-flash) Projects are built with the [toolchain](#about-toolchains) defined when the project was created, and using the active configuration. Project files must be generated before you can build the project. - For [32-bit device development using AppBuilder](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-with-appbuilder), click **Generate** in the Simplicity IDE. - Files are automatically generated if the project uses [Project Configurator](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-with-project-configurator). Progress is shown in the lower right of the Simplicity IDE perspective. ![new project generate](/ss-5-users-guide-building-and-flashing/0.8/images/new-project-generate.png) Speed varies depending on your system, number of projects, and other factors. Be sure that generation and indexing complete before building the application image. The result of the build is a compiled application known as a firmware image or binary. The binaries are physically located in a directory named for the compiler used to generate them, and are also shown as a 'binaries' group in project explorer. Right-click a binary for a context menu from which you can debug, flash, and perform other functions. The binaries generated depend on both the SDK and the target device. For example, the Keil® 8051 compiler for an 8-bit device generates: - *.hex (application image) - *.omf (contains additional debug information) The GNU ARM® compiler for a 32-bit device using the Zigbee EmberZNet SDK generates: - *.axf (image that can be read on a Microsoft Windows device) - *.bin (binary image file, can be flashed to any address) - *.gbl (Gecko Bootloader file, specialized firmware file for use with the Gecko bootloader) - *.hex (application image file) - *.s37 (similar to a binary file but contains the target memory location to flash to - an application image or a bootloader image, but not both) Note that if you need a .gbl file but do not see one in the binary directory, you can use Simplicity Commander to create one. Commands invoked from Simplicity Commander's CLI can be used to: - Generate key files for signing and encryption - Sign application images for Secure Boot - Create GBL images (encrypted or unencrypted, signed or unsigned) - Parse GBL images For details about using Simplicity Commander see [UG162: Simplicity Commander Reference Guide](https://www.silabs.com/documents/public/user-guides/ug162-simplicity-commander-reference-guide.pdf). For details about using the Gecko Bootloader, including its enhanced security features, see [UG266: Silicon Labs Gecko Bootloader User's Guide](https://www.silabs.com/documents/public/user-guides/ug266-gecko-bootloader-user-guide.pdf). See your SDK's quick-start guide for more stack-specific information about building and flashing. #### About Toolchains SSv5 provides a GNU ARM® toolchain to build projects for 32-bit devices and a 30-day evaluation license to the Keil® 8051 toolchain to build projects for 8-bit devices. You can apply for a free full license when you build an 8-bit project. ![build flash keil](/ss-5-users-guide-building-and-flashing/0.8/images/build-flash-keil.png) You can also add your own toolchain, for example IAR-EWARM. IAR is required for some projects, such as the Zigbee Dynamic Multiprotocol and Micrium OS examples. However, you must use the version specified in the SDK release notes front page under compatible tools. See your SDK's quick-start guide for information on how to load a compatible version and obtain a free evaluation license. SSv5 provides an integration package for IAR, so that you can use that tool within SSv5. ![build flash iar integration](/ss-5-users-guide-building-and-flashing/0.8/images/build-flash-iar-integration.png) Projects use the toolchain selected at the time of project creation. The selection is available on the first of the three New Project Wizard dialogs. ![new project target toolchain](/ss-5-users-guide-building-and-flashing/0.8/images/new-project-target-toolchain.png) The toolchain and build configuration are displayed in Project Explorer view with the project directory. The build configuration determines whether the image is built for debugging or release. Default is typically equivalent to a debug build. ![build flash project directory](/ss-5-users-guide-building-and-flashing/0.8/images/build-flash-project-directory.png) If more than one toolchain is available, you can configure which are presented as options when creating a new project. In the **Preferences** filter field type `toolchain`. Uncheck the ones you do not wish to display. You can also completely remove toolchains, or add new toolchains through this dialog. ![tips toolchains](/ss-5-users-guide-building-and-flashing/0.8/images/tips-toolchains.png) #### Simple Build Right-click the project directory and in the context menu select **Build**, or click the **Build (hammer)** button on the Simplicity IDE perspective toolbar to build a project with its toolchain and the active build configuration. ![build flash hammer](/ss-5-users-guide-building-and-flashing/0.8/images/build-flash-hammer.png) While the Build menu selection always uses the active configuration, the **Build** button's drop-down menu allows you to select a different configuration. This also changes the active configuration for the project to the one selected. If the **Build** button is not enabled, make sure you have a project directory or file in the directory selected. #### Debug Build and Flash Click the **Debug (bug)** button in either the Simplicity IDE or Debug perspective to build an application image, flash it to the device, and open the Debug perspective (if it is not already open). ![build flash debug button](/ss-5-users-guide-building-and-flashing/0.8/images/build-flash-debug-button.png) The **Debug** button's drop-down menu allows you to select the project in your workspace you want to debug. ![build flash debug drop-down](/ss-5-users-guide-building-and-flashing/0.8/images/build-flash-debug-drop-down.png) If you have a lot of projects use **Organize Favorites** to select favorites and organize them. These projects then appear at the top of the selection list with other projects below a demarcation line. ![build flash debug favorites](/ss-5-users-guide-building-and-flashing/0.8/images/build-flash-debug-favorites.png) Select **Debug Configurations** to open a tabbed set of configuration option dialogs. If you click **Debug**, the build and flash process will proceed with the options you selected. See [Using the Debugger](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-testing-and-debugging/using-the-debugger) for more information. ![build flash debug configuration](/ss-5-users-guide-building-and-flashing/0.8/images/build-flash-debug-configuration.png) ### Post-Build Editor (PBE) The Post-Build Editor (PBE) is provided to make it easy for the user to specify actions required on the project output binary to create various types of image files. The tool provides the following capabilities: - Adding signatures or checksums to application or bootloader binaries - Merging applications and other data into production images - Packaging applications and other data into upgrade files, including GBL and Zigbee OTA. #### Workflow The PBE-defined post-build steps are stored in a post-build YAML file with an '.slpb' extension that can be used either from within Simplicity Studio 5 (SSv5) or by running Simplicity Commander on the command line. Simplicity Studio IDE projects and SLC exported projects will execute the post-build steps automatically using the post-build command step to call the command line version of Simplicity Commander. Also, the various project configurator generators (GCC Makefile, Visual Studio Code Compatible (beta), and IAR Embedded Workbench) will include the necessary Simplicity Commander call to automatically perform the post build steps when the project is built in those environments. Several example .slpb files are included in the Gecko SDK Suite (GSDK) starting with version 4.2.0.0. For examples of projects that use the .slpb feature, see the TrustZone examples. Refer to [UG162: Simplicity Commander User's Guide](https://www.silabs.com/documents/public/user-guides/ug162-simplicity-commander-reference-guide.pdf) for details on the signing and secure boot information in the following tasks. #### Tasks The PBE supports four different tasks: [copy](#copy), [convert](#convert), [create_gbl](#create-gbl), and [create_ota](#create-ota). ##### Copy The `copy` task is used to copy a file from one folder to another and it is also the starting point for specifying the post-build sequence. ![post build editor copy](/ss-5-users-guide-building-and-flashing/0.8/images/pbe-copy.png) - Required Arguments: - Input name: The project relative path and filename to copy. - Output name: The destination project relative path and filename. Folders will be created as needed. - Optional Arguments: - Export output as: The parameter name to assign to the output file. ##### Convert The `convert` task performs various actions on the binary to convert it to another form, such as adding a CRC or a signature. See the _Simplicity Commander User’s Guide_ 'Convert and Modify File Commands' section for details. ![post build editor convert](/ss-5-users-guide-building-and-flashing/0.8/images/pbe-convert.png) - Required Arguments: - Input name: The project relative path and filename to convert. - Output name: The destination project relative path and filename. Folders will be created as needed. - Optional Arguments: - Export output as: The parameter name to assign to the output file. - Add CRC checkbox: To calculate and store the CRC32 on the bootloader image. The Gecko Bootloader can use the CRC to ensure image integrity when Secure Boot is not used. - Secure boot: Private Key and Intermediary Certificate to use to sign the secure boot image. - Signature file to sign the image - Include-section: - Exclude-section: - Verify: Key file The `Include-section` and `Exclude-section` optional arguments can be used if the input file is an Executable and Linkable Format (ELF) file. If neither the Include-section nor the Exclude-section arguments are used, all .text sections will be extracted, as well as sections of type `progbits` with address not equal to 0x0. ##### Create_gbl The `create_gbl` task creates a Gecko Bootloader file (GBL) from an application and/or bootloader image that optionally includes a Secure Element (SE) upgrade image. See the _Simplicity Commander User’s Guide_ "GBL Commands" section for details. ![post build editor create_gbl](/ss-5-users-guide-building-and-flashing/0.8/images/pbe-create-gbl.png) - Required Arguments: - Output name: The destination project relative path and filename. Folders will be created as needed. - Optional Arguments: - Export output as: The parameter name to assign to the output file. - Application Image: Application image file. - Bootloader: Bootloader image file. - SE upgrade: Secure Element upgrade image file. - Metadata: Metadata bin file to include in the image. - Compression: Compression method for output (none, lzma, lz4). - Sign using HWM checkbox: Check if the signature will be created using Hardware Security Module. - Signing key - Signing certificate - Encrypt: Encryption key used to encrypt image. - Include-section: . - Exclude-section: . ##### Create_ota The `create_ota` task creates a Zigbee Over-the-air (OTA) bootloader file from one or more GBL files. See the _Simplicity Commander User’s Guide_ "OTA Commands" section for details. **NOTE: The "Input name" field should be ignored; it will be removed in a future release. The "Input name" is a duplicate of the "Upgrade Image". Using both will add two copies of the file to the output.** ![post build editor create_ota](/ss-5-users-guide-building-and-flashing/0.8/images/pbe-create-ota.png) - Required Arguments: - Upgrade Image: The project relative path of the gbl file. - Output name: The destination project relative path and filename. Folders will be created as needed. - Manufacturer ID - Image type - Header string - Firmware Version - Optional Arguments: - Export output as: The parameter name to assign to the output file - Manufacturer tag: Tag ID. - Stack version - Credentials - Target device EUI64 - Minimum HW version - Maximum HW version #### Example ##### Series 1 Combined Bootloader An example of the PBE can be seen by creating a Series 1 bootloader for an EFR32MG12 target part. The PBE file copies the output .s37 of the main bootloader and adds a CRC to it. Then it copies the pre-built first stage bootloader image into a combined bootloader file that can be programmed to the device. To create this example: 1. Add BRD4161A to the Launcher Perspective [My Products] window and select it. 2. Make sure GSDK 4.2.0 or later is the Preferred SDK. 3. Click the Example Projects and Demos tab and click the Bootloaders filter checkbox 4. Click [Create] for “Bootloader – SoC Internal Storage (single image on 1MB device) 5. Build the project. In the build console output will be a call to commander.exe with the postbuild argument and the .slpb file: ```bash "C:\SiliconLabs\SimplicityStudio\v5\developer\adapter_packs\commander\commander.exe" postbuild "C:\Users\USERNAME\SimplicityStudio\v5_workspace\bootloader-storage-internal-single/bootloader-storage-internal-single.slpb" --parameter build_dir:"C:\Users\USERNAME\SimplicityStudio\v5_workspace\bootloader-storage-internal-single\GNU ARM v10.3.1 - Default" Parsing file C:\Users\japitt\SimplicityStudio\v5.rel.Staging_1865\bootloader-storage-internal-single/bootloader-storage-internal-single.slpb... Running task copy... Running task convert... Running task convert... DONE ``` The 'artifact' folder is created with three files in it: ![post build editor artifact folder](/ss-5-users-guide-building-and-flashing/0.8/images/pbe-artifact-folder-contents.png) Opening the .slpb file shows three operations with the last one being a convert that takes the ‘autogen/first_stage.s37’ file and adds it to the main bootloader image in a new file called ‘bootloader-storage-internal-single-combined.s37. ![post build editor Series 1 Combined Bootloader](/ss-5-users-guide-building-and-flashing/0.8/images/pbe-series1-combined-bootloader.png) ##### Series 2 OTA Image Creation The following example was created using an EFR32MG24B210F1536IM48 target on a BRD4186C radio board. It includes all four tasks and can be created with the following steps: 1. Create and build a "Bootloader - SoC Internal Storage single image with LZMA compression, 1MB Flash" (bootloader-storage-internal-single-lzma) project. 2. Create and build a "Zigbee SoC ZigbeeMinimal" (ZigbeeMinimal) project. 3. Open the bootloader .slpb file in the PBE. It will have copy and convert tasks already defined: ![post build editor EFR32MG24 Bootloader](/ss-5-users-guide-building-and-flashing/0.8/images/pbe-efr32mg24-bootloader.png) ###### Add a Create_gbl Task 1. Select the Convert task and then click the "+" icon and select "create_gbl". 2. Next to 'Application Image', click **BROWSE** and select the ZigbeeMinimal.s37 file. Multiple application images could be entered in this field if needed. 3. Next to 'Bootloader', click **BROWSE** and select the bootloader .s37 file. 4. Next to 'SE Upgrade', click **BROWSE** and browse to the Secure Element upgrade image file "s2c4_se_fw_upgrade_2v2p1.seu". 5. Click the 'Compression' dropdown and select "lzma". 6. Click the 'Output name' field and enter "artifact/CompressedZigbeeMinimal.gbl". 7. Click **SAVE**. The GBL task should look like this: ![post build editor EFR32MG24 GBL Task](/ss-5-users-guide-building-and-flashing/0.8/images/pbe-efr32mg24-gbl-task.png) ###### Add a Create_ota Task 1. Click the "+" icon and select "create_ota". 2. Click the 'Output name' field and enter "artifact/CompressedZigbeeMinimal.ota". 3. Click the 'Manufacturer ID' field and enter your manufacturer ID. A dummy value of 0x1002 is used in this example. 4. Click the 'Image type' field and enter a hex number for the image type. A dummy value of 0x5678 is used in this example. 5. Click the 'Header string' field and enter "Example". 6. Click the 'Upgrade Image' field and enter the path and .gbl filename from the create_gbl task - artifact/CompressedZigbeeMinimal.gbl. Note multiple .gbl files could be entered in this field if needed. 7. Click the 'Firmware Version' field and enter an unsigned integer value for the version. A dummy value of 0x1002 is used in this example. 8. Click **SAVE**. The OTA task should look like this: ![post build editor EFR32MG24 OTA Task](/ss-5-users-guide-building-and-flashing/0.8/images/pbe-efr32mg24-ota-task.png) ###### Test the Post-Build File Build the project and at the end of the build commander will be called with the .slpb file and each of the tasks will be run: ```c "C:\SiliconLabs\SimplicityStudio\v5\developer\adapter_packs\commander\commander.exe" postbuild "C:\SiliconLabs\workspaces\v5_workspace\bootloader-storage-internal-single-lzma/bootloader-storage-internal-single-lzma.slpb" --parameter build_dir:"C:\SiliconLabs\workspaces\v5_workspace\bootloader-storage-internal-single-lzma\GNU ARM v10.3.1 - Default" Parsing file C:\SiliconLabs\workspaces\v5_workspace\bootloader-storage-internal-single-lzma/bootloader-storage-internal-single-lzma.slpb... Running task copy... Running task convert... Running task GBL create... Running task OTA create... DONE ``` ### Flashing Simplicity Studio® 5 (SSv5) offers several ways to load (flash) a firmware image to your device. - With the **Debug** button (see [Debug build and flash](building#debug-build-and-flash)) - Through the debug adapter's context menu, [Upload Application...](#upload-application) selection - Using the [Flash Programmer](#flash-programmer) tool See your SDK's quick start guide for more stack-specific information about building and flashing. #### Upload Application This option is useful if you want to load a bootloader image and an application image in a single step. To use this option, you will need to know the radio board part number (shown in the Debug Adapters view), and the location and name of the binary image you wish to load. The default workspace locations are: Windows 10 workspace: C:\Users\\SimplicityStudio Mac workspace: /Users//SimplicityStudio In the Debug Adapters view, right-click the adapter (top line) and select **Upload Application...** from the debug adapter context menu. ![build flash upload app menu](/ss-5-users-guide-building-and-flashing/0.8/images/build-flash-upload-app-menu.png) The Application Image Upload dialog is displayed. ![build flash upload app dialog](/ss-5-users-guide-building-and-flashing/0.8/images/build-flash-upload-app-dialog.png) Browse to the project directory, go to the directory corresponding to the compiler toolchain, and select an image file. This example uses the .GBL file, as it assumes you are also loading a Gecko Bootloader image. (Start with [UG103.6: Bootloader Fundamentals](https://www.silabs.com/documents/public/user-guides/ug103-06-fundamentals-bootloading.pdf) if you are not familiar with bootloaders.) Click **Open**. ![build flash upload app binary](/ss-5-users-guide-building-and-flashing/0.8/images/build-flash-upload-app-binary.png) Check **Bootloader image**, then browse to the folder containing a prebuilt bootloader image. Images are located in the Simplicity Studio platform bootloader folder under sample apps. In this case open the SPI Flash Single folder, for example: C:\SiliconLabs\SimplicityStudio\\developer\sdks\gecko_sdk_suite\\platform\bootloader\sample-apps\bootloader-storage-spiflash-single Open the folder that corresponds to your board and part number and select the .s37 file, for example: efr32mg12p332f1024gl125-brd4162a\bootloader-storage-spiflash-single-combined.s37 Click **Open**. ![build flash upload app bootloader](/ss-5-users-guide-building-and-flashing/0.8/images/build-flash-upload-app-bootloader.png) Now that both the application image and the bootloader are selected, check **Erase Chip**, to make sure that the main flash block is erased before your new image is uploaded. New users will typically always check this. - The **After uploading** options are **Run** (begin executing the code immediately) and **Halt** (wait for an event, such as a debugger to connect or manual initiation of a boot sequence). During initial development you will typically leave this set to **Run**. - The **Flash** options determine the storage location, and are Internal and External SPI. Leave the option set to **Internal**. The completed dialog should resemble the following: ![build flash upload app done](/ss-5-users-guide-building-and-flashing/0.8/images/build-flash-upload-app-done.png) Click **OK**. #### Flash Programmer The Flash Programmer is a tool that provides a number of options for use when flashing images to a device. Select the Flash Programmer from the **Tools** button on the toolbar. Some perspectives have a button specifically for the Flash Programmer. ![build flash programmer button](/ss-5-users-guide-building-and-flashing/0.8/images/build-flash-programmer-button.png) The Flash Programmer provides basic flash and erase functionality, but also allows you to lock parts of memory and enable or disable debug access. ![build flash programmer start](/ss-5-users-guide-building-and-flashing/0.8/images/build-flash-programmer-start.png) **Flash Part** The Flash Programmer is configured to facilitate flashing .hex or .bin files. ![build flash programmer part](/ss-5-users-guide-building-and-flashing/0.8/images/build-flash-programmer-part.png) To flash an image, browse to the image location. Note that the images you see are filtered by the extension drop-down to the right of the file name field. ![build flash programmer filter](/ss-5-users-guide-building-and-flashing/0.8/images/build-flash-programmer-filter.png) Click **Open** and then click **Program** to flash the image. By default, the **Erase** function erases the main page. Click **Advanced Settings** to change what is erased. Finally, if you have more than one device connected, click **Change Device** to select the target. **Flash Erase/Write Protection** Use these functions to protect or remove protection from a custom range, or default pages. ![build flash programmer protection](/ss-5-users-guide-building-and-flashing/0.8/images/build-flash-programmer-protection.png) **Debug Lock Tools** Use these functions to unlock or lock debug access. ### SBOM Generation The Software Bill of Materials (SBOM) generation tool is integrated into Simplicity Studio and can parse SLC projects to generate a project report that lists all components and their relationships for Simplicity SDK 2024.12.0 or newer. An SBOM helps developers understand the software's composition, ensuring that all components are accounted for and properly managed. SBOM generation is automatic and created in standard formats like CycloneDX and SPDX under each project build, e.g., ..\v5_workspace\bt_soc_thermometer\autogen\sbom. ## Testing and Debugging ### Testing and Debugging This section provides information on testing and debugging application firmware. - [Overview and Resources](overview-and-resources) reviews the tools that are available and additional documentation. - [Using the Debugger](using-the-debugger) provides details on Simplicity Studio's built-in debuggers. - [Using Wireshark](using-wireshark) describes how to connect a device to the Wireshark packet analyzer. ### Resources Simplicity Studio® 5 (SSv5) offers a number of tools that can be used to test and debug application functionality, power consumption, and network behavior. Tools include: - A built-in [debugger](using-the-debugger), either the GNU Debugger (GDB) client and SEGGER's GDB server or a Simplicity Studio Debugger. - Connectivity to the [Wireshark packet analyzer](using-wireshark). - [Network Analyzer](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-tools-network-analyzer) - [Energy Profiler](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-tools-energy-profiler) In addition, a number of SDKs provide example applications that can be used for testing, such as: - NodeTest (Zigbee EmberZNet SDK) (See [AN1019: Using the NodeTest Application](https://www.silabs.com/documents/public/application-notes/an1019-node-test.pdf)) - Deprecated in Zigbee EmberZNet SDK 6.10.0.0 - RAILtest (Proprietary Flex SDK) (see [UG409: RAILtest User's Guide](https://www.silabs.com/documents/public/user-guides/ug409-railtest-users-guide.pdf)) Finally, Silicon Labs provides a number of other documentation resources related to testing such as: - [AN1267: Radio Frequency Physical Layer Evaluation in Bluetooth® SDK v3.x](https://www.silabs.com/documents/public/application-notes/an1297-custom-direction-finding-solutions-silicon-labs-bluetooth.pdf) - [AN1142: Mesh Network Performance Comparison](https://www.silabs.com/documents/public/application-notes/an1142-mesh-network-performance-comparison.pdf) - [AN718: Manufacturing Test Overview](https://www.silabs.com/documents/public/application-notes/AN718-MfgTestOverview.pdf) - [UG104: Testing and Debugging Applications for the Silicon Labs EM35x and EFR32MG Platforms (Zigbee)](https://www.silabs.com/documents/public/user-guides/ug104-test-debug-apps.pdf) ### Using the Debuggers Simplicity Studio® 5 (SSv5) supports two debuggers: - For 32-bit device users, SSv5 includes support for a GNU Debugger (GDB) client and SEGGER's GDB server. The GNU Debugger (GDB) enables thread-aware debugging, and offers features such as unlimited flash breakpoints. This is the default debugger - The classic Simplicity Studio debugger is a full featured debugger that offers the ability to step through code, set breakpoints, examine memory, variables and registers. To change from the GNU debugger, on the toolbar click Preferences and select **Simplicity Studio > Debuggers**. Select **Simplicity Studio Debugger** and click **Apply and Close**. ![debug preferences](/ss-5-users-guide-testing-and-debugging/0.8/images/debug-preferences.png) Silicon Labs supplies the debug models for each of their devices so that all of the registers can be examined and modified using either debugger. The debugger runs in the [**Debug**](#debug-perspective) perspective. The debug perspective can be opened in a variety of ways, but most commonly by clicking the **Debug** button in the Simplicity IDE perspective once a project has reached a point where it will build and link correctly. ![debug icon](/ss-5-users-guide-testing-and-debugging/0.8/images/debug-icon.png) If a debug session has never been started before, a warning that a debug configuration does not exist might appear. Click the down arrow next to the debug icon, select **Debug as...** and then select either **Silicon Labs ARM Program** for 32-bit parts or **Silicon Labs 8051 Program** for EFM8 and C8051 parts. If a single debug adapter is available, SSv5 automatically downloads the code to that device. If more than one debug adapter is available, SSv5 will prompt to select one. With the Simplicity Studio debugger you can also save a [**snapshot**](#about-snapshots) of register values on a device, which can be used to compare the states of two different devices, or the state of the device at two different points in time. #### Debug Perspective The Debug Perspective by default is composed of the editor (A) and three tabbed view panes. ![debug bluetooth start](/ss-5-users-guide-testing-and-debugging/0.8/images/debug-bluetooth-start.png) The Debug view (B) shows the call stack and call hierarchy that can help debug and find where functions are called. The Project Explorer view is available as a tab. The right pane (C) and the bottom pane (D) contains tabbed views into data and consoles. These vary between the two debuggers. Depending on your actions, additional views may open in either the right or bottom pane. Buttons in the Debug perspective toolbar (E) for the Simplicity Studio debugger and the GDB are shown below. The toolbar is similar for both debuggers. ![debug menu](/ss-5-users-guide-testing-and-debugging/0.8/images/debug-menu.png) |Number|Command|Description| |---|---|---| |1|Debug|Starts a new debug session. An active debug session must be disconnected before starting a new session using the same debug adapter.| |2|Reset the device|Performs a hardware reset.| |3|Create snapshot|(Simplicity Studio Debugger only) Creates a snapshot when clicked (default). Drop down the menu to select **Create when Stopped** or **Create at Breakpoints**. See [About Snapshots](#about-snapshots) for more information.| |4|Skip|Skips all breakpoints.| |5|Resume|Runs the application after reset or hitting a breakpoint.| |6|Suspend|Halts the application.| |7|Terminate|Terminates the session.| |8|Disconnect|(Simplicity Studio Debugger only, gray for GDB) Terminates the session and disconnects the debug adapter. SSv5 automatically switches back to the Simplicity IDE perspective.| |9|Step into|Single steps into the first line of a function.| |10|Step over|Single steps over a function, executing the entire function.| |11|Step return|Steps out of a function, executing the rest of the function.| |12|Instruction Stepping Mode|Toggles assembly single stepping. When enabled, single stepping executes a single assembly instruction at a time. If clicked, opens a Disassembly view in the right pane that shows the assembly code corresponding to the source code at the current line of execution.| |13|Restart|(Simplicity Studio debugger only) Restarts a process or target without terminating and relaunching| |14|Open Element|Opens a dialog where you can see the qualified name and location for an element. Start typing to bring up a list of matching elements.| |15|Toggle Mark Occurrences|Turns the mark occurrences function on and off.| A debug adapter can only support a single debug session at a time. An active debug session must be disconnected before code can be recompiled and a new debug session started. To set a breakpoint, double-click in the blue bar to the left of the code editor or right-click on a line of code and select **Add Breakpoint**. #### Simplicity Studio Debugger This section describe the various views in the Simplicity Studio debugger. ![debug studio debugger right pane](/ss-5-users-guide-testing-and-debugging/0.8/images/debug-studio-right-pane.png) - The **Variables** view shows the values of variables. - The **Breakpoints** view provides functionality to manage breakpoints. - The **Registers** view displays and allows you to change register contents. Registers with bitfields are split into individual fields with the enumeration value decoded. Registers that have changed between breakpoints are highlighted in yellow. - The **Expressions** view allows you to add and change expressions. If possible, SSv5 evaluates the expression and displays its current value when the application is halted. If an expression is out of scope, SSv5 cannot evaluate the expression until the application is halted in a section of code where the expression is in scope. - The **Disassembly** view provides an interleaved display of the original source code with the assembler instructions use to execute the source code. The Memory view in the bottom pane displays the contents of the CODE, RAM, and XRAM memory. To experiment, in the Monitors menu click **+**. Select **Enter memory space and address**, select a memory space such as CORE and enter an address to view, such as 0x0000. Click **OK**. A memory monitor is added to the Memory view that displays the contents of the space starting at the address you provided. #### GDB This section describe the various views in the GNU Debugger. ![debug GDB right pane](/ss-5-users-guide-testing-and-debugging/0.8/images/debug-gdb-right-pane.png) - The **Variables** view shows the values of variables. - The **Breakpoints** view provides functionality to manage breakpoints. - The **Registers** view displays and allows you to change general register contents. Registers that have changed between breakpoints are highlighted in yellow. To see other registers, select a peripheral in the Peripherals view. - The **Expressions** view allows you to add and change expressions. If possible, SSv5 evaluates the expression and displays its current value when the application is halted. If an expression is out of scope, SSv5 cannot evaluate the expression until the application is halted in a section of code where the expression is in scope. - The **Disassembly** view provides an interleaved display of the original source code with the assembler instructions use to execute the source code. - The **Peripherals** view, after a short delay, shows peripherals with bitfields that are split into individual fields shown as a hex value. Their values cannot be modified. When a peripheral is selected, the **Memory** tab in the bottom pane shows associated registers and their values. The Memory view in the bottom pane displays the contents of the CODE, RAM, and XRAM memory. To experiment, in the Monitors menu click **+** and enter an address or an expression to monitor. A monitor for that address or expression is added. The bottom pane also includes a Debugger Console, with output specific to GDB Debug SEGGER J-Link Debugging. #### About Snapshots The Snapshot feature is available in the Simplicity Studio debugger only. A snapshot saves the values of the registers on a device at a particular point in time. This feature is useful when comparing the states of two systems next to each other or looking at the state of the hardware at separate points in time. Once you take a snapshot, the Snapshot Album view opens in the bottom view pane. ![debug snapshot](/ss-5-users-guide-testing-and-debugging/0.8/images/debug-snapshot.png) In the Debug perspective, if you do not see the Snapshot Album view, select **Window > Show View > Other > Snapshot Albums**. To view a snapshot, right-click a snapshot in the list and select **Launch Snapshot**. This adds a debug session in the Debug window as it was at the time of the snapshot, with a Snapshot label at the start of the debug configuration. However, it is not an active debug session on hardware. To switch back to a debug session on hardware, select the Silicon Labs ARM debug configuration in the Debug window if a hardware debug session was active or else select **Run > Debug** if a session is not active. ### Using Wireshark Beginning with version 5.5.0, Simplicity Studio® 5 (SSv5) supports live interaction between the application running on a Silicon Labs device and the Wireshark packet analyzer. Windows/Mac users can download Wireshark from [https://www.wireshark.org/download.html](https://www.wireshark.org/download.html). Linux users can find instructions at [https://www.wireshark.org/docs/wsug_html_chunked/ChBuildInstallUnixInstallBins.html](https://www.wireshark.org/docs/wsug_html_chunked/ChBuildInstallUnixInstallBins.html). If you installed the GSDK in an earlier version of Simplicity Studio, click **Install** on the toolbar. Click **Manage Installed Packages** and go to the Tools tab. Find the "Packet Trace Using Wireshark Integration" tool and click **Install**. ![Wireshark integration tool](/ss-5-users-guide-testing-and-debugging/0.8/images/debug-wireshark-install.png) 1. Make sure that debug output is enabled in your project, if it is available. This is enabled by default in most GSDK examples and demos. 2. Build and flash the project to your device. If you are working in Simplicity Studio, do not start a debug session to build and flash the project, but rather build it and then flash the binary separately. 3. In Simplicity Studio's Debug Adapters view, select one or more devices and right-click one of the devices. Two Wireshark options are available, 'Start Wireshark Data Source' and 'Start Wireshark Data Source with Options'. ![Wireshark options menu](/ss-5-users-guide-testing-and-debugging/0.8/images/debug-wireshark-start-menu.png) **Start Wireshark Data Source**: If all selected devices are connected through a network, the Wireshark Data Source starts. Devices connected by USB use the application Silink to communicate with the network. The network ports that Silink uses are assigned dynamically and are different on each launch. Knowing the port numbers can be useful when filtering captured packets by TCP port using Wireshark's display filters functionality. If you select at least one device connected by USB, a dialog is presented showing the device's IP address and port number. ![Wireshark USB IP and port number](/ss-5-users-guide-testing-and-debugging/0.8/images/debug-wireshark-usb-info.png) **Start Wireshark Data Source with Options**: A dialog is displayed in which you can configure the output log name and the capture duration in milliseconds. It also shows the IP address and port number. ![Wireshark capture options](/ss-5-users-guide-testing-and-debugging/0.8/images/debug-wireshark-options.png) When Wireshark Data Source starts, Simplicity Studio writes a script to Wireshark’s Personal Extcap directory. If this fails, a dialog where you can specify the target location is displayed. To find the location, launch Wireshark, select **Help > About Wireshark**, and go to the Folders tab. ![Wireshark script location](/ss-5-users-guide-testing-and-debugging/0.8/images/debug-wireshark-no-script.png) 4. After the Wireshark Data Source starts successfully, Simplicity Studio launches Wireshark automatically, and locks the device. In the Wireshark startup dialog, select a network interface to use and configure the capture and display filters. If the device is connected by USB, select the 'loopback' network interface. For networked devices, try Wi-Fi or Ethernet. See the Wireshark documentation for details on using Wireshark. ![Wireshark's starting dialog](/ss-5-users-guide-testing-and-debugging/0.8/images/debug-wireshark-startup.png) Note: Wireshark is launched as a child process of Simplicity Studio. If you close Simplicity Studio, Wireshark also closes. After you have completed the packet analysis, in Simplicity Studio right-click any of the devices connected to Wireshark, and click 'Stop Wireshark Data Source'. This stops Wireshark Data Source for all connected devices. ![Device context menu](/ss-5-users-guide-testing-and-debugging/0.8/images/debug-wireshark-stop-data-source.png) Note: Stopping Wireshark Data Source does not close Wireshark and closing Wireshark does not stop Wireshark Data Source. ## Using the Tools ### Using the Tools - Overview Simplicity Studio® 5 (SSv5) provides a number of tools to assist with development activities. Use the **Tools** button to see a list of available tools. The Project COMPATIBLE TOOLS tab provides a list filtered by the project's target device. ![tools start](/ss-5-users-guide-tools-overview/0.6/images/tools-start.png) Many of these tools are discussed on other pages in this guide, for example: - [Simplicity IDE](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-about-the-simplicity-ide) - [Application Builder](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-with-appbuilder) - [Migrate Projects](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-getting-started/migrate-from-ss-4) - [Flash Programmer](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-building-and-flashing#flash-programmer) - [Hardware Configurator](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-for-8bit-devicesusing-hardware-configurator) These pages discuss: - [Bluetooth NCP Commander](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-tools-bluetooth-ncp-commander) - [Energy Profiler](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-tools-energy-profiler) - [Network Analyzer](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-tools-network-analyzer) - [Bluetooth Direction Finding tools suite](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-direction-finding-tools) More tools will be documented in future releases of the _Simplicity Studio 5 User's Guide_. ### Bluetooth NCP Commander Bluetooth NCP Commander is a Simplicity Studio® 5 (SSv5) tool for sending BGAPI commands to an NCP target application during development. Two versions of the tool are available in SSv5: - Bluetooth NCP Commander - Bluetooth NCP Commander Standalone ![Project Configurator COMPATIBLE TOOLS tab with NCP Commander highlighted](/ss-5-users-guide-tools-bluetooth-ncp-commander/0.8/images/ncpcommander-launch.png) For detailed information about using NCP Commander and developing Bluetooth NCP-Host applications, see [AN1259: Using the Silicon Labs Bluetooth® Stack v3.x and Higher in Network Co-Processor Mode](https://www.silabs.com/documents/public/application-notes/an1259-bt-ncp-mode-sdk-v3x.pdf). #### Bluetooth NCP Commander Standalone The Standalone version is provided for customers who need to control an NCP device on custom hardware. The Standalone version can access the system COM ports that are not exposed in SSv5. Users who wish to work outside of the SSv5 environment can do so by copying the directory /developer/adapter_packs/ncp_commander. The Standalone version cannot access parts over Ethernet, which the integrated SSv5 version can. #### Bluetooth NCP Commander To open Bluetooth NCP Commander, make sure that the correct board is connected. If you are just getting started, build and flash a project based on **Bluetooth - NCP**. In the Project Configurator COMPATIBLE TOOLS tab, click **LAUNCH** on the Bluetooth NCP Commander card. In the Connection Manager dialog, select the target device and click **Connect**. ![Connection Manager](/ss-5-users-guide-tools-bluetooth-ncp-commander/0.8/images/ncpcommander-connection-manager.png) Once the UART connection to the mainboard is established, an Interactive view opens, which you can use to issue BGAPI commands. Note that the connected device is shown in the lower right. You can change target devices without leaving Bluetooth NCP Commander by clicking that area. It will show "Disconnected" if not connected to any device. Check the log for the NCP target response and status messages. You can also issue commands manually. For example, you can issue the 'sl_bt_system_hello()' command at any time to verify that communication between the host and the device is working. The Smart Console provides auto completion and documentation for the possible commands. ![Smart Console showing autocomplete](/ss-5-users-guide-tools-bluetooth-ncp-commander/0.8/images/ncpcommander-smart-console.png) NCP Commander provides a simple scripting feature. Create or import an existing script using the controls in the top right corner. You can use any BGAPI commands in the script, but it has no additional features, such as branching or error handling. Click **Export** to save the commands sent through the console to a file that can be imported back as a script. ##### Advertising To start advertising, click "+" next to "Advertise" to create an advertiser set. ![Plus button used to create advertise sets](/ss-5-users-guide-tools-bluetooth-ncp-commander/0.8/images/ncpcommander-new-advertiser-set.png) Select the desired advertising mode, create custom advertising packets if desired, and click **Start**. ![Advertiser mode](/ss-5-users-guide-tools-bluetooth-ncp-commander/0.8/images/ncpcommander-advertiser-mode.png) When advertising, the NCP target example accepts Bluetooth connections. If you connect to a WSTK or with another central device (for example with your phone), you can see the events and commands on the log. ![Log for a phone connection](/ss-5-users-guide-tools-bluetooth-ncp-commander/0.8/images/ncpcommander-ncp-connect-by-phone.png) ##### GATT Database NCP commander supports creating a GATT database. To generate a basic GATT database, open the Local GATT view, and click **Create Basic GATT**. The following database is generated. ![Local GATT database](/ss-5-users-guide-tools-bluetooth-ncp-commander/0.8/images/ncpcommander-local-gatt.png) Here you can add services and characteristics. You can also read out the local GATT database from the device. ##### Bluetooth mesh NCP Commander supports Bluetooth mesh features. You can issue Bluetooth mesh commands manually in the Smart Console, or use the interactive host provisioner feature to provision and configure mesh nodes and manage mesh networks, instead of using a Bluetooth mesh mobile application. To use the Bluetooth Mesh features, create, build, and flash the device with an NCP example supporting Mesh features, such as **Bluetooth Mesh - NCP Empty**. This section provides a summary of host provisioning. For details see [AN1259: Using the Silicon Labs Bluetooth® Stack v3.x and Higher in Network Co-Processor Mode](https://www.silabs.com/documents/public/application-notes/an1259-bt-ncp-mode-sdk-v3x.pdf). To start using the host provisioner, select either **Provision** or **Networks & Nodes** on the left menu, and click **Initialize as Provisioner**. ![Start the host provisioned](/ss-5-users-guide-tools-bluetooth-ncp-commander/0.8/images/ncpcommander-mesh-start-provisioning.png) If you do not have a network from a previous configuration or have reset the provisioner node, you must create a new network with **Create New Network**. To provision devices, select **Provision** on the left menu, and click **Start Scan** in the right panel. The devices that are transmitting unprovisioned beacons are shown in the **Discovered Devices** section. Click **Provision** next to the device you want to provision. ![Provisioning a device](/ss-5-users-guide-tools-bluetooth-ncp-commander/0.8/images/ncpcommander-mesh-provision.png) Before configuring provisioned devices, you may need to create application keys and groups. Application keys, groups and other network settings can be managed in the **Settings** tab of the **Networks & Nodes** menu item. To configure provisioned devices, select **Networks & Nodes** on the left menu. Provisioned devices are shown in the **Provisioned Devices** section of the **Settings** tab. Click **Configure**. ![Configuring a device](/ss-5-users-guide-tools-bluetooth-ncp-commander/0.8/images/ncpcommander-mesh-configure-provisioned-device.png) This opens a **Mesh Node** tab in which you can add an application key. Once you have added the key, the interface changes to include a **Get DCD** control (not shown). Click **Get DCD** to to configure all the Models available on your node(s), bind to app keys, set publishing or subscription to groups, fine tune parameters, and so on. ![Configuring models](/ss-5-users-guide-tools-bluetooth-ncp-commander/0.8/images/ncpcommander-mesh-model-configuration.png) To configure the host provisioner, first initialize models using **Initialize Client Models**. ![Initialize Client Models](/ss-5-users-guide-tools-bluetooth-ncp-commander/0.8/images/ncpcommander-mesh-initialize-models.png) Bind an application key to the models and, optionally, subscribe the models to a group. When configuration is complete, click **Done** The Show Nodes tab is displayed. Click **Get DCD** to configure all the Models available on your node(s), bind to app keys, set publishing or subscription to groups, fine-tune parameters, and so on. ![Get DCD](/ss-5-users-guide-tools-bluetooth-ncp-commander/0.8/images/ncpcommander-mesh-get-dc.png) After listing, you can **Get** or **Set** the Server states of the Node(s). ![Get-Set Server states](/ss-5-users-guide-tools-bluetooth-ncp-commander/0.8/images/ncpcommander-get-set-states.png) Click **Set** to set the current state of the selected Server of the selected Node. ![Set Server state](/ss-5-users-guide-tools-bluetooth-ncp-commander/0.8/images/ncpcommander-set-state.png) Click **Get** to get the current state of the selected Server of the selected Node. ![Get Server state](/ss-5-users-guide-tools-bluetooth-ncp-commander/0.8/images/ncpcommander-get-state.png) On the **Show Groups** tab, you can **Set** or **Get** the Server Model(s) states on a Group level. ![Show Groups](/ss-5-users-guide-tools-bluetooth-ncp-commander/0.8/images/ncpcommander-show-groups.png) In **Settings**, if the **Reset Mesh Node before Initializing as Provisioner** option is enabled, the host provisioner does a factory reset (the **sl_btmesh_node_reset()** command) on the NCP target device before initializing the node. Clicking **Clear Data** next to Remove all locally saved mesh data removes the network and application keys that were configured during initialization. ![Show Groups](/ss-5-users-guide-tools-bluetooth-ncp-commander/0.8/images/ncpcommander-settings.png) ### Bluetooth Direction Finding Tool Suite A Real Time Locating System (RTLS) consists of many locators that pick up the signals of asset tags to locate them in 3D space. To calculate the positions of the asset tags, you must know each locator’s position, orientation, and configuration (such as antenna array type, switching pattern, and so on). The Silicon Labs’ Real Time Locating (RTL) library also needs configuration parameters, such as estimation mode, azimuth, elevation constraints, and so on, to provide the best estimation for a given environment. The Bluetooth Direction Finding Tool Suite is meant to ease development with the Silicon Labs’ RTL library. It provides tools to configure the system, and also helps development with analyzer tools that calculate many output parameters from the observed IQ samples. **Note:** The tools were created for demonstration purposes, and not to be used in production. For development purposes, start with the sample application described in [AN1296: Application Development with Silicon Labs RTL Library](https://www.silabs.com/documents/public/application-notes/an1296-application-development-with-rtl-library.pdf). The implementation described in AN1296 requires you to configure and build both individual locators and a locator host application in order to test the system. While the SDK examples provide the openness to customize and add new features to your direction find-ing project using RTL library APIs directly, the manual configuration of the locators and their topologies may not be a trivial task. It is simpler to configure a single locator and multi-locator setup through interactive graphical interfaces available through the Direction Finding Tools Suite. The Suite is composed of: - AoA Analyzer - Positioning Tool Both are available through the Simplicity Studio Tools menu. #### AoA Analyzer AoA Analyzer can: - Create a locator configuration file without the need to manually edit the .json file, to ease the configurations process. - Apply the configuration for a single locator board and run the RTL library to estimate angles from the incoming data (without the need to build and run any host sample application). #### Positioning Tool While it is easy to configure a single locator and get angle information of asset tags, configuring and running a multi-locator setup to get position information can be rather complicated. To calculate position, the RTL needs to know the coordinates and orientation of the locator so that it can translate the angle feeds from each one of them with respect to the coordinate system of a given topology. Simplicity Studio provides the Positioning tool, which makes the configuration and testing of a multi-locator setup easy and quick. Positioning Tool can: - Create a multi-locator topology without the need to manually edit the configuration .json file. - Add locators to the topology and configure their positioning RTL parameters (such coordinates and orientation) easily. - Apply the configuration and locate asset tags in 3D. - Import/Export a topology from/to a configuration .json file. For details about the tools and references to other direction-finding documentation, see [UG514: Using the Bluetooth® Direction Finding Tool Suite](https://www.silabs.com/documents/public/user-guides/ug514-using-bluetooth-direction-finding-tool-suite.pdf) ### Energy Profiler #### Energy Profiler Simplicity Studio® 5 (SSv5)'s Energy Profiler enables you to visualize the energy consumption of individual devices, multiple devices on one target system, or a network of interacting wireless devices to analyze and improve the power performance of these systems. Real-time information on current consumption is correlated with the program counter providing advanced energy software monitoring capabilities. It also provides a basic level of integration with the Network Analyzer network analysis tool. Energy saving and efficiency are at the top of developers’ priorities for an ever-growing number of embedded systems applications. These constraints can be due to government regulations (for example, metering applications), a requirement to increase battery life, or simply a need to lower the electricity bill. In battery-operated systems, energy efficiency often plays the most important role. In cases where developers are satisfied with their system’s battery life, increasing the energy efficiency means they can switch to a smaller and cheaper battery, which will lower the overall cost. There are also situations where the operating life must be extended to the absolute maximum, such as products where the battery cannot be replaced or replacement involves very high costs. Having a low-power MCU by itself does not mean you will have lower energy consumption. The trick is to optimize your software not just in terms of functionality, but also with respect to energy efficiency. Having full control of the hardware surrounding the MCU and optimizing the overall software and peripheral usage are crucial factors for reducing system energy consumption. Software is not usually seen as an energy drain, yet every clock cycle consumes energy. Minimizing the number of clock cycles becomes a key challenge to reduce overall system consumption. The Energy Profiler enables you to visualize the energy consumption of individual devices, multiple devices on one target system, or a network of interacting wireless devices to analyze and improve the power performance of these systems. Real-time information on current consumption is correlated with the program counter providing advanced energy software monitoring capabilities. It also provides a basic level of integration with the Network Analyzer network analysis tool. In these pages the following terms will be used: **AEM**: Advanced Energy Monitor **ISD**: The file extension used with Multi-Node Energy Profiler and Network Analyzer files. **PTI**: Packet Trace Information #### Starting an Energy Analysis Session An energy analysis session can be started from either the [Simplicity IDE Perspective](#from-the-simplicity-ide-perspective) or from the [Energy Profiler](#from-the-energy-profiler). ##### From the Simplicity IDE Perspective Some Silicon Labs SDKs contain examples that are pre-configured to deliver energy profiling data to the Energy Profiler. In the Simplicity Studio Launcher perspective, you can find example titles such as "Powertest" or "Energy modes" or "Emode" for many development kits. In the figure below, the selected device is an EFR32 development kit. The Flex SDK has been installed. ![energy prof examples](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-examples.png) Create an example (in this case **Flex(RAIL) - Energy Mode**). Because this is a RAIL example, the Simplicity IDE perspective opens with the [Radio Configurator](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-developing-with-project-configurator/proprietary-radio-configurator) open. If this is an AppBuilder project, click **Generate**. Right-click the project directory. In the context menu select **Profile As > Simplicity Energy Profiler Target**. ![energy prof build project](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-build-project.png) SSv5 then: 1. Rebuilds the entire project. 2. Flashes the application to compatible hardware. 3. Starts energy capture for that device. 4. Switches to the Energy Profiler perspective. 5. Displays the device data on Single-Node View, Multi-Node View, and Scope View. In step 2 above, if more than one connected device is compatible with the application being profiled, SSv5 prompts you to select a device. Select the target of interest and click **OK**. ![energy prof select device](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-select-device.png) After the application is built and the firmware flashed, the Energy Profiler perspective is displayed, with a release notes dialog. Click **OK**. ![energy prof rel notes](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-rel-notes.png) ##### From the Energy Profiler If application firmware is already running on a device, you can connect to it from the Energy Profiler tool. Open the Energy Profiler perspective. Click **Quick Access** to display its menu and select **Start Energy Capture**. ![energy prof quick start](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-quick-start.png) If more than one connected device is compatible with the application being profiled, SSv5 prompts you to select a device. Select the target of interest and click **OK**. ![energy prof select device](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-select-device.png) Energy Profiler then: - Starts energy capture for that device. - Depending upon which view is currently active, displays the device’s energy data on Single-Node view, Multi-Node view, or Scope view. ##### Customer Hardware and Software Design Information This section discusses design requirements in order for a device to be able to use Energy Profiler features. Among these features is Code Correlation, which connects power consumption and executed code. Using code correlation is discussed in more detail in [Profiling with Code Correlation](profiling-with-code-correlation) ###### Hardware Design **EFM8 Hardware Interface** To use the Energy Profiler functionality on a board design, the board needs to include a debug interface that can be connected to a Silicon Labs starter kit (STK) or wireless starter kit (WSTK). For the basic Energy Profiler current measurements, the board must be powered from the VAEM supply of a Silicon Labs STK or WSTK. Both the current measurement and EFM8 C2 Debug interface can be obtained by using the Silicon Labs Mini Simplicity 10 pin connector. This connector is detailed in [AN958: Debugging and Programming Interfaces for Custom Designs](https://www.silabs.com/documents/public/application-notes/an958-mcu-stk-wstk-guide.pdf). The EFM8 C2 interface signals are on SWDIO (Pin 7 C2D) and SWCLK (Pin 8 C2CK) pins shown in the following figure. ![energy prof efm8](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-efm8.png) Code correlation is not possible with the EFM8 parts as they do not include the SWO pin that is used to transmit the program counter information. As mentioned in [AN958: Debugging and Programming Interfaces for Custom Designs](https://www.silabs.com/documents/public/application-notes/an958-mcu-stk-wstk-guide.pdf), using the Silicon Labs debug adapter board (BRD8010A) is the easiest way to get the Mini Simplicity pinout from a Silicon Labs STK or WSTK development kit. **EFM32 and EFR32 Hardware Interface** To use the Energy Profiler functionality on a board design, the board needs to include a debug interface that can be connected to a Silicon Labs STK or WSTK. For the basic Energy Profiler current measurements, the board must be powered from the VAEM supply of a Silicon Labs STK or WSTK. To also include code correlation, the debug interface must include the SWD interface. Both the current measurement and the code correlation (SWD) can be obtained by using the Silicon Labs Mini Simplicity 10 pin connector. This connector is detailed in [AN958: Debugging and Programming Interfaces for Custom Designs](https://www.silabs.com/documents/public/application-notes/an958-mcu-stk-wstk-guide.pdf). The Mini Simplicity 10 pin connector can be used with all EFM32 and EFR32 parts. The pinout is shown in the following figure. ![energy prof efm8](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-efm8.png) As mentioned in [AN958: Debugging and Programming Interfaces for Custom Designs](https://www.silabs.com/documents/public/application-notes/an958-mcu-stk-wstk-guide.pdf), using the Silicon Labs debug adapter board (BRD8010A) is the easiest way to get the Mini Simplicity pinout from a Silicon Labs STK or WSTK development kit. The debug adapter board is not compatible with the older EFM32 Development Kits (DKs) and some of the older EFM32 starter kits (STK) that have a different debug connector on them (Gecko, Giant Gecko (EFM32GG-STK3700), Leopard Gecko, Tiny Gecko, Wonder Gecko, Zero Gecko). ###### Software Design To use the current monitoring functionality provided by the AEM interface, no software changes or setup are required. To use the code correlation functionality, the SWD interface must be configured to output periodic program counter information. Currently, code correlation is not possible with the EFM8 family. The Multi-Node Energy Profiler can still be used to monitor the overall energy use of the parts over time / usage scenarios. Software can be configured in two ways: - [Project configurator method](#project-configurator-method) (using software components; preferred for SSv5 projects) - [Legacy method](#legacy-method) (by manually adding the necessary source code) ###### Project Configurator Method (heading level 7) This method of enabling code correlation is preferred in SSv5, as it leverages the software components and thereby reduces the chance of error. 1. In the Project Configurator, SOFTWARE COMPONENTS tab, find and install the **SWO Debug** component. 2. Click Configure to open the Component editor. 3. Open its configuration file and turn on **Enable interrupt event trace** and **Enable program counter samples**. 4. If the device allows SWO functionality on multiple GPIO pins, in the SL_Debug card's **SWV** field, select the pin to be used as the SWO output. ![SWO Debug component configuration](/ss-5-users-guide-tools-energy-profiler/0.7/images/swo-debug-component-configuration.png) Further initialization of the software component in code is not required provided that the **System Init** component is installed in the project. ###### Legacy Method (heading level 7) This method should be used for Appbuilder project and projects not created in the Project Configurator. 1. The following paths must be included in your project, as they provide access to relevant header files used to enable code correlation. These header files are readily available for Silicon Labs parts. For custom design boards use bsp_trace.h and traceconfig.h as a reference instead. 1. /developer/sdks/gecko_sdk_suite//hardware/kit/common/bsp - Grants access to bsp_trace.h 2. (not required for AppBuilder projects) /developer/sdks/gecko_sdk_suite//hardware/kit/kitname/config - Grants access to traceconfig.h - For AppBuilder projects, instead see the next step. 2. (Only for Appbuilder projects) In the Hardware Configurator file (.hwconf) in the "DefaultMode" peripheral tab, enable the GPIO module. This adds the **BSP_TRACE_SWO_** macros to the hal-config.h file. ![DefaultMode peripherals tab with GPIO enabled](/ss-5-users-guide-tools-energy-profiler/0.7/images/hwconf-gpio.png) 3. Add bsp_trace.c to the project (from /developer/sdks/gecko_sdk_suite//hardware/kit/common/bsp) 4. The code must enable SWO output from the MCU. To enable this output, add `#include bsp_trace.h` to the appropriate module and call `BSP_TraceSwoSetup()` during initialization as indicated in the following sections, based on the SDK being used. **Stackless project MCU SDK:** Place `BSP_TraceSwoSetup()` after the `EMU_DCDCInit()` call in main(). ```c++ #include "bsp_trace.h" . . . /* Initialize DCDC. Always start in low-noise mode. */ dcdcInit.dcdcMode = emuDcdcMode_LowNoise; EMU_DCDCInit(&dcdcInit); // Setup SWD for code correlation BSP_TraceSwoSetup(); ``` **Bluetooth LE SDK:** Place `BSP_TraceProfilerSetup()` in main.c after the `initApp()` call. ```c++ #include "bsp_trace.h" . . . // Initialize application initApp(); // Setup SWD for code correlation BSP_TraceProfilerSetup(); // Initialize LEDs BSP_LedsInit(); ``` **Flex SDK:** Place `BSP_TraceProfilerSetup()` in main.c after the `BSP_Init()` call. ```c++ #include "hal_common.h" #include "bsp_trace.h" . . . // Initialize the BSP BSP_Init(BSP_INIT_BCC); // Setup SWD for code correlation BSP_TraceProfilerSetup(); ``` **EmberZNet SDK:** Place `BSP_TraceProfilerSetup()` in af-main-soc.c after the `emberInit()` call. ```c++ #include "afv2-bookkeeping.h" #if defined(CORTEXM3_EFR32_MICRO) || defined (CORTEXM3_EMBER_MICRO) #define EXTENDED_RESET_INFO #include "hal/micro/cortexm3/ diagnostic.h" #endif #include "bsp_trace.h" . . . int emberAfMain (MAIN_FUNCTION_PARAMETERS) { EmberStatus status; int returnCode; if (emberAfMainStartCallback(& returnCode, APP_FRAMEWORK_MAIN_ARGUMENTS)) { return returnCode; } } // Initialize the Ember Stack. status = emberInit(); if (status != EMBER_SUCCESS) { emberAfCorePrintln("%pemberInit 0x%x", "ERROR: ", status); // The app can choose what to do here. If the app is running // another device then it could stay running and report the // error visually for example. This app asserts. assert(false); } else { emberAfDebugPrintln("init pass"); } // Setup SWD for code correlation BSP_TraceProfilerSetup(); ``` The program must be built with debug information enabled so that source code lookup is possible. If you create your project in Simplicity Studio, this is enabled by default. If you import a project into Simplicity Studio, check compiler options in project context menu **Properties...-> C/C++ Build -> Settings**. If you build the program outside of Simplicity Studio, check compiler options of the build tools. **EFM32 Software Configuration** 1. Add bsp_trace.c to the project. (from \developer\sdks\gecko_sdk_suite<version>\hardware\kit\common\bsp) 2. The macros BSP_TRACE_SWO_PIN, BSP_TRACE_SWO_PORT and BSP_TRACE_SWO_LOC must be defined. For EFM32 parts this is done by default for Silicon Labs development kits in \developer\sdks\gecko_sdk_suite\\hardware\kit\/hal-config-board.h. For a custom board design the Silicon Labs hal-config-board.h can be used as an example for defining the values. The following is an example for the Pearl Gecko Starter Kit (SLSTK3401A): ```c++ // $[GPIO] #define PORTIO_GPIO_SWV_PIN (2) #define PORTIO_GPIO_SWV_PORT (gpioPortF) #define PORTIO_GPIO_SWV_LOC (0) #define BSP_TRACE_SWO_PIN (2) #define BSP_TRACE_SWO_PORT (gpioPortF) #define BSP_TRACE_SWO_LOC (0) // [GPIO]$ ``` 3. The code must enable SWO output from the MCU. To enable this output, add `#include bsp_trace.h` to main.c and call `BSP_TraceProfilerSetup()` during initialization after the `EMU_DCDCInit()` call in `main()`. ```c++ #include #include "bsp_trace.h" . . . /* Initialize DCDC. Always start in low-noise mode. */ dcdcInit.dcdcMode = emuDcdcMode_LowNoise; EMU_DCDCInit(&dcdcInit); // Setup SWD for code correlation BSP_TraceProfilerSetup(); ``` 4. The program must be built with debug information enabled so that source code lookup is possible. If you create your project in SSv5, this is enabled by default. If you import a project into SSv5, check compiler options in project context menu **Properties... > C/C++ Build > Settings**. If you build your program outside of SSv5, check compiler options of the build tools. #### Energy Profiler User Interface The Energy Profiler perspective is divided into six primary sections. The following figure shows Single-Node view. - Quick Access Menus - The most frequently used menus for Multi-Node Energy Profiler are available on the user interface itself and also from the Profiler menu at the top menu bar. - View Selector - Three views for Multi-Node Energy Profiler can be selected by clicking the View Selector bar. - Data Control - Controls in this area are used to enable and disable data flow to the user interface and to disk. - Statistics - Energy data for the waveform is shown in the statistics area. - Code Correlation - Function execution related to power consumption is shown in the Code Correlation view. - Editor - Source code for the program is shown here and works in conjunction with the Code Correlation view. ![energy prof interface](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-interface.png) Three views are available for evaluating power performance: - [Single-Node View](#single-node-view) - [Multi-Node View](#multi-node-view) - [Scope View](#scope-view) ##### Single-Node View Single-Node view is used to display a single device’s waveform and events. It displays a high-detail waveform and ensures that all events rows are visible, without the need to scroll the UI. The Energy Profiler perspective combines this Single-Node view, the Code Correlation view, and the source code Editor view, allowing you to perform in-depth analysis of a single device from many viewpoints. Any active device may be selected through the **Display Nodes** menu. ![energy prof single node](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-single-node.png) ##### Multi-Node View Multi-Node view is used to display multiple device waveform and events. It allows you to investigate system behavior and interactions between devices. Two devices are visible in the main portion of the UI, while others are viewed by scrolling. The Multi-Node view groups each individual device’s waveform and events together. The Energy Profiler perspective combines this Multi-Node view, the Code Correlation view, and the source code Editor view, allowing you to perform in-depth analysis of multiple devices from many viewpoints. ![energy prof multi node](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-multi-node.png) Multi-Node view offers the following capabilities: - Sorting - Node display control **Sorting** Sorting in Multi-Node view allows you to order waveforms based upon several criteria. For example, it may be useful to sort descending by average power, such that the highest power consumers are easily identified at the top. As shown in the following figure, devices may be sorted ascending and descending by name, average current, average power, or total energy. ![energy prof multi sort](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-multi-sort.png) **Displaying Nodes** Enabling capture on any device automatically adds it to the Multi-Node view. However, as the number of devices displayed increases, UI performance may be impacted. Click **Display Nodes** to select the devices that will be displayed. This selection only affects the waveform display. If recording is enabled, data for all actively capturing devices is streamed to disk regardless of whether or not they are displayed. ![energy prof multi select](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-multi-select.png) ##### Scope View Scope view is used to display multiple device waveforms and events, allowing you to investigate system behavior and interactions between devices. In Scope view, all waveforms are displayed in one waveform area, so that you can see all waveforms without needing to scroll the UI. It also enables the user overlay and align traces like an oscilloscope. All event traces are grouped below the waveform view. The Energy Profiler perspective combines this Scope view, the Code Correlation view, and the source code Editor view allowing you to perform in-depth analysis of a single device from many viewpoints. ![energy prof scope](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-scope.png) Scope view offers the following capabilities: - Sorting - Node display control - Waveform display control **Sorting** Sorting in Scope view allows you to order events based upon several criteria. For example, it may be useful to sort events descending by average power, such that the events for the highest power consumers are easily identified at the top. ![energy prof multi sort](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-multi-sort.png) **Displaying Nodes** Enabling capture on any device automatically adds it to scope view. However, as the number of devices displayed increases, UI performance may be impacted. Click **Display Nodes** to select which devices will be displayed. This selection only enables or disables display of waveform and event data in the UI. If recording is enabled, data for all actively capturing devices is streamed to disk regardless of whether they are displayed. ![energy prof scope select](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-scope-select.png) **Displaying Waveforms** One of the Scope view’s key benefits is the ability to view waveforms in a single view at difference scales, enabling you to compare waveform characteristics that would not be possible for two waveforms on the same scale. The waveform scale/offset controls are available by default at the upper right corner of the Scope waveform view. The color of the waveform scale/offset control indicates which waveform will be adjusted when the sliders are moved. ![energy prof scope wave](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-scope-wave.png) The drop-down menu at the top of the control allows you to select the device to be adjusted by the waveform scale and offset control. The debug adapter name colors match the colors in the waveform portion of Scope view. ![energy prof scope wave2](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-scope-wave2.png) Toggle wave scale/offset control display using the show/hide button above it. ![energy prof scope wave3](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-scope-wave3.png) **Selecting Ranges** Energy Profiler provides the ability to select a range of data by clicking and dragging across the waveforms or events. This is useful for determining power statistics for regions of interest. Once a range is selected, a light gray section summarizing the energy statistics for the selected region is displayed. That section also allows you to re-center the selection in the waveform view if it has scrolled out of view and includes a button to close/deselect the region. ![energy prof select range](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-select-range.png) #### Energy Statistics Energy Profiler calculates the following device and system statistics: - Average current - Average power - Total energy Statistics are provided for each individual device in the waveform’s top bar on both Single-Node and Multi-Node views. The sum for all devices is provided in the top bar of Multi-Node Energy Profiler for all three views. Single-Node and Multi-Node views provide individual device statistics, while Scope view does not. ![energy prof stats](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-stats.png) This page reviews how to: - [Configure energy statistics](#energy-statistics-configuration) - [Save a snapshot for future reference](#energy-statistics-snapshot) - [Review saved statistics](#review-saved-statistics) ##### Energy Statistics Configuration Energy Profiler allows you to select which of the actively capturing devices are included in the total system energy statistics calculation displayed in the top bar. Click the **Energy Statistics Configuration** icon and select the devices to be included in the calculation. It is important to note that the devices available for selection are those that are actively capturing data, which may be different from the devices that are selected for display in the UI. ![energy prof stats config](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-stats-config.png) ##### Energy Statistics Snapshot Energy Profiler allows you to save statistics for future reference and comparison. Click the **Save Snapshot** icon on any of the energy statistics panels and be presented with a dialog to provide a name and tag for future reference. ![energy prof stats snapshot](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-stats-snapshot.png) ##### Review Saved Statistics Once you have saved multiple snapshots, you may want to review them, or to copy them to the clipboard for use in other applications. This is possible through the **Profiler->Session Statistics...** menu. ![energy prof stats save](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-stats-save.png) #### Play and Record Data Control The following diagram provides a general description of data flow from target devices into SSv5 profiling applications. Data is sourced from target devices from the debug adapter either through USB or Ethernet connectivity to the host PC. The host debug adapter software layer provides data to the AEM/PTI data streaming engine, which in turn provides data to analysis applications such as Multi-Node Energy Profiler or Network Analyzer. The AEM/PTI data streaming engine saves data to disk in temporary files during a capture session. When the user ends the session, Energy Profiler prompts the user with the option to save the data to file. ![energy prof control chart](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-control-chart.png) [Play](#play-control) and [record](#record-control) controls in the top bar of the Energy Profiler perspective provide control over data being captured from connected devices. ![energy prof control buttons](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-control-buttons.png) ##### Play Control The Play control determines whether data being captured is displayed in the Multi-Node Energy Profiler UI. The Play control has three states: - Running (green) - Paused (black) - Frozen (orange) ![energy prof control play](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-control-play.png) - **Running**: The "Running" state is entered when a capture is first started. When the Play control is green and displays "Running", it means energy capture data is actively arriving and being displayed on the UI. The visible portion of the waveform and events is the most recently captured data as it is arriving to Multi-Node Energy Profiler. The time position scroll bar is all the way to the right. - **Paused**: The "Paused" state is entered by clicking **Play** while it is in the green "Running" state. The Play control turns black and displays "Paused", indicating energy capture data is actively arriving but it is not being displayed on the UI. The visible portion of the waveform and events may be anywhere on the timeline of previously captured data. Pausing the display has no effect on whether data is saved to disk. Save to disk is determined by the state of the Record control. - **Frozen**: The "Frozen" state means energy capture data is actively arriving for display, but the visible portion of the waveform and events in the UI is previously captured data. The time position scroll bar may be anywhere on the timeline of previously captured data. The "Frozen" state is entered when the UI is in the play state and the time position scroll bar is scrolled or moved to the left. The "Frozen" state may also be entered as the result of a "Freeze trigger" condition. The "Frozen" Play control state has no effect on whether data is saved to disk. Save to disk is determined by the state of the Record control. ##### Record Control The Record control manages data streaming to disk. There are two states to the Record control: - Recording (red) - Not recording (black) ![energy prof control record](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-control-record.png) - **Recording**: When the Record control is red and displays "Recording", it means energy capture data is actively arriving and is being saved to temporary files to disk. When an energy capture is started, the "Recording" state is entered automatically. The state of the Record control has no effect on the Play control or the data being displayed in the UI. Clicking the Record control while in the "Recording" state transitions to the "Not Rec" state (that is, not recording). The "Recording" state may also be entered by use of Record triggers. - **Not Recording**: When the Record control is black and displays "Not Rec", it means energy capture data is actively arriving but it is not being saved to disk. The "Not Rec" state is entered by clicking the Record control when it is in the "Recording" state. The state of the Record control has no effect on the Play control or the data being displayed in the UI. Clicking the Record control while in the "Not Rec" state will transition to the "Recording" state. The "Not Rec" state may also be entered by use of record triggers. #### Freeze and Record Triggers Triggers provide a method to automate freezing the display or recording to disk. Trigger icons are found below the Play and Record controls. Three triggers are available: - [Freeze trigger](#freeze-trigger) - [Record start trigger](#record-start-stop-triggers) - [Record stop trigger](#record-start-stop-triggers) ![energy prof trigger controls](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-trigger-controls.png) Triggers are driven by criteria set by the user. To set the criteria, use the context menu available from each trigger icon. The context menu also provides the ability to clear all conditions, which also disables the trigger. ![energy prof trigger criteria](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-trigger-criteria.png) ##### Trigger States The four trigger states are each designated by a color: - Grey - Trigger conditions are not set - Yellow - Trigger conditions are set, trigger is not armed - Red - Trigger conditions are set, trigger is armed - Green - Trigger has fired When Energy Profiler first starts up in a new workspace, all trigger icons are grey, indicating trigger conditions have not yet been set. Clicking a grey trigger icon opens the trigger configuration dialog, allowing you to specify trigger conditions. Once trigger conditions have been set, the trigger icon turns yellow, indicating the trigger conditions are set but the trigger is not armed. Clicking a yellow trigger icon arms the trigger as indicated by the trigger icon turning red. Incoming data is now evaluated against the trigger condition. Once the trigger condition is satisfied, the trigger icon turns green, indicating the armed trigger has fired. The relevant action (freeze, record start, or record stop) will have been executed. The following diagram shows the trigger state behavior. ![energy prof trigger states](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-trigger-states.png) ##### Freeze Trigger The freeze trigger transitions the user interface from play to freeze mode automatically based upon search criteria. The freeze criteria are set through the Freeze Trigger Conditions dialog. This is invoked either through the **Profiler > Freeze Trigger...** menu selection or by right-clicking the **Freeze Trigger** icon and selecting **Configure Freeze Trigger". ![energy prof trigger freeze](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-trigger-freeze.png) In the following diagram, the play freeze trigger condition has occurred in the incoming data. Freeze mode is automatically entered for the waveform display and data continues to arrive as indicated by the scroll bar automatically moving to the left as new data arrives. Notice that the freeze trigger icon is green, indicating the trigger condition has occurred in arriving data. ![energy prof trigger freeze2](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-trigger-freeze2.png) ##### Record Start/Stop Triggers The record start/stop triggers automatically start and stop data record to disk based upon search criteria. This may be beneficial for capturing rare conditions rather than recording large amounts of data followed by search. The record start criteria are set through the Record Start/Stop Trigger Conditions dialog, which is invoked through the **Profiler > Record Triggers...** selection" menu or by right-clicking the **Record Start** or **Record Stop** icon and selecting the **Configure** option. The record start/stop trigger conditions are set together in a single dialog as shown in the following figure. ![energy prof trigger record](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-trigger-record.png) In the following figure, the record start trigger condition has occurred in the incoming data as indicated by the green record start trigger icon. The record stop trigger condition has not yet occurred and data will be written to disk until it does. ![energy prof trigger record2](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-trigger-record2.png) #### Search Capability One of Energy Profiler's most powerful aspects is the ability to search data. Search is available both during a live capture and with an offline ISD file. Click **Search** to open the Search Conditions dialog. ![energy prof search](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-search.png) When you click **OK**, a search is performed on all data currently available, whether from the currently active capture or in offline mode from an open file. The search results window is displayed on completion. Sections where the data matched the criteria are shown in red. A summary of the count and % coverage of the matching regions is shown at the upper right. Use the context menu to jump to the matching in the waveform view from the search results window. ![energy prof search2](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-search2.png) #### Profiling with Code Correlation Code correlation is one of the most powerful features in Energy Profiler. Energy Profiler captures program execution in conjunction with the energy data. This allows Energy Profiler to calculate the power consumed by each function executed in the application. This data may then be sorted to highlight the portions of an application that consume the most power. This enables the application developer to know where they should concentrate their software development efforts to reduce power consumption. Additionally, Energy Profiler can color-code sections of the current waveform to represent which functions were executing when a given section of the current waveform occurred. This page reviews: - [Enabling code correlation](#enabling-code-correlation) - [The Code Correlation view](#code-correlation-view) - [Color coding](#color-coding-and-code-correlation) ##### Enabling Code Correlation This section assumes an embedded application is already configured to produce AEM data through a debug adapter (see [Customer Hardware and Software Design Information](./starting-a-session#customer-hardware-and-software-design-information) for details). For code correlation to operate, Energy Profiler needs access to debug information associated with the embedded application that is currently running. This information is available in the AXF file output from the build. Code correlation can be enabled when an application is started from the Simplicity IDE perspective through context menu commands for a given project, or it can be associated with an application already running on an embedded device that is being profiled in Energy Profiler. **From the Simplicity IDE Perspective** One simple way to enable the code correlation view is to start the energy profiling session by using the context menu on the project from the Simplicity IDE perspective, as shown below. The associated debug file will be provided to Energy Profiler when the session is started. ![energy prof code correl](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-code-correl.png) Once Energy Profiler starts, the following view is displayed. Notice in the Code Correlation view, energy consumed by each function is updated in real time. Clicking any of the functions opens the associated source code file and jumps to that function in the file. ![energy prof code correl view](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-code-correl-view.png) **From Energy Profiler** If you start energy capture with a running embedded application, Energy Profiler does not have the debug information it needs to associate program execution with source code. In these cases, the Code Correlation view is as shown in the following figure. ![energy prof code correl profiler](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-code-correl-profiler.png) Click the **elect an Executable** link and the program selection dialog is displayed. Debug files from open projects are provided in the list. Alternatively, you may browse to select the debug file. ![energy prof code correl profiler2](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-code-correl-profiler2.png) ##### Code Correlation View The Code Correlation view is shown below the waveform portion of the Multi-Node Energy Profiler Perspective, and works in conjunction with the Editor view. When multiple devices are displayed in the Multi-Node view, you can click on each adapter to view the function profile data associated with that device. The function data may be sorted as desired. Clicking on any function opens the associated source file in the Editor view with the start of scope for that function selected. ![energy prof code correl view2](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-code-correl-view2.png) ##### Color Coding and Code Correlation Energy Profiler provides the ability to color-code the current waveform based on program execution. You can set the color for each function using the context menus in the Code Correlation view. ![energy prof code correl color](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-code-correl-color.png) The following figure shows the current waveform view with several functions set to different colors. ![energy prof code correl color2](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-code-correl-color2.png) #### Debugging with the Logic Analyzer **Note:** Energy Profiler's integrated Logic Analyzer can only be used with Wireless Pro Kit Mainboards, such as BRD4002A. The features described in this section are enabled only when supported hardware is connected. The Logic Analyzer displays the profiles from up to eight channels corresponding to the mainboard's four external pins, two LEDs, and two buttons: External channels: 0-3 - CH0 - CH1 - CH2 - CH3 Internal channels: 4-7 - CH4: LED0 - CH5: LED1 - CH6: BTN0 - CH7: BTN1 ![pro kit for logic analyzer](/ss-5-users-guide-tools-energy-profiler/0.7/images/logic-analyzer-pro-kit.png) The Logic Analyzer's channel buttons act as toggles: click a button to display the logic signal, click again to turn it off. The channels that are being displayed can be dragged and positioned closer to or farther away from other channels or the energy profile. ![logic analyzer generic view](/ss-5-users-guide-tools-energy-profiler/0.7/images/logic-analyzer-generic-view.png) Freeze triggers can be set for the logic signals as for other features, as described in [Freeze and Record Triggers](freeze-and-record). Click the Freeze trigger to open the configuration dialog, then select **DigitalSignal**, the target channel, and the condition. Logic channel data recording will be enabled in a future release. ![logic analyzer freeze trigger](/ss-5-users-guide-tools-energy-profiler/0.7/images/logic-analyzer-trigger-view.png) #### Energy Profiler and Network Analyzer Integration **Note: This functionality is only available in offline mode with a previously saved ISD file.** Energy Profiler and Network Analyzer now provide a basic level of integration when trace data from a debug adapter includes both AEM and PTI data. This integration allows you to easily move between the two applications by selecting an event in either one and selecting **Show in Network Analyzer** or **Show in Energy Profiler**. An SSv5 preference determines whether moving between applications leaves the Energy Profiler perspective and opens the Network Analyzer perspective, or stays in the Energy Profiler perspective. ![energy prof net anal preference](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-net-anal-preference.png) This page reviews: - [How to use the integrated tools](#using-the-integrated-tools) - [Use Cases for Multi-Node Energy Profiler and Network Analyzer](#use-cases-for-multi-node-energy-profiler-and-network-analyzer) - [Post analysis using an ISD file](#post-analysis-using-an-isd-file) ##### Using the Integrated Tools To open a previously saved ISD file, either use the top menu **Profiler > Open ISD File...** menu or the **Quick Access > Open ISD File...** menu, as shown in the following figure. ![energy prof net anal open isd](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-net-anal-open-isd.png) Once the file is open, you can examine previously recorded details. In the following figure, notice two devices transmitting and receiving packets. Select a TX or RX event and display the context menu. One of the options is **Show in Network Analyzer**. ![energy prof net anal switch](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-net-anal-switch.png) Select that option and the Network Analyzer view opens either in the Energy Profiler perspective or the Network Analyzer perspective, based upon the preference setting. ![energy prof net anal show](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-net-anal-show.png) Likewise, you can select an event in Network Analyzer and use the context menu to navigate back to Energy Profiler. ![energy prof net anal show2](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-net-anal-show2.png) ##### Use Cases for Multi-Node Energy Profiler and Network Analyzer Depending upon your goals for an analysis session, there will be times when you will primarily use Network Analyzer, times when you will primarily use Energy Profiler, and times when you will find it advantageous to use them together. When you are interested in energy consumption of a single or multiple devices, Energy Profiler is where you will focus your time. From a network communication perspective, it provides only the start time of a TX or RX packet, and does not provide any decoding of the packets themselves. Still, this information can be revealing in your application's consumption of power relative to network activity. For example, by using the search tool, you can set search criteria that identify all points in the data where a packet was transmitted and the power exceeded a given value. If you have an expected power performance based upon your design, you can quickly identify when your system is operating outside its specification. If you are interested in packet contents, node activity, and network interaction in a wireless network, Network Analyzer is where you will focus your time. Network Analyzer's multiple editor panes provide tiered displays of network activity, letting you drill down from a high-level map of node interactions to the details of each packet. Customizable filters enable you to specify exactly which network activities to display, allowing you to sift out information unrelated to a given task. These features allow you to determine when your network is behaving as expected, but are not available in Energy Profiler. You will find yourself benefitting from the integration of these applications where these two information spaces intersect. For example, the Energy Profiler use case mentioned above ended at finding a transmit packet that exceeded expected power consumption. To investigate further, you could select **Show in Network Analyzer** to investigate that specific node's network activity and packet contents, in hopes of determining why the power was higher for that particular network transaction. In contrast, you may suspect that packets with specific content are the root cause of high power consumption. In Network Analyzer you could search for that data, and use **Show in Energy Profiler** to determine if indeed those packet contents are the root cause of high power consumption. ##### Post Analysis Using an ISD File Both Network Analyzer and Energy Profiler capture data in the same format, which are saved in the ISD file format. Both applications can open an ISD file that has been save by either application. For example, if you have completed an Energy Profiler session and saved the ISD file, only to realize later that you are interested in the packet trace information, you would open that file from Network Analyzer to further investigate it. It is important to note, however, that captures started in Energy Profiler include packet trace data by default, but captures started in Network Analyzer only contain energy data if the preference to include it has been selected, as shown in the following figure. ![energy prof net anal analysis](/ss-5-users-guide-tools-energy-profiler/0.7/images/energy-prof-net-anal-analysis.png) ### Network Analyzer #### Network Analyzer Simplicity Studio® 5 (SSv5)'s Network Analyzer enables debugging of complex wireless systems. This tool captures a trace of wireless network activity that can be examined in detail live or at a later time. ![net anal start](/ss-5-users-guide-tools-network-analyzer/0.7/images/net-anal-start.png) More than simply a packet sniffer, the Network Analyzer works with the data sniffer interface on the Silicon Labs wireless chips to provide direct feedback from the baseband radio of each device, allowing any supported radio to report detailed packet transmission and reception data, such as timestamps, link quality (or LQI), receive sensitivity (or RSSI), and CRC pass/fail results, all without any software overhead. With SSv5, any PTI-enabled Silicon Labs platform can record the radio activity regardless of the application firmware that is being used, so there’s no need to have a dedicated sniffer device installed to catch the traffic. The Network Analyzer also enables capture from multiple sources simultaneously into the same log file without falsely duplicating packets. This enables the developer to compare how well different radios in the network heard the same transmission. In cases when detail is not desired, Network Analyzer makes it easier to understand the workings of a complex wireless protocol. Related packet events are automatically grouped into a Transactions pane within the capture view, allowing for quicker parsing of what’s happening during that portion of the traffic log. Quickly access statistics like total duration, number of related packets, number of point-to-point and end-to-end retries, and unexpected conditions like requests with missing responses or deliveries where expected acknowledgments are missing. In addition to capturing packet events, Network Analyzer also captures asserts, debug prints, and many other events. This guide contains the following sections: - [Network Analyzer Interface](./network-analyzer-interface): Provides a guided tour of all elements of the Network Analyzer Perspective. - [Capturing Data and Managing Sessions](./capturing-and-saving-data): Describes how to perform live captures, and save and manage the resulting data. - [Viewing Data in Editors](./viewing-data-in-editors): Goes into detail about working with the data presented in both the Stream Editor and the Large File Editor. - [Filtering Captured Data](./viewing-packet-data): Explains how to focus on exactly what you need from a Network Analyzer session. - [Multinetwork Considerations](./multinetwork-considerations): Discusses how to manage nodes that belong to more than one network. - [Custom Decoders](./custom-decoders): Explains the basics of how to create custom decoders. - [Network Analyzer Preferences](./network-analyzer-preferences): Provides a reference for the many ways you can customize Network Analyzer to meet your needs. #### Network Analyzer Interface The Network Analyzer Interface is presented as a Network Analyzer perspective. ![Network Analyzer Perspective](/ss-5-users-guide-tools-network-analyzer/0.7/images/network-analyzer-ui.png) The Network Analyzer perspective contains the following work areas: - Debug Adapters view (1) - Lists all debug adapters and their connected hardware that are accessible to Network Analyzer. See [Simplicity IDE User Interface Review](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-about-the-simplicity-ide/user-interface-review) - Capture sessions (2) - Contain data captured from a node or set of nodes, with each session shown as a tab, and a live session shown in a ***Live** tab. - [Editor Panes](#editor-panes) - Display the data of a selected capture session in the editor area with up to five different panes. Network Analyzer supports two types of capture sessions: - Live sessions - Display data as it is captured; the display is continuously refreshed as new data arrives. - Saved sessions - Contain captured data that has been saved to permanent storage in a named .isd file. You can load a saved session and play it back at any time. - [Toolbar and Menu](#toolbar-and-menu) (3) and [Supporting Views](#other-views) (11) - Provide options to control data capture and display. A filter Bar (4) allows you to enter data filters, as described in [Filtering Captured Data](./viewing-packet-data#filter-bar). A Timeline Bar (5) displays the statistics of the traffic over time, as discussed in [Viewing Data in editors](./viewing-data-in-editors#timeline-bar) The [Views area](#other-views) (11) displays additional views in a tabbed interface. ##### Editor Panes Editor panes provide different aspects of capture session data. Up to five editor panes can be open at any one time: - **Map** (6) provides a graphical view of the network, where nodes are displayed with their network identifiers. The map also displays network activity. - **Transactions** (7) displays high-level node interactions that might comprise multiple events. - **Events** (8) displays information about all events transmitted and received during a capture session. - **Event Detail** (9) displays the decoded contents of the event that is currently selected in the Events pane. - **Hex Dump** (10) displays the data of the selected event in raw bytes. Network Analyzer highlights bytes that map to the data currently selected in the Event Detail pane. It shows multiple "layers", so if the packet is decrypted, the "raw" layer shows encrypted data, but the higher-level layers show this data progressively decrypted. Using the editor is discussed in more detail in [Viewing Data in Editors](./viewing-data-in-editors) ##### Toolbar and Menu The Network Analyzer Toolbar and Menu provides shortcuts to frequently-used features. Selections and controls are either enabled or disabled depending on what the user is doing. ![network analyzer menu](/ss-5-users-guide-tools-network-analyzer/0.7/images/network-analyzer-menu.png) On the toolbar, hover over any control to see a short description. The following describes the controls in order from left to right. Where the function is also available on the Network Analyzer menu, it is so noted. ![network analyzer toolbar first half](/ss-5-users-guide-tools-network-analyzer/0.7/images/net-anal-toolbar-1.png) Network Analyzer toolbar controls are added to the controls already present in the Simplicity IDE. See [About the Simplicity IDE](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-about-the-simplicity-ide) for more information. This section provides Network Analyzer-specific information, if any, about those controls. **Open File** - Opens a file dialog from which the user may select one of the applicable extensions, such as .isd, or .log. Equivalent to File > Open File (Network Analyzer Trace, Energy Profiler, etc.). **Open Capture Directory** - Opens the folder to which an output file has previously been saved. Equivalent to File > Other Network Analyzer Actions > Open Network Analyzer Capture Directory. **Restart a Process** - Simplicity IDE function. **New** - Creates a new project or other file. Equivalent to File > Other Network Analyzer Functions > New Live Capture Session. **Save (Ctrl+S)** - Saves any changes to the currently opened file to disk. If the file has never been saved before, the user can say where they want it saved and what extension they want to give it. If the file was previously saved, Network Analyzer saves over the old file. **Save All (Ctrl+Shift+S)** - Saves all files that have been edited, including any files open elsewhere in Simplicity Studio. As with Save, the user has the option to indicate where and how to save any files that have never been saved. **Next Annotation** and **Previous Annotation** - Simplicity IDE function. **Last Edit Location** - Simplicity IDE function. **Back** and **Forward** - Simplicity IDE function. **Pin Editor** - Simplicity IDE function. **Reopen Editor** - Closes and reopens the editor. When you have changed or added new decryption keys to the preferences, it is useful to be able to reopen the file and run it through the decryptors and decoders again. **Clear Events** - Clears the editor of all events. This is useful when you are capturing on a network and are waiting for some set of events to occur but do not want to keep everything else around. **Live Capture Options** - Opens the [Capture Options](./capturing-and-saving-data#capturing-with-options) dialog, used to tailor the condition under which events will be captured. **View and Modify Security Keys** (Toolbar and Menu) - Opens the **Active live capture keys** dialog, where you can add security keys to be used during the current capture in progress. Any keys that are added will also be added to the list of security keys in the Network Analyzer preferences. **Pause Stream** (Toolbar and Menu) - Pauses a capture without stopping it. This is useful to stop capturing for period of time, and then later continue as if nothing happened. Live events occurring during a pause are not retrievable. **Import** - Select files to import and the type of import. Additional fields allow you to specify characteristics of the import. Equivalent to File > Network Analyzer Import. **Export** - Select the exporter to use, and the output file name and location. Other options depend on the exporter. Equivalent to File > Network Analyzer Export. ![network analyzer toolbar second half](/ss-5-users-guide-tools-network-analyzer/0.7/images/net-anal-toolbar-2.png) **Show Short Id** (Toolbar and Menu) - Displays a node's shortId on the map, if one is known for the currently selected time. **Show Long Id** (Toolbar and Menu) - Displays a node's long Id (64 bit identifier) on the map, if one is known. **Show Pan Id** (Toolbar and Menu) - Displays the pan Id on the map, if one is know for the currently selected time. **Show Node Label** (Toolbar and Menu) - Displays the node's label. If the node is connected to Network Analyzer over the backchannel, this value will be the host name of the adapter connected to the node. **Show Signal Strength** (Toolbar and Menu) **Show All Connectivity** (Toolbar and Menu) - Shows the quality of connections between nodes on the map. **Show all Simultaneous Events on Map** (Toolbar and Menu) - During periods of heavy traffic, several simultaneous transactions may overlap. When enabled, the map shows all traffic. When it is disabled (default), the map shows only the traffic related to the currently selected transaction. **Show All Transactions on Map** (Toolbar and Menu) - When enabled, all transactions that overlap with the currently selected one are shown on the map. **Filter Nodes** (Toolbar and Menu) - Filters out nodes that are not involved with the filtered event. **Map Zoom In** and **Map Zoom Out** (Toolbar and Menu) - Increases and decreases the size of the map in the map page. Zooming in can be useful if you are looking at a very large network where a large number of nodes are positioned very close together. **Edit Trace File Description** (Toolbar and Menu) - Each saved Network Analyzer trace file contains a description. The description can be used to store information that is important to the trace but may not be included by default. Generally the description is used to provide context for the trace and any other information that may be of help to the viewer. A checkbox on the dialog determines if the description is shown when the file is loaded. **Go To Line** (Toolbar and Menu) - Moves the event cursor directly to the event number entered. This is only enabled if the Stream preference "Show event numbers" is selected. To turn this feature on go to: Window > Preferences > Network Analyzer > Capture Configuration > Show event numbers. **Go to Time** (Toolbar and Menu) - Moves the cursor to the transaction and event that match or immediately follow the specified time. **Go To Bookmark** (Toolbar and Menu) - Moves the event or transaction cursor to the bookmark selected in the bookmark dialog. Assign bookmarks to events or transactions by right-clicking the event or transaction and selecting **Add Bookmark**. **Decrease Font Size** and **Increase Font Size** (Toolbar and Menu) - Decreases and increases the size of the font used in the Event, Transaction and Detail panes. **Apply Row Coloring** (Toolbar and Menu) - Turns coloring on and off in the Transaction and Event panes. Row colors are applied based on the pre-defined filters included in the [Filter Manager](./viewing-packet-data#filter-manager). **Lock To Bottom** (Toolbar and Menu) - Locks the event cursor to the bottom of the Event pane. During a live capture, this causes the Map and Details panes to always show the latest event. To remove the lock, select any event or transaction during a live session, which causes a view to scroll as the events are captured. **Start Replay** (Toolbar and Menu) - Begins scrolling forward through events from the current event selected. If no event is selected, the scrolling will begin from the start of the current trace file. Once replay has started, converts to a **Stop Replay** function. **Timeline Bar** - Toggles the [timeline](viewing-data-in-editors#timeline) shown at the top of the currently opened Stream Editor. **Toggle Filter Bar** - Toggles the [Filter Bar](./viewing-packet-data#filter-bar) at the top of the currently opened Stream Editor. **Show Filter Manager View** - Toggles the [Filter Manager View](./viewing-packet-data#filter-manager). The following are selections on the Network Analyzer menu that are not on the toolbar: **Show DAG** - Shows the connectivity DAG from the captured neighbor DAG events. Applies only in cases when the networking stack is instrumented with the correct abilities. **Load Background Image** and **Clear Background Image** - Loads and clears a background image on the map pane. Also available on the Map pane context menu. **Print map** - Prints the nodes as currently displayed in the map pane. **Organize map** - Organizes the nodes on the map into a Default, Random, Square, or Hexagonal placement. Also available on the Map pane context menu. ##### Other Views Network Analyzer provides access to a wide range of functionality through the use of views. The views are all accessible in the menu **Window > Show View**. For a complete listing of all available Views, select **Window > Show View > Other...**. The following lists some of the most helpful views. The first four are open in the Views area by default. **Radio Info** - The Radio Info View shows data captured for each event, as discussed in [Radio Info View](./viewing-data-in-editors#radio-info-view). **Event Difference** - Event Difference view is a helper view that displays the specific differences between two packets, as discussed in [Event Difference View](./viewing-data-in-editors#event-difference-view). **Connectivity view** - (15.4 captures only) Displays a graph of network connectivity, using the neighbor information from the nodes. **Data capture view** **Adapters** - (deprecated) **Application Controller view** - (deprecated) **Error Log** - Decoder, decryption, and other types of errors are displayed in a tabular format in the Error Log View. Each error is shown in a single row with its summary message, the plugin or component that reported the error, and the date and time the error was encountered. To view detailed information about the error, double-click it. The error will be displayed in an Event Details dialog that includes the date, severity, message, and, if available, stack trace. The navigation at the top of the view allows you to perform basic functions on the Error log itself, including Export, Import, Clear, Delete, Open, and Restore. ![Error Log View](/ss-5-users-guide-tools-network-analyzer/0.7/images/error-log.png) **Expression Manager** - Also known as the [Filter Manager](./viewing-packet-data#filter-manager), this tool is used to compose and edit custom filtering expressions. **Progress** - The Progress View shows the progress of user actions. Actions that take a long time to execute may be managed within the Progress View. For example, the application upload action can take several seconds. The Progress View provides a user interface for managing this action. If you wish to stop an action, you may do so in the Progress View. **Sample Application Wizard** - (deprecated) Other views of interest are: **Event Detail** - Event details are normally shown in the EventDetail Pane within the Stream Editor. If you want to see the event details in a separate window, you can open the Event Detail View. This view shows the details for the currently selected Event in the same format as the Event Detail Pane, but in a view that you can pull outside of Network Analyzer and resize to your liking. **Hex Dump** - Similar to event details, the hex dump information is shown the Hex Dump Pane within the Stream Editor. If you want to see the hex dump in a separate window, you can open the Hex Dump View. This view shows the hex dump of the currently selected Event in the same format as the Hex Dump Pane, but in a view that you can pull outside of Network Analyzer and resize to your liking. **Search** - Search data is displayed in the Search Pane within the Large File Editor. However, as with the Event Details and Hex Dump Panes, you may wish to see this data in a separate view. The Search View allows you to view search results in a window that you can pull outside of Network Analyzer and resize to your liking. **Shell** - The Shell View provides command line access to the scripting capabilities of Network Analyzer. For a list of all commands available within the shell, simply enter `help` at the command line. #### Capturing Data and Managing Sessions Network Analyzer can display one or more network capture sessions. Each capture session displays the transaction and event data captured from one or more nodes. The captured data is shown in editor panes. In general, Network Analyzer captures all incoming and outgoing packet data via the selected adapters, regardless of whether the host nodes have sniffer applications. The captured data includes failed transmissions, as well as debug messages from node applications that are compiled in debug mode. This kind of capture is called a perfect trace session. The capture nodes of a perfect trace session are not sniffers but nodes that might be running your own application that you are trying to debug. The perfect trace session compiles all incoming and outgoing data from each node in chronological real time, providing a richly-layered display of all activity within a network. A perfect trace session can be especially useful for debugging a network in development as it allows you to see every packet on the network. Network Analyzer supports two types of capture sessions: - Live sessions display data as it is captured. The display is continuously refreshed as new data arrives. When a live session starts, it is unnamed and its data is maintained in temporary storage until you save it to a named file. Network Analyzer can capture live session data from multiple sets of adapters into the same session. You cannot, however, capture from one adapter into different sessions at the same time. You can run more than one live session at the same time. - Saved sessions contain captured data that has been saved to permanent storage in a named .isd file. You can load a saved session and analyze it at any time. When you start Network Analyzer, it opens a new live session. Network Analyzer displays each session in an editor with its own tab. The tab of each saved session is labeled with the session's file name; the first live session is labeled **Live**, the second **Live1**, the third **Live2**, and so on. You can capture data from the node of any connected Debug Adapter, from one node at a time or multiple nodes simultaneously. You can also capture all network traffic over the current channel by capturing data from a connected sniffer node. Note: The types of data captured from a node depend primarily on the software protocol running on the node, and also the capabilities of the node's radio chip and Debug Adapter. ##### Starting a Capture Before starting a capture, open **Preferences > Network Analyzer > Decoding > Stack Versions** and make sure that the protocol running on the adapters is selected. If you are working in a multiprotocol environment, select 'Auto-detecting decoder stack'. A change here will not affect any active capture sessions but will apply to the next capture you start. To start a capture: 1. Select one or more connected adapters. Multiple adapters are usually on the same network. 2. Right-click the selected adapters. 3. On the context menu, select **Start Capture**. ![capture menu](/ss-5-users-guide-tools-network-analyzer/0.7/images/start-capture.png) Alternatively, select **File > Other Network Analyzer Actions > New Live Capture Session**. This creates a new live capture session and puts it on top of the editor list. When you start a capture on an adapter, or on multiple adapters at the same time, the live session used for the capture is assigned in one of the following ways: - If no live sessions are currently active, a new live session is created and used. - If live sessions are active, but they are not on top of the editor stack (for example, another file is opened and currently on top), a new live session is created and used. - If a live session is active and it is also on top of the editor stack, then this session will be used for capture. ##### Capturing with Options You can filter packets out of the stream during a capture. For example, you can choose to see only packets from a certain PAN ID and drop all other packets. 1. Select one or more connected adapters. 2. Right-click the selected adapters. 3. On the menu, select **Start capture with options**. 4. Configure options in the resulting dialog, and click **OK**. ![capture options dialog](/ss-5-users-guide-tools-network-analyzer/0.7/images/capture-options.png) In the capture options dialog, you can set the following: - Capture only PANs: (15.4 protocols only) This filter, based on PAN ID, allows a comma-separated list of hexadecimal values. - Aggressive mode: Filters out all events that may not be or definitely are not packets. - Enable advanced energy measurement: This enables AEM packet filtering. AEM packets are used with Energy Profiler. If you turn this option on and later look at the data in Energy Profiler, you will not see any packets. - Enable PC sample data: If selected, captures diagnostic events. - Enable exception sample data: If selected, captures Java framework exceptions, which are used for deep diagnostics of possible Network Analyzer bugs. - Enable debug channel: If selected, enables capturing all other non-packet events. - Silent capture to file: If selected, performs a lengthy capture as a background task. Traffic will not show in the GUI until the capture is stopped and the file is opened. The silent capture enables you to run a capture over several days, as it does not consume memory resources, only disk space. - The start capture options specify the trigger for delayed start of capture. - immediately: No automation, capture starts right away. - after: Capture starts after a certain time or after a certain number of events. - upon: Capture starts upon Node reset, or upon an event containing a specified ASCII or byte pattern. The triggers for starting and stopping capture on node reset work only if you have DEBUG level NORMAL turned on for the node that you are capturing from. With the debug level set to Normal, the chip will send debug information, including node resets, over the back channel to Network Analyzer. Network Analyzer uses these reset and other commands to trigger the start-and-stop capture process. If an image does not have debug turned on, it will not send reset information to Network Analyzer, and Network Analyzer has no basis for triggering start or stop capture. You can also modify some, but not all, capture options through the Live Capture Options toolbar control. ##### Capturing from a Sniffer Node Any adapter's node that connects to Network Analyzer can be designated as a sniffer. A sniffer node is capable of capturing all data that is transmitted among nodes over the designated channel. A sniffer node must have a sniffer application loaded. The sniffer application enables the node to capture over-the-air transmissions between nodes over the designated channel. When you start capturing from a sniffer node, the sniffer node captures all packets that are exchanged by the nodes on the designated channel. If no sniffer application is currently loaded, load one in either of the following ways: - In the Debug Adapters view, right-click the adapter and select **Sniffer Configurator**. - On the Adapters tab, select the adapter. - On the Upload tab, select the target adapter. - On the Apply Configuration tab, apply the appropriate configuration. ![Sniffer dialog](/ss-5-users-guide-tools-network-analyzer/0.7/images/apply-sniffer-configuration.png) - In the Debug Adapters view, right-click the adapter and select **Make Sniffer**. Network Analyzer will first check whether the node has a Sniffer image on it before attempting to upload the new Sniffer image. ##### Stopping a Capture 1. Select one or more connected adapters. 2. Right-click the selected adapter(s). 3. On the context menu, select **Stop Capture**. To resume capture, select **Start Capture**. ##### Pausing a Capture Pause a capture at any time by selecting **Pause** on the Network Analyzer menu or the toolbar. This is a convenient way to stop capturing from a device or devices without having to start a new capture at a later time. Events that occur during the pause are lost, and cannot be retrieved. ##### Clearing Session Events Click **Clear Events** on the Network Analyzer menu or toolbar to purge all events and their associated transactions from the current session. **Caution!** You cannot retrieve cleared events. This is mostly used if you are working on a scenario on an embedded node, where you control some activity through command-line actions. You then simply "Clear" events between each retry, instead of having to do a complete "Start Capture / Stop Capture". Note: Network Analyzer is designed to stay connected and continue capturing, even when the firmware on the target node is uploaded and the node resets. That does not stop the capture session. ##### Saving a Session When you start a capture, it is initially written to an unnamed live session. At any point during a live session, you can save the data thus far captured to a file by selecting File > Save or clicking the toolbar Save control. After you save a session file, Network Analyzer continues to append capture data to it; however, you must save again in order to retain this data in the session file. Network Analyzer saves session data to an .isd file, which is a compressed file that stores session data and the network state. Network state includes display settings such as map modifications, which Network Analyzer restores when you reload the session file. Network Analyzer closes a saved session from further captures after you explicitly stop the capture, or when you start another live session. After a saved session is closed, it cannot be reopened to capture more data. If you modify a saved session file - for example, set bookmarks or reposition icons in the Map pane - Network Analyzer asks whether to save or discard those changes before you close the session. Note: For security reasons, Security Keys that you may use to decrypt captured data are not included in saved .isd files by default. If you wish to share security keys with your files, you should turn on the option "Save decryption keys in Network Analyzer files" on the Security Keys preference page, which you can access by selecting Window > Preferences > Network Analyzer > Decoding > Security Keys ###### Saving Multiple Sessions If multiple open capture sessions have unsaved data, you can save all of them at once by selecting **File > Save All**, or using the toolbar **Save All** control. ###### Exporting to Other File Formats To export a capture session to another file format: 1. Select **File > Network Analyzer Export** or click the toolbar **Network Analyzer Export** control. 2. Select the export format 3. Name the output file. 4. Click **Save**. ###### Extracting Individual Events You can extract specific events from the Transactions pane, Events pane, or Hex Dump pane, and save them into a separate text log file. To extract specific events to a text file: 1. Right-click the event in the Transactions, Events, or Hex Dump panes that you want to extract. 2. On the menu, select **Extract to**. 3. Name the output file with a text extension. 4. Click **Save**. Once you specify a file, you can append additional events to it by right-clicking the event that you want to append and selecting **Append to **. ##### Open and Close Options To open a capture file, select **File > Open Recent File (Network Analyzer trace ...)** or click the toolbar control. To close a single capture session, close the session tab. To close all capture sessions, right-click any session tab and select **Close All**, or select **File > Close All**. To close all but the current capture session, right-click its session tab and select **Close Others**. ##### Replaying a Session (Rarely used) Replay events of the current session, whether live or saved, by selecting **Start Replay** on the Network Analyzer menu or the toolbar. Network Analyzer replays the session from the selected event at a constant speed. Replaying events in a live session has no effect on the capture in progress. Once replay has started, both the toolbar control and the menu selection convert to a **Stop Replay** function. #### Viewing Data in Editors On the File menu, select **Open File (Network Analyzer trace ..)** or **Open Recent File (Network Analyzer trace ...)** to open data in an editor. If the file is smaller than the size set in Preferences > Network Analyzer > Capture File Storage for a file to be considered large, Network Analyzer opens it in the Stream Editor. Otherwise, Network Analyzer opens it in the Large File editor. - **[Stream Editor](#stream-editor)**: The Stream Editor decrypts, decodes, and displays details of individual events. - **[Large File Editor](#large-file-editor)**: The Large File Editor does not offer any detailed decoding and presentation of events. Instead, it provides a high-level overview of a file and allows users to open their points of interest in the Stream Editor. The Stream Editor provides details about individual events. However, in the case of really large captures, this may tax system resources. The Large File Editor shows an overall timeline and node statistics. It allows you to scan very large captures for areas of interest, which you can then open in Stream Editor. ##### Stream Editor ![stream editor showing HA demo](/ss-5-users-guide-tools-network-analyzer/0.7/images/stream-editor.png) The Stream Editor contains five editor panes, each of which provides a different view of the captured session data: - [Map pane](#map-pane): Provides a map of the network, with nodes displayed with their network identifiers. The map also displays network activity. - [Transactions pane](#transactions-pane): Displays high-level node interactions that might comprise multiple events. - [Events pane](#events-pane): Displays information about all packets transmitted and received during a capture session. - [Event Detail pane](#event-detail-pane): Displays the decoded contents of the packet that is currently selected in the Events pane. - [Hex Dump pane](#hex-dump-pane): Displays the data of the selected event in raw bytes. Network Analyzer highlights bytes that map to the data currently selected in the Event Detail pane. All five editor panes may be open at once. Live captured data is continuously updated and displayed in the editor panes. A [Timeline Bar](#timeline-bar) displays the statistics of the traffic over time. Views are presented in a tabbed interface in the lower left of the default Network Analyzer perspective. - [Radio Info View](#radio-info-view): Shows the information from the radio of all the receivers in the network that have heard the currently selected event. - [Event Difference View](#event-difference-view): Displays the differences between two packets. - Connectivity View: (15.4 captures only) Displays a graph of network connectivity, using the neighbor information from the nodes. For more information about using the Stream Editor panes, see the [Editor navigation tools](#editor-navigation-tools). ###### Map Pane The following information is applicable to 15.4 networks only. The Map pane shows all interaction between nodes at a high level. As events occur or are replayed, the Map pane refreshes to show the pattern of network communication. Debug messages issued from a node also display next to the node. ![stream editor map pane](/ss-5-users-guide-tools-network-analyzer/0.7/images/stream-editor-map.png) Each node in the map pane is given a different color depending on its capabilities within the network as they are understood by Network Analyzer based on captured data. - RED: The node is a network coordinator. - BLACK: The node is a router. - GREEN: Default color for network nodes. The following figure shows the graphical elements that appear in the Map pane to depict network activity. Thick lines depict transactions, while thin lines depict single packets. ![stream editor codes in the map pane](/ss-5-users-guide-tools-network-analyzer/0.7/images/stream-editor-map-code.png) Note: The colors shown vary according to the transaction or event type, and can be configured through the [Filter Manager](./viewing-packet-data#filter-manager). The data that is shown for each node is managed through menu/toolbar options: - **Show Short ID** toggles display of the node's 16-bit address that is unique within the personal area network (PAN). - **Show EUI64** toggles display of the node's unique 64-bit IEEE address. - **Show PAN ID** toggles display of the PAN identifier of the node's network. This label can be useful when the map displays multiple networks. - **Show Node Label** displays the custom label that you create for map display only. - **Show LQI** toggles display of link quality data that pertains to the quality of connection between nodes. This is available with perfect trace captures, but not with sniffer captures. - **Show Connectivity** shows the neighbor relationships between nodes in the network. - **Simultaneous Events** displays on the Map pane all events that occurred at the same time as the transaction or event that is currently selected. The currently selected event is in color and any other events display in gray. - **Zoom Map In** and **Zoom Map Out** enlarge and shrink the space that the map uses to display nodes. Zoom options have no effect on the size of node icons. You can move node icons within the Map pane display. This has no effect on network functionality. However, it can help to highlight certain node interactions and relationships. When you move node icons in a session, Network Analyzer asks whether to save those changes before you close the session. Right-click anywhere in the map pane to bring up a context menu. - **Organize Map** establishes the layout of all nodes on a map. You can also modify individual node positions as needed. The following layouts are available: - Default Placement aligns nodes in a linear pattern. - Random Placement scatters the nodes across the map randomly. - Square Grid aligns the nodes in a grid. - Hexagonal Grid aligns the nodes in a hexagonal, offset pattern. - **Load Background Image** and **Clear Background Image** manage the display of a background image in the Map pane. Right-click on a node to bring up a context menu. - **Assign EUI64** lets you assign a EUI64 to a node (not available if Network Analyzer obtains the EUI64). Network Analyzer obtains a node's EUI64 only when that node associates with a network. If the node already belongs to a network when a session begins, its EUI64 is unknown. This option lets you display a known EUI64 for a node; the node's actual EUI64 is unaffected by this label. The Multinetwork checkbox can be used to indicate that the node is operating on multiple networks. See [Multinetwork Considerations](./multinetwork-considerations) for more information. - **Multinetwork** toggles the multinetwork property. See [Multinetwork Considerations](./multinetwork-considerations) for more information. - **Label** lets you customize the node's adapter (device) label with any string up to 25 characters long. This string appears in brackets after the node's device name. (By default, the Map pane labels each node that is undergoing capture with its device name.) You can also make the labels time-dependent by entering a start time. This lets you supply multiple names for the same node. This can be useful while debugging applications, by indicating the node's current state. - **Icon** and **More Icons** allow you to display the node as an icon. ###### Transactions Pane The Transactions Pane displays higher-layer protocol events that consist of multiple packet transmissions. For example, a Zigbee broadcast is retransmitted by every node in the network. By analyzing packet headers, Network Analyzer determines which packets belong to the same transaction and groups them accordingly. ![stream editor transactions pane](/ss-5-users-guide-tools-network-analyzer/0.7/images/stream-editor-transactions.png) Typical 15.4 transactions include: - **802.15.4 association**: Involves a request-response protocol that consists of at least 6 packet transmissions. - **APS unicast**: Can contain the following events: - A MAC layer unicast packet and its MAC retries - Acknowledgements for each hop along the route - An end-to-end APS acknowledgement message, which itself consists of multiple MAC unicast packets - Multiple end-to-end APS retries - **Zigbee route discovery**: Involves a broadcast route request followed by unicast route-reply packets across multiple hops. In the case of Bluetooth Low Energy (and Bluetooth mesh), a “transaction” refers to an actual Bluetooth Low Energy transaction as defined in the core specification. This corresponds most of the time to a Bluetooth Low Energy procedure. Equally, the event pane displays the actual Bluetooth Low Energy events corresponding to the transaction or procedure. For more details, refer to the Bluetooth Core specification document. Network Analyzer understands the protocol semantics for many transaction types. Therefore it can group multiple packets in real time to facilitate high-level analysis. All transactions are listed in chronological order, using transaction start times. Each selection maps to one or more events in the Events Pane, which are marked accordingly. Clock icons indicate concurrent transactions with the current selection. All transactions and their events are uniquely numbered. However, the transaction numbers may not be in sequence, and various factors will result in number gaps. For example, only top-level transactions and the lowest-level packets are shown. Intermediate transactions are not shown. Also, number gaps are likely to occur if filters are turned on. When you click on a transaction, the information shown in the Event Detail Pane and the Hex Dump Pane corresponds to the first packet in the transaction. However, if filters are turned on, the first transaction might not be shown in the Event Pane. In that case, the event detail information in the transaction display will not be consistent with the first packet shown in the Event Pane. In fact, with a filter expression such as `show(transaction.summary != null, SELF)` only transactions are displayed and the Event Pane will be blank. In that case, click the transaction to see the first events in the transaction in the Event Detail and Hex Dump Panes. ###### Events Pane The Events pane displays information about packets received by the current session. All events are displayed in chronological order. ![serial editor events pane](/ss-5-users-guide-tools-network-analyzer/0.7/images/stream-editor-events.png) Events that belong to the currently selected transaction in the [Transactions pane](#transactions-pane) are marked by one of the following icons: ![transaction icons](/ss-5-users-guide-tools-network-analyzer/0.7/images/stream-editor-transaction-codes.png) Clock icons mark unrelated events that are concurrent with the selected transaction in the Transactions pane. ###### Event Detail Pane The Event Detail pane displays the decoded contents of the event that is currently selected in the [Events pane](#events-pane). The content of this pane varies according to the event type. If a transaction is selected on the [Transactions pane](#transactions-pane), the Event Detail pane shows the details of the first event in the transaction. Pane options include: - **Expand Bitfield**: Shows the bitfields in an expanded mode, like Wireshark. - **Use Fixed Fonts**: Can improve readability as information is presented aligned. When capturing from multiple devices, Network Analyzer may capture the same packet as heard by several different sources. In order to reduce confusion, Network Analyzer automatically performs duplicate detection on all packets captured. If the transmission is captured over the backchannel, only the transmitted packet is kept. Otherwise the first receive packet is kept. All duplicate packets are dropped after extracting their RadioInfo data. Only the radio info frame for each duplicate packet is kept. The radio info for each individual instance of a packet captured by Network Analyzer is visible in the [Radio Info View](#radio-info-view) ![Event detail pane in the stream editor](/ss-5-users-guide-tools-network-analyzer/0.7/images/stream-editor-event-detail.png) **Pinning a field**: The Event Detail pane has the ability to "pin" a field into view. When you double-click on a specific field, the Pin icon in the top left of the pane turns bright red, indicating that it is active. Now, as you move through events, this field is always visible when it is present in the currently selected packet. This is useful if you are interested in a specific field across multiple events in a trace file. In the above figure, the Zigbee Application Support Delivery Mode is "pinned" into view. The pin can be deactivated at any time by either double-clicking on the pinned field, or by clicking the Pin icon itself. ###### Hex Dump Pane The Hex Dump pane displays data in raw bytes of a selected event in the [Events pane](#events-pane). Clicking on bytes in the Hex Dump pane selects the corresponding field in the [Event Detail pane](#event-detail-pane). Alternatively, selecting a field or a frame in the Event Detail pane highlights the corresponding bytes in the Hex Dump pane. The pane shows multiple "layers", so if the packet is decrypted, the "raw" layer shows encrypted data, but the higher-level layers show this data progressively decrypted. ![Stream editor hex dump pane](/ss-5-users-guide-tools-network-analyzer/0.7/images/stream-editor-hex-dump.png) ###### Timeline Bar The Timeline bar displays the statistics of the traffic over time. The Timeline bar function on the Network Analyzer toolbar toggles the Timeline Bar on and off. ![Stream editor timeline bar](/ss-5-users-guide-tools-network-analyzer/0.7/images/stream-editor-timeline-bar.png) Available actions are: - Click on the Timeline bar to move the cursor to the event closest to the time selected. - Click and drag on the Timeline bar to filter the display to only the time within the selected area. - Right-click to display a timeline menu. The Timeline bar shows bookmarks as yellow flags. You can click a bookmark to jump to it in the Transaction and Event panes. It shows red flags for errors, such as out-of-sequence problems. ###### Radio Info View The Radio Info view is a helper view that shows the information from the radio of all the receivers in the network that have heard the currently selected event. It is available through the tabbed Views interface in the lower left of the default Network Analyzer perspective. If not, add it through **Window > Show View**. The view displays in a tree all the information that has been gathered from the receiver nodes. Displayed information includes LQI value, CRC value, and the status bits that show several states of the radio. ![Stream Editor radio info view](/ss-5-users-guide-tools-network-analyzer/0.7/images/stream-editor-radio-info.png) The event that supplied radio information in the figure above was captured from both the sending and receiving nodes. This is possible because the trace that contains this event was created by capturing from both the sending and receiving nodes simultaneously using Network Analyzer's Perfect Trace capability. While the original events were merged into a single event by Network Analyzer's duplicate detection mechanism, the radio information was retained for each event and is shown in the Radio Info view with the time that the event was captured by Network Analyzer. ###### Event Difference View Event Difference view is a helper view that displays the specific differences between two packets. It is available through the tabbed Views interface in the lower left of the default Network Analyzer perspective. If not, add it through **Window > Show View**. ![Stream Editor Event Difference View](/ss-5-users-guide-tools-network-analyzer/0.7/images/stream-editor-event-diff.png) Once the view is shown, it tracks the selected events. The view will by default show the difference between the last two events selected. If you select event 1, and then click on event 2, the view shows the difference between those two events. If later you select event 3, the view shows the differences between event 2 and 3. Packet frames that do not have any differences are shown in green. Frames that contain differences are shown in red. Expand the frame to see which portions of the frames are different. The menu at the top of the view supports additional functions. ![Stream editor event difference view icons](/ss-5-users-guide-tools-network-analyzer/0.7/images/stream-editor-event-diff-icons.png) - **Show traffic counts**: Opens a window showing the statistics for the events between, but not including, the two selected event. - **Show byte differences**: Enables viewing of individual bytes in the view. - **Pin last selected event**: Changes the way events are tracked. If this is enabled, then the first event for diffing stays the same, and only the second event changes. You can use this if you wish to always differentiate events against a certain static event, rather than always viewing last two selected events. - **Include fields that are same**: Enables filtering out fields that are same in both events. ###### Editor Navigation Tools Some of the Network Analyzer Toolbar functions are specific to working in the Stream Editor. ![stream editor navigation toolbar options](/ss-5-users-guide-tools-network-analyzer/0.7/images/stream-editor-toolbar-options.png) - **Edit description of trace file**: Opens a simple dialog which allows you to view and edit overall description of the captured data. This is helpful if you need to pass on some information others for analyzing the contents of the trace file. - **Go to Line**: Moves the cursor to the event or transaction having the specified event number. This is only enabled if the Stream preference "Show event numbers" is selected. To turn this feature on go to: Window > Preferences > Network Analyzer > Capture Configuration > Show event numbers. - **Go to Time**: Moves the cursor to the transaction and event that match or immediately follow the specified time. - **Go to Bookmark**: Moves the cursor to the selected bookmark. Assign bookmarks to events or transactions by right-clicking the event or transaction and selecting **Add Bookmark**. - **Lock to Bottom**: Locks the cursor on the latest event during a live session. To remove the lock, select any event or transaction during a live session, which causes a view to scroll as the events are captured. ##### Large File Editor If the file is larger than the size set in Preferences > Network Analyzer > Capture File Storage, Network Analyzer opens it in the Large File editor. The Large File Editor allows you to find and select a region of interest, which you can then open and analyze with the Stream Editor. ![large file editor](/ss-5-users-guide-tools-network-analyzer/0.7/images/large-file-editor.png) The Large File Editor consists of three component panes: - [Large File Timeline](#large-file-timeline): Shows a high-level view of a large file's traffic over time. - [Large File Search pane](#large-file-search): Provides a mechanism for searching across very large files. - [Large File Network Nodes pane](#large-file-network-nodes): Shows all of the network devices included in a large file. ###### Large File Timeline The Large File Timeline shows a high-level view of a large file's traffic over time. It works similarly to the [Stream Editor's](#stream-editor) timeline. In fact, the Large File and the Stream Editor timelines use the same widget. **Large File Timeline Segments**: The entire set of events shown in the Large File Timeline is broken into segments. By default, each segment includes up to 5,000 events. Segments boundaries are shown in the Large File Timeline by horizontal grey lines. **Large File Timeline Time Markers**: The Large File Timeline shows the actual time during which a file was captured. The capture start-time appears in the bottom left corner of the Timeline. The capture end-time appears in the bottom right corner. Moving the cursor to any point on the timeline displays the time for that point. **Large File Intervals**: A Large File Interval is a subset of an entire trace. You can create an interval by clicking and dragging. Click on the Large File Timeline at the desired start-point, and then drag the cursor along the timeline to the desired end-point. The click and drag operation creates the interval you defined, and zooms the timeline view into that interval. To clear the interval, click the Clear Selection button in the toolbar under the timeline, or right-click on the timeline and select **Clear interval**. Once you have created an interval, you can open that interval in the Stream Editor by clicking the Open Interval button, or right-clicking in the timeline and selecting **Open Interval**. **Timeline Flags**: Search results and errors are displayed in the Large File Timeline by flags. Search results are displayed as a yellow flag. Errors are displayed as a red flag. When you move the mouse over the flag, the Timeline displays the Summary of the Event or Transaction that is associated with the flag. ###### Large File Search Use the Large File Search mechanism to search for events across very large files. The entire filter language is supported in the Large File Search. For more information, see [Filter Language](./viewing-packet-data#filter-language). To run a search in the Large File Editor, enter the filter expression into the Filter Expression text box and click the Start Search control. The search progress is shown in the Large File Timeline. Options allow you to limit the search within a time interval or to limit the number of search results. It is useful to limit the number of search results, as the system can become slow if the search expression matches an extremely large number of events. Filter results are shown in the Search Results table. Search results are grouped into results trees and labeled with the time and date that the search was performed. To view search result details, double-click an individual search result. This opens three segments in a Stream Editor: one before the selected event, one that contains the event, and one after the event. Note: The expressions and search results are saved into the Network Analyzer file. Thus they will be seen by other users who open the same Network Analyzer file. Controls to the right of the search results allow you to delete, tag, open, and assign decorative icons to the searches and search results. ###### Large File Network Nodes The Large File Network Node pane shows all of the network devices included in a large file. The information provided about each node in a trace includes: - EUI64 address - Short address - PAN ID - Node type Since each of these values is subject to change over time, the summary also includes the time at which each value was discovered. #### Filtering Captured Data By default, the Events pane displays all session events. You can build and apply filters that constrain Network Analyzer to show only events that are of interest. By filtering events, you can analyze results more efficiently. Each capture session has its own filter settings. A filter can be used either to search for the next matching event or to display only the events that match the filter. In the latter mode, when you change a session's filters, Network Analyzer immediately refreshes the display. When you exit Network Analyzer, all session filters are cleared and must be reapplied when you restart. Network Analyzer provides two ways to edit filters: - [Filter Manager](#filter-manager): Maintains a set of saved filters that you can review and edit. You can also add new filters. You specify any of the saved filters for display on the Filters menu, accessed through the **n saved filters** button on the filter bar, so that they are available for use in one or more sessions. - [Filter Bar](#filter-bar): An editor that attaches to a given session, where you can enter one or more filter expressions on the fly. Network Analyzer discards filter bar expressions for all sessions when it exits. [Quick filters](#quick-filters) are available when you right-click on events and transactions. They provide an easy way to create common expressions for the filter bar. [Filter Language](#filter-language) is a powerful syntax used to create filters. ##### Filter Manager The Filter Manager lets you: - Use filter expressions to customize display of entries in the Events pane. - Specify which filters appear in the Filters menu. The Filter Manager is available through menu and toolbar selections as well as through Window > Show View (as Expression Manager). ![Expression Manager](/ss-5-users-guide-tools-network-analyzer/0.7/images/expression-filter-manager.png) An older feature, the Expression Builder, is deprecated. ###### Maintaining Filters To add a filter to the Filters menu, check the Menu checkbox. This makes the filter available to the current sessions. To restore filters to installation settings, click **Reset**. To rename a filter, click on the name field and edit. You can also create new, delete, export and import filters. ###### Setting Filter Color Schemes You can associate a color scheme with each filter. If an event evaluates as true for a given filter expression, Network Analyzer applies the filter's color scheme to that event. An event can be configured with a color scheme for two display levels: - For the Map pane, the color used by the graphic representing the event type. - For the Events pane, the foreground and background colors used by event type instances. Note: Setting a color scheme on a filter expression does not specify whether to display events; it only determines how to display certain event types. Note: If a filter's foreground color is the same as its background color you will not be able to read the text in the event and it will effectively disappear from view. To set a filter color scheme, in the Filter Manager: 1. Next to the filter of interest, check the Color checkbox to enable the controls for Map (Map color), and Fg (Foreground color) and Bg (background color) for event instances. 2. Click the control you want to set to enable the color selector control. 3. Click the color selector control, set the filter's color, and click **OK**. If you have changed Foreground or Background colors you will see the change on the Name field. 4. For each filter, set the color scheme's Priority level by assigning a positive or negative integer value. If an event evaluates as true for multiple filters, Network Analyzer uses the color scheme with the highest precedence. In the case where there is no clear precedence, Network Analyzer randomly chooses one of the matching color schemes. 5. To refresh the Map pane and Events pane with the new color scheme, click **Reapply**. A filter whose menu checkbox is selected is shown in the Filters menu. The order in which the filters are displayed in the Filters menu is determined by their order in the filter manager table. ##### Filter Bar A session's Filter Bar provides the same level of functionality as the Filter Manager for building expressions. Any filter expression that appears in a session's Filter Bar is combined with the saved filter expressions that are already in effect for that session. ![Filter Bar](/ss-5-users-guide-tools-network-analyzer/0.7/images/filter-bar.png) The Filter bar is displayed by default, but can be toggled on and off using the **Show Filter Bar** menu control. You can compose a Filter Bar expression in the following ways: 1. Enter the expression directly in the filter edit field, and press Enter. 2. Create a Quick filter. To apply a Filter Bar filter, enter an expression into the filter edit field and press Enter. To find an event that matches the filter, click the Find icons on the Filter Bar. To remove a filter, select it and press Enter. Note: A history of filter expressions is maintained in the drop-down list. ##### Quick Filters Network Analyzer provides several filters that are available from the Transactions pane, Events pane, Event Detail pane, and Hex Dump pane. To access a quick filter, right-click an item and choose a quick filter pop-up menu option. ###### Hide or Show Events/Transactions Access these filters by right-clicking an event (Events pane) or transaction (Transactions pane) and selecting a pop-up menu option to hide or show specific information. The filter options that are available depend on the selected transaction or event. You can specify to hide all events/transactions of the selected type, or to show only that type. In addition if you select an event of type APITrace, the pop-up menu displays two filter options: - Hide type: APITrace - Show only type: APITrace Further, if you select an event such as a neighbor exchange that has a source and/or destination address, the pop-up menu also contains these two filter options: - Show only destination: short-ID - Show only source: short-ID In all cases, Network Analyzer enters the corresponding filter expression in the session's Filter Bar. This can help you to understand the filter language. For example, if you specify to show only route discovery transactions, this expression is set in the filter bar: `isType(Route)` ###### Frame Byte Pattern Filtering A frame pattern filter matches a specific byte-array pattern. For example, you could filter for packets in a payload whose frame has the third byte equal to 0x33. (Many more complex combinations are possible.) To create a frame pattern filter: 1. Right-click a frame in the Event Detail pane or Hex Dump pane. 2. Select Filter by frame pattern from the pop-up menu. 3. In the Byte Pattern dialog, check the byte pattern match desired and click OK. The filter is added to the Filter Bar for this session. ![Byte Pattern](/ss-5-users-guide-tools-network-analyzer/0.7/images/frame-pattern.png) ##### Filter Language Filter language enables you to construct logical expressions, based on decoded fields in events. The following are some examples: - `fifteenFour.sequence == 0x52`: Matches events where 15.4 sequence number equals hex 0x52. - `fifteenFour.ackRequired == true && fifteenFour.source == 0x035f`: Matches events where 15.4 ack required flag is set, and source shortId is 0x035f. - `isPresent(zigbeeSecurity.frameCounter)`: Matches events that contain the Zigbee security frame, and the frameCounter field within it. - `event.summary | "string"`: Matches events where a string is a substring of the summary. - `isType(Packet)`: Matches events that are packets. - `frameMatch(fifteenFour,"**88**EF/**********")`: Matches events where 15.4 frame contains second byte equal to 0x88 and fourth byte equal to 0xEF. A good way to learn the filter language is by first using the **Add to filter** context menu option in the Event Detail Pane. This option will add a filter expression for the chosen field. You can use most standard logical operators (&&, ||) and standard comparison operators ( ==, !=, |, <, >, <=, >=, etc.) in filter expressions. ###### Event and Transaction Filter Extensions In addition to filtering on decoded packet fields, you can filter on several other Event and Transaction values. ###### Event Extensions: (heading level 7) - event.summary: A String value of the summary shown in the Event Pane. - Example: event.summary == "APS Ack" - event.linkStatus: True if the packet is a Link Status packet. - Example: event.linkStatus == true - event.ack: True if the packet is an 802.15.4 ack. - Example: event.ack == true - event.time: The time that the event was transmitted (tx) or received (rx). - Example: event.time >= 75.78 - event.originator: The adapter that saw and reported the event. - Example: event.originator == "ewb-unit04" - event.status: The event status, listed in the righthand column of the event status window - Example: event.status == "ZCL: ReportEventStatus" - event.type: The type of event, shown in the Type column of the Event and Transaction Panes. - Example: event.type == "Packet" - event.corrupt: The event corruption string, empty if event is not corrupt - Example: event.corrupt < "crypt" ###### Transaction Extensions: (heading level 7) - transaction.summary: Filters on the transaction summary field shown in the Summary column of the Transaction Pane. - Example: transaction.summary == "ZCL: LoadControlEvent" - transaction.packetCount: Filters on the number of packets in the transaction shown in the P# column of the Transaction Pane - Example: transaction.packetCount == 4 - transaction.macRetries: Filters on the number of MAC retries in the transaction shown in the M# column in the Transaction Pane. - Example: transaction.macRetries == 2 - transaction.endToEndRetries: Filters on the number of end to end retries shown in the E# column in the Transaction Pane. - Example: transaction.endToEndRetries == 3 - transaction.status: Filters on the status of the transaction shown in the Status column of the Transaction Pane. - Example: transaction.status == "CRC failed" - transaction.dest: Filters on the network destination of the transaction shown in the NWK Dest column of the Transaction Pane. - Example: transaction.dest == 0x05c7 - transaction.source: Filters on the network source of the transaction shown in the NWK Src column of the Transaction Pane. - Example: transaction.source == 0x0000 ###### How Network Analyzer Applies a Filter When Network Analyzer captures an over-the-air message, it runs the message through a processing stream. The processing stream is made up primarily of Decoders and Groupers. **Decoders:** Decoders are responsible for making sense of the message based on its format so that it may be displayed to the user. Each over-the-air message captured becomes a single Event of type Packet. This Event is displayed to the user in the Event view. **Groupers:** The groupers are responsible for making sense of a series of packets and grouping them into a hierarchy under a single Transaction. The Transaction is displayed in the Transaction view. ###### Using `show(expression, SELF|PARENT|CHILD|SIBLING)` (heading level 7) Events exist within a hierarchical structure where Transactions represent the top of the hierarchy and Events are at the bottom. The hierarchical nature of trace data creates something of a problem for filtering. In most cases, you wish to see Transactions associated with filter-matching Events, and vice versa. For instance, if you use a filter like: "transaction.summary == Association", you probably do not want to see only the transactions in the Transaction Pane. You probably also want to see the events contained within the Association displayed in the Event Pane. You can solve this problem by using the optional `show(expr, args)` syntax in your filters. The show syntax allows you to explicitly indicate the conditions under which an event or transaction should match your filter. The arguments for the show syntax are as follows: **SELF** - The Event or Transaction matches if it contains data that matches the expression provided. **PARENT** - A Transaction should be shown if any one of its child Events matches the filter. **CHILD** - An Event should be shown if the Transaction to which it belongs matches the filter. **SIBLING** - An Event matches if its PARENT transaction contains another Event which itself matches the filter. **Filter display defaults**: Filter expressions that do not explicitly contain the optional `show(expr, args)` syntax are implemented as though they contain one of two default syntaxes. Which default syntax is used depends on where the filter is executed, in the Stream Editor or in the Large File Editor. - Stream Editor default: `show(expression, SELF|PARENT|CHILD)` By default, filter expressions that do not explicitly contain the show(expr, args) syntax are implemented as though they were wrapped in the following syntax: `show(expression, SELF|PARENT|CHILD)` The SELF|PARENT|CHILD arguments provide what Silicon Labs believes a user expects to see when a filter is run in the Stream Editor. The filter display includes the events and transactions that match the filter itself. If an Event matches the filter, you also see an associated Transaction (PARENT) regardless of whether that Transaction matches the filter. Likewise, if a Transaction matches the filter, you also see its associated Events (CHILD) regardless of whether those Events match the filter. - Large File Editor default: `show(expression, SELF)` By default, the search mechanism in the Large File Editor returns only those Events and Transactions which themselves match the filter expression provided. This behavior makes it very easy to run a filter to search for all the Transactions with a given summary without having the search results bogged down with hits for their associated Events. ###### Expression Validation (heading level 7) **Lexical validation** - When you enter a filter expression, the filter engine validates whether the expression is lexically correct. If an expression is not lexically correct, Network Analyzer gives you an error message with a suggestion about where there may be a problem in the expression. **Event Key validation** - When you enter a lexically correct expression, Network Analyzer also runs an event key validation. It checks that any identifier provided represents a real entity within an Event or Transaction. If the filter engine is not able to find any associated data for an event key within the expression, Network Analyzer will warn you that you are using an unverified identifier. For example, in the expression `fifteenFour.dest == 0xffff` fifteenFour.dest is a verifiable event key in that Network Analyzer knows that it represents real data in an event. Here are two examples to illustrate the validation of expressions in Network Analyzer. Consider this expression: `foo == bar` The filter mechanism has no way of knowing what foo and bar represent, or that they even represent any type of data within an Event or Transaction. While this expression is lexically correct, Network Analyzer will warn the user that foo and bar could not be verified, and that the expression may provide unexpected results. In fact, this expression will not show anything, since foo may very well equal bar, but the filter engine has no way of knowing that. Consider also this expression: `foo == foo` This expression also displays a warning. However, when run, it will return ALL events, because while Network Analyzer does not know what foo is, it knows it definitely equals foo. **Special identifiers** - Several special identifiers are not mapped to an event key. - payload.xxx, which evaluates into the payload bytes for a given layer xxx, for example payload.raw or payload.tcp_stream. You can form expressions like `payload.raw == {001122aabbcc}` to match payloads - flag.xxx, which evaluates into the value of the event flag for a given event, for example: `flag.neighbor_exchange` or `flag.fragment`. #### Multinetwork Considerations If your application uses nodes operating on multiple networks, this information can be reflected when reviewing capture sessions. Currently, however, Network Analyzer cannot auto-detect multinetwork nodes. At the onset, unless all traditional, conceptual nodes constituting the multinetwork node are assigned EUI64s, each conceptual node shows up as a separate node in the Map editor pane. Each such node must be assigned the same EUI64 by right-clicking on the node in the Map editor pane and selecting **Assign EUI64…** A dialog pops up that facilitates the assignment, and the **Multinetwork EUI64** checkbox must be checked to inform Network Analyzer that the node is indeed a multinetwork node. This sequence is illustrated in the following figure. ![net anal multinetwork](/ss-5-users-guide-tools-network-analyzer/0.7/images/net-anal-multinetwork.png) Once all the constituent conceptual nodes have been assigned the same EUI64, Network Analyzer coalesces them into one node in the Map editor pane. Alternatively, if the all the conceptual nodes know the EUI64 or all have been coalesced but Network Analyzer has not been informed that the node is multinetwork, the **Multinetwork node** menu item in the figure above can be toggled. Once a node is known to Network Analyzer to be multinetwork, it is indicated as such by being colored magenta in the Map editor pane. #### Custom decoders Network Analyzer provides functionality to create custom decoders. This section provides instructions on how to use Lua, a language embedded inside Network Analyzer, to develop custom payload decoders for Simplicity Studio. ##### Procedure There are five main steps to leverage this functionality. ###### Step 1: Writing a decoder All Lua decoders must implement the following six functions. - **name():** Returns a string that will be used as the name of your decoder. - **filterName():** Returns a string that will serve as the filterName that can be used to filter the packets decoded by this decoder later on. - **description():** Returns a string that will act as the description of the frame in Network Analyzer. - **enabled():** Returns a boolean value that corresponds to whether the decoder should be active by default when first loaded/when defaults are reapplied. - **accept(event, packet):** Decides which packets your decoder is interested in. It has two objects, of type [Event](#event-object-api) and [Packet](#packet-object-api). The packet object can be used to figure out the raw bytes of the entire packet or just the bytes of the payload. The event object can be used to identify and read information from prior frames via `get()` and `contain()` functions. - **decode(event, fieldContext, formatter):** Handles the actual decoding. It has two objects, of type [Event](#event-object-api) and [FieldContext](#fieldcontext-object-api). The decode process functions by using the `append()`` and `decode()`` functions to create and register different fields of interest. The **formatter** field is optional and is used for formatting the fields of your decoder. More detailed decoder examples can be found under [Example Decoders](#example-decoders). ###### Step 2: Loading into Simplicity Studio After the decoder is ready to be tested, load it into Simplicity Studio. 1. Open Simplicity Studio 2. Go to **Window -> Preferences -> Network Analyzer -> Decoding** 3. Click **Add**, select the LUA file that corresponds to our decoder, and then click **Open**. You should now see the decoder under the table of Decoders. ###### Step 3: Editing the Decoder Once the decoder is loaded, you can now edit it in Simplicity Studio. Click **Edit** under the decoding screen to open a text editor where you can modify the file. Note that if you save your decoder while there are syntax errors, then you may need to re-add your decoder. ###### Step 4: Testing the Decoder Once the decoder is loaded into Studio, you can test it against specific packets by doing the following: 1. From the **Decoding** page, click decoder in the table of custom decoders. 2. Click **Test**. 3. Set the desired options (for example, Input Format or Payload vs. Full Over The Air) 4. Enter the raw payload or over-the-air packet bytes in the input textbox. NOTE: The OUT box does not work and will be fixed in a future release. You see how this works by looking at the example decoders and trying the example packets that are listed. You can also have additional inline debug information printed to screen with print() statements within the decoder. ###### Step 5: Use with Network Captures If the decoder is enabled (as indicated by the checkbox next to its entry in the **Preference -> Decoding** page), then you can decode messages using this decoder in Network Analyzer. Note: To have logging during longer network captures, go to **Preference -> Decoding** and check **Enable Debug Logging**. This will write to file any calls to the following function: ```lua log("message") ``` See [Example decoders](#example-decoders) to see how this is done. ##### Field Formatters You can enhance the decoded information by implementing custom field formatters. Currently, Network Analyzer supports user-written functions that take in an integer and outputs a string that can be used as a description. Note that these formatters can sometimes get in null information, so these functions should be able to deal with null. Example of a formatter: ```lua function decoder.versionName(version) local versions = { [0] = "Version 1", [1] = "Version 2", [2] = "Version 3", [3] = "Version 4", } return versions[version] or "Unknown version" end ``` In order to use this functionality, include the following line at the top of your custom decoder: ```lua decoder.fieldFormatters = { "versionName" } ``` Each of the strings within this array should correspond to the names of the function that you are using as a formatter. To use these formatters in your decoder, add a third argument to the decode functions that corresponds to a map of formatters that are indexed by the strings given in fieldFormatter. For example, in function decode(event, fieldcontext, formatter), formatter is a map, indexed by function name, that corresponds to the formatter. Once this is done, you can use a formatter by adding a third argument to many of fieldContext's append and decode functions. ```lua fc.append("versionName", 1, formatter["versionName"]); ``` See [Example decoders](#example-decoders) to see how this is done. The list of currently supported append/decode functions that allow for a field formatter is provided in the next sections. ###### Event Object API **`void setStderr(final String err)`** - Sets the stderr of the decoder. - **Parameters:** `err` — **`void setStdout(final String out)`** - Sets the stdout of the decoder. - **Parameters:** `out` — **`Object get(final String eventKey, final String subkey)`** - Wrapper function to access the value associated in the decorated map. Mainly for use with custom user payload decoders. - **Parameters:** - `EventKey` — A string that must corresponds to the name of a specific frame. See EventKey Documentation. - `Subkey` — A string that corresponds to field names. See FieldContext API to see how to generate these fields. - **Returns:** Object Null if it does not exist. **`int getInt(final String eventKey, final String subkey)`** - Wrapper function to access the value associated in the decorated map. Mainly for use with custom user payload decoders. - **Parameters:** - `EventKey` — A string that must corresponds to the name of a specific frame. See EventKey Documentation. - `Subkey` — A string that corresponds to field names. See FieldContext API to see how to generate these fields. - **Returns:** int Null if it does not exist. **`boolean getBoolean(final String eventKey, final String subkey)`** - Wrapper function to access the value associated in the decorated map. Mainly for use w/ custom user payload decoders. - **Parameters:** - `EventKey` — A string that must corresponds to the name of a specific frame. See EventKey Documentation. - `Subkey` — A string that corresponds to field names. See FieldContext API to see how to generate these fields. - **Returns:** boolean Null if it does not exist. **`boolean containsSubkey(final String eventKey, final String subkey`** - Wrapper function so that users can figure out if a frame/subkey combination is known by the decorated map. - **Parameters:** - `EventKey` — A string that must corresponds to the name of a specific frame. See EventKey Documentation. - `Subkey` — A string that corresponds to field names. See FieldContext API to see how to generate these fields. - **Returns:** boolean True if the subkey's corresponding field is found under the frame given by EventKey **`boolean containsKey(final String eventKey)`** - Wrapper function so that users can figure out if an frame/eventKey is known by the the event. - **Parameters:** `Subkey` — A string that corresponds to field names. See FieldContext API to see how to generate these fields. - **Returns:** boolean True if the event encountered or recognizes the event key in question, false otherwise. ###### Packet Object API **`byte[] currentLayerBytes()`** - Returns raw byte array. Decryptors need this. **`int currentOffset()`** - Returns the current offset where the decoders need to pick up. **`void setSummary(final String summary)`** - Sets the summary string. - **Parameters:** `summary` — **`String summary()`** - Returns the packet summary string. **`void setCorruption(final String message)`** - Backwards compatibility. JC interface needs this. - **Parameters:** `message` — **`void skip(final int skipBytes)`** - Skips bytes. Remove after packet decoders are cleaned up. **`void setEndOffset(final int end)`** - **Parameters:** `end` — **`void setOffset(final int offset)`** - **Parameters:** `offset` — **`int micCount()`** - Returns number of all mics **`int endOffset()`** - Returns the end of "over the air" packet. - **Returns:** end of over the air packet **`int flagBits()`** **`void setFlagBits(final int bits)`** - **Parameters:** `bits` — **`boolean isFragment()`** - Returns true if this packet is a fragment. - **Parameters:** `` — - **Returns:** boolean ###### FieldContext Object API **`void append(String name, int length)`** - Appends the number of bytes as a field. This method is more efficient than decode, so if you do not need the value of the field, use this. Example Input and Output: 0x01234567 -> 0x01234567 - **Parameters:** - `name` — The name of the field that is to be registered. - `length` — An integer number of bytes to read from the payload and save as name. **`void appendBytes(String name, int length)`** - Appends the number of bytes as given by length as a byte field. This method is more efficient than decode, so if you do not needs the value of the field, use this. Example Input and Output: 0x01234567 -> 01 23 45 67 - **Parameters:** - `name` — The name of the field that is to be registered. - `length` — An integer number of bytes to read from the payload and save as name. `void appendEui64(String name)` - Appends the next 8 bytes as the EUID of the sender. This method is more efficient than decode, so if you do not needs the value of the field, use this. The format will be Little Endian here. Example Input and Output: 0x89ABCDEF01234567 -> 67452301EFCAB89 - **Parameters:** `name` — The name of the field that is to be registered. **`void appendFloat(String name, int length)`** - Appends the field as a float. This method is more efficient than decode, so if you do not needs the value of the field, use this. Example Input and Output: 0x00000001x -> 1.4 E-45 - **Parameters:** - `name` — The name of the field that is to be registered. - `length` — An integer number of bytes to read from the payload and save as name. **`void appendFloatLE(String name, int length)`** - Appends the field as a float in little endian order. This method is more efficient than decode, so if you do not needs the value of the field, use this. Example Input and Output: - **Parameters:** - `name` — The name of the field that is to be registered. - `length` — An integer number of bytes to read from the payload and save as name. 0x01000001x -> 1.4 E-45 **`void appendRemainingBytesLE(String name)`** - Appends the remaining bytes in the packet in little endian order. This method is more efficient than decode, so if you do not needs the value of the field, use this. - **Parameters:** `name` — The name that will be used to refer to the field containing the remaining bytes **`int decode(String name, int length)`** - Decodes the field as an int and returns value. - **Parameters:** - `name` — The name of the field that is to be registered. - `length` — An integer number of bytes to read from the payload and save as name. - **Returns:** int The value that was decoded from the payload and copied into the field called name. **`int decodeLE(String name, int length)`** - Decodes the field as an int in little endian format and returns value. - **Parameters:** - `name` — The name of the field that is to be registered. - `length` — An integer number of bytes to read from the payload and save as name. - **Returns:** int The value that was decoded from the payload and copied into the field called name. **`String decodeString(String name, int length)`** - Decodes length bytes as a string. Example Output: 0x68656c6c6f20776f726c64 -> 'hello world' - **Parameters:** - `name` — The name of the field the string will be registered as. - `length` — The number of bytes to be decoded as a string. **`void appendStringWithLength(String name)`** - Appends a string that first contains a length byte and then the remainder as bytes. - **Returns:** String **`boolean decodeBit(String name)`** - Decodes and returns the value of the next bit in the payload. - **Parameters:** `name` — The name of the field that is to be registered. - **Returns:** boolean The value of the decoded bit. **`int decodeBits(String name, int numOfBits)`** - Decodes bits as field name. Identical to bits(name.name(), numOfBits); - **Parameters:** - `name` — The name of the field that is to be registered. - `numOfBits` — The number of bits that are to be decoded jointly. - **Returns:** int The value of the decoded bits as an integer. **`void bit(String name)`** - This method heavily depends on the last field being decoded. So it's meaningful to be used kinda only in context of last field. You would do this: fc.decode(flags); fc.bit(flag1); fc.bit(flag2); fc.bit(flag3); As each field take length from flags and does internal bitshifting to calculate masks of flag1 flag2. - **Parameters:** `name` — The name of the field that the bit is to be decoded as. **`void bits(String name, int numOfBits)`** - Appends numOfBits within a bitfield, labeling then name. - **Parameters:** - `name` — The name of the field that the bit is to be decoded as. - `numOfBits` — The number of bits that are to be decoded as a group. **`void namelessBitField(int nBytes)`** - Declares the start of the nameless bit field. - **Parameters:** `nBytes` — The number of bytes to be treated as a nameless field. **`void namelessBitFieldLE(int nBytes)`** - Declares the start of a nameless bit field. - **Parameters:** `nBytes` — The number of bytes to be treated as a nameless field. **`void skipBits(int numOfBits)`** - Skips given number of bits in decoding. - **Parameters:** `numOfBits` — The number of bits to be skipped. **`void skipBytes(int n)`** - Skips n bytes without decoding them. **`void appendString(String name, int length)`** - Appends length bytes as a string. This method is more efficient than decode, so if you do not needs the value of the field, use this. Example Output: 0x68656c6c6f20776f726c64 -> 'hello world' - **Parameters:** - `name` — The name of the field the string will be registered as. - `length` — The number of bytes to be decoded as a string. **`void appendSummary(String append)`** - Appends a message to describe the packet in network analyzer. This can be useful for describing what kind of payload the packet is. - **Parameters:** `append` — A string that will be appended to the packet's summary. **`void setSummary(String summary)`** - Sets the summary for what kind of event the payload could be. This will be what is read under the the network analyzer. - **Parameters:** `summary` — The summary that will be read under network analyzer. **`void setPrefix(String prefix)`** - Sets a prefix for the payload. A prefix will be prepended to the fields that are decoded by this decoder. - **Parameters:** `prefix` — A string that will be prepended to the names of fields for this decoder. **`void applyPrefixToSummary()`** - Sets the summary to be the prefix associated with the protocol. See fc.setPrefix() **`String codeNameSuffix()`** - Returns the codeNameSuffix, the suffix that is appeneded to each field. - **Returns:** String The codeNameSuffix currently set for the decoder. **`int currentOffset()**` - Returns the current offset for next element to be decoded in the payload. - **Returns:** int The current offset within the packet. **`boolean hasRemainingBytes()`** - Returns true if there are remaining bytes left in the payload that have not been updated. - **Returns:** boolean True if there are remaining bytes left. **`int remainingBytes()`** - Returns the number of bytes left before the end of the payload - **Returns:** int The remaining bytes that have been not been processed within the payload. **`void setAppendLengthsToFieldCodes(boolean flag)`** - Toggles the mode where the lengths of the fields are appended to the names. If you are decoding field "x" with length, 2, then the actual name of the field will be "x_2" if the length appending mode is true, and only "x" if its false. - **Parameters:** `flag` — Setting this true will append lengths to the end of fields as stated above. **`void setCodeNameSuffix(String codeNameSuffix)`** - Sets the codeNameSuffix - **Parameters:** `codeNameSuffix` — A string that will be appended to the ends of field names. ##### EventKey / Subkey Fields To see the full list of EventKeys that are currently available, go to **Window -> Preferences -> Network Analyzer -> Decoding -> Frames and Fields**. This window displays the valid frames and associated fields for your selected stack and profile. Note that the string you should use as the EventKey is the text that is located within brackets (e.g., if there is line "IEEE 802.15.4 [fifteenFour]", then you should refer to that frame using "fifteenFour"). If you expand the tree under each frame, then you will be able to see all the valid fields, and the text string that can be used as a subkey to search for them. ##### Example Decoders ###### Custom Decoder Skeleton > ```lua > -- Custom Decoder Skeleton (custom-decoder-skeleton.lua) > -- Users should use this as a framework to build their decoders. > > -- Create a table to hold all the functions > local decoder = {} > > -- This will let you set what the name of the frame should be when viewed in the network analyzer. > decoder.name = "Custom Decoder Skeleton" > > -- This will determine what the decoder can be filtered by in the network analyzer when viewing all packets. > decoder.filterName = "SampleDecoder" > > -- This is a function that is describing what the frame should have as its description > -- when you are viewing specific information in the network analyzer. > decoder.description = "This is an example of how you can describe a frame" > > -- This function will let you set whether the decode should be enabled by default when > -- loading it for the first time or when resetting the settings to default. > decoder.enabled = true > > -- This function will do the actual decoding of the payload. > -- You should primarily use the functions as defined for the FieldContext object fc to do this. > -- The functions for event can be used to process information from earlier frames. > function decoder.decode(event, fieldContext) > -- Your decoding logic here > end > > -- This function determines if an event is relevant to this decoder. > -- Note that this should be specific to the payload; if it is too generic, > -- then event payloads belonging to other decoders may be mistakenly read and decoded by this decoder. > function decoder.accept(event, packet) > return false > end > > return decoder > ``` ###### Field Formatter Example > ```lua > -- Example Decoder for using a field formatter (field-formatter-example.lua) > -- Create a table to hold all the functions > local decoder = {} > > decoder.name = "Field Formatter Example" > decoder.filterName = "fieldFormatterExample" > decoder.description = "This is an example of how you can log debug information and test your decoder" > decoder.enabled = true > > -- The list of field formatters > local fieldFormatters = { "decimal", "enuming", "bitFields", "bitDescription" } > > -- This function will do the actual decoding of the payload. > -- Note that the function call when using custom decoding requires > -- the addition of the third parameter formatter. > function decoder.decode(event, fc, formatter) > fc:setAppendLengthsToFieldCodes(true) > fc:append("append", 4, formatter["decimal"]) > fc:decodeLE("appendLe", 4, formatter["enuming"]) > fc:namelessBitField(4) > fc:bits("decodeBits", 3, formatter["bitFields"]) > fc:bit("decodedBit", formatter["bitDescription"]) > end > > -- This function determines if an event is relevant to this decoder. > function decoder.accept(event, packet) > return true > end > > -- These are three examples of field formatters. > -- Note that these functions MUST be able to handle null values. > function decimal(value) > return tostring(value) > end > > function enuming(value) > if value == 0 then > return "ZERO" > elseif value == 1 then > return "ONE" > elseif value == 2 then > return "TWO" > else > return "NOT ONE OR ZERO" > end > end > > function bitFields(value) > if value == tonumber("0001", 2) then > return "1" > elseif value == tonumber("0010", 2) then > return "2" > elseif value == tonumber("0100", 2) then > return "3" > else > return "invalid" > end > end > > function bitDescription(value) > return (value and "1" or "0") > end > > return decoder > ``` ###### Payload Decoder Logging Example > ```lua > -- Sample Logging Examples for testing and debugging (payload-decoder-logging-example.lua) > -- Users should see this for how they may be able to do some initial logging. > > -- Create a table to hold all the functions > local decoder = {} > > decoder.name = "Payload Decoder Logging Example" > decoder.filterName = "debugExampleDecoder" > decoder.description = "This is an example of how you can log debug information and test your decoder" > decoder.enabled = true > > function decoder.decode(event, fieldContext) > -- This will show up under the test console, but not the log file. > print("Hello world!") > > -- This will show up under the log file, but not the test console. > local a = fieldContext:decode("var1", 2) > log(a) > end > > function decoder.accept(event, packet) > return false > end > > return decoder > ``` ###### Sensor Sink Example > ```lua > -- Example Packet w/ Length byte for Full Over the Air (sensor-sink.lua) > -- 384188E8FF01FFFF00000803111100000AD5C12D0610000084E10A00006F0D0000080101000FC0010184E10A00006F0D000000FB8B7AC0220903 > > -- Create a table to hold all the functions > local decoder = {} > > decoder.name = "Sensor Sink Example" > decoder.filterName = "sensor" > decoder.description = "Lorem Ipsum" > decoder.enabled = true > > function decoder.decode(event, fc) > fc:appendEui64("SenderEuid64") > local clusterId > if event:containsSubkey("zigbeeApplicationSupport", "clusterId") == true then > clusterId = event:getInt("zigbeeApplicationSupport", "clusterId") > else > clusterId = event:getInt("zigbeeApplicationSupport", "clusterIdV2") > end > if clusterId == 0x01 then > fc:setSummary("Sink Advertise") > fc:append("senderShortId", 2) > elseif clusterId == 0x02 then > fc:setSummary("Sensor Select Sink") > elseif clusterId == 0x03 then > fc:setSummary("Sink Ready") > elseif clusterId == 0x04 then > fc:setSummary("Sink Query") > elseif clusterId == 0x0A then > fc:setSummary("Sensor Data") > fc:appendBytes("SensorData", 40) > elseif clusterId == 0x64 then > fc:setSummary("Sensor Hello") > fc:appendString("hello", 5) > end > end > > function decoder.accept(event, packet) > local accept = false > local clusterId > > if event:containsSubkey("zigbeeApplicationSupport", "clusterId") == true then > clusterId = event:getInt("zigbeeApplicationSupport", "clusterId") > else > clusterId = event:getInt("zigbeeApplicationSupport", "clusterIdV2") > end > > local profileId = event:getInt("zigbeeApplicationSupport", "profileId") > > if (clusterId == 0x01 or clusterId == 0x02 or clusterId == 0x03 or clusterId == 0x04 or clusterId == 0x0A or clusterId == 68) and (profileId == 0xC00F) then > accept = true > end > > return accept > end > > return decoder > ``` ###### Payload Decoding Example > ```lua > -- Example Packet w/ no length byte and payload only (payload-decoding-example.lua) > -- 01234567 89abcdef 01234567 89abcdef01234567 00000001 01000000 68656c6c6f20776f726c64 abcd abcd ffcdabcd 0f 00000000ff > -- Similar Example that is corrupted instead: > -- 01234567 89abcdef 01234567 89abcdef01234567 00000001 01000000 68656c6c6f20776f726c64 abcd abcd ffcdabcd ff 00000000ff > > -- Create a table to hold all the functions > local decoder = {} > > decoder.name = "Payload Decoding Example" > decoder.filterName = "exd" > decoder.description = "Lorem Ipsum" > decoder.enabled = true > > function decoder.decode(event, fc) > fc:setAppendLengthsToFieldCodes(true) > fc:append("append", 4) > fc:appendLE("appendLe", 4) > fc:appendBytes("appendBytes", 4) > fc:appendEui64("Eui64") > fc:appendFloat("appendFloat", 4) > fc:appendFloatLE("AppendFloatLe", 4) > fc:appendString("AppendString", 11) > fc:decode("decode", 2) > fc:setPrefix("Prefix") > fc:decodeLE("decodeLe", 2) > fc:decodeBytes("decodeBytes", 4) > fc:namelessBitField(1) > fc:bit("bitTest0") > fc:setSummary("Hello! ") > > if fc:decodeBit("Error") == true then > fc:bits("Error Code", 3) > fc:setCorruption("Error was set!") > fc:setSummary("Failed!") > else > fc:decodeBits("Data", 3) > fc:appendSummary("Success") > end > > fc:setCodeNameSuffix("suffix") > fc:skipBytes(4) > fc:appendRemainingBytesLE("appendRemainingBytesLe") > end > > function decoder.accept(event, packet) > return true > end > > return decoder > ``` #### Network Analyzer Preferences To access Network Analyzer preferences, select Window > Preferences > Network Analyzer. The preferences you set apply to all capture sessions. Network Analyzer saves your preferences and uses them each time Network Analyzer restarts. Preference categories include: - [Capture Configuration](#capture-configuration-preferences) - [Capture File Storage](#capture-file-storage-preferences) - [Connectivity Display](#connectivity-display-preferences) - [Decoding](#decoding-preferences) - [Energy Profiler Integration](#energy-profiler-integration-preferences) - [Node Icons](#node-icons-preferences) - [Optional Dialogs](#optional-dialogs-preferences) - Stream Visualization (deprecated function) - [Timeline](#timeline-preferences) - [Wireshark](#wireshark-preferences) ##### Capture Configuration Preferences ![Capture configuration preferences](/ss-5-users-guide-tools-network-analyzer/0.7/images/prefs-capture-configurations.png) These preferences offer general, time management, and user interface configuration options. Changes take effect in the next new capture session. Some options are: - Sorting and duplicate match window: Specifies in microseconds a time span in which duplicate packets can be detected. If identical packets arrive within the specified time span, Network Analyzer detects the duplication and allows only one to display. - Perform drift correction in network Analyzer: Allows drift for autocorrection. - Drift Threshold: Specifies the amount of time-drift that Network Analyzer will tolerate between the absolute PC clock and the adapter clocks before it resets its "time-correction" factor. In most situations you should not change this value. In a typical situation, adapter clocks are more precise than PC clocks, but they do not provide absolute time, just relative time against an arbitrary reference. ##### Capture File Storage Preferences ![Capture file storage preferences](/ss-5-users-guide-tools-network-analyzer/0.7/images/prefs-capture-file-storage.png) These preferences determine, among other things, what is considered a large file, which in turn determines the default editor used. Changes take effect in the next new capture session. Some of the options are: - Monitor the timestamp and optionally reload: Monitors whether the file has changed on the disk, and prompts to reload if so. - Monitor files for appending after opening: Enables Network Analyzer to detect new packet data appended by an external program to an open session file, and read it in for display. - Preserve open files across sessions: Instructs Network Analyzer to automatically reopen files from previous session - Enable large file handling: Enables Network Analyzer to handle large files in the Large File Editor. Files are considered large if they contain more events than the number entered in "Number of events for a file to be large." ##### Connectivity Display Preferences ![Connectivity display preferences](/ss-5-users-guide-tools-network-analyzer/0.7/images/prefs-connectivity-display.png) These preferences customize how device connectivity is displayed. ##### Decoding Preferences ![Decoding preferences group level](/ss-5-users-guide-tools-network-analyzer/0.7/images/prefs-decoding-group.png) The **Decoding** preferences group affect how decoding is handled. Changes take effect in the next new capture session. On the Decoding dialog, some options are: - Selected stack: The stack selected for decoding newly captured data. Links allow you to make changes in other preference interfaces. This setting has no effect on a previously captured trace. The decoding stack for a trace file is stored in the file itself. - Security level: The security level set for the MAC and network layers. Valid values include 1 through 5. ###### Security Keys ![Decoding preferences security keys](/ss-5-users-guide-tools-network-analyzer/0.7/images/prefs-decoding-security-keys.png) Specifies the security decryption keys. To enable a key, select the Decryption key checkbox. To edit a key, select its name or key values. All enabled decryption keys are run against each incoming packet until one is successful. Successful keys are automatically moved to the top of the key list to improve performance. Decryption keys can also be obtained from network traffic for future use. Buttons on the right of the dialog provide the following features: - New: Creates a new key for editing. - Import: Opens a dialog from which you can import a key file. - Clone: Creates a copy of the currently selected key. - Delete: Removes the currently selected key. - Invert swaps the order of the key values. - Clear All: Removes all security keys. - Run HMAC: Opens a dialog that allows you to manually calculate the HMAC authenticated key from trust key and IEEE EUI64 address. - ASCII edit...: Converts a human-readable ASCII string into a binary security key. The checkboxes at the bottom of the keys list provide the following options: - Save decryption keys in ISD files (unchecked by default): Saves the security keys that you have specified into the capture file along with your traffic. Note: If you are sharing the Network Analyzer file with users who have a right to know your key, this may make the opening of the file easier for them, as they will not have to separately enter the key. However, by doing this, you create a security risk. Never enable this option, if your keys must remain secure and known to you only. - Disable keys when not used for n days (checked by default): You can configure the number of days unused keys should be kept. ###### Stack Versions ![Decoding preferences stack versions](/ss-5-users-guide-tools-network-analyzer/0.7/images/prefs-decoding-stack-versions.png) A list of profiles representing Gecko SDK Suite stack versions. Check the stack that is deployed on the network you are using. If you are working with Dynamic Multiprotocol projects, select 'Auto-detecting decoder stack'. ###### Transaction Groupers ![Decoding preferences transaction groupers](/ss-5-users-guide-tools-network-analyzer/0.7/images/prefs-decoding-transaction-groupers.png) A table of all the groupers loaded into Network Analyzer. Transaction groupers are responsible for making transactional sense out of a trace of network data. Groupers watch for batches of events and record them as a transaction. ##### Energy Profiler Integration Preferences ![Energy Profiler Integration Preferences](/ss-5-users-guide-tools-network-analyzer/0.7/images/prefs-energy-profiler.png) See [Energy Profiler and Network Analyzer](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-tools-energy-profiler/energy-profiler-and-network-analyzer) in the Energy Profiler section for more information about using the two tools together and the effect of these preferences. ##### Node Icon Preferences ![Node Icon Preferences](/ss-5-users-guide-tools-network-analyzer/0.7/images/prefs-node-icon.png) Network Analyzer provides several predefined icons. The Node Icons dialog displays all icons that are available for customizing display of nodes in the map pane. You can also add icons of your own. ##### Optional Dialog Preferences ![Optional Dialog Preferences](/ss-5-users-guide-tools-network-analyzer/0.7/images/prefs-optional-dialog.png) Some dialogs can be turned off if you prefer not to interact with them. ##### Timeline Preferences ![Timeline Preferences](/ss-5-users-guide-tools-network-analyzer/0.7/images/prefs-timeline.png) Among other options, you can choose the colors and fonts for features of the Timeline. ##### Wireshark Preferences If you are using the Wireshark open source packet analyzer, these options configure the integration. ![Wireshark Preferences](/ss-5-users-guide-tools-network-analyzer/0.7/images/prefs-wireshark.png) ### SLC-CLI #### SLC-CLI User's Guide The Silicon Labs Configurator (SLC) is a metadata specification for the Gecko SDK (GSDK). It also describes methods of creating and configuring embedded software projects for Silicon Labs IoT devices using this metadata. Software is grouped into components (defined by .slcc files) that may provide features and/or require features provided by other components. Example projects (.slcp) describe a single software application (usually made up of multiple components plus application code) that can be used to generate an IDE project. See the [SLC Specification](https://siliconlabs.github.io/slc-specification/) for details about SLC. The SLC Command Line Interface (SLC-CLI) tool, among other things, resolves project and component dependencies and generates a project for a specified embedded target and build system (for example, IAR Embedded Workbench or GNU tools via a Makefile), among other things. This user’s guide provides references to the most common operations done with SLC-CLI. #### About SLC-CLI SLC-CLI is provided as a downloadable .zip file for three operating systems: - Windows® OS - MacOS® X - Linux® OS SLC-CLI may be used with the following SDKs and platforms: - Gecko Bootloader - Gecko Platform - The Gecko SDK (the suite of Silicon Labs SDKs) Example projects (defined in .slcp files) are installed with the SDK in a directory under the Gecko SDK (GSDK) installed directory. The location varies depending on the SDK. - Amazon AWS: \app\amazon\example - Bluetooth SDK: \app\bluetooth\example - Bluetooth Mesh SDK: \app\btmesh\example - OpenThread SDK: \protocol\openthread\sample-apps - 32-Bit MCU SDK: \app\mcu_example - Proprietary (Flex) SDK: \app\flex\example\ - Gecko Bootloader: \platform\bootloader\sample-apps - GSDK Platform: \app\common\example - Wi-SUN SDK: \app\wisun\example - Z-Wave SDK: \protocol\z-wave\apps - Zigbee SDK: \protocol\zigbee\app SLC-compatible SDKs may also support extensions that may include example projects as well as components. By default, extensions are installed into the “extension” folder at the root of an SDK. Extension: _|extension|_ #### Installation ##### Requirements The SLC-CLI .zip files are available here: - [https://www.silabs.com/developer-tools/simplicity-studio/configurator-command-line-interface?tab=downloads](https://www.silabs.com/developer-tools/simplicity-studio/configurator-command-line-interface?tab=downloads) In addition to the SLC-CLI .zip file and the Gecko SDK, you will need Java 64-bit JVM version 17 or higher, available through [Amazon Correto](https://docs.aws.amazon.com/corretto/latest/corretto-17-ug/downloads-list.html). Note that some files, such as the Windows .msi files, can be found on the [releases page](https://github.com/corretto/corretto-11/releases). ##### Installing the CLI 1. Unpack the SLC-CLI zip file. 2. (Optional) To call SLC-CLI from anywhere in your system, add the path to the expanded slc-cli to your PATH. If you do not do this step on Mac or Linux systems, you will need to preface all calls to `slc` with `./` as in `./slc`, assuming you are following this procedure in the current directory. 3. (Optional) All project operations require a path to the GSDK installation directory. To make these operations easier, you may want to create an environment variable for the GSDK location. ##### Other Tools SLC-CLI provides a number of options for generating project files. In order to build an application image you also need a compiler toolchain, such as GCC or IAR. In order to flash the image to a target device, you need Simplicity Commander. Simplicity Commander enables you to complete these essential tasks: - Flash an application. - Configure the application image. - Manage the target device. Download an Operating System-specific Simplicity Commander zip file here: [https://www.silabs.com/developers/mcu-programming-options](https://www.silabs.com/developers/mcu-programming-options). For instructions on using Simplicity Commander, see [UG162: Simplicity Commander Reference Guide](https://www.silabs.com/documents/public/user-guides/ug162-simplicity-commander-reference-guide.pdf). #### Usage `slc --help` provides details on usage and a list of available commands. `slc \ -h` shows all options for the command. ##### SLC-CLI Configuration SLC-CLI operations are based on the context of a specific SLC-compatible SDK. It is recommended to first configure SLC-CLI to use a specific SDK by default. 1. Configure SLC-CLI to a specific GSDK location, for example: `slc configuration --sdk users\\SimplicityStudio\SDKs\gecko_sdk` Then all commands that use an SDK will use this configured location. If you do not do this, you must specify the SDK path with the - -sdk option each time you issue a command, such as generate discussed below. 2. If using GNU toolchain from the command line (for example, with a GNU Make build system), first configure your GCC location. `slc configuration -gcc=\path\to\your\GNU\ARM\embedded\toolchain` Note: If you do not already have a GNU toolchain installed, you can download the proper version (aligned with what your SDK supports) from here: [https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm/downloads). See the release notes for your SDK version for compatible compilers. Example - SLC-CLI configuration on MacOS for GNU toolchain with default GSDK installation directory: `slc configuration --sdk=~/SimplicityStudio/SDKs/gecko_sdk --gcc-toolchain=/Applications/ARM`
Operation
Example
Description
**configuration**
`slc configuration --sdk="C:\sdk\sdk.slcs"`
Sets the given SDK to be default available (unless explicitly overridden in other commands). Any command that requires an SDK parameter will no longer require it, and will instead use this configured default. This either points directly to an .slcs file, or it points to a folder containing an .slcs file. Supplying an empty string (--sdk="") clears this value. May be set to a relative value. If this value is set and an override path is provided in the generation operation, the override is used.
`-e, --examine`
Prints the current configuration file and its location.
`-gcc, --gcc_toolchain "C:\path\to\gcc"`
Sets the default GCC toolchain path for use with the Makefile generator. This should point to the directory that contains the bin and lib folders.
##### General Options These options can be specified for any action and must appear after the command. For instance, `slc configuration --cli-config file.cfg –sdk=/sdk/path` is correct. |Option|Example|Description| |---|---|---| |`-v, --verbose`|`-v 1`|Sets verbosity levels. Values: SILENT, ERROR, WARNING, INFO, DEBUG, TRACE| |`--cli-config`|`--cli-config /home/myhome/configfile.cfg`|Allows customization of where the configuration information, set via slc configuration and subcommands, is stored. Overrides the defaults and can be used for every command if the defaults are not properly working in your environment. This must be a file.

The output of slc-cli help provides the default location on your system.| |`-wrk, --working-directory`|`--working-directory=/work/here`|The working directory that the command line should assume it was called from, such as for relative path resolution. In most cases, this should not need to be overridden.| ##### Working with Projects This section assumes you have configured the GSDK location as described above. `slc generate *\*` generates a project from an existing .slcp file, such as an SDK example. The path to the example is either the fully defined path, or the path relative to the calling location. Key options are: **-d ** (optional) specifies the destination for the generated project. If not specified, the project is generated to the source.slcp location. **-np** generates a new project by copying the .slcp file and all files defined in it into the destination location. All file references in the .slcp are updated to point to the destination location. Any sources that should be highlighted are shown in the SLC-CLI output. **-name=** specifies a different generated project name. Otherwise the name of the source .slcp file is used. **--with ** customizes the generated project for the target specified by the full part number or board ID, for example “EFR32BG22C224F512IM40” or “brd4184b”. To generate a new project with a new name for all supported toolchains: `slc generate \path\to\example.slcp -np -d -name= --with ` A number of files are generated that can be used with different tools. For example, to build the project with Make (if Make is in your path): `make -f .Makefile` Examples: Windows: Generate for all toolchains, for EFR32MG12P232F512GM68 device: `slc generate C:\Users\\SimplicityStudio\SDKs\gecko_sdk\app\bluetooth\example\soc_empty\soc_empty.slcp -np -d c:\test-soc-empty\ -name=test-soc-empty --with EFR32MG12P232F512GM68` MacOS: Generate, build (GNU Make/GCC), and flash (Simplicity Commander) project to Thunderboard Sense 2 (BRD4166A): ```c $ GSDK=~/SimplicityStudio/SDKs/gecko_sdk $ slc configuration --sdk=$GSDK --gcc-toolchain=/Applications/ARM $ slc generate $GSDK/app/common/example/blink_baremetal -np -d blinky -name=blinky -o makefile --with brd4166a $ cd blinky $ make -f blinky.Makefile $ commander flash build/debug/blinky.hex ``` ###### Project Operation Options All project-level operations listed in section [Project Operations](#project-operations) can accept the same basic arguments enumerated here. |Option|Required|Example|Description| |---|---|---|---| |`-p, --project-file`|yes, may be a positional parameter instead|-p blink.slcp|The actual project file that any project operations will be working against.| |`--with`|no|--with brd3200c,micriumos

--with pwm:led0:led1,brd2200a|Comma-separated list of components to include in the project in addition to components enumerated by the .slcp file itself and in addition to any auto-computed dependencies.

If a component is instantiable, then the instance names must be supplied separated by ':', with the first of the ':' separated list being the actual id, and subsequent ones being instance names.| ###### Project Operations Project operations always specify an SDK to load from as well as a project file _.slcp_ to draw from. You must specify an SDK (-s or --sdk) for every project operation unless you have configured a default SDK.
Operation
Example/Arguments
Description
**generate**
`generate -p="blink/blink.slcp -d="blink/output/blink_project"`
Generates the project to the given destination. By default this links all sources.
Destination is not required. If not specified, then the slcp directory is used.
`-d, --export-destination=DESTINATION`
Location for the generated project. If not provided, the .slcp or .slcw location is used. Generation location is used even for non-generating commands, as information there can still contribute to the project state.
`-name, --project-name`
Overrides the project name in the slcp. This determines some output file names and the generated binary names.
`-o, --output-type=OUTPUT_TYPE`
The output of the generation, effectively what kinds of files should be generated and for what tools/IDEs.
`--force`
Forces operation to continue in the presence of validation errors.
`--require-clean-project`
para:[If the slcp parser finds a potential problem and issues a warning, generation is halted.] para:[Examples: a project refers to a component not in the SDK , or a project uses deprecated metadata terms (like name instead of id for component listing, or name instead of project_name for the project's default name)]
`--configuration=CONFIGURATION_OVERRIDE_MAP`
Provides the same function as ‘configuration’ in the .slcp but command line options take precedence. Takes a comma-delimited list of changes in the format “configuration_name:value”. The same configuration cannot be referenced more than once on the command line.
`-cp, --copy-sources`
Copies all files referenced by this project, selected components, and any other running tools (Pin Tool, etc.). By default, no files are copied.
`-cpproj, --copy-proj-sources`
Copies all files referenced by the project and links any SDK sources. Can be combined with -cpsdk.
`-cpsdk, --copy-sdk-sources`
Copies all files referenced by the selected components and links any project sources. Can be combined with -cpproj.
`-nocp, --no-copy`
Causes all files to be linked into the generation location. Only generated files will exist in the generation location. Cannot be used with any other copy operation.
`-np, --new-project`
Runs the new project creation layout. This runs a standard generation step and then copies over any project sources (slcp, config folder, etc.), fixing any paths in the slcp file to point to the new location of the files. This defaults to -cpproj.
`-extmpl, --export-templates=EXPORT_TEMPLATES_FOLDER`
Location for custom export templates. Each exporter requires its own particular name for the files in this directory, but generally they are looking for the same files defined in the global exporter directory (/developer/exporter_templates) using 'custom.' (e.g., custom.project.mak)
`-tlcn, --toolchain`
Generates for the specified toolchain. The toolchains are not treated in the same way as components and so do not appear selected in the project. The current valid selections are gcc and iar.
`-tools, --config-tools=`
Specifies the tools to be generated based on the file extension. If this is not provided, then all active tools will generate. You may list more than one tool extension separated by commas.
`-o, --output-typ`e
The output of the generation, effectively what kinds of files should be generated, and for what tools/IDEs. You may list more than one type, separated by commas.
`-lfewp, --list-files-ewp`
Forces the IAR EWP generator to define all SLC contributed sources in the *.ewp file as well as the *.ipcf file. This mimics the IAR Project Connection support in IAR Embedded Workbench and is useful for Linux builds of IAR, which do not support *.ipcf files.
`--generator-timeout=TIMEOUT_SECONDS`
Overrides the default 30s timeout for each generation cycle. One call to generate may include multiple generation cycles, so this total generation time could be multiples of this timeout.
`-log, --log-only`
If set, all errors, warnings, and information is only printed to the process log files. Nothing is printed to the console.
`-s, --sdk=SDK_PATH`
Location of either the sdk folder containing the .slcs file, or the file itself. This is only required if no default sdk is set using 'slc configuration -s SDK_PATH'. If an sdk is supplied here and one is configured as default, this one takes precedence.
`-tpl, --template-output`
Causes all files to be generated as in the template style. This is useful for pre-made examples. This turns on no_copy and therefore cannot be used with copy sources.
`--with=COMPONENT_LIST`
Accepts a comma separated list of component IDs to be added to the project. Use a ':' operator for instance-capable components to separate instance names after the component ID (for example, 'pwm:led0:led1' for led0 and led1 instances with pwm).
If a component is to come from an extension, a semicolon should be used first to specify the id of the extension such as 'pwm;arc:led0:led1' if with-ing a component called pwm from an extension called 'arc' with instances 'led0' and 'led1'. The version of the extension is not supplied but is inferred from the project state.
`--without=COMPONENT_LIST`
Accepts a comma separated list of component IDs to be removed from the project. You may use a ':' operator with instance-capable components to specify the instance to remove. If no ‘:’ is provided, all instances are removed.
This uses ‘;’ semantics as described above for ‘--with’ to remove components belonging to extensions.
--without runs after the ‘--with’ command, so if a component appears in both lists it will not be added.
**validate-project**
`validate-project -p="blink/blink.slcp"`
Validates if a project would generate, essentially a dry run of generation. If the project is invalid, more information (such as a dependency tree) is output, indicating what and why it failed to auto-select all required dependencies, and what was missing. Python validation is not run by default.
`--config-location `
Tells the configuration validation scripts to run using the specified config folder for the project. Configuration files on that path will contribute their configuration values. The rule is that, if a configuration value appears in a config file on this path, it is considered the ultimate user configuration and overrides any default values.
**summarise, summarize**
`summarize --project blink.slcp`
Shows a summary of all components that make up a project, including both those explicitly set in the .slcp, and those implicitly brought in via dependency resolution.
`--why`
Summary of implicit components will be replaced with a long list of implicit components that include why they were brought in (the component that needed them, and the API rule.) In many cases, the component name and API ID are identical, but essentially the left side of 'for' is the component ID, and the right side is the API(s).
`--api`
An additional list is provided at the end of the summary showing every API that is provided by the project. In other words, every selected component put together will form a total set of available API.
**graph**
`graph --project blink.slcp`
`graph --project blink.slcp`
`--validate`
`--focus "emlib_common, cmsis_core"`
Shows a dependency graph instead of the inverted dependency system that `summarise --why` shows. This dependency graph is represented as a tree, where the first occurrence of a component shows that component's dependencies as well, but subsequent occurrences show only a '^', indicating that a deeper dive has been done earlier in the tree. This is essentially a compromise solution, since dependency graphs can otherwise be very web-like. Color and non-color systems both support drawing attention in their own way to different things.
Any component that provides an API other than itself will have that API listed after its name if that API is responsible for providing something another component in this project required.
Any component that appears as a 'child' to itself will show a green '[Cycle]' phrase. Cycles do not prevent dependency management from working. This merely calls attention to them.
`--validate`
Option to show validation issues in-line with the dependency graph. Validation issues are prefaced with an '!' and, if color is supported, are red.
`--focus`
Draws attention to a specific component/component(s) via either color or text, wherever they appear in the tree.
**clone**
`clone –t emlib –d project_sdk_extension –a neo_politan`
Clones sdk components for developers who wish to use a component in a slightly modified form. Takes care of ensuring all referenced files and other data is copied so that the cloned components are truly self-contained. To use the resulting clone, place it in a new sdk extension.
`--destination`
The location that the component will be cloned into. The component's slcc and directly required files will be cloned to this location.
`--target=TARGET_COMPONENT_ID`
The component to be cloned. Referenced files will be copied along with the .slcc, and the project search paths will be updated and saved. Clone data is automatically added based on the current system's date.
`--author "Fozzy Bear"`
If the optional author option is specified, the cloned component's author field in the .slcc is updated.
**upgrade**
`upgrade "blink.slcp"`
Upgrades the given project in place. If no upgrade rules report verification is needed or an upgrade is impossible, this modifies the project and the config folder in the same folder as the project. Does nothing if no config folder exists or the upgrade cannot complete properly. .bak files are created as backups for all files affected by the upgrade.
`--dry-run`
Runs the upgrade up to the point where the temporary configuration files that have been modified would be merged into the project, but stops short. It reports any issues upgrading, but even if there none, it will not actually modify the project.
`--verified`
If any upgrade rules indicate that 'verification is required', passing this allows the upgrade to take place.
**sbom**
`--all-components=[,...]`
Add every component from a comma separated list of input SDK or extension path to the SBOM. This is a utility command that is fully equivalent to `--with=`. This cannot be specified with the `-p` command.
`--cyclone-json`
The CycloneDX JSON output format.
`--cyclone-xml`
The CycloneDX XML output format.
`--spdx-default`
The SPDX default (tag:value) output format.
`--spdx-json`
The SPDX JSON.
##### Working with SDKs and Extensions These commands provide information about the components (.slcc files) included in an SDK or extension. ###### SDK Options These options are shared among all SDK commands. |Option|Example|Description| |---|---|---| |-s --sdk|`-s '/sdk/gsdk'`|Indicates the location of the primary SDK to use. This option overrides the global SDK configuration. If no SDK is configured (see above for **Configuration**) then this option becomes required. This either points directly to the .slcs file, or it points to a folder containing that file.| ###### SDK Operations
Operation
Example/Arguments
Description
**where**
`where micriumos`
Displays the location of a component based on the name. This is a subset of the information in **examine**.
**examine**
`examine micriumos`
Displays information about a component, such as where it is defined in the SDK, sources, provided APIs, and all additional metadata defined in the yaml itself.
**validate**
`validate sdk/platform/component/rtx.slcc`
Validates the .slcc file only, without validating anything else in the SDK. This ensures it is both proper yaml, and that it makes no semantic errors (such as missing required fields, misnamed fields, junk fields, or incorrect types).
**show-available**
`show-available toolchains [component option]`
Shows available toolchains and/or project types to use with **generate** or all distinct values for a component option (quality, provides, category, etc.).
**prune**
`prune --with brd2204a,EFM32GG11B820F2048GL192`
Returns a list of component IDs that are not conflicting with the given components. This is most effectively used to filter out components that would not work on certain hardware. Unlike **slc choices**, this is not intended to help fix validation errors, but rather to show everything that one could possibly add to a project given the current constraints.
This uses the project-level --with commands. A project may still be specified, however, in which case the total components in the project are treated as the input to this command.
Note: Using --with instead of an .slcp means including the components on the command line only. No dependencies are automatically resolved! If used directly with .slcp files, project dependencies are resolved as normal.
`--trace`
After displaying all available components that could be added, shows a (typically very long) section afterwards of everything that was filtered out due to conflicts of dependencies, and then a list of APIs that are subsequently unavailable. The unavailable API list includes 1 to many OR-listings of requirements that would have had to have existed for the API to be acceptable for this project.
##### Creating SDK Extensions This section discusses what constitutes an SDK extension and how to create one, as well as collating any information from the primary specification that pertains to SDK extensions. Note that this document is updated separately from the specification. In the event that the specification and this document do not align, the specification supersedes this document. ###### What Makes Up an SDK Extension? To be used as an SDK extension, all you need initially is an `.slce` file and a folder that contains it. This becomes the container for the SDK extension. Additionally, if you intend to install an SDK extension into an SDK manually (as opposed to letting the Simplicity Studio UI handle it), make sure the folder containing the `.slce` file is in a folder called `extension` inside of the SDK you intend to install it into. ###### Creating the Empty SDK Extension First you will create an empty SDK extension for the sole purpose of testing that the integration of the SDK extension into the SDK is successful. So you can test as you go, you will create an SDK extension such that you do not need to go to the Simplicity Studio UI to install it. 1. Name your base folder anything you like. 2. Ensure your base folder is in the extension directory of the SDK. If the folder does not exist, create it. By default, it is likely you will not have it if you have yet to install extensions into a particular SDK. 1. Because you will be using the `slc cli` later to verify your SDK extension is installed properly, make sure you are creating your SDK extension in the same SDK that is configured with `slc configuration –-sdk`. 2. If you are performing these steps with an sdk you downloaded using the Simplicity Studio installation, you will typically find the sdk in your user home folder. Navigate to **SimplicityStudio → SDKs → gecko_sdk** to find your installed sdk. You can also see where you installed the sdk from Simplicity Studio by checking the installation manager. Go to **Launcher View**, select **Install** at the top, and select the **SDKs** tab. Then, find the **Gecko SDK - 32-bit and Wireless MCUs** installation card and check the path indicated there. This is an example folder structure: ```c + - SimplicityStudio | + - SDKs | + - gecko_sdk | + - extension | + - your_extension ``` Note: This is extension singular, **not** extensions plural. 3. Create an `.slce` file at the base folder you wish to use. If starting from scratch completely, your folder may be empty. 4. Substituting where appropriate, enter the following into the `.slce` file. .**slce minimum working data** ```c id: "" label: "" version: sdk: id: "gecko_sdk" version: "4.1.0" component_path: - path: ``` - is a unique id for this SDK extension and how SLC internally recognizes it as distinct from another vendor. The SLC specification for id indicates which characters are allowed. Generally, this means no spaces, all lowercase, and _ (underscore character) are permitted. - a human-readable name for the SDK extension. This may contain spaces. - the starting version. This must follow semantic versioning rules – for example, 1.0.0, 0.0.1. - is the folder at the same level as the `.slce` file where the SDK extension can find your `.slcc` files. If you do not know, the `.slcc` file defines an installable component into an SLC project. You may define multiple paths here as well. This procedure assumes the path is . , as in ```c component_path: - path: . ``` - The sdk definition is typically `gecko_sdk` because that is the only SLC aware Silicon Labs sdk at this time. You may need to change the version number if you have a later version of the GSDK. - If you want to learn your `gecko_sdk` version without opening Simplicity Studio, open the `gecko_sdk.slcs` file inside the sdk folder and check the `sdk_version` metadata. 5. You now have a valid `.slce` file. If you already have some `.slcc` files and they are targeted by `component_path`, skip to step 6. Otherwise: 1. Make a new `.slcc` file in the same directory as the `.slce` (or in one of the directories pointed to by `component_path`). 2. Add a bare minimum amount of text for the `.slcc` to be considered valid. For example: ```c id: neopolitan_icecream label: Neopolitan Icecream package: "ext-comp" description: Neopolitan Icecream category: Melting|Icecream quality: alpha ``` The above is an absolute minimum set of required keys for an `.slcc` file to be considered a valid component. 6. Ensure that your `slc` command line is installed and available. 7. Ensure that `slc configuration` is set to use the sdk you are installing the SDK extension for. 8. Run `slc signature trust -extpath ` so it is trusted. Otherwise, none of its contents will be parsed, and will therefore not be found in later steps. This should be the path to the _folder containing the .slce_ , not to the `.slce` itself. Note: This is different from `slc signature trust -extid :` which installs trust for your SDK extension based on its `id` and `version` regardless of where it ends up moving. The former method will trust the SDK extension location allowing you to rename or reversion it without losing trust. If you are following this procedure and manually installed the SDK extension in with your GSDK, you will likely vastly prefer the `-extpath` option. 9. Run `slc signature trust --sdk ` if you have not yet trusted your SDK. 10. Run `slc examine -ext :` where the `id` is either the dummy `id` you created for the test component (in the above example, that would be `neopolitan_icecream`), or the `id` of some component that should exist in your SDK extension. The `-ext` part tells `examine` to look in a specific SDK extension and you must supply both the `id` and `version` so it knows where to look (since the same `id` could be used in different places). 11. The SLC command line will report the component is found and the information about it will be displayed on the console. If it does not appear, recheck the above steps. Otherwise, you have installed your SDK extension. Note: The most common error here is not trusting the SDK extension. If it is not trusted, you will not receive any notification, it will just not load and not find the component. ###### Making a Project Use an SDK Extension (Command Line) Normally, you can add an SDK extension to a project using the Component Selector in the Simplicity Studio User Experience (UX). Without that, you must do this manually. You add an SDK extension to a project by modifying its `.slcp` file to refer to the SDK extension. Components within that SDK extension are included using a special syntax. 1. Make a new project. This is beyond the scope of this document, but you can take an existing Simplicity Studio project you have or use `slc generate -np` on an example project in the SDK to create a new one to work with if you do not have one already. Refer to the relevant `slc` documentation on how to find and generate an example. 2. Inside the `.slcp` file, add a section as shown below. Add to the same level as other root metadata tags: ```c sdk_extension: - id: version: ``` 3. This tells the project that it will use that SDK extension with specifically that version. You may define multiple SDK extensions to use in a project, but for a given `id`, you may only choose one version. 4. Now, tell the project to use one of the components in the SDK extension. There is a `component` key at the root of the yaml with a list of components selected in a project. Observe the difference between referring to a component from the SDK and a component from the SDK extension as shown below. ```c component: - id: emlib - id: neopolitan_icecream from: ``` - `emlib` comes from the GSDK. Any component from the GSDK needs only the `id` field. You do not need to have this specific component. This is just an example of what using a component from the main SDK looks like compared to the SDK extension. - `neopolitan_icecream`, or whatever `id` of a component in your sdk extension, comes from that SDK extension. As such, you need to tell SLC that this component comes from a different location. Note that the version is not included next to the `from` field. This is why `sdk_extension` field exists earlier. `sdk_extension` indicates what specific SDK extension to pick out. You cannot have multiple SDK extensions with the same `id` even if the versions are different, in the same project. The component listing will always refer to whatever version of that SDK extension is being brought in at the time. 5. You can now use `slc summarise` on the project to view and ensure that your project is seeing the component. ###### Using Your SDK Extension with the Simplicity Studio IDE The Simplicity Studio Integrated Development Environment (IDE) provides a User Interface (UI) for adding SDK extensions from anywhere on your system. However, if you are actively developing SDK extensions, it is important to be aware of a few limitations. This section discusses how to add your custom SDK extension to Simplicity Studio in this way and what to look out for as an SDK extension developer. First, if you have followed the above procedures up to this point and used a project that is already part of a Simplicity Studio workspace, it is already connected. You need only launch Simplicity Studio and open the project. The SDK extension will already be installed and you can browse components within it. If you followed the above procedures but did not use a project in a Simplicity Studio workspace, follow these steps **Using an already installed and trusted SDK extension with a project**: 1. Create a new project or pick an existing one using the same `sdk` you installed the SDK extension for. 2. Open the `.slcp` file. 3. Navigate to the **Component Selector** by clicking the **Software Components** tab. 4. Search for a component in your SDK extension. 5. After you find it, Simplicity Studio prompts you to add the SDK extension to the project before you install the component. 6. Install the component and your project is now connected to that SDK extension. For the above steps, you do not need to install the SDK extension at a preference level to be globally accessible. By placing it in the GSDK’s `extension` folder, you already did that manually and Simplicity Studio has detected that. **However, if you did not install the SDK extension** or you are using a different GSDK that does not have the SDK extension, your flow will be a bit more involved. If you wish to use your SDK extension with a different SDK or you have distributed it and another SDK wishes to use it, follow these steps: 1. In Simplicity Studio go to **Preferences > Simplicity Studio > SDKs** and select the Gecko SDK Suite to which the SDK extension will be added. Click **Add Extension…**. 2. Click **Browse** and navigate to the root folder of the new SDK extension and click **Select Folder**. 3. The SDK extension should be displayed in the Detected SDK Extension window with the correct name, version, and path. Click **OK** and then **Trust** and **Apply and Close**. **Important:** Be aware that installing an SDK extension like this will copy the SDK extension from wherever it was into the proper folder structure and rename it so it is detected as an SDK extension. Because this is a _copy_, changes you make to your original SDK extension will **not** be reflected until you remove and add the SDK extension again. This is why the earlier part of the above procedures recommend starting from the correct installation location of the GSDK you want to test with because this shields you from this complication. 4. You can now follow the above steps in **Using an already installed and trusted SDK extension with a project**. ##### Daemon Mode The SLC CLI can be run as a daemon. In this mode, the application is launched and remains open to service further commands. This reduces the time to service any given command, especially those which require loading the sdk (which is most of them). To run a command in daemon mode, add `--daemon` to any command, after the slc but before the command itself. For example, `slc --daemon generate neo_politan.slcp -d gen_destination`. If the daemon is not currently running, it will start. If it is, it will merely connect. The daemon mode was built to scale with Continuous Integration and Continuous Development (CI/CD) systems that may be running many operations at once. As such, it is enough to just add `--daemon` to any command, and SLC CLI will automatically handle what it needs to ensure that if multiple calls are all attempting to start the daemon, only one will win and service every call. ###### Daemon Mode Considerations - The SDK that is loaded when the daemon first launches, as configured by slc configuration, is the assumed default for all future commands until the daemon is shut down. - When using the daemon for CI/CD flows: - It is recommended that every command references the --sdk directly and does not rely on any configuration. - Run all slc signature trust commands with the --daemon option. ###### Shutting Down The daemon will automatically shut down in two scenarios (outside of crashes): - If a bug occurs where a daemon is launched but not connected to, the daemon process will end after 30 seconds. - After the daemon has serviced at least one command, and it has been more than 30 minutes since the last command. This timeout can be adjusted. The daemon can be manually shut down by issuing the following command: ```c slc --daemon daemon-shutdown ``` ###### Daemon Options Reference The following are supported daemon-specific options that apply to the daemon connections themselves. As with `--daemon` they should be used before the slc command. |Option|Example|Description| |---|---|---| |--do-not-launch-daemon| |Will attempt to connect to an existing daemon, but will fail if none is present (in other words, it will not attempt to start up a daemon if one is not available).| |--daemon-timeout=TIMEOUT| |How long, in minutes, the daemon will stay alive after servicing a request before it automatically shuts down.| |--daemon-only| |If set, the daemon will not attempt to use a direct call to fallback. Under normal circumstances, if something goes wrong attempting to connect to a daemon, then SLC CLI is launched directly to service whatever command it was given. This fallback may be considered more of a problem than a solution in some cases, such as system testing. If this is set, the launcher will never attempt to do a direct launch of SLC CLI, and fail immediately if anything goes wrong attempting to either start, or connect to, a Daemon.| |--reload-sdk| |Reload the SDK from the input location from disk. Users should call this if the SDK has changed on disk and SLC is currently running in Daemon mode.| ###### Workarounds When SLC CLI has issues with daemon mode, it will try to fall back to servicing the command as if daemon mode was not requested. In the event of instability, try the following: - Check the user directory's .uc/cli folder for data directories (cli ones should be cli_pdata.) Delete all of the data directories. Normally, the launcher should delete .running files that are stale (empty and never getting filled in) or refer to dead process ids, but if a daemon has hung in an unexpected way and simply cannot respond, this is the easiest way to remove it from consideration. - Check if there are any stray .lock files in any data directories, and delete them if they exist. ## Additional Information ### Tips and Tricks Many of these tips rely on changes in Preferences. This can be accessed through the **Window > Preferences** selection, or the **Preferences** button on the toolbar. #### Useful Windows 10 paths Default Simplicity Studio Install Path: C:\SiliconLabs\SimplicityStudio Downloaded location for kit resources: C:\SiliconLabs\SimplicityStudio\v5\offline\aem\[www.silabs.com\documents\public\schematic-files](http://www.silabs.com\documents\public\schematic-files) Command line or direct GUI access to Simplicity Commander: C:\SiliconLabs\SimplicityStudio\v5\developer\adapter_packs\commander Protocol SDK locations for all GSDK SDKs: - GSDK 4.x: C:\Users\<NAME>\SimplicityStudio\SDKs\gecko_sdk\protocol\ - GSDK 3.x: C:\SiliconLabs\SimplicityStudio\v5\developer\sdks\gecko_sdk_suite\\ Beginning with GSDK 4.0, content such as documentation or demos that was previously installed with the SDK is now downloaded after being accessed through Simplicity Studio: C:\SiliconLabs\SimplicityStudio\v5\offline\com.silabs.sdk.stack.super_ #### Useful Mac OS paths Default Simplicity Studio Install Path: /Applications/SimplicityStudio.app/Contents/Eclipse (recommend changing to one word SimplicityStudio.app) Downloaded location for kit resources: /Applications/SimplicityStudio.app/Contents/Eclipse/offline/aem/[www.silabs.com/documents/public/schematic-files](http://www.silabs.com/documents/public/schematic-files) Command line or direct GUI access to Simplicity Commander: /Applications/SimplicityStudio.app/Contents/Eclipse/developer/adapter_packs/commander Protocol SDK locations for all GSDK SDKs: - GSDK 4.x: /Users/<NAME>/SimplicityStudio/SDKs/gecko_sdk/protocol/ - GSDK 3.x: /Applications/SimplicityStudio.app/Contents/Eclipse/developer/sdks/gecko_sdk_suite//protocol Beginning with GSDK 4.0, content such as documentation or demos that was previously installed with the SDK is now downloaded after being accessed through Simplicity Studio: /Applications/SimplicityStudio.app/Contents/Eclipse/offline/com.silabs.sdk.stack.super_ #### Default Project Locations Default project locations in your Windows 10 workspace C:\Users<user>\SimplicityStudio Ex: C:\Users\daseymou\SimplicityStudio Default project locations in your Mac workspace /Users//SimplicityStudio Ex: /Users/mahallam/SimplicityStudio #### Get All Parts of an Update When you update Simplicity Studio, whether in response to an update notification or in the Installation Manager, Simplicity Studio installs all Product Updates. However, other updates may also be available, for example for the GSDK or compiler support. The best practice after Simplicity Studio installs an update is to open the Installation Manager and select **Install by Technology Type**. Check the boxes for each technology type being used and click **Next**. Click **Advanced** and then **Next**. The next dialog shows you if there are any required or recommended packages to be installed. If yes, install them, otherwise click **Cancel** to leave the Installation Manager. For example, in an update from Simplicity Studio version 5.1 to 5.3.2, the following recommended updates, including GCC toolchain and the GSDK, were available. ![recommended updates](/ss-5-users-guide-tips-and-tricks/1.0/images/tip-installing-other-items.png) #### How to Update the Internal Simplicity Studio Copy of Simplicity Commander Simplicity Commander, included with Simplicity Studio, is regularly updated with other Simplicity Studio updates. In general, to get the latest Simplicity Commander update, update Simplicity Studio. However, sometimes the release of a new Simplicity Commander to the Silicon Labs website ([https://www.silabs.com/mcu/programming-options](https://www.silabs.com/mcu/programming-options)) lags behind the release of a new Simplicity Studio™ version. If the new version of Simplicity Commander includes a feature that is required for development then it is possible to replace the Simplicity Studio version with the following procedure. First exit all running instances of Simplicity Studio and then download the appropriate version of Simplicity Commander from the above website. The procedure for updating Simplicity Commander on the MacOS is slightly different and is described after the Windows and Linux instructions. ##### Windows and Linux (verified on Windows 10 and Ubuntu 18.04 LTS) Two Simplicity Commander files in the current installation must be backed up as they have to be added back after the update. The default paths for the Simplicity Studio version of Simplicity Commander are: Windows: `C:\SiliconLabs\SimplicityStudio\v4\developer\adapter_packs\commander` Linux: `~/SimplicityStudio_v4/developer/adapter_packs/commander` Back up the following two files: 1. [apack.info](http://apack.info/) 2. commander40x40.png When the downloaded version of Simplicity Commander is expanded on Windows it is placed in a [Simplicity Commander] folder and on Linux in a [SimplicityCommander-Linux] folder. The Linux version will contain an additional tarball that needs to be expanded into a [commander] folder. The contents of that folder ([Simplicity Commander] on Windows or [commander] on Linux) should be used to replace the internal Simplicity Studio™ commander located at the above paths. Then copy in the two files that were backed up (apack.info and commander40x40.png) replacing the apack.info file. ##### MacOS Instructions (verified on MacOS Catalina version 10.15.4) After the SimplicityCommander-Mac.zip is expanded it will be placed in a folder with a release note text file, a README.txt and the Commander .dmg file. When the .dmg file is opened it mounts the Commander application as a volume. The Commander.app can then be executed from that volume, dragged into the Applications folder or, in this case, used to replace the internal Simplicity Studio installation. Drag Commander.app into the folder containing the existing Commander.app: `/Applications/Simplicity\ Studio.app/Contents/Eclipse/developer/adapter_packs/commander` A popup will be displayed saying an item named "Commander.app" already exists with various options: ![Commander Exists](/ss-5-users-guide-tips-and-tricks/1.0/images/commander-exists.png) Click **Replace**. Note: If Commander.app is dragged from the Applications folder it will move it out of Applications and not create a copy. ##### Conclusion To verify the new version is being used, start Simplicity Studio and launch Simplicity Commander (from the Launcher perspective Tools icon (green wrench)) and select [Help] > [About Simplicity Commander] and the version will match the name of the .zip (Windows), .tgz (Linux) or .dmg (MacOS) file. Commander is also used behind the scenes for several operations including flashing images and various security commands. Note there has been at least one report on a Mac that it had to be rebooted for this to work correctly. That should not normally be necessary, but it might if Simplicity Commander or Simplicity Studio did not shut down cleanly for some reason so it is worth trying. #### Optionally Disable Automatic Updates By default, SSv5 checks for updates when you first open it. You can manage update frequency through **Preferences > Install/Update > Automatic Updates**. ![launcher update frequency](/ss-5-users-guide-tips-and-tricks/1.0/images/launcher-update-frequency.png) Either uncheck **Automatically find new updates and notify me** or change the **Update Schedule** selection to use a schedule such as once a week. If you have turned automatic updates off, you can check for updates by clicking **Install** on the toolbar, then **Manage Installed Packages**, and then **Check for Updates** on the Product Updates tab. See [About Update Frequency](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-about-the-launcher/toolbar#about-update-frequency) for details on the selections available. #### Performance Enhancements To improve SSv5 performance, try one or more of the following suggestions. **Disable SDKs not being used** If you have installed many different versions of different SDKs and GSDKs over time, go to **Preferences**, type `SDK` in the filter field, and uncheck the ones not currently being used. ![tips sdks](/ss-5-users-guide-tips-and-tricks/1.0/images/tips-sdks.png) **Disable unused targets or toolchains** If you have installed multiple toolchains but are not using all of them, or are not using all of the targets, disable the unused ones. Go to **Preferences** and type `toolchain` or `target` in the filter field, and uncheck any unused items. ![tips toolchains](/ss-5-users-guide-tips-and-tricks/1.0/images/tips-toolchains.png) **Use different workspaces for different GSDK versions or compilers** Overloading a workspace with projects and different versions of SDKs can slow down SSv5 operations. Keep separate workspaces for specific project and/or SDK versions and/or toolchains. Note that this is necessary if you are using different versions of the IAR compiler to match different versions of the GSDK. While you can use **File > Switch Workspaces** to change workspaces as described in [Project Explorer View](/simplicity-studio-5-users-guide/5.11.2/ss-5-users-guide-about-the-simplicity-ide/user-interface-review#project-explorer-view), if you will be working with different workspaces, you may wish to have SSv5 prompt you on startup about which workspace to use. Go to **Preferences > General > Startup and Shutdown > Workspaces** and check **Prompt for workspace on startup**. ![Workspace preferences](/ss-5-users-guide-tips-and-tricks/1.0/images/simp-ide-workspace-pref.png) Then on startup you can select a workspace or create a new workspace by clicking **Browse** and adding a directory. ![Add a directory](/ss-5-users-guide-tips-and-tricks/1.0/images/simp-ide-workspace-select.png) **Increase heap size** Close SSv5. Use a text editor to open following file within the Simplicity Studio root path, for example: _C:\SiliconLabs\SimplicityStudio\v5\studio.ini_ In the following figure, the line `Xmx5g` was added to increase the maximum Java heap SSv5 will use to 5 GBytes. Choose larger or smaller depending on your system resources. Without that line SSv5 defaults to a maximum of one quarter of the system RAM. On a system with 8 GBytes of RAM that would be 2 GBytes and SSv5 might run out of Java Heap space on memory-intensive operations. ![tips heap](/ss-5-users-guide-tips-and-tricks/1.0/images/tips-heap.png) #### SDK installation or updates are not working The cause might be your IT department using proxy servers, and potentially also man-in-the-middle security monitoring. See the following knowledge base articles for more information on how to work around these situations: [Configuring Simplicity Studio to Work with Proxy Servers](https://www.silabs.com/community/software/simplicity-studio/knowledge-base.entry.html/2018/11/12/configuring_simplici-hwpu) [Installing SSL Security Certificates for Simplicity Studio Updates](https://www.silabs.com/community/software/simplicity-studio/knowledge-base.entry.html/2018/10/12/installing_ssl_secur-UVxo) #### Speed up debug session startup Go to Preferences > Run/Debug > Launching, and under General Options uncheck **Build (if required) before launching**. This will interfere with your workflow if you are accustomed to making a change and clicking the Debug button to build the project before launching the project. #### Speed up reading large source files Enable folding of #if/#ifdef's and if/else, do/while, for, and switch statements in source code. Go to **Preferences** and type `folding` in the filter field, and check the three "Enable folding … " options. ![tips folding](/ss-5-users-guide-tips-and-tricks/1.0/images/tips-folding.png) #### Speed up the indexer If the Indexer is taking a long time to run, close other projects. If still slow, in the Project Explorer view right-click the project directory and select **Index > Rebuild**. ![index rebuild](/ss-5-users-guide-tips-and-tricks/1.0/images/tips-index.png) #### Restore a perspective layout To reset a perspective to its original layout, right-click the perspective button in the toolbar and select **Reset**. #### Find a Version Go to **Help > About Simplicity Studio** for version information. The overall SSv5 version is at the top of the dialog. The Studio Version tab lists version information for all the components that make up SSv5. The Toolchains and SDKs tab lists version information for the installed SDKs and toolchains. ![Help about](/ss-5-users-guide-tips-and-tricks/1.0/images/tips-help-about.png) #### Report a Bug Go to **Help > Report bug ...**. The default selection generates a log file to the location you specify. This is useful if you need to attach a log to a case that's already created. ![Hel report a bug](/ss-5-users-guide-tips-and-tricks/1.0/images/tips-help-bug1.png) Select **Submit bug at Silabs.com** if you are creating a new ticket. This generates the log file and provides instructions on creating a ticket. ![help submit a bug at silabs.com](/ss-5-users-guide-tips-and-tricks/1.0/images/tips-help-bug2.png) #### Capture a Simplicity Studio 5 Thread Dump If Simplicity Studio 5 happens to hang (become unresponsive for several minutes) during an operation, the best way to report this to Silicon Labs is to use a Java tool called jstack to capture a thread dump while the program is still in the hung state. This thread dump can be used by the Silicon Labs team to analyze the hang. If Simplicity Studio 5 is shut down and restarted, a thread dump at that point will not be useful. The jstack tool is included in the Simplicity Studio 5 installed Java Runtime Environment (JRE). Once you have generated the thread dump file according to one of the following procedures, attach it to a Silicon Labs support case along with other details of what operation was being performed right before the hang as well as any screenshots taken of what was shown in the application. A support case can be created from the Silicon Labs Simplicity Studio Community home page or with this url: [https://siliconlabs.force.com/s/contactsupport](https://siliconlabs.force.com/s/contactsupport). The procedure to use the jstack tool for Windows, MacOS and Linux is described in the following sections. ##### Windows 1. Open Windows Task Manager and go to the Details tab to find the PID for Simplicity Studio (studio.exe). 2. Open a command prompt and issue the following command, adjusting it based on the Simplicity Studio installation path: `[SIMPLICITY_STUDIO_INSTALLATION]\features\com.silabs.external.java.windows.x86_64.feature_11.0.5\jre\bin\jstack.exe PID > [PATH]\SSv5ThreadDump.txt` For example, with the default installation path: `C:\SiliconLabs\SimplicityStudio\v5\features\com.silabs.external.java.windows.x86_64.feature_11.0.5\jre\bin\jstack.exe -l -e 41068 > C:\temp\SSv5ThreadDump.txt` ##### MacOS 1. Open a terminal window. 2. Use the following command to get the PID: `ps aux | grep studio` This is an example of the output with the pid **76698**: ```C++ USERNAME@mac0010128 ~ % ps aux | grep studio USERNAME 76698 5.6 9.7 12491892 1633396 ?? S Tue09AM 92:52.70 /Applications/SimplicityStudio5.app/Contents/MacOS/studio USERNAME 19420 0.0 0.0 4268300 680 s000 R+ 3:26PM 0:00.00 grep studio ``` 1. Use the PID with the jstack command `[SIMPLICITY_STUDIO_INSTALLATION]/Contents/Eclipse/jre/Contents/Home/bin/jstack -l -e PID > [PATH]/SSv5ThreadDump.txt` For example `/Applications/Simplicity\ Studio.app/Contents/Eclipse/jre/Contents/Home/bin/jstack -l -e 76698 > ~/Documents/SSv5ThreadDump.txt` ##### Linux 1. Open a terminal window. 2. Use the following command to get the PID: `ps aux | grep studio` This is an example of the output with the pid **10233**: ```C++ ThinkPad-W530:~$ ps aux | grep studio USERNAME 10233 10.1 27.3 110505488 2115904 ? Sl 12:55 10:58 /home/USERNAME/SimplicityStudio_v5//jre/bin/java -Dosgi.requiredJavaVersion=11.0.5 -Xms40m -Declipse.p2.unsignedPolicy=allow -Djava.net.preferIPv4Stack=true -Djxbrowser.ipc.external=true -jar /home/USERNAME/SimplicityStudio_v5//plugins/org.eclipse.equinox.launcher_1.5.600.v20191014-2022.jar -os linux -ws gtk -arch x86_64 -showsplash -launcher /home/USERNAME/SimplicityStudio_v5/studio -name Studio --launcher.library /home/USERNAME/SimplicityStudio_v5//plugins/org.eclipse.equinox.launcher.gtk.linux.x86_64_1.1.1100.v20190907-0426/eclipse_1801.so -startup /home/USERNAME/SimplicityStudio_v5//plugins/org.eclipse.equinox.launcher_1.5.600.v20191014-2022.jar --launcher.overrideVmargs -exitdata a78007 -vm /home/USERNAME/SimplicityStudio_v5//jre/bin/java -vmargs -Dosgi.requiredJavaVersion=11.0.5 -Xms40m -Declipse.p2.unsignedPolicy=allow -Djava.net.preferIPv4Stack=true -Djxbrowser.ipc.external=true -jar /home/USERNAME/SimplicityStudio_v5//plugins/org.eclipse.equinox.launcher_1.5.600.v20191014-2022.jar ``` 1. Use the PID with the jstack command: `[SIMPLICITY_STUDIO_INSTALLATION]/jre/bin/jstack -l -e PID > [PATH]/SSv5ThreadDump.txt` For example: `~/SimplicityStudio_v5/jre/bin/jstack -l -e 10233 > ~/Documents/SSv5ThreadDump.txt` #### Convert an Existing Simplicity Studio 5 Project from GCC to IAR 1. Create a new IAR build configuration: - Right-click the project folder and select Build Configurations > Manage. - In the resulting Manage Build Configurations dialog, click **New**. - Select the IAR ARM build configuration to use (IAR ARM Default recommended) and click **OK**. 2. Still in the Manage Build Configurations dialog, select the new build configuration and click **Set Active**. 3. Open the project's .slcp file and, on the OVERVIEW tab, click **Edit** on the Project Generators card. 4. Select IAR EMBEDDED WORKBENCH PROJECT and click **Save**. For Bluetooth projects steps 5 through 7 are also necessary. For Platform and Flex projects proceed to step 8. 5. In the Project Explorer view: - Right-click the project folder and select Properties. - In the resulting Properties dialog, expand C/C++ Build and select Settings. - Under Tool Settings select IAR Linker for ARM > Library and select all of the libraries with GCC or gcc in the name or path and also the 'gcc', 'c', 'm' and 'nosys' libraries. - Click **Delete** in the dialog menu. - Click **Apply and Close**. 6. In the Project Explorer view: - Expand gecko_sdk_n.n.n > platform > Device > SiliconLabs > > Source. - Right-click the GCC folder and select Resource Configurations > Exclude from Build... - In the resulting dialog, check the box for the IAR ARM ... build configuration. - Click **OK** 7. Check if the project contains gecko_sdk_n.n.n > service > udelay > src > sl_udelay_armv6m_gcc.s. If it does, exclude it from the build with the same command as in the previous step. 8. Build the project. It should be successful. If not, check if any other GCC-specific files exist that need to be excluded from the build configuration. #### Use Custom Boards Connect the board either using an external Segger J-Link Debug Adapter or a Silicon Labs mainboard, with Debug Mode set to OUT. (In the Debug Adapters view, right-click the device, select **Device Configuration**, and change the Debug Mode on the Adapter Configuration tab). Create the project with the chip part number set in the Target, SDK, and Toolchain Selection dialog. You cannot use Flash Programmer until the debug adapter's device configuration has been configured with the part. Use Simplicity Commander instead. Projects based on custom boards can be built and flashed as part of a debug session. Simplicity Studio then displays and allows you to confirm the target settings to use for the debug session. ![Debug device selection with target settings shown](/ss-5-users-guide-tips-and-tricks/1.0/images/custom-board-debug-device-selection.png) You can change the debug adapter's device configuration by right-clicking the device in the Debug Adapters view, selecting **Device Configuration**, and making either of these changes: 1. On the Device Hardware tab, enter the target part number. ![Manually set the part in Device Configuration](/ss-5-users-guide-tips-and-tricks/1.0/images/custom-board-manual-debug-adapter-config.png) 1. On the Device Hardware tab, change the Target Interface to **SWD**. Click **Detect Part**. ![Get Simplicity Studio to detect the part in Device Configuration](/ss-5-users-guide-tips-and-tricks/1.0/images/custom-board-autodetect-debug-adapater-config.png) #### Discover Network Devices Sometimes Simplicity Studio may fail to discover a device connected on a local network. For devices with EFR32/EM3xx/Si917 MCUs, this can be addressed through the **Preferences > Simplicity Studio > Device Manager > TCP/IP Adapters** settings. Enabling more network scanning, for example by selecting the **Include all network interfaces. (Use when connected to VPN)** checkbox on that dialog, can flood the network with undesired discovery requests. The preferred method is by discovering the specific device. - On the TCP/IP Adapters dialog, check **Use TCP discovery for individual addresses**. - In the **Discovery Subnet Configuration** text box, enter the individual IP address. #### Place a Project Under Source Control Note that not all of these folders will be present in all projects. Which ones are present depends on if the project is a Project Configurator-based project (has a .slcp file) as well as what operations have been done with the project, especially in the Project Configurator. ##### Hidden Folders in SSv5 IDE Projects: |Files / Folder|Purpose|Under Source Control?| |---|---|---| |.pdm|Tracks project changes compared to the original project template used during project creation, normally from a software example.|Yes - very important| |.cproject & .project files|Eclipse project files, contains project settings for the different build configurations such as Includes, Defines, and compiler options.|Yes| |.settings|Tracks project-level preferences for Eclipse and Simplicity Studio.|Probably - but some might only apply to the local developer| |.trash|Keeps a copy of Project Configurator files or folders for software components that were deleted from the project and had been changed from the default values. The files are kept in case the component is added back, in which case the last used settings for the component are restored. Can also contains user-copied/supplied source files, for example if the user adds their own source files to the project and then deletes them.|No| |.uceditor|Keeps a list of software components that were edited on this computer.|No| |.projectlinkstore|Contains quick links for commonly used files or resources.  The listed links are updated based on how often a user opens a file or resource.|No| ##### General Source Control Information for Project Configurator Projects: |File / Folder|Purpose|Under Source Control?| |---|---|---| |.slcp, .slps and .pintool|The main Project Configurator files.|Yes| |config|Contains the configuration header files for all of the software components used in the project. Changes made in the header files are reflected in the Project Configurator and vice versa. Also contains subfolders with Advanced Configurator (AC) configuration files. For example, Bluetooth projects have a 'btconf' subfolder with the gatt_configuration.btconf file and possibly 'in_place_ota_dfu.xml' file.|Yes - Cannot be recreated| |autogen|Contains files created by the Project Configurator based on the installed software components and the files in the 'config' folder. The files are necessary to build the project, but they will be recreated on project generation.|Normally yes, but with some flexibility depending on the workflow of the team (that is, do they always do a generation after updating the project).| |gecko_sdk_x.y.z|Created by the Project Configurator based on the installed components. It will be recreated on project generation.|Same as for the 'autogen' folder| |Build output folders ('GNU ARM...', 'IAR ARM...' or 'Keil 8051...')|Created when the project is built.|Not normally|