群组管理

将具备共性的设备组成一个群组，群组具备和设备类似的控制页面，使用群组命令可以控制群组中的设备。群组与场景都可以实现批量控制设备的功能，场景中各个设备的操作可以灵活多样，群组以通用共性视角批量操作设备执行相同操作。常见的有 Wi-Fi 设备群组和 Zigbee 设备群组。

涂鸦支持群组管理体系，您可以创建群组、修改群组名称、管理群组设备，通过群组管理多个设备，解散群组。

功能概述

ThingSmartGroup 类需要使用群组 ID（groupId）初始化。错误的群组 ID 会导致初始化失败，并且实例返回 nil。

• 封装类

  类名	说明
  ThingSmartGroup	群组类
  ThingSmartGroupModel	群组数据模型类

• ThingSmartGroupModel 数据模型

  字段	类型	描述
  groupId	NSString	群组唯一 ID
  productId	NSString	群组对应的产品 ID
  time	long long	群组的创建时间
  name	NSString	群组名称
  iconUrl	NSString	群组展示图标的 URL
  type	ThingSmartGroupType	群组类型
  isShare	BOOL	是否为分享群组
  dps	NSDictionary	群组中设备的功能数据
  dpCodes	NSDictionary	群组中设备的功能数据，以键值对的形式存储
  localKey	NSString	群组通信使用的 Key
  deviceNum	NSInteger	群组下的设备数量
  productInfo	NSDictionary	群组对应的产品相关信息
  pv	NSString	群组协议版本，Wi-Fi 协议版本
  homeId	long long	群组所在的家庭 ID
  roomId	long long	群组所在的房间 ID
  displayOrder	NSInteger	群组在房间维度的排序
  homeDisplayOrder	NSInteger	群组在家庭维度的排序
  deviceList	NSArray	群组的设备列表
  localId	NSString	群组在局域网通讯中的 ID
  meshId	NSString	群组的 Mesh ID
  schemaArray	NSArray	群组 DP 规则信息
  standard	BOOL	是否是标准群组

群组管理

获取群组类型

接口说明

获取群组的类型。

@interface ThingGroupMakerHelper : NSObject

/// Return ThingGroupBizType based on device ID
+ (ThingGroupBizType)groupBizTypeFromDeviceId:(NSString *)devId;

/// Return ThingGroupBizType based on group ID
+ (ThingGroupBizType)groupBizTypeFromGroupId:(NSString *)groupId;

@end

参数说明

属性	类型	说明
devId	NSString	设备 ID，根据设备 ID 获取群组的类型。
groupId	NSString	群组 ID，根据群组 ID 获取群组的类型。

返回数据说明

属性	说明
ThingGroupBizType	ThingGroupBizTypeWi-Fi：Wi-Fi 群组 ThingGroupBizTypeStandardWi-Fi：标准 Wi-Fi 群组 ThingGroupBizTypeZigbee：Zigbee 群组 ThingGroupBizTypeStandardSIGMesh：标准蓝牙 mesh 群组 ThingGroupBizTypeBeacon：Beacon 群组 ThingGroupBizTypeStandardZigbee：标准 Zigbee 群组 ThingGroupBizTypeThread：Thread 群组

调用示例

let groupType = ThingGroupMakerHelper.groupBizType(fromDeviceId: device.devId)

获取群组服务

接口说明

获取指定的群组服务。

@interface ThingGroupServiceMaker : NSObject
+ (id<ThingGroupServiceProtocol>)groupServiceMakerWithBuildQuery:(NSDictionary *)params;
@end

参数说明

属性	类型	说明
params	NSDictionary	devId：设备 ID，通过设备获取群组服务时需要传。 groupId: 群组 ID，通过群组获取群组服务时需要传。 deviceList：设备列表，当群组类型是蓝牙 mesh 或者 beacon 时需要传该字段。具体字段内容请参考 ThingSmartDeviceModel。

返回数据说明

数据	说明
id<ThingGroupServiceProtocol>	一个群组服务对象。

调用示例

let groupType = ThingGroupMakerHelper.groupBizType(fromDeviceId: device.devId)

