Summary

This is the first article in a series about my journey implementing PSoC 6 SDK libraries for the Maxxim One Wire Bus and the DS18B20 temperature sensor.

As you can see there will be many parts to this story:

Story

I recently got a twitter message from a gentleman named “Neeraj Dhekale”.  He asked about a library for a one wire sensor for PSoC, actually to be specific he asked about a component for a PSoC 4.

Then I asked him what sensor and responded that he wanted to use the Maxxim DS18B20 temperature sensor.

This sensor is a one wire temperature sensor, here is a bit of snapshot from the data sheet.

After reading the data sheet I decided that I really didn’t want to implement a complete library for this sensor.  So, I started looking around for a driver library.  After googling around a little bit I found a library on GitHub (https://github.com/DavidAntliff/esp32-ds18b20) which looked promising, even though it is ESP32 specific.

But, after looking at this GitHub library a bit, I decide to start from there.

Before I get started two comments.

1. He asked for PSoC 4 … but I am going to do PSoC 6 (because I can use Modus Toolbox).  There is no reason why this wouldn’t work on PSoC 4 – but it would take a bit of work
2. I can’t think of a good reason to use 1-wire, it sure seems like I2C would be simpler

Build a Base Project

I start this whole effort by creating a new project for the CY8CKIT-062S2-43012 (because that happens to be the kit on my desk at the moment)

I will use the IoT Expert FreeRTOS Template project

For debugging this whole thing I will use a command line shell.  To get this into the project I add the ntshell library. Run “make modlibs” to start the library manager.

In the library manager pick the “ntshell” library

To develop this project I want to use Visual Studio code.  So, I run “make vscode” (to create the configuration files) and start vscode by running “code .”

When VSCODE starts up it looks like this:

In order to use the ntshell library you need to shuffle the files around a little bit.  Move the ntshell.h/.c into the main project by doing a drag/drop in the explorer window.

It will ask you really want to move the files

Once it is done, the ntshell functions which you need to customize will be part of the project.

To use the ntshell, you need to add the task to main.c

#include "cy_pdl.h"
#include "cyhal.h"
#include "cybsp.h"
#include "cy_retarget_io.h"
#include <stdio.h>
#include "FreeRTOS.h"
#include "task.h"

#include "ntshell.h"
#include "ntlibc.h"
#include "psoc6_ntshell_port.h"

// Global variable with a handle to the shell
ntshell_t ntshell;

void ntShellTask()
{

  printf("Started ntshell\n");
  setvbuf(stdin, NULL, _IONBF, 0);
  ntshell_init(
	       &ntshell,
	       ntshell_read,
	       ntshell_write,
	       ntshell_callback,
	       (void *)&ntshell);
  ntshell_set_prompt(&ntshell, "DS18B20> ");
  vtsend_erase_display(&ntshell.vtsend);
  ntshell_execute(&ntshell);
}

And start the task

    xTaskCreate(ntShellTask, "nt shell task", configMINIMAL_STACK_SIZE*2,0 /* args */ ,0 /* priority */, 0);

Build and compile

And you should have a working project.

Run “make program” to get the board going

arh (master *) OWB_DS18B20 $ make program
Tools Directory: /Applications/ModusToolbox/tools_2.1

Prebuild operations complete
Commencing build operations...

Tools Directory: /Applications/ModusToolbox/tools_2.1

Initializing build: mtb-example-psoc6-empty-app Debug CY8CKIT-062S2-43012 GCC_ARM

Auto-discovery in progress...
-> Found 202 .c file(s)
-> Found 50 .S file(s)
-> Found 27 .s file(s)
-> Found 0 .cpp file(s)
-> Found 0 .o file(s)
-> Found 4 .a file(s)
-> Found 450 .h file(s)
-> Found 0 .hpp file(s)
-> Found 0 resource file(s)
Applying filters...
Auto-discovery complete

Constructing build rules...
Build rules construction complete

==============================================================================
= Building application =
==============================================================================
Building 181 file(s)
==============================================================================
= Build complete =
==============================================================================

Calculating memory consumption: CY8C624ABZI-D44 GCC_ARM -Og

   ---------------------------------------------------- 
  | Section Name         |  Address      |  Size       | 
   ---------------------------------------------------- 
  | .cy_m0p_image        |  0x10000000   |  5972       | 
  | .text                |  0x10002000   |  49532      | 
  | .ARM.exidx           |  0x1000e17c   |  8          | 
  | .copy.table          |  0x1000e184   |  24         | 
  | .zero.table          |  0x1000e19c   |  8          | 
  | .data                |  0x080022e0   |  1688       | 
  | .cy_sharedmem        |  0x08002978   |  8          | 
  | .noinit              |  0x08002980   |  148        | 
  | .bss                 |  0x08002a14   |  985176     | 
  | .heap                |  0x080f3270   |  46480      | 
   ---------------------------------------------------- 

  Total Internal Flash (Available)          2097152    
  Total Internal Flash (Utilized)           59468      

  Total Internal SRAM (Available)           1046528    
  Total Internal SRAM (Utilized)            1033500    


Programming target device... 
Open On-Chip Debugger 0.10.0+dev-3.0.0.665 (2020-03-20-17:12)
Licensed under GNU GPL v2
For bug reports, read
        http://openocd.org/doc/doxygen/bugs.html
Info : auto-selecting first available session transport "swd". To override use 'transport select <transport>'.
adapter speed: 2000 kHz
** Auto-acquire enabled, use "set ENABLE_ACQUIRE 0" to disable
cortex_m reset_config sysresetreq
cortex_m reset_config sysresetreq
Info : Using CMSIS loader 'CY8C6xxA_SMIF' for bank 'psoc6_smif0_cm0' (footprint 6485 bytes)
Warn : SFlash programming allowed for regions: USER, TOC, KEY
Info : CMSIS-DAP: SWD  Supported
Info : CMSIS-DAP: FW Version = 2.0.0
Info : CMSIS-DAP: Interface Initialised (SWD)
Info : SWCLK/TCK = 1 SWDIO/TMS = 1 TDI = 0 TDO = 0 nTRST = 0 nRESET = 1
Info : CMSIS-DAP: Interface ready
Info : KitProg3: FW version: 1.11.159
Info : KitProg3: Pipelined transfers disabled, please update the firmware
Warn : *******************************************************************************************
Warn : * KitProg firmware is out of date, please update to the latest version using fw-loader at *
Warn : * ModusToolbox/tools/fw-loader                                                            *
Warn : *******************************************************************************************
Info : VTarget = 3.263 V
Info : kitprog3: acquiring PSoC device...
Info : clock speed 2000 kHz
Info : SWD DPIDR 0x6ba02477
Info : psoc6.cpu.cm0: hardware has 4 breakpoints, 2 watchpoints
Info : psoc6.cpu.cm0: external reset detected
***************************************
** Silicon: 0xE402, Family: 0x102, Rev.: 0x11 (A0)
** Detected Device: CY8C624ABZI-S2D44A0
** Detected Main Flash size, kb: 2048
** Flash Boot version: 3.1.0.45
** Chip Protection: NORMAL
***************************************
Info : psoc6.cpu.cm4: hardware has 6 breakpoints, 4 watchpoints
Info : psoc6.cpu.cm4: external reset detected
Info : Listening on port 3333 for gdb connections
Info : Listening on port 3334 for gdb connections
Info : kitprog3: acquiring PSoC device...
target halted due to debug-request, current mode: Thread 
xPSR: 0x41000000 pc: 0x00000190 msp: 0x080ff800
** Device acquired successfully
** psoc6.cpu.cm4: Ran after reset and before halt...
target halted due to debug-request, current mode: Thread 
xPSR: 0x01000000 pc: 0x0000012a msp: 0x080ff800
** Programming Started **
auto erase enabled
Info : Flash write discontinued at 0x10001754, next section at 0x10002000
Info : Padding image section 0 at 0x10001754 with 172 bytes (bank write end alignment)
[100%] [################################] [ Erasing     ]
[100%] [################################] [ Programming ]
Info : Padding image section 1 at 0x1000e844 with 444 bytes (bank write end alignment)
[100%] [################################] [ Erasing     ]
[100%] [################################] [ Programming ]
wrote 57856 bytes from file /Users/arh/proj/xxx/OWB_DS18B20/build/CY8CKIT-062S2-43012/Debug/mtb-example-psoc6-empty-app.hex in 2.294771s (24.621 KiB/s)
** Programming Finished **
** Verify Started **
verified 57240 bytes in 0.155447s (359.598 KiB/s)
** Verified OK **
** Resetting Target **
shutdown command invoked

arh (master *) OWB_DS18B20 $

And you should have a working project (with a blinking led and a command line)

Add the DS18B20 Library

Now that I have a working project the next step is to clone the DS18B20 library into my project.  This is done using

• git clone https://github.com/DavidAntliff/esp32-ds18b20

The next step is to establish how bad things are with the new library.  So run the compiler.

When I look at the ds18b20.c file I can see that there are some obvious problems

#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/gpio.h"
#include "esp_system.h"
#include "esp_log.h"

#include "ds18b20.h"
#include "owb.h"

Fix those:

#include "FreeRTOS.h"
#include "task.h"
//#include "driver/gpio.h"
//#include "esp_system.h"
//#include "esp_log.h"

#include "ds18b20.h"
//#include "owb.h"

Run the compiler again.  Now I am missing owb.h which is the public header file for the one wire bus.

In file included from esp32-ds18b20/ds18b20.c:47:0:
./esp32-ds18b20/include/ds18b20.h:37:10: fatal error: owb.h: No such file or directory
 #include "owb.h"

I now make a directory to hold the new owb files called “p6sdk-onewire”.  Then I add a file “owb.h” (as a blank file)

When I run the compiler again, there are now two classes or error … owb and esp32 logging function. Here is an example of the ESP_ problems.

esp32-ds18b20/ds18b20.c:249:17: warning: implicit declaration of function 'ESP_LOG_BUFFER_HEX_LEVEL' [-Wimplicit-function-declaration]
                 ESP_LOG_BUFFER_HEX_LEVEL(TAG, scratchpad, count, ESP_LOG_DEBUG);
                 ^~~~~~~~~~~~~~~~~~~~~~~~
esp32-ds18b20/ds18b20.c:249:66: error: 'ESP_LOG_DEBUG' undeclared (first use in this function)
                 ESP_LOG_BUFFER_HEX_LEVEL(TAG, scratchpad, count, ESP_LOG_DEBUG);

And here is an example of the owb problems.

esp32-ds18b20/ds18b20.c: In function 'ds18b20_wait_for_conversion':
esp32-ds18b20/ds18b20.c:504:30: error: request for member 'use_parasitic_power' in something not a structure or union
         if (ds18b20_info->bus->use_parasitic_power)
                              ^~
esp32-ds18b20/ds18b20.c: At top level:
esp32-ds18b20/ds18b20.c:568:54: error: unknown type name 'OneWireBus'
 DS18B20_ERROR ds18b20_check_for_parasite_power(const OneWireBus * bus, bool * present)
                                                      ^~~~~~~~~~
esp32-ds18b20/ds18b20.c: In function 'ds18b20_check_for_parasite_power':
esp32-ds18b20/ds18b20.c:577:44: error: 'OWB_ROM_SKIP' undeclared (first use in this function); did you mean 'CY_ROM_SIZE'?
             if ((err = owb_write_byte(bus, OWB_ROM_SKIP)) == DS18B20_OK)
                                            ^~~~~~~~~~~~
                                            CY_ROM_SIZE
make[1]: *** [/Users/arh/proj/xxx/OWB_DS18B20/build/CY8CKIT-062S2-4301

To make this thing go, I edit ds18b20.c file and add logging templates (just stub functions that don’t do anything)

void ESP_LOGD(const char * code, char *val,...)
{

}

void ESP_LOGE(const char * code, ...)
{

}

void ESP_LOGW(const char *code,...)
{

}

#define ESP_LOG_DEBUG 0
void ESP_LOG_BUFFER_HEX_LEVEL(const char *code,...)
{

}

uint64_t esp_timer_get_time()
{
    return 0;
}

Create owb.h

If I was smart, I would have started with David Antliff “owb” library.  But I don’t.  What I do is search through “ds18b20.c” and find every function call to owb_ and then copy those function calls into owb.h (my new file).  Then I fix the function calls to have correct prototypes based on what I see in the ds18b20 library.  Here is what my owb.h file looks like after that process.

#ifndef OWB_H
#define OWB_H

#ifdef __cplusplus
extern "C" {
#endif

#define OWB_ROM_MATCH 0
#define OWB_ROM_SKIP 0

#include <stdint.h>
#include "cyhal.h"
#include "FreeRTOS.h"
#include "semphr.h"

typedef struct  
{
    cyhal_gpio_t  pin;
    bool use_parasitic_power;
    SemaphoreHandle_t signalSemaphore;
    cyhal_timer_t bitTimer;
    bool detect;
    SemaphoreHandle_t owb_num_active;
} OneWireBus;        

typedef struct {
    uint8_t romAddr[8];

} OneWireBus_ROMCode;

typedef enum {
    OWB_STATUS_OK,
    OWB_STATUS_ERROR,
} owb_ret_t ;

owb_ret_t owb_init(OneWireBus *bus);
    
owb_ret_t owb_reset(OneWireBus *bus, bool *result);

owb_ret_t owb_write_bit( OneWireBus *bus, uint8_t val);
owb_ret_t owb_write_byte( OneWireBus *bus, uint8_t val);
owb_ret_t owb_write_bytes( OneWireBus *bus, uint8_t *buffer, uint32_t length);

owb_ret_t owb_write_rom_code(OneWireBus *bus, OneWireBus_ROMCode romcode);

owb_ret_t owb_read_bit( OneWireBus *bus, uint8_t *bit);
owb_ret_t owb_read_byte( OneWireBus *bus, uint8_t *byte);
owb_ret_t owb_read_bytes( OneWireBus *bus, uint8_t *buffer, uint32_t length);

owb_ret_t owb_crc8_bytes(uint32_t val, uint8_t *buffer, uint32_t length);

void   owb_set_strong_pullup( OneWireBus *bus, bool val);

#endif

#ifdef __cplusplus
}
#endif

When I run the compiler again things look way better (just some complaining about const datatypes) and a complaint about the include path.  The include path thing is visual studio code not knowing that I added a new directory called p6sdk-onewire.

To fix the include path I run “make vscode” which tells VSCODE about the new directory.

That is a good place to split this article.  In the next article I will add functions to read and write the bus.

Summary

This article walks you through a PSoC 6 SDK example of measuring a pulse width using the TCPWM block’s counter function.

The Story

Recently I have been working with a Cypress guy and frequent collaborator Hassane.  He is working on a project that includes some kind of sonic distance sensor (I am actually not sure which one).  In order to “read” the sensor you need to be able to measure the width of a pulse which is easy enough to do using the TCPWM.  I originally wanted to use the Cypress HAL to setup the PSoC 6 to do this function, but it is not yet enabled.  So, I need to use PDL and the PSoC 6 Configurator.

Configure The TCPWM

Start with a new PSoC 6 project.  In my case I am using the CY8CKIT-062-WiFi-BT development kit because I had one where I had already soldered a wire onto the user switch.  My plan is to create a “pulse” with the user switch, starting from the press, ending with the user letting go.  This will be an active low pulse.  I will configure the TCPWM to have start, reload setup as Falling edges.  In other words the counter will reset and start counting when the button is pressed.  Then I will setup Stop and Reload on Rising edges, in other words the timer will STOP and give an interrupt on the rising edge.  All of these pins are connected to P9[0] on the PSoC.

You might ask yourself, why P9[0]?  That development kit has a switch connected to P0[4] seems like you should have connected the TCPWM to that pin.  That was done because the TCPWM is only attached to a limited set of signals.  Here is a screenshot from the configurator.

I want this setup to be interrupt based, specifically I want an interrupt when the Capture signal is active.  It is also interesting when the counter rolls over (overflow).  So I setup the interrupt source to be “Overflow & Underflow or Compare & Capture”.

The last thing you need is a clock.   you now need a clock.  To do this clock on the Clock Signal.  For this example I decided to use a 16-bit clock.

But what frequency is the input clock?  To set this go to the “Peripheral-Clocks”  The click on the divider you choose from above.  Then pick a divide value.  I choose 10000 which will give me 100MHz/10K=10KHz.

But where did the 100MHz come from?  Click on the “System” and look at the clock diagram.  All of the “Peripheral Clocks” use the signal “CLK_PERI” as their source.  This is attached to CLK_HF0 (which is 100Mhz) in this case.

The Program

Once is everything is configured you need to write a bit of code.

9-14: First I create an ISR which will set a flag and clear the interrupt source in the TCPWM

Then I write a main function

20: Turn on the printf functionality using the cy_retarget_io library

25: Initialize the counter using the structure created by the configurator.

26: Then I enable the counter to run.  Be careful with this function because counter numbers are NOT the same thing as counter masks.  Counter 3 is counter mask 1<<3=8

28-30: Turn on the interrupts and register my ISR called counterDone

34: In the loop I wait around until the flag gets set by the ISR

36: Read the value from the counter and convert it to seconds

37: Print the value

38: Reset the flag

And do it all over again

#include "cy_pdl.h"
#include "cyhal.h"
#include "cybsp.h"
#include "cy_retarget_io.h"
#include <stdio.h>

volatile int flag=0;

void counterDone()
{
    uint32 intCause = Cy_TCPWM_GetInterruptStatusMasked(MYC_HW,MYC_NUM);
    flag = 1;
    Cy_TCPWM_ClearInterrupt(MYC_HW,MYC_NUM,intCause);
}

int main(void)
{
    cybsp_init() ;
    
    cy_retarget_io_init(CYBSP_DEBUG_UART_TX, CYBSP_DEBUG_UART_RX, CY_RETARGET_IO_BAUDRATE);
    __enable_irq();

    printf("Started\n");

    Cy_TCPWM_Counter_Init(MYC_HW,MYC_NUM,&MYC_config);
    Cy_TCPWM_Enable_Multiple(MYC_HW,MYC_MASK);

    cy_stc_sysint_t mycounter= {.intrSrc = MYC_IRQ, .intrPriority=7};
    Cy_SysInt_Init(&mycounter,counterDone);
    NVIC_EnableIRQ(MYC_IRQ);

    for(;;)
    {
        if(flag == 1)
        {
            float val = (float)Cy_TCPWM_Counter_GetCounter(MYC_HW,MYC_NUM) / 10000.0;
            printf("%.2fs\n",val);
            flag = 0;
        }
    }
}

Test

For an earlier article I had to solder a wire onto the switch.  This let me attach it to an oscilliscope.  It turns out that was an easy way to attach the switch to P9[0]

When I run the project I get a bunch of different pulse.  Looks good.

Summary

This article walks you through the steps to add DeepSleep Tickless mode to your PSoC 6 FreeRTOS project.  It includes an example project that demonstrates the use of the Cypress HAL and DeepSleep to acheive power savings.

This article is part of the "PSoC 6 Low Power Techniques" Series which covers a range of tools you have to lower the power of your system.  The following articles are (or will be) available:

The following resources are available

The Story

I recently taught the Modus Toolbox-101 class to a group of Cypress Field Applications Engineers.  In that class we have a chapter called “PSoC 6 Low Power” which shows you how to use the Low Power Assistant to improve your system power.  This chapter was built around the ARM MBED OS Software Development Kit inside of Modus Toolbox.  Every time I show people the low power assistant I am blown away by how easy it is to do.  Cypress is currently working on a major upgrade to our FreeRTOS implementation, but I thought that in advance of that I would take some of the steps myself.  Specifically, using FreeRTOS Tickless Mode.

What is Tickless mode?  In order to understand this you should understand that FreeRTOS runs a scheduler – and its not just FreeRTOS but every RTOS.  The scheduler is responsible for pausing, starting, stopping etc. the tasks based on your configuration (i.e. priorities).  The scheduler task needs to run on a regular basis, like every 1ms, or the system will fall apart.  This is done for you automatically by hooking up a system tick interrupt which interrupts whatever user task is happening and running the scheduler.

The next thing that you need to know is that RTOSs have a task called “idle” which runs when all of the real tasks are blocked either by a delay, semaphore, queue etc.  All this idle task does is burn CPU cycles until the next SysTick interrupt.  The idle task is implemented with something like while(1);  This isn’t really very constructive because the CPU is active, the clocks are active, etc. and this whole thing typically burns mA’s of current (at least on a PSoC 6).

So, what should you do?  The answer is that instead of “idling” you should put the CPU to Sleep, preferably DeepSleep.  But where should you do that?  The perfect place is in the idle task.  If you setup the idle task to just put the CPU to Sleep/DeepSleep then you save power.

But if the CPU is asleep how do you wakeup and when?  There are two answers to those questions:

1. If nothing is pending, there are no timers running, you should go to sleep and wait for an interrupt (from an MCU peripheral … like a pin)
2. If you know that everything is blocked, but a task is supposed to wakeup at some specified time, then you should go to sleep until that time.

But how do you set a wakeup time?  Simple.  Use the PSoC 6 MCWDT as a DeepSleep Low Power Timer.

In this article I will show you how to setup the FreeRTOS configuration files plus the HAL lptimer to achieve goal.  The sections are:

• PSoC Configurator
• FreeRTOSConfig.h
• LowPower.c
• A Demo Program

PSoC 6 Configurator

If you look at the PSoC 6 device configurator you will find a section called “RTOS”.  This was put by the Low Power Assistant team to enable stuff for MBEDOS.  However, it can/could/will be used for FreeRTOS as well.   All this configuration does is create a section of #defines which can then be used to setup your low power code.

The first parameter is “System Idle Power Mode” which can be set as “Active, CPU Sleep or System Deep Sleep”.

The second parameter is “Deep Sleep Latency” which is an integer which can set the minimum sleep time.  In other words if you are going to sleep less than this number, don’t bother.

When you configure these parameters, it will create the following #defines in the cycfg_system.h

The first three are used because the c-preprocessor can only evaluate integer expressions.  These defines enable you to do compares with the power mode in your code.  The “CY_CFG_PWR_SYS_IDLE_MODE” it set to whatever you specified in the configurator.  Here is a clip from the cycfg_system.h

#define CY_CFG_PWR_MODE_ACTIVE 0x04UL
#define CY_CFG_PWR_MODE_SLEEP 0x08UL
#define CY_CFG_PWR_MODE_DEEPSLEEP 0x10UL
#define CY_CFG_PWR_SYS_IDLE_MODE CY_CFG_PWR_MODE_DEEPSLEEP
#define CY_CFG_PWR_DEEPSLEEP_LATENCY 8UL

FreeRTOSConfig.h

So now what?  Lets use those defines to get FreeRTOS going.  The first thing you need to do is tell FreeRTOS that you want to use TICKLESS IDLE by setting the #define configUSE_TICKLESS_IDLE.  There are three possible settings:

• 0 or undefined – no tickless idle
• 1 – use the built-in port (which we did’t supply)
• 2 – use a application developer supplied low power configuration (this is what we are going to do)

I add this block of code to my FreeRTOSConfig.h.  It says:

63: If the user has selected Sleep or DeepSleep

64: Give me access to the vApplicationSleep function (which I will write)

65: Tell FreeRTOS to call the vApplicationSleep function in the idle task

66: And tell FreeRTOS that I want to use MY OWN implementation of Tickless

69-71: If the user has specified a minimum time, then tell FreeRTOS to use that minimum.

#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

LowPower.c

Now I need to implement the function “vApplicationSleep” which will look at the state of affairs and “do the needful”.  I decided to put all of the low power stuff a file called “lowPower.c”.   It goes like this:

24-25: Create a low power timer (if I haven’t already)

27-28: Disable the SysTick and disable the ARM global interrupts

31: Ask the RTOS if we REALLY want to go to sleep, which could have changed if there was an interrupt or a task became active before the interrupts were disabled

32: Reset the timer to 0 (so that we can get a maximum delay)

34: If we are really going to go to sleep (in other words we shouldn’t abort)

Remember from above there are two Sleep/DeepSleep cases:

1. There are no tasks waiting
2. There is a task waiting

36-40: If there is a task waiting then setup the timer to wakeup in that amount of time

42: Remember when you went to sleep, so you can fix the system timer after you wake backup

43-46: Sleep or DeepSleep (depending on what the user said in the configurator)

48: Or bail if the developer didn’t turn on this code

51: When you wake up find out what time it is

54: Fix the tick count in the RTOS based on how long you slept

56: Disable the lptimer interrupt

61-62: Enable the interrupts and turn the SysTick back on.

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

static inline uint32_t msToTicks(uint32_t ms)
{
	uint64_t val = (CY_SYSCLK_WCO_FREQ*(uint64_t)ms/1000);
	val = (val>UINT32_MAX)?UINT32_MAX:val;
	return (uint32_t)val;
}

static inline uint32_t ticksToMs(uint32_t ticks)
{
	return (ticks * 1000) / CY_SYSCLK_WCO_FREQ;
}

/* Define the function that is called by portSUPPRESS_TICKS_AND_SLEEP(). */
void vApplicationSleep( TickType_t xExpectedIdleTime )
{
	static cyhal_lptimer_t myTimer={0};
	unsigned long ulLowPowerTimeBeforeSleep, ulLowPowerTimeAfterSleep;

	if(myTimer.base == 0)
		cyhal_lptimer_init(&myTimer);

    Cy_SysTick_Disable();
    uint8_t interruptState = Cy_SysLib_EnterCriticalSection();

    /* Ensure it is still ok to enter the sleep mode. */
    eSleepModeStatus eSleepStatus = eTaskConfirmSleepModeStatus();
	cyhal_lptimer_reload(&myTimer);

    if( eSleepStatus != eAbortSleep )
    {
    	if( eSleepStatus != eNoTasksWaitingTimeout )
    	{
    		cyhal_lptimer_set_delay	(&myTimer,msToTicks(xExpectedIdleTime));
    	    cyhal_lptimer_enable_event (&myTimer, CYHAL_LPTIMER_COMPARE_MATCH, 7, true);
    	}
    	/* Enter the low power state. */
        ulLowPowerTimeBeforeSleep = cyhal_lptimer_read(&myTimer);
#if CY_CFG_PWR_SYS_IDLE_MODE == CY_CFG_PWR_MODE_DEEPSLEEP
    	cyhal_system_deepsleep();
#elif CY_CFG_PWR_SYS_IDLE_MODE == CY_CFG_PWR_MODE_SLEEP
    	cyhal_system_sleep();
#else
    	goto exitPoint;
#endif
    	// How long did it sleep
    	ulLowPowerTimeAfterSleep = cyhal_lptimer_read(&myTimer);

    	/* Correct the kernels tick count to account for the time the microcontroller spent in its low power state. */
    	vTaskStepTick( ticksToMs(ulLowPowerTimeAfterSleep - ulLowPowerTimeBeforeSleep));
    }
    cyhal_lptimer_enable_event (&myTimer, CYHAL_LPTIMER_COMPARE_MATCH, 4, false);

#if !(CY_CFG_PWR_SYS_IDLE_MODE == CY_CFG_PWR_MODE_DEEPSLEEP || CY_CFG_PWR_SYS_IDLE_MODE == CY_CFG_PWR_MODE_SLEEP)
exitPoint:
#endif
    Cy_SysLib_ExitCriticalSection(interruptState);
    Cy_SysTick_Enable();
}

A Demo Program

The last thing to wrap this up is to build an example demo program.  This one will do two things

1. Blink the LED 3 times using an RTOS Delay
2. When the USER button is pressed it will wakeup and do it again.

This will demonstrate that you can do both DeepSleep modes.

1. DeepSleep between LED toggles (i.e. while it it waiting for the vTaskDelay)
2. DeepSleep indefinitely until the Switch is pressed

Start this example with a main that sets up the Switch, then starts the blinking task

int main(void)
{
    uxTopUsedPriority = configMAX_PRIORITIES - 1 ; // enable OpenOCD Thread Debugging

    cybsp_init() ;

    cyhal_gpio_init(CYBSP_SW2,CYHAL_GPIO_DIR_INPUT,CYHAL_GPIO_DRIVE_PULLUP,1);
    cyhal_gpio_enable_event(CYBSP_SW2, CYHAL_GPIO_IRQ_FALL, 7, true);
    cyhal_gpio_register_callback(CYBSP_SW2, buttonEvent, 0);
     __enable_irq();

    // Stack size in WORDs Idle task = priority 0
    xTaskCreate(blinkTask, "blinkTask", configMINIMAL_STACK_SIZE,0 /* args */ ,2 /* priority */, &blinkTaskHandle);
    vTaskStartScheduler();
}

The event handler sets a semaphore when the button is pressed.

void buttonEvent(void *callback_arg, cyhal_gpio_event_t event)
{
	BaseType_t xHigherPriorityTaskWoken;
	xHigherPriorityTaskWoken = pdFALSE;
	xSemaphoreGiveFromISR( xSemaphore, &xHigherPriorityTaskWoken );
	portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
}

The blinking LED task, initializes the LED and the sempahore.

Then blinks until the count is 0, waits for the semaphore, then resets the count back to 6 (aka 3 blinks)

void blinkTask(void *arg)
{
    cyhal_gpio_init(CYBSP_USER_LED,CYHAL_GPIO_DIR_OUTPUT,CYHAL_GPIO_DRIVE_STRONG,0);

    int count=BLINK_COUNT;
    xSemaphore = xSemaphoreCreateBinary(  );
    for(;;)
    {
    	while(count--)
    	{
    		cyhal_gpio_toggle(CYBSP_USER_LED);
    		vTaskDelay(1000);
    	}
    	xSemaphoreTake( xSemaphore,0xFFFFFFFF );
    	count = BLINK_COUNT;
    }
}

 

Summary

In this article I build several different programs to measure the DeepSleep to Active wakeup time of the PSoC 6 which ranges from 15uS to 120uS.  I will discuss the data sheet max of 25uS and the useful limit of about 60uS.  I will include an analysis of the system issues that will influence your wakeup time.

This article is part of the "PSoC 6 Low Power Techniques" Series which covers a range of tools you have to lower the power of your system.  The following articles are (or will be) available:

The following resources are available

The Story

As I was working on implementing the FreeRTOS tickless mode I noticed (incorrectly) that the wakeup time from DeepSleep was around 5ms.  When I saw this number I thought “wow, that is a long time”, then I looked at the data sheet and discovered that it was really “25 uS Guaranteed by design”.  Given that Cypress is very careful about our data sheet numbers I thought “wow… 25uS is a long way from 5ms.  Did we really make that bad an error in the data sheet?”

I decided to dig in to figure out what was really happening.  The real answer is that the wakeup time isn’t anywhere near 5ms. That turned out to be an IoT Expert Alan bug (shhhh don’t tell anyone), but it did turn into an interesting investigation of the PSoC 6 chip.

In order to measure the wakeup time I needed a way to measure between a wakeup trigger and the system being awake.  The best way seemed to use a pin to trigger the wakeup and pin to indicate the system being awake. Then measure using an oscilloscope.  In the PSoC 6, in order to wakeup the system you need to send an interrupt to the Wakeup Interrupt Controller, here is a picture from the TRM.  These interrupts also serve as interrupts for the ARM Cores.

The basic flow of all of these examples is:

1. Enable interrupts on the input pin which is attached to SW2 aka P04 or Arduino D0
2. Write a 0 to the P50/D0 output pin
3. DeepSleep
4. Write a 1 to the P50/D0 output pin
5. Go back to 2

Here is a picture of my CY8CKIT-062-WiFi-BT development kit.  Notice that I soldered a wire to the Switch (SW2) which is connected to P04.  The green switch wire is barely attached because I didn’t want to delaminate the switch from the board.  The yellow wire is attached to P50/D0.

What follows is a discussion of 7 different configurations.  As much as possible I try to use the Cypress Hardware Abstraction Layer (HAL) but as I dig, I get down to writing registers directly.

1. Basic Pin Event and HAL Write
2. Register Custom ISR Instead of HAL ISR
3. Disable ARM Interrupts (no ISR)
4. Write the Output Pin Register Directly (no HAL)
5. Try Different Clock Frequencies
6. Modify the Cypress PDL Function Cy_SysPm_EnterDeepSleep
7. Write the ARM DeepSleep Register Directly and Call __WIFI

Basic Pin Event and HAL Write

I started with this very simple example.  The steps are:

• Use the HAL to enable two output pins (one attached to the LED) and one attached to the Oscilliscope.
• Use the HAL to configure the Switch as an input and then enable interrupts on that switch.

Go into the main loop and:

• Write the LED to On (aka 0) to indicate DeepSleep
• Write the D0 to 0
• DeepSleep
• Write the D0 to 1
• Write the LED to Off (to indicate Active)
• Do a little delay… then do it all over again

int main(void)
{
    /* Initialize the device and board peripherals */
    cybsp_init();

    cyhal_gpio_init(CYBSP_D0,CYHAL_GPIO_DIR_OUTPUT,CYHAL_GPIO_DRIVE_STRONG,0);
    cyhal_gpio_init(CYBSP_SW2,CYHAL_GPIO_DIR_INPUT,CYHAL_GPIO_DRIVE_PULLUP,1);
    cyhal_gpio_init(CYBSP_USER_LED,CYHAL_GPIO_DIR_OUTPUT,CYHAL_GPIO_DRIVE_STRONG,1);

    cyhal_gpio_enable_event(CYBSP_SW2, CYHAL_GPIO_IRQ_FALL, 4, true);

	__enable_irq();

    while(1)
    {
    	cyhal_gpio_write(CYBSP_USER_LED,0);
    	cyhal_gpio_write(CYBSP_D0,0);
    	cyhal_system_deepsleep();
    	cyhal_gpio_write(CYBSP_D0,1);
    	cyhal_gpio_write(CYBSP_USER_LED,1);
    	CyDelay(2000);
    }
}

When I measure this on the Oscilloscope I get 57uS

Register Custom ISR Instead of HAL ISR

Well, 57uS is definitely more than 25uS (though it is way way less than 5ms).  I wondered why isn’t it meeting spec.  And I thought, maybe it is burning time in the HAL pin interrupt service routine.  So, I decided to attach my own ISR.

First there is an interrupt service routine function called “buttonHandler” which toggles the D0 pin to 1, then clears the port interrupt.

In the main function instead of enabling the event, I setup the interrupt directly by:

• Configuring the Port for interrupts
• Setting the edge to falling (because there is a resistive pullup on the switch)
• Loading my own ISR
• Enabling the interrupt

Then in the main loop I remove the D0 pin write to 1.

#include "cybsp.h"
#include "cyhal.h"
#include "cycfg.h"

void buttonHandler()
{
	cyhal_gpio_write(CYBSP_D0,1);
	Cy_GPIO_ClearInterrupt(GPIO_PRT0,4);
}


int main(void)
{
    /* Initialize the device and board peripherals */
    cybsp_init();


    cyhal_gpio_init(CYBSP_D0,CYHAL_GPIO_DIR_OUTPUT,CYHAL_GPIO_DRIVE_STRONG,0);
    cyhal_gpio_init(CYBSP_SW2,CYHAL_GPIO_DIR_INPUT,CYHAL_GPIO_DRIVE_PULLUP,1);
    cyhal_gpio_init(CYBSP_USER_LED,CYHAL_GPIO_DIR_OUTPUT,CYHAL_GPIO_DRIVE_STRONG,1);



	Cy_GPIO_SetInterruptMask(GPIO_PRT0,4,1);
	Cy_GPIO_SetInterruptEdge(GPIO_PRT0,4,CY_GPIO_INTR_FALLING);

	Cy_SysInt_SetVector(ioss_interrupts_gpio_0_IRQn, buttonHandler);

	NVIC_EnableIRQ(ioss_interrupts_gpio_0_IRQn);

    __enable_irq();

    while(1)
    {
    	cyhal_gpio_write(CYBSP_USER_LED,0);
    	cyhal_gpio_write(CYBSP_D0,0);
    	cyhal_system_deepsleep();
    	cyhal_gpio_write(CYBSP_USER_LED,1);
    	CyDelay(2000);
    }
}

When I measure this, I find that it is 54uS instead of 57uS (notice I left the cursors from the previous measurement)

Disable ARM Interrupts (no ISR)

Then I think maybe the problem is the jump to the ISR.  Inside the ARM there are two enable controls over interrupts

1. In the NVIC
2. A global ARM interrupt control

So, I use the cyhal_gpio_enable_event to enable the NVIC.  Then I use the CMSIS function __disable_irq to turn off the ARM interrupts.

int main(void)
{
    /* Initialize the device and board peripherals */
    cybsp_init();

    cyhal_gpio_init(CYBSP_D0,CYHAL_GPIO_DIR_OUTPUT,CYHAL_GPIO_DRIVE_STRONG,0);
    cyhal_gpio_init(CYBSP_SW2,CYHAL_GPIO_DIR_INPUT,CYHAL_GPIO_DRIVE_PULLUP,1);
    cyhal_gpio_init(CYBSP_USER_LED,CYHAL_GPIO_DIR_OUTPUT,CYHAL_GPIO_DRIVE_STRONG,1);

    cyhal_gpio_enable_event(CYBSP_SW2, CYHAL_GPIO_IRQ_FALL, 4, true);

	__disable_irq();

    while(1)
    {
    	cyhal_gpio_write(CYBSP_USER_LED,0);
    	cyhal_gpio_write(CYBSP_D0,0);
    	cyhal_system_deepsleep();
    	cyhal_gpio_write(CYBSP_D0,1);
    	cyhal_gpio_write(CYBSP_USER_LED,1);
    	CyDelay(2000);
    }
}

Now it is 53uS or basically the same as before.  So this doesn’t explain the missing 30uS (or whatever is required to get blow the data sheet spec)

Write the Output Pin Register Directly (no HAL)

Then I think to myself, maybe the HAL functions are slow.  Look at the pin write function:

cyhal_gpio_write(CYBSP_D0,0);

When you look at the function you see that it is really a MACRO for an inline call to the PDL function

__STATIC_INLINE void cyhal_gpio_write_internal(cyhal_gpio_t pin, bool value)
{
    Cy_GPIO_Write(CYHAL_GET_PORTADDR(pin), CYHAL_GET_PIN(pin), value);
}

#define cyhal_gpio_write(pin, value) cyhal_gpio_write_internal(pin, value)

The inline PDL function turns a pin number into a Port, Pin combination with a call to some other PDL functions.

#define CYHAL_GET_PORTADDR(pin)    (Cy_GPIO_PortToAddr(CYHAL_GET_PORT(pin)))  /**< Macro to get the port address from pin */

Those functions basically lookup the bit mask and base address of the Port,Pin.  Plus they have some error checking.

__STATIC_INLINE GPIO_PRT_Type* Cy_GPIO_PortToAddr(uint32_t portNum)
{
    GPIO_PRT_Type* portBase;
    
    if(portNum < (uint32_t)IOSS_GPIO_GPIO_PORT_NR)
    {
        portBase = (GPIO_PRT_Type *)(CY_GPIO_BASE + (GPIO_PRT_SECTION_SIZE * portNum));
    }
    else
    {
        /* Error: Return default base address */
        portBase = (GPIO_PRT_Type *)(CY_GPIO_BASE);
    }

    return (portBase);
}

Then they call this macro:

GPIO_PRT_OUT_SET(GPIO_PRT5) = 0x01;

Which is just a direct register write.

(((GPIO_PRT_V1_Type*)(base))->OUT_SET)

So I change over my program to write directly to the port register and is make ZERO difference.  On the range where I can see the pulse between the interrupt and the pin write, the difference is too small to register.

Try Different Clock Frequencies

The next thing that I wonder is if the CPU frequency matters.  On my board there are three possible sources of CM4 clock.

• The 8MHz IMO
• The FLL (also known as CLK_PATH0)
• The PLL (also known as CLK_PATH1)

To try the different possibilities, I start by selecting CLK_PATH1 (the PLL) as the source clock for CLK_HF0

Then configure the PLL to 100 MHz

Then I tell the “PATH_MUX1” to use the IMO

Then I start running tests.  Here is the table of results for a bunch of different combinations.

OK.  The “wakeup” time seems to depend on the clock source and frequency.  First, notice that if you use the PLL that it typically takes 16uS to lock … and it could take as much as 35uS.  That explains part of the difference.

The FLL consistently takes 7.uS to lock.  In fact that is the main reason it exists on this chip.

We know that the FLL and PLL explain some of the difference in the startup time.  But where is the rest?

Modify the Cypress PDL Function Cy_SysPm_EnterDeepSleep

The answer is that there are a bunch of things that happen AFTER the chip wakes up inside of the Cy_SysPm_EnterDeepSleep.  These things are part of the house keeping that it takes to make everything really work.

First, look at the cyhal_system_deepsleep() function, which is really just a #define for the PDL DeepSleep function.

#define cyhal_system_deepsleep()                Cy_SysPm_CpuEnterDeepSleep(CY_SYSPM_WAIT_FOR_INTERRUPT)

If you dig through that function you will find yourself down in another function named “EnterDeepSleepRam.  If you look on line 2965 you will find that the code sets the bit in the ARM System Control Register which tells it to DeepSleep.  Then on line 2969 it executes the ARM assembly language instruction “WFI” also known as Wait For interrupt.  The WFI puts the CPU to sleep, or deep sleep depending on bit in the SCR register.  On lines 2970, 2993 and 3030 you can see that I instrumented the code to toggle the D0 GPIO so I can measure time.

/*******************************************************************************
* Function Name: EnterDeepSleepRam
****************************************************************************//**
*
* The internal function that prepares the system for Deep Sleep and 
* restores the system after a wakeup from Deep Sleep.
*
* \param waitFor
* Selects wait for action. See \ref cy_en_syspm_waitfor_t.
*
* \return
* - true - System Deep Sleep was occurred. 
* - false - System Deep Sleep was not occurred.
*
*******************************************************************************/
#if defined (__ICCARM__)
    #pragma diag_suppress=Ta023
    __ramfunc
#else
    CY_SECTION(".cy_ramfunc") CY_NOINLINE
#endif
static void EnterDeepSleepRam(cy_en_syspm_waitfor_t waitFor)
{
    /* Store the address of the Deep Sleep indicator into the RAM */
    volatile uint32_t *delayDoneFlag = &FLASHC_BIST_DATA_0;
    
#if (CY_CPU_CORTEX_M4)

    /* Store the address of the CM4 power status register */
    volatile uint32_t *cpussCm4PwrCtlAddr = &CPUSS_CM4_PWR_CTL;

    /* Repeat the WFI/WFE instruction if a wake up was not intended. 
    *  Cypress ID #272909
    */
    do
    {
#endif /* (CY_CPU_CORTEX_M4) */

        /* The CPU enters Deep Sleep mode upon execution of WFI/WFE */
        SCB_SCR |= SCB_SCR_SLEEPDEEP_Msk;

        if(waitFor != CY_SYSPM_WAIT_FOR_EVENT)
        {
            __WFI();
        	GPIO_PRT_OUT_SET(GPIO_PRT5) = 0x01;

        }
        else
        {
            __WFE();

        #if (CY_CPU_CORTEX_M4)
            /* Call the WFE instruction twice to clear the Event register 
            *  of the CM4 CPU. Cypress ID #279077
            */
            if(wasEventSent)
            {
                __WFE();
            }
            wasEventSent = true;
        #endif /* (CY_CPU_CORTEX_M4) */
        }

#if (CY_CPU_CORTEX_M4)
    } while (_FLD2VAL(CPUSS_CM4_PWR_CTL_PWR_MODE, (*cpussCm4PwrCtlAddr)) == CM4_PWR_STS_RETAINED);
#endif /* (CY_CPU_CORTEX_M4) */

	GPIO_PRT_OUT_CLR(GPIO_PRT5) = 0x01;

    /* Set 10 uS delay only under condition that the FLASHC_BIST_DATA[0] is 
    *  cleared. Cypress ID #288510
    */
    if (*delayDoneFlag == NEED_DELAY)
    {
        uint32_t ddftSlowCtl;
        uint32_t clkOutputSlow;
        uint32_t ddftFastCtl;

        /* Save timer configuration */
        ddftSlowCtl   = SRSS_TST_DDFT_SLOW_CTL_REG;
        clkOutputSlow = SRSS_CLK_OUTPUT_SLOW;
        ddftFastCtl   = SRSS_TST_DDFT_FAST_CTL_REG;

        /* Configure the counter to be sourced by IMO */
        SRSS_TST_DDFT_SLOW_CTL_REG = SRSS_TST_DDFT_SLOW_CTL_MASK;
        SRSS_CLK_OUTPUT_SLOW       = CLK_OUTPUT_SLOW_MASK;
        SRSS_TST_DDFT_FAST_CTL_REG = TST_DDFT_FAST_CTL_MASK;

        /* Load the down-counter to count the 10 us */
        SRSS_CLK_CAL_CNT1 = IMO_10US_DELAY;

        while (0U == (SRSS_CLK_CAL_CNT1 & SRSS_CLK_CAL_CNT1_CAL_COUNTER_DONE_Msk))
        {
            /* Wait until the counter stops counting */
        }

        /* Indicate that delay was done */
        *delayDoneFlag = DELAY_DONE;
        
        /* Restore timer configuration */
        SRSS_TST_DDFT_SLOW_CTL_REG = ddftSlowCtl;
        SRSS_CLK_OUTPUT_SLOW       = clkOutputSlow;
        SRSS_TST_DDFT_FAST_CTL_REG = ddftFastCtl;
    }
	GPIO_PRT_OUT_SET(GPIO_PRT5) = 0x01;


}
#if defined (__ICCARM__)

Here is the SCR register documentation where you can see the bit “SLEEPDEEP” bit[2]

And later in the documentation the Wait For Interrupt (WFI) instruction.

When I ran the code I got:

• From the falling edge of the to the rising edge is 17.12uS (deep sleep to first instruction on line 2970)
• From the rising to falling edge is 6.25uS (line 2970 to line 2993)
• From the falling to riding edge is 30uS (line 2993 to 3030)
• From the rising to falling edge is 3.5uS (line 3030 to the first line in the main function)

Here is the scope trace.

What does it all mean?  There are basically three things going on from the Wakeup until the application developer has control.

1. Cypress implementation of work arounds for chip issues
2. Synchronization between the two MCUs in the PSoC 6
3. Unwinding the DeepSleep preparations (user callbacks)

Write the ARM DeepSleep Register Directly and Call __WIFI

So this gives us a hint.  We could implement just the DeepSleep instructions.  If you did, the code would look like this:

#include "cybsp.h"
#include "cyhal.h"
#include "cycfg.h"


int main(void)
{
    /* Initialize the device and board peripherals */
    cybsp_init();

    cyhal_gpio_init(CYBSP_D0,CYHAL_GPIO_DIR_OUTPUT,CYHAL_GPIO_DRIVE_STRONG,0);
    cyhal_gpio_init(CYBSP_SW2,CYHAL_GPIO_DIR_INPUT,CYHAL_GPIO_DRIVE_PULLUP,1);
    cyhal_gpio_init(CYBSP_USER_LED,CYHAL_GPIO_DIR_OUTPUT,CYHAL_GPIO_DRIVE_STRONG,1);

    cyhal_gpio_enable_event(CYBSP_SW2, CYHAL_GPIO_IRQ_FALL, 4, true);


    __disable_irq();

    while(1)
    {
    	cyhal_gpio_write(CYBSP_D0,0);

        SCB_SCR |= SCB_SCR_SLEEPDEEP_Msk;
        __WFI();
    	GPIO_PRT_OUT_SET(GPIO_PRT5) = 0x01;

    	Cy_GPIO_ClearInterrupt(GPIO_PRT0,4);
    	NVIC_ClearPendingIRQ	(	ioss_interrupts_gpio_0_IRQn	)	;
    	cyhal_gpio_write(CYBSP_USER_LED,0);

    	CyDelay(2000);
    	cyhal_gpio_write(CYBSP_USER_LED,1);

    }
}

Well there it is 12uS.  That is for sure below the data sheet limit of 25uS.

But is it a good idea?  No, almost certainly not.  If you don’t call the Cypress functions you will

1. Not be protected from the dual core interactions
2. Not call our functions to work around silicon bugs
3. Potentially not manage the clocks correctly

So unless you have some really compelling reason you should just use the Cypress functions and accept the 50ish uS to get back to Active.

Summary

This article walks you through the steps to use the PSoC 6 MultiCounter Watch Dog Timer (MCWDT) as a DeepSleep Timer.  This includes using the Cypress HAL (lptimer), PDL as well as the configurators to achieve this goal.

This article is part of the "PSoC 6 Low Power Techniques" Series which covers a range of tools you have to lower the power of your system.  The following articles are (or will be) available:

The following resources are available

The Story

If you want to build a low power PSoC 6 project you need a method to wake up the chip from DeepSleep.  This is particularly true of projects that use an RTOS in Tickless mode where you need a mechanism to go to DeepSleep and wakeup at a specific time.  Why DeepSleep?  Because it burns way-way less power than the active modes.  Way less means something like 3 orders of magnitude less. 

In this article I will

• Describe the MultiCounter Watch Dog Timer (MCWDT)
• Configure the MCWDT using the PSoC 6 Configurator
• Configure the MCWDT using PDL
• Configure the MCWDT using the HAL – AKA the lptimer
• Show the LP Timer Deep Sleep Current vs. Active Current
• Measure the Sleep Time & Show Interactions with DeepSleep and rest of the PSoC6

The Multi Counter Watch Dog Timer (MWCDT)

Inside of the PSoC 6 there are two blocks that have some variant of the name Watch Dog Timer.  Specifically the:

• Multi Counter Watch Dog Timer (MCWDT)
• Watch Dog Timer (WDT)

Here is a screenshot from the PSoC 6 block diagram.

As I was working on this article I spoke with the original architect of the PSoC 6 and he told me that you should use the WDT as a WDT (but that it could be used as a periodic timer) and you should use the MCWDT as a periodic timer (but that it could be used as a WDT).  This is a pretty common example of the Cypress design aesthetic of maximizing flexibility.

Bottom line:  You should use the MCWDT as a deep sleep timer.

What is the MCWDT?  It is actually three counters which can be used individually or cascaded.  The counters each up count to a specific match value (aka period) and reset or they optionally count continuously.  And each counter can generate an interrupt when the period is reached.  The one “weird” thing is that counter 2 doesn’t have a match value, it has a match BIT position meaning it will match every 2,4,8,16…  times depending on the bit position.

The counters are clocked by one of the 32kHz clocks in the PSoC 6 called “LFCLK” which can either be the WCO, the ILO or the PILO.  This means that each “count” is 1/32768 = 30uS-ish

This means you can have

• 2×16-bit counters and 1×32 bit
• 2×32-bit counters
• 1×16-bit and 1×48-bit counter
• 1×64-bit counter

Here is a picture of the block diagram from the TRM.

PSoC 6 Configurator

For the first project I will use the PSoC 6 Configurators to setup the PDL configuration structures.   I will make a project that will blink an LED at 1Hz.  To do this I will configure counter 0 to turn 30.5uS into milliseconds and counter 1 to count 500 milliseconds.  When counter 1 hits 500 it will toggle the LED.

Start by making a new project:

Give it a name and choose the Empty PSoC6 App as a template

From the quick panel choose “Device Configurator (new configuration)”

Then click on Peripherals –> System and enable Multi-Counter Watchdog Timer (MCWDT) 0.

Notice that you can configure it to count up to the max then rollover (also known as Free running) or you can have it reset the counters back to 0 when it hits the match value (also known as Clear on match)

And when it his the end what do you want it to do?  Interrupt, Watchdog reset, 3xWatchdog reset or nothing?

Here is the configuration we want for this example:

When you hit “save” the configurator will update the files in “libs->TARGET_CY8CKIT-062-WiFi-BT->COMPONENT_BSP_DESIGN_MODUS->GeneratedSource”.  Specifically cycfg_peripherals.h/.c.

In the cycfg_peripherals.h it makes an #define alias called “mycounter_” which is sets you up for the MCWDT0

And in the cycfg_peripherals.c it sets up the configuration structure

Now you can write this simple program in main.c

• Lines 5-9 provide an ISR that toggles the LED and clears the MCWDT interrupt.  Notice that I assumed the interrupt was counter 1
• Lines 18-27 setup interrupts for the MCWDT0
• Lines 30-36 use the PDL configuration structure form the PSoC 6 configurator to setup the MCWDT

The main loop just goes into DeepSleep to save power.

#include "cybsp.h"
#include "cyhal.h"
#include <stdio.h>

void mcwdtISR()
{
	Cy_MCWDT_ClearInterrupt	(mycounter_HW,CY_MCWDT_CTR1);
	cyhal_gpio_toggle(CYBSP_USER_LED1);
}


int main(void)
{
	cybsp_init() ;

	cyhal_gpio_init(CYBSP_USER_LED1,CYHAL_GPIO_DIR_OUTPUT,CYHAL_GPIO_DRIVE_STRONG,1);

	cy_stc_sysint_t intrCfg =
	{
			.intrSrc = mycounter_IRQ,
			.intrPriority = 4UL
	};

	Cy_SysInt_Init(&intrCfg, mcwdtISR);
	NVIC_EnableIRQ(mycounter_IRQ);

	__enable_irq();


	Cy_MCWDT_Unlock(mycounter_HW);
	Cy_MCWDT_Disable(mycounter_HW, CY_MCWDT_CTR0 | CY_MCWDT_CTR1, 100);

	Cy_MCWDT_Init(mycounter_HW,&mycounter_config);
	Cy_MCWDT_SetInterruptMask(	MCWDT_STRUCT0,	CY_MCWDT_CTR1	);

	Cy_MCWDT_Enable(mycounter_HW, CY_MCWDT_CTR0 | CY_MCWDT_CTR1 , 100);

	for(;;)
	{
		Cy_SysPm_DeepSleep(CY_SYSPM_WAIT_FOR_INTERRUPT);
	}
}

Basic HAL LP Timer

Obviously you can do all of the PDL stuff… but we also provide a higher level abstraction called the “LPTIMER”  which does all of the configuration for you.   To demonstrate this I create the same program except using the HAL.  This program will use the LPTIMER and an event to blink the LED at 1hz (toggle every 500ms).

The main.c has:

• Lines 9-12 a simple function to turn milliseconds into ticks of the MCWDT (remember it is clocked with 32KHz)
• Lines 14-18 is the event handler function which is called when the LPTIMER expires.  All it does is toggle the LED and reset the timer to MSDELAY
• Lines 26-29 setup the LPTimer, enable the interrupt event, register the callback function and then set the timer

The main loop just goes to DeepSleep.

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

#define MSDELAY 500

cyhal_lptimer_t myTimer;

static inline uint32_t msToTicks(uint32_t ms)
{
	return (uint32_t)(CY_SYSCLK_WCO_FREQ*(ms/1000));
}

void lptimer_event(void *callback_arg, cyhal_lptimer_event_t event)
{
	cyhal_gpio_toggle(CYBSP_LED8);
	cyhal_lptimer_set_delay(&myTimer, msToTicks(MSDELAY));
}

int main(void)
{

	cybsp_init() ;
	cyhal_gpio_init(CYBSP_LED8,CYHAL_GPIO_DIR_OUTPUT,CYHAL_GPIO_DRIVE_STRONG,1);

	cyhal_lptimer_init(&myTimer);
	cyhal_lptimer_enable_event (&myTimer, CYHAL_LPTIMER_COMPARE_MATCH, 4, true);
	cyhal_lptimer_register_callback(&myTimer, lptimer_event, 0);
	cyhal_lptimer_set_delay(&myTimer, msToTicks(MSDELAY));

	__enable_irq();

	for(;;)
	{
		cyhal_system_deepsleep();

	}
}

LP Timer Deep Sleep Current vs. Active Current

For the next project I will use the LPTIMER to demonstrate the DeepSleep current versus the Active Current.  This project:

• Will use LED8 to indicate DeepSleep and LED9 to indicate Active
• Go to DeepSleep for 2 seconds (so you can read the power)
• Wait in a busy-wait loop for 2 seconds
• Loop again

The main.c has:

• Lines 8-12 a simple function to turn milliseconds into ticks of the MCWDT (remember it is clocked with 32KHz)
• Lines 17-18 Setup the two LEDs to indicate the power state
• Lines 20-21 initialize the low power timer.  Notice that you can enable the event (which will wakeup the chip) but you don’t have to provide an event handler.  The LPTIMER ISR will handle clearing the interrupts for you
• Lines 27-29 will setup the LPTIMER delay, turn on LED8 and off LED9 and go to DeepSleep
• Lines 31-32 will turn off LED8 and on LED9 then go into a busy wait loop.

Notice that I did two three things weren’t aren’t awesome:

1. I hardcoded the 0/1 for the LED state (they are active low)… this is too bad since the BSP actually provides CYBSP_LED_STATE_ON
2. I put two LED set on the same line (two statements on the same line is super dangerous)
3. No comments (yes Hassane will make commentary on this)

#include "cyhal.h"
#include "cybsp.h"

cyhal_lptimer_t myTimer;

#define MSDELAY 2000

static inline uint32_t msToTicks(uint32_t ms)
{
	return (uint32_t)(CY_SYSCLK_WCO_FREQ*(ms/1000));
}

int main(void)
{
	cybsp_init() ;

	cyhal_gpio_init(CYBSP_LED8,CYHAL_GPIO_DIR_OUTPUT,CYHAL_GPIO_DRIVE_STRONG,1);
	cyhal_gpio_init(CYBSP_LED9,CYHAL_GPIO_DIR_OUTPUT,CYHAL_GPIO_DRIVE_STRONG,1);

	cyhal_lptimer_init(&myTimer);
	cyhal_lptimer_enable_event (&myTimer, CYHAL_LPTIMER_COMPARE_MATCH, 4, true);

	__enable_irq();

	for(;;)
	{
		cyhal_lptimer_set_delay(&myTimer,msToTicks(MSDELAY));
		cyhal_gpio_write(CYBSP_LED8,0);	cyhal_gpio_write(CYBSP_LED9,1);
		cyhal_system_deepsleep();

		cyhal_gpio_write(CYBSP_LED8,1);	cyhal_gpio_write(CYBSP_LED9,0);
		Cy_SysLib_Delay(MSDELAY);

	}
}

On the back of my development kit I setup the multimeter to be in series with the PSoC 6 power.  Notice that I keep from loosing the jumper by attaching it to only 1 of the pins.

When I measure the power I get Active power of about 10mA

And DeepSleep power of 15uA… that’s cool almost 1000x difference.

The one things that took me a LONG time to figure out is that I was having problems with the PSoC 6 resetting.  My multimeter has a bunch of different ranges for current measurement.  Each of these different ranges have a different shunt-resistor to increase the accuracy of the meter.  The interesting part is that the meter actually uses a mechanical relay to switch between the ranges.  You can hear it clicking between the ranges.  It turns out that sometime the relay switching took long enough that the PSoC6 would loose power and reset.

Measure the Sleep Time?

The next thing that I was curious about was how long it actually slept.  So I created a new project which would print out the counter values before and after the sleeps using printf which was added to my project with “Retarget I/O”.  You can do this in the library manager.

Once the library is added to your project you can enable it by adding the

#include "cy_retarget_io.h"

And

cy_retarget_io_init(CYBSP_DEBUG_UART_TX, CYBSP_DEBUG_UART_RX, CY_RETARGET_IO_BAUDRATE);

In this project I add prints to look at the sleep time… on lines 42 & 48

#include "cy_pdl.h"
#include "cyhal.h"
#include "cybsp.h"
#include "cy_retarget_io.h"

cyhal_lptimer_t myTimer;

#define MSDELAY 2000

static inline uint32_t msToTicks(uint32_t ms)
{
	return (uint32_t)(CY_SYSCLK_WCO_FREQ*(ms/1000));
}

int main(void)
{

	uint32_t sleepTime=0,wakeTime=0,totalTime=0;

	cybsp_init() ;


	cy_retarget_io_init(CYBSP_DEBUG_UART_TX, CYBSP_DEBUG_UART_RX, CY_RETARGET_IO_BAUDRATE);
	printf("Started Project\n");

	cyhal_gpio_init(CYBSP_LED8,CYHAL_GPIO_DIR_OUTPUT,CYHAL_GPIO_DRIVE_STRONG,1);
	cyhal_gpio_init(CYBSP_LED9,CYHAL_GPIO_DIR_OUTPUT,CYHAL_GPIO_DRIVE_STRONG,1);


	cyhal_lptimer_init(&myTimer);
	cyhal_lptimer_enable_event (&myTimer, CYHAL_LPTIMER_COMPARE_MATCH, 4, true);

	__enable_irq();

	for(;;)
	{
		cyhal_lptimer_set_delay(&myTimer,msToTicks(MSDELAY));
		cyhal_gpio_write(CYBSP_LED8,0);	cyhal_gpio_write(CYBSP_LED9,1);
		sleepTime = cyhal_lptimer_read(&myTimer);
		cyhal_system_deepsleep();
		wakeTime = cyhal_lptimer_read(&myTimer);
		printf("Deep Sleep Time = %ld Wake=%ld Sleep=%ld\n",wakeTime-sleepTime,wakeTime,sleepTime);

		cyhal_gpio_write(CYBSP_LED8,1);	cyhal_gpio_write(CYBSP_LED9,0);
		sleepTime = cyhal_lptimer_read(&myTimer);
		Cy_SysLib_Delay(MSDELAY);
		wakeTime = cyhal_lptimer_read(&myTimer);
		totalTime = (wakeTime<sleepTime)?wakeTime+UINT32_MAX-sleepTime:wakeTime-sleepTime;
		printf("Sleep Time = %ld %ld %ld\n",totalTime,wakeTime,sleepTime);

	}
}

I immediately see that something is wrong.  Now my project never DeepSleeps.  But why?

In order to figure this out I add the code to look at the return code from the cyhal_deep_sleep function.

		cy_rslt_t failedCode = cyhal_system_deepsleep();
		wakeTime = cyhal_lptimer_read(&myTimer);
		printf("Deep Sleep Time = %ld Wake=%ld Sleep=%ld\n",wakeTime-sleepTime,wakeTime,sleepTime);
		uint8_t type = CY_RSLT_GET_TYPE(failedCode);
		uint16_t module_id = CY_RSLT_GET_MODULE(failedCode);
		uint16_t error_code = CY_RSLT_GET_CODE(failedCode);
		printf("Type = %02X Module=%02X Code=%02X\n",type,module_id,error_code);

When I run this you see that I am getting error code 0xFF.  But where is that coming from?

Now is a good time to examine the lower power callbacks.  When you initialize the UART in the HAL it will add a low power callback.  The low power call back is called in one of four situations:

When you look a the hal uart initialization function in cy

 

cy_rslt_t cyhal_uart_init(cyhal_uart_t *obj, cyhal_gpio_t tx, cyhal_gpio_t rx, const cyhal_clock_divider_t *clk, const cyhal_uart_cfg_t *cfg)
{
    CY_ASSERT(NULL != obj);

On line 278 it sets up the callback function “cyhal_uart_pm_callback”

        obj->pm_params.base = obj->base;
        obj->pm_params.context = obj;
        obj->pm_callback.callback = &cyhal_uart_pm_callback;
        obj->pm_callback.type = CY_SYSPM_DEEPSLEEP;
        obj->pm_callback.skipMode = 0;
        obj->pm_callback.callbackParams = &(obj->pm_params);
        obj->pm_callback.prevItm = NULL;
        obj->pm_callback.nextItm = NULL;
        if (!Cy_SysPm_RegisterCallback(&(obj->pm_callback)))
            result = CYHAL_UART_RSLT_ERR_PM_CALLBACK;

Then when you look in cy_hal_uart.c you see that the function will call the function Cy_SCB_UART_DeepSleepCallback (line 103)

static cy_en_syspm_status_t cyhal_uart_pm_callback(cy_stc_syspm_callback_params_t *params, cy_en_syspm_callback_mode_t mode)
{
    cyhal_uart_t *obj = params->context;
    cy_stc_syspm_callback_params_t pdl_params = { .base = obj->base, .context = &(obj->context) };
    cy_en_syspm_status_t rslt = Cy_SCB_UART_DeepSleepCallback(&pdl_params, mode);
    GPIO_PRT_Type *txport = obj->pin_tx != NC ? CYHAL_GET_PORTADDR(obj->pin_tx) : NULL,
                  *rtsport = obj->pin_rts != NC ? CYHAL_GET_PORTADDR(obj->pin_rts) : NULL;
    uint8_t txpin = (uint8_t)CYHAL_GET_PIN(obj->pin_tx), rtspin = (uint8_t)CYHAL_GET_PIN(obj->pin_rts);
    switch (mode)
    {
        case CY_SYSPM_CHECK_READY:
            if (rslt == CY_SYSPM_SUCCESS)
            {
                if (NULL != txport)
                {
                    obj->saved_tx_hsiom = Cy_GPIO_GetHSIOM(txport, txpin);
                    Cy_GPIO_Set(txport, txpin);
                    Cy_GPIO_SetHSIOM(txport, txpin, HSIOM_SEL_GPIO);
                }
                if (NULL != rtsport)
                {
                    obj->saved_rts_hsiom = Cy_GPIO_GetHSIOM(rtsport, rtspin);
                    Cy_GPIO_Set(rtsport, rtspin);
                    Cy_GPIO_SetHSIOM(rtsport, rtspin, HSIOM_SEL_GPIO);
                }
            }
            break;

        case CY_SYSPM_CHECK_FAIL: // fallthrough
        case CY_SYSPM_AFTER_TRANSITION:
            if (NULL != txport)
            {
                Cy_GPIO_SetHSIOM(txport, txpin, obj->saved_tx_hsiom);
            }
            if (NULL != rtsport)
            {
                Cy_GPIO_SetHSIOM(rtsport, rtspin, obj->saved_rts_hsiom);
            }
            break;

        default:
            break;
    }
    return rslt;
}

And in the PDL file cy_scb_uart.c you can see that this function will fail if there is data currently being transmitted (line 315)

cy_en_syspm_status_t Cy_SCB_UART_DeepSleepCallback(cy_stc_syspm_callback_params_t *callbackParams, cy_en_syspm_callback_mode_t mode)
{
    cy_en_syspm_status_t retStatus = CY_SYSPM_FAIL;

    CySCB_Type *locBase = (CySCB_Type *) callbackParams->base;
    cy_stc_scb_uart_context_t *locContext = (cy_stc_scb_uart_context_t *) callbackParams->context;

    switch(mode)
    {
        case CY_SYSPM_CHECK_READY:
        {
            /* Check whether the High-level API is not busy executing the transmit
            * or receive operation.
            */
            if ((0UL == (CY_SCB_UART_TRANSMIT_ACTIVE & Cy_SCB_UART_GetTransmitStatus(locBase, locContext))) &&
                (0UL == (CY_SCB_UART_RECEIVE_ACTIVE  & Cy_SCB_UART_GetReceiveStatus (locBase, locContext))))
            {
                /* If all data elements are transmitted from the TX FIFO and
                * shifter and the RX FIFO is empty: the UART is ready to enter
                * Deep Sleep mode.
                */
                if (Cy_SCB_UART_IsTxComplete(locBase))
                {
                    if (0UL == Cy_SCB_UART_GetNumInRxFifo(locBase))
                    {
                        /* Disable the UART. The transmitter stops driving the
                        * lines and the receiver stops receiving data until
                        * the UART is enabled.
                        * This happens when the device failed to enter Deep
                        * Sleep or it is awaken from Deep Sleep mode.
                        */
                        Cy_SCB_UART_Disable(locBase, locContext);

                        retStatus = CY_SYSPM_SUCCESS;
                    }
                }
            }
        }
        break;

        case CY_SYSPM_CHECK_FAIL:
        {
            /* The other driver is not ready for Deep Sleep mode. Restore the
            * Active mode configuration.
            */

            /* Enable the UART to operate */
            Cy_SCB_UART_Enable(locBase);

            retStatus = CY_SYSPM_SUCCESS;
        }
        break;

        case CY_SYSPM_BEFORE_TRANSITION:
            /* Do noting: the UART is not capable of waking up from
            * Deep Sleep mode.
            */
        break;

        case CY_SYSPM_AFTER_TRANSITION:
        {
            /* Enable the UART to operate */
            Cy_SCB_UART_Enable(locBase);

            retStatus = CY_SYSPM_SUCCESS;
        }
        break;

        default:
            break;
    }

    return (retStatus);
}

But, where does the error code come from?  When you click on it, you find yourself on this enumeration:

typedef enum
{
    CY_SYSPM_SUCCESS         = 0x0U,                                         /**< Successful. */
    CY_SYSPM_BAD_PARAM       = CY_SYSPM_ID | CY_PDL_STATUS_ERROR | 0x01U,    /**< One or more invalid parameters. */
    CY_SYSPM_TIMEOUT         = CY_SYSPM_ID | CY_PDL_STATUS_ERROR | 0x02U,    /**< A time-out occurred. */
    CY_SYSPM_INVALID_STATE   = CY_SYSPM_ID | CY_PDL_STATUS_ERROR | 0x03U,    /**< The operation is not setup or is in an
                                                                                  improper state. */
    CY_SYSPM_CANCELED        = CY_SYSPM_ID | CY_PDL_STATUS_ERROR | 0x04U,    /**< Operation canceled. */
    CY_SYSPM_SYSCALL_PENDING = CY_SYSPM_ID | CY_PDL_STATUS_ERROR | 0x05U,    /**< Canceled due syscall operation pending. */
    CY_SYSPM_FAIL            = CY_SYSPM_ID | CY_PDL_STATUS_ERROR | 0xFFU     /**< Unknown failure. */
} cy_en_syspm_status_t;

And when you look at CY_SYSPM_ID your find:

/** SysPm driver identifier */
#define CY_SYSPM_ID                      (CY_PDL_DRV_ID(0x10U))

OK… so the reason in our project that it doesn’t go into deep sleep is that the printf from earlier has not finished.  To fix this you update your project to keep trying until the DeepSleep call succeeds (on lines 43-45)

	for(;;)
	{
		cyhal_lptimer_set_delay(&myTimer,msToTicks(MSDELAY));
		cyhal_gpio_write(CYBSP_LED8,0);	cyhal_gpio_write(CYBSP_LED9,1);
		sleepTime = cyhal_lptimer_read(&myTimer);
		cy_rslt_t failedCode;
		do {
			failedCode = cyhal_system_deepsleep();
		} while(failedCode != CY_SYSPM_SUCCESS);

		wakeTime = cyhal_lptimer_read(&myTimer);

		printf("Deep Sleep Time = %ld Wake=%ld Sleep=%ld\n",wakeTime-sleepTime,wakeTime,sleepTime);


		cyhal_gpio_write(CYBSP_LED8,1);	cyhal_gpio_write(CYBSP_LED9,0);
		sleepTime = cyhal_lptimer_read(&myTimer);
		Cy_SysLib_Delay(MSDELAY);
		wakeTime = cyhal_lptimer_read(&myTimer);
 		totalTime = (wakeTime<sleepTime)?wakeTime+UINT32_MAX-sleepTime:wakeTime-sleepTime;
		printf("Sleep Time = %ld %ld %ld\n",totalTime,wakeTime,sleepTime);
	}

Now this makes a lot more sense