Developing with WiSeConnect™ SDK v3.x with the SiWx91x Host™#

This guide describes how to develop applications for the SiWx91x™ chipset family using the WiSeConnect™ SDK v3.x in System-on-chip (SoC) mode, where both the application and the connectivity stack run on the SiWx91x chipset.

Note: The output images in this guide are for illustration purposes only. Details such as board names and version numbers may not exactlyb match the product.

Check Prerequisites#

Software#

  • Simplicity Studio

  • Gecko software development kit (GSDK)

Note:

  • We recommend using the latest GSDK version.

  • Refer to the Release Notes for the GSDK version tested with this release.

Hardware#

  • Wi-Fi Access Point (802.11 ax/b/g/n)

  • SiWx917 SoC development boards or kits. See the Check Prerequisites > Hardware section on the Starting in SoC Mode page.

  • Windows/Linux/MacOS computer with a USB port

  • Type C USB cable compatible with the computer's USB port (for e.g., type C to type A if the computer has a type A USB port).

Setup Software#

You may setup the following software in this section while waiting to receive the hardware:

Install Simplicity Studio#

  1. Download the latest version of Simplicity Studio and follow the installation instructions. During the installation:

    • make sure you log in to Simplicity Studio in the Installation Manager window,

    • select Install by technology type, and

    • select the WiSeConnect extension under 32-bit and Wireless MCUs.

    Select WiSeConnect 3 ExtensionSelect WiSeConnect 3 Extension

Install the GNU ARM v12.2.1 Toolchain#

Note: From v4.4.0 on, Gecko SDK (GSDK) requires v12.2.1 of the GNU ARM toolchain to compile a project successfully. Follow the instructions in this section to install this toolchain version and configure it for your new projects.

  1. Log in to Simplicity Studio if not already done.

  2. In the Simplicity Studio home page, select Install > Manage installed packages.

    Manage Installed PackagesManage Installed Packages

  3. Select the Toolchains tab.

  4. Click Install next to GNU ARM Toolchain (v12.2.rel1.xxxx.x) - 12.2.yyyy, where xxxx.x and yyyy may vary depending on the toolchain minor or patch version.

    Install GNU ARM Toolchain 12.2.1Install GNU ARM Toolchain 12.2.1

  5. The toolchain will be installed.

  6. Close the Installation Manager window.

  7. Click Preferences.

  8. Expand the Simplicity Studio section in the Preferences dialog and select the Toolchains section.

  9. Select GNU ARM v12.2.1 and un-select all other toolchains shown.

  10. Click Apply and Close.

    Select the GNU ARM v12.2.1 toolchainSelect the GNU ARM v12.2.1 toolchain

Note: If you have an existing project, see Silicon Labs community page for instructions to configure the toolchain version in your project.

Install the WiSeConnect 3 Extension#

If you already selected the WiSeConnect extension in the Install Simplicity Studio section, you may skip this section.

Before installing the WiSeConnect 3 extension, upgrade to a compatible GSDK version if not already done. See the Prerequisites section for the supported GSDK versions.

You may install WiSeConnect 3 through one of the following alternative paths:

Install WiSeConnect 3 through the Installation Manager#

  1. Log in to Simplicity Studio if not already done.

  2. In the Simplicity Studio home page, select Install > Manage installed packages.

    Manage Installed PackagesManage Installed Packages

  3. Select the SDKs tab.

  4. Next to the WiSeConnect - 3.x.x extension, click Install.

    Install from the SDKs TabInstall from the SDKs Tab

Install WiSeConnect 3 through the Manage SDKs Window#

