Sona IF and Sterling LWBx Software Integration Guide

  1. Introduction
    1. Terminology
    2. Scope
    3. Cautions and Warnings
    4. Build Host Linux Distribution and Version
  2. Module Overview
    1. Sona IF513
    2. Sona IF573
    3. Sterling LWB+
    4. Sterling LWB5+
    5. Sterling LWB
    6. Sterling LWB5
  3. IFX Radio Stack Software
    1. Obtaining Source and Firmware
    2. Backports
    3. Firmware
    4. Supplicant
  4. Regulatory Compliance
    1. Regulatory Domain Configuration
  5. Host Interface Dependencies
    1. Power On Reset
    2. Sona IF series SDIO Power Supply Restrictions
    3. Sterling LWB5 and LWB5+ SDIO Power Supply Restrictions
    4. SDIO Slot Power Management
    5. SUSCLK / Sleep Clock
    6. Sona IF513 and IF573 Bluetooth Interface Requirements
  6. Runtime Validation
  7. Yocto Integration
  8. Compatibility Issues
    1. Sterling LWB5+
Sona IF573Sterling-LWBSterling-LWB+Sterling-LWB5Sterling-LWB5+

Introduction

This document details the software integration requirements for the Sona IF and Sterling LWBx series radios. Specific integration steps will vary based on the host platform architecture and build system, but the basic integration requirements are common to all platforms. Many platforms use Yocto as the build system, and this document also provides a usage overview for the Ezurio Yocto layer.

Terminology

The following terminology is applicable to this document:

Product Description Web Page
Sona IF573 CYW55573 based radio module Product Page
Sona IF513 CYW55513 based radio module Product Page
Sterling LWB+ CYW43439 based radio module Product Page
Sterling LWB5+ CYW4373E based radio module Product Page
Sterling LWB CYW4343w based radio module Product Page
Sterling LWB5 CYW43353 (a.k.a CYW4339A0) based radio module Product Page
Sona IF series Generic reference to any of IF573/IF513
Sterling LWBx series Generic reference to any of LWB+/LWB5+/LWB/LWB5

Scope

The scope of this document is limited to providing integration requirements for the Sona IF and Sterling LWBx series radios and a usage overview of the Ezurio Yocto layer that supports them. It is assumed the reader has an understanding of Linux and building Linux software using the build system employed for the host platform on which these radios are utilized.

Cautions and Warnings

Adhere to all cautions and warnings included with all materials. The Sona IF and Sterling LWBx series radios and DVKs can be damaged by electrostatic discharge (ESD); handle accordingly.

Build Host Linux Distribution and Version

This guide was produced using a build host running Ubuntu 22.04. While it is possible to use a different version of Ubuntu or an entirely different Linux distribution, doing so may require a different procedure. Build hosts running distributions other than Ubuntu 22.04 are beyond the scope of this document.

Module Overview

The Sona IF and Sterling LWBx series consists of six different radios, with varying form factors and interfaces.

Sona IF513

The Sona IF513 is a tri-band a/b/g/n/ac/ax Wi-Fi 6E + BT 5.4 1x1 SISO radio based on the Infineon AIROC™ CYW55513 chipset. It is offered as a solder-down M.2 1216 module with MHF4 antenna connector(s) or as a pluggable 2230 M.2 E-Key module with MHF4 antenna connector(s). The Sona IF513 supports an SDIO host interface for Wi-Fi and a UART interface for Bluetooth. A development kit is available with all interfaces brought to convenient headers.

Note: The Sona IF513 M.2 module comes in two variants that differ in antenna configuration based on how the integrated Sona IF513 module is populated. Be sure to correctly identify which M.2 variant you have.

Sona IF573

The Sona IF573 is a tri-band a/b/g/n/ac/ax Wi-Fi 6E + BT 5.4 2x2 MIMO radio based on the Cypress CYW55573 chipset. It is offered as a solder down M.2 1318 module with MHF4 antenna connectors or trace pins as well as a pluggable 2230 M.2 E-Key module with MHF4 antenna connectors. The Sona IF573 supports either PCIe or SDIO host interface for Wi-Fi and a UART interface for Bluetooth. A development kit is available with all interfaces brought to convenient headers.

Note: The Sona IF573 M.2 module comes in two variants that differ in supported host interface based on how the integrated Sona IF573 module is populated. Be sure to correctly identify which M.2 variant you have (SDIO/UART or PCIe/UART) as integration requirements are different.

