Main Content

ble

Connect to Bluetooth Low Energy peripheral device

Description

A ble object represents a connection to a Bluetooth® Low Energy peripheral device from your computer. Find nearby connectable devices using blelist.

Creation

Description

b = ble(name) connects to a Bluetooth Low Energy device using its name.

example

b = ble(address) connects to a Bluetooth Low Energy device using its address.

example

Input Arguments

expand all

Device name, specified as a character vector or string scalar. Identify the name of the peripheral device you want to connect to using the information returned by blelist. If a device does not have a name, then use its address to connect to it.

Example: b = ble("Tile") connects to the peripheral device with the name "Tile".

Data Types: char | string

Device address, specified as a character vector or string scalar. Identify the address of the peripheral device you want to connect to using the information returned by blelist. If a device does not have a name, then use its address to connect to it.

Example: b = ble("5A8769A09DA6") connects to the peripheral device with the MAC address "5A8769A09DA6" on a Windows® computer.

Example: b = ble("121B0BAC-0DE7-4FB1-909A-EEA6877DBC5C") connects to the peripheral device with the random OS-assigned address "121B0BAC-0DE7-4FB1-909A-EEA6877DBC5C" on a macOS computer.

Data Types: char | string

Properties

expand all

This property is read-only.

Peripheral device name, returned as a string scalar.

Data Types: string

This property is read-only.

Peripheral device address, returned as a string scalar. On Windows, this value is the 48-bit Bluetooth MAC address of the device. On macOS, this value is a random 128-bit OS-assigned address.

Data Types: string

This property is read-only.

Peripheral device connection status, returned as numeric or logical 1 (true) or 0 (false).

Data Types: logical

This property is read-only.

Services included on the peripheral device, returned as a table. The table has the following columns.

ColumnDescription
ServiceNameName of the service included on the peripheral device, returned as a string
ServiceUUIDUUID of the service included on the peripheral device, returned as a string

For a full list of standard services and their UUIDs, see the Bluetooth SIG website. All custom services have the name "Custom" and are differentiated by their UUID values.

Note

On macOS, the "Generic Access" and "Generic Attributes" services and their characteristics are hidden. The Services and Characteristics properties do not show them.

Data Types: table

This property is read-only.

Characteristics included on the peripheral device, returned as a table. To access a specific characteristic listed in the table, create an object using characteristic. This table has the following columns.

ColumnDescription
ServiceNameName of the service included on the peripheral device, returned as a string
ServiceUUIDUUID of the service included on the peripheral device, returned as a string
CharacteristicNameName of the characteristic included on the peripheral device, returned as a string
CharacteristicUUIDUUID of the characteristic included on the peripheral device, returned as a string
AttributesSupported operations on a characteristic, returned as a cell array. See the Attributes property for possible values

For a full list of standard characteristics and how to interpret them, see the Bluetooth SIG website. All custom characteristics have the name "Custom" in the Characteristics table and are differentiated by their UUID values.

Note

On macOS, the "Generic Access" and "Generic Attributes" services and their characteristics are hidden. The Services and Characteristics properties do not show them.

Data Types: table

Object Functions

characteristicAccess a characteristic on Bluetooth Low Energy peripheral device

Examples

collapse all

Search for and establish a connection to your Bluetooth Low Energy peripheral device.

Scan for nearby peripheral devices that have the name "Gear Fit2 (E16A)" using blelist.

blelist("Name","Gear Fit2 (E16A)")
ans=1×5 table
    Index           Name              Address        RSSI    Advertisement
    _____    __________________    ______________    ____    _____________

      1      "Gear Fit2 (E16A)"    "8498663EE16A"    -61     [1×1 struct] 

Create a connection to the device.

b = ble("Gear Fit2 (E16A)")
b = 
  ble with properties:

               Name: "Gear Fit2 (E16A)"
            Address: "8498663EE16A"
          Connected: 1
           Services: [2×2 table]
    Characteristics: [3×5 table]

Show services and characteristics

Search for and establish a connection to your Bluetooth Low Energy peripheral device.

Scan for nearby peripheral devices that have the name "Gear Fit2 (E16A)" using blelist.

blelist("Name","Gear Fit2 (E16A)")
ans=1×5 table
    Index           Name              Address        RSSI    Advertisement
    _____    __________________    ______________    ____    _____________

      1      "Gear Fit2 (E16A)"    "8498663EE16A"    -58     [1×1 struct] 

Create a connection to the device with address "8498663EE16A". On a Windows® computer, this address represents the 48-bit Bluetooth MAC address of the peripheral device.

b = ble("8498663EE16A")
b = 
  ble with properties:

               Name: "Gear Fit2 (E16A)"
            Address: "8498663EE16A"
          Connected: 1
           Services: [2×2 table]
    Characteristics: [3×5 table]

Show services and characteristics

Search for and establish a connection to your Bluetooth Low Energy peripheral device.

Scan for nearby peripheral devices that have the name "Gear Fit2 (E16A)" using blelist.

blelist("Name","Gear Fit2 (E16A)")
ans=1×5 table
    Index           Name                          Address                    RSSI    Advertisement
    _____    __________________    ______________________________________    ____    _____________

      1      "Gear Fit2 (E16A)"    "2F4AFADA-1F14-4BBD-A1F1-E7E64C0CF5BA"    -49     [1×1 struct] 

Create a connection to the device with address "2F4AFADA-1F14-4BBD-A1F1-E7E64C0CF5BA". On a macOS computer, this address represents the random 128-bit OS-assigned address of the peripheral device.

b = ble("2F4AFADA-1F14-4BBD-A1F1-E7E64C0CF5BA")
b = 
  ble with properties:

               Name: "Gear Fit2 (E16A)"
            Address: "2F4AFADA-1F14-4BBD-A1F1-E7E64C0CF5BA"
          Connected: 1
           Services: []
    Characteristics: []

Show services and characteristics

Version History

Introduced in R2019b