User Manual DA14585/586 SDK 6 Software Developer’s Guide UM-B-080

Abstract This document describes the steps required to develop Bluetooth® low energy applications on the SmartBond™ DA1458x Product Family software platform, specifically for the DA14585/586 devices, as supported by the new v6.x SDK series. It guides the developer through a series of examples which build on each other, introducing the key concepts to developing a Bluetooth low energy application with the DA14585/586 software architecture and APIs.

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Contents Abstract ...... 1 Contents ...... 2 Figures ...... 6 Tables ...... 7 1 References ...... 8 2 Introduction...... 9 2.1 Target Audience ...... 9 2.2 How to Use This Manual ...... 9 3 Getting Started ...... 10 3.1 Development Environment ...... 10 3.2 Software Development Kit (SDK) ...... 10 3.3 SmartSnippetsTM Toolbox ...... 10 4 Blinky: Your First DA14585/586 Application ...... 12 4.1 Application Description...... 12 4.2 Hardware Configuration ...... 12 4.3 Running the Example ...... 12 5 Proximity Reporter: Your First Bluetooth Low Energy Application...... 14 5.1 Application Description...... 14 5.2 User Interface ...... 14 5.3 Loading the Project ...... 14 5.4 Going Through the Code...... 16 5.4.1 Basic Operation ...... 16 5.4.2 Initialization ...... 16 5.4.3 Events Processing and Callbacks ...... 17 5.5 BLE Application Abstract Code Flow ...... 20 5.6 Building the Project for Different Targets and Development Kits ...... 22 5.7 Interacting with BLE Application ...... 23 5.7.1 LightBlue iOS Application ...... 23 5.7.2 BLE Scanner Android Application ...... 24 6 Peripheral Example Applications ...... 26 6.1 Introduction ...... 26 6.2 Software Description ...... 26 6.3 Getting Started ...... 27 6.4 Configuring the UART Interface on a DA1458x DK ...... 27 6.5 Using a Serial Port Terminal with a DA14585/586 DK ...... 27 6.5.1 Connecting to a DA14585/586 DK-Basic ...... 27 6.5.2 Connecting to a DA1458x DK-Pro ...... 28 6.6 UART (Simple) Example ...... 29 6.6.1 Hardware Configuration ...... 29 6.6.2 Running the Example ...... 30 6.7 UART2 Asynchronous Example ...... 31 6.7.1 Hardware Configuration ...... 31 6.7.2 Running the Example ...... 31 6.8 SPI Flash Memory Example...... 33

User Manual Revision 5.0 14-May-2018

CFR0012 2 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

6.8.1 Hardware Configuration ...... 33 6.8.2 Running the Example ...... 34 6.9 I2C EEPROM Example ...... 36 6.9.1 Hardware Configuration ...... 36 6.9.2 Running the Example ...... 36 6.10 Quadrature Decoder Example ...... 38 6.10.1 Hardware Configuration ...... 38 6.10.2 Running the Example ...... 38 6.11 Systick Example ...... 41 6.11.1 Hardware Configuration ...... 41 6.11.2 Running the Example ...... 41 6.12 TIMER0 (PWM0, PWM1) Example ...... 41 6.12.1 Hardware Configuration ...... 41 6.12.2 Running the Example ...... 42 6.13 TIMER0 General Example ...... 42 6.13.1 Hardware Configuration ...... 42 6.13.2 Running the Example ...... 43 6.14 TIMER2 (PWM2, PWM3, PWM4) Example ...... 43 6.14.1 Hardware Configuration ...... 44 6.14.2 Running the Example ...... 44 6.15 Battery Example ...... 46 6.15.1 Hardware Configuration ...... 46 6.15.2 Running the Example ...... 46 7 Developing Bluetooth Low Energy Applications ...... 48 7.1 The Seven Pillar Example Applications ...... 48 7.2 Pillar 1 (Bare Bone) ...... 49 7.2.1 Application Description ...... 49 7.2.2 Basic Operation ...... 49 7.2.3 User Interface ...... 49 7.2.4 Loading the Project ...... 50 7.2.5 Going Through the Code ...... 51 7.2.5.1 Initialization ...... 51 7.2.5.2 Events Processing and Callbacks ...... 52 7.2.5.3 BLE Application Abstract Code Flow ...... 54 7.2.6 Building the Project for Different Targets and Development Kits ...... 55 7.2.7 Interacting with BLE Application ...... 56 7.2.7.1 LightBlue iOS ...... 56 7.3 Pillar 2 (Custom Profile) ...... 57 7.3.1 Application Description ...... 57 7.3.2 Basic Operation ...... 58 7.3.3 User Interface ...... 59 7.3.4 Loading the project ...... 60 7.3.5 Going Through the Code ...... 61 7.3.5.1 Initialization ...... 61 7.3.5.2 Events Processing and Callbacks ...... 62 7.3.5.3 BLE Application Abstract Code Flow ...... 64 7.3.6 Building the Project for Different Targets and Development Kits ...... 64

User Manual Revision 5.0 14-May-2018

CFR0012 3 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.3.7 Interacting with BLE Application ...... 66 7.3.7.1 LightBlue iOS ...... 66 7.4 Pillar 3 (Peripheral) ...... 67 7.4.1 Basic Operation ...... 67 7.4.2 User Interface ...... 67 7.4.3 Loading the Project ...... 68 7.4.4 Going Through the Code ...... 69 7.4.4.1 Initialization ...... 69 7.4.4.2 Events Processing and Callbacks ...... 70 7.4.4.3 BLE Application Abstract Code Flow ...... 72 7.4.5 Building the Project for Different Targets and Development Kits ...... 73 7.4.6 Interacting with BLE Application ...... 74 7.4.6.1 LightBlue iOS ...... 74 7.5 Pillar 4 (Security) ...... 75 7.5.1 Application Description ...... 75 7.5.2 Basic Operation ...... 75 7.5.3 User Interface ...... 75 7.5.4 Loading the Project ...... 75 7.5.5 Going Through the Code ...... 76 7.5.5.1 Initialization ...... 76 7.5.5.2 Events Processing and Callbacks ...... 80 7.5.5.3 BLE Application Abstract Code Flow ...... 82 7.5.6 Building the Project for Different Targets and Development Kits ...... 86 7.5.7 Interacting with BLE Application ...... 87 7.5.7.1 LightBlue iOS ...... 87 7.5.7.2 BLE Scanner Android ...... 88 7.6 Pillar 5 (Sleep Mode) ...... 88 7.6.1 Application Description ...... 88 7.6.2 Basic Operation ...... 89 7.6.3 User Interface ...... 91 7.6.4 Loading the Project ...... 92 7.6.5 Going Through the Code ...... 93 7.6.5.1 Initialization ...... 93 7.6.5.2 Events Processing and Callbacks ...... 94 7.6.5.3 BLE Application Abstract Code Flow ...... 96 7.6.6 Building the Project for Different Targets and Development Kits ...... 97 7.6.7 Interacting with BLE Application ...... 98 7.6.7.1 LightBlue iOS ...... 98 7.7 Pillar 6 (OTA) ...... 99 7.7.1 Basic Operation ...... 99 7.7.2 User Interface ...... 100 7.7.3 Loading the Project ...... 101 7.7.4 Going Through the Code ...... 102 7.7.4.1 Initialization ...... 102 7.7.4.2 Events Processing and Callbacks ...... 103 7.7.4.3 BLE Application Abstract Code Flow ...... 104 7.7.5 Building the Project for Different Targets and Development Kits ...... 104

User Manual Revision 5.0 14-May-2018

CFR0012 4 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.7.6 Interacting with BLE Application ...... 106 7.7.6.1 LightBlue iOS ...... 106 7.7.7 SUOTA Application ...... 107 7.8 Pillar 7 (All in One) ...... 108 7.8.1 Application Description ...... 108 7.8.2 Basic Operation ...... 108 7.8.3 User Interface ...... 109 7.8.4 Loading the Project ...... 110 7.8.5 Going Through the Code ...... 111 7.8.5.1 Initialization ...... 111 7.8.5.2 Events Processing and Callbacks ...... 114 7.8.5.3 BLE Application Abstract Code Flow ...... 118 7.8.6 Building the Project for Different Targets and Development Kits ...... 119 7.8.7 Interacting with BLE Application ...... 120 7.8.7.1 LightBlue iOS ...... 120 8 AES Encryption example application ...... 121 8.1 Application Description...... 121 8.2 Hardware Configuration ...... 121 8.3 Running the example ...... 121 9 ANCS Client example application ...... 123 9.1 Application Description...... 123 9.2 Going Through the Code...... 123 9.3 Advertising, connecting, configuring ...... 124 9.4 ANCS notification handling ...... 125 9.5 GATT service change notifications handling...... 128 9.6 Verbose logging ...... 129 9.7 Trigger negative action...... 130 9.8 Hardware Configuration ...... 130 9.9 Running the example ...... 131 10 Non-Connectable Advertising example application ...... 133 10.1 Application Description...... 133 10.2 Running the example ...... 133 11 External wake-up mechanisms ...... 134 11.1 External Processor Wakes up DA14586/586 ...... 134 11.1.1 Waking up the DA14585/586 using any GPIO ...... 134 11.1.2 Waking up the DA14585/586 using the UART CTS signal ...... 135 11.1.3 Waking up the DA14585/586 using the SPI_EN signal ...... 137 11.2 Waking up an external processor from DA14585/586 ...... 138 11.3 Sleep limitation ...... 139 11.4 Software changes ...... 139 11.4.1 External processor to DA14585/586 wake-up process software...... 140 11.4.2 DA14585/586 to external processor wake-up process software ...... 140 11.4.3 DA14585/586 wake-up timing ...... 141 Appendix A Writing HEX file into OTP memory ...... 142 Revision History ...... 144

User Manual Revision 5.0 14-May-2018

CFR0012 5 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Figures Figure 1: Blinky Example Output Console ...... 13 Figure 2: Proximity Reporter Keil Project Layout ...... 15 Figure 3: Proximity Reporter - User Application Code Flow ...... 20 Figure 4: The default advertise function ...... 21 Figure 5: Advertise parameters configuration ...... 21 Figure 6: User application behaviour after advertising completes ...... 22 Figure 7: Building the Project for Different Targets ...... 22 Figure 8: Development Kit Selection for Proximity Reporter Application ...... 23 Figure 9: iOS LightBlue Application Connected to Proximity Reporter Application ...... 24 Figure 10: Android BLE Scanner App Connected to Proximity Reporter Application ...... 25 Figure 11: Jumper Configurations for UART example ...... 27 Figure 12: DA14585/586 DK - Basic Virtual COM Port ...... 28 Figure 13: DA14585/586 DK-Pro Virtual COM Port ...... 29 Figure 14: UART Simple Example ...... 30 Figure 15: UART2 Example Console Output: Write Test ...... 31 Figure 16: UART2 Example Console Output: Read Test ...... 32 Figure 17: UART2 Example Console Output: Loopback Test ...... 32 Figure 18: SPI Flash Memory Example ...... 35 Figure 19: I2C EEPROM Example ...... 37 Figure 20: Quadrature Decoder Example ...... 39 Figure 21: Quadrature Decoder ISR-Only Reports ...... 39 Figure 22: Quadrature Decoder Polling-Only Reports ...... 40 Figure 23: Quadrature Decoder Polling and ISR Reports ...... 40 Figure 24: TIMER0 (PWM0, PWM1) Test Running ...... 42 Figure 25: TIMER0 General Test Completed ...... 43 Figure 26: TIMER2 (PWM2, PWM3, PWM4) Test Running ...... 44 Figure 27: TIMER2 (PWM2, PWM3, PWM4) Test Completed ...... 45 Figure 28: Battery Example ...... 46 Figure 29: Pillar Example Projects ...... 48 Figure 30: Pillar 1 Keil Project Layout ...... 50 Figure 31: Pillar 1 Application - User Application Code Flow ...... 54 Figure 32: Building the Project for Different Targets ...... 55 Figure 33: Development Kit Selection for Pillar 1 Application ...... 55 Figure 34: LightBlue Application Connected to Pillar 1 Application ...... 57 Figure 35: Pillar 2 Keil Project Layout ...... 60 Figure 36: Pillar 2 Application - User Application Code Flow ...... 64 Figure 37: Building the Project for Different Targets ...... 65 Figure 38: Development Kit Selection for Pillar 2 Application ...... 65 Figure 39: LightBlue Application Connected to Pillar 2 Application ...... 66 Figure 40: Pillar 3 Keil Project Layout ...... 68 Figure 41: Pillar 3 Application - User Application Code Flow ...... 72 Figure 42: Building the Project for Different Targets ...... 73 Figure 43: Development Kit Selection for Pillar 3 Application ...... 73 Figure 44: LightBlue Application Connected to Pillar 3 Application ...... 74 Figure 45: Pillar 4 Keil Project Layout ...... 76 Figure 46: Pillar 4 Application - User Application Code Flow for Pairing procedure ...... 83 Figure 47: Pillar 4 Application - User Application Code Flow for Encryption ...... 85 Figure 48: Building the Project for Different Targets ...... 86 Figure 49: Development Kit Selection for Pillar 4 Application ...... 86 Figure 50: LightBlue Application Connected to Pillar 4 Application ...... 87 Figure 51: LightBlue Application Pairing with Pillar 4 Application using Numeric Comparison ...... 88 Figure 52: Pillar 5 Keil Project Layout ...... 92 Figure 53: Pillar 5 Application - User Application Code Flow ...... 96 Figure 54: Building the Project for Different Targets ...... 97 Figure 55: Development Kit Selection for Pillar 5 Application ...... 97 Figure 56: LightBlue Application Connected to Pillar 5 Application ...... 98 Figure 57: Pillar 6 Keil Project Layout ...... 101 Figure 58: Building the Project for Different Targets ...... 105 User Manual Revision 5.0 14-May-2018

CFR0012 6 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Figure 59: Development Kit Selection for Pillar 6 Application ...... 105 Figure 60: LightBlue Application Connected to Pillar 6 Application ...... 106 Figure 61: Dialog SUOTA Application Discovering Pillar 6 Application ...... 107 Figure 62: Pillar 7 Keil Project Layout ...... 110 Figure 63: Pillar 7 Application - User Application Simplified Code Flow ...... 118 Figure 64: Building the project for different targets ...... 119 Figure 65: Development Kit Selection for the Pillar 7 Application ...... 119 Figure 66: LightBlue Application Connected to Pillar 7 Application ...... 120 Figure 67: Serial port settings ...... 121 Figure 68: AES encryption demo application ...... 122 Figure 69: AES encryption on ongoing BLE connection ...... 122 Figure 70: Booting - sample log snippet ...... 124 Figure 71: Booting - message flowchart ...... 125 Figure 72: Basic Notification handling flowchart...... 126 Figure 73: Sample notifications – log ...... 127 Figure 74: Detailed notification handling flowchart ...... 128 Figure 75: Service change indication - sample log ...... 129 Figure 76: Service change indication message flowchart ...... 129 Figure 77: Verbose logs enabled ...... 130 Figure 78: reject incoming call ...... 130 Figure 79: Serial port settings ...... 131 Figure 80: ANCS example advertising console message ...... 131 Figure 81: ANCS example pairing console message ...... 132 Figure 82: External CPU to DA14585/586 generic wake-up connections ...... 135 Figure 83: External CPU to DA14585/586 generic wake-up process ...... 135 Figure 84: External CPU to DA14585/586 wake-up UART connections ...... 136 Figure 85: External CPU to DA14585/586 wake-up process via UART ...... 136 Figure 86: External CPU to DA14585/586 wake-up SPI connections ...... 137 Figure 87: External CPU to DA14585/586 wake-up process via SPI ...... 137 Figure 88: DA14585/586 to external processor wake-up connections ...... 138 Figure 89: DA14585/586 to external processor wake-up process ...... 139 Figure 90: DA14585/586 wake up timing ...... 141 Figure 91: OTP Programmer ...... 142

Tables AES Advanced Encryption Standard ANCS Apple Notification Center Service BLE Bluetooth Low Energy CPU Central Processing Unit CSRK Connection Signature Resolving Key DA1458x DA1458x SoC Platform of Product Family of devices, for this document specifically referring to the DA14585/586 devices DISS Device Information Service Server DK Development Kit EDIV Encrypted Diversifier GAP Generic Access Profile GTL Generic Transport Layer HCI Host Controller Interface HW Hardware IRK Identity Resolving Key LTK Long Term Key MITM Man In The Middle NC Notification Consumer

User Manual Revision 5.0 14-May-2018

CFR0012 7 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

NVDS Non-Volatile Data Storage NP Notification Provider OOB Out of Band OTA Over The Air OTP One Time Programmable (memory) RandNB Random Number SDK Software Development Kit SoC System on Chip SUOTAR Software Update Over The Air Receiver SUOTA Software Update Over The Air UUID Universally Unique IDentifier

1 References [1] UM-B-048, Getting Started with DA1458x Development Kits - Basic, User Manual, Dialog Semiconductor. [2] UM-B-049, Getting Started with DA1458x Development Kits - Pro, User Manual, Dialog Semiconductor. [3] DA14585 Data sheet, Dialog Semiconductor. [4] DA14586 Data sheet, Dialog Semiconductor. [5] UM-B-079, DA14585/586 Software Platform Reference, User Manual, Dialog Semiconductor. [6] UM-B-012, DA1458x Creation of a secondary boot loader, User manual, Dialog Semiconductor [7] AN-B-023, DA1458x Interfacing with external memory, Application note, Dialog Semiconductor [8] UM-B-019, DA1458x Beacon reference design User Manual, Dialog Semiconductor [9] UM-B-018, DA1458x SmartTag reference application, User manual, Dialog Semiconductor [10] UM-B-025, DA1458x Basic Development kit, User manual, Dialog Semiconductor [11] Bluetooth Specification version 5.0, Bluetooth SIG. [12] UM-B-013, DA14580 External processor interface over SPI, User manual, Dialog Semiconductor [13] NIST SP 800-38A, Recommendation for Block Cipher Modes of Operation: Methods and Techniques (December 2001) [14] UM-B-083, SmartSnippets Toolbox, User manual, Dialog Semiconductor. [15] ANCS specification, Apple Developer [16] UM-B-004, DA14580 Peripheral Drivers, User Manual, Dialog Semiconductor

User Manual Revision 5.0 14-May-2018

CFR0012 8 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

2 Introduction This document aims to provide a step by step guide to the embedded software developer on how to develop a Bluetooth® low energy standard applications using the DA14585/586 System on Chip (SoC) family of integrated circuit (IC) devices.

2.1 Target Audience This is a document for embedded software developers, also called embedded firmware engineers that are working on developing applications on any of the SmartBond™ DA14585/586 Product Family of devices which are based on the DA14585/586 System on Chip (SoC) platform. Developers new to the DA14585/586 System on Chip (SoC) platform are advised to first read [5], especially the first chapters, and then scan through the rest of the reference documents, both to get familiar with the software platform and to learn where to find specific information as needed. Then spend some time reading through the sections of this guide. Experienced embedded firmware engineers after going through the contents of [5], can focus on the “pillar” examples as provided in this document, and then take a deep dive into the SDK and deeper detailed technical documentation. This should provide a clear idea on how applications can be developed and how they can be executed on Dialog’s DA14585/586 Bluetooth® low energy devices. In addition, they provide information on how to best utilize the capabilities offered by Dialog’s DA14585/586 SoC platform.

2.2 How to Use This Manual This document describes the development steps to create Bluetooth low energy applications on the DA14585/586 software architecture, utilizing SDK 6.x and its supporting tool chain. It assumes that the SDK has been installed and that the development tools have already been installed using the SmartSnippetsTM Studio installer (see following Section 3 for more details). It will walk the developer through the following stages:

 Validate the development tool setup by building, running and debugging the first application  Use the structured pillar examples to step-by-step increase knowledge of the different aspects of a Bluetooth low energy application  Use the peripherals of the DA14585/586 SoC.  How to create a new project

The examples in this document are all loaded into internal RAM by the debugger. This guide does not cover the programming of external memories or the internal OTP.

User Manual Revision 5.0 14-May-2018

CFR0012 9 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

3 Getting Started All the development tools are installed by the SmartSnippetsTM Studio installer. The installation and setup instructions depend upon the specific development board being used. The development environment must be a Windows PC.

For the Basic Development Kit (DK) follow UM-B-048, Getting Started with DA14585/586 Development Kits - Basic, User Manual [1] For the Pro Development Kit (DK) follow UM-B-049, Getting Started with DA14585/586 Development Kits - Pro, User Manual [2].

Having followed the instructions in the appropriate Getting Started Guide the developer should have the following components installed.

3.1 Development Environment The DA14585/586 development environment consists of: ● ARM Keil µVision IDE/Debugger, ARM C/C++ Compiler, and its essential middleware components, Keil IDE and the Keil build tools. ● Segger ARM JTAG software that is fully supported by the Keil environment.

This is installed by SmartSnippetsTM Studio.

3.2 Software Development Kit (SDK) The DA14585/586 Software Development Kit (SDK) in its latest v6.x release as downloaded from the customer support DA14585 product page: https://support.dialog- semiconductor.com/connectivity/product/da14585. .

3.3 SmartSnippetsTM Toolbox SmartSnippetsTM Toolbox is a framework of PC based utilities to control DA14585/586 development kit, consisting of: ● Booter is used for downloading for downloading hex files to DA14585/586 SRAM over UART and for resetting the chip to execute from there. ● UART Terminal is available only for connection over UART. After successfully downloading the selected file to the DA14585/586 chip, the ‘Start Terminal’ button is activated and the user can press it in order to receive data from UART. ● Power Profiler is used for plotting the current (and associated charge) drawn by the DA14585/586 on the ProDK in real time over USB. Not supported in Basic DK. ● Sleep Mode Advisor is used to help users understand how much power their application dissipates Sleep modes and what is its impact in battery lifetime duration. ● OTP Programmer tool is used for burning the OTP Memory and OTP Header. ● SPI Flash Programmer is used for downloading an image file to the SPI Flash Memory (DA14585/586). ● RF Master, RF master is an implementation of Bluetooth SIG standardized receiver and transmitter HCI commands and additional custom test HCI commands. RF Master has replaced Connection Manager tool. RF Master supports the following tests: ○ LE Tx/Rx ○ Unmodulated Tx/Rx ○ Continuous Tx

User Manual Revision 5.0 14-May-2018

CFR0012 10 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

○ XTAL ○ Sleep

The “User Guide” html for all these utilities can be found under the “help” drop down menu of the SmartSnippetsTM Toolbox application and in [14]. This is installed by SmartSnippetsTM Studio

User Manual Revision 5.0 14-May-2018

CFR0012 11 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

4 Blinky: Your First DA14585/586 Application The Getting Started guides for the development kits provide in their “Using the Development Kit” section an example application called Blinky. It demonstrates step-by-step how to load the Blinky example as a project in the Keil environment, how to set up and build it, and finally how to execute it via the debug environment on any of the DA14585/586 devices.

4.1 Application Description Blinky is a simple application example which demonstrates basic initialization of DA14585/586 and LED blinking. The project is located in the \projects\target_apps\peripheral_examples\blinky SDK directory. The Keil v5 project file is the: \projects\target_apps\peripheral_examples\blinky\Keil_5\blinky.uvp rojx

4.2 Hardware Configuration The common UART terminal configuration described in section 6.4 is required.

Table 1: Blinky Example UART & LED Jumper Configuration GPIO Function DA14585/586 DK-Basic DA14585/586 DK-Pro P0_4 UART2 TX Connect J4.11 - J4.12 Connect J5.11 - J5.12 P0_5 UART2 RX Connect J4.13 - J4.14 Connect J5.13 - J5.14 P1_0 LED Connect J9.1 – J9.2 Connect J9.1 – J9.2

In addition to the jumper settings for the UART & LED this example, like all others need jumpers installed for the SWD debugger as shown in Table 2. Table 2: Blinky SWD Debugger Jumper Configuration

GPIO Function DA14585/586 DK-Basic DA14585/586 DK-Pro T_TMS SWD IO Connect J4.25 - J4.26 Connect J5.25 - J5.26 T_TCK SWD CLK Connect J4.27 - J4.28 Connect J5.27 - J5.28

4.3 Running the Example Please follow the step-by-step instructions as described in the Getting Started guides for the development kits in their “Using the Development Kit” section. After the Blinky example has been built and downloaded to the DK the LED will start to blink and the following output from program will be visible in the console.

User Manual Revision 5.0 14-May-2018

CFR0012 12 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Figure 1: Blinky Example Output Console

The source code for this example is located in function blinky_test() inside: projects\target_apps\peripheral_examples\blinky\src\main.c

User Manual Revision 5.0 14-May-2018

CFR0012 13 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

5 Proximity Reporter: Your First Bluetooth Low Energy Application

5.1 Application Description The Proximity profile defines the behavior of a Bluetooth device when it moves away from a peer device so that either the connection is dropped or the path loss increases above a predefined level. Either of these conditions will cause an immediate alert. This alert can be used to notify the user that the devices have become separated. The Proximity profile can also be used to define the behavior of two devices which are coming closer together such that either a connection is made or the path loss decreases below a predefined level. The Proximity profile defines two roles: ● Proximity Monitor (PM). The Proximity Monitor shall be a GATT client. ● Proximity Reporter (PR). The Proximity Reporter shall be a GATT server. This section describes only the Proximity Reporter application. The project is located inside the \projects\target_apps\ble_examples\prox_reporter SDK directory. The Keil v5 project file is inside the \projects\target_apps\ble_examples\prox_reporter\Keil_5 directory. Note 1 The Proximity Reporter project supports entering deep sleep mode (e.g. shipping mode - when the device is not yet activated by the end customer). Upon wakeup this project is not supposed to restart execution. To restart execution after wakeup the developer must program the code to OTP or to external flash memory resource (e.g. SPI flash). Please refer to 5.4.2 for the mechanism that wakes up the application from the Deep sleep.

5.2 User Interface The application will notify the user when an alert indication, link loss and immediate alert are triggered. The Alert Notification will be: ● High level alert: A fast (500 ms) LED blinking. ● Low level alert: A slow (1500 ms) LED blinking. The user can stop alert notification by pressing a push button. The selected LED and push button (port and pin number of the DA14585/586) are defined by the user configuration depending on the underlying hardware (Development Kit). The user file user_periph_setup.h holds the peripheral configuration settings of the LED and push button (for the Pro DK it is SW3).

5.3 Loading the Project The Proximity Reporter application is developed under the Keil v5 tool and has the project file prox_reporter.uvprojx. Figure 2 shows the Keil project layout with emphasis on the user related files, These are included in the Keil project folders user_config, user_platform and user_app. These folders contain the user configuration files of the Proximity Reporter application.

