ArduinoBLE library

Is there a complete language reference somewhere for the ArduinoBLE library? The reference I keep getting directed to seems to be missing a whole lot of information. Thanks people.

This is the official ArduinoBLE reference.

It contains everything you need to create a BLE peripheral and central. What major information are you missing that would be needed for the application layer?

My free pfodDesigner Android app will generate the code for a Nordic UART connection for you.
see Arduino NANO 33 Made Easy No Coding required

Passing strings as values, different types of characteristic values, streaming data, standard UUIDs (link is 403-forbidden), etc. I’m new to BLE and there’s not a lot in the reference to learn from.

What would you like to do?

Please be more specific. There are a couple of characteristic types defined for standard types e.g., int, bool, ...

If you want something else, you can use the generic BLECharacteristic which only needs an array of bytes. You can use unions to overlay the bytes with a struct for instance. There are examples in the forum. If you let me know what you would like I can create an example for you or point you to an example I already posted.

Check out the Arduino Nano 33 BLE and IoT sub forum.

There is no such thing as streaming data for BLE. What you can do is to enable notifications to a characteristic? They will inform the central that the peripheral updated the characteristic and the central can get the value. When you write to the characteristic in a regular interval you get a continuous "stream" of updates. But there is no guarantee that the central actually picked up the value. This is wireless. Packets can get lost. You have to solve that at the application layer if that is an issue.

You can get the assigned UUIDs (16-bit) from the Bluetooth web page.

For your own services and characteristics, you must use random 128-bit UUIDs. There are generators available online. You can write yourself a script in the language of your choice. You could even write an Arduino sketch and print yourself some UUIDs in the Serial Monitor.

For the most part, BLE is quite easy from an application layer point of view.

When you look at the ArduinoBLE examples you have most of what you need. There are a few nicer ways to program this. I am sure you will learn that by looking at an example or two. Let me know what you would like to do in your sketch.

Thank you for the help! Quite simply I want to know as much about BLE as you do (in respect to Arduino), but don’t know where to learn it. Just as a learning exercise I wanted to use LightBlue to send “Hello World” (or whatever) to the Arduino and have the Arduino Serial.print this text when it recognized that new data was received. I couldn’t figure it out using the reference, probably because I’m missing some assumed knowledge. I tend to skip ahead. I was able to control a Neopixel project by sending various hex values, but that’s as far as I got. Thanks again for your help.

I am not sure whether this works in LightBlue. I found EFR Connect support read and write of text data and BLE Scanner allows writing text but displays the characteristic as HEX formatted byte values. In the Serial Monitor you get standard text print with both apps.

Here is an example with a text characteristic. I recommend using that only if you really have text. Using this instead of intelligently designing characteristics would be a waste of GATT capabilities.

  This example shows how to create a text characteristic.

  The circuit:
  - Arduino Nano 33 BLE and BLE Sense
  - Arduino Nano RP2040 Connect
  - Arduino Nano 33 IoT

  You can use a generic BLE central app, like EFR Connect (iOS and Android),
  to interact with the services and characteristics created in this sketch.

  This example code is in the public domain.

#include <ArduinoBLE.h>


#define BLE_UUID_TEXT_SERVICE                     "F7550000-4CC1-77AB-E173-3C14C2B87ADB"
#define BLE_UUID_TEXT                             "F7550001-4CC1-77AB-E173-3C14C2B87ADB"

// BLE

#define BLE_DEVICE_NAME                           "Arduino RP2040"
#define BLE_LOCAL_NAME                            "Arduino RP2040"

#define TEXT_LENGTH                               20

typedef struct __attribute__( ( packed ) )
  char bytes[TEXT_LENGTH + 1]; // need one additional char for '\0' termination
  bool updated = false;
} text_data_t;

text_data_t textData = { "Hello Arduino", false };

BLEService textService( BLE_UUID_TEXT_SERVICE );
BLECharacteristic textCharacteristic( BLE_UUID_TEXT, BLERead | BLEWrite, TEXT_LENGTH );

// APP & I/O

#define BLE_LED_PIN                               LED_BUILTIN

void setup()
  Serial.begin( 9600 );
  while ( !Serial );

  Serial.println( "ArduinoBLE Example - Text" );

  pinMode( BLE_LED_PIN, OUTPUT );
  digitalWrite( BLE_LED_PIN, LOW );

  if ( !setupBleMode() )
    Serial.println( "Failed to initialize BLE!" );
    while ( 1 );
    Serial.println( "BLE initialized. Waiting for clients to connect." );

void loop()

void printTask()
  if ( textData.updated )
    Serial.println( textData.bytes );
    textData.updated = false;

bool setupBleMode()
  if ( !BLE.begin() )
    return false;

  // set advertised local name and service UUID
  BLE.setDeviceName( BLE_DEVICE_NAME );
  BLE.setLocalName( BLE_LOCAL_NAME );
  BLE.setAdvertisedService( textService );

  // BLE add characteristics
  textService.addCharacteristic( textCharacteristic );

  // add service
  BLE.addService( textService );

  // set the initial value for the Characteristic
  textCharacteristic.writeValue( textData.bytes, sizeof textData.bytes );

  // set BLE event handlers
  BLE.setEventHandler( BLEConnected, blePeripheralConnectHandler );
  BLE.setEventHandler( BLEDisconnected, blePeripheralDisconnectHandler );

  // set service and characteristic specific event handlers
  textCharacteristic.setEventHandler( BLEWritten, textCharacteristicWrittenHandler );

  // start advertising

  return true;

void bleTask()
  const uint32_t BLE_UPDATE_INTERVAL = 10;
  static uint32_t previousMillis = 0;

  uint32_t currentMillis = millis();
  if ( currentMillis - previousMillis >= BLE_UPDATE_INTERVAL )
    previousMillis = currentMillis;

void textCharacteristicWrittenHandler( BLEDevice central, BLECharacteristic bleCharacteristic )
  uint32_t length = bleCharacteristic.valueLength();
  textCharacteristic.readValue( textData.bytes, length );
  textData.bytes[length] = '\0';
  textData.updated = true;

void blePeripheralConnectHandler( BLEDevice central )
  digitalWrite( BLE_LED_PIN, HIGH );
  Serial.print( F( "Connected to central: " ) );
  Serial.println( central.address() );

void blePeripheralDisconnectHandler( BLEDevice central )
  digitalWrite( BLE_LED_PIN, LOW );
  Serial.print( F( "Disconnected from central: " ) );
  Serial.println( central.address() );