Building and debugging Atmel AVR (Arduino-based) project using Eclipse IDE+PlatformIO

eclipse_platformio_iconI received a lot of feedbacks after PlatformIO had been released. Some people have been asking me the interesting questions, such as:

Also I’ve received valuable answers and wishes  from the “LinkedIn Professionals” (here and here). Most of them like to work with an IDE and preferably Eclipse IDE.   As PlatformIO is a console tool with rich commands interface it can work with different IDEs as the “builder, uploader & debugger”.

Today I want to explain how we can build and debug Atmel AVR (Arduino) based project using Eclipse IDE + PlatformIO.


UPDATE: I’m glad to announce that you don’t need to perform these manual steps to integrate PlatformIO with Eclipse. PlatformIO 2.0 has been released with a lot of new features and has built-in project generator for the popular IDEs, including Eclipse. More details here…


Installing Atmel AVR platform with PlatformIO

Firstly we should install Atmel AVR platform. And we won’t build anything from sources because PlatformIO has already pre-built different development platforms for Mac, Linux and Windows OS. (If you haven’t PlatformIO installed in your system yet – here you can read how to do it).

Then using PlatformIO please search for an embedded platform for Atmel AVR micro-controllers:

As we can see, the name of development platform in PlatformIO repository is “atmelavr“. So, install it:

Check “atmelavr” packages when downloading and unpacking process will be finished:

Installing Eclipse IDE

The installation process of Eclipse IDE is easy and simple: “download, unpack and open it!”. Please go to Eclipse Downloads page and download for your OS “Eclipse IDE for C/C++ Developers”. Unpack it and run.

Setup New Project

In Eclipse IDE: navigate to “File → New → C++ Project“,  enter “Project name“,  set “Project type” to “Executable → Empty Project”, leave “Toolchains” by default in your OS (it doesn’t matter because Eclipse will use PlatformIO with the own pre-built toolchains) and press “Next → Next → Finish” :

Eclipse - C++ Project - Empty Project

The second step is to configure project source code builder. PlatformIO has own builder and you don’t need to install additional tools (like, Makefile or etc). PlatformIO Source Code Builder works perfectly in the popular OS: Mac OS X, Linux and Windows!

