AN228571  Getting started with PSoC™ 6 MCU on ModusToolbox™ software

A wealth of data available here helps you to select the right PSoC™ MCU and quickly and effectively integrate it into your design. For a comprehensive list of F-RAM resources, see How to design with F-RAM - KBA223067. The following is an abbreviated list of resources for F-RAM.

• Overview: PSoC™ portfolio
• F-RAM webpage
• Product selectors: F-RAM
• Datasheets describe and provide electrical specifications for each device family.
• Application notes and Code examples cover a broad range of topics, from basic to advanced level. You can also browse our collection of code examples.
• Technical reference manuals (TRMs) provide detailed descriptions of the architecture and registers in each device family.
• F-RAM programming specification provides the information necessary to program the nonvolatile memory of F-RAM devices.
• CAPSENSE™ design guides: Learn how to design capacitive touch-sensing applications with PSoC™ devices.
• Development tools: Many low-cost kits and shield boards are available for evaluation, design, and development of different applications using F-RAMs.
• Training videos: Video training on our products and tools, including a dedicated series on F-RAMs.
• Technical Support: PSoC™ 6 community forum, Knowledge base articles.

There are two development platforms that you can use for application development with F-RAM:

• ModusToolbox™: This software includes configuration tools, low-level drivers, middleware libraries, and other packages that enable you to create MCU and wireless applications. All tools run on Windows, macOS, and Linux. ModusToolbox™ includes an Eclipse IDE, which provides an integrated flow with all the ModusToolbox™ tools. Other IDEs such as Visual Studio Code, IAR Embedded Workbench and Arm® MDK (μVision) are also supported.

  ModusToolbox™ software supports stand-alone device and middleware configurators. Use the configurators to set the configuration of different blocks in the device and generate code that can be used in firmware development. It is recommended that you use ModusToolbox™ software for all application development for F-RAMs. See the ModusToolbox™ tools package user guide for more information.

  Libraries and enablement software are available at the GitHub site.

  Software resources available at GitHub support one or more of the target ecosystems:

  • MCU and Bluetooth® SoC ecosystem – a full-featured platform for F-RAM, Bluetooth®, and Bluetooth® low energy application development.
  • Connectivity ecosystem – a set of libraries providing core functionality of Wi-Fi including connectivity, security, firmware upgrade support, and application layer protocols for applications.
  • Amazon FreeRTOS ecosystem – extends the FreeRTOS kernel with software libraries that make it easy to securely connect small, low-power Infineon devices to most cloud services.

  ModusToolbox™ tools and resources can also be used on the command line. See the build system chapter in theModusToolbox™ tools package user guide for detailed documentation.

• PSoC™ Creator: A proprietary IDE that runs on Windows only. It supports a subset of F-RAMs, as well as other PSoC™ families such as PSoC™ 3, PSoC™ 4, and PSoC™ 5LP. See AN221774 - Getting started with PSoC™ 6 on PSoC™ Creator for more information.

You can develop firmware for F-RAMs using your preferred IDE such as Eclipse IDE, IAR Embedded Workbench, Keil µVision 5 or Visual Studio Code.

ModusToolbox™ Configurators are stand-alone tools that can be used to set up and configure F-RAM resources and other middleware components without using the Eclipse IDE. The Device Configurator and middleware configurators use the design.x files within the application workspace. You can then point to the generated source code and continue developing firmware in your IDE.

If there is a change in the device configuration, edit the design.x files using the configurators and regenerate the code. It is recommended that you generate resource configurations using the configuration tools provided with ModusToolbox™ software.

See ModusToolbox™ tools package user guide for details.

Adding native FreeRTOS support to a ModusToolbox™ application project is like adding any middleware library. You can include the FreeRTOS middleware in your application by using the Library Manager. If using the Eclipse IDE for ModusToolbox™, select the application project and click the Library Manager link in the Quick Panel. Click Add Library and select freertos from the Core dialog, as Figure 9 shows.

The .mtb file pointing to the FreeRTOS middleware is added to the application project's deps directory. The middleware content is also downloaded and placed inside the corresponding folder called freertos. The default location is in the shared asset repo named mtb_shared. To continue working with FreeRTOS, follow the steps in the Quick Start section of FreeRTOS documentation.

All Kits have a KitProg3 onboard programmer/debugger. It supports Cortex® Microcontroller Software Interface Standard - Debug Access Port (CMSIS-DAP). See the KitProg3 user guide for details.

The Eclipse IDE requires KitProg3 and uses the OpenOCD protocol for debugging F-RAM applications. It also supports GDB debugging using industry standard probes like the Segger J-Link.

