You are here: Lua Scripting Resources eGuide > Lua Scripting API Reference Guide > Bluetooth® Smart Library > startScanning

20.2.1 startScanning

error = bleCentral.startScanning([UUID, ] callback [, object])

Scans for Bluetooth® LE devices advertising a service with the given service UUID (Universal Unique Identifier) or for Bluetooth® LE devices advertising any service if no UUID is provided. Successive calls of startScanning automatically stop previous scans. A malformed UUID will cause a Lua error as this is an authoring error and not a run-time error..

Parameter

Type

Description

UUID

in string
(optional)

UUID of the service searched for.
The UUID can be provided in 16- or 128-bit format.

callback

in function

Callback to receive asynchronously peripherals
found, one peripheral at a time

object

in any
(optional)

If an object is provided it will be passed as the first parameter to the specified callback function.
The object can be of any type except nil.

error

out string
(optional)

If successful nil is returned, an error message otherwise

Introduced in platform.apiLevel = '2.5'

Callback Function

callback([object,] peripheral, advertisementData, isConnectable, RSSI)

The callback function provided in startScanning will be called for every Bluetooth® LE device fulfilling the search criteria. The peripheral parameter will be a peripheral object representing the found Bluetooth® LE device. The same peripheral object might be reported more than once based on peripheral and platform behavior.

Parameter

Type

Description

object

in any
(optional)

If an object was provided as a parameter to the function startScanning, it will be passed as the first parameter to this callback function

peripheral

in peripheral object

One peripheral found during scanning

advertisementData

in table

A table containing the advertisement data of the
device..

isConnectable

in boolean

true if the device advertises as connectable, otherwise false

RSSI

in Integer value

The received signal strength indicator (RSSI) in dbm.

Advertisement Data Keys

The constants described in the following table are part of the ble table, e.g.

ble.AD TX POWER LEVEL.

Name

Description

AD NAME

Same as the device name or a shortened name. Please see subsection 20.3.1 for peripheral:getName().

AD MANUFACTURER DATA

Bluetooth® technology is switched off. This implies that any A string with the first 2 octets identifying the manufacturer (see Company Identifiers.). The interpretation of any other octet in the string is manufacturer specific.

AD SERVICE UUIDS

A list of service UUIDs. This list might be complete or not.

AD TX POWER LEVEL

If provided by the device, the sending power level of the device in dBm. Subtracting the RSSI value from the power level can be used to compare the approximate distance of different devices

Introduced in platform.apiLevel = '2.5'

Extended in platform.apiLevel = ‘2.6'