Using Eclipse to Program the nRF51822

In a previous post I discussed using Arm’s Keil IDE and Nordic’s nRF81 DK to program the nRF51822.  I was right in assuming this would be the fastest way (for me given I had no experience with any of the supported IDEs).  I wasn’t satisfied with the Keil IDE because:

• the IDE is Windows only.  I use a Mac.  While I can run the IDE in Windows within a Parallels VM, the look and keyboard interactions are tedious and quite frankly far less than a delightful experience.  I found myself mentally switching between how to do things on the Mac versus on Windows.  Also, the look of the Windows is far from crystal clear, looking more like a bitmapped image of a Window than something I am directly interacting with.
• the IDE will eventually cost a lot.  While exploration up to 32K is free, I did not like the feeling this ceiling is looming.  In addition, support is extremely important AND expensive for the company to provide.  They deserve some amount of money for the IDE.  I would not get the level of support I would want with this proprietary program.  I also didn’t like paying for a Windows version when I am a Mac user.

I decided to give the Eclipse IDE a try.   The forums appear vibrant and accepting, similar to the Arduino community that has been so supportive.

Benefits of the Eclipse IDE

• it is written in Java which means I can run it “natively” on my Mac. 
• it is a mature environment. The Eclipse Wikipedia entry states the initial release was in November, 2001.
• it has a lot of smart people organized around evolving the IDE and releasing stable releases.  Mars was release on June 24 (which – oh my! is today!).  The numbers are impressive.  This Eclipse newsletter notes: The Mars release is the expression of the effort of 379 committers and 351 contributors working on approximately 65 million lines of code for seventy nine separate open source projects.
• it is powerful.  I was able to build, flash the nRF51 DK, and do source line debugging all from within the Eclipse IDE.  I guess the 65 million lines of code are being (mostly?) productive.
• it seems to be used by a vibrant, large, and ever growing community.  The wikipedia entry lists several programming languages that are supported.  I am anectodally seeing a growing use of the Eclipse IDE by Universities as well as folks like me. 

Concerns with using Eclipse

• While there is vision around concepts of  a Workspace, Project, and Perspective which provide strong visual to set the context of how to interact with the Eclipse IDE, there are usually several ways of doing something which gets confusing and it is incredibly rich.  This is not surprising given the incredible amount of contributions and the number of years Eclipse has been around. 
• There is a loose coupling between Eclipse and the C/C++ environment.  For example, a workspace can either have a managed Makefile or a Makefile.  I am using a Makefile.  When I update the Eclipse IDE with an #include path, the source path in the Makefile is not updated.  I have to remember to update the Makefile to fix symbol unresolved errors.

The above is not a comprehensive list.  Just some ideas that come to my mind.  What I want to focus on is what it takes to set up an Eclipse environment on the Mac for programming the nRF51822.

The Goal

The goal of this post is to provide enough information such that the Mars version of Eclipse and the nRF51 SDK (current version 8.1) can build, flash to the chip, and debug apps written to the nRF822’s cortex-m0 µC and BLE hardware.

 

Thanks to Those That Went Before

• The Eclipse team for bringing us a well done, freely available IDE that enables us to embrace more micro controller options.
• Vidar Berg – a Nordic employee – gave excellent answers to support questions I posted in Nordic’s developer support. He is also the author of the post “Development with GCC and Eclipse” that served as the backbone to this post.
• Nguyen Hoan Hoang – a consultant who is active on the Nordic DevZone – tirelessly answered my questions.  He is inspirational in his knowledge and exceptionally giving in his feedback.  I found his web site to be very helpful.

Non-Goal

It is not the goal to redo the tutorials of others.  The challenge I had with existing tutorials included:

• there are enough differences in setting up the Eclipse environment on the Mac versus Windows that I found myself having to switch between tutorials and figure out what steps were relevant to installing the environment on the Mac.
• there are different combinations of how folks wish to program for the nRF51822.  Some stick with the GCC.  I wanted to use the Eclipse IDE because for me it is easier to use Eclipse’s debugging environment and more efficient to fix bugs as well as write code.
• there are different ways to build a binary in Eclipse – with a Makefile and opting for Eclipse to figure it out (managed Makefile).  I didn’t understand this concept at first…which got me confused for awhile.
• some of the recommendations within the tutorials didn’t make sense to me and ultimately were not the best way to do things.  This too took me awhile to figure out :-).