For more information on debugging firmware on devices with ModusToolbox™, refer to the Program and Debug section in the Eclipse IDE for ModusToolbox™ user guide.

For the complete list of kits for the F-RAM along with the shield modules, see the Microcontroller (MCUs) kits page.

Before you get started, make sure that you have the appropriate development kit for your F-RAM product line and have installed the required software. You also need internet access to the GitHub repositories during project creation.

These instructions are grouped into several sections. Each section is devoted to a phase of the application development workflow. The major sections are:

1. Create a new application
2. View and modify the design configuration
3. Write firmware
4. Build the application
5. Program the device
6. Test your design

This design is developed for the 62S2 Wi-Fi Bluetooth® Prototyping Kit (CY8CPROTO-062S2-43439) You can use other supported kits to test this example by selecting the appropriate kit while creating the application. The code described in the sections that follow has been tested on the following additional kits.

This design uses the CM4 core of the F-RAM to execute two tasks: UART communication and LED control.

At device reset, the Infineon-supplied pre-built CM0+ application image enables the CM4 core and configures the CM0+ core to go to sleep. The CM4 core uses the UART to print a “Hello World” message to the serial port stream, and starts blinking the user LED on the kit. When the user presses the enter key on the serial console, the blinking is paused or resumed.

This section takes you on a step-by-step guided tour of the new application process. It uses the Empty AppEmpty PSoC4 App starter application and manually adds the functionality from the Hello World starter application. The Eclipse IDE for ModusToolbox™ is used in the instructions, but you can use any IDE or the command line if you prefer.

If you are familiar with developing projects with ModusToolbox™ software, you can use the Hello World starter application directly. It is a complete design, with all the firmware written for the supported kits. You can walk through the instructions and observe how the steps are implemented in the code example.

If you start from scratch and follow all the instructions in this application note, you can use the Hello World code example as a reference while following the instructions.

Launch the Dashboard 3.1 application to get started. Please note that the Dashboard 3.1 application needs access to the internet to successfully clone the starter application onto your machine.

The Dashboard 3.1 application helps you get started using the various tools with easy access to documentation and training material, a simple path for creating applications and creating and editing BSPs.

1. Open the Dashboard 3.1 application.

   To open the Dashboard 3.1 application, click [ModusToolbox installation path]/ModusToolbox folder/dashboard 3.1.0

2. On the Dashboard 3.1 window, in the right pane, in the Target IDE drop-down list, select Eclipse IDE for ModusToolbox™, and click Launch Eclipse IDE for ModusToolbox™.

   
   

3. Select a new workspace.

   At launch, Eclipse IDE for ModusToolbox™ presents a dialog to choose a directory for use as the workspace directory. The workspace directory is used to store workspace preferences and development artifacts. You can choose an existing empty directory by clicking the Browse button, as shown in the following figure. Alternatively, you can type in a directory name to be used as the workspace directory along with the complete path, and the IDE will create the directory for you.

   
   

4. Create a new ModusToolbox™ application.
   1. Click New Application in the Start group of the Quick Panel.
   2. Alternatively, you can choose File > New > ModusToolbox™ Application, as shown in the following figure.

      The Project Creator opens.

      
      

5. Select a target F-RAM development kit

   ModusToolbox™ speeds up the development process by providing BSPs that set various workspace/project options for the specified development kit in the new application dialog.

   1. In the Choose Board Support Package (BSP) dialog, choose the Kit Name that you have. The steps that follow use CY8CPROTO-062S2-43439. See Figure 14 for help with this step
   2. Click Next

      
      

   3. In the Select Application dialog, select Empty App starter application, as shown in the following figure.
   4. In the Name field, type in a name for the application, such as Hello_World. You can choose to leave the default name if you prefer.
   5. Click Create to create the application, as shown in the following figure, wait for the Project Creator to automatically close once the project is successfully created.

   
   

You have successfully created a new ModusToolbox™ application for a F-RAM.

The BSP uses CY8C624ABZI-D54 as the default device that is mounted on the PSoC™ 62S2 Wi-Fi-Bluetooth® prototyping kit (CY8CPROTO-062S2-43439) along with the CYW43439KUBG Wi-Fi/Bluetooth® radio.

If you are using custom hardware based on F-RAM, or a different F-RAM part number, please refer to the Custom BSP App Note or the BSP Assistant user guide.

Figure 16 shows the Eclipse IDE Project Explorer interface displaying the structure of the application project.

A F-RAM application consists of a project to develop code for the CM4 core. A project folder consists of various subfolders – each denoting a specific aspect of the project.

