Low Power Assist

group index

Overview

Power consumption is a key operational factor for embedded devices. The Low Power Assistant (LPA) allows you to configure a PSoC 6 MCU and WLAN (Wi-Fi / BT Radio) device to provide low-power features. This framework presents a unified, low-overhead, user-friendly way to configure, connect, and operate within multiple tasks / cases.

The key points for LPA include:

  • Applies to MCU, Wi-Fi, and BT

  • This is for RTOS-oriented applications (FreeRTOS, Mbed OS, Amazon FreeRTOS).

  • Only the configuration is required; no functions should be called in runtime. Once the LPA middleware is configured, it is transparent to the application. Application code changes are not needed and the application runs as normal.

  • There are different flows:

    • ModusToolbox Device Configurator Flow.

    • Manual Configuration Flow.

Features

There are various use cases for the LPA covered in the following sections. The LPA allows you to configure different parts of your design to be energy efficient.

  • Part 1. MCU Low Power Provides the integration between the low-power firmware and the IoT framework (most notably, the RTOS) used in the system to be energy efficient.

  • Part 2. Wi-Fi Low Power

    • Wi-Fi Host-wake Signal Provides a way for a WLAN device to wake up the Host MCU from its low-power state.

    • Wi-Fi Address Resolution Protocol (ARP) Offload Improves the power consumption of your connected system by reducing the time the Host needs to stay awake due to ARP broadcast traffic. In general, the ARP Offload reduces broadcast traffic.

    • Wi-Fi Packet Filter Offload Allows the host processor to limit which types of packets get passed up to the host processor from the WLAN subsystem. This is useful to keep out unwanted/unneeded packets from the network that might otherwise wake up the host out of a power saving Deep Sleep mode, or prevent it from entering Deep Sleep mode.

    • Wi-Fi TCP Keep Alive Offload Improves the power consumption of your Host MCU by offloading TCP Keepalive to WLAN Firmware

  • Part 3. Bluetooth Low Power Configures BT low-power features that enable the host to achieve its lowest power function. It also configures the wake host interrupt signal (device to host) and related device integration.

The listed capabilities make the LPA middleware useful for a variety of applications, including automotive, IoT, and industrial.

The LPA middleware provides an easy way to make the low-power features of Cypress devices available to developers in the form of a portable configuration layer. LPA consists of the following components:

  • One of these components is a configurator tool (using a personality), which makes the low-power features of the system easy to use (ModusToolbox Device Configurator Tool Guide). This personality writes data structures that are processed by firmware and implement the choices made in the personality.

  • This firmware is another component of the LPA feature. The firmware is used at system initialization and does not require user interaction.

  • A small firmware module provides the integration between the low-power firmware and the IoT framework (most notably the RTOS) used in the system. This final piece of firmware will be part of the IoT framework you are using.

Getting Started

The LPA middleware can be used in various software environments including Mbed OS, FreeRTOS and Amazon FreeRTOS. The quickest way to get started is by using the Code Examples. Cypress Semiconductor continuously extends its portfolio of code examples at the Cypress Semiconductor website and at the Cypress Semiconductor GitHub website. The following Quick Start Guide sections describe several use cases for using the LPA features:

  • MCU Low Power Quick Start Guide

  • Wi-Fi Host Wake Signal Quick Start Guide

  • Wi-Fi Address Resolution Protocol (ARP) Offload Quick Start Guide

  • Wi-Fi Packet Filter Offload Quick Start Guide

  • Wi-Fi TCP Keepalive Offload Quick Start Guide

  • Bluetooth Low Power Quick Start Guide

Refer to the Supported Software and Tools section for compatibility information.

Refer to the Changelog for the differences between the Middleware versions.

The LPA efficiency for several use cases is included in the Performance Data section.

For more details about LPA and ModusToolbox, refer to the More Information section.

Prerequisites

  • A development environment configured for Mbed OS/ FreeRTOS. Refer to the Supported Software and Tools section for the required Mbed OS / FreeRTOS / Amazon FreeRTOS version.

  • Availability of the CY8CKIT-062S2-43012 pioneer kit (or other kits that supports PSoC 6 power consumption measurement).

    The CY8CKIT-062S2-43012 kit is recommended, since this section documents measurement instructions for this kit. If other kit is used, refer to its documentation and learn how to measure current consumed.

  • For Only Mbed OS, Execute below command for CY8CKIT-062S2-43012 first time 

    python -m pip install --upgrade pip
pip install mbed-ls --upgrade
mbedls -m 190B:CY8CKIT_062S2_43012

  • DC Power Monitor or Ammeter.

Definitions

This section lists definitions used throughout this document.

Acronym/Term

Definition

Remark

AP

Access Point

Wireless Access Point connection for the Device (e.g., Wireless Router).

ARP

Address Resolution Protocol

ARP is a procedure for mapping a dynamic Internet Protocol (IP) address to a permanent physical machine address in a local area network (LAN).

TKO

TCP Keepalive Offload

BT

Bluetooth

Bluetooth is a wireless technology standard.

Device

WLAN Device

The Wi-Fi and/or BT radio module (WLAN Processor).

Host

Host Processor

The Host (or Application) processor (e.g., PSoC 6).

LPA

Low Power Assistant

OLM

Offload Manager

OOB

Out-Of-Band

Configurator

Cypress Configuration Tool

Configurators are a set of powerful but intuitive tools that work together to set up various MCU features. Each Configurator generates very readable, user-modifiable firmware to initialize the whole device with a single function call. Refer to ModusToolBox

Personality

Information File

Personalities are files that define how resources are used by a Configurator. The Low Power Assistant functionality is embedded in the Device Configurator as a personality.

SDIO

Secure Digital Input / Output

WLAN

Wireless Local Area Network

WLAN means any wireless local area network no matter what technology is used and Wi-Fi is a type of WLAN that follows the IEEE 802.11 standards

AFR

Amazon FreeRTOS

MTB

ModusToolbox

Refer to ModusToolBox

Part 1. MCU Low Power

The MCU low-power feature allows you to take advantage of the power saving features of a PSoC MCU simply by configuring a few parameters. Using the MCU low-power feature, you can configure the system to achieve maximum power savings during system idling or to establish maximum performance by operating only in Active power mode. This feature works in conjunction with real time operating systems (RTOS), such as Mbed OS.

There are two parameters available: System Idle Power Mode and Deep Sleep Latency.

The System Idle Power Mode parameter defines the power state that the MCU needs to enter automatically any time the system is idle. Setting it to Active power mode disables power saving and allows the system to perform tasks with less intervention, since there are no transitions to / from CPU Sleep / System Deep Sleep states.

The Deep Sleep Latency parameter controls if the desired deep sleep time is larger than needed to perform a transition from System Deep Sleep to Active power mode to perform tasks.

Quick Start Guide

This section provides step-by-step instructions for how to use the MCU Low Power feature with Mbed OS , FreeRTOS and Amazon FreeRTOS, as well as its impact on the device power consumption.

Perform the following steps to evaluate the device power consumption with different MCU Low Power configurations:

MBEDOS

  1. Import the mbed-os-example-blinky example project and switch to the example directory: 

    mbed import mbed-os-example-blinky
cd mbed-os-example-blinky

  2. Set the desired System Idle Power mode (DeepSleep, Sleep or Active). In Mbed OS, the System Idle Power mode is set to Deep Sleep by default to achieve the best power saving. This step can be done by using the ModusToolbox Device Configurator or by manually updating the code.

    • MCU Low power using the ModusToolbox Device Configurator Refer to ModusToolbox Device Configurator Flow

    • MCU Low power Manual configuration Refer to Manual Configuration Flow

  3. update the main.cpp file with below change to change LED ON time to 5secs along with Psoc Wake setting during LED On state 

    #include "mbed.h"
#include "platform/mbed_thread.h"

// Blinking rate in milliseconds
#define BLINKING_RATE_MS        5000

int main()
{
    // Initialise the digital pin LED1 as an output
    DigitalOut led(LED1);
    while (true) {
       // Turn on the onboard Led to indicate the thread Active state.
      led = 0;

      // The Cy_SysLib_Delay() implements a loop that blocks further
      // code execution for the specified period of time.
      // This call is used to keep the thread in the Active state long enough
      // to evaluate the PSoC power consumption in the Active state.
      Cy_SysLib_Delay(BLINKING_RATE_MS);

      // Turn off the onboard LED to indicate thread Idle state.
      led = 1;

      // Put the thread into the Idle state to evaluate the PSoC power
      // consumption in the configured System Idle Power mode state.
      thread_sleep_for(BLINKING_RATE_MS);
   }
}

  4. Build the project and program the board. The following command is example for the CY8CKIT_062S2_43012 board, using GCC_ARM as the toolchain: 

    mbed compile -DMBED_TICKLESS --target CY8CKIT_062S2_43012 --toolchain GCC_ARM --flash

    Note If you cannot program the board, make sure the board DAP-Link mode is selected. Refer to the guide of your kit of how to change the mode.

  5. Check the board operation. Refer to the How to Measure Power Consumption section for corresponding instructions. Observe the power consumption in different states of the main thread (Active, Idle). The illuminated user LED indicates the Active state.The non-illuminated LED indicates the Idle state. The duration of Active/Idle states can be adjusted by changing the BLINKING_RATE_MS macro value in the main.cpp file. Refer to the following picture for an example of the DC Power Analyzer output:

    i. PSoC6 Active state current average Note High Active current is due to PSoC running in LP mode at high system clock frequency and other peripherals are active.

    ../../../_images/mod_blinky_active_inv1.jpg

    ii. PSoC6 Deep Sleep state current average

    ../../../_images/mod_blinky_sleep_inv1.jpg

FREERTOS

  1. Checkout empty app and add FreeRTOS library 

    git clone https://github.com/cypresssemiconductorco/mtb-example-psoc6-empty-app.git
cd mtb-example-psoc6-empty-app

  2. Add below files to deps folder for CY8CKIT_062S2_43012 

    # MTB2.1 and lib approach

abstraction-rtos.lib :  https://github.com/cypresssemiconductorco/abstraction-rtos/#latest-v1.X
TARGET_CY8CKIT-062S2-43012.lib : https://github.com/cypresssemiconductorco/TARGET_CY8CKIT-062S2-43012/#latest-v2.X
freertos.lib : https://github.com/cypresssemiconductorco/freertos/#latest-v10.X

# MTB2.2 and .mtb approach
echo https://github.com/cypresssemiconductorco/TARGET_CY8CKIT-062S2-43012#latest-v2.X#\$\$ASSET_REPO\$\$/TARGET_CY8CKIT-062S2-43012/latest-v2.X > deps/TARGET_CY8CKIT-062S2-43012.mtb
echo https://github.com/cypresssemiconductorco/freertos/#latest-v10.X#\$\$ASSET_REPO\$\$/freertos/latest-v10.X > deps/freertos.mtb

  3. Delete below libs from deps folder 

    deps/TARGET_CY8CPROTO-062-4343W.lib

  4. Add attached (FreeRTOSConfig.h) to mtb-example-psoc6-empty-app

    configUSE_TICKLESS_IDLE : This change to support Tickless Deep Sleep mode 

    #include <cycfg_system.h>

#if (CY_CFG_PWR_SYS_IDLE_MODE == CY_CFG_PWR_MODE_SLEEP) || (CY_CFG_PWR_SYS_IDLE_MODE == CY_CFG_PWR_MODE_DEEPSLEEP)
extern void vApplicationSleep( uint32_t xExpectedIdleTime );
#define portSUPPRESS_TICKS_AND_SLEEP( xIdleTime ) vApplicationSleep( xIdleTime )
#define configUSE_TICKLESS_IDLE  2
#endif

#if CY_CFG_PWR_DEEPSLEEP_LATENCY > 0
#define configEXPECTED_IDLE_TIME_BEFORE_SLEEP   CY_CFG_PWR_DEEPSLEEP_LATENCY
#endif

  5. Update Makefile with below changes 

    COMPONENTS=FREERTOS PSOC6HAL LWIP MBEDTLS

# For MTB2.2, below change

CY_GETLIBS_SHARED_PATH=../
CY_GETLIBS_SHARED_NAME=mtb_shared

  6. Set the desired System Idle Power mode (DeepSleep, Sleep or Active). In FreeRTOS, the System Idle Power mode is set to Deep Sleep by default to achieve the best power saving. This step can be done by using the ModusToolbox Device Configurator or by manually updating the code.

    • MCU Low power using the ModusToolbox Device Configurator Refer to ModusToolbox Device Configurator Flow

    • MCU Low power Manual configuration Refer to Manual Configuration Flow

  7. Replace main.c file with below code 

    #include "cy_pdl.h"
#include "cyhal.h"
#include "cybsp.h"
#include "FreeRTOS.h"
#include "task.h"

#define BLINKING_RATE_MS        5000
static void blinky(void *args)
{
    TickType_t ticks = pdMS_TO_TICKS(BLINKING_RATE_MS) ;

    // Initialize the User LED
    cyhal_gpio_init((cyhal_gpio_t) CYBSP_USER_LED, CYHAL_GPIO_DIR_OUTPUT, CYHAL_GPIO_DRIVE_STRONG, CYBSP_LED_STATE_OFF);

    while (true)
    {
        //Turn ON LED
        cyhal_gpio_write((cyhal_gpio_t)CYBSP_USER_LED, false);
        //Add Delay for 5 seconds so that MCU doesnot go to Deep Sleep
        cyhal_system_delay_ms(BLINKING_RATE_MS);
        //Turn OFF LED
        cyhal_gpio_write((cyhal_gpio_t)CYBSP_USER_LED, true);
        vTaskDelay(ticks) ;
    }
}
int main(void)
{
    cy_rslt_t result;

    // Initialize the device and board peripherals
    result = cybsp_init() ;
    if (result != CY_RSLT_SUCCESS)
    {
        CY_ASSERT(0);
    }
    __enable_irq();

    xTaskCreate( blinky, "Blinky Task", 1024*10,  0,  1,  0);
    // Start the FreeRTOS scheduler
    vTaskStartScheduler();
}

  8. Build the project and program the board. The following command is example for the CY8CKIT_062S2_43012 board, using GCC_ARM as the toolchain: 

    make getlibs
make program TARGET=CY8CKIT-062S2-43012 TOOLCHAIN=GCC_ARM

  9. Check the board operation. Refer to the How to Measure Power Consumption How to Measure Power Consumption section for corresponding instructions. Observe the power consumption in different states of the main thread (Active, Idle). The illuminated user LED indicates the Active state.The non-illuminated LED indicates the Idle state. The duration of Active/Idle states can be adjusted by changing the BLINKING_RATE_MS value in the blinky function. Refer to the following picture for an example of the DC Power Analyzer output:

    ../../../_images/FreeRTOS_blinky_current1.png

AFR

  1. Checkout AFR example app 

    git clone https://github.com/cypresssemiconductorco/amazon-freertos.git --recurse-submodules
cd amazon-freertos/projects/cypress/
git clone https://github.com/cypresssemiconductorco/afr-example-wlan-lowpower.git
cd afr-example-wlan-lowpower

  2. Make sure below FreeRTOSConfig.h changes are present (config_files folder):

    configUSE_TICKLESS_IDLE : This change to support Tickless Deep Sleep mode 

    #include <cycfg_system.h>

#if (CY_CFG_PWR_SYS_IDLE_MODE == CY_CFG_PWR_MODE_SLEEP) || (CY_CFG_PWR_SYS_IDLE_MODE == CY_CFG_PWR_MODE_DEEPSLEEP)
extern void vApplicationSleep( uint32_t xExpectedIdleTime );
#define portSUPPRESS_TICKS_AND_SLEEP( xIdleTime ) vApplicationSleep( xIdleTime )
#define configUSE_TICKLESS_IDLE  2
#endif
#if CY_CFG_PWR_DEEPSLEEP_LATENCY > 0
#define configEXPECTED_IDLE_TIME_BEFORE_SLEEP   CY_CFG_PWR_DEEPSLEEP_LATENCY
#endif

  3. Update vApplicationDaemonTaskStartupHook function in main.c file with below code 

    void vApplicationDaemonTaskStartupHook( void )
{
 uint32_t blink_rate = 5000; // LED BLINK RATE in MS
 TickType_t ticks = pdMS_TO_TICKS(blink_rate) ;
    while (true)
    {
        //Turn ON LED
        cyhal_gpio_write((cyhal_gpio_t)CYBSP_USER_LED, false);
        //Add Delay for 5 seconds so that MCU doesnot go to Deep Sleep
        Cy_SysLib_Delay(blink_rate);
        //Turn OFF LED
        cyhal_gpio_write((cyhal_gpio_t)CYBSP_USER_LED, true);
        vTaskDelay(ticks) ;
    }
}

  4. Set the desired System Idle Power mode (DeepSleep, Sleep or Active). In AFR, the System Idle Power mode is set to Deep Sleep by default to achieve the best power saving. This step can be done by using the ModusToolbox Device Configurator or by manually updating the code.

    • MCU Low power using the ModusToolbox Device Configurator Refer to ModusToolbox Device Configurator Flow

    • MCU Low power Manual configuration Refer to Manual Configuration Flow

  5. Build the project using CMake / Make.

    The following command is example for the CY8CKIT_062S2_43012 board, using GCC_ARM as the toolchain:

    CMake 

    cd amazon-freertos/projects/cypress/afr-example-wlan-lowpower
cmake -DVENDOR=cypress -DBOARD=CY8CKIT_062S2_43012 -DCOMPILER=arm-gcc -S . -B build -G Ninja -DCMAKE_TOOLCHAIN_FILE=../../../tools/cmake/toolchains/arm-gcc.cmake
cmake --build build --clean-first

    Make 

    cd amazon-freertos/projects/cypress/afr-example-wlan-lowpower
make build TARGET=CY8CKIT-062S2-43012 TOOLCHAIN=GCC_ARM

  6. Program the board with afr-example-wlan-lowpower.elf file generated under below folder using Cypress Programmer CMake : amazon-freertos/projects/cypress/afr-example-wlan-lowpower/build/ Make : amazon-freertos/build/cy/afr-example-wlan-lowpower/CY8CKIT-062S2-43012/Debug

  7. Check the board operation. Refer to the How to Measure Power Consumption How to Measure Power Consumption section for corresponding instructions. Observe the power consumption in different states of the main thread (Active, Idle). The illuminated user LED indicates the Active state.The non-illuminated LED indicates the Idle state. The duration of Active/Idle states can be adjusted by changing the blink_rate variable in the vApplicationDaemonTaskStartupHook function.

    Refer to the following picture for an example of the DC Power Analyzer output:

    ../../../_images/afr_blinky_current_low1.png

MCU Low Power Configuration Considerations

The following are the different flows to configure LPA middleware:

  • ModusToolbox Device Configurator Flow. Generating the initialization code using the ModusToolbox Device Configurator greatly simplifies configuring the PSoC and enabling the LPA features. The ModusToolbox Device Configurator provides the user interface to set up and automatically generate the initialization code (including analog routing) and configuration structures.

  • Manual Configuration Flow. Manually adding settings into configuration files. Manual implementation of the initialization code (including analog routing) and configuration structures is recommended for expert users only.

Note If you modify the output of the ModusToolbox Device Configurator, you cannot import it back into the tool.

ModusToolbox Device Configurator Flow

  • Mandatory steps to avoid design.modus file modification in checkout repo

    MbedOS

    1. Copy folder mbed-os-example-blinky/mbed-os/targets/TARGET_Cypress/TARGET_PSOC6/TARGET_CY8CKIT_062S2_43012 to mbed-os-example-blinky folder

    2. Delete all files in mbed-os-example-blinky/TARGET_CY8CKIT_062S2_43012 except COMPONENT_BSP_DESIGN_MODUS folder and its contents

    3. Rename mbed-os-example-blinky/TARGET_CY8CKIT_062S2_43012/COMPONENT_BSP_DESIGN_MODUS to mbed-os-example-blinky/TARGET_CY8CKIT_062S2_43012/CUSTOM_BSP_DESIGN_MODUS

    4. Delete design.cyqspi and design.cycapsense file in mbed-os-example-blinky/TARGET_CY8CKIT_062S2_43012/CUSTOM_BSP_DESIGN_MODUS

    5. Add/update mbed_app.json in mbed-os-example-blinky folder with below details (This will tell mbed to ignore the BSP configuration shipped with MbedOS) 

      {
     "target_overrides": {
         "*": {
              "target.components_remove": ["BSP_DESIGN_MODUS"]
         }
     }
 }

    6. If mbed-os branch used is 5.15 or above, please do the below changes as well

      • update mbed_app.json with below line in “target_overrides”: 

        "target.components_add": ["CUSTOM_DESIGN_MODUS"]

    FreeRTOS

    1. Copy contents of folder mtb-example-psoc6-empty-app/libs/TARGET_CY8CKIT-062S2-43012/COMPONENT_BSP_DESIGN_MODUS to mtb-example-psoc6-empty-app/COMPONENT_CUSTOM_DESIGN_MODUS/TARGET_CY8CKIT_062S2_43012 folder

    2. Delete design.cyqspi and design.cycapsense file in mtb-example-psoc6-empty-app/TARGET_CY8CKIT_062S2_43012/CUSTOM_BSP_DESIGN_MODUS

    3. update Makefile in mtb-example-psoc6-empty-app folder with below details (This will tell build to ignore the BSP configuration inside libs folder) 

      COMPONENTS+=CUSTOM_DESIGN_MODUS
DISABLE_COMPONENTS=BSP_DESIGN_MODUS

  • Navigate to the ModusToolbox installation folder and launch the ModusToolbox Device Configurator (<install_dir>/tools_2.2/device-configurator).

  • Select File->Open, navigate to the board’s design.modus file, and open it: MBEDOS: mbed-os-example-blinky/TARGET_CY8CKIT_062S2_43012/CUSTOM_BSP_DESIGN_MODUS/design.modus FreeRTOS: mtb-example-psoc6-empty-app/COMPONENT_CUSTOM_DESIGN_MODUS/TARGET_CY8CKIT_062S2_43012/design.modus AFR: amazon-freertos/projects/cypress/afr-example-wlan-lowpower/COMPONENT_CUSTOM_DESIGN_MODUS/TARGET_CY8CKIT-062S2-43012/design.modus

  • If the design.modus file does not open and pops with a error message No device support library path provided , then point to the psoc6pdl folder inside the mbed-os/targets/TARGET_Cypress/TARGET_PSOC6/psoc6pdl/devicesupport.xml file in the window popup. This is because the design.modus file will update its path to the PDL directory when it is opened for the first time.

  • Select the Host device tab, and then select the System tab for that device.

  • Enable the Power personality (if disabled) and go to the Power Parameters pane to configure the LPA Middleware.

  • Configure RTOS related parameters:

    1. System Idle Power Mode (Active/Sleep/DeepSleep)

    2. Deep Sleep Latency

  • Perform File->Save to generate initialization code.

../../../_images/Power_Personality1.png

After saving the configuration file, the generated code is available under the GeneratedSource folder, located in the same directory as the design.modus file in the BSP:

  • C Data File: GeneratedSource/cycfg_platform.c

  • C Header File: GeneratedSource/cycfg_platform.h

Manual Configuration Flow

Manual configuration is only recommended for experts. To configure the MCU LPA Middleware related parameters not using the ModusToolbox Device Configurator, do the following steps:

  1. Find and open the cycfg_system.h file under …/GeneratedSource/ folder with a text editor.

  2. Configure the System Idle Power Mode parameter value by adding / modifying the following macro with one of the possible options: 

    // Possible options
#define CY_CFG_PWR_MODE_ACTIVE 0x04UL
#define CY_CFG_PWR_MODE_SLEEP 0x08UL
#define CY_CFG_PWR_MODE_DEEPSLEEP 0x10UL
// Selected option
#define CY_CFG_PWR_SYS_IDLE_MODE CY_CFG_PWR_MODE_DEEPSLEEP

  3. Configure the Deep Sleep Latency parameter value by adding / modifying the following macro with a value from a range 0-10: 

    #define CY_CFG_PWR_DEEPSLEEP_LATENCY 0UL

  4. Save changes.

Note Using the ModusToolbox Device Configurator overwrites changes you made in the cycfg_system.h file.

Configuration Parameters

The following parameters and their mapping to macros are available:

Category

Parameter

Description

Parameter values

RTOS

System Idle Power Mode

Selects the lowest power mode the system attempts to enter when there are no active tasks to execute; that is, the system is in idle state. This option only applies to an RTOS based application.

  • System Deep Sleep (default)

  • CPU Sleep

  • Active

RTOS

Deep Sleep Latency (ms)

Selects the greater value among time required to enter in and exit from the Deep Sleep power mode. This option only applies to an RTOS based application.

  • 0 (default)

  • 0-10

Part 2. Wi-Fi Low Power

WLAN FW supports various offloads that continue operations on behalf of the host while the host is asleep. Making the best use of these FW offloads requires proper configuration, as well as coordination with the host OS and host power management systems. Up until now it has been the responsibility of each application developer to realize FW offloads even exist, figure out how to use and configure them, and coordinate with the power management system on the host. The offloads manager (OLM) is responsible for:

  • Encapsulating the configuration, coordination, and knowledge of WLAN offloads into a single, portable, easy-to-use middleware.

  • Providing a consistent means of developing offloads.

  • Providing a platform agnostic configuration and initialization interface.

Integrating WLAN offloads on the host has typically been performed by customers or hard-coded into the WLAN driver. With the introduction of an offload configurator, customers can configure a range of offloads. This configuration is consistent and portable since multiple platforms perform similar steps to integrate any particular offload.