Note: You must have the hardware available before using these steps to install the WiSeConnect 3 extension.

  1. Download the WiSeConnect v3.x source code from the following URL after substituting 3.x.x with the desired release version:

    https://github.com/SiliconLabs/wiseconnect/archive/refs/tags/v3.x.x.zip
    • If you don't know your release version, go to the GitHub Releases Page and select the version to download.

  2. Unzip the downloaded wiseconnect-3.x.x.zip file. It will be extracted into a folder structure similar to the following:

    wiseconnect-3.x.x
    |--- wiseconnect-3.x.x
    |------ <source code>
  3. Launch Simplicity Studio and log in.

  4. Connect the SiWx91x to your computer.

  5. In the Debug Adapters pane, select your radio board.

  6. In the General Information section, click Manage SDKs.

    Click the Manage SDKs butttonClick the Manage SDKs buttton

  7. The Preferences window will be opened in the SDKs section.

  8. Select Gecko SDK Suite vx.x.x and click Add Extension.

    Add ExtensionAdd Extension

  9. In the Add SDK Extensions window, click Browse.

    Click the Browse buttonClick the Browse button

  10. Locate and select the wiseconnect-3.x.x sub-folder extracted in step 2 above which contains the source code.

  11. Studio will detect the WiSeConnect 3 SDK extension.

  12. Select the detected extension and click OK.

    Add SDK Extensions WindowAdd SDK Extensions Window

  13. If a Verify SDK Extension popup is displayed, click Trust.

    Click the Trust buttonClick the Trust button

  14. The selected WiSeConnect 3 extension will be displayed.

  15. Click Apply and Close.

    Selected ExtensionSelected Extension

Connect SiWx91x to Computer#

  1. Connect the WPK board to your computer using a USB cable.

    Hardware ConnectionHardware Connection

  2. Simplicity Studio will detect and display your radio board.

    Detect BoardDetect Board

Troubleshoot a Board Detection Failure#

If Simplicity Studio does not detect your radio board, try the following:

  • In the Debug Adapters pane, Click the Refresh button (having an icon of two looping arrows).

  • Press the RESET button on the WPK board.

  • Power-cycle your device by disconnecting and reconnecting the USB cable.

Upgrade SiWx91x Connectivity Firmware#

Note: The flash memory map has been modified with WiSeConnect SDK v3.1.1. If you have an older radio board, you must migrate to the new memory map before flashing any firmware. Please follow the SiWG917 – TA Flash Memory Map Change Guide to perform a migration.

We recommend that you upgrade the SiWx917 connectivity firmware to the latest available version when:

  • you first receive an SiWx917 Pro kit

  • you first receive a radio board, or

  • you upgrade to a new version of the WiSeConnect 3 extension

  1. In the Simplicity Studio home page, click Tools.

  2. In the Tools dialog, select Simplicity Commander and click OK.

    Select CommanderSelect Commander

  3. In the Simplicity Commander window, click Select Kit and choose your radio board.

    Select KitSelect Kit

  4. In the navigation pane, go to the Flash section.

  5. Click Browse next to the Binary File field.

    Select the Flash OptionSelect the Flash Option

  6. Locate and select the firmware file to flash from within the connectivity_firmware sub-folder of the WiSeConnect 3 extension path.

    Note:

    • If you don't see any files in the sub-folder, select All files in the file filter field in the Browse dialog.

    • The WiSeConnect 3 extension path is the one where the extension was downloaded during installation. If you're not sure what the path is, you may refer to the location in the Preferences > SDKs page shown on clicking Manage SDKs.

    Click the Manage SDKs butttonClick the Manage SDKs buttton

    Selected ExtensionSelected Extension

  7. Click Flash.

    Click the Flash buttonClick the Flash button

  8. The firmware will be flashed and the Log Window will display the message: "Flashing completed successfully!"

Troubleshoot Firmware Update Failure#

If the firmware update fails, try the following:

  • Toggle the power switch towards AEM (Advanced Energy Monitoring) on the WPK board

  • Try the following steps:

    • Press and hold the ISP button on the radio board.

    • Press and release the RESET button on the WPK board.

    • Release the ISP button on the radio board.

    • In the Flash section in step 5 above, click Erase chip.

    • The flash will be erased.

    • Press the RESET button on the WPK again.

    • Retry the firmware upgrade.

  • In case studio failed to detect your board, see the Troubleshoot a Board Detection Failure section.