1. The files provided by the BSP are in the bsps folder and are listed under TARGET_<bsp name> sub-folders. All the input files for the device and peripheral configurators are in the config folder inside the BSP. The GeneratedSource folder in the BSP contains the files that are generated by the configurators and are prefixed with cycfg_. These files contain the design configuration as defined by the BSP. From ModusToolbox™ 3.x or later, you can directly customize configurator files of BSP for your application rather than overriding the default design configurator files with custom design configurator files since BSPs are completely owned by the application.

   The BSP folder also contains the linker scripts and the start-up code for the F-RAM used on the board.

2. The build folder contains all the artifacts resulting from a build of the project. The output files are organized by target BSPs.

3. The deps folder contains .mtb files, which provide the locations from which ModusToolbox™ pulls the libraries that are directly referenced by the application. These files typically each contain the GitHub location of a library. The .mtb files also contain a git Commit Hash or Tag that tells which version of the library is to be fetched and a path as to where the library should be stored locally.

   For example, Here, retarget-io.mtb points to mtb://retarget-io#latest-v1.X#$$ASSET_REPO$$/retarget-io/latest-v1.X. The variable $$ASSET_REPO$$ points to the root of the shared location which defaults to mtb_shared. If the library must be local to the application instead of shared, use $$LOCAL$$ instead of $$ASSET_REPO$$.

4. The libs folder also contains .mtb files. In this case, they point to libraries that are included indirectly as a dependency of a BSP or another library. For each indirect dependency, the Library Manager places a .mtb file in this folder. These files have been populated based on the targets available in deps folder.

   For example, using BSP CY8CPRTO-062S2-43439 populates libs folder with the following .mtb files: cmsis.mtb, core-lib.mtb, core-make.mtb, mtb-hal-cat1.mtb, mtb-pdl-cat1.mtb, cat1cm0p.mtb, recipe-make-cat1a.mtb.

   For example, using BoyII kit name populates libs folder with the following .mtbfiles: cmsis.mtb, core-lib.mtb, core-make.mtb, mtb-hal-catX.mtb, mtb-pdl-catX.mtb, catXcm33.mtb, recipemake-catXa.mtb.

   The libs folder contains the file mtb.mk, which stores the relative paths of all the libraries required by the application. The build system uses this file to find all the libraries required by the application.

   Everything in the libs folder is generated by the Library Manager so you should not manually edit anything in that folder.
5. An application contains a Makefile which is at the application's root folder. This file contains the set of directives that the make tool uses to compile and link the application project. There can be more than one project in an application. In that case there is a Makefile at the application level and one inside each project. See AN215656 - PSoC™ 6 MCU dual-core system design for details related to multi-project applications
6. By default, when creating a new application or adding a library to an existing application and specifying it as shared, all libraries are placed in an mtb_shared directory adjacent to the application directories.

   The mtb_shared folder is shared between different applications within a workspace. Different applications may use different versions of shared libraries if necessary.

At this point in the development process, you have created an application with the assistance of an application template and modified it to add the retarget-io middleware. In this part, you write the firmware that implements the design functionality.

If you are working from scratch using the EmptyPSoC™ 6 starter application, you can copy the respective source code to the main.c of the application project from the code snippet provided in this section. If you are using the Hello World code example, all the required files are already in the application.

Firmware flow

We now examine the code in the main.c file of the application. Figure 19 shows the firmware flowchart.

The CM0+ core comes out of reset and enables the CM4 core. The CM0+ core is then configured to go to sleep by the provided CM0+ application. Resource initialization for this example is performed by the CM4 core. It configures the system clocks, pins, clock to peripheral connections, and other platform resources.

When the CM4 core is enabled, the clocks and system resources are initialized by the BSP initialization function. The retarget-io middleware is configured to use the debug UART, and the user LED is initialized. The debug UART prints a “Hello World!” message on the terminal emulator – the on-board KitProg3 acts the USB-UART bridge to create the virtual COM port. A timer object is configured to generate an interrupt every 1000 milliseconds. At each Timer interrupt, the CM4 core toggles the LED state on the kit.

The firmware is designed to accept the 'Enter' key as an input and on every press of the 'Enter' key the firmware starts or stops the blinking of the LED.

Note that the application code uses BSP/HAL/middleware functions to execute the intended functionality.

cybsp_init()- This BSP function sets up the HAL hardware manager and initializes all the system resources of the device including but not limited to the system clocks and power regulators.

cy_retarget_io_init()- This function from the retarget-io middleware uses the aliases set up in the BSP for the debug UART pins to configure the debug UART with a standard baud rate of 115200 and also redirects the input/output stream to the debug UART.

