Installing Eclipse for use with FreeRTOS.org

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

I successfully used Java version 1.6.0_01

Eclipse Framework

Adding remote debugging capability

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

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!

Building a 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

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: 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

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.

Starting an Eclipse 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

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

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.

1. Select the server application within the Debug window.
2. Click the same Terminate button as used to stop the GDB session.