Software Integration Guide - Sona TI351

  1. Introduction
    1. Scope
    2. Cautions and Warnings
    3. Build Host Linux Distribution and Version
  2. Host Interface Dependencies
    1. Power On Reset
    2. Power Supply Restrictions
    3. In-band vs Out Of Band Interrupts
    4. Wake On Wireless
    5. HOST_IRQ_WL State at Boot
    6. UART Hardware Handshaking Requirements
  3. Ezurio Connectivity Stack Software
    1. Obtaining Source and Firmware
    2. Backports
    3. Firmware
    4. Supplicant
  4. Sona TI Device Tree Configuration
    1. Requirements
    2. Sample Device Tree
  5. Regulatory Compliance
    1. Regulatory Domain Configuration
  6. Yocto Integration
  7. Buildroot Integration
    1. Installation
    2. Configuration
  8. Runtime Validation
Sona TI351

Introduction

This document details the software integration requirements for the Sona TI351 radio module. 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 or Buildroot as the build system, and Ezurio supports both of these build systems.

Scope

The scope of this document is limited to providing integration requirements for the Sona TI351 radio and a usage overview of the Ezurio Yocto layer and Buildroot br2-external tree that supports it. 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 this radio is utilized.

Cautions and Warnings

Adhere to all cautions and warnings included with all materials. The Sona TI351 radio and DVK 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.

Host Interface Dependencies

Power On Reset

The W_DISABLE1# pin on the Sona TI351 drives the radio reset input. This signal must be controlled by the host platform GPIO.

Power Supply Restrictions

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

In-band vs Out Of Band Interrupts

The Sona TI351 supports either in-band (SDIO controller) interrupt or Out Of Band (GPIO) interrupts. If using GPIO-based Out Of Band interrupts the interrupt should be configured as LEVEL sensitive. If the host CPU is not able to support LEVEL sensitive interrupts, in-band must be used.

If using Out Of Band interrupts, the polarity differs between M.2 1216 and M.2 2230 modules. The M.2 1216 variant uses the HOST_IRQ_WL pin and the signal is active high. The M.2 2230 variant uses the SDIO_WAKE# signal and is active low.

Wake On Wireless

The SDIO_WAKE#/HOST_IRQ_WL signal is used to implement Wake On Wireless and must be implemented if Wake On Wireless is desired. Wake On Wireless requires using the Out Of Band (GPIO) interrupt architecture.

The SDIO_WAKE#/HOST_IRQ_WL signal does not need to be implemented if Wake On Wireless is not required.

HOST_IRQ_WL State at Boot

The SDIO_WAKE#/HOST_IRQ_WL pin on the Sona TI351 M.2 1216 solder down module is internally directly connected to the HOST_IRQ_WL pin on the CC3351. This is a SenseOnPower pin that is pulled low internally and must be low when the device powers up. It must not be pulled high or driven high by the host platform. If this cannot be guaranteed, the signal must be buffered.

The Sona TI351 M.2 2230 plugin module buffers this signal before exposing it as SDIO_WAKE# so it does not have the same restriction.

UART Hardware Handshaking Requirements

The UART interface requires RTS/CTS hardware handshaking.

In addition, the UART on the host must immediately stop transmitting when RTS is asserted. If the host sends even one byte after RTS is asserted the firmware will hang unless low level power management is disabled in TI351 firmware. Some UART controllers are unable to meet this requirement.

The UART used on FTDI serial/USB converters is known to be unable to meet this requirement.

Low level power management can be disabled by writing a '0' to the 'sleep_auth' parameter in the cc33xx debugfs interface prior to enabling Bluetooth. This step is required if using FTDI serial/USB converters or any other UART that cannot meet this requirement.

Ezurio Connectivity Stack Software

The Sona TI351 is supported by the Ezurio Connectivity Stack. The Connectivity Stack includes the backports, firmware, supplicant and Network Manager packages.

The Connectivity Stack also includes a Yocto integration layer and a Buildroot br2-external tree that handle much of the integration for users of these systems.

Obtaining Source and Firmware

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

The Yocto layer and Buildroot br2-external tree supporting the Sona TI351 are available on Github at meta-summit-radio and summit-radio-external respectively. Platforms using these build systems should use these layers to download, build and install the Connectivity Stack components. See Yocto Integration and Buildroot Integration for more details.

Backports

The backports package contains the kernel components needed to support the Sona TI351 radio. These include the cc33xx 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 TI351 radio uses the sona_ti 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-sona_ti
make

This is handled automatically by the Ezurio Yocto layer and Buildroot br2-external tree for those using these build systems.

The backports build process will produce the following binaries that are needed to support the Wi-Fi subsystem on the Sona TI351 radio:

cc33xx.ko -------- at ./drivers/net/wireless/ti/cc33xx/
cc33xx_sdio.ko --- at ./drivers/net/wireless/ti/cc33xx/
mac80211 --------- at ./net/mac80211/
cfg80211.ko ------ at ./net/wireless/
compat.ko -------- at ./compat/

The following binaries are needed to support the Bluetooth subsystem on the Sona TI351 radio:

bluetooth.ko ----- at ./net/bluetooth/
btti_uart.ko ----- at ./drivers/bluetooth/
hci_uart.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 publicly available Sona TI351 WW (World Wide) firmware package contains radio firmware, power tables and other low level configuration needed for Wi-Fi and Bluetooth radio functionality. This package is compliant in all regions supported by the Sona TI351. See the Regulatory Release notes for a list of countries supported. Optimized country specific firmware packages are available on request. Contact Ezurio if you need optimized support for a specific country.

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 TI351 firmware files will be located in /lib/firmware/ti-connectivity. 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 and Buildroot br2-external tree for those using these build systems.

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.

Supplicant

Supplicant & Network Manager

Ezurio provides the Summit supplicant and Network Manager in source code as part of the Ezurio Connectivity Stack. The Summit supplicant is an enhanced version of the open source wpa_supplicant. 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 and Buildroot br2-external tree for those using these build systems.

Sona TI Device Tree Configuration

Requirements

The Sona TI351 requires proper configuration in the device tree. The following points must be observed:

  • The SDIO host controller node must contain a sub-node for the TI351 Wi-Fi function (function number 2)
  • The SDIO host controller node should enable run-time PM with the cap-power-off-card property
  • The SDIO host controller should limit operation to SD3.0 only (max 50MHz)
  • The SDIO host controller driver should control the W_DISABLE# pin using a device tree regulator referenced by the vmmc-supply property.
    • The regulator should not be configured with the regulator-always-on property because the driver will toggle it in some scenarios
  • The Bluetooth serdev driver, if used, must reference the same device tree regulator used by the Wi-Fi function.

The SDIO interrupt can either be in-band or out of band (OOB) using the SDIO_WAKE#/HOST_IRQ_WL signal. If Wake On Wireless is desired, then the interrupt must be out of band using the HOST_IRQ_WL/SDIO_WAKE# signal. The HOST_IRQ_WL signal is the interrupt output from the M.2 1216 module and is active high. It is inverted on the M.2 2230 carrier board for compliance with the M.2 specification and is exposed on the M.2 2230 module as the active low SDIO_WAKE#.

Sample Device Tree

Here is a sample device tree section demonstrating the above requirements using an M.2 2230 module and OOB interrupt. In this example host GPIO2_6 is connected to the W_DISABLE# pin and host GPIO2_9 is used for SDIO interrupt via SDIO_WAKE#. The interrupt is active low because this is the M.2 2230 module. If this had been the M.2 1216 module the interrupt would be HOST_IRQ_WL and would be active high.

The driver will use the in-band SDIO interrupt if the interrupt properties are not included in the device tree.

/ {
    reg_usdhc1_vmmc: regulator-usdhc1 {
        compatible = "regulator-fixed";
        regulator-name = "WLAN_EN";
        pinctrl-names = "default";
        pinctrl-0 = <&pinctrl_reg_usdhc1_vmmc>;
        regulator-min-microvolt = <3300000>;
        regulator-max-microvolt = <3300000>;
        gpio = <&gpio2 6 GPIO_ACTIVE_HIGH>;
        enable-active-high;
    };
};

&usdhc1 {
    vmmc-supply = <&reg_usdhc1_vmmc>;
    max-frequency = <50000000>;
    cap-power-off-card;

    #address-cells = <1>;
    #size-cells = <0>;

    wlcore: wlcore@2 {
        compatible = "ti,cc33xx";
        reg = <2>;

        // OOB IRQ support if needed
        interrupt-parent = <&gpio2>;
        interrupts = <9 IRQ_TYPE_LEVEL_LOW>;
    };
};

A reference device tree snippet with essential elements to support Bluetooth serdev operation is shown below. Note the following:

  • A 'bluetooth' subnode is created in the uart node used to communicate with the Sona TI351. This causes the UART to be managed as a bluetooth serdev client instead of a tty device.
  • The 'compatible' property is set to "ti,cc33xx-bt"
  • The cc33xx-supply property references the same regulator used by the SDIO host controller.
&uart1 {
    bluetooth {
        compatible = "ti,cc33xx-bt";
        cc33xx-supply = <&reg_usdhc1_vmmc>;
        max-speed = <115200>;
    };
};

Regulatory Compliance

Regulatory Domain Configuration

The Sona TI351 is compliant with regulatory requirements in many countries, and holds modular certification in some of them. The parameters needed for compliance are contained in the firmware package. Ezurio provides a World Wide firmware package that is configured to be compliant in all supported countries. See the Regulatory Release notes for the list of supported countries and the channels supported in each of them.

Please contact Ezurio if optimized support for a specific country is required.

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.

Yocto Integration

Ezurio provides a Yocto layer that includes support for the Sona TI radio. 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. The example below checks out the lrd-13.24.0.x branch, which supports the 13.24.0.20 release.

