eirikm gravatar image

Posted 2014-09-01 15:02:00 +0100


Getting started with nRF51 development on Mac OS X

Update: Since this blog was originally written the nrfjprog tool has been ported to OS X (now macOS). This means that the flash programming is much simpler, and it is simply a matter of following the documentation for the tool. Also, nRF Toolbox for iOS is deprecated; use the nRF Connect iOS app instead

I recently decided to try the nRF51 SDK on Mac OS X to see how it was to compile and program the example applications. It worked nicely, and it wasn't even that hard to figure out. But evidently there were things to find out, and before things were actually working there was always the fear of discovering that some of the setup was wrong and you have wasted hours on a stupid mistake.

The questions are many: Do I have the right tools? Where do get started in the SDK? Are there other changes needed? And from experience there are always things you don't think about before they hit you in your face. This blog is the guide I wish I had when I first started out. If by following the steps there is at least some confidence that things are working as they should, then I can go on exploring from there. I hope you find it helpful!

Setting up the tools

First of all, and at the risk of stating the obvious: Buy a development kit!

You will need this for the license to programming and debugging software. For this tutorial the nRF51822-EK (Evaluation Kit) was used.

Assuming nothing, here is the (minimum) software you need download (the version I used are in parenthesis):

  • nRF51-SDK-zip: This is the Nordic Semiconductor SDK for nRF51 (6.0.0). See the nRF51/52 SDK download page to get it. Unpack the SDK to a location of your own choice.
  • S110-SD-v7: The S110 (v7.0.0) softdevice that supports peripheral devices. Find it on the same page as above.
  • GCC ARM Embedded: Compiler tools for ARM Cortex-M. Download the latest version from Launchpad (gcc-arm-none-eabi-4_8-2014q2-20140609-mac). Unpack the tarball to /usr/local.
  • J-Link software for Mac: Get the latest version from Segger (V4.90b) and run the installer.
  • (You might need to install make. Not sure if it is installed byt default or part of XCode.)

Compiling the Bluetooth Smart example

The examples in the SDK each have a makefile (or several) in the gcc folder that works without modification. However, there is one important change that is needed for one of the template files, which is to set the correct toolchain path. This is defined in Makefile.posix: (SDK location)\nrf51822\Source\templates\gcc\Makefile.posix

GNU_INSTALL_ROOT := /usr/local/gcc-arm-none-eabi-4_8-2014q2
GNU_VERSION := 4.8.3
GNU_PREFIX := arm-none-eabi

Make sure that GNU_INSTALL_ROOT is the correct path GCC toolchain on your computer. Also check that GNU_VERSION is the right one.

To make things interesting I'll use a Bluetooth Smart example: the Heart Rate Monitor application ((SDK location)/nrf51822/Board/pca10001/s110/ble_app_hrs). With the changes in Makefile.posix you should now be able to compile it.

~ em$ cd <SDK location>/nrf51822/Board/pca10001/s110/ble_app_hrs/gcc
gcc em$ make -f ble_app_hrs.Makefile all

This example has more than on makefile so you need to specify which one to use. The build result is found in the _build folder.

Flash Programming

For simplicity in this tutorial copy the softdevice (S110) .hex file to the _build folder of the Heart Rate Monitor example. The programming is performed from the _build folder:

_build em$ JLinkExe -device nrf51822_xxaa -if swd -speed 4000
J-Link>loadbin s110_nrf51822_7.0.0_softdevice.bin 0
J-Link>loadbin ble_app_hrs_s110_xxaa.hex 0x16000

Setting the correct device is crucial, and the speed setting is needed to make the programming fast enough. The softdevice is first programmed in the beginning (location 0) and the application is programmed immediately after (0x16000 for S110 v7.0). After the programming a reset is needed ('r' + 'g').

Now, try to connect the HRM to your phone: I used nRF Toolbox for iOS/eng-GB).

Troubleshooting tips

If you are struggling to make the app work it might be a good idea to clean the memory and reprogram. Unfortunately the only way to erase the memory is to do some magic register writes:

J-Link>w4 4001e504 2
J-Link>w4 4001e50c 1

