Welcome to the .NET nanoFramework nanoFramework.Device.Bluetooth Library repository

Build status

| Component | Build Status | NuGet Package | |:-|---|---| | nanoFramework.Device.Bluetooth | | |

nanoFramework.Device.Bluetooth class Library

Bluetooth Low Energy library.

This library is based on the Windows.Devices.Bluetooth UWP class library but simplified and with the asynchronous related calls made synchronous. The original .Net assembly depended on Windows.Storage.Streams for DataReader & DataWriter; this library has simplified inbuilt versions. So references to IBuffer in .Net UWP examples should now use Buffer instead.

Firmware versions

Bluetooth is currently only supported on ESP32 devices with following firmware.

ESP32_BLE_REV0
ESP32_BLE_REV3
ESP32_PSRAM_BLE_GenericGraphic_REV3
ESP32_S3_BLE
M5Core2
LilygoTWatch2021
ESP32_ETHERNET_KIT_1.2

The Bluetooth is not in every firmware due to a restriction in the IRAM memory space in the firmware image. For earlier revision 1 ESP32 devices, the PSRAM implementation required a large number of PSRAM library fixes which greatly reduces the available space in the IRAM area, so PSRAM is currently disabled for ESP32_BLE_REV0. With the revision 3 devices the Bluetooth and PSRAM are both available.

Samples

A number of Bluetooth LE samples are available in the nanoFramework samples repo

Usage

Overview

This implementation supports a cut down version of the Gatt Server and Gatt Client implementations.

The device can either run as a Server or Client, but not at the same time.

For more information see relevant sections: -

Gatt Server
Gatt Client / Central
Advertisement Publishing

Also as part of this assembly is the NordicSPP class which implements a Serial Protocol Profile based on the Nordic specification. This allows clients to easily connect via Bluetooth LE to send and receive messages via a Bluetooth Serial Terminal application. A common use case is for provisioning devices. See SPP section later for usage.

Attributes and UUIDs

Each service, characteristic and descriptor is defined by it's own unique 128-bit UUID. These are called GUID in .Net and UUID in the Bluetooth specifications.

If the attribute is standard UUID defined by the Bluetooth SIG, it will also have a corresponding 16-bit short ID (for example, the characteristic Battery Level has a UUID of 00002A19-0000-1000-8000-00805F9B34FB and the short ID is 0x2A19). The common standard UUIDs can be seen in the classes GattServiceUuids and GattCharacteristicUuids.

If the short ID is not present in GattServiceUuids or GattCharacteristicUuids then create your own short GUID by calling the utility function CreateUuidFromShortCode.

Guid uuid1 = Utility.CreateUuidFromShortCode(0x2A19);

Security and Pairing

The assembly supports pairing with encryption and authentication.

If you don't do anything in your code it will use the Just works method of pairing which will enable encryption on the connection.

To enable Authentication you will need to handle the pairing events in your code.

For more information see Pairing section.

Gatt Server

The main object for the Gatt Server is the BluetoothLEServer class. This is a singleton class so there can only be one occurance of the BluetoothLEServer object. The BluetoothLEServer object can be accessed by using the static BluetoothLEServer.Instance property. The first call to this will create the object. Calling dispose will remove the object from memory.

This object is new and doesn't exist in the normal Windows implementation and was added to allow better handling of pairing and connections from the managed code.

Setting the Device Name and it Appearance

The device name and appearance is part of the Generic Access service which is automatically included in each Gatt Server definition. The name should be the name of current device and the appearance which is optional is a 16 bit code that represents the use of the device. Defaults to 0 which is "Unknown Device". For details on codes see the Bluetooth Sig Assigned numbers document; section 2.6.3 Appearance Subcategory values. Use the values column for the code. For example code 0x0481 is for a cycling computer.

    BluetoothLEServer server = BluetoothLEServer.Instance;
    server.DeviceName = "Esp32_01";
    server.Appearance = 0x0481;

Defining the service and associated Characteristics

The GattServiceProvider is used to create and advertise the primary service definitions. An extra device information service will be automatically created when first service is created.

GattServiceProviderResult result = GattServiceProvider.Create(uuid);
if (result.Error != BluetoothError.Success)
{
    return result.Error;
}

serviceProvider = result.ServiceProvider;

To create further services for the Gatt server call GattServiceProvider.Create(UUID) for each new service.

Access all created services via the BluetoothLEServer instance.

BluetoothLEServer server = BluetoothLEServer.instance;
GattServiceProvider[] services = server.Services()

Or find a specific service by using its UUID.

BluetoothLEServer server = BluetoothLEServer.instance;
GattServiceProvider service = server.GetServiceByUUID(uuid)

Using the Service property of the GattServiceProvider all the required characteristics can be added. Currently only Read, Write, WriteWithoutResponse, Notify and Indicate characteristics are supported.

Adding a Read Characteristic

If a userDescription is added to the GattLocalCharacteristicParameters then a user description descriptor will be automatically added to the Characteristic. For a read Characteristic you will need an associated event handler to provide the data for the read.

GattLocalCharacteristicParameters ReadParameters = new GattLocalCharacteristicParameters
{
    CharacteristicProperties = (GattCharacteristicProperties.Read),
    UserDescription = "My Read Characteristic"
};

GattLocalCharacteristicResult characteristicResult = serviceProvider.Service.CreateCharacteristic(uuid1, ReadParameters);
if (characteristicResult.Error != BluetoothError.Success)
{
    // An error occurred.
    return characteristicResult.Error;
}

_readCharacteristic = characteristicResult.Characteristic;
_readCharacteristic.ReadRequested += _readCharacteristic_ReadRequested;

You can have a read Characteristics with a constant value by setting the StaticValue property.

// Setting a Int 16 constant value to the characteristic. 
DataWriter dr = new DataWriter();
dr.WriteInt16(123);

GattLocalCharacteristicParameters ReadParameters = new GattLocalCharacteristicParameters
{
    CharacteristicProperties = (GattCharacteristicProperties.Read),
    UserDescription = "My Read Characteristic",
    StaticValue = dr.DetachBuffer()
};

If the StaticValue is set the read event will not be called and doesn't need to be defined.

NanoFramework.Device.Bluetooth

Install / Use

README