Bluetooth LE (BLE)

BLE Class

BLE.advertise()

BLE.advertise, advertise

A BLE peripheral can periodically publish data to all nearby devices using advertising. Once you've set up the BleAdvertisingData object, call BLE.advertise() to continuously advertise the data to all BLE devices scanning for it.

Optionally, you can provide a scanResponse data object. If provided, the central device can ask for it during the scan process. Both the advertising data and scan data are public - any device can see and request the data without authentication.

// PROTOTYPE
int advertise(BleAdvertisingData* advertisingData, BleAdvertisingData* scanResponse = nullptr) const;

// EXAMPLE
BleAdvertisingData advData;

// While we support both the health thermometer service and the battery service, we
// only advertise the health thermometer. The battery service will be found after
// connecting.
advData.appendServiceUUID(healthThermometerService);


// Continuously advertise when not connected
BLE.advertise(&advData);

Returns 0 on success or a non-zero error code.

You cannot use BLE advertising while in listening mode (blinking dark blue). The device will be advertising its configuration capabilities to the Particle app when in listening mode.

BLE.advertise(iBeacon)

You can advertise as an Apple iBeacon. See the iBeacon section for more information.

// PROTOTYPE
int advertise(const iBeacon& beacon) const;

Returns 0 on success or a non-zero error code.

You cannot use BLE advertising including iBeacon while in listening mode (blinking dark blue). The device will be advertising its configuration capabilities to the Particle app when in listening mode.

BLE.advertise()

The advertising data set using the previous two calls is saved. You can using BLE.stopAdvertising() to stop and BLE.advertise() to resume advertising.

// PROTOTYPE
int advertise() const;

// EXAMPLE
BLE.advertise();

Returns 0 on success or a non-zero error code.

BLE.stopAdvertising()

BLE.stopAdvertising, stopAdvertising

Stops advertising. You can resume advertising using BLE.advertise(). Advertising automatically stops while connected to a central device and resumes when disconnected.

// PROTOTYPE
int stopAdvertising() const;

// EXAMPLE
BLE.stopAdvertising();

BLE.advertising()

BLE.advertising, advertising

Returns true (1) if advertising is currently on or false (0) if not.

// PROTOTYPE
bool advertising() const;

BLE.getAdvertisingData()

BLE.getAdvertisingData, getAdvertisingData

You can get the advertising data that you previously set using getAdvertisingData(). Initially the data will be empty.

// PROTOTYPE
ssize_t getAdvertisingData(BleAdvertisingData* advertisingData) const;

See also BleAdvertisingData.

BLE.setAdvertisingData()

BLE.setAdvertisingData, setAdvertisingData

You can set the advertising data using setAdvertisingData. You might want to do this if you want to change the data while continuously advertising.

// PROTOTYPE
int setAdvertisingData(BleAdvertisingData* advertisingData) const;

See also BleAdvertisingData.

BLE.setAdvertisingInterval()

BLE.setAdvertisingInterval, setAdvertisingInterval

Sets the advertising interval. The unit is 0.625 millisecond (625 microsecond) intervals. The default value is 160, or 100 milliseconds.

The range is from 20 milliseconds (32) to 10.24 seconds (16383).

Interval Value Milliseconds Description
32 20 ms Minimum value
160 100 ms Default value
400 250 ms
800 500 ms
1600 1 sec
3200 2 sec Upper end of recommended range
16383 10.24 sec Maximum value

Returns 0 on success or a non-zero error code.

// PROTOTYPE
int setAdvertisingInterval(uint16_t interval) const;

// EXAMPLE

// Set advertising interval to 500 milliseconds
BLE.setAdvertisingInterval(800);

BLE.setAdvertisingTimeout()

BLE.setAdvertisingTimeout, setAdvertisingTimeout

Normally, advertising continues until stopAdvertising() is called or a connection is made from a central device.

You can also have advertising automatically stop after a period of time. The parameter is in units of 10 milliseconds, so if you want to advertise for 10 seconds you'd set the parameter to 1000.

Pass 0 to advertise until stopped. This is the default.

Returns 0 on success or a non-zero error code.

// PROTOTYPE
int setAdvertisingTimeout(uint16_t timeout) const;

BLE.setAdvertisingType()

BLE.setAdvertisingType, setAdvertisingType

The advertising type can be set with this method. This is not typically necessary.

Type Value
CONNECTABLE_SCANNABLE_UNDIRECTED 0
CONNECTABLE_UNDIRECTED 1
CONNECTABLE_DIRECTED 2
NON_CONNECTABLE_NON_SCANNABLE_UNDIRECTED 3
NON_CONNECTABLE_NON_SCANNABBLE_DIRECTED 4
SCANNABLE_UNDIRECTED 5
SCANNABLE_DIRECTED 6

