NovaSDK 2.0.1

您想在Podfile中添加类似以下的内容：

target 'MyApp' do
  pod 'NovaSDK', '~> 2.0'
end

然后在终端内部运行pod install，或者从CocoaPods.app中运行。

或者为了测试它，运行以下命令

pod try NovaSDK

NovaSDK 2.0.1

由
Joe Walnes
joewalnes

Nova iOS SDK

官方iOS SDK，用于Nova蓝牙iPhone闪光灯。

这是SDK的第二个版本，与第一个版本相比有重大变更。如果您在进行迁移，请参阅V2迁移指南。

这是什么做的？

使用蓝牙LE发现附近的Nova闪光灯并与它们通信
允许控制多个闪光灯（每个闪光灯都可以唯一识别）
监控每个闪光灯的信号强度（例如，哪个离手机最近）
支持自动和手动连接模式
手动连接：客户端可以探索范围内的Nova闪光灯，信号强度，并根据需要显式连接和断开连接
自动连接：SDK将自动连接到最近的闪光灯（单个或多台闪光灯）或先前记住的闪光灯
提供无缝连接的用户体验 - 用户无需在蓝牙设置中显式配对闪光灯
允许连接的闪光灯根据用户定义的亮度和色温进行开关灯操作

它能做什么？

只是一些想法...

与自定义相机应用程序集成，以提供
创建手电筒应用程序
摩尔斯电码信标
使用Nova设备作为位置感知应用程序的信标
一些美丽的艺术作品

示例

提供了一个简单的“你好，世界”应用程序，该应用程序简单地连接到最近的闪光灯，并且每秒切换灯的开关状态。

安装

使用Cocoapods并将它添加到您的Podfile中

pod 'NovaSDK', '~> 2.0.0'

库很小，它的唯一依赖项是系统的CoreBluetooth框架。

核心类型

NVFlashService：用于发现附近闪光灯的核心服务。客户端可以遍历可用的附近闪光灯，设置自动连接的规则，在应用程序移动到后台时暂停/恢复扫描。
NVFlashServiceDelegate：可选的委托协议，客户端可以实现以在发现新的闪光灯、连接或断开连接时接收回调。
NVFlash：每个发现的闪光灯。客户端可以显式连接/断开连接，监控信号强度和连接状态，并控制来自每个闪光灯发出的光。
NVFlashSettings: 当告诉闪光灯点亮时使用的配置。包括暖色LED亮度、冷色LED亮度和自动关闭闪光的超时设置。
NVFlashStatus: 枚举类型，描述闪光灯的状态。
- Available: 在范围内，可以连接使用。
- Unavailable: 不再在范围内。
- Connecting: 连接进行中。
- Ready: 已连接，准备使用。
- Busy: 已连接，但当前正在处理一个现有命令。

使用方法

初始化

初始化Nova闪光灯服务。在 applicationDidFinishLaunching: 中进行初始化是一个不错的选择。

// Objective-C

// Setup. Do this when app starts.
// A good time is applicationDidFinishLaunching:
NVFlashService *flashService = [NVFlashService new];

// Optionally, set a delegate implementing NVFlashServiceDelegate to be
// notified of flash discovery/connection events.
flashService.delegate = self;

// Swift

// Setup. Do this when app starts.
// A good time is applicationDidFinishLaunching:
let flashService = NVFlashService()

// Optionally, set a delegate implementing NVFlashServiceDelegate to be
// notified of flash discovery/connection events.
flashService.delegate = self

在 applicationDidBecomeActive: 中应启用服务，这将激活蓝牙接收器，并开始扫描。

// Objective-C
[flashService enable];

// Swift
flashService.enable()

在 applicationWillResignActive: 中应禁用服务，这将关闭蓝牙LE扫描，以节省iPhone和Nova的电池寿命。

// Objective-C
[flashService disable];

// Swift
flashService.disable()

发现附近的闪光灯

当闪光灯服务启用时，它将自动执行蓝牙扫描以发现附近的闪光灯。

有两种方式可以知道哪些闪光灯在范围内：1. 定期检查 flashService.flashes 或 flashService.connectedFlashes 数组的元素。2. 通过实现 NVFlashServiceDelegate 协议来接收回调。

遍历闪光灯数组

NVFlashService.flashes 数组包含 NVFlash 对象，可以在任何时候查询，返回所有已发现的闪光灯。

NVFlashService.connectedFlashes 类似，但它只包含当前已连接的闪光灯子集。

// Objective-C
for (id<NVFlash> flash in flashService.flashes) { // alternatively flashService.connectedFlashes
  NSLog(@"flash: identifier=%@, status=%@, signalStrength=%f",
        flash.identifier,                  // unique ID assigned to each flash
        NVFlashStatusString(flash.status), // connectivity status
        flash.signalStrength);             // value from 0.0 (weakest) to 1.0 (strongest)
}

// Swift
for flash in flashService.flashes as [NVFlash] { // alternatively flashService.connectedFlashes
  NSLog("flash: identifier=%@, status=%@, signalStrength=%f",
        flash.identifier,                  // unique ID assigned to each flash
        NVFlashStatusString(flash.status), // connectivity status
        flash.signalStrength)              // value from 0.0 (weakest) to 1.0 (strongest)
}

