XyBleSdk 3.1.6

XyBleSdk 3.1.6

×

由 XYO Foundation、Carter Harrison、Deploy 维护。

XyBleSdk 3.1.6

logo

BCH compliance Carthage compatible

sdk-ble-ios

目录

描述

一个适合于使用 XY Finder 设备，但也可用于与其他蓝牙设备进行通信的蓝牙库。如果设备发出 iBeacon 信号，库将具备监控能力。该库设计用于减轻与 Core Bluetooth 类的基于代理的交互，并提供直观的 API，使开发者能够以同步方式编写异步代码。该库依赖 Google Promises 库。

要求

  • iOS 11.0+
  • MacOS 10.13+
  • Xcode 10.1+
  • Swift 4.2+

安装

Swift包管理器

    .package(url: "https://github.com/XYOracleNetwork/sdk-ble-swift.git", from: "3.1.6")

CocoaPods

注意，目前CocoaPods只支持iOS。

CocoaPods 是用于Cocoa项目的依赖管理器。您可以使用以下命令安装它：

$ gem install cocoapods

需要CocoaPods 1.6.0.beta.2+。

要使用CocoaPods将集成到您的Xcode项目中，请在您的 Podfile 中指定它。

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '11.0'
use_frameworks!

target '<Your Target Name>' do
    pod 'XyBleSdk', '~> 3.0.7'
end

然后，运行以下命令：

$ pod install

Carthage

Carthage 是一个去中心化的依赖管理器，它构建您的依赖并提供二进制框架。

您可以使用 Homebrew 使用以下命令安装Carthage：

$ brew update
$ brew install carthage

要使用Carthage将集成到您的Xcode项目中，请在您的 Cartfile 中指定它。

github "XYOracleNetwork/sdk-ble-swift" ~> 3.0.7

运行 carthage update --use-submodules 来构建框架，并将构建的 XyBleSdk.framework、FBLPromises.framework 和 Promises.framework 拖到您的Xcode项目的 Linked Frameworks and Libraries 中。然后切换到 Build Phases 选项卡，添加一个 New run script phase。展开 Run Script 并将以下内容添加到 Shell 文本框中：

/usr/local/bin/carthage copy-frameworks

在 Input Files 下点击“+”按钮并添加以下内容：

$(SRCROOT)/Carthage/Build/<target platform>/Promises.framework
$(SRCROOT)/Carthage/Build/<target platform>/FBLPromises.framework
$(SRCROOT)/Carthage/Build/<target platform>/XyBleSdk.framework

最后，您需要添加一个 New Copy Files Phase，选择 Frameworks 作为 Destination，并添加这三个框架，确保已选中 Code Sign On Copy 复选框。

SDK概述

使用Core Bluetooth与蓝牙设备通信很困难。开发者需要监控来自 CBCentral 和 CBPeripheral 的代理方法，没有处理多个连接的清晰路径。Core Bluetooth的教程代码通常是一系列特定的方法调用，这些调用位于这些代理内部，当尝试以更可重用模式的代码应用时可能会导致挫败感。由于固件和环境条件，蓝牙设备的响应时间往往不可预测，这使得它们很难处理，特别是如果应用程序需要多个不同设备连接才能正常工作。

代码示例

XyBleSdk提供了与XY Finder或其他蓝牙设备通信的简单接口。让我们看看一个XY Finder设备的示例。

let device = XYBluetoothDeviceFactory.build(from: "xy:ibeacon:a44eacf4-0104-0000-0000-5f784c9977b5.20.28772")
var batteryLevel: Int?
device.connection {
    batteryLevel = device.get(BatteryService.level, timeout: .seconds(10)).asInteger
    if let level = batteryLevel, level > 15 {
        self.batteryStatus = "Battery at \(level)"
    } else {
        self.batteryStatus = "Battery level low"
    }
}

XYBluetoothDeviceFactory可以从字符串、外围设备等构建一个设备。使用connection管理CBCentral和关联的CBPeripheral代理，确保在尝试在块中执行GATT操作之前有一个连接。

“获取”(get)、“设置”(set)和"通知"(notify)方法在指定设备上操作并阻塞，直到返回结果。这允许开发者在不等待回调或代理方法被调用的情况下编写同步代码，或者直接处理底层的承诺。如果需要，每个操作还可以取一个超时时间；默认为30秒。

一旦所有操作都完成，如果需要执行后续操作，您可以使用“then”(因此)。