In Eclipse IDE make right click on the created project (“Project Explorer“) : “Properties → C/C++ Build and go to “Builder Settings” tab:

  1. Uncheck “Use default build command” and set “Build command” to platformio -f -c eclipse
  2. Uncheck “Generate Makefiles automatically“.
  3. Set “Build directory” to  ${workspace_loc:/***_YOUR_PROJECT_NAME_***}

On this pane please follow to “Behaviour” tab:

  1. Set “Build (incremental build)” to run
  2. Set “Clean” to  run --target clean

Eclipse - PlatformIO - Source Code Builder #2

Then setup for the project “Includes“: “C/C++ General → Paths and Symbols Add… . And add 2 directories:

  1. Set “Directory” to  ${HOME}/.platformio/packages/toolchain-atmelavr/avr/include and checkAdd to all languages“.
  2. Set “Directory” to  ${HOME}/.platformio/packages/framework-arduinoavr/cores/arduino and checkAdd to all languages“.

If you want to use native AVR programming, you have to specify additional preprocessor symbol (the next tab “#Symbols” in this pane) about your MCU. For example, an Arduino Uno is based on the ATmega328 MCU. In this case I will add new Symbol  __AVR_ATmega328__  with empty Value for “All languages”.

Eclipse Setup Project Symbols

 My first “Blink” program

The simple “Blink” program will consist from 2 files:

  1. Main “C” source file named main.cpp  that must be located in the  src directory.
    In Eclipse IDE make right click on the created project (“Project Explorer“) : “New → Folder and set “Folder name” to  src  and press “Finish“. Then make again right click on the newly created   src  folder: “New → File” and set “File name” to  main.cpp  and copy the source code which is described below to it.
  2.  Project Configuration File  platformio.ini
    In Eclipse IDE make right click on the created project (“Project Explorer“) : “New → File” and set “File name” to  platformio.ini and copy the source code which is described below to it.

The full list with supported boards is located here.

Now, you can build project and then upload firmware to your device with shortcut Cmd + B  (Mac) or   Ctrl + B (Windows/Linux) or “Menu: Project → Build Project:

NOTICE! If you received this message: “Error: Program “platformio” not found in PATH”, then you need to update Eclipse $PATH variable. In Eclipse IDE make right click on the created project (“Project Explorer“) : “Properties → C/C++ Build → Environment → PATH → Edit” and set to /usr/local/bin:/bin:/usr/bin:/usr/sbin:/sbin .

Hardware debugging

If you want to debug your application, you have to install “C/C++ GDB Hardware Debugging” plugin which allows GDB to do hardware debugging. For this open “Install New Software…” from Eclipse menu, then select “–All Available Sites–” and search with “gdb” query. Put checkbox near plugin and install it pressing “Next” button. Restart Eclipse IDE.

The whole debugging process consists of two parts:

  1. In the first part we should customise a hardware debugging tool that will communicate from the one side with our hardware device (via JTAG interface or etc.), and from another with GDB over TCP/IP protocol by some port.
    For example, if you have JTAG ICE tool you can use avarice  AVaRICE Program. But if you haven’t (like me), you can use simulavr  a simulator for the Atmel AVR family of micro controllers. All these programs are supplied  with PlatformIO and located in ${HOME}/.platformio/packages/toolchain-atmelavr/bin folder.
  2. In the second part we should setup GDB tool:
    • specify our JTAG device with TCP/IP data from #1 step
    • allow to load symbols at startup from our firmware file
    • setup runtime options.

All detailed information about these parts you can find here.

Hardware debugging with GDB + SimulAVR

As I just said, I will use simulator for  atmega16 device.

  1. Run  simulavr via “External Tools” menu:
    • NameStart SimulAVR as Atmega16
    • Location${HOME}/.platformio/packages/toolchain-atmelavr/bin/simulavr
    • Working Directory${workspace_loc}
    • Arguments--gdbserver --port 4242 --device atmega16

    eclipse_externaltool_simulavrThen you should see similar result:
    eclipse_externaltool_simulavr_console
    P.S: If you decided to use avarice , please read avarice manual and setup:

    • NameStart AVaRICE
    • Location${HOME}/.platformio/packages/toolchain-atmelavr/bin/avarice
    • Working Directory${workspace_loc}
    • Arguments--program --file ${workspace_loc:/blink/.pioenvs/arduino_uno/firmware.elf} --part _DEVICE_NAME_HERE_ --jtag _PORT_HERE_ :4242

     

  2. SetupDebugging Configuration“:
    “Main” TAB:

    • Namearduino_pro5 Hardware Debugging
    • C/C++ Application${workspace_loc:/blink/.pioenvs/arduino_uno/firmware.elf}

    eclipse_debugging_conf_main
    “Debugger” TAB:

    • GDB Command/Users/ikravets/.platformio/packages/toolchain-atmelavr/bin/avr-gdb
    • CheckUse remote target
    • JTAG DeviceGeneric TCP/IP
    • Host name or IP addresslocalhost
    • Port number4242

    eclipse_debugging_conf_debugger
    “Startup” TAB:

    • CheckLoad symbols
    • Use file${workspace_loc:/blink/.pioenvs/arduino_uno/firmware.elf}
    • Set breakpoint atsetup
    • CheckResume

    eclipse_debugging_conf_setup

  3. After pressing “Debug” button you will see this:
    eclipse_debugging_result_1eclipse_debugging_result_2

Conclusion

I’ve just shown how we can use PlatformIO console tool to build and debug single source code with different development platforms using Eclipse IDE.

You can download already configured project from GitHub Examples Repository.

If you have any questions, don’t hesitate to ask me in the comments below.

  • Nicolas Colomer

    Hi Ivan, great how-to post! Platformio appears to be very promising and simplifies things a lot. Do you think possible to generate a preconfigured empty project (as you describe in this post) automatically, eg. from (platformio?) command line?

    • Yes, please read Get Started and Quickstart section.

      For example, if you have Arduino Uno board, then you can can init project with this command:

      $ platformio init --board=uno

      • Nicolas Colomer

        (well, sorry, the question look stupid 🙂
        I followed all these steps but I was thinking more about the generation of the Eclipse configuration itself (the .cproject file) so that we just have to import the project in Eclipse after platformio init. WDYT?
        Again, what you achieved with PlatformIO is really great! I’m very impatient to code some juicy sketches using it 😉

        • I got you. Sorry, PlatformIO doesn’t have this feature. But… If you really need it, just open an issue. Maybe, I will find time for it. It isn’t hard to implement.

          P.S: To my mind, the best way is to create own Eclipse CDT-based version with internal PlatformIO support 🙂

  • Dontsov Evgeny

    Thank you, Ivan for this great program!
    🙂
    I start to write concept of tiny SCADA for Arduino and was surprised so useful PlatformIO!

    A little comments:
    – while understanding PlatformIO, I can’t reinit it, so I call “pip uninstall platformio”… Maybe you can add “reset” command?

    Best regards, т.е. успехов и достижений!

    Евгений

    • Maybe you can add “reset” command?

      Why do you need “uninstall/install” PlatformIO? Can you explain me with an example?

      Best regards, т.е. успехов и достижений!

      Thanks a lot! И Вам большое СПАСИБО за отзыв! 🙂

      • Dontsov Evgeny

        I have some folders. There is a root folder of project. I do “platformio init –project-dir=”…/platformio” and can be wrong in path. Now I can’t do “init” with right path, cause platformio write that it is already initialized.
        I uninstall platformio and try to do command with right path.

        “run” command works only in project-dir. Maybe add “project-dir” option?

        • 1. You shouldn’t mix “PlatformIO” and “PlatformIO-based Project.

          2. You don’t need to install/re-install PlatformIO. If I understand, you want to initialise the same folder more then one. It’s impossible.

          If you want to have different projects with the different source code, then just run “platformio init -d /dir/1/” and “platformio init -d /dir/2”. You will have 2 different folders with the different source code.

          “run” command works only in project-dir. Maybe add “project-dir” option?

          I got you. I hope, I will add it in feature. You can use this command:
          $ cd /project/1/ && platformio run

  • CodeAndWire

    Hi, Thanks for this. Platformio looks great. All works well but i have a few questions. Im a little confused on how to include a library though. I installed a library from the command line with “platformio lib install 89”. Do i need to copy the library to the lib folder of my eclipse project or can i include it another way? Where is the default location for libraries installed by platformio? I tried simply adding #include “PubSubClient.h” to the top of the main.c but this doesnt work.
    thank you.

    • Do i need to copy the library to the lib folder of my eclipse project or can i include it another way?

      No, you don’t need to copy something.

      Where is the default location for libraries installed by platformio?

      See this information in documentation.

      I tried simply adding #include “PubSubClient.h” to the top of the main.c but this doesnt work

      I’ve just tried PubSubClient Library and don’t have any problems. See my log:

      http://pastebin.com/UxXhq83k

      • CodeAndWire

        Hi. Thanks. I see from the log you are using the platformio run command line to build the .ino
        I am confused about how to add a library to an eclipse project. I’ll try a few more things.

        • Eclipse helps you only with $ platformio run command. For other commands you should use CLI in Terminal. I mean, that it should like:
          1. Initialise project via CLI
          2. Install specific libraries
          3. Import project form Eclipse
          4. Customise Eclipse
          5. Build + upload using Eclipse
          6. Make any changes to PlatformIO based project using CLI+Terminal (not Eclipse)

          Eclipse doesn’t have GUI which replaces PlatformIO commands, like library installation.

  • Omar Belkhiria

    Hi, Ivan. I appreciate your unique SW.

    I encountered some problems with Platformio. I use ubuntu 14.04 + Eclipse Mars to program for Arduino 2560 (apparently not supported by simulavr).
    First off, built-in project generator seems not to work yet well; so after trying it, I jumped to manual steps. After building the cpp code successfully, I didn’t find simulavr nor gdb-avr at ${HOME}/.platformio/packages/toolchain-atmelavr/bin/simulavr. Even I downloaded simulavr and unarchived it at this folder; the console displayed after running: /home/omar/.platformio/packages/toolchain-atmelavr/bin/usr/bin/simulavr: unrecognized option ‘–port’.

    Thank you for help.

    • I encountered some problems with Platformio. I use ubuntu 14.04 + Eclipse Mars to program for Arduino Mega 2560 (apparently, its µC not supported by simulavr). First off, the built-in project generator seems not to work yet well;

      Please open your issue here https://github.com/platformio/platformio/issues . It should work without any problems.

      I didn’t find simulavr nor gdb-avr at ${HOME}/.platformio/packages/toolchain-atmelavr/bin/simulavr. Even I downloaded simulavr and unarchived it at this folder; the console displayed after running: /home/omar/.platformio/packages/toolchain-atmelavr/bin/usr/bin/simulavr: unrecognized option ‘–port’.

      You are right, these binaries are missed in toolchain for toolchain-atmelavr-linux_x86_64. Please open the new issue for it here https://github.com/platformio/platformio/issues

  • Omar Belkhiria

    I don’t know why each time I open my program with Eclipse; I find a list of 20 warnings but justly, I open preferences in Window menu then C/C++ build and I click apply then I rebuild the code-> all the warnings disappear. Last time, I had a new warning:
    Class ‘LiquidCrystal’ has virtual method ‘write’ but non-virtual destructor LiquidCrystal.h

    Do yo have some ideas?

    • I’ve just re-tested with the latest Eclipse Mars and I can’t reproduce these warnings. Have you added to includes the source directory of LiquidCrystal library?