osd-contiki/platform/nrf52dk/README.md

254 lines
8.7 KiB
Markdown
Raw Normal View History

2016-01-09 14:44:39 +01:00
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/)