Documentation library

nRF5 SDK v13.0.0
Introduction

The nRF5 SDK documentation includes descriptions and other reference material to help you understand the various components of the SDK. Examples are provided for development purposes only and should always be tested with your design.

See Getting Started for instructions on how to run the provided examples. If you are migrating from SDK v12.2.0, see the Migration guide.

This version of the SDK supports the following SoftDevices:

Note
The nRF5 SDK v13.0.0 provides experimental support for the nRF52840 SoC. However, not all features are supported on nRF52840. See the release notes for details.

To download a copy of the SDK documentation for offline use, go to developer.nordicsemi.com.

SDK Release Notes:

nRF5 SDK v13.0.0
------------------------
Release Date: Week 11, 2017

Highlights:
- Implemented a new license scheme for the SDK distribution. See the 
  documentation folder for details.
- Updated the Bluetooth and ANT examples to support the newest 
  SoftDevices S132 v4.0.2, S140 v5.0.0-2.alpha, and S212 v4.0.0.
- Included a new 804.15.4 stack library with an example.
- Released the Eddystone example and the NFC Type 4 Tag stack in 
  production quality. 
- Added workarounds for the nRF52832 anomaly 109 (DMA: DMA access 
  transfers might be corrupted).
- Added serialization of the ANT S212 SoftDevice v4.0.0 (experimental).
- Added an example showing secure DFU with UART transport layer.
- This release does not support nRF51.
- This release does not support the S332 SoftDevice.
 
The following toolchains/devices have been used for testing and
verification:
- ARM: MDK-ARM version 5.18a
- GCC: GCC ARM Embedded 4.9 2015q3
- IAR: IAR Workbench 7.60.2
   
Supported SoftDevices:
- S132 v4.0.2
- S140 v5.0.0-2.alpha
- S212 v4.0.0
    
Supported boards:
- PCA10040
- PCA10056 (limited support; see the "Scope for the nRF52840 chip" section)
- Dynastream's D52DK1 (only for ANT examples)
    
For other devices and boards, see the SDK documentation, section "Using
the SDK with other boards".
    
    
*** Scope for the nRF52840 chip
********************************
All examples and libraries for the new chip must be treated as
experimental.
Some examples have not been ported to run on nRF52840. Check the
existing example projects to see which targets are supported.
    
The following SDK features are supported on the new nRF52840 chip:
  - New 804.15.4 stack library with an example
  - Most BLE, hardware peripheral, and NFC examples (with some
    exceptions; see the available example projects for details)
  - Peripheral HAL and drivers (both for existing and new peripherals)
  - Cryptography library including CryptoCell CC310 backend
  - NFC Type 2 Tag and Type 4 Tag 
  - Secure DFU (only with micro-ecc backend)
  - Serialization of the S140 SoftDevice v5.0.0-2.alpha with UART
   
The following SDK features are not supported on the new nRF52840 chip yet:
   - ANT
   - DTM
   - ESB and Gazell
   - FreeRTOS
   - Eddystone
       
       
*** New features
*****************
    
** BLE **
- Added an experimental BLE Multiperipheral example 
  (experimental_ble_app_multiperipheral) that uses the proprietary LED 
  Button Service to show how a peripheral device can manage connections 
  with multiple peers simultaneously.
 
** ANT **
- Added serialization for S212 v4.0.0. With this solution, an ANT 
  application can run on any architecture, without the SoftDevice. All 
  SoftDevice API calls are transported via UART to an nRF52 device that 
  runs the ANT connectivity application (examples\connectivity\experimental_ant) 
  and the S212 SoftDevice. The ANT I/O example demonstrates the new 
  serialization solution (examples\ant\ant_io_demo, see targets: 
  "ser_s212_uart"). Note that the serialized solution does not support 
  the new API calls added in S212 v4.0.0.
  The SDK folders with the ANT serialization implementation are not 
  marked as experimental, because the paths would be too long.
- Added a new ANT Frequency Agility example 
  (examples\ant\experimental\ant_frequency_agility).
 
** 804.15.4 **
- Added a full 802.15.4 stack implementation to the SDK. The library 
  (components\experimental_802_15_4) is available only for nRF52840 
  devices. The MAC layer API is located in 
  components\experimental_802_15_4\api\MAC. The example application is 
  located in examples\802_15_4\experimental\wireless_uart.
- Added an experimental Wireless UART example (wireless_uart) that shows
  how to use the new 804.15.4 stack.
 
** NFC **
- Added two experimental examples that show NFC pairing (BLE Pairing
  Using NFC - experimental_ble_nfc_pairing_reference and 
  ble_nfc_pairing_reference_c).
 
** DFU **
- Added support for serial/UART and an example for a secure DFU 
  bootloader using UART (experimental).