Power consumption is a key operational factor for embedded devices. WLAN offloads play a key role in determining host power consumption since offloads let the host go into System Deep Sleep for extended periods of time while handling things like 802.11 roaming, ARP, IPV6 neighbor resolution, key rotation, TCP keep alive, etc. on behalf of the host.

However, each one of these different offloads needs to be recognized, configured, connected to the power management subsystem, and debugged. Currently, this needs be done by each individual application developer. Due to this high overhead, offloads are often overlooked and therefore power consumption not as low as it could be.

The LPA middleware provides a framework that manages WLAN offloads, reduces the overhead incurred by application developers, and makes our offloads more usable while reducing host power consumption.

The framework:

  • Encapsulates the programming for all low-power offloads it supports. Applications writers don’t need to know these details.

  • Uses the ModusToolbox Device Configurator and personalities to configure:

    • which offloads will get compiled in.

    • parameters for each offload.

  • Each offload has its own set of configured parameters and its own implementation. Offloads do not call functionality contained in another offload.

  • Provides a consistent means of developing offloads.

  • Is adaptable to new offloads being offered by the firmware.

  • Is easily portable new hosts and new architectures. Therefore, the OLM is independent on the platform and network stack.

  • Code efficient:

    • Minimal space: The object code for an offload driver that is never used at run-time is not linked into the program image.

    • Static memory usage: no runtime calls to malloc/free.

  • The framework supports multiple WLAN host driver instances. That is, a collection of offload driver instances and configurations are applied per WLAN host driver instance.

Each offload can be enabled or disabled at build-time.

Wi-Fi Host-wake Signal

Host-wake provides a way for a WLAN device to wake up the Host MCU from its low-power state. Host-wake is implemented using a GPIO on the MCU that is connected to the WLAN device. The WLAN device asserts the host-wake GPIO to bring the host MCU out of its low-power state. This interrupt is called an out-of-band (OOB) interrupt. This configuration is critical for all the WLAN Low power offload like ARP, Packet Filter, TCP Keep alive to wake up Host MCU out of its low power state.

Refer to the Wi-Fi Low Power Configuration Considerations section to configure the Host-wake pin on the Host. The Host-wake pin polarity is configurable. The WLAN device is configured to re-route the SDIO in-band card interrupt to WL_HOST_WAKE (OOB GPIO interrupt). The following diagram shows connections between the Host and WLAN device:

../../../_images/HostWakeSignal1.png

Where:

  • SDIO: clock, data

  • WL_HOST_WAKE: OOB interrupt line to wake Host for service

Quick Start Guide

This Quick Start Guide demonstrates how to configure and use the WLAN_HOST_WAKE pin for the MCU Low Power feature in the Mbed OS environment. This guide also shows the feature’s impact on the system’s low power.

MBEDOS

The mbed-os-example-wifi is used as a base for this guide on the CY8CKIT_062S2_43012 pioneer kit. This section assumes that you have an Mbed OS development environment configured. Refer to https://os.mbed.com/getting-started/ for instructions about how to do that.

By default, the WLAN_HOST_WAKE pin is configured for Cypress boards. If you use another board you might need to modify / change the WLAN_HOST_WAKE assignment and verify it is configured properly.

Perform the following steps:

  1. Import the mbed-os-example-wifi example project and switch to the example directory: 

    mbed import mbed-os-example-wifi
cd mbed-os-example-wifi

  2. Execute the following command in order to update Mbed OS, download the LPA middleware : 

    mbed add https://github.com/cypresssemiconductorco/lpa/
mbed add https://github.com/cypresssemiconductorco/connectivity-utilities
mbed deploy

  3. Modify the example for your Wi-Fi SSID parameters:

    • Modify mbed_app.json to update “wifi-ssid” and “wifi-password” values as desired: 

      ...
    "wifi-ssid": {
        "help": "WiFi SSID",
        "value": "\"SSID\""
    },
    "wifi-password": {
        "help": "WiFi Password",
        "value": "\"PASSWORD\""
    }
...

    • Add “MBED” Component to mbed_app.json in target_overrides section which is required for compiling helpers in LPA code

      ”target.components_add”: [“MBED”]

      {
     "target_overrides": {
         "*": {
              "platform.stdio-convert-newlines": true,
              "target.components_add": ["MBED"]
         }
     }
}

    • Optional: modify main.cpp to update Wi-Fi security settings: 

      int ret = wifi->connect(MBED_CONF_APP_WIFI_SSID, MBED_CONF_APP_WIFI_PASSWORD, NSAPI_SECURITY_WPA_WPA2);
      Modify the last parameter if needed to either: 
      NSAPI_SECURITY_NONE
NSAPI_SECURITY_WEP
NSAPI_SECURITY_WPA
NSAPI_SECURITY_WPA2
NSAPI_SECURITY_WPA_WPA2
NSAPI_SECURITY_WPA3

  4. Modify main.cpp to go to deep-sleep after connecting to the Wi-Fi Access Point. MBED uses LWIP as the network stack. LWIP has periodic timers (smallest timer ~100ms), which wake up the Host MCU periodically. Do the following to suspend these timers. This is needed to demonstrate/verify that WLAN_HOST_WAKE pin is properly configured, and that the Host MCU does not wake up from any other reason other than OOB from WLAN device due to Network activity.

    • Include WhdSTAInterface.h and network_activity_handler.h: 

      #include "WhdSTAInterface.h"
#include "network_activity_handler.h"

    • Add the following declarations: 

      // This macro specifies the interval in milliseconds that the device monitors
// the network for inactivity. If the network is inactive for duration lesser 
// than INACTIVE_WINDOW_MS in this interval, the MCU does not suspend the network 
// stack and informs the calling function that the MCU wait period timed out 
// while waiting for network to become inactive.

#define INACTIVE_INTERVAL_MS    (300u)

// This macro specifies the continuous duration in milliseconds for which the 
// network has to be inactive. If the network is inactive for this duration, the
// MCU will suspend the network stack. Now, the MCU will not need to service the
// network timers which allows it to stay longer in sleep/deepsleep.

#define INACTIVE_WINDOW_MS      (200u)

    • Modify main.cpp to allow the host MCU to go to deep-sleep and stay in deep-sleep until woken up by an external event. For this, replace the line “wifi->disconnect();” with the following code: 

      while(true) {
    wait_net_suspend(static_cast<WhdSTAInterface*>(wifi),
       osWaitForever, INACTIVE_INTERVAL_MS, INACTIVE_WINDOW_MS);
}

  5. Verify WLAN_HOST_WAKE pin configurations using device configurator

    • Mandatory steps to avoid design.modus file modification in mbed-os folder

      1. Copy folder mbed-os-example-wifi/mbed-os/targets/TARGET_Cypress/TARGET_PSOC6/TARGET_CY8CKIT_062S2_43012 to mbed-os-example-wifi folder

      2. Delete all files in mbed-os-example-wifi/TARGET_CY8CKIT_062S2_43012 except COMPONENT_BSP_DESIGN_MODUS folder and its contents

      3. Rename mbed-os-example-wifi/TARGET_CY8CKIT_062S2_43012/COMPONENT_BSP_DESIGN_MODUS to mbed-os-example-wifi/TARGET_CY8CKIT_062S2_43012/CUSTOM_BSP_DESIGN_MODUS

      4. Delete design.cyqspi and design.cycapsense file in mbed-os-example-wifi/TARGET_CY8CKIT_062S2_43012/CUSTOM_BSP_DESIGN_MODUS

      5. Add/update mbed_app.json in mbed-os-example-wifi folder with below details (This will tell mbed to ignore the BSP configuration shipped with MbedOS) 

        {
     "target_overrides": {
         "*": {
              "platform.stdio-convert-newlines": true,
              "target.components_remove": ["BSP_DESIGN_MODUS"]
         }
     }
 }

      6. If mbed-os branch used is 5.15 or above, please do the below changes as well

        • update mbed_app.json with below line in “target_overrides”: 

          "target.components_add": ["CUSTOM_DESIGN_MODUS"]

    • Navigate to ModusToolbox installation folder and launch the ModusToolbox Device Configurator (<install_dir>/tools_2.2/device-configurator).

    • Select File->Open, navigate to the board’s design.modus file, and open it: mbed-os-example-wifi/TARGET_CY8CKIT_062S2_43012/CUSTOM_BSP_DESIGN_MODUS/design.modus

    • If the design.modus file does not open and pops with a error message No device support library path provided , then point to the psoc6pdl folder inside the mbed-os/targets/TARGET_Cypress/TARGET_PSOC6/psoc6pdl/devicesupport.xml (For MTB2.2, point to mtb_shared/mtb-pdl-cat1/<>/devicesupport.xml) file in the window popup. This is because the design.modus file will update its path to the PDL directory when it is opened for the first time.

    • Switch to the “Pins” tab, enable P4[1] pin, specify its name as “CYBSP_WIFI_HOST_WAKE”, in the “Parameters” pane change “Interrupt Trigger Type” to “Rising Edge”. If you are using a different pioneer kit, refer to its guide for Host<->Device connection pinout.

  6. Build the project and program the board. The following command is example for the CY8CKIT_062S2_43012 board, using GCC_ARM as the toolchain: 

    mbed compile -DMBED_TICKLESS -DMBED_CPU_STATS_ENABLED --target CY8CKIT_062S2_43012 --toolchain GCC_ARM --flash --sterm

    Note If you cannot program the board, make sure the board DAP-Link mode is selected. Refer to the guide of your kit of how to change the mode.

    MBED_CPU_STATS_ENABLED : This helps to understand how much time MCU remained in sleep state

    When the modified mbed-os-example-wifi starts, the console output lists available Wi-Fi networks. It then connects to the specified above Wi-Fi Access Point, and then the PSoC 6 MCU goes to System Deep Sleep. 

    Scan:
WLAN MAC Address : D4:4D:A4:A0:02:A4
WLAN Firmware    : wl0: Oct 29 2019 22:00:20 version 13.10.271.215 (r723093) FWID 01-f268ebc9
WLAN CLM         : API: 18.2 Data: 9.10.0 Compiler: 1.36.1 ClmImport: 1.34.1 Creation: 2019-10-29 21:50:17
WHD VERSION      : v1.50.0-rc1 : v1.50.0-rc1 : GCC 7.3 : 2019-10-30 18:42:31 +0530
Network: airport_5g secured: WPA2 BSSID: 24:A2:E1:f0:50:25 RSSI: -84 Ch: 36
Network: Broadcom secured: None BSSID: 0:10:18:ee:b5:f7 RSSI: -52 Ch: 36
Network: test_2nd_cy secured: WPA2 BSSID: F8:32:E4:b0:ff:8c RSSI: -74 Ch: 36
Network: eero secured: WPA2 BSSID: F8:BB:BF:b2:2:54 RSSI: -33 Ch: 36
Network: WWD secured: WPA/WPA2 BSSID: 64:A5:C3:64:16:13 RSSI: -77 Ch: 36
Network: eero secured: WPA/WPA2 BSSID: F8:BB:BF:b1:74:b4 RSSI: -36 Ch: 36
Network: eero secured: WPA/WPA2 BSSID: F8:BB:BF:69:2b:8 RSSI: -46 Ch: 36
Network: prke-bsh5g secured: WPA/WPA2 BSSID: 44:4E:6D:45:b0:58 RSSI: -82 Ch: 36
Network:  secured: Unknown BSSID: F8:BB:BF:b2:2:52 RSSI: -33 Ch: 36
Network: testap secured: None BSSID: 0:A0:50:30:81:65 RSSI: -64 Ch: 36
Network: RW1 secured: WPA2 BSSID: C8:8:73:3c:87:2c RSSI: -75 Ch: 40
Network: CYFI secured: WPA2 BSSID: B0:B8:67:3b:ac:70 RSSI: -86 Ch: 44
Network: CYFI secured: WPA2 BSSID: 80:8D:B7:69:77:30 RSSI: -70 Ch: 44
Network: CYFI_GUEST secured: None BSSID: 80:8D:B7:69:77:31 RSSI: -70 Ch: 44
Network: CYFI_ZOOM secured: WPA2 BSSID: 80:8D:B7:69:77:32 RSSI: -70 Ch: 44
15 networks available.

Connecting to SSID...
Success

MAC: d4:4d:a4:a0:02:a4
IP: 192.168.1.12
Netmask: 255.255.255.0
Gateway: 192.168.1.1
RSSI: -29

Network Stack Suspended, MCU will enter DeepSleep power mode

  7. PSoC 6 MCU is in System Deep Sleep. Only WLAN OOB can wake Host up in this situation. Check the board operation. Use a PC to connect to the same Wi-Fi Access Point as the PSoC 6 board.

    Send a “ping” command to the board and observe in the serial terminal that the PSoC 6 MCU wakes up each command: 

    C:\>ping 192.168.1.12

Pinging 192.168.1.12 with 32 bytes of data:
Reply from 192.168.1.12: bytes=32 time=738ms TTL=255
Reply from 192.168.1.12: bytes=32 time=662ms TTL=255
Reply from 192.168.1.12: bytes=32 time=727ms TTL=255
Reply from 192.168.1.12: bytes=32 time=468ms TTL=255

Ping statistics for 192.168.1.12:
    Packets: Sent = 4, Received = 4, Lost = 0 (0% loss),
Approximate round trip times in milli-seconds:
Minimum = 468ms, Maximum = 738ms, Average = 648ms

<Terminal logs >
Resuming Network Stack, Network stack was suspended for 8906ms

=====================================================
WHD Stats..
tx_total:57, rx_total:329, tx_no_mem:0, rx_no_mem:0
tx_fail:0, no_credit:0, flow_control:0
Bus Stats..
cmd52:2260, cmd53_read:1028, cmd53_write:634
cmd52_fail:0, cmd53_read_fail:0, cmd53_write_fail:0
oob_intrs:120, sdio_intrs:312, error_intrs:0, read_aborts:0
=====================================================

Network Stack Suspended, MCU will enter DeepSleep power mode
    Ping traffic causes WLAN OOB periodically wakes up the host, oob_intrs displayed in the serial terminal output shows the number of WLAN OOB interrupts receieved.

FREERTOS

  1. Checkout Wi-Fi Example app 

    git clone https://github.com/cypresssemiconductorco/mtb-example-anycloud-wlan-lowpower.git
cd mtb-example-anycloud-wlan-lowpower

  2. Make sure below FreeRTOSConfig.h changes are present:

    configUSE_TICKLESS_IDLE : This change to support Tickless Deep Sleep mode 

    #include <cycfg_system.h>

#if (CY_CFG_PWR_SYS_IDLE_MODE == CY_CFG_PWR_MODE_SLEEP) || (CY_CFG_PWR_SYS_IDLE_MODE == CY_CFG_PWR_MODE_DEEPSLEEP)
extern void vApplicationSleep( uint32_t xExpectedIdleTime );
#define portSUPPRESS_TICKS_AND_SLEEP( xIdleTime ) vApplicationSleep( xIdleTime )
#define configUSE_TICKLESS_IDLE  2
#endif

#if CY_CFG_PWR_DEEPSLEEP_LATENCY > 0
#define configEXPECTED_IDLE_TIME_BEFORE_SLEEP   CY_CFG_PWR_DEEPSLEEP_LATENCY
#endif

  3. Add lib file for TARGET_CY8CKIT-062S2-43012 in deps folder and delete deps/TARGET_CY8CPROTO-062-4343W.lib 

    TARGET_CY8CKIT-062S2-43012.lib : https://github.com/cypresssemiconductorco/TARGET_CY8CKIT-062S2-43012/#latest-v2.X

# MTB2.2 and .mtb approach , make sure below mtb files are present
echo https://github.com/cypresssemiconductorco/TARGET_CY8CKIT-062S2-43012#latest-v2.X#\$\$ASSET_REPO\$\$/TARGET_CY8CKIT-062S2-43012/latest-v2.X > deps/TARGET_CY8CKIT-062S2-43012.mtb

  4. Modify the example for your Wi-Fi SSID parameters in lowpower_task.h 

    #define WIFI_SSID                         "SSID"
#define WIFI_PASSWORD                     "PASSWORD"
#define WIFI_SECURITY                     CY_WCM_SECURITY_WPA2_MIXED_PSK

  5. The wait_net_suspend() used in lowpower_task.c allows the host MCU to go to deep-sleep and stay in deep-sleep until woken up by an external event. 

    wait_net_suspend(wifi, portMAX_DELAY, INACTIVE_INTERVAL_MS, INACTIVE_WINDOW_MS);

  6. Make sure below Makefile changes present if LPA version used is greater than 3.0.0 

    COMPONENTS=WCM SECURE_SOCKETS

# For MTB2.2, below change

CY_GETLIBS_SHARED_PATH=../
CY_GETLIBS_SHARED_NAME=mtb_shared

  7. Verify WLAN_HOST_WAKE pin configurations using device configurator

    • Navigate to ModusToolbox installation folder and launch the ModusToolbox Device Configurator (<install_dir>/tools_2.2/device-configurator).

    • Select File->Open, navigate to the board’s design.modus file, and open it: mtb-example-anycloud-wlan-lowpower/COMPONENT_CUSTOM_DESIGN_MODUS/TARGET_CY8CKIT-062S2-43012/design.modus

    • If the design.modus file does not open and pops with a error message No device support library path provided , then point to the psoc6pdl folder inside the mtb-example-anycloud-wlan-lowpower/libs/psoc6pdl/devicesupport.xml(For MTB2.2, point to mtb_shared/mtb-pdl-cat1/<>/devicesupport.xml) file in the window popup. This is because the design.modus file will update its path to the PDL directory when it is opened for the first time.

    • Switch to the “Pins” tab, enable P4[1] pin, specify its name as “CYBSP_WIFI_HOST_WAKE”, in the “Parameters” pane change “Interrupt Trigger Type” to “Rising Edge”. If you are using a different pioneer kit, refer to its guide for Host<->Device connection pinout.

  8. Build the project and program the board. The following command is example for the CY8CKIT_062S2_43012 board, using GCC_ARM as the toolchain: 

    make getlibs
make program TARGET=CY8CKIT-062S2-43012 TOOLCHAIN=GCC_ARM

    When the modified mtb-example-anycloud-wlan-lowpower starts, the console output shows that it connects to the specified above Wi-Fi Access Point, and then the PSoC 6 MCU goes to System Deep Sleep. 

    =======================================================
CE230106 - AnyCloud Example: WLAN Lowpower
=======================================================

WLAN MAC Address : D4:4D:A4:A0:02:A4
WLAN Firmware    : wl0: Jan 27 2020 21:57:29 version 13.10.271.236 (5a526db) FWID 01-61e2b002
WLAN CLM         : API: 18.2 Data: 9.10.0 Compiler: 1.36.1 ClmImport: 1.34.1 Creation: 2020-01-27 21:54:33
WHD VERSION      : v1.80.0 : v1.80.0 : GCC 7.2 : 2020-03-10 04:09:17 -0500
Info:Connecting to AP
IP Address 10.0.0.201 assigned
Info:Successfully joined Wi-Fi network 'SSID'.
Info:Beacon period = 100, DTIM period = 3

Network Stack Suspended, MCU will enter DeepSleep power mode
Resuming Network Stack, Network stack was suspended for 15253ms

=====================================================
WHD Stats..
tx_total:64, rx_total:71, tx_no_mem:0, rx_no_mem:0
tx_fail:0, no_credit:0, flow_control:0
Bus Stats..
cmd52:2286, cmd53_read:366, cmd53_write:559
cmd52_fail:0, cmd53_read_fail:0, cmd53_write_fail:0
oob_intrs:72, sdio_intrs:147, error_intrs:0, read_aborts:0
=====================================================
Network is active. Resuming network stack
Network Stack Suspended, MCU will enter DeepSleep power mode

  9. PSoC 6 MCU is in System Deep Sleep. Only WLAN OOB can wake Host up in this situation. Check the board operation. Use a PC to connect to the same Wi-Fi Access Point as the PSoC 6 board.

    Send a “ping” command to the board and observe in the serial terminal that the PSoC 6 MCU wakes up each command: 

    C:\>ping -n 3 10.0.0.201
Pinging 10.0.0.201 with 32 bytes of data:
Reply from 10.0.0.201: bytes=32 time=274ms TTL=255
Reply from 10.0.0.201: bytes=32 time=393ms TTL=255
Reply from 10.0.0.201: bytes=32 time=396ms TTL=255

Ping statistics for 10.0.0.201:
    Packets: Sent = 3, Received = 3, Lost = 0 (0% loss),
Approximate round trip times in milli-seconds:
    Minimum = 274ms, Maximum = 396ms, Average = 354ms

<Terminal logs >
Resuming Network Stack, Network stack was suspended for 443ms
=====================================================
WHD Stats..
tx_total:91, rx_total:97, tx_no_mem:0, rx_no_mem:0
tx_fail:0, no_credit:0, flow_control:0
Bus Stats..
cmd52:2314, cmd53_read:488, cmd53_write:607
cmd52_fail:0, cmd53_read_fail:0, cmd53_write_fail:0
oob_intrs:93, sdio_intrs:187, error_intrs:0, read_aborts:0
=====================================================

Network Stack Suspended, MCU will enter Deep sleep power mode
    Ping traffic causes WLAN OOB periodically wakes up the host, oob_intrs displayed in the serial terminal output shows the number of WLAN OOB interrupts received.

AFR

  1. Checkout Wi-Fi Low Power Example app 

    git clone https://github.com/cypresssemiconductorco/amazon-freertos.git --recurse-submodules
cd amazon-freertos/projects/cypress/
git clone https://github.com/cypresssemiconductorco/afr-example-wlan-lowpower.git
cd afr-example-wlan-lowpower

  2. Make sure below FreeRTOSConfig.h changes are present (config_files folder):

    configUSE_TICKLESS_IDLE : This change to support Tickless Deep Sleep mode 

    #include <cycfg_system.h>

#if (CY_CFG_PWR_SYS_IDLE_MODE == CY_CFG_PWR_MODE_SLEEP) || (CY_CFG_PWR_SYS_IDLE_MODE == CY_CFG_PWR_MODE_DEEPSLEEP)
extern void vApplicationSleep( uint32_t xExpectedIdleTime );
#define portSUPPRESS_TICKS_AND_SLEEP( xIdleTime ) vApplicationSleep( xIdleTime )
#define configUSE_TICKLESS_IDLE  2
#endif
#if CY_CFG_PWR_DEEPSLEEP_LATENCY > 0
#define configEXPECTED_IDLE_TIME_BEFORE_SLEEP   CY_CFG_PWR_DEEPSLEEP_LATENCY
#endif

  3. Modify the example for your Wi-Fi SSID parameters in lowpower_task.h 

    #define WIFI_SSID                         "SSID"
#define WIFI_PASSWORD                     "PASSWORD"
#define WIFI_SECURITY                     eWiFiSecurityWPA2

  4. The wait_net_suspend() used in lowpower_task.c allows the host MCU to go to deep-sleep and stay in deep-sleep until woken up by an external event. 

    wait_net_suspend(wifi, portMAX_DELAY, INACTIVE_INTERVAL_MS, INACTIVE_WINDOW_MS);

  5. Verify WLAN_HOST_WAKE pin configurations using device configurator

    • Navigate to ModusToolbox installation folder and launch the ModusToolbox Device Configurator (<install_dir>/tools_2.2/device-configurator).

    • Select File->Open, navigate to the board’s design.modus file, and open it: amazon-freertos/projects/cypress/afr-example-wlan-lowpower/COMPONENT_CUSTOM_DESIGN_MODUS/TARGET_CY8CKIT-062S2-43012/design.modus

    • If the design.modus file does not open and pops with a error message No device support library path provided , then point to the psoc6pdl folder inside the amazon-freertos/vendors/cypress/psoc6/psoc6pdl/devicesupport.xml file in the window popup. This is because the design.modus file will update its path to the PDL directory when it is opened for the first time.

    • Switch to the “Pins” tab, enable P4[1] pin, specify its name as “CYBSP_WIFI_HOST_WAKE”, in the “Parameters” pane change “Interrupt Trigger Type” to “Rising Edge”. If you are using a different pioneer kit, refer to its guide for Host<->Device connection pinout.

  6. Build the project using CMake / Make.

    The following command is example for the CY8CKIT_062S2_43012 board, using GCC_ARM as the toolchain:

    CMake 

    cd amazon-freertos/projects/cypress/afr-example-wlan-lowpower
cmake -DVENDOR=cypress -DBOARD=CY8CKIT_062S2_43012 -DCOMPILER=arm-gcc -S . -B build -G Ninja -DCMAKE_TOOLCHAIN_FILE=../../../tools/cmake/toolchains/arm-gcc.cmake
cmake --build build --clean-first
    Make 
    cd amazon-freertos/projects/cypress/afr-example-wlan-lowpower
make build TARGET=CY8CKIT-062S2-43012 TOOLCHAIN=GCC_ARM

  7. Program the board with afr-example-wlan-lowpower.elf file generated under below folder using Cypress Programmer CMake : amazon-freertos/projects/cypress/afr-example-wlan-lowpower/build/ Make : amazon-freertos/build/cy/afr-example-wlan-lowpower/CY8CKIT-062S2-43012/Debug When the modified afr-example-wlan-lowpower starts, the console output shows that it connects to the specified above Wi-Fi Access Point, and then the PSoC 6 MCU goes to System Deep Sleep. 

    Info: ==================================
Info: AFR Example: WLAN Low Power
Info: ==================================

