[Update] I’ve published a more up-to-date version of this blog post that covers all three major operating systems (macOS, Windows, and Linux) using a different IDE. Check it out here: The complete cross-platform nRF development tutorial

Today’s tutorial focuses on setting up the environment for nRF52 Mac development and debugging for Bluetooth Low Energy applications. Specifically, I will be using the new Nordic nRF52840 Preview Development Kit board that supports the enhanced features of Bluetooth 5 (including longer range, bigger advertisements and increased speed).

A few notes about the setup/environment as well as the goals of this tutorial:

  • We’ll be running on macOS Sierra v10.12.4 (on a late-2016 15″ MacBook Pro)
  • We will be using the NetBeans IDE for this tutorial (really any IDE that supports gdb and gdbserver connection should work with additional customizations)
  • We’ll be using the nRF52840 Preview Development Kit
  • We’ll be able to live-debug (runtime debug) the application within the IDE and stepping through source code
  • The power of running within a macOS or Linux environment vs. Windows is the capabilities for automation and automated testing
  • This will be a first in a series of blog posts focused on deep technical implementations of BLE applications on different development kits
  • Nordic Semiconductor modules have great gcc support which makes it relatively easy to get started on a macOS or Linux environment
  • This tutorial is intended to serve as a complete tutorial that guides you step by step on setting up your environment from scratch (this should be a one-time thing)
  • I ran through all these steps with Xcode already installed on my Mac, so I recommend installing it first to be able to run through the tutorial successfully.

On macOS, unless you’re running within a Virtual Machine, you’re stuck with following tutorials that help you set up with Eclipse (or you can shell out some serious money for IAR or Keil). I’m a big fan of open-source tools such as GCC and believe they have some major advantages over proprietary and IDE-based tools (automation, consistency across multiple platforms…etc).

I’m personally not a big fan of Eclipse (although I realize it’s the most popular open-source IDE for  embedded developers) – I just find it a bit slow and too clunky whereas NetBeans is more simplified and provides a better user experience. I’ve been using NetBeans for embedded (both Linux and microcontroller level) development for over 10 years now. (If you’re not aware, Microchip’s most recent IDE called MPLAB X is actually based on NetBeans. Other vendors have done the same but with Eclipse.)

Alright, enough with all this Eclipse vs. NetBeans dilemma. Let’s get technical.

The nRF52 series

The nRF series are one of the most popular Bluetooth low energy chips, and are used in many BLE applications. Some of the reasons why they’ve been a top choice for many are:

  • The new nRF52 chips support Bluetooth 5.
  • Support for multiple development environments and toolchains including GCC, which gives developers more freedom and flexibility over what other vendors provide.
  • The excellent support you get from Nordic’s Developer Zone.
  • Support by new open source IoT and BLE solutions (nRF5x series is supported by both the Zephyr Project and MyNewt which are gaining popularity because of their openness and strong capabilities)

From Nordic’s Infocenter:

The nRF52 Series of system on chip (SoC) devices embed a powerful yet low-power ARM® Cortex®-M4 processor with our industry leading 2.4 GHz RF transceivers. In combination with the very flexible orthogonal power management system and a programmable peripheral interconnect (PPI) event system, the nRF52 series enables you to make ultra-low power wireless solutions.

The nRF52 Series offers pin-compatible device options for Bluetooth® low energy, proprietary 2.4 GHz, and Apache®solutions giving you the freedom to develop your wireless system using the technology that suits your application the best. Our unique memory and hardware resource protection system allows you to develop applications on devices with embedded protocol stacks running on the same processor without any need to link in the stack or strenuous testing to avoid application and stack from interfering with each other.

The nRF52 runs a proprietary BLE stack provided by Nordic Semiconductor called the SoftDevice.

From Nordic’s Infocenter:

A SoftDevice is a wireless protocol stack library for building System on Chip (SoC) solutions.

