AN982: ® LOW ENERGY SOFTWARE GLUCOSE SENSOR APPLICATION NOTE

Wednesday, 02 December 2020

Version 1.2

VERSION HISTORY

Version Comment

1.0 First version

1.1 Minor updates

Renamed "Bluetooth Smart" to "" according to the 1.2 official Bluetooth SIG nomenclature

Silicon Labs

TABLE OF CONTENTS 1 Introduction ...... 4 2 What is Bluetooth Low Energy Technology? ...... 5 3 Introduction to the Bluegiga Bluetooth Low Energy Software ...... 6 3.1 The Bluetooth Low Energy Stack ...... 6 3.2 The Bluetooth Low Energy SDK ...... 6 3.3 The BGAPI Protocol ...... 8 3.4 The BGLib Host Library ...... 9 3.5 BGScriptTM Scripting Language ...... 10 3.6 The Profile Toolkit ...... 11 4 Glucose profile ...... 12 4.1 Description ...... 12 4.2 GATT Server: Service requirements ...... 13 4.3 GATT Server: Attribute requirements ...... 13 4.4 Recommended connection establishment procedures ...... 14 4.5 Security requirements ...... 14 5 Implementing a Glucose Sensor ...... 15 5.1 Creating a project (project.xml) ...... 16 5.2 Hardware configuration (hardware.xml) ...... 17 5.3 GATT database for Glucose Sensor (gatt.xml) ...... 18 5.4 Application Configuration (config.xml) ...... 22 5.5 BGScript for Glucose Sensor (glucose_sensor.bgs) ...... 23 5.6 Compiling and Installing the Firmware ...... 28 5.7 Testing the Glucose Sensor ...... 32 5.8 Testing with BLEGUI software ...... 32 5.9 Testing with iPhone or iPad ...... 38 6 External resources ...... 42

Silicon Labs

1 Introduction

This application note discusses how to build a Bluetooth 4.0 glucose profile sensor using Bluegiga’s Bluetooth 4.0 software development kit, for use with a DKBLE112 hardware evaluation board and an Apple iPhone or iPad, or other Bluetooth Low Energy device capable of acting as a glucose collector. The application note contains a practical example of how to build a GATT-based Glucose Profile and how to make a basic glucose sensor device using BGScript scripting language, including authenticated bonding (encryption) and on-module glucose record storage and retrieval. Various other features of the development kit are also demonstrated in this project for the sake of instruction, such as SPI communication to the on-board LCD, potentiometer ADC readings to simulate glucose levels, and UART debug data output. Note that the glucose profile as implemented is an official profile standardized by the Bluetooth SIG.

Silicon Labs Page 4 of 43

2 What is Bluetooth Low Energy Technology?

Bluetooth Low Energy (Bluetooth 4.0) is a new, open standard developed by the Bluetooth SIG. It’s targeted to address the needs of new modern wireless applications such as ultra-low power consumption, fast connection times, reliability and security. Bluetooth Low Energy consumes 10-20 times less power and is able to transmit data 50 times quicker than classical Bluetooth solutions. Link: How Bluetooth low energy technology works? Bluetooth Low Energy is designed for new emerging applications and markets, but it still embraces the very same benefits we already know from the classical, well established Bluetooth technology: • Robustness and reliability - The adaptive frequency hopping technology used by Bluetooth Low Energy allows the device to quickly hop within a wide frequency band, not just to reduce interference but also to identify crowded frequencies and avoid them. On addition to broadcasting Bluetooth Low Energy also provides a reliable, connection oriented way of transmitting data. • Security - Data privacy and integrity is always a concern is wireless, mission critical applications. Therefore Bluetooth Low Energy technology is designed to incorporate high level of security including authentication, authorization, encryption and man-in-the-middle protection. • Interoperability - Bluetooth Low Energy technology is an open standard maintained and developed by the Bluetooth SIG. Strong qualification and interoperability testing processes are included in the development of technology so that wireless device manufacturers can enjoy the benefit of many solution providers and consumers can feel confident that equipment will communicate with other devices regardless of manufacturer. • Global availability - Based on the open, license free 2.4GHz frequency band, Bluetooth Low Energy technology can be used in world wide applications. There are two types of Bluetooth 4.0 devices: • Bluetooth 4.0 single-mode devices that only support Bluetooth Low Energy and are optimized for low-power, low-cost and small size solutions. • Bluetooth 4.0 dual-mode devices that support Bluetooth Low Energy and classical Bluetooth technologies and are interoperable with all the previously Bluetooth specification versions. Key features of Bluetooth Low Energy wireless technology include: • Ultra-low peak, average and idle mode power consumption • Ability to run for years on standard, coin-cell batteries • Low cost • Multi-vendor interoperability • Enhanced range Bluetooth Low Energy is also meant for markets and applications, such as: • Automotive • Consumer electronics • Smart energy • Entertainment • Home • Security & proximity • Sports & fitness

