Device Pairing

Overview

Empower smart devices to be paired through routers or gateways. The typical pairing mode is Wi-Fi Easy Connect (EZ). In this mode, the SDK gets the pairing token from the cloud and enables the app to broadcast the pairing information. The router ID, password, and pairing token are published. Then, the smart device receives the pairing information and starts the activation process. The activated device is connected to both the app and the cloud. Now, you have kicked off your journey with smart control in the cloud.

Functional description

Device pairing of the HarmonyOS SDK supports the following features:

• Wi-Fi device pairing, including the following modes:
  • Wi-Fi Easy Connect mode (a.k.a. EZ mode)
  • Wi-Fi access point mode (a.k.a. AP mode)
• Bluetooth device pairing
  • Bluetooth low energy device pairing
  • Bluetooth and Wi-Fi combo device pairing
• Wired device pairing
• Sub-device pairing
• Smart camera pairing in QR code mode
• Device paring in QR code mode

How-to

Import the module.

import {
  ITSmartActivator,
  ITSmartActivatorListener,
  TSmartActivator,
  TSmartActivatorBuilder,
  TSmartActivatorStep,
  TSmartDeviceType,
  TSmartScanMode,
  TSmartScannerBuilder,
  TSmartScannerListener,
  TSmartScannerResult
} from '@thingsmart/activator';

Terms

The following table lists specific terms and definitions that are used in this topic. For more information, see Glossary.

Term	Description
Wi-Fi device	A smart device that uses a Tuya Wi-Fi module to connect to a router and interact with apps and the cloud.
Wi-Fi Easy Connect	Also known as the EZ mode. This pairing mode is implemented through the following steps: 1. The app encapsulates the pairing data into the specified section of an IEEE 802.11 packet and sends the packet to the network. 2. The Wi-Fi module of a smart device runs in promiscuous mode and listens for and captures all packets over the network. 3. The Wi-Fi mode parses the packets that carry the pairing data from the app into the data format specified by the protocol.
AP Pairing	Also known as the AP mode. A mobile phone acts as a station (STA) and connects to the AP of a smart device. Then, both devices establish a socket connection to exchange data through a designated port.
IPC pairing with QR code scanning	A camera device scans the QR code on the app to get the pairing data.
Wired device	A device that connects to a router over a wired network. For example, a wired device can be a Zigbee wired gateway or a wired camera.
Sub-device	A device that interacts with apps and the cloud through a gateway. For example, a Zigbee sub-device is such a device.
Zigbee	Zigbee is a short-range, simple, low-power, low-data-rate, cost-efficient, and two-way wireless communication technology. It applies to short-range, low-power, and low-rate data transfer between various electronic devices, periodic data transfer, intermittent data transfer, and data transfer at a longer interval.
Zigbee gateway	The device that integrates the Zigbee coordinator and Wi-Fi features. It is used for Zigbee networking and data storage.
Zigbee sub-device	A router or an end device on a Zigbee network. Each Zigbee sub-device forwards data, or responds to control commands.

APIs

TSmartActivatorRequester

Pairing request

getActivatorToken

Get a pairing token.

getActivatorToken(homeId: number): Promise<TSmartActivatorToken | null | undefined>

Parameters:

Parameter	Type	Required	Description
homeId	number	Yes	The ID of the specified home.

Return value:

Type	Description
Promise	Returns a Promise of type TSmartActivatorToken | null | undefined.

parseQRCode

Parse a QR code. During pairing, it is used to scan the device’s QR code to parse its data.

parseQRCode(content: string): Promise<Record<string, Object>>

Parameters:

Parameter	Type	Required	Description
content	string	Yes	The text content of the QR code obtained after camera scanning.

Return value:

Type	Description
Promise	Returns a Promise of type Record<string, Object>.

getMQTTDirectlyActivatorToken

Get a token when scanning a device QR code.

getMQTTDirectlyActivatorToken(homeId: number, uuid: string): Promise<TSmartActivatorToken>

Parameters:

Parameter	Type	Required	Description
homeId	number	Yes	The ID of the specified home.
uuid	string	Yes	The device UUID parsed from the QR code.

Return value:

Type	Description
Promise	Returns a Promise of type TSmartActivatorToken.

TSmartScannerBuilder

Device scanning

constructor

constructor(scanListener: TSmartScannerListener)

Parameters:

Parameter	Type	Required	Description
scanListener	TSmartScannerListener	Yes	The scanner listener. When a device is detected, it calls the methods within the listener.

setScanTimeout

It must be called before starting the scan to take effect.

