After completing this how-to you will be ready to begin your own design project.
An Introduction to the Development Process with the Synergy Platform
Once you have all the software running on your system you will probably be ready to begin development. This how to guide will help you get up to speed on developing with the Synergy Platform and will make it easy to create your first project and to begin writing code for your application. The Synergy Software Package (SSP) dramatically simplifies the process of creating an application, so it may be a bit different from previous MCU development environments you are familiar with. We recommend that you take the time to learn the basics of the SSP before diving in and writing code. If you use this how to guide carefully and completely you will be writing code and creating useful applications in record time.
A summary list of what this How to Guide covers is given below. We highly recommend you do these tasks in the order listed.
1: Test out your tool installation and target kit by importing and running a simple LED blinking (Blinky) project. This task won't cover any details of how to create a new project or write code- we want to make sure the tool flow is working first. Link.
2: See the power of the Synergy Software Package (SSP) in action. Take an example design that works with one communication interface (a UART) and quickly change it to another interface (USB) simply by changing the configuration. No rewriting of code required! Link.
3: Learn the basics on creating a project, adding threads and modules, configuring a module, generating code, writing your own code, launching and debugging a program. Links to additional resources and examples are provided if you want to dig into the details of each of these development steps. Link.
4: Suggestions for Next Steps. Link.
1: Test out your tools with Blinky
1.1 Introduction, goals and prerequisites
The goal of this task is to use a simple LED blinking project, Blinky, to test out your tool installation and target kit. (The descriptions and background for the following steps are minimal by design. We want to quickly get through this task and end up with a working system, so you can move on to other tasks, where more details of developing with the SSP can be explained.
Blinky is the “Hello World” of micro-controllers. If the LED blinks you know that:
- The toolchain is setup correctly and builds a working executable image for your chip.
- The debugger has installed with working drivers and is properly connected to the board.
- The board is powered up and its jumper and switch settings are probably correct.
- The microcontroller is alive, the clocks are running, and the memory is initialized.
The Blinky example application used in this task is designed to run the same way on all boards offered by Renesas that hold the Synergy microcontroller. The code in Blinky is completely board independent. It does the work by calling into the BSP (board support package) for the particular board it is running on. This works because:
- Every board has at least one LED connected to a GPIO pin.
- That one LED is always labeled LED1 on the silk screen.
- Every BSP supports an API call that returns a list of LEDs on a board, and their port and pin assignments.
To complete this task you need:
- Windows based PC
- An ISDE (e2 studio or IAR EW for Renesas Synergy- installed in a previous Getting Started Guide step)
- Synergy Software Package (installed in a previous Getting Started Guide step)
- A Synergy board/kit (purchased as described in a previous Getting Started Guide step)
1.2 Create a new project and generate code
The creation and configuration of a Synergy project is the first step in the creation of an application. The base SSP pack includes a pre-written Blinky example application that is simple and works on all Renesas Synergy boards.
Follow these steps to create a Synergy project:
- In the e2 studio or IAR for Renesas Synergy ISDE, click File > New > Synergy C Project
- Assign a name to this new project. Blinky is a good name to use for this task.
- Identify the license file if the license window is empty. The license file for this version of the platform can be found in your <ISDE base directory> starting here: ISDE\internal\projectgen\arm\Licenses\SSP_License_Example_EvalLicense_<rev>.xml.
- The Project Configuration window, as seen in Figure 1 below, shows your selection. Click Next.
Figure 1: Project Configuration Window- part 1
5. Select the SSP version and the name of your board from the Device Selection drop-down lists and click Next.
Figure 2: Project Configuration Window- part 2
6. Select either the Blinky or the Blinky with ThreadX project template and click Finish.
Figure 3: Project Configuration Window- part 3
7. Once the project has been created, the name of the project will show up in the Project Explorer window of the ISDE. Now press the Generate Project Content button in the top right corner of the Synergy Project Editor window to generate your board specific files.
Figure 4: Generate Project Content
Your new project is now created, configured, and ready to build.
Blinky example code (Optional details)
The Blinky application code is stored in the hal_entry.c file (if you selected the Blinky project template) or the blinky_thread_entry.c file (if you selected the Blinky with ThreadX project template). These files are generated by the ISDE and are located in the project's src/ folder, available for view in the upper left Project Explorer window. (No need to open these folders and view the source files now. You will have a chance to view source later in this article).
The application performs the following steps:
1) Get the LED information for the selected board by calling the BSP HAL function R_BSP_LedsGet.
2) Define the output level HIGH for the GPIO pins controlling the LEDs for the selected board.
3) Get the selected system clock speed and scale down the clock, so the LED toggling can be observed.
4) Toggle the LED by writing to the GPIO pin with g_ioport.p_api->pinWrite()
1.3 Build the Blinky project
Select your new project in the Project Explorer window and build it.
There are three ways to build a project:
a. Click on Project in the menu bar and select Build Project.
b. Click on the hammer icon.
c. Right-click on the project and select Build Project.
Figure 5: Build the Project
Once the build is complete a message is displayed in the build Console window that displays the final image file name
and section sizes in that image.
Figure 6: Typical Blinky Build Report
You project has been built and is available to download to the MCU on your target kit and to debug.
1.4 Download and Debug the Blinky project
To download and debug the project on a board, you need:
- The board to be connected to the ISDE
- The debugger to be configured to communicate with the board
- The application to be programmed into the microcontroller
Applications run from the internal flash memory of your microcontroller. To run or debug the application, the application must first be programmed to the microcontroller’s flash memory. There are two ways to do this:
- JTAG debugger
- Built-in boot-loader via UART or USB
Some boards have an on-board JTAG debugger and others require an external JTAG debugger connected to a header on the board. Refer to your board’s user manual to learn how to connect the JTAG debugger to your ISDE.
Download and debug step by step guide
1. Configure the debugger for your project by clicking Run > Debug Configurations or by selecting the drop-down menu next to the bug icon,
and Selecting Debug Configurations. In either case, the window shown in Figure 7 below will open.
Figure 7: Debug Configuration Selection
2. Select your debugger configuration in the window (Blinky Debug in the above example). If it is not visible then it must be created by clicking the New icon as shown in the top left corner of the window in the above example. Once selected, the Debug Configuration window displays the detailed debug configuration settings for your Blinky project in the right side of the window as shown in Figure 8 below.
3. Press Debug to begin debugging the application.
Figure 8: Select Debug Configurations and Enter Debug Mode
About the debug process (optional details)
In debug mode, the ISDE executes the following tasks:
1. Downloading the application image to the microcontroller and programming the image to the internal flash
2. Setting a breakpoint at main().
3. Setting the stack pointer register to the stack.
4. Loading the program counter register with the address of the reset vector.
5. Displaying the startup code where the program counter points to.
1.5 Run Blinky in Debug Mode
Once in Debug mode, click Run > Resume or click on the Play icon twice.
The LED on the board marked LED1 should now be blinking. You have proven out your tool installation, tool flow and your target kit. You are now ready to try a more advanced project- one that shows some of the powerful capabilities of the SSP.
2: The power of the SSP in action
Describe example here.
3: An overview of the SSP
3.1 Creating a project
3.2 Adding a new thread and a new module
3.3 Configuring a module
3.4 Adding your own code
3.5 Launching and debugging a program
Links to more information.
Much of the low level work in setting up drivers and defining properties is not done in user code by is done automatically by the SSP. All you need to do is select the various high level functions you want to add to your project, configure them with easy pull down menus and then have the SSP generate the code used to implement you configuration selections.
3: Adding a New Thread and a New Module
All modules including the drivers are added and configured in the Threads tab.
The HAL/Common modules in the Threads list on the left of the below figure are provided by default for an RTOS-less system. It contains 4 driver modules used by all Synergy projects:
- g_cgc: Clock Generation Circuit
- g_fmi: Flash Microcontroller Information
- g_elc: Event Link Controller
- g_ioport: I/O Ports
Figure 1: HAL/Common Modules are Shown in the SSP Threads Tab
To add a new thread to a project, click New Thread in the Threads list. Adding a thread for the first time will also add the ThreadX RTOS.
Figure 2: Adding a New Thread
To add a new module, first select a thread from the Threads list. The name of that thread will be shown on the right. Then click on New Stack and select the driver from the selection menu that shows up. The new stack will show up in the HAL/Common Stacks region.
Figure 3: Adding a New Module
Configuring a Module
Configuring modules in the Synergy Platform is simple. First, examine the light green area shown in the image below:
Figure 4: Configuring a New Module
The light green area shows where the modules are added to the project. This is like what we saw previously. When a developer clicks on a module in the HAL/Common Stacks window, that module can be configured in the properties tab shown in the light red region in the lower left. A developer can simply find the property name that needs to be configured in the module and then change the value for the property.
The Properties Pane
The Properties Pane contains several regions that are important for configuring modules. A close-up can be seen in the image below:
Figure 6: Properties Pane Organization
The Common section has settings for the whole module e.g. Parameter Checking. All modules have this section.
The Module section is where developers configure module specific settings. These settings are for this instance of the module. There can be many instances of a module included in a project. Module instances are identified by the module name. In this case, we are looking at the g_timer instance on the r_gpt timer module.
Module configuration is based on the configuration option structure for that module. An example configuration structure for the Timer Driver API configuration settings can be seen below. As you can see, the configuration structure members directly map to the property entries in the properties pane.
Figure 7: Example Configuration Settings
Once a module has been configured, clicking on the “Generate Project Content” button creates a configuration output. This output is also created every time a developer builds the project.
Output is saved in the src/synergy_gen folder. Files in this folder is updated every time you hit “Generate Project Content” or build the project. Therefore, any changes you make in this folder will be overwritten.
Control: is internal to the SSP. So, there is no configuration for it.
Configuration: contains the settings needed to setup the Module Properties pane. As you can see the exact same setting specified by the developer show up here for the Timer Driver on g_gpt.
Instance: is the collection of all these structures in one place so the developer can easily access them. Developers always use the members of instance to use the module’s API functions. In this example the instance name is g_timer.
Using the Configurator Output
The SSP APIs are accessed and used thru the instance structure. The instance name is what the developer specifies in the Name value in the Properties Pane. Developers can use e2 Studio’s autocomplete feature to easily access the instance and use it in their code. In upper right, the timer instance structure is shown. The structure contains three pointers to control, config, and the modules API. The driver module name is g_timer.
Where is the Configuration Stored?
The project and module configurations are stored in several different files as can be seen in the image below:
- The configuration.xml file contains which modules are used in the project and their configurations. These settings come from the choices a developer makes within the Synergy Configuration Tool.
- The pin configuration is stored in a .pincfg file. This file contains pin settings for the board used in the project.
- There can be multiple pin configurations depending on the project requirements. One good example is a low power pin configuration where the project goes into low power state and may want to configure pins differently.
- Another type of file where pins setting are store is the Excel file. This is a .CSV file and contains the pins setting information in an easy to access format.
Additional Resources and Suggestions
In this step we show you how to install the tools needed to develop projects targeting the Renesas Synergy Platform. By following this step by step guide we will have your system up and running in less than 30 minutes. Just click on this link to go to the How to guide that shows each step needed to complete this task. Link