api.md

# ArduinoBLE library

## BLE class

Used to enable the Bluetooth® Low Energy module.

### `BLE.begin()`

Initializes the Bluetooth® Low Energy device.

#### Syntax

```
BLE.begin()

```

#### Parameters

None

#### Returns
- 1 on success
- 0 on failure

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }


```

### `BLE.end()`

Stops the Bluetooth® Low Energy device.

#### Syntax

```
BLE.end()

```

#### Parameters

None

#### Returns
Nothing

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  // ....

  BLE.end();


```

### `BLE.poll()`

Poll for Bluetooth® Low Energy radio events and handle them.

#### Syntax

```
BLE.poll() 
BLE.poll(timeout)

```

#### Parameters

**timeout**: optional timeout in ms, to wait for event. If not specified defaults to 0 ms.

#### Returns
Nothing

#### Example

```arduino

  // assign event handlers for connected, disconnected to peripheral
  BLE.setEventHandler(BLEConnected, blePeripheralConnectHandler);
  BLE.setEventHandler(BLEDisconnected, blePeripheralDisconnectHandler);

  

  BLE.poll();


```

### `BLE.setEventHandler()`

Set the event handler (callback) function that will be called when the specified event occurs.

#### Syntax

```
BLE.setEventHandler(eventType, callback)

```

#### Parameters

- **eventType**: event type (BLEConnected, BLEDisconnected)
- **callback**: function to call when event occurs
#### Returns
Nothing.

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  // ...

  // assign event handlers for connected, disconnected to peripheral
  BLE.setEventHandler(BLEConnected, blePeripheralConnectHandler);
  BLE.setEventHandler(BLEDisconnected, blePeripheralDisconnectHandler);

  


void blePeripheralConnectHandler(BLEDevice central) {
  // central connected event handler
  Serial.print("Connected event, central: ");
  Serial.println(central.address());
}

void blePeripheralDisconnectHandler(BLEDevice central) {
  // central disconnected event handler
  Serial.print("Disconnected event, central: ");
  Serial.println(central.address());
}


```

### `BLE.connected()`

Query if another Bluetooth® Low Energy device is connected

#### Syntax

```
BLE.connected()

```

#### Parameters

None

#### Returns
- **true** if another Bluetooth® Low Energy device is connected, 
- otherwise **false**.

#### Example

```arduino

    // while the central is still connected to peripheral:
    while (BLE.connected()) {

       // ...
    }


```

### `BLE.disconnect()`

Disconnect any Bluetooth® Low Energy devices that are connected

#### Syntax

```
BLE.disconnect()

```

#### Parameters

None

#### Returns
- **true** if any Bluetooth® Low Energy device that was previously connected was disconnected, 
- otherwise **false**.

#### Example

```arduino

  if (BLE.connected()) {
    

    BLE.disconnect();
  }


```

### `BLE.address()`

Query the Bluetooth® address of the Bluetooth® Low Energy device.

#### Syntax

```
BLE.address()

```

#### Parameters

None

#### Returns
- The **Bluetooth® address** of the Bluetooth® Low Energy device (as a String).

#### Example

```arduino

  **String** address = BLE.address();

  Serial.print(“Local address is: “);
  Serial.println(address);


```

### `BLE.rssi()`

Query the RSSI (Received signal strength indication) of the connected Bluetooth® Low Energy device.

#### Syntax

```
BLE.rssi()

```

#### Parameters

None

#### Returns
- The **RSSI** of the connected Bluetooth® Low Energy device, 127 if no Bluetooth® Low Energy device is connected.

#### Example

```arduino

  if (BLE.connected()) {
    

   Serial.print(“RSSI = “);
    Serial.println(BLE.rssi());
  }


```

### `BLE.setAdvertisedServiceUuid()`

Set the advertised service UUID used when advertising.

#### Syntax

```
BLE.setAdvertisedServiceUuid(uuid)

```

#### Parameters

- **uuid:** 16-bit or 128-bit Bluetooth® Low Energy UUID in **String** format

#### Returns
Nothing

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  BLE.setAdvertisedServiceUuid(“19B10000-E8F2-537E-4F6C-D104768A1214");

  // ...  

  // start advertising
  BLE.advertise();


```

### `BLE.setAdvertisedService()`

Set the advertised service UUID used when advertising to the value of the BLEService provided.

#### Syntax

```
BLE.setAdvertisedService(bleService)

```

#### Parameters

- **bleService:** BLEService to use UUID from

#### Returns
Nothing

#### Example

```arduino

BLEService ledService("19B10000-E8F2-537E-4F6C-D104768A1214"); // Bluetooth® Low Energy LED Service

// ...

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  BLE.setAdvertisedService(ledService);

  // ...  

  // start advertising
  BLE.advertise();


```

### `BLE.setManufacturerData()`

Set the manufacturer data value used when advertising.

#### Syntax

```
BLE.setManufacturerData(data, length)

```

#### Parameters

- **data:** byte array containing manufacturer data
- **length:** length of manufacturer data array

#### Returns
Nothing

#### Example

```arduino

 // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  byte data[5] = { 0x01, 0x02, 0x03, 0x04, 0x05};

  BLE.setManufacturerData(data, 5);

  // ...  

  // start advertising
  BLE.advertise();



```

### `BLE.setLocalName()`

Set the local value used when advertising.

#### Syntax

```
BLE.setLocalName(name)

```

#### Parameters

- **name:** local name value to use when advertising

#### Returns
Nothing

#### Example

```arduino

 // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  BLE.setLocalName("LED");

  // ...  

  // start advertising
  BLE.advertise();



```

### `BLE.setDeviceName()`

Set the device name in the built in device name characteristic. If not set, the value defaults “Arduino”.

#### Syntax

```
BLE.setDeviceName(name)

```

#### Parameters

- **name:** device name value

#### Returns
Nothing

#### Example

```arduino

 // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  BLE.setDeviceName("LED");

  // ...  

  // start advertising
  BLE.advertise();



```

### `BLE.setAppearance()`

Set the appearance in the built in appearance characteristic. If not set, the value defaults 0x0000.

#### Syntax

```
BLE.setAppearance(appearance)

```

#### Parameters

- **appearance:** appearance value

#### Returns
Nothing

#### Example

```arduino

 // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  BLE.setAppearance(0x8000);

  // ...  

  // start advertising
  BLE.advertise();



```

### `BLE.addService()`

Add a BLEService to the set of services the Bluetooth® Low Energy device provides

#### Syntax

```
BLE.addService(service)

```

#### Parameters

- **service:** BLEService to add

#### Returns
Nothing

#### Example

```arduino

BLEService ledService("19B10000-E8F2-537E-4F6C-D104768A1214"); // Bluetooth® Low Energy LED Service



 // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  // ...

  BLE.addService(ledService);

  // ...  


```

### `BLE.advertise()`

Start advertising.

#### Syntax

```
BLE.advertise()

```

#### Parameters

None

#### Returns
- 1 on success,
- 0 on failure.

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  // ...

  BLE.advertise();

  // ...  


```

### `BLE.stopAdvertise()`

Stop advertising.

#### Syntax

```
BLE.stopAdvertise()

```

#### Parameters

None

#### Returns
Nothing

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  // ...

  BLE.advertise();

  // ...  

  BLE.stopAdvertise();


```

### `BLE.central()`

Query the central Bluetooth® Low Energy device connected.

#### Syntax

```
BLE.central()

```

#### Parameters

None

#### Returns
- **BLEDevice** representing the central.

