sigurdon gravatar image

Posted 2016-07-15 12:19:57 +0100

Getting started with the nRF51 or nRF52 Development Kit

This tutorial will help you get started with a simple BLE service with your new nRF5 Development Kit. The tutorial will explain in detail how to set up and start working with a BLE example project, and how to proceed with testing and using the service. In particular, the tutorial will show how to setup the UART over BLE service.

    No tags

Getting started with nRF5 DK

Requirements

In order to follow this guide, it is necessary to have read and followed the nRF5 DK user guide. The user guide explains the required tools and software, and how to set them up. It also gives a brief explanation of the layout and hardware of the Development Kit, making it easier to follow this tutorial.

Preparing the Development Kit

  • Download and extract nRF5 SDK 12.2

  • Connect the nRF5 DK to the computer with a USB cable

  • Flip the power switch in the bottom left corner to "ON"

Before the DK can be programmed with a user application, it must be flashed with the correct SoftDevice. The SoftDevice is a preprogrammed hex file that contains all the necessary functions to control the radio in BLE mode. These functions are hidden from the user so that all one has to think about is creating the application. Depending on which chip and SDK is being used, the correct Softdevice must be chosen. To determine which Softdevice you need, the following compatibility matrix(nRF51/nRF52) can be used. The differences between the softdevices are listed in the SDK documentation.

For this tutorial we will use SoftDevice s13x, s13x can act in both peripheral and central roles. In order to figure out which SoftDevice is compatible with which SDK version we can consult the compatibility matrix. For nRF51 we will use s130 version 2.0.1 and for nRF52 we will use s132 version 3.0.0 Both are compatible with nRF5 SDK 12.2

Next we need to flash the SoftDevice onto the development kit.

Installing the command line tools

Download and install the command line tools executable.

Open the command line and type:

  • nrfjprog --help

This will list the different input parameters and other help documentation. If the command line reports that it cannot find the program follow the instructions below in Adding PATH Variables.

Adding PATH Variables

Sometimes nrfjprog.exe will not be added to PATH by default, this is how to do it manually. If you are looking for more information on what the PATH variable is, please consult this answer at Superuser.

In windows 7 (for other systems consult the link above) navigate to environment variables by:

  • Pressing: Win+Break

  • Then click on Advanced system settings

  • Click on Environment Variables...

Add the variable to path by clicking the Edit... button

image description

Then add nrfjprog by adding ´;C:\Program Files (x86)\Nordic Semiconductor\nrf5x\bin´ to the end of the variable value for PATH. Make sure that you add a ; between entries in PATH values, i.e. path1;path2.

Then press OK. Now you will be able to see the help dialog when you type nrfjprog --help in a new command line.

Setting up the example

The SoftDevice hex file can be found in

  • nRF 51: ...[YOUR_SDK12.2_LOCATION]\nRF5_SDK_12.2.0_f012efa\components\softdevice\s130\hex
  • nRF 52: ...[YOUR_SDK12.2_LOCATION]\nRF5_SDK_12.2.0_f012efa\components\softdevice\s132\hex

Program the hex file by first erasing and then programming the chip with:

nRF51

nrfjprog --family nRF51 --eraseall
nrfjprog --family nRF51 --program [SOFTDEVICE_LOCATION]\s130_nrf51_2.0.1_softdevice.hex

nRF52

nrfjprog --family nRF52 --eraseall
nrfjprog --family nRF52 --program [SOFTDEVICE_LOCATION]\s132_nrf52_3.0.0_softdevice.hex

If you want to expand on this you can even run these commands directly from Keil, see this blogpost.

Opening the project

In your SDK folder the project can be found in:

  • nRF 51 DK: ..\examples\ble_peripheral\ble_app_uart\pca10028\s130\arm5_no_packs
  • Open the µVision5 Project ble_app_uart_s130_pca10028
  • nRF 52 DK: ..\examples\ble_peripheral\ble_app_uart\pca10040\s132\arm5_no_packs
  • Open the µVision5 Project ble_app_uart_s132_pca10040

If you see the following message, click “yes”.

image description

If you are using the PCA10028 (nRF51 DK) or PCA10040 (nRF52 DK) board you can now compile the code and load the program onto the board. If you are using a different board, however, you must change a definition in the project to make it work as expected.

Preparing the project for a different board

In order to make it easy to port projects between different boards, all projects come with a board support package. In the main.c file, it can be seen that bsp.h is included, which in turn includes boards.h. In the latter file we see some preprocessor directives that check if a certain symbol is defined, and if it is a corresponding header file will be included. These header files are the board-specific files that map the correct pins to the correct external components. For example, on the nRF52 development kit, LED_1 is connected to pin 17, while on the nRF51 development kit, LED_1 is connected to pin 21. Porting a project to a different board is then a matter of simply defining the correct board in the project. In Keil, project defines can be entered in the target options.

  • Go to Projects -> Options for Target, or click the shortcut as shown below