User Manual Revision 5.0 14-May-2018

CFR0012 14 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Figure 2: Proximity Reporter Keil Project Layout

User Manual Revision 5.0 14-May-2018

CFR0012 15 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

5.4 Going Through the Code

5.4.1 Basic Operation The Proximity Reporter application supports the following services. ● Immediate Alert service (UUID 0x1802). ● Link Loss service (UUID 0x1803). ● Tx Power service (UUID 0x1804). ● Device Information service (UUID 0x180A). ● Battery service (UUID 0x180F). ● Software Update Over The Air Receiver (SUOTAR) service (UUID 0xFEF5). The Proximity Reporter application has the following features: ● Two levels of Alert Indications. Low/High -> Slow/Fast green LED blinking. ● 500 ms advertising interval. ● Extended sleep without OTP copy mode after 3 minutes of inactivity. ● Push button. ● Stop Alert indications. ● Exit Extended sleep without OTP copy mode. ● Pairing / bonding / encryption. ● Supports Extended / Deep sleep mode. The Proximity Reporter operation is implemented in C source file user_proxr.c.

5.4.2 Initialization The previously mentioned Keil project folders (user_config, user_platform and user_app), contain the files that initialize and configure the Proximity Reporter application. \user_config ● da1458x_config_advanced.h, holds DA14585/586 advanced configuration settings. ● da1458x_config_basic.h, holds DA14585/586 basic configuration settings. ● user_callback_config.h, callback functions that handle various events or operations. ● user_config.h, holds advertising parameters, connection parameters, etc. ● user_modules_config.h, defines which application modules are included or excluded from the user’s application. For example: ○ #define EXCLUDE_DLG_DISS (0) In this case the Device information application profile is included is included in the core SDK and the SDK takes care of the Device information application profile message handling internally. ○ #define EXCLUDE_DLG_DISS (1) In this case the Device information application profile is excluded from the core SDK. The user application must take care of the Device information application profile message handling. ● user_profiles_config.h, defines which BLE profiles (Bluetooth SIG adopted or custom ones) will be included in user’s application. The BLE profiles that are included in the user_profile_config.h file are: ○ CFG_PRF_DISS, includes the Immediate Alert, Link Loss and Tx Power services. ○ CFG_PRF_BASS, includes the Device Information service. ○ CFG_PRF_PXPR, includes the Battery service.

User Manual Revision 5.0 14-May-2018

CFR0012 16 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

\user_platform ● user_periph_setup.h, holds hardware related settings relative to the used Development Kit. The default is the ProDK. ● user_periph_setup.c, source code file that handles peripheral (GPIO, UART, etc.) configuration and initialization relative to the selected Development Kit.

\user_app ● user_proxr.c & user_proxr.h, proximity reporter application source and header files. These files provide the main application, defining what to do when a button is pressed, when a connection is dropped or when adverting stops. These are all implemented as user callbacks as described in the next section. It also defines the trigger mechanism used to wake up from deep sleep, as it is demonstrated in the proximity reporter application. ○ CFG_EXT_INT_WAKEUP_DEEP_SLEEP – An external wake up interrupt (instantaneous button press) triggers the system to wake up from deep sleep. ○ CFG_POR_WAKEUP_DEEP_SLEEP - A power on reset (POR) source (continuous button press for approximately 3sec, by default) triggers the system to wake up from deep sleep Note 1 If both flags are UNDEFINED, the system does not enter the Deep sleep mode, but the selected Extended sleep mode (as defined in user_config.h file). The system exits the Extended sleep mode, if the user presses the button causing the advertising to restart. Note 2 When the system enters the Deep sleep mode, all the RAM blocks are switched off. No application code or data are retained. Note 3 When the system exits from Deep sleep mode, the boot rom code is executed and the application code has to be loaded again, either from OTP memory or external memory source (e.g SPI flash). Note 4 If a Basic DK is used for testing the proximity reporter demo application then a momentary push button must be connected to the relevant GPIO pin. Note 5 The SDK by default as well as this application, during initialization, reads and uses the XTAL16M oscillator trimming value as stored in the OTP header. However, if there has been no trimming yet, the XTAL16M oscillator trimming value in the OTP Header will be zero, and this zero value will then be used by default from the SDK. To alter the default behavior, the SDK provides a configuration flag that allows the user to still read and use the XTAL16M oscillator trimming value from the OTP header, so that if the stored OTP value is zero, it reverts in using an indicative hardcoded value as the XTAL16M oscillator trimming value. You can read more about the XTAL16M oscillator trim on the OTP Header section in the device datasheet, or at Table 37, of Appendix G Booting from serial interfaces, in the UM-B-079 DA14585/586 SDK 6 Software Platform Reference document. Note 6 The OTP header value for the XTAL16M oscillator trimming in the DA14585 and DA14586 devices on the Pro and Basic Development Kits, is not written (ie it is read as zero), to allow for the user/developer to provide and write a preferred XTAL16M oscillator trimming value. Therefore, if you have not calculated and written already a non-zero value, in the XTAL16M oscillator trimming value for the Development Kit that you have in use, it is advised to enable and use in this application and in the SDK the CFG_USE_DEFAULT_XTAL16M_TRIM_VALUE_IF_NOT_CALIBRATED configuration flag, that resides within the da1458x_config_advanced.h file as follows; #define CFG_USE_DEFAULT_XTAL16M_TRIM_VALUE_IF_NOT_CALIBRATED

5.4.3 Events Processing and Callbacks Several events can occur during the lifetime of the Bluetooth low energy application and these events need to be handled in a specific manner. The application is responsible for selecting which events and operations it should handle and which it should just leave to be handled with the default SDK behavior. The SDK uses a mechanism which registers callbacks for every event or operation that defines the system behavior. The C header file user_callback_config.h, which is part of the user application contains the registration of callback functions. The Proximity Reporter application registers the following callback functions: ● General BLE events:

User Manual Revision 5.0 14-May-2018

CFR0012 17 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide static const struct app_callbacks user_app_callbacks = { .app_on_connection = default_app_on_connection, .app_on_disconnect = user_app_on_disconnect, .app_on_update_params_rejected = NULL, .app_on_update_params_complete = NULL, .app_on_set_dev_config_complete = default_app_on_set_dev_config_complete, .app_on_adv_nonconn_complete = NULL, .app_on_adv_undirect_complete = app_advertise_complete, .app_on_adv_direct_complete = NULL, .app_on_db_init_complete = default_app_on_db_init_complete, .app_on_scanning_completed = NULL, .app_on_adv_report_ind = NULL, .app_on_get_dev_name = default_app_on_get_dev_name, .app_on_get_dev_appearance = default_app_on_get_dev_appearance, .app_on_get_dev_slv_pref_params = default_app_on_get_dev_slv_pref_params, .app_on_set_dev_info = default_app_on_set_dev_info, .app_on_data_length_change = NULL, .app_on_update_params_request = default_app_update_params_request, .app_on_generate_static_random_addr = default_app_generate_static_random_addr, .app_on_svc_changed_cfg_ind = NULL, #if (BLE_APP_SEC) .app_on_pairing_request = default_app_on_pairing_request, .app_on_tk_exch = default_app_on_tk_exch, .app_on_irk_exch = NULL, .app_on_csrk_exch = NULL, .app_on_ltk_exch = default_app_on_ltk_exch, .app_on_pairing_succeeded = NULL, .app_on_encrypt_ind = NULL, .app_on_encrypt_req_ind = NULL, .app_on_security_req_ind = NULL, .app_on_addr_solved_ind = NULL, .app_on_addr_resolve_failed = NULL, .app_on_ral_cmp_evt = NULL, .app_on_ral_size_ind = NULL, .app_on_ral_addr_ind = NULL, #endif // (BLE_APP_SEC) }; The above structure defines whether each event will be processed by a default handler, by a user defined handler or it will not be processed at all (NULL entries). The user defined handlers (e.g. app_advertise_complete()) are defined in C source file user_proxr.c.

● System specific events: static const struct arch_main_loop_callbacks user_app_main_loop_callbacks = { .app_on_init = default_app_on_init, .app_on_ble_powered = NULL, .app_on_sytem_powered = NULL, .app_before_sleep = NULL, .app_validate_sleep = NULL, .app_going_to_sleep = NULL, .app_resume_from_sleep = NULL, }; The above structure defines that a certain event will be processed by a default handler or by a user defined handler or it will not be processed at all (NULL entries). In this case the default SDK application initialization function is used and all other events are not handled.

● BLE operations: static const struct default_app_operations user_default_app_operations = { .default_operation_adv = default_advertise_operation,

User Manual Revision 5.0 14-May-2018

CFR0012 18 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

};

The above structure defines that a certain operation will be processed by a default handler or by a user defined handler or it will not be processed at all (NULL entries). In this case only the default advertising operation is used. Note 7 DA14585/586 SDK version 6.0.8 and above supports the URI data type in advertising and/or scan response packets. The URI data type allows the representation of a URI. A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource, as defined in IETF STD66. For more info about the URI data type please refer to [11]. An example implementation of a URI can be seen in the advertising data of the proximity reporter demo application. Please check ADV_TYPE_URI in the USER_ADVERTISE_DATA definition in the usef_config.h file of the project. #define USER_ADVERTISE_DATA ("\x09"\ ADV_TYPE_COMPLETE_LIST_16BIT_SERVICE_IDS\ ADV_UUID_LINK_LOSS_SERVICE\ ADV_UUID_IMMEDIATE_ALERT_SERVICE\ ADV_UUID_TX_POWER_SERVICE\ ADV_UUID_SUOTAR_SERVICE\ "\x10"\ ADV_TYPE_URI\

"\x16\x2F\x2F\x77\x77\x77\x2E\x69\x61\x6E\x61 \x2E\x6F\x72\x67")

User Manual Revision 5.0 14-May-2018

CFR0012 19 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

5.5 BLE Application Abstract Code Flow Figure 3 shows the abstract code flow diagram of the Proximity Reporter application. The diagram depicts the SDK interaction with the callback functions registered in user_callback_config.h and the functions implemented in user_proxr.c. The user configuration block is purely executing the callbacks defined for these operations and events. It is simply calling the default handlers for each of the events until adverting is started. The first user defined callback is app_advertise_complete() which is plugged into the callback table as .app_on_adv_undirect_complete().

User User SDK Application Configuration

app_on_init() default_app_on_init()

app_on_set_dev_config_complete()

default_app_on_set_dev_config_complete()

app_on_db_init_complete()

default_app_on_db_init_complete()

default_operation_adv()

default_advertise_operation()

app_on_adv_undirect_complete()

app_advertise_complete() ) default_app_on_adv_undirect_complete()

app_on_connection() from peer devicepeerfrom