#### Example

```arduino

  // listen for Bluetooth® Low Energy peripherals to connect:
  BLEDevice central = BLE.central();

  // if a central is connected to peripheral:
  if (central) {
    Serial.print("Connected to central: ");
    // print the central's MAC address:
    Serial.println(central.address());

    
  }


```

### `BLE.setAdvertisingInterval()`

Set the advertising interval in units of 0.625 ms. Defaults to 100ms (160 * 0.625 ms) if not provided.

#### Syntax

```
BLE.setAdvertisingInterval(advertisingInterval)

```

#### Parameters

- **advertisingInterval:** advertising interval in units of 0.625 ms

#### Returns
Nothing.

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  // ...

  BLE.setAdvertisingInterval(320); // 200 * 0.625 ms

  BLE.advertise();


```

### `BLE.setConnectionInterval()`

Set the minimum and maximum desired connection intervals in units of 1.25 ms.

#### Syntax

```
BLE.setConnectionInterval(minimum, maximum)

```

#### Parameters

- **minimum:** minimum desired connection interval in units of 1.25 ms
- **maximum:** maximum desired connection interval in units of 1.25 ms

#### Returns
Nothing.

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  // ...

  BLE.setConnectionInterval(0x0006, 0x0c80); // 7.5 ms minimum, 4 s maximum



```

### `BLE.setConnectable()`

Set if the device is connectable after advertising, defaults to **true**.

#### Syntax

```
BLE.setConnectable(connectable)

```

#### Parameters

- **true**: the device will be connectable when advertising
- **false**: the device will NOT be connectable when advertising

#### Returns
Nothing.

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  // ...

  BLE.setConnectable(false); // make the device unconnectable when advertising



```

### `BLE.scan()`

Start scanning for Bluetooth® Low Energy devices that are advertising.

#### Syntax

```
BLE.scan()
BLE.scan(withDuplicates)

```

#### Parameters

- **withDuplicates:** optional, defaults to **false**. If **true**, advertisements received more than once will not be filtered

#### Returns
- 1 on success, 
- 0 on failure.

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  Serial.println("BLE Central scan");

  // start scanning for peripheral
  BLE.scan();

  

  BLEDevice peripheral = BLE.available();

  if (peripheral) {
     // ...
  }


```

### `BLE.scanForName()`

Start scanning for Bluetooth® Low Energy devices that are advertising with a particular (local) name.

#### Syntax

```
BLE.scanForName(name)
BLE.scanForName(name, withDuplicates)

```

#### Parameters

-  **name:** (local) name of device (as a **String**) to filter for
- **withDuplicates:** optional, defaults to **false**. If **true**, advertisements received more than once will not be filtered.

#### Returns
- 1 on success,
- 0 on failure.

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  Serial.println("BLE Central scan");

  // start scanning for peripheral
  BLE.scanForName("LED");

  

  BLEDevice peripheral = BLE.available();

  if (peripheral) {
     // ...
  }


```

### `BLE.scanForAddress()`

Start scanning for Bluetooth® Low Energy devices that are advertising with a particular (Bluetooth®) address.

#### Syntax

```
BLE.scanForAddress(address)
BLE.scanForAddress(address, withDuplicates)

```

#### Parameters

- **address:** (Bluetooth®) address (as a String) to filter for
- **withDuplicates:** optional, defaults to **false**. If **true**, advertisements received more than once will not be filtered

#### Returns
- 1 on success, 
- 0 on failure.

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  Serial.println("BLE Central scan");

  // start scanning for peripheral
  BLE.scanForAddress("aa:bb:cc:ee:dd:ff");

  

  BLEDevice peripheral = BLE.available();

  if (peripheral) {
     // ...
  }


```

### `BLE.scanForUuid()`

Start scanning for Bluetooth® Low Energy devices that are advertising with a particular (service) UUID.

#### Syntax

```
BLE.scanForUuid(uuid)
BLE.scanForUuid(uuid, withDuplicates)

```

#### Parameters

- **uuid:** (service) UUID (as a **String**) to filter for
- **withDuplicates:** optional, defaults to **false**. If **true**, advertisements received more than once will not be filtered.

#### Returns
- 1 on success,
- 0 on failure.

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  Serial.println("BLE Central scan");

  // start scanning for peripheral
  BLE.scanForUuid("aa10");

  

  BLEDevice peripheral = BLE.available();

  if (peripheral) {
     // ...
  }


```

### `BLE.stopScan()`

Stop scanning for Bluetooth® Low Energy devices that are advertising.

#### Syntax

```
BLE.stopScan()

```

#### Parameters

None

#### Returns
Nothing

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  Serial.println("BLE Central scan");

  // start scanning for peripheral
  BLE.scan();

  
  BLE.stopScan();


```

### `BLE.available()`

Query for a discovered Bluetooth® Low Energy device that was found during scanning.

#### Syntax

```
BLE.available()

```

#### Parameters

Nothing

#### Returns
- **BLEDevice** representing the discovered device.

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  Serial.println("BLE Central scan");

  // start scanning for peripheral
  BLE.scan();

  

  BLEDevice peripheral = BLE.available();

  if (peripheral) {
     // ...
  }


```

## BLEDevice Class

Used to get information about the devices connected or discovered while scanning

### `bleDevice.poll()`

Poll for Bluetooth® Low Energy radio events for the specified Bluetooth® Low Energy device and handle them.

#### Syntax

```
bleDevice.poll()
bleDevice.poll(timeout)

```

#### Parameters

- **timeout**: optional timeout in ms, to wait for event. If not specified defaults to 0 ms.

#### Returns
Nothing

#### Example

```arduino

  // listen for Bluetooth® Low Energy centrals to connect:
  BLEDevice central = BLE.central();

  // if a central is connected to peripheral:
  if (central) {
    

   central.poll();

    // ...
  }


```

### `bleDevice.connected()`

Query if a Bluetooth® Low Energy device is connected

#### Syntax

```
bleDevice.connected()

```

#### Parameters

None

#### Returns
- **true** if the Bluetooth® Low Energy device is connected,
- otherwise **false**.

#### Example

```arduino

  // listen for Bluetooth® Low Energy centrals to connect:
  BLEDevice central = BLE.central();

    // while the central is still connected
    while (central.connected()) {

       // ...
    }


```

### `bleDevice.disconnect()`

Disconnect the Bluetooth® Low Energy device, if connected

#### Syntax

```
bleDevice.disconnect()

```

#### Parameters

None

#### Returns
- **true** if the Bluetooth® Low Energy device was disconnected,
- otherwise **false**.

#### Example

```arduino

 // listen for Bluetooth® Low Energy centrals to connect:
  BLEDevice central = BLE.central();

  

  central.disconnect();


```

### `bleDevice.address()`

Query the Bluetooth® address of the Bluetooth® Low Energy device.

#### Syntax

```
bleDevice.address()

```

#### Parameters

None

#### Returns
- **Bluetooth® address** of the Bluetooth® Low Energy device (as a String).

#### Example

```arduino

  // listen for Bluetooth® Low Energy peripherals to connect:
  BLEDevice central = BLE.central();

  // if a central is connected to peripheral:
  if (central) {
    Serial.print("Connected to central: ");
    // print the central's MAC address:
    Serial.println(central.address());

    .
  }


```

### `bleDevice.rssi()`

Query the RSSI (Received signal strength indication) of the Bluetooth® Low Energy device.

#### Syntax

```
bleDevice.rssi()