image description

  • In the C/C++ tab, change the BOARD_PCA10028 symbol in the list of Preprocessor Symbols to the board you wish.

  • Click Ok

Compiling and flashing the project

The project can now be compiled and flashed onto the development kit.

  • Go to Project -> Build Target, or press the Build button shown on the left below.

image description

  • When the code has compiled and the board is connected to the computer, click Load as shown above on the right, and the program will be flashed onto the chip. Make sure you have connected the board to your computer with the USB cable. The program is now running, and you should notice LED1 blinking on the board approximately every 2 seconds.

image description

If everything is working as expected, you can move on to the next step, which will show how to test and debug the ble_app_uart application you have built and flashed.

Testing and debugging a BLE service

The ble_app_uart project does two things that we can easily test. First, it sets up a wired UART connection between the kit and the computer, via the USB cable. Then it sets up an UART BLE service that we can connect to. Whatever is sent from the computer to the kit is relayed to the connected device, and vice versa. In other words, the kit works as a wireless bridge between the device and the computer.

image description

Setting up a terminal

In order to communicate with the nRF5 via UART, we will need to set up a terminal on our computer. The command prompt in Windows can be used, but is very troublesome to use. There are several different third-party programs that are suited, and this tutorial will be using Termite. Download and install the latest version, and you are ready.

In order to connect to the DK we have to select the correct COM-port in Termite. First of all, connect the nRF5 DK running the ble_app_uart project to your computer. Open up Termite and click settings. Depending on what devices you have on your computer, you might have several choices, as shown below.

image description

To find the correct port, follow these steps:

  • Go to the start-menu in Windows, and type devmgmt.msc to open Device Manager.

  • Scroll down and expand Ports (COM & LPT)

  • Find the Port named JLink CDC UART Port, and note the number in the paranthesis.

  • If you have more than one Jlink UART Port, unplug the one you want to use, plug it back in, and observe which one that appeared last.

Go back to Termite and select the correct port. The default UART settings in the ble_app_uart project use a baud-rate of 115200 and RTS/CTS flow control. The rest of the settings are default (8 data bits, 1 stop bit, no parity). Because the project uses RTS/CTS hardware flow control (HWFC), the terminal must send an RTS (Ready To Send) signal to the DK before they can start communication. There are two ways to handle this problem; turn off hardware flow control in the development kit, or configure the terminal to use hardware flow control. Both methods will be discussed here.

Method one - Configuring HWFC in Termite

  • Make sure the DK is connected to the computer, and the ble_app_uart project is running. (LED 1 should be blinking if you followed the previous tutorial)

  • In Termite, connect to the correct COM port with the settings described above

  • In Termite, go to settings, and under Plug Ins, enable Status LEDs. Click OK

  • Click on the dark green rectangle above RTS to set this signal high.

  • The text Start... should now appear in the window below.

image description

Method two - disabling HWFC in the project

  • Open the ble_app_uart project

  • In the main file, find the uart_init function

  • In the comm_params struct, change the fifth variable from APP_UART_FLOW_CONTROL_ENABLED to APP_UART_FLOW_CONTROL_DISABLED

It should now look like this:

const app_uart_comm_params_t comm_params =
      {
          RX_PIN_NUMBER,
          TX_PIN_NUMBER,
          RTS_PIN_NUMBER,
          CTS_PIN_NUMBER,
          APP_UART_FLOW_CONTROL_DISABLED,
          false,
          UART_BAUDRATE_BAUDRATE_Baud115200
      };
  • In Termite, go to settings and set flow control to none.

  • Rebuild the project and flash it to the DK

  • The text Start... should now immediately appear in Termite

You have now verified that the project is running and is successfully sending on UART!

Next, we can test the BLE capabilities and check if we can connect to the device and use it as intended.

Connecting to the nRF5 DK

There are several ways in which we can connect to the DK. Two of them will be discussed here, namely with either a mobile device, or the nRF51 Dongle.

Using a mobile device

If you have a device that supports BLE, you can download the nRF Toolbox app from Google Play, or App Store if you are on iOS.

  • Download and install nRF Toolbox

  • Open nRF Toolbox, and click UART

  • Make sure the nRF5 DK is running the ble_app_uart project (LED1 should be blinking every 2 seconds, indicating that it is advertising)

  • Click Connect

  • If you didn't change the device name in the project, Nordic_UART should appear on the list of available devices

  • Click on Nordic_UART

  • If everything went well, swipe right inside the app, and you will see something like below:

image description

  • In Termite, you can now type anything in the bottom textbox, and send it to the DK

  • The text will then be sent by the DK, to your device, and display the text in the nRF Toolbox UART app

image description

image description

Congratulations! You have now tested the ble_app_uart project and verified that it works!

Using the nRF51 Dongle

If you have the nRF51 Dongle, you can use it to connect to the nRF5 DK.

  • Plug in the dongle in a USB port in your computer

  • Open the Master Control Panel, and select the COM-port for the Dongle.

  • If the Log says No response from master emulator you will need to flash the dongle with the latest Master Emulator Firmware:

  • Go to File -> Flash programming and click Program

image description

It should now look like below

image description

  • Click Start Discovery

  • If the ble_app_uart project is running on the DK, you should see Nordic_UART under discovered devices in the master control panel

  • Click on Nordic_UART, and then click Select Device

  • Click Connect, and if it was successful, click Discover Services

  • Click Enable Services so the DK is allowed to send notifications to the Master Control Panel

The Service Discovery panel in the Master Control Panel should now look like this: image description

The two devices are now connected and ready to communicate. The two interesting characteristics are UART TX and UART RX in the "UART over BLE" service. These are seen from the DK's perspective, so the TX line is what is being transmitted from the DK, to the dongle, and the RX line is the other way around. You can now try the following:

  • In Termite, send some text to the DK by entering it in the bottom text-field, and press enter (make sure Append LF is checked in Termite settings)

  • In the Master Control Panel, observe that the TX Characteristic has changed to the text you just sent. (note: if you send more than 20 bytes, only the last 20 bytes will be seen in the characteristic)

For example, if you enter the text "Hello" in termite, you will see the following in Master Control Panel:

image description

The values are hexadecimal, and a quick lookup in the ASCII table reveals the letters H (0x48) e (0x65) l (0x6C) l (0x6C) o (0x6F). 0x0A is the new-line character that was appended at the end of the text by Termite. To see why this character is required, you can inspect the UART0_IRQHandler function in the main file in the ble_app_uart project.

Now we can try sending some text the other way, by writing to the RX characteristic.

  • In Master Control Panel, click on the UART RX characteristic.

  • In the Value field below, select text, enter some text, and click Write

image description

The same text should now appear in your Termite window

image description

Final notes and further reading

Now that you have set up and run your first example your are ready to continue development. Check out the tutorial section here on DevZone for specific examples. If you encounter troubles try searching DevZone and see if someone has had and/or fixed the problem before, create a question if you can't find anything.

14 comments

andrewst93 gravatar image

Posted Nov. 25, 2016, 2:23 a.m.

I'm trying to recreate this tutorial and I get the connection between my iOS app and termite and I can send data but it only appears as just bytes like this (0x00000001706424b0) and not ASCII characters. I am using the SDK 12.1 on the NRF52DK and not really sure what to provide that will help to solve this problem, brand new to microcontrollers and the NRF52DK system overall.

Thanks!

jhewitt gravatar image

Posted Dec. 8, 2016, 11:41 p.m.

Got this working on android and with nRF51 Dongle, so thanks! Still feel like I'm wandering around in the swamp though.

SergeyP gravatar image

Posted Dec. 11, 2016, 8:54 a.m.

Yeah, I am also experiencing issues with the iOS application but my experience was better with the Android app, the only issue I am seeing is that commands sent from the Termit do not always reach to the Android app or reach with a big delay. The best experience I had with the dongle - it just works with no problems/delays.

Gerstalexej gravatar image

Posted Jan. 13, 2017, 3:29 p.m.

I'm using the nrf52-DevKit and the app on ios.

It says

Connecting to: Nordic_HRM... centralManager.connect(peripheral, options:nil)

[Callback] Central Manager did connect peripheral

Connected to: Nordic_HRM Discovering services...

peripher.discoverServices([some Mac address])

[Callback] Central Manager did disconnect peripheral

Error Code: Unknown error

Note that the device is called Nordic_HRM in the app and not Nordic_UART.

When clicking the load button in Keil, termite shows "UART Start!" but nothing more.

What am I doing wrong?

EDIT: It works as expected on Android, just tested it out. Why does it behave differently on ios?

Quark Li gravatar image

Posted March 2, 2017, 6:42 p.m.

Hi,

I followed the tutorial but encountered trouble as the following. When I use nRF Toolbox on Android to connect to Nordic_UART whcih is running the ble_uart_app with LED blinking every 2 seconds, it connected to BLE,

