blelist

Scan nearby Bluetooth Low Energy peripheral devices

collapse all in page

Syntax

list = blelist
list = blelist(Name,Value)

Description

list = blelist scans nearby advertising Bluetooth® Low Energy peripheral devices detected by your computer. Use ble to connect to a peripheral device.

example

list = blelist(Name,Value) scans using optional name-value pair arguments. Use name-value pair arguments to scan for specific devices or to scan for a longer time.

example

Examples

collapse all

Open Live Script

Scan for nearby Bluetooth Low Energy peripheral devices and look at the device advertisement data.

Use blelist to list all nearby peripheral devices that are currently advertising data. If your peripheral device is already connected to another device or application, it may not appear in this list. Disconnect your peripheral device from any other devices or applications first for MATLAB® to discover it.

list = blelist
list=14×5 table
    Index           Name              Address        RSSI    Advertisement
    _____    __________________    ______________    ____    _____________

      1      "Gear Fit2 (E16A)"    "8498663EE16A"    -54     [1×1 struct] 
      2      ""                    "2C4D2724754D"    -69     [1×1 struct] 
      3      ""                    "1B75E09FD18F"    -70     [1×1 struct] 
      4      ""                    "4F7D6DAF9FCE"    -75     [1×1 struct] 
      5      ""                    "7B8ADB5851BD"    -76     [1×1 struct] 
      6      ""                    "1838D92EC312"    -78     [1×1 struct] 
      7      ""                    "6A71507635AC"    -86     [1×1 struct] 
      8      ""                    "68CA4203A060"    -86     [1×1 struct] 
      9      ""                    "65C057AD64E5"    -88     [1×1 struct] 
     10      ""                    "399A1B26F47D"    -88     [1×1 struct] 
     11      ""                    "78BDCC3784C0"    -89     [1×1 struct] 
     12      ""                    "5446498F593E"    -91     [1×1 struct] 
     13      ""                    "67992F048DDB"    -92     [1×1 struct] 
     14      ""                    "3A0DAC7C7DCE"    -94     [1×1 struct]

The RSSI values indicate signal strength. The table lists devices with a stronger signal first. These devices are closer.

View advertisement data of the first device.

list.Advertisement(1)
ans = struct with fields:
                            Type: ["Connectable Undirected"    "Scan Response"]
                      Appearance: "Generic Watch"
              ShortenedLocalName: []
               CompleteLocalName: "Gear Fit2 (E16A)"
                    TxPowerLevel: []
    SlaveConnectionIntervalRange: []
        ManufacturerSpecificData: [0 117 1 0 2 0 1 3 0]
                     ServiceData: []
            CompleteServiceUUIDs: []
          IncompleteServiceUUIDs: []
        ServiceSolicitationUUIDs: []

If your device has a larger advertising interval than the default timeout value of three seconds, you can specify a larger timeout value.

list = blelist('Timeout',10);
Open Live Script

You can use name-value pair arguments to scan for Bluetooth Low Energy peripheral devices with a specified name prefix or advertising specified services.

Scan for peripheral devices with names starting with the string "UA".

list = blelist("Name","UA")
list=2×5 table
    Index           Name               Address        RSSI    Advertisement
    _____    ___________________    ______________    ____    _____________

      1      "UA E39 MODULE"        "84DD20E39AB6"    -84     [1×1 struct] 
      2      "UA Footpod 239AE2"    "0CF3EE239AE2"    -87     [1×1 struct]

You can also scan for peripheral devices by their services. Scan for devices that advertise the Heart Rate service.

list = blelist("Services","Heart Rate")
list=1×5 table
    Index    Name       Address        RSSI    Advertisement
    _____    ____    ______________    ____    _____________

      1       ""     "84DD20E39AB6"    -85     [1×1 struct]

Name-Value Arguments

collapse all

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: list = blelist("Name","UA") returns all peripheral devices with names that start with "UA".

Peripheral device name for filtering results, specified as the comma-separated pair consisting of 'Name' and a character vector or string scalar. Using this name-value pair argument lists only peripheral devices that start with the specified value in their names.

Example: list = blelist("Name","Pebble") returns all peripheral devices with names that start with "Pebble".

Data Types: char | string

Service name or UUID for filtering results, specified as the comma-separated pair consisting of 'Services' and a character vector, string scalar, cell array of character vectors, or string array. Using this name-value pair argument produces a list of only peripheral devices that advertise all the specified services.

Example: list = blelist("Services",["180a","180d"]) returns all peripheral devices that advertise both services with the UUIDs 180a and 180d.

Example: list = blelist("Services","Heart Rate") returns all peripheral devices that advertise the service "Heart Rate".

Data Types: char | string | cell

Amount of time to scan for in seconds, specified as the comma-separated pair consisting of 'Timeout' and a number. The value must be less than 10,485. If you are unable to find your device using blelist, try a larger value for this parameter.

Example: list = blelist("Timeout",20) searches for nearby peripheral devices for 20 seconds.

Data Types: double

Output Arguments

collapse all

List of nearby peripheral devices, returned as a table. The table has the following columns.

Peripheral device name, returned as a string scalar.

Data Types: string

Peripheral device identifier, 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

Signal strength in dB, returned as a double. RSSI is the received signal strength indicator. The table lists devices with a stronger signal first. These devices are closer to your computer.

Data Types: double

Advertisement data of a peripheral device, returned as a structure. Advertisement contains connection information about each peripheral device.

On Windows, the Type field shows the connection status, returned as a string. The possible values follow.

ValuePeripheral device description
"Connectable Undirected"Can connect to your computer
"Connectable Directed"Can connect to your computer only if it is programmed to do so
"Nonconnectable Undirected"Cannot connect to your computer but sends advertising information
"Scannable Undirected"Cannot connect to your computer but is scannable
"Scan Response"Sends a scan response to a scan request

On macOS, the Connectable field shows the connection status, returned as a number. 1 indicates true, or connectable, and 0 or any other number indicates false, or nonconnectable.

The rest of the fields in Advertisement are other advertisement data defined in the Generic Access Profile (GAP) by Bluetooth SIG. For a full list of advertising data types and references to their specifications, see the Bluetooth SIG website.

Data Types: struct

Version History

Introduced in R2019b

See Also

Topics