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. Start the eclipse IDE and switch to the workbench
2. Now 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.

• for native we select the main directory of RIOT and choose the Linux GCC
• for msba2 we select the main directory of RIOT and choose the <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:, i.e. 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 the details we click Next > again presenting us the Review Licenses view

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

7. Setting up the the 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. In the new view 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 build the set project by clicking Project→Build All

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 now built executable relative from the RIOT main folder,

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

1. We hit 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 flshing/communicating parameters for our specific project (msba2)

Flashing and connecting 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 generating two executables in ./tools/bin

1. lpc2k_pgm used to flash the built codeimage msba2 board
2. pseudoterm used to communicate with the msba2 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"

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: of the flash.sh script and select it
3. Then we add the device path, e.g. /dev/ttyUSB0

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

1. and the path to the codeimage to the Arguments:

• 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: of the terminal.sh script and select it
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 ist 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 board to build for using the RIOT_BOARD variable

• e.g. native

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

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

1. for msba2:

• setup the flashing and the communication Arguments:
  • 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 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!