lab11 / nrf5x-base

Starting point and shared code for Nordic nRF5x BLE platforms.

Nordic nRF5x Support Files

This repository is a starting point and shared code for Nordic nRF5x BLE platforms. This repo is a collection of libraries, SDKs, Softdevices, and Makefiles to be included within other projects using the Nordic platfroms. Pull requests welcome.

The currently supported SDK versions are: 9.0.0, 10.0.0, 11.0.0, 12.2.0.

The currently supported Softdevice versions are: s110_7.3.0, s110_8.0.0, s120_2.1.0, s130_1.0.0, s130_2.0.0, s130_2.0.1.

Usage

First, add this project as a submodule inside of your repo with your nRF5x code.

git submodule add https://github.com/lab11/nrf5x-base

Then write an application for the nRF5x SoC you are using and include a Makefile that looks like this:

PROJECT_NAME = $(shell basename "$(realpath ./)")

APPLICATION_SRCS = $(notdir $(wildcard ./*.c))
# Various C libraries that need to be included
APPLICATION_SRCS += softdevice_handler.c
APPLICATION_SRCS += ble_advdata.c
APPLICATION_SRCS += ble_conn_params.c
APPLICATION_SRCS += app_timer.c
APPLICATION_SRCS += ble_srv_common.c
APPLICATION_SRCS += app_util_platform.c
APPLICATION_SRCS += nrf_drv_common.c
APPLICATION_SRCS += nrf_delay.c
APPLICATION_SRCS += led.c
APPLICATION_SRCS += simple_ble.c
APPLICATION_SRCS += simple_adv.c
# Add other libraries here!

# platform-level headers and source files
LIBRARY_PATHS += ../../include
SOURCE_PATHS += ../../src

# Set the softdevice needed for the application
SOFTDEVICE_MODEL = s110

# Include the main Makefile
NRF_BASE_PATH ?= ../../nrf5x-base
include $(NRF_BASE_PATH)/make/Makefile

An example Makefile is included in this repo as Makefile.example. Copy to your own application directory and modify as desired.

Generally, the expected directory structure for your project is:

    /apps
        /<application 1>
        /<application 2>
        ...
    /src
        various platform-level code (e.g. functions shared between applications)
    /include
        various platform-level headers (e.g. platform pin mappings)
    /nrf5x-base (submodule)

Example Applications

This repo has several example and test applications. See the apps folder.

Supported Features

There are libraries for many common BLE functions in this repo:

• simple_ble: Quick interface to most common BLE functions
  • BLE Advertisements
    • Device name only
    • Manufacturer data
    • Eddystone
    • Rotating multiple advertisements
  • BLE Services
• SQL style database (LittleD)
• RTT Debugging
• Nordic BLE Serialization
• Nordic DFU over-the-air reprogramming.

Program a nRF51822

To flash an application to a nRF51822 BLE chip, there is some setup you must do.

1. Install the arm-none-eabi-gcc compiler.

   On Ubuntu:

    sudo add-apt-repository ppa:team-gcc-arm-embedded/ppa
    sudo apt-get update
    sudo apt-get install gcc-arm-embedded
   

2. Install the JLink software for your platform. You want the "Software and documentation pack".

3. Acquire a JLink JTAG programmer. The "EDU" edition works fine.

4. Program an app! With the JLink box attached to the target board:

    make flash
   

   will write the app and softdevice to the nRF51822. You can erase a chip with:

    make erase-all
   

   See the make folder for a complete list of commands.

   Most of our boards use a TagConnect header instead of the way-too-large ARM JTAG header. We use our own adapter, but Segger also makes one.

5. Upon inital programming, the nRF will enter debug mode, which will prevent the nRF from sleeping and prevent the reset line from working. To fix this, either perform a powerdown/powerup or download nrfjprog from (https://www.nordicsemi.com/eng/Products/Bluetooth-low-energy/nRF51822) and run nrfjprog --pinreset

Git Submodules

If you're using submodules in your project, you may want to use this to make git automatically update them: https://gist.github.com/brghena/fc4483a2df83c47660a5

BLE Tools for Other Platforms

When developing a BLE application, several tools exist to make your life easier. The easiest option, if you have access to an android phone, is nRF Master Control Panel. On iOS, LightBlue Explorer has similar or better functionality. Alternatively, noble is a NodeJS library for interacting with BLE that can run from a Linux or Mac computer.

Example Platforms Using nRF5x-base

• Squall
• BLEES
• Nucleum
• PolyPoint
• PowerBlade

License

The files in this repository are licensed under the MIT License unless otherwise noted by the local directory's README and license files.

nrf5x-base's Issues

Compile for nRF51 and nRF52

Does anyone knows if it’s possible to compile using SDK11 to both platforms?

On SDK 11 & 12 blank SoftDevice is impossible

For SDK11 and 12 softDevice is forced by the makefile.

What BLE gateway APIs do you need?

To guide what gateway infrastructure we need, it might be useful to start with what APIs we would like to be able to use at the application layer. These APIs would likely be the top layer in a cloudcomm-like system, where the running application offloads data to a gateway subsystem. That gateway library ("gwlib") would then likely store the data until it can offload it to a gateway, which would then forward the data on somehow. Now, there are quite a few different designs that could work here.

Some thoughts:

1. Something simple

Setup a URL at boot and then just write data. The endpoint at the given URL will get HTTP posts with the data.

void gwlib_init (char* url);
void gwlib_write (uint8_t* buf, uint32_t len);

2. More like files:

This makes gwlib also capable of storing the data. Each create() creates a "file" which can then be removed after it is offloaded or kept until delete() is called.

void gwlib_init (char* url);
int gwlib_create (uint8_t* buf, uint32_t len, bool persistent);
void gwlib_delete (int file);

3. The HTTP option

Instead of a log-type abstraction, what about an HTTP-like abstraction? This would let the app issue HTTP POSTs that, when a gateway was in contact, would be issued by the gateway, with a callback being called when the POST completed. This provides a lot more flexibility, but does change the abstraction.

void gwlib_post (char* url, uint8_t* buf, uint32_t len, post_callback_f callback);

Others?

There are many possibilities for this, and these are certainly not all of them. What would be most useful for you?

Add support for turning on and off debug

We should be able to use RTT when debugging, and then disable it when things work.

Add prettier make output

It's a little annoying to scroll through all the lines of output when we include so many folders in compilation. Also need to add a way to get the full output back.

Remove softdevice folder

Instead use the softdevice binaries in the sdk folders, like:

https://github.com/lab11/nrf5x-base/tree/master/sdk/nrf51_sdk_11.0.0/components/softdevice/s130/hex

(solved, need feedback) Can't figure out how to link gzll_nrf51_gcc.a with s130

I'm trying to use the gazell library with the s130 softdevice (s210 only works on nrf51422).

Without changing anything, I can't find the gazell header files. That's an easy fix:

LIBRARY_PATHS += $(SDK_INCLUDE_PATH)proprietary_rf/gzll

now the application compiles, but cannot link. Specifically:

_build/main.o: In function `main':
main.c:(.text.startup.main+0x70): undefined reference to `nrf_gzll_init'
main.c:(.text.startup.main+0x76): undefined reference to `nrf_gzll_set_base_address_0'
main.c:(.text.startup.main+0x7a): undefined reference to `nrf_gzll_enable'
collect2: error: ld returned 1 exit status

I believe this is because neither gzll_nrf51_gcc.a nor gzll_nrf51_sd_resources_gcc.a are being linked in.

nm -a shows nrf_gzll_init is within the former static library:

$ arm-none-eabi-nm -a nrf5x-base/sdk/nrf5_sdk_12.2.0/components/proprietary_rf/gzll/gcc/gzll_nrf51_gcc.a  | grep nrf_gzll_init
00000658 T nrf_gzll_init

I've momentarily hacked in the following:

LDFLAGS += -L $(SDK_PATH)components/proprietary_rf/gzll/gcc -l:gzll_nrf51_gcc.a

I'm now running into an issue I don't know how to resolve:

$ make V=1
BUILD OPTIONS:
  SoftDevice  s130
  SDK         12
  nRF         nrf51422
  RAM         16 kB
  FLASH       256 kB
  Board       BOARD_NULL

arm-none-eabi-gcc -mthumb -mcpu=cortex-m0 -march=armv6-m -L ../../nrf5x-base/make/../make/ld -T ../../nrf5x-base/make/../make/ld/gcc_nrf51_s130_2.0.1_16_256.ld -Wl,--gc-sections -Wl,-Map=_build/gzl_s130.Map -L ../../nrf5x-base/make/../sdk/nrf5_sdk_12.2.0/components/proprietary_rf/gzll/gcc -l:gzll_nrf51_gcc.a _build/startup_nrf51.os _build/system_nrf51.o _build/main.o _build/softdevice_handler.o _build/app_util_platform.o _build/app_error_weak.o _build/app_timer.o _build/app_error.o _build/nrf_drv_common.o _build/nrf_drv_clock.o _build/led.o  -o _build/gzl_s130.elf
_build/main.o: In function `main':
main.c:(.text.startup.main+0x70): undefined reference to `nrf_gzll_init'
main.c:(.text.startup.main+0x76): undefined reference to `nrf_gzll_set_base_address_0'
main.c:(.text.startup.main+0x7a): undefined reference to `nrf_gzll_enable'
collect2: error: ld returned 1 exit status

It's finding the library (if I change the path or the name of the library, it rightfully complains) but it does not seem to be linking it in.

Any suggestions?

S130 SoftDevice Linking

The current linker script for the S130 device did not work for me with a custom nrf51822_XXAC board. The mem locations below did work, gleaned from the S130 spec. Has anyone else had this problem?

/* S130  Linker script to configure memory regions. */
MEMORY
{
  FLASH (rx) : ORIGIN = 0x0 + 108K + 4K, LENGTH = 256K - 112K /* 112 kB is taken by S130, 144 kB for app. */
  RAM (rwx) : ORIGIN = 0x20000000 + 10K, LENGTH = 32K - 10K /* 10 kB is taken by S130, 22 kB for app. */
}
INCLUDE "gcc_nrf51_common.ld"

Windows vs Posix detection behaves incorrectly under cygwin

Cygwin should use the posix variations, not the windows ones.

---

Needs to be fixed in two places:

but now I get this error:

$ make
BUILD OPTIONS:
  SoftDevice  s130
  SDK         11
  nRF         nrf51822
  RAM         16 kB
  FLASH       256 kB
  Board       BOARD_NULL

/bin/sh: -c: line 1: syntax error: unexpected end of file
nrf5x-base//make/Makefile:889: recipe for target '_build/system_nrf51.o' failed
make: *** [_build/system_nrf51.o] Error 1


Hrm.. that's weird, but I have a guess -- I assume you're building this in cygwin?

Edit nrf5x-base/make/Makefile
Delete lines 867, 868, 869, and 871
  (force it to include Makefile.posix)

I'm guessing it's incorrectly thinking you're building in a windows environment



A little better..

$ make
BUILD OPTIONS:
  SoftDevice  s130
  SDK         11
  nRF         nrf51822
  RAM         16 kB
  FLASH       256 kB
  Board       BOARD_NULL

  CC        nrf5x-base//make/../sdk/nrf51_sdk_11.0.0/components/toolchain/system_nrf51.c
  CC        main.c
  CC        goc.c
  CC        uart.c
  CC        nrf5x-base//make/../sdk/nrf51_sdk_11.0.0/components/libraries/timer/app_timer.c
  CC        nrf5x-base//make/../sdk/nrf51_sdk_11.0.0/components/libraries/util/app_error.c
  CC        nrf5x-base//make/../sdk/nrf51_sdk_11.0.0/components/libraries/util/app_util_platform.c
  CC        nrf5x-base//make/../sdk/nrf51_sdk_11.0.0/components/drivers_nrf/common/nrf_drv_common.c
In file included from nrf5x-base//make/../sdk/nrf51_sdk_11.0.0/components/drivers_nrf/common/nrf_drv_common.c:14:0:
nrf5x-base//make/../sdk/nrf51_sdk_11.0.0/components/drivers_nrf/common/nrf_drv_common.h:20:28: fatal error: nrf_drv_config.h: No such file or directory
compilation terminated.
nrf5x-base//make/Makefile:889: recipe for target '_build/nrf_drv_common.o' failed
make: *** [_build/nrf_drv_common.o] Error 1



Ugh..

Same problem in lines 9-13 of:
nrf5x-base/sdk/nrf51_sdk_11.0.0/components/toolchain/gcc/Makefile.common

Looks like that should be the only other place where it's choosing platforms

Question; Is the current makefile manage C++ (.cpp) file ?

Update blink app to SDK 11

It's languishing at SDK 9 right now. Not super helpful.

ADC reading

Hello there, I know it's a little bit old, but was wondering if there is a tiny example on how to read adc from a pin, I tried adding these headers but failed to compile.

#include "nrf_log.h"
#include "nrf_log_ctrl.h"
#include "nrf_log_default_backends.h"

Greetings!

Request: configure entire BLE address in simple_ble

Sometimes a random address isn't the right solution, and a way to pass in the full address would be helpful.

Enable individual GCC optimization flags

Currently, most make files already include an initial CFLAGS += -Os to optimize for binary code size. To make sure that this is always the case, the same step is repeated in /make/Makefile, line 237.

The issue with the current implementation is that developers in fact do not have the freedom to choose their optimization level. As GCC only takes the last optimization flag into consideration, anything declared in the local make file will be ignored. Apart from being a bug, this behaviour is especially a nuisance when trying to debug, as any locally defined -Og flag is ignored. Of course, this can be solved by manually deleting the optimization flag overwrite in /make/Makefile.

As an easy solution, I propose changing line 237 from CFLAGS += -Os to CFLAGS ?= -Os , as this will only be used if CFLAGS has not been defined (possibly with a different optimization flag) before. Of course, this might result in no optimization flag if the developer declares CFLAGS and forgets to add an optimization level himself; however, in my view such a change is in the responsibility of the developer and not this repo.

Simple BLE: add function to change connection interval

Would be useful

Add a library for timer calls

Should be able to make it so much easier than it is now. Something like:

start_timer(1000, my_func);

DFU doesn't rebuild with new Makefile parameters

The problem the DFU bootloader can remain built and compile with your app even if the settings invalidate the LD file it was built with (16 KB RAM for example).

Replication:

• Have an app (such as BLEES) checked out with nrf5x-base as a submodule
• Build an app in the nrf5x-base submodule with dfu
• Go to an app back in the main repository that has invalid settings and build it
• App builds and includes the bootloader that was built with the wrong LD file

@nealjack

How to build for both SDK12 (nrf51) and SDK15 (nrf52)?

Less an issue, but not sure how else to raise the question.

I'd like to be able to develop for both nrf51 and nrf52 devices without having two copies of nrf5x-base checked out. I'm not trying to use the same source code to build for both (although that would be nice) but rather just to have apps/nrf51_foo and apps/nrf52_bar and be able to build both using the nrf5x-base submodule.

Is this an eventual goal? I understand that nrf52 support is currently in its own branch. Is the intention to eventually have both supported in master?

`ble_gap_adv_params_t` changed as of SDK 11

simple_ble.c incorrectly initializes the ble_gap_adv_params_t struct when used with SDK 11/S130. There are more fields that didn't exist before.

License for simple_ble simple_adv and other nrf5x-base code

Which license is the nrf5x-base project under?
I would like to use in commercial hardware and contribute some small features back but cannot use beyond prototyping until a license is known.

simple_add_charactierstic arguments should be booleans and better named

the first four parameters (read, write, notify, vlen are uint8_t but appear to be just booleans. Also, vlen is poorly named, since it's whether or not the characteristic is variable length and not an actual length.

Check if softdevice is programmed

Not sure if there is an easy way to do this (or any way) but it would be AWESOME if the flashing scripts would run make from-scratch automatically for you if the softdevice hasn't been programmed because I ALWAYS forget to.

simple_ble does not support SDK 12

I'm either missing something or app_trace on which simple_ble depends has apparently been removed from SDK 12.

  CC        ../../make/../lib/simple_ble.c
../../make/../lib/simple_ble.c:19:23: fatal error: app_trace.h: No such file or directory
 #include "app_trace.h"
                       ^

Implement IoT Gateway as a library

The key function from https://github.com/lab11/iot-gateway/blob/master/squall/software/apps/iotgw/main.c should be added as function in the /advertisement folder.

(nrf52832 branch) - cannot use two UARTEs

On the nRF52840 there are two UARTEs but the nrf52840_peripherals.h file says there are two UARTEs and a single UART. This isn't entirely correct -- the UART is at address 0x40002000, and UARTE0 is at the same address (UARTE1 is at 0x40028000).

Anyway -- since nrf52840_peripherals.h says there is a UART and two UARTEs, the macros at the top of nrf_drv_uart.h will define both NRF_DRV_UART_WITH_UARTE and NRF_DRV_UART_WITH_UART, which causes the build to fail because there's no way to say "two UARTEs and one UART" so it tries to instantiate two UARTs.

How to recreate:
Set up a project where you want to use two UARTEs. I believe the correct app_config.h stanzas are as follows:

#define UART_ENABLED 1
#define UART0_ENABLED 1
#define UART1_ENABLED 1
#define UART_EASY_DMA_SUPPORT 1

In the SDK, apply_old_config.h will take these defines and define NRFX_UARTE_ENABLED, NRFX_UARTE0_ENABLED and NRFX_UARTE1_ENABLED. nrf_drv_uart.h will set up for two UARTEs since UARTE_PRESENT is defined in nrf52840_peripherals.hand also becauseapply_old_config.hcreatedNRFX_UARTE_ENABLED`

This is all perfect until you realize that nrf_drv_uart.h also defines NRF_DRV_UART_WITH_UART since the peripherals.h file says there is a UART as well as two UARTEs.

I believe this is an error, as the nRF52840 has a total of two UART devices with DMA, not three (two with DMA and one without). I think the correct fix is to modify nrf52840_peripherals.h but before I create a PR I wanted to run this by you.

ST-Link support

Would you be interested in a PR with some preliminary ST-Link support? I currently have erasing and flashing (and softdevice flashing) functional (that is, no MAC changing or debugging yet).

• "basic" targets: flash, reset, erase: #20
• "advanced" targets: flash bootloader, DFU, pin-reset

(nrf52832 branch) trying to build uart app, multiple definition of UARTE0_UART0_IRQHandler?

Using commit:4c13fd06 (before the Makefile rewrite that seems to be currently broken).

I'm trying to port an SDK12 application on nrf51 over to nrf52.

sdk_config.h seems to need both UARTE and UART enabled or it just flat out won't build.

NRFX_UARTE_ENABLED 1
NRFX_UARTE0_ENABLED 1
NRFX_UART_ENABLED 1
NRFX_UART0_ENABLED 1

This seems wrong, but ok. Everything builds now, but fails to link, claiming that there are multiple definitions of UARTE0_UART0_IRQHandler (in both nrfx_uarte.c and nrfx_uart.c).

I'm getting lost in the C preprocessor macro maze trying to resolve this.

I've added the following in my Makefile:

APPLICATION_SRCS += app_fifo.c
APPLICATION_SRCS += app_uart_fifo.c
APPLICATION_SRCS += nrf_drv_uart.c
APPLICATION_SRCS += nrfx_uart.c
APPLICATION_SRCS += nrfx_uarte.c

If I leave any of those out, it fails to build due to missing functions.

Any guidance would be very much appreciated.

Add BLE address loading to library

Loading BLE addresses from flash has been left to the applications to do, and really ought to be pulled into the library. ble_init ought to check the flash region and act if it sees an address there.

correct way to use app_usbd?

With SDK15 and the nRF52840, what is the correct way to include the USBD (specifically the CDC/ACM class) component?

I started by adding

SDK_HEADER_PATHS += $(SDK_ROOT)components/libraries/usbd/
SDK_HEADER_PATHS += $(wildcard $(SDK_ROOT)components/drivers_nrf/usbd/)

in the SDK's make/Includes.mk, but I know this is the way for much wailing and gnashing of teeth. Besides, it looks like I'm going to have to also include a whole bunch more (components/libraries/usbd/class/cdc, components/libraries/class/cdc/acm, etc.)...

Ideally this should be in the apps/my_app/Makefile, but I think you're trying to steer us into doing this in the Boards/board_name/Build.mk which feels weird (it's not a board-specific thing, it's an app-specific thing)...

Question: downloaded_test.bin, how it is working

Someone can explain a little more how this "check" part is working ?

we are downloading from the target the downloaded_test.bin ?
We are comparing it with softdevice_test.bin ? (where this last file comes from ? )

then in my case:

• erase all with erase-all.jlink
• flash soft_device with flash-softdevice.jlink (flash the binary s110_softdevice.bin)
• then flash the application (nRF51_app_s110.hex ) with flash.jlink

device not visible when using ENABLE_WIRELESS_DFU=1

even examples that already have ENABLE_WIRELESS_DFU=1, as service-example render device not visible (not advertising?).
Removing that line everything works ok.
I'm using nRF51822xxaa (16K, 256K)

just changed:

NRF_IC=nrf51822
RAM_KB=16
FLASH_KB=256

RAM restitution between app and bootloader is not working

Currently, application might overwrite part of the address because it does not recognize the upper six bytes of memory as reserved and may overwrite with a variable.

no support for nrf51 in SDK14

The Makefile specifically omits nrf51 support when SDK 14 is selected. If I omit this specific check my test code seems to work fine with SDK 14.