default_app_on_connection() (

Request Request to connect

Figure 3: Proximity Reporter - User Application Code Flow

The default advertising function is the default_advertise_operation(), as shown in Figure 4, and it is located in \sdk\app_modules\src\app_default_hnd.

User Manual Revision 5.0 14-May-2018

CFR0012 20 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

void default_advertise_operation(void) { if (user_default_hnd_conf.adv_scenario == DEF_ADV_FOREVER) { app_easy_gap_undirected_advertise_start(); } else if (user_default_hnd_conf.adv_scenario == DEF_ADV_WITH_TIMEOUT) { app_easy_gap_undirected_advertise_with_timeout_start(user_default_hnd_conf.advertise_p eriod, NULL); } }

Figure 4: The default advertise function

The parameters of the default_advertise_operation() can be configured in the user_config.h file located in \projects\target_apps\ble_examples\prox_reporter\src\config as shown in the following code snippet (Figure 5). This specifies that the advertising is to last 3 minutes and that there is no security defined for the connection. static const struct default_handlers_configuration user_default_hnd_conf = { //Configure the advertise operation used by the default handlers //Possible values: // - DEF_ADV_FOREVER // - DEF_ADV_WITH_TIMEOUT .adv_scenario = DEF_ADV_WITH_TIMEOUT,

//Configure the advertise period in case of DEF_ADV_WITH_TIMEOUT. //It is measured in timer units (3 min). Use MS_TO_TIMERUNITS macro to convert //from milliseconds (ms) to timer units. .advertise_period = MS_TO_TIMERUNITS(180000),

//Configure the security start operation of the default handlers //if the security is enabled (CFG_APP_SECURITY) .security_request_scenario = DEF_SEC_REQ_NEVER };

Figure 5: Advertise parameters configuration

User Manual Revision 5.0 14-May-2018

CFR0012 21 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

The user function app_advertise_complete() is used to define the specific behavior that the application has when the 3 minute advertising period is finished. As shown in Figure 6 this is to stop any active alert, enable a button to wake up from deep sleep and then to enter deep sleep. void app_advertise_complete(const uint8_t status) { #if (BLE_PROX_REPORTER) app_proxr_alert_stop(); #endif

// Disable wakeup for BLE and timer events. Only external (GPIO) wakeup events can wakeup processor. if (status == GAP_ERR_CANCELED) { arch_ble_ext_wakeup_on(); }

// configure button to trigger wake-up interrupt app_button_enable();

// Put system into deep sleep put_system_into_deep_sleep(); } Figure 6: User application behaviour after advertising completes

5.6 Building the Project for Different Targets and Development Kits The Proximity Reporter application can be built for two different target processors, DA14585 and DA14586. The selection is done via the Keil tool as depicted in Figure 7.

Figure 7: Building the Project for Different Targets

The user also has to select the correct Development Kit in order to build and run the application. This selection is done via the Configuration Wizard of the user_periph_setup.h file. The configuration wizard is available via a tab at the bottom of the text file window as shown in Figure 8.

User Manual Revision 5.0 14-May-2018

CFR0012 22 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Figure 8: Development Kit Selection for Proximity Reporter Application

After the proper selection of the target processor and development kit, the application is ready to be built.

The Proximity Reporter application does not use the UART and so the only jumpers that must be present are those for the debugger interface as noted in Table 2.

5.7 Interacting with BLE Application

5.7.1 LightBlue iOS Application The LightBlue iOS application can be used to connect an iPad/iPod/iPhone device to the application. In such a case the iPad/iPod/iPhone acts as a BLE Central and the application as a BLE Peripheral. Figure 9 shows the result when the iPad/iPod/iPhone device manages to connect to the DA14585/586 (the application’s advertising device name is DIALOG-PRXR).

User Manual Revision 5.0 14-May-2018

CFR0012 23 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Figure 9: iOS LightBlue Application Connected to Proximity Reporter Application

5.7.2 BLE Scanner Android Application The Android application BLE Scanner can be used to scan for and then connect to the DIALOG_PRXR app as shown in Figure 10. Unlike the LightBlue application the BLE Scanner application does not display the text strings for each characteristic. They have to be read by pressing the R button next to the characteristic.

User Manual Revision 5.0 14-May-2018

CFR0012 24 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Figure 10: Android BLE Scanner App Connected to Proximity Reporter Application

User Manual Revision 5.0 14-May-2018

CFR0012 25 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

6 Peripheral Example Applications The DA14585/586 Software Development Kit (SDK) includes a set of engineering examples which demonstrate the use of the drivers provided with the SDK to use the main peripheral devices of DA14585/586.

6.1 Introduction The peripheral example applications demonstrate the DA14585/586’s peripheral connectivity capabilities such as interfacing to SPI Flash and I2C EEPROM memories as well as using on chip peripherals such as the timers, the quadrature decoder, and the ADC. The user interaction, when applicable, is done via a UART terminal. The following examples are provided: ● UART Print String Example: How to configure, initiate, and send to the UART interface. ● UART2 Asynchronous Example: How to perform IRQ based IO operations using the UART2 interface. ● SPI Flash Memory Example: How to initiate, read, write and erase an SPI Flash memory. ● I2C EEPROM Example: How to initiate, read, write and erase an EEPROM memory. ● Quadrature Encoder Example: How to configure and read from the quadrature decoder peripheral. The Wakeup Timer setup for responding to GPIO activity is also demonstrated in this example. ● Systick Example: How to use Systick timer to generate an interrupt periodically. A LED is changing its state upon each interrupt. ● TIMER0 (PWM0, PWM1) Example: How to configure TIMER0 to produce PWM signals. A melody is produced on an externally connected buzzer. ● TIMER0 general Example: How to configure TIMER0 to count a specified amount of time and generate an interrupt. LED is blinking every interrupt ● TIMER2 (PWM2, PWM3, PWM4) Example: How to configure TIMER2 to produce PWM signals. LEDs are changing light brightness in this example. ● Battery Example: How to read the battery indication level, using the ADC.

6.2 Software Description The peripheral example applications are in the target_apps\peripheral_examples\ directory of the DA14585/586 Software Development Kit. The driver implementations are located in the directory sdk\platform\driver. The steps to use the DA14585/586 peripheral drivers in an application are: ● Add the driver’s source code file (e.g. spi\spi.c) to the project. ● Include the driver’s header file (e.g. spi\spi.h) in all files that will use the driver’s API. ● Add the driver folder path to the Include Paths (C/C++ tab of Keil Target Options). Do this by right clicking on the project in the project window and select Options for Target: Each of the example projects includes the following files: main.c: Includes both the main and test functions. user_periph_setup.c: Includes the system initialization and GPIO configuration functions for peripheral that is about to be presented. user_periph_setup.h: Defines the hardware configuration, such as GPIO assignment for peripheral that is being used. common_uart.c, .h: Introduces functions to print byte, word, double word and string variables. It calls functions from the GPIO driver.

User Manual Revision 5.0 14-May-2018

CFR0012 26 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

6.3 Getting Started It is assumed that the user is familiar with the use of the DA14585/586 Development Kits as described in [1] for the Basic DK or [2] for the ProDK. Before running each of the peripheral examples the DA14585/586 development board must have the jumpers correctly configured. Each example contains a subsection which describes the GPIO assignment of the DA14585/586 development board and jumper settings required.

6.4 Configuring the UART Interface on a DA1458x DK The DA14585/586 UART2 interface will be used for the UART interaction terminal. It does not use RTS and CTS in this example. In addition, the SWD debugger jumpers also need to be in place. The jumper configuration is shown in Figure 11.

GPIO Function DA14585/586 DK-Basic DA14585/586 DK-Pro P0_4 UART2 TX Connect J4.11 - J4.12 Connect J5.11 - J5.12 P0_5 UART2 RX Connect J4.13 - J4.14 Connect J5.13 - J5.14 T_TMS SWD IO Connect J4.25 - J4.26 Connect J5.25 – J5.26 T_TCK SWD CLK Connect J4.27 – J4.28 Connect J5.27 – J5.28

Figure 11: Jumper Configurations for UART example

6.5 Using a Serial Port Terminal with a DA14585/586 DK A serial port terminal application (e.g. Tera Term) should be used for user interaction with each peripheral example project. All examples use the following COM port settings: Baud rate: 115200 Data: 8-bit Parity: none Stop: 1 bit Flow control: none The procedure of discovering the COM port number of a DA1458x DK is described in subsequent paragraphs.

6.5.1 Connecting to a DA14585/586 DK-Basic When the DA14585/586 DK-Basic [1] is connected via USB to a Windows machine (e.g. laptop), a J- Link device should be discovered in the Windows Devices and Printers. Note down the J-Link CDC UART Port which is displayed in the J-Link’s properties window (COM106 in Figure 12) so it can be used in a serial port terminal application.

User Manual Revision 5.0 14-May-2018

CFR0012 27 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Figure 12: DA14585/586 DK - Basic Virtual COM Port

6.5.2 Connecting to a DA1458x DK-Pro When the DA14585/586 DK [2] is connected via USB with a Windows machine (e.g. laptop) a Dual RS232-HS device should be discovered in the Windows Devices and Printers. In the Dual RS232- HS’s properties window two USB Serial Ports are displayed. Note down the number of the serial COM port with the smaller number (COM80 in Figure 13) so it can be used in a terminal console application.

User Manual Revision 5.0 14-May-2018

CFR0012 28 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Figure 13: DA14585/586 DK-Pro Virtual COM Port

6.6 UART (Simple) Example The simple UART example demonstrates how to configure, initiate, and send some characters synchronously to the UART interface. The project is in the \projects\target_apps\peripheral_examples\uart SDK directory. The UART example is developed under the Keil v5 tool. Double click on the Keil project file \projects\target_apps\peripheral_examples\uart\Keil_5\uart.uvprojx to launch the IDE.

6.6.1 Hardware Configuration The common UART terminal configuration described in Figure 11 is required.

User Manual Revision 5.0 14-May-2018

CFR0012 29 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

6.6.2 Running the Example In Keil build the example project and load it to the DK by starting Debug Session (Debug > Start/Stop Debug Session). When the project is run in the debug session the console will display the message shown in Figure 14. The uart_test function uses print_hword, print_word and printf_string functions to print the message on the console.

Figure 14: UART Simple Example

The user can select the UART settings in the header file: \projects\target_apps\peripheral_examples\uart\include\user_periph _setup.h The predefined settings are the following and can be found in uart.h header file : // Select UART settings #define UART2_BAUDRATE UART_BAUDRATE_115K2 // Baudrate in bits/s: { 9K6, 14K4, 19K2, 28K8, 38K4, 57K6, 115K2} #define UART2_FRAC_BAUDRATE UART_FRAC_BAUDRATE_115K2 // Baudrate fractional part: {9K6, 14K4, 19K2, 28K8, 38K4, 57K6, 115K2} #define UART2_DATALENGTH UART_CHARFORMAT_8 // Datalength in bits: {5, 6, 7, 8} #define UART2_PARITY UART_PARITY_NONE // Parity: {UART_PARITY_NONE, UART_PARITY_EVEN, UART_PARITY_ODD} #define UART2_STOPBITS UART_STOPBITS_1 // Stop bits: {UART_STOPBITS_1, UART_STOPBITS_2} #define UART2_FLOWCONTROL UART_FLOWCONTROL_DISABLED // Flow control: {UART_FLOWCONTROL_DISABLED, UART_FLOWCONTROL_ENABLED} The source code for this example can be found in function uart_test in: projects\target_apps\peripheral_examples\uart\src\main.c.

User Manual Revision 5.0 14-May-2018

CFR0012 30 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

6.7 UART2 Asynchronous Example

The UART2 asynchronous example demonstrates how to perform IRQ based IO operations using the UART2 driver (\sdk\platform\driver\uart\uart2.c). The project is in the \projects\target_apps\peripheral_examples\uart2_async SDK directory. The UART2 asynchronous example is developed under the Keil v5 tool. The Keil project file is the: \projects\target_apps\peripheral_examples\uart2_async\Keil_5\uart2 _async.uvprojx

6.7.1 Hardware Configuration The common UART terminal configuration described in Figure 11 is required.

6.7.2 Running the Example Build and load the example project to the DK. When it runs it executes an asynchronous write test (in function uart2_write_test) and the following lines displayed in the terminal window.

Figure 15: UART2 Example Console Output: Write Test

Next an asynchronous read test is executed (in function uart2_read_test) and the user is prompted to enter 5 characters. On the assumption that the user typed the five characters a, b, c, d, and e, then upon pressing the fifth character e the typed characters are printed in the terminal window as shown in Figure 16.

User Manual Revision 5.0 14-May-2018

CFR0012 31 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Figure 16: UART2 Example Console Output: Read Test

The last test executed is the loopback test (in function uart2_loopback_test), where every received character is echoed back to the sender. For example, if the user types “Hello world!” then the following will be output (see Figure 17):

Figure 17: UART2 Example Console Output: Loopback Test

User Manual Revision 5.0 14-May-2018

CFR0012 32 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

6.8 SPI Flash Memory Example The SPI Flash memory example demonstrates how to initiate, read, write and erase an SPI Flash memory using the SPI Flash driver. The project is located in the \projects\target_apps\peripheral_examples\spi\spi_flash SDK directory. The SPI Flash memory example is developed under the Keil v5 tool. The Keil project file is the: \projects\target_apps\peripheral_examples\spi\spi_flash\Keil_5\spi _flash.uvprojx

6.8.1 Hardware Configuration To run this example additional jumpers need to be added to enable the SPI connection to the external SPI flash device. UART2 Tx is still connected but UART2 Rx must be removed as it conflicts with SPI DI. Table 3 shows the jumper configurations required for the case where UART Rx is not required (ie UART2 is only outputting log data).

Table 3: SPI Flash Memory Example Jumper Configuration without UART2 RX GPIO Function DA14585/586 DK-Basic DA14585/586 DK-Pro P0_4 UART2 TX Connect J4.11 - J4.12 Connect J5.11 - J5.12 P0_5 (UART2 RX) or SPI DI Connect J6.1 - J4.13 Connect J6.1 - J5.13 (J4.14 is not connected) (J5.14 is not connected) P0_6 SPI DO Connect J6.2 – J4.15 Connect J6.2 – J5.15 P0_3 SPI CS Connect J4.19 - J4.20 Connect J5.19 – J5.20 P0_0 SPI CLK Connect J4.21 - J4.22 Connect J5.21 – J5.22 VBAT SPI_SUPPLY Connect J4.23 - J4.24 Connect J5.23 – J5.24 T_TMS SWD IO Connect J4.25 - J4.26 Connect J5.25 – J5.26 T_TCK SWD CLK Connect J4.27 – J4.28 Connect J5.27 – J5.28

If reading from UART2 is necessary then as the UART2 RX default pin conflicts with the SPI MISO pin (P0_5), a separate pin will have to be used for UART2 RX. The header file user_periph_setup.h has already been setup to allocate UART2 Rx to P0_7. In this case a jumper wire is needed to connect UART2 Rx as shown in Table 4.

Table 4: SPI Flash Memory Example Jumper Configuration with UART2 RX GPIO Function DA14585/586 DK-Basic DA14585/586 DK-Pro P0_4 UART2 TX Connect J4.11 - J4.12 Connect J5.11 - J5.12 P0_5 SPI DI Connect J6.1 - J4.13 Connect J6.1 - J5.13 P0_6 SPI DO Connect J6.2 – J4.15 Connect J6.2 – J5.15 P0_7 UART2 RX Connect J4.17 - J4.14 Connect J5.17 - J5.14 (with a jumper wire) (with a jumper wire) P0_3 SPI CS Connect J4.19 - J4.20 Connect J5.19 – J5.20 P0_0 SPI CLK Connect J4.21 - J4.22 Connect J5.21 – J5.22 VBAT SPI_SUPPLY Connect J4.23 - J4.24 Connect J5.23 – J5.24 T_TMS SWD IO Connect J4.25 - J4.26 Connect J5.25 – J5.26 T_TCK SWD CLK Connect J4.27 – J4.28 Connect J5.27 – J5.28

User Manual Revision 5.0 14-May-2018

CFR0012 33 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

6.8.2 Running the Example Once the user has built and loaded the example project to the DK, a series of read and write operations will be performed on the SPI Flash memory (as shown in Figure 18). The user also has to enter the characteristics of the SPI Flash in the header file: \projects\target_apps\peripheral_examples\spi\spi_flash\include\us er_periph_setup.h The predefined characteristics are the following: #define SPI_FLASH_SIZE (256 * 1024) // SPI Flash memory size in bytes #define SPI_FLASH_PAGE 256 // SPI Flash memory page size in bytes The user can also select the SPI module parameters, such as word mode, polarity, phase and frequency: #define SPI_WORD_MODE SPI_8BIT_MODE // Select SPI bit mode #define SPI_SMN_MODE SPI_MASTER_MODE // {SPI_MASTER_MODE, SPI_SLAVE_MODE} #define SPI_POL_MODE SPI_CLK_INIT_HIGH // {SPI_CLK_INIT_LOW, SPI_CLK_INIT_HIGH} #define SPI_PHA_MODE SPI_PHASE_1 // {SPI_PHA_MODE_0, SPI_PHA_MODE_1} #define SPI_MINT_EN SPI_NO_MINT // {SPI_MINT_DISABLE, SPI_MINT_ENABLE} #define SPI_CLK_DIV SPI_XTAL_DIV_2 // Select SPI clock divider between // 8, 4, 2 and 14 The spi_test function performs the following tests: 1. The GPIO pins used for the SPI Flash and the SPI module are initialized. 2. The SPI Flash device memory is erased. To erase a device on which protection has been activated, the full test must be run once (see step 11a). 3. The contents of the SPI Flash are read and printed to the console. 4. The JEDEC ID is read and the device is detected, if a corresponding entry is found in the supported devices list [16]. 5. The Manufacturer/Device ID and the Unique ID are read, if the device is known to support it. 6. 256 bytes of data is written to the SPI Flash using the Program Page instruction. 7. The contents of the SPI Flash are read and printed out on the console. 8. A sector of the SPI Flash is erased. 9. 512 bytes of data is written to the SPI Flash using the spi_write_data function, which is used for writing data longer than the SPI Flash page. 10. The 512 bytes of data are read back and printed to the console. 11. If supported by the SPI Flash memory device, a suitable test for the device’s memory protection capabilities is performed: a. The whole memory area is configured as unprotected and a full memory array erase is performed. b. The memory is tested in various configurations to demonstrate the effect the memory protection of the various blocks of memory has on data storage and how previously stored data is affected by overwrite. c. Finally, once again the whole memory area is configured as unprotected and a full memory array erase is performed.

User Manual Revision 5.0 14-May-2018

CFR0012 34 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Figure 18: SPI Flash Memory Example

In case you use a supported external SPI Flash device other than W25X10, the results of the SPI memory protection features test will differ. The user can change the test procedure by editing the function spi_test. The SPI Flash driver API is described in detail in [5]. The source code for this example can be found in function spi_test inside: \projects\target_apps\peripheral_examples\spi\spi_flash\src\main.c .

User Manual Revision 5.0 14-May-2018

CFR0012 35 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

6.9 I2C EEPROM Example The I2C EEPROM example demonstrates how to initiate, read, write and erase an I2C EEPROM memory. Neither the Basic DK nor the ProDK have an I2C memory mounted. So, this example will only work with the addition of an external I2C memory connected using jumper wires. The project is in the SDK directory \projects\target_apps\peripheral_examples\i2c\i2c_eeprom. The I2C EEPROM example is developed under the Keil v5 tool. The Keil project file is the: \projects/target_apps/peripheral_examples/i2c/i2c_eeprom/Keil_5/i2 c_eeprom.uvprojx

6.9.1 Hardware Configuration

Table 5: I2C EEPROM Example Jumper Settings GPIO Function DA14585/586 DK-Basic DA14585/586 DK-Pro P0_2 I2C SCL Jumper wire to external I2C Jumper wire to external I2C memory memory P0_3 I2C SDA Jumper wire to external I2C Jumper wire to external I2C memory memory P0_4 UART2 TX Connect J4.11 - J4.12 Connect J5.11 - J5.12 P0_5 UART2 RX Connect J4.13 - J4.14 Connect J5.13 - J5.14 T_TMS SWD IO Connect J4.25 - J4.26 Connect J5.25 – J5.26 T_TCK SWD CLK Connect J4.27 – J4.28 Connect J5.27 – J5.28

An external I2C EEPROM must be connected to the DA14585/586 DK using the pins shown in Table 5: P0_2 for SCL and P0_3 for SDA. If a different selection of GPIO pins is needed, the user should edit the I2C_GPIO_PORT, I2C_SCL_PIN and I2C_SDA_PIN defines in user_periph_setup.h.

6.9.2 Running the Example Once the user has built and loaded the example project to the DK, a series of read and writes operations will be performed on the I2C EEPROM, as shown in Figure 19. The predefined I2C EEPROM characteristics are the following: #define I2C_EEPROM_SIZE 0x20000 // EEPROM size in bytes #define I2C_EEPROM_PAGE 256 // EEPROM's page size in bytes The user can also select the I2C module’s parameters, such as slave address, speed mode, address mode and addressing scheme (1-byte/2-byte): #define I2C_SLAVE_ADDRESS 0x50 // Set slave device address #define I2C_SPEED_MODE I2C_FAST // Speed mode: I2C_STANDARD (100 kbits/s), I2C_FAST: (400 kbits/s) #define I2C_ADDRESS_MODE I2C_7BIT_ADDR // Addressing mode: {I2C_7BIT_ADDR, I2C_10BIT_ADDR} #define I2C_ADDRESS_SIZE I2C_2BYTES_ADD // Address width: {I2C_1BYTE_ADDR, I2C_2BYTES_ADDR, I2C_2BYTES_ADDR} The i2c_test function performs the following tests: ● Initializes the GPIO pins used for the I2C EEPROM and the I2C module. ● Writes 256 bytes of data to the I2C EEPROM. ● Reads the contents of the I2C EEPROM.

User Manual Revision 5.0 14-May-2018

CFR0012 36 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

● Writes and reads bytes 0x5A, 0x6A, 0x7A and 0xFF at addresses 22, 0, 255 and 30 respectively. ● Reads the contents of the I2C EEPROM. ● Releases the configured GPIO pins and the I2C module. ● This is shown in detail in Figure 19.

Figure 19: I2C EEPROM Example

The user can change the test procedure by editing the function i2c_test. The I2C EEPROM driver API is described in detail in [5]. The source code for this example is in function i2c_test inside: \projects\target_apps\peripheral_examples\i2c\i2c_eeprom\src\main. c.

User Manual Revision 5.0 14-May-2018

CFR0012 37 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

6.10 Quadrature Decoder Example The Quadrature decoder example demonstrates how to configure and read from the quadrature decoder peripheral. The Wakeup Timer setup for responding to GPIO activity is also demonstrated in this example. Neither the Basic DK nor the ProDK have a Quadrature decoder mounted. So, this example will only work with the addition of an external quadrature decoder connected using jumper wires. The project is in the SDK directory \projects\target_apps\peripheral_examples\quadrature_decoder. The Quadrature decoder example is developed under the Keil v5 tool. The Keil project file is the: …\quadrature_decoder\Keil_5\quadrature_decoder.uvprojx

6.10.1 Hardware Configuration The jumper settings required by the Quadrature decoder example are shown in Table 6

Table 6: Quadrature Decoder Example Jumper Settings GPIO Function DA14585/586 DK-Basic DA14585/586 DK-Pro GND Common Terminal Jumper wire J4.2 to common Jumper wire J5.2 to common terminal of Quadrature decoder terminal of Quadrature encoder P0_0 CHX_A Jumper wire J4.21 to CHX_A of Jumper wire J5.21 to CHX_A of Quadrature encoder Quadrature encoder P0_1 CHX_B Jumper wire J4.10 to CHX_B of Jumper wire J5.10 to CHX_B of Quadrature encoder Quadrature encoder P0_4 UART2 TX Connect J4.11 - J4.12 Connect J5.11 - J5.12 P0_5 UART2 RX Connect J4.13 - J4.14 Connect J5.13 - J5.14 P0_6 K1 BUTTON Not available SW2 P1_1 K2 BUTTON Not available SW3 T_TMS SWD IO Connect J4.25 - J4.26 Connect J5.25 – J5.26 T_TCK SWD CLK Connect J4.27 – J4.28 Connect J5.27 – J5.28

The quadrature encoder CHX_A and CHX_B pins must be connected to P0_0 and P0_1 respectively. The common terminal of the quadrature encoder must be connected to ground. To enable the K1 and K2 buttons functionality on a Basic DK, the user must connect external HW to P0_6 and P1_1.

6.10.2 Running the Example Once the user has built and loaded the example project to the DK, the console will display the screen shown in Figure 20.

User Manual Revision 5.0 14-May-2018

CFR0012 38 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Figure 20: Quadrature Decoder Example

If the rotary encoder is activated (e.g. the mouse wheel is scrolled and the rotary encoder is attached to a mouse) the quadrature decoder-wakeup timer interrupt will be triggered, and after each trigger the terminal screen will report the axes relative coordinates. In this configuration, only the X channel terminals are configured and connected (see Figure 21).

Figure 21: Quadrature Decoder ISR-Only Reports

If at any time the K1 button is pressed (the user should make sure that the correct jumper configuration for buttons K1 and K2 is selected, as described in [2]), polling of the relative coordinates will be enabled. Then the terminal window will start polling the quadrature decoder driver (see Figure 22). If the quadrature decoder is activated, a mixture of ISR and polling generated reports are displayed (see Figure 23).

User Manual Revision 5.0 14-May-2018

CFR0012 39 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Figure 22: Quadrature Decoder Polling-Only Reports

Figure 23: Quadrature Decoder Polling and ISR Reports

The polling can be stopped by pressing K1 button again. To terminate the test, one can press K2 at any time. The message “Quadrature Decoder Test terminated!” will be printed. If the count of events needs to be changed before an interrupt is triggered, the parameter QDEC_EVENTS_COUNT_TO_INT in user_periph_setup.h can be modified accordingly. In the same file, the clock divisor of the quadrature decoder can be changed by altering the parameter QDEC_CLOCK_DIVIDER. The source code for this example is in function quad_decoder_test inside: \projects\target_apps\peripheral_examples\quadrature_decoder\src\m ain.c.

User Manual Revision 5.0 14-May-2018

CFR0012 40 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

6.11 Systick Example The Systick example demonstrates how to use the systick timer to generate an interrupt periodically. LED is changing its state upon each interrupt. The project is in the SDK directory \projects\target_apps\peripheral_examples\systick . The Systick example is developed under the Keil v5 tool. The Keil project file is the: \projects\target_apps\peripheral_examples\systick\Keil_5\systick.u vprojx

6.11.1 Hardware Configuration This example does not use the UART terminal.

Table 7. Systick Example Jumper Settings GPIO Function DA14585/586 DK-Basic DA14585/586 DK-Pro P1_0 LED Connect J9.1 – J9.2 Connect J9.1 – J9.2 T_TMS SWD IO Connect J4.25 - J4.26 Connect J5.25 – J5.26 T_TCK SWD CLK Connect J4.27 – J4.28 Connect J5.27 – J5.28

6.11.2 Running the Example Once the user has built and loaded the example project to the DK, the LED will start to blink every 1s. The source code for this example is in the function systick_test inside: \projects\target_apps\peripheral_examples\systick\src\main.c.

6.12 TIMER0 (PWM0, PWM1) Example The TIMER0 (PWM0, PWM1) example demonstrates how to configure TIMER0 to produce PWM signals. A melody is produced on an externally connected buzzer. The project is located in the \projects\target_apps\peripheral_examples\timer0\timer0_pwm SDK directory. The TIMER0 (PWM0, PWM1) example is developed under the Keil v5 tool. The Keil project file is the: \projects\target_apps\peripheral_examples\timer0\timer0_pwm\Keil_5 \timer0_pwm.uvprojx

6.12.1 Hardware Configuration

Table 8: Timer0 Example Jumper Settings GPIO Function DA14585/586 DK-Basic DA14585/586 DK-Pro P0_2 PWM0 Connect buzzer between J4.9 and Connect buzzer between J5.9 and J4.2 J5.2 P0_3 PWM1 Connect buzzer between J4.9 and Connect buzzer between J5.9 and J4.19 J5.19 P0_4 UART2 TX Connect J4.11 - J4.12 Connect J5.11 - J5.12 P0_5 UART2 RX Connect J4.13 - J4.14 Connect J5.13 - J5.14 T_TMS SWD IO Connect J4.25 - J4.26 Connect J5.25 – J5.26 T_TCK SWD CLK Connect J4.27 – J4.28 Connect J5.27 – J5.28

User Manual Revision 5.0 14-May-2018

CFR0012 41 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

To have an audible indication of the generated PWM signals, the user can connect a buzzer between P0_2 and ground (PWM0) or between P0_3 and ground (PWM1).

6.12.2 Running the Example Once the user has built and loaded the example project to the DK, the PWM0 and PWM1 signals will become active and start producing an audible melody if a buzzer is connected to P0_2 or P0_3. While the melody is playing, stars are being drawn in the terminal window on each beat (interrupt handling - Figure 24).

Figure 24: TIMER0 (PWM0, PWM1) Test Running

Upon completion, the following message will appear: “Timer0 stopped End of test” The source code for this example is in function timer0_test inside: \projects\target_apps\peripheral_examples\timer0\timer0_pwm\src\ma in.c.

6.13 TIMER0 General Example The TIMER0 general example demonstrates how to configure TIMER0 to count a specified amount of time and generate an interrupt. A LED is changing state upon each timer interrupt. The project is in the SDK directory \projects\target_apps\peripheral_examples\timer0\timer0_general. The TIMER0 general example is developed under the Keil v5 tool. The Keil project file is the: \projects\target_apps\peripheral_examples\timer0\timer0_genera\Kei l_5\timer0_general.uvprojx

6.13.1 Hardware Configuration The common UART terminal configuration described in section 6.4 is required.

User Manual Revision 5.0 14-May-2018

CFR0012 42 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Table 9: Timer0 General Example Jumper Settings GPIO Function DA14585/586 DK-Basic DA14585/586 DK-Pro P0_4 UART2 TX Connect J4.11 - J4.12 Connect J5.11 - J5.12 P0_5 UART2 RX Connect J4.13 - J4.14 Connect J5.13 - J5.14 P1_0 LED Connect J9.1 – J9.2 Connect J9.1 – J9.2 T_TMS SWD IO Connect J4.25 - J4.26 Connect J5.25 – J5.26 T_TCK SWD CLK Connect J4.27 – J4.28 Connect J5.27 – J5.28

6.13.2 Running the Example Once the user has built and loaded the example project to the DK, the LED will be changing its state every second until the end of the test. The duration of the test (expressed in seconds) can be set by user and it will also be printed in the console. See Figure 25.

Figure 25: TIMER0 General Test Completed

The source code for this example is located in function timer0_general_test in the file: \projects\target_apps\peripheral_examples\timer0\timer0_general\sr c\main.c.

6.14 TIMER2 (PWM2, PWM3, PWM4) Example The TIMER2 (PWM2, PWM3, PWM4) example demonstrates how to configure TIMER2 to produce PWM signals. The PWM outputs are used to change the brightness of LEDs in this example. The project is in the SDK directory \projects\target_apps\peripheral_examples\timer2\timer2_pwm. The TIMER2 (PWM2, PWM3, PWM4) example is developed under the Keil v5 tool. The Keil project file is the: \projects\target_apps\peripheral_examples\timer2\timer2_pwm\Keil_5 \timer2_pwm.uvprojx

User Manual Revision 5.0 14-May-2018

CFR0012 43 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

6.14.1 Hardware Configuration

Table 10: TIMER2 Example Jumper Settings GPIO Function DA14585/586 DK-Basic DA14585/586 DK-Pro P0_4 UART2 TX Connect J4.11 - J4.12 Connect J5.11 - J5.12 P0_5 UART2 RX Connect J4.13 - J4.14 Connect J5.13 - J5.14 P1_2 PWM2 P0_7 PWM3 P1_0 PWM4

To use the LED segments inside D1 and D2 as a visual indication for signals PWM2, PWM3 and PWM4, the user has to connect PIN3 to PIN4 on connector J16 (PWM3), PIN1 to PIN2 on connector J16 (PWM4) and PIN3 to PIN4 on connector J15 (PWM2). The brightness of the LED segments is then directly influenced by the duty cycle of the PWM signals.

6.14.2 Running the Example Once the user has built the Timer2 (PWM2, PWM3, PWM4) example and loaded to DK, the PWM2, PWM3 and PWM4 signals will become active. If the jumper configuration described in section 6.14.1 has been selected, there will be a visible indication of the PWM3 and PWM4 signals on segments of the D2 and D1 LED segments, as their brightness will be directly influenced by the PWM signals’ duty cycle. The brightness will be changing automatically because each PWM duty cycle will change in a loop function. The screen shown in Figure 26 will appear.

Figure 26: TIMER2 (PWM2, PWM3, PWM4) Test Running

After the test has been completed, the screen shown in Figure 27 will then appear.

User Manual Revision 5.0 14-May-2018

CFR0012 44 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Figure 27: TIMER2 (PWM2, PWM3, PWM4) Test Completed

The source code for this example is in function timer2_test inside: \projects\target_apps\peripheral_examples\timer2\timer2_pwm\src\ma in.c.

User Manual Revision 5.0 14-May-2018

CFR0012 45 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

6.15 Battery Example The Battery example demonstrates how to read the battery level using the ADC. The project is in the SDK directory \projects\target_apps\peripheral_examples\adc\batt_lvl. The Battery example is developed under the Keil v5 tool. The Keil project file is the: \projects\target_apps\peripheral_examples\adc\batt_lvl\Keil_5\batt _lvl.uvprojx

6.15.1 Hardware Configuration

Table 11: Battery Example Jumper Settings GPIO Function DA14585/586 DK-Basic DA14585/586 DK-Pro P0_4 UART2 TX Connect J4.11 - J4.12 Connect J5.11 - J5.12 P0_5 UART2 RX Connect J4.13 - J4.14 Connect J5.13 - J5.14 T_TMS SWD IO Connect J4.25 - J4.26 Connect J5.25 – J5.26 T_TCK SWD CLK Connect J4.27 – J4.28 Connect J5.27 – J5.28 Battery selection Connect J5.2 – J5.3 Connect J11.2 – J11.3

Refer to [1] and [2] for more details on how to set up a DA14585/586 DK for CR2032 battery operation.

6.15.2 Running the Example Once the user has built and loaded the example project to the DK, the ADC is configured to provide a measurement of the battery level. The percentage left indication calculated for the coin-cell battery CR2032 is displayed on the terminal screen (see Figure 28).

Figure 28: Battery Example

This example can be verified using an external voltage source (well-stabilized in the range 2.5 V to 3 V) instead of a 3 V battery. The DK must have been configured for 3 V operation.

User Manual Revision 5.0 14-May-2018

CFR0012 46 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

CAUTION The voltage of the external voltage source must never exceed 3 V.

For details about the configuration of the ADC, one should consult [5]. The source code for this example is in function batt_test in: \projects\target_apps\peripheral_examples\adc\batt_lvl\src\main.c.

User Manual Revision 5.0 14-May-2018

CFR0012 47 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7 Developing Bluetooth Low Energy Applications

7.1 The Seven Pillar Example Applications The DA14585/586 SDK 6.x includes seven pillar Bluetooth low energy example application projects to assist and guide on the development of Bluetooth Low Energy applications. Every pillar project inherits the functionality of a previous pillar project and adds extra features. The base pillar project is the Pillar 1 (bare bone), as it is depicted in Figure 29. The goal of the pillar example projects is to provide, in a step-by-step approach, an introduction and explanation of the Bluetooth low energy features and functionality as supported by the DA14585/586 software platform and devices.

Figure 29: Pillar Example Projects

User Manual Revision 5.0 14-May-2018

CFR0012 48 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.2 Pillar 1 (Bare Bone)

7.2.1 Application Description The Pillar 1 (bare bone) BLE example application demonstrates basic BLE procedures such as advertising, connection, connection parameters update and implementation of the Device Information Service Server (DISS). The application uses the “Integrated processor” configuration.

7.2.2 Basic Operation Supported services: ● Device Information service (UUID 0x180A). Features: ● Supports Extended Sleep mode ● Basic Configuration Settings: ○ Advertising interval ○ Connection interval. ○ Slave latency ○ Supervision timeout ● Advertising data: ○ Device name. ○ Device information service support. ○ Manufacturer specific data (for advertising data update feature): ○ - Company identifier ○ - Proprietary data: 16-bit counter ● Advertising data is updated on the fly every 30s as follows: ○ Change proprietary data (increment by 1 the 16-bit counter) ○ Restart advertising update timer The Pillar 1 application behavior is included in C source file user_barebone.c.

7.2.3 User Interface A peer such as a mobile phone connected to the Pillar 1 application can: ● Check the advertising device name. ● Check that the advertising data 16-bit counter is incremented in every advertising event or when the respective timer expires. ● Use the Device information service.

User Manual Revision 5.0 14-May-2018

CFR0012 49 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.2.4 Loading the Project The Pillar 1 application is developed under the Keil uVision v5tool. The Keil project file is: \projects\target_apps\ble_examples\ble_app_barebone\Keil_5\ble_app _barebone.uvprojx. Figure 30 shows the Keil project layout with the emphasis on the user application related files in the Keil project folders user_config, user_platform and user_app. These folders contain the user configuration files of the Pillar 1 application.

Figure 30: Pillar 1 Keil Project Layout

User Manual Revision 5.0 14-May-2018

CFR0012 50 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.2.5 Going Through the Code

7.2.5.1 Initialization The previously mentioned Keil project folders (user_config, user_platform and user_app) contain the files that initialize and configure the Pillar 1 application. \user_config ● da1458x_config_advanced.h, holds DA14585/586 advanced configuration settings. ● da1458x_config_basic.h, holds DA14585/586 basic configuration settings. ● user_callback_config.h, callback functions that handle various events or operations. ● user_config.h, holds advertising parameters, connection parameters, etc. ● user_modules_config.h, defines which application modules are included or excluded from the user’s application. For example: ○ #define EXCLUDE_DLG_DISS (0), the Device information application profile is included. The SDK takes care of the Device information application profile message handling. ○ #define EXCLUDE_DLG_DISS (1), the Device information application profile is excluded. The user application has to take care of the Device information application profile message handling. ● user_profiles_config.h, defines which BLE profiles (Bluetooth SIG adopted or custom ones) will be included in user’s application. Particularly, the C header files (each header file denotes the respective BLE profile) that are included in the user_profile_config.h file are: ○ CFG_PRF_DISS, includes the Device Information Service Server Role ● user_periph_setup.h, holds hardware related settings relative to the used Development Kit.

\user_platform ● user_periph_setup.c, source code file that handles peripheral (GPIO, UART, etc.) configuration and initialization relative to the Development Kit.

\user_app ● user_barebone.c, source code file that implements the application specific code such as creating the advertising packet, managing the timers to control the advertising period and handling connection events.

Note 8 The SDK by default as well as this application, during initialization, reads and uses the XTAL16M oscillator trimming value as stored in the OTP header. However, if there has been no trimming yet, the XTAL16M oscillator trimming value in the OTP Header will be zero, and this zero value will then be used by default from the SDK. To alter the default behavior, the SDK provides a configuration flag that allows the user to still read and use the XTAL16M oscillator trimming value from the OTP header, so that if the stored OTP value is zero, it reverts in using an indicative hardcoded value as the XTAL16M oscillator trimming value. You can read more about the XTAL16M oscillator trim on the OTP Header section in the device datasheet, or at Table 37, of Appendix G Booting from serial interfaces, in the UM-B-079 DA14585/586 SDK 6 Software Platform Reference document [5]. Note 9 The OTP header value for the XTAL16M oscillator trimming in the DA14585 and DA14586 devices on the Pro and Basic Development Kits, is not written (ie it is read as zero), to allow for the user/developer to provide and write a preferred XTAL16M oscillator trimming value. Therefore, if you have not calculated and written already a non-zero value, in the XTAL16M oscillator trimming value for the Development Kit that you have in use, it is advised to enable and use in this application and in the SDK the CFG_USE_DEFAULT_XTAL16M_TRIM_VALUE_IF_NOT_CALIBRATED configuration flag, that resides within the da1458x_config_advanced.h file as follows; #define CFG_USE_DEFAULT_XTAL16M_TRIM_VALUE_IF_NOT_CALIBRATED

User Manual Revision 5.0 14-May-2018

CFR0012 51 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.2.5.2 Events Processing and Callbacks Several events can occur during the lifetime of the Bluetooth low energy application and these events need to be handled in a specific manner. The application is responsible for selecting which events and operations it should handle and which it should just leave to be handled with the default SDK behavior. The SDK uses a mechanism which registers callbacks for every event or operation that defines the system behavior. The C header file user_callback_config.h, which is part of the user application contains the registration of callback functions.

The Pillar 1 application registers the following callback functions: ● General BLE events: static const struct app_callbacks user_app_callbacks = { .app_on_connection = user_app_connection, .app_on_disconnect = user_app_disconnect, .app_on_update_params_rejected = NULL, .app_on_update_params_complete = NULL, .app_on_set_dev_config_complete = default_app_on_set_dev_config_complete, .app_on_adv_nonconn_complete = NULL, .app_on_adv_undirect_complete = user_app_adv_undirect_complete, .app_on_adv_direct_complete = NULL, .app_on_db_init_complete = default_app_on_db_init_complete, .app_on_scanning_completed = NULL, .app_on_adv_report_ind = NULL, .app_on_get_dev_name = default_app_on_get_dev_name, .app_on_get_dev_appearance = default_app_on_get_dev_appearance, .app_on_get_dev_slv_pref_params = default_app_on_get_dev_slv_pref_params, .app_on_set_dev_info = default_app_on_set_dev_info, .app_on_data_length_change = NULL, .app_on_update_params_request = default_app_update_params_request, .app_on_generate_static_random_addr = default_app_generate_static_random_addr, .app_on_svc_changed_cfg_ind = NULL, #if (BLE_APP_SEC) .app_on_pairing_request = NULL, .app_on_tk_exch = NULL, .app_on_irk_exch = NULL, .app_on_csrk_exch = NULL, .app_on_ltk_exch = NULL, .app_on_pairing_succeeded = NULL, .app_on_encrypt_ind = NULL, .app_on_encrypt_req_ind = NULL, .app_on_security_req_ind = NULL, .app_on_addr_solved_ind = NULL, .app_on_addr_resolve_failed = NULL, .app_on_ral_cmp_evt = NULL, .app_on_ral_size_ind = NULL, .app_on_ral_addr_ind = NULL, #endif // (BLE_APP_SEC) }; The above structure defines that a certain event will be processed by a default handler or by a user defined handler or it will not be processed at all (NULL entries). The user defined handlers (e.g. user_app_connection(), user_app_disconnect() and user_app_adv_undirect_complete()) are defined in C source file user_barebone.c. ● System specific events: static const struct app_bond_db_callbacks user_app_bond_db_callbacks = { .app_bdb_init = NULL,

User Manual Revision 5.0 14-May-2018

CFR0012 52 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

.app_bdb_get_size = NULL, .app_bdb_add_entry = NULL, .app_bdb_remove_entry = NULL, .app_bdb_search_entry = NULL, .app_bdb_get_number_of_stored_irks = NULL, .app_bdb_get_stored_irks = NULL, .app_bdb_get_device_info_from_slot = NULL, }; The above structure defines that a certain event will be processed by a default handler or by a user defined handler or it will not be processed at all (NULL entries). The user defined handlers (e.g. user_app_init()) are defined in C source file user_barebone.c. ● BLE operations: static const struct default_app_operations user_default_app_operations = { .default_operation_adv = user_app_adv_start, }; The above structure defines that a certain operation will be processed by a default handler or by a user defined handler or it will not be processed at all (NULL entries). The user defined handlers (e.g. user_app_adv_start()) is defined in C source file user_barebone.c.

User Manual Revision 5.0 14-May-2018

CFR0012 53 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.2.5.3 BLE Application Abstract Code Flow Figure 31 shows the abstract code flow diagram of the Pillar 1 application. The diagram depicts the SDK interaction with the callback functions registered in user_callback_config.h and the functions implemented in user_barebone.c.

User User SDK Application Configuration

app_on_init() user_app_init()

default_app_on_init()

app_on_set_dev_config_complete()

default_app_on_set_dev_config_complete()

app_on_db_init_complete()

default_app_on_db_init_complete()

default_operation_adv() user_app_adv_start()

app_easy_gap_undirected_advertise_start() t ) c

app_on_adv_undirect_complete() e e c i n v n user_app_adv_undirect_complete() e o d

c

r o e t e

t

app_on_connection() p s

e

user_app_connection() m u o q r f e (

default_app_on_connection() R

Figure 31: Pillar 1 Application - User Application Code Flow

User Manual Revision 5.0 14-May-2018

CFR0012 54 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.2.6 Building the Project for Different Targets and Development Kits The Pillar 1 application can be built for two different target processors: DA14585 and DA14586. The selection is done via the Keil tool as shown in Figure 32.

Figure 32: Building the Project for Different Targets

The user has also to select the correct Development Kit in order to build and run the application. This selection is done via the Configuration Wizard of the user_periph_setup.h file via the Configuration Wizard tab shown at the bottom of the text editor pane shown in Figure 33.

Figure 33: Development Kit Selection for Pillar 1 Application

After the proper selection of the target processor and development kit, the application is ready to be built.

User Manual Revision 5.0 14-May-2018

CFR0012 55 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

The Pillar 1 application does not use the UART and so the only jumpers that must be present are those for the debugger interface as noted in Table 2.

7.2.7 Interacting with BLE Application As described earlier in Section 5.7 it is possible to use either an iOS app like LightBlue or an Android app like BLE Scanner to interact with the Pillar applications. The screenshots for the rest of this document will only show the LightBlue applications.

7.2.7.1 LightBlue iOS The LightBlue iOS application can be used to connect an iPad/iPod/iPhone device to the application. In such a case the iPad/iPod/iPhone acts as a BLE Central and the application as a BLE Peripheral. Figure 34 shows the result when the iPad/iPod/iPhone device manages to connect to the DA14585/586 (the application’s advertising device name is DIALOG-BRBN).

User Manual Revision 5.0 14-May-2018

CFR0012 56 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Figure 34: LightBlue Application Connected to Pillar 1 Application

7.3 Pillar 2 (Custom Profile)

7.3.1 Application Description The Pillar 2 (custom profile) Bluetooth low energy example application has the same functionality as the Pillar 1 application and adds the implementation of a user defined custom service (128-bit UUID). The aim of Pillar 2 is to demonstrate only the custom database creation. It uses the “Integrated processor” configuration.

User Manual Revision 5.0 14-May-2018

CFR0012 57 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.3.2 Basic Operation Supported services: ● Inherits the services from the Pillar 1 application, plus: ● Custom service defined by the user with 128-bit UUID. Features: ● Inherits the features from Pillar 1 application, plus: ● Advertising data is updated on the fly every 30s ● 3 custom services: ○ Custom Service 1. Table 12 shows the Custom service 1 characteristic values along with their properties. ○ Custom Service 2. Table 13 shows the Custom service 2 characteristic values along with their properties. ○ Custom Service 3. Table 14 shows the Custom service 2 characteristic values along with their properties. The Pillar 2 behavior is included in C source file user_profile.c.

Table 12: Pillar 2 Custom Service 1 Characteristic Values and Properties Name Properties Length (B) Description/Purpose CONTROL POINT WRITE 1 Accept commands from peer LED STATE WRITE NO RESPONSE 1 Toggles a LED connected to a GPIO ADC VAL 1 READ, NOTIFY 2 Reads sample from an ADC channel ADC VAL 2 READ 2 Reads sample from an ADC channel BUTTON STATE READ, NOTIFY 1 Reads the current state of a push button connected a GPIO INDICATEABLE CHAR READ, INDICATE 20 Demonstrate indications LONG VAL CHAR READ, WRITE, NOTIFY 50 Demonstrate writes to long characteristic value

Table 13: Pillar 2 Custom Service 2 Characteristic Values and Properties

Name Properties Length (B) Description/Purpose WRITE ME WRITE 1 Custom characteristic that accepts commands from peer WRITE ME (NO RSP) WRITE NO RESPONSE 1 Custom characteristic that accepts commands from peer

Table 14: Pillar 2 Custom Service 3 Characteristic Values and Properties

Name Properties Length (B) Description/Purpose READ ME (NOTIFY) READ, NOTIFY 2 Reads a value READ ME READ 2 Reads a value READ ME (INDICATE) READ, INDICATE 2 Demonstrate indications

User Manual Revision 5.0 14-May-2018

CFR0012 58 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

The Pillar 2 application does not provide any behavior for the new added Custom services. It just demonstrates the databases creation of the Custom services. Note 10 For more information about the Custom services of the Pillar 2 please check user_custs1_def.h C header file located in \projects\target_apps\ble_examples\ble_app_profile\src\custom_profil e.

7.3.3 User Interface A peer connected to the Pillar 2 application can do the same as in the Pillar 1 application, plus: ● Inspect the Custom services.

User Manual Revision 5.0 14-May-2018

CFR0012 59 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.3.4 Loading the project The Pillar 2 application is developed under the Keil v5 tool. The Keil project file is the: projects\target_apps\ble_examples\ble_app_profile\Keil_5\ble_app_profile.uvprojx. Figure 35 shows the Keil project layout with emphasis on the user configuration files, included in the Keil project folders user_config, user_platform, user_custom_profile and user_app.

Figure 35: Pillar 2 Keil Project Layout The additional folder, compared to Pillar 1, is user_custom_profile.

User Manual Revision 5.0 14-May-2018

CFR0012 60 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.3.5 Going Through the Code

7.3.5.1 Initialization The previously mentioned Keil project folders (user_config, user_platform, user_custom_profile and user_app) contain the files that initialize and configure the Pillar 2 application. \user_config ● da1458x_config_advanced.h, holds DA14585/586 advanced configuration settings. ● da1458x_config_basic.h, holds DA14585/586 basic configuration settings. ● user_callback_config.h, callback functions that handle various events or operations. ● user_config.h, holds advertising parameters, connection parameters, etc. ● user_modules_config.h, defines which application modules are included or excluded from the user’s application. For example: ○ #define EXCLUDE_DLG_DISS (0), the Device information application profile is included. The SDK takes care of the Device information application profile message handling. ○ #define EXCLUDE_DLG_DISS (1), the Device information application profile is excluded. The user application has to take care of the Device information application profile message handling. ● user_periph_setup.h, holds hardware related settings relative to the used Development Kit. ● user_profiles_config.h, defines which BLE profiles (Bluetooth SIG adopted or custom ones) will be included in user’s application. Particularly, the C header files (each header file denotes the respective BLE profile) that are included in the user_profile_config.h file are: ○ CFG_PRF_DISS, includes the Device Information service. ○ CFG_PRF_CUST1, includes the Custom 1 service. \user_custom_profile ● user_custs1_def.c, defines the structure of the Custom 1 profile database structure. ● user_custs_config.c, defines the cust_prf_funcs[] array, which contains the Custom profiles API functions calls. \user_platform ● user_periph_setup.c, source code file that handles peripheral (GPIO, UART, etc.) configuration and initialization relative to the Development Kit. \user_app ● user_profile.c, source code file that implements the application specific code such as creating the advertising packet, managing the timers to control the advertising period and handling connection events.

Note 11 The SDK by default as well as this application, during initialization, reads and uses the XTAL16M oscillator trimming value as stored in the OTP header. However, if there has been no trimming yet, the XTAL16M oscillator trimming value in the OTP Header will be zero, and this zero value will then be used by default from the SDK. To alter the default behavior, the SDK provides a configuration flag that allows the user to still read and use the XTAL16M oscillator trimming value from the OTP header, so that if the stored OTP value is zero, it reverts in using an indicative hardcoded value as the XTAL16M oscillator trimming value. You can read more about the XTAL16M oscillator trim on the OTP Header section in the device datasheet, or at Table 37, of Appendix G Booting from serial interfaces, in the UM-B-079 DA14585/586 SDK 6 Software Platform Reference document [5]. Note 12 The OTP header value for the XTAL16M oscillator trimming in the DA14585 and DA14586 devices on the Pro and Basic Development Kits, is not written (ie it is read as zero), to allow for the user/developer to provide and write a preferred XTAL16M oscillator trimming value. Therefore, if you have not calculated and written already a non-zero value, in the XTAL16M oscillator trimming value for the Development Kit that you have in use, it is advised to enable and use in this application and in the

User Manual Revision 5.0 14-May-2018

CFR0012 61 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

SDK the CFG_USE_DEFAULT_XTAL16M_TRIM_VALUE_IF_NOT_CALIBRATED configuration flag, that resides within the da1458x_config_advanced.h file as follows; #define CFG_USE_DEFAULT_XTAL16M_TRIM_VALUE_IF_NOT_CALIBRATED

7.3.5.2 Events Processing and Callbacks Several events can occur during the lifetime of the Bluetooth low energy application and these events need to be handled in a specific manner. The application is responsible for selecting which events and operations it should handle and which it should just leave to be handled with the default SDK behavior. The SDK uses a mechanism which registers callbacks for every event or operation that defines the system behavior. The C header file user_callback_config.h, which is part of the user application contains the registration of callback functions. The Pillar 2 application registers the following callback functions: ● General BLE events: static const struct app_callbacks user_app_callbacks = { .app_on_connection = user_app_connection, .app_on_disconnect = user_app_disconnect, .app_on_update_params_rejected = NULL, .app_on_update_params_complete = NULL, .app_on_set_dev_config_complete = default_app_on_set_dev_config_complete, .app_on_adv_nonconn_complete = NULL, .app_on_adv_undirect_complete = user_app_adv_undirect_complete, .app_on_adv_direct_complete = NULL, .app_on_db_init_complete = default_app_on_db_init_complete, .app_on_scanning_completed = NULL, .app_on_adv_report_ind = NULL, .app_on_get_dev_name = default_app_on_get_dev_name, .app_on_get_dev_appearance = default_app_on_get_dev_appearance, .app_on_get_dev_slv_pref_params = default_app_on_get_dev_slv_pref_params, .app_on_set_dev_info = default_app_on_set_dev_info, .app_on_data_length_change = NULL, .app_on_update_params_request = default_app_update_params_request, .app_on_generate_static_random_addr = default_app_generate_static_random_addr, .app_on_svc_changed_cfg_ind = NULL, #if (BLE_APP_SEC) .app_on_pairing_request = NULL, .app_on_tk_exch = NULL, .app_on_irk_exch = NULL, .app_on_csrk_exch = NULL, .app_on_ltk_exch = NULL, .app_on_pairing_succeeded = NULL, .app_on_encrypt_ind = NULL, .app_on_encrypt_req_ind = NULL, .app_on_security_req_ind = NULL, .app_on_addr_solved_ind = NULL, .app_on_addr_resolve_failed = NULL, .app_on_ral_cmp_evt = NULL, .app_on_ral_size_ind = NULL, .app_on_ral_addr_ind = NULL, #endif // (BLE_APP_SEC) }; The above structure defines that a certain event will be processed by a default handler or by a user defined handler or it will not be processed at all (NULL entries). The user defined handlers (e.g user_app_connection(), user_app_disconnect() and user_app_adv_undirect_complete()) are defined in C source file user_profile.c. ● System specific events:

User Manual Revision 5.0 14-May-2018

CFR0012 62 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

static const struct arch_main_loop_callbacks user_app_main_loop_callbacks = { .app_bdb_init = NULL, .app_bdb_get_size = NULL, .app_bdb_add_entry = NULL, .app_bdb_remove_entry = NULL, .app_bdb_search_entry = NULL, .app_bdb_get_number_of_stored_irks = NULL, .app_bdb_get_stored_irks = NULL, .app_bdb_get_device_info_from_slot = NULL, };

The above structure defines that a certain event will be processed by a default handler or by a user defined handler or it will not be processed at all (NULL entries). The user defined handler (e.g. user_app_init()) is defined in C source file user_profile.c. ● BLE operations: static const struct default_app_operations user_default_app_operations = { .default_operation_adv = user_app_adv_start, }; The above structure defines that a certain operation will be processed by a default handler or by a user defined handler or it will not be processed at all (NULL entries). The user defined handlers (e.g. user_app_adv_start()) is defined in C source file user_profile.c. ● Custom profile message handling: static const catch_rest_event_func_t app_process_catch_rest_cb = (catch_rest_event_func_t)user_catch_rest_hndl; Callback function that contains the Custom profile messages handling in user application space. For Pillar 2 application this function is totally unused, since Pillar 2 application does not include any behavior related to the Custom service. Subsequent Pillar examples will provide this.

User Manual Revision 5.0 14-May-2018

CFR0012 63 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.3.5.3 BLE Application Abstract Code Flow Figure 36 shows the abstract code flow diagram of the Pillar 2 application. The diagram depicts the SDK interaction with the callback functions registered in user_callback_config.h and the functions implemented in user_profile.c.

User User SDK Application Configuration

app_on_init() user_app_init()

default_app_on_init()

app_on_set_dev_config_complete()

default_app_on_set_dev_config_complete()

app_on_db_init_complete()

default_app_on_db_init_complete()

default_operation_adv() user_app_adv_start()

app_easy_gap_undirected_advertise_start()

app_on_adv_undirect_complete() ) user_app_adv_undirect_complete()

app_on_connection()

user_app_connection()

from peer devicepeerfrom

(

default_app_on_connection() Request to connect

Figure 36: Pillar 2 Application - User Application Code Flow

7.3.6 Building the Project for Different Targets and Development Kits The Pillar 2 application can be built for two different target processors: DA14585 and DA14586. The selection is done via the Keil tool as depicted in Figure 37.

User Manual Revision 5.0 14-May-2018

CFR0012 64 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Figure 37: Building the Project for Different Targets

The user has also to select the correct Development Kit in order to build and run the application. This selection is done via the Configuration Wizard of the user_periph_setup.h file as shown in Figure 38.

Figure 38: Development Kit Selection for Pillar 2 Application

After the proper selection of the target processor and development kit, the application is ready to be built. The Pillar 2 application does not use the UART and so the only jumpers that must be present are those for the debugger interface as noted in Table 2.

User Manual Revision 5.0 14-May-2018

CFR0012 65 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.3.7 Interacting with BLE Application

7.3.7.1 LightBlue iOS The LightBlue iOS application can be used to connect an iPad/iPod/iPhone device to the application. In such a case the iPad/iPod/iPhone acts as a BLE Central and the application as a BLE Peripheral. Figure 39 shows the result when the iPad/iPod/iPhone device manages to connect to the DA14585/586 (the application’s advertising device name is DIALOG-PRFL).

Figure 39: LightBlue Application Connected to Pillar 2 Application

User Manual Revision 5.0 14-May-2018

CFR0012 66 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.4 Pillar 3 (Peripheral) The Pillar 3 (peripheral) BLE example application demonstrates the same as the Pillar 2 application. The application also adds some basic functionality to the custom service (read/write/notify values). It uses the “Integrated processor” configuration.

7.4.1 Basic Operation Supported services: ● Inherits the services from Pillar 2 application. Features: ● Inherits the features from Pillar 2 application, plus: ● In Custom Service 1 CONTROL POINT, LED STATE and ADC VAL 1 characteristic values introduce some behavior with a connected peer device. In Custom Services 2 and 3 characteristic values do not have any functionality added, they are just dummy characteristics. The Pillar 3 application behavior is included in C source file user_peripheral.c. Table 15 shows the Custom service characteristic values along with their properties.

Table 15. Pillar 3 Custom Service Characteristic Values and Properties Name Properties Length (B) Description/Purpose CONTROL POINT WRITE 1 Accept commands from peer LED STATE WRITE NO RESPONSE 1 Toggles a LED connected to a GPIO ADC VAL 1 READ, NOTIFY 2 Reads sample from an ADC channel (in reality returns an incrementing counter) ADC VAL 2 READ 2 Reads sample from an ADC channel BUTTON STATE READ, NOTIFY 1 Reads the current state of a push button connected a GPIO INDICATEABLE CHAR READ, INDICATE 20 Demonstrate indications LONG VAL CHAR READ, WRITE. NOTIFY 50 Demonstrate writes to long characteristic value

The Pillar 3 application adds functionality only for the highlighted characteristic values of the Custom 1 service. The implementation code of the Custom service is included in C source file user_custs1_impl.c.

7.4.2 User Interface A peer connected to the Pillar 3 application can do the same as in the Pillar 2 application, plus: ● Use the Custom service. ● Write to Control Point of the Custom Service: ○ Byte 0x00 disables ADC VAL 1 auto notifications (disables respective timer). ○ Byte 0x01 enables ADC VAL 1 auto notifications (enables respective timer). ● Write to LED STATE of the Custom Service: ○ Byte 0x00 turns an LED off. ○ Byte 0x01 turns an LED on. ● Read/notify ADC VAL 1 value. When the ADC VAL 1 auto notifications are turned on and the notify operation is required by the peer, a 16-bit counter is incremented. This counter value emulates the Analog value of the ADC VAL 1 (there is no hardware support for reading an Analog value).

User Manual Revision 5.0 14-May-2018

CFR0012 67 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

The selected LED (port and pin number of the DA14585/586) is defined by the user configuration based on the chosen DK. The user files user_periph_setup.h and user_periph_setup.c hold the peripheral configuration settings of the LED.

7.4.3 Loading the Project The Pillar 3 application is developed under the Keil v5 tool. The Keil project file is: \projects\target_apps\ble_examples\ble_app_peripheral\ble_app_peri pheral.uvprojx. Figure 40 shows the Keil project layout with emphasis on the user related files, included in the Keil project folders user_config, user_platform, user_custom_profile and user_app. These folders contain the user configuration files of the Pillar 3 application.

Figure 40: Pillar 3 Keil Project Layout

The additional file, compared to Pillar 2, is the user_custs1_impl.c.

User Manual Revision 5.0 14-May-2018

CFR0012 68 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.4.4 Going Through the Code

7.4.4.1 Initialization The previously mentioned project folders (user_config, user_platform, user_custom_profile and user_app) contain the files that initialize and configure the Pillar 3 application. \user_config ● da1458x_config_advanced.h, holds DA14585/586 advanced configuration settings. ● da1458x_config_basic.h, holds DA14585/586 basic configuration settings. ● user_callback_config.h, callback functions that handle various events or operations. ● user_config.h, holds advertising parameters, connection parameters, etc. ● user_modules_config.h, defines which application modules are included or excluded from the user’s application. For example: ○ #define EXCLUDE_DLG_DISS (0), the Device information application profile is included. The SDK takes care of the Device information application profile message handling. ○ #define EXCLUDE_DLG_DISS (1), the Device information application profile is excluded. The user application has to take care of the Device information application profile message handling. ● user_periph_setup.h, holds hardware related settings relative to the used Development Kit. ● user_profiles_config.h, defines which BLE profiles (Bluetooth SIG adopted or custom ones) will be included in user’s application. Particularly, the C header files (each header file denotes the respective BLE profile) that are included in the user_profile_config.h file are: ○ CFG_PRF_DISS, includes the Device Information service. ○ CFG_PRF_CUST1, includes the Custom 1 service. \user_custom_profile ● user_custs_config.c, defines the cust_prf_funcs[] array, which contains the Custom profiles API functions calls. ● user_custs1_def.c, defines the Custom 1 profile database structure. \user_platform ● user_periph_setup.c, source code file that handles peripheral (GPIO, UART, etc.) configuration and initialization relative to the Development Kit. \user_app  user_custs1_impl.c source file that adds the read and write handlers for accesses to the custom 1 service characteristics. ● user_peripheral.c source code file that implements the application specific code such as creating the advertising packet, managing the timers to control the advertising period and handling connection events. In addition it provides user_catch_rest_hndl() which is the handler for the requests to the custom 1 service such as read, write, confirm and notify.

Note 13 The SDK by default as well as this application, during initialization, reads and uses the XTAL16M oscillator trimming value as stored in the OTP header. However, if there has been no trimming yet, the XTAL16M oscillator trimming value in the OTP Header will be zero, and this zero value will then be used by default from the SDK. To alter the default behavior, the SDK provides a configuration flag that allows the user to still read and use the XTAL16M oscillator trimming value from the OTP header, so that if the stored OTP value is zero, it reverts in using an indicative hardcoded value as the XTAL16M oscillator trimming value. You can read more about the XTAL16M oscillator trim on the OTP Header section in the device datasheet, or at Table 37, of Appendix G Booting from serial interfaces, in the UM-B-079 DA14585/586 SDK 6 Software Platform Reference document [5]. Note 14 The OTP header value for the XTAL16M oscillator trimming in the DA14585 and DA14586 devices on the Pro and Basic Development Kits, is not written (ie it is read as zero), to allow for the user/developer to provide and write a preferred XTAL16M oscillator trimming value. Therefore, if you have not calculated and written already a non-zero value, in the XTAL16M oscillator trimming value for User Manual Revision 5.0 14-May-2018

CFR0012 69 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

the Development Kit that you have in use, it is advised to enable and use in this application and in the SDK the CFG_USE_DEFAULT_XTAL16M_TRIM_VALUE_IF_NOT_CALIBRATED configuration flag, that resides within the da1458x_config_advanced.h file as follows; #define CFG_USE_DEFAULT_XTAL16M_TRIM_VALUE_IF_NOT_CALIBRATED

7.4.4.2 Events Processing and Callbacks Several events can occur during the lifetime of the Bluetooth low energy application and these events need to be handled in a specific manner. The application is responsible for selecting which events and operations it should handle and which it should just leave to be handled with the default SDK behavior. The SDK uses a mechanism which registers callbacks for every event or operation that defines the system behavior. The C header file user_callback_config.h, which is part of the user application contains the registration of callback functions. For example, in the Pillar 3 application the user_app_callbacks[] array has the following entries: static const struct app_callbacks user_app_callbacks = { .app_on_connection = user_app_connection, .app_on_disconnect = user_app_disconnect, .app_on_update_params_rejected = NULL, .app_on_update_params_complete = NULL, .app_on_set_dev_config_complete = default_app_on_set_dev_config_complete, .app_on_adv_nonconn_complete = NULL, .app_on_adv_undirect_complete = user_app_adv_undirect_complete, .app_on_adv_direct_complete = NULL, .app_on_db_init_complete = default_app_on_db_init_complete, .app_on_scanning_completed = NULL, .app_on_adv_report_ind = NULL, .app_on_get_dev_name = default_app_on_get_dev_name, .app_on_get_dev_appearance = default_app_on_get_dev_appearance, .app_on_get_dev_slv_pref_params = default_app_on_get_dev_slv_pref_params, .app_on_set_dev_info = default_app_on_set_dev_info, .app_on_data_length_change = NULL, .app_on_update_params_request = default_app_update_params_request, .app_on_generate_static_random_addr = default_app_generate_static_random_addr, .app_on_svc_changed_cfg_ind = NULL, #if (BLE_APP_SEC) .app_on_pairing_request = NULL, .app_on_tk_exch = NULL, .app_on_irk_exch = NULL, .app_on_csrk_exch = NULL, .app_on_ltk_exch = NULL, .app_on_pairing_succeeded = NULL, .app_on_encrypt_ind = NULL, .app_on_encrypt_req_ind = NULL, .app_on_security_req_ind = NULL, .app_on_addr_solved_ind = NULL, .app_on_addr_resolve_failed = NULL, .app_on_ral_cmp_evt = NULL, .app_on_ral_size_ind = NULL, .app_on_ral_addr_ind = NULL, #endif // (BLE_APP_SEC) }; The above array defines that a certain event will be processed by a default handler or by a user defined handler or it will not be processed at all (NULL entries). The user defined handlers (e.g. user_app_connection(), user_app_disconnect() and user_app_adv_undirect_complete()) are defined in C source file user_peripheral.c.

User Manual Revision 5.0 14-May-2018

CFR0012 70 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

An important change to Pillar 3 application is the addition of the new calls for all the Custom profile operations to user_catch_rest_hndl(). The implementation of these handlers is in C source file user_custs1_impl.c. These Custom profile messages are application specific and their handling is transferred to user application. The SDK is agnostic of the specific Custom profile messages and it is the user’s application responsibility to handle them. The user_callback_config.h configuration header file contains the registration of the callback function user_catch_rest_hndl(), as is described below. static const catch_rest_event_func_t app_process_catch_rest_cb = (catch_rest_event_func_t)user_catch_rest_hndl;

User Manual Revision 5.0 14-May-2018

CFR0012 71 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.4.4.3 BLE Application Abstract Code Flow Figure 41 shows the abstract code flow diagram of the Pillar 3 application. The diagram depicts the SDK interaction with the callback functions registered in user_callback_config.h and the functions implemented in user_peripheral.c.

User User SDK Application Configuration

app_on_init() user_app_init()

default_app_on_init()

app_on_set_dev_config_complete()

default_app_on_set_dev_config_complete()

app_on_db_init_complete()

default_app_on_db_init_complete()

default_operation_adv() user_app_adv_start()

app_easy_gap_undirected_advertise_start() t ) c

app_on_adv_undirect_complete() e e c i n v n user_app_adv_undirect_complete() e o d

c

r o e t e

t

app_on_connection() p s

e

user_app_connection() m u o q r f e (

default_app_on_connection() R

Figure 41: Pillar 3 Application - User Application Code Flow

User Manual Revision 5.0 14-May-2018

CFR0012 72 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.4.5 Building the Project for Different Targets and Development Kits The Pillar 3 application can be built for two different target processors: DA14585 and DA14586. The selection is done via the Keil tool as depicted in Figure 42.

Figure 42: Building the Project for Different Targets

The user has also to select the correct Development Kit in order to build and run the application. This selection is done via the Configuration Wizard of the user_periph_setup.h file as shown in Figure 43.

Figure 43: Development Kit Selection for Pillar 3 Application

After the proper selection of the target processor and development kit, the application is ready to be built. The Pillar 3 application does not use the UART and so the only jumpers that must be present are those for the debugger interface as noted in Table 2.

User Manual Revision 5.0 14-May-2018

CFR0012 73 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.4.6 Interacting with BLE Application

7.4.6.1 LightBlue iOS The LightBlue iOS application can be used to connect an iPad/iPod/iPhone device to the application. In such a case the iPad/iPod/iPhone acts as a BLE Central and the application as a BLE Peripheral. Figure 44 shows the result when the iPad/iPod/iPhone device manages to connect to the DA14585/586(the application’s advertising device name is DIALOG-PRPH).

Figure 44: LightBlue Application Connected to Pillar 3 Application

User Manual Revision 5.0 14-May-2018

CFR0012 74 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.5 Pillar 4 (Security)

7.5.1 Application Description The Pillar 4 (security) BLE example application has the same services as the Pillar 2 application. The difference is that Pillar 4 adds support for different security models and bonding procedures which are selected in compile time. It uses the “Integrated processor” configuration.

7.5.2 Basic Operation Supported services: ● Inherits the services from Pillar 2 application. Features: ● Inherits the features from Pillar 2 application, plus: ● Access to the service inherited from Pillar 2 is protected according to current security configuration set through the CFG_APP_SECURITY flag in da1458x_config_basic.h. The Pillar 4 application behavior is included in C source file user_security.c. Table 16 shows the Custom service characteristic values along with their properties.

Table 16: Pillar 4 Custom Service Characteristic Values and Properties Name Properties Length (B) Description/Purpose CONTROL POINT WRITE 1 Accept commands from peer LED STATE WRITE NO RESPONSE 1 Toggles a LED connected to a GPIO ADC VAL 1 READ, NOTIFY 2 Reads sample from an ADC channel ADC VAL 2 READ 2 Reads sample from an ADC channel BUTTON STATE READ, NOTIFY 1 Reads the current state of a push button connected a GPIO INDICATEABLE CHAR READ, INDICATE 20 Demonstrate indications LONG VAL CHAR READ, WRITE. NOTIFY 50 Demonstrate writes to long characteristic value

The Pillar 4 application does not provide any behavior for the added Custom services. It just demonstrates the various security features and the creation of the Custom services. Every access to the Custom service is possible only when certain security conditions are met. This may include valid bond and/or encrypted connection. It depends on the currently selected security setup.

7.5.3 User Interface A peer connected to the Pillar 4 application can do the same as in the Pillar 2 application, plus: ● Use the Custom service with certain preconditions. The preconditions required reading from or writing to a Custom service’s characteristics or reading their descriptors depends on the currently selected security preset.

7.5.4 Loading the Project The Pillar 4 application is developed under the Keil v5 tool. The Keil project file is the: projects\target_apps\ble_examples\ble_app_security\Keil_5\ble_app_security.uvprojx The following picture shows the Keil project layout with emphasis on the user related files, included in the Keil project folders user_config, user_platform, user_custom_profile and user_app. These folders contain the user configuration files of the Pillar 4 application.

User Manual Revision 5.0 14-May-2018

CFR0012 75 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Figure 45: Pillar 4 Keil Project Layout

7.5.5 Going Through the Code

7.5.5.1 Initialization The previously mentioned Keil project folders (user_config, user_platform, user_custom_profile and user_app) contain the files that initialize and configure the Pillar 4 application. \user_config ● da1458x_config_advanced.h, holds DA14585/586advanced configuration settings. ● da1458x_config_basic.h, holds DA14585/586basic configuration settings. ● user_callback_config.h, callback functions that handle various events or operations. ● user_config.h, holds advertising parameters, connection parameters, etc. It also holds the flag used for configuring the security features at compile time. More specifically, the user may define: ○ The IO capabilities of the device ○ The support of Out of Band (OOB) data ○ The authentication requirements ○ The encryption key size

User Manual Revision 5.0 14-May-2018

CFR0012 76 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

○ The minimum allowed security level (security requirements) ○ The key distribution capabilities ○ Depending on the user security configuration and the security capabilities of the peer device, one of the following pairing methods may occur: . Legacy Pairing – OOB . Legacy Pairing – Just Works . Legacy Pairing – Passkey Entry . Secure Connection – Just Works . Secure Connection – Passkey Entry . Secure Connection – Numeric Comparison ○ If none of the above flags is defined, then the security features will be set to the minimum security capabilities. ○ Peer device’s bond data can be stored on an external SPI Flash or I2C EEPROM memory. SPI Flash is the default setting. . #define USER_CFG_APP_BOND_DB_USE_SPI_FLASH, for SPI Flash (default) . #define USER_CFG_APP_BOND_DB_USE_I2C_EEPROM, for I2C EEPROM. . If neither of the above flags is defined the bond data will be only cached in the application RAM. . #define USER_CFG_BOND_DB_MAX_BONDED_PEERS, number of maximum bond data slots in database. Note 15 At the time of writing this document, neither Android nor iOS support the OOB mechanism for Bluetooth pairing. SmartBond™ DA14585/586 supports the OOB mechanism, only when legacy pairing is used. ● This configuration header file allows also selecting the addressing mode and privacy capabilities of the peripheral device by setting the USER_CFG_ADDRESS_MODE flag to one of the following options: ○ APP_CFG_ADDR_PUB: . The peripheral device is non-private and operates with Public Address. Although it does not claim privacy support, it can resolve the Random Resolvable Private Address (RPA) of a bonded peer in its BLE host layer. . The Public Address of the device shall be set in CFG_NVDS_TAG_BD_ADDRESS flag in da1458x_config_advanced.h. This address does not change upon power-cycle. ○ APP_CFG_ADDR_STATIC: . The peripheral device is non-private and operates with a Random Static Address (RSA). Although it does not claim privacy support, it can resolve the RPA of a bonded peer in its BLE host layer. . There are three options to configure the RSA:  If user_gapm_conf.addr_type is set to a valid RSA, then this RSA will be used. This address does not change upon power-cycle.  If user_gapm_conf.addr_type is not valid and default_app_generate_static_random_addr is connected to app_on_generate_static_random_addr in user_callback_config.h, then a new RSA will be generated at each power-cycle.  If user_gapm_conf.addr_type is not valid and default_app_generate_unique_static_random_addr is connected to app_on_generate_static_random_addr in user_callback_config.h, then a unique device RSA will be generated based on information stored in the OTP header. This address does not change upon power-cycle.

User Manual Revision 5.0 14-May-2018

CFR0012 77 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

○ APP_CFG_HOST_PRIV_RPA: . The peripheral device is a private one and operates with a RPA generated in its BLE host layer. The RPA of a bonded peer can also be resolved in its BLE host layer. . Identity information: The device shall exchange its identity information during pairing procedure.  A valid IRK shall be set in user_gapm_conf.irk and GAP_KDIST_IDKEY shall be enabled in USER_CFG_FEAT_RESP_KDIST.  The device will always send as identity address its Public Address defined in CFG_NVDS_TAG_BD_ADDRESS.  Renew duration: The interval of generating a new RPA shall be set in user_gapm_conf.renew_dur. This field controls the duration of RPA before it gets regenerated and it is counted in units of 10 ms. The minimum valid value for renew_dur is 15000 (150 s). If the value of renew_dur is set to less than 15000 then BLE stack will automatically set it to 15000. ○ APP_CFG_HOST_PRIV_NRPA: . The device is a private one and operates with a non-RPA generated in its BLE host layer. This configuration can only be used in non-connectable modes/procedures (e.g. broadcaster role, non-connectable advertising). ○ APP_CFG_CNTL_PRIV_RPA_PUB: . The peripheral device is a private one and operates with a RPA generated in its BLE controller layer. When the device is bonded with a peer, then the device information of the peer will be stored in the resolving list located in the BLE controller layer. Upon re-connection, the RPA of the bonded peer will be automatically resolved in the BLE controller layer and its identity will be directly used in the application layer of the peripheral device. If the resolving list of the peripheral is empty (no bonded devices), then it will operate with a Public Address. . Identity information: The device shall exchange its identity information during pairing procedure.  A valid IRK shall be set in user_gapm_conf.irk and GAP_KDIST_IDKEY shall be enabled in USER_CFG_FEAT_RESP_KDIST.  The device will always send as identity address its Public Address defined in CFG_NVDS_TAG_BD_ADDRESS.  Renew duration: The interval of generating a new RPA shall be set in user_gapm_conf.renew_dur. This field controls the duration of RPA before it gets regenerated and it is counted in units of 10 ms. The minimum valid value for renew_dur is 15000 (150 s). If the value of renew_dur is set to less than 15000 then BLE stack will automatically set it to 15000. ○ APP_CFG_CNTL_PRIV_RPA_RAND: . The peripheral device is a private one and operates with a RPA generated in its BLE controller layer. When the device is bonded with a peer, then the device information of the peer will be stored in the resolving list located in the BLE controller layer. Upon re-connection, the RPA of the bonded peer will be automatically resolved in the BLE controller layer and its identity will be directly used in the application layer of the peripheral device. The peripheral will operate with RPA independently to the existence of bonded peers. . Identity information: The device shall exchange its identity information during pairing procedure.

User Manual Revision 5.0 14-May-2018

CFR0012 78 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

 A valid IRK shall be set in user_gapm_conf.irk and GAP_KDIST_IDKEY shall be enabled in USER_CFG_FEAT_RESP_KDIST.  The device will always send as identity address its Public Address defined in CFG_NVDS_TAG_BD_ADDRESS.  Renew duration: The interval of generating a new RPA shall be set in user_gapm_conf.renew_dur. This field controls the duration of RPA before it gets regenerated and it is counted in units of 10 ms. The minimum valid value for renew_dur is 15000 (150 s). If the value of renew_dur is set to less than 15000 then BLE stack will automatically set it to 15000. ● The controller privacy mode can be set by defining the USER_CFG_CNTL_PRIV_MODE flag to one of the following values: ○ APP_CFG_CNTL_PRIV_MODE_NETWORK: Peripheral device will only accept advertising packets from bonded peer devices that operate with RPA. ○ APP_CFG_CNTL_PRIV_MODE_DEVICE: Peripheral device will accept advertising packets from bonded peer devices that operate with both RPA and non-private addresses (Public, Random Static). ● user_modules_config.h, defines which application modules are included or excluded from the user’s application. For example: ○ #define EXCLUDE_DLG_DISS (0), the Device information application profile is included. The SDK takes care of the Device information application profile message handling. ○ #define EXCLUDE_DLG_DISS (1), the Device information application profile is excluded. The user application has to take care of the Device information application profile message handling. ○ #define EXCLUDE_DLG_SEC (0), the Security application module is handled in this Pillar application. ● user_periph_setup.h, holds hardware related settings relative to the used Development Kit. In this application it also defines the I2C pin configuration for the EEPROM module. ● user_profiles_config.h, defines which BLE profiles (Bluetooth SIG adopted or custom ones) will be included in user’s application, as well as their configuration (features, security level, etc.). Particularly, the C header files (each header file denotes the respective BLE profile) that are included in the user_profiles_config.h file are: ○ CFG_PRF_DISS, includes the Device Information service. ○ CFG_PRF_CUST1, includes the Custom 1 service. ● The security requirement for a specific profile can be defined here. For example: ○ #define APP_CUSTS1_SEC_REQ SRV_PERM_UNAUTH: In order to access specific attributes of the CUSTS1 services, a minimum security of mode 1 level 2 has to be reached. \user_custom_profile ● user_custs_config.c, defines the cust_prf_funcs[] array, which contains the Custom profiles API functions calls. ● user_custs1_def.c, defines the structure of the Custom 1 profile database structure. \user_platform ● user_periph_setup.c, source code file that handles peripheral (GPIO, UART, etc.) configuration and initialization relative to the Development Kit. \user_app ● user_security.c, source code file that implements the application specific code such as creating the advertising packet, managing the timers to control the advertising period and handling connection events. It also initializes the security and adds the key exchange handler.

User Manual Revision 5.0 14-May-2018

CFR0012 79 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Note 16 The SDK by default as well as this application, during initialization, reads and uses the XTAL16M oscillator trimming value as stored in the OTP header. However, if there has been no trimming yet, the XTAL16M oscillator trimming value in the OTP Header will be zero, and this zero value will then be used by default from the SDK. To alter the default behavior, the SDK provides a configuration flag that allows the user to still read and use the XTAL16M oscillator trimming value from the OTP header, so that if the stored OTP value is zero, it reverts in using an indicative hardcoded value as the XTAL16M oscillator trimming value. You can read more about the XTAL16M oscillator trim on the OTP Header section in the device datasheet, or at Table 37, of Appendix G Booting from serial interfaces, in the UM-B-079 DA14585/586 SDK 6 Software Platform Reference document. Note 17 The OTP header value for the XTAL16M oscillator trimming in the DA14585 and DA14586 devices on the Pro and Basic Development Kits, is not written (ie it is read as zero), to allow for the user/developer to provide and write a preferred XTAL16M oscillator trimming value. Therefore, if you have not calculated and written already a non-zero value, in the XTAL16M oscillator trimming value for the Development Kit that you have in use, it is advised to enable and use in this application and in the SDK the CFG_USE_DEFAULT_XTAL16M_TRIM_VALUE_IF_NOT_CALIBRATED configuration flag, that resides within the da1458x_config_advanced.h file as follows; #define CFG_USE_DEFAULT_XTAL16M_TRIM_VALUE_IF_NOT_CALIBRATED

7.5.5.2 Events Processing and Callbacks Several events can occur during the lifetime of the Bluetooth low energy application and these events need to be handled in a specific manner. The application is responsible for selecting which events and operations it should handle and which it should just leave to be handled with the default SDK behavior. The SDK uses a mechanism which registers callbacks for every event or operation that defines the system behavior. The C header file user_callback_config.h, which is part of the user application contains the registration of callback functions. The Pillar 4 application registers the following callback functions: ● General BLE events: static const struct app_callbacks user_app_callbacks = { .app_on_connection = user_app_connection, .app_on_disconnect = user_app_disconnect, .app_on_update_params_rejected = NULL, .app_on_update_params_complete = NULL, .app_on_set_dev_config_complete = default_app_on_set_dev_config_complete, .app_on_adv_nonconn_complete = NULL, .app_on_adv_undirect_complete = user_app_adv_undirect_complete, .app_on_adv_direct_complete = NULL, .app_on_db_init_complete = default_app_on_db_init_complete, .app_on_scanning_completed = NULL, .app_on_adv_report_ind = NULL, .app_on_get_dev_name = default_app_on_get_dev_name, .app_on_get_dev_appearance = default_app_on_get_dev_appearance, .app_on_get_dev_slv_pref_params = default_app_on_get_dev_slv_pref_params, .app_on_set_dev_info = default_app_on_set_dev_info, .app_on_data_length_change = NULL, .app_on_update_params_request = default_app_update_params_request, .app_on_generate_static_random_addr = default_app_generate_unique_static_random_addr, .app_on_svc_changed_cfg_ind = NULL, #if (BLE_APP_SEC) .app_on_pairing_request = default_app_on_pairing_request, .app_on_tk_exch = user_app_on_tk_exch, .app_on_irk_exch = NULL, .app_on_csrk_exch = default_app_on_csrk_exch, .app_on_ltk_exch = default_app_on_ltk_exch, .app_on_pairing_succeeded = default_app_on_pairing_succeeded, .app_on_encrypt_ind = NULL, .app_on_encrypt_req_ind = default_app_on_encrypt_req_ind,

User Manual Revision 5.0 14-May-2018

CFR0012 80 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

.app_on_security_req_ind = NULL, .app_on_addr_solved_ind = default_app_on_addr_solved_ind, .app_on_addr_resolve_failed = default_app_on_addr_resolve_failed, .app_on_ral_cmp_evt = default_app_on_ral_cmp_evt, .app_on_ral_size_ind = NULL, .app_on_ral_addr_ind = NULL, #endif // (BLE_APP_SEC) }; The above structure defines that a certain event will be processed by a default handler or by a user defined handler or it will not be processed at all (NULL entries). The user defined handlers (e.g user_app_connection(), user_app_disconnect(), user_app_adv_undirect_complete(), and user_app_on_tk_exch()) are defined in C source file user_security.c. Note that most of them will be called from the newly enabled security application module (the preprocessor value CFG_APP_SECURITY must be defined in da1458x_config_basic.h to set the BLE_APP_SEC). Note 18 The default configuration of the project uses UART to display the Temporary Keys in case of Passkey Entry and Numeric Comparison pairing methods. ○ However, if CFG_PRINTF is undefined or default_app_on_tk_exch is used, then the Passkey will have a default value of “123456”. ○ In each case of Numeric Comparison, the confirmation value will be automatically accepted, since a keyboard or Yes/No buttons are not implemented in the specific example. ○ In case of Secure Connections, the LTK will be also printed in UART, so that it can be used with debugging/sniffing tools. ● When peer device uses a resolvable private address that needs to be resolved by the peripheral, then app_easy_security_resolve_bdaddr() can be called. app_easy_security_resolve_bdaddr() sends the stored IRKs in the BLE stack, which tries to find the IRK that resolves the peer’s BD address. If resolution is successful, then the host application will receive an .app_on_addr_solved_ind event. If the operation fails an .app_on_addr_resolve_failed event will be received. ● Bond database specific events: static const struct app_bond_db_callbacks user_app_bond_db_callbacks = { .app_bdb_init = default_app_bdb_init, .app_bdb_get_size = default_app_bdb_get_size, .app_bdb_add_entry = default_app_bdb_add_entry, .app_bdb_remove_entry = NULL, .app_bdb_search_entry = default_app_bdb_search_entry, .app_bdb_get_stored_irks = default_app_bdb_get_stored_irks, }; The above structure defines that a certain event will be processed by a default handler or by a user defined handler or it will not be processed at all (NULL entries). By default a bond database is implemented in app_bond_db.c. However, a user implementation of the bond database can be hooked to the above callback table. The default implementation of the bond database: ○ Has a default number of five bond data slots. ○ In each valid slot, depending on the bonding procedure, bond database stores the keys (LTKs – including EDIV and RandNB, remote IRK – including peer’s identity, CSRKs), the peer’s BD address and a set of flags. ○ When adding bond data for a peer device the storing algorithm checks if an older entry exists for that peer in the bond DB. If yes, it updates the old entry, otherwise uses an empty slot. If there is not an empty slot in the database, then the least recently added slot will be replaced. ○ Bond data of known peer device can be searched and/or removed using different types (by slot, by EDIV, by BD address, by IRK, etc.) ○ app_bdb_get_stored_irks can be used to get all the stored IRKs in the database. This is useful when the peer has a random private resolvable address, which needs to be resolved.

User Manual Revision 5.0 14-May-2018

CFR0012 81 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

● System specific events: static const struct arch_main_loop_callbacks user_app_main_loop_callbacks = { .app_on_init = user_app_init, .app_on_ble_powered = NULL, .app_on_sytem_powered = NULL, .app_before_sleep = NULL, .app_validate_sleep = NULL, .app_going_to_sleep = NULL, .app_resume_from_sleep = NULL, }; The above structure defines that a certain event will be processed by a default handler or by a user defined handler or it will not be processed at all (NULL entries). The user defined handlers (e.g. user_app_init()) is defined in C source file user_security.c. ● BLE operations: static const struct default_app_operations user_default_app_operations = { .default_operation_adv = user_app_adv_start, }; The above structure defines that a certain operation will be processed by a default handler or by a user defined handler or it will not be processed at all (NULL entries). The user defined handlers (e.g. user_app_adv_start()) is defined in C source file user_security.c. ● Custom profile message handling: static const catch_rest_event_func_t app_process_catch_rest_cb = (catch_rest_event_func_t)user_catch_rest_hndl; Callback function that contains the Custom profile messages handling in user application space. For Pillar 4 application this function is totally unused, since Pillar 4 application does not include any behavior related to the Custom service. Service is protected from the unauthorized access automatically at database level and requires no additional action from the user application space.

7.5.5.3 BLE Application Abstract Code Flow Figure 46 shows the abstract code flow diagram of the Pillar 4 application. The diagram depicts the SDK interaction with the callback functions registered in user_callback_config.h and the functions implemented in user_security.c. It shows only the part that is new, compared to the previous Pillar application. The connection establishment procedure is identical to the previous application and the following function flow diagram shows the subsequent pairing procedure.

User Manual Revision 5.0 14-May-2018

CFR0012 82 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

User User SDK

Application Configuration )

app_on_connection() user_app_connection()

default_app_on_connection()

from peerdevicefrom

(

Request Request to connect )

app_on_pairing_request() pair default_app_on_pairing_request()

app_on_tk_exch() Request Request to

user_app_on_tk_exch() devicepeerfrom

(

app_easy_security_tk_exch() app_on_ltk_exch() default_app_on_ltk_exch()

app_on_csrk_exch() default_app_on_csrk_exch()

app_on_pairing_succeeded() default_app_on_pairing_succeeded()

Figure 46: Pillar 4 Application - User Application Code Flow for Pairing procedure

1. app_on_pairing_request() will be called when a peer device initiates a pairing procedure. default_app_on_pairing_request()will be called so that local device will respond with its supported security features. 2. app_on_tk_exch()will be called if a temporary key needs to be used for the pairing procedure (OOB, PassKey Entry, Numeric Comparison). In the example project, user_app_on_tk_exch(), depending on the pairing method, has the following functionality: a. OOB: local device will assign to OOB data the value defined in APP_SECURITY_OOB_TK_VAL b. Passkey Entry: If a UART display is used (CFG_PRINTF is defined), local device will generate a random 6-digit passkey and display it in UART. If a UART display is not used, then it will use the default passkey, defined in APP_SECURITY_MITM_PASSKEY_VAL (123456). c. Numeric Comparison: If a UART display is used (CFG_PRINTF is defined), local device will display the calculated confirmation value in UART. A keyboard or Yes/No

User Manual Revision 5.0 14-May-2018

CFR0012 83 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

buttons are not implemented in the current project. The device will auto-accept the confirmation value in all cases. 3. app_on_ltk_exch() will be called, only in case of Legacy Pairing, when bonding is enabled and both devices support the distribution of the encryption key by the responder. It will call default_app_on_ltk_exch() to generate the LTK which will be used for future encryption of the link. In case of Secure Connection pairing, LTK is calculated and distributed during the pairing procedure in the lower layers. 4. app_on_csrk_exch() will be called, only when bonding is enabled and both devices support the distribution of the sign key by the responder. It will call default_app_on_csrk_exch() to generate the CSRK which will be used for data signing in future connections. 5. app_on_pairing_succeeded() will be called after the successful completion of the pairing procedure and distribution of keys. default_app_on_pairing_succeeded()is responsible to store the exchanged bonding information to the bonding database (cache and/or external non-volatile memory). Note 19 Local IRK is statically defined in user_gapm_conf struct in user_config.h file and will be exchanged if bonding is enabled and both devices support the distribution of the IRK by the responder. Figure 47 abstract code flow diagram of the Pillar 4 application in case of reconnecting with an already bonded device. 1. app_on_encrypt_req_ind() will be called when a peer device initiates an encryption procedure. default_app_on_encrypt_req_ind()is responsible for restoring the encryption key from the bond database: a. In case of Legacy Pairing, bond information of connected peer device can be addressed in bond database by using the EDIV number, which is provided as a parameter in app_on_encrypt_req_ind(). b. In case of Secure Connection Pairing, the bond information of connected peer device can be addressed in bond database by using its BD or Identity address. i. If peer device has a public or static random address, then the BD address will be used ii. If peer device uses a random private resolvable address, then an address resolution procedure will begin to extract the Identity Address. The IRK that will successfully resolve the BD address will be used to address the bond information of the connected peer in bond database and hence, restore the LTK with which the link will be encrypted. iii. If peer device uses a random private non-resolvable address, then local device will automatically reject encryption and disconnect. 2. app_on_addr_solved_ind() will be called when address resolution procedure completes successfully. The IRK that resolved the random private resolvable address is included as a parameter. 3. app_on_addr_resolve_failed()will be called when address resolution procedure fails. Local device will automatically reject encryption and disconnect.

User Manual Revision 5.0 14-May-2018

CFR0012 84 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

User User SDK

Application Configuration )

app_on_connection() user_app_connection()

default_app_on_connection()

from peerdevicefrom

(

Request Request to connect ) app_on_encrypt_req_ind() default_app_on_encrypt_req_ind()

app_on_addr_solved_ind()

from peer devicepeerfrom

( Request Request to encrypt app_on_addr_resolve_failed()

Figure 47: Pillar 4 Application - User Application Code Flow for Encryption

User Manual Revision 5.0 14-May-2018

CFR0012 85 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.5.6 Building the Project for Different Targets and Development Kits The Pillar 4 application can be built for two different target processors: DA14585 and DA14586. The selection is done via the Keil tool as depicted in Figure 48.

Figure 48: Building the Project for Different Targets

The user also has to select the correct Development Kit in order to build and run the application. This selection is done via the Configuration Wizard of the user_periph_setup.h file as shown in Figure 49.

Figure 49: Development Kit Selection for Pillar 4 Application

After the proper selection of the target processor and development kit, the application is ready to be built. Note 20 As the default setting is to use SPI Flash to store the bonding information the jumpers must be enabled for SPI Flash accesses as shown in Table 3.

User Manual Revision 5.0 14-May-2018

CFR0012 86 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.5.7 Interacting with BLE Application

7.5.7.1 LightBlue iOS The LightBlue iOS application can be used to connect an iPad/iPod/iPhone device to the application. In such a case the iPad/iPod/iPhone acts as a BLE Central and the application as a BLE Peripheral. Figure 50 shows the result when the iPad/iPod/iPhone device manages to connect to the DA14585/586 (the application’s advertising device name is DLG-SECURITY). Depending on the currently selected security setup you can be asked to allow devices to pair or to enter passkey or to confirm the calculated pin.

Figure 50: LightBlue Application Connected to Pillar 4 Application

User Manual Revision 5.0 14-May-2018

CFR0012 87 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Figure 51: LightBlue Application Pairing with Pillar 4 Application using Numeric Comparison

7.5.7.2 BLE Scanner Android The BLE Scanner application in Android does not request bonding and so none of the Pillar 4 security features are actually used.

7.6 Pillar 5 (Sleep Mode)

7.6.1 Application Description The Pillar 5 (sleep mode) BLE example application primarily adds sleep to the Pillar 2 application. The main purpose of this application example is to show how to use the sleep mode API and change in runtime the sleep mode. The two sleep modes that are used are: ● Extended sleep without OTP copy. ● Extended sleep with OTP copy. In Extended sleep without OTP copy, the application code and retention data is retained in RAM. After wake-up from sleep, no OTP mirror, no boot from SPI, I2C or UART interface shall happen. RAM block 4 is always retained (BLE state). This mode resembles to the extended sleep mode of the DA14580 chip.

User Manual Revision 5.0 14-May-2018

CFR0012 88 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

In Extended sleep with OTP copy, the application code is stored in OTP memory. After wake-up from sleep, the OTP mirror will take place. The RAM blocks which include code will not be retained. The RAM blocks which include retention data will be retained. RAM block 4 is always retained (BLE state). This mode resembles to the deep sleep mode of the DA14580 chip. As in the SDK of the DA14580 chip, the user can preselect to use either the Extended sleep mode without OTP copy or the Extended sleep mode with OTP copy, by providing the respective sleep configuration in the user_config.h file.

/****************************************** * Default sleep mode. Possible values are: * * - ARCH_SLEEP_OFF * - ARCH_EXT_SLEEP_ON * - ARCH_EXT_SLEEP_OTP_COPY_ON * ****************************************** */

One of the above sleep modes will be used when the system logic decides that the DA14585 chip is ready to sleep. For more information about Sleep modes refer to section 7.1.1 of [5].

7.6.2 Basic Operation Supported services: ● Inherits the services from Pillar 2 application. Features: ● Inherits the features from Pillar 2 application, plus: ● Will advertise for a certain time with sleep enabled. After advertising has finished the only method of exiting sleep is a button press. On connection it also enters extended sleep. ● In Custom service 1 CONTROL POINT, ADC VAL 2 and BUTTON STATE characteristic values introduce some behavior with a connected peer device. The Pillar 5 application behavior is included in C source file user_sleepmode.c. Table 17 shows the Custom service characteristic values along with their properties.

Table 17. Pillar 5 Custom Service Characteristic Values and Properties Name Properties Length (B) Description/Purpose CONTROL POINT WRITE 1 Accept commands from peer LED STATE WRITE NO RESPONSE 1 Toggles a LED connected to a GPIO ADC VAL 1 READ, NOTIFY 2 Reads sample from an ADC channel ADC VAL 2 READ 2 Reads sample from an ADC channel BUTTON STATE READ, NOTIFY 1 Reads the current state of a push button connected a GPIO INDICATEABLE CHAR READ, INDICATE 20 Demonstrate indications LONG VAL CHAR READ, WRITE. NOTIFY 50 Demonstrate writes to long characteristic value

User Manual Revision 5.0 14-May-2018

CFR0012 89 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

The Pillar 5 application provides behavior only for the highlighted characteristic values of the Custom 1 service. The implementation code of the Custom 1 service is included in C source file user_sleepmode_task.c.

User Manual Revision 5.0 14-May-2018

CFR0012 90 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.6.3 User Interface When the device is powered up or disconnected: ● Device advertises for a defined amount of time APP_ADV_DATA_UPDATE_TO with a default value of 30 s. While the device is in the advertising state its sleep mode is set to Extended sleep with OTP copy (the OTP copy is emulated when the system runs in DEVELOPMENT_DEBUG mode). ● After the expiration of the above timeout, and if the device does not enter the connected state, it stops advertising. Now the device does nothing and waits for an external event to exit the sleeping state. ● The user can wake up the device by pressing a button. After the button press the device will start to advertise again for the predefined time. ● When the device enters the connected state then the sleep mode is turned to Extended sleep without OTP copy. A peer connected to the Pillar 5 application can do the following: ● Use Custom Service. ● Write to Control Point of Custom Service. ○ Byte 0x00 disables PWM timer (turns LED off and restores sleep mode). This is LED D3 on ProDK and D7 on BasicDK. ○ Byte 0x01 enables PWM timer (turns LED on and puts device into active mode) – user can attach speaker to selected pin (P1_0) to hear PWM frequency change. ○ Byte 0x02 disables ADC VAL 2 update. ○ Byte 0x03 enables ADC VAL 2 update. ADC VAL 2 characteristic is updated with battery voltage at every connection event. ● Read/notify BUTTON STATE value. When the button is pressed or released characteristic value is updated accordingly. ● Read battery voltage on ADC VAL 2. When functionality is enabled in Control Point user can read value from ADC input.

User Manual Revision 5.0 14-May-2018

CFR0012 91 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.6.4 Loading the Project The Pillar 5 application is developed under the Keil v5 tool. The Keil project file is: \projects\target_apps\ble_examples\ble_app_sleepmode\Keil_5\ble_ap p_sleepmode.uvprojx Figure 52 shows the Keil project layout with emphasis on the user related files, included in the Keil project folders user_config, user_platform, user_custom_profile and user_app. These folders contain the user configuration files of the Pillar 5 application.

Figure 52: Pillar 5 Keil Project Layout

User Manual Revision 5.0 14-May-2018

CFR0012 92 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.6.5 Going Through the Code

7.6.5.1 Initialization The previously mentioned Keil project folders (user_config, user_platform, user_custom_profile and user_app) contain the files that initialize and configure the Pillar 5 application. \user_config ● da1458x_config_advanced.h, holds DA14585/586 advanced configuration settings. ● da1458x_config_basic.h, holds DA14585/586 basic configuration settings. ● user_callback_config.h, callback functions that handle various events or operations. ● user_config.h, holds advertising parameters, connection parameters, etc. ● user_modules_config.h, defines which application modules are included or excluded from the user’s application. For example: ○ #define EXCLUDE_DLG_DISS (0), the Device information application profile is included. The SDK takes care of the Device information application profile message handling. ○ #define EXCLUDE_DLG_DISS (1), the Device information application profile is excluded. The user application has to take care of the Device information application profile message handling. ● user_periph_setup.h, holds hardware related settings relative to the used Development Kit. ● user_profiles_config.h, defines which BLE profiles (Bluetooth SIG adopted or custom ones) will be included in user’s application. Particularly, the C header files (each header file denotes the respective BLE profile) that are included in the user_profile_config.h file are: ○ CFG_PRF_DISS, includes the Device Information service. ○ CFG_PRF_CUST1, includes the Custom 1 service. \user_custom_profile ● user_custs1_def.c, defines the structure of the Custom 1 profile database structure. ● user_custs_config.c, defines the cust_prf_funcs[] array, which contains the Custom profiles API functions calls. \user_platform ● user_periph_setup.c, source code file that handles peripheral (GPIO, UART, etc.) configuration and initialization relative to the Development Kit. \user_app ● user_sleepmode.c, source code file that implements the application specific code such as creating the advertising packet, managing the timers to control the advertising period and handling connection events.  user_sleepmode_task.c, source code file that handles the entry to sleep, configures exit from sleep on a button press and handles Control Point characteristic accesses.

Note 21 The SDK by default as well as this application, during initialization, reads and uses the XTAL16M oscillator trimming value as stored in the OTP header. However, if there has been no trimming yet, the XTAL16M oscillator trimming value in the OTP Header will be zero, and this zero value will then be used by default from the SDK. To alter the default behavior, the SDK provides a configuration flag that allows the user to still read and use the XTAL16M oscillator trimming value from the OTP header, so that if the stored OTP value is zero, it reverts in using an indicative hardcoded value as the XTAL16M oscillator trimming value. You can read more about the XTAL16M oscillator trim on the OTP Header section in the device datasheet, or at Table 37, of Appendix G Booting from serial interfaces, in the UM-B-079 DA14585/586 SDK 6 Software Platform Reference document [5]. Note 22 The OTP header value for the XTAL16M oscillator trimming in the DA14585 and DA14586 devices on the Pro and Basic Development Kits, is not written (ie it is read as zero), to allow for the user/developer to provide and write a preferred XTAL16M oscillator trimming value. Therefore, if you

User Manual Revision 5.0 14-May-2018

CFR0012 93 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

have not calculated and written already a non-zero value, in the XTAL16M oscillator trimming value for the Development Kit that you have in use, it is advised to enable and use in this application and in the SDK the CFG_USE_DEFAULT_XTAL16M_TRIM_VALUE_IF_NOT_CALIBRATED configuration flag, that resides within the da1458x_config_advanced.h file as follows; #define CFG_USE_DEFAULT_XTAL16M_TRIM_VALUE_IF_NOT_CALIBRATED

7.6.5.2 Events Processing and Callbacks Several events can occur during the lifetime of the Bluetooth low energy application and these events need to be handled in a specific manner. The application is responsible for selecting which events and operations it should handle and which it should just leave to be handled with the default SDK behavior. The SDK uses a mechanism which registers callbacks for every event or operation that defines the system behavior. The C header file user_callback_config.h, which is part of the user application contains the registration of callback functions. For example, in the Pillar 5 application the user_app_callbacks[] array has the following entries: static const struct app_callbacks user_app_callbacks = { .app_on_connection = user_app_connection, .app_on_disconnect = user_app_disconnect, .app_on_update_params_rejected = NULL, .app_on_update_params_complete = NULL, .app_on_set_dev_config_complete = default_app_on_set_dev_config_complete, .app_on_adv_nonconn_complete = NULL, .app_on_adv_undirect_complete = user_app_adv_undirect_complete, .app_on_adv_direct_complete = NULL, .app_on_db_init_complete = default_app_on_db_init_complete, .app_on_scanning_completed = NULL, .app_on_adv_report_ind = NULL, .app_on_get_dev_name = default_app_on_get_dev_name, .app_on_get_dev_appearance = default_app_on_get_dev_appearance, .app_on_get_dev_slv_pref_params = default_app_on_get_dev_slv_pref_params, .app_on_set_dev_info = default_app_on_set_dev_info, .app_on_data_length_change = NULL, .app_on_update_params_request = default_app_update_params_request, .app_on_generate_static_random_addr = default_app_generate_static_random_addr, .app_on_svc_changed_cfg_ind = NULL, #if (BLE_APP_SEC) .app_on_pairing_request = NULL, .app_on_tk_exch = NULL, .app_on_irk_exch = NULL, .app_on_csrk_exch = NULL, .app_on_ltk_exch = NULL, .app_on_pairing_succeeded = NULL, .app_on_encrypt_ind = NULL, .app_on_encrypt_req_ind = NULL, .app_on_security_req_ind = NULL, .app_on_addr_solved_ind = NULL, .app_on_addr_resolve_failed = NULL, .app_on_ral_cmp_evt = NULL, .app_on_ral_size_ind = NULL, .app_on_ral_addr_ind = NULL, #endif // (BLE_APP_SEC) };

The above array defines that a certain event will be processed by a default handler or by a user defined handler or it will not be processed at all (NULL entries). The user defined handlers (e.g user_app_connection(), user_app_disconnect() and user_app_adv_undirect_complete()) are defined in C source file user_sleepmode.c.

User Manual Revision 5.0 14-May-2018

CFR0012 94 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Similar to Pillar 3 project Pillar 5 also defines user_catch_rest_hndl() handler that catches all the Custom service messages and handles them in the user application. The implementation of this handler is in C source file user_sleepmode_task.c. An important addition to Pillar 5 application is the app_button_enable()function, which is called from the user_app_adv_undirect_complete() event handler. After the advertising is completed it configures one of the user buttons as a wake up trigger, just before the application goes to sleep. The registered wakeup callback function app_button_press_cb() is set to restore the BLE core stack and peripherals back to fully functional state. The user_callback_config.h configuration header file contains the registration of the callback function user_catch_rest_hndl(), as is described below. static const catch_rest_event_func_t app_process_catch_rest_cb = (catch_rest_event_func_t)user_catch_rest_hndl; The user_callback_config.h configuration header file contains the registration of the callback function user_app_on_wakeup(), as is described below. static const struct app_bond_db_callbacks user_app_bond_db_callbacks = { .app_bdb_init = NULL, .app_bdb_get_size = NULL, .app_bdb_add_entry = NULL, .app_bdb_remove_entry = NULL, .app_bdb_search_entry = NULL, .app_bdb_get_number_of_stored_irks = NULL, .app_bdb_get_stored_irks = NULL, .app_bdb_get_device_info_from_slot = NULL, };

User Manual Revision 5.0 14-May-2018

CFR0012 95 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.6.5.3 BLE Application Abstract Code Flow Figure 53 shows the abstract code flow diagram of the Pillar 5 application. The diagram depicts the SDK interaction with the callback functions registered in user_callback_config.h and the functions implemented in user_sleepmode.c. It shows only the part that is new, compared to the Pillar 2 application. The connection establishment procedure is the same as in previous application and the following function flow diagram shows the platform entering sleep mode and the wakeup calls triggered by the button press. Advertising is restarted after wakeup.

User User SDK Application Configuration

app_easy_gap_undirected_advertise_start()

app_on_adv_undirect_complete() user_app_adv_undirect_complete()

app_easy_wakeup_set(app_wakeup_cb)

wkupct_register_callback(app_button_press_cb)

sleep modesleep

Platform goes goes to Platform )

app_button_press_cb() button press button

app_easy_wakeup() (

Wakeup Wakeup event

app_wakeup_cb()

app_easy_gap_undirected_advertise_start()

Figure 53: Pillar 5 Application - User Application Code Flow

User Manual Revision 5.0 14-May-2018

CFR0012 96 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.6.6 Building the Project for Different Targets and Development Kits The Pillar 5 application can be built for two different target processors: DA14585 and DA14586. The selection is done via the Keil tool as depicted in Figure 54.

Figure 54: Building the Project for Different Targets

The user has also to select the correct Development Kit in order to build and run the application. This selection is done via the Configuration Wizard of the user_periph_setup.h file as shown in Figure 55.

Figure 55: Development Kit Selection for Pillar 5 Application

After the proper selection of the target processor and development kit, the application is ready to be built.

User Manual Revision 5.0 14-May-2018

CFR0012 97 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.6.7 Interacting with BLE Application

7.6.7.1 LightBlue iOS The LightBlue iOS application can be used to connect an iPad/iPod/iPhone device to the application. In such a case the iPad/iPod/iPhone acts as a BLE Central and the application as a BLE Peripheral. Figure 56 shows the result when the iPad/iPod/iPhone device manages to connect to the DA14585/586 (the application’s advertising device name is DIALOG-SLEEP).

Figure 56: LightBlue Application Connected to Pillar 5 Application

User Manual Revision 5.0 14-May-2018

CFR0012 98 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.7 Pillar 6 (OTA) The Pillar 6 (OTA) BLE example application demonstrates the same as the Pillar 2 application, plus the SUOTAR service (16-bit UUID). The SUOTAR service requires no action on user space side and can be used by peer device for Software Updates Over The Air (SUOTA). The project uses the “Integrated processor” configuration. This project does not create an update firmware image that can be uploaded using SUOTA.

7.7.1 Basic Operation Supported services: ● Inherits the services from Pillar 2 application. ● SUOTAR service defined by the user with 16-bit UUID. Features: ● Inherits the features from Pillar 2 application, plus: ● SUOTA firmware updates to external SPI/I2C memories The Pillar 6 behavior is included in C source file user_ota.c. Table 18 shows the Custom 1 service characteristic values along with their properties.

Table 18: Pillar 6 Custom Service Characteristic Values and Properties Name Properties Length (B) Description/Purpose CONTROL POINT WRITE 1 Accept commands from peer LED STATE WRITE NO RESPONSE 1 Toggles a LED connected to a GPIO ADC VAL 1 READ, NOTIFY 2 Reads sample from an ADC channel ADC VAL 2 READ 2 Reads sample from an ADC channel BUTTON STATE READ, NOTIFY 1 Reads the current state of a push button connected a GPIO INDICATEABLE CHAR READ, INDICATE 20 Demonstrate indications LONG VAL CHAR READ, WRITE. NOTIFY 50 Demonstrate writes to long characteristic value

The Pillar 6 application does not provide any behavior for the Custom service.

User Manual Revision 5.0 14-May-2018

CFR0012 99 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Table 19: Pillar 6 SUOTAR Service Characteristic Values and Properties Name Properties Length (B) Description/Purpose SUOTA MEMORY DEVICE READ, WRITE 4 Defines what is the target physical memory and base address of the patch. GPIO MAP READ, WRITE 4 Port and pin map for the physical memory device as well as device address in case of I2C EEPROMs. MEMORY INFORMATION READ 4 Number of bytes transferred. SUOTA PATCH LENGTH READ, WRITE 2 Block length of SUOTA image to be sent at a time. SUOTA DATA READ, WRITE, WRITE 20 20 bytes of SUOTA data, word aligned. NO RESPONSE MS byte first. SUOTA SERVICE STATUS READ, NOTIFY 1 SUOTA Service Status.

7.7.2 User Interface A peer connected to the Pillar 6 application is able to do the same as in the Pillar 2 application, plus: ● Update firmware image over a Bluetooth Low Energy link.

User Manual Revision 5.0 14-May-2018

CFR0012 100 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.7.3 Loading the Project The Pillar 6 application is developed under the Keil v5 tool. The Keil project file is: \projects\target_apps\ble_examples\ble_app_ota\Keil_5\ble_app_ota. uvprojx Figure 57 shows the Keil project layout with emphasis on the user related files, included in the Keil project folders user_config, user_platform, user_custom_profile and user_app. These folders contain the user configuration files of the Pillar 6 application.

Figure 57: Pillar 6 Keil Project Layout

There is no new file added compared to the Pillar 2 project as the configuration will pull in the SDKs SUOTA service to provide the low-level handling of the reception and writing to SPI of the new image.

User Manual Revision 5.0 14-May-2018

CFR0012 101 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.7.4 Going Through the Code

7.7.4.1 Initialization The previously mentioned project folders (user_config, user_platform, user_custom_profile and user_app) contain the files that initialize and configure the Pillar 6 application. \user_config ● da1458x_config_advanced.h, holds DA14585/586 advanced configuration settings. ● da1458x_config_basic.h, holds DA14585/586 basic configuration settings. ● user_callback_config.h, callback functions that handle various events or operations. ● user_config.h, holds advertising parameters, connection parameters, etc. ● user_modules_config.h, defines which application modules are included or excluded from the user’s application. For example: ○ #define EXCLUDE_DLG_DISS (0), the Device information application profile is included. The SDK takes care of the Device information application profile message handling. ○ #define EXCLUDE_DLG_DISS (1), the Device information application profile is excluded. The user application must take care of the Device information application profile message handling. ● user_periph_setup.h, holds hardware related settings relative to the used Development Kit. ● user_profiles_config.h, defines which BLE profiles (Bluetooth SIG adopted or custom ones) will be included in user’s application. Particularly, the C header files (each header file denotes the respective BLE profile) that are included in the user_profile_config.h file are: ○ CFG_PRF_DISS, includes the Device Information service. ○ CFG_PRF_SUOTAR, includes the SUOTAR service. ○ CFG_PRF_CUST1, includes the Custom 1 service. It also exposes some configuration flags for the SUOTAR service: ○ #define CFG_SUOTAR_I2C_DISABLE , Disable I2C external memory module ○ #define CFG_SUOTAR_SPI_DISABLE , Disable SPI external memory module \user_custom_profile ● user_custs1_def.c, defines the structure of the Custom 1 profile database structure. ● user_custs_config.c, defines the cust_prf_funcs[] array, which contains the Custom profiles API functions calls. \user_platform ● user_periph_setup.c, source code file that handles peripheral (GPIO, UART, etc.) configuration and initialization relative to the Development Kit. \user_app ● user_ota.c, source code file that implements the application specific code such as creating the advertising packet, managing the timers to control the advertising period and handling connection events. It also provides the handler for SUOTA state changes and checks if on a disconnection a SUOTA triggered reboot is required.

Note 23 The SDK by default as well as this application, during initialization, reads and uses the XTAL16M oscillator trimming value as stored in the OTP header. However, if there has been no trimming yet, the XTAL16M oscillator trimming value in the OTP Header will be zero, and this zero value will then be used by default from the SDK. To alter the default behavior, the SDK provides a configuration flag that allows the user to still read and use the XTAL16M oscillator trimming value from the OTP header, so that if the stored OTP value is zero, it reverts in using an indicative hardcoded value as the XTAL16M oscillator trimming value. You can read more about the XTAL16M oscillator trim on the OTP Header

User Manual Revision 5.0 14-May-2018

CFR0012 102 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

section in the device datasheet, or at Table 37, of Appendix G Booting from serial interfaces, in the UM-B-079 DA14585/586 SDK 6 Software Platform Reference document. Note 24 The OTP header value for the XTAL16M oscillator trimming in the DA14585 and DA14586 devices on the Pro and Basic Development Kits, is not written (ie it is read as zero), to allow for the user/developer to provide and write a preferred XTAL16M oscillator trimming value. Therefore, if you have not calculated and written already a non-zero value, in the XTAL16M oscillator trimming value for the Development Kit that you have in use, it is advised to enable and use in this application and in the SDK the CFG_USE_DEFAULT_XTAL16M_TRIM_VALUE_IF_NOT_CALIBRATED configuration flag, that resides within the da1458x_config_advanced.h file as follows; #define CFG_USE_DEFAULT_XTAL16M_TRIM_VALUE_IF_NOT_CALIBRATED

7.7.4.2 Events Processing and Callbacks Several events can occur during the lifetime of the Bluetooth low energy application and these events need to be handled in a specific manner. The application is responsible for selecting which events and operations it should handle and which it should just leave to be handled with the default SDK behavior. The SDK uses a mechanism which registers callbacks for every event or operation that defines the system behavior. The C header file user_callback_config.h, which is part of the user application contains the registration of callback functions. The Pillar 6 application registers the following callback functions: ● General BLE events: static const struct app_callbacks user_app_callbacks = { .app_on_connection = user_app_connection, .app_on_disconnect = user_app_disconnect, .app_on_update_params_rejected = NULL, .app_on_update_params_complete = NULL, .app_on_set_dev_config_complete = default_app_on_set_dev_config_complete, .app_on_adv_nonconn_complete = NULL, .app_on_adv_undirect_complete = user_app_adv_undirect_complete, .app_on_adv_direct_complete = NULL, .app_on_db_init_complete = default_app_on_db_init_complete, .app_on_scanning_completed = NULL, .app_on_adv_report_ind = NULL, .app_on_get_dev_name = default_app_on_get_dev_name, .app_on_get_dev_appearance = default_app_on_get_dev_appearance, .app_on_get_dev_slv_pref_params = default_app_on_get_dev_slv_pref_params, .app_on_set_dev_info = default_app_on_set_dev_info, .app_on_data_length_change = NULL, .app_on_update_params_request = default_app_update_params_request, .app_on_generate_static_random_addr = default_app_generate_static_random_addr, .app_on_svc_changed_cfg_ind = NULL, #if (BLE_APP_SEC) .app_on_pairing_request = default_app_on_pairing_request, .app_on_tk_exch = default_app_on_tk_exch, .app_on_irk_exch = NULL, .app_on_csrk_exch = NULL, .app_on_ltk_exch = default_app_on_ltk_exch, .app_on_pairing_succeeded = NULL, .app_on_encrypt_ind = NULL, .app_on_encrypt_req_ind = NULL, .app_on_security_req_ind = NULL, .app_on_addr_solved_ind = NULL, .app_on_addr_resolve_failed = NULL, .app_on_ral_cmp_evt = NULL, .app_on_ral_size_ind = NULL, .app_on_ral_addr_ind = NULL, #endif // (BLE_APP_SEC)

User Manual Revision 5.0 14-May-2018

CFR0012 103 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

}; The above structure defines that a certain event will be processed by a default handler or by a user defined handler or it will not be processed at all (NULL entries). The user defined handlers (e.g. user_app_connection(), user_app_disconnect() and user_app_adv_undirect_complete()) are defined in C source file user_ota.c. ● System specific events: static const struct app_bond_db_callbacks user_app_bond_db_callbacks = { .app_bdb_init = NULL, .app_bdb_get_size = NULL, .app_bdb_add_entry = NULL, .app_bdb_remove_entry = NULL, .app_bdb_search_entry = NULL, .app_bdb_get_number_of_stored_irks = NULL, .app_bdb_get_stored_irks = NULL, .app_bdb_get_device_info_from_slot = NULL, };

The above structure defines that a certain event will be processed by a default handler or by a user defined handler or it will not be processed at all (NULL entries). The user defined handlers (e.g. user_app_init()) is defined in C source file user_ota.c. ● BLE operations: static const struct default_app_operations user_default_app_operations = { .default_operation_adv = user_app_adv_start, }; The above structure defines that a certain operation will be processed by a default handler or by a user defined handler or it will not be processed at all (NULL entries). The user defined handlers (e.g. user_app_adv_start()) is defined in C source file user_ota.c. ● Custom profile message handling: static const catch_rest_event_func_t app_process_catch_rest_cb = (catch_rest_event_func_t)user_catch_rest_hndl; Callback function that contains the Custom profile messages handling in user application space. For Pillar 6 application this function is totally unused, since Pillar 6 application does not include any behavior related to the Custom service.

7.7.4.3 BLE Application Abstract Code Flow The code flow of the functions implemented in user_ota.c for the Pillar 6 application is the same as shown in Figure 36 for the Pillar 2 application. The whole OTA functionality requires no custom user application code to be written as it uses an internal module from the SDK.

7.7.5 Building the Project for Different Targets and Development Kits The Pillar 6 application can be built for two different target processors: DA14585 and DA14586. The selection is done via the Keil tool as depicted in Figure 58.

User Manual Revision 5.0 14-May-2018

CFR0012 104 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Figure 58: Building the Project for Different Targets

The user has also to select the correct Development Kit in order to build and run the application. This selection is done via the Configuration Wizard of the user_periph_setup.h file as shown in Figure 59.

Figure 59: Development Kit Selection for Pillar 6 Application

After the proper selection of the target processor and development kit, the application is ready to be built. As the default setting is to use SPI Flash to store update firmware image the jumpers must be enabled for SPI Flash accesses as shown in Table 3.

User Manual Revision 5.0 14-May-2018

CFR0012 105 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.7.6 Interacting with BLE Application

7.7.6.1 LightBlue iOS The LightBlue iOS application can be used to connect an iPad/iPod/iPhone device to the application. In such a case the iPad/iPod/iPhone acts as a BLE Central and the application as a BLE Peripheral. The following picture shows the result when the iPad/iPod/iPhone device manages to connect to the DA14585/586 (the application’s advertising device name is DIALOG-OTA).

Figure 60: LightBlue Application Connected to Pillar 6 Application

User Manual Revision 5.0 14-May-2018

CFR0012 106 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.7.7 SUOTA Application The Dialog SUOTA application can be installed from the App Store on iOS devices and from the Google Play Store on Android based platforms. Only devices that are advertising the SUOTAR service are shown to the user.

Figure 61: Dialog SUOTA Application Discovering Pillar 6 Application

User Manual Revision 5.0 14-May-2018

CFR0012 107 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.8 Pillar 7 (All in One)

7.8.1 Application Description The Pillar 7 (All in One) BLE example application demonstrates the same functionality as all previous applications. The project uses the “Integrated processor” configuration.

7.8.2 Basic Operation Supported services: ● Inherits the services from Pillar 2 application. ● Inherits the SUOTAR service from Pillar 6. Features: ● Inherits the features from Pillar 2 (Custom Profile) application. ● Inherits the features from Pillar 3 (Peripheral) application. ● Inherits the features from Pillar 4 (Security) application. ● Inherits the features from Pillar 5 (Sleep) application. ● Inherits the SUOTA functionality from Pillar 6 application. The Pillar 7 behavior is included in C source file user_all_in_one.c. Table 20 shows the Custom service 1 characteristic values along with their properties.

Table 20: Pillar 7 Custom Service Characteristic Values and Properties Name Properties Length (B) Description/Purpose CONTROL POINT WRITE 1 Accept commands from peer LED STATE WRITE NO RESPONSE 1 Toggles a LED connected to a GPIO ADC VAL 1 READ, NOTIFY 2 Reads sample from an ADC channel ADC VAL 2 READ 2 Reads sample from an ADC channel BUTTON STATE READ, NOTIFY 1 Reads the current state of a push button connected a GPIO INDICATEABLE CHAR READ, INDICATE 20 Demonstrate indications LONG VAL CHAR READ, WRITE. NOTIFY 50 Demonstrate writes to long characteristic value

The Pillar 7 application provides the same behavior for the Custom 1 Service as Pillar 3 (Peripheral) and Pillar 5 (Sleep). The implementation code of the Custom service is included in C source file user_custs1_impl.c.

User Manual Revision 5.0 14-May-2018

CFR0012 108 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Table 21: Pillar 7 SUOTAR Service Characteristic Values and Properties Name Properties Length (B) Description/Purpose SUOTA MEMORY DEVICE READ, WRITE 4 Defines what is the target physical memory device and base address of the patch. GPIO MAP READ, WRITE 4 Port and pin map for the physical memory device as well as device address in case of I2C EEPROMs. MEMORY INFORMATION READ 4 Number of bytes transferred. SUOTA PATCH LENGTH READ, WRITE 2 Block length of SUOTA image to be sent at a time. SUOTA PATCH DATA READ, WRITE, WRITE 20 20 bytes of SUOTA data, word NO RESPONSE aligned. MS byte first. SUOTA SERVICE STATUS READ, NOTIFY 1 SUOTA Service Status.

Pillar 7 provides the same SUOTA functionality as Pillar 6.

7.8.3 User Interface A peer connected to the Pillar 7 application has access the all the services provided individually by Pillars 2, 3, 4, 5, plus: ● Perform software updates as in the Pillar 6 application.

User Manual Revision 5.0 14-May-2018

CFR0012 109 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.8.4 Loading the Project The Pillar 7 application is developed under the Keil v5 tool. The Keil project file is: \projects\target_apps\ble_examples\ble_app_all_in_one\Keil_5\ble_a pp_ota.uvprojx Figure 62 shows the Keil project layout with emphasis on the user related files, included in the Keil project folders user_config, user_platform, user_custom_profile and user_app. These folders contain the user configuration files of the Pillar 7 application.

Figure 62: Pillar 7 Keil Project Layout

User Manual Revision 5.0 14-May-2018

CFR0012 110 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Just like in Pillar 3 the user_custs1_impl.c contain the implementation code of the Custom service.

7.8.5 Going Through the Code

7.8.5.1 Initialization The previously mentioned Keil project folders (user_config, user_platform, user_custom_profile and user_app) contain the files that initialize and configure the Pillar 7 application. \user_config ● da1458x_config_advanced.h, holds DA14585/586 advanced configuration settings. ● da1458x_config_basic.h, holds DA14585/586 basic configuration settings. ● user_callback_config.h, callback functions that handle various events or operations. ● user_config.h, holds advertising parameters, connection parameters. It also contains all the security configuration defines that the Pillar 4 (Security) application was using. More specifically, user may define: ○ The IO capabilities of the device ○ The support of Out of Band (OOB) data ○ The authentication requirements ○ The encryption key size ○ The minimum allowed security level (security requirements) ○ The key distribution capabilities ○ Depending on the user security configuration and the security capabilities of the peer device, one of the following pairing methods may occur: . Legacy Pairing – OOB . Legacy Pairing – Just Works . Legacy Pairing – Passkey Entry . Secure Connection – Just Works . Secure Connection – Passkey Entry . Secure Connection – Numeric Comparison ○ If none of the above flags is defined, then the security features will be set to the minimum security capabilities. ○ Peer device’s bond data can be stored on an external SPI Flash or I2C EEPROM memory. SPI Flash is the default setting. . #define USER_CFG_APP_BOND_DB_USE_SPI_FLASH, for SPI Flash (default) . #define USER_CFG_APP_BOND_DB_USE_I2C_EEPROM, for I2C EEPROM. . If neither of the above flags is defined the bond data will be only cached in the application RAM. . #define USER_CFG_BOND_DB_MAX_BONDED_PEERS, number of maximum bond data slots in database. ○ Note: At the time of writing this document, neither Android nor iOS support the OOB mechanism for Bluetooth pairing. SmartBond™ DA14585/586 supports the OOB mechanism, only when legacy pairing is used. ● This configuration header file allows also selecting the addressing mode and privacy capabilities of the peripheral device by setting the USER_CFG_ADDRESS_MODE flag to one of the following options: ○ APP_CFG_ADDR_PUB: . The peripheral device is non-private and operates with Public Address. Although it does not claim privacy support, it can resolve the Random Resolvable Private Address (RPA) of a bonded peer in its BLE host layer.

User Manual Revision 5.0 14-May-2018

CFR0012 111 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

. The Public Address of the device shall be set in CFG_NVDS_TAG_BD_ADDRESS flag in da1458x_config_advanced.h. This address does not change upon power-cycle. ○ APP_CFG_ADDR_STATIC: . The peripheral device is non-private and operates with a Random Static Address (RSA). Although it does not claim privacy support, it can resolve the RPA of a bonded peer in its BLE host layer. . There are three options to configure the RSA:  If user_gapm_conf.addr_type is set to a valid RSA, then this RSA will be used. This address does not change upon power-cycle.  If user_gapm_conf.addr_type is not valid and default_app_generate_static_random_addr is connected to app_on_generate_static_random_addr in user_callback_config.h, then a new RSA will be generated at each power-cycle.  If user_gapm_conf.addr_type is not valid and default_app_generate_unique_static_random_addr is connected to app_on_generate_static_random_addr in user_callback_config.h, then a unique device RSA will be generated based on information stored in the OTP header. This address does not change upon power-cycle. ○ APP_CFG_HOST_PRIV_RPA: . The peripheral device is a private one and operates with a RPA generated in its BLE host layer. The RPA of a bonded peer can also be resolved in its BLE host layer. . Identity information: The device shall exchange its identity information during pairing procedure.  A valid IRK shall be set in user_gapm_conf.irk and GAP_KDIST_IDKEY shall be enabled in USER_CFG_FEAT_RESP_KDIST.  The device will always send as identity address its Public Address defined in CFG_NVDS_TAG_BD_ADDRESS.  Renew duration: The interval of generating a new RPA shall be set in user_gapm_conf.renew_dur. This field controls the duration of RPA before it gets regenerated and it is counted in units of 10 ms. The minimum valid value for renew_dur is 15000 (150 s). If the value of renew_dur is set to less than 15000 then BLE stack will automatically set it to 15000. ○ APP_CFG_HOST_PRIV_NRPA: . The device is a private one and operates with a non-RPA generated in its BLE host layer. This configuration can only be used in non-connectable modes/procedures (e.g. broadcaster role, non-connectable advertising). ○ APP_CFG_CNTL_PRIV_RPA_PUB: . The peripheral device is a private one and operates with a RPA generated in its BLE controller layer. When the device is bonded with a peer, then the device information of the peer will be stored in the resolving list located in the BLE controller layer. Upon re-connection, the RPA of the bonded peer will be automatically resolved in the BLE controller layer and its identity will be directly used in the application layer of the peripheral device. If the resolving list of the peripheral is empty (no bonded devices), then it will operate with a Public Address. . Identity information: The device shall exchange its identity information during pairing procedure.

User Manual Revision 5.0 14-May-2018

CFR0012 112 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

 A valid IRK shall be set in user_gapm_conf.irk and GAP_KDIST_IDKEY shall be enabled in USER_CFG_FEAT_RESP_KDIST.  The device will always send as identity address its Public Address defined in CFG_NVDS_TAG_BD_ADDRESS.  Renew duration: The interval of generating a new RPA shall be set in user_gapm_conf.renew_dur. This field controls the duration of RPA before it gets regenerated and it is counted in units of 10 ms. The minimum valid value for renew_dur is 15000 (150 s). If the value of renew_dur is set to less than 15000 then BLE stack will automatically set it to 15000. ○ APP_CFG_CNTL_PRIV_RPA_RAND: . The peripheral device is a private one and operates with a RPA generated in its BLE controller layer. When the device is bonded with a peer, then the device information of the peer will be stored in the resolving list located in the BLE controller layer. Upon re-connection, the RPA of the bonded peer will be automatically resolved in the BLE controller layer and its identity will be directly used in the application layer of the peripheral device. The peripheral will operate with RPA independently to the existence of bonded peers. . Identity information: The device shall exchange its identity information during pairing procedure.  A valid IRK shall be set in user_gapm_conf.irk and GAP_KDIST_IDKEY shall be enabled in USER_CFG_FEAT_RESP_KDIST.  The device will always send as identity address its Public Address defined in CFG_NVDS_TAG_BD_ADDRESS.  Renew duration: The interval of generating a new RPA shall be set in user_gapm_conf.renew_dur. This field controls the duration of RPA before it gets regenerated and it is counted in units of 10 ms. The minimum valid value for renew_dur is 15000 (150 s). If the value of renew_dur is set to less than 15000 then BLE stack will automatically set it to 15000. ● The controller privacy mode can be set by defining the USER_CFG_CNTL_PRIV_MODE flag to one of the following values: ○ APP_CFG_CNTL_PRIV_MODE_NETWORK: Peripheral device will only accept advertising packets from bonded peer devices that operate with RPA. ○ APP_CFG_CNTL_PRIV_MODE_DEVICE: Peripheral device will accept advertising packets from bonded peer devices that operate with both RPA and non-private addresses (Public, Random Static). ● user_modules_config.h, defines which application modules are included or excluded from the user’s application. For example: ○ #define EXCLUDE_DLG_DISS (0), the Device information application profile is included. The SDK takes care of the Device information application profile message handling. ○ #define EXCLUDE_DLG_DISS (1), the Device information application profile is excluded. The user application has to take care of the Device information application profile message handling. ● user_periph_setup.h, holds hardware related settings relative to the used Development Kit. In this particular application it also defines the I2C pin configuration for the EEPROM module. ● user_profiles_config.h, defines which BLE profiles (Bluetooth SIG adopted or custom ones) will be included in user’s application. Particularly, the C header files (each header file denotes the respective BLE profile) that are included in the user_profile_config.h file are: ○ CFG_PRF_DISS, includes the Device Information service.

User Manual Revision 5.0 14-May-2018

CFR0012 113 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

○ CFG_PRF_SUOTAR, includes the SUOTAR service. ○ CFG_PRF_CUST1, includes the Custom 1 service. The security requirement for a specific profile can be defined here. For example: ○ #define APP_SUOTA_SEC_REQ SRV_PERM_SECURE: In order to access specific attributes of the SUOTA service, a minimum security of mode 1 level 4 has to be reached. ○ #define APP_CUSTS1_SEC_REQ SRV_PERM_UNAUTH: In order to access specific attributes of the CUSTS1 services, a minimum security of mode 1 level 2 has to be reached. It also exposes some configuration flags for the SUOTAR service: ○ #define CFG_SUOTAR_I2C_DISABLE , Disable I2C external memory module ○ #define CFG_SUOTAR_SPI_DISABLE , Disable SPI external memory module \user_custom_profile ● user_custs1_def.c, defines the structure of the Custom 1 profile database structure. ● user_custs_config.c, defines the cust_prf_funcs[] array, which contains the Custom profiles API functions calls. \user_platform ● user_periph_setup.c, source code file that handles peripheral (GPIO, UART, etc.) configuration and initialization relative to the Development Kit. \user_app ● user_all_in_one.c, source code file that implements the application specific code such as creating the advertising packet, managing the timers to control the advertising period and handling connection events. It also enables the sleep, the security and provides the handler for SUOTA state changes and checks if on a disconnection a SUOTA triggered reboot is required. ● user_custs1_impl.c, source code file that provides all the handlers to implement the custom characteristics for custom service 1.

Note 25 For more information about the user_config directory of BLE_APP_ALL_IN_ONE demo application please refer to section 8.3 of [5]. Note 26 The SDK by default as well as this application, during initialization, reads and uses the XTAL16M oscillator trimming value as stored in the OTP header. However, if there has been no trimming yet, the XTAL16M oscillator trimming value in the OTP Header will be zero, and this zero value will then be used by default from the SDK. To alter the default behavior, the SDK provides a configuration flag that allows the user to still read and use the XTAL16M oscillator trimming value from the OTP header, so that if the stored OTP value is zero, it reverts in using an indicative hardcoded value as the XTAL16M oscillator trimming value. You can read more about the XTAL16M oscillator trim on the OTP Header section in the device datasheet, or at Table 37, of Appendix G Booting from serial interfaces, in the UM-B-079 DA14585/586 SDK 6 Software Platform Reference document. Note 27 The OTP header value for the XTAL16M oscillator trimming in the DA14585 and DA14586 devices on the Pro and Basic Development Kits, is not written (ie it is read as zero), to allow for the user/developer to provide and write a preferred XTAL16M oscillator trimming value. Therefore, if you have not calculated and written already a non-zero value, in the XTAL16M oscillator trimming value for the Development Kit that you have in use, it is advised to enable and use in this application and in the SDK the CFG_USE_DEFAULT_XTAL16M_TRIM_VALUE_IF_NOT_CALIBRATED configuration flag, that resides within the da1458x_config_advanced.h file as follows; #define CFG_USE_DEFAULT_XTAL16M_TRIM_VALUE_IF_NOT_CALIBRATED

7.8.5.2 Events Processing and Callbacks Several events can occur during the lifetime of the Bluetooth low energy application and these events need to be handled in a specific manner. The application is responsible for selecting which events and operations it should handle and which it should just leave to be handled with the default SDK behavior.

User Manual Revision 5.0 14-May-2018

CFR0012 114 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

The SDK uses a mechanism which registers callbacks for every event or operation that defines the system behavior. The C header file user_callback_config.h, which is part of the user application contains the registration of callback functions. The SDK mechanism that takes care of the above requirements, is the registration of callback functions for every event or operation. The C header file user_callback_config.h, which resides in user space, contains the registration of the callback functions. The Pillar 7 application registers the following callback functions: ● General BLE events: static const struct app_callbacks user_app_callbacks = { .app_on_connection = user_app_connection, .app_on_disconnect = user_app_disconnect, .app_on_update_params_rejected = NULL, .app_on_update_params_complete = NULL, .app_on_set_dev_config_complete = default_app_on_set_dev_config_complete, .app_on_adv_nonconn_complete = NULL, .app_on_adv_undirect_complete = user_app_adv_undirect_complete, .app_on_adv_direct_complete = NULL, .app_on_db_init_complete = default_app_on_db_init_complete, .app_on_scanning_completed = NULL, .app_on_adv_report_ind = NULL, .app_on_get_dev_name = default_app_on_get_dev_name, .app_on_get_dev_appearance = default_app_on_get_dev_appearance, .app_on_get_dev_slv_pref_params = default_app_on_get_dev_slv_pref_params, .app_on_set_dev_info = default_app_on_set_dev_info, .app_on_data_length_change = NULL, .app_on_update_params_request = default_app_update_params_request, .app_on_generate_static_random_addr = default_app_generate_unique_static_random_addr, .app_on_svc_changed_cfg_ind = NULL, #if (BLE_APP_SEC) .app_on_pairing_request = default_app_on_pairing_request, .app_on_tk_exch = user_app_on_tk_exch, .app_on_irk_exch = NULL, .app_on_csrk_exch = default_app_on_csrk_exch, .app_on_ltk_exch = default_app_on_ltk_exch, .app_on_pairing_succeeded = default_app_on_pairing_succeeded, .app_on_encrypt_ind = NULL, .app_on_encrypt_req_ind = default_app_on_encrypt_req_ind, .app_on_security_req_ind = NULL, .app_on_addr_solved_ind = default_app_on_addr_solved_ind, .app_on_addr_resolve_failed = default_app_on_addr_resolve_failed, .app_on_ral_cmp_evt = NULL, .app_on_ral_size_ind = NULL, .app_on_ral_addr_ind = NULL, .app_on_ral_cmp_evt = default_app_on_ral_cmp_evt, .app_on_ral_size_ind = NULL, .app_on_ral_addr_ind = NULL, #endif // (BLE_APP_SEC) };

The above structure defines that a certain event will be processed by a default handler or by a user defined handler or it will not be processed at all (NULL entries). The user defined handlers (e.g user_app_connection(), user_app_disconnect(), user_app_adv_undirect_complete(), and user_app_on_tk_exch()) are defined in C source file user_all_in_one.c. Note that most of them will be called from the enabled security application module (the preprocessor value CFG_APP_SECURITY must be defined in da1458x_config_basic.h to set BLE_APP_SEC).

User Manual Revision 5.0 14-May-2018

CFR0012 115 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Note 28 The default configuration of the project uses UART to display the Temporary Keys in case of Passkey Entry and Numeric Comparison pairing methods. ○ However, if CFG_PRINTF is undefined or default_app_on_tk_exch is used, then the Passkey will have a default value of “123456”. ○ In each case of Numeric Comparison, the confirmation value will be automatically accepted, since a keyboard or Yes/No buttons are not implemented in the specific example. ○ In case of Secure Connections, the LTK will be also printed in UART, so that it can be used with debugging/sniffing tools. ● Bond database specific events: static const struct app_bond_db_callbacks user_app_bond_db_callbacks = { .app_bdb_init = default_app_bdb_init, .app_bdb_get_size = default_app_bdb_get_size, .app_bdb_add_entry = default_app_bdb_add_entry, .app_bdb_remove_entry = NULL, .app_bdb_search_entry = default_app_bdb_search_entry, .app_bdb_get_number_of_stored_irks = default_app_bdb_get_number_of_stored_irks, .app_bdb_get_stored_irks = default_app_bdb_get_stored_irks, .app_bdb_get_device_info_from_slot = default_app_bdb_get_device_info_from_slot, };

The above structure defines that a certain event will be processed by a default handler or by a user defined handler or it will not be processed at all (NULL entries). By default, a bond database is implemented in app_bond_db.c. However, a user implementation of the bond database can be hooked to the above callback table. The default implementation of the bond database: ○ Has a default number of five bond data slots. ○ In each valid slot, depending on the bonding procedure, bond database stores the keys (LTKs – including EDIV and RandNB, remote IRK – including peer’s identity, CSRKs), the peer’s BD address and a set of flags. ○ When adding bond data for a peer device the storing algorithm checks if an older entry exists for that peer in the bond DB. If yes, it updates the old entry, otherwise uses an empty slot. If there is not an empty slot in the database, then the least recently added slot will be replaced. ○ Bond data of known peer device can be searched and/or removed using different types (by slot, by EDIV, by BD address, by IRK, etc.) ○ app_bdb_get_stored_irks can be used to get all the stored IRKs in the database. This is useful when the peer has a random private resolvable address, which needs to be resolved. ● System specific events: static const struct arch_main_loop_callbacks user_app_main_loop_callbacks = { .app_on_init = user_app_init, .app_on_ble_powered = NULL, .app_on_sytem_powered = NULL, .app_before_sleep = NULL, .app_validate_sleep = NULL, .app_going_to_sleep = NULL, .app_resume_from_sleep = NULL, }; The above structure defines that a certain event will be processed by a default handler or by a user defined handler or it will not be processed at all (NULL entries). The user defined handlers (e.g. user_app_init()) is defined in C source file user_all_in_one.c. ● BLE operations: static const struct default_app_operations user_default_app_operations = { .default_operation_adv = user_app_adv_start, };

User Manual Revision 5.0 14-May-2018

CFR0012 116 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

The above structure defines that a certain operation will be processed by a default handler or by a user defined handler or it will not be processed at all (NULL entries). The user defined handlers (e.g. user_app_adv_start()) is defined in C source file user_all_in_one.c. ● Custom profile message handling: static const catch_rest_event_func_t app_process_catch_rest_cb = (catch_rest_event_func_t)user_catch_rest_hndl; Callback function that contains the Custom profile messages handling in user application space. For the Pillar 7 application this function is handling the same write or read request as the Pillar 3 (Peripheral) and Pillar 5 (Sleep) applications do.

User Manual Revision 5.0 14-May-2018

CFR0012 117 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.8.5.3 BLE Application Abstract Code Flow Figure 63 shows the abstract code flow diagram of the Pillar 7 application in a simplified form. The diagram depicts the SDK interaction with the callback functions registered in user_callback_config.h and the functions implemented in user_all_in_one.c. The initialization sequence is the same as in the Pillar 1 application and is not shown on this diagram.

User User SDK Application Configuration

app_easy_gap_undirected_advertise_start()

g n t i u s i o t r app_on_adv_undirect_complete() e e m v i t d

user_app_adv_undirect_complete() A app_easy_wakeup_set(app_wakeup_cb) ) t s n s

platform goes to sleep mode... e e v r e p

p n u

app_wakeup_cb() o t e t k u a

app_easy_gap_undirected_advertise_start() b ( W

app_on_adv_undirect_complete() user_app_adv_undirect_complete() app_on_connection() user_app_connection() default_app_on_connection()

app_on_pairing_request() default_app_on_pairing_request() . . . app_on_pairing_succeeded() default_app_on_pairing_succeeded()

Figure 63: Pillar 7 Application - User Application Simplified Code Flow

User Manual Revision 5.0 14-May-2018

CFR0012 118 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.8.6 Building the Project for Different Targets and Development Kits The Pillar 7 application can be built for two different target processors: DA14585 and DA14586. The selection is done via the Keil tool as depicted in Figure 64.

Figure 64: Building the project for different targets

The user has also to select the correct Development Kit to build and run the application. This selection is done via the Configuration Wizard of the user_periph_setup.h file as shown in Figure 65.

Figure 65: Development Kit Selection for the Pillar 7 Application

After the proper selection of the target processor and development kit, the application is ready to be built. Note 29 As the default setting is to use SPI Flash to store the bonding and software update information the jumpers must be enabled for SPI Flash accesses as shown in Table 3.

User Manual Revision 5.0 14-May-2018

CFR0012 119 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7.8.7 Interacting with BLE Application

7.8.7.1 LightBlue iOS The LightBlue iOS application can be used to connect an iPad/iPod/iPhone device to the application. In such a case the iPad/iPod/iPhone acts as a BLE Central and the application as a BLE Peripheral. Figure 66 shows the result when the iPad/iPod/iPhone device manages to connect to the DA14585/586 (the application’s advertising device name is DIALOG-ALL-IN). Please note that during the device interrogation you can be asked to accept pairing or enter passkey. It depends on security settings that are currently defined in user_config.h.

Figure 66: LightBlue Application Connected to Pillar 7 Application

User Manual Revision 5.0 14-May-2018

CFR0012 120 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

8 AES Encryption example application

8.1 Application Description The AES Encryption demo application is a simple application example which demonstrates how the CryptoAPI can be used to encrypt or decrypt user data using AES algorithm. Note 30 user can also use this CryptoAPI while a BLE connection is ongoing. The project is in the SDK directory. \projects\target_apps\misc\aes. The Keil v5 project file is in the \projects\target_apps\ misc\aes\Keil_5\aes.uvprojx directory. The Crypto API makes use of the AES-128 Encryption hardware block to accelerate the calculations needed to do an AES encryption. For decryption a SW based algorithm is used. Note that the AES Encryption demo makes use of the AES Crypto API during the application initialization. It is not guaranteed that the example will work properly if the Crypto API is called at any other time apart from the initialization e.g. during the advertising/connection events. For more information about the Crypto API please refer to Appendix E of [5].

8.2 Hardware Configuration The common UART terminal configuration described in section 6.4 is required. The port that the board is attached is automatically identified. A serial terminal like Tera Term is needed with serial port settings shown in Figure 67.

Figure 67: Serial port settings

8.3 Running the example Once the user has built and loaded the example project to the DK, the console will display the messages shown in Figure 68. A key and a plain text are provided by the example. For more info about the key and the plain text please refer to [13]. The AES Encryption demo application supports the use of the CryptoAPI while a BLE connection is ongoing. To demonstrate this function:  A BLE connection must be successfully established. The console prints the messages shown in Figure 68 User Manual Revision 5.0 14-May-2018

CFR0012 121 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

 User then must disconnect from the device (manually)  User must reconnect to device. AES encryption runs again as shown in Figure 69.

The application first encrypts the plain text using the key then the encrypted data are decrypted. The aes_operation() function is used for the encryption and the decryption. The app_aes_test() function uses user_app_format_data()function to print the results on the console.

Figure 68: AES encryption demo application

Figure 69: AES encryption on ongoing BLE connection

The source code for this example is found in: \projects\target_apps\misc\aes\src\user_aes.c

User Manual Revision 5.0 14-May-2018

CFR0012 122 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

9 ANCS Client example application

9.1 Application Description This application is a sample implementation of an Apple Notification Center Service (ANCS) Client. The DA1585/586 SDK contains a simple implementation of the Notification Consumer (NC) device application. The project demonstrates the use of the ANCS client task from user code space. The application prints log messages using serial port. The ANCS demo application uses also GATT client to handle service change notifications from a Notification Provider (NP) device. Note 31 For more information about ANCS Client please refer to [15]. The application supports all features of Notification Consumer (NC) role provided by this service. The ANCS Client demo application is an application example which can contact the apple notification center and retrieve new messages if needed. These messages - once received - could be streamed to the user by e.g. using UART. The project is found in the SDK directory: \projects\target_apps\misc\ancs_client. The Keil v5 project file is: \projects\target_apps\misc\ancs_client\Keil_5\ ancs_client.uvprojx Upon connection the iOS device does its best to inform the NC of any pre-existing notifications. By default, all of these pre-existing notifications are dropped by the application and only notifications generated after the connection are processed. For every new notification received, the ANCS Client requests the notification attributes / performs negative action / takes no action, by performing a check. The ANCS Client example application can be easily adjusted to meet the functional requirements of a relevant product. In case it is required to get the attributes of every received notification, care must be taken to ensure the client application does not run out of memory in the event of notification and attribute flooding. A proposed way of dealing with that situation is to introduce an attribute fetching and caching mechanism as per the ANCS specification [15]. Note 32 For the ANCS client task API please refer to Appendix F of [5].

9.2 Going Through the Code This section describes the NC demo implementation. ● user_profiles_config.h –the following definitions enable the client tasks

#define CFG_PRF_ANCC – enable ANCS client #define CFG_PRF_GATTC – enable GATT client

#define ANC_CFG_DROP_PREEXISTING_NTF (1) – enables feature that after connection will drop all received notification that were pre-existing on the NP device, too many notifications received in short period can cause out of memory situation and platform crash

#define CFG_VERBOSE_LOG (0) - enables extended printouts from application. Disabled by default. ● user_callback_config.h – contains definition of the ANCS client and GATT client application callback structures ● user_ancs_client.h – contains definitions of ANCS related handlers functions ● user_ancs_client.c – contains implementation of ANCS related handlers function Keil project files are located in \projects\target_apps\misc\ancs_client\Keil_5. To open the project please use ancs_client.uvprojx file.

User Manual Revision 5.0 14-May-2018

CFR0012 123 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

The Demo ANCS client application uses UART (with the default configuration) to print application output. For this reason SPI flash memory cannot be used to store bond data. To disable the storing of bond data in the SPI USER_CFG_APP_BOND_DB_USE_SPI_FLASH must be udefined in the user_config.h file To store bond data in non-volatile memory, user can use I2C eeprom or redefine UART configuration and use SPI flash located on DK. Note 33 As the default setting is to use SPI Flash to store the bonding and software update information the jumpers must be enabled for SPI Flash accesses as shown in Table 3. After selecting required target (585 or 586) project can be compiled and run the same way as any other project located in the SDK. To use the demo application, user needs an iOS device that supports Apple Notification Centre.

9.3 Advertising, connecting, configuring After booting, NC starts advertising with name DLG-ANCC-DEMO. NP starts scan for the NC device and triggers a connection. When the connection is established NC waits for one second before starting the discovery procedure. The purpose of this delay is to give the NP some time to complete its initialization procedure. Figure 71 shows the basic message flowchart between NC application, client tasks and the NP device. After the discovery of the services, NC enables Service Change indication and notifications for the ANCS service. In case of insufficient authentication error NC will trigger pairing procedure.

Figure 70: Booting - sample log snippet

User Manual Revision 5.0 14-May-2018

CFR0012 124 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Figure 71: Booting - message flowchart

9.4 ANCS notification handling Figure 72 shows the basic flowchart for the notification handling. NC demo application uses a simple queue mechanism to store incoming notifications. The memory used for data storage is dynamically allocated within the KE_MEM_ENV heap region. The size of this region can be configured in the da1458x_config_advanced.h file.

User Manual Revision 5.0 14-May-2018

CFR0012 125 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Figure 72: Basic Notification handling flowchart

Before each memory allocation NC checks if there is enough space available. If there is no memory available, notification data is dropped. This should prevent heap overflow errors. NC uses two separate queues. One for storing incoming notifications and attributes and one for application attributes. When a new notification event is received from the ANCS client task (user_on_ancc_ntf_src_ind_cb ()), memory for notification structure is allocated and added to the notification queue: // ANCS notification details info struct notification { struct co_list_hdr hdr; struct anc_ntf_src ntf; char title[ANCC_ATTS_MAX_LEN]; char date[ANCC_ATTS_MAX_LEN]; char message[ANCC_ATTS_MSG_MAX_LEN]; char *app_id; }; Fields for title, date and message id have a predefined maximum length. Space for application id is allocated after receiving a related event.

User Manual Revision 5.0 14-May-2018

CFR0012 126 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

When NC receives a notification from the queue, sends a request to the ANC client to get the notification attributes (app_ancc_get_ntf_atts()). Then the ANC client task passes each received attribute to the application layer in a separate message (user_on_ancc_ntf_src_ind_cb()). Attributes are stored in the notification structure. When all requested notification attributes are received (user_on_ancc_get_ntf_att_cmp_cb()) the NC checks if the application attribute for a specific application id has already be received and stored. If the application attribute is not present, NC sends a request to the ANC client to fetch it (app_ancc_get_app_atts()). When the attribute is received (user_on_ancc_app_att_ind_cb()) NC allocates memory and stores data in the application queue: // ANCS application info struct application { struct co_list_hdr hdr; char *app_id; char *display_name; }; The application attribute is fetched only once from the NP. It is kept in memory for as long as the connection is alive and reused if needed. Memory allocated for application attributes is released upon a disconnection event. When fetching an application attribute is completed (user_on_ancc_get_app_att_cmp_cb()), a message with notification details is printed on the serial console. Figure 73 contains an example log snippet that shows received notifications details.

Figure 73: Sample notifications – log

In the last step, the NC releases the memory allocated for notifications. If the notification queue is not empty, the NC gets the next element and starts fetching its attributes. The described process repeats until the notification queue is empty. Figure 74 shows a detailed message flowchart between the NC application layer, the ANC client task and the NP device.

User Manual Revision 5.0 14-May-2018

CFR0012 127 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Figure 74: Detailed notification handling flowchart

9.5 GATT service change notifications handling NP triggers a Service Change indication to inform the NC that a range of handles has changed. The NC checks if the handles range pointed in Service Change indication match the handles range that was previously discovered for ANCS service. If handles match, the ANCS service will be rediscovered. If service rediscovery is successful, the application will enable ANCS notifications. In case the rediscovery failed, application will wait for the next Service Change indication.

User Manual Revision 5.0 14-May-2018

CFR0012 128 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Figure 75: Service change indication - sample log

Figure 76: Service change indication message flowchart

9.6 Verbose logging User can enable more detailed logging by setting the CFG_VERBOSE_LOG flag before compiling. By default, verbose logging feature is disabled.

User Manual Revision 5.0 14-May-2018

CFR0012 129 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Figure 77: Verbose logs enabled

9.7 Trigger negative action User can trigger a negative action for the last received notification, e.g. reject incoming call. Negative action is triggered by pressing SW3 button on a ProDK motherboard. To see the result of the negative action verbose logging must be enabled.

Figure 78: reject incoming call

9.8 Hardware Configuration The common UART terminal configuration described in section 6.4 is required. A serial terminal like Tera Term is needed with serial port settings shown in Figure 67.

User Manual Revision 5.0 14-May-2018

CFR0012 130 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Figure 79: Serial port settings

9.9 Running the example The application runs as Notification Consumer, thus it uses LE Peripheral role when started and starts advertising. 1. Use iOS device for scan for devices and connect to ANCS demo application 2. Due to security requirements of ANCS pairing will be triggered and should be accepted. 3. Once connected, any notification which already exist on iOS device will be retrieved and printed in logs. 4. Any new notification on iOS device will be retrieved and printed in logs from now on. 5. Notifications can be created using various apps like Mail, Reminders, Calendars and many others. Debug logs are output using serial port available when platform is connected to PC. Once the user has built, loaded and run the example project on the DK, the console will display the messages as shown in Figure 80 and Figure 81 .

Figure 80: ANCS example advertising console message User Manual Revision 5.0 14-May-2018

CFR0012 131 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Figure 81: ANCS example pairing console message

User Manual Revision 5.0 14-May-2018

CFR0012 132 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

10 Non-Connectable Advertising example application

10.1 Application Description This demo is a non-connectable advertising application example. To make non-connectable advertising more efficient the flag type field inside the advertising packet is optional (please check Core Specification Supplement v6 by Bluetooth SIG). If the flag type field is not used it will free up to 3 Bytes of space which can be used to send more advertising data. This might be useful for BLE mesh applications. The project is in the SDK directory \projects\target_apps\misc\. The Keil v5 project file is: \projects\target_apps\misc\ble_app_noncon\Keil_5\ ble_app_noncon.uvprojx

10.2 Running the example Once the user has built and loaded the example the device starts advertising non-connectable packets.

User Manual Revision 5.0 14-May-2018

CFR0012 133 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

11 External wake-up mechanisms This section describes the external wake-up mechanisms that can be used in external processor based applications of the DA14585/586 SoC to further extend the already ultra-low power features of the device. The two possible wakeup mechanisms are that: ● The DA14585/586 sleeps forever and is woken up by an external processor signal. This can be used as an alternative to the existing auto-wakeup mechanism ● The external processor is in sleep mode and is woken up by the DA14585/586 on a pre- programmed Bluetooth low energy timer event or a kernel timer expiration.

They are both described in the following sections.

11.1 External Processor Wakes up DA14586/586 For the external processor to DA14585/586 wake-up feature, the DA14585/586 Wakeup Timer, as described in [3], [4] and [5] can be used. This DA14585/586 internal hardware block can wake up the system after a pre-programmed number of GPIO events. Any of the GPIO inputs can be selected and configured to generate a wake-up interrupt. A simple toggle of the pre-configured pin will wake up the system. In this wake-up architecture, the DA14585/586 sleeps forever (see Section 11.3 for more information) and only wakes up when the external host wants it to. This external host processor can wake up the system by toggling a DA14585/586 GPIO assigned to a DA14585/586 wake-up interrupt and send the required message. The following DA14585/586 signals can be used as wake-up signals: ● Any GPIO ● The DA14585/586 UART CTS signal, when the UART is being used as the transport layer. ● The DA14585/586 SPI_EN (CS) when SPI is being used as the transport layer. When the last two signals are used the following applies: a DA14585/586 GPIO cannot have multiple functions at the same time. For example, it cannot act as a UART CTS signal and as a wake-up interrupt simultaneously. Therefore, the software must reconfigure the GPIO functionality as required. Before going to sleep, the software must configure the GPIO as a wake-up interrupt. When the DA14585/586 wakes up, it should reconfigure it back to UART CTS. Sections 11.1.1, 11.1.2 and 11.3 provide a more detailed analysis of the external processor to DA14585/586 wake-up procedure. Three examples are provided: using any GPIO, using the UART CTS signal and using the SPI_EN signal.

11.1.1 Waking up the DA14585/586 using any GPIO Any DA14585/586 GPIO can be used as wake-up interrupt for the DA14585/586. This generic implementation implies that the user is aware of the system hardware and that the GPIO used will not conflict with any other external hardware. When the user decides to use any GPIO in either the UART or the SPI transport interface, it should be noted that the flow control of the transport layer should definitely be used. The flow control will provide a safe mechanism for communication synchronization. Only by using the flow control the host system will be sure that the DA14585/586 has woken up and is ready to receive messages. Figure 83 illustrates the generic GPIO wake-up process with flow control and Figure 82 shows the required connections.

User Manual Revision 5.0 14-May-2018

CFR0012 134 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Figure 82: External CPU to DA14585/586 generic wake-up connections

Figure 83: External CPU to DA14585/586 generic wake-up process

Details: 1. The DA14585/586 is in sleep mode. The GPIO input signal has simple GPIO functionality and is configured to have a wake-up interrupt, active either LOW or HIGH. 2. The external processor wants to send a message to the DA14585/586. It toggles the GPIO. 3. The external processor cannot send any data yet. The DA14585/586 is still in the wake-up process and therefore the external processor should wait for the flow control signal. 4. The DA14585/586 has woken up and asserts or de-asserts (depending on the transport layer used) the flow control signal. It is ready to receive messages. 5. The external processor detects the flow control signal and sends the data. 6. The DA14585/586 replies. 7. Actions on the DA14585/586 are performed, according to the received message and when finished it goes to sleep by appropriate flow control signaling.

11.1.2 Waking up the DA14585/586 using the UART CTS signal In this external wake-up configuration using the UART CTS as a wake-up signal, a special requirement exists: the external processor should be able to modify its RTS signal functionality. That means that it should be able to toggle its RTS signal before sending anything via the UART interface.

User Manual Revision 5.0 14-May-2018

CFR0012 135 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

This may not be feasible in some processors, as the UART driver might be a fixed hardware block with dedicated signals whose functionality cannot be changed. In that case the process described in Section 11.1.1 can be used. Figure 84 shows the connections needed and Figure 85 illustrate the external wake-up process. A more detailed description follows.

Figure 84: External CPU to DA14585/586 wake-up UART connections

Figure 85: External CPU to DA14585/586 wake-up process via UART

Details: 1. The DA14585/586 is in sleep mode. The CTS input signal has simple GPIO functionality and is configured to have an active HIGH wake-up interrupt. 2. The external processor wants to send a message to the DA14585/586. It should take control of the CTS signal from its UART driver block and toggle it HIGH. 3. The external processor cannot send any data yet because the RTS signal is still HIGH. The DA14585/586 is still in the wake-up process. 4. The DA14585/586 has woken-up and sets the RTS signal LOW. It is ready to receive messages. 5. The external processor detects the LOW level of the RTS signal and sends the data. 6. The DA14585/586 replies.

User Manual Revision 5.0 14-May-2018

CFR0012 136 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

7. Actions on the DA14585/586 are performed, according to the received message and when finished it goes to sleep, making RTS HIGH. 8. At the same time and just before entering sleep, the DA14585/586 changes the CTS signal from UART CTS functionality to simple GPIO functionality with external wake-up interrupt.

11.1.3 Waking up the DA14585/586 using the SPI_EN signal The SPI external wake-up process uses a similar procedure to the UART described above. The same requirement exists, which implies that the external CPU should be able to control the SPI_EN (CS) SPI signal apart from any dedicated SPI driver it may have. Figure 86 and Figure 87 are described in [12]. They illustrate an external wake-up process with the SPI using the SPI_EN as the wake-up signal.

Figure 86: External CPU to DA14585/586 wake-up SPI connections

Figure 87: External CPU to DA14585/586 wake-up process via SPI

Details: 1. The DA14585/586 is in sleep mode. The SPI_EN input signal has simple GPIO functionality and is configured to have an active LOW wake-up interrupt.

User Manual Revision 5.0 14-May-2018

CFR0012 137 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

2. The external processor wants to send a message to the DA14585/586. It should take control of the SPI_EN signal from its SPI driver block and toggle it LOW. 3. The external processor cannot send any data yet, since the SPI custom flow control is enabled as described in [12]. 4. The DA14585/586 has woken up and sets the DREADY signal HIGH as described in [12]. 5. The external processor detects the HIGH level on the DREADY signal and sets the SPI_EN LOW. 6. The MOSI and MISO bytes and the rest of the flow control process and SPI data exchange are described in [12].

11.2 Waking up an external processor from DA14585/586 The DA14585/586 can wake up an external processor by toggling a GPIO signal. The DA14585/586 system could wake itself up to service BLE events, respond to internal kernel timer expirations and perform other tasks. When the DA14585/586 system wakes up, the UART or the SPI interface is automatically activated to enable the communication with the external processor and possibly send a message to it. If the external processor is in sleep mode, the DA14585/586 can toggle a GPIO to wake up the external processor. Figure 88 shows a block diagram of the connections needed for the DA14585/586 to wake up an external processor. Figure 89, illustrates the process. It shows how the DA14585/586 can wake up an external processor before sending a message over the transport layer interface. A simple DA14585/586 GPIO signal is used and is toggled according to the external processor requirements. Flow control should be used with both the SPI or UART options to ensure communication synchronization. The steps outlined next give a more detailed description of the process.

Figure 88: DA14585/586 to external processor wake-up connections

User Manual Revision 5.0 14-May-2018

CFR0012 138 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Figure 89: DA14585/586 to external processor wake-up process

Details: 1. The external processor is in sleep mode. The DA14585/586 GPIO signal, configured to act as the external processor wake-up signal, is set to output. It is initialized either to LOW or HIGH depending on the external processor wake-up signal requirements. 2. The DA14585/586 wants to send a message to the external processor. The DA14585/586 should toggle the GPIO to wake up the external processor. 3. The DA14585/586 cannot yet send any data. The external processor is still in the wake-up process and therefore the DA14585/586 should wait for the flow control signaling. 4. The external processor has woken up and it asserts or de-asserts (depending on the interface used) the flow control signal. It is ready to receive messages. 5. The DA14585/586 detects the level change of the flow control signal and sends the data. 6. The external processor replies. 7. Actions on the external processor are performed, according to the received message and when finished it goes to sleep by appropriate flow control signaling.

11.3 Sleep limitation A sleep limitation currently exists in the software stack, which prevents the DA14585/586 to sleep forever in the external processor configuration and when the GTL interface is used. This limitation does not exist in the integrated processor configuration software. The DA14585/586 must automatically wake itself up at least every 600s, even when no external wake-up interrupt is triggered. This automatic wake up does not prevent the external wake-up process to be fully functional as described. A workaround for this limitation will be given in a future release of this application note, as alternatives are still under investigation.

11.4 Software changes The software changes needed to implement the external wake-up processes will be outlined next.

User Manual Revision 5.0 14-May-2018

CFR0012 139 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

11.4.1 External processor to DA14585/586 wake-up process software To enable the external processor to DA14585/586 wake-up process one should include the following definition: /*External wake up mechanism*/ #define EXTERNAL_WAKEUP 1 This definition can be found in the following two files: \sdk\platform\arch\arch.h The external wake-up GPIO assignment can be passed as a function parameter when the function ext_wakeup_enable() is called. This is called when EXTERNAL_WAKEUP == 1 and BLE_APP_PRESENT == 0 This is done inside the following file \platform\arch\main\arch_main.c in the function arch_goto_sleep() as shown below. static inline void arch_goto_sleep (sleep_mode_t current_sleep_mode) { #if (USE_RANGE_EXT) // Disable range extender range_ext.disable(NULL); #endif

sleep_mode_t sleep_mode = current_sleep_mode;

ble_turn_radio_off ( ); //turn the radio off and check if we can go into deep sleep sleep_mode = ble_validate_sleep_mode(sleep_mode);

// grant access to the application to check if we can go to sleep app_sleep_prepare_proc(&sleep_mode); //SDK Improvements for uniformity this one should be changed?

//turn the peripherals off according to the current sleep mode arch_turn_peripherals_off(sleep_mode);

// hook for app specific tasks just before sleeping app_sleep_entry_proc(sleep_mode);

#if ((EXTERNAL_WAKEUP) && (!BLE_APP_PRESENT)) // external wake up, only in external processor designs ext_wakeup_enable(EXTERNAL_WAKEUP_GPIO_PORT, EXTERNAL_WAKEUP_GPIO_PIN, EXTERNAL_WAKEUP_GPIO_POLARITY); #endif

// do the last house keeping of the clocks and go to sleep arch_switch_clock_goto_sleep (sleep_mode); } The above gives default GPIO wake-up configurations for either UART CTS or SPI_EN signals, depending on the communication transport layer used. One could modify the parameters of the ext_wakeup_enable function as desired and set any GPIO port and pin as the wake-up signal, irrespectively of the interface in use.

11.4.2 DA14585/586 to external processor wake-up process software An example implementation exists in the throughput evaluation project. One could edit the following definitions to change the GPIO used as the wake-up signal. #define EXT_WAKEUP_PORT GPIO_PORT_0 #define EXT_WAKEUP_PIN GPIO_PIN_7

User Manual Revision 5.0 14-May-2018

CFR0012 140 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

These definitions can be found in the following file: projects\target_apps\hci\hci\src\config\user_periph_setup.h The activation of the wake-up process is enabled by defining the CFG_EXT_PROCESSOR_WKUP in the da1458x_config_advanced.h configuration file.

11.4.3 DA14585/586 wake-up timing The wake-up delay of the DA14585/586 is 4.5 ms to 5 ms. This delay is the same, irrespectively of the transport layer or the wake-up signal being used.

Figure 90: DA14585/586 wake up timing

Figure 90 shows the wake-up timing. From the start of the wake-up signal toggle (GPIO, UART CTS or SPI_EN signal) until the DA14585/586 is ready to receive messages, indicated by the flow control process, 4.5 ms to 5 ms are needed.

User Manual Revision 5.0 14-May-2018

CFR0012 141 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Appendix A Writing HEX file into OTP memory The SmartSnippets OTP Programmer tool enables downloading the default firmware into the System RAM and writing a user-defined HEX or BIN file into the OTP memory. The tool can be used for: writing a secondary bootloader in the OTP memory of a DA14585/586. Figure 91 shows the main screen of the OTP Programmer.

Figure 91: OTP Programmer

The following steps are required for writing the executable secondary_bootloader.hex into OTP memory using SmartSnippets Toolbox v4.8.3 in UART mode: 1. Open SmartSnippets and select the chip version. 2. Open the “Board Setup” tool and select the appropriate UART configuration. 3. Open the “OTP Programmer” tool. 4. Write the secondary_bootloader.hex into the OTP memory at offset 0. Enable Application Flag 1 and Application Flag 2, set DMA Length (Length = size / 4) and write the OTP header.

Note 34 For DA14585/586 Basic Kit if the “UART only” option is checked in the Port selection dialog of SmartSnippets Toolbox v4.8.3 the following behavior is observed when using OTP programmer tool: Firmware download succeeds but OTP Header reading fails (OTP Header reading is performed automatically after FW download). To avoid this unwanted behavior please check the JTAG option in the Port selection dialog as shown below:

User Manual Revision 5.0 14-May-2018

CFR0012 142 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

User Manual Revision 5.0 14-May-2018

CFR0012 143 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Revision History

Revision Date Description 1.0 23-Dec-2016 Initial version. Applies to SDK 6.0.1 for DA14585/586. 2.0 24-Mar-2017 Update for the DA14585/586 SDK Release 6.0.2 3.0 15-Jun-2017 Update for the DA14585/586 SDK Release 6.0.4 4.0 09-Nov-2017 Update for the DA14585/586 SDK Release 6.0.6 5.0 14-May-2018 Update for the DA14585/586 SDK Release 6.0.8 Change details: ● Section 8.2.5.2: Events Processing and Callbacks Section has been updated to include changes in the new version. ● Section 8.3.5.2: Events Processing and Callbacks Section has been updated to include changes in the new version. ● Section 8.5.5.1: Initialization Section has been updated to include changes in the new version. ● Section 8.5.5.2: Events Processing and Callbacks Section has been updated to include changes in the new version. ● Section 8.6.5.2: Events Processing and Callbacks Section has been updated to include changes in the new version. ● Section 8.8.5.2: Events Processing and Callbacks Section has been updated to include changes in the new version. ● Section 10.2: Going Through the Code New section ● Section 10.3: Advertising, connecting, configuring New section ● Section 10.4: ANCS notification handling New section ● Section 10.5: GATT service change notifications handling New section ● Section 10.6: Verbose logging New section ● Section 10.7: Trigger negative action New section

User Manual Revision 5.0 14-May-2018

CFR0012 144 of 145 © 2018 Dialog Semiconductor

UM-B-080 DA14585/586 SDK 6 Software Developer’s Guide

Status Definitions

Status Definition

DRAFT The content of this document is under review and subject to formal approval, which may result in modifications or additions.

APPROVED The content of this document has been approved for publication. or unmarked

Disclaimer Information in this document is believed to be accurate and reliable. However, Dialog Semiconductor does not give any representations or warranties, expressed or implied, as to the accuracy or completeness of such information. Dialog Semiconductor furthermore takes no responsibility whatsoever for the content in this document if provided by any information source outside of Dialog Semiconductor. Dialog Semiconductor reserves the right to change without notice the information published in this document, including without limitation the specification and the design of the related semiconductor products, software and applications. Applications, software, and semiconductor products described in this document are for illustrative purposes only. Dialog Semiconductor makes no representation or warranty that such applications, software and semiconductor products will be suitable for the specified use without further testing or modification. Unless otherwise agreed in writing, such testing or modification is the sole responsibility of the customer and Dialog Semiconductor excludes all liability in this respect. Customer notes that nothing in this document may be construed as a license for customer to use the Dialog Semiconductor products, software and applications referred to in this document. Such license must be separately sought by customer with Dialog Semiconductor. All use of Dialog Semiconductor products, software and applications referred to in this document are subject to Dialog Semiconductor’s Standard Terms and Conditions of Sale, available on the company website (www.dialog-semiconductor.com) unless otherwise stated. Dialog and the Dialog logo are trademarks of Dialog Semiconductor plc or its subsidiaries. All other product or service names are the property of their respective owners. © 2018 Dialog Semiconductor. All rights reserved.

Contacting Dialog Semiconductor

United Kingdom (Headquarters) North America Singapore China (Shenzhen) Dialog Semiconductor (UK) LTD Dialog Semiconductor Inc. Dialog Semiconductor Singapore Dialog Semiconductor China Phone: +44 1793 757700 Phone: +1 408 845 8500 Phone: +65 64 8499 29 Phone: +86 755 2981 3669 Germany Japan Hong Kong China (Shanghai) Dialog Semiconductor GmbH Dialog Semiconductor K. K. Dialog Semiconductor Hong Kong Dialog Semiconductor China Phone: +49 7021 805-0 Phone: +81 3 5425 4567 Phone: +852 3769 5200 Phone: +86 21 5424 9058 The Netherlands Taiwan Korea Dialog Semiconductor B.V. Dialog Semiconductor Taiwan Dialog Semiconductor Korea Phone: +31 73 640 8822 Phone: +886 281 786 222 Phone: +82 2 3469 8200 Email: Web site: [email protected] www.dialog-semiconductor.com User Manual Revision 5.0 14-May-2018

CFR0012 145 of 145 © 2018 Dialog Semiconductor