- Implemented SoftDevice major version checks for certain upgrade types.
- Implemented a delayed reset after the DFU: After a SoftDevice, 
  bootloader, or SoftDevice and bootloader update, a timer will start. 
  If no new update is initiated before its expiration, the device will 
  look for a valid application and launch it.
- Added a new set of error codes (extended error codes) that the DFU 
  target may send as a response to the DFU controller to convey the 
  reason for a failure.
 
** Serialization **
- Added serialization support for the ANT S212 SoftDevice v4.0.0 
  (experimental). See the ANT section for details.
  
** Drivers and libraries **
- Added workarounds for the nRF52832 anomaly 109 (DMA: DMA access 
  transfers might be corrupted). Affected drivers: PWM, SPIM, TWIM, 
  SPIS, and TWIS.
- Added several new libraries:
    - Command line interface (CLI) library: Console that supports 
      various serial interfaces (UART, RTT, USB CDC ACM).
      See the usage example in examples/peripheral/cli.
    - GFX library: Graphics library that supports simple operations like
      drawing circles, lines, rectangles, or bitmaps and printing 
      strings. GFX uses an LCD driver interface. Two implementations for
      popular TFTs have been added (ILI9341, ST7735). 
      See the usage example in examples/peripheral/gfx.
    - Serial port library: Module for handling UART communication. It 
      supports multibyte transfers, time-outs, and buffering of data. 
      The module is a replacement for app_uart. 
      See the usage example in examples/peripheral/serial.
    - SPI transaction manager: Module for managing thread-safe access to
      the SPI driver. The module supports scheduling transactions that 
      consist of multiple transfers. See the usage example in 
      examples/peripheral/spi_master_using_nrf_spi_mngr.
    - Error code to string converter (STRERR): Module for converting 
      error codes to strings. The module is used by nrf_log.
- Added two drivers for TFT LCDs: ILI9341 and ST7735.
 
 
*** Changes
************

** BLE **
- Updated all BLE examples to use the nRF Connect PC application 
  (replacing Master Control Panel).
- Modified all BLE example to have logging enabled by default, to make 
  testing and debugging the SDK examples more consistent. Note that 
  logging greatly increases power consumption. Therefore, logging should
  be disabled in any final product or when performing power profiling 
  tests.
- Updated the Eddystone example so that it can be released in production
  quality.
- Updated all BLE examples to support the newest SoftDevices S132 v4.0.2
  and S140 v5.0.0-2.alpha.
- Updated the Peer Manager to handle more than eight links.
- Updated all BLE examples to use the GATT module.
- Updated the GATT module to handle Data Length update related events.
- Improved the Alert Notification example application to more clearly 
  convey the Alert Notification Service. Increased the verbosity on UART
  instead of relying only on the LEDs.
- Removed the experimental label from the Running Speed and Cadence 
  central example application.
- Cleaned up the use of RX/TX in the Nordic UART Service (NUS) to match 
  the terminology used in external tools (nRF Connect, nRF Toolbox).
- Modified the BLE UART example to enable the use of long ATT_MTU.
 
** DFU **
- Updated the experimental BLE Buttonless DFU Service to use the 
  RAM-retention register to enter bootloader mode instead of flash 
  access.
- Updated the experimental BLE Buttonless DFU Service to use the 
  Secure-DFU UUID (16-bit proprietary Nordic UUID).
- Updated the BLE Buttonless DFU characteristic to use a new 
  vendor-specific base UUID (0x8EC9xxxx-F315-4F60-9FB8-838830DAEA50). 
  The UUID changed to 0x8EC90003-F315-4F60-9FB8-838830DAEA50.
- Changed the BLE Buttonless DFU characteristic from notification to 
  indication.
- Changed the minimum version requirement for nrfutil to v2.2.0.
 
** NFC **
- Updated the NFC Type 4 Tag library so that it can be released in 
  production quality. The library was moved to components\nfc\t4t_lib. 
  The example that shows the Type 4 Tag library is located in 
  examples\nfc\writable_ndef_msg.
- Updated the BLE Heart Rate Collector Example with NFC Pairing and the
  HID Keyboard Application with BLE pairing using NFC to use the NFC BLE
  Pairing library (nfc_pair_lib).
- Updated the BSP NFC Module so that it can be used without restrictions
  together with Type 2 and Type 4 Tag libraries.
 
** Serialization **
- Updated serialization to support the latest BLE SoftDevices S132 
  v4.0.2 and S140 v5.0.0-2.alpha.
 