```

#### Parameters

None

#### Returns
- **RSSI** of the connected Bluetooth® Low Energy device, 127 if the Bluetooth® Low Energy device is not connected.

#### Example

```arduino

  if (bleDevice.connected()) {
    

    Serial.print(“RSSI = “);
    Serial.println(bleDevice.rssi());
  }


```

### `bleDevice.characteristic()`

Get a BLECharacteristic representing a Bluetooth® Low Energy characteristic the device provides.

#### Syntax

```
bleDevice.characteristic(index)
bleDevice.characteristic(uuid)
bleDevice.characteristic(uuid, index)

```

#### Parameters

- **index**: index of characteristic
- **uuid**: uuid (as a **String**)

#### Returns
- **BLECharacteristic** for provided parameters

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  Serial.println("BLE Central scan");

  // start scanning for peripheral
  BLE.scan();

  

  BLEDevice peripheral = BLE.available();

  if (peripheral) {
    // ...

    Serial.println("Connecting ...");

    if (peripheral.connect()) {
      Serial.println("Connected");
    } else {
      Serial.println("Failed to connect!");
      return;
    }

    // discover peripheral attributes
    Serial.println("Discovering attributes ...");
    if (peripheral.discoverAttributes()) {
      Serial.println("Attributes discovered");
    } else {
      Serial.println("Attribute discovery failed!");
      peripheral.disconnect();
      return;
    }

    BLECharacteristic batteryLevelCharacterisic = peripheral.characteristic("2a19");

    if (batteryLevelCharacterisic) {
      // use the characteristic
    } else {
      Serial.println("Peripheral does NOT have battery level characteristic");
    }

    // ...
  }


```

### `bleDevice.discoverAttributes()`

Discover all of the attributes of Bluetooth® Low Energy device.

#### Syntax

```
bleDevice.discoverAttributes()

```

#### Parameters

None

#### Returns
- **true**, if successful, 
- **false** on failure.

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  Serial.println("BLE Central scan");

  // start scanning for peripheral
  BLE.scan();

  

  BLEDevice peripheral = BLE.available();

  if (peripheral) {
    // ...

    Serial.println("Connecting ...");

    if (peripheral.connect()) {
      Serial.println("Connected");
    } else {
      Serial.println("Failed to connect!");
      return;
    }

    // discover peripheral attributes
    Serial.println("Discovering attributes ...");
    if (peripheral.discoverAttributes()) {
      Serial.println("Attributes discovered");
    } else {
      Serial.println("Attribute discovery failed!");
      peripheral.disconnect();
      return;
    }

    // ...
  }


```

### `bleDevice.discoverService()`

Discover the attributes of a particular service on the Bluetooth® Low Energy device.

#### Syntax

```
bleDevice.discoverService(serviceUuid)

```

#### Parameters

- **serviceUuid:** service UUID to discover (as a **String**)

#### Returns
- **true**, if successful,
- **false** on failure.

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  Serial.println("BLE Central scan");

  // start scanning for peripheral
  BLE.scan();

  

  BLEDevice peripheral = BLE.available();

  if (peripheral) {
    // ...

    Serial.println("Connecting ...");

    if (peripheral.connect()) {
      Serial.println("Connected");
    } else {
      Serial.println("Failed to connect!");
      return;
    }

    // discover service attributes
    Serial.println("Discovering service attributes ...");
    if (peripheral.serviceUuid("fffe")) {
      Serial.println("Service attributes discovered");
    } else {
      Serial.println("Service attribute discovery failed!");
      peripheral.disconnect();
      return;
    }

    // ...
  }


```

### `bleDevice.deviceName()`

Query the device name (BLE characteristic UUID 0x2a00) of a Bluetooth® Low Energy device.

#### Syntax

```
bleDevice.deviceName()

```

#### Parameters

None

#### Returns
- **Device name** (as a String).

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  Serial.println("BLE Central scan");

  // start scanning for peripheral
  BLE.scan();

  

  BLEDevice peripheral = BLE.available();

  if (peripheral) {
    // ...

    Serial.println("Connecting ...");

    if (peripheral.connect()) {
      Serial.println("Connected");
    } else {
      Serial.println("Failed to connect!");
      return;
    }

    // discover peripheral attributes
    Serial.println("Discovering attributes ...");
    if (peripheral.discoverAttributes()) {
      Serial.println("Attributes discovered");
    } else {
      Serial.println("Attribute discovery failed!");
      peripheral.disconnect();
      return;
    }

    // read and print device name of peripheral
    Serial.println();
    Serial.print("Device name: ");
    Serial.println(peripheral.deviceName());
    Serial.print("Appearance: 0x");
    Serial.println(peripheral.appearance(), HEX);
    Serial.println();

    // ...
  }


```

### `bleDevice.appearance()`

Query the appearance (BLE characteristic UUID 0x2a01) of a Bluetooth® Low Energy device.

#### Syntax

```
bleDevice.appearance()

```

#### Parameters

None

#### Returns
- **Appearance value** (as a number).

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  Serial.println("BLE Central scan");

  // start scanning for peripheral
  BLE.scan();

  

  BLEDevice peripheral = BLE.available();

  if (peripheral) {
    // ...

    Serial.println("Connecting ...");

    if (peripheral.connect()) {
      Serial.println("Connected");
    } else {
      Serial.println("Failed to connect!");
      return;
    }

    // discover peripheral attributes
    Serial.println("Discovering attributes ...");
    if (peripheral.discoverAttributes()) {
      Serial.println("Attributes discovered");
    } else {
      Serial.println("Attribute discovery failed!");
      peripheral.disconnect();
      return;
    }

    // read and print device name of peripheral
    Serial.println();
    Serial.print("Device name: ");
    Serial.println(peripheral.deviceName());
    Serial.print("Appearance: 0x");
    Serial.println(peripheral.appearance(), HEX);
    Serial.println();

    // ...
  }


```

### `bleDevice.serviceCount()`

Query the number of services discovered for the Bluetooth® Low Energy device.

#### Syntax

```
bleDevice.serviceCount()

```

#### Parameters

None

#### Returns
- The number of **services discovered** for the Bluetooth® Low Energy device.

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  Serial.println("BLE Central scan");

  // start scanning for peripheral
  BLE.scan();

  

  BLEDevice peripheral = BLE.available();

  if (peripheral) {
    // ...

    Serial.println("Connecting ...");

    if (peripheral.connect()) {
      Serial.println("Connected");
    } else {
      Serial.println("Failed to connect!");
      return;
    }

    // discover peripheral attributes
    Serial.println("Discovering attributes ...");
    if (peripheral.discoverAttributes()) {
      Serial.println("Attributes discovered");
    } else {
      Serial.println("Attribute discovery failed!");
      peripheral.disconnect();
      return;
    }

    int serviceCount = peripheral.serviceCount();

    Serial.print(serviceCount);
    Serial.println(" services discovered");

    // ...
  }


```

### `bleDevice.hasService()`

Query if the Bluetooth® Low Energy device has a particular service.

#### Syntax

```
bleDevice.hasService(uuid)
bleDevice.hasService(uuid, index)