WLAN MAC Address : D4:4D:A4:A0:02:A4
WLAN Firmware    : wl0: Jan 27 2020 21:57:29 version 13.10.271.236 (5a526db) FWID 01-61e2b002
WLAN CLM         : API: 18.2 Data: 9.10.0 Compiler: 1.36.1 ClmImport: 1.34.1 Creation: 2020-01-27 21:54:33
WHD VERSION      : v1.90.2 : v1.90.2 : GCC 9.2 : 2020-04-13 02:49:57 -0500
Offloads not configured
Info: Wi-Fi module initialized. Connecting to AP...
Info: Wi-Fi connected to AP: SSID
Info: IP Address acquired: 192.168.43.11
Info: Beacon period = 100, DTIM period = 3

Network Stack Suspended, MCU will enter DeepSleep power mode
Resuming Network Stack, Network stack was suspended for 1948ms

=====================================================
WHD Stats..
tx_total:67, rx_total:71, tx_no_mem:0, rx_no_mem:0
tx_fail:0, no_credit:0, flow_control:0
Bus Stats..
cmd52:2313, cmd53_read:351, cmd53_write:558
cmd52_fail:0, cmd53_read_fail:0, cmd53_write_fail:0
oob_intrs:68, sdio_intrs:154, error_intrs:0, read_aborts:0
=====================================================
Network is active. Resuming network stack

Network Stack Suspended, MCU will enter DeepSleep power mode

  8. PSoC 6 MCU is in System Deep Sleep. Only WLAN OOB can wake Host up in this situation. Check the board operation. Use a PC to connect to the same Wi-Fi Access Point as the PSoC 6 board.

    Send a “ping” command to the board and observe in the serial terminal that the PSoC 6 MCU wakes up each command: 

    C:\>ping -n 3 192.168.43.11
Pinging 192.168.43.11 with 32 bytes of data:
Reply from 192.168.43.11: bytes=32 time=274ms TTL=255
Reply from 192.168.43.11: bytes=32 time=393ms TTL=255
Reply from 192.168.43.11: bytes=32 time=396ms TTL=255

Ping statistics for 192.168.43.11:
    Packets: Sent = 3, Received = 3, Lost = 0 (0% loss),
Approximate round trip times in milli-seconds:
    Minimum = 274ms, Maximum = 396ms, Average = 354ms

<Terminal logs >
Resuming Network Stack, Network stack was suspended for 443ms
=====================================================
WHD Stats..
tx_total:91, rx_total:97, tx_no_mem:0, rx_no_mem:0
tx_fail:0, no_credit:0, flow_control:0
Bus Stats..
cmd52:2314, cmd53_read:488, cmd53_write:607
cmd52_fail:0, cmd53_read_fail:0, cmd53_write_fail:0
oob_intrs:93, sdio_intrs:187, error_intrs:0, read_aborts:0
=====================================================

Network Stack Suspended, MCU will enter Deep sleep power mode
    Ping traffic causes WLAN OOB periodically waking up the host, oob_intrs displayed in the serial terminal output shows the number of WLAN OOB interrupts received.

Wi-Fi Address Resolution Protocol (ARP) Offload

The Address Resolution Protocol (ARP) Offload part of the Low Power Assistant is designed to improve the power consumption of your connected system by reducing the time the Host needs to stay awake due to ARP broadcast traffic. In general, the ARP Offload reduces the broadcast traffic. To enable this support, refer to the Wi-Fi Low Power Configuration Considerations section. This document describes how to enable the ARP Offload features that can be incorporated into your project from Cypress GitHub LPA Middleware.

ARP is used for mapping an Internet Protocol address (IP address; ex: 192.168.1.1)) to a physical machine address (MAC; ex: ac:32:df:14:16:07) lookup. ARP uses broadcast frames to accomplish this.

  • Reduce System Deep Sleep wake-up to reduce Host Processor power consumption.

  • Reduce Network traffic. If many IoT devices are in one space, the Wi-Fi bands can get congested with unnecessary broadcast traffic.

ARP broadcast traffic is normally forwarded from the Network to the Device (Wi-Fi Radio) and then to the Host (Application CPU) Network Stack. If the Host is sleeping, the Device wakes it up. Having the Device handle some of the ARP traffic will reduce the frequency that the Host sleeps/wakes up, reducing Host power consumption by staying in CPU Sleep and System Deep Sleep states longer. Having the Device handle some of the ARP requests from the Host to the network will reduce Network traffic.

../../../_images/ARP11.png

The WLAN ARP Offload feature of the Low Power Assistant will help you to configure the ARP requests handling by the Device.

Awake vs. Sleeping

The ARP offload feature of the Low Power Assistant has the following basic modes:

  • While the Host (Host Processor) is “Awake”

  • While the Host (Host Processor) is in CPU Sleep or System Deep Sleep.

It is possible to enable and configure these modes based on the Sleep status of the Application CPU.

Host Auto Reply

Host Auto Reply is a power-saving and network traffic reduction feature. Using the ARP Offload Host Auto Reply feature, the Device will answer Host ARP Requests, without broadcasting to the Network. If a Host generated ARP Request results in a cache hit in the Device ARP cache, the Device will fabricate an ARP Response and not forward the request to the Network.

This may be useful when the Host ARP cache is cleared to disable the Host ARP table entry timers prior to entering System Deep Sleep. When the Host is woken up, if the Host ARP cache queries in its own Network Stack and results in a cache miss, the Host ARP Request will be sent to the Device. If the ARP Request results in a cache hit in the Device, the Device will respond without soliciting the network. As long as the Device ARP cache entry hasn’t expired, the Device will fabricate an ARP Response to the Host, thus reducing broadcast traffic.

The ARP Agent is enabled by setting the ARP Offload Agent flag and ARP Offload Enable in the Device Configurator. The ARP Agent will store “ARP IP : MAC” combos in the Device ARP cache. The Device ARP cache is filled with IP:MAC combos when ARP Offload and ARP Agent are enabled and the Network has responded to a Host ARP Request. There is an “age out” value that you can set in the ARP Offload configuration to determine the length of time the ARP cache entry is valid. This ensures that the WLAN ARP cache is updated appropriately.

The size of the WLAN Device ARP Cache is 16. The Host Network Stack maintains an ARP cache regardless if the WLAN Device ARP Agent is turned on or not.

../../../_images/ARP21.png

Peer Auto Reply

Peer Auto Reply is another power-saving feature so that the Device can respond to ARP requests from Peers (Network) without waking up the Host Processor.

This is accomplished by setting the ARP Offload Enable and Peer Auto Reply flags in the Device Configurator. When enabled, this feature instructs the Device to answer ARP requests to the Peers without actually asking the Host. This allows the Host to stay in CPU Sleep or System Deep Sleep longer to save power. Once the IP address of the Device is established (that is, the Device has connected to an AP and an IP has been assigned and stored in the Device), the Device will intercept any ARP request sent to the Host, and then fabricate and send an ARP response without involving the Host. If the Host was in CPU Sleep or System Deep Sleep mode, the Host is not awakened.

The max number of entries for this feature is set to 8 (defined in the Device Firmware and is not modifiable).

../../../_images/ARP31.png

Host and Peer Auto Reply

Host Auto Reply and Peer Auto Reply features can be enabled together for Application CPU Awake mode.

Host IP Snoop

When enabled, the Snoop facility watches for ARP Responses from the Host to the Network, and caches them in the WLAN Device Host IP Table. The size of this table is 8 entries, which allows for the Device to support multiple IP addresses.

Quick Start Guide

This Quick Start Guide demonstrates of how to configure and use the ARP offload feature in the Mbed OS, FreeRTOS environment and its impact on the system power consumption.

MBEDOS

The mbed-os-example-wifi is used as a base for this guide on the CY8CKIT_062S2_43012 pioneer kit. This section assumes that you have an Mbed OS development environment configured. Refer to https://os.mbed.com/getting-started/ for instructions about how to do that.

The following steps are required to set up the mbed-os-example-wifi example and enable the ARP offload feature:

  1. Import the mbed-os-example-wifi example project and switch to the example directory: 

    mbed import mbed-os-example-wifi
cd mbed-os-example-wifi

  2. Execute the following command in order to replace Mbed OS, download the LPA middleware and connectivity utilities: 

    mbed add https://github.com/cypresssemiconductorco/lpa/
mbed add https://github.com/cypresssemiconductorco/connectivity-utilities/
mbed deploy

  3. Modify the example for your Wi-Fi SSID parameters:

    • Modify mbed_app.json to update “wifi-ssid” and “wifi-password” values as desired: 

      ...
    "wifi-ssid": {
        "help": "WiFi SSID",
        "value": "\"SSID\""
    },
    "wifi-password": {
        "help": "WiFi Password",
        "value": "\"PASSWORD\""
    }
...

    • Add “MBED” Component to mbed_app.json in target_overrides section which is required for compiling helpers in LPA code

      ”target.components_add”: [“MBED”]

      {
     "target_overrides": {
         "*": {
              "platform.stdio-convert-newlines": true,
              "target.components_add": ["MBED"]
         }
     }
}

    • Optional: modify main.cpp to update Wi-Fi security settings: 

      int ret = wifi->connect(MBED_CONF_APP_WIFI_SSID, MBED_CONF_APP_WIFI_PASSWORD, NSAPI_SECURITY_WPA_WPA2);
      Modify the last parameter if needed to either: 
      NSAPI_SECURITY_NONE
NSAPI_SECURITY_WEP
NSAPI_SECURITY_WPA
NSAPI_SECURITY_WPA2
NSAPI_SECURITY_WPA_WPA2
NSAPI_SECURITY_WPA3

  4. Modify main.cpp to go to deep-sleep after connecting to the Wi-Fi Access Point. MBED uses LWIP as the network stack. LWIP has periodic timers (smallest timer ~100ms), which wake up the Host MCU periodically. Do the following to suspend these timers, so the Host MCU can be in deep-sleep for a longer time. This is needed to demonstrate / verify ARP offload is not waking up the Host MCU.

    • Include WhdSTAInterface.h and network_activity_handler.h: 

      #include "WhdSTAInterface.h"
#include "network_activity_handler.h"

    • Add the following declarations: 

      // This macro specifies the interval in milliseconds that the device monitors
// the network for inactivity. If the network is inactive for duration lesser
// than INACTIVE_WINDOW_MS in this interval, the MCU does not suspend the network
// stack and informs the calling function that the MCU wait period timed out
// while waiting for network to become inactive.

#define INACTIVE_INTERVAL_MS    (300u)

// This macro specifies the continuous duration in milliseconds for which the
// network has to be inactive. If the network is inactive for this duration, the
// MCU will suspend the network stack. Now, the MCU will not need to service the
// network timers which allows it to stay longer in sleep/deepsleep.

#define INACTIVE_WINDOW_MS      (200u)

    • Modify main.cpp to allow the host MCU to go to deep-sleep and stay in deep-sleep until woken up by an external event. For this, replace the line “wifi->disconnect();” with the following code: 

      while(true) {
    wait_net_suspend(static_cast<WhdSTAInterface*>(wifi),
      osWaitForever, INACTIVE_INTERVAL_MS, INACTIVE_WINDOW_MS);
}

  5. Configure the ARP offload. The easiest way to configure ARP offload is to use the ModusToolbox Device Configurator.

    • Mandatory steps to avoid design.modus file modification in mbed-os folder

      1. Copy folder mbed-os-example-wifi/mbed-os/targets/TARGET_Cypress/TARGET_PSOC6/TARGET_CY8CKIT_062S2_43012 to mbed-os-example-wifi folder

      2. Delete all files in mbed-os-example-wifi/TARGET_CY8CKIT_062S2_43012 except COMPONENT_BSP_DESIGN_MODUS folder and its contents

      3. Rename mbed-os-example-wifi/TARGET_CY8CKIT_062S2_43012/COMPONENT_BSP_DESIGN_MODUS to mbed-os-example-wifi/TARGET_CY8CKIT_062S2_43012/CUSTOM_BSP_DESIGN_MODUS

      4. Delete design.cyqspi and design.cycapsense file in mbed-os-example-wifi/TARGET_CY8CKIT_062S2_43012/CUSTOM_BSP_DESIGN_MODUS

      5. Add/update mbed_app.json in mbed-os-example-wifi folder with below details (This will tell mbed to ignore the BSP configuration shipped with MbedOS) 

        {
     "target_overrides": {
         "*": {
              "platform.stdio-convert-newlines": true,
              "target.components_remove": ["BSP_DESIGN_MODUS"]
         }
     }
 }

      6. If mbed-os branch used is 5.15 or above, please do the below changes as well

        • update mbed_app.json with below line in “target_overrides”: 

          "target.components_add": ["CUSTOM_DESIGN_MODUS"]

    • Navigate to ModusToolbox installation folder and launch the ModusToolbox Device Configurator (<install_dir>/tools_2.2/device-configurator).

    • Select File->Open, navigate to the board’s design.modus file, and open it: mbed-os-example-wifi/TARGET_CY8CKIT_062S2_43012/CUSTOM_BSP_DESIGN_MODUS/design.modus

    • If the design.modus file does not open and pops with a error message No device support library path provided , then point to the psoc6pdl folder inside the mbed-os/targets/TARGET_Cypress/TARGET_PSOC6/psoc6pdl/devicesupport.xml file in the window popup. This is because the design.modus file will update its path to the PDL directory when it is opened for the first time.

    • Switch to the “Pins” tab, enable P4[1] pin, specify its name as “CYBSP_WIFI_HOST_WAKE”, in the “Parameters” pane change “Interrupt Trigger Type” to “Rising Edge”. If you are using a different pioneer kit, refer to its guide for Host<->Device connection pinout.

    • Switch to the connectivity device “CYW943012WKWBG” tab (in case the CY8CKIT_062S2_43012 board is used).

    • Enable Power->Wi-Fi.

    • In “Wi-Fi - Parameters” pane enable “Host Wake Configuration” and set “Host Device Interrupt Pin” to “CYBSP_WIFI_HOST_WAKE”.

    • Enable ARP offload.

    • Set “ARP offload Feature(s)” to “Peer Auto Reply”.

    • Enable “Snoop Host IP From Traffic When ARP Offload Enabled”.

    • Set “ARP Offload Cache Entries Expire after (s)” to 1200.

    • Save the configuration to generate the necessary code.

  6. Build the project and program the board. The following command is example for the CY8CKIT_062S2_43012 board, using GCC_ARM as the toolchain: 

    mbed compile -DMBED_TICKLESS -DMBED_CPU_STATS_ENABLED --target CY8CKIT_062S2_43012 --toolchain GCC_ARM --flash --sterm

    Note If you cannot program the board, make sure the board DAP-Link mode is selected. Refer to the guide of your kit of how to change the mode.

    MBED_CPU_STATS_ENABLED : This helps to understand how much time MCU remained in sleep state

    When the modified mbed-os-example-wifi starts, the console output lists available Wi-Fi networks. It then connects to the specified above Wi-Fi Access Point, and then the PSoC 6 MCU goes to System Deep Sleep. 

    Scan:
WLAN MAC Address : D4:4D:A4:A0:02:A4
WLAN Firmware    : wl0: Oct 29 2019 22:00:20 version 13.10.271.215 (r723093) FWID 01-f268ebc9
WLAN CLM         : API: 18.2 Data: 9.10.0 Compiler: 1.36.1 ClmImport: 1.34.1 Creation: 2019-10-29 21:50:17
WHD VERSION      : v1.50.0-rc1 : v1.50.0-rc1 : GCC 7.3 : 2019-10-30 18:42:31 +0530
Network: airport_5g secured: WPA2 BSSID: 24:A2:E1:f0:50:25 RSSI: -84 Ch: 36
Network: Broadcom secured: None BSSID: 0:10:18:ee:b5:f7 RSSI: -52 Ch: 36
Network: test_2nd_cy secured: WPA2 BSSID: F8:32:E4:b0:ff:8c RSSI: -74 Ch: 36
Network: eero secured: WPA2 BSSID: F8:BB:BF:b2:2:54 RSSI: -33 Ch: 36
Network: WWD secured: WPA/WPA2 BSSID: 64:A5:C3:64:16:13 RSSI: -77 Ch: 36
Network: eero secured: WPA/WPA2 BSSID: F8:BB:BF:b1:74:b4 RSSI: -36 Ch: 36
Network: eero secured: WPA/WPA2 BSSID: F8:BB:BF:69:2b:8 RSSI: -46 Ch: 36
Network: prke-bsh5g secured: WPA/WPA2 BSSID: 44:4E:6D:45:b0:58 RSSI: -82 Ch: 36
Network:  secured: Unknown BSSID: F8:BB:BF:b2:2:52 RSSI: -33 Ch: 36
Network: testap secured: None BSSID: 0:A0:50:30:81:65 RSSI: -64 Ch: 36
Network: RW1 secured: WPA2 BSSID: C8:8:73:3c:87:2c RSSI: -75 Ch: 40
Network: CYFI secured: WPA2 BSSID: B0:B8:67:3b:ac:70 RSSI: -86 Ch: 44
Network: CYFI secured: WPA2 BSSID: 80:8D:B7:69:77:30 RSSI: -70 Ch: 44
Network: CYFI_GUEST secured: None BSSID: 80:8D:B7:69:77:31 RSSI: -70 Ch: 44
Network: CYFI_ZOOM secured: WPA2 BSSID: 80:8D:B7:69:77:32 RSSI: -70 Ch: 44
15 networks available.

Connecting to SSID...
Success

MAC: d4:4d:a4:a0:02:a4
IP: 192.168.1.12
Netmask: 255.255.255.0
Gateway: 192.168.1.1
RSSI: -29

Network Stack Suspended, MCU will enter DeepSleep power mode

  7. Check the board operation. Use a PC to connect to the same Wi-Fi Access Point as the PSoC 6 board.

    • Send a “ping” command to the board and observe in the serial terminal that the PSoC 6 MCU wakes up for each command: 

      C:\>ping 192.168.1.12

Pinging 192.168.1.12 with 32 bytes of data:
Reply from 192.168.1.12: bytes=32 time=738ms TTL=255
Reply from 192.168.1.12: bytes=32 time=662ms TTL=255
Reply from 192.168.1.12: bytes=32 time=727ms TTL=255
Reply from 192.168.1.12: bytes=32 time=468ms TTL=255

Ping statistics for 192.168.1.12:
    Packets: Sent = 4, Received = 4, Lost = 0 (0% loss),
Approximate round trip times in milli-seconds:
Minimum = 468ms, Maximum = 738ms, Average = 648ms

<Terminal logs >
  Resuming Network Stack, Network stack was suspended for 8906ms

  =====================================================
  WHD Stats..
  tx_total:57, rx_total:329, tx_no_mem:0, rx_no_mem:0
  tx_fail:0, no_credit:0, flow_control:0
  Bus Stats..
  cmd52:2260, cmd53_read:1028, cmd53_write:634
  cmd52_fail:0, cmd53_read_fail:0, cmd53_write_fail:0
  oob_intrs:120, sdio_intrs:312, error_intrs:0, read_aborts:0
  =====================================================

  Network Stack Suspended, MCU will enter DeepSleep power mode

    • Send an “arping” command as follows and observe that the PSoC 6 MCU is in Deep Sleep mode. 

      C:\>arp-ping.exe 192.168.1.12

Reply that D4:4D:A4:A0:02:A4 is 192.168.1.12 in 1124.833ms
Reply that D4:4D:A4:A0:02:A4 is 192.168.1.12 in 121.340ms
Reply that D4:4D:A4:A0:02:A4 is 192.168.1.12 in 1122.989ms
Reply that D4:4D:A4:A0:02:A4 is 192.168.1.12 in 1119.256ms

Ping statistics for 192.168.1.12/arp
     4 probes sent.
     4 successful, 0 failed.
Approximate trip times in milli-seconds:
     Minimum = 121.340ms, Maximum = 1124.833ms, Average = 872.105ms

      Use any available ARPping tool. As an example:

      Since the WLAN device’s ARP cache is empty on the initial ARP request from the peer, it looks up the IP details from the host and updates its ARP cache. This causes the host to wake up because of network activity between the host MCU and the WLAN device. On subsequent ARP requests from the peer, the host remains asleep. The WLAN device continues to respond to the ARP request as it has the ARP data available in its ARP cache.

    • Verify the ARP offload is working as desired. Refer to the How to Measure Power Consumption section for corresponding instructions. The following oscilloscope screen capture shows current measurement with the ARP offload enabled:

      ../../../_images/arp_offload_inv1.jpg

      While the WLAN device (purple graph) responds to each request, the PSoC 6 MCU (blue graph) is in System Deep Sleep mode.

  8. Disable the ARP Offload feature and observe that the PSoC 6 MCU wakes up on each request. Launch the ModusToolbox Device Configurator and open the appropriate design.modus file. Select the “CYW943012WKWBG” tab, select Power->Wi-Fi personality, and disable ARP offload by de-selecting the check box next to “ARP offload”. Save the configuration. Then, build and program the application. With ARP offload disabled, the Host MCU (PSoC 6) will wake for every ARP request, as shown in the following power profile.

    ../../../_images/arp_nooffload_inv1.jpg

FREERTOS

The following steps are required to set up the wifi-low-power example and enable the ARP offload feature:

  1. Checkout Wi-Fi Example app 

    git clone https://github.com/cypresssemiconductorco/mtb-example-anycloud-wlan-lowpower.git
cd mtb-example-anycloud-wlan-lowpower

  2. Make sure below FreeRTOSConfig.h changes are present:

    configUSE_TICKLESS_IDLE : This change to support Tickless Deep Sleep mode 

    #include <cycfg_system.h>

#if (CY_CFG_PWR_SYS_IDLE_MODE == CY_CFG_PWR_MODE_SLEEP) || (CY_CFG_PWR_SYS_IDLE_MODE == CY_CFG_PWR_MODE_DEEPSLEEP)
extern void vApplicationSleep( uint32_t xExpectedIdleTime );
#define portSUPPRESS_TICKS_AND_SLEEP( xIdleTime ) vApplicationSleep( xIdleTime )
#define configUSE_TICKLESS_IDLE  2
#endif

#if CY_CFG_PWR_DEEPSLEEP_LATENCY > 0
#define configEXPECTED_IDLE_TIME_BEFORE_SLEEP   CY_CFG_PWR_DEEPSLEEP_LATENCY
#endif

  3. Add lib file for TARGET_CY8CKIT-062S2-43012 in deps folder and delete deps/TARGET_CY8CPROTO-062-4343W.lib 

    TARGET_CY8CKIT-062S2-43012.lib : https://github.com/cypresssemiconductorco/TARGET_CY8CKIT-062S2-43012/#latest-v2.X

# MTB2.2 and .mtb approach , make sure below mtb files are present
echo https://github.com/cypresssemiconductorco/TARGET_CY8CKIT-062S2-43012#latest-v2.X#\$\$ASSET_REPO\$\$/TARGET_CY8CKIT-062S2-43012/latest-v2.X > deps/TARGET_CY8CKIT-062S2-43012.mtb

  4. Modify the example for your Wi-Fi SSID parameters in lowpower_task.h 

    #define WIFI_SSID                         "SSID"
#define WIFI_PASSWORD                     "PASSWORD"
#define WIFI_SECURITY                     CY_WCM_SECURITY_WPA2_MIXED_PSK

  5. The wait_net_suspend() used in lowpower_task.c allows the host MCU to go to deep-sleep and stay in deep-sleep until woken up by an external event. 

    wait_net_suspend(wifi, portMAX_DELAY, INACTIVE_INTERVAL_MS, INACTIVE_WINDOW_MS);

  6. Make sure below Makefile changes present if LPA version used is greater than 3.0.0 

    COMPONENTS=WCM SECURE_SOCKETS

# For MTB2.2, below change

CY_GETLIBS_SHARED_PATH=../
CY_GETLIBS_SHARED_NAME=mtb_shared

  7. Configure the ARP offload. The easiest way to configure ARP offload is to use the ModusToolbox Device Configurator.

    • Navigate to ModusToolbox installation folder and launch the ModusToolbox Device Configurator (<install_dir>/tools_2.2/device-configurator).

    • Select File->Open, navigate to the board’s design.modus file, and open it: mtb-example-anycloud-wlan-lowpower/COMPONENT_CUSTOM_DESIGN_MODUS/TARGET_CY8CKIT-062S2-43012/design.modus

    • If the design.modus file does not open and pops with a error message No device support library path provided , then point to the psoc6pdl folder inside the mtb-example-anycloud-wlan-lowpower/libs/psoc6pdl/devicesupport.xml (For MTB2.2, point to mtb_shared/mtb-pdl-cat1/<>/devicesupport.xml) file in the window popup. This is because the design.modus file will update its path to the PDL directory when it is opened for the first time.

    • Switch to the “Pins” tab, enable P4[1] pin, specify its name as “CYBSP_WIFI_HOST_WAKE”, in the “Parameters” pane change “Interrupt Trigger Type” to “Rising Edge”. If you are using a different pioneer kit, refer to its guide for Host<->Device connection pinout.

    • Switch to the connectivity device “CYW943012WKWBG” tab (in case the CY8CKIT_062S2_43012 board is used).

    • Enable Power->Wi-Fi.

    • In “Wi-Fi - Parameters” pane enable “Host Wake Configuration” and set “Host Device Interrupt Pin” to “CYBSP_WIFI_HOST_WAKE”.

    • Enable ARP offload.

    • Set “ARP offload Feature(s)” to “Peer Auto Reply”.

    • Enable “Snoop Host IP From Traffic When ARP Offload Enabled”.

    • Set “ARP Offload Cache Entries Expire after (s)” to 1200.

    • Save the configuration to generate the necessary code.

  8. Build the project and program the board. The following command is example for the CY8CKIT_062S2_43012 board, using GCC_ARM as the toolchain: 

    make getlibs
