Develop your own Bluetooth Low Energy Applications by Elektor

books books

books

for Raspberry Pi, ESP32 and nRF52 with Python, Arduino and Zephyr Bluetooth Low Energy (BLE) radio chips are ubiquitous from Raspberry Pi to lightbulbs. BLE is an elaborate technology with a comprehensive specification, but the basics are quite accessible. A progressive and systematic approach will lead you far in mastering this wireless communication technique, which is essential for working in low power scenarios. In this book, you’ll learn how to: > Discover BLE devices in the neighborhood by listening to their advertisements. > Create your own BLE devices advertising data. > Connect to BLE devices such as heart rate monitors and proximity reporters. > Create secure connections to BLE devices with encryption and authentication. > Understand BLE service and profile specifications and implement them. > Reverse engineer a BLE device with a proprietary implementation and control it with your own software. > Make your BLE devices use as little power as possible.

Koen Vervloesem has been writing for over 20 years on Linux, open-source software, security, home automation, AI, programming, and the Internet of Things. He holds a Master’s degree in Computer Science Engineering, a Master’s degree in Philosophy, and an LPIC-3 303 Security certificate. He is a board member of the Belgian privacy activist organisation the Ministry of Privacy.

This book shows you the ropes of BLE programming with Python and the Bleak library on a Raspberry Pi or PC, with C++ and NimBLE-Arduino on Espressif’s ESP32 development boards, and with C on one of the development boards supported by the Zephyr real-time operating system, such as Nordic Semiconductor's nRF52 boards. Starting with a very little amount of theory, you’ll develop code right from the beginning. After you’ve completed this book, you’ll know enough to create your own BLE applications. Elektor International Media BV www.elektor.com

Develop your own Bluetooth Low Energy Applications • Koen Vervloesem

Develop your own Bluetooth Low Energy Applications

BLE

Develop your own Bluetooth Low Energy Applications for Raspberry Pi, ESP32 and nRF52 with Python, Arduino and Zephyr

Koen Vervloesem

Develop your own

Bluetooth Low Energy Applications for Raspberry Pi, ESP32 and nRF52 with Python, Arduino and Zephyr

● Koen Vervloesem

Boek BLE 220329 UK.indd 3

06/05/2022 15:54

Bluetooth Low Energy Applications

● This is an Elektor Publication. Elektor is the media brand of Elektor International Media B.V.

PO Box 11, NL-6114-ZG Susteren, The Netherlands Phone: +31 46 4389444

storing in any medium by electronic means and whether or not transiently or incidentally to some other use of this publication, without the written permission of the copyright holder except in accordance with the provisions of the Copyright Designs and Patents Act 1988 or under the terms of a licence issued by the Copyright Licencing Agency Ltd., 90 Tottenham Court Road, London, England W1P 9HE. Applications for the copyright holder's permission to reproduce any part of the publication should be addressed to the publishers.

● Declaration

The Author and Publisher have used their best efforts in ensuring the correctness of the information contained in this book. They do not assume, and hereby disclaim, any liability to any party for any loss or damage caused by errors or omissions in this book, whether such errors or omissions result from negligence, accident, or any other cause.

● British Library Cataloguing in Publication Data

A catalogue record for this book is available from the British Library

● ISBN 978-3-89576-500-1 ISBN 978-3-89576-501-8

eBook

Printed in the Netherlands by Ipskamp Printing, Enschede

Elektor is part of EIM, the world's leading source of essential technical information and electronics products for pro engineers, electronics designers, and the companies seeking to engage them. Each day, our international team develops and delivers high-quality content - via a variety of media channels (including magazines, video, digital media, and social media) in several languages - relating to electronics design and DIY electronics. www.elektormagazine.com

●4

Boek BLE 220329 UK.indd 4

06/05/2022 15:54

