Latest: FreeRTOS V7.1.1 was released May 1, 2012. View the change history.
Free RTOS logo
FreeRTOS royalty free RTOS RSS feed  Real time embedded FreeRTOS mailing list  
Quick Start Supported MCUs Books & Kits Ecosystem Contact & Support



Last site update May 11 2012

 

nabto

FreeRTOS Connect

Installing Eclipse for use with FreeRTOS.org

Note: This page is very out of date, and describes steps that are no longer required.

This page describes how to install Eclipse for use with the FreeRTOS Eclipse demo projects - resulting in a completely open source embedded cross development environment. The Eclipse Europa version along with CDT V4 and the official remote debugging launch target are utilised which, when compared to their predecessors, are easier to install and include improved functionality.

Julian Friedrich has also been good enough to publish up to date instructions for our German speaking users in the FreeRTOS Interactive forums. Thanks Julian!

The FreeRTOS Eclipse projects are provided pre-configured for interfacing with the required external tools, such as flash programmers, compilers and JTAG interfaces. This page only describes the installation and use of the tools that are common to all the FreeRTOS Eclipse demos. The documentation page specific to each individual demo provides the information on installing any extra tools that are relevant to that demo only - it is there essential to read the documentation for the demo you are using in addition to this page.

Information is also provided on how the FreeRTOS projects have setup the Eclipse CDT version 4. This supplemental information is not required to use the demo projects, but may be of interest to those creating new Eclipse projects.

Installation steps:

  1. Installing the Eclipse development environment
    1. Obtaining the Java run time environment.
    2. Installing the Eclipse C/C++ development environment.
    3. Updating Eclipse for cross development (debugging through JTAG).

  2. Opening and using a FreeRTOS demo project.
    1. Opening a demo project
    2. An important project configuration setting!
    3. Building the project
    4. Programming the microcontroller
    5. Starting a debug server
    6. Starting a debug session
    7. Terminating a debug session

Installing the Eclipse development environment

Java Runtime Environment

Eclipse is primarily written in Java so requires the Java Runtime Environment (JRE) to execute. Most computers will already have the JRE installed. To check if this is the case for your computer, open a command prompt and type "java -version". If the command is not recognised then you will need to download and install the JRE from Sun Microsystems prior to installing Eclipse.

I successfully used Java version 1.6.0_01

Eclipse Framework

Download and install the Eclipse Framework. Select for download the "Eclipse IDE for C/C++ Developers" version that is correct for your host environment as this includes both Eclipse and the C/C++ development plugins (the CDT) as a single download. Installation is simply a matter of unzipping the files into a convenient location - there is no installation procedure as such. Note that I have only tested the setup from a Windows host, and the FreeRTOS demo projects are configured to interface to external Windows tools.

Adding remote debugging capability

The "Eclipse IDE for C/C++ Developers" download provides everything that is required to develop applications that will run on the host computer, but this is not what we want to do. Instead, we want to develop applications that can be executed and debugged on a remote microcontroller target. In order to achieve this we require an additional Eclipse component. To install the additional component:
  1. Start Eclipse by double clicking Eclipse.exe within your Eclipse installation directory.

  2. As Eclipse starts up you will receive a prompt to enter a workspace location. For now, just accept the default location. Eclipse will then open to show a desktop containing five or more circular icons - ignore these for now.

  3. From the 'Help' menu, select 'Software Updates', then 'Find and Install'


    Selecting 'Find and Install' from the 'Help' menu

  4. A Wizard will appear. On the first page select "Search for new features to install", then click next.

  5. The second page shows the update sites that Eclipse will visit to search for a list of available components. By default "Europa Discovery Site" and "The Eclipse Project Updates" will probably be displayed - but the update we require is not available on either of these sites - so instead click the 'New Remote Site' button.

  6. A dialogue box will appear in which you can give the new remote site a name, and enter its URL. Give the new site an appropriate name then enter the following as the URL: http://download.eclipse.org/tools/cdt/releases/europa


    Entering the URL of the remote site having first clicked the "New Remote Site" button

  7. The new remote site just entered will now appear in the list (I called it "Required for JTAG debugging"). Check the box next to the site, and un-check the boxes next to any other sites before clicking "Finish".


    Ensure the box next to the name of the site just entered is checked prior to clicking the "Finish" button

  8. Eclipse will then search for updates and display what it finds in a search results window. In the results window expand the "CDT Optional Features" branch to reveal "Eclipse C/C++ GDB hardware debugging". Ensure this option is selected then click "Next". You will need to accept the license conditions before finishing the wizard.


    Selecting the "Eclipse C/C++ GDB hardware debugging" option

  9. Install the component then restart Eclipse when prompted to do so.