If you are wondering if things are working at all, try building and programming the blinky_example at memory location 0. Since this example doesn't require the softdevice you have removed one source of error.

Automating Tasks by Modifying the Makefiles

Working with the J-Link CLI quickly gets cumbersome, but by modifying Makefile.posix the things you need to do can be automated. Here is file I used:

GNU_INSTALL_ROOT := /usr/local/gcc-arm-none-eabi-4_8-2014q2
GNU_VERSION := 4.8.3
GNU_PREFIX := arm-none-eabi

FLASH_START_ADDR = $(shell $(OBJDUMP) -h         $(OUTPUT_BINARY_DIRECTORY)/$(OUTPUT_FILENAME).out -j .text | grep .text | awk '{print $$4}')

JLINK_OPTS = -device nrf51822 -if swd -speed 4000

flash-jlink: flash.jlink
    $(JLINK) flash.jlink

    printf "loadbin $(OUTPUT_BINARY_DIRECTORY)/$(OUTPUT_FILENAME).bin $(FLASH_START_ADDR)\nr\ng\nexit\n" > flash.jlink

erase-all: erase-all.jlink
    $(JLINK) erase-all.jlink

    # Write to NVMC to enable erase, do erase all, wait for completion. reset
    printf "w4 4001e504 2\nw4 4001e50c 1\nsleep 100\nr\nexit\n" > erase-all.jlink


.PHONY:  flash-jlink flash.jlink erase-all erase-all.jlink run-debug

With this modification you have makefile targets for flash programming (flash-jlink) and erasing the chip (erase-all). In addition there is a command to launch the debugger (run-debug) which we will look at next.

Tip: For more options and ideas have a look at this Github repo.

Running the Debugger

With the modified Makefile.posix it is easy to start a GDB server:

gcc em$ make -f ble_app_hrs.Makefile run-debug

This will start a GDB server in your current terminal window. Note that there is a port number in the parameter list (9992, GDB_PORT_NUMBER in Makefile.posix) which you need to connect to GDB.

In order to load debug symbols you need to compile the project in debug mode (make clean & make debug). Start the debugger with the .out file to load the symbols. In another terminal window start GDP:

gcc em$ /usr/local/gcc-arm-none-eabi-<version>/bin/arm-none-eabi-gdb _build/ble_app_hrs_s110_xxaa.out
[Loading ... check that symbols are loaded]
(gdb) target remote localhost:9992
(gdb) b main.c:621
(gdb) monitor reset
(gdb) continue

The line number in main.c might differ, so set it to the Connected case in the on_ble_evt() callback routine. Try to connect the heart rate monitor to your phone and check that the GDB breaks the execution.

Next step - IDE integration

I kept IDE integration out of this guide, but it is a natural next step. The nAN-29 Application Note explains how to set up Eclipse with GCC. Personally I'm tempted to try something else.


hnhoan gravatar image

Posted Sept. 2, 2014, 12:11 a.m.

IDE integration, try here http://embeddedsoftdev.blogspot.ca/p/eclipse.html Blog site contains examples code for nRF51822 with Eclipse project, including Eclipse project to compile DFU. You'll also find an alternative to the JLink to program the nRF5x on the blog page.

sprhawk gravatar image

Posted Sept. 2, 2014, 3:44 p.m.

Great !

I have my own scripts here:


and a demo:


janekm gravatar image

Posted Sept. 2, 2014, 6:23 p.m.

A nice summary!

freqmod gravatar image

Posted Sept. 12, 2014, 12:36 p.m.

Most of these instructions are also applicable for linux development, flashing & debugging too, if anybody has problems with that.

antoniordz gravatar image

Posted Sept. 13, 2014, 10:52 p.m.

Great!!! I have been wanting to stop using windows on my mac!

jimcredland gravatar image

Posted Feb. 1, 2015, 5:02 p.m.

This is great stuff. Thank you! I also found some links which helped set up Xcode as the editor, with some Makefile integration and indexing of the nordic headers.


Was the key one.

kerem gravatar image

Posted April 22, 2015, 3:04 a.m.

