Bluetoe

Putin's Invasion of Ukraine

Please consider donating to one of the funds that help victims of the war in Ukraine:

• https://spendenkonto-nothilfe.de

Overview

Bluetoe implements a GATT server with a very low memory footprint and a convenient C++ interface. Bluetoe makes things easy but gives you the opportunity to fiddle with all the low-level GATT details if necessary. Bluetoe's primary target is very small microcontrollers. Here is a complete example of a small GATT server that allows a client to controll an IO pin, running on a nRF52832:

#include <bluetoe/server.hpp>
#include <bluetoe/device.hpp>
#include <nrf.h>

using namespace bluetoe;

// LED1 on a nRF52 eval board
static constexpr int io_pin = 17;

static std::uint8_t io_pin_write_handler( bool state )
{
    // On an nRF52 eval board, the pin is connected to the LED's cathode. This inverts the logic.
    NRF_GPIO->OUT = state
        ? NRF_GPIO->OUT & ~( 1 << io_pin )
        : NRF_GPIO->OUT | ( 1 << io_pin );

    return error_codes::success;
}

using blinky_server = server<
    service<
        service_uuid< 0xC11169E1, 0x6252, 0x4450, 0x931C, 0x1B43A318783B >,
        characteristic<
            requires_encryption,
            free_write_handler< bool, io_pin_write_handler >
        >
    >
>;

blinky_server gatt;

device< blinky_server > gatt_srv;

int main()
{
    // Init GPIO pin
    NRF_GPIO->PIN_CNF[ io_pin ] =
        ( GPIO_PIN_CNF_DRIVE_S0H1 << GPIO_PIN_CNF_DRIVE_Pos ) |
        ( GPIO_PIN_CNF_DIR_Output << GPIO_PIN_CNF_DIR_Pos );

    for ( ;; )
        gatt_srv.run( gatt );
}

Documentation

http://torstenrobitzki.github.io/bluetoe/

L2CAP

Bluetoe ships with its own fully-usable link layer based on the nRF52832. The link layer implementation is based and tested on an abstract device called a scheduled radio, and should be easy to port to similar hardware. As Bluetoe is a GATT server implementation, only parts of the link layer relevant to GATT have been implemented. Bluetoe can be easily adapted to any other existing L2CAP implementation (those based on HCI, for example).

Current State

The following table shows the list of supported GATT procedures, along with and their current and planned implementation status:

Feature	Sub-Procedure	Status
Server Configuration	Exchange MTU	implemented
Primary Service Discovery	Discover All Primary Services	implemented
	Discover Primary Service By Service UUID	implemented
Relationship Discovery	Find Included Services	implemented
	Declare Secondary Services	implemented
Characteristic Discovery	Discover All Characteristic of a Service	implemented
	Discover Characteristic by UUID	implemented
Characteristic Descriptor Discovery	Discover All Characteristic Descriptors	implemented
Characteristic Value Read	Read Characteristic Value	implemented
	Read Using Characteristic UUID	implemented
	Read Long Characteristic Value	implemented
	Read Multiple Characteristic Values	implemented
Characteristic Value Write	Write Without Response	implemented
	Signed Write Without Response	not planned
	Write Characteristic Value	implemented
	Write Long Characteristic Values	implemented
	Characteristic Value Reliable Writes	implemented
Characteristic Value Notification	Notifications	implemented
Characteristic Value Indication	Indications	implemented
Characteristic Descriptor Value Read	Read Characteristic Descriptors	implemented
	Read Long Characteristic Descriptors	implemented
Characteristic Descriptor Value Write	Write Characteristic Descriptors	implemented
	Write Long Characteristic Descriptors	implemented
Cryptography	Encryption	implemented
	Authentication	planned

This is the current state of implemented Advertising Data:

Advertising Data	Format	Status
Service UUID	Incomplete List of 16-bit Service UUIDs	implemented
	Complete List of 16-bit Service UUIDs	implemented
	Incomplete List of 32-bit Service UUIDs	not planned
	Complete List of 32-bit Service UUIDs	not planned
	Incomplete List of 128-bit Service UUIDs	implemented
	Complete List of 128-bit Service UUIDs	implemented
Local Name	Shortened Local Name	implemented
	Complete Local Name	implemented
Flags	Flags	implemented
Manufacturer Specific Data	Manufacturer Specific Data	planned
TX Power Level	TX Power Level	planned
Secure Simple Pairing Out of Band		not planned
Security Manager Out of Band		not planned
Security Manager TK Value		not planned
Slave Connection Interval Range		not planned
Service Solicitation		not planned
Service Data		not planned
Appearance	Appearance	implemented
LE Role	LE Role	planned

This is the current state of the Link Layer implementation:

Aspect	Feature	Status
Roles	Slave Role	implemented
	Master Role	not planned
Advertising	connectable undirected advertising	implemented
	connectable directed advertising	implemented
	non-connectable undirected advertising	implemented
	scannable undirected advertising	implemented
Device Filtering		implemented
Connections	Single Connection	implemented
	Multiple Connection	not planned
Connection	Slave Latency	planned
Feature Support	LE Encryption	implemented
	Connection Parameters Request Procedure	implemented
	Extended Reject Indication	planned
	Slave-initiated Features Exchange	planned
	LE Ping	implemented
	LE Data Packet Length Extension	planned
	LL Privacy	not planned
	Extended Scanner Filter Policies	not planned

Pull requests are welcome.

Dependencies

• Boost for Unit tests
• CMake for build
• A decent C++ compiler supporting C++11

Current Measurements

All measurements were done without any traffic and a slave latency of 0. Average current was measured using various connection intervals.

nRF52840 blinky without encryption

• Calibrated RC Sleep Clock (500ppm) (13608 Bytes binary size)

  • 546µA average at 7.5ms
  • 283µA average at 15ms
  • 155µA average at 30ms

• Crystal Oscilator Sleep Clock (20ppm) (13364 Bytes binary size)

  • 526µA average at 7.5ms
  • 207µA average at 15ms
  • 143µA average at 30ms
  • 22.4µA average at 660ms

nRF52840 blinky with encryption

• Calibrated RC Sleep Clock (500ppm) (22848 Bytes binary size)

  • 613µA average at 7.5ms
  • 211µA average at 30ms
  • 113µA average at 660ms

• Crystal Oscilator Sleep Clock (20ppm) (22608 Bytes binary size)

  • 589µA average at 7.5ms
  • 197µA average at 30ms

• Synthesized Sleep Clock (40ppm) (22596 Bytes binary size)

  • 1.09mA average at 7.5ms
  • 776µA average at 30ms

• Old radio implementation (40ppm) (22212 Bytes binary size)

  • 1.08mA average at 7.5ms
  • 874µA average at 15ms
  • 770µA average at 30ms
  • 674µA average at 660ms

nRF52820 blinky with encryption

• Calibrated RC Sleep Clock (500ppm / 1ms HFXO startup time) (21880 Bytes binary size)

  • 347µA average at 15ms
  • 217µA average at 30ms
  • 94µA average at 660ms

• Calibrated RC Sleep Clock (500ppm / 0.3ms HFXO startup time) (21880 Bytes binary size)

  • 316µA average at 15ms
  • 103µA average at 660ms