The default is CONNECTABLE_SCANNABLE_UNDIRECTED (0).

// PROTOTYPE
int setAdvertisingType(BleAdvertisingEventType type) const;

See BleAdvertisingEventType for more information.

BLE.getAdvertisingParameters()

BLE.getAdvertisingParameters, getAdvertisingParameters

Gets the advertising parameters.

// PROTOTYPE
int getAdvertisingParameters(BleAdvertisingParams* params) const;

// EXAMPLE
BleAdvertisingParams param;
param.version = BLE_API_VERSION;
param.size = sizeof(BleAdvertisingParams);

int res = BLE.getAdvertisingParameters(&param);

See BleAdvertisingParameters for more information.

BLE.setAdvertisingParameters()

BLE.setAdvertisingParameters, setAdvertisingParameters

Sets the advertising parameters using individual values for interval, timeout, and type.

// PROTOTYPE
int setAdvertisingParameters(uint16_t interval, uint16_t timeout, BleAdvertisingEventType type) const;
  • interval Advertising interval in 0.625 ms units. Default is 160.
  • timeout Advertising timeout in 10 ms units. Default is 0.
  • type BleAdvertisingEventType. Default is CONNECTABLE_SCANNABLE_UNDIRECTED (0).

BLE.setAdvertisingParameters(BleAdvertisingParams)

Sets the advertising parameters from the BleAdvertisingParams struct.

// PROTOTYPE
int setAdvertisingParameters(const BleAdvertisingParams* params) const;

See BleAdvertisingParameters for more information.

BLE.getScanResponseData()

BLE.getScanResponseData, getScanResponseData

In addition to the advertising data, there is an additional 31 bytes of data referred to as the scan response data. This data can be requested during the scan process. It does not require connection or authentication. This is only used from scannable peripheral devices.

// PROTOTYPE
ssize_t getScanResponseData(BleAdvertisingData* scanResponse) const;

See also BleAdvertisingData.

BLE.setScanResponseData()

BLE.setScanResponseData, setScanResponseData

In addition to the advertising data, there is an additional 31 bytes of data referred to as the scan response data. This data can be requested during the scan process. It does not require connection or authentication. This is only used from scannable peripheral devices.

// PROTOTYPE
int setScanResponseData(BleAdvertisingData* scanResponse) const;

See also BleAdvertisingData.

BLE.addCharacteristic(characteristic)

BLE.addCharacteristic, addCharacteristic

Adds a characteristic to this peripheral device from a BleCharacteristic object.

// PROTOTYPE
BleCharacteristic addCharacteristic(BleCharacteristic& characteristic) const;

// EXAMPLE

// Global variables:
BleUuid serviceUuid("09b17c16-3498-4c02-beb6-3d5792528181");
BleUuid buttonCharacteristicUuid("fe0a8cd7-9f69-45c7-b7a1-3ecb0c9e97c7");
BleCharacteristic buttonCharacteristic("b", BleCharacteristicProperty::NOTIFY, buttonCharacteristicUuid, serviceUuid);

// In setup():
BLE.addCharacteristic(buttonCharacteristic);

BleAdvertisingData data;
data.appendServiceUUID(serviceUuid);
BLE.advertise(&data);

There is a limit of 20 user characteristics, with a maximum description of 20 characters.

You can have up to 20 user services, however you typically cannot advertise that many services as the advertising payload is too small. You normally only advertise your primary service that you device will searched by. Other, less commonly used services can be found after connecting to the device.

BLE.addCharacteristic(parameters)

Instead of setting the parameters in a BleCharacteristic object you can pass them directly to addCharacteristic.

The parameters are the same as the BleCharacteristic constructors and are described in more detail in the BleCharacteristic documentation.

// PROTOTYPE
BleCharacteristic addCharacteristic(const char* desc, BleCharacteristicProperty properties, BleOnDataReceivedCallback callback = nullptr, void* context = nullptr) const;

BleCharacteristic addCharacteristic(const String& desc, BleCharacteristicProperty properties, BleOnDataReceivedCallback callback = nullptr, void* context = nullptr) const;

template<typename T>
BleCharacteristic addCharacteristic(const char* desc, BleCharacteristicProperty properties, T charUuid, T svcUuid, BleOnDataReceivedCallback callback = nullptr, void* context = nullptr) const;

template<typename T>
BleCharacteristic addCharacteristic(const String& desc, BleCharacteristicProperty properties, T charUuid, T svcUuid, BleOnDataReceivedCallback callback = nullptr, void* context = nullptr) const;

