Bluetooth Device Pairing

Last Updated on : 2025-04-16 06:09:12download

Bluetooth device search and pairing applies to Bluetooth Low Energy (LE), Bluetooth mesh, combo device, and beacon.

Bluetooth types

Bluetooth type	Description	Example
Bluetooth LE	A point-to-point connection is created between a Bluetooth or Bluetooth LE device and a mobile phone.	Body fat scales, wrist-worn trackers, thermostats, electric toothbrushes, and smart locks
Bluetooth mesh	Enable many-to-many (m:m) device communications over a mesh network released by Bluetooth SIG.	Cool white lights (C), cool and warm white lights (CW), white and colored lights (RGBCW), sockets, sensors, and other sub-devices
Combo devices	Devices that support both Bluetooth and other protocols, such as Wi-Fi and Bluetooth LE combo, can be paired over Bluetooth.	Bluetooth mesh gateways, IP cameras (IPCs), and Wi-Fi and Bluetooth combo devices
Bluetooth beacon	Bluetooth beacon is a broadcast protocol built on top of Bluetooth LE.	Lights, fans, remotes, and body fat scales.

Start searching

val scanKey = ThingActivatorCoreKit.getScanDeviceManager().startBlueToothDeviceSearch(
        millisTimeOut: Long,
        scanTypeList: List<ScanType>,
        thingActivatorScanCallback: ThingActivatorScanCallback
    )

Parameter description

Parameters	Description
scanTypeList	`SINGLE` `MESH` `SIG_MESH` `SINGLE_QR` `THING_BEACON`
millisTimeOut	The timeout value, in milliseconds.
thingActivatorScanCallback	The search timeout callback.

Description of ScanType

`ScanType` enum	Applicability
SINGLE	Bluetooth LE device: `ThingDeviceBlueActiveTypeEnum.SINGLE_BLE` `ThingDeviceBlueActiveTypeEnum.BLE_WIFI` `ThingDeviceBlueActiveTypeEnum.MULT_MODE`
SIG_MESH	Bluetooth mesh device: `ThingDeviceBlueActiveTypeEnum.SIGMESH_SUB`
THING_BEACON	Bluetooth beacon device: `ThingDeviceBlueActiveTypeEnum.BEACON`

Stop searching

ThingActivatorCoreKit.getScanDeviceManager().stopScan(scanKey)

Start pairing

Bluetooth LE

val builder = ThingDeviceActiveBuilder()
        builder.thingActivatorScanDeviceBean = thingActivatorScanDeviceBean
        builder.timeout = 120L
        builder.relationId = relationId
        builder.activeModel = ThingDeviceActiveModeEnum.SINGLE_BLE
        builder.listener = object : IThingDeviceActiveListener {
            override fun onActiveError(errorBean: ThingDeviceActiveErrorBean) {

            }

            override fun onActiveLimited(limitBean: ThingDeviceActiveLimitBean) {

            }

            override fun onActiveSuccess(deviceBean: DeviceBean) {

            }

            override fun onBind(devId: String) {

            }

            override fun onFind(devId: String) {

            }

        }

val activeManager = ThingActivatorCoreKit.getActiveManager().newThingActiveManager()
activeManager.startActive(builder)

Parameter description

Parameters	Description
thingActivatorScanDeviceBean	The discovered device.
relationId	The home ID.
timeout	The pairing timeout value, in seconds.
activeModel	The pairing capability enum.
listener	The callback for the result of pairing.

Bluetooth LE and Wi-Fi combo

val builder = ThingDeviceActiveBuilder()
        builder.thingActivatorScanDeviceBean = thingActivatorScanDeviceBean
        builder.timeout = 120L
        builder.relationId = relationId
        builder.ssid = ssid
        builder.password = password
        builder.activeModel = ThingDeviceActiveModeEnum.BLE_WIFI
        builder.listener = object : IThingDeviceStatePauseActiveListener {
                override fun onFind(devId: String) {
                }

                override fun onBind(devId: String) {
                }

                override fun onActiveSuccess(deviceBean: DeviceBean) {

                }

                override fun onActiveError(errorBean: ThingDeviceActiveErrorBean) {

                }

                override fun onActiveLimited(limitBean: ThingDeviceActiveLimitBean) {
                }

        override fun onActivatorStatePauseCallback(stateData: PauseStateData?) {

                }
            }