Silicon Labs Page 5 of 43

3 Introduction to the Bluegiga Bluetooth Low Energy Software

The Bluegiga Bluetooth Low Energy Software enables developers to quickly and easily develop Bluetooth Low Energy applications without in-depth knowledge of the Bluetooth Low Energy technology. The Bluetooth Low Energy Software consist of two parts: • The Bluetooth Low Energy Stack • The Bluetooth Low Energy Software Development Kit (SDK) 3.1 The Bluetooth Low Energy Stack

The Bluetooth Low Energy stack is a fully Bluetooth 4.0 single mode compatible software stack implementing slave and master modes, all the protocol layers such as L2CAP, Attribute Protocol (ATT), Generic Attribute Profile (GATT), Generic Access Profile (GAP) and security and connection management. The Bluetooth Low Energy is meant for the Bluegiga Bluetooth Low Energy products such as BLE112, BLE113 and BLED112 and it runs on the embedded MCU used in these products so no host is needed.

3.2 The Bluetooth Low Energy SDK

The Bluetooth Low Energy SDK is a software development kit, which enables the device and software vendors to develop products on top of the Bluegiga’s Bluetooth Low Energy hardware and software. The Bluetooth Low Energy SDK supports multiple development models and the software developers can decide whether the application software runs on a separate host (a low power MCU) or whether they want to make fully standalone devices and execute their code on the MCU embedded in the Bluegiga Bluetooth Low Energy modules. The SDK also contains documentation, tools for compiling the firmware, installing it into the hardware and lot of example application speeding up the development process. fully standalone applications using a simple scripting language called BGScriptTM. Several profiles and examples are also offered as a part of the Bluetooth Low Energy Software in order to easily develop the Bluetooth Low Energy compatible end products. Bluegiga’s Bluetooth Low Energy Software provides a complete development framework for Bluetooth Low Energy application implementers.

Silicon Labs Page 6 of 43

Figure 1: Bluetooth Low Energy Software The Bluetooth Low Energy Software architecture is illustrated and it consists of the following components • The Bluetooth Low Energy stack implementing the Bluetooth Low Energy protocol • BGAPITM APIs that enable the software developers to interface to the Bluetooth Low Energy Stack • BGScriptTM Virtual Machine (VM) and scripting language which enable application code to be developed and executed directly on the Bluetooth Low Energy hardware • BGLibTM lightweight host library which implements the BGAPI binary protocol and parser and is target for applications where separate host processor is used to interface to the Bluetooth Low Energy modules over UART or USB. • Profile ToolkitTM is a GATT based profile development tool that enables software developers quickly and easily to describe the Bluetooth Low Energy profiles, services and characteristics using simple XML templates Each of these components are described in more detail in the following chapters.

Silicon Labs Page 7 of 43

3.3 The BGAPI Protocol

For applications where a separate host is used to implement the end user application, a transport protocol is needed between the host and the Bluetooth stack. The transport protocol is used to communicate with the Bluetooth stack as well to transmit and receive data packets. This protocol is called BGAPI and it's a lightweight binary based communication protocol designed specifically for ease of implementation within host devices with limited resources. The BGAPI protocol is a simple command, response and event based protocol and it can be used over UART SPI (at the moment not supported by the Bluetooth Low Energy hardware) or USB interfaces.

Figure 2: BGAPI protocol