There is a limit of 20 user characteristics, with a maximum description of 20 characters.

You can have up to 20 user services, however you typically cannot advertise that many services as the advertising payload is too small. You normally only advertise your primary service that you device will searched by. Other, less commonly used services can be found after connecting to the device.

See also BleCharacteristicProperty.

BLE.scan(array)

BLE.scan, scan

Scan for BLE devices. This is typically used by a central device to find nearby BLE devices that can be connected to. It can also be used by an observer to find nearby beacons that continuously transmit data.

There are three overloads of BLE.scan(), however all of them are synchronous. The calls do not return until the scan is complete. The BLE.setScanTimeout() method determines how long the scan will run for.

The default is 5 seconds, however you can change it using setScanTimeout().

// PROTOTYPE
int scan(BleScanResult* results, size_t resultCount) const;

The BleScanResult is described below. It contains:

  • address The BLE address of the device
  • advertisingData The advertising data sent by the device
  • scanData The scan data (optional)
  • rssi The signal strength of the advertising message.

Prior to Device OS 3.0, these were member variables.

In Device OS 3.0 and later, they are methods, so you must access them as:

  • address() The BLE address of the device
  • advertisingData() The advertising data sent by the device
  • scanData() The scan data (optional)
  • rssi() The signal strength of the advertising message.

For example:

len = scanResults[ii].advertisingData().get(BleAdvertisingDataType::MANUFACTURER_SPECIFIC_DATA, buf, BLE_MAX_ADV_DATA_LEN);

BLE.scan(Vector)

The Vector version of scan does not require guessing the number of scan items ahead of time. However, it does dynamically allocate memory to hold all of the scan results.

This call does not return until the scan is complete. The setScanTimeout() function determines how long the scan will run for.

The default is 5 seconds, however you can change it using setScanTimeout().

// PROTOTYPE
Vector<BleScanResult> scan() const;

// EXAMPLE - Device OS 3.0 and later
#include "Particle.h"

SYSTEM_MODE(MANUAL);

SerialLogHandler logHandler(LOG_LEVEL_TRACE);

void setup() {
    (void)logHandler; // Does nothing, just to eliminate warning for unused variable
}

void loop() {
    Vector<BleScanResult> scanResults = BLE.scan();

    if (scanResults.size()) {
        Log.info("%d devices found", scanResults.size());

        for (int ii = 0; ii < scanResults.size(); ii++) {
            Log.info("MAC: %02X:%02X:%02X:%02X:%02X:%02X | RSSI: %dBm",
                    scanResults[ii].address()[0], scanResults[ii].address()[1], scanResults[ii].address()[2],
                    scanResults[ii].address()[3], scanResults[ii].address()[4], scanResults[ii].address()[5], scanResults[ii].rssi());

            String name = scanResults[ii].advertisingData().deviceName();
            if (name.length() > 0) {
                Log.info("Advertising name: %s", name.c_str());
            }
        }
    }

    delay(3000);
}

// EXAMPLE - Device OS 2.0 and earlier
#include "Particle.h"

SYSTEM_MODE(MANUAL);

SerialLogHandler logHandler(LOG_LEVEL_TRACE);

void setup() {
    (void)logHandler; // Does nothing, just to eliminate warning for unused variable
}

void loop() {
    Vector<BleScanResult> scanResults = BLE.scan();

    if (scanResults.size()) {
        Log.info("%d devices found", scanResults.size());

        for (int ii = 0; ii < scanResults.size(); ii++) {
            Log.info("MAC: %02X:%02X:%02X:%02X:%02X:%02X | RSSI: %dBm",
                    scanResults[ii].address[0], scanResults[ii].address[1], scanResults[ii].address[2],
                    scanResults[ii].address[3], scanResults[ii].address[4], scanResults[ii].address[5], scanResults[ii].rssi);

            String name = scanResults[ii].advertisingData.deviceName();
            if (name.length() > 0) {
                Log.info("Advertising name: %s", name.c_str());
            }
        }
    }

    delay(3000);
}

The BleScanResult is described below. It contains:

  • address The BLE address of the device
  • advertisingData The advertising data sent by the device
  • scanData The scan data (optional)
  • rssi The signal strength of the advertising message.

BLE.scan(callback)

The callback version of scan does not return until the scan has reached the end of the scan timeout. There are still advantages of using this, however:

  • You do not need to guess how many scan results there will be ahead of time.
  • If you expect to have a lot of BLE devices in the area but only care about a few, this version can save on memory usage.
  • The callback is called as the devices are discovered - you can start to display before the timeout occurs.
  • You can stop scanning when the desired device is found instead of waiting until the timeout.