Opening and using a FreeRTOS demo project

Opening a demo project

Eclipse stores information on your Eclipse projects in a central location called a workspace - and it is possible to manage all your projects from a single workspace. However, for distribution convenience each FreeRTOS Eclipse demo uses its own workspace, and each such workspace is included in the directory that contains the relevant demo application code. Having a one to one mapping between Eclipse projects and Workspaces in this manner permits each FreeRTOS demo workspace/project to be distributed with settings that are specific to that demo.

The location of the workspace associated with a FreeRTOS demo is detailed on the documentation page associated with the demo. The workspace can be opened by either selecting the workspace location when Eclipse starts up, or by selecting "Switch Workspace" from the Eclipse "File" menu.

If upon attempting to open a workspace you are presented with a warning message saying the workspace is already open, or not available, then look for a file called .lock within the .metadata directory. If the file exists, delete it, then attempt to open the workspace again.

When you open a demo project workspace you will be presented with a familiar looking development environment that includes two 'perspectives' - a C/C++ perspective and a Debug perspective. You can switch between the perspectives using the buttons in the top right corner of the Eclipse Workbench window - highlighted by the red box in the image below.


The C/C++ perspective

An important project configuration setting!

Before using the project it is important to setup the FreeRTOS_ROOT variable as follows:
  1. Select "Preferences" from the "Window" menu. The Preferences window shown below will appear.
  2. Expand the "General" node in the tree view, then the "Workspace node", and select "Linked Resources" - as highlighted by the red box in the image below.
  3. FreeRTOS_ROOT should be the only entry under "Defined path variables". Select this entry then click "Edit". A dialogue box will appear (again shown in the image below) that permits you to modify the path entry so that it is correct for your system. The path should be to the root of your FreeRTOS installation - the directory that contains the Demo and Source subdirectories.


    Editing the FreeRTOS_ROOT variable

  4. Having set the FreeRTOS_ROOT variable to be correct for your system, click OK to close the dialogue box, then do the same to close the preferences window.
  5. Finally, right click on the RTOSDemo project within the Navigation window (not surprisingly - highlighted by the red box in the image below) and select "Refresh" from the resultant pop up menu. This will permit the navigation window to locate all the files within the project.


    Refreshing the RTOSDemo project within the Navigation window

Building a project

