Wurth Elektronik ANR005 Proteus-II Instruction Manual

ANR005 PROTEUS-II
ADVANCED DEVELOPER GUIDE
VERSION 1.1
JUNE 18, 2019

The content of this document is property of Würth Elektronik eiSos and con-
tains confidential information. It is not intended to be distributed to any third
party without the written consent of Würth Elektronik eiSos.

Revision history
Manual
version
FW
version
HW
version Notes Date
1.0 1.0.0 2.1
• Initial version
• New corporate design and structure
• Updated chapter for custom firmware
development
November
2018
1.1 1.0.0 2.1
• Updated file name to new AppNote name
structure. Updated important notes, legal
notice & license terms chapters. June 2019
ANR005 Proteus-II version 1.1 © June 2019
www.we-online.com/wireless-connectivity 1

Abbreviations and abstract
Abbreviation Name Description
BTMAC Bluetooth conform MAC address of the module used
on the RF-interface.
CS Checksum Byte wise XOR combination of the preceding fields.
BLE Bluetooth Low
Energy According to Bluetooth specification.
BT Bluetooth According to Bluetooth specification.
DTM Direct test mode Mode to test Bluetooth specific RF settings.
GAP Generic Access
Profile
The GAP provides a basic level of functionality that all
Bluetooth devices must implement.
I/O Input/output Pinout description.
LPM Low power mode Mode for efficient power consumption.
MAC MAC address of the module.
MTU Maximum
transmission unit Maximum packet size of the Bluetooth connection.
Payload The intended message in a frame / package.
RF Radio frequency Describes wireless transmission.
RSSI Receive Signal
Strength Indicator
The RSSI indicates the strength of the RF signal. Its
value is always printed in two’s complement notation.
Soft device Operating system used by the nRF52 chip.
UART
Universal
Asynchronous
Receiver
Transmitter
Allows the serial communication with the module.
[HEX] 0xhh Hexadecimal
All numbers beginning with 0x are hexadecimal
numbers. All other numbers are decimal, unless
stated otherwise.
ANR005 Proteus-II version 1.1 © June 2019
www.we-online.com/wireless-connectivity 2

Contents
1 Introduction 5
2 Prerequisites 5
3 Bluetooth profiles 5
4 AMBER SPP-like profile 6
4.1 Generic Access Protocol (GAP) . . . . . . . . . . . . . . . . . . . . . . . . . 6
4.2 Generic Attribute Profile (GATT) . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.2.1 Data length extension . . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.2.2 Companyidentifier ........................... 7
4.2.3 UUID................................... 7
4.2.4 PrimaryService............................. 8
4.2.4.1 Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4.3 BLEpacketcontent................................ 8
4.3.1 RF-Packetformat ............................ 8
4.3.2 Advertising packet content . . . . . . . . . . . . . . . . . . . . . . . 9
4.3.3 Scan response packet content . . . . . . . . . . . . . . . . . . . . . 9
5 App development 10
5.1 Connection setup message charts . . . . . . . . . . . . . . . . . . . . . . . 10
5.1.1 No security and authentication . . . . . . . . . . . . . . . . . . . . . 10
5.1.2 Justworkspairing............................ 10
5.1.3 Static pass key pairing . . . . . . . . . . . . . . . . . . . . . . . . . 11
5.2 Bonding development hints . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
5.3 Nordic BLE UART example app as base . . . . . . . . . . . . . . . . . . . . 13
6 Custom firmware development 15
6.1 Custom firmware services of Würth Elektronik eiSos . . . . . . . . . . . . . 16
6.2 Important information for custom firmware development . . . . . . . . . . . 16
6.2.1 How to adapt Nordic Semiconductor SDK examples to run on the
Proteus-IIhardware?.......................... 19
6.2.2 Firmware development hints . . . . . . . . . . . . . . . . . . . . . . 21
7 Important notes 23
7.1 General customer responsibility . . . . . . . . . . . . . . . . . . . . . . . . . 23
7.2 Customer responsibility related to specific, in particular safety-relevant ap-
plications ..................................... 23
7.3 Best care and attention . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
7.4 Customer support for product specifications . . . . . . . . . . . . . . . . . . 23
7.5 Productimprovements.............................. 24
7.6 Productlifecycle ................................. 24
7.7 Propertyrights .................................. 24
7.8 General terms and conditions . . . . . . . . . . . . . . . . . . . . . . . . . . 24
8 Legal notice 25
8.1 Exclusionofliability................................ 25
8.2 Suitability in customer applications . . . . . . . . . . . . . . . . . . . . . . . 25
ANR005 Proteus-II version 1.1 © June 2019
www.we-online.com/wireless-connectivity 3