make program TARGET=CY8CKIT-062S2-43012 TOOLCHAIN=GCC_ARM

    When the modified mtb-example-anycloud-wlan-lowpower starts, the console output shows that it connects to the specified above Wi-Fi Access Point, and then the PSoC 6 MCU goes to System Deep Sleep. 

    =======================================================
CE230106 - AnyCloud Example: WLAN Lowpower
=======================================================

WLAN MAC Address : D4:4D:A4:A0:02:A4
WLAN Firmware    : wl0: Jan 27 2020 21:57:29 version 13.10.271.236 (5a526db) FWID 01-61e2b002
WLAN CLM         : API: 18.2 Data: 9.10.0 Compiler: 1.36.1 ClmImport: 1.34.1 Creation: 2020-01-27 21:54:33
WHD VERSION      : v1.80.0 : v1.80.0 : GCC 7.2 : 2020-03-10 04:09:17 -0500
Info:Connecting to AP
IP Address 10.0.0.201 assigned
Info:Successfully joined Wi-Fi network 'SSID'.
Info:Beacon period = 100, DTIM period = 3

Network Stack Suspended, MCU will enter DeepSleep power mode
Resuming Network Stack, Network stack was suspended for 15253ms

=====================================================
WHD Stats..
tx_total:64, rx_total:71, tx_no_mem:0, rx_no_mem:0
tx_fail:0, no_credit:0, flow_control:0
Bus Stats..
cmd52:2286, cmd53_read:366, cmd53_write:559
cmd52_fail:0, cmd53_read_fail:0, cmd53_write_fail:0
oob_intrs:72, sdio_intrs:147, error_intrs:0, read_aborts:0
=====================================================
Network is active. Resuming network stack
Network Stack Suspended, MCU will enter DeepSleep power mode

  9. Check the board operation. Use a PC to connect to the same Wi-Fi Access Point as the PSoC 6 board.

    • Send a “ping” command to the board and observe in the serial terminal that the PSoC 6 MCU wakes up for each command: 

      C:\>ping -n 3 10.0.0.201

Pinging 10.0.0.201 with 32 bytes of data:
Reply from 10.0.0.201: bytes=32 time=319ms TTL=255
Reply from 10.0.0.201: bytes=32 time=233ms TTL=255
Reply from 10.0.0.201: bytes=32 time=151ms TTL=255

Ping statistics for 10.0.0.201:
  Packets: Sent = 3, Received = 3, Lost = 0 (0% loss),
Approximate round trip times in milli-seconds:
  Minimum = 151ms, Maximum = 319ms, Average = 234ms

<Terminal logs >
Resuming Network Stack, Network stack was suspended for 2456ms

=====================================================
WHD Stats..
tx_total:174, rx_total:198, tx_no_mem:0, rx_no_mem:0
tx_fail:0, no_credit:0, flow_control:0
Bus Stats..
cmd52:2638, cmd53_read:1001, cmd53_write:796
cmd52_fail:0, cmd53_read_fail:0, cmd53_write_fail:0
oob_intrs:199, sdio_intrs:401, error_intrs:0, read_aborts:0
=====================================================
Network is active. Resuming network stack

Network Stack Suspended, MCU will enter DeepSleep power mode

    • Send an “arping” command as follows and observe that the PSoC 6 MCU is in Deep Sleep mode. 

      C:\>arp-ping.exe -n 3 10.0.0.201
Reply that D4:4D:A4:A0:02:A4 is 10.0.0.201 in 113.078ms
Reply that D4:4D:A4:A0:02:A4 is 10.0.0.201 in 1115.498ms
Reply that D4:4D:A4:A0:02:A4 is 10.0.0.201 in 1113.863ms

Ping statistics for 10.0.0.201/arp
   3 probes sent.
   3 successful, 0 failed.
Approximate trip times in milli-seconds:
   Minimum = 113.078ms, Maximum = 1115.498ms, Average = 780.813ms

      Use any available ARPping tool. As an example:

      Since the WLAN device’s ARP cache is empty on the initial ARP request from the peer, it looks up the IP details from the host and updates its ARP cache. This causes the host to wake up because of network activity between the host MCU and the WLAN device. On subsequent ARP requests from the peer, the host remains asleep. The WLAN device continues to respond to the ARP request as it has the ARP data available in its ARP cache.

    • Verify the ARP offload is working as desired. Refer to the How to Measure Power Consumption section for corresponding instructions. The following oscilloscope screen capture shows current measurement with the ARP offload enabled:

      ../../../_images/FreeRTOS_ARP_Enable1.png

      While the WLAN device (purple graph) high spikes responds to each request, the PSoC 6 host (blue graph) is in System Deep Sleep mode.

  10. Disable the ARP Offload feature and observe that the PSoC 6 Host wakes up on each request. Launch the ModusToolbox Device Configurator and open the appropriate design.modus file. Select the “CYW943012WKWBG” tab, select Power->Wi-Fi personality, and disable ARP offload by de-selecting the check box next to “ARP offload”. Save the configuration. Then, build and program the application. With ARP offload disabled, the Host MCU (PSoC 6) will wake for every ARP request.

    ../../../_images/FreeRTOS_ARP_Disable1.png

AFR

The following steps are required to set up the afr-example-wlan-offloads example and enable the ARP offload feature:

  1. Checkout Wi-Fi Low Offloads Example app 

    git clone https://github.com/cypresssemiconductorco/amazon-freertos.git --recurse-submodules
cd amazon-freertos/projects/cypress/
git clone https://github.com/cypresssemiconductorco/afr-example-wlan-offloads.git
cd afr-example-wlan-offloads

  2. Make sure below FreeRTOSConfig.h changes are present:

    configUSE_TICKLESS_IDLE : This change to support Tickless Deep Sleep mode 

    #include <cycfg_system.h>

#if (CY_CFG_PWR_SYS_IDLE_MODE == CY_CFG_PWR_MODE_SLEEP) || (CY_CFG_PWR_SYS_IDLE_MODE == CY_CFG_PWR_MODE_DEEPSLEEP)
extern void vApplicationSleep( uint32_t xExpectedIdleTime );
#define portSUPPRESS_TICKS_AND_SLEEP( xIdleTime ) vApplicationSleep( xIdleTime )
#define configUSE_TICKLESS_IDLE  2
#endif
#if CY_CFG_PWR_DEEPSLEEP_LATENCY > 0
#define configEXPECTED_IDLE_TIME_BEFORE_SLEEP   CY_CFG_PWR_DEEPSLEEP_LATENCY
#endif

  3. Modify the example for your Wi-Fi SSID parameters in wifi_config.h 

    #define WIFI_SSID                         "SSID"
#define WIFI_PASSWORD                     "PASSWORD"
#define WIFI_SECURITY                     eWiFiSecurityWPA2

  4. Modify below macro in wlan_offload.h to use offload configurations from ModusToolbox Device Configurator 

    #define USE_CONFIGURATOR_GENERATED_CONFIG    (1)

  5. The wait_net_suspend() used in wlan_offload.c allows the host MCU to go to deep-sleep and stay in deep-sleep until woken up by an external event. 

    wait_net_suspend(wifi, portMAX_DELAY, INACTIVE_INTERVAL_MS, INACTIVE_WINDOW_MS);

  6. Configure the ARP offload. The easiest way to configure ARP offload is to use the ModusToolbox Device Configurator.

    • Navigate to ModusToolbox installation folder and launch the ModusToolbox Device Configurator (<install_dir>/tools_2.2/device-configurator).

    • Select File->Open, navigate to the board’s design.modus file, and open it: amazon-freertos/projects/cypress/afr-example-wlan-offloads/COMPONENT_CUSTOM_DESIGN_MODUS/TARGET_CY8CKIT-062S2-43012/design.modus

    • If the design.modus file does not open and pops with a error message No device support library path provided , then point to the psoc6pdl folder inside the amazon-freertos/vendors/cypress/psoc6/psoc6pdl/devicesupport.xml file in the window popup. This is because the design.modus file will update its path to the PDL directory when it is opened for the first time.

    • Switch to the “Pins” tab, enable P4[1] pin, specify its name as “CYBSP_WIFI_HOST_WAKE”, in the “Parameters” pane change “Interrupt Trigger Type” to “Rising Edge”. If you are using a different pioneer kit, refer to its guide for Host<->Device connection pinout.

    • Switch to the connectivity device “CYW943012WKWBG” tab (in case the CY8CKIT_062S2_43012 board is used).

    • Enable Power->Wi-Fi.

    • In “Wi-Fi - Parameters” pane enable “Host Wake Configuration” and set “Host Device Interrupt Pin” to “CYBSP_WIFI_HOST_WAKE”.

    • Enable ARP offload.

    • Set “ARP offload Feature(s)” to “Peer Auto Reply”.

    • Enable “Snoop Host IP From Traffic When ARP Offload Enabled”.

    • Set “ARP Offload Cache Entries Expire after (s)” to 1200.

    • Save the configuration to generate the necessary code.

  7. Build the project using CMake / Make.

    The following command is example for the CY8CKIT_062S2_43012 board, using GCC_ARM as the toolchain:

    CMake 

    cd amazon-freertos/projects/cypress/afr-example-wlan-offloads
cmake -DVENDOR=cypress -DBOARD=CY8CKIT_062S2_43012 -DCOMPILER=arm-gcc -S . -B build -G Ninja -DCMAKE_TOOLCHAIN_FILE=../../../tools/cmake/toolchains/arm-gcc.cmake
cmake --build build --clean-first

    Make 

    cd amazon-freertos/projects/cypress/afr-example-wlan-offloads
make build TARGET=CY8CKIT-062S2-43012 TOOLCHAIN=GCC_ARM

  8. Program the board with afr-example-wlan-offloads.elf file generated under below folder using Cypress Programmer CMake : amazon-freertos/projects/cypress/afr-example-wlan-offloads/build/ Make : amazon-freertos/build/cy/afr-example-wlan-offloads/CY8CKIT-062S2-43012/Debug When the modified afr-example-wlan-offloads starts, the console output shows that it connects to the specified above Wi-Fi Access Point, and then the PSoC 6 MCU goes to System Deep Sleep. 

    Info: ==================================
Info: AFR Example: WLAN Offloads
Info: ==================================

WLAN MAC Address : D4:4D:A4:A0:02:A4
WLAN Firmware    : wl0: Jan 27 2020 21:57:29 version 13.10.271.236 (5a526db) FWID 01-61e2b002
WLAN CLM         : API: 18.2 Data: 9.10.0 Compiler: 1.36.1 ClmImport: 1.34.1 Creation: 2020-01-27 21:54:33
WHD VERSION      : v1.90.2 : v1.90.2 : GCC 9.2 : 2020-04-13 02:49:57 -0500
Info: --Offload Manager is initialized with the device configurator generated configuration--
Info: Wi-Fi module initialized. Connecting to AP...
Info: Wi-Fi connected to AP: SSID
Info: IP Address acquired: 192.168.43.11
Error: Unable to find TKO offloads configuration
Error: tcp_socket_connection_start: Offload descriptor TKO not found. No TCP connection has been established.
Check the TCP Keepalive offload settings in ModusToolbox Device Configurator tool
Error: One or more TCP socket connections failed.

Network Stack Suspended, MCU will enter DeepSleep power mode
Resuming Network Stack, Network stack was suspended for 27547ms

=====================================================
WHD Stats..
tx_total:81, rx_total:80, tx_no_mem:0, rx_no_mem:0
tx_fail:0, no_credit:0, flow_control:0
Bus Stats..
cmd52:2339, cmd53_read:402, cmd53_write:583
cmd52_fail:0, cmd53_read_fail:0, cmd53_write_fail:0
oob_intrs:79, sdio_intrs:167, error_intrs:0, read_aborts:0
=====================================================
Network is active. Resuming network stack

Network Stack Suspended, MCU will enter DeepSleep power mode

  9. Check the board operation. Use a PC to connect to the same Wi-Fi Access Point as the PSoC 6 board.

    • Send a “ping” command to the board and observe in the serial terminal that the PSoC 6 MCU wakes up for each command: 

      C:\>ping 192.168.43.11 -n 3

Pinging 192.168.43.11 with 32 bytes of data:
Reply from 192.168.43.11: bytes=32 time=360ms TTL=255
Reply from 192.168.43.11: bytes=32 time=1394ms TTL=255
Reply from 192.168.43.11: bytes=32 time=10ms TTL=255

Ping statistics for 192.168.43.11:
    Packets: Sent = 3, Received = 3, Lost = 0 (0% loss),
Approximate round trip times in milli-seconds:
    Minimum = 10ms, Maximum = 1394ms, Average = 588ms

<Terminal logs >
Resuming Network Stack, Network stack was suspended for 2456ms

=====================================================
WHD Stats..
tx_total:174, rx_total:198, tx_no_mem:0, rx_no_mem:0
tx_fail:0, no_credit:0, flow_control:0
Bus Stats..
cmd52:2638, cmd53_read:1001, cmd53_write:796
cmd52_fail:0, cmd53_read_fail:0, cmd53_write_fail:0
oob_intrs:199, sdio_intrs:401, error_intrs:0, read_aborts:0
=====================================================
Network is active. Resuming network stack

Network Stack Suspended, MCU will enter DeepSleep power mode

    • Send an “arping” command as follows and observe that the PSoC 6 MCU is in Deep Sleep mode. 

      C:\>arp-ping.exe -n 3 192.168.43.11
Reply that D4:4D:A4:A0:02:A4 is 192.168.43.11 in 114.427ms
Reply that D4:4D:A4:A0:02:A4 is 192.168.43.11 in 114.142ms
Reply that D4:4D:A4:A0:02:A4 is 192.168.43.11 in 1114.262ms

Ping statistics for 192.168.43.11/arp
3 probes sent.
     3 successful, 0 failed.
Approximate trip times in milli-seconds:
     Minimum = 114.142ms, Maximum = 1114.262ms, Average = 447.610ms

      Use any available ARPping tool. As an example:

      Since the WLAN device’s ARP cache is empty on the initial ARP request from the peer, it looks up the IP details from the host and updates its ARP cache. This causes the host to wake up because of network activity between the host MCU and the WLAN device. On subsequent ARP requests from the peer, the host remains asleep. The WLAN device continues to respond to the ARP request as it has the ARP data available in its ARP cache.

    • Verify the ARP offload is working as desired. Refer to the How to Measure Power Consumption section for corresponding instructions. The following oscilloscope screen capture shows current measurement with the ARP offload enabled:

      ../../../_images/afr_arp_enable_low1.png

      While the WLAN device (purple graph) high spikes responds to each request, the PSoC 6 host (blue graph) is in System Deep Sleep mode.

  10. Disable the ARP Offload feature and observe that the PSoC 6 Host wakes up on each request. Launch the ModusToolbox Device Configurator and open the appropriate design.modus file. Select the “CYW943012WKWBG” tab, select Power->Wi-Fi personality, and disable ARP offload by de-selecting the check box next to “ARP offload”. Save the configuration. Then, build and program the application. With ARP offload disabled, the Host MCU (PSoC 6) will wake for every ARP request.

    ../../../_images/afr_arp_disable_low1.png

Wi-Fi Packet Filter Offload

Packet filters allow the host processor to limit which types of packets get passed up to the host processor from the WLAN subsystem. This is useful to keep out unwanted / unneeded packets from the network that might otherwise wake the host out of a power-saving System Deep Sleep mode or prevent it from entering System Deep Sleep mode.

Packet filters are useful when:

  • Trying to keep the host processor in System Deep Sleep for as long as possible.

  • Trying to get the host processor into System Deep Sleep as soon as possible.

Whenever a WLAN packet is destined for the host, the WLAN processor must awaken the host (if it is asleep) so it can retrieve the packet for processing. Often times the host network stack processes the packet only to discover that the packet should be thrown away, because it is not needed. For example, it is destined for a port or service that is being used. Packet filters allow these types of packets to be filtered and discarded by the WLAN processor so the host is not interrupted.

Filter Types

The following types of packet filters are supported, based on a standard IP Stack:

../../../_images/PacketFiletr1.png

A general purpose STA might want these types of packets:

  • Ether type ARP

  • IP protocol ICMP

  • TCP port 22 (ssh)

  • UDP port 68 (DHCP)

Other packet types are highly dependent on what applications and data types are in use. Multiple filters may be configured to operate simultaneously.

Network Layer / Ether Types

The EtherType filter is based on a 16-bit ethertype field present in ethernet packets, and it is the lowest level of the TC/IP stack. A technical description and list of choices can be found in numerous places, such as Ether Type.

The most commonly used protocols (and most useful filters) are:

  • IP (value 0x800)

  • ARP (value 0x806).

Filtering on IP would match any and all IP packets coming from the network. This is a very coarsely grained filter and it will include all ICMP, TCP, and UDP packets as shown in the diagram above. Filtering on ARP is finer grained, and it will only match on ARP packets. Filtering all IP will have an enormous impact due to the large number of packets it will match and is generally not recommended for general usage.

Valid EtherType filters consist of a 16-bit number greater than or equal to 0x800.

Transport Layer / IP Protocols

The next layer up the stack is the Transport layer, which consists of various IP protocols such as TCP, UDP, and ICMP. Discussions of the protocols themselves are outside the realm of this document, but are widely available. A list of protocol numbers is also widely available, including: IP Protocol Numbers.

IP Protocol filters consist of a single 8-bit number. No checking is done to see if this number matches a well-known protocol since it is possible for vendors to use proprietary numbers and protocols.

Filtering on one IP protocol will only match that protocol. For example, filtering on UDP would match a UDP packet, but not ICMP or TCP packets. However, matching on TCP is still very coarsely grained and will likely include the majority of packets destined for the host processor (depending on your environment). Port numbers are the next level of filter refinement.

Applications Layer / TCP & UDP Port Numbers

The applications layer distinguishes between various applications based on Port numbers. These are simply well-known numbers used to identify various TCP and UDP based applications. Technical discussions about port numbers and list of numbers that belong to which applications can be found widely on the internet, for example: TCP and UDP Port Numbers.

Port filters are 16-bit port numbers as described above. With a port number filter, you can filter on, for example, only ssh packets (port 22), only on ftp packets (port 20), or any other of the many applications listed above.

Due to the large number and constantly changing port definitions, the OLM makes no attempt to sanity check these values.

IP packets have both source and destination ports. Destination ports are the well-known port numbers described in the link above and generally the most useful. Source ports describe the temporary, ephemeral port numbers used by the host sending the packets. These are generated on the fly and not well known. Since they are not known ahead of time, creating a filter for them is difficult. Port ranges can be used to match a wide range of source ports to cover this case.

Port filters support optional port ranges. A port range describes a start and end such that any port number within that start-end range will match. This is most useful for matching a short-lived ephemeral source port number since it will not be known ahead of time.

Since both TCP and UDP use port numbers, filters are configured to match one or the other (TCP or UDP). If both TCP and UDP need to be filtered for a particular port, two filters can be created; one for each.

Action (Keep vs Toss)

Filters can be configured to either Keep (send to host) or Toss (drop / discard). When configured to drop, only the specified packets are dropped, while any others not specifically filtered are passed to the host. Likewise, when configured to keep packets, only the specified packets are passed to the host and the rest discarded. The most helpful model is to use only ‘keep’ filters. In other words, use ‘keep’ filters to specify the complete list of packet types the host is interested in, and discard the rest. This works because (usually) it is much simpler to list the packets the host wants to receive versus creating a complete list of packets it doesn’t want.

When using keep filters, use care to allow enough packets through for networking protocols to work properly. For instance, the processor must be able to join a network, get a DHCP address, respond to ARP requests, and possibly share network keys. Not creating enough keep filters to allow all these type of packets through will prevent the host from joining the network. A reasonable minimal set of keep filters includes:

  • Keep, EtherType 0x806 #Allow ARP through

  • Keep, EtherType 0x888e #Allow security packets through

  • Keep, Port Filter: UDP Dest Port 68 #Allow DHCP packets through.

These additional filters might also be needed depending on your application:

  • Keep, Port Filter: UDP, Source Port 53 #Allow DNS packet (use source port)

  • Keep, Port Filter: TCP Dest Port 8883 #Allow Secure MQTT packets

  • Keep, Port Filter: TCP Dest Port 1883 #Allow Open MQTT packets

These ‘keep’ filters will keep only the packet types as described; all other traffic will be discarded so it is critical to use enough filters to allow your application to receive the traffic it needs. This type of configuration is useful when your system receives many different kinds of traffic and it is easier to describe the traffic to be kept rather than the traffic to be discarded.

Alternatively, it is often simpler to describe the specific type of traffic to be discarded and keeping everything else. For example, someone on the network keeps pinging your machine (using ICMP packets) and waking it. You’d like to block ICMP and keep everything else. In this case, just one filter is needed:

  • Discard, IPType 1 # toss ICMP packet

This will discard all incoming ping/ICMP packets and keep all other traffic.

There are no minimal filters for toss filters because the system will filter the specific packets and everything else gets passed up to the host.

Note All active filters need to be of the same type (keep or toss). Mixing active keep and toss filters will cause unexpected behaviors.

Below diagram shows packet filter offload with ICMP packet configured to be discarded

../../../_images/pf_ping_packet_discard1.png

When Active (Sleep vs Wake)

Filters can be configured to be active either when the host processor is active or asleep, or both. When a filter is not active, it has no effect. When the system goes into sleep mode, it disables all wake filters and enables all sleep filters just before entering sleep. When waking, all sleep filters are disabled and wake filters enabled.

  • Wake filters allow the host to go into sleep mode faster.

  • Sleep filters help the host stay asleep longer.

Normally, without packet filters, the WLAN subsystem passes all packets destined for the host up to the host network stack for processing. If the host is in System Deep Sleep, the WLAN subsystem will first wake the host and then pass the packet up to the stack. From there, the network stack will pass the packet on to the application that is listening for that type of packet. If no applications are listening for that type of packet, the network stack drops the packet.

For instance:

  • An http packet arrives on port 80, but there is no http server running that would read the packet (port 80 is default http port).

  • An ssh packet arrives on port 22, but there is no ssh server running that would read that packet (port 22 is default ssh port).

In both cases, the host would awake from its battery saving System Deep Sleep just to drop a packet. It is not hard to imagine scenarios where traffic your application doesn’t want or doesn’t care about ends up penalizing your battery usage by constantly waking the host from System Deep Sleep. Alternatively, these unwanted packets can also prevent the host from entering System Deep Sleep in the first place. The host has an idle sleep threshold. When the host has been idle longer than that threshold, it will put itself to sleep. Processing unwanted packets (even just dropping them) will cause the host to come out of idle and prevent it from reaching the idle sleep threshold, preventing the host from entering sleep. In both cases, traffic patterns keep the processor awake, burning power.

Quick Start Guide

This Quick Start Guide demonstrates of how to configure and use the Packet Filter feature in the Mbed OS/ FreeRTOS environment and its impact on the system power consumption.

MBEDOS

The mbed-os-example-wifi is used as a base for this guide on the CY8CKIT_062S2_43012 pioneer kit. This section assumes that a user has an Mbed OS development environment configured. Refer to https://os.mbed.com/getting-started/ to setup Mbed OS develop environment.

The following steps are required to setup the mbed-os-example-wifi example with enabling the Packet Filter feature:

  1. Import the mbed-os-example-wifi example project and switch to the example directory: 

    mbed import mbed-os-example-wifi
cd mbed-os-example-wifi

  2. Execute the following command in order to replace Mbed OS, download the LPA middleware and connectivity utilities: 

    mbed add https://github.com/cypresssemiconductorco/lpa/
mbed add https://github.com/cypresssemiconductorco/connectivity-utilities/
mbed deploy

  3. Modify the example for your Wi-Fi SSID parameters:

    • Modify mbed_app.json to update “wifi-ssid” and “wifi-password” values as desired: 

      ...
    "wifi-ssid": {
        "help": "WiFi SSID",
        "value": "\"SSID\""
    },
    "wifi-password": {
        "help": "WiFi Password",
        "value": "\"PASSWORD\""
    }
...

    • Add “MBED” Component to mbed_app.json in target_overrides section which is required for compiling helpers in LPA code

      ”target.components_add”: [“MBED”]

      {
     "target_overrides": {
         "*": {
              "platform.stdio-convert-newlines": true,
              "target.components_add": ["MBED"]
         }
     }
}

    • Optional: modify main.cpp to update Wi-Fi security settings: 

      int ret = wifi->connect(MBED_CONF_APP_WIFI_SSID, MBED_CONF_APP_WIFI_PASSWORD, NSAPI_SECURITY_WPA_WPA2);
      Modify the last parameter if needed to either: 
      NSAPI_SECURITY_NONE
NSAPI_SECURITY_WEP
NSAPI_SECURITY_WPA
NSAPI_SECURITY_WPA2
NSAPI_SECURITY_WPA_WPA2
NSAPI_SECURITY_WPA3

  4. Modify main.cpp to go to deep-sleep after connecting to the Wi-Fi Access Point. MBED uses LWIP as the network stack. LWIP has periodic timers (smallest timer ~100ms), which wake up the Host MCU periodically. Do the following to suspend these timers, so the Host MCU can be in deep-sleep for a longer time. This is needed to demonstrate / verify Packet Filter(s) are not waking up the Host MCU.

    • Include WhdSTAInterface.h and network_activity_handler.h: 

      #include "WhdSTAInterface.h"
#include "network_activity_handler.h"

    • Add the following declarations: 

      // This macro specifies the interval in milliseconds that the device monitors