```

#### Parameters

- **uuid**: uuid to check (as a **String**)
- **index**: optional, index of service to check if the device provides more than on. Defaults to 0, if not provided.

#### Returns
- **true**, if the device provides the service,
- **false** otherwise.

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  Serial.println("BLE Central scan");

  // start scanning for peripheral
  BLE.scan();

  

  BLEDevice peripheral = BLE.available();

  if (peripheral) {
    // ...

    Serial.println("Connecting ...");

    if (peripheral.connect()) {
      Serial.println("Connected");
    } else {
      Serial.println("Failed to connect!");
      return;
    }

    // discover peripheral attributes
    Serial.println("Discovering attributes ...");
    if (peripheral.discoverAttributes()) {
      Serial.println("Attributes discovered");
    } else {
      Serial.println("Attribute discovery failed!");
      peripheral.disconnect();
      return;
    }

    if (peripheral.hasService("180f")) {
      Serial.println("Peripheral has battery service");
    }

    // ...
  }


```

### `bleDevice.service()`

Get a BLEService representing a Bluetooth® Low Energy service the device provides.

#### Syntax

```
bleDevice.service(index)
bleDevice.service(uuid)
bleDevice.service(uuid, index)

```

#### Parameters

- **index**: index of service
- **uuid**: uuid (as a **String**)

#### Returns
- **BLEService** for provided parameters

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  Serial.println("BLE Central scan");

  // start scanning for peripheral
  BLE.scan();

  

  BLEDevice peripheral = BLE.available();

  if (peripheral) {
    // ...

    Serial.println("Connecting ...");

    if (peripheral.connect()) {
      Serial.println("Connected");
    } else {
      Serial.println("Failed to connect!");
      return;
    }

    // discover peripheral attributes
    Serial.println("Discovering attributes ...");
    if (peripheral.discoverAttributes()) {
      Serial.println("Attributes discovered");
    } else {
      Serial.println("Attribute discovery failed!");
      peripheral.disconnect();
      return;
    }

    BLEService batteryService = peripheral.service("180f");

    if (batteryService) {
      // use the service
    } else {
      Serial.println("Peripheral does NOT have battery service");
    }

    // ...
  }


```

### `bleDevice.characteristicCount()`

Query the number of characteristics discovered for the Bluetooth® Low Energy device.

#### Syntax

```
bleDevice.characteristicCount()

```

#### Parameters

None

#### Returns
- The **number of characteristics** discovered for the Bluetooth® Low Energy device.

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  Serial.println("BLE Central scan");

  // start scanning for peripheral
  BLE.scan();

  

  BLEDevice peripheral = BLE.available();

  if (peripheral) {
    // ...

    Serial.println("Connecting ...");

    if (peripheral.connect()) {
      Serial.println("Connected");
    } else {
      Serial.println("Failed to connect!");
      return;
    }

    // discover peripheral attributes
    Serial.println("Discovering attributes ...");
    if (peripheral.discoverAttributes()) {
      Serial.println("Attributes discovered");
    } else {
      Serial.println("Attribute discovery failed!");
      peripheral.disconnect();
      return;
    }

    int characteristicCount = peripheral.characteristicCount();

    Serial.print(characteristicCount);
    Serial.println(" characteristis discovered");

    // ...
  }


```

### `bleDevice.hasCharacteristic()`

Query if the Bluetooth® Low Energy device has a particular characteristic.

#### Syntax

```
bleDevice.hasCharacteristic(uuid)
bleDevice.hasCharacteristic(uuid, index)

```

#### Parameters

- **uuid**: uuid to check (as a **String**)
- **index**: optional, index of characteristic to check if the device provides more than on. Defaults to 0, if not provided.

#### Returns
- **true**, if the device provides the characteristic, 
- **false** otherwise.

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  Serial.println("BLE Central scan");

  // start scanning for peripheral
  BLE.scan();

  

  BLEDevice peripheral = BLE.available();

  if (peripheral) {
    // ...

    Serial.println("Connecting ...");

    if (peripheral.connect()) {
      Serial.println("Connected");
    } else {
      Serial.println("Failed to connect!");
      return;
    }

    // discover peripheral attributes
    Serial.println("Discovering attributes ...");
    if (peripheral.discoverAttributes()) {
      Serial.println("Attributes discovered");
    } else {
      Serial.println("Attribute discovery failed!");
      peripheral.disconnect();
      return;
    }

    if (peripheral.hasCharacteristic("2a19")) {
      Serial.println("Peripheral has battery level characteristic");
    }

    // ...
  }


```

### `bleDevice.hasLocalName()`

Query if a discovered Bluetooth® Low Energy device is advertising a local name.

#### Syntax

```
bleDevice.hasLocalName()

```

#### Parameters

Nothing

#### Returns
- **true**, if the device is advertising a local name, 
- **false** otherwise.

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  Serial.println("BLE Central scan");

  // start scanning for peripheral
  BLE.scan();

  

  BLEDevice peripheral = BLE.available();

  if (peripheral) {
    // ...

    // print the local name, if present
    if (peripheral.hasLocalName()) {
      Serial.print("Local Name: ");
      Serial.println(peripheral.localName());
    }

    // ...
  }


```

### `bleDevice.hasAdvertisedServiceUuid()`

Query if a discovered Bluetooth® Low Energy device is advertising a service UUID.

#### Syntax

```
bleDevice.hasAdvertisedServiceUuid()
bleDevice.hasAdvertisedServiceUuid(index)

```

#### Parameters

- **index**: optional, defaults to 0, the index of the service UUID, if the device is advertising more than one.

#### Returns
- **true**, if the device is advertising a service UUID, 
- **false** otherwise.

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  Serial.println("BLE Central scan");

  // start scanning for peripheral
  BLE.scan();

  

  BLEDevice peripheral = BLE.available();

  if (peripheral) {
    // ...

    // print the advertised service UUIDs, if present
    if (peripheral.hasAdvertisedServiceUuid()) {
      Serial.print("Service UUIDs: ");
      for (int i = 0; i < peripheral.advertisedServiceUuidCount(); i++) {
        Serial.print(peripheral.advertisedServiceUuid(i));
        Serial.print(" ");
      }
      Serial.println();
    }

    // ...
  }


```

### `bleDevice.advertisedServiceUuidCount()`

Query the number of advertised services a discovered Bluetooth® Low Energy device is advertising.

#### Syntax

```
bleDevice.advertisedServiceUuidCount()

```

#### Parameters

None

#### Returns
- The **number of advertised services** a discovered Bluetooth® Low Energy device is advertising.

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  Serial.println("BLE Central scan");

  // start scanning for peripheral
  BLE.scan();

  

  BLEDevice peripheral = BLE.available();

  if (peripheral) {
    // ...

    // print the advertised service UUIDs, if present
    if (peripheral.hasAdvertisedServiceUuid()) {
      Serial.print("Service UUIDs: ");
      for (int i = 0; i < peripheral.advertisedServiceUuidCount(); i++) {
        Serial.print(peripheral.advertisedServiceUuid(i));
        Serial.print(" ");
      }
      Serial.println();
    }

    // ...
  }


```

### `bleDevice.localName()`

Query the local name a discovered Bluetooth® Low Energy device is advertising with.

#### Syntax

```
bleDevice.localName()

```

#### Parameters

Nothing

#### Returns
- **Advertised local name** (as a String).

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  Serial.println("BLE Central scan");

  // start scanning for peripheral
  BLE.scan();

  

  BLEDevice peripheral = BLE.available();

  if (peripheral) {
    // ...

    // print the local name, if present
    if (peripheral.hasLocalName()) {
      Serial.print("Local Name: ");
      Serial.println(peripheral.localName());
    }

    // ...
  }