8.3 Trademarks .................................... 25
8.4 Usagerestriction ................................. 25
9 License terms 27
9.1 Limitedlicense .................................. 27
9.2 Usageandobligations .............................. 27
9.3 Ownership..................................... 28
9.4 Firmwareupdate(s)................................ 28
9.5 Disclaimerofwarranty .............................. 28
9.6 Limitationofliability................................ 29
9.7 Applicable law and jurisdiction . . . . . . . . . . . . . . . . . . . . . . . . . . 29
9.8 Severabilityclause ................................ 29
9.9 Miscellaneous................................... 29
ANR005 Proteus-II version 1.1 © June 2019
www.we-online.com/wireless-connectivity 4

1 Introduction
This document provides all the information necessary to integrate the Proteus-II BLE module
into user application. The standard features available with the default firmware are described
in detail. Further, key parameters of the BLE specifications necessary to ensure interoper-
ability with Bluetooth compliant third party devices are listed and described in detail.
Besides of this, valuable hints to start an app development as well as to start a custom
firmware development on base of the Proteus-II hardware are given in the subsequent chap-
ters.
2 Prerequisites
A basic understanding of the Bluetooth Low Energy standard as well as application devel-
opment background on the desired platform is necessary to fully understand this document.
The manual of Proteus-II contains basic information of the standard firmware and the soft-
ware interfaces provided by the application. Please read this manual carefully and complete-
ly before using its information.
Würth Elektronik eiSos does not provide general support towards the Bluetooth standard or
smart device app development (independent of the platform).
3 Bluetooth profiles
Bluetooth specification uses so called "Profiles" to specify the general behavior of a Blue-
tooth enabled device to communicate with other Bluetooth devices. Profiles are built on the
Bluetooth standard to clearly define what kind of data is transmitted. The device’s application
determines which profiles it must support, from hands-free capabilities to heart rate sensors
to alerts and more.
A device may support more than one profile. For two devices to be compatible, they must
support the same BLE profile.
The Proteus-II module ships with the so called AMBER SPP-like (Serial Port Profile) profile
created based on the Generic Attribute profile (GATT). This profile aims at providing a BLE
based wireless replacement to a serial cable connection.
ANR005 Proteus-II version 1.1 © June 2019
www.we-online.com/wireless-connectivity 5

4 AMBER SPP-like profile
This section contains the key data of the AMBER SPP-like profile. Each device in the net-
work must support this profile to communicate with an Proteus-II device with the default
SPP-like firmware. Customer applications may support and/or provide other profiles, ser-
vices or interfaces.
4.1 Generic Access Protocol (GAP)
The main purpose of this protocol is to describe the parameters of lower layers of the Blue-
tooth stack including discovery, scanning and security capabilities. The Proteus-II GAP spec-
ifications are listed below:
• Appearance as specified in the user setting RF_Appearance .
• Device name as specified in the user setting RF_DeviceName .
• Device address (6 Byte MAC) of type "public", see user setting FS_BTMAC (0x0018DAxxxxxx)
• Timings:
–See user settings RF_ScanTiming and RF_ScanFlags for scan and advertising re-
lated timing parameters like
*Advertising interval
*Scan window
*Scan interval
*Connection setup timeout
–See user setting RF_ConnectionTiming for connection related timing parameters
like
*Minimum connection interval
*Maximum connection interval
*Connection supervision timeout
–See user setting RF_TXPower for TX power value.
–See user setting RF_SecFlags for security settings.
–Slave latency: 0
–Peripheral requests for connection parameters update if central has differing con-
nection parameters
*Connection parameters update (initial): 5s
*Connection parameters update (periodic): 10s
*Connection parameters update counter before connection shut down: 3
ANR005 Proteus-II version 1.1 © June 2019
www.we-online.com/wireless-connectivity 6