SoftDevices are precompiled into a binary image and functionally verified according to the wireless protocol specification, so that all you have to think about is creating the application. The unique hardware and software framework provide run-time memory protection, thread safety, and deterministic real-time behavior. The Application Programming Interface (API) is declared in header files for the C programming language. These characteristics make the interface similar to a hardware driver abstraction where device services are provided to the application, in this case, a complete wireless protocol.

Hardware Requirements

To follow this tutorial you will need the following:

  • Nordic Semiconductor nRF52 Development Kit
  • A micro-USB to USB cable (for connecting the development kit to your PC)
  • A macOS computer (MacBook Pro, MacBook, MacBook Air…etc)

Make sure your dev kit is configured as follows:

nRF Power Source is set to VDD (middle-position)
The top-right switch is set to DEFAULT
The bottom-left switch is set to ON

Steps

Download NetBeans

NetBeans is an open source IDE that’s targeted towards Java development but supports other development environments including C & C++. Since it is JVM-based it can run on all the major platforms including macOS, Linux, and Windows. You can download the latest version of NetBeans here. Make sure you download the C/C++ (or “All” version which includes all supported technologies). I am running with version 8.2 (latest as of May 2017). After the download is complete go ahead and install the application.

NetBeans Download C/C++ Option

Download nRF tools and SDK

There are a couple of tools that you’ll need to download from Nordic Semi’s site to get started with the nRF52840 development kit. All can be found under the Downloads section HERE. Download each of these to your local machine (preferably you local Downloads folder).

  1. nRF5x SDK: nRF5-SDK-zip. (I’m running with version 13.0.0).
  2. nRF5x Command Line Tools: nRF5x-Command-Line-Tools-OSX (I’m running with version 9.4.0)

Download the ARM GCC toolchain

Download the latest version from this link. I’m running with version 6-2017-q1-update. Look for the Mac OS X 64-bit link.

Download and install the SEGGER tools

Download the tool here. Look for the J-Link Software and Documentation pack for MacOSX download link under J-Link Software and Documentation Pack. After downloading go ahead and install the software.

Setting up the downloaded tools

To make things easy we’ll put all the tools in one folder.

Start by running a terminal session (⌘ + Space bar -> type “terminal” -> return).

[simterm]
$ mkdir -p ~/opt
$ cd ~/opt
$ tar xjvf ~/Downloads/gcc-arm-none-eabi-6-2017-q1-update-mac.tar.bz2
$ mkdir -p nRF5_SDK_13.0.0
$ cd nRF5_SDK_13.0.0
$ tar xjvf ~/Downloads/nRF5_SDK_13.0.0_04a0bfd.zip
$ cd ~/opt
$ mkdir -p nRF5x-Command-Line-Tools_9_4_0_OSX
$ cd nRF5x-Command-Line-Tools_9_4_0_OSX
$ tar xjvf ~/Downloads/nRF5x-Command-Line-Tools_9_4_0_OSX.tar
[/simterm]After that you’ll want to configure the SDK to point to the correct compiler that you installed.
First, run the following command:
[simterm]$ ~/opt/gcc-arm-none-eabi-6-2017-q1-update/bin/arm-none-eabi-gcc –version[/simterm]
You should see an output similar to:
Locate the Makefile.posix file in a Finder session (under ~/opt/nRF5_SDK_13.0.0/components/toolchain/gcc) and edit the file to correspond to the version and location we have it installed in. For example, mine changed from:
to
Note: If you are using nRF SDK 14.0.0 or above, you will need to include “/bin/” appended to the end of the path.

Install a serial terminal program

You can use any serial terminal program that runs on macOS. I prefer a multi-platform program called CoolTerm (download it here).

Set up the development project in NetBeans

We’ll be running an example included in the nRF SDK called ble_app_hrs (Heart Rate Service demo).

Launch NetBeans.

Configure the armgcc toolchain.
Navigate to the Netbeans menu -> Preferences -> C/C++ tab -> Build Tools
Click on Add
Browse and locate the folder for the gcc compiler (mine is at ~/opt/gcc-arm-none-eabi-6-2017-q1-update)