```

### `bleDevice.advertisedServiceUuid()`

Query an advertised service UUID discovered Bluetooth® Low Energy device is advertising.

#### Syntax

```
bleDevice.advertisedServiceUuid()
bleDevice.advertisedServiceUuid(index)

```

#### Parameters

- **index**: optional, defaults to 0, the index of the **service UUID**, if the device is advertising more than one.

#### Returns
- Advertised service **UUID** (as a String).

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  Serial.println("BLE Central scan");

  // start scanning for peripheral
  BLE.scan();

  

  BLEDevice peripheral = BLE.available();

  if (peripheral) {
    // ...

    // print the advertised service UUIDs, if present
    if (peripheral.hasAdvertisedServiceUuid()) {
      Serial.print("Service UUIDs: ");
      for (int i = 0; i < peripheral.advertisedServiceUuidCount(); i++) {
        Serial.print(peripheral.advertisedServiceUuid(i));
        Serial.print(" ");
      }
      Serial.println();
    }

    // ...
  }


```

### `bleDevice.connect()`

Connect to a Bluetooth® Low Energy device.

#### Syntax

```
bleDevice.connect()

```

#### Parameters

None

#### Returns
- **true**, if the connection was successful, 
- **false** otherwise.

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  Serial.println("BLE Central scan");

  // start scanning for peripheral
  BLE.scan();

  

  BLEDevice peripheral = BLE.available();

  if (peripheral) {
    // ...

    Serial.println("Connecting ...");

    if (peripheral.connect()) {
      Serial.println("Connected");
    } else {
      Serial.println("Failed to connect!");
      return;
    }

    // ...
  }


```

## BLEService Class

Used to enable the services board provides or interact with services a remote board provides.

### `BLEService()`

Create a new Bluetooth® Low Energy service.

#### Syntax

```
BLEService(uuid)

```

#### Parameters

- **uuid**: 16-bit or 128-bit UUID in **String** format

#### Returns
- New **BLEService** with the specified **UUID**

#### Example

```arduino

BLEService ledService("19B10000-E8F2-537E-4F6C-D104768A1214"); // Bluetooth® Low Energy LED Service


```

### `bleService.uuid()`

Query the UUID of the specified BLEService.

#### Syntax

```
bleService.uuid()

```

#### Parameters

None

#### Returns
- UUID of the Bluetooth® Low Energy service as a **String**.

#### Example

```arduino

BLEService ledService("19B10000-E8F2-537E-4F6C-D104768A1214"); // Bluetooth® Low Energy LED Service


Serial.print(“LED service UUID = “);
Serial.println(ledService.uuid());



```

### `bleService.addCharacteristic()`

Add a BLECharateristic to the Bluetooth® Low Energy service.

#### Syntax

```
bleService.addCharacteristic(bleCharacteristic)

```

#### Parameters

None

#### Returns
Nothing

#### Example

```arduino

BLEService ledService("19B10000-E8F2-537E-4F6C-D104768A1214"); // Bluetooth® Low Energy LED Service

// Bluetooth® Low Energy LED Switch Characteristic - custom 128-bit UUID, readable and writable by central
BLECharacteristic switchCharacteristic("19B10001-E8F2-537E-4F6C-D104768A1214", BLERead | BLEWrite, 1);




// add the characteristic to the service
ledService.addCharacteristic(switchCharacteristic);



```

### `bleService.characteristicCount()`

Query the number of characteristics discovered for the Bluetooth® Low Energy service.

#### Syntax

```
bleService.characteristicCount()

```

#### Parameters

None

#### Returns
- The **number of characteristics** discovered for the Bluetooth® Low Energy service.

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  Serial.println("BLE Central scan");

  // start scanning for peripheral
  BLE.scan();

  

  BLEDevice peripheral = BLE.available();

  if (peripheral) {
    // ...

    Serial.println("Connecting ...");

    if (peripheral.connect()) {
      Serial.println("Connected");
    } else {
      Serial.println("Failed to connect!");
      return;
    }

    // discover peripheral attributes
    Serial.println("Discovering attributes ...");
    if (peripheral.discoverAttributes()) {
      Serial.println("Attributes discovered");
    } else {
      Serial.println("Attribute discovery failed!");
      peripheral.disconnect();
      return;
    }

    BLEService batteryService = peripheral.service("180f");

    if (batteryService) {
      // use the service
      int characteristicCount = batteryService.characteristicCount();

      Serial.print(characteristicCount);
      Serial.println(" characteristics discovered in battery service");
    } else {
      Serial.println("Peripheral does NOT have battery service");
    }

    // ...
  }


```

### `bleService.hasCharacteristic()`

Query if the Bluetooth® Low Energy service has a particular characteristic.

#### Syntax

```
bleService.hasCharacteristic(uuid)
bleService.hasCharacteristic(uuid, index)

```

#### Parameters

- **uuid**: uuid to check (as a **String**)
- **index**: optional, index of characteristic to check if the device provides more than on. Defaults to 0, if not provided.

#### Returns
- **true**, if the service provides the characteristic,
- **false** otherwise.

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  Serial.println("BLE Central scan");

  // start scanning for peripheral
  BLE.scan();

  
  BLEDevice peripheral = BLE.available();

  if (peripheral) {
    // ...

    Serial.println("Connecting ...");

    if (peripheral.connect()) {
      Serial.println("Connected");
    } else {
      Serial.println("Failed to connect!");
      return;
    }

    // discover peripheral attributes
    Serial.println("Discovering attributes ...");
    if (peripheral.discoverAttributes()) {
      Serial.println("Attributes discovered");
    } else {
      Serial.println("Attribute discovery failed!");
      peripheral.disconnect();
      return;
    }

    BLEService batteryService = peripheral.service("180f");

    if (batteryService) {
      // use the service
      if (batteryService.hasCharacteristic("2a19")) {
        Serial.println("Battery service has battery level characteristic");
      }
    } else {
      Serial.println("Peripheral does NOT have battery service");
    }

    // ...
  }


```

### `bleService.characteristic()`

Get a BLECharacteristic representing a Bluetooth® Low Energy characteristic the service provides.

#### Syntax

```
bleService.characteristic(index)
bleService.characteristic(uuid)
bleService.characteristic(uuid, index)

```

#### Parameters

- **index**: index of characteristic
- **uuid**: uuid (as a **String**)

#### Returns
- **BLECharacteristic** for provided parameters

#### Example

```arduino

  // begin initialization
  if (!BLE.begin()) {
    Serial.println("starting Bluetooth® Low Energy module failed!");

    while (1);
  }

  Serial.println("BLE Central scan");

  // start scanning for peripheral
  BLE.scan();

  

  BLEDevice peripheral = BLE.available();

  if (peripheral) {
    // ...

    Serial.println("Connecting ...");

    if (peripheral.connect()) {
      Serial.println("Connected");
    } else {
      Serial.println("Failed to connect!");
      return;
    }

    // discover peripheral attributes
    Serial.println("Discovering attributes ...");
    if (peripheral.discoverAttributes()) {
      Serial.println("Attributes discovered");
    } else {
      Serial.println("Attribute discovery failed!");
      peripheral.disconnect();
      return;
    }

    BLEService batteryService = peripheral.service("180f");

    if (batteryService) {
      // use the service
      BLECharacteristic batteryLevelCharacterisic = peripheral.characteristic("2a19");

      if (batteryLevelCharacterisic) {
        // use the characteristic
      } else {
        Serial.println("Peripheral does NOT have battery level characteristic");
      }
    } else {
      Serial.println("Peripheral does NOT have battery service");
    }

    // ...
  }


