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

20.3.3 connect

error = peripheral:connect([timeout, ]callback [, object])

Requests connection to the Bluetooth® LE device represented by the peripheral object. The callback will be called for all events related to the connection state of this peripheral object. An optional timeout can be provided to automatically abort the request after the time specified. After disconnecting or after a failure during the connection procedure, the specified callback will not be referenced anymore.

Caution

Please make sure you disconnect peripheral objects before closing the document. A simple way to do so is by calling peripheral:disconnect() from the on.destroy() event.

Parameter

Type

Description

timeout

in number
(optional)

If provided, connection request aborts after the specified time in seconds.
The specified time can be between 0 and 3600. 0 or less waits forever, anything above 3600 defaults to 3600.

callback

in function

Callback to receive asynchronous events about the connection state

object

out 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'

Extended in platform.apiLevel = ‘2.6'

Callback Function

callback([object,] peripheral, event [, error])

The callback function provided in peripheral:connect() will be called for every event related to the connection state between the Bluetooth ® LE central and the peripheral. Based on whether
an object was provided in the call to connectPeripheral, the callback should have three or four parameters.

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

A peripheral found during scanning

event

in bleCentral table constant

Please see the following section for details

error

in string (optional) )

If successfully connected or disconnected the
parameter will be nil, an error message otherwise (unsuccessful connection or dropped connected)

Event Constants

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

Name

Description

CONNECTED

The connection has been successfully established

CONNECTING FAILED

The connect procedure failed. A new call of the connect() function is required to retry connecting.

DISCONNECTED

The connection has been successfully terminated

Introduced in platform.apiLevel = '2.5'