Click Open
Choose GNU Mac for Tool Collection Family
Type a name like “GNU_ARM
First we need to add the path to the nRF command line tool to our Run path so we can flash the target from the IDE
Click on $PATH
Under Modify Run Command Path:
Add the folder for nrfjprog to the PATH variable
(for me I added ;${HOME}/opt/nRF5x-Command-Line-Tools_9_4_0_OSX/nrfjprog/)
Click OK
Set the C Compiler, C++ Compiler, Assembler, Debugger command as following (make should already be set):
C Compiler: ${HOME}/opt/gcc-arm-none-eabi-6-2017-q1-update/bin/arm-none-eabi-gcc
C++ Compiler: ${HOME}/opt/gcc-arm-none-eabi-6-2017-q1-update/bin/arm-none-eabi-g++
Assembler: ${HOME}/opt/gcc-arm-none-eabi-6-2017-q1-update/bin/arm-none-eabi-as
Debugger: ${HOME}/opt/gcc-arm-none-eabi-6-2017-q1-update/bin/arm-none-eabi-gdb
(If you’re going to be using NetBeans a lot for developing on the nRF platform go ahead and set the compiler as the Default)
Press OK

Create the NetBeans project
Navigate to the File menu -> New Project

Choose C/C++ Project with Existing Sources
Click Next
Click the Browse button and navigate to the folder ${HOME}/opt/nRF5_SDK_13.0.0/examples/ble_peripheral and select the ble_app_hrs folder
Select “Custom” under “Select Configuration Mode:
Disable the “Use Build Analyzer” option
Hit Next


Make sure the Pre-Build Step option is checked
Click Browse and navigate to the folder ${HOME}/opt/nRF5_SDK_13.0.0/examples/ble_peripheral/ble_app/hrs/pca10056/s140/armgcc/
Hit Select
Under Custom Command -> Command type: make


Hit Next until you get to the Project Name and Location step
Name the project (preferably a name different than the original ble_app_hrs name)
Click Browse and choose a folder where you want the NetBeans project to be created (I prefer a Projects folder under my home directory)
Click Finish
The project should start building automatically and (fingers-crossed) the build will succeed.

This build is fine if we want to just flash the target and let it run. However, if we want to debug the application we need to make some modifications to Makefile.
In the Projects window look for the label Important Files, expand it and double click on Makefile.
Scroll down the file until you find the section:

change the line to:

This will remove the code optimization performed by the compiler and also ensure all debug symbols needed by gdb are produced.
After this step, you’ll want to clean and rebuild your project.

Configuring the NetBeans project
Right Click on the Project in the Project window, Click Properties
Navigate to Code Assistance -> C Compiler
Click the “…” next to Include Directories
Click Add
Navigate to ${HOME}/opt and click on the nRF5_SDK_13.0.0 folder, then click Select
Press OK
Right-click on the Project -> Code Assistance -> Reparse Project
This will make sure that functions and API calls are parsed correctly, and that you can navigate to function and symbol definitions and be able to browse the source code more efficiently (the whole point of using an IDE!).
Note: If you’re running into issues and still seeing a lot of red underlined #include and function calls, try this:

Right click on the Project
Click on Code Assistance
Configure Code Assistance
Select Analyzer : Search file system for C/C++ header files
Hit Next
Browse to locate the …..opt/nRF5_SDK_13.0.0 folder and select it
Hit Next
Hit Finish

Configure the Run command (to flash the target)
Right click the Project name -> Properties -> Run
Replace the Run Command with make flash_softdevice flash
Your configuration should look something like this:

Hit OK
Make sure the development kit is connected to your computer and the LED (labeled LED5) right next to the MCU labeled PCA10056 is lit-up.
Hit the Play button at the Top of the Editor window and make sure the operation runs successfully.
The Output window should look something like this:


Note: You can remove the “flash_softdevice” part, it is only needed once or when the softdevice firmware changes. (I prefer to keep it just in case – worth the few extra seconds added…)

Setting the Build Result file
Project Properties -> Make -> Build Result -> “…” button
Navigate to the ble_app_hrs/pc10056/s140/armgcc/_build/nrf52840_xxaa.out (make sure you build before this step, otherwise an output file and the _build folder won’t exist)