```

## BLECharacteristic Class

Used to enable the characteristics board offers in a service or interact with characteristics a remote board provides.

### `BLECharacteristic()`

Create a new Bluetooth® Low Energy characteristic.

#### Syntax

```
BLECharacteristic(uuid, properties, value, valueSize)
BLECharacteristic(uuid, properties, stringValue)

BLEBoolCharacteristic(uuid, properties)
BLEBooleanCharacteristic(uuid, properties)
BLECharCharacteristic(uuid, properties)
BLEUnsignedCharCharacteristic(uuid, properties)
BLEByteCharacteristic(uuid, properties)
BLEShortCharacteristic(uuid, properties)
BLEUnsignedShortCharacteristic(uuid, properties)
BLEWordCharacteristic(uuid, properties)
BLEIntCharacteristic(uuid, properties)
BLEUnsignedIntCharacteristic(uuid, properties)
BLELongCharacteristic(uuid, properties)
BLEUnsignedLongCharacteristic(uuid, properties)
BLEFloatCharacteristic(uuid, properties)
BLEDoubleCharacteristic(uuid, properties)
```

#### Parameters

- **uuid**: 16-bit or 128-bit UUID in **String** format
- **properties**: mask of the properties (BLEBroadcast, BLERead, BLEWriteWithoutResponse, BLEWrite, BLENotify, BLEIndicate)
- **valueSize**: (maximum) size of characteristic value
- **stringValue**: value as a string

#### Returns
- New **BLECharacteristic** with the specified **UUID** and value

#### Example

```arduino

// Bluetooth® Low Energy Battery Level Characteristic
BLEUnsignedCharCharacteristic batteryLevelChar("2A19",  // standard 16-bit characteristic UUID
    BLERead | BLENotify); // remote clients will be able to get notifications if this characteristic changes



```

### `bleCharacteristic.uuid()`

Query the UUID of the specified BLECharacteristic.

#### Syntax

```
bleCharacteristic.uuid()

```

#### Parameters

None

#### Returns
- **UUID** of the Bluetooth® Low Energy service as a **String**.

#### Example

```arduino

// Bluetooth® Low Energy LED Switch Characteristic - custom 128-bit UUID, read and writable by central
BLEByteCharacteristic switchCharacteristic("19B10001-E8F2-537E-4F6C-D104768A1214", BLERead | BLEWrite);


Serial.print(“Switch characteristic UUID = “);
Serial.println(switchCharacteristic.uuid());



```

### `bleCharacteristic.properties()`

Query the property mask of the specified BLECharacteristic.

#### Syntax

```
bleCharacteristic.properties()

```

#### Parameters

None

#### Returns
- **Properties of the characteristic masked** (BLEBroadcast, BLERead, BLEWriteWithoutResponse, BLEWrite, BLENotify, BLEIndicate)

#### Example

```arduino

// Bluetooth® Low Energy LED Switch Characteristic - custom 128-bit UUID, read and writable by central
BLEByteCharacteristic switchCharacteristic("19B10001-E8F2-537E-4F6C-D104768A1214", BLERead | BLEWrite);


byte properties = switchCharacteristic.properties();

if (properties & BLERead) {
  // characteristic is readable ...
}

if (properties & (BLEWrite | BLEWriteWithoutResponse)) {
  // characteristic is writable ...
}


```

### `bleCharacteristic.valueSize()`

Query the maximum value size of the specified BLECharacteristic.

#### Syntax

```
bleCharacteristic.valueSize()

```

#### Parameters

None

#### Returns
- The **maximum value** size of the characteristic (in bytes)

#### Example

```arduino

// Bluetooth® Low Energy LED Switch Characteristic - custom 128-bit UUID, read and writable by central
BLEByteCharacteristic switchCharacteristic("19B10001-E8F2-537E-4F6C-D104768A1214", BLERead | BLEWrite);



Serial.print(“value size = “);
Serial.println(switchCharacteristic.valueSize());


```

### `bleCharacteristic.value()`

Query the current value of the specified BLECharacteristic.

#### Syntax

```
bleCharacteristic.value()

```

#### Parameters

None

#### Returns
- The **current value** of the characteristic, value type depends on the constructor used

#### Example

```arduino

// Bluetooth® Low Energy LED Switch Characteristic - custom 128-bit UUID, read and writable by central
BLEByteCharacteristic switchCharacteristic("19B10001-E8F2-537E-4F6C-D104768A1214", BLERead | BLEWrite);



      if (switchCharacteristic.value()) {   // any value other than 0
          Serial.println("LED on");
          digitalWrite(ledPin, HIGH);         // will turn the LED on
        } else {                              // a 0 value
          Serial.println(F("LED off"));
          digitalWrite(ledPin, LOW);          // will turn the LED off
        }



```

### `bleCharacteristic.valueLength()`

Query the current value size of the specified BLECharacteristic.

#### Syntax

```
bleCharacteristic.valueLength()

```

#### Parameters

None

#### Returns
- The **current value** size of the characteristic (in bytes)

#### Example

```arduino

// Bluetooth® Low Energy LED Switch Characteristic - custom 128-bit UUID, read and writable by central
BLEByteCharacteristic switchCharacteristic("19B10001-E8F2-537E-4F6C-D104768A1214", BLERead | BLEWrite);



Serial.print(“value length = “);
Serial.println(switchCharacteristic.valueLength());


```

### `bleCharacteristic.readValue()`

Read the current value of the characteristic. If the characteristic is on a remote device, a read request will be sent.

#### Syntax

```
bleCharacteristic.readValue(buffer, length)
bleCharacteristic.readValue(value)

```

#### Parameters

- **buffer:** byte array to read value into length: size of buffer argument in bytes 
- **value**: variable to read value into (by reference)

#### Returns
- **Number of bytes** read

#### Example

```arduino

  while (peripheral.connected()) {
    // while the peripheral is connected

    // check if the value of the simple key characteristic has been updated
    if (simpleKeyCharacteristic.valueUpdated()) {
      // yes, get the value, characteristic is 1 byte so use byte value
      byte value = 0;

      simpleKeyCharacteristic.readValue(value);

      if (value & 0x01) {
        // first bit corresponds to the right button
        Serial.println("Right button pressed");
      }

      if (value & 0x02) {
        // second bit corresponds to the left button
        Serial.println("Left button pressed");
      }
    }
  }


```

### `bleCharacteristic.writeValue()`

Write the value of the characteristic. If the characteristic is on a remote device, a write request or command will be sent.

#### Syntax

```
bleCharacteristic.writeValue(buffer, length)
bleCharacteristic.writeValue(value)

```

#### Parameters

- **buffer**: byte array to write value with
- **length**: number of bytes of the buffer argument to write
- **value**: value to write

#### Returns
- 1 on success, 
- 0 on failure

#### Example

```arduino

    // read the button pin
    int buttonState = digitalRead(buttonPin);

    if (oldButtonState != buttonState) {
      // button changed
      oldButtonState = buttonState;

      if (buttonState) {
        Serial.println("button pressed");

        // button is pressed, write 0x01 to turn the LED on
        ledCharacteristic.writeValue((byte)0x01);
      } else {
        Serial.println("button released");

        // button is released, write 0x00 to turn the LED off
        ledCharacteristic.writeValue((byte)0x00);
      }
    }


```

### `bleCharacteristic.setEventHandler()`

Set the event handler (callback) function that will be called when the specified event occurs.

#### Syntax

```
bleCharacteristic.setEventHandler(eventType, callback)

