Log Characteristic Value from Bluetooth Low Energy Peripheral Device Using Callback Function

This example shows how to access a characteristic of your Bluetooth® Low Energy (BLE) device, create a callback function to read the raw BLE characteristic value for a fixed duration, and log it in a text file.

Required Hardware

Any BLE device with characteristics that supports attributes such as Read and either Notify or Indicate. For more details see, Attributes. This example uses Arduino® Nano 33 BLE hardware.

Discover and Connect to BLE Device

First, check that the BLE device supports connections by finding it in MATLAB®. The blelist function scans advertising BLE peripheral devices that are advertising indications.

blelist

Run bluetoothlist to search for nearby Bluetooth classic devices.

ans=29×5 table
    Index          Name              Address        RSSI    Advertisement
    _____    _________________    ______________    ____    _____________

      1      ""                   "2693A0535E04"    -19      1×1 struct  
      2      ""                   "3A136453F9FD"    -37      1×1 struct  
      3      "Mambo_560253"       "E014F6303DFD"    -38      1×1 struct  
      4      ""                   "229CC4005139"    -55      1×1 struct  
      5      ""                   "3745017A158B"    -56      1×1 struct  
      6      ""                   "26864404E2D7"    -58      1×1 struct  
      7      "WaveGen"            "42162F5C6B30"    -58      1×1 struct  
      8      ""                   "10EBD9CAA72B"    -60      1×1 struct  
      9      ""                   "1DD7C49A016F"    -61      1×1 struct  
     10      ""                   "35E69990D1D3"    -61      1×1 struct  
     11      "vineethnArduino"    "7C9EBD3ACC32"    -64      1×1 struct  
     12      ""                   "2EF9235E31A2"    -68      1×1 struct  
     13      ""                   "55ACCE12E59D"    -68      1×1 struct  
     14      ""                   "E07F70DE320F"    -68      1×1 struct  
     15      ""                   "21F3C3B77DDD"    -69      1×1 struct  
     16      ""                   "7638FEDD33A4"    -69      1×1 struct  
      ⋮

Once you find the device in MATLAB, connect to it by calling ble. Specify the name of the device if it has a unique name, or specify the device address. This example uses the device address.

bleObj = ble("42162F5C6B30");

Retrieve Characteristic Value

Retrieve all the available characteristics of the BLE device.

allCharacteristics = bleObj.Characteristics;

Create a characteristic object using the ServiceUUID and CharacteristicUUID input arguments. Select the characteristic that supports attributes such as Read and either Notify or Indicate. This enables you to read the characteristic value upon being notified by the BLE device.

charObj = characteristic(bleObj,allCharacteristics.ServiceUUID(4),allCharacteristics.CharacteristicUUID(4));

Subscribe to the selected characteristic to enable notifications or indications. This selection enables the callback function to be triggered whenever a new characteristic value sent by the BLE device.

subscribe(charObj);

Create a log file to store the characteristic value available at the BLE device.

fileID = fopen("rawBLEData.txt","w+");

Create and Execute Callback Function

Create a callback function to handle the new data notifications. Name the function displayCharacteristicData and define it as follows.

Specify the read mode as 'oldest' instead of 'latest'. Calling the 'latest' data may lead to errors in the callback function caused by the flushing of previous data. Log the timestamp and the data to the file with millisecond precision.

function displayCharacteristicData(src,~,fileID)
% After subscribing to the notification or indication of
% BLE characteristic value, this callback function will be
% triggered each time the BLE device sends new characteristic
% data.
[data,timestamp] = read(src,'oldest');

% Store the time stamp with milli second precision
timestamp.Format = 'MM/dd/uuuu HH:mm:ss.SSSS';

% Log the timestamp
fprintf(fileID,"\n%s\t",timestamp);

% Log the data
fprintf(fileID,repmat('%d ',1,length(data)), data);
end

Initialize the callback function to collect the characteristic value sent by the BLE device.

Use the @ operator to assign the function handle to the DataAvailableFcn property of the characteristic object. Use an anonymous function to pass arguments to your callback in addition to the source and event data arguments passed by MATLAB. Anonymous functions can use any variables that are available in the current workspace. For more details, see Additional Arguments for Callback Function.

charObj.DataAvailableFcn = @(src,event)displayCharacteristicData(src,event,fileID);

Log the characteristic value for a duration of 10 seconds

pause(10);

Close the log file.

fclose(fileID);

Clean Up

After you finish working with the characteristic, disable notifications using unsubscribe and set the DataAvailableFcn property to null.

unsubscribe(charObj);
charObj.DataAvailableFcn = [];