The default is 5 seconds, however you can change it using setScanTimeout().

Note: You cannot call BLE.connect() from a BLE.scan() callback! If you want to scan then connect, you must save the BleAddress and then do the connect after BLE.scan() returns.

// PROTOTYPE
int scan(BleOnScanResultCallback callback, void* context) const;
int scan(BleOnScanResultCallbackRef callback, void* context) const;

// EXAMPLE
#include "Particle.h"

SYSTEM_MODE(MANUAL);

SerialLogHandler logHandler(LOG_LEVEL_TRACE);

void scanResultCallback(const BleScanResult *scanResult, void *context);

void setup() {
    (void)logHandler; // Does nothing, just to eliminate warning for unused variable
}

void loop() {
    Log.info("starting scan");

    int count = BLE.scan(scanResultCallback, NULL);
    if (count > 0) {
        Log.info("%d devices found", count);
    }

    delay(3000);
}

void scanResultCallback(const BleScanResult *scanResult, void *context) {
    Log.info("MAC: %02X:%02X:%02X:%02X:%02X:%02X | RSSI: %dBm",
            scanResult->address[0], scanResult->address[1], scanResult->address[2],
            scanResult->address[3], scanResult->address[4], scanResult->address[5], scanResult->rssi);

    String name = scanResult->advertisingData.deviceName();
    if (name.length() > 0) {
        Log.info("deviceName: %s", name.c_str());
    }
}

The callback has this prototype:

void scanResultCallback(const BleScanResult *scanResult, void *context)

The BleScanResult is described below. It contains:

  • address The BLE address of the device
  • advertisingData The advertising data sent by the device
  • scanData The scan data (optional)
  • rssi The signal strength of the advertising message.

The context parameter is often used if you implement your scanResultCallback in a C++ object. You can store the object instance pointer (this) in the context.

The callback is called from the BLE thread. It has a smaller stack than the normal loop stack, and you should avoid doing any lengthy operations that block from the callback. For example, you should not try to use functions like Particle.publish() and you should not use delay(). You should beware of thread safety issues. For example you should use Log.info() and instead of Serial.print() as Serial is not thread-safe.

Since 3.0.0:

// PROTOTYPES
typedef std::function<void(const BleScanResult& result)> BleOnScanResultStdFunction;

int scan(const BleOnScanResultStdFunction& callback) const;

template<typename T>
int scan(void(T::*callback)(const BleScanResult&), T* instance) const;

In Device OS 3.0.0 and later, you can implement the BLE.scan() callback as a C++ member function or a C++11 lambda.


Since 3.0.0:

In Device OS 3.0.0 and later, it's also possible to pass to have the scan result passed by reference instead of pointer.

void scanResultCallback(const BleScanResult &scanResult, void *context)

BLE.scanWithFilter()

BLE.scanWithFilter, scanWithFilter

void scan() {
    BleScanFilter filter;
    filter.deviceName("MyDevice").minRssi(-50).serviceUUID(0x1234);
    Vector<BleScanResult> scanResults = BLE.scanWithFilter(filter);
}

Since 3.0.0:

You can also BLE scan with a filter with Device OS 3.0.0 and later. The result is saved in a vector.

The scanResults vector only contains the scanned devices those comply with all of the following conditions in the example above:

  • The scanned device should be broadcasting device name "MyDevice".
  • The RSSI of the scanned device should be large than -50 dBm.
  • The scanned device should be broadcasting service UUID 0x1234.

See BLEScanFilter for additional options.

BLE.stopScanning()

BLE.stopScanning, stopScanning

The stopScanning() method interrupts a BLE.scan() in progress before the end of the timeout. It's typically called from the scan callback function.

You might want to do this if you're looking for a specific device - you can stop scanning after you find it instead of waiting until the end of the scan timeout.

// PROTOTYPE
int stopScanning() const;

// EXAMPLE
void scanResultCallback(const BleScanResult *scanResult, void *context) {
    // Stop scanning if we encounter any BLE device in range
    BLE.stopScanning();
}

BLE.setScanTimeout()

BLE.setScanTimeout, setScanTimeout

Sets the length of time scan() will run for. The default is 5 seconds.

// PROTOTYPE
int setScanTimeout(uint16_t timeout) const;

// EXAMPLE

// Scan for 1 second
setScanTimeout(100);

The unit is 10 millisecond units, so the default timeout parameter is 500.

Returns 0 on success or a non-zero error code.

BLE.getScanParameters()

BLE.getScanParameters, getScanParameters

Gets the parameters used for scanning.

// PROTOTYPE
int getScanParameters(BleScanParams* params) const;