Yet, there is A LOT of great info on getting the Eclipse environment.  I will refer to these sections instead of redoing them here.  

Setting up the Eclipse IDE + GNU ARM Tools + nRF51 SDK on a Mac

 Vidar’s tutorial, Development with GCC and Eclipse, was the most helpful post on getting set up.  I call Vidar out by name because during my process I had several questions I directed to Nordic support.  Vidar’s answers where consistently excellent / useful.  I had no context of what all these steps meant.  It took me several times to gain this context before I succeeded in all the task.  The tutorial:

• installs the Kepler version of the Eclipse IDE.  The current version is Mars (this link shows the progression of Eclipse releases from 2.0 through June, 2015).  Since the Eclipse IDE is evolving, before installing the Eclipse IDE gain familiarity with the current version…accommodations will need to be made for steps that have changed based on the evolution of the Eclipse IDE.
• is more approachable to someone running Windows instead of the Mac.  The recommendations for the Mac are sparse and not specific.  

Steps

With that said, on with the steps

• Download the tools Vidar recommends( note: before installing the tools read the bullets below).  Given installation on a Mars – as Vidar points out – the GnuWin32 and nRF-tools aren’t part of the Mac environment.  Also check about the latest versions.  Posts are dated the minute they are published.  Perhaps the nRF51 SDK is on version 25…right now the latest is 8.1.  As of this writing the latest Eclipse version is Mars (link here.  The download is “Eclipse IDE for C/C++ Developers” ).  
• Install Eclipse.  When installing, the IDE asks for a Workspace.  Workspaces are a concept that needs to be understood.  There is an article from 2005 that helped me better understand the role Workspaces serve within Eclipse.  While the post uses old Windows UI, the properties, concepts, and the first two recommendations still ring true.  After several attempted installs of Eclipse, what I would recommend is to link the workspace to a folder that represents projects of the same category.   So for example, /Users/happyday/documents/nRF51822 might be mine.  Do not link your workspace to a path where the Eclipse app is installed.  If you link the workspace to a path within the folder structure where Eclipse is installed source code, binaries…your hard work!…will most likely be deleted.
• Open Eclipse.   If the error:  “Version 1.6.0_65 of the JVM is not suitable for this product.” occurs, follow the directions posted in this Stack Exchange post. I got this error the first time I tried to open Eclipse on my Mac.  After googling how to fix it, the advice in the Stack Exchange post fixed the problem.
• Install the nRF51 SDK. Unzip the nRF51 SDK into a folder under the workspace folder.  Following the example, /Users/happyday/documents/nRF51822/nRF51_sdk might be mine.
• Install the GNU tools.  The Mac version of the GNU tools for ARM processors is compressed using tar.  The file will decompress when clicked on.  Place the folder structure below /usr/local .  This is the assumed path for the GNU tools.  Install the GNU Arm Eclipse plug-in from here.  You might also want to change some of the default preferences as discussed in this link.
• Install the J-Link tools.  The nRF51 DK includes a J-Link OB chip.  This is wonderful because J-Link can be used to flash the nRF51 as well as do source line debugging.  Here is the link to instructions and files needed for installation.  I added JLink’s executable path(in my case this was /Applications/SEGGER/JLink)  to the $PATH variable following so that terminal would find it no matter what folder i was in.  This is not necessary if running JLink commands within the Eclipse IDE.  However, occasionally I would go to a terminal window and try out a JLink command.
• Install the EmbSysRegView plug-in.  As noted on the EmbSysRegView project page: “EMBedded SYStems REGister VIEW is an Eclipse Plugin which is designed for monitoring and modifying memory values of embedded devices. Therefore it offers a structured display of the special functions registers (SFR). While debugging, the register values are presented in the Hexadecimal (HEX) and Binary (Bin) column of the view.”  Instructions for installing the plug-in are under the “Install and Use” tab.  Installing EmbSysRegView has a tricky step on Macs.  In Vidar’s instructions, he states under setting up Eclipse: “To install the register view file for Nordic Semiconductor devices copy file nrf51.xml from ../nRF51 SDK/SVD/ to the folder.”  On the Mac, this file needs to be copied within Eclipse.app.  On my Mac, Eclipse is installed in /Applications/Eclipse.  Within the file manager, I right-click on Eclipse.App and choose “Show Package Contents”