Several different menu items or keystrokes can be used to build a project. For example, right click on the project name within the navigation pane (highlighted by the purple box in the image captioned "The C/C++ perspective above) then click "Build Project" from the resultant pop up window. I prefer to map function keys to perform common operations - these mappings are then saved as part of the workspace. For example, in the RTOSDemo workspace the F7 key can be used to build the project.

The output produced by the compiler will be displayed in the Console tabbed pane - highlighted by the blue box in the image captioned "C/C++ perspective" above - with any errors or warnings also being displayed in the Problems tab - highlighted by the green box in the same image. Clicking on an error or warning in the Problems pane will cause the source line that generated the error/warning to be displayed in the editor pane.

Programming the microcontroller

Eclipse cannot itself program the flash memory of a target microcontroller but does provide a convenient interface for calling whichever tool is being used for this purpose. The actual tool required depends on the microcontroller being used. Information required to download and install the tool relevant to a particular demo is provided on the documentation page specific to that demo.

Each FreeRTOS Eclipse demo project includes a menu item that can be used to program the flash directly from within the Eclipse Workbench. The name of the menu item will depend on the programming tool being used - the image below shows the menu location - in the case depicted OpenOCD was being used as the programming tool.


Programming the microcontroller flash from within the Eclipse IDE

To program the flash memory of your microcontroller:

  1. Ensure your target hardware is connected to your host computer, as described in the documentation for the demo in use.
  2. Select the "Run | External Tools | XYZ Programmer" menu item.
  3. Inspect the output in the Console tab to ensure the programming operation was successful.
NOTE: It might be necessary to stop any debug servers that are running in order to successfully write to the microcontroller flash memory. See the next subsection for more information.

NOTE: The flash programming interface may use an internal TCP/IP connections for communication. If you are running a firewall on your host computer then the TCP/IP communication might be blocked. If this is the case you will have to configure your firewall to permit the connections, then restart the flash programming process.

Starting a debug server from Eclipse

Eclipse provides a graphical interface to the GDB debugger but does not itself know how to communicate with the target hardware. Usually a separate server application is required for this purpose - the server providing an interface between GDB (running on the host computer) and whichever JTAG interface device is being used. The JTAG interface device actually required is dependent on the demo application being used, with more information being provided on the documentation page specific to the demo.

Each FreeRTOS Eclipse demo project includes a menu item that can be used to start the required server application. The name of the menu item will depend on the server being used - the image above shows the menu location - in the case depicted OpenOCD was also being used as the debug interface server.

NOTE: Where the same JTAG interface tool is being used to both program the microcontroller flash and to interface with the GDB server then the server application must be stopped before next attempting to program the flash memory.

To start the debug server:

  1. Select the "Run | External Tools | XYZ Server" menu item.
  2. Inspect the output in the Console tab to ensure the server has started.
NOTE: Debug servers will often use internal TCP/IP connections for communication. If you are running a firewall on your host computer then the TCP/IP communication might be blocked. If this is the case you will have to configure your firewall to permit the connections, then restart the debug server.

Starting an Eclipse debug session

With the microcontroller flash programmed, and the debug interface server started (if required), a debugging session can commence. To start a debug session:
  1. Switch to the debug perspective using the buttons in the top right corner of the Eclipse Workbench.
  2. Select the debug server being used within the Debug window (highlighted by the red box in the diagram below - OpenOCD_ftdi was being used in the case depicted).
  3. Click the "Debug RTOSDemo" speed button - highlighted by the green box in the diagram below.


Starting a debug session

The debug session should start and the application execute as far as, and breaking on, main(). If the application fails to stop at main() then simply kill the debug session, then click the "Debug RTOSDemo" button again.

Controlling an Eclipse debug session

Eclipse provides all the debugging features that would be expected - step into, step over, break points, disassembly views, memory and variable inspection, etc.

The debug session execution can be controlled using the buttons highlighted by the red box in the image below. Note that the buttons might not be active unless the GDB session is select within the Debug pane - as highlighted by the green box in the image below. Alternatively the execution commands can be mapped to key stokes. For example, in the RTOSDemo workspace I have mapped F11 to the Step Into command, and F10 to the Step Over command.


The buttons used to control a debug session

Terminating a debug session

To terminate a debug session:
  1. Select the GDB session from within the Debug window - highlighted by the green box in the image captioned "The buttons used to control a debug session" above.
  2. Click the Terminate button - the button with a red square icon within the red box in the same image above.
To allow the flash memory to be reprogrammed it is also necessary to terminate the GDB server (if one is being used):
  1. Select the server application within the Debug window.
  2. Click the same Terminate button as used to stop the GDB session.









[ Back to the top ]    [ About FreeRTOS ]    [ Sitemap ]    [ ]




Copyright (C) 2004-2010 Richard Barry. Copyright (C) 2010-2012 Real Time Engineers Ltd.
Any and all data, files, source code, html content and documentation included in the FreeRTOSTM distribution or available on this site are the exclusive property of Real Time Engineers Ltd.. See the files license.txt (included in the distribution) and this copyright notice for more information. FreeRTOSTM and FreeRTOS.orgTM are trade marks of Real Time Engineers Ltd.