cd /my_project/sources/
git clone https://github.com/Ezurio/meta-summit-radio -b lrd-13.24.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_PROVIDER_wpa-supplicant = "summit-supplicant"
PREFERRED_RPROVIDER_wpa-supplicant = "summit-supplicant"
PREFERRED_RPROVIDER_wpa-supplicant-cli = "summit-supplicant"
PREFERRED_RPROVIDER_wpa-supplicant-passphrase = "summit-supplicant"

Add the backports, firmware, supplicant and any other desired packages to your Yocto image recipe.

IMAGE_INSTALL:append = " kernel-module-ti-backports"
IMAGE_INSTALL:append = " summit-supplicant"
IMAGE_INSTALL:append = " ti351-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.

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>

Buildroot Integration

Ezurio provides a Buildroot br2-external tree that includes support for the Sona TI351 radio. Platforms that use the Buildroot build system can use this br2-external tree to do much of the integration automatically. This section gives a brief overview of the steps needed to include and use this tree.

Basic familiarity with Buildroot is assumed.

Installation

The Ezurio Buildroot br2-external tree is called summit-radio-external and is available on gitHub at summit-radio-external. Clone or copy this into your project directory alongside your main buildroot directory.

Note: Be sure to specify the branch corresponding to the Ezurio Connectivity Stack release version. The example below checks out the lrd-13.24.0.x branch, which supports the 13.24.0.20 release.

cd /my_project/
git clone https://github.com/Ezurio/summit-radio-external -b lrd-13.24.0.x

The summit-radio-external br2-external tree must be added to your buildroot configuration using the BR2_EXTERNAL make variable. There are several ways this could be done, depending on whether you have other br2-external trees. In most cases, you can specify it as part of any call to make and the value will be preserved for future calls to make.

For example:

make BR2_EXTERNAL=$PWD/summit-radio-external <your_defconfig>-menuconfig

If you have multiple br2-external trees in your project, specify all of them in a colon deliminated list.

Configuration

Once installed, run the Buildroot menuconfig command to configure the Ezurio Connectivity Stack for the Sona TI351.

make BR2_EXTERNAL=$PWD/summit-radio-external <your_defconfig>-menuconfig

The Ezurio Connectivity Stack components are available at External options ---> Summit Radio Configuration. Support can be added using a pre-configured Radio Stack Bundle or by adding the components individually. The Core Sona TI351 Radio Stack Bundle is the preferred mechanism and automatically includes the Summit backports, Summit supplicant and hostapd and Summit NetworkManager by default. These components can be individually configured as necessary.

Note: The Sona TI351 radio firmware component must be manually configured.

  • Select Radio Stack Bundles
  • Select Core Sona TI Radio Stack Bundle
  • Select Summit Radio Firmware
  • Select Sona TI Radio Firmware
  • Select the desired Sona TI351 firmware package.

Note: Only the World Wide firmware package is publicly available. Contact Ezurio if you need support for optimized country specific firmware packages.

The backports package contains the following in-tree defconfig files pre-configured for the Sona TI351:

defconfig Description
sona_ti Sona TI351 support for Wi-Fi and Bluetooth
sona_ti_nbt Sona TI351 support for Wi-Fi only

The Sona TI351 Radio Stack Bundle will default the backports configuration using one of these defconfigs depending on the presence of the BlueZ stack in the buildroot configuration. The backports defconfig can be verified (or changed) at Summit Linux Backports / Wi-Fi & Bluetooth drivers ---> Backports defconfig name

Note: The Radio Stack Bundles enable Connectivity Stack components by default, if they are not otherwise configured. Once a component is disabled, it is configured and the Radio Stack Bundle logic will not re-enable it. If the Summit supplicant, hostapd and Summit Network Manager have been previously disabled the Radio Stack Bundle will not enable them.

Save the Buildroot configuration after the Ezurio Connectivity Stack has been configured. Update the defconfig file to preserve the changes.

make <your_defconfig>-savedefconfig

Note: You may need to manually save the resulting defconfig file to in your configs directory.

See the buildroot documentation for more details.

Runtime Validation

The Linux kernel will automatically load the Wi-Fi driver as long as the device tree is configured properly.

The Bluetooth interface requires support from a user mode application because it must be enabled via the wifi interface. If using serdev no further initialization is needed. Otherwise btattach (assuming BlueZ Bluetooth stack) is needed to create the HCI interface.

The following user-mode script can be used to start Bluetooth when using either serdev or btattach. This script assumes the tty interface corresponding to the Bluetooth serial port is /dev/ttymxc0. Modify this port as necessary for your platform.

#!/bin/sh

PHY=`ls /sys/class/ieee80211/`

echo "1" > /sys/kernel/debug/ieee80211/$PHY/cc33xx/ble_enable

if [ -c /dev/ttymxc0 ]; then
  sleep 1
  btattach -B /dev/ttymxc0 -P h4 &
fi

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.

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
        Interface wlan0
                ifindex 3
                wdev 0x1
                addr e8:cb:f5:80:00:42
                type managed
                multicast TXQ:
                        qsz-byt qsz-pkt flows   drops   marks   overlmt hashcol tx-bytes        tx-packets
                        0       0       0       0       0       0       0       0               0

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 E8:CB:F5:80:00:43 summit [default]