Troubleshooting Bluetooth Low Energy

Issue

If you are having issues connecting to your Bluetooth^® Low Energy peripheral device from MATLAB^® or are unable to read or write data, you can try some of the following troubleshooting tips.

Possible Solutions

Check Supported Platforms

The Bluetooth Low Energy interface is supported on these platforms:

macOS
Windows^® 10 and Windows 11

Before trying other troubleshooting steps, make sure your computer is running one of the supported platforms.

Configure Adapter

If MATLAB does not detect your built-in or external Bluetooth adapter when you call blelist, try the following:

Make sure the adapter supports Bluetooth 4.0 and higher.
Restart Bluetooth services on your computer.
Update to the latest device drivers for your adapter.
Reboot your computer.

Check Device Status

If your device does not appear in the blelist output, make sure that you have done the following:

Power on your peripheral device.
Bring your peripheral device within range of your computer.
Disconnect your peripheral device from any other devices or applications first. The output from blelist shows you only nearby devices that are currently advertising data. If your device is already connected in another application or in MATLAB, it might not appear in the output.
Try a larger value for the Timeout parameter in blelist. This increases the amount of time MATLAB scans for nearby devices. For example, blelist("Timeout",20) searches for nearby peripheral devices for 20 seconds. The default timeout value is three seconds. If your device transmits advertisement data less often than once every three seconds, MATLAB might not capture it.

If your peripheral device powers off or disconnects, the UUID might change when it powers on again or reconnects. However, the name remains the same in the blelist output. If you are trying to create a new ble object for the same device, specify the new UUID instead of the name.

On Windows, if a peripheral device has already been paired but the firmware that defines characteristics and descriptors is changed, ble might fail to connect the device to your computer. To fix this, disconnect and then reconnect your device to Windows.

If you are unable to create a characteristic object for your Bluetooth Low Energy device on Windows, try pairing your device on Windows before using ble to connect to it in MATLAB. You can pair to a device in Windows Settings > Devices > Add Bluetooth or other device.

Enable Bluetooth Permissions on macOS

If you are using macOS, you may need to configure additional settings. Try the following steps when you get this error message:

Bluetooth permission is not enabled for MATLAB. Allow MATLAB or Terminal to use Bluetooth from the Security & Privacy settings.

Open Security & Privacy > Privacy > Bluetooth and click the + icon.

If you launch MATLAB from Applications, add MATLAB to the list of apps that are allowed Bluetooth access.
If you launch MATLAB from Terminal, add Terminal to the list of apps that are allowed Bluetooth access.
If you launch MATLAB from both Applications and Terminal, add both MATLAB and Terminal to the list of apps that are allowed Bluetooth access.

Troubleshoot Read and Write Operations

Using read(c,'latest') or read(c) inside a callback function for a characteristic with a high rate can throw an error or block MATLAB for a long time. Instead, use read(c,'oldest') in a callback function. For an example, see Read Characteristic Data from a Bluetooth Low Energy Peripheral Device Using a Callback Function.

On macOS, some device characteristics require authentication to read or write for the first time. After you create a ble object, run read or write. Follow the prompts that appear on your computer to pair your peripheral device.