The BGAPI provides access for example to the following layers in the Bluetooth Low Energy Stack: • Generic Access Profile - GAP allows the management of discoverability and connetability modes and open connections • Security manager - Provides access the Bluetooth Low Energy security functions • Attribute database - An class to access the local attribute database • Attribute client - Provides an interface to discover, read and write remote attributes • Connection - Provides an interface to manage Bluetooth Low Energy connections • Hardware - An interface to access the various hardware layers such as timers, ADC and other hardware interfaces • Persistent Store - User to access the parameters of the radio hardware and read/write data to non- volatile memory • System - Various system functions, such as querying the hardware status or reset it

Silicon Labs Page 8 of 43

3.4 The BGLib Host Library

For easy implementation of BGAPI protocol an ANSI C host library is available. The library is easily portable ANSI C code delivered within the Bluetooth Low Energy SDK. The purpose is to simplify the application development to various host environments.

Figure 3: BGLib host library

Silicon Labs Page 9 of 43

3.5 BGScriptTM Scripting Language

The Bluetooth Low Energy SDK Also allows the application developers to create fully standalone devices without a separate host MCU and run all the application code on the Bluegiga Bluetooth Low Energy Hardware. The Bluetooth Low Energy modules can run simple applications along the Bluetooth Low Energy stack and this provides a benefit when one needs to minimize the end product’s size, cost and current consumption. For developing standalone Bluetooth Low Energy applications the SDK includes the Script VM, compiler and other BGScript development tools. BGScript provides access to the same software and hardware interfaces as the BGAPI protocol and the BGScript code can be developed and compiled with free- of-charge tools provided by Bluegiga. Typical BGScript applications are only few tens to hundreds lines of code, so they are really quick and easy to develop and lots of readymade examples are provides with the SDK.

Figure 4: BGScript application model BGScript code example:

# System Started event system_boot(major, minor, patch, build, ll_version, protocol_version,hw) #Enable advertising mode call gap_set_mode(gap_general_discoverable,gap_undirected_connectable) #Enable bondable mode call sm_set_bondable_mode(1) #Start timer at 1 second interval (32768 = crystal frequency) call hardware_set_soft_timer(32768) end

Silicon Labs Page 10 of 43

3.6 The Profile Toolkit

The Bluetooth Low Energy profile toolkit a simple set of tools, which can used to describe GATT based Bluetooth Low Energy services and characteristics. The profile toolkit consists of a simple XML based description language and templates, which can be used to describe the devices GATT database. The profile toolkit also contains a compiler, which converts the XML to binary format and generates API to access the characteristic values.

Figure 5: A profile toolkit example of GAP service

Silicon Labs Page 11 of 43

4 Glucose profile 4.1 Description

The Glucose Profile enables a device to connect and interact with a glucose sensor for use in consumer and professional healthcare applications. The full Bluetooth SIG specification for the Glucose Profile is available in PDF form here: https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=248025 An organized table structure of the Glucose profile as defined by the Bluetooth SIG is available here: http://developer.bluetooth.org/gatt/profiles/Pages/ProfileViewer.aspx?u=org.bluetooth.profile.glucose.xml (Other links present in this document to services and characteristics also go to the Bluetooth SIG service browser online.) The Glucose Profile defines two roles: 1. Glucose Sensor The sensor is the devices which has the actual glucose measurement device and provides the GATT structure and data storage for use by a collector (see below). A glucose sensor must include at least a partial implementation of the Device Information service as well as the sensor portion of the Glucose service, as defined by the Bluetooth SIG. 2. Collector The collector is the device which gathers glucose data from the sensor. In this example, we will do partial testuse an iOS application provided by Nordic Semiconductor for a comprehensive GUI-based collector. This application note does not discuss the implementation of a collector itself. The figure below shows the relationship of these two roles. Glucose Sensor Collector Glucose Service

Generic Access Service Glucose Measurement Generic Access Service

Glucose Measurement Context

Glucose Feature Device Information Device Information Service Record Access Service Control Point

Figure 6: Glucose Profile roles

Silicon Labs Page 12 of 43

4.2 GATT Server: Service requirements

The table below describes the service requirements.

Service UUID Glucose Sensor

GAP service 1800 Mandatory

Glucose service 1808 Mandatory

Device Information service 180A Mandatory

Table 1: Service requirements

4.3 GATT Server: Attribute requirements

The table below describes the structure and requirements for the attribute used in the Glucose Service. (Links go to the Bluetooth SIG online characteristic definition browser for that attribute)