Create Project#

  1. Log in to Simplicity Studio and connect the SiWx91x to your computer.

  2. Go to the Debug Adapters section.

  3. Select your radio board from the displayed list.

  4. The Launcher page will display the selected radio board's details.

  5. Select the OVERVIEW tab.

  6. Verify the following in the General Information section:

    • The Debug Mode is Onboard Device (MCU).

    • The Preferred SDK is the version you selected earlier.

      Verify General InformationVerify General Information

  7. Select the EXAMPLE PROJECTS AND DEMOS tab.

  8. Locate the example you want and click CREATE.

    Select ExampleSelect Example

  9. In the New Project Wizard window, click FINISH.

    Click FinishClick Finish

Configure an Application#

Configure the settings for your example. For Wi-Fi - STATION PING (SOC) (the recommended example for this guide) or for other examples, see the Application Build Environment section in the README page for configuration instructions.

You may use the Component Editor to configure the components in your example.

Build an Application#

  1. Launch Simplicity Studio and log in.

  2. In the Project Explorer pane, right-click the project name and select Build Project.

    • You may also click the Build button with a hammer icon on the Simplicity IDE perspective toolbar.

      Select Build OptionSelect Build Option

Flash an Application#

Note: The SiWx91x SoC comes pre-flashed with a bootloader. A bootloader image does not need to be flashed separately.

Note: The flash memory map has been modified with WiSeConnect SDK v3.1.1. If you have an older radio board, you must migrate to the new memory map before flashing any firmware. Please follow the SiWG917 – TA Flash Memory Map Change Guide to perform a migration.

There are two alternative methods to flash an application to the application processor of the SiWx91x device:

