Using the Eclipse IDE for C and CPP Developers, Howto

This brief howto is meant as a quick guidance to start developing using RIOT-OS and eclipse. It should give at least a hint how to start developing with eclipse. Right now this howto is focused on the native and the msba2 board.

Prerequisites

Before we start it is assumed that:

• the OS used for development is equipped with a working and somehow current GCC toolchain (native)
• the OS used for development is equipped with the recommended or somehow current gcc-arm-none-eabi cross toolchain (msba2)
• the RIOT GIT-repository have been cloned, (head over to the getting started guide if you're uncertain how to obtain the RIOT source)
• and the Eclipse IDE for C/C++ Developers is installed/available

Please note, for this tutorial:

• we use the hello-world example
• we use the Linaro Toolchain Binaries GCC in version 4.8 for ARM cross compillation

1. Setup the eclipse IDE for RIOT development

1. We start the eclipse IDE and switch to the workbench
2. There we create a new Makefile project with existing code by clicking on: File→New→Makefile Project with Existing Code
3. The Toolchain and indexer Settings window shows up asking for the directory containing the source and the Makefile
4. we select the main directory of RIOT and choose:

• for native the Linux GCC
• for msba2 <none>

1. finally we click on Finish

2. Preparing variables

1. We select the RIOT project in the Project explorer and click the Project→Properties menu
2. There we select Build Variables and click on Add... opening the Define a New Variable window
3. Using a speaking Variable Name:, e.g. RIOT_PROJECT, we set the Value: to examples/hello-world
4. We create another variable, RIOT_BOARD, with msba2 OR native as value (i.e. the actual used board for development)
5. We Apply the changes and click OK

3. Preparing ARM cross compilation

1. Installing GNU ARM eclipse Plug-ins

2. We click on Help→Install New Software, which opens an Install window

3. In the Work with: field we type http://gnuarmeclipse.sourceforge.net/updates and click Add...

4. We select GNU ARM C/C++ Cross Development Tools and click Next > presenting us the Install details

5. After checking them we click Next >, presenting us the Review Licenses view

6. To install the plug-ins we accept the Eclipse Foundation Software User Agreement(s) and click Finish

7. Setting up the the ARM cross toolchain

8. We select the RIOT project in the Project explorer and click the Project→Properties menu

9. In the new Properties for RIOT window we select Tool Chain Editor

10. There we uncheck the Display compatible toolchains only

11. and select the Cross ARM GCC from the Current toolchain: dropdown menu

12. We click on Settings and set the Global path to the bin folder of the toolchain * e.g. /home/user/Development/toolchains/gcc-arm-none-eabi-4_8-2014q1/bin

13. Then we Apply the changes and click OK

4. Setup our environment

1. We select the RIOT project in the Project explorer and click the Project→Properties menu
2. In the presented Properties for RIOT window select C/C++ Build
3. we uncheck Use default build command,
4. and add the previously specified RIOT_BOARD variable to our build

• e.g. ${cross_make} BOARD=${RIOT_BOARD} (for msba2 and further ARM boards)
• e.g. make BOARD=${RIOT_BOARD} (for native)

1. Then we add the project path to the Build Location using the RIOT_PROJECT variable

• e.g. ${workspace_loc:/RIOT}/${RIOT_PROJECT}

1. For debugging on native we append all-debug as build command additionally

• i.e. make BOARD=${RIOT_BOARD} all-debug

1. Then we Apply the changes and click OK

After setting the project properties we hit Project→Build All to build the project

5. Setting Run/Debug parameters for our specific project (native)

1. We click on Run→Run Configurations... which opens the Run Configurations window
2. There we add a new launch configuration (if not already present)
3. Now we adjust the C/C++ application: path to the just built executable, relative from the RIOT main folder:

• i.e. examples/hello-world/bin/native/hello-world.elf

1. We click the Apply button and if everything went right,
2. hitting the Run button executes our built project

Repeat the setup for Debug Configurations if not applied automatically by Eclipse, to enable debugging.

6. Setting flashing/communicating parameters for our specific project (msba2)

Flashing and connecting with the msba2 requires to build the ./RIOT/boards/msba2-common/tools. So we fire up a terminal, switch to the ./tools folder and execute make compiling two executables in ./tools/bin

1. lpc2k_pgm used to flash the built codeimage
2. pseudoterm used to communicate with the board

We change to ./RIOT/boards/msba2-common/tools/bin and create two shell scripts:

• we type touch flash.sh && chmod a+x flash.sh
• and touch terminal.sh && chmod a+x terminal.sh

Using a text editor we open the flash.sh file and add:

#!/bin/bash
TOOLPARAMETER="lpc2k_pgm $1 $2"
TOOLDIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
xterm -e "sudo $TOOLDIR/$TOOLPARAMETER"

Then we open the terminal.sh file and add:

#!/bin/bash
TOOLPARAMETER="pseudoterm $1"
TOOLDIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
xterm -e "sudo $TOOLDIR/$TOOLPARAMETER"

Now back to eclipse, we click on Run→External Tools→External Tools Configurations...

Flashing:

1. In the new window we create a new configuration for flashing using a speaking Name: (e.g. flash_msba2)
2. We click on Browse File System... for the Location: and select the flash.sh script
3. Then we add the device path to the Arguments:, e.g. /dev/ttyUSB0

• it is assumed here that the msba2 board is connected and recognized as /dev/ttyUSB0

1. and also the path to the codeimage

• e.g. ${workspace_loc:/RIOT}/examples/hello-world/bin/msba2/hello-world.hex

1. We Apply the changes and Close the window

Communicating:

1. we create a further configuration for communication using a speaking Name: (e.g. terminal_msba2)
2. We click on Browse File System... for the Location: and select the terminal.sh script
3. Then we add the device path to the Arguments:

• e.g. /dev/ttyUSB0

1. We Apply the changes and Close the window

Now we go to Run→External Tools→Organize Favorites..., select our created configurations and hit OK

Run→External Tools→flash_msba2 will open an xterm starting the flash process using its Arguments:

1. as device path, e.g. /dev/ttyUSB0
2. as the codeimage to flash, e.g. ${workspace_loc:/RIOT}/examples/hello-world/bin/msba2/hello-world.hex

Run→External Tools→terminal_msba2 will open an xterm connecting the msba2 using its Arguments:

1. as device path, e.g. /dev/ttyUSB0

7. Final words

Now we can:

1. select a project to be build using the RIOT_PROJECT variable

• e.g. examples/hello-world

1. select a target board using the RIOT_BOARD variable

• e.g. native

1. compile the desired project hitting Project→Build All
2. specific to native:

• setup the C/C++ application: path (cf. 5.3)
• Run the compiled code
• Debug the compiled code

1. specific to msba2:

• setup the Arguments: for flashing and communication
  • e.g. /dev/ttyUSB0 for the connected device (cf. Flashing: 6.3 and Communicating: 6.3)
  • e.g. ${workspace_loc:/RIOT}/examples/hello-world/bin/msba2/hello-world.hex (cf. Flashing: 6.4)
• flash the codeimage on the msba2 using Run→External Tools→flash_msba2
• communicate with the msba2 using Run→External Tools→terminal_msba2

This litte howto ends here for now. I hope it was somehow helpful. So, Happy RIOT-ing!