val activeManager = ThingActivatorCoreKit.getActiveManager().newThingActiveManager()
activeManager.startActive(builder)

Parameter description

Parameters	Description
thingActivatorScanDeviceBean	The discovered device.
relationId	The home ID.
ssid	The name of the target Wi-Fi network.
password	The password of the target Wi-Fi network.
timeout	The pairing timeout value, in seconds.
activeModel	The pairing capability enum.
listener	The callback for the result of pairing.

If you do not listen for onActivatorStatePauseCallback, use IThingDeviceActiveListener instead.
onActivatorStatePauseCallback returns the reason for the paused pairing, such as an incorrect password or router connection failure. The app can rescan for Wi-Fi networks and select one again. Then, call resumeActive to continue pairing.

Restart pairing

When a device returns the reason for the paused pairing (such as an incorrect password or router connection failure) through onActivatorStatePauseCallback, the app can restart the pairing process with the method ThingResumeActiveBuilder.

val builder = ThingResumeActiveBuilder(uuid)

activeManager.resumeActive(builder)

Parameter description

`resumeType` enum	Description
RESUME_TYPE_WIFI	Continue the Wi-Fi pairing process.
RESUME_TYPE_BLE	Pair over Bluetooth due to unavailable Wi-Fi.

Bluetooth mesh

val builder = ThingDeviceActiveBuilder()
        builder.meshSearchBeans = meshSearchBeanList
        builder.timeout = 120L
        builder.relationId = relationId
        builder.currentMeshBean = currentMeshBean
        builder.activeModel = ThingDeviceActiveModeEnum.SIGMESH_SUB
        builder.listener = object : IThingDeviceActiveListener {
            override fun onActiveError(errorBean: ThingDeviceActiveErrorBean) {

            }

            override fun onActiveLimited(limitBean: ThingDeviceActiveLimitBean) {

            }

            override fun onActiveSuccess(deviceBean: DeviceBean) {

            }

            override fun onBind(devId: String) {

            }

            override fun onFind(devId: String) {

            }

        }

val activeManager = ThingActivatorCoreKit.getActiveManager().newThingActiveManager()
activeManager.startActive(builder)

Parameter description

Parameters	Description
meshSearchBeans	The list of discovered devices.
relationId	The home ID.
timeout	The pairing timeout value, in seconds.
currentMeshBean	The current Bluetooth mesh network.
activeModel	The pairing capability enum.
listener	The callback for the result of pairing.

For more information about a Bluetooth mesh network, see Initialize a Bluetooth mesh network.

Beacon

val builder = ThingDeviceActiveBuilder()
        builder.meshSearchBeans = meshSearchBeanList
        builder.timeout = 120L
        builder.relationId = relationId
        builder.activeModel = ThingDeviceActiveModeEnum.BEACON
        builder.listener = object : IThingDeviceActiveListener {
            override fun onActiveError(errorBean: ThingDeviceActiveErrorBean) {

            }

            override fun onActiveLimited(limitBean: ThingDeviceActiveLimitBean) {

            }

            override fun onActiveSuccess(deviceBean: DeviceBean) {

            }

            override fun onBind(devId: String) {

            }

            override fun onFind(devId: String) {

            }

        }

val activeManager = ThingActivatorCoreKit.getActiveManager().newThingActiveManager()

activeManager.startActive(builder)

activeManager.stopActive()

activeManager.stop(thingActivatorScanDeviceBean.uniqueId)

Parameter description

Parameters	Description
meshSearchBeans	The list of discovered devices.
relationId	The home ID.
timeout	The pairing timeout value, in seconds.
activeModel	The pairing capability enum.
listener	The callback for the result of pairing.

Stop pairing

activeManager.stopActive()

Prev DocWi-Fi AP Mode

Next DocSub-Device Pairing