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

Syntax

b = ble(name)

b = ble(address)

Description

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

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

Input Arguments

name — Device name

character vector | string scalar

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

address — Device address

character vector | string scalar

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

Name — Peripheral device name

string scalar

This property is read-only.

Peripheral device name, returned as a string scalar.

Data Types: string

Address — Peripheral device address

string scalar

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

Connected — Peripheral device connection status

true or 1 | false or 0

This property is read-only.

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

Data Types: logical

Services — Services included on peripheral device

table

This property is read-only.

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

Column	Description
ServiceName	Name of the service included on the peripheral device, returned as a string
ServiceUUID	UUID 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

Characteristics — Characteristics included on peripheral device

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.

Column	Description
ServiceName	Name of the service included on the peripheral device, returned as a string
ServiceUUID	UUID of the service included on the peripheral device, returned as a string
CharacteristicName	Name of the characteristic included on the peripheral device, returned as a string
CharacteristicUUID	UUID of the characteristic included on the peripheral device, returned as a string
Attributes	Supported 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

characteristic

Access a characteristic on Bluetooth Low Energy peripheral device

Examples

Connect to a Bluetooth Low Energy Peripheral Device Using Its Name

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

Connect to a Bluetooth Low Energy Peripheral Device Using Its Address on Windows

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

Connect to a Bluetooth Low Energy Peripheral Device Using Its Address on macOS

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