Once you flash the Wi-Fi - STATION PING (SOC) example (the recommended example for this guide), you may refer to the Test the Application section of its README page to explore its output. The other sections of the README like the Purpose/Scope section and Overview section (not present in some README's) provide more information about the example.

See the Examples page to explore all available examples and view their README pages.

Flash an Application Built Using Simplicity Studio#

  1. Build the application as described in the Build an Application section.

  2. In the Project Explorer pane, right-click on your project name and select Run As > 1 Silicon Labs ARM Program.

    Flash ApplicationFlash Application

  3. The application binary will be flashed on the radio board and the application will start running.

  4. View the standard output or enter input data as needed. See the Console Input and Output section.

Note: See the troubleshooting section in case the application fails to flash.

Flash an Application Binary#

  1. If the binary was built as described in the Build an Application section, a file with a .rps extension is generated. This file will be available under GNU ARM vXX.x.x - Default in the users workspace. To see its location in your computer's file system, right-click on the .rps file and select Show In > System Explorer.

    • Alternatively, you may have obtained a .rps file through another means such as someone else building and providing the binary to you.

      M4 rpsM4 rps

  2. The instructions to flash the application binary are almost the same as those for flashing an SiWx91x firmware file, except for the point noted below:

    • Instead of choosing the SiWx91x firmware file, select the .rps you obtained in step 1 above.

    Note: If you don't see .rps files in the sub-folder, select All files in the file filter field in the Browse dialog.

    Browse the fileBrowse the file

Troubleshoot an Application Flash Failure#

The application may fail to flash for one of the following reasons:

  • Error code 102 is displayed in the logs, indicating that ISP mode is enabled. Try the following steps:

    • Press and hold the ISP button on the radio board.

    • Press and release the RESET button on the WPK board.

    • Release the ISP button on the radio board.

    • Retry flashing the application.

  • "Could not connect debugger. Could not connect to target device" is displayed in the logs, indicating that the application processor is in a low power state with no flash access. Try the same steps as those described above for error 102.

  • Unknown reason - try re-launching Simplicity Studio.

  • For additional tips, see the Troubleshoot Firmware Update Failure section. Follow the suggested steps and then, instead of retrying the connectivity firmware update, retry flashing the application.

Configure the Debugger#

Note: Application debugging currently does not work. This is a known issue and has two alternative workarounds:

Configure the Simplicity Studio Debugger#

  1. Open Simplicity Studio.

  2. Click Preferences.

  3. In the Preferences window, select Simplicity Studio > Debuggers.

  4. Select Simplicity Studio Debugger and click Apply.

  5. Click Apply and Close.

    Select Simplicity Studio DebuggerSelect Simplicity Studio Debugger

Configure the GDB Debugger#

  1. In the Project Explorer pane, right-click on your project name and select Debug As > 1 Silicon Labs ARM Program.

  2. Studio will switch to debug mode and fail to halt execution at main() as described in the debugging section.

  3. Close the Debug pane.

  4. In the Project Explorer pane, right-click on your project name and select Debug As > Debug Configurations.

    Select Debug ConfigurationsSelect Debug Configurations

  5. Under GDB SEGGER J-Link Debugging, select your project name.

  6. Select the Startup tab.

  7. Unselect the Set breakpoint at field.

  8. Click Apply and click Debug.

    Debug ConfigurationsDebug Configurations

Debug an Application#

  1. In the Project Explorer pane, select your project name.

  2. From the menu, select Run > Debug As > 1 Silicon Labs ARM Program.

    Switch to Debug ModeSwitch to Debug Mode

  3. Studio will switch to debug mode and halt execution at the main() function in your application.

  4. Add a break point in the desired location of the code and click the Resume button (having an icon with a rectangular bar and play button).

  5. Execution will halt at the break point.

  6. Use the following debug functions to direct the execution of the code:

    • Step In button (having an icon with a arrow pointing between two dots).

    • Step Over button (having an icon with an arrow going over a dot).

    • Step Out button (having an icon with an arrow pointing out from between two dots).

      Debug OptionsDebug Options

  7. View the standard output or enter input data as needed. See the Console Input and Output section.

Troubleshoot an Application Debug Failure#

The application may fail to enter the debug mode due to one of the following reasons:

  • Studio failed to halt execution at the main() function. Perform the following steps before trying again:

    • Click the Suspend button (having a pause button icon).

    • Click the Reset button (having an icon of a play button with an arrow underneath).

      Reset DebugReset Debug

    • Retry debugging the application.

  • For additional tips, see the Troubleshoot an Application Flash Failure section. Follow the suggested steps and then, instead of retrying the flashing of the application, retry debugging the application.

Console Input and Output#

  1. Connect your WPK board to your computer.

  2. Open Simplicity Studio.

  3. In the Debug Adapters pane, select your WPK board.

  4. The Adapter FW field shows your WPK board's current firmware version, similar to 1vnpxxbyyy, where n is the major version, xx is the patch version number and yyy is the build number.

  5. Click Update to 1.4.xx.yyyy if the version is before 1v4p10b215, or in other words:

    • Major version = 4 and one of the following is true:

      • patch < 10 or

      • patch = 10 and build < 215

    Upgrade WPK FirmwareUpgrade WPK Firmware

  6. The firmware will be upgraded on your WPK board.

  7. In the Debug Adapters pane, right-click on your radio board and click Launch Console.

    Launch ConsoleLaunch Console

  8. Select the Serial 1 tab.

  9. Place the cursor inside the text input field and hit Enter.

  10. Console output will start getting displayed in the Serial 1 tab.

    Serial 1 Tab for Console OutputSerial 1 Tab for Console Output

  11. Console input can be entered and sent to the device.

    Serial 1 Tab for Console InputSerial 1 Tab for Console Input

Customize Application Components#

Simplicity Studio allows you to add or remove functional components in your application, such as BSD Sockets.

Note: For information about the functional components available with WiSeConnect SDK v3.x, see the Application Components section.

Add a Component#

  1. In the Project Explorer pane, double-click the project_name.slcp file.

  2. Select the SOFTWARE COMPONENTS tab.

  3. Select the SDK Extensions filter.

  4. Browse or search for and select the component that you want to install.

  5. Click Install.

    Install ComponentInstall Component

    Note: Image is for illustration only. Component details shown may be outdated.

  6. Studio will add the component and display a success message.

    Component Added SuccessfullyComponent Added Successfully

    Note: Image is for illustration only. Component details shown may be outdated.

    Note: You may use the Component Editor to configure a component after adding it or to configure other components in your example.

Remove a Component#

  1. View the list of WiSeConnect 3 extension components by following steps 1-3 of the previous section.

  2. Select the Installed filter to view the components you have installed.

  3. Browse or search for and select the component you want to remove.

  4. Select the component and click Uninstall.

    Uninstall ComponentUninstall Component

    Note: Image is for illustration only. Component details shown may be outdated.