Sterling LWB+

The Sterling LWB+ is a 2.4GHz b/g/n Wi-Fi + BT 5.2 SISO radio based on the Cypress CYW43439 chipset. It is offered as a solder down module with integrated chip antenna or antenna connector, a pluggable 2230 M.2 E-Key module with MHF4 antenna connector, and as a SIP without the front-end antenna circuitry. The Sterling LWB+ supports an SDIO 2.0 host interface for Wi-Fi and a UART interface for Bluetooth. A development kit is available consisting of the LWB+ module mounted to a carrier board with a full size SDIO interface, and all available interfaces brought to convenient headers.

Sterling LWB5+

The Sterling LWB5+ is a dual band a/b/g/n/ac Wi-Fi + BT 5.0 SISO radio based on the Cypress CYW4373E chipset. It is offered as a solder down module with integrated chip antenna or antenna connector, an M.2 module with integrated antenna connectors supporting antenna diversity, and as a pluggable USB adapter. The Sterling LWB5+ supports an SDIO 3.0 host interface for Wi-Fi and a UART interface for Bluetooth, or a shared USB host interface that supports both Wi-Fi and Bluetooth. Multiple development kits are available for the LWB5+ including a module based kit that supports all host interfaces and power supply configurations, as well as an M.2 development kit supporting either the SDIO/UART or USB/USB M.2 variants.

Note: The LWB5+ M.2 module comes in two variants that differ in supported host interface based on how the integrated LWB5+ module is populated. Be sure to correctly identify which M.2 variant you have (SDIO/UART or USB/USB) as integration requirements are different.

Sterling LWB

The Sterling LWB is a 2.4GHz b/g/n Wi-Fi + BT 4.2 SISO radio based on the Cypress 4343W chipset. It is offered as a solder down module with integrated chip antenna or antenna connector, as well as a SIP without the front-end antenna circuitry. The Sterling LWB supports an SDIO 2.0 host interface for Wi-Fi and a UART interface for Bluetooth. A development kit is available consisting of the LWB module mounted to a carrier board with a full size SDIO interface, and all available interfaces brought to convenient headers.

Sterling LWB5

The Sterling LWB5 is a dual band a/b/g/n/ac Wi-Fi + BT 4.2 SISO radio based on the Cypress CYW43353 chipset. It is offered as a solder down module with integrated chip antenna or antenna connector, as well as a SIP without the front-end antenna circuitry. The Sterling LWB5 supports an SDIO 3.0 host interface for Wi-Fi and a UART interface for Bluetooth. A development kit is available consisting of the LWB5 module mounted to a carrier board with a full size SDIO interface, and all available interfaces brought to convenient headers.

IFX Radio Stack Software

Ezurio provides a backports package, firmware package and supplicant package to support the Sona IF and Sterling LWBx series radios. The backports and supplicant packages are common to all Sona IF and Sterling LWBx series radios. Multiple firmware packages are provided as they depend on radio type, interface, antenna configuration and regulatory domain.

Obtaining Source and Firmware

The source for the backports and supplicant packages are available at our public facing GitHub repository. Firmware packages are also available at this location.

The Ezurio Yocto layer supporting the Sona IF and Sterling LWBx series radios is available on GitHub. Checkout the branch with name corresponding to the radio release version.

Backports

The backports package contains the kernel components needed to support the Sona IF and Sterling LWBx series radios. These include the brcmfmac Wi-Fi driver, the cfg80211 driver, the Bluetooth kernel subsystem and bluetooth drivers. The backports package is created based on the latest Ezurio-supported kernel. The backports package supports the use of customer platforms using earlier kernel versions.

The set of components required from backports is specified in a defconfig file. The backports package includes a set of reference defconfigs for the various radios the backports package can support. These files are located in the defconfigs subdirectory in the root of the backports package. The Sona IF and Sterling LWBx series radios use the lwb reference defconfig.

The kernel components included in the backports package must be the ones that are used on the target platform. Components built into the base kernel will take precedence over corresponding components from the backports package. Therefore it is important to ensure that these components are not marked as built-in ('y') in the base kernel configuration.

  • Wireless device drivers located at Device Drivers/Network device support/Wireless LAN
  • cfg80211 located at Networking support/Wireless
  • Bluetooth core and drivers located at Networking support/Bluetooth subsystem support

