contiki/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/)