var params: [AnyHashable: AnyObject] = [:]
params["devId"] = device.devId! as AnyObject

if (groupType == .bleMesh || groupType == .sigMesh || groupType == .beacon) {
    let impl = ThingSmartBizCore.sharedInstance().service(of: ThingBusinessGroupProtocol.self) as? ThingBusinessGroupProtocol
    let deviceList = impl?.deviceListForCurrentSpace() ?? []
    params["deviceList"] = deviceList as AnyObject
}

self.service = ThingGroupServiceMaker.groupServiceMaker(withBuildQuery: params)

获取设备列表

接口说明

获取符合群组类型的设备。

- (void)fetchDeviceListWithSuccess:(ThingGroupDevListResult)result failure:(void(^)(NSError *error))failure;

参数说明

属性	类型	说明
result	-	成功回调，请参考 ThingSmartGroupDevListModel。
failure	-	失败回调。

ThingSmartGroupDevListModel 说明

数据	类型	说明
devId	NSString	设备 ID。
gwId	NSString	网关 ID。
online	BOOL	设备是否在线。
iconUrl	NSString	设备图片链接。
productId	NSString	设备产品 ID。
checked	BOOL	设备是否选中。
name	NSString	设备名称。
nodeId	NSString	设备节点 ID。

调用示例

let groupType = ThingGroupMakerHelper.groupBizType(fromDeviceId: device.devId)

var params: [AnyHashable: AnyObject] = [:]
params["devId"] = device.devId! as AnyObject

if (groupType == .bleMesh || groupType == .sigMesh || groupType == .beacon) {
    let impl = ThingSmartBizCore.sharedInstance().service(of: ThingBusinessGroupProtocol.self) as? ThingBusinessGroupProtocol
    let deviceList = impl?.deviceListForCurrentSpace() ?? []
    params["deviceList"] = deviceList as AnyObject
}

self.service = ThingGroupServiceMaker.groupServiceMaker(withBuildQuery: params)

self.service?.fetchDeviceList?(success: { list in

}, failure: { e in

})

创建群组

接口说明

创建群组。

- (void)createGroupWithName:(NSString *)name
                 deviceList:(NSArray <NSString *> *)deviceList
                    process:(ThingGroupProcess)process
                    success:(ThingGroupSuccess)result
                    failure:(ThingGroupResultFailure)failure;

参数说明

属性	类型	说明
name	NSString	成功回调，请参考 ThingSmartGroupDevListModel。
deviceList	NSArray <NSString *>	设备 ID 列表，需要添加到群组中的设备的 ID。
process	NSDictionary<NSString *,NSNumber *>	进度。
result	-	成功回调，群组 ID。
failure	-	失败回调，每个失败设备的设备 ID 对映一个错误码。

调用示例

SVProgressHUD.show()

self.service?.fetchDeviceList?(success: { list in
    guard let listIds = list?.compactMap({ return $0.devId }) else {
        SVProgressHUD.dismiss()
        return
    }

    self.service?.createGroup?(withName: "My group Name", deviceList: listIds, process: { process in

    }, success: { groupId in
        SVProgressHUD.dismiss()
        return
    }, failure: { e in
        SVProgressHUD.dismiss()
        return
    })

}, failure: { e in
    SVProgressHUD.dismiss()
    return
})

编辑群组

接口说明

编辑群组。

- (void)updateGroupWithDeviceList:(NSArray <NSString *> *)deviceList
                             process:(ThingGroupProcess)process
                             success:(ThingGroupSuccess)result
                          failure:(ThingGroupResultFailure)failure;

参数说明

属性	类型	说明
deviceList	NSArray <NSString *>	设备 ID 列表，需要添加到群组中的设备的 ID。
process	NSDictionary<NSString *,NSNumber *>	进度。
result	-	成功回调，群组 ID。
failure	-	失败回调，每个失败设备的设备 ID 对映一个错误码。

调用示例

