Running Amazon FreeRTOS Code Examples - KBA228845

Version 6

    Version: **


    This knowledge base article applies to the code examples (CEs) available in the Cypress GitHub repository for ModusToolbox™ Amazon FreeRTOS SDK.


    In addition to the demo applications bundled with Amazon FreeRTOS, Cypress provides code examples that demonstrate the unique features of PSoC 6 MCU such as CapSense®. You can find these code examples in the Cypress GitHub repository.


    These code examples support three build flows - ModusToolbox IDE, ModusToolbox Command Line Interface (CLI), and CMake.


    Software Requirements





    Required for cloning Amazon FreeRTOS and code examples


    Required to run the code examples using either the ModusToolbox IDE or the CLI.

    Cypress Programmer

    Required to program the target board if you are using CMake to build the code example


    Required if you are using CMake to build the code example


    Required if you are using CMake with Windows


    Setting Up Your Hardware 


    First, ensure that your kit is programmed with the latest KitProg3 firmware. Do the following to update the KitProg3 firmware. See the firmware-loader page for detailed instructions.


    1. Download the latest firmware-loader tool. The firmware-loader tool is also installed with the ModusToolbox IDE at the location <install_dir>/ModusToolbox/tools_x.x/fw-loader-x.x.


    2. Connect the KitProg USB connector on the kit to your computer.


    3. Run the following command from the directory where the firmware-loader binary is located.

    fw-loader --update-kp3


    Note: On Linux, you must run the udev_rules\ script before the first run of the fw-loader.


    4. Ensure that the kit is in KitProg3 mode to program it from the ModusToolbox IDE. The amber color STATUS LED (LED2) should be steady ON or blinking at 1-Hz rate. If not, press the SW3 MODE SELECT button to switch the mode to KitProg3.



    Cloning Amazon FreeRTOS and Code Example


    1. Clone Amazon FreeRTOS from GitHub and checkout the latest release using its tag. See the file in the code example to find out the release that the code example supports. The following command also clones all the submodules:


    git clone -b <release-tag> --recurse-submodules


        • <amazon-freertos> refers to the path of the Amazon FreeRTOS folder in your computer.
        • The maximum length of a file path on Microsoft Windows is 260 characters. Lengthy Amazon FreeRTOS directory paths can cause build failures. Make sure that the path to the <amazon-freertos> directory is fewer than 98 characters.


    2. Go to <amazon-freertos>/projects/cypress folder.


    3. Clone the code example along with the submodules.

    git clone <repo-url> --recurse-submodules

                For example, run the following command to clone afr-example-capsense.

    git clone --recurse-submodules


    4. Connect the board to your PC using the provided USB cable through the USB connector.


    5. Open a terminal program and select the KitProg3 COM port. Set the serial port parameters to 8N1 and 115200 baud.


    Configuring Amazon FreeRTOS


    1. Before you begin, you must configure AWS IoT to connect your device to the AWS Cloud.

    You can find the instructions to set up AWS IoT connection in the “First Steps” section of the Amazon FreeRTOS user guide. You must use only the version of Amazon FreeRTOS from Cypress’ GitHub repository to work with Cypress kits and ignore the instructions given at Amazon FreeRTOS user guide for downloading it from elsewhere. Some code examples may not require connecting to AWS IoT. In that case, you can skip this step. See the file in the code example to know whether the code example requires AWS IoT setup.


    2. Once you have configured AWS IoT, you need to configure Amazon FreeRTOS. The exact configuration may differ from one code example to another. See the file in the code example for instructions. In general, you need to configure the following. These files are located under <amazon-freertos>/demos/include directory.

      • Wi-Fi settings (SSID, password) and MQTT endpoint in aws_clientcredential.h
      • Client certificate and private key in aws_clientcredential_keys.h


    Running the Code Example


    Using ModusToolbox IDE


    1. Open the ModusToolbox IDE and choose or create a workspace.

    2. Go to File > Import.

    3. In the window that appears, expand General, choose Existing Projects into Workspace, and then click Next

    4. In Select root directory, click Browse and choose the <amazon-freertos>/projects/cypress/<code_example_directory>. The <code_example> project should be selected by default. Click Finish to import the project into your workspace.

    5. Click the project in the Project Explorer. This makes the build and program actions appear in the Quick Panel.

    6. In the Quick Panel, click <code_example> Program (KitProg3). This action builds the project and programs the kit.

    7. Follow the instructions in the code example to observe the output. You may need to establish a serial terminal connection to observe the UART output if the code example supports it.


    Using a Different Target with ModusToolbox IDE


    The target board is specified through the TARGET variable in the Makefile of the code example. Do the following to use a different target with the IDE:


    1. Delete all the launch configuration files (*.launch) under <amazon-freertos/projects/cypress/<code_example_directory>/.mtbLaunchConfigs directory.

    2. Update the TARGET variable in the Makefile with the new target. For example, CY8CKIT-062-WIFI-BT.

    Note: The target name in the Makefile uses hyphen instead of underscore as the separator.

    3. In the Project Explorer of the IDE, right-click the code example and choose Build Targets > Create.

    4. In the window that appears, enter eclipse under Target Name and click OK.


    The build target appears under the project as shown below.

    5. Double-click eclipse under Build Targets and wait until the launch configuration files for the new target are generated. You can see the status in the Build Console window.

    6. To program the new target, click the project in the Project Explorer and <code_example> Program (KitProg3) from the Quick Panel.


    Using Command Line Interface (CLI)


    The ModusToolbox Command Line Interface is a GNU make-based build system that is used to perform application builds. This section explains how to run the code example using the CLI. See Running ModusToolbox from the Command Line for details. The ModusToolbox IDE uses the same build system. Therefore, switching from CLI to IDE and back is fully supported.


    1. Open a CLI terminal and navigate to the CE directory.

    2. Run the make program command to build and program the application using the default toolchain to the default target. You can specify a target and toolchain manually:

    make program TARGET=<BSP> TOOLCHAIN=<toolchain>

    Example: make program TARGET=CY8CKIT-062-WIFI-BT TOOLCHAIN=GCC_ARM

    Note: The target name in the make command uses hyphen as the separator.

    3. Follow the instructions given in the code example to observe the output. You may need to establish a serial terminal connection to observe the UART output if the code example supports it.


    Using CMake


    1. Create a build folder under <amazon-freertos> directory. For example, <amazon-freertos>/build/cmake_build.

    2. Run the following command from the build folder. Replace the board name and the code example name with your board and the code example that you want to run.

    cmake -G Ninja -S ../.. -B . -DVENDOR=cypress -DCOMPILER=arm-gcc -DBOARD=CY8CPROTO_062_4343W -DAPP=projects/cypress/afr-example-wifi-scan


      • The board name in the cmake command uses underscore as the separator.
      • The above command generates configuration for the build tool Ninja. You can generate for other build tools supported by CMake such as “Unix Makefiles”.

    3. Once CMake has generated the configuration, run the following command:

    cmake --build .

    Note: The current directory is specified using a dot at the end of the command.

    4. Use Cypress Programmer to program the *.elf file generated under <amazon-freertos>/build/cmake_build directory.

    5. Follow the instructions given in the code example to observe the output. You may need to establish a serial terminal connection to observe the UART output if the code example supports it.