Note: You can open the Device Configurator to view the aliases that are set up in the BSP.

cyhal_gpio_init()- This function from the GPIO HAL initializes the physical pin to drive the LED. The LED used is derived from the alias for the pin set up in the BSP.

timer_init()- This function wraps a set of timer HAL function calls to instantiate and configure a hardware timer. It also sets up a callback for the timer interrupt.

Copy the following code snippet to main.c of your application project.

Code listing 1: main.c file

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


/*******************************************************************************
* Macros
*******************************************************************************/

/* LED blink timer clock value in Hz  */
#define LED_BLINK_TIMER_CLOCK_HZ          (10000)

/* LED blink timer period value */
#define LED_BLINK_TIMER_PERIOD            (9999)


/*******************************************************************************
* Function Prototypes
*******************************************************************************/
void timer_init(void);
static void isr_timer(void *callback_arg, cyhal_timer_event_t event);


/*******************************************************************************
* Global Variables
*******************************************************************************/
bool timer_interrupt_flag = false;
bool led_blink_active_flag = true;

/* Variable for storing character read from terminal */
uint8_t uart_read_value;

/* Timer object used for blinking the LED */
cyhal_timer_t led_blink_timer;


/*******************************************************************************
* Function Name: main
********************************************************************************
* Summary:
* This is the main functionfor CM4 core. It sets up a timer to trigger a 
* periodic interrupt. The main while loop checks for the status of a flag set 
* by the interrupt and toggles an LED at 1Hz to create an LED blinky. The 
* while loop also checks whether the 'Enter' key was pressed and 
* stops/restarts LED blinking.
*
* Parameters:
*  none
*
* Return:
*  int
*
*******************************************************************************/
int main(void)
{
    cy_rslt_t result;

    /* Initialize the device and board peripherals */
    result = cybsp_init();
    
    /* Board init failed. Stop program execution */
    if (result != CY_RSLT_SUCCESS)
    {
        CY_ASSERT(0);
    }

    /* Enable global interrupts */
    __enable_irq();

    /* Initialize retarget-io to use the debug UART port */
    result = cy_retarget_io_init(CYBSP_DEBUG_UART_TX, CYBSP_DEBUG_UART_RX,
                                 CY_RETARGET_IO_BAUDRATE);

    /* retarget-io init failed. Stop program execution */
    if (result != CY_RSLT_SUCCESS)
    {
        CY_ASSERT(0);
    }

    /* Initialize the User LED */
    result = cyhal_gpio_init(CYBSP_USER_LED, CYHAL_GPIO_DIR_OUTPUT, 
                             CYHAL_GPIO_DRIVE_STRONG, CYBSP_LED_STATE_OFF);

    /* GPIO init failed. Stop program execution */
    if (result != CY_RSLT_SUCCESS)
    {
        CY_ASSERT(0);
    }

    /* \x1b[2J\x1b[;H - ANSI ESC sequence for clear screen */
    printf("\x1b[2J\x1b[;H");

    printf("****************** "
           "Hello World! Example "
           "****************** \r\n\n");

    printf("Hello World!!!\r\n\n");
    
    printf("For more projects, "
           "visit our code examples repositories:\r\n\n");

    printf("https://github.com/Infineon/"
           "Code-Examples-for-ModusToolbox-Software\r\n\n");

    /* Initialize timer to toggle the LED */
    timer_init();
 
    printf("Press 'Enter' key to pause or "
           "resume blinking the user LED \r\n\r\n");

    for (;;)
    {
        /* Check if 'Enter' key was pressed */
        if (cyhal_uart_getc(&cy_retarget_io_uart_obj, &uart_read_value, 1) 
             == CY_RSLT_SUCCESS)
        {
            if (uart_read_value == '\r')
            {
                /* Pause LED blinking by stopping the timer */
                if (led_blink_active_flag)
                {
                    cyhal_timer_stop(&led_blink_timer);

                    printf("LED blinking paused \r\n");
                }
                else /* Resume LED blinking by starting the timer */
                {
                    cyhal_timer_start(&led_blink_timer);

                    printf("LED blinking resumed\r\n");
                }

                /* Move cursor to previous line */
                printf("\x1b[1F");

                led_blink_active_flag ^= 1;
            }
        }

        /* Check if timer elapsed (interrupt fired) and toggle the LED */
        if (timer_interrupt_flag)
        {
            /* Clear the flag */
            timer_interrupt_flag = false;

            /* Invert the USER LED state */
            cyhal_gpio_toggle(CYBSP_USER_LED);
        }
    }
}