** Drivers and libraries **
- Updated the implementation of app_uart.
- Moved the static configuration of app_timer to sdk_config.h.
- Updated several hardware drivers:
    - nrf_drv_power: Added initial support for USB plugging with SoftDevice.
    - nrf_drv_pwm: Allowed for playbacks to be started using PPI.
    - nrf_drv_spi: Added an abort function.
    - nrf_drv_twi: Added a function for checking if the driver is busy.
    - nrf_drv_uart: Added a function for checking the receiver state.
    - nrf_drv_csense: Extended the driver to perform measurements using 
      SAADC. COMP is still supported, but it is not recommended for 
      production (see anomaly 84).
 

*** Bugfixes
*************
 
- Fixed several bugs in secure DFU to prevent handling invalid updates.
- Updated secure DFU on nRF52840 to utilize the entire 1 MB of flash, up
  from the old (unintended) limitation of 512 KB.
- Fixed a bug where ble_app_hrs_rscs_relay would not dispatch 
  advertising time-out events to the advertising module.
- Fixed a bug where ble_app_uart would not handle the disconnected event
  if it was received before a service discovery was completed.
- Fixed a bug where ble_app_pwr_profiling did not initialize the button 
  module.
- Fixed a bug where ble_app_proximity would not always trigger "High 
  Alert" on the AlertLevel characteristic when the link was lost.
- Fixed a bug where ble_app_uart would be blocked if app_uart_put 
  returned an error.
- Fixed a bug where Peer Manager corrupted FDS data in flash.
- Fixed a bug where FDS records updated with fds_record_update() would 
  not be garbage collected.
- Fixed an unaligned access error in FDS when using certain compiler 
  options in GCC.
- Fixed a bug in FDS where a missing swap page went undetected.
- Fixed the tick update method in FreeRTOS.
- Fixed a bug where wake-on-field functionality would not work with Type
  2 and Type 4 Tag libraries.
- Several bugfixes and improvements on drivers:
    - nrf_drv_timer: Fixed a bug in NRF_TIMER_IS_BIT_WIDTH_VALID.
    - nrf_drv_saadc: Fixed a bug where nrf_drv_saadc_calibrate_offset() 
      enabled a wrong interrupt.
    - nrf_drv_pwm: Fixed inaccurate description of the 
      NRF_DRV_PWM_FLAG_LOOP flag.

 
*** Known Issues
*****************
  
** BLE **
- If the S132 SoftDevice is configured with 0 Peripheral roles and 0 
  Central roles, sd_ble_enable() may corrupt up to 8 bytes above the 
  returned app_ram_base. For applications having such a configuration, 
  set the application RAM start to 8 bytes or more above the returned 
  app_ram_base.
 
** DFU **
- The S140 SoftDevice currently does not support updating the bootloader.
- Secure DFU (serial):
    - nrfutil currently does not support sending combined zip images 
      (SD+APP, SD+BL+APP, BL+SD). Use individually generated zip-images 
      instead.
    - The device will not automatically boot the application after a 
      SoftDevice update. Reset the device manually.
- Secure DFU (BLE): Updates of SD+BL+APP may time out between the SD+BL 
  and APP stage on certain Android phones. Investigate the time-out 
  value with respect to your mobile app and consider increasing it.


------------------------------------------------------------------------

nRF5 SDK v13.0.0-1.alpha
------------------------
Release Date: Week 50, 2016
  
This release is an alpha release and should ONLY be used for the
following purposes:
- Exploring and trying out the new Bluetooth 5 features available
  with the new SoftDevices.
- Trying out new features on the nRF52840 chip.
 
Highlights:
- Updated the BLE ATT_MTU Throughput Example (ble_app_att_mtu_throughput)
  to showcase a PHY data rate of 2 Ms/s and coded PHY for long-range 
  transmission.
- Updated the cryptography library to include a CryptoCell CC310
  backend (API changes compared to SDK 12.2.0).
- Updated the BLE LE Secure Connections Multirole Example
  (ble_app_multirole_lesc) to use the CryptoCell CC310 backend of the
  cryptography library (available only for nRF52840).
- Added serialization of the new SoftDevices S132 v5.0.0-1.alpha and
  S140 v5.0.0-1.alpha. Added USB CDC ACM serial as transport layer.
- Dropped support for nRF51 Series devices.
- Dropped support for RTX.
  
The following toolchains/devices have been used for testing and
verification:
- ARM: MDK-ARM version 5.18a
- GCC: GCC ARM Embedded 4.9 2015q3
- IAR: IAR Workbench 7.30.4
  
Supported SoftDevices:
- S140 v5.0.0-1.alpha
- S132 v5.0.0-1.alpha
- S212 v2.0.0
- S332 v2.0.0
   
Supported boards:
- PCA10040
- PCA10056 (limited support; see the "Scope for the nRF52840" section)
- Dynastream's N5DK1 (only for ANT examples)
   