// EXAMPLE
BleScanParams scanParams;
scanParams.version = BLE_API_VERSION;
scanParams.size = sizeof(BleScanParams);
int res = BLE.getScanParameters(&scanParams);

See BleScanParams for more information.

BLE.setScanParameters()

BLE.setScanParameters, setScanParameters

Sets the parameters used for scanning. Typically you will only ever need to change the scan timeout, but if you need finer control you can use this function.

// PROTOTYPE
int setScanParameters(const BleScanParams* params) const;

See BleScanParams for more information.

BLE.connect()

BLE.connect, connect

In a central device the logic typically involves:

  • Scanning for a device
  • Selecting one, either manually from a user selection, or automatically by its capabilities.
  • Connecting to it to exchange more data (optional)

Scanning for devices provides its address as well as additional data (advertising data). With the address you can connect:

// PROTOTYPE
BlePeerDevice connect(const BleAddress& addr, bool automatic = true) const;
BlePeerDevice connect(const BleAddress& addr, const BleConnectionParams* params, bool automatic = true) const;
BlePeerDevice connect(const BleAddress& addr, uint16_t interval, uint16_t latency, uint16_t timeout, bool automatic = true) const;

This call is synchronous and will block until a connection is completed or the operation times out.

Returns a BlePeerDevice object. You typically use a construct like this:

// EXAMPLE - Device OS 3.0.0 and later:
BlePeerDevice peer = BLE.connect(scanResults[ii].address());
if (peer.connected()) {
    Log.info("successfully connected %02X:%02X:%02X:%02X:%02X:%02X!",
                            scanResults[ii].address()[0], scanResults[ii].address()[1], scanResults[ii].address()[2],
                            scanResults[ii].address()[3], scanResults[ii].address()[4], scanResults[ii].address()[5]);
    // ...
}
else {
    Log.info("connection failed");
    // ...
}

// EXAMPLE - Device OS 2.x and earlier:
BlePeerDevice peer = BLE.connect(scanResults[ii].address);
if (peer.connected()) {
    Log.info("successfully connected %02X:%02X:%02X:%02X:%02X:%02X!",
                            scanResults[ii].address[0], scanResults[ii].address[1], scanResults[ii].address[2],
                            scanResults[ii].address[3], scanResults[ii].address[4], scanResults[ii].address[5]);
    // ...
}
else {
    Log.info("connection failed");
    // ...
}

It is possible to save the address and avoid scanning, however the address could change on some BLE devices, so you should be prepared to scan again if necessary.