// the network for inactivity. If the network is inactive for duration lesser
// than INACTIVE_WINDOW_MS in this interval, the MCU does not suspend the network
// stack and informs the calling function that the MCU wait period timed out
// while waiting for network to become inactive.

#define INACTIVE_INTERVAL_MS    (300u)

// This macro specifies the continuous duration in milliseconds for which the
// network has to be inactive. If the network is inactive for this duration, the
// MCU will suspend the network stack. Now, the MCU will not need to service the
// network timers which allows it to stay longer in sleep/deepsleep.

#define INACTIVE_WINDOW_MS      (200u)

    • Modify main.cpp to allow the host MCU to go to deep-sleep and stay in deep-sleep until woken up by an external event. For this, replace the line “wifi->disconnect();” with the following code: 

      while(true) {
    wait_net_suspend(static_cast<WhdSTAInterface*>(wifi),
       osWaitForever, INACTIVE_INTERVAL_MS, INACTIVE_WINDOW_MS);
}

  5. Configure Packet Filters, the preferred way to is to use ModusToolbox IDE.

    • Mandatory steps to avoid design.modus file modification in mbed-os folder

      1. Copy folder mbed-os-example-wifi/mbed-os/targets/TARGET_Cypress/TARGET_PSOC6/TARGET_CY8CKIT_062S2_43012 to mbed-os-example-wifi folder

      2. Delete all files in mbed-os-example-wifi/TARGET_CY8CKIT_062S2_43012 except COMPONENT_BSP_DESIGN_MODUS folder and its contents

      3. Rename mbed-os-example-wifi/TARGET_CY8CKIT_062S2_43012/COMPONENT_BSP_DESIGN_MODUS to mbed-os-example-wifi/TARGET_CY8CKIT_062S2_43012/CUSTOM_BSP_DESIGN_MODUS

      4. Delete design.cyqspi and design.cycapsense file in mbed-os-example-wifi/TARGET_CY8CKIT_062S2_43012/CUSTOM_BSP_DESIGN_MODUS

      5. Add/update mbed_app.json in mbed-os-example-wifi folder with below details (This will tell mbed to ignore the BSP configuration shipped with MbedOS) 

        {
     "target_overrides": {
         "*": {
              "platform.stdio-convert-newlines": true,
              "target.components_remove": ["BSP_DESIGN_MODUS"]
         }
     }
 }

      6. If mbed-os branch used is 5.15 or above, please do the below changes as well

        • update mbed_app.json with below line in “target_overrides”: 

          "target.components_add": ["CUSTOM_DESIGN_MODUS"]

    • Navigate to ModusToolbox installation folder and launch the ModusToolbox Device Configurator (<install_dir>/tools_2.2/device-configurator).

    • Select File->Open, navigate to the board’s design.modus file, and open it: mbed-os-example-wifi/TARGET_CY8CKIT_062S2_43012/CUSTOM_BSP_DESIGN_MODUS/design.modus

    • If the design.modus file does not open and pops with a error message No device support library path provided , then point to the psoc6pdl folder inside the mbed-os/targets/TARGET_Cypress/TARGET_PSOC6/psoc6pdl/devicesupport.xml file in the window popup. This is because the design.modus file will update its path to the PDL directory when it is opened for the first time.

    • Switch to the “Pins” tab, enable P4[1] pin, specify its name as “CYBSP_WIFI_HOST_WAKE”, in the “Parameters” pane change “Interrupt Trigger Type” to “Rising Edge”. If you are using a different pioneer kit, refer to its guide for Host<->Device connection pinout.

    • Switch to the connectivity device “CYW943012WKWBG” tab (in case the CY8CKIT_062S2_43012 board is used).

    • Enable Power->Wi-Fi.

    • In “Wi-Fi - Parameters” pane enable “Host Wake Configuration” and set “Host Device Interrupt Pin” to “CYBSP_WIFI_HOST_WAKE”.

    • Disable ARP offload.

    • Enable “Add minimal set of keep filters”, these filters allow ARP, DNS, DHCP and 802.1x security packets to wake up the Host, and are needed to connect to WiFi Access point, any other WiFi packets are dropped by WLAN chip and not forwarded to the Host MCU (PSoC6)

    • Save the configuration to generate the necessary code.

  6. Build the project and program the board. The following command is example for the CY8CKIT_062S2_43012 board, using GCC_ARM as the toolchain: 

    mbed compile -DMBED_TICKLESS -DMBED_CPU_STATS_ENABLED --target CY8CKIT_062S2_43012 --toolchain GCC_ARM --flash --sterm

    Note If you cannot program the board, make sure the board DAP-Link mode is selected. Refer to the guide of your kit of how to change the mode.

    MBED_CPU_STATS_ENABLED : This helps to understand how much time MCU remained in sleep state

    When the modified mbed-os-example-wifi starts, the console output lists available Wi-Fi networks. It then connects to the specified above Wi-Fi Access Point, and then the PSoC 6 MCU goes to System Deep Sleep. 

    Scan:
WLAN MAC Address : D4:4D:A4:A0:02:A4
WLAN Firmware    : wl0: Oct 29 2019 22:00:20 version 13.10.271.215 (r723093) FWID 01-f268ebc9
WLAN CLM         : API: 18.2 Data: 9.10.0 Compiler: 1.36.1 ClmImport: 1.34.1 Creation: 2019-10-29 21:50:17
WHD VERSION      : v1.50.0-rc1 : v1.50.0-rc1 : GCC 7.3 : 2019-10-30 18:42:31 +0530
Network: airport_5g secured: WPA2 BSSID: 24:A2:E1:f0:50:25 RSSI: -84 Ch: 36
Network: Broadcom secured: None BSSID: 0:10:18:ee:b5:f7 RSSI: -52 Ch: 36
Network: test_2nd_cy secured: WPA2 BSSID: F8:32:E4:b0:ff:8c RSSI: -74 Ch: 36
Network: eero secured: WPA2 BSSID: F8:BB:BF:b2:2:54 RSSI: -33 Ch: 36
Network: WWD secured: WPA/WPA2 BSSID: 64:A5:C3:64:16:13 RSSI: -77 Ch: 36
Network: eero secured: WPA/WPA2 BSSID: F8:BB:BF:b1:74:b4 RSSI: -36 Ch: 36
Network: eero secured: WPA/WPA2 BSSID: F8:BB:BF:69:2b:8 RSSI: -46 Ch: 36
Network: prke-bsh5g secured: WPA/WPA2 BSSID: 44:4E:6D:45:b0:58 RSSI: -82 Ch: 36
Network:  secured: Unknown BSSID: F8:BB:BF:b2:2:52 RSSI: -33 Ch: 36
Network: testap secured: None BSSID: 0:A0:50:30:81:65 RSSI: -64 Ch: 36
Network: RW1 secured: WPA2 BSSID: C8:8:73:3c:87:2c RSSI: -75 Ch: 40
Network: CYFI secured: WPA2 BSSID: B0:B8:67:3b:ac:70 RSSI: -86 Ch: 44
Network: CYFI secured: WPA2 BSSID: 80:8D:B7:69:77:30 RSSI: -70 Ch: 44
Network: CYFI_GUEST secured: None BSSID: 80:8D:B7:69:77:31 RSSI: -70 Ch: 44
Network: CYFI_ZOOM secured: WPA2 BSSID: 80:8D:B7:69:77:32 RSSI: -70 Ch: 44
15 networks available.

Connecting to SSID...
Success

MAC: d4:4d:a4:a0:02:a4
IP: 192.168.1.12
Netmask: 255.255.255.0
Gateway: 192.168.1.1
RSSI: -29

Network Stack Suspended, MCU will enter DeepSleep power mode

  7. Check the board operation. Use a PC to connect to the same Wi-Fi Access Point as the PSoC 6 board.

    • Send “ping” command to the board and observe in serial terminal that it does not wake up the PSoC 6 device since there is no “keep” packet filter for ICMP pings, there is no response for the pings: 

      C:\>ping 192.168.1.12
 
Pinging 192.168.1.12 with 32 bytes of data:
Request timed out.
Request timed out.
 
Ping statistics for 192.168.1.12:
    Packets: Sent = 2, Received = 0, Lost = 2 (100% loss),

    • Send an “arping” command as follows and observe that the PSoC 6 MCU is in Deep Sleep mode. Use any available ARPping tool. As an example:

      • Windows: https://www.elifulkerson.com/projects/arp-ping.php

      • Mac : http://macappstore.org/arping/

      • linux : sudo apt install arping; arping [ip address] 

        C:\>arp-ping.exe 192.168.1.12
Reply that D4:4D:A4:A0:02:A4 is 192.168.1.12 in 1127.934ms
Reply that D4:4D:A4:A0:02:A4 is 192.168.1.12 in 1116.976ms
Reply that D4:4D:A4:A0:02:A4 is 192.168.1.12 in 1124.160ms
Reply that D4:4D:A4:A0:02:A4 is 192.168.1.12 in 1119.439ms

Ping statistics for 192.168.1.12/arp
  4 probes sent.
  4 successful, 0 failed.
Approximate trip times in milli-seconds:
  Minimum = 1116.976ms, Maximum = 1127.934ms, Average = 1122.127ms

      Observe that PSoC 6 MCU wakes up for each command since there is “keep” packet filter for ARP pings, the ARP pings are responded back: 

      Resuming Network Stack, Network stack was suspended for 396ms

=====================================================
WHD Stats..
tx_total:51, rx_total:405, tx_no_mem:0, rx_no_mem:0
tx_fail:0, no_credit:0, flow_control:0
Bus Stats..
cmd52:4525, cmd53_read:3086, cmd53_write:1064
cmd52_fail:0, cmd53_read_fail:0, cmd53_write_fail:0
oob_intrs:611, sdio_intrs:2067, error_intrs:0, read_aborts:0
=====================================================

Network Stack Suspended, MCU will enter DeepSleep power mode

  8. Verify the packet Filter is working as desired. Refer to the How to Measure Power Consumption section for corresponding instructions. The following oscilloscope screen capture shows current measurement with the Packet Filter enabled

    i. ARP Ping : This wakes up the host as packet filter for ARP is configured

    ../../../_images/packet_filter_arp_ping1.png

    ii. Ping : This doesnot wakeup the host as ICMP packet is not configured as packet filter type ../../../_images/packet_filter_ping1.png

FREERTOS

The following steps are required to setup the wifi-low-power example with enabling the Packet Filter feature:

  1. Checkout Wi-Fi Example app 

    git clone https://github.com/cypresssemiconductorco/mtb-example-anycloud-wlan-lowpower.git
cd mtb-example-anycloud-wlan-lowpower

  2. Make sure below FreeRTOSConfig.h changes are present:

    configUSE_TICKLESS_IDLE : This change to support Tickless Deep Sleep mode 

    #include <cycfg_system.h>

#if (CY_CFG_PWR_SYS_IDLE_MODE == CY_CFG_PWR_MODE_SLEEP) || (CY_CFG_PWR_SYS_IDLE_MODE == CY_CFG_PWR_MODE_DEEPSLEEP)
extern void vApplicationSleep( uint32_t xExpectedIdleTime );
#define portSUPPRESS_TICKS_AND_SLEEP( xIdleTime ) vApplicationSleep( xIdleTime )
#define configUSE_TICKLESS_IDLE  2
#endif

#if CY_CFG_PWR_DEEPSLEEP_LATENCY > 0
#define configEXPECTED_IDLE_TIME_BEFORE_SLEEP   CY_CFG_PWR_DEEPSLEEP_LATENCY
#endif

  3. Add lib file for TARGET_CY8CKIT-062S2-43012 in deps folder and delete deps/TARGET_CY8CPROTO-062-4343W.lib 

    TARGET_CY8CKIT-062S2-43012.lib : https://github.com/cypresssemiconductorco/TARGET_CY8CKIT-062S2-43012/#latest-v2.X

# MTB2.2 and .mtb approach , make sure below mtb files are present
echo https://github.com/cypresssemiconductorco/TARGET_CY8CKIT-062S2-43012#latest-v2.X#\$\$ASSET_REPO\$\$/TARGET_CY8CKIT-062S2-43012/latest-v2.X > deps/TARGET_CY8CKIT-062S2-43012.mtb

  4. Modify the example for your Wi-Fi SSID parameters in lowpower_task.h 

    #define WIFI_SSID                         "SSID"
#define WIFI_PASSWORD                     "PASSWORD"
#define WIFI_SECURITY                     CY_WCM_SECURITY_WPA2_MIXED_PSK

  5. The wait_net_suspend() used in lowpower_task.c allows the host MCU to go to deep-sleep and stay in deep-sleep until woken up by an external event. 

    wait_net_suspend(wifi, portMAX_DELAY, INACTIVE_INTERVAL_MS, INACTIVE_WINDOW_MS);

  6. Make sure below Makefile changes present if LPA version used is greater than 3.0.0 

    COMPONENTS=WCM SECURE_SOCKETS

# For MTB2.2, below change

CY_GETLIBS_SHARED_PATH=../
CY_GETLIBS_SHARED_NAME=mtb_shared

  7. Configure Packet Filters, the preferred way to is to use ModusToolbox IDE.

    • Navigate to ModusToolbox installation folder and launch the ModusToolbox Device Configurator (<install_dir>/tools_2.2/device-configurator).

    • Select File->Open, navigate to the board’s design.modus file, and open it: mtb-example-anycloud-wlan-lowpower/COMPONENT_CUSTOM_DESIGN_MODUS/TARGET_CY8CKIT-062S2-43012/design.modus

    • If the design.modus file does not open and pops with a error message No device support library path provided , then point to the psoc6pdl folder inside the mtb-example-anycloud-wlan-lowpower/libs/psoc6pdl/devicesupport.xml (For MTB2.2, point to mtb_shared/mtb-pdl-cat1/<>/devicesupport.xml) file in the window popup. This is because the design.modus file will update its path to the PDL directory when it is opened for the first time.

    • Switch to the “Pins” tab, enable P4[1] pin, specify its name as “CYBSP_WIFI_HOST_WAKE”, in the “Parameters” pane change “Interrupt Trigger Type” to “Rising Edge”. If you are using a different pioneer kit, refer to its guide for Host<->Device connection pinout.

    • Switch to the connectivity device “CYW943012WKWBG” tab (in case the CY8CKIT_062S2_43012 board is used).

    • Enable Power->Wi-Fi.

    • In “Wi-Fi - Parameters” pane enable “Host Wake Configuration” and set “Host Device Interrupt Pin” to “CYBSP_WIFI_HOST_WAKE”.

    • Disable ARP offload.

    • Enable “Add minimal set of keep filters”, these filters allow ARP, DNS, DHCP and 802.1x security packets to wake up the Host, and are needed to connect to WiFi Access point, any other WiFi packets are dropped by WLAN chip and not forwarded to the Host MCU (PSoC6)

    • Save the configuration to generate the necessary code.

  8. Build the project and program the board. The following command is example for the CY8CKIT_062S2_43012 board, using GCC_ARM as the toolchain: 

    make getlibs
make program TARGET=CY8CKIT-062S2-43012 TOOLCHAIN=GCC_ARM

    When the modified mtb-example-anycloud-wlan-lowpower starts, the console output shows that it connects to the specified above Wi-Fi Access Point, and then the PSoC 6 MCU goes to System Deep Sleep. 

    =======================================================
CE230106 - AnyCloud Example: WLAN Lowpower
=======================================================

WLAN MAC Address : D4:4D:A4:A0:02:A4
WLAN Firmware    : wl0: Jan 27 2020 21:57:29 version 13.10.271.236 (5a526db) FWID 01-61e2b002
WLAN CLM         : API: 18.2 Data: 9.10.0 Compiler: 1.36.1 ClmImport: 1.34.1 Creation: 2020-01-27 21:54:33
WHD VERSION      : v1.80.0 : v1.80.0 : GCC 7.2 : 2020-03-10 04:09:17 -0500
Info:Connecting to AP
IP Address 10.0.0.201 assigned
Info:Successfully joined Wi-Fi network 'SSID'.
Info:Beacon period = 100, DTIM period = 3

Network Stack Suspended, MCU will enter DeepSleep power mode
Resuming Network Stack, Network stack was suspended for 15253ms

=====================================================
WHD Stats..
tx_total:64, rx_total:71, tx_no_mem:0, rx_no_mem:0
tx_fail:0, no_credit:0, flow_control:0
Bus Stats..
cmd52:2286, cmd53_read:366, cmd53_write:559
cmd52_fail:0, cmd53_read_fail:0, cmd53_write_fail:0
oob_intrs:72, sdio_intrs:147, error_intrs:0, read_aborts:0
=====================================================
Network is active. Resuming network stack
Network Stack Suspended, MCU will enter DeepSleep power mode

  9. Check the board operation. Use a PC to connect to the same Wi-Fi Access Point as the PSoC 6 board.

    • Send “ping” command to the board and observe in serial terminal that it does not wake up the PSoC 6 MCU since there is no “keep” packet filter for ICMP pings, there is no response for the pings: 

      C:\>ping -n 3 10.0.0.201

Pinging 10.0.0.201 with 32 bytes of data:
Request timed out.
Request timed out.
Request timed out.

Ping statistics for 10.0.0.201:
    Packets: Sent = 3, Received = 0, Lost = 3 (100% loss),

    • Send an “arping” command as follows and observe that the PSoC 6 MCU is in Deep Sleep mode. Use any available ARPping tool. As an example:

      • Windows: https://www.elifulkerson.com/projects/arp-ping.php

      • Mac : http://macappstore.org/arping/

      • linux : sudo apt install arping; arping [ip address] 

        C:\>arp-ping.exe -n 3 10.0.0.201
Reply that D4:4D:A4:A0:02:A4 is 10.0.0.201 in 113.209ms
Reply that D4:4D:A4:A0:02:A4 is 10.0.0.201 in 125.789ms
Reply that D4:4D:A4:A0:02:A4 is 10.0.0.201 in 1114.333ms

Ping statistics for 10.0.0.201/arp
    3 probes sent.
    3 successful, 0 failed.
Approximate trip times in milli-seconds:
    Minimum = 113.209ms, Maximum = 1114.333ms, Average = 451.111ms

      Observe that PSoC 6 MCU wakes up for each command since there is “keep” packet filter for ARP pings, the ARP pings are responded back: 

      Resuming Network Stack, Network stack was suspended for 2456ms

=====================================================
WHD Stats..
tx_total:174, rx_total:198, tx_no_mem:0, rx_no_mem:0
tx_fail:0, no_credit:0, flow_control:0
Bus Stats..
cmd52:2638, cmd53_read:1001, cmd53_write:796
cmd52_fail:0, cmd53_read_fail:0, cmd53_write_fail:0
oob_intrs:199, sdio_intrs:401, error_intrs:0, read_aborts:0
=====================================================
Network is active. Resuming network stack

Network Stack Suspended, MCU will enter DeepSleep power mode

  10. Verify the packet Filter is working as desired. Refer to the How to Measure Power Consumption section for corresponding instructions. The following oscilloscope screen capture shows current measurement with the Packet Filter enabled

    i. ARP Ping : This wakes up the host as packet filter for ARP is configured

    ../../../_images/FreeRTOS_PF_ARP_ping1.png

    ii. Ping : This doesnot wakeup the host as ICMP packet is not configured as packet filter type ../../../_images/FreeRTOS_PF_ping_nowake1.png

AFR

The following steps are required to setup the afr-example-wlan-offloads example with enabling the Packet Filter feature:

  1. Checkout Wi-Fi Low Offloads Example app 

    git clone https://github.com/cypresssemiconductorco/amazon-freertos.git --recurse-submodules
cd amazon-freertos/projects/cypress/
git clone https://github.com/cypresssemiconductorco/afr-example-wlan-offloads.git
cd afr-example-wlan-offloads

  2. Make sure below FreeRTOSConfig.h changes are present:

    configUSE_TICKLESS_IDLE : This change to support Tickless Deep Sleep mode 

    #include <cycfg_system.h>

#if (CY_CFG_PWR_SYS_IDLE_MODE == CY_CFG_PWR_MODE_SLEEP) || (CY_CFG_PWR_SYS_IDLE_MODE == CY_CFG_PWR_MODE_DEEPSLEEP)
extern void vApplicationSleep( uint32_t xExpectedIdleTime );
#define portSUPPRESS_TICKS_AND_SLEEP( xIdleTime ) vApplicationSleep( xIdleTime )
#define configUSE_TICKLESS_IDLE  2
#endif

#if CY_CFG_PWR_DEEPSLEEP_LATENCY > 0
#define configEXPECTED_IDLE_TIME_BEFORE_SLEEP   CY_CFG_PWR_DEEPSLEEP_LATENCY
#endif

  3. Modify the example for your Wi-Fi SSID parameters in wifi_config.h 

    #define WIFI_SSID                         "SSID"
#define WIFI_PASSWORD                     "PASSWORD"
#define WIFI_SECURITY                     eWiFiSecurityWPA2

  4. Modify below macro in wlan_offload.h to use offload configurations from ModusToolbox Device Configurator 

    #define USE_CONFIGURATOR_GENERATED_CONFIG    (1)

  5. The wait_net_suspend() used in wlan_offload.c allows the host MCU to go to deep-sleep and stay in deep-sleep until woken up by an external event. 

    wait_net_suspend(wifi, portMAX_DELAY, INACTIVE_INTERVAL_MS, INACTIVE_WINDOW_MS);

  6. Configure Packet Filters, the preferred way to is to use ModusToolbox IDE.

    • Navigate to ModusToolbox installation folder and launch the ModusToolbox Device Configurator (<install_dir>/tools_2.2/device-configurator).

    • Select File->Open, navigate to the board’s design.modus file, and open it: amazon-freertos/projects/cypress/afr-example-wlan-offloads/COMPONENT_CUSTOM_DESIGN_MODUS/TARGET_CY8CKIT-062S2-43012/design.modus

    • If the design.modus file does not open and pops with a error message No device support library path provided , then point to the psoc6pdl folder inside the amazon-freertos/vendors/cypress/psoc6/psoc6pdl/devicesupport.xml file in the window popup. This is because the design.modus file will update its path to the PDL directory when it is opened for the first time.

    • Switch to the “Pins” tab, enable P4[1] pin, specify its name as “CYBSP_WIFI_HOST_WAKE”, in the “Parameters” pane change “Interrupt Trigger Type” to “Rising Edge”. If you are using a different pioneer kit, refer to its guide for Host<->Device connection pinout.

    • Switch to the connectivity device “CYW943012WKWBG” tab (in case the CY8CKIT_062S2_43012 board is used).

    • Enable Power->Wi-Fi.

    • In “Wi-Fi - Parameters” pane enable “Host Wake Configuration” and set “Host Device Interrupt Pin” to “CYBSP_WIFI_HOST_WAKE”.

    • Disable ARP offload.

    • Enable “Add minimal set of keep filters”, these filters allow ARP, DNS, DHCP and 802.1x security packets to wake up the Host, and are needed to connect to WiFi Access point, any other WiFi packets are dropped by WLAN chip and not forwarded to the Host MCU (PSoC6)

    • Save the configuration to generate the necessary code.

  7. Build the project using CMake / Make.

    The following command is example for the CY8CKIT_062S2_43012 board, using GCC_ARM as the toolchain:

    CMake 

    cd amazon-freertos/projects/cypress/afr-example-wlan-offloads
cmake -DVENDOR=cypress -DBOARD=CY8CKIT_062S2_43012 -DCOMPILER=arm-gcc -S . -B build -G Ninja -DCMAKE_TOOLCHAIN_FILE=../../../tools/cmake/toolchains/arm-gcc.cmake
cmake --build build --clean-first

    Make 

    cd amazon-freertos/projects/cypress/afr-example-wlan-offloads
make build TARGET=CY8CKIT-062S2-43012 TOOLCHAIN=GCC_ARM

  8. Program the board with afr-example-wlan-offloads.elf file generated under below folder using Cypress Programmer CMake : amazon-freertos/projects/cypress/afr-example-wlan-offloads/build/ Make : amazon-freertos/build/cy/afr-example-wlan-offloads/CY8CKIT-062S2-43012/Debug

    When the modified afr-example-wlan-offloads starts, the console output shows that it connects to the specified above Wi-Fi Access Point, and then the PSoC 6 MCU goes to System Deep Sleep. 

    Info: ==================================
Info: AFR Example: WLAN Offloads
Info: ==================================

WLAN MAC Address : D4:4D:A4:A0:02:A4
WLAN Firmware    : wl0: Jan 27 2020 21:57:29 version 13.10.271.236 (5a526db) FWID 01-61e2b002
WLAN CLM         : API: 18.2 Data: 9.10.0 Compiler: 1.36.1 ClmImport: 1.34.1 Creation: 2020-01-27 21:54:33
WHD VERSION      : v1.90.2 : v1.90.2 : GCC 9.2 : 2020-04-13 02:49:57 -0500
Info: --Offload Manager is initialized with the device configurator generated configuration--
Info: Wi-Fi module initialized. Connecting to AP...
Info: Wi-Fi connected to AP: SSID
Info: IP Address acquired: 192.168.43.11
Error: Unable to find TKO offloads configuration
Error: tcp_socket_connection_start: Offload descriptor TKO not found. No TCP connection has been established.
Check the TCP Keepalive offload settings in ModusToolbox Device Configurator tool
Error: One or more TCP socket connections failed.

Network Stack Suspended, MCU will enter DeepSleep power mode
Resuming Network Stack, Network stack was suspended for 27547ms