setScanTimeout(scanTimeout: number): TSmartScannerBuilder

Parameters:

Parameter	Type	Required	Description
scanTimeout	number	Yes	The timeout duration in milliseconds. The default value is 120 seconds. Scanning will stop when this duration is reached.

Return value:

Type	Description
TSmartScannerBuilder	Returns an instance of the device scanner class, facilitating chained calls to other configuration methods.

addScanMode

Add the specified scanning mode, primarily including Bluetooth scanning and LAN scanning.

addScanMode(scanMode: TSmartScanMode): TSmartScannerBuilder

Parameters:

Parameter	Type	Required	Description
scanMode	TSmartScanMode	Yes	The scanning mode.

Return value:

Type	Description
TSmartScannerBuilder	Returns an instance of the device scanner class, facilitating chained calls to other configuration methods.

startScan

Start scanning. Scanning results are returned via the scan listener callback.

startScan(): void

stopScan

Stop all scanning modes.

stopScan(): void

stopScanMode

Stop the specified scanning mode.

stopScanMode(model: TSmartScanMode): void

TSmartScannerListener

Name	Type	Required	Description
onDeviceFound	(scanResult: TSmartScannerResult) => void	Yes	Device discovery listener method. It is called when a device is discovered.
onStop	(error: Error) => void	No	Device discovery stop callback method. It is called when the device discovery times out. This callback will not occur after a manual stop.

TSmartScannerResult

Name	Type	Required	Description
uniqueId	string	Yes	The unique ID of the specified device.
productId	string	Yes	The product ID.
deviceType	TSmartDeviceType	Yes	The device type.
name	string	Yes	The device name. The value is obtained via a network request. If the request fails, it will default to “New Device”.
icon	string	Yes	The URL of a device icon. The value is obtained via a network request. If the request fails, it will default to an empty string.
scannedBleDevice	Device	No	This value is present when it is a Bluetooth device or a combo device.

TSmartScanMode

export enum TSmartScanMode {
  SCAN_MODE_BLE = 1 << 0,       // Bluetooth scanning
  SCAN_MODE_LAN = 1 << 1,       // LAN scanning
}

TSmartDeviceType

export enum TSmartDeviceType {
  BLE,              // Bluetooth device
  WIFI_BLE,         // Combo device
  WIRED             // Wired device
}

TSmartActivator

Device pairing

createActivator

createActivator(builder: TSmartActivatorBuilder): ITSmartActivator

Parameters:

Parameter	Type	Required	Description
builder	TSmartActivatorBuilder	Yes	Create an instance that implements the ITSmartActivator interface via the builder.

Return value:

Type	Description
ITSmartActivator	Returns an instance that implements the ITSmartActivator interface.

buildApActivatorBuilder

This method is called to create a builder during AP pairing.

buildApActivatorBuilder(
    ssid: string,
    password: string,
    timeout: number = 120000,
    token: TSmartActivatorToken,
    listener: ITSmartActivatorListener,
    homeId: number,
    extraParameters?: Record<string, Object>
  ): TSmartActivatorBuilder

Parameters:

Parameter	Type	Required	Description
ssid	string	Yes	The name of the specified Wi-Fi network.
password	string	Yes	The password of the specified Wi-Fi network.
timeout	number	No	The timeout duration in milliseconds. The default value is 120 seconds.
token	TSmartActivatorToken	Yes	The token, obtained via getActivatorToken.
listener	ITSmartActivatorListener	Yes	The pairing listener. The pairing result will be returned via a callback in the listener.
homeId	number	Yes	The ID of the specified home.
extraParameters	Record<string, Object>	No	Reserved for additional parameters.

Return value:

Type	Description
TSmartActivatorBuilder	Returns a builder of the TSmartActivatorBuilder type.

buildEzActivatorBuilder

This method is called to create a builder during EZ pairing.

buildEzActivatorBuilder(
    ssid: string,
    password: string,
    timeout: number = 120000,
    listener: ITSmartActivatorListener,
    homeId: number,
    token?: TSmartActivatorToken,
    extraParameters?: Record<string, Object>
  ): TSmartActivatorBuilder

Parameters:

Parameter	Type	Required	Description
ssid	string	Yes	The name of the specified Wi-Fi network.
password	string	Yes	The password of the specified Wi-Fi network.
timeout	number	No	The timeout duration in milliseconds. The default value is 120 seconds.
listener	ITSmartActivatorListener	Yes	The pairing listener. The pairing result will be returned via a callback in the listener.
homeId	number	Yes	The ID of the specified home.
token	TSmartActivatorToken	No	The token, obtained through getActivatorToken. If not provided, it will be obtained internally using homeId.
extraParameters	Record<string, Object>	No	Reserved for additional parameters.