```

#### Parameters

- **eventType**: event type (BLESubscribed, BLEUnsubscribed, BLERead, BLEWritten) 
- **callback**: function to call when the event occurs

#### Returns
Nothing

#### Example

```arduino

// create switch characteristic and allow remote device to read and write
BLEByteCharacteristic switchCharacteristic("19B10001-E8F2-537E-4F6C-D104768A1214", BLERead | BLEWrite);




  // assign event handlers for characteristic
  switchCharacteristic.setEventHandler(BLEWritten, switchCharacteristicWritten);



void switchCharacteristicWritten(BLEDevice central, BLECharacteristic characteristic) {
  // central wrote new value to characteristic, update LED
  Serial.print("Characteristic event, written: ");

  if (switchCharacteristic.value()) {
    Serial.println("LED on");
    digitalWrite(ledPin, HIGH);
  } else {
    Serial.println("LED off");
    digitalWrite(ledPin, LOW);
  }
}

  

```

### `bleCharacteristic.broadcast()`

Broadcast the characteristics value as service data when advertising.

#### Syntax

```
bleCharacteristic.broadcast()

```

#### Parameters

None

#### Returns
- 1 on success,
- 0 on failure

#### Example

```arduino

// create button characteristic and allow remote device to get notifications
BLEByteCharacteristic buttonCharacteristic("19B10012-E8F2-537E-4F6C-D104768A1214", BLERead | BLENotify | BLEBroadcast);



buttonCharacteristic.broadcast();



```

### `bleCharacteristic.written()`

Query if the characteristic value has been written by another Bluetooth® Low Energy device.

#### Syntax

```
bleCharacteristic.written()

```

#### Parameters

None

#### Returns
- **true** if the characteristic value has been written by another Bluetooth® Low Energy device,
- **false** otherwise

#### Example

```arduino

// Bluetooth® Low Energy LED Switch Characteristic - custom 128-bit UUID, read and writable by central
BLEByteCharacteristic switchCharacteristic("19B10001-E8F2-537E-4F6C-D104768A1214", BLERead | BLEWrite);




 // listen for Bluetooth® Low Energy peripherals to connect:
  BLEDevice central = BLE.central();

  // if a central is connected to peripheral:
  if (central) {
    Serial.print("Connected to central: ");
    // print the central's MAC address:
    Serial.println(central.address());

    // while the central is still connected to peripheral:
    while (central.connected()) {
      // if the remote device wrote to the characteristic,
      // use the value to control the LED:
      if (switchCharacteristic.written()) {
        if (switchCharacteristic.value()) {   // any value other than 0
          Serial.println("LED on");
          digitalWrite(ledPin, HIGH);         // will turn the LED on
        } else {                              // a 0 value
          Serial.println(F("LED off"));
          digitalWrite(ledPin, LOW);          // will turn the LED off
        }
      }
    }

    // when the central disconnects, print it out:
    Serial.print(F("Disconnected from central: "));
    Serial.println(central.address());
  }




```

### `bleCharacteristic.subscribed()`

Query if the characteristic has been subscribed to by another Bluetooth® Low Energy device.

#### Syntax

```
bleCharacteristic.subscribed()

```

#### Parameters

None

#### Returns
- **true** if the characteristic value has been subscribed to by another Bluetooth® Low Energy device,
- **false** otherwise

#### Example

```arduino

// Bluetooth® Low Energy Battery Level Characteristic
BLEUnsignedCharCharacteristic batteryLevelChar("2A19",  // standard 16-bit characteristic UUID
    BLERead | BLENotify); // remote clients will be able to get notifications if this characteristic changes





  if (batteryLevelChar.subscribed()) {
     // set a new value , that well be pushed to subscribed Bluetooth® Low Energy devices
    batteryLevelChar.writeValue(0xab);
  }


```

### `bleCharacteristic.addDescriptor()`

Add a BLEDescriptor to the characteristic.

#### Syntax

```
bleCharacteristic.addDescriptor(bleDescriptor)

```

#### Parameters

- **bleDescriptor**: descriptor to add to the characteristic

#### Returns
Nothing

#### Example

```arduino

// Bluetooth® Low Energy Battery Level Characteristic
BLEUnsignedCharCharacteristic batteryLevelChar("2A19",  // standard 16-bit characteristic UUID
    BLERead | BLENotify); // remote clients will be able to get notifications if this characteristic changes

BLEDescriptor batteryLevelDescriptor("2901", "millis");





  batteryLevelChar.addDescriptor(batteryLevelDescriptor);


```

### `bleCharacteristic.descriptorCount()`

Query the number of Bluetooth® Low Energy descriptors discovered for the characteristic.

#### Syntax

```
bleCharacteristic.descriptorCount()

```

#### Parameters

None

#### Returns
- The **number of Bluetooth® Low Energy descriptors** discovered for the characteristic

#### Example

```arduino

 // loop the descriptors of the characteristic and explore each
  for (int i = 0; i < characteristic.descriptorCount(); i++) {
    BLEDescriptor descriptor = characteristic.descriptor(i);

    // ...
  }


```

### `bleCharacteristic.hasDescriptor()`

Check if a characteristic has a particular descriptor.

#### Syntax

```
bleCharacteristic.hasDescriptor(uuid)
bleCharacteristic.hasDescriptor(uuid, index)

```

#### Parameters

- **index**: index of descriptor
- **uuid**: uuid (as a **String**)

#### Returns
- **true**, if the characteristic has a matching descriptor,
- otherwise **false**.

#### Example

```arduino

  if (characteristic.hasDescriptor("2901")) {
    Serial.println("characteristic has description descriptor");
  }


```

### `bleCharacteristic.descriptor()`

Get a BLEDescriptor that represents a characteristics Bluetooth® Low Energy descriptor.

#### Syntax

```
bleCharacteristic.descriptor(index)
bleCharacteristic.descriptor(uuid)
bleCharacteristic.descriptor(uuid, index)

```

#### Parameters

- **index**: index of descriptor
- **uuid**: uuid (as a **String**)

#### Returns
- BLEDescriptor that represents a characteristics Bluetooth® Low Energy descriptor

#### Example

```arduino

  if (characteristic.hasDescriptor("2901")) {
    Serial.println("characteristic has description descriptor");
  }


```

### `bleCharacteristic.canRead()`

Query if a Bluetooth® Low Energy characteristic is readable.

#### Syntax

```
bleCharacteristic.canRead()

```

#### Parameters

None

#### Returns
- **true**, if characteristic is readable, 
- **false** otherwise

#### Example

```arduino

  if (characteristic.canRead("2901")) {
    Serial.println("characteristic is readable");
  }


```

read

Perform a read request for the characteristic.

#### Syntax

```
bleCharacteristic.read()

```

#### Parameters

None

#### Returns
- **true**, if successful, 
- **false** on failure

#### Example

```arduino

  if (characteristic.read()) {
    Serial.println("characteristic value read");

    // ...
  } else {
    Serial.println("error reading characteristic value");
  }


```

### `bleCharacteristic.canWrite()`

Query if a Bluetooth® Low Energy characteristic is writable.

#### Syntax

```
bleCharacteristic.canWrite()

```

#### Parameters

None

#### Returns
- **true**, if characteristic is writable,
- **false** otherwise

#### Example

```arduino

  if (characteristic.canWrite()) {
    Serial.println("characteristic is writable");
  }