=====================================================
WHD Stats..
tx_total:81, rx_total:80, tx_no_mem:0, rx_no_mem:0
tx_fail:0, no_credit:0, flow_control:0
Bus Stats..
cmd52:2339, cmd53_read:402, cmd53_write:583
cmd52_fail:0, cmd53_read_fail:0, cmd53_write_fail:0
oob_intrs:79, sdio_intrs:167, error_intrs:0, read_aborts:0
=====================================================
Network is active. Resuming network stack

Network Stack Suspended, MCU will enter DeepSleep power mo

  9. Check the board operation. Use a PC to connect to the same Wi-Fi Access Point as the PSoC 6 board.

    • Send “ping” command to the board and observe in serial terminal that it does not wake up the PSoC 6 device since there is no “keep” packet filter for ICMP pings, there is no response for the pings: 

      C:\>ping 192.168.43.11 -n 3

Pinging 192.168.43.11 with 32 bytes of data:
Request timed out.
Request timed out.
Request timed out.

Ping statistics for 192.168.43.11:
 Packets: Sent = 3, Received = 0, Lost = 3 (100% loss),

    • Send an “arping” command as follows and observe that the PSoC 6 MCU is in Deep Sleep mode. Use any available ARPping tool. As an example:

      • Windows: https://www.elifulkerson.com/projects/arp-ping.php

      • Mac : http://macappstore.org/arping/

      • linux : sudo apt install arping; arping [ip address] 

        C:\>arp-ping.exe -n 3 192.168.43.11
Reply that D4:4D:A4:A0:02:A4 is 192.168.43.11 in 1113.866ms
Reply that D4:4D:A4:A0:02:A4 is 192.168.43.11 in 1113.747ms
Reply that D4:4D:A4:A0:02:A4 is 192.168.43.11 in 1113.806ms

Ping statistics for 192.168.43.11/arp
  3 probes sent.
     3 successful, 0 failed.
Approximate trip times in milli-seconds:
     Minimum = 1113.747ms, Maximum = 1113.866ms, Average = 1113.806ms

      Observe that PSoC 6 MCU wakes up for each command since there is “keep” packet filter for ARP pings, the ARP pings are responded back: 

      Resuming Network Stack, Network stack was suspended for 2456ms

=====================================================
WHD Stats..
tx_total:174, rx_total:198, tx_no_mem:0, rx_no_mem:0
tx_fail:0, no_credit:0, flow_control:0
Bus Stats..
cmd52:2638, cmd53_read:1001, cmd53_write:796
cmd52_fail:0, cmd53_read_fail:0, cmd53_write_fail:0
oob_intrs:199, sdio_intrs:401, error_intrs:0, read_aborts:0
=====================================================
Network is active. Resuming network stack

Network Stack Suspended, MCU will enter DeepSleep power mode

  10. Verify the packet Filter is working as desired. Refer to the How to Measure Power Consumption section for corresponding instructions. The following oscilloscope screen capture shows current measurement with the Packet Filter enabled

    i. ARP Ping : This wakes up the host as packet filter for ARP is configured

    ../../../_images/afr_pf_arpping_wake_low1.png

    ii. Ping : This doesnot wakeup the host as ICMP packet is not configured as packet filter type ../../../_images/afr_pf_ping_sleep_low1.png

Wi-Fi TCP Keep Alive Offload

TCP Keepalive Offload part of the Low Power Assistant is designed to improve the power consumption of your connected system by reducing the time the Host needs to stay awake to support TCP Keepalive Request. This document describes how to enable TCP Keep alive Offload and configure 4 different sockets for TCP keepalive that can be incorporated into your project from Cypress GitHub LPA Middleware.

TCP Keepalive maintains idle TCP connections by periodically passing packets between the client and server. If either the client or server does not respond to a packet, the connection is considered inactive and is terminated. This helps in pruning dead connections. Typically TCP Keepalives are sent every 45 or 60 seconds on an idle TCP connection, and the connection is dropped after 3 sequential ACKs are missed. This means Host MCU has to wake up periodically to send TCP Keepalive packet to maintain TCP connection during idle state.

TCP Keepalive Offload helps in moving this functionality to WLAN firmware so that Host MCU doesnot need to wake up periodically to send/receive TCP Keepalive packets. This functionality is offloaded only when Host MCU goes to sleep and network stack is suspended

../../../_images/TCP_Keepalive_basic_graph1.png

Quick Start Guide

This Quick Start Guide demonstrates of how to configure and use the TCP Keep alive offload feature in the Mbed OS & FreeRTOS environment and its impact on the system power consumption.

MBEDOS

The mbed-os-example-wifi is used as a base for this guide on the CY8CKIT_062S2_43012 pioneer kit. This section assumes that you have an Mbed OS development environment configured. Refer to https://os.mbed.com/getting-started/ for instructions about how to do that.

The following steps are required to set up the mbed-os-example-wifi example and enable the TCP Keepalive offload feature:

  1. Import the mbed-os-example-wifi example project and switch to the example directory: 

    mbed import mbed-os-example-wifi
cd mbed-os-example-wifi

  2. Execute the following command in order to replace Mbed OS, download the LPA middleware and connectivity utilities: 

    mbed add https://github.com/cypresssemiconductorco/lpa/
mbed add https://github.com/cypresssemiconductorco/connectivity-utilities/
mbed deploy

  3. Modify the example for your Wi-Fi SSID parameters:

    • Modify mbed_app.json to update “wifi-ssid” and “wifi-password” values as desired: 

      ...
    "wifi-ssid": {
        "help": "WiFi SSID",
        "value": "\"SSID\""
    },
    "wifi-password": {
        "help": "WiFi Password",
        "value": "\"PASSWORD\""
    }
...

    • Add “MBED” Component to mbed_app.json in target_overrides section which is required for compiling helpers in LPA code

      ”target.components_add”: [“MBED”]

      {
     "target_overrides": {
         "*": {
              "platform.stdio-convert-newlines": true,
              "target.components_add": ["MBED"]
         }
     }
}

  4. Replace main.cpp with this (main.txt) which is configuring TCP Keepalive offload based on the configurator parameters (Copy main.txt as main.cpp)

    • Optional: modify main.cpp to update Wi-Fi security settings: 

      int ret = wifi->connect(MBED_CONF_APP_WIFI_SSID, MBED_CONF_APP_WIFI_PASSWORD, NSAPI_SECURITY_WPA_WPA2);
      Modify the last parameter if needed to either: 
      NSAPI_SECURITY_NONE
NSAPI_SECURITY_WEP
NSAPI_SECURITY_WPA
NSAPI_SECURITY_WPA2
NSAPI_SECURITY_WPA_WPA2
NSAPI_SECURITY_WPA3

  5. Configure the TCP Keepalive offload. There are two ways to configure the TCP keep-alive offload one via Device configurator and other via Manual Configuration

    i. The easiest way to configure TCP Keepalive offload is to use the ModusToolbox Device Configurator.

    • Mandatory steps to avoid design.modus file modification in mbed-os folder

      1. Copy folder mbed-os-example-wifi/mbed-os/targets/TARGET_Cypress/TARGET_PSOC6/TARGET_CY8CKIT_062S2_43012 to mbed-os-example-wifi folder

      2. Delete all files in mbed-os-example-wifi/TARGET_CY8CKIT_062S2_43012 except COMPONENT_BSP_DESIGN_MODUS folder and its contents

      3. Rename mbed-os-example-wifi/TARGET_CY8CKIT_062S2_43012/COMPONENT_BSP_DESIGN_MODUS to mbed-os-example-wifi/TARGET_CY8CKIT_062S2_43012/CUSTOM_BSP_DESIGN_MODUS

      4. Delete design.cyqspi and design.cycapsense file in mbed-os-example-wifi/TARGET_CY8CKIT_062S2_43012/CUSTOM_BSP_DESIGN_MODUS

      5. Add/update mbed_app.json in mbed-os-example-wifi folder with below details (This will tell mbed to ignore the BSP configuration shipped with MbedOS) 

        {
     "target_overrides": {
         "*": {
              "platform.stdio-convert-newlines": true,
              "target.components_remove": ["BSP_DESIGN_MODUS"]
         }
     }
 }

      6. If mbed-os branch used is 5.15 or above, please do the below changes as well

        • update mbed_app.json with below line in “target_overrides”: 

          "target.components_add": ["CUSTOM_DESIGN_MODUS"]

    • Navigate to ModusToolbox installation folder and launch the ModusToolbox Device Configurator (<install_dir>/tools_2.2/device-configurator).

    • Select File->Open, navigate to the board’s design.modus file, and open it: mbed-os-example-wifi/TARGET_CY8CKIT_062S2_43012/CUSTOM_BSP_DESIGN_MODUS/design.modus

    • If the design.modus file does not open and pops with a error message No device support library path provided , then point to the psoc6pdl folder inside the mbed-os/targets/TARGET_Cypress/TARGET_PSOC6/psoc6pdl/devicesupport.xml file in the window popup. This is because the design.modus file will update its path to the PDL directory when it is opened for the first time.

    • Switch to the “Pins” tab, enable P4[1] pin, specify its name as “CYBSP_WIFI_HOST_WAKE”, in the “Parameters” pane change “Interrupt Trigger Type” to “Rising Edge”. If you are using a different pioneer kit, refer to its guide for Host<->Device connection pinout.

    • Switch to the connectivity device “CYW943012WKWBG” tab (in case the CY8CKIT_062S2_43012 board is used).

    • Enable Power->Wi-Fi.

    • In “Wi-Fi - Parameters” pane enable “Host Wake Configuration” and set “Host Device Interrupt Pin” to “CYBSP_WIFI_HOST_WAKE”.

    • Enable TCP Keep Alive Offload.

    • Configure Interval, Retry Interval, Retry Count

    • Configure Source port, Destination port, Destination IP address (TCP server)

    • Save the configuration to generate the necessary code.

    ii. The manual configuration Steps

    • Read the OLM configuration from device configurator and make a copy of OLM device configurator Code Snippet 6: Read OLM configuration from device configurator.

    • search for “TKO” name in the device configurator list, if present then use it establish TCP connection Code Snippet 5: Use cy_tcp_create_socket_connection to offload TCP Keep-alive to WiFi Firmware

    • If TCP Keep-alive offload is not present in device configurator then add TCP keep-alive offload list Code Snippet 3: Search for TCP KA offload in the device configurator list.

    • call the API to restart olm Code Snippet 4: Use cylpa_restart_olm when the OLM configuration is changed by the user application.

    • Establish TCP connection Code Snippet 5: Use cy_tcp_create_socket_connection to offload TCP Keep-alive to WiFi Firmware

    • TCP keep-alive offload will be enabled when host MCU goes to sleep Code Snippet 1: Using wait_net_suspend for suspend/resume network stack

    • Note The maximum supported TCP connections that can be offloaded to WLAN device is 4 (MAX_TKO) this is WLAN firmware limitation, if the API Code Snippet 5: Use cy_tcp_create_socket_connection to offload TCP Keep-alive to WiFi Firmware is invoked more than 4 times then LIFO ( Last In First Out) Algorithm is followed where the MRU(Most Recently Used) TCP connections will only be offloaded to WLAN device.

  6. Use a PC to connect to the same Wi-Fi Access Point as the PSoC 6 board. Run tcp_echo_server.py in that PC to act as TCP Server. This script works only for Python version 2.7 

    python tcp_echo_server.py --port 3360

  7. Build the project and program the board. The following command is example for the CY8CKIT_062S2_43012 board, using GCC_ARM as the toolchain: 

    mbed compile -DMBED_TICKLESS -DMBED_CPU_STATS_ENABLED --target CY8CKIT_062S2_43012 --toolchain GCC_ARM --flash --sterm

    Note If you cannot program the board, make sure the board DAP-Link mode is selected. Refer to the guide of your kit of how to change the mode.

    MBED_CPU_STATS_ENABLED : This helps to understand how much time MCU remained in sleep state

    When the modified mbed-os-example-wifi starts, the console output lists available Wi-Fi networks. It then connects to the specified above Wi-Fi Access Point, connects to TCP server using the configurator settings and then the PSoC 6 MCU goes to System Deep Sleep. 

    Scan:
WLAN MAC Address : DC:EF:CA:00:36:3B
WLAN Firmware    : wl0: Sep  5 2019 23:24:33 version 7.45.98.92 (r722362 CY) FWID 01-f7128517
WLAN CLM         : API: 12.2 Data: 9.10.39 Compiler: 1.29.4 ClmImport: 1.36.3 Creation: 2019-09-05 23:10:00
WHD VERSION      : v1.50.0-rc1 : v1.50.0-rc1 : GCC 7.3 : 2019-10-30 18:42:31 +0530
Network: eero secured: WPA2 BSSID: F8:BB:BF:b1:74:b3 RSSI: -67 Ch: 1
Network: eero secured: WPA2 BSSID: F8:BB:BF:69:2b:6 RSSI: -65 Ch: 1
Network:  secured: None BSSID: F8:BB:BF:b2:2:55 RSSI: -71 Ch: 1
Network:  secured: Unknown BSSID: F8:BB:BF:b2:2:51 RSSI: -72 Ch: 1
Network: eero secured: Unknown BSSID: F8:BB:BF:b2:2:53 RSSI: -69 Ch: 1
Network: TPUT2G secured: None BSSID: A0:63:91:d1:45:55 RSSI: -85 Ch: 1
Network: SilverFox secured: WPA2 BSSID: AC:22:B:ce:f9:10 RSSI: -41 Ch: 1
Network: ape secured: WPA2 BSSID: 24:A2:E1:f0:50:24 RSSI: -84 Ch: 1
Network: 2GAP secured: None BSSID: 0:90:4C:12:d2:7 RSSI: -90 Ch: 1
Network: test_2nd_cy secured: WPA2 BSSID: F8:32:E4:b0:ff:88 RSSI: -69 Ch: 1
Network: r6300 secured: WPA2 BSSID: 4:A1:51:19:e:e RSSI: -70 Ch: 4
Network: 1STLEE_CH6 secured: WPA2 BSSID: 0:10:18:ee:b6:ea RSSI: -69 Ch: 6
Network: prasanna-acrg secured: None BSSID: 0:10:18:e2:e9:b1 RSSI: -67 Ch: 6
Network: CYFI secured: Unknown BSSID: B0:B8:67:3b:27:e0 RSSI: -54 Ch: 6
Network: steveo_test_2g secured: WPA2 BSSID: 84:1B:5E:e5:63:a5 RSSI: -60 Ch: 6
15 networks available.

Connecting to testtko...
Success

MAC: dc:ef:ca:00:36:3b
IP: 192.168.1.16
Netmask: 255.255.255.0
Gateway: 192.168.1.1
RSSI: -31

TKO is enabled via configurator
Set LWIP keepalive: Interval 20, Retry Interval 3, keepalive value 20
Socket[0]: Created connection to IP 192.168.1.13, local port 3353, remote port 3360
Socket[1]: ERROR -3004, Unable to connect:  IP 0.0.0.0, local port 0, remote port 0
Socket[2]: ERROR -3004, Unable to connect:  IP 0.0.0.0, local port 0, remote port 0
Socket[3]: ERROR -3004, Unable to connect:  IP 0.0.0.0, local port 0, remote port 0

Network Stack Suspended, MCU will enter DeepSleep power mode

TCP Keepalive device configurator reference:

../../../_images/TCPKA_deviceConfigurator1.png

Verify the TCP Keepalive offload is working as desired.Refer to the How to Measure Power Consumption section for corresponding instructions. The following oscilloscope screen capture shows current measurement with

TCP Keepalive Offload enabled with 20 seconds interval configuration: ../../../_images/tcp_keepalive_enabled1.png

FREERTOS

The following steps are required to setup the wifi-low-power tcp keepalive offload example and enable the TCP Keepalive offload feature.

  1. Checkout Wi-Fi TCP Keepalive offload Example app 

    git clone https://github.com/cypresssemiconductorco/mtb-example-anycloud-offload-tcp-keepalive.git
cd mtb-example-anycloud-offload-tcp-keepalive

  2. Make sure below FreeRTOSConfig.h changes are present:

    configUSE_TICKLESS_IDLE : This change to support Tickless Deep Sleep mode 

    #include <cycfg_system.h>

#if (CY_CFG_PWR_SYS_IDLE_MODE == CY_CFG_PWR_MODE_SLEEP) || (CY_CFG_PWR_SYS_IDLE_MODE == CY_CFG_PWR_MODE_DEEPSLEEP)
extern void vApplicationSleep( uint32_t xExpectedIdleTime );
#define portSUPPRESS_TICKS_AND_SLEEP( xIdleTime ) vApplicationSleep( xIdleTime )
#define configUSE_TICKLESS_IDLE  2
#endif

#if CY_CFG_PWR_DEEPSLEEP_LATENCY > 0
#define configEXPECTED_IDLE_TIME_BEFORE_SLEEP   CY_CFG_PWR_DEEPSLEEP_LATENCY
#endif

  3. Add lib file for TARGET_CY8CKIT-062S2-43012 in deps folder and delete deps/TARGET_CY8CPROTO-062-4343W.lib 

    TARGET_CY8CKIT-062S2-43012.lib : https://github.com/cypresssemiconductorco/TARGET_CY8CKIT-062S2-43012/#latest-v2.X

# MTB2.2 and .mtb approach , make sure below mtb files are present
echo https://github.com/cypresssemiconductorco/TARGET_CY8CKIT-062S2-43012#latest-v2.X#\$\$ASSET_REPO\$\$/TARGET_CY8CKIT-062S2-43012/latest-v2.X > deps/TARGET_CY8CKIT-062S2-43012.mtb

  4. Modify the example for your Wi-Fi SSID parameters in app_config.h 

    #define WIFI_SSID                         "SSID"
#define WIFI_PASSWORD                     "PASSWORD"
#define WIFI_SECURITY                     CY_WCM_SECURITY_WPA2_MIXED_PSK

  5. The wait_net_suspend() used in tcp_keepalive_offload.c allows the host MCU to go to deep-sleep and stay in deep-sleep until woken up by an external event. 

    wait_net_suspend(wifi, portMAX_DELAY, NETWORK_INACTIVE_INTERVAL_MS, NETWORK_INACTIVE_WINDOW_MS);

  6. Configure the TCP Keepalive offload. There are two ways to configure the TCP keep-alive offload one via Device configurator and other via Manual Configuration

    i. The easiest way to configure TCP Keepalive offload is to use the ModusToolbox Device Configurator.

    • Navigate to ModusToolbox installation folder and launch the ModusToolbox Device Configurator (<install_dir>/tools_2.2/device-configurator).

    • Select File->Open, navigate to the board’s design.modus file, and open it: mtb-example-anycloud-offload-tcp-keepalive/COMPONENT_CUSTOM_DESIGN_MODUS/TARGET_CY8CKIT-062S2-43012/design.modus

    • If the design.modus file does not open and pops with a error message No device support library path provided , then point to the psoc6pdl folder inside the mtb-example-anycloud-offload-tcp-keepalive/libs//psoc6pdl/devicesupport.xml (For MTB2.2, point to mtb_shared/mtb-pdl-cat1/<>/devicesupport.xml) file in the window popup. This is because the design.modus file will update its path to the PDL directory when it is opened for the first time.

    • Switch to the “Pins” tab, enable P4[1] pin, specify its name as “CYBSP_WIFI_HOST_WAKE”, in the “Parameters” pane change “Interrupt Trigger Type” to “Rising Edge”. If you are using a different pioneer kit, refer to its guide for Host<->Device connection pinout.

    • Switch to the connectivity device “CYW943012WKWBG” tab (in case the CY8CKIT_062S2_43012 board is used).

    • Enable Power->Wi-Fi.

    • In “Wi-Fi - Parameters” pane enable “Host Wake Configuration” and set “Host Device Interrupt Pin” to “CYBSP_WIFI_HOST_WAKE”.

    • Enable TCP Keep Alive Offload.

    • Configure Interval, Retry Interval, Retry Count

    • Configure Source port, Destination port, Destination IP address (TCP server)

    • Save the configuration to generate the necessary code.

    ii. Manual configuration steps

    • Read the OLM configuration from device configurator and make a copy of OLM device configurator Code Snippet 2: Read OLM configuration from device configurator.

    • search for “TKO” name in the device configurator list, if present then use it establish TCP connection Code Snippet 5: Use cy_tcp_create_socket_connection to offload TCP Keep-alive to WiFi Firmware

    • If TCP Keep-alive offload is not present in device configurator then add TCP keep-alive offload list Code Snippet 3: Search for TCP KA offload in the device configurator list.

    • call the API to restart olm Code Snippet 4: Use cylpa_restart_olm when the OLM configuration is changed by the user application.

    • Establish TCP connection Code Snippet 5: Use cy_tcp_create_socket_connection to offload TCP Keep-alive to WiFi Firmware

    • TCP keep-alive offload will be enabled when host MCU goes to sleep Code Snippet 1: Using wait_net_suspend for suspend/resume network stack

    • Note The maximum supported TCP connections that can be offloaded to WLAN device is 4 (MAX_TKO) this is WLAN firmware limitation, if the API Code Snippet 5: Use cy_tcp_create_socket_connection to offload TCP Keep-alive to WiFi Firmware is invoked more than 4 times then LIFO ( Last In First Out) Algorithm is followed where the MRU(Most Recently Used) TCP connections will only be offloaded to WLAN device.

  7. Use a PC to connect to the same Wi-Fi Access Point as the PSoC 6 board. Run tcp_echo_server.py in that PC to act as TCP Server 

    python tcp_echo_server.py --port 3360

  8. Make sure below Makefile changes present if LPA version used is greater than 3.0.0 

    COMPONENTS=WCM SECURE_SOCKETS

# For MTB2.2, below change

CY_GETLIBS_SHARED_PATH=../
CY_GETLIBS_SHARED_NAME=mtb_shared

  9. Build the project and program the board. The following command is example for the CY8CKIT_062S2_43012 board, using GCC_ARM as the toolchain: 

    make getlibs
make program TARGET=CY8CKIT-062S2-43012 TOOLCHAIN=GCC_ARM

    When the modified mtb-example-connectivity-offload-tcp-keepalive starts, the console output lists available Wi-Fi networks. It then connects to the specified above Wi-Fi Access Point, and then the PSoC 6 MCU goes to System Deep Sleep. 

    Info: ============================================
Info: AnyCloud Example: WLAN TCP Keepalive Offload
Info: ============================================

WLAN MAC Address : D4:4D:A4:A0:02:A4
WLAN Firmware    : wl0: Jan 27 2020 21:57:29 version 13.10.271.236 (5a526db) FWID 01-61e2b002
WLAN CLM         : API: 18.2 Data: 9.10.0 Compiler: 1.36.1 ClmImport: 1.34.1 Creation: 2020-01-27 21:54:33
WHD VERSION      : v1.80.0 : v1.80.0 : GCC 7.2 : 2020-03-10 04:09:17 -0500
Wi-Fi initialization is successful
Join to AP: SSID
IP Address 192.168.43.11 assigned
Successfully joined wifi network SSID
Taking TCP Keepalive configuration from the Generated sources.
TCP remote IP Address f2ba8c0  remote port:3360
TCP Connection Established Successfully ctx:8011050
Socket[0]: Created connection to IP 192.168.43.15, local port 3353, remote port 3360
Skipped TCP socket connection for socket id[1]. Check the TCP Keepalive configuration.
Skipped TCP socket connection for socket id[2]. Check the TCP Keepalive configuration.
Skipped TCP socket connection for socket id[3]. Check the TCP Keepalive configuration.
Low power task created
whd_tko_toggle: Successfully enabled

Network Stack Suspended, MCU will enter DeepSleep power mode

  10. Verify the TCP Keepalive offload is working as desired.Refer to the How to Measure Power Consumption section for corresponding instructions.The following oscilloscope screen capture shows current measurement with

TCP Keepalive Offload enabled with 20 seconds interval configuration and WLAN DTIM configured as 3 : ../../../_images/FreeRTOS_TKO_Enable1.png

AFR

The following steps are required to setup the afr-example-wlan-offloads example and enable the TCP Keepalive offload feature.

  1. Checkout Wi-Fi TCP Keepalive offload Example app 

    git clone https://github.com/cypresssemiconductorco/amazon-freertos.git --recurse-submodules
cd amazon-freertos/projects/cypress/
git clone https://github.com/cypresssemiconductorco/afr-example-wlan-offloads.git
cd afr-example-wlan-offloads

  2. Make sure below FreeRTOSConfig.h changes are present:

    configUSE_TICKLESS_IDLE : This change to support Tickless Deep Sleep mode 

    #include <cycfg_system.h>

#if (CY_CFG_PWR_SYS_IDLE_MODE == CY_CFG_PWR_MODE_SLEEP) || (CY_CFG_PWR_SYS_IDLE_MODE == CY_CFG_PWR_MODE_DEEPSLEEP)
extern void vApplicationSleep( uint32_t xExpectedIdleTime );
#define portSUPPRESS_TICKS_AND_SLEEP( xIdleTime ) vApplicationSleep( xIdleTime )
#define configUSE_TICKLESS_IDLE  2
#endif
#if CY_CFG_PWR_DEEPSLEEP_LATENCY > 0
#define configEXPECTED_IDLE_TIME_BEFORE_SLEEP   CY_CFG_PWR_DEEPSLEEP_LATENCY
#endif

  3. Modify the example for your Wi-Fi SSID parameters in wifi_config.h 

    #define WIFI_SSID                         "SSID"