Kernel versions 5.19 and higher must include cfg80211 as a module (m) in the base platform kernel configuration. It must not be left out, and must not be included as built-in (y).

  • Networking support->Wireless->cfg80211 - wireless configuration API

Note: The backports package is a subset of kernel components that have been "backported" to earlier kernel versions. It does not include all dependencies needed for operation. Any dependencies must still be provided by the base kernel configuration for full functionality. In particular, the Bluetooth subsystem has dependencies on a number of crypto modules such as CRYPTO_ECDH. These must be explicitly included in the base kernel configuration if they are not already brought in as a dependency of another base kernel component. See the Help for the Bluetooth subsystem support in the Linux kernel menuconfig for a list of the items that are normally selected; these components must be explicitly included if necessary.

The procedure for building the backports package will depend on your build system. Ultimately it involves setting environment variables to specify the target Linux version, CPU architecture and cross compiler. The .config file is built from the desired defconfig, and then the binaries are built. See the following for an example:

set -a
CROSS_COMPILE=${CROSS_COMPILE}
ARCH=${TARGET_CPU}
KLIB_BUILD=${DEV_PATH}/${LINUX_DIR}
set +a
make defconfig-lwb
make

This is handled automatically by the Ezurio Yocto layer for those using the Yocto build system.

The backports build process will produce the following binaries that are needed to support the Wi-Fi subsystem on the Sona IF and Sterling LWBx series radios:

brcmfmac.ko ------ at ./drivers/net/wireless/broadcom/brcm80211/brcmfmac/
brcmfmac-cyw.ko -- at ./drivers/net/wireless/broadcom/brcm80211/brcmfmac/cyw/
brcmutil.ko ------ at ./drivers/net/wireless/broadcom/brcm80211/brcmutil/
cfg80211.ko ------ at ./net/wireless/
compat.ko -------- at ./compat/

The following binaries are needed to support the Bluetooth subsystem on the Sterling LWBx series radios (depending on selected host interface):

bluetooth.ko ----- at ./net/bluetooth/
hci_uart.ko ------ at ./drivers/bluetooth/
btusb.ko --------- at ./drivers/bluetooth/
btbcm.ko --------- at ./drivers/bluetooth/
compat.ko -------- at ./compat/

Verify these binaries are present on the target platform to confirm the backports build process completed successfully.

Firmware

The Sona IF and Sterling LWBx series firmware packages contain radio firmware, power tables and other low level configuration needed for Wi-Fi and Bluetooth radio functionality. The LWB and LWB5 firmware packages are pre-configured for operation in specific regulatory regions. The Sona IF series/LWB+/LWB5+ firmware packages are not pre-configured for specific regulatory domains, but there are multiple IF series and LWB5+ firmware packages depending on the radio variant. The correct firmware package must be used and the correct regulatory domain must be implemented.

The firmware packages are provided in a compressed tar file that must be extracted to the root file system of the target device. The tar file contains the path information for each file; Sona IF series firmware files will be located in /lib/firmware/cypress. Sterling LWBx firmware files will be located in /lib/firmware/brcm. Several files may be soft links to other files for easier maintenance. It is essential that these names and locations be maintained. The file extraction is handled automatically by the Ezurio Yocto layer for those using the Yocto build system.

Verify the firmware package contents are present on the target platform in the correct location to confirm the firmware portion of the build process completed successfully.

Sterling LWB5+ Firmware Variants

The Sterling LWB5+ supports multiple host interfaces as well as multiple antenna configurations. Each combination of host interface and antenna configuration requires a unique firmware package. The hardware design will determine which host interface and antenna configuration is required.

The LWB5+ firmware package names include the host interface and antenna configuration. The host interface could be either SDIO/UART (Wi-Fi on SDIO, Bluetooth on UART) or USB/USB (both Wi-Fi and Bluetooth on USB). The firmware naming convention uses the Wi-Fi portion of the host interface so an SDIO firmware variant targets an LWB5+ strapped for SDIO/UART while a USB firmware variant targets an LWB5+ strapped for USB/USB operation. The antenna configuration portion of the firmware name is either Single Antenna (abbreviated 'sa' in the package name) or Diversity Antenna (abbreviated 'div' in the package name).