A central device can connect to up to 3 peripheral devices at a time. (It's limited to 1 in Device OS 1.3.0.)

See the next section for the use of BleConnectionParams as well as interval, latency, and timeout.

BLE.connect(options)

This version of connect allows parameters for the connection to be set.

// PROTOTYPE
BlePeerDevice connect(const BleAddress& addr, uint16_t interval, uint16_t latency, uint16_t timeout) const;
  • addr The BleAddress to connect to.
  • interval The minimum connection interval in units of 1.25 milliseconds. The default is 24 (30 milliseconds).
  • latency Use default value 0.
  • timeout Connection timeout in units of 10 milliseconds. Default is 500 (5 seconds). Minimum value is 100 (1 second).

Note that the timeout is the timeout after the connection is established, to determine that the other side is no longer available. It does not affect the initial connection timeout.

Returns a BlePeerDevice object.

BLE.setPPCP()

BLE.setPPCP, setPPCP

Sets the connection parameter defaults so future calls to connect() without options will use these values.

// PROTOTYPE
int setPPCP(uint16_t minInterval, uint16_t maxInterval, uint16_t latency, uint16_t timeout) const;
  • minInterval the minimum connection interval in units of 1.25 milliseconds. The default is 24 (30 milliseconds).
  • maxInterval the minimum connection interval in units of 1.25 milliseconds. The default is 24 (30 milliseconds). The connect(options) call sets both minInterval and maxInterval to the interval parameter.
  • latency Use default value 0.
  • timeout Connection timeout in units of 10 milliseconds. Default is 500 (5 seconds). Minimum value is 100 (1 second).

Note that the timeout is the timeout after the connection is established, to determine that the other side is no longer available. It does not affect the initial connection timeout.

BLE.connected()

BLE.connected, connected

Returns true (1) if a connected to a device or false (0) if not.

// PROTOTYPE
bool connected() const;

Can be used in central or peripheral mode, however if central mode if you are supporting more than one peripheral you may want to use the connected() method of the BlePeerDevice object to find out the status of individual connections.

BLE.disconnect()

BLE.disconnect, disconnect

Disconnects all peers.

// PROTOTYPE
int disconnect() const;

Returns 0 on success or a non-zero error code.

BLE.disconnect(peripheral)

Typically used in central mode when making connections to multiple peripherals to disconnect a single peripheral.

// PROTOTYPE
int disconnect(const BlePeerDevice& peripheral) const;

The BlePeerDevice is described below. You typically get it from BLE.connect().

Returns 0 on success or a non-zero error code.

BLE.on()

BLE.on, on

Turns the BLE radio on. It defaults to on in SYSTEM_MODE(AUTOMATIC). In SYSTEM_MODE(SEMI_AUTOMATIC) or SYSTEM_MODE(MANUAL) you must turn on BLE.

// PROTOTYPE
int on();

// EXAMPLE
void setup() {
  BLE.on();
}

Returns 0 on success, or a non-zero error code.

BLE.off()

BLE.off, off

Turns the BLE radio off. You normally do not need to do this.

// PROTOTYPE
int off();

Returns 0 on success, or a non-zero error code.

BLE.begin()

BLE.begin, begin

Starts the BLE service. It defaults to started, so you normally do not need to call this unless you have stopped it.

// PROTOTYPE
int begin();

Returns 0 on success, or a non-zero error code.

BLE.end()

BLE.end, end

Stops the BLE service. You normally do not need to do this.

// PROTOTYPE
int end();

Returns 0 on success, or a non-zero error code.

BLE.onConnected()

BLE.onConnected, onConnected

Registers a callback function that is called when a connection is established. This is only called for peripheral devices. On central devices, BLE.connect() is synchronous.

You can use this method, or you can simply monitor BLE.connected() (for peripheral devices) or peer.connected() for central devices.

// PROTOTYPE
void onConnected(BleOnConnectedCallback callback, void* context);

The prototype for the callback function is:

void callback(const BlePeerDevice& peer, void* context);

The callback parameters are:

  • peer The BlePeerDevice object that has connected.
  • context The value you passed to onConnected when you registered the connected callback.

The callback is called from the BLE thread. It has a smaller stack than the normal loop stack, and you should avoid doing any lengthy operations that block from the callback. For example, you should not try to use functions like Particle.publish() and you should not use delay(). You should beware of thread safety issues. For example you should use Log.info() and instead of Serial.print() as Serial is not thread-safe.

Since 3.0.0:

// PROTOTYPES
typedef std::function<void(const BlePeerDevice& peer)> BleOnConnectedStdFunction;

void onConnected(const BleOnConnectedStdFunction& callback) const;

template<typename T>
void onConnected(void(T::*callback)(const BlePeerDevice& peer), T* instance) const;

in Device OS 3.0.0 and later, the onConnected() callback can be a C++ class member function or a C++11 lambda.

BLE.onDisconnected()

BLE.onDisconnected, onDisconnected

Registers a callback function that is called when a connection is disconnected on a peripheral device.

You can use this method, or you can simply monitor BLE.connected() (for peripheral devices) or peer.connected() for central devices.

// PROTOTYPE
void onDisconnected(BleOnDisconnectedCallback callback, void* context);
`

The prototype for the callback function is:

void callback(const BlePeerDevice& peer, void* context);

The callback parameters are the same as for onConnected().

Since 3.0.0:

// PROTOTYPES
typedef std::function<void(const BlePeerDevice& peer)> BleOnDisconnectedStdFunction;

void onDisconnected(const BleOnDisconnectedStdFunction& callback) const;

template<typename T>
void onDisconnected(void(T::*callback)(const BlePeerDevice& peer), T* instance) const;

in Device OS 3.0.0 and later, the onDisconnected() callback can be a C++ class member function or a C++11 lambda.

BLE.setTxPower()

BLE.setTxPower, setTxPower

Sets the BLE transmit power. The default is 0 dBm.

Valid values are: -20, -16, -12, -8, -4, 0, 4, 8.

-20 is the lowest power, and 8 is the highest power.

Returns 0 on success or a non-zero error code.

// PROTOTYPE
int setTxPower(int8_t txPower) const;

// EXAMPLE
BLE.setTxPower(-12); // Use lower power

Returns 0 on success or a non-zero error code.

BLE.txPower()

BLE.txPower, txPower

Gets the current txPower. The default is 0.

Returns 0 on success or a non-zero error code.

// PROTOTYPE
int txPower(int8_t* txPower) const;

// EXAMPLE
int8_t txPower;
txPower = BLE.tx(&txPower);
Log.info("txPower=%d", txPower);

BLE.address()

BLE.address, address

Get the BLE address of this device.

// PROTOTYPE
const BleAddress address() const;

See BleAddress for more information.

BLE.selectAntenna()

BLE.selectAntenna, selectAntenna

Since 1.3.1:

Selects which antenna is used by the BLE radio stack. This is a persistent setting.

Note: B Series SoM devices do not have an internal (chip) antenna and require an external antenna to use BLE. It's not necessary to select the external antenna on the B Series SoM as there is no internal option.

// Select the internal antenna
BLE.selectAntenna(BleAntennaType::INTERNAL);
// Select the external antenna
BLE.selectAntenna(BleAntennaType::EXTERNAL);

If you get this error when using BleAntennaType::EXTERNAL:

Error: .../wiring/inc/spark_wiring_arduino_constants.h:44:21: expected unqualified-id before numeric constant

After all of your #include statements at the top of your source file, add:

#undef EXTERNAL

This occurs because the Arduino compatibility modules has a #define for EXTERNAL which breaks the BleAntennaType enumeration. This will only be necessary if a library you are using enables Arduino compatibility.

BLE.setPairingIoCaps()

BLE.setPairingIoCaps, setPairingIoCaps

// PROTOTYPE
int setPairingIoCaps(BlePairingIoCaps ioCaps) const;

Since 3.0.0:

Sets the capabilities of this side of the BLE connection.

Value Description
BlePairingIoCaps::NONE This side has no display or keyboard
BlePairingIoCaps::DISPLAY_ONLY Has a display for the 6-digit passcode
BlePairingIoCaps::DISPLAY_YESNO Display and a yes-no button
BlePairingIoCaps::KEYBOARD_ONLY Keyboard or numeric keypad only
BlePairingIoCaps::KEYBOARD_DISPLAY Display and a keyboard (or a touchscreen)

Ideally you want one side to have a keyboard and one side to have a display. This allows for an authenticated connection to assure that both sides the device they say they are. This prevents man-in-the-middle attack ("MITM") where a rogue device could pretend to be the device you are trying to pair with.

Even if neither side has a display or keyboard, the connection can still be paired and encrypted, but there will be no authentication.

For more information about pairing, see BLE pairing.

BLE.setPairingAlgorithm()

BLE.setPairingAlgorithm, setPairingAlgorithm

// PROTOTYPE
int setPairingAlgorithm(BlePairingAlgorithm algorithm) const;

Since 3.0.0:

Value Description
BlePairingAlgorithm::AUTO Automatic selection
BlePairingAlgorithm::LEGACY_ONLY Legacy Pairing mode only
BlePairingAlgorithm::LESC_ONLY Bluetooth LE Secure Connection Pairing (LESC) only

At this time, LESC pairing is not supported; only legacy pairing can be used. You can still specify LESC pairing, however it will fall back to "just works" mode which offers encryption but not authentication. You will not be prompted for the numeric comparison used in LESC pairing mode.

BLE.startPairing()

BLE.startPairing, startPairing

// PROTOTYPE
int startPairing(const BlePeerDevice& peer) const;

Since 3.0.0:

When using BLE pairing, one side is the initiator. It's usually the BLE central device, but either side can initiate pairing if the other side is able to accept the request to pair. See BLE.onPairingEvent(), below, for how to respond to a request.

The results is 0 (SYSTEM_ERROR_NONE) on success, or a non-zero error code on failure.

For more information about pairing, see BLE pairing.

BLE.rejectPairing()

BLE.rejectPairing, rejectPairing

// PROTOTYPE
int rejectPairing(const BlePeerDevice& peer) const;

Since 3.0.0:

If you are the pairing responder (typically the BLE peripheral, but could be either side) and you do not support being the responder, call BLE.rejectPairing() from your BLE.onPairingEvent() handler.

The results is 0 (SYSTEM_ERROR_NONE) on success, or a non-zero error code on failure.

BLE.setPairingNumericComparison()

BLE.setPairingNumericComparison, setPairingNumericComparison

// PROTOTYPE
int setPairingNumericComparison(const BlePeerDevice& peer, bool equal) const;

Since 3.0.0:

This is used with BlePairingEventType::NUMERIC_COMPARISON to confirm that two LESC passcodes are identical. This requires a keypad or a yes-no button.

The results is 0 (SYSTEM_ERROR_NONE) on success, or a non-zero error code on failure.

LESC is not supported at this time so you will probably not need to use this function.

BLE.setPairingPasskey()

BLE.setPairingPasskey, setPairingPasskey

// PROTOTYPE
int setPairingPasskey(const BlePeerDevice& peer, const uint8_t* passkey) const;

Since 3.0.0:

When you have a keyboard and the other side has a display, you may need to prompt the user to enter a passkey on your keyboard. This is done by the BlePairingEventType::PASSKEY_INPUT event. Once they have entered it, call this function to set the code that they entered.

The passkey is BLE_PAIRING_PASSKEY_LEN bytes long (6). The passkey parameter does not need to be null terminated.

The results is 0 (SYSTEM_ERROR_NONE) on success, or a non-zero error code on failure.

BLE.isPairing()

BLE.isPairing, isPairing

// PROTOTYPE
bool isPairing(const BlePeerDevice& peer) const;

Since 3.0.0:

Returns true if the pairing negotiation is still in progress. This is several steps but is asynchrnouous.

BLE.isPaired()

BLE.isPaired, isPaired

// PROTOTYPE
bool isPaired(const BlePeerDevice& peer) const;

Since 3.0.0:

Returns true if pairing has been successfully completed.

BLE.onPairingEvent()

BLE.onPairingEvent, onPairingEvent

// PROTOTYPES
void onPairingEvent(BleOnPairingEventCallback callback, void* context = nullptr) const;
void onPairingEvent(const BleOnPairingEventStdFunction& callback) const;

template<typename T>
void onPairingEvent(void(T::*callback)(const BlePairingEvent& event), T* instance) const {
    return onPairingEvent((callback && instance) ? std::bind(callback, instance, _1) : (BleOnPairingEventStdFunction)nullptr);
}

// BleOnPairingEventCallback declaration
typedef void (*BleOnPairingEventCallback)(const BlePairingEvent& event, void* context);

// BleOnPairingEventCallback example function
void myPairingEventCallback(const BlePairingEvent& event, void* context);

// BleOnPairingEventStdFunction declaration
typedef std::function<void(const BlePairingEvent& event)> BleOnPairingEventStdFunction;

Since 3.0.0:

For more information about pairing, see BLE pairing.

BlePairingEventType::REQUEST_RECEIVED

Informational event that indicates that pairing was requested by the other side.

event.peer is the BLE peer that requested the pairing.

If you are not able to respond to pairing requests, you should call BLE.rejectPairing().

BlePairingEventType::PASSKEY_DISPLAY

If you have specified that you have a display, the negotiation process may require that you show a passkey on your display. This is indicated to your code by this event. The passkey is specified by the other side; you just need to display it. It's in the event payload:

  • event.payload.passkey is a character array of passcode characters
  • BLE_PAIRING_PASSKEY_LEN is the length in characters. Currently 6.
// Example using USB serial as the display and keyboard
if (event.type == BlePairingEventType::PASSKEY_DISPLAY) {
  Serial.print("Passkey display: ");
  for (uint8_t i = 0; i < BLE_PAIRING_PASSKEY_LEN; i++) {
      Serial.printf("%c", event.payload.passkey[i]);
  }
  Serial.println("");
}

Note that event.payload.passkey is not a null terminated string, so you can't just print it as a c-string. It's a fixed-length array of bytes of ASCII digits (0x30 to 0x39, inclusive).

BlePairingEventType::PASSKEY_INPUT

If you specified that you have a keyboard, the negotiation process may require that the user enter the passcode that's displayed on the other side into the keyboard or keypad. When this is required, this event is passed to your callback.

// Example using USB serial as the display and keyboard
if (event.type == BlePairingEventType::PASSKEY_INPUT) {
  Serial.print("Passkey input: ");
  uint8_t i = 0;
  uint8_t passkey[BLE_PAIRING_PASSKEY_LEN];
  while (i < BLE_PAIRING_PASSKEY_LEN) {
      if (Serial.available()) {
          passkey[i] = Serial.read();
          Serial.write(passkey[i++]);
      }
  }
  Serial.println("");

  BLE.setPairingPasskey(event.peer, passkey);
}

BlePairingEventType::STATUS_UPDATED

The pairing status was updated. These fields may be of interest:

  • event.payload.status.status
  • event.payload.status.bonded
  • event.payload.status.lesc
BLEPairingEvent
struct BlePairingEvent {
    BlePeerDevice& peer;
    BlePairingEventType type;
    size_t payloadLen;
    BlePairingEventPayload payload;
};

The structure passed to the callback has these elements. The payload varies depending on the event type. For example, for the BlePairingEventType::PASSKEY_DISPLAY event, the payload is the passkey to display on your display.

BlePairingEventPayload

The payload is either the passkey, or a status:

union BlePairingEventPayload {
    const uint8_t* passkey;
    BlePairingStatus status;
};
BlePairingStatus

Fields of the payload used for BlePairingEventType::STATUS_UPDATED events.

struct BlePairingStatus {
    int status;
    bool bonded;
    bool lesc;
};