#define WIFI_PASSWORD                     "PASSWORD"
#define WIFI_SECURITY                     eWiFiSecurityWPA2

  4. Modify below macro in wlan_offload.h to use offload configurations from ModusToolbox Device Configurator 

    #define USE_CONFIGURATOR_GENERATED_CONFIG    (1)

  5. The wait_net_suspend() used in wlan_offload.c allows the host MCU to go to deep-sleep and stay in deep-sleep until woken up by an external event. 

    wait_net_suspend(wifi, portMAX_DELAY, INACTIVE_INTERVAL_MS, INACTIVE_WINDOW_MS);

  6. Configure the TCP Keepalive offload. There are two ways to configure the TCP keep-alive offload one via Device configurator and other via Manual Configuration.

    i. The easiest way to configure TCP Keepalive offload is to use the ModusToolbox Device Configurator.

    • Navigate to ModusToolbox installation folder and launch the ModusToolbox Device Configurator (<install_dir>/tools_2.2/device-configurator).

    • Select File->Open, navigate to the board’s design.modus file, and open it: amazon-freertos/projects/cypress/afr-example-wlan-offloads/COMPONENT_CUSTOM_DESIGN_MODUS/TARGET_CY8CKIT-062S2-43012/design.modus

    • If the design.modus file does not open and pops with a error message No device support library path provided , then point to the psoc6pdl folder inside the amazon-freertos/vendors/cypress/psoc6/psoc6pdl/devicesupport.xml file in the window popup. This is because the design.modus file will update its path to the PDL directory when it is opened for the first time.

    • Switch to the “Pins” tab, enable P4[1] pin, specify its name as “CYBSP_WIFI_HOST_WAKE”, in the “Parameters” pane change “Interrupt Trigger Type” to “Rising Edge”. If you are using a different pioneer kit, refer to its guide for Host<->Device connection pinout.

    • Switch to the connectivity device “CYW943012WKWBG” tab (in case the CY8CKIT_062S2_43012 board is used).

    • Enable Power->Wi-Fi.

    • In “Wi-Fi - Parameters” pane enable “Host Wake Configuration” and set “Host Device Interrupt Pin” to “CYBSP_WIFI_HOST_WAKE”.

    • Enable TCP Keep Alive Offload.

    • Configure Interval, Retry Interval, Retry Count

    • Configure Source port, Destination port, Destination IP address (TCP server)

    • Save the configuration to generate the necessary code.

    ii. Manual configuration steps

    • Read the OLM configuration from device configurator and make a copy of OLM device configurator Code Snippet 2: Read OLM configuration from device configurator.

    • search for “TKO” name in the device configurator list, if present then use it establish TCP connection Code Snippet 5: Use cy_tcp_create_socket_connection to offload TCP Keep-alive to WiFi Firmware

    • If TCP Keep-alive offload is not present in device configurator then add TCP keep-alive offload list Code Snippet 3: Search for TCP KA offload in the device configurator list.

    • call the API to restart olm Code Snippet 4: Use cylpa_restart_olm when the OLM configuration is changed by the user application.

    • Establish TCP connection Code Snippet 5: Use cy_tcp_create_socket_connection to offload TCP Keep-alive to WiFi Firmware

    • TCP keep-alive offload will be enabled when host MCU goes to sleep Code Snippet 1: Using wait_net_suspend for suspend/resume network stack

    • Note The maximum supported TCP connections that can be offloaded to WLAN device is 4 (MAX_TKO) this is WLAN firmware limitation, if the API Code Snippet 5: Use cy_tcp_create_socket_connection to offload TCP Keep-alive to WiFi Firmware is invoked more than 4 times then LIFO ( Last In First Out) Algorithm is followed where the MRU(Most Recently Used) TCP connections will only be offloaded to WLAN device.

  7. Use a PC to connect to the same Wi-Fi Access Point as the PSoC 6 board. Run tcp_echo_server.py in that PC to act as TCP Server 

    python tcp_echo_server.py --port 3360

  8. Build the project using CMake / Make.

    The following command is example for the CY8CKIT_062S2_43012 board, using GCC_ARM as the toolchain:

    CMake 

    cd amazon-freertos/projects/cypress/afr-example-wlan-offloads
cmake -DVENDOR=cypress -DBOARD=CY8CKIT_062S2_43012 -DCOMPILER=arm-gcc -S . -B build -G Ninja -DCMAKE_TOOLCHAIN_FILE=../../../tools/cmake/toolchains/arm-gcc.cmake
cmake --build build --clean-first

    Make 

    cd amazon-freertos/projects/cypress/afr-example-wlan-offloads
make build TARGET=CY8CKIT-062S2-43012 TOOLCHAIN=GCC_ARM

  9. Program the board with afr-example-wlan-offloads.elf file generated under below folder using Cypress Programmer CMake : amazon-freertos/projects/cypress/afr-example-wlan-offloads/build/ Make : amazon-freertos/build/cy/afr-example-wlan-offloads/CY8CKIT-062S2-43012/Debug When the modified afr-example-wlan-offloads starts, the console output lists available Wi-Fi networks. It then connects to the specified above Wi-Fi Access Point, and then the PSoC 6 MCU goes to System Deep Sleep. 

    Info: ==================================
Info: AFR Example: WLAN Offloads
Info: ==================================

WLAN MAC Address : D4:4D:A4:A0:02:A4
WLAN Firmware    : wl0: Jan 27 2020 21:57:29 version 13.10.271.236 (5a526db) FWID 01-61e2b002
WLAN CLM         : API: 18.2 Data: 9.10.0 Compiler: 1.36.1 ClmImport: 1.34.1 Creation: 2020-01-27 21:54:33
WHD VERSION      : v1.90.2 : v1.90.2 : GCC 9.2 : 2020-04-13 02:49:57 -0500
Info: --Offload Manager is initialized with the device configurator generated configuration--
Info: Wi-Fi module initialized. Connecting to AP...
Info: Wi-Fi connected to AP: SSID
Info: IP Address acquired: 192.168.43.11
TCP remote IP Address c0a82b0f  remote port:3360
TCP local IP Address c0a82b0b local port:3353
TCP Connection Established Successfully ctx:80124d8
SetSockOpt LWIP keepalive: Interval 20, Retry Interval 3, keepalive value 20
Info: Socket[0]: Created connection to IP 192.168.43.15, local port 3353, remote port 3360
Info: Skipped TCP socket connection for socket id[1]. Check the TCP Keepalive configuration.
Info: Skipped TCP socket connection for socket id[2]. Check the TCP Keepalive configuration.
Info: Skipped TCP socket connection for socket id[3]. Check the TCP Keepalive configuration.
whd_tko_toggle: Successfully enabled

Network Stack Suspended, MCU will enter DeepSleep power mode

  10. Verify the TCP Keepalive offload is working as desired.Refer to the How to Measure Power Consumption section for corresponding instructions. The following oscilloscope screen capture shows current measurement with

TCP Keepalive Offload enabled with 20 seconds interval configuration and WLAN DTIM configured as 3 : ../../../_images/afr_tko_offload_low1.png

Wi-Fi Low Power Configuration Considerations

The following are the different flows to configure LPA middleware:

  • ModusToolbox Device Configurator Flow. Generating the initialization code using the ModusToolbox Device Configurator greatly simplifies configuring the PSoC and enabling the LPA features. The ModusToolbox Device Configurator provides the user interface to set up and automatically generate the initialization code (including analog routing) and configuration structures.

  • Manual Configuration Flow. Manually adding settings into configuration files. Manual implementation of the initialization code (including analog routing) and configuration structures is recommended for expert Users only.

Note If you modify the output of the ModusToolbox Device Configurator, you cannot import it back to the tool.

ModusToolbox Device Configurator Flow

To open the ModusToolbox Device Configurator, right-click on the project in the Project Explorer pane in the ModusToolbox IDE, and select ModusToolbox Configurators > Device Configurator.

  1. Select the Wi-Fi Radio device tab (e.g., CYW4343WKUBG).

  2. Enable the Wi-Fi personality and go to the Wi-Fi Parameters pane to configure the LPA Middleware.

  3. Set Host Wake Configuration. Enable and assign the Host Device Interrupt Pin. Refer to the kit datasheet to find out which pin is routed on board PCB.

  4. Set ARP Offload. Enable and configure the LPA with the desired parameters.

  5. Set AWS MQTT Filters. Enable MQTT TLS Filter to enable corresponding filter.

  6. Configure MQTT TLS Filter Configuration parameters with desired values.

  7. Set Packet Filters. Enable Filter Configuration <N> to get access to the filter parameters.

  8. Configure the enabled filter on the previous step with desired parameters.

  9. Perform File->Save to generate initialization code.

../../../_images/WIFI_Personality1.png

After saving the configuration file, the generated code is available under the GeneratedSource folder, located next to the design.modus file in the BSP:

  • C Data File: /GeneratedSource/cycfg_connectivity_wifi.c

  • C Header File: /GeneratedSource/cycfg_connectivity_wifi.h

Host Wake Configuration Notes

By Default, WLAN host wake is configured properly and below device configurator support allows user to modify it to different GPIOs. But if user selects checkbox and doesnot select any pin for , System will Hang and this should be avoided by the user

../../../_images/hostwake_MTConfigure1.png

Manual Configuration Flow

Manual implementation of the initialization code (including analog routing) and configuration structures is recommended for expert Users only.