Note: Diversity Antenna means the hardware design implements two physical antennas, although only one will be operating at a time. Single Antenna means the hardware design implements a single physical antenna. Both LWB5+ M.2 module variants (SDIO/UART and USB/USB) implement antenna diversity and support the Diversity Antenna package. The LWB5+ solder-down modules with integrated chip antenna or antenna connector are Single Antenna configurations. The LWB5+ USB dongle has an integrated chip antenna and is a USB/USB Single Antenna design.

Note: The LWB5+ M.2 module can also be used in a single antenna configuration if desired. To do so, the antenna must be installed in ANT0 connector; the ANT1 connector can be left open. The firmware package containing the 'sa-m2' suffix must be used for this configuration.

IF513 Firmware Variants

The IF513 supports single antenna or diversity antenna configurations. Each antenna configuration has a firmware package. The hardware design will determine which antenna configuration is required.

Supplicant

Supplicant & Network Manager

Ezurio provides the Summit supplicant and Network Manager in source code as part of the Sona IF and Sterling LWBx series radio stack. The Summit supplicant is an enhanced version of the open source wpa_supplicant and contains functionality needed to support some features of the Sona IF and Sterling LWBx series radios. The Summit supplicant is required for full functionality.

Network Manager is an optional component that handles network configuration at a high level. Ezurio has extended Network Manager to support additional wireless client and AP configuration options in the Summit supplicant.

Building and installing the supplicant and Network Manager is beyond the scope of this document. This is handled automatically by the Ezurio Yocto layer for those using the Yocto build system.

Regulatory Compliance

Regulatory Domain Configuration

The OEM must configure the regulatory domain on the host platform either with a brcmfmac module parameter or a device tree setting. All radios support using host platform configuration to determine regulatory domain. The LWB and LWB5 also support regulatory domain specific firmware packages, but these packages will be overridden by host platform configuration if the host platform configuration exists. The Sona IF series and Sterling LWB+/LWB5+ regulatory domain must be set on the host platform; the driver will fail to load if the configuration is not present.

Note: Firmware contains region specific regulatory settings for channel support, maximum power levels etc. It is essential that the correct regulatory domain is implemented based on the regulatory region where the target platform will operate. There is no support for a "World Wide" configuration that is valid in multiple regulatory regions. Failure to configure the correct regulatory domain will cause the radio to be out of compliance with regulatory requirements. This is a condition of using the Ezurio modular certification.

Note: Regulatory requirements prohibit allowing any entity, including a professional installer, OEM representative or end user to change any setting that would cause the radio to operate in a non-compliant manner. The target platform must be secured against attempts to change the regulatory configuration to a different region. This is a condition of using the Ezurio modular certification.

See per-radio regulatory release notes for the regulatory domains and country code settings that are supported for each radio. The LWB and LWB5 firmware packages include the regulatory domain code in the firmware package name. The country code value is used for host platform configuration via module parameter or device tree setting.

Module Parameter Configuration

The Sona IF and Sterling LWBx series radios support regulatory domain configuration using a brcmfmac module parameter. The module parameter is called 'regdomain', and it takes a country code string. The string must be one of the values listed as a Country Code in the per-radio regulatory release notes for the radio (or 'ETSI' for use in EU countries), and can only be used if the radio type in use supports that country. Module parameter configuration is the easiest to implement however it may not be secure from end user modification. Device tree configuration is preferred and will override the module parameter if both are present.

# Sample contents of a brcmfmac.conf file configured for operation in 
# the United States
options brcmfmac regdomain="US"

Device Tree Configuration

The Sona IF and Sterling LWBx series radios support regulatory domain configuration using the device tree. The configuration must be located in the device tree node corresponding to the Wi-Fi portion of the radio. The node path will vary based on host platform architecture. The node must contain the standard brcmfmac 'compatible' property. The regulatory domain is configured with a new property called 'laird,regdomain'. This property must be set to one of the values listed as a Country Code in the per-radio regulatory release notes for the radio (or 'ETSI' for use in EU countries). The string can only be used if the radio type in use supports that country. Device tree configuration is the preferred mechanism because it is secure against end user modification. Device tree configuration will override module parameter configuration as well as firmware package configuration (relevant for LWB/LWB5 only).

# Sample device tree node for an SDIO/UART Sona IF573 module configured for
# operation in the United States
# Note that the compatible string must be "brcm,bcm4329-fmac"
#
# Note that the node address (reg) must be <1>, which is the SDIO Wi-Fi
# function number