Characteristic UUID Length Type Support Security Properties

Variable Glucose Measurement 2A18 Hex Mandatory None Notify (max 17B)

Variable Glucose Measurement Context 2A34 Hex Optional None Notify (max 17B)

Glucose Feature 2A51 2 bytes Hex Mandatory None Read

Variable Writeable with Record Access Control Point 2A52 Hex Mandatory Write, Indicate (typical 2B) Authentication

Table 2: Glucose Service structure (sensor only) • Each UUID in this service is an official, adopted 16-bit ID for the characteristic • The Glucose Measurement and Context length is variable depending on the features supported by the sensor. This demo emulates all specified features (though most data is arbitrarily chosen only for demo purposes). and has a length of 17 bytes. This fits within the maximum payload size for indicated values (20 bytes). • Security is not necessary to connect to a glucose sensor in order to read a single measurement taken during connection, but it is required to access historical records which may be stored on the device. These records are only accessible through the Record Access Control Point. In order to write control commands to this attribute, the collector must bond (a.k.a. pair) with the sensor. A collector which connects but does not pair will not be allowed to write any values to the control point, and therefore will not be able to access any stored records. • Glucose Measurement and the optional Glucose Measurement Context cannot be directly read, but may only be pushed (via notifications) from the sensor to the collector, after the collector enables client notifications for those services. Glucose Feature contains a constant value describing the feature set of the sensor device, and may be read as desired by the collector.

Silicon Labs Page 13 of 43

4.4 Recommended connection establishment procedures

4.4.1 Un-bonded devices

Advertisement duration Parameter Value

First 30 seconds (fast connection) Advertising interval 20ms to 30ms

After 30 seconds (reduced power) Advertising interval 1000ms to 2500ms

Table 3: Advertising parameters for un-bonded Glucose Sensor • The Glucose Sensor should use the GAP Limited Discoverable Mode with connectable undirected advertising events when establishing an initial connection. (For simplicity, this demo implementation uses GAP General Discoverable Mode.) • If the connection is not established within a time limit, the sensor may exit GAP Connectable mode. (For simplicity, this demo implementation does not ever exit GAP Connectable mode.)

4.4.2 Bonded devices

The following produce is uses for bonded devices: • A Glucose Sensor shall enter the GAP Undirected Connectable Mode either when commanded by the user to initiate a connection to a Collector or when a Glucose Sensor has one or more stored records to send to a previously connected Collector. • The Glucose Sensor should write the address of the target Collector in its White List and set its controller advertising filter policy to ‘process scan and connection requests only from devices in the White List’. The advertisement parameters should be as in Table 3. • If the connection is not established within a time limit, the sensor may exit GAP Connectable mode.

4.4.3 Link loss procedure

When connection is terminated due to link loss the sensor should attempt reconnection with the Collector by entering the GAP connectable mode using the recommended parameters from Table 3.

4.5 Security requirements

The Glucose Sensor shall bond with the Collector. When bonding is used: 1. All supported characteristics specified by the Glucose Service shall be set to Security Mode 1 and either Security Level 2 or 3. 2. The Glucose Sensor shall use the SM Slave Security Request procedure to inform the Collector of its security requirements. 3. All characteristics specified by the Device Information Service that are relevant to this profile should be set to the same security mode and level as the characteristics in the Glucose Service.

Silicon Labs Page 14 of 43

5 Implementing a Glucose Sensor

The chapter contains step by step instructions how to implement a stand-alone Glucose Sensor with Bluegiga’s Bluetooth 4.0 Software Development Kit. The chapter is split into following steps: 1. Creating a project 2. Defining hardware configuration 3. Building Glucose and Device Information Services with Profile Toolkit 4. Writing BGScript source code 5. Compiling the GATT database and BGScript into binary firmware 6. Installing the firmware into BLE112 or DKBLE112 hardware The actual project comes as an example with the Bluegiga’s Bluetooth Low Energy Software Development Kit v.1.1.1 or newer under the \example\glucose_sensor\ directory.

Silicon Labs Page 15 of 43

5.1 Creating a project (project.xml)

The Glucose Sensor implementation is started by first creating a project file (project.xml), which defines the resources use by the project and the firmware output file. This project file includes a description of each of the main elements of the project.