/*******************************************************************************
* Function Name: timer_init
********************************************************************************
* Summary:
* This function creates and configures a Timer object. The timer ticks 
* continuously and produces a periodic interrupt on every terminal count 
* event. The period is defined by the 'period' and 'compare_value' of the 
* timer configuration structure 'led_blink_timer_cfg'. Without any changes, 
* this application is designed to produce an interrupt every 1 second.
*
* Parameters:
*  none
*
*******************************************************************************/
 void timer_init(void)
 {
    cy_rslt_t result;

    const cyhal_timer_cfg_t led_blink_timer_cfg = 
    {
        .compare_value = 0,                 /* Timer compare value, not used */
        .period = LED_BLINK_TIMER_PERIOD,   /* Defines the timer period */
        .direction = CYHAL_TIMER_DIR_UP,    /* Timer counts up */
        .is_compare = false,                /* Don't use compare mode */
        .is_continuous = true,              /* Run timer indefinitely */
        .value = 0                          /* Initial value of counter */
    };

    /* Initialize the timer object. Does not use input pin ('pin' is NC) and
     * does not use a pre-configured clock source ('clk' is NULL). */
    result = cyhal_timer_init(&led_blink_timer, NC, NULL);

    /* timer init failed. Stop program execution */
    if (result != CY_RSLT_SUCCESS)
    {
        CY_ASSERT(0);
    }

    /* Configure timer period and operation mode such as count direction, 
       duration */
    cyhal_timer_configure(&led_blink_timer, &led_blink_timer_cfg);

    /* Set the frequency of timer's clock source */
    cyhal_timer_set_frequency(&led_blink_timer, LED_BLINK_TIMER_CLOCK_HZ);

    /* Assign the ISR to execute on timer interrupt */
    cyhal_timer_register_callback(&led_blink_timer, isr_timer, NULL);

    /* Set the event on which timer interrupt occurs and enable it */
    cyhal_timer_enable_event(&led_blink_timer, CYHAL_TIMER_IRQ_TERMINAL_COUNT,
                              7, true);

    /* Start the timer with the configured settings */
    cyhal_timer_start(&led_blink_timer);
 }


/*******************************************************************************
* Function Name: isr_timer
********************************************************************************
* Summary:
* This is the interrupt handler function for the timer interrupt.
*
* Parameters:
*    callback_arg    Arguments passed to the interrupt callback
*    event            Timer/counter interrupt triggers
*
*******************************************************************************/
static void isr_timer(void *callback_arg, cyhal_timer_event_t event)
{
    (void) callback_arg;
    (void) event;

    /* Set the interrupt flag and process it from the main while(1) loop */
    timer_interrupt_flag = true;
}

This completes the summary of how the firmware works in the code example. Feel free to explore the source files for a deeper understanding.

This section shows how to build the application.

1. Select the application project in the Project Explorer view.
2. Click Build Application shortcut under the <name> group in the Quick Panel.

   It selects the build configuration from Makefile and compiles/links all projects that constitute the application. By default, Debug configurations are selected.

3. The Console view lists the results of the build operation, as Figure 20 shows.

If you encounter errors, revisit prior steps to ensure that you completed all the required tasks.

This section shows how to program the F-RAM.

ModusToolbox™ software uses the OpenOCD protocol to program and debug applications on F-RAMs. The kit must be running KitProg3. Some kits are shipped with KitProg2 firmware instead of KitProg3. See Programming/debugging using Eclipse IDE for details. The ModusToolbox™ tools package includes the fw-loader command-line tool to switch the KitProg firmware from KitProg2 to KitProg3. See the F-RAM KitProg Firmware Loader section in the Eclipse IDE for ModusToolbox™ user guide for more details.

If you are using a development kit with a built-in programmer connect the board to your computer using the USB cable.

If you are developing on your own hardware, you can use a hardware programmer/debugger; for example, a , , or .

The Console view lists the results of the programming operation, as shown in the following figure.

This section describes how to test your design.

Follow the steps below to observe the output of your design. This note uses Tera Term as the UART terminal emulator to view the results, but you can use any terminal of your choice to view the output.

1. Select the serial port

   Launch Tera Term and select the USB-UART COM port as Figure 23 shows. Note that your COM port number may be different.

   
   

2. Set the baud rate

   Set the baud rate to 115200 under Setup > Serial port as Figure 24 shows.

   
   

3. Reset the device

   Press the reset switch (SW1) on the kit. A message appears on the terminal as Figure 25 shows. The user LED on the kit will start blinking.

   
   

4. Pause/resume LED blinking functionality

   Press the Enter key to pause/resume blinking the LED. When the LED blinking is paused, a corresponding message will be displayed on the terminal as Figure 26 shows.