now follow Vidar’s instructions on where to copy the nrf51.xml file and the additional Eclipse set up steps to get the registers showing within the Eclipse IDE.

• Configure the Eclipse IDE according to the steps outlined in Vidar’s instructions.

Building a BLE Peripheral App

As most software folks know, the instructions to compile and build an app are usually contained within a Makefile.  A feature of IDEs like Arduino, XCode, Eclipse and others is creating and updating compile and build commands without having to be an expert in the arcane options and commands of a makefile.

Eclipse features both the ability for the IDE to manage compiling and linking as well as using a makefile.  It all depends how a project is created.  If the choice is to use an existing makefile – it is up to you to keep the makefile source and include files in sync.  I’ll touch on this in a bit.

Creating a Managed MakeProject

When creating an empty C project, all the options that would be in a makefile are set in the Eclipse Tool settings.

UI to set compiler and link settings when there is no makefile

I tried using a managed makefile through an example from a web site labeled “Embedded System Development”  I ended up not going down this path because it would take me longer than I like to understand all the options since I am less familiar with the C tool chain.  I’ll eventually have to have a better grasp on compiling and building, but for now I will rely on makefiles that have been written by Nordic engineers specific for the nRF51 DK.

Using an Existing Makefile

I ended up successfully debugging a BLE app on the nRF51822 by starting with a makefile.  The Tool Settings dialog looks different when a Makefile is used.

Tool Settings when this is a makefile

Starting with an SDK Example

I started with the Makefile and Linkfile located at …/examples/ble_peripheral/ble_app_template/pca10028/s110/armgcc To create a project named EC_Test:

• created folder named EC_Test
• copied the Makefile file and ble_app_templage_gcc_nrf51.ld files from the ble_app_template…/armgcc location into EC_Test
• copied the ble_app_template main.c into EC_Test
• renamed ble_app_template_gcc_nrf51.ld EC_test.ld so the linker file felt like it was part of the EC_Test project
• created a new project in Eclipse that starts off with a Makefile: File -> New -> Makefile Project With Existing Code
• pointed to the folder EC_Test (it contains the makefile).  
• Edited the Makefile
• searched for ble_app_template_gcc_nrf51.ld and change to EC_test.ld
• changed PROJECT_NAME to EC_Test
• removed the bin target (I discuss later why only the .hex file is needed).
• corrected path locations:
• added a variable SDK_PATH, e.g.:  SDK_PATH = /Users/margaret/Documents/EHAL/ARM/Nordic/nRF51/nrf51_sdk
• changed the variable TEMPLATE_PATH, e.g.:  TEMPLATE_PATH = $(SDK_PATH)/components/toolchain/gcc
• found/replaced ../../../../../.. with $(SDK_PATH)
• Added a folder to the Eclipse project to hold main.c :  focus the cursor on the project name, EC_Test,  then right-click and choose New->Folder (I named my folder src)
• Moved main.c into the src folder.

Note: the Makefile requires additional modifications which are discussed below.

Adding Source and Include Files

