How to create a new Synergy project

Overview

This guide will help you create your first project that can be run on Renesas Synergy boards using integrated system development environment e2studio. The steps described below are usually followed every time a new project for Synergy is created from scratch.

Goal

After completing this how-to guide you will be able to create a basic Synergy project that is ready to be compiled and run on Renesas Synergy board.

Steps

Initial project configuration

Begin by opening e2studio ISDE and pointing to workspace directory of your choice.

Navigate to File -> New -> Synergy Project.

Enter desired project name and select the toolset (GCC ARM is default).

On the next page, you're required to select your target board. Bear in mind that projects created for a specific development or starter kit will usually not run on a different board. The device field is filled automatically when a non-custom board is selected.

Additional toolchain options are also available. For GCC, it is recommended to leave these unchanged. In case where fields are empty, please make sure you have correctly installed and registered GCC ARM Embedded toolchain (offered during installation of e2studio).

On the final tab, you're able to select project template as a foundation for your code. For most applications, board-specific Board Support Package is suitable. Should you choose to download additional project examples from Synergy Gallery, they'll be found on this list as well.

Using Synergy Project Configurator

The initial setup created basic directory structure for your project. The Synergy Project Configurator should be opened automatically:

Summary screen breaks down selected software components as well as target board and device.

BSP tab allows you to replace board support package with an alternative version for different board. Remember that some components included in the project may not be compatible with the new target board (eg. when moving graphics LCD project form S7 onto S3 board). Selecting Properties tab in the bottom half of the screen will allow you to adjust hardware behavior. When using RTOS (HAL/Common isn't the only thread in Threads tab), set RTOS being used to ThreadX to prevent errors in configuration.

Clocks screen provides detailed configuration for clock generation circuit module. For most projects, these settings should be left at their default values.

Pins pane is used to create pin configuration file. Most connections on the chip package can be used for multiple peripherals. When using external peripherals such as graphic LCD or pushbutton switches, pins have to be connected and set to appropriate characteristics (direction, pull up, drive capacity and output level) in order to be functional and addressable from within the source code. Note that JTAG pins should always stay connected during development, as disconnecting them will leave the board inaccessible by the programmer and debugger.

Threads tab is the main place used for configuring your project contents. Here, you can create additional threads (thus, enabling ThreadX RTOS) and populate them with drivers, frameworks and RTOS objects (such as queues or event flags). Each item has it's own settings that can be adjusted on the Properties tab in the panel visible on the bottom half of the screen. Adding components to the project also enables them on the Components tab. Some properties may also affect settings in the ICU tab.

ICU section allows you to adjust interrupt controller unit to respond to certain system hardware events. Same options are available on Threads tab when configuring properties for a given driver or framework (only if they offer interrupting capabilities).

Components pane lists all the modules available from the installed Synergy Support Package. Installing more than one version of SSP will enable you to choose between two versions of a given module. Selection boxes are used to include the features in the project but it's also done automatically, when populating Modules section on Threads tab with the same entires.

After project has been configured Generate Project Content button has to be pressed in order to export project setup into compilable C code.

Understanding directory structure of the Synergy project

Project contents are grouped into different folders, depending on their type and purpose:

src folder contains user code for execution once the system has booted up and is running

synergy_gen folder contains files generated by Synergy Project Configurator and they should not be edited as any changes will be overwritten with the configurator output. This source code usually defines API instances for the modules selected as well as interrupt function prototypes.

hal_entry.c file features hal_entry function that is called at the end of start-up procedure. It is only relevant in non-RTOS projects (only one thread: HAL/Common in the Threads tab in the configurator) as the function is not called during ThreadX start-up.

new_thread_entry.c and any other _entry.c file holds user code executed inside the threads that were created using the configurator. Similarly to hal_entry file, the function will exit once it reaches the end and therefore for continuous execution, it is advised to place the code in a permanent loop inside that function.

synergy directory stores complete board support package for the target device as well as selected SSP components (that includes HAL drivers and frameworks). Changes in the Synergy Configurator usually reflect on the contents of this folder.

script holds the linker script file used to pre-configure the memory space on the target device. This file is always the same for a given board.

synergy_cfg folder contains low-level board setup such as pin, interrupt and clock configuration files. These are also generated by the configurator and shouldn't be edited manually.

configuration.xml is the Synergy Configurator file. It's explained in detail in the previous section.

.pincfg file is used by the ISDE to generate the actual pin setup file (bsp_pin_cfg.h). Every Synergy project is created with deafult pin settings that can be altered using Synergy Configurator.

.launch and .jlink files store debug and runtime configuration of the project and in most cases, they shouldn't be edited by user.

What's Next

Now, you should able to create and edit Synergy projects. Feel free to revisit this guide to refresh your understanding of the e2studio ISDE.

You're now ready to jump into project development. Why not start with Threaded Blinky project as an introduction to using real-time operating system on Renesas Synergy embedded platform. You can find an article on it here: Running Threaded Blinky on the Synergy Platform