&usdhc1 {
    #address-cells = <1>;
    #size-cells = <0>;

    brcmf_sdio: wifi@1 {
        reg = <1>;
        compatible = "brcm,bcm4329-fmac";
        laird,regdomain = "US";
    };
};
# Sample device tree node for a PCIE/UART Sona IF573 module configured for
# operation in the United States
# Note that the compatible string must be "brcm,bcm4329-fmac"

&pcie {
    pcie@0 {
        reg = <0x0000 0 0 0 0>;
        #address-cells = <3>;
        #size-cells = <2>;

    brcmf_pcie: wifi@1 {
        reg = <0x000000 0 0 0 0>;
        compatible = "brcm,bcm4329-fmac";
        laird,regdomain = "US";
        };
    };
};

Host Interface Dependencies

Power On Reset

The Sona IF and Sterling LWBx series radios expose signals (WL_REG_ON and BT_REG_ON) that enable regulator circuitry internal to the chipset. The Wi-Fi and Bluetooth functionality respectively will be disabled if these signals are at a low state.

  • These signals are pulled low by default on the Sterling LWB/LWB5/LWB+ radios, so they must be driven high by the host platform in order for the radio to function.
  • These signals are pulled high by default on the Sterling LWB5+, so the Wi-Fi and Bluetooth radios will be enabled by default when power is applied.
  • The Sona IF573 pulls the WL_REG_ON and BT_REG_ON (W_DISABLE#/W_DISABLE2#) signals high on the M.2 2230 card and leaves them pulled low on the M.2 1318 solder down module. However, the BT_REG_ON (WL_DISABLE2#) signal MUST be controlled by host platform GPIO under software control.
  • The Sona IF513 leaves the WL_REG_ON and BT_REG_ON (W_DISABLE#/W_DISABLE2#) signals pulled low on both the M.2 2230 card and the M.2 1216 solder down module. The WL_REG_ON and BT_REG_ON (W_DISABLE#/W_DISABLE2#) signals MUST be controlled by host platform GPIO under software control. Otherwise, the card will not function. Additionally, the SDIO_DATA2 line must be high when the first of either WL_REG_ON or BT_REG_ON signals transitions from low to high. This would be a problem, for example, if a pull-up were used on either the W_DISABLE# or W_DISABLE2# line and the SDIO_DATA2 line was pulled low, even briefly, by the processor during startup.
  • The Sterling LWB+ SDIO_DATA2 line must be high when the first of either WL_REG_ON or BT_REG_ON signals transitions from low to high. The radio module has an internal 10k Ohm pull-up on the line, however, care should be taken to insure the host isn't loading this line when the first of either WL_REG_ON or BT_REG_ON signals transitions from low to high.

Note: Ezurio recommends controlling the WL_REG_ON and BT_REG_ON (WL_DISABLE#/WL_DISABLE2#) signals using host GPIO in all cases. This guarantees that the module can be reset as needed to handle foreseen and unforeseen use cases. In addition, the Sona IF513 and IF573 require host GPIO control over the BT_REG_ON/WL_DISABLE2# signal. It is not possible to support Bluetooth on the Sona IF513 or IF573 without it.

Note: There is requirement to delay an absolute minimum of 150 milliseconds after power supplies are stable AND the WL_REG_ON and/or BT_REG_ON signals are asserted before the host platform can perform the first access across the interface. This is due to an internal Power On Reset that is performed when these signals are asserted. We recommend waiting 250 milliseconds after signal assertion before allowing the first host access to ensure the internal reset sequence has completed.

Sona IF series SDIO Power Supply Restrictions

The Sona IF series SDIO interfaces operate at 1.8V only. The host platform SDIO interface must operate at 1.8V at all times, including during bus enumeration.

Sterling LWB5 and LWB5+ SDIO Power Supply Restrictions

The Sterling LWB5 and LWB5+ have an SDIO3.0 interface that can operate at 1.8V to support UHS-1 speed modes. The actual voltage that is used by the radio interface is the VDDIO power supply on the radio module. The host SDIO voltage level must match the VDDIO power supply on the Sterling LWB5/LWB5+ at all times for the interface to function properly.

It is possible for the host platform to dynamically move from 3.3V to 1.8V as the SDIO interface is enumerated and the radio capabilities are discovered. If the host platform does change voltage, that same dynamic voltage supply must be supplied to the VDDIO pins on the Sterling LWB5/LWB5+. If the VDDIO pins on the Sterling LWB5/LWB5+ are held at a fixed voltage, then the host platform is also required to stay at that same voltage.

This issue primarily occurs on Sterling LWB5/LWB5+ development kits where the VDDIO rail is configurable, but fixed to a specific level. If used with an SDIO3.0+ capable host via an SDIO slot, then it is likely the host interface will attempt to enumerate the radio at 3.3V and then switch to 1.8V as part of changing to a higher UHS-1 speed mode. If the VDDIO supply on the radio is fixed at 3.3V, then the host must be prevented from switching to 1.8V after enumeration. This is typically done by setting the "no-1-8-v" property in the SDIO controller device tree, and results in the controller staying in SDIO 2.0 compliant mode (Full Speed or High Speed support only).

Note: The VDDIO power supply on the Sterling LWB5+ SDIO/UART M.2 module is fixed at 1.8V. Therefore the host platform SDIO interface must operate at 1.8V at all times, including during bus enumeration.

If the VDDIO supply on the radio matches the VDDIO supply on the host, there are no additional software considerations related to bus voltage.

SDIO Slot Power Management

The brcmfmac driver will aggressively go to a low power mode during periods of inactivity. While in this low power state it will not respond to most SDIO bus accesses. This is normally not a problem because most SDIO bus accesses are initiated by the brcmfmac driver which will first bring the radio back out of the low power state. However, the SDIO host stack will also do a direct bus access using a SELECT command in cases where the host stack needs to determine if the device is still present. If that bus access occurs when the radio happens to be in a low power state the bus access will fail causing the SDIO host driver to determine there is no device present. This may result in the host stack attempting to power cycle the slot. This is most likely to occur at platform resume if the slot is configured to keep power in suspend.

The host stack will not attempt to query the slot in this way if the slot is marked as non-removable. If this is necessary it is done with the "non-removable" entry in the SDIO controller device tree node.

SUSCLK / Sleep Clock

As detailed in the integration guides, for Sona IF and Sterling LWBx radios, SUSCLK / 32.768 kHz Sleep Clock is an externally supplied clock that is mandatory any time the radio is not held in reset. If this clock is not supplied when the radio is enumerated on the host bus, errors WILL occur.

Sona IF513 and IF573 Bluetooth Interface Requirements

The Sona IF513 and IF573 Bluetooth cores implement a secure firmware download protocol that requires the radio core to be placed into a special 'autobaud' mode. Bluetooth firmware download is only supported in autobaud mode. Autobaud mode is entered when the CTS input on the radio is in the asserted (low) state when BT_REG_ON is asserted (W_DISABLE2# de-asserted), bringing the Bluetooth core out of reset. This requires that there is host GPIO control over the BT_REG_ON/W_DISABLE2# signal. This is complicated by the fact that the H4 protocol implemented on the Bluetooth UART requires hardware handshaking for reliable communications.

The hciattach/btattach user mode daemons that have traditionally been used to manage Bluetooth serial interfaces can not be used with the Sona IF513 and IF573. These utilities do not have the capability to sequence the BT_REG_ON/WL_DISABLE2# and CTS signals to place the radio into the autobaud mode to perform firmware download. Instead, the Bluetooth serial interface on the Sona IF513/IF573 should be managed using the serial device bus (serdev) interface available in kernel 4.12 and later. The host GPIO used to control BT_REG_ON/WL_DISABLE2# is specified in the serdev bluetooth binding along with other properties.

Here is a sample device tree binding that configures the Sona IF513/IF573 Bluetooth interface for an iMX8MP-EVK board that uses a GPIO pin on an I2C expander to control BT_REG_ON/WL_DISABLE2#. 

&uart1 {
  bluetooth {
      compatible = "infineon,cyw55572-bt";
      brcm,requires-autobaud-mode;
      max-speed = <921600>;
      # shutdown-gpios defines the pin that controls BT_REG_ON
      # A logical 1 is used to power on the radio
      shutdown-gpios = <&pca6416 7 GPIO_ACTIVE_HIGH>;
    };
};

Note the following essential elements:

  • a 'bluetooth' subnode is created in the uart node.
    • This causes the UART to be managed as a bluetooth serdev client instead of tty device
  • The 'compatible' property is set to "infineon,cyw55572-bt"
  • The 'brcm,requires-autobaud-mode' property is defined
  • 'shutdown-gpios' specifies the GPIO pin used to control BT_REG_ON/WL_DISABLE2#
    • GPIO name is misleading - a logical '1' is used to power on the radio and must result in the gpio going high

Runtime Validation

The Linux kernel will automatically load the Wi-Fi and Bluetooth drivers when they are using the PCIe, SDIO or USB interfaces. These are client drivers and the corresponding bus driver on the host will enumerate the interface and load the proper client driver. Bluetooth will also load automatically on a UART interface if serdev is used and the interface is properly configured in the device tree.

The Bluetooth interface on the Sona IF and Sterling LWBx series radios require support from a user mode application if serdev is not used. The UART must be attached to the Bluetooth stack HCI interface with the correct parameters to communicate with the radio and allow the Bluetooth firmware to be downloaded.

Ezurio recommends the BlueZ Bluetooth stack which includes the user mode helper applications needed for initialization. The 'btattach' command can be used to start the Bluetooth serial interface. The correct port must be identified and used in the command, as well as the 'bcm' protocol as shown in the following example:

/usr/bin/btattach -B /dev/ttyS1 -P bcm &

Note: The Sterling LWB5+ DVKs expose the Bluetooth serial uart over USB via an FTDI USB/UART bridge chip. The host platform must include the ftdi_sio driver if this interface is used. The corresponding port in this case will typically be /dev/ttyUSB0.

Note: There is much documentation online referencing the legacy hciattach and hciconfig utilities that were used with the legacy BlueZ stack (version 4). These utilities are not compatible with the Bluetooth core in modern kernels and can not be used with Ezurio software. The BlueZ5 stack must be used, along with the btattach and bluetoothctl utilities that it provides.

Note: The secure firmware download mechanism in the Sona IF573 is not compatible with the btattach utility. Designs using the Sona IF573 that require Bluetooth should use serdev to manage the Bluetooth UART interface. It is possible to use the brcm_patchram_plus utility available from Ezurio together with a platform specific script if serdev can not be used. This should be limited to platforms using kernels prior to v4.12. Contact Ezurio for details if this is needed.

Platform integration can be validated by checking to see if the Wi-Fi and Bluetooth interfaces are available. Low level Wi-Fi interface management is best done using the 'iw' tool. All wireless devices known to the platform can be shown with the 'iw dev' command. If the wireless device appears in the list then it has been properly integrated:

# iw dev
phy#0
    Unnamed/non-netdev interface
        wdev 0x2
        addr b2:fb:15:81:7f:d2
        type P2P-device
        txpower 31.00 dBm
    Interface wlan0
        ifindex 5
        wdev 0x1
        addr b0:fb:15:81:7f:d2
        type managed
        channel 1 (2412 MHz), width: 20 MHz, center1: 2412 MHz
        txpower 31.00 dBm

Low level Bluetooth interface management can be done using the 'bluetoothctl' command. All Bluetooth devices known to the platform can be listed with the 'bluetoothctl list' command. If the Bluetooth device appears in the list then it has been properly integrated:

# bluetoothctl list
Controller B0:FB:15:81:7F:D3 summit [default]

Yocto Integration

Ezurio provides a Yocto layer that includes support for the Sona IF and Sterling LWBx series radios. Platforms that use the Yocto build system can use this layer to do much of the integration automatically. This section gives a brief overview of the steps needed to include and use this layer. Please see the README file in the meta-summit-radio layer for more specific details.

The Ezurio Yocto layer is available on gitHub. Clone or copy this into your project sources directory.

Note: The default Github branch contains only a README file listing the branches that should be used for each radio release version. Be sure to use the branch corresponding to the radio release.

cd /my_project/sources/
git clone https://github.com/Ezurio/meta-summit-radio
git checkout <lrd-a.b.0.x>

The meta-summit-radio layer must be referenced in the conf/bblayers.conf file to be recognized by the build system. Due to a breaking syntax change in bitbake introduced in Yocto 3.4, the meta-summit-radio layer has two implementations. Add the appropriate line to your conf/bblayers.conf file depending on your version of Yocto:

BBLAYERS += "${BSPDIR}/sources/meta-summit-radio/meta-summit-radio"
OR
BBLAYERS += "${BSPDIR}/sources/meta-summit-radio/meta-summit-radio-pre-3.4"

Set the preferred provider for the wpa_supplicant to the Summit supplicant by appending the following lines to the build's conf/local.conf file:

PREFERRED_RPROVIDER_wpa-supplicant = "summit-supplicant-lwb-if"
PREFERRED_RPROVIDER_wpa-supplicant-cli = "summit-supplicant-lwb-if-cli"
PREFERRED_RPROVIDER_wpa-supplicant-passphrase = "summit-supplicant-lwb-if-passphrase"

The Ezurio Yocto layer includes support for the 60 Series radios as well. The 60 Series packages are providers for the wireless-regdb-static package. However, that is only valid when using a 60 Series radio. The PREFERRED_RPROVIDER for wireless-regdb-static should be set to the upstream component when using Sona IF series or Sterling LWBx series radios.

PREFERRED_RPROVIDER_wireless-regdb-static = "wireless-regdb"

Add the backports, firmware, supplicant and any other desired packages to your bitbake image recipe. Be sure to select the firmware version that corresponds to your design. You may only select one firmware package per image.

IMAGE_INSTALL:append = " kernel-module-lwb-if-backports"
IMAGE_INSTALL:append = " summit-supplicant-lwb-if"

# Select firmware package as needed
IMAGE_INSTALL:append = " if573-pcie-firmware"
#IMAGE_INSTALL:append = " if573-sdio-firmware"

#IMAGE_INSTALL:append = " if513-sdio-div-firmware"
#IMAGE_INSTALL:append = " if513-sdio-sa-firmware"

#IMAGE_INSTALL:append = " lwb5plus-sdio-div-firmware"
#IMAGE_INSTALL:append = " lwb5plus-sdio-sa-firmware"
#IMAGE_INSTALL:append = " lwb5plus-sdio-sa-m2-firmware"
#IMAGE_INSTALL:append = " lwb5plus-usb-div-firmware"
#IMAGE_INSTALL:append = " lwb5plus-usb-sa-firmware"
#IMAGE_INSTALL:append = " lwb5plus-usb-sa-m2-firmware"

#IMAGE_INSTALL:append = " lwbplus-firmware"

Warning: Do not use the IMAGE_INSTALL += "xxx" syntax in your conf/local.conf file to add components to your image. If you use the conf/local.conf file instead of modifying an image recipe, use the append syntax above (or the older syntax for Yocto versions prior to 3.4). Use of 'IMAGE_INSTALL +=' syntax in conf/local.conf can cause subtle issues in the final image that can be very difficult to debug.

Note: The Yocto layer includes a mechanism to configure the regulatory domain using the module parameter mechanism discussed previously. It can be implemented by setting the LWB_REGDOMAIN variable to the required country code listed as a Country Code in the per-radio regulatory release notes for the radio in the build's conf/local.conf file as shown below. This will create a brcmfmac.conf file in /etc/modprobe.d containing the specified country code in the regdomain module parameter. 

LWB_REGDOMAIN = "US"

Note: You do not need to use this mechanism to specify the regulatory domain. You could choose to implement it using a device tree setting or configure the module parameter some other way. However, the regulatory domain must be configured in some manner or the driver will fail to load.

Configure your kernel to ensure compatibility with the backports package, specifically ensuring that the wireless and Bluetooth subsystems are not built-in to the kernel. See the Backports section for details:

bitbake -c menuconfig virtual/kernel

Now you can bake your final image:

bitbake <image name>

Compatibility Issues

Sterling LWB5+

libmtp

libmtp is a library implementation of Microsoft's Media Transfer Protocol for USB media players and phones, for the Linux operating system.

libmtp automatically probes USB devices in certain device classes, and this probing action can interfere with the download of firmware to the LWB5+ radios when configured for the USB interface. If libmtp is to be installed on your device, you may need to blacklist the LWB5+ in the libmtp udev rules to prevent firmware download failure.

This can be done by adding the following lines to /lib/udev/rules.d/69-libmtp.rules on your target device:

# Exclude Ezurio LWB5+ radio
ATTR{idVendor}=="04b4", ATTR{idProduct}=="bd29", GOTO="libmtp_rules_end"

When libmtp interferes with the download of device firmware via USB, this generally manifests as a brcmfmac driver kernel message containing Unknown chip BCM57005 and a firmware download failure.