```

### `bleCharacteristic.canSubscribe()`

Query if a Bluetooth® Low Energy characteristic is subscribable.

#### Syntax

```
bleCharacteristic.canSubscribe()

```

#### Parameters

None

#### Returns
- **true**, if characteristic is subscribable,
- **false** otherwise

#### Example

```arduino

  if (characteristic.canSubscribe()) {
    Serial.println("characteristic is subscribable");
  }


```

### `bleCharacteristic.subscribe()`

Subscribe to a Bluetooth® Low Energy characteristics notification or indications.

#### Syntax

```
bleCharacteristic.subscribe()

```

#### Parameters

None

#### Returns
- **true**, on success,
- **false** on failure

#### Example

```arduino

  // ...

  // retrieve the simple key characteristic
  BLECharacteristic simpleKeyCharacteristic = peripheral.characteristic("ffe1");

  // subscribe to the simple key characteristic
  Serial.println("Subscribing to simple key characteristic ...");
  if (!simpleKeyCharacteristic) {
    Serial.println("no simple key characteristic found!");
    peripheral.disconnect();
    return;
  } else if (!simpleKeyCharacteristic.canSubscribe()) {
    Serial.println("simple key characteristic is not subscribable!");
    peripheral.disconnect();
    return;
  } else if (!simpleKeyCharacteristic.subscribe()) {
    Serial.println("subscription failed!");
    peripheral.disconnect();
    return;
  }

  // ...


```

### `bleCharacteristic.canUnsubscribe()`

Query if a Bluetooth® Low Energy characteristic is unsubscribable.

#### Syntax

```
bleCharacteristic.canUnsubscribe()

```

#### Parameters

None

#### Returns
- **true**, if characteristic is unsubscribable,
- **false** otherwise

#### Example

```arduino

  if (characteristic.canUnsubscribe()) {
    Serial.println("characteristic is unsubscribable");
  }


```

### `bleCharacteristic.unsubscribe()`

Unsubscribe to a Bluetooth® Low Energy characteristics notifications or indications.

#### Syntax

```
bleCharacteristic.unsubscribe()

```

#### Parameters

None

#### Returns
- **true**, on success,
- **false** on failure

#### Example

```arduino

  // ...

  // retrieve the simple key characteristic
  BLECharacteristic simpleKeyCharacteristic = peripheral.characteristic("ffe1");

  // subscribe to the simple key characteristic
  Serial.println("Subscribing to simple key characteristic ...");
  if (!simpleKeyCharacteristic) {
    Serial.println("no simple key characteristic found!");
    peripheral.disconnect();
    return;
  } else if (!simpleKeyCharacteristic.canSubscribe()) {
    Serial.println("simple key characteristic is not subscribable!");
    peripheral.disconnect();
    return;
  } else if (!simpleKeyCharacteristic.subscribe()) {
    Serial.println("subscription failed!");
    peripheral.disconnect();
    return;
  }

  // ...

  simpleKeyCharacteristic.unsubscribe();


```

### `bleCharacteristic.valueUpdated()`

Has the characteristics value been updated via a notification or indication.

#### Syntax

```
bleCharacteristic.valueUpdated()

```

#### Parameters

None

#### Returns
- **true**, if the characteristics value been updated via a notification or indication

#### Example

```arduino

  while (peripheral.connected()) {
    // while the peripheral is connected

    // check if the value of the simple key characteristic has been updated
    if (simpleKeyCharacteristic.valueUpdated()) {
      // yes, get the value, characteristic is 1 byte so use byte value
      byte value = 0;

      simpleKeyCharacteristic.readValue(value);

      if (value & 0x01) {
        // first bit corresponds to the right button
        Serial.println("Right button pressed");
      }

      if (value & 0x02) {
        // second bit corresponds to the left button
        Serial.println("Left button pressed");
      }
    }
  }


```

## BLEDescriptor Class

Used to describe a characteristic the board offers

### `BLEDescriptor()`

Create a new Bluetooth® Low Energy descriptor.

#### Syntax

```
BLEDescriptor(uuid, value, valueSize)
BLEDescriptor(uuid, stringValue)

```

#### Parameters

- **uuid**: 16-bit or 128-bit UUID in string format
- **value**: byte array value
- **valueSize**: size of byte array value
- **stringValue**: value as a string

#### Returns
- New **BLEDescriptor** with the specified **UUID** and value

#### Example

```arduino

BLEDescriptor millisLabelDescriptor("2901", "millis");


```

### `bleDescriptor.uuid()`

Query the UUID of the specified BLEDescriptor.

#### Syntax

```
bleDescriptor.uuid()

```

#### Parameters

None

#### Returns
- **UUID** of the Bluetooth® Low Energy descriptor (as a String).

#### Example

```arduino

BLEDescriptor millisLabelDescriptor("2901", "millis");


Serial.print(“millis label descriptor UUID = “);
Serial.println(millisLabelDescriptor.uuid());



```

### `bleDescriptor.valueSize()`

Query the value size of the specified BLEDescriptor.

#### Syntax

```
bleDescriptor.valueSize()

```

#### Parameters

None

#### Returns
- **Value size** (in bytes) of the Bluetooth® Low Energy descriptor.

#### Example

```arduino

BLEDescriptor millisLabelDescriptor("2901", "millis");


Serial.print(“millis label descriptor value size = “);
Serial.println(millisLabelDescriptor.valueSize());



```

### `bleDescriptor.valueLength()`

Query the length, in bytes, of the descriptor current value.

#### Syntax

```
bleDescriptor.valueLength()

```

#### Parameters

None

#### Returns
- **Length of descriptor** value in bytes.

#### Example

```arduino

  // read the descriptor value
  descriptor.read();

  // print out the value of the descriptor
  Serial.print(", value 0x");
  printData(descriptor.value(), descriptor.valueLength());

  // ...

  void printData(const unsigned char data[], int length) {
    for (int i = 0; i < length; i++) {
      unsigned char b = data[i];

      if (b < 16) {
        Serial.print("0");
      }

      Serial.print(b, HEX);
    }
  }


```

### `bleDescriptor.value()`

Query the value of the specified BLEDescriptor.

#### Syntax

```
bleDescriptor.value()

```

#### Parameters

None

#### Returns
- Value byte array of the **BLE descriptor**.

#### Example

```arduino

BLEDescriptor millisLabelDescriptor("2901", "millis");



  int descriptorValueSize = millisLabelDescriptor.valueSize();
  byte descriptorValue[descriptorValueSize];

  for (int i = 0; i < descriptorValueSize; i++) {
    descriptorValue[i] = millisLabelDescriptor.value()[i];
  }



```

### `bleDescriptor.readValue()`

Read the current value of the descriptor. If the descriptor is on a remote device, a read request will be sent.

#### Syntax

```
bleDescriptor.readValue(buffer, length)
bleDescriptor.readValue(value)

```

#### Parameters

- **buffer**: byte array to read value into
- **length**: size of buffer argument in bytes
- **value**: variable to read value into (by reference)

#### Returns
- **Number of bytes** read

#### Example


```arduino

  byte value = 0;

  /get the value, descriptor is 1 byte so use byte value    
  descriptor.readValue(value);


```

### `bleDescriptor.read()`

Perform a read request for the descriptor.

#### Syntax

```
bleDescriptor.read()

```

#### Parameters

None

#### Returns
- **true**, if successful,
- **false** on failure

#### Example

```arduino

  if (descriptor.read()) {
    Serial.println("descriptor value read");

    // ...
  } else {
    Serial.println("error reading descriptor value");
  }

```