Remember: When you add an include/source file to the Eclipse project, the paths (i.e.:  INC_PATHS and C_SOURCE_FILES must also be added to the makefile.

Because Eclipse does not use a makefile, in order to take full advantage of the Eclipse IDE  (who doesn’t want source level debugging AND printf’s???), adding/deleting source and include files from the project is a two step process.  The include files needs to be added to the IDE and also to the makefile.  To add the include files, I click on the project folder and then type in ⌘i to bring up the Path dialog box.

The makefiles include with the SDK examples are optimized.  Follow Vidar’s “Edit Makefile” steps (found in this post) to add in instructions to make to include debug information and be a bit more verbose.

When I was building a program to test the nRF51 DK talking to an ADS1015, I started with the ble_app_template project that comes with the nRF51 SDK.  The makefile listed a lot of include files that main.c was dependent on.  Since Eclipse does not get info from the makefile, I wanted to tell Eclipse about it.  Here is a screen shot of the list of include files:

This help file describes the UI that lets you tell Eclipse the path to include files.  I found the fastest way to add include files was to:

• get the list of include paths from the makefile.  These are listed using the INC_PATHS variable:

INC_PATHS += -I../../../../../../components/drivers_nrf/uart

• get the path to the nRF51 SDK into the clipboard.  Since I have Alfred installed, I took advantage of Alfred’s ability to create snippets so that I could quickly past the path to the SDK and then attach the rest.  In my case, the snippet is “${workspace_loc}/../../Nordic/nRF51/nrf51_sdk/“
• click to add an include, past the snippet, then write in the rest of the path.  In the example above, the rest of the path is “/components/drivers_nrf/uart

New source and/or include file added to the Eclipse IDE must be added to the makefile by adding the include’s path as an additional INC_PATHS +=  and C_SOURCE_FILES += in order to compile and build the app.

Loading the App Onto nRF51

A BLE app requires two binaries to be loaded onto the nRF51:

• The SoftDevice library provided by Nordic that handles calls and replies from BLE.  I use the library for a peripheral, s110_softdevice.hex.  This file comes with the nRF51 SDK in the …/components/softdevice/s110/hex/ folder.
• The app.

The SoftDevice need only be loaded once.  Every time the app is rebuilt it needs to be reloaded onto the nRF51.  JLink – a utility that comes when the SEGGER tools are installed (see above) – is used on the Mac to load binaries.  First thing is to figure out what commands and how to format them so the JLink utility does what we want.  The second thing is to figure out how to integrate loading into Eclipse.

Loading Binaries

Since I program on a Mac, I’d rather use a native Mac program than Nordic’s nRFgo Studio to copy the app’s binary onto the nRF51.  SEGGER provides the JLinkExe utility (I also call JLinkExe JLink) when the SEGGER tools are installed (installing the SEGGER tools was outlined as an earlier step).  I ended up creating makefile targets (link to makefile overview) that evolved from this post on programming the nRF51 DK + Eclipse on a Mac.  I start this section going through concepts that were new to me and then discuss how the flash.jlink file integrates within the makefile so that loading the app becomes part of Eclipse.

The Device Name

When starting JLink, a mandatory parameter is the name of the device.  As noted within a Nordic support reply message I received: Regarding device types, the xxAC variant has 32K of RAM as opposed to xxAA with 16K (overview overview of chip variants can be found in the compatibility matrix.) 

For example, if you open a terminal window and then type in (assuming the JLink utilities can be found):

JLinkExe -device nrf51422_xxac

(note: the nRF51 DK uses the nrf51422 and has 32K of RAM)

The JLink utility starts up with the correct device info for the nRF51 DK.  Now that the JLink utility is running, the files are loaded.  But I got confused on what file format to load a .bin or a .hex?  After all – the makefile examples seemed to make both binaries.  Why?

Use the HEX file format

Some of the makefiles I looked at built both a .hex and a .bin file.  I asked Nordic support this question and got the answer:

I do not see any reasons for using the .bin files instead of .hex files unless creating an image for doing DFU. The Keil projects does for instance not output a .bin file by default.
.hex files specifies which addresses the data/code shall be loaded into, whereas .bin files use byte padding to get the correct address offsets when there are gaps between data/code and it does not contain info about the start address.  So with .hex files Jlink will now exactly where to load data.  

The important point (besides curiosity in trying DFU which I’ll do at some point) was the .hex files contained the address of where the data and code should be loaded.

Copy Binaries to the nRF51 DK

 I found two commands the JLink utility uses for loading a binary:

• loadbin:  loadbin takes a .bin formatted file.  I started using the loadbin command because many of the posts used this command.  The challenge I had was ensuring I had the right address (i.e.: loadbin <filename.bin> <address to load binary at>
• loadfile: loadfile takes a .hex formatted file.  I prefer using loadfile because there is no need to specify an address.

For example, after starting the JLinkexe utility as noted above, the command to load a binary would look like:

loadfile _build/nrf51422_xxac_s110.hex

here the name of the app is nrf51422_xxac_s110.hex.  Hmm…I was using the name that came with the makefile.  Pretty darn ugly.

Make a Flash Programming Target

I integrated flash programming into Eclipse by creating three flash target within the makefile.  First, setting up the variables:

JLINK_OPTS = -device nrf51422_xxac 

JLINK = JLinkExe $(JLINK_OPTS)

then setting up the targets:

#############################################################################

# Target: erase

# remove all binaries from the nRF51

#############################################################################

erase: erase.jlink

$(JLINK) erase.jlink

erase.jlink:

printf “erase\nr\nexit\n” > erase.jlink

#############################################################################

# Target: flash_softdevice

# load the s110 softdevice onto the nRF51

#############################################################################

flash_softdevice: flash_softdevice.jlink

$(JLINK) flash_softdevice.jlink

flash_softdevice.jlink:

printf “loadfile /Users/margaret/Documents/EHAL/ARM/Nordic/nRF51/nrf51_sdk/components/softdevice/s110/hex/s110_softdevice.hex\nr\ng\nexit\n” >flash_softdevice.jlink

#############################################################################

# Target: flash

# load app onto the nRF51

#############################################################################

flash: flash.jlinka

$(JLINK) flash.jlink

flash.jlink:

printf “loadfile /Users/margaret/Documents/EHAL/ARM/Nordic/nRF51/nrf51_sdk/examples/ble_peripheral/ble_app_template/pca10028/s110/armgcc/_build/nrf51422_xxac_s110.hex\nr\ng\nexit\n” > flash.jlink

(the paths and filenames are relative to what I have. You will need to change these).  There is no need to reload the s110 softdevice once loaded so I broke out loading the softdevice from loading the app.

Run Target from Eclipse

The menu item – Make Target – off the project in the navigator:

is where to start.  First, let Eclipse know about the target in the makefile by going to the Create… dialog and entering the target name.  Then run the target commands by going to the Build… dialog and choosing the target to run.  

Debugging

 Assuming the changes to the makefile were made as discussed above, source line debugging is straightforward.  Just explore Run -> Debug Configurations to get going.  It is a little bit trickier is getting printf() to work.

printf()

There seem to be several ways to get to writing out to a serial port.  The one that worked for me was SEGGER’s Real Time Terminal (RTT) utility.   Noted in this overview:  “…SEGGER_RTT_printf(), which can be used to print formatted strings via RTT, directly, without a standard library.”  There is a Nordic Devzone post where it is states RTT is the way to go for real time apps that use BLE.

Include the RTT library within the Eclipse IDE and the makefile (see adding Source and Include Files above).  The library for the 8.1 nRF51 SDK is located at …/components/RTT .

Include SEGGER_RTT.h to the project by writing  #include”SEGGER_RTT.h” near the top of the main.c file in the project

 Include printf() statements, e.g.:  SEGGER_RTT_printf(0,“The raw ADC value is: %d\n”,rawADC);

Open a Terminal window

Start the RTT client, e.g.: jlinnkrttclient

Note: sometimes the RTT client couldn’t connect.  While using options that help these utilities (e.g.: -if SWD and -device nrf51422_xxac) might help clarify any confusion, I found my challenge with connecting to be because the port was busy.  For example, if I started the RTT client before starting the debug session (which uses the SWD port).  At this point, I could use Unixy commands (which I am no expert in) to kill the JLink apps running on the Mac, or start over and unplug/plug in the nRF51 DK from the USB port.  This post gives some detail on SEGGER’s tools for the Mac  

 A Note on Navigation

To use commands like those for search, make sure to highlight the scope you wish to search on.  For example, searching on the project can be done by highlighting/left clicking on the project within the navigator.  Then when telling the Search -> C/C++ to search for a string (e.g.: *SCL* to search for occurrences of scl and SCL within the files) the radio button for all files within the project is available.

That’s It For Now

I now have a very rudimentary understanding of how to use Eclipse.  Nothing is very difficult, however there is A LOT of pieces that need to come together.  I am thrilled that I can have an IDE that runs on the Mac.  I am thrilled to have source level debugging.  The folks on the Eclipse team have done amazing work that has benefited so many of us.  Time to get coding.

 

 

Thanks for reading this far.