nes-proj/platform/nrf52dk/README.md

Contiki for nRF52 Development Kit

This guide's aim is to help you with using Contiki for Nordic Semiconductor's nRF52 DK.

The port depends on Nordic Semiconductor IoT SDK for nRF52. The IoT SDK contains source code and libraries which are required for successfull port compilation. It also contains SoftDevice binary driver which is required for BLE operation. See prerequisites section for details on how to set up the SDK.

For more information about SoftDevice please refer to the SDK docummentation [nRF52 Datasheet and SDK documentation].

This port supports DK versions PCA10040 and PCA10036.

Port Features

The following features have been implemented:

• Support for IPv6 over BLE using Contiki 6LoWPAN implementation
• Contiki system clock and rtimers (using 32kHz and 1MHz timers)
• UART driver
• Watchdog driver
• Hardware RNG
• Temperature sensor driver
• DK LED driver
• DK Buttons driver
• Real Time Transfer (RTT) I/O support

Note that this port supports only IPv6 network stack.

The port is organized as follows:

• nRF52832 CPU and BLE drivers are located in cpu/nrf52832 folder
• nRF52 Development Kit drivers are located in platform/nrf52dk folder
• Platform examples are located in examples/nrf52dk folder

Prerequisites and Setup

In order to compile for the nRF52 DK platform you'll need:

• nRF5 IOT SDK https://developer.nordicsemi.com

  Download nRF5 IOT SDK, extract it to a folder of your choice, and point NRF52_SDK_ROOT environmental variable to it, e.g.,:

  wget https://developer.nordicsemi.com/nRF5_IoT_SDK/nRF5_IoT_SDK_v0.9.x/nrf5_iot_sdk_3288530.zip
  unzip nrf5_iot_sdk_3288530.zip -d /path/to/sdk
  export NRF52_SDK_ROOT=/path/to/sdk
  

• An ARM compatible toolchain The port has been tested with GNU Tools for ARM Embedded Processors version 5.2.1.

  For Ubuntu you can use package version provided by your distribution:

  sudo apt-get install gcc-arm-none-eabi
  

  Alternatively, install the toolchain from PPA to get the latest version of the compiler: https://launchpad.net/~team-gcc-arm-embedded/+archive/ubuntu/ppa

  For other systems please download and install toolchain available at https://launchpad.net/gcc-arm-embedded

• GNU make

• Segger JLink Software for Linux https://www.segger.com/jlink-software.html

  This package contains tools necessary for programming and debugging nRF52 DK.

  For Ubuntu you can download and install a .deb package. Alternatively download tar.gz archive and extract it to a folder of your choice. In this case you need to set NRF52_JLINK_PATH environmental variable to point to the JLink tools location:

  export NRF52_JLINK_PATH=/path/to/jlink/tools
  

  To keep this variable set between sessions please add the above line to your rc.local file.

  In order to access the DK as a regular Linux user create a 99-jlink.rules file in your udev rules folder (e.g., /etc/udev/rules.d/) and add the following line to it:

  ATTRS{idProduct}=="1015", ATTRS{idVendor}=="1366", MODE="0666"
  

  When installing from a deb package, the 99-jlink.rules file is added automatically to /etc/udev/rules.d folder. However, the syntax of the file doesn't work on newer udev versions. To fix this problem edit this file and replace ATTR keyword with ATTRS.

To fully use the platform a BLE enabled router device is needed. Please refer to Preqrequisites section in README-BLE-6LoWPAN.md for details.

Getting Started

Once all tools are installed it is recommended to start by compiling and flashing examples/hello-word application. This allows to verify that toolchain setup is correct.

To compile the example, go to examples/hello-world and execute:

make TARGET=nrf52dk

If you haven't used the device with Contiki before we advise to erase the device and flash new SoftDevice:

make TARGET=nrf52dk erase
make TARGET=nrf52dk softdevice.flash

If the compilation is completed without errors flash the board:

make TARGET=nrf52dk hello-world.flash

The device will start BLE advertising as soon as initialized. By default the device name is set to 'Contiki nRF52 DK'. To verify that the device is advertising properly run:

sudo hcitool lescan

And observe if the device name appears in the output. Also, observe if LED1 is blinking what indicates that device is waiting for a connection from BLE master.

If device is functioning as expected you can test IPv6 connection to the device. Please refer to README-BLE-6LoWPAN.md on details how to do this.

Examples

Examples specific for nRF52 DK can be found in examples/nrf52dk folder. Please refer to README.md in respective examples for detailed description.

The DK has also been tested with the examples/hello-world and examples/webserver-ipv6 generic examples.

Compilation Options

The Contiki TARGET name for this port is nrf52dk, so in order to compile an application you need to invoke GNU make as follows:

make TARGET=nrf52dk

In addition to this port supports the following variables which can be set on the compilation command line:

• NRF52_SDK_ROOT=<SDK PATH> This variable allows to specify a path to the nRF52 SDK which should be used for the build.

• NRF52_WITHOUT_SOFTDEVICE={0|1} Disables SoftDevice support if set to 1. By default, SoftDevice support is used. Note that SoftDevice must be present (flashed) in the device before you run an application that requires it's presence.

• NRF52_USE_RTT={0|1} Enables RealTime Terminal I/O. See VCOM and RTT for details. By default, RTT is disabled and IO is done using Virtual COM port.

• NRF52_JLINK_SN=<serial number> Allows to choose a particular DK by its serial number (printed on the label). This is useful if you have more than one DK connected to your PC and whish to flash a particular device.

• NRF52_DK_REVISION={pca10040|pca10036} Allows to specify DK revision. By default, pca10040 is used.

Compilation Targets

Invoking make solely with the TARGET variable set will build all applications in a given folder. A particular application can be built by invoking make with its name as a compilation target:

make TARGET=nrf52dk hello-world 

In order to flash the application binary to the device use <application>.flash as make target, e.g.:

make TARGET=nrf52dk hello-world.flash

In addition, the SoftDevice binary can be flashed to the DK by invoking:

make TARGET=nrf52dk softdevice.flash

To remove all build results invoke:

make TARGET=nrf52dk clean

The device memory can be erased using:

make TARGET=nrf52dk erase

Note, that once the device is erased, the SoftDevice must be programmed again.

Virtual COM and Real Time Transfer

By default, the nRF52 DK uses a Virtual COM port to output logs. Once the DK is plugged in a /tty/ACM<n> or /ttyUSB<n> device should appear in your filesystem. A terminal emulator, such as picocom or minicom, can be used to connect to the device. Default serial port speed is 38400 bps.

To connect to serial port using picocom invoke:

picocom -fh -b 38400 --imap lfcrlf /dev/ttyACM0 

Note, that if you have not fixed file permissions for /dev/ttyACM0 according to section Segger JLink Software for Linux you'll need to use root or sudo to open the port with picocom.

In addition to Virtual COM the port supports SEGGER's Real Time Transfer for low overhead I/O support. This allows for outputting debugging information at much higher rate with significantly lower overhead than regular I/O.

To compile an application with RTT rather that VCOM set NRF52_USE_RTT to 1 on the compilation command line:

make TARGET=nrf52dk NRF52_USE_RTT=1 hello-world

You can then connect to the device terminal using JLinkRTTClient. Note that a JLlink gdb or commander must be connected to the target for the RTT to work.

More details regarding RTT can be found at https://www.segger.com/jlink-rtt.html

Docummentation

This port provides doxygen source code docummentation. To build the docummentation please run:

sudo apt-get install doxygen
cd <CONTIKI_ROOT>\doc
make

Support

This port is officially supported by Nordic Semiconductor. Please send bug reports or/and suggestions to wojciech.bober@nordicsemi.no.

License

All files in the port are under BSD license. nRF52 SDK and SoftDevice are licensed on a separate terms.

Resources

• nRF52 Datasheet and SDK documentation (http://infocenter.nordicsemi.com)
• nRF52 SDK Downloads (https://developer.nordicsemi.com/)
• JLink Tools (https://www.segger.com/)