Set up gdbserver in NetBeans
Tools menu -> Plugins -> Available Plugins (may need to click “Check for Newest”)
Find the C/C++ gdbserver plugin and install it

Debugging

In a terminal window, run the following command:
[simterm]$ JLinkGDBServer -device nRF52840_xxAA -if swd -endian little -speed 1000 -port 2331 -singlerun -notimeout[/simterm]
Let’s make sure we understand each of the arguments:
-device nRF52840_xxAA: sets the device to the nRF52840
-if swd: sets the interface to SWD or Serial Wire Debug which is the interface used on the development kit we’re using
-endian little: sets the configuration to little endian
-speed 1000: sets the speed to 1000 Hz or 1 kHz
-port 2331: sets the IP port for the gdbserver to 2331 (you can change it to whatever port number you want, just make sure you change it accordingly in NetBeans
-singlerun: this will configure gdbserver to accept a single connection from gdb, and will exit upon termination of that one debug session
-notimeout: this will disable any timeout waiting for a connection from gdb.Once you run the command you should see an output similar to this:
(Insert picture of terminal session showing the gdbserver creating the session)

Now on the actual debugging!
Here we’ll learn how to debug a target program in real-time and step through the code.
First set a breakpoint in the main() function in main.c (in our example it is located under ble_app_hrs/main.c and the last part of that file.
I set mine at log_init(); 
The way you set a breakpoint is click in the margin on the line number of the desired line.


Now make sure your JLinkGDBServer is running in the terminal and come back to NetBeans.
Note: Reader Mike Wirth pointed out that there are some issues with running JLinkGDBServer in a separate Terminal window. The solution is to run the command from within NetBeans. You can do so by navigating to the menu Window -> IDE Tools -> Terminal and running the command from there (within NetBeans).  
Click the Dropdown menu arrow on the debug button then select “Attach Debugger”.

Make sure the Target is set to: remote localhost:2331 (this is the port we set for the GDB server on the local machine)

Basically, JLink connects to the Interface chip (the chip on the dev kit that creates a mounted drive. It then creates a proxy gdbserver on the local machine that allows a gdb process to connect to and debug the target MCU (in this case the nRF 52840). Once you hit OK, you should see NetBeans connect to the gdbserver and momentarily it’ll stop at the breakpoint you set in the main function. It may take a few seconds before it hits the breakpoint, but eventually the breakpoint line will be highlighted in GREEN.

If you run into issues and don’t see it stop at the breakpoint, try restarting the JLinkGDBServer command
We ran JLinkGDBServer in singlerun mode, which means once you hit the Stop Debug button in NetBeans you will have to start the GDBServer again. To run continuously run the command without the “-singlerun” argument. Then when you stop debugging and initiate the remote debugging again JLink will restart the target.

Note: there are some well-known difficulties and challenges with debugging applications running with the SoftDevice stack. More about it here and here

Logging

The interface MCU also provides a serial output that you can monitor through a terminal program on your development machine. You may have to do a trial and error, for me the serial shows up as “usbmodem1461”. Set the Baud rate at 115200, hit OK then click Connect.

You should see log messages when you connect to the BLE peripheral. For example:


You can increase the log level by modifying the following in sdk_config.h at …./ble_app_hrs/pca10056/s140/config/sdk_config.h

#ifndef NRF_LOG_DEFAULT_LEVEL
#define NRF_LOG_DEFAULT_LEVEL 4
#endif

The default value for NRF_LOG_DEFAULT_LEVEL is 3. The different levels are:
<0=> Off
<1=> Error
<2=> Warning
<3=> Info
<4=> Debug

Summary and Closing

In this tutorial we went over how to set up, install and configure a project in NetBeans to develop for the nRF52840 Preview Development Kit. In the upcoming blog posts I will be going over:

  • More in-depth tutorials for development of actual BLE applications
  • Utilizing the new Bluetooth 5 features
  • Other tutorials for setup and development on other popular BLE dev kits.

Feel free to add any comments or questions in the comments section below. Hope you found this post useful!