Bluetooth LE (BLE)

BlePeerDevice

When using a Particle device in BLE central mode, connecting a peripheral returns a BlePeerDevice object. This object can be used to see if the connection is still open and get BleCharacteristic objects for the peripheral device.

Typically you'd get the BlePeerDevice from calling BLE.connect().

// Device OS 3.0 and later
BlePeerDevice peer = BLE.connect(scanResults[ii].address());
if (peer.connected()) {
    peerTxCharacteristic = peer.getCharacteristicByUUID(txUuid);
    peerRxCharacteristic = peer.getCharacteristicByUUID(rxUuid);
    // ...
}

// Device OS 2.x and earlier
BlePeerDevice peer = BLE.connect(scanResults[ii].address);
if (peer.connected()) {
    peerTxCharacteristic = peer.getCharacteristicByUUID(txUuid);
    peerRxCharacteristic = peer.getCharacteristicByUUID(rxUuid);
    // ...
}

Once you have the BlePeerDevice object you can use the following methods:

connected()

Returns true if the peer device is currently connected.

// PROTOTYPE
bool connected();

// EXAMPLE
if (peer.connected()) {
    // Peripheral is connected
}
else {
    // Peripheral has disconnected
}

address()

Get the BLE address of the peripheral device.

// PROTOTYPE
const BleAddress& address() const;

// EXAMPLE 1
Log.trace("Received data from: %s", peer.address().toString().c_str());


// EXAMPLE 2
Log.trace("Received data from: %02X:%02X:%02X:%02X:%02X:%02X", peer.address()[5], peer.address()[4], peer.address()[3], peer.address()[2], peer.address()[1], peer.address()[0]);

See BleAddress for more information.

getCharacteristicByUUID()

Get a characteristic by its UUID, either short or long UUID. See also BleUuid. Returns true if the characteristic was found.

You often do this from the central device after making a connection.

// PROTOTYPE
bool getCharacteristicByUUID(BleCharacteristic& characteristic, const BleUuid& uuid) const;

// EXAMPLE
BleCharacteristic characteristic;
bool bResult = peer.getCharacteristicByUUID(characteristic, BleUuid(0x180d));

// EXAMPLE
BleCharacteristic characteristic;
bool bResult = peer.getCharacteristicByUUID(characteristic, BleUuid("6E400002-B5A3-F393-E0A9-E50E24DCCA9E"));

getCharacteristicByDescription()

Get the characteristic by its description. As these strings are not standardized like UUIDs, it's best to use UUIDs instead. Returns true if the characteristic was found.

// PROTOTYPE
bool getCharacteristicByDescription(BleCharacteristic& characteristic, const char* desc) const;
bool getCharacteristicByDescription(BleCharacteristic& characteristic, const String& desc) const;

// EXAMPLE
BleCharacteristic characteristic;
bool bResult = peer.getCharacteristicByDescription(characteristic, "rx");

BleScanResult

When scanning, you get back one of:

• An array of BleScanResult records
• A Vector of BleScanResult records
• A callback that is called once for each device found, passed a BleScanResult.

The following fields are provided:

• address The BLE address of the peripheral. You use this if you want to connect to it. See BleAddress.
• advertisingData The advertising data provided by the peripheral. It's small (up to 31 bytes).
• scanResponse The scan response data. This is an optional extra 31 bytes of data that can be provided by the peripheral. It requires an additional request to the peripheral, but is less overhead than connecting.
• rssi The signal strength, which is a negative number of dBm. Numbers closer to 0 are a stronger signal.

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.

discoverAllCharacteristics

// PROTOTYPE
Vector<BleCharacteristic> discoverAllCharacteristics();
ssize_t discoverAllCharacteristics(BleCharacteristic* characteristics, size_t count);

Since 3.0.0:

In Device OS 3.0.0 and later, once you're connected to a BLE peripherals, you can optionally query all of the characteristics available on that peer. Normally you would know the characteristic you wanted and would get the single characteristic by UUID or description, but it is also possible to retrieve all characteristics.