Content Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Chapter 1 • Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 1.1 What is Bluetooth Low Energy? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 1.2 Layered architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 1.3 How to communicate with BLE devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 1.3.1 Without a connection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 1.3.2 With a connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 1.4 Advantages of BLE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 1.4.1 Low power consumption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 1.4.2 Ubiquitous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 1.4.3 Low cost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 1.5 Disadvantages of BLE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 1.5.1 Short range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 1.5.2 Limited speed. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 1.5.3 You need a gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 1.6 Platforms used in this book. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 1.6.1 Python/Bleak (Raspberry Pi, PC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 1.6.2 C++/NimBLE-Arduino (ESP32) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 1.6.3 C/Zephyr (nRF52) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 1.7 How to use this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 1.8 Summary and further exploration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Chapter 2 • Preparing your development environment . . . . . . . . . . . . . . . . . . . . . . 24 2.1 Python and Bleak on your PC or Raspberry Pi . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 2.2 The Arduino platform with NimBLE-Arduino for the ESP32 . . . . . . . . . . . . . . . . . . 25 2.2.1 Install Arduino CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 2.2.2 Install the ESP32 Arduino core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 2.2.3 Detect your ESP32 board . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 2.2.4 Install the NimBLE-Arduino library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 2.3 The Zephyr development environment for nRF5 devices . . . . . . . . . . . . . . . . . . . . 30 2.3.1 Build a Zephyr application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 2.3.2 Flash a Zephyr application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

●5

Boek BLE 220329 UK.indd 5

06/05/2022 15:54

Bluetooth Low Energy Applications 2.4 The nRF Connect for Desktop application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 2.5 The nRF Connect mobile app. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 2.6 The Bluetooth Low Energy app in nRF Connect for Desktop . . . . . . . . . . . . . . . . . 34 2.7 Wireshark and a BLE sniffer dongle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 2.7.1 Downloading Wireshark and the nRF Sniffer for Bluetooth LE . . . . . . . . . . . . 36 2.7.2 Installing the nRF Sniffer for Bluetooth LE firmware . . . . . . . . . . . . . . . . . . 36 2.7.3 Installing the nRF Sniffer capture tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 2.7.4 Installing the BLE profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 2.7.5 Testing a BLE packet capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 2.8 Summary and further exploration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Chapter 3 • Broadcasting data with advertisements . . . . . . . . . . . . . . . . . . . . . . . . 43 3.1 Device roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 3.2 Advertising packets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 3.2.1 Advertising channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 3.2.2 Advertising packet structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 3.3 Discovering advertisements with Bleak. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 3.3.1 Scanning for devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 3.3.2 Detection callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 3.3.3 Active and passive scanning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 3.4 Public and random Bluetooth addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 3.5 The iBeacon specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 3.6 Decoding iBeacon advertisements using Bleak . . . . . . . . . . . . . . . . . . . . . . . . . . 58 3.7 Discovering advertisements with NimBLE-Arduino . . . . . . . . . . . . . . . . . . . . . . . . 61 3.8 Decoding manufacturer-specific data using NimBLE-Arduino . . . . . . . . . . . . . . . . . 66 3.8.1 Decoding iBeacon advertisements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 3.8.2 Decoding Microsoft advertising beacons. . . . . . . . . . . . . . . . . . . . . . . . . . . 69 3.9 Broadcasting iBeacon advertisements with Zephyr. . . . . . . . . . . . . . . . . . . . . . . . 73 3.9.1 Advertising data structures in Zephyr . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 3.9.2 Enabling Bluetooth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 3.9.3 Advertising. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 3.9.4 Building and flashing the code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

●6

Boek BLE 220329 UK.indd 6

06/05/2022 15:54

3.9.5 Investigating the advertised packets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 3.10 Broadcasting sensor data as manufacturer-specific data with Zephyr . . . . . . . . . . 82 3.10.1 Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 3.10.2 Project structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 3.10.3 Source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 3.10.4 Decoding the BME280 sensor data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 3.11 Advertise scan response data with Zephyr . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 3.12 Summary and further exploration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Chapter 4 • Connections and services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 4.1 Device roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 4.2 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 4.3 Services, characteristics, and descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 4.3.1 Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 4.3.2 Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 4.3.3 Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 4.4 Discovering services and characteristics with nRF Connect . . . . . . . . . . . . . . . . . 101 4.5 A minimal GATT server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 4.6 Discovering services and characteristics with Bleak . . . . . . . . . . . . . . . . . . . . . . 105 4.7 Reading and writing characteristics using Bleak. . . . . . . . . . . . . . . . . . . . . . . . . 108 4.7.1 Reading characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 4.7.2 Reading characteristics by their handle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 4.7.3 Writing characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 4.8 Notifications and indications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 4.8.1 Read heart rate notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 4.8.2 Read notifications from multiple devices . . . . . . . . . . . . . . . . . . . . . . . . . 119 4.9 Creating a heart rate monitor with NimBLE-Arduino. . . . . . . . . . . . . . . . . . . . . . 124 4.10 Creating a GATT server with Zephyr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 4.10.1 Exposing the Device Information service . . . . . . . . . . . . . . . . . . . . . . . . 131 4.10.2 Creating a BLE sensor with Zephyr . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 4.10.3 Reading the sensor characteristic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 4.10.4 Sniffing packets in an unencrypted BLE connection . . . . . . . . . . . . . . . . . 148

●7

Boek BLE 220329 UK.indd 7

06/05/2022 15:54

Bluetooth Low Energy Applications 4.11 Receiving service data without a connection . . . . . . . . . . . . . . . . . . . . . . . . . . 149 4.11.1 Scanning for service data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 4.11.2 Receiving Exposure Notification advertisements . . . . . . . . . . . . . . . . . . . 151 4.12 Summary and further exploration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 Chapter 5 • Securing BLE connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 5.1 BLE security architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 5.2 Pairing and bonding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 5.2.1 Phase 1: Exchange of pairing information . . . . . . . . . . . . . . . . . . . . . . . . 158 5.2.2 Phase 2: Pairing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 5.2.2.1 LE Legacy Connection pairing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 5.2.2.2 LE Secure Connection pairing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 5.2.3 Phase 3: Bonding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 5.3 Security modes and levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 5.4 Encrypting the BLE connection to a Zephyr sensor. . . . . . . . . . . . . . . . . . . . . . . 165 5.4.1 Implementing Security Mode 1 Level 2 . . . . . . . . . . . . . . . . . . . . . . . . . . 166 5.4.2 Securely connecting to your sensor board . . . . . . . . . . . . . . . . . . . . . . . . 173 5.4.3 Sniffing the pairing procedure with Wireshark . . . . . . . . . . . . . . . . . . . . . 175 5.5 Authenticating a BLE connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 5.5.1 Implementing Secure Connections Only Mode . . . . . . . . . . . . . . . . . . . . . 177 5.5.2 Securely connecting with the board. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 5.5.3 Sniffing the pairing procedure with Wireshark . . . . . . . . . . . . . . . . . . . . . 188 5.6 Privacy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 5.7 Summary and further exploration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 Chapter 6 • Profiles and roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 6.1 Common BLE profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 6.1.1 Generic profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 6.1.2 GATT profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 6.2 Understanding a profile specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 6.2.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 6.2.2 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 6.2.3 Proximity Reporter Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

●8

Boek BLE 220329 UK.indd 8

06/05/2022 15:54

6.2.4 Proximity Monitor Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 6.2.5 Connection Establishment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 6.2.6 Security Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 6.2.7 GATT Interoperability Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 6.2.8 Acronyms and Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 6.2.9 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 6.3 Understanding a service specification. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 6.3.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 6.3.2 Service Declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 6.3.3 Service Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 6.3.4 Service Behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 6.3.5 Acronyms and Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 6.3.6 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 6.4 Understanding the definition of a characteristic . . . . . . . . . . . . . . . . . . . . . . . . . 203 6.4.1 Description. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 6.4.2 Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 6.5 Implementing a Proximity Reporter in Zephyr . . . . . . . . . . . . . . . . . . . . . . . . . . 204 6.6 Implementing a Proximity Monitor in NimBLE-Arduino . . . . . . . . . . . . . . . . . . . . 210 6.7 Summary and further exploration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 Chapter 7 • Reverse engineering BLE devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 7.1 Investigating the LED badge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 7.2 Decompiling the mobile app . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 7.3 Sniffing BLE traffic between the LED badge and the mobile app . . . . . . . . . . . . . 222 7.4 Writing arbitrary images to the LED badge using Bleak . . . . . . . . . . . . . . . . . . . 225 7.4.1 Finding LED badges. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 7.4.2 Writing images to the LED badge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 7.5 Summary and further exploration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 Chapter 8 • Lowering power consumption. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 8.1 Measuring power consumption with the Nordic Semiconductor Power Profiler Kit II 232 8.1.1 Ampere Meter mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 8.1.2 Source Meter mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234

●9

Boek BLE 220329 UK.indd 9

06/05/2022 15:54

Bluetooth Low Energy Applications 8.2 Measuring an iBeacon’s power consumption . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 8.3 Lowering power consumption by disabling hardware . . . . . . . . . . . . . . . . . . . . . 237 8.4 Lowering the power consumption by using a larger advertising interval . . . . . . . . 238 8.5 Estimating battery life . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 8.6 Summary and further exploration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 Chapter 9 • Conclusion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 9.1 Other BLE development platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 9.2 More about Bluetooth Low Energy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 9.3 Some ideas for further exploration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 Chapter 10 • Appendix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 10.1 Where to find BLE specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 10.2 16-bit UUID ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247 10.3 Verifying a product’s Bluetooth qualifications . . . . . . . . . . . . . . . . . . . . . . . . . 247 10.4 Establishing a serial connection to a device over USB . . . . . . . . . . . . . . . . . . . . 248 10.4.1 Check the port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 10.4.2 Install the USB-to-serial driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 10.4.3 Give the user access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 10.4.4 Start the serial connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 10.5 Sniffing BLE traffic on your Android device using the Bluetooth HCI snoop log. . . 250 10.5.1 Investigating the Bluetooth HCI snoop log file with Wireshark . . . . . . . . . 250 10.5.2 Sniffing live BLE traffic in Wireshark with the Android Debug Bridge . . . . . 251 10.6 Tips for specific hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 10.6.1 Programming boards that have the Adafruit nRF52 bootloader . . . . . . . . . 251 10.6.2 Programming boards with Arduino BOSSA . . . . . . . . . . . . . . . . . . . . . . . 253 Index

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

● 10

Boek BLE 220329 UK.indd 10

06/05/2022 15:54

Preface

Preface Bluetooth Low Energy (BLE) is one of the most accessible wireless communication standards. You don’t need any expensive equipment to develop BLE devices such as wireless sensor boards, proximity beacons, or heart rate monitors. All you need is a computer or a Raspberry Pi, an ESP32 microcontroller board, or a development board with a Nordic Semiconductor nRF5 (or an equivalent BLE SoC from another manufacturer). On the software side, BLE is similarly accessible. Many development platforms, most of them open source, offer an API (application programming interface) to assist you in developing your own BLE applications. This book shows you the ropes of BLE programming with Python and the Bleak library on a Raspberry Pi or PC, with C++ and NimBLE-Arduino on Espressif’s ESP32 development boards, and with C and the Zephyr real-time operating system on Nordic Semiconductor’s nRF52 boards. While Bluetooth Low Energy is a complex technology with a comprehensive specification, getting started with the basics is relatively easy. This book takes a practical approach to BLE programming to make the technology even more approachable. With a minimal amount of theory, you’ll develop code right from the start. After you’ve completed this book, you’ll know enough to create your own BLE applications. Koen Vervloesem, February 2022

● 11

Boek BLE 220329 UK.indd 11

06/05/2022 15:54

Bluetooth Low Energy Applications

Chapter 1 • Introduction Bluetooth Low Energy (BLE) is a complex technology, but the basics are quite accessible. In this book, you’ll learn how to: • • • • • •

discover BLE devices in the neighborhood by listening to their advertisements create your own BLE devices advertising data connect to BLE devices such as heart rate monitors and proximity reporters create secure connections to BLE devices with encryption and authentication understand BLE service and profile specifications and implement them reverse engineer a BLE device with a proprietary implementation and control it with your own software • reverse engineer a BLE device with a proprietary implementation and control it with your own software • make your BLE devices use as little power as possible This chapter introduces Bluetooth Low Energy and its advantages. It also lists the software and hardware platforms used in this book, as well as the reasons to choose them.

1.1 What is Bluetooth Low Energy? Bluetooth is a wireless communication standard in the 2.4 GHz Industrial, Scientific, and Medical (ISM) frequency band. These days, if you hear about Bluetooth support in a product, it is almost always Bluetooth Low Energy (BLE). It’s a radical departure from the original Bluetooth standard, which is now called Classic Bluetooth. Bluetooth Low Energy and Classic Bluetooth are actually different protocols. Classic Bluetooth is essentially a wireless version of the traditional serial connection. If you want to print a document, transfer a file or stream audio, you want this to happen as fast as possible. Therefore, the focus of development in Classic Bluetooth was on attaining faster and faster speeds with every new version. However, Classic Bluetooth wasn’t a good fit for devices with low power consumption, for instance those powered by batteries. That’s why Nokia adapted the Bluetooth standard to enable it to work in low-power scenarios. In 2006, they released their resulting technology onto the market, dubbed Wibree. The Bluetooth Special Interest Group (SIG), the organization that maintains the Bluetooth specifications, showed interest in this new development. After consulting with Nokia, they decided to adopt Wibree as part of Bluetooth 4.0, with the new name, Bluetooth Low Energy. Classic Bluetooth remained available for high-throughput applications. Note: In practice, many chipsets support both Classic Bluetooth and Bluetooth Low Energy, especially in laptops and smartphones.

● 12

Boek BLE 220329 UK.indd 12

06/05/2022 15:54

Chapter 1 • Introduction

1.2 Layered architecture The Bluetooth Core Specification (https://www.bluetooth.com/specifications/specs/ core-specification/) is more than 3200 pages long. And this is only the core specification; there are many supplemental documents for BLE. However, BLE has a layered architecture. Many end-user applications only use the upper layers, so you don’t need to know the details of the architecture’s lower layer. This book doesn’t refer to the Bluetooth Core Specification, but mainly to the supplemental specifications, which concern the upper layers.

Figure 1.1 The layered architecture of Bluetooth Low Energy The BLE architecture consists of three main blocks:tController, Host, andnApplication. Controller This has the lower-level layers: the Physical Layer (PHY), Link Layer (LL) and Direct Test Mode (DTM). These are the layers where the Bluetooth radio does its work. The controller communicates with the outside world using the antenna, in a frequency band around 2.4 GHz. It communicates with the host using a standardized interface between the two blocks – the Host Controller Interface (HCI). 1 Host This is the block with which the end user or application developer comes in contact. The Logical Link Control and Adaptation Protocol (L2CAP) defines channels and signaling commands. On top of it, the Security Manager Protocol (SMP) handles secure connections (with authentication and encryption), and the Attribute Protocol (ATT) defines how to expose and access data as attributes. The Generic Attribute Profile (GATT) 2 builds on the Attribute Protocol to define how to discover services and their characteristics and how to read and write their values. The upper layer of the Host block is the Generic Access Profile (GAP), which defines how devices can discover other devices and connect, pair, and bond to them. The host communicates with the controller using its part of the host controller interface, and applications communicate with the host depending on the APIs exposed by the operating system.

1 2

As the HCI is an interface between Host and Controller, it’s shown in both layers Yes, GATT doesn’t look like an acronym for Generic Attribute Profile, but the Bluetooth specification uses this because GAP is already taken by Generic Access Profile. You’ll get used to it.

● 13

Boek BLE 220329 UK.indd 13

06/05/2022 15:54

Bluetooth Low Energy Applications

Application This layer builds on top of the Generic Attribute Profile to implement application-specific characteristics, services, and profiles. A characteristic defines a specific type of data, such as an Alert Level. A service defines a set of characteristics and their behaviors, such as the Link Loss Service. A profile is a specification that describes how two or more devices with one or more services communicate with each other. An example is the Proximity profile, which has two roles: Proximity Monitor and Proximity Reporter. The application layer is where the example programs in this book reside, and they make use of the layers in the Host block. The three blocks don’t have to run on the same processor. In fact, there are three common configurations – one single-chip and two dual-chip: Single-chip (SoC) Controller, host, and application code run on the same chip. The host and controller communicate through function calls and queues in the chip’s RAM. Most simple devices such as BLE sensors use this configuration; it keeps the cost down. Some smartphones also use this configuration if they have a SoC with Bluetooth built in. Dual-chip over HCI A dual-chip solution with application and host on one chip, and the controller on another chip, communicates over HCI. Because HCI is a standardized interface, it lets you combine different platforms. For instance, on a Raspberry Pi, the Wi-Fi and BLE chip implements a BLE controller. If you connect a BLE dongle to an older Raspberry Pi, this dongle also implements a BLE controller. 3 BlueZ, the Raspberry Pi Linux kernel’s Bluetooth stack, implements a BLE host. So, BlueZ communicates with the BLE controller in the built-in BLE chip or on the BLE dongle (see Figure 1.2). In the former case, the HCI uses SDIO, and in the latter, UART over USB. 4 Many smartphones and tablets also use the dual-chip over HCI configuration, with a powerful processor running the host and a Bluetooth chip running the controller. Dual-chip with connectivity device Another dual-chip solution is one with the application running on one chip and the host and controller on another chip. The latter is then called the connectivity device because it adds BLE connectivity to the other device. This approach is useful if you have an existing hardware device that you want to extend with BLE connectivity. Because there’s no standardized interface in this case, the communication between the application processor and the connectivity device needs to make use of a proprietary protocol implemented by the connectivity device. A three-chip solution with controller, host, and application each running on its own chip is also possible. However, because of the associated cost, this is typically only done for development systems. 3 4

In fact, you can easily create your own BLE dongle with an nRF52840 Dongle and the controller part of Zephyr’s BLE stack. Just build the sample samples/bluetooth/hci_usb from the Zephyr samples and flash it to your dongle. The next chapter explains how to do this BlueZ even supports multiple controllers simultaneously.

● 14

Boek BLE 220329 UK.indd 14

06/05/2022 15:54

Chapter 1 • Introduction

Figure 1.2 A dual-chip implementation of the BLE architecture

1.3 How to communicate with BLE devices Bluetooth Low Energy has two ways to communicate between devices: with and without a connection.

1.3.1 Without a connection Without a connection means that the device just broadcasts information in an advertisement. Every BLE device in the neighborhood is able to receive this information. Some examples of BLE devices broadcasting data are: Proximity beacons These devices, often following Apple’s iBeacon standard, broadcast their ID. Receivers calculate their approximate distance to the beacons based on the advertisement’s Received Signal Strength Indicator (RSSI). Sensors Many temperature and humidity sensors broadcast their sensor values. Most devices do this in an unencrypted fashion, but some of them encrypt the data to prevent it being read by every device in the neighborhood. Mobile phones After the COVID-19 pandemic started in 2020, Google and Apple collaborated on the Exposure Notifications standard for contact tracing. As part of this technology, Android phones and iPhones broadcast unique (but anonymous) numbers. Other phones can pick up these numbers and use them later to warn users that they have been in contact with someone who is known to have had COVID-19.

1.3.2 With a connection The other way to communicate between BLE devices is with a connection. One device (the client) scans for BLE advertisements to find the device it wants to connect to. Then, optionally, it may do an active scan to ask the device (the server) which services are offered. After the client connects to the server, the client can use the server’s services. Each BLE service is a container of specific data from the server. You can read this data, or (with some services) write a value to the server.

● 15

Boek BLE 220329 UK.indd 15

06/05/2022 15:54

Bluetooth Low Energy Applications

Some examples of BLE devices using a connection are: Fitness trackers Your smartphone can connect to a fitness tracker and read your heart rate, the tracker’s battery level, and other measurements. Sensors Some environmental sensors let you read their sensor values over a BLE connection. Proximity reporters These devices sound an alert when their connection to another device is lost.

1.4 Advantages of BLE 1.4.1 Low power consumption As its name implies, Bluetooth Low Energy is optimized for low-power applications. Its whole architecture is designed to reduce power consumption. For instance, setting up a connection, reading or writing data, and disconnecting happens in a couple of milliseconds. The radio is often the most energy-consuming part of a device. Therefore, the idea is to turn on the Bluetooth radio, create a connection, read or write data, disconnect, and turn off the radio again until the next time the device has to communicate. This way, a well-designed BLE temperature sensor is able to work on a coin cell for ten years or more. You can use the same approach with other wireless technologies, such as Wi-Fi, but they require more power and take more time to set up a connection.

1.4.2 Ubiquitous BLE radio chips are ubiquitous. You can find them in smartphones, tablets, and laptops. This means that all those devices can talk to your BLE sensors or lightbulbs. Most manufacturers create mobile apps to control their BLE devices. You can also find BLE radios in many single-board computers, such as the Raspberry Pi, and in popular microcontroller platforms such as the ESP32. 5 This makes it quite easy for you to create your own gateways for BLE devices. And, platforms such as the Nordic Semiconductor nRF5 series of microcontrollers with BLE radio even make it possible to create your own battery-powered BLE devices.

1.4.3 Low cost There’s no cost to access the official BLE specifications. Moreover, BLE chips are cheap, and the available development boards (based on an nRF5 or an ESP32) and Raspberry Pis are quite affordable. This means you can just start with BLE programming at minimal cost.

The first Raspberry Pi with built-in BLE was the Raspberry Pi Model 3B (released in 2016).

● 16

Boek BLE 220329 UK.indd 16

06/05/2022 15:54

Chapter 1 • Introduction

1.5 Disadvantages of BLE 1.5.1 Short range BLE has a short range (for most devices, less than 10 meters) compared to other wireless networks, such as Zigbee, Z-Wave, and Thread. It’s not a coincidence that these competitors all have a mesh architecture, in which devices can forward their neighbors’ messages in order to improve range. Low-power wide area networks (LPWANs), such as LoRaWAN, Sigfox, and NB-IoT, have even longer ranges. In 2017, the Bluetooth SIG added Bluetooth Mesh, a mesh protocol. This builds upon BLE’s physical and link layers with a whole new stack above them. However, Bluetooth Mesh isn’t as well-established as the core BLE protocol, at least not for home use.

1.5.2 Limited speed The BLE radio has a limited transmission speed. For Bluetooth 4.2 and earlier, this is 1 Mbps, while for Bluetooth 5 and later, this can be up to 2 Mbps. This makes BLE unsuitable for high-bandwidth applications.

1.5.3 You need a gateway Wi-Fi devices have their own IP addresses, so you can communicate with them directly from other IP-based devices, and they are integrated into your LAN (local area network). Bluetooth doesn’t have this: to integrate your BLE devices with other network devices, you need a gateway. This device has to translate Bluetooth packets to IP-based protocols such as MQTT (Message Queuing Telemetry Transport). That’s why many BLE device manufacturers have smartphone apps that function as device gateways. 6

1.6 Platforms used in this book This book focuses on Bluetooth Low Energy programming on three platforms: Programming

Library

language Python

Bleak

Software

Hardware

platform

Windows, Linux,

Raspberry Pi or PC

macOS C++ C

NimBLE-Arduino

Arduino framework

ESP32

Zephyr7

nRF52

Table 1.1 BLE platforms used in this book These choices were made in order to demonstrate a wide range of applications compatible with many software and hardware platforms.

6 7

You can run IPv6 over BLE with 6LoWPAN, but this isn’t yet well-established. A more developed solution in the same 2.4 GHz frequency band is Thread, which uses 6LoWPAN over the IEEE 802.15.4 wireless protocol. There’s no library for Zephyr in this table because the Zephyr operating system includes all functionality we need for BLE development.

● 17

Boek BLE 220329 UK.indd 17

06/05/2022 15:54

Bluetooth Low Energy Applications

1.6.1 Python/Bleak (Raspberry Pi, PC) Python is an easy-to-use programming language that works on all major operating systems. There are a lot of Python Bluetooth Low Energy libraries, but many of them support only a single operating system. Bleak (https://bleak.readthedocs.io), which stands for Bluetooth Low Energy platform Agnostic Klient, is a welcome exception. It supports: • Windows 10, version 16299 (Fall Creators Update) or higher • Linux distributions with BlueZ 5.43 or higher (also on a Raspberry Pi) • OS X 10.11 (El Capitan) or macOS 10.12+

Figure 1.3 With Python and Bleak, a Raspberry Pi is the perfect small computer to communicate with your BLE devices. Bleak is a GATT client: it’s able to connect to BLE devices that act as GATT servers. It supports reading, writing, and getting notifications from GATT servers, and it’s also able to discover BLE devices and read advertising data broadcast by them. While Bleak doesn’t implement a GATT server, in practice this isn’t a big limitation. GATT servers are typically implemented on constrained devices, so, for this purpose, the ESP32 and nRF52 hardware platforms are a better match. 8

1.6.2 C++/NimBLE-Arduino (ESP32) If you’re looking at microcontrollers, the Arduino framework has become quite popular, not only on the original Arduino boards, which don’t have BLE functionality, but also on ESP32 development boards, which do.

If you really want to implement a GATT server on a Raspberry Pi or your PC, have a look at Bless (https://github.com/kevincar/bless). This is an acronym for Bluetooth Low Energy Server Supplement, and the library follows a similar API style to Bleak.

● 18

Boek BLE 220329 UK.indd 18

06/05/2022 15:54

Chapter 1 • Introduction

Figure 1.4 Espressif’s ESP32-PICO-KIT v4 is one of the many ESP32 development boards that you can use with NimBLE-Arduino for BLE development. Programming for the Arduino framework is done in a variant of C++, but the framework and many Arduino libraries hide much of C++’s complexity. Even if you only know some C (which is much less complex than C++), you’ll be able to use the Arduino framework. One of the more popular BLE libraries for Arduino on the ESP32 is NimBLE-Arduino (https:// github.com/h2zero/NimBLE-Arduino). It’s a fork of NimBLE (https://mynewt.apache.org/ latest/network/), which is part of the Apache Mynewt real-time operating system. With NimBLE-Arduino, you can easily create your own GATT server or client. Note: If you prefer to use Espressif’s ESP-IDF instead of the Arduino framework, you can use esp-nimble-cpp (https://github.com/h2zero/esp-nimble-cpp). In fact, NimBLE-Arduino and esp-nimble-cpp use the same API. This means that many NimBLE-Arduino examples in this book can be reused with ESP-IDF with only a few minor changes.

1.6.3 C/Zephyr (nRF52) For even more constrained devices, typically battery-powered, you need a specialized realtime operating system (RTOS). This book uses the Zephyr Project (https://zephyrproject. org) on nRF52840-based devices from Nordic Semiconductor. Zephyr has a completely open-source Bluetooth Low Energy stack.

Figure 1.5 Nordic Semiconductor’s nRF52840 Dongle is an affordable development platform for BLE applications with Zephyr. Zephyr’s BLE stack is highly configurable. You can build Zephyr firmware for three configuration types:

● 19

Boek BLE 220329 UK.indd 19

06/05/2022 15:54

Bluetooth Low Energy Applications

Combined build Builds the BLE controller, BLE host, and your application for a one-chip configuration. Host build Builds the BLE host and your application, along with an HCI driver to let your device communicate with an external BLE controller on another chip. 9 Controller build Builds the BLE controller with an HCI driver to let your device communicate with an external BLE host on another chip. With some basic knowledge of C, you can create your own BLE devices with Zephyr, such as BLE beacons, sensor boards, and proximity reporters. Zephyr has extensive documentation of its Bluetooth API, as well as a lot of ready-to-use examples that you can build upon. For the examples in this book, you’ll use the combined build type.

1.7 How to use this book This is a book about programming. I expect you to have some programming experience. Knowledge of C, C++, and Python would be perfect. However, if you only know one or two of these programming languages, that won’t be a problem. The necessary C++ knowledge is minimal, so a basic knowledge of Python and C will suffice. You need some (affordable) hardware for the examples in this book: • The Python examples are hardware-agnostic due to the use of Bleak. So, whether you want to use a Raspberry Pi or another Linux computer, a Windows computer, or a Mac, it won’t make much difference. • For the NimBLE-Arduino examples, any ESP32 development board will suffice.

• For the Zephyr examples, I recommend a Nordic Semiconductor nRF52840 Dongle, but you can use any BLE microcontroller supported by Zephyr. Some other manufacturers have variants of the dongle, such as the April USB Dongle 52840 (with an external antenna) or the nRF52840 MDK USB Dongle from makerdiary (with a case). Consult the appendix at the end of this book if you want to use one of these, because they come with a different bootloader.

9 10

For instance, on Nordic Semiconductor devices, the BLE controller can be a SoftDevice controller. Note that the ESP8266, the ESP32’s predecessor, isn’t suitable for this book; it doesn’t have BLE.

● 20

Boek BLE 220329 UK.indd 20

06/05/2022 15:54

Chapter 1 • Introduction

Figure 1.6 From left to right: April Brother's April USB Dongle 52840, Nordic Semiconductor's nRF52840 Dongle, and makerdiary's nRF52840 MDK USB Dongle.. If you’re really serious about BLE development with Zephyr, I also recommend Nordic Semiconductor’s nRF52840 Development Kit. This is the bigger (and slightly less affordable) brother of the nRF52840 Dongle, offering more capabilities to debug your code easily. If you have one of these, you can do your initial development on it, and move your code to the nRF52840 Dongle when you’ve solved the most complex issues.

Figure 1.7 Nordic Semiconductor’s nRF52840 Development Kit has some powerful debugging capabilities. So, at the minimum, you need your computer, one ESP32 development board and one BLE microcontroller supported by Zephyr. Note: I recommend buying a couple of Nordic Semiconductor nRF52840 Dongles. As you’ll see in the next chapter, with the right firmware, you can turn these into adapters to explore other BLE devices and connect to them. You can also turn them into BLE sniffers that pick up BLE packets in the air and sniff traffic between other devices. They’re quite affordable too, with a price of around €10.

● 21

Boek BLE 220329 UK.indd 21

06/05/2022 15:54

Bluetooth Low Energy Applications

At the end of this book, you should be able to create your own BLE software based on the examples here. Here’s a short overview of what I’ll cover in this book: Chapter 1: Introduction An introduction to Bluetooth Low Energy, its layered architecture, and its advantages and disadvantages Chapter 2: Preparing your development environment A preparation of your development environment for Python/Bleak, Arduino/NimBLE-Arduino, and Zephyr, as well as some useful tools for exploring BLE devices, and a BLE packet sniffer in Wireshark Chapter 3: Broadcasting data with advertisements A deep dive into advertising packets, which are fundamental for device discovery, but also a powerful way to broadcast data without the need to connect to a BLE device Chapter 4: Connections and services The use of BLE connections to read and write characteristics and receive notifications and indications from peripherals Chapter 5: Securing BLE connections Security measures to encrypt and authenticate BLE connections and use resolvable private addresses to thwart user tracking Chapter 6: Profiles and roles A step-by-step guide to implementing a BLE profile, as well as how to understand profile and service specifications Chapter 7: Reverse engineering BLE devices Reverse engineering a BLE LED badge by investigating its services and characteristics, decompiling the accompanying mobile app, and sniffing BLE traffic between the device and its mobile app Chapter 8: Lowering power consumption An investigation into and optimization of a BLE implementation’s power consumption Chapter 9: Conclusion A wrap-up of this book, with some resources for learning more about Bluetooth Low Energy and some ideas for further exploration Appendix Some specialized tips that could come in handy in various situations

● 22

Boek BLE 220329 UK.indd 22

06/05/2022 15:54

Chapter 1 • Introduction

Note: All of the code examples from this book are published at https://github.com/ koenvervloesem/bluetooth-low-energy-applications. Read the instructions in this GitHub repository for more information about how to download them. The repository also lists errors that may have been found in this book since its publication, as well as information about changes that impact the examples herein.

1.8 Summary and further exploration In this introductory chapter, I explained the basics of Bluetooth Low Energy and its architecture. I also explained the two different ways to communicate with BLE devices: with and without a connection. After this, you learned about some of the advantages and disadvantages of BLE. At the end of this chapter, I introduced the platforms used in this book, both hardware and software. Of course, these platforms aren’t the only ones you can use for BLE programming. For instance, I don’t cover BLE programming on mobile devices (Android or iOS). However, with the BLE knowledge learned from this book, you’ll be able to understand the BLE APIs offered by other platforms. In the next chapter, you’ll learn how to set these platforms up, so that your development environment is ready for the rest of the book.

● 23

Boek BLE 220329 UK.indd 23

06/05/2022 15:54

Bluetooth Low Energy Applications

Index 6LoWPAN ........................................... 17 16-bit UUIDs ........................98, 105, 246 A active scanning ..............................63, 68 Adafruit nRF52 bootloader ...... 32, 33, 246, 251, 253 ADV_DIRECT_IND ............................... 46 advertisement... 15, 50, 52, 56, 62, 68, 73, 74, 90, 149, 232, 236 advertising channels ............................ 44 advertising interval .....56, 78, 89, 198, 238 advertising packets.......................44, 240 advertising parameters ........... 77, 89, 236 ADV_IND ................................ 46, 52, 56 ADV_NONCONN_IND .........46, 56, 94, 152 ADV_SCAN_IND .............................46, 94 Alert Level characteristic ......111, 201, 209 AltBeacon ........................................... 95 Android app ............................... 219, 250 Apache Mynewt............................19, 243 APK file ..................................... 219, 220 Appearance Values ..................... 136, 246 Apple Continuity Protocol ..................... 96 April USB Dongle 52840 .....20, 32, 37, 251 Arduino ....................... 17, 26, 61, 66, 96, 124, 243, 248, 253 Arduino CLI ........................................ 25 Arduino core ................................27, 243 assigned numbers ............................. 150 attribute...............................98, 141, 156 attribute permissions ......................... 156 Attribute Protocol (ATT)...................13, 98 authentication..................... 13, 148, 157, 160, 164, 185 B battery life ................................ 232, 239 beacontools ........................................ 96 Bleak ...... 17, 24, 48, 58, 92, 95, 105, 108, 115, 147, 149, 173, 198, 225 BLE Audio.................................. 243, 245 Bless ................................................. 18 Bluetooth address .................. 46, 53, 189

Bluetooth Core Specification ... 13, 51, 191, 200, 203, 244 Bluetooth HCI snoop log.............. 222, 250 Bluetooth High Speed ........................ 244 Bluetooth Long Range ........................ 244 Bluetooth Mesh ............. 17, 193, 243, 244 Bluetooth qualification ........195, 200, 201, 244, 246, 247 Bluetooth Special Interest Group (SIG) .. 12 BlueZ................ 14, 18, 53, 108, 119, 243 BME280 ...............................82, 136, 165 bonding .................................... 156, 164 bootloader ...................................37, 251 BOSSA bootloader ............................. 246 broadcaster ............................. 44, 73, 94 broadcasting .......................... 15, 44, 243 C callback function ........ 50, 63, 77, 93, 118, 123, 130, 141, 179, 209 central ....................44, 97, 116, 186, 209 characteristic ...14, 99, 108, 115, 141, 172, 178, 201, 219 characteristic declaration ............. 100, 142 characteristic definition ...................... 203 Characteristic Presentation Format Descriptor ........................................ 101 Characteristic User Description Descriptor ........................................ 101 characteristic value.......100, 111, 116, 209 Classic Bluetooth ...................12, 201, 245 Client Characteristic Configuration Descriptor (CCCD) .............................101 CMake ............................................... 79 CMakeLists.txt ................ 79, 83, 132, 177 company ID.................. 53, 56, 68, 70, 81 Company Identifiers .......................... 246 connection interval ..............130, 198, 232 Connection Signature Resolving Key(CSRK) ......................... 163 connectivity device .............................. 14 CONNECT_REQ .....................46, 104, 222 Construct ................59, 92, 111, 147, 154 contact tracing ......................15, 151, 152 Core Bluetooth .................................. 243 Core Specification Supplement ............ 246

● 254

Boek BLE 220329 UK.indd 254

06/05/2022 15:55

Index

COVID-19 ...................................15, 151 CP210x ............................................ 248 CR2025............................................ 239 CR2032............................................ 239 CR2477............................................ 239 current consumption .......................... 232 D Dalvik byte code ............................... 220 data signing ..................................... 164 declaration ID ................................... 247 decompiling ..........................22, 217, 231 descriptor ............ 101, 106, 108, 144, 172 device discovery.............................22, 43 Device Information service .......... 108, 131 devicetree ...................... 84, 85, 181, 185 devicetree overlay ............................... 84 Device Under Test (DUT) .................... 232 Direction Finding ............................... 243 Direct Test Mode (DTM)........................ 13 E EAFP.................................................. 61 Eddystone .......................................... 95 encryption ................... 13, 152, 156, 163, 172, 179, 189, 199 entropy ..................................... 160, 162 ESP32 .. 17, 25, 61, 69, 124, 215, 243, 248 ESP8266 ............................................ 20 ESP-IDF ......................................19, 243 EUI-48 ............................................... 53 Exposure Notifications...................15, 152 Extended Advertising ......................... 244 F FTDI ................................................ 249 G gateway ............................................. 17 GATT client ..................... 18, 98, 179, 195 GATT server...... 18, 19, 97, 110, 131, 135, 195, 245 GATT Specification Supplement ... 100, 118, 131, 202, 246 Generic Access Profile (GAP) ...........13, 43, 97, 192

Generic Attribute Profile (GATT) ........... 13, 192, 195 Google/Apple Exposure Notification .... 151, 246 H handle .................. 98, 100, 106, 110, 118 heart rate..................... 98, 115, 154, 193 Heart Rate Measurement characteristic ............................. 118, 130 heart rate monitor ...................... 124, 154 Heart Rate Profile ....................... 129, 193 Heart Rate Service ............................ 130 HID over GATT ........................... 193, 245 Host Controller Interface (HCI) ............. 13 I iBeacon . 15, 55, 73, 95, 232, 236, 238, 246 Identity Resolving Key (IRK) ..........55, 164 Immediate Alert Service..................... 195 indications .... 101, 115, 130, 142, 145, 172 initiator ............... 157, 161, 163, 176, 188 input/output capabilities ..................... 176 interference ........................................ 44 J jadx................................................. 220 Just Works ..................160, 162, 165, 175 K Kconfig .............................................. 80 L LBYL .................................................. 61 LE 1M PHY ........................................ 244 LE 2M PHY ........................................ 244 LE Coded PHY ................................... 244 LED badge................................. 217, 250 LE Legacy Connection pairing...... 158, 159, 163, 165, 190 LE Secure Connection pairing ...... 155, 158, 161, 162, 163, 164, 165, 176 Link Layer (LL) .................................... 13

● 255

Boek BLE 220329 UK.indd 255

06/05/2022 15:55

Bluetooth Low Energy Applications

Link Loss service ................111, 192, 196, 201, 204, 209, 215 little-endian ...........47, 56, 70, 91, 93, 151 Logical Link Control and Adaptation Protocol (L2CAP) ................................. 13 LoRaWAN ........................................... 17 LTV .................................................... 96 M major ................................57, 69, 76, 80 man-in-the-middle (MITM) attack ........ 157 manufacturer-specific data .............33, 35, 52, 55, 58, 66, 68, 75, 80, 82, 219 master ........................... 44, 97, 157, 164 Mbed OS .......................................... 253 measured power ...................... 57, 74, 95 Message Integrity Check (MIC) ........... 164 Microsoft advertising beacon ................. 69 minicom ........................................... 249 minimal GATT server.......................... 105 minor ................................57, 69, 76, 80 MQTT ................................................. 17 N n-able .............................................. 243 NB-IoT ............................................... 17 NFC .......................................... 160, 162 NimBLE-Arduino ....17, 25, 61, 66, 96, 124, 198, 210, 243 Nokia ................................................. 12 non-connectable advertising ...... 44, 76, 89 notifications ......... 101, 116, 130, 136, 147 nRF52840 Development Kit ...... 21, 31, 83, 85, 165, 173, 176, 232, 248 nRF52840 Dongle ....14, 19, 30, 36, 80, 82, 135, 136, 172, 248 nRF Connect for Desktop .....24, 32, 33, 34, 35, 36, 37, 42, 232, 233, 236, 240, 242 nRF Connect mobile app... 33, 91, 101, 209 nRF Sniffer for Bluetooth LE ...36, 148, 176, 222, 252 nrfutil ................................................ 29 Numeric Comparison .................. 162, 176

OUI ................................................... 53 Out of Band (OOB) ..................... 160, 162 P pairing ..156, 172, 175, 188, 191, 199, 215 pairing methods ......................... 160, 162 pairing request........................... 173, 175 passive scanning ................................. 52 Passkey Entry ............................ 160, 162 PDU types .......................................... 46 peripheral 44, 97, 102, 108, 116, 131, 135, 136, 156, 166, 177, 190, 195, 204 permissions ......... 142, 156, 172, 179, 209 Physical Layer (PHY) ............................ 13 Pillow ............................................... 228 pip .................................................... 25 pixel editor ....................................... 229 Pixelorama ....................................... 229 PlatformIO ....................................25, 41 power consumption ................ 12, 16, 232 power management subsystem ........... 237 Power Profiler ............................ 232, 236 Power Profiler Kit II ........................... 232 primary service ............100, 142, 172, 209 privacy .......................................55, 189 private address ..........55, 79, 89, 164, 189 prj.conf ..... 80, 85, 95, 132, 135, 136, 142, 166, 175, 177, 189, 190, 204, 237, 252 profile ................... 14, 129, 155, 192, 244 Proximity Beacon ................................ 55 Proximity Monitor ...................... 192, 195, 197, 210 Proximity profile ................................ 192 Proximity Reporter ........................... 192, 195, 196, 204 public address..............................54, 190 PuTTY .............................................. 249 Python ..............................17, 24, 49, 58, 93, 96, 105, 109, 112, 114, 118, 119, 135, 145, 149, 173, 225 Q QDID ............................................... 247 QR code .............................160, 162, 218

O observer ............................................ 44

● 256

Boek BLE 220329 UK.indd 256

06/05/2022 15:55

Index

R racing to idle .................................... 232 random address ...........................54, 190 range.................................... 17, 37, 244 Raspberry Pi ................. 14, 16, 17, 24, 54 resolvable address............................... 55 resolvable private address (RPA) ......... 190 responder............ 157, 161, 163, 176, 188 reverse engineering ........................... 219 RSSI ........................... 15, 33, 50, 57, 69, 72, 74, 80, 95, 226 RTOS ................................................. 19 RuuviTag .................83, 96, 136, 154, 247 S SARS-CoV-2 ..................................... 151 scan interval ................. 64, 129, 198, 215 scanner..................48, 58, 72, 80, 92, 94, 120, 149, 226 SCAN_REQ .........................46, 52, 64, 94 SCAN_RSP .........................46, 52, 64, 94 scan window ................. 64, 129, 198, 215 screen ............................66, 69, 72, 186, 209, 215, 249 SDIO ................................................. 14 Secure Connections Only Mode .... 165, 177 security database ....................... 156, 176 Security Mode 1 ................................ 164 Security Mode 1 Level 1 ..................... 164 Security Mode 1 Level 2 ......164, 166, 172, 199, 215 Security Mode 1 Level 3 ..................... 199 Security Mode 1 Level 4 .............. 165, 177 Security Mode 2 ................................ 164 Security Mode 3 ................................ 165 SEGGER J-Link .................................... 33 serial connection ............ 66, 69, 129, 145, 173, 176, 186, 209, 215, 248, 249 service ...... 14, 15, 99, 101, 105, 129, 136, 141, 177, 186, 192, 196, 200, 220 service data...................................... 149 service declaration ............................ 100 service definition ............................... 100 Short Term Key (STK) ........................ 159 Sigfox ................................................ 17 slave ............................. 44, 97, 157, 164

SoftDevice........................20, 31, 36, 247 speed ................................................ 17 T Temporary Key (TK) .......................... 159 Theengs Decoder ................................ 96 Thread ............................................... 17 TLV.................................................... 96 Tx Power Service ............................... 195 U UART ..........................................14, 237 UF2 ................................................. 252 UUID .. 51, 57, 76, 98, 100, 109, 129, 134, 141, 149, 198, 201, 209, 220, 247 V Visual Studio Code .........................25, 41 W west .............................. 30, 80, 232, 253 Wibree ........................................12, 244 Windows.Devices.Bluetooth ................ 242 Wireshark..35, 45, 52, 56, 80, 91, 95, 104, 148, 150, 175, 188, 222, 250 Z Zephyr ...................14, 17, 19, 29, 41, 73, 82, 94, 131, 136, 154, 165, 175, 177, 186, 190, 199, 204, 232, 252 Zigbee ............................................... 17 Z-Wave .............................................. 17

● 257

Boek BLE 220329 UK.indd 257

06/05/2022 15:55

books books

books

Develop your own Bluetooth Low Energy Applications • Koen Vervloesem

Develop your own Bluetooth Low Energy Applications

BLE

Develop your own Bluetooth Low Energy Applications for Raspberry Pi, ESP32 and nRF52 with Python, Arduino and Zephyr

Koen Vervloesem

Develop your own Bluetooth Low Energy Applications

Articles inside

Preface

Chapter 1 • Introduction