Connected to [...] Discovering Services.. gatt.discoverServices() Discovering Services.. gatt.discoverServices() [Callback] Connection state changed with status: 0 and new state: 0 (DISCONNECTED) Connectin Lost [Callback] Connection state changed with status: 0 and new state: 2 (CONNECTED)

then keep repeating the above log. What could possibly be the problem? Thanks!

==== Update ==== I tried to use nRF Connect (Android) instead of nRF Toolbox. It works fine in nRF Connect. If I connected to nRF52DK, I can see Nordic UART Service as Primary Service and I can send and receive messages in the UART service. I assume there is some problem with nRF Toolbox (Android).

gokhangocmen94 gravatar image

Posted March 10, 2017, 12:25 p.m.

Hello.

I want to apply this application without using USB cable and create virtual COM PORT on my PC. I can use ft232rl for this. How Can I do this ?

sigurdon gravatar image

Posted March 10, 2017, 12:34 p.m.

For new questions unrelated to the tutorial, please post a new question here: https://devzone.nordicsemi.com/questions/ask/

Reeshma gravatar image

Posted March 31, 2017, 8:47 a.m.

HI sigurd, Can you please tell me , what changes will i need to made in order to send the data from uart to ble in ble_app_uart example code of nrf52832 SDK 13.0...?? In the above example code , i can able to send the data from ble app in android to the serial monitor window

Posted April 16, 2017, 7:23 a.m.

Sigurd,

First, thank you for a great tutorial! It was very easy to follow and everything worked great up to the point in which I wanted to transfer data back and forth from my phone to the Termite application.

I am using board PCA10056 with Android device and I have tried both the nRF Toolbox and the nRF Connect apps.

I am able to get the code to load properly and LED 1 blinks every couple seconds. I can find the Nordic_UART device and can "connect" to it but then it gives me two different errors

Error:(0x16): GATT CONN TERMINATE LOCAL HOST Error:(0x8): GATT CONN TERMINATE LOCAL HOST After which the Connection is lost.

Posted May 25, 2017, 9:24 p.m.

Hello,

I am trying to follow the tutorial with using SEGGER Embedded Studio. I am able to compile the project ble_app_uart_s130_pca10028 and download it. Such that it shows

J-Link: Flash download: Total time needed: 6.279s (Prepare: 0.046s, Compare: 0.000s, Erase: 6.225s, Program: 0.000s, Verify: 0.000s, Restore: 0.007s)
Preparing target for download
  Executing script TargetInterface.resetAndStop(1000)
Programming 25.8 KB of addresses 00000000 -- 00006733
Programming 0.0 KB of addresses 00006734 -- 0000673d
J-Link: Flash download: Flash programming performed for 1 range (26624 bytes)
J-Link: Flash download: Total time needed: 0.618s (Prepare: 0.090s, Compare: 0.023s, Erase: 0.000s, Program: 0.443s, Verify: 0.002s, Restore: 0.058s)

However, the LED1 doesn't turn on. The pca10028.h file defines the LED_1 as 21 #define LED_1 21.

How could I track the issue?

Thank you

sigurdon gravatar image

Posted May 29, 2017, 5:14 p.m.

Hi julio cesar,

Please take a look at the Segger Embedded Studio blog post here:

https://devzone.nordicsemi.com/blogs/1032/segger-embedded-studio-a-cross-platform-ide/

soyeon gravatar image

Posted Sept. 27, 2017, 7 p.m.

Can I use this tutorial in nRF51822 Evaluation Kit?

Thank you.

KIKI gravatar image

Posted Oct. 20, 2017, 10:10 a.m.

Hello! I am working on the nRF52840 and IOS 'nRF Toolbox'. I can see the LED1 blinky and then when I open the 'nRF Toolbox', click 'UART', I could only find a device named 'Nordic_Prox', connect it the LED1 keeps lighting. But through log from my handphone, it says 'connecting to : Nordic_Prox' and 'No UART connected'.

I don't know how to deal with this, could any friends give me some guidance? Thank you very much!

XPC_summer gravatar image

Posted Dec. 8, 2017, 6:41 a.m.

Hi, thanks for the detailed tutorial, but when I was compiling the project (I am using PCA10028), it was not successful and KEIL5 display this: image description

it looks like I didn't install NordicSemiconductor.nRF_DeviceFamilyPack.8.11.1.pack according to the message (in fact, I already installed NordicSemiconductor.nRF_DeviceFamilyPack.8.15.0.pack). Then I downloaded NordicSemiconductor.nRF_DeviceFamilyPack.8.11.1.pack from KEIL and complied it again, it was still not successful, and KEIL5 display this: image description

it looks like 8.11.1 pack is not suitable for my board? how can I fix this problem? Thanks a lot!

Sign in to comment.

Related posts by tag

No results