I am having problems with compiling the samples using gcc for arm 4.9 on os x 10.9 and nrf51 sdk 8.0. I am getting errors such as:

clang: error: unknown argument: '-f'

clang: error: no such file or directory: 'em$'

clang: error: no such file or directory: 'make'

Is there a more recent guide for simply compiling any of the examples on os x? Should I just go for the virtualbox/win7/keil setup as that's more relevant to the current documentation?

I don't have the development board but only a nrf5188 beacon, I'm trying to build one of the examples and flash it on the beacon using nRF Master Control Panel application on Android.

shlomozippel gravatar image

Posted May 12, 2015, 2:09 a.m.

I just played around with getting SDK v.8 samples to work on mac. A few notes that might save you some time:

  • There is no need to specify the flash start address when flashing samples build with SoftDevice support. The .hex file contains the correct offsets (based on the sections defined in the custom linker scripts) and LinkExe ignores the start address
  • $(OUTPUT_FILENAME) isn't defined when Makefile.posix is imported into the various example Makefiles. I added hardcoded OUTPUT_FILENAME := nrf51422_xxac to the posix makefile just to get the examples working without changing every makefile individually.

@kerem - it looks like you copied the entire line including the shell prompt. Try dropping the gcc em$ from the command you're trying to run.

Posted July 28, 2015, 10:51 p.m.

I have been going through the example. A quicker link to the SDK.


I was confused when it was not in the download section and spent a good amount of time looking through the IOT sdk.

eirikm gravatar image

Posted Aug. 5, 2015, 1:01 p.m.

@patrick: The site you posted to was not launched when I first wrote this blog post. I have updated the link in the post. I also removed the comment that a login is required; it no longer is :)

gap gravatar image

Posted Oct. 28, 2015, 2:51 p.m.

Thanks for this guide.

Here are some updates for compiling with the latest SDK (9.0.0):

The location of makefile.posix has changed from:

(SDK location)/nrf51822/Source/templates/gcc/Makefile.posix


(SDK location)/components/toolchain/gcc/Makefile.posix

For the compilation example, the path and filenames have changed a little:


cd <SDK location>/nrf51822/Board/pca10001/s110/ble_app_hrs/gcc
make -f ble_app_hrs.Makefile all

new (just one makefile in the folder):

cd <SDK location>/examples/ble_peripheral/ble_app_hrs/pca10028/s110/armgcc
make -f Makefile all
hawkinchina gravatar image

Posted Nov. 16, 2015, 9:51 a.m.

Great! I want to continue to write code on my mac!

Next step , it had better to use vim as editor.

carlos.po5i gravatar image

Posted Aug. 6, 2016, 1:11 a.m.

I think it would important to include some tasks to flash the softdevice because erase-all cleans everything.

This is my code:

flash-softdevice-jlink: flash-softdevice.jlink
    $(JLINK) flash-softdevice.jlink

    printf "loadbin ../../../../../../components/softdevice/s130/hex/s130_nrf51_2.0.0_softdevice.hex 0\nr\ng\nexit\n" > flash-softdevice.jlink
Lola gravatar image

Posted April 30, 2017, 9:13 p.m.

This is working great! although there are many modifications had to be made in the new s132. Also for some reason you said we should drag the s132 hex file into the _build folder then you : loadbin s110_nrf51822_7.0.0_softdevice.bin instead of using the .hex file for some reason. I did it with the hex and it worked.

ryangrimm gravatar image

Posted Sept. 28, 2017, 11:59 p.m.

It would be great if this post were updated as nrfjprog has been ported to Mac OS (https://devzone.nordicsemi.com/blogs/840/nrfjprog-pynrfjprog-intro-mac-os-x-linux-now-suppo/). I'm just getting started using this toolchain and feel like I very nearly went down an old and more painful road. Considering that the previous comment is only a handful of months old as well it appears like I'm not the only one.

eirikm gravatar image

Posted Sept. 29, 2017, 9:39 a.m.

Thanks for heads up! I added a warning at the top for now to avoid more people being misled.

Sign in to comment.

User menu

    or sign up

Recent questions