Using the Eclipse IDE for C and CPP Developers, Howto - kbonset/RIOT GitHub Wiki

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, the msba2 board and the stm32f4discovery board.

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 or stm32f4discovery)
• the RIOT GIT-repository have been cloned, (head over to the quick started guide if you're uncertain how to obtain the RIOT source)
• and the Eclipse IDE for C/C++ Developers is installed/available

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

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 or stm32f4discovery <none>

1. finally we click on Finish

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 stm32f4discovery OR native as value (i.e. the actual used board for development)
5. We Apply the changes and click OK

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 press enter

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 * Please restart eclipse, if Cross ARM GCC is not available

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

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 or stm32f4discovery 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

1. We open a terminal and switch to to the location of the RIOT project

• e.g. cd /home/user/Development/RIOT/examples/hello-world

1. Now we create a configuration .xml file for eclipse by typing:

• make BOARD=stm32f4discovery eclipsesym
  • Note: the set BOARD should be the same as set for the ${RIOT_BOARD} variable in eclipse before.

1. Now we import the generated configuration file in our eclipse project

• We open the project properties, menu Project→Properties
• Then select C/C++ General→Paths and Symbols
  • (optionally) we click Restore Defaults to delete any existing macros and include paths
• We Click on Import Settings... and
• Select the generated eclipsesym.xml located in our application directory and press Finish
• We rebuild the C/C++ index to teach eclipse the new paths and symbols using Project→C/C++ Index→Rebuild

Note: the settings in eclipsesym.xml are specific for the selected project and BOARD.
If you start to develop another project or want to use additional compile time options these 3 steps must be repeated.

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

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.

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

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

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

We create two external tools in order to flash and to initialize the debugger on the board. If they are launched too many times it can sometimes generate conflicts, so we create two tools to clean them.

#####Notes: Some tools need you to be sudo user so Eclipse asks you for your password. To handle this, we need to create/update this file: /etc/sudo.conf

# Path to askpass helper program 
Path askpass /usr/bin/ssh-askpass

( For all next commands details, please read firstly this page Getting started with STM32F[0|3|4]discovery boards )

1. Now back to Eclipse, we click on Run→External Tools→External Tools Configurations...
2. In the new window we create a new configuration for flashing using a speaking Name: (e.g. STM32-Flash)
3. We fill Location: with /usr/bin/sudo
4. Then we can execute the next command as sudo user and so we fill Arguments with
   • -A st-flash write ${workspace_loc:/RIOT}/examples/hello-world/bin/stm32f4discovery/hello-world.hex 0x8000000
5. We can also disable the checkbox Build before launch in the Build tab
6. We Apply the changes and Close the window

1. We click on Run Configurations in the Run tab
2. In the new window we create a new configuration, Name: (e.g. STM32)
3. We can enable the checkbox Disable auto build to avoid compiling each time we run
4. We fill C/C++ Application: with /usr/bin/sudo
5. Then we can execute the next command as sudo user and so in the Arguments tab, we fill Program arguments with
   • -A ${workspace_loc:/RIOT}/dist/tools/pyterm/pyterm.py /dev/ttyUSB1
   • Please note that the serial number of ttyUSB* depends on your configuration
6. We Apply the changes and Close the window

1. We create another tool in External Tools Configurations
2. In the new window we create a new configuration using a speaking Name: (e.g. Stop STM32)
3. We fill Location: with /usr/bin/sudo
4. Then we can execute the next command as sudo user and so we fill Arguments with
   • -A pkill python (Please note that this will also kill all process that use python)
5. We can also disable the checkbox Build before launch in the Build tab
6. We Apply the changes and Close the window

1. We create another tool in External Tools Configurations
2. In the new window we create a new configuration using a speaking Name: (e.g. Init STM32-Debug )
3. We fill Location: with /usr/bin/sudo
4. Then we can execute the next command as sudo user and so we fill Arguments with
   • -A st-util
5. We can also disable the checkbox Build before launch in the Build tab
6. We Apply the changes and Close the window

1. We click on Debug Configurations in the Run tab
2. In the new window we create a new GDB Hardware Debugging configuration, Name: (e.g. STM32-Debug)
3. We can enable the checkbox Disable auto build to avoid compiling each time we run
4. We fill C/C++ Application: with ${workspace_loc:/RIOT}/examples/hello-wolrd/bin/stm32f4discovery/hello-world.elf
5. We provide to Eclipse our debugger in the Debugger tab:

• We fill GDB Command with the path of the ARM GDB e.g. /home/user/Development/toolchains/gcc-arm-none-eabi-4_8-2014q1/bin/arm-none-eabi-gdb
• We specify in Port number 4242 because the "Init STM32-Debug" tool we created just before uses the port 4242

1. We Apply the changes and Close the window

1. We create another tool in External Tools Configurations
2. In the new window we create a new configuration using a speaking Name: (e.g. Clean STM32-Debug)
3. We fill Location: with /usr/bin/sudo
4. Then we can execute the next command as sudo user and so we fill Arguments with
   • -A pkill st-util
5. We can also disable the checkbox Build before launch in the Build tab
6. We Apply the changes and Close the window

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. 6)
• 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.1 and Communicating: 6.1)
  • e.g. ${workspace_loc:/RIOT}/examples/hello-world/bin/msba2/hello-world.hex
• flash the codeimage on the msba2 using Run→External Tools→flash_msba2
• communicate with the msba2 using Run→External Tools→terminal_msba2

1. specific to stm32f4discovery:

• Run
  • flash the codeimage on the stm32f4discovery using Run→External Tools→STM32-Flash
  • Run the compiled code
  • stop running using Run→External Tools→Stop STM32 (You can also click on the red square but note that it can generate conflicts)
• Debug
  • flash the codeimage on the stm32f4discovery using Run→External Tools→STM32-Flash
  • to avoid some conflicts, we advise to stop the past initialization of some debuggers using Run→External Tools→Clean STM32-Debug
  • initialize the debugger using Run→External Tools→Init STM32-Debug
  • Debug the compiled code using Run→Debug History→STM32-Debug (sometimes we need to launch it a few times to make it run)