接收代理回调

客户端可以选择实现 NVFlashServiceDelegate 协议，并将其设置为 flashService.delegate，以便在发现和连接事件发生时接收回调。

// Objective-C

// Implement NVFlashServiceDelegate protocol. All methods are optional.

- (void) flashServiceAddedFlash:(id<NVFlash>)flash {
  NSLog(@"added flash %@", flash.identifier);
}

- (void) flashServiceRemovedFlash:(id<NVFlash>)flash {
  NSLog(@"removed flash %@", flash.identifier);
}

- (void) flashServiceConnectedFlash:(id<NVFlash>)flash {
  NSLog(@"connected flash %@", flash.identifier);
}

- (void) flashServiceDisconnectedFlash:(id<NVFlash>)flash {
  NSLog(@"disconnected flash %@", flash.identifier);
}

// Swift

// Implement NVFlashServiceDelegate protocol. All methods are optional.

func flashServiceAddedFlash(flash: NVFlash) {
  NSLog("added flash %@", flash.identifier)
}

func flashServiceRemovedFlash(flash: NVFlash) {
  NSLog("removed flash %@", flash.identifier)
}

func flashServiceConnectedFlash(flash: NVFlash) {
  NSLog("connected flash %@", flash.identifier)
}

func flashServiceDisconnectedFlash(flash: NVFlash) {
  NSLog("disconnected flash %@", flash.identifier)
}

连接到闪光灯

有两种方法可以连接到闪光灯：1. 手动调用感兴趣 NVFlash 实例的 connect/disconnect。这提供了最多的控制。2. 启用 autoConnect 并允许闪光灯服务自动连接到最近的Nova。这是最简单的方法。

自动连接

这是一个推荐的方法，因为它让闪光灯服务为你做大部分工作。

当启用 autoConnect 时，闪光灯服务将定期尝试连接到合适的Nova（或多个Nova）。客户端可以通过查看 flashService.connectedFlashes 数组或处理 flashServiceConnectedFlash:/flashServiceDisconnectedFlash: 回调来了解Nova已连接。

自动连接到最近的Nova

// Objective-C

// call this after initializing NVFlashService
flashService.autoConnect = YES;

// Swift

// call this after initializing NVFlashService
flashService.autoConnect = true

默认的自动连接规则将尝试

每次只连接到 1 个Nova
信号强度最强的Nova
从所有信号强度 >0.1（10%）的已发现Nova集合中

自动连接到多个Nova

上述规则可以被更改。例如

// Objective-C

flashService.autoConnectMaxFlashes = 4;          // connect to the 4 closest Novas
flashService.autoConnectMinSignalStrength = 0.5; // require signal strength >=50%

// Swift

flashService.autoConnectMaxFlashes = 4           // connect to the 4 closest Novas
flashService.autoConnectMinSignalStrength = 0.5  // require signal strength >=50%

记住一个Nova，并且只自动连接到该Nova

在某些情况下，客户端可能希望记住一个闪光灯，并只在未来重新连接到相同的闪光灯（或闪光灯组）。

为此，客户端应存储一个包含NVFlash.identifier值的列表。这些字符串可以本地持久化。每个字符串对于每个闪存都是唯一的。

在重新连接后

// Objective-C

// Only auto connect to specific flashes.
// Identifiers are strings previously obtained from NVFlash.identifier
flashService.autoConnectWhiteList = @[identifier1, identifier2];

// Swift

// Only auto connect to specific flashes.
// Identifiers are strings previously obtained from NVFlash.identifier
flashService.autoConnectWhiteList = [identifier1, identifier2]

手动连接

对于希望对要连接的Novas有更多控制的客户端，可以在适当的时候迭代单个NVFlash实例（见上）并显式连接/断开连接。

重要：如果启用了autoConnect，不要尝试手动连接到闪存。如有疑问，请使用autoConnect代替（见上）——这要简单得多。

// Objective-C

id<NVFlash> flash = /* whichever flash instance */;

// to connect
[flash connect];

// to disconnect
[flash disconnect];

// Objective-C

let flash: NVFlash = /* whichever flash instance */

// to connect
flash.connect()

// to disconnect
flash.disconnect()

点亮Nova

Nova包含LED灯组，其中一半具有暖白色调，另一半具有冷白色调。可以单独控制两个灯组的亮度，以产生不同的亮度和色温。

选择亮度和色温

持有所需亮度/温度设置的NVFlashSettings对象。字段如下

warm：暖色LED的亮度，从0（关闭）到255（全亮度）
cool：冷色LED的亮度，从0（关闭）到255（全亮度）

为了方便，常用设置使用了预置

// Objective-C

NSFlashSettings *settings = [NFFlashSettings bright];

// or...
NSFlashSettings *settings = [NFFlashSettings gentle];
NSFlashSettings *settings = [NFFlashSettings neutral];
NSFlashSettings *settings = [NFFlashSettings warm];
NSFlashSettings *settings = [NFFlashSettings customWarm:123, cool:201];