func editGroup(with group: ThingSmartGroupModel) {
    let groupType = ThingGroupMakerHelper.groupBizType(fromDeviceId: group.groupId)

    var params: [AnyHashable: AnyObject] = [:]
    params["groupId"] = group.groupId! as AnyObject

    if (groupType == .bleMesh || groupType == .sigMesh || groupType == .beacon) {
        let impl = ThingSmartBizCore.sharedInstance().service(of: ThingBusinessGroupProtocol.self) as? ThingBusinessGroupProtocol
        let deviceList = impl?.deviceListForCurrentSpace() ?? []
        params["deviceList"] = deviceList as AnyObject
    }

    self.service = ThingGroupServiceMaker.groupServiceMaker(withBuildQuery: params)

    SVProgressHUD.show()
    self.service?.fetchDeviceList?(success: { list in

        guard let listIds = list?.compactMap({ return $0.devId }) else {
            SVProgressHUD.dismiss()
            return
        }

        self.service?.updateGroup?(withDeviceList: listIds, process: { process in

        }, success: { groupId in
            SVProgressHUD.dismiss()
            return
        }, failure: { e in
            SVProgressHUD.dismiss()
            return
        })

    }, failure: { e in
        SVProgressHUD.dismiss()
        return
    })
}

删除群组

接口说明

删除群组。

- (void)removeGroupWithGroupId:(NSString *)groupId
                       success:(void (^)(void))success
                       failure:(void (^)(NSError *error))failure;

参数说明

属性	类型	说明
groupId	NSString	要删除的群组 ID。
success	-	成功回调。
failure	-	失败回调。

调用示例

func deleteGroup(with group: ThingSmartGroupModel) {
    let groupType = ThingGroupMakerHelper.groupBizType(fromDeviceId: group.groupId)
    var params: [AnyHashable: AnyObject] = [:]
    params["groupId"] = group.groupId! as AnyObject

    if (groupType == .bleMesh || groupType == .sigMesh || groupType == .beacon) {
        let impl = ThingSmartBizCore.sharedInstance().service(of: ThingBusinessGroupProtocol.self) as? ThingBusinessGroupProtocol
        let deviceList = impl?.deviceListForCurrentSpace() ?? []
        params["deviceList"] = deviceList as AnyObject
    }

    self.service = ThingGroupServiceMaker.groupServiceMaker(withBuildQuery: params)

    SVProgressHUD.show()
    self.service?.removeGroup?(withGroupId: group.groupId, success: {
        SVProgressHUD.dismiss()
        self.tableView.reloadData()
        return
    }, failure: { e in
        SVProgressHUD.dismiss()
        return
    })
}

更多功能

请参考 群组管理。

完整示例

import UIKit
import ThingSmartBizCore
import ThingModuleServices
import SVProgressHUD
import ThingSmartDeviceKit
import ThingDeviceDetailKit
import ThingGroupManagerKit
import ThingGroupHandleSktAPI

class DeviceDetailKitVC: DeviceListBaseVC {

    override func handle(index: Int) {
        let alert = UIAlertController(title: nil, message: nil, preferredStyle: .actionSheet)

        if (self.isGroup) {
            if (index >= home.groupList.count) {return}
            let group = self.home.groupList[index]

            alert.addAction(UIAlertAction(title: "Timer", style: .default, handler: { action in
                let vc = DeviceDetailKitTimerVC(bizId: group.groupId, isGroup: true)
                self.navigationController?.pushViewController(vc, animated: true)
            }))

            alert.addAction(UIAlertAction(title: "Edit Group", style: .default, handler: { action in
                self.editGroup(with: group)
            }))

            alert.addAction(UIAlertAction(title: "Delete Group", style: .default, handler: { action in
                self.deleteGroup(with: group)
            }))
        }else{
            if (index >= home.deviceList.count) {return}
            let device = self.home.deviceList[index]

            alert.addAction(UIAlertAction(title: "Device Info", style: .default, handler: { action in
                let vc = DeviceDetailKitInfoVC(deviceId: device.devId)
                self.navigationController?.pushViewController(vc, animated: true)
            }))

            alert.addAction(UIAlertAction(title: "Timer", style: .default, handler: { action in
                let vc = DeviceDetailKitTimerVC(bizId: device.devId, isGroup: false)
                self.navigationController?.pushViewController(vc, animated: true)
            }))

            alert.addAction(UIAlertAction(title: "Create Group", style: .default, handler: { action in
                self.createGroup(with: device)
            }))

        }

        alert.addAction(UIAlertAction(title: "Cancel", style: .cancel))
        self.present(alert, animated: true)
    }

    var service: ThingGroupServiceProtocol?
    func createGroup(with device: ThingSmartDeviceModel) {
        let groupType = ThingGroupMakerHelper.groupBizType(fromDeviceId: device.devId)

        var params: [AnyHashable: AnyObject] = [:]
        params["devId"] = device.devId! as AnyObject

        if (groupType == .bleMesh || groupType == .sigMesh || groupType == .beacon) {
            let impl = ThingSmartBizCore.sharedInstance().service(of: ThingBusinessGroupProtocol.self) as? ThingBusinessGroupProtocol
            let deviceList = impl?.deviceListForCurrentSpace() ?? []
            params["deviceList"] = deviceList as AnyObject
        }

        self.service = ThingGroupServiceMaker.groupServiceMaker(withBuildQuery: params)

        SVProgressHUD.show()
        self.service?.fetchDeviceList?(success: { list in

            guard let listIds = list?.compactMap({ return $0.devId }) else {
                SVProgressHUD.dismiss()
                return
            }

            self.service?.createGroup?(withName: "My group Name", deviceList: listIds, process: { process in

            }, success: { groupId in
                SVProgressHUD.dismiss()
                return
            }, failure: { e in
                SVProgressHUD.dismiss()
                return
            })

        }, failure: { e in
            SVProgressHUD.dismiss()
            return
        })
    }

    func editGroup(with group: ThingSmartGroupModel) {
        let groupType = ThingGroupMakerHelper.groupBizType(fromDeviceId: group.groupId)

        var params: [AnyHashable: AnyObject] = [:]
        params["groupId"] = group.groupId! as AnyObject

        if (groupType == .bleMesh || groupType == .sigMesh || groupType == .beacon) {
            let impl = ThingSmartBizCore.sharedInstance().service(of: ThingBusinessGroupProtocol.self) as? ThingBusinessGroupProtocol
            let deviceList = impl?.deviceListForCurrentSpace() ?? []
            params["deviceList"] = deviceList as AnyObject
        }

        self.service = ThingGroupServiceMaker.groupServiceMaker(withBuildQuery: params)

        SVProgressHUD.show()
        self.service?.fetchDeviceList?(success: { list in

            guard let listIds = list?.compactMap({ return $0.devId }) else {
                SVProgressHUD.dismiss()
                return
            }

            self.service?.updateGroup?(withDeviceList: listIds, process: { process in

            }, success: { groupId in
                SVProgressHUD.dismiss()
                return
            }, failure: { e in
                SVProgressHUD.dismiss()
                return
            })

        }, failure: { e in
            SVProgressHUD.dismiss()
            return
        })
    }

    func deleteGroup(with group: ThingSmartGroupModel) {
        let groupType = ThingGroupMakerHelper.groupBizType(fromDeviceId: group.groupId)

        var params: [AnyHashable: AnyObject] = [:]
        params["groupId"] = group.groupId! as AnyObject

        if (groupType == .bleMesh || groupType == .sigMesh || groupType == .beacon) {
            let impl = ThingSmartBizCore.sharedInstance().service(of: ThingBusinessGroupProtocol.self) as? ThingBusinessGroupProtocol
            let deviceList = impl?.deviceListForCurrentSpace() ?? []
            params["deviceList"] = deviceList as AnyObject
        }

        self.service = ThingGroupServiceMaker.groupServiceMaker(withBuildQuery: params)

        SVProgressHUD.show()
        self.service?.removeGroup?(withGroupId: group.groupId, success: {
            SVProgressHUD.dismiss()
            self.tableView.reloadData()
            return
        }, failure: { e in
            SVProgressHUD.dismiss()
            return
        })
    }

}