For other devices and boards, see the SDK documentation, section "Using
the SDK with other boards".
   
   
*** Scope for the nRF52840 chip
********************************
All examples and libraries for the new chip must be treated as
experimental.
Some examples have not been ported to run on nRF52840. Check the
existing example projects to see which targets are supported.
   
The following SDK features are supported on the new nRF52840 chip:
  - Most BLE, hardware peripheral, and NFC examples (with some
    exceptions; see the available example projects for details)
  - Peripheral HAL and drivers (both for existing and new peripherals)
  - Cryptography library including CryptoCell CC310 backend
  - NFC Type 2 Tag and Type 4 Tag  
  - Secure DFU (only with micro-ecc backend)
  - Serialization of the SoftDevices S132 v5.0.0-1.alpha and
    S140 v5.0.0-1.alpha with UART and USB CDC ACM transport layers
  
The following SDK features are not supported on the new nRF52840 chip yet:
   - ANT
   - DTM
   - ESB and Gazell
   - FreeRTOS
   - Eddystone
      
      
*** New features
*****************
   
** BLE **
- Updated the BLE ATT_MTU Throughput Example to demonstrate the use of 
  Bluetooth 5 features:
    - PHY data rate of 2 Ms/s (nRF52832 and nRF52840)
    - Coded PHY for long-range transmission (nRF52840 only)
 
** NFC **
- Added a layer of abstraction for NFC OOB pairing, the NFC BLE Pairing
  Library (nfc_ble_pair_lib).
- Added a central and a peripheral NFC BLE example that use the new NFC
  BLE Pairing Library:
  - Heart Rate Collector Application with NFC pairing (ble_app_hrs_nfc_c,
    to be used with the Adafruit shield)
  - BLE Peripheral example: Heart Rate Application with BLE pairing 
    using NFC Pairing Library (ble_app_hrs_nfc_pairing_lib)
   
** Cryptography **
- Added a backend to the cryptography library that supports the ARM 
  CryptoCell 310 hardware-accelerated cryptography engine.
- Updated the LE Secure Connections Multirole Example to showcase how 
  to use the cryptography library with the CryptoCell CC310 backend 
  (nRF52840 only).
 
** Serialization **
- Added serialization of the new SoftDevices S132 v5.0.0-1.alpha and
  S140 v5.0.0-1.alpha.
- Added the transport layer USB CDC ACM (nRF52840 only).

   
*** Changes
************
 
** Drivers and libraries **
- Refactored the RNG driver.
    
** BLE **
- Fixed a bug in the Multi-link Example where disconnecting all central
  links would disable the app_button module.
- Fixed two bugs in the Buttonless DFU Template Application:
  - The example now has writable set on the Control Point characteristic.
  - The example is now using the correct part of the flash, enabling 
    flashing when a bootloader is present.
- Fixed a bug in the ANCS Client Application where NULL-termination of a
  received attribute could happen outside its allocated buffer.
- Fixed a bug in the ANCS Client Application where using RFU attribute 
  IDs could cause illegal memory access.
- Modified the LE Secure Connections Multirole Example to prevent 
  creation of a second link to the same peer simultaneously.
   
** NFC **
- Fixed a bug in NFC Type 2 and Type 4 Tag HAL where NFC would hang when
  the chip was woken up from SYSTEM_OFF and HFXO was started before NFCT
  requested it.
  
** Serialization **
- UART and HCI UART transports have been optimized to better utilize 
  EasyDMA.
 

*** Known Issues
****************
   
** Overall **
- Updating the MDK requires to manually copy the header and linker files
  into the SDK folder (ARM Keil uVision 4, IAR Workbench, ARMGCC).
- When uploading an application to an nRF52 IC using nrfjprog, you must
  provide the "--reset/-r" argument or powercycle the board.
   
** BLE **
- Some examples might have excessively verbose logging.
- Examples that use the Peer Manager might assert when deleting bonds,
  because advertising is started twice.
- In the Proximity Application, writing "High Alert" to the AlertLevel
  characteristic of the Link Loss Service does not trigger a high alert
  when the link is lost.
- When an Android device is used as a peripheral, it sends slave
  security request with the MITM bit set. The central applications in
  the SDK will reject the security request (Pairing Failed) because
  they do not support MITM.
- Advertisement intervals in the Eddystone Beacon Application are not
  verified. Clients must ensure that the configured advertisement 
  interval is within the valid range. Note that EID/eTLM configurations 
  might require advertisement intervals larger than the default value.
   
** NFC **
- NFC Type 2 and Type 4 Tag HAL modules require using TIMER4 on nRF52832.
- Type 2 Tag on nRF52840 chips might fail unpredictably.
- Some mobile phone apps cannot write Type 4 Tag ("NFC Tool" seems to 
  be okay to use).