Return value:

Type	Description
TSmartActivatorBuilder	Returns a builder of the TSmartActivatorBuilder type.

buildWiredActivatorBuilder

This method is called to create a builder when pairing a wired device over LAN.

buildWiredActivatorBuilder(
    homeId: number,
    gwId: string,
    productId: string,
    timeout: number = 120000,
    listener: ITSmartActivatorListener,
    token?: TSmartActivatorToken,
    extraParameters?: Record<string, Object>
  ): TSmartActivatorBuilder

Parameters:

Parameter	Type	Required	Description
homeId	number	Yes	The ID of the specified home.
gwId	string	Yes	Corresponds to the uniqueId in TSmartScannerResult.
productId	string	Yes	Corresponds to the productId in TSmartScannerResult.
timeout	number	No	The timeout duration in milliseconds. The default value is 120 seconds.
listener	ITSmartActivatorListener	Yes	The pairing listener. The pairing result will be returned via a callback in the listener.
token	TSmartActivatorToken	No	The token, obtained through getActivatorToken. If not provided, it will be obtained internally using homeId.
extraParameters	Record<string, Object>	No	Reserved for additional parameters.

Return value:

Type	Description
TSmartActivatorBuilder	Returns a builder of the TSmartActivatorBuilder type.

buildSubDeviceActivatorBuilder

This method is called to create a builder when pairing a gateway sub-device.

buildSubDeviceActivatorBuilder(gwId: string, timeout: number = 120000, listener: ITSmartActivatorListener, extraParameters?: Record<string, Object>): TSmartActivatorBuilder

Parameters:

Parameter	Type	Required	Description
gwId	string	Yes	The virtual ID of the gateway.
timeout	number	No	The timeout duration in milliseconds. The default value is 120 seconds.
listener	ITSmartActivatorListener	Yes	The pairing listener. The pairing result will be returned via a callback in the listener.
extraParameters	Record<string, Object>	No	Reserved for additional parameters.

Return value:

Type	Description
TSmartActivatorBuilder	Returns a builder of the TSmartActivatorBuilder type.

buildBleActivatorBuilder

This method is called to create a builder when pairing a Bluetooth LE device.

buildBleActivatorBuilder(
    homeId: number,
    timeout: number = 60000,
    listener: ITSmartActivatorListener,
    extraParameters?: Record<string, Object>
  ): TSmartActivatorBuilder

Parameters:

Parameter	Type	Required	Description
homeId	number	Yes	The ID of the specified home.
timeout	number	No	The timeout duration in milliseconds. The default value is 60 seconds.
listener	ITSmartActivatorListener	Yes	The pairing listener. The pairing result will be returned via a callback in the listener.
extraParameters	Record<string, Object>	No	Reserved for additional parameters.

Return value:

Type	Description
TSmartActivatorBuilder	Returns a builder of the TSmartActivatorBuilder type.

buildBleWifiActivatorBuilder

This method is called to create a builder when pairing a Wi-Fi and Bluetooth combo device.

buildBleWifiActivatorBuilder(
    homeId: number,
    ssid: string,
    password: string,
    timeout: number = 120000,
    listener: ITSmartActivatorListener,
    token?: TSmartActivatorToken,
    extraParameters?: Record<string, Object>
  ): TSmartActivatorBuilder

Parameters:

Parameter	Type	Required	Description
homeId	number	Yes	The ID of the specified home.
ssid	string	Yes	The name of the specified Wi-Fi network.
password	string	Yes	The password of the specified Wi-Fi network.
timeout	number	No	The timeout duration in milliseconds. The default value is 120 seconds.
token	TSmartActivatorToken	No	The token, obtained through getActivatorToken. If not provided, it will be obtained internally using homeId.
listener	ITSmartActivatorListener	Yes	The pairing listener. The pairing result will be returned via a callback in the listener.
extraParameters	Record<string, Object>	No	Reserved for additional parameters.

Return value:

Type	Description
TSmartActivatorBuilder	Returns a builder of the TSmartActivatorBuilder type.

buildQRCodeActivatorBuilder

This method is called to create a builder when an IPC device scans a QR code on the app for pairing. The QR code string is obtained through the getQRCodeString method.

buildQRCodeActivatorBuilder(
    homeId: number,
    ssid: string,
    password: string,
    timeout: number = 120000,
    listener: ITSmartActivatorListener,
    token: TSmartActivatorToken,
    extraParameters?: Record<string, Object>
  ): TSmartActivatorBuilder

Parameters:

Parameter	Type	Required	Description
homeId	number	Yes	The ID of the specified home.
ssid	string	Yes	The name of the specified Wi-Fi network.
password	string	Yes	The password of the specified Wi-Fi network.
timeout	number	No	The timeout duration in milliseconds. The default value is 120 seconds.
listener	ITSmartActivatorListener	Yes	The pairing listener. The pairing result will be returned via a callback in the listener.
token	TSmartActivatorToken	Yes	The value is obtained through getActivatorToken. Note that this token must be consistent with the one used in the getQRCodeString method.
extraParameters	Record<string, Object>	No	Reserved for additional parameters.

Return value:

Type	Description
TSmartActivatorBuilder	Returns a builder of the TSmartActivatorBuilder type.

getQRCodeString

Assemble the ssid, password, and token into a single string, used to generate a QR code for pairing by scanning with IPC devices.

getQRCodeString(ssid: string, password: string, token: TSmartActivatorToken): string

Parameters:

Parameter	Type	Required	Description
ssid	string	Yes	The name of the specified Wi-Fi network.
password	string	Yes	The password of the specified Wi-Fi network.
token	TSmartActivatorToken	Yes	The value is obtained through getActivatorToken. Note that this token must be consistent with the one used in the buildQRCodeActivatorBuilder method.

Return value:

Type	Description
string	The returned string is used to generate the QR code.

buildMQTTDirectlyActivatorBuilder

This method is called to create a builder when the app scans the device’s QR code for pairing. The UUID parameter is obtained by parsing the QR code, using the parseQRCode method. The token parameter is obtained by calling the getMQTTDirectlyActivatorToken method.

buildMQTTDirectlyActivatorBuilder(
    homeId: number,
    uuid: string,
    timeout: number = 120000,
    listener: ITSmartActivatorListener,
    token?: TSmartActivatorToken,
    extraParameters?: Record<string, Object>
  ): TSmartActivatorBuilder

Parameters:

Parameter	Type	Required	Description
homeId	number	Yes	The ID of the specified home.
uuid	string	Yes	The device UUID, obtained by calling the parseQRCode method.
timeout	number	No	The timeout duration in milliseconds. The default value is 120 seconds.
listener	ITSmartActivatorListener	Yes	The pairing listener. The pairing result will be returned via a callback in the listener.
token	TSmartActivatorToken	Yes	Obtained by getMQTTDirectlyActivatorToken.
extraParameters	Record<string, Object>	No	Reserved for additional parameters.

Return value:

Type	Description
TSmartActivatorBuilder	Returns a builder of the TSmartActivatorBuilder type.

ITSmartActivatorListener

Pairing listener

Name	Type	Required	Description
onActiveSetpAndError	(step: TSmartActivatorStep, error?: Error, device?: TSmartDeviceModel) => void	No	The listener method for the pairing process. It is called back when there is a change or an error during the process.
onActiveSuccess	(deviceModel: TSmartDeviceModel) => void	Yes	Pairing success callback.

TSmartActivatorStep

enum TSmartActivatorStep {
  Start,        // Pairing started
  Found,        // Device polled/discovered
  Registered,   // Device registered
  Initialized,  // Device activation completed
  TimeOut,      // Pairing timed out
}

TSmartActivatorError

The error code during pairing. It can be determined based on the name property of the error object.

enum TSmartActivatorError {
  // Undefined error.
  Unknown = 'UNKNOWN',
  // Parameter error.
  ParameterError = 'PARAM_ERROR',
  // Timeout.
  Timeout = 'TIMEOUT',
  // Pairing token error. Failed to obtain the token.
  TokenError = 'TOKEN_ERROR',
  // Failed to pair the Bluetooth device.
  BleActiveError = 'BLE_ACTIVE_ERROR',
  // Strong-binding device. The device is already bound.
  DeviceAlreadyBind = 'DEVICE_ALREADY_BIND',// Do not change this value. It corresponds to the cloud error code.
  // Failed to pair the combo device.
  BleWifiActiveError = 'BLE_WIFI_ACTIVE_ERROR'
}

appendDevice

Add a device for pairing. For Bluetooth and combo devices, this method must be called first to add the target device before starting the pairing process.

appendDevice(...device: Device[]): void

startActive

Start pairing.

startActive(): void

stopActive

Stop pairing.

stopActive(): void