Limitations

  1. The maximum number of filters is ultimately dictated by free memory on the Wi-Fi chipset. More memory will allow more filters. Different Wi-Fi chips running FW from different branches will likely have slightly different maximum numbers of filters. It is possible to add 20 filters on a CY8CKIT_062S2_43012 kit without any issue.

  2. Network stack suspend/resume functionality which is called in main.cpp function which enables Host MCU to remain in deep sleep for more duration (wake up only for external event) has a 32-Bit LP-Ticker support limitation in MbedOS (Maximum sleep-time possible is 36 hours(1.5 days). This means Host MCU will wake up without interrupt from external event after 36 hrs and then immediately goes back to sleep. This has very less power impact.

IPv6 Packet Filter for MCU Deep Sleep

  • MCU will wake for IPv6 packets intermittently, So add packet filter for IPv6 packets to avoid unnecessary wakeup.

    How to configure packet Filter for IPv6 packets:

    • Navigate to ModusToolbox installation folder and launch the ModusToolbox Device Configurator (<install_dir>/tools_2.2/device-configurator).

    • Select File->Open, navigate to the board’s design.modus file, and open it:

    • Switch to the connectivity device “CYW943012WKWBG” tab (in case the CY8CKIT_062S2_43012 board is used).

    • Enable Power->Wi-Fi.

    • In “Wi-Fi - Parameters” pane enable “Host Wake Configuration” and set “Host Device Interrupt Pin” to “CYBSP_WIFI_HOST_WAKE”.

    • Select Enable Packet Filter Configuration 0

    • Select Filter Type as “Ether Type”

    • Select Action as “Discard”

    • Configure Ethertype as “0x86dd”

    • Save the configuration to generate the necessary code

WLAN Low Power Configuration

WLAN Firmware support two different low power modes like (legacy) 802.11 PS-Poll mode and high throughput powersave mode. Refer to WLAN Powersave API

These can be configured using below Wi-Fi Host Driver APIs:

  1. 802.11 PS-Poll mode 

    // ifp : Pointer to WHD Interface

whd_wifi_enable_powersave(ifp);

  2. High Throughout Powersave mode 

    // This macro specifies the duration in milliseconds for which the STA stays
// awake after receiving frames from AP in PM2 mode. The delay value must be set
// to a multiple of 10 and not equal to zero. Minimum value is 10u. Maximum
// value is 2000u.
// ifp : Pointer to WHD Interface

#define RETURN_TO_SLEEP_MS                (10u)

whd_wifi_enable_powersave_with_throughput(ifp, RETURN_TO_SLEEP_MS);

Configuration Parameters

The following parameters and their mapping to macros are available:

Category

Parameter

Description

Parameter values

Host Wake Configuration

Host Device Interrupt Pin

Selects the host pin which is connected to Wi-Fi device's HOST WAKE signal.

  • Empty (default)

  • Any enabled pin from Pin tab

Host Wake Configuration

Wi-Fi Device Interrupt Pin

Wi-Fi device GPIO_0 is reserved as device wake-up interrupt request pin (WL HOST WAKE).

  • Read Only

ARP Offload

ARP Offload When Host Awake

Respond to ARP Requests when Awake.

  • Disabled (default)

  • Host Auto Reply

  • Peer Auto Reply

  • Host and Peer Auto Reply

ARP Offload

ARP Offload When Host Sleeping

Respond to ARP Requests when Sleeping.

  • Disabled (default)

  • Peer Auto Reply

ARP Offload

Snoop Host IP from traffic when ARP Offload enabled

The host IP address is snooped from an ARP Request. If disabled, the WLAN Device will need to be informed of the Host IP address when the network interface is configured (statically or dynamically via DHCP).

  • Off (default)

  • On

ARP Offload

ARP Offload Cache entries expire after (s)

When the ARP cache table is offloaded from the host to the device, table entries are subject to an aging value called "peer age".

  • 1200 (default)

  • 1-4294967295

MQTT Filter Configuration

Filter ID

Filter ID

  • 0 (for MQTT Filter)

  • 1 (for MQTT TLS Filter)

MQTT Filter Configuration

Action

Filter can either pass up packets that match the filter to the host (Keep) or drop them so the host never gets them (Discard).

  • Keep (default)

  • Discard

MQTT Filter Configuration

When Active

Defines when the filter is active, when the host is awake, when it goes to sleep, or both.

  • Sleep (default)

  • Wake

  • Always

MQTT Filter Configuration

Protocol

Choose communication protocol.

  • TCP (default)

  • UDP

MQTT Filter Configuration

Direction

Inbound - destination port, outbound - source port.

  • Destination Port (default)

  • Source Port

MQTT Filter Configuration

Port Number

Either the single port to be filtered or the beginning of the block of contiguous numbers. When using a block, the starting port must be power of 2.

  • 8883 for TLS

  • 1883 for Non TLS

Packet Filter Configuration <N>

Filter ID

Filter ID

  • 0-21

Packet Filter Configuration <N>

Filter Type

Each port filter can specify either a single port or a block of port numbers.

  • Port Filter on a 16 bit UDP or TCP port number. Refer to Filter Types for details of port numbers.

  • Port Block Filter of port numbers (vs a single port). Envisioned to be used by short lived ephemeral ports on source port.

  • Ether Type accepts a 16 bit ethertype value to filter on. Refer to the Filter Types section (EtherTypes). Common values are 0x800 (IP) and 0x806 (ARP).

  • IP Type accepts an 8 bit IP Protocol number to filter on. Refer to the Filter Types section (IPProtocols).

  • Port Filter

  • Port Block Filter

  • Ether Type

  • IP Type

Packet Filter Configuration <N>

Action

Filter can either pass up packets that match the filter to the host (Keep) or drop them so the host never gets them (Discard).

  • Keep (default)

  • Discard

Packet Filter Configuration <N>

When Active

Defines when the filter is active, when the host is awake, when it goes to sleep, or both.

  • Sleep (default)

  • Wake

  • Always

Packet Filter Configuration <N>

Protocol

Chooses communication protocol. Filter can be constrained to either TCP or UDP. To match either TCP or UDP use two filters, one for each.

  • TCP (default)

  • UDP

Packet Filter Configuration <N>

Direction

Inbound - destination port, outbound - source port. Packets have both a source and destination port. This specifies which one to use. A single port usually uses the destination port.

  • Destination Port (default)

  • Source Port

Packet Filter Configuration <N>

Port Number

Either the single port to be filtered or the beginning of the block of contiguous numbers. When using a block, the starting port must be a power of 2.

  • 1024 for Packet filter (default)

  • 0-65535

Packet Filter Configuration <N>

Range

Indicates the size of the block of port numbers, must be of the form (2^y - 1) and less than Port Number (Filter Type = Port Filter Block). 0 indicates just a single port.

  • 1023 (default)

  • 0-65535

Packet Filter Configuration <N>

Ether Type

Enter EtherType value for desired protocol (Filter Type = Ether Type).

  • 0 (default)

  • 0-65535

Packet Filter Configuration <N>

IP protocol

Enter desired IP protocol number (Filter Type = IP Type).

  • 0 (default)

  • 0-255

TCP Keepalive Offload Configuration <N>

Interval

Enter desired Keepalive Request interval in seconds

  • 20 (default)

  • 0-65535

TCP Keepalive Offload Configuration <N>

Retry Interval

Keepalive retry interval in seconds if Keepalive ack is not received

  • 3 (default)

  • 0-65535

TCP Keepalive Offload Configuration <N>

Retry Count

Retry count in seconds if Keepalive ack is not received

  • 3 (default)

  • 0-65535

TCP Keepalive Offload Configuration <N>

Source port

TCP Keepalive Source port number

  • 0 (default)

  • 0-65535

TCP Keepalive Offload Configuration <N>

Destination port

TCP Keepalive Destination port number

  • 0 (default)

  • 0-65535

TCP Keepalive Offload Configuration <N>

Destination IP address

TCP Keepalive Destination IP address

  • 0.0.0.0 (default)

Part 3. Bluetooth Low Power

The Bluetooth low-power feature enables the host to achieve its lowest power consumption with enabled Bluetooth. The BT Low Power personality helps configure the pin connections between the MCU host and BT device.

With proper configuration, it is possible to achieve low-power consumption by enabling the host MCU and BT device to enter the System Deep Sleep mode. The GPIO connection specified in the BT LPA personality should match the connections present on the target board. In most cases, the target board BSP settings have the GPIO properly set. So, change it only if the hardware is being modified. The goal of the BT LPA is to make the pin setup easier using a portable configuration layer.

Refer to the BT Low Power Configuration Considerations section to configure the WAKE pins. The following diagram shows connections between the Host and WLAN device.

../../../_images/BTWake1.png

Where:

  • UART: (CTS / TXD / RXD / RTS)

  • BT_HOST_WAKE (host wake): MCU input pin which can wake the MCU with interrupt.

  • BT_DEV_WAKE (device wake): an output MCU host pin which is connected as input BT device pin which interrupts the BT device when set in active state.

Another use case for the BT LPA personality is to disable low-power mode, even though all the pins are properly connected and configured. In this case, the BT LPA personality should specify Low Power, but leave the Pins unconnected in the personality. This results in Low Power being disabled.

Quick Start Guide

This Quick Start Guide demonstrates configuring and using the BT Low Power feature in the Mbed OS/ FreeRTOS environment, as well as its impact on the system low power.

MBEDOS

As a base for this guide, the mbed-os-example-ble example is used. This section assumes that you have an Mbed OS development environment configured. Refer to https://os.mbed.com/getting-started/ for instructions about how to do that.

Steps to create the mbed-os-example-ble/BLE_Beacon application and configure the BT low power feature.

  1. Import the mbed-os-example-ble/BLE_Beacon example project and switch to the example directory: 

    git clone https://github.com/ARMmbed/mbed-os-example-ble.git
cd mbed-os-example-ble/BLE_Beacon
mbed deploy

  2. Configure BT Wake up Configurations. This step can be done by using the ModusToolbox Device Configurator or by manually updating the code.

    • BT Low power using the ModusToolbox Device Configurator Refer to ModusToolbox Device Configurator Flow

    • BT Low power Manual configuration Refer to Manual Configuration Flow

  3. update main.cpp in source folder with below change to update Company code 

    uint16_t comp_id      = 0x0131;

  4. Build the project and program the board. The Cypress Board’s BT Powersave is configured and enabled by default. The following command is example for the CY8CKIT_062S2_43012 board, using GCC_ARM as the toolchain: 

    mbed compile -DMBED_TICKLESS --target CY8CKIT_062S2_43012 --toolchain GCC_ARM --flash

    Note If you cannot program the board, make sure the board DAP-Link mode is selected. Refer to the guide of your kit of how to change the mode.

  5. Open Ble scanner app in phone, Filter by mac address displayed on the serial port for this device. Click bond on the app

  6. Check the board operation. Refer to the How to Measure Power Consumption section for corresponding instructions. Following images show current measurement

    i. Current measurement when BT is advertising

    ../../../_images/ble_beacon_not_connected1.jpg

    ii. Current measurements when when BT is connected

    ../../../_images/ble_beacon_connected1.jpg

  7. To disable the BT Low Power feature or to change the BT_HOST_WAKE / BT_DEV_WAKE pins, Cypress recommends using the ModusToolbox Device Configurator. Use the appropriate connectivity device tab (for the CY8CKIT_062S2_43012 board it is CYW943012WKWBG). Click the checkbox next to Power->BT to enable/disable BT low power. Follow the instructions in sections “Host wake up signal” and “Device wake up signal” to modify the BT_HOST_WAKE and BT_DEV_WAKE pins and their polarity, respectively.

    BT Low power Disable Configurator reference

    • Select BT Wake-Up configurations enable checkbox and don’t configure Host Wake up signal & Device Wake up Signal for Low power disable verification

    ../../../_images/ble_Lowpower_disable_configurator1.png

    BT Low power disable current graph

    ../../../_images/ble_Lowpower_disable1.png

  8. BLE Device details can be changed by modifying below variables in main.cpp 

    static const uint8_t uuid[] = { 0xE2, 0x0A, 0x39, 0xF4, 0x73, 0xF5, 0x4B, 0xC4,
                                        0xA1, 0x2F, 0x17, 0xD1, 0xAD, 0x07, 0xA9, 0x61 };
uint16_t major_number = 1122;
uint16_t minor_number = 3344;
uint16_t tx_power     = 0xC8;
uint16_t comp_id      = 0x004C;

FREERTOS

mtb-example-anycloud-ble-wifi-onboarding is used as base for this guide.

Steps to create the mtb-example-anycloud-ble-wifi-onboarding application and configure the BT low power feature.

  1. Clone the example repo and switch to the example directory: 

    git clone https://github.com/cypresssemiconductorco/mtb-example-anycloud-ble-wifi-onboarding.git
cd mtb-example-anycloud-ble-wifi-onboarding

  2. Make sure CY8CKIT-062S2-43012.lib file is present inside deps folder 

    TARGET_CY8CKIT-062S2-43012.lib : https://github.com/cypresssemiconductorco/TARGET_CY8CKIT-062S2-43012/#latest-v2.X

# MTB2.2 and .mtb approach , make sure below mtb files are present
echo https://github.com/cypresssemiconductorco/TARGET_CY8CKIT-062S2-43012#latest-v2.X#\$\$ASSET_REPO\$\$/TARGET_CY8CKIT-062S2-43012/latest-v2.X > deps/TARGET_CY8CKIT-062S2-43012.mtb

  3. Update FreeRTOSConfig.h with below changes to enable MCU Deep Sleep Functionality

    configUSE_TICKLESS_IDLE : This change to support Tickless Deep Sleep mode 

    #include <cycfg_system.h>

#if (CY_CFG_PWR_SYS_IDLE_MODE == CY_CFG_PWR_MODE_SLEEP) || (CY_CFG_PWR_SYS_IDLE_MODE == CY_CFG_PWR_MODE_DEEPSLEEP)
extern void vApplicationSleep( uint32_t xExpectedIdleTime );
#define portSUPPRESS_TICKS_AND_SLEEP( xIdleTime ) vApplicationSleep( xIdleTime )
#define configUSE_TICKLESS_IDLE  2
#endif

#if CY_CFG_PWR_DEEPSLEEP_LATENCY > 0
#define configEXPECTED_IDLE_TIME_BEFORE_SLEEP   CY_CFG_PWR_DEEPSLEEP_LATENCY
#endif

  4. Make sure below changes are present in app_bt_cfg.c which controls BT Host wake and device wake from device configurator 

    .controller_config =
 {
        .bt_power_pin      = CYBSP_BT_POWER,
        .sleep_mode =
    {
        // For ModusToolBox BT LPA configuration
        #if defined(CYCFG_BT_LP_ENABLED)
            .sleep_mode_enabled   = CYCFG_BT_LP_ENABLED,
            .device_wakeup_pin    = CYCFG_BT_DEV_WAKE_GPIO,
            .host_wakeup_pin      = CYCFG_BT_HOST_WAKE_GPIO,
            .device_wake_polarity = CYCFG_BT_DEV_WAKE_POLARITY,
            .host_wake_polarity   = CYCFG_BT_HOST_WAKE_IRQ_EVENT
        #else
         .sleep_mode_enabled   = true,
         .device_wakeup_pin    = CYBSP_BT_DEVICE_WAKE,
         .host_wakeup_pin      = CYBSP_BT_HOST_WAKE,
         .device_wake_polarity = CYBT_WAKE_ACTIVE_LOW,
         .host_wake_polarity   = CYBT_WAKE_ACTIVE_LOW
        #endif
     }
 },

  5. Configure BT Wake up Configurations. This step can be done by using the ModusToolbox Device Configurator or by manually updating the code.

    • BT Low power using the ModusToolbox Device Configurator Refer to ModusToolbox Device Configurator Flow

    • BT Low power Manual configuration Refer to Manual Configuration Flow

  6. Update Makefile with below changes 

    COMPONENTS=WCM SECURE_SOCKETS

# For MTB2.2, below change

CY_GETLIBS_SHARED_PATH=../
CY_GETLIBS_SHARED_NAME=mtb_shared

  7. Build the project and program the board. The Cypress Board’s BT Powersave is configured and enabled by default. The following command is example for the CY8CKIT_062S2_43012 board, using GCC_ARM as the toolchain: 

    make getlibs
make program TARGET=CY8CKIT-062S2-43012 TOOLCHAIN=GCC_ARM

  8. Open Ble scanner app in phone, Filter by mac address displayed on the serial port for this device. Click bond on the app

  9. Check the board operation. Refer to the How to Measure Power Consumption

    section for corresponding instructions. Following image show current measurement with BLE advertising and connected.

    High Current Spike in PSoC6 is due to WiFi

    ../../../_images/ble_beacon_anycloud1.png

  10. To disable the BT Low Power feature or to change the BT_HOST_WAKE / BT_DEV_WAKE pins, Cypress recommends using the ModusToolbox Device Configurator. Use the appropriate connectivity device tab (for the CY8CKIT_062S2_43012 board it is CYW943012WKWBG). Click the checkbox next to Power->BT to enable/disable BT low power. Follow the instructions in sections “Host wake up signal” and “Device wake up signal” to modify the BT_HOST_WAKE and BT_DEV_WAKE pins and their polarity, respectively.

AFR

ble demo application in Amazon FreeRTOS SDK is used as base for this guide.

Steps to compile ble demo application and configure the BT low power feature.

NOTE: This is just to show BT LPA configurations and does not verify BLE services

  1. Clone the example repo and switch to the example directory: 

    git clone https://github.com/cypresssemiconductorco/amazon-freertos.git --recurse-submodules
cd amazon-freertos/demos/ble

  2. Comment out below lines in vendors/cypress/boards/CY8CKIT_062S2_43012/aws_demos/application_code/main.c 

    //tcpip_init(NULL, NULL);    # This is make sure LWIP timers are not running(else there will be 100ms PSoC6 wakeup)
//prvWifiConnect();          # Disable WiFi Connect for this example 
//vDevModeKeyProvisioning(); # Disable Device provision

  3. Update below macros in vendors/cypress/boards/CY8CKIT_062S2_43012/aws_demos/config_files/aws_demo_config.h 

    #define CONFIG_BLE_GATT_SERVER_DEMO_ENABLED                      # Updated from CONFIG_MQTT_DEMO_ENABLED
#define democonfigNETWORK_TYPES     ( AWSIOT_NETWORK_TYPE_BLE )

  4. Update below macro in vendors/cypress/boards/CY8CKIT_062S2_43012/aws_demos/config_files/aws_iot_network_config.h 

    #define configENABLED_NETWORKS      ( AWSIOT_NETWORK_TYPE_BLE )

  5. Comment out below task in demos/ble/aws_ble_gatt_server_demo.c (This is just to avoid PsoC6 waking up every one second) 

    In vGattDemoSvcHook Function,
#if 0
    if( xRet == pdTRUE )
    {
        xRet = xTaskCreate(
            vCounterUpdateTaskFunction,
            "GattDemoCounterTask",
            configMINIMAL_STACK_SIZE * 4,
            NULL,
            tskIDLE_PRIORITY,
            &xCounterUpdateTask );
    }
#endif

  6. Update vendors/cypress/boards/CY8CKIT_062S2_43012/aws_demos/config_files/FreeRTOSConfig.h with below changes to enable MCU Deep Sleep Functionality

    configUSE_TICKLESS_IDLE : This change to support Tickless Deep Sleep mode 

    #include <cycfg_system.h>

#if (CY_CFG_PWR_SYS_IDLE_MODE == CY_CFG_PWR_MODE_SLEEP) || (CY_CFG_PWR_SYS_IDLE_MODE == CY_CFG_PWR_MODE_DEEPSLEEP)
extern void vApplicationSleep( uint32_t xExpectedIdleTime );
#define portSUPPRESS_TICKS_AND_SLEEP( xIdleTime ) vApplicationSleep( xIdleTime )
#define configUSE_TICKLESS_IDLE  2
#endif

#if CY_CFG_PWR_DEEPSLEEP_LATENCY > 0
#define configEXPECTED_IDLE_TIME_BEFORE_SLEEP   CY_CFG_PWR_DEEPSLEEP_LATENCY
#endif

// Add below line 
#define IOT_BLE_ADD_CUSTOM_SERVICES ( 1 )

  7. Configure BT Wake up Configurations. This step can be done by using the ModusToolbox Device Configurator or by manually updating the code.

    • BT Low power using the ModusToolbox Device Configurator Refer to ModusToolbox Device Configurator Flow

    • BT Low power Manual configuration Refer to Manual Configuration Flow

  8. Build the project using CMake / Make.

    The following command is example for the CY8CKIT_062S2_43012 board, using GCC_ARM as the toolchain:

    CMake 

    cd amazon-freertos/demos/ble
cmake -G Ninja -DVENDOR=cypress -DBOARD=CY8CKIT_062S2_43012 -DCOMPILER=arm-gcc -S ../../ -B build -DBLE_SUPPORTED=1 -DAFR_TOOLCHAIN_PATH=../../tools/
cmake --build build --clean-first

    Make 

    cd projects/cypress/CY8CKIT_062S2_43012/mtb/aws_demos/
*** Make sure BLE_SUPPORT=1 in Makefile ***
make build

  9. Open Ble scanner app in phone, Filter by mac address displayed on the serial port for this device. Click bond on the app

  10. Check the board operation. Refer to the How to Measure Power Consumption

    section for corresponding instructions. Following image show current measurement with BLE advertising and connected.

    High Current may be due to Demo app using WiFi and GATT Timer running every one second

    ../../../_images/ble_beacon_afr1.png

  11. To disable the BT Low Power feature or to change the BT_HOST_WAKE / BT_DEV_WAKE pins, Cypress recommends using the ModusToolbox Device Configurator. Use the appropriate connectivity device tab (for the CY8CKIT_062S2_43012 board it is CYW943012WKWBG). Click the checkbox next to Power->BT to enable/disable BT low power. Follow the instructions in sections “Host wake up signal” and “Device wake up signal” to modify the BT_HOST_WAKE and BT_DEV_WAKE pins and their polarity, respectively.

BT Low Power Configuration Considerations

The following are the different flows to configure LPA middleware:

  • ModusToolbox Device Configurator Flow. Generating the initialization code using the ModusToolbox Device Configurator greatly simplifies configuring the PSoC and enabling the LPA features. The ModusToolbox Device Configurator provides the user interface to set up and automatically generate the initialization code (including analog routing) and configuration structures.

  • Manual Configuration Flow. Manually adding settings into configuration files. Manual implementation of the initialization code (including analog routing) and configuration structures is recommended for expert Users only.

Note If you modify the output of the ModusToolbox Device Configurator, you cannot import it back to the tool.

ModusToolbox Device Configurator Flow

Mandatory steps to avoid design.modus file modification inside checkout repo

mbedos

  • Copy folder mbed-os-example-ble/BLE_Beacon/mbed-os/targets/TARGET_Cypress/TARGET_PSOC6/TARGET_CY8CKIT_062S2_43012 to mbed-os-example-ble/BLE_Beacon folder

  • Delete all files in mbed-os-example-ble/BLE_Beacon/TARGET_CY8CKIT_062S2_43012 except COMPONENT_BSP_DESIGN_MODUS folder and its contents

  • Rename mbed-os-example-ble/BLE_Beacon/TARGET_CY8CKIT_062S2_43012/COMPONENT_BSP_DESIGN_MODUS to mbed-os-example-ble/BLE_Beacon/TARGET_CY8CKIT_062S2_43012/CUSTOM_BSP_DESIGN_MODUS

  • Delete design.cyqspi and design.cycapsense file in mbed-os-example-ble/BLE_Beacon/TARGET_CY8CKIT_062S2_43012/CUSTOM_BSP_DESIGN_MODUS

  • Add/update mbed_app.json in mbed-os-example-ble/BLE_Beacon folder with below details (This will tell mbed to ignore the BSP configuration shipped with MbedOS). Make sure to add board specific target.components.remove field under target_overrides 

    {
     "target_overrides": {
          "CY8CKIT_062S2_43012": {
              "target.components_remove": ["BSP_DESIGN_MODUS"]
         }
     }
 }

  • If mbed-os branch used is 5.15 or above, please do the below changes as well

    • update mbed_app.json with below line in “target_overrides”: 

      "target.components_add": ["CUSTOM_DESIGN_MODUS"]

FreeRTOS Ignore this step if application already added this COMPONENT_CUSTOM_DESIGN_MODUS Folder

  1. Copy contents of folder mtb-example-anycloud-ble-wifi-onboarding/libs/TARGET_CY8CKIT-062S2-43012/COMPONENT_BSP_DESIGN_MODUS to mtb-example-anycloud-ble-wifi-onboarding/COMPONENT_CUSTOM_DESIGN_MODUS/TARGET_CY8CKIT_062S2_43012 folder

  2. Delete design.cyqspi and design.cycapsense file in mtb-example-anycloud-ble-wifi-onboarding/TARGET_CY8CKIT_062S2_43012/CUSTOM_BSP_DESIGN_MODUS

  3. update Makefile in mtb-example-anycloud-ble-wifi-onboarding folder with below details (This will tell build to ignore the BSP configuration inside libs folder) 

    COMPONENTS+=CUSTOM_DESIGN_MODUS
DISABLE_COMPONENTS=BSP_DESIGN_MODUS

To open the ModusToolbox Device Configurator, right-click on the project in the Project Explorer pane in the ModusToolbox IDE, and select ModusToolbox Configurators > Device Configurator.

  1. MBEDOS : Open mbed-os-example-ble/BLE_Beacon/TARGET_CY8CKIT_062S2_43012/CUSTOM_BSP_DESIGN_MODUS/design.modus FREERTOS : Open mtb-example-anycloud-ble-wifi-onboarding/COMPONENT_CUSTOM_DESIGN_MODUS/TARGET_CY8CKIT_062S2_43012/design.modus AFR : Open vendors/cypress/boards/CY8CKIT_062S2_43012/aws_demos/application_code/cy_code/design.modus

    • If the design.modus file does not open and pops with a error message No device support library path provided , then point to the devicesupport.xml file in psoc6pdl folder MBEDOS: mbed-os/targets/TARGET_Cypress/TARGET_PSOC6/psoc6pdl/devicesupport.xml FREERTOS: mtb-example-anycloud-ble-wifi-onboarding/libs/psoc6pdl/devicesupport.xml AFR:

      vendors/cypress/MTB/psoc6/psoc6pdl/devicesupport.xml

      This is because the design.modus file will update its path to the PDL directory when it is opened for the first time.

  2. Select Wi-Fi Radio device tab (for example, CYW4343WKUBG).

  3. Enable the BT resource and go to the BT Parameters pane to configure the LPA Middleware.

  4. Enable BT Wake Configuration.

  5. Choose a pin for Host-wake-up signal. Refer to the kit datasheet to find out which pin is routed on board PCB.

  6. Choose a pin for Device-wake-up signal and Device-wake-up trigger interrupt type. Refer to the kit datasheet to find out which pin is routed on board PCB.

  7. Perform File->Save to generate initialization code.

../../../_images/BT_Personality1.png

After saving the configuration file, the generated code is available under the GeneratedSource folder, located next to the design.modus file in the BSP:

  • C Data File: /GeneratedSource/cycfg_connectivity_bt.c

  • C Header File: /GeneratedSource/cycfg_connectivity_bt.h

Manual Configuration Flow

To configure MCU LPA Middleware related parameters not using ModusToolbox Device Configurator, do the following steps:

  1. Find and open the cycfg_connectivity_bt.h file under …/COMPONENT_BSP_DESIGN_MODUS/GeneratedSource/folder with a text editor.

  2. To configure Host-Wake-Up Signal parameter add/modify the following macros: 

    #define CYCFG_BT_HOST_WAKE_GPIO CYBSP_CSD_TX_HAL_PORT_PIN
#define CYCFG_BT_HOST_WAKE_IRQ_EVENT CYCFG_BT_WAKE_EVENT_ACTIVE_LOW

  3. To configure Device-Wake-Up Signal parameter add/modify the following macros: 

    #define CYCFG_BT_DEV_WAKE_GPIO CYBSP_WIFI_SDIO_DAT0_HAL_PORT_PIN
#define CYCFG_BT_DEV_WAKE_POLARITY CYCFG_BT_WAKE_EVENT_ACTIVE_LOW

  4. Save changes.

Note Using the ModusToolbox Device Configurator overwrites changes you made in the cycfg_connectivity_bt.h file.

Note The board Pin connections must match the manual settings. If the BSP pins are being changed, then it will require some board rework to match the hardware connections to the manually changed connections.

Configuration Parameters

The following parameters and their mapping to macros are available:

Category

Parameter

Description

Parameter values

Host Wake Configuration

Host-Wake-Up Signal

Select the host pin which is connected to BT device's BT_HOST_WAKE signal.

  • Empty (default)

  • Any enabled pin from Pin tab

Host Wake Configuration

Host-Wake-IRQ-Event

Select the Trigger for Host wake IRQ event.

  • Falling Edge (Active Low) (default)

  • Rising Edge (Active High)

BT Device Wake Configuration

Device-Wake-Up Signal

Select the host pin which is connected to BT device's BT_DEV_WAKE signal.

  • Empty (default)

  • Any enabled pin from Pin tab

BT Device Wake Configuration

Device-Wake-Up Polarity

Select the Polarity condition for BT_DEV_WAKE signal.

  • Active Low (default)

  • Active High

How to Measure Power Consumption

This section describes how to measure power consumption for the CY8CKIT-062S2-43012 kit used in the Quick Start Guide sections. Refer to the guide of your kit of how to measure power consumption.

To prepare your equipment and measure the current consumption do the following steps:

  • DC Power analyzer used:

    • Disconnect the KitProg USB cable to power off the board.

    • Optional: To prevent the current leakages and observe the real current consumption remove the following components:

      • For base board versions > Rev02 : Remove the jumper J25.

      • For base board versions <= Rev02 : Remove the potentiometer R1.

      Note If you do not remove the component you still be able to observe approximate current consumption but due to the current leakage it is slightly higher.

    • Connect the negative probe to the GND test point.

    • Remove the J15 jumper and connect the positive probe to the J15 P6.VDD pin for PSoC6 Measurement.

    • Configure the DC Power Analyzer to 3.3 V DC output.

    • Remove the J8 jumper and connect the positive probe to the J8 VBAT 1 pin for WLAN 43012 Measurement.

    • Configure the DC Power Analyzer to 3.6 V DC output.

    • Power on the board by connecting the KitProg USB cable again.

    • Enable DC output on the DC Power Analyzer.

  • Ammeter used:

    • Disconnect the KitProg USB cable to power off the board.

    • Optional: To prevent the current leakages and observe the real current consumption remove the following components:

      • For base board versions > Rev02 : Remove the jumper J25.

      • For base board versions <= Rev02 : Remove the potentiometer R1.

      Note If you do not remove the component you still be able to observe approximate current consumption but due to the current leakage it is slightly higher.

    • Remove the J15 jumper and connect the negative probe to the J15 P6.VDD pin for PSoC6 Measurement.

    • Connect the positive probe to the J15 VTARG pin.

    • Remove the J8 jumper and connect the negative probe to the J8 VCC VBAT 1 pin for WLAN 43012 Measurement.

    • Connect the positive probe to the J8 VCC VBAT pin (Pin 2).

    • Power on the board by connecting the KitProg USB cable again.

    • Turn on the Ammeter.

Performance Data

Note

The Performance Data report is measured on CY8CKIT_062S2_43012 board.

Lower MCU Current for AFR and FreeRTOS cases is due to the fact that app disables the Phase-Locked Loop (PLL), disables the HF clock for unused peripherals like audio/USB, and configures the Buck regulator instead of the Low Dropout (LDO) regulator to power the PSoC 6 MCU device.

Quick Start Guide Example

SDK

Based On

PSoC6 + CYW943012 Average current
Without LPA

PSoC6 + CYW943012 Average current
With LPA

Configurations

Notes

MCU Low Power QSG

MBEDOS

mbed-os-blinky-led

17.9mA

25.9uA

Without LPA: MCU Idle power mode set to Active
With LPA: MCU Idle power mode set to Deep Sleep

AnyCloud SDK(FreeRTOS)

mtb-example-psoc6-empty-app

17.2mA

24uA

AFR

afr-example-wlan-lowpower

1.6mA

29uA

Wi-Fi ARP offload QSG

MBEDOS

mbed-os-example-wifi

4.7mA

360uA

Without LPA: ARP offload not enabled
With LPA: ARP offloads enabled
MCU Idle power mode set to Deep Sleep for both use cases.
ARP pings every 3 seconds for total 30 seconds duration

  • beacon interval : 100ms

  • DTIM : 3

AnyCloud SDK(FreeRTOS)

mtb-example-anycloud-wlan-lowpower

2.85mA

600uA

AFR

afr-example-wlan-offloads

770uA

290uA

Wi-Fi Packet filter QSG

MBEDOS

mbed-os-example-wifi

6.2mA

400uA

Without LPA: No Packet filters configured
With LPA: ICMP ping packets filtered
MCU Idle power mode set to Deep Sleep for both use cases.
Ping packets every 3 seconds for duration of 30 secs

  • beacon interval : 100ms

  • DTIM : 3

AnyCloud SDK(FreeRTOS)

mtb-example-anycloud-wlan-lowpower

2.5mA

350uA

AFR

afr-example-wlan-offloads

1.4mA

235uA

Wi-Fi TCP Keepalive Offload QSG

MBEDOS

mbed-os-example-wifi

19.5mA

550uA

Without LPA: TCP Keepalive offload not enabled
With LPA: TCP Keepalive offload enabled
MCU Idle power mode set to Deep Sleep for both use cases.

  • TCP Keepalive interval : 20 seconds

  • beacon interval : 100ms

  • DTIM : 3

  • PM2_SLEEP_RET : 10ms

AnyCloud SDK(FreeRTOS)

mtb-example-anycloud-offload-tcp-keepalive

1.6mA

600uA

AFR

afr-example-wlan-offloads

1.6mA

236uA

BT Low Power QSG
(BT Advertising)

MBEDOS

mbed-os-example-ble/BLE_Beacon

12.5mA

80.5uA

Without LPA: BT low power not enabled
With LPA: BT low power enabled
MCU Idle power mode set to Deep Sleep for both use cases
BLE Advertising interval : 1000ms

AnyCloud SDK(FreeRTOS)

mtb-example-anycloud-ble-wifi-onboarding

3.4mA

350uA

AFR

demos/ble

4.5mA

80uA

BT Low Power QSG
(BT Connected)

MBEDOS

mbed-os-example-ble/BLE_Beacon

18.5mA

550uA

Without LPA: BT low power not enabled
With LPA: BT low power enabled
MCU Idle power mode set to Deep Sleep for both use cases
BLE Advertising interval : 1000ms

AnyCloud SDK(FreeRTOS)

mtb-example-anycloud-ble-wifi-onboarding

3.5mA

760uA

AFR

demos/ble

4.5mA

3.5mA

High Current is due to

  • BLE Demo app using Wi-Fi

  • Wakes up every one second due to GATT Timer

Wi-Fi Host Wake Configuration

CY8CKIT_062_WIFI_BT

  • On the PSoC6 MCU Pins tab of the Device Configurator tool , Enable the Host wake pin P2[7] and name it CYBSP_WIFI_HOST_WAKE.

  • In the Parameters pane, change the following.

    • Drive Mode: Analog High-Z. Input buffer off.

    • Initial Drive State: High(1).

    • Interrupt Trigger Type: Rising Edge.

  • Go to WiFi tab, set Host Device Interrupt Pin to CYBSP_WIFI_HOST_WAKE.

../../../_images/hostwake_config_4343_062_kit1.png

CY8CKIT_062S2_43012

  • On the PSoC6 MCU Pins tab of the Device Configurator tool , Enable the Host wake pin P4[1] and name it CYBSP_WIFI_HOST_WAKE.

  • In the Parameters pane, change the following.

    • Drive Mode: Analog High-Z. Input buffer off.

    • Initial Drive State: High(1).

    • Interrupt Trigger Type: Rising Edge.

  • Go to WiFi tab, set Host Device Interrupt Pin to CYBSP_WIFI_HOST_WAKE.

../../../_images/hostwake_config_43012_062S2_kit1.png

CY8CPROTO_062_4343W

  • On the PSoC6 MCU Pins tab of the Device Configurator tool , Enable the Host wake pin P0[4] and name it CYBSP_WIFI_HOST_WAKE.

  • In the Parameters pane, change the following.

    • Drive Mode: Analog High-Z. Input buffer off.

    • Initial Drive State: High(1).

    • Interrupt Trigger Type: Rising Edge.

  • Go to WiFi tab, set Host Device Interrupt Pin to CYBSP_WIFI_HOST_WAKE.

../../../_images/hostwake_config_4343W_062_kit1.png

BT Wake Configuration

CY8CKIT_062_WIFI_BT

  • On the PSoC6 MCU Pins tab of the Device Configurator tool

    • Enable the BT Host wake pin P3[5] and name it CYBSP_BT_HOST_WAKE.

      • In the Parameters pane, change the following.

        • Drive Mode: Analog High-Z. Input buffer off

        • Initial Drive State: Low(0).

    • Enable the BT Device wake pin P4[0] and name it CYBSP_BT_DEVICE_WAKE.

      • In the Parameters pane, change the following.

        • Drive Mode: Strong Drive. Input buffer off.

        • Initial Drive State: Low(0).

  • Go to BT tab in CYW4343WKUBG and change the following.

    • Enable BT Wake up Configurations checkbox

    • Host Wake-Up Signal : CYBSP_BT_HOST_WAKE

    • Host Wake-Up IRQ event: Failing Edge

    • Device Wake-Up Signal : CYBSP_BT_DEVICE_WAKE

    • Device Wake-up Polarity : Active low

../../../_images/btwake_config_4343_062_kit1.png

CY8CKIT_062S2_43012

  • On the PSoC6 MCU Pins tab of the Device Configurator tool

    • Enable the BT Device wake pin P3[5] and name it CYBSP_BT_DEVICE_WAKE.

      • In the Parameters pane, change the following.

        • Drive Mode: Strong Drive. Input buffer off.

        • Initial Drive State: Low(0).

    • Enable the BT Host wake pin P4[0] and name it CYBSP_BT_HOST_WAKE.

      • In the Parameters pane, change the following.

        • Drive Mode: Analog High-Z. Input buffer off.

        • Initial Drive State: Low(0).

  • Go to BT tab in CYW43012C0WKWBG and change the following.

    • Enable BT Wake up Configurations checkbox

    • Host Wake-Up Signal : CYBSP_BT_HOST_WAKE

    • Host Wake-Up IRQ event: Failing Edge

    • Device Wake-Up Signal : CYBSP_BT_DEVICE_WAKE

    • Device Wake-up Polarity : Active low

../../../_images/btwake_config_43012_062S2_kit1.png

CY8CPROTO_062_4343W

  • On the PSoC6 MCU Pins tab of the Device Configurator tool

    • Enable the BT Device wake pin P3[5] and name it CYBSP_BT_DEVICE_WAKE.

      • In the Parameters pane, change the following.

        • Drive Mode: Strong Drive. Input buffer off.

        • Initial Drive State: Low(0).

    • Enable the BT Host wake pin P4[0] and name it CYBSP_BT_HOST_WAKE.

      • In the Parameters pane, change the following.

        • Drive Mode: Analog High-Z. Input buffer off.

        • Initial Drive State: Low(0).

  • Go to BT tab in CYW4343WKUBG and change the following.

    • Enable BT Wake up Configurations checkbox

    • Host Wake-Up Signal : CYBSP_BT_HOST_WAKE

    • Host Wake-Up IRQ event: Failing Edge

    • Device Wake-Up Signal : CYBSP_BT_DEVICE_WAKE

    • Device Wake-up Polarity : Active low

../../../_images/btwake_config_4343W_062_kit1.png

Supported Software and Tools

This version of the LPA Middleware was validated for compatibility with the following Software and Tools:

Software and Tools

Version

ModusToolbox Software Environment

2.2

- ModusToolbox Device Configurator

2.2

- Power Personality in Device Configurator

1.2

- Wi-Fi Personality in Device Configurator

1.0

- BT Personality in Device Configurator

1.0

GCC compiler for MBED-OS

9.2.0

GCC compiler for Anycloud FreeRTOS

9.3.0

GCC compiler for Amazon FreeRTOS

7.2.1

IAR Compiler

8.32

ARM Compiler 6

6.14

MBED OS

6.8.0

AnyCloud FreeRTOS

SDK v1.4

Amazon FreeRTOS

V202007.00

MISRA-C Compliance

If you need a MISRA compliance report for this library, please create a ticket at www.cypress.com/support

Errata

This section lists the known problems with the LPA middleware.

Changelog

Version

Changes

Reason for Change

3.1.0

Minor Fixes and documentation update

MBED OS 6.8.0 , Anycloud SDKv1.4 , Amazon FreeRTOS v202007.00

3.0.0

LPA Middleware for all SDK(s)

MBED OS 6.2.0 , Anycloud SDKv1.2 , Amazon FreeRTOS v202007.00

2.1.0(ER)

Add LPA Support to Amazon FreeRTOS release

Added AFR SDK support to Wi-Fi Only LPA

Support WLAN Low power configurations in LPA for all OS

Feature enhancement

2.0.0

Add LPA Support to FreeRTOS - AnyCloud SDK release

Added AnyCloud SDK support to LPA

Add TCP Keepalive offload support

Feature enhancement

1.0.0

The initial version

More Information

For more information, Cypress highly recommends starting with these documents.

Note Links to other software component’s documentation (middleware and PDL) point to Cypress GitHub and the latest available version of the software. To get documentation for a specific version, download it from GitHub and unzip the component archive. The documentation is available in the docs folder.

LPA API

LPA API’s are documented below

Utilities

LPA utility API’s used by LPA middle-ware