4.2 Generic Attribute Profile (GATT)
The directions RX and TX in this document are described from the perspective
of a central role, see description below.
4.2.1 Data length extension
The Proteus-II supports up to 243 Byte of payload data. To use this feature the data length
extension has to be requested by the central device. In this case, the GATT MTU size must
be 243 Byte payload + 1 Byte AMBER header + 3 Byte NUS header, which is 247 Byte in
total.
The PDU size should be 243 Byte payload + 1 Byte AMBER header + 3 Byte NUS header +
4 Byte BLE header, which is 251 Byte in total.
Check also the message charts in chapter 5 to see the MTU request in the connection setup
process.
4.2.2 Company identifier
The Bluetooth listed company identifier of Würth Elektronik eiSos (formerly Amber wireless
GmbH) is 0x031A (794dec).
4.2.3 UUID
The Proteus-II uses a 128Bit UUID of type "Vendor specific". The base UUID is adapted by
the 16Bit UUIDs of the primary service and the corresponding characteristics.
These UUIDs are only allowed to be used when one of the two corresponding devices is a
Proteus-II BLE module or contains a Proteus-II BLE module of Würth Elektronik eiSos which
have installed AMBER SPP-like firmware.
Service 16Bit UUID Full UUID
Proteus-II base 6E400000-C352-11E5-953D-0002A5D5C51B
Proteus-II primary service 0x0001 6E400001-C352-11E5-953D-0002A5D5C51B
TX_CHARACTERISTIC 0x0002 6E400002-C352-11E5-953D-0002A5D5C51B
RX_CHARACTERISTIC 0x0003 6E400003-C352-11E5-953D-0002A5D5C51B
By means of the user setting RF_SPPBaseUUID the base UUID can be adapted
to generate a custom profile.
ANR005 Proteus-II version 1.1 © June 2019
www.we-online.com/wireless-connectivity 7

4.2.4 Primary Service
4.2.4.1 Characteristics
• The first characteristic of the Proteus-II primary service is TX_CHARACTERISTIC :
–The data is sent from central/client to peripheral/server using a write command.
–Server:
*Has to allow a write command as well as a write without response command.
–Client:
*Use write command to send data to the server.
• The second characteristic of the Proteus-II primary service is RX_CHARACTERISTIC :
–The data is sent from peripheral/server to central/client using a notification.
–Server:
*Has to allow/enable notifications. Notify client/central when sending data.
*When the notification enable bit is written in the
CCCD (Client Characteristic
Configuration Descriptor) by the central, the peripheral prints a CMD_CHANNELOPEN_RSP
on the UART to signalize that the peripheral can send data to the central now.
The central can only write this bit, when the configured security level of the
peripheral has been met.
–Client:
*Has to enable notifications.
The permissions to access the characteristics is determined by the security mode of the
module.
Proteus-II
security mode CCCD read CCCD write, RX attribute read/write, TX attribute read/write
No security no protection, open
link no protection, open link
Just works no protection, open
link
require encryption, but no MITM protection
(Mode 1, Level 2)
Static pass key no protection, open
link
require encryption and MITM protection
(Mode 1, Level 3)
4.3 BLE packet content
4.3.1 RF-Packet format
To identify the type of data transmitted via BLE, we introduced a 1 Byte packet header.
Thus, the standard BLE payload has to match the following format to be understood by the
Proteus-II:
ANR005 Proteus-II version 1.1 © June 2019
www.we-online.com/wireless-connectivity 8