// Swift

let settings = NFFlashSettings.bright()

// or...
let settings = NFFlashSettings.gentle()
let settings = NFFlashSettings.neutral()
let settings = NFFlashSettings.warm()
let settings = NFFlashSettings.custom()
let settings = NFFlashSettings.customWarm(123, cool: 201)

开启灯光

一旦定义了设置（见上），使用beginFlash向闪存发送消息以激活LED。

重要：由于蓝牙LE的特性，从调用此函数到LED真正点亮之间会有轻微的延迟。如果时间很重要，可以传递一个回调，当闪存确认LED已经打开时调用。

// Objective-C

id<NVFlash> flash = /* whichever flash you want to control */;

// Fire and forget. Flash typically lights up within 100-200 milliseconds.
[flash beginFlash:settings];

// Alternatively, fire and pass a callback to know when flash has responded
[flash beginFlash:settings withCallback:^(BOOL success) {
  if (success) {
    NSLog(@"Flash is now lit up");
  } else {
    NSLog(@"Flash failed to light. Try charging it.");
  }
}];

// Swift

let flash: NVFlash = // whichever flash you want to control

// Fire and forget. Flash typically lights up within 100-200 milliseconds.
flash.beginFlash(settings)

// Alternatively, fire and pass a callback to know when flash has responded
flash.beginFlash(settings) {success in
  if (success) {
    NSLog("Flash is now lit up")
  } else {
    NSLog("Flash failed to light. Try charging it.")
  }
}

关闭灯光

要关闭灯光，调用endFlash。

// Objective-C

[flash.endFlash];

// Swift

flash.endFlash()

和beginFlash一样，你也可以向endFlash传递一个回调，以便在闪存确认其现在已关闭时受到通知。

闪存超时

Nova硬件包括一个超时功能，可在一定时间后自动关闭闪存。这是一个安全机制，以确保如果应用崩溃或手机上发生其他意外事件，闪存不会保持开启状态并耗尽所有电量。

默认超时时间为10秒。这大致是正确的，因为Nova不包含高分辨率计时器。实际上，它将有大约20%的容差。

要更改超时，您可以修改NVFlashSettings。

// Objective-C

NVFlashSettings *settings = [[NVFlashSettings warm] flashSettingsWithTimeout:20000)]; // in milliseconds

// Swift

let settings = NVFlashSettings.warm().flashSettingsWithTimeout(20000) // in milliseconds

将所有内容组合起来

这是hello world应用程序。它演示了初始化服务、自动连接到最近的Nova、监听连接/断开事件以及控制灯光。

协调相机闪光灯

如果您将Nova集成到相机应用中，以下是拍照的基本事件流。

在尝试触发闪光灯时，应该只有当flashService.status == NVFlashServiceReady时。

// Objective-C

// Step 1: Tell flash to activate.
[flash beginFlash:settings withCallback:^ (BOOL success) {

  // Step 2: This callback is called when the flash has acknowledged that
  //         it is lit.

  // Check whether flash activated succesfully.
  if (success) {

    // Step 3: Tell camera to take photo.
    [myCameraAbstraction takePhotoWithCallback:(^ {

      // Step 4: When photo has been captured, turn the flash off.
      [flashService:endFlashWithCallback:(^ {
        // Step 5: Done. Ready to take another photo.
      })];

    })];

  } else {
    // Error: flash could not be triggered.
  }
}];

// Swift

// Step 1: Tell flash to activate.
flash.beginFlash(settings) { success in

  // Step 2: This callback is called when the flash has acknowledged that
  //         it is lit.

  // Check whether flash activated succesfully.
  if (success) {

    // Step 3: Tell camera to take photo.
    myCameraAbstraction.takePhotoWithCallback() {

      // Step 4: When photo has been captured, turn the flash off.
      flashService.endFlash() { success in
        // Step 5: Done. Ready to take another photo.
      }

    }

  } else {
    // Error: flash could not be triggered.
  }
}

提示和技巧。色调和色调调整。

观察闪存属性更改

标准键值观察(key-value observing)可用于对实例字段（例如status、signalStrength、lit）进行观察，以监测闪光灯状态的变化。建议在flashServiceFlashAdded:/flashServiceFlashRemoved:或flashServiceConnectedFlash:/flashServiceDisconnectedFlash:委托回调中添加/移除观察者。

线程

此库应由主线程调用。所有调用都是快速的并且不会阻塞。

短光闪烁

对于短暂的光闪烁，通常使用对的短暂超时而不是显式调用endFlash更为简单。

需要帮助？

Nova硬件和软件由Joe Walnes创建。如需帮助，请发送电子邮件至[a contact email protected]或提出GitHub问题。

链接

www.novaphotos.com
AppStore上的Nova Camera应用程序（使用此SDK）
购买地点（包括苹果店、亚马逊、Photojojo...）
@joewalnes在GitHub、[Twitter](https://twitter.com/joewalnes)、Medium
更多Nova开源仓库（包括应用程序、Android SDK和协议文档）

照片来自Photojojo