let device = XYBluetoothDeviceFactory.build(from: "xy:ibeacon:a44eacf4-0104-0000-0000-5f784c9977b5.20.28772")
var batteryLevel: Int = 0
device.connection {
    batteryLevel = device.get(BatteryService.level, timeout: .seconds(10)).asInteger
    if let level = batteryLevel, level > 15 {
        self.batteryStatus = "Battery at \(level)"
    } else {
        self.batteryStatus = "Battery level low"
    }
}.then {
    self.showBatteryNotification(for: batteryLevel)
}

您可以使用结果中的“hasError”检查操作是否有错误。错误类型为《XYFinderBluetoothError》。

let device = XYBluetoothDeviceFactory.build(from: "xy:ibeacon:a44eacf4-0104-0000-0000-5f784c9977b5.20.28772")
var batteryLevel: Int = 0
device.connection {
    batteryLevel = device.get(BatteryService.level, timeout: .seconds(10)).asInteger
    guard batteryLevel.hasError == false else { return }
    if let level = batteryLevel, level > 15 {
        self.batteryStatus = "Battery at \(level)"
    } else {
        self.batteryStatus = "Battery level low"
    }
}.then {
    self.showBatteryNotification(for: batteryLevel)
}

如果您想无论结果如何都始终执行特定操作，可以使用“always”(总是)。

let device = XYBluetoothDeviceFactory.build(from: "xy:ibeacon:a44eacf4-0104-0000-0000-5f784c9977b5.20.28772")
var batteryLevel: Int = 0
device.connection {
    batteryLevel = device.get(BatteryService.level, timeout: .seconds(10)).asInteger
    guard batteryLevel.hasError == false else { return }
    if let level = batteryLevel, level > 15 {
        self.batteryStatus = "Battery at \(level)"
    } else {
        self.batteryStatus = "Battery level low"
    }
}.then {
    self.showBatteryNotification(for: batteryLevel)
}.always {
    self.updateView()
}

服务

该库提供了与蓝牙设备的三种类型通信，分别为get、set和notify。这些操作基于GATT服务的特征，该特征通过XYServiceCharacteristicType协议定义。通过创建一个实现该协议的枚举来添加新服务。

public enum MyService: String, XYServiceCharacteristic {

    public var serviceUuid: CBUUID { return MyService.serviceUuid }

    case level

    public var characteristicUuid: CBUUID {
        return BatterySeMyServicervice.uuids[self]!
    }

    public var characteristicType: XYServiceCharacteristicType {
        return .integer
    }

    public var displayName: String {
        return "My Level"
    }

    private static let serviceUuid = CBUUID(string: "0000180F-0000-1000-8000-00805F9B34FB")

    private static let uuids: [MyService: CBUUID] = [
        .level: CBUUID(string: "00002a19-0000-1000-8000-00805f9b34fb")
    ]

    public static var values: [XYServiceCharacteristic] = [
        level
    ]
}

操作结果

XYBluetoothResult类包含从“获取”(get)调用接收的数据，并允许将数据传递给“获取”(get)服务调用。XYBluetoothResult允许访问原始数据，以及方便的方法asInteger、asString和asByteArray。错误信息作为error中的《XYFinderBluetoothError》可用。

设备事件通知

当连接的设备状态改变或执行操作（如按下XY4+上的按钮）时，通过XYFinderDeviceEventManager发送XYFinderEvent通知。您可以像下面这样订阅这些事件

self.subscriptionUuid = XYFinderDeviceEventManager.subscribe(to: [.buttonPressed]) { event in
    switch event {
    case .buttonPressed(let device, _):
        guard let currentDevice = self.selectedDevice, currentDevice == device else { return }
        self.buttonPressed(on: device)
    default:
        break
    }
}

subscribe调用的结果是您可以使用它来取消订阅的订阅UUID

XYFinderDeviceEventManager.unsubscribe(to: [.buttonPressed], referenceKey: self.subscriptionUuid)

智能扫描

XYSmartScan单例可用于扫描和监测XY Finder设备。当在iOS应用中使用库时，使用switchToForeground将其置于前台模式，将扫描特定XY Finder设备家族的设备，并将switchToBackground置于后台模式时，使用低功耗监测。macOS库将使用CBCentralManager.scanForPeripherals方法定位设备。

示例项目

该库包含两个示例项目，一个用于macOS，一个用于iOS。macOS示例需要在项目目录中运行carthage update。iOS示例需要运行pod install或carthage update。

维护者

  • Arie Trouw
  • Carter Harrison

许可证

有关详细许可证信息，请参阅LICENSE文件。

致谢

使用🔥和❄️由XYO