LightingKit 1.4.0

LightingKit 1.4.0

×

由 Pete Morris 维护。

LightingKit 1.4.0

LightingKit

一个用于在 iOS 上发现和控制 HomeKit 灯的光库。

目录

简介

LightingKit 是一个简单的 iOS 库，用于通过 HomeKit 发现和使用照明配件。它专门设计用于处理灯泡配件。

使用 LightingKit，您可以：

  • 发现新的灯并添加到家庭和房间中。
  • 开启和关闭灯（包括分组灯）。
  • 设置亮度。
  • 在指定的时间内渐进式地更改亮度。
  • 即将添加对色调和饱和度的支持。

安装 LightingKit

Carthage

将在您的项目 Cartfile 中添加 LightingKit 作为依赖项

github "p-morris/LightingKit" ~> 1.0.0

使用 Carthage 更新项目依赖

carthage update

请确保在项目的构建设置中链接了 LightingKit.framework，并且在项目的构建阶段中将其复制为资源。

Cocoapods

在 Podfile 中添加 LightingKit

pod 'LightingKit'

运行命令安装 LightingKit

pod install

入门

1) 为您的项目启用 HomeKit 功能

打开项目窗口的“能力”选项卡。向下滚动到“HomeKit”，将其切换为“启用”。

2) 将 HomeKit 使用描述添加到 Info.plist 文件

打开您的项目 Info.plist 文件，并添加 Privacy - HomeKit Usage Description 键。

其值应该是 String 类型。当用户被要求授予 HomeKit 权限时，将会显示此值。

重要！ 如果您未向项目的 info.plist 文件中添加此键，则启动 LightingKit 时您的应用将崩溃。

3) 创建一个 LightingKit 对象

将 LightingKit 库导入您希望使用的文件中

import LightingKit

您的大部分与 LightingKit 的交互将通过 LightingKit 类进行。

初始化一个 LightingKit 对象

let kit = LightingKit()

4) 连接到 HomeKit

执行 LightingKit 对象的 start() 函数以连接到 HomeKit

kit.start()

重要! - 使用 start() 函数启动 LightingKit 将提示用户进行 HomeKit 权限请求（如果尚未授权）。

5) 当 LightingKit 准备就绪时获取回调

如果不对发生的事情进行检查，启动 LightingKit 就没有什么用处了！

要获取回调，设置 LightingKit 对象的 permissionsDelegate 属性

kit.permissionsDelegate = self

然后，让您的类遵守 LightingKitPermissionsDelegate 协议以便在 LightingKit 准备就绪时接收回调

extension ViewController: LightingKitPermissionsDelegate {
    func lightingKit(_ lightingKit: LightingKit, permissionsGranted: Bool) {
        if permissionsGranted {
            // Ready! Now you can control lights!
        } else {
            // Oops! The user didn't grant permission.
        }
    }
}

家居、房间和灯具

在 LightingKit 中，用户拥有家居、房间和灯具。

家居

Home 相当直观！它表示一个特定的家庭，其中包含房间和灯具。

您可以通过您的 LightingKit 对象访问用户的全家居数组

let usersHomes = kit.homes

您可以通过以下方式添加新的 Home

kit.addHome(name: "29 Neibolt Street") { (home) in
    if let newHome = home {
        // The Home was added successfully!
    }
}

房间

Room 属于 Home (住宅)。

你可以通过将一个 Home 对象作为参数传递给 LightingKit 对象的 rooms(forHome:) 方法来获取特定住宅中的房间数组。

let rooms = kit.rooms(forHome: aHome)

Home 可以包含无限数量的自定义房间。你可以像这样将一个 Room 添加到 Home

kit.addRoom(name: "Bedroom", toHome: myHome) { (room) in
    if let newRoom = room {
        // The Room was added successfully!
    }
}

默认房间

每个 Home 都包含默认的 Room。

如果用户还没有向他们的 Home 添加任何自定义房间，那么住宅将仍然包含一个房间：默认房间。

灯光

Light 属于 Room。

你可以这样获取某个房间中所有灯光的数组。

let lights = kit.lights(forRoom: aRoom)

控制灯光

开启和关闭灯光

持有特定的 Light 对象后，您可以通过其 power 属性来打开和关闭它。

light.power?.on(true, completion: { (error) in
    if error == nil {
        // Light was turned on!
    }
})

您还可以检查 Light 是否当前已启动。由于 Power 属性是可选的，因此您必须先解包它。

if let power = light.power, power.isOn {
    // The light is currently turned on!
}

设置亮度

每个Light都有一个brightness属性，可以用来获取Light的当前亮度。

亮度是一个介于0和100之间的Int（100是可能的最大亮度级别）。

let brightnessLevel = light.brightness?.value

可以像这样设置亮度级别

light.brightness?.set(brightness: 50, completion: { (error) in
    if error == nil {
        // The brightness was set!
    }
})

随时间设置亮度

您还可以在设置时间段内更新Light的亮度值。

在这种情况下，灯的亮度将从当前值逐渐变为您指定的值。

例如，要将灯的亮度在30秒内设置为100

light.brightness?.set(brightness: 100, duration: 30, brightnessDelegate: self)

要接收关于定时亮度更新状态的回调，请确保您的类符合TimedBrightnessUpdateDelegate协议

extension ViewController: TimedBrightnessUpdateDelegate {
    func brightness(_ brightness: Brightness, valueDidChange newValue: Int) {
        // The brightness was updated to a new value!
    }
    
    func brightness(_ brightness: Brightness, didCompleteTimedUpdate newValue: Int) {
        // The timed brightness update is complete!
    }
    
    func brightness(_ brightness: Brightness, timedUpdateFailed error: Error?) {
        // The timed brightness update failed
    }
}

设置新灯

如果灯尚未添加到HomeKit中，则需要先将它添加并设置，然后您才能使用LightingKit进行控制。

将Light添加到HomeKit包括两个简单的步骤：搜索新灯，然后将它们添加到房间中。

1) 搜索设置灯光的灯光

设置您的LightingKit对象的searchDelegate属性，然后开始搜索

kit.searchDelegate = self
kit.searchForNewLighting()

为了在找到与照明相关的配件时接收回调，请确保您的类符合LightingKitAccessorySearchDelegate协议

extension ViewController: LightingKitAccessorySearchDelegate {
    func lightingKit(_ lightingKit: LightingKit, foundNewLight light: Light) {
        // LightingKit found a new light!
    }
    func lightingKit(_ lightingKit: LightingKit, foundNewBridge bridge: Bridge) {
        // Don't worry, I'll explain what a bridge is later!
    }
}

2) 将新灯添加到房间

找到需要设置的Light后，只需将其添加到房间中即可开始设置过程

kit.add(newLight: light, toRoom: room) { (success) in
    if success {
        // The light was setup, and added to the room!
    }
}

重要！ - 在室内添加新的灯具将触发iOS HomeKit配件设置流程。

一旦新的 灯具 成功添加到 房间 中，您就可以像往常一样控制它了！

3) 停止搜索

当您完成对新的灯具的查找后，请记住停止搜索

kit.stopNewLightingSearch()

网桥和网桥连接的灯具

某些智能灯具需要“网桥”来连接到网络。例如 Philips Hue 照明产品就需要这样的网桥。

网桥本身 是一个需要在 HomeKit 中添加的硬件配件。

添加网桥后，连接到该网桥的所有配件将自动通过 LightingKit 使用。不需要逐一设置每个连接到网桥的灯具。

设置新的 网桥

当您使用 LightingKit 进行新的照明搜索时，当发现需要设置的新的网桥时，您的 LightingKitAccessorySearchDelegate 将收到回调

extension AppDelegate: LightingKitAccessorySearchDelegate {
    func lightingKit(_ lightingKit: LightingKit, foundNewBridge bridge: Bridge) {
        // A new bridge was found
    }
}

有了新的 网桥 对象，可以按照这种方式进行设置

kit.add(newBridge: bridge, toHome: home) { (success, lights) in
    if success {
        // The bridge was set up successfully!
    }
}

如果网桥连接了任何灯具，它们将以 Light 对象数组的格式传递。在上述示例中，lights 是可选的 Light 对象数组（如果网桥没有连接任何灯具，则设置为 nil）。

重要！ - 设置完 网桥 后，连接到它的任何灯具将自动添加到指定 家 的“默认房间”中。如果您愿意，可以将这些灯具分配到您选择的任何 房间 中。

kit.assignLights(lights: newLights, toRoom: room) { (assigned, failed) in
    if assigned.count > 0 {
        // These lights were successfully assigned to the room!
    }
    if failed.count > 0 {
        // HomeKit failed to add these lights to the room.
    }
}

照明组

使用iOS Home应用程序，用户可以创建一个组并将灯具添加到其中。这可以让他们同时控制该组中的所有灯具。

在 LightingKit 中，灯具组用 LightingGroup 类表示。

您可以通过这种方式获取特定 房间 的 LightingGroup 对象数组

kit.lightingGroups(forRoom: room) { lightingGroups in 
    if let lightingGroups = lightingGroups {
        // We have some lighting groups
    }
}

一个LightingGroup对象包含一个名称和唯一标识符。它还提供了PowerGroup和BrightnessGroup属性，用于访问组内所有灯具的电源和亮度服务。

要开启特定LightingGroup中的所有灯具，请使用其power属性

group.power.on(true) { errors in 
    if errors == nil {
        // All the lights in the group were turned on! 
    }
}

要设置组内所有灯具的亮度

group.brightness?.set(brightness: 100) { errors in 
    if errors == nil {
        // The brightness was set for all lights in the group!
    }
}

您还可以对组进行定时亮度更新的设置

group.brightness?.set(brightness: 100, duration: 10, brightnessDelegate: self)

要接收LightingGroup的定时亮度更新回调，您需要遵守TimedBrightnessGroupUpdateDelegate协议

extension ViewController: TimedBrightnessGroupUpdateDelegate {
    func brightnessGroup(_ group: BrightnessGroup, didCompleteTimedBrightnessUpdate errors: [Error]?) {
        if errors == nil {
            // The brightness was updated for all lights in the group!
        }
    }
}

问题和请求

如果您遇到任何错误，或者有希望得到支持的特殊功能，请提交一个GitHub问题，我将尽快回复您。