Group Management

A device group includes devices of the same type and gathers a series of devices. Wi-Fi and Zigbee are the most common group types. Tuya provides the capabilities to implement device group management. For example, create, rename, manage, or dismiss a group, and manage multiple devices in the same group.

Functional description

The TSmartGroup class requires the group ID specified by groupId to implement initialization. An incorrect group ID might cause failed initialization. In this case, undefined is returned.

• Encapsulation class

  Class name	Description
  TSmartGroup	The group class.
  ThingSmartGroupModel	The group data model class.

• Data model of ThingSmartGroupModel

  Field	Type	Description
  groupId	string	The unique group ID.
  productId	string	The product ID (PID) of a group.
  time	number	The time when the group was created.
  name	string	The group name.
  iconUrl	string	The URL of the group icon.
  type	TSmartGroupType	The group type.
  isShare	boolean	Indicates whether the group is a shared group.
  dps	Record<string,Object>	The data points (DPs) of devices in the group.
  dpCodes	Record<string,Object>	The DPs of the group devices, stored in the key-value pair format.
  localKey	string	The key that the group uses for communication.
  deviceNum	number	The number of devices managed in the group.
  productInfo	Record<string,Object>	The PID information of the group.
  pv	number	The protocol version of the group. A Wi-Fi protocol version is supported.
  homeId	number	The ID of the home to which the group belongs.
  roomId	number	The ID of the room to which the group belongs.
  displayOrder	number	The sequence in which the group is sorted by room.
  homeDisplayOrder	number	The sequence in which the group is sorted by home.
  deviceList	TSmartDeviceModel[]	The list of group devices.
  localId	string	The group ID used on a local area network (LAN).
  meshId	string	The mesh ID of the group.
  schemaArray	TSmartSchemaModel[]	The schema array of group DP rules.
  standard	boolean	Indicates whether a standard group is used.

Create a Wi-Fi group

Query devices available to create a group

Returns a list of devices that can be used to create a group together with a device specified by the product ID (PID) of the device.

API description

export class TSmartGroup {
	public static async getDeviceList(productId: string, ownerId: string, gwId?: string): Promise<TSmartGroupDevListModel[] | undefined>
}

Parameters

Parameter	Description
productId	The PID of the group.
gwId	(Optional) The gateway ID of the group. Do not include this parameter when querying for devices that can create groups.
homeId	The ID of the specified home.

Sample code

const list = await TSmartGroup.getDeviceList(this.deviceModel?.productId!, this.deviceModel?.ownerId!, this.deviceModel?.parentId)

Create a group

API description

export class TSmartGroup {
	public static async create(params: TSmartGroupAddParams, progress?:(p: Record<string, number>) => void)
}

TSmartGroupAddParams description

Parameter	Description
name	The group name.
homeId	The ID of the home to which the group belongs.
productVer	The product version.
productId	The PID of the device from which the target group can be accessed.
devIdList	A list of device IDs.
groupType	The type of group to create. 0: Wi-Fi group  2: Zigbee group

Sample code

const list = await TSmartGroup.getDeviceList(this.deviceModel?.productId!, this.deviceModel?.ownerId!, this.deviceModel?.parentId)
let devs: string[] = []
list?.forEach(d => {
  devs.push(d.devId!)
})

const group = await TSmartGroup.create({
  name: 'New Group',
  productId: this.deviceModel?.productId ?? "",
  productVer: this.deviceModel?.productVer ?? "1.0.0",
  homeId: Number(this.deviceModel?.ownerId),
  devIdList: devs,
  groupType: TSmartGroupType.WiFi
})

Query devices available to join a group

Returns a list of devices that can be added or that have been added to a group specified by the PID of the group.

API description

export class TSmartGroup {
	public async getDeviceList(productId: string): Promise<TSmartGroupDevListModel[] | undefined>
}

Parameters

Parameter	Description
productId	The PID of the group.

Sample code

let res = await group.getDeviceList("your_group_product_id")

Update and save a group relationship

API description

export class TSmartGroup {
	public async updateGroupRelations(devList: string[]): Promise<void>
}

Parameters

Parameter	Description
devList	The list of device IDs in the group.

Sample code

let res = await group.updateGroupRelations(devList)

Execute callback

Returns the data update result after group DPs are sent.

API description

export class TSmartGroup {
	public registerListener(listener: TSmartGroupListener)
    public unregisterListener()
}

export interface TSmartGroupListener {
  onDpsChanged: (groupId: string, dps: DpsType) => void;
}

Create a Zigbee group

A Zigbee group supports Zigbee sub-devices, Smart Gateway Pro sub-devices, Sub-G sub-devices, and other devices that can communicate over Zigbee.

Query devices available to create or join a group

API description

export class TSmartGroup {
	public static async getDeviceList(productId: string, ownerId: string, gwId?: string): Promise<TSmartGroupDevListModel[] | undefined>
}

Parameters

Parameter	Description
productId	The PID of the group.
gwId	(Optional) The gateway ID of the group. This parameter is required when querying devices that can create/join Zigbee groups.
homeId	The ID of the specified home.

Sample code

const list = await TSmartGroup.getDeviceList(this.deviceModel?.productId!, this.deviceModel?.ownerId!, this.deviceModel?.parentId)

Create a group

API description

export class TSmartGroup {
	public static async create(params: TSmartGroupAddParams, progress?:(p: Record<string, number>) => void)
}

TSmartGroupAddParams description

Parameter	Description
name	The group name.
homeId	The ID of the home to which the group belongs.
productVer	The product version.
productId	The PID of the device from which the target group can be accessed.
devIdList	A list of device IDs.
groupType	The type of group to create. 0: Wi-Fi group  2: Zigbee group

Sample code

const list = await TSmartGroup.getDeviceList(this.deviceModel?.productId!, this.deviceModel?.ownerId!, this.deviceModel?.parentId)
let devs: string[] = []
list?.forEach(d => {
  devs.push(d.devId!)
})

const group = await TSmartGroup.create({
  name: 'New Group',
  productId: this.deviceModel?.productId ?? "",
  productVer: this.deviceModel?.productVer ?? "1.0.0",
  homeId: Number(this.deviceModel?.ownerId),
  devIdList: devs,
  groupType: TSmartGroupType.Zigbee
})

Update and save a group relationship

API description

export class TSmartGroup {
	public async updateGroupRelations(devList: string[]): Promise<void>
}

Parameters

Parameter	Description
devList	The list of device IDs in the group.

Sample code

let res = await group.updateGroupRelations(devList)

Group control

Initialize a group instance

API description

export class TSmartGroup {
	public static init(groupId: string): TSmartGroup | undefined
}

Rename a group

API description

export class TSmartGroup {
	public async updateGroupName(name: string): Promise<void>
}

Dismiss a group

API description

export class TSmartGroup {
	public async dismissGroup(): Promise<void>
}

Send group control commands

API description

export class TSmartGroup {
	public async publishDps(dps: string)
}

Execute callback

API description

export class TSmartGroup {
	public registerListener(listener: TSmartGroupListener)
    public unregisterListener()
}

TSmartGroupListener

export interface TSmartGroupListener {
  onDpsChanged: (groupId: string, dps: DpsType) => void;
  onInfoUpdated: (groupId: string) => void;
  onRemoved: (groupId: string) => void;
}

Query group list

const r = group?.groupModel.deviceList