BlueRangeSDK 1.1.14

BlueRangeSDK 1.1.14

×

测试已测试✓
Lang语言 Obj-CObjective C
许可证 Apache 2
发布最新发布2017年9月

由 me-mway 维护。

BlueRangeSDK 1.1.14

  • 由
  • M-Way Solutions GmbH

BlueRange SDK

概述

BlueRange SDK 是一个基于 Android 和 iOS 的库，使应用程序能够与 Relution SmartBeacons 交云。SmartBeacons 可以通过构建基于 FruityMesh 信标固件的 BLE 网络(mesh) 遥距管理、监控、更新和配置，从而始终连接到云端。

特性

目前，BlueRange SDK 支持 iOS 8.0 及以上版本的设备和 API 级别 18 或更高版本的 Android 设备。然而，基于 BLE 广告的特性在 Android 设备上（API 级别 21）需要蓝牙 LE 外设模式。

BlueRange SDK 由核心层和服务层组成。

核心层 包含一系列组件，可以简化信标消息流处理（例如 iBeacon 或 Eddystone 消息）。这些消息处理组件可以组合起来，形成一个灵活的事件驱动架构。

服务层 位于核心层之上，将您的应用程序与 Relution 连接起来。

具体支持以下功能：

核心

广告

  • 发送任意数据的 BLE 广告消息。
  • 发送用于生成热图广告的消息。

扫描

  • 扫描不同格式的信标消息。
    • iBeacon 消息：苹果公司的标准 BLE 广告格式，包含一个标识符三元组（UUID、major 和 minor）。
    • Eddystone UID 消息：谷歌的标准 BLE 信标格式之一，由一个 10 字节命名空间 UID 和一个 6 字节实例标识符组成。
    • Eddystone URL 消息：另一种 Eddystone 信标格式，包含一个 URL。
    • Join Me 消息：基于 FruityMesh 的信标广播这些消息以建立信标网络。每个数据包包含信标 ID、其连接性和一些其他信息，可用于识别和分析 Relution SmartBeacons。
    • Relution 标签 消息：仅由 Relution IoT 支持的广告消息格式。它包含用于离线接近式营销场景的标签列表。
    • 资产管理 消息：Relution AssetBeacons 使用的广告消息格式。资产信标可用于资产定位和追踪。
  • 当应用程序运行在 后台 时将继续扫描。然而，由于 Apple 限制，此功能有限。
  • 节能：可以通过更改扫描循环持续时间和睡眠间隔来控制。

日志记录

  • 消息可以 持久记录并在以后进行处理。
  • 用于收集室内定位的训练和验证数据。

报告

  • 长时间记录的消息可以汇总成状态报告并发布到云端。
  • 云可以对这些报告进行评估以生成热图或服务器端强室内定位。

聚合

  • 大多数邻近消息用例都需要稳定的信号强度（RSSI）来正确估计信标距离。可以使用消息聚合器来平均信标消息流的RSSI测量值。

触发

  • 可以使用消息触发器来实现邻近营销场景。每当信标消息到达时，如果满足预定义的时间或位置条件，触发器将执行操作，并通知您的应用程序操作已执行。目前支持的操作参数有：
    • 操作延迟：操作将在预定义的延迟后执行。
    • 操作锁定：操作在触发后锁定一定时间。
    • 激活距离：只有当设备与信标的距离低于预定义的阈值时，才会触发操作。
    • 验证周期：操作可以有一个验证开始和结束时间。

服务

Relution SmartBeacon校准

  • 由于信标在无线电特性上各不相同，可以通过校准RSSI来改进距离估计。

Relution邻近营销

  • 实现邻近营销（在Relution物联网中也称为"Relution活动"）。

Relution热图

  • 设备将发送由信标收集的广告消息，用于在云端生成热图。

API参考

  • 有关特定类的更多信息，请参阅docs文件夹中的API参考。

安装

手册

将构建命令（如下所述）生成的BlueRangeSDK.framework包含在您的目标"嵌入式二进制文件"中。要做到这一点，请选择您的Xcode项目目标，并按"通用"标签中的"嵌入式二进制文件"部分中的"+"按钮。然后，单击"添加其他"并添加BlueRangeSDK.framework文件。

可以使用以下导入方案导入BlueRange SDK的头文件：

#import <BlueRangeSDK/<HeaderFile>.h>

构建

构建

为了构建包含ARM和Intel架构符号的通用（胖）二进制文件

./Build.sh

SDK二进制文件可以在BlueRangeSDK-<VERSION>/ios/BlueRangeSDK.framework中找到。

仅构建ARM架构

./Build_ARM_only.sh

SDK二进制文件可以在build/Debug-iphoneos/BlueRangeSDK.framework中找到。

生成Javadoc

./GenerateDocs.sh

示例代码

以下部分显示了可能有助于您将库集成到应用程序中的代码示例。

Relution物联网服务

服务配置

如果您的应用程序应连接到Relution，请使用RelutionIoTService。如下所示，您必须在启动服务之前配置服务。

  • 活动：如果您想使用Relution邻近营销并通知您在Relution"活动"部分中定义的已执行的特定操作，请打开此功能。
  • 分析：如果您希望SDK定期向Relution发送报告，这些报告以后可用于分析，请打开此功能。
  • 热图：如果您想使设备发送热图消息，请打开此功能。Relution SmartBeacon将估计附近设备数量并向云端发送热图报告。
  • 日志记录：如果您想使SDK记录到控制台，请打开日志记录。关闭此功能以提高应用程序的整体性能。
// .h
#import <BlueRangeSDK/BRRelutionIoTService.h>
@interface <YourClass> : NSObject<BRLoginObserver>
@property BRRelutionIoTService* relutionIoTService;
@end

// .m
#import <BlueRangeSDK/BRRelutionIoTService.h>

- (void) startRelutionIoTService {
    NSString* baseUrl = @"http://iot.relution.io";
    NSString* username = @"your_relution_username";
    NSString* password = @"your_relution_password";
    
    self->_relutionIoTService = [[BRRelutionIoTService alloc] init];
    [self->_relutionIoTService setLoginData:baseUrl 
        andUsername:username andPassword:password andLoginObserver:self];
    [self->_relutionIoTService setLoggingEnabled:true]; // Logging
    [self->_relutionIoTService setCampaignActionTriggerEnabled:true]; // Campaigns
    [self->_relutionIoTService setHeatmapGenerationEnabled:true]; // Heatmap
    [self->_relutionIoTService setHeatmapReportingEnabled:true]; // Analytics
    [self->_relutionIoTService start];
}

- (void) onLoginSucceeded {
    
}

- (void) onLoginFailed {
    
}

- (void) onRelutionError {
    
}

Relution SmartBeacon校准

要校准iBeacon消息的RSSI值，只需将设备放置在信标1米远的位置
并将基于约10秒测量的平均RSSI值发送到Relution，方法如下所示调用calibrateIBeacon：

// .h
#import <BlueRangeSDK/BRRelutionIoTService.h>
@interface <YourClass> : NSObject<BRBeaconMessageObserver>
@property BRRelutionIoTService* relutionIoTService;
@end

// .m
#import <BlueRangeSDK/BRRelutionIoTService.h>
#import <BlueRangeSDK/BRIBeaconMessage.h>

- (void) registerBeaconMessageObserver {
    [BRRelutionIoTService addBeaconMessageObserver:self];
}

- (void) onMessageReceived: (BRBeaconMessage*) message {
    // Do something with the message.
    if ([message isKindOfClass:BRIBeaconMessage]) {
        // Get the iBeacon message
        BRIBeaconMessage* iBeaconMessage = (BRIBeaconMessage*)message;
        // User moves to a place 1 meter away from the beacon that sends the iBeacon message...
        // Calibrate the iBeacon message.
        [BRRelutionIoTService calibrateIBeacon:iBeaconMessage.iBeacon withTxPower:iBeaconMessage.rssi];
    }
}

Relution邻近消息

为在Relution"活动"部分中定义的操作注册事件监听器。

// .h
#import <BlueRangeSDK/BRRelutionIoTService.h>
@interface <YourClass> : NSObject<
    BRBeaconNotificationActionObserver,
    BRBeaconContentActionObserver,
    BRBeaconTagActionObserver>
@property BRRelutionIoTService* relutionIoTService;
@end

// .m
#import <BlueRangeSDK/BRRelutionIoTService.h>

- (void) registerCampaignActionObservers {
    // Get informed about to campaign actions.
    [BRRelutionIoTService addBeaconNotificationActionObserver:self];
    [BRRelutionIoTService addBeaconContentActionObserver:self];
    [BRRelutionIoTService addBeaconTagActionObserver:self];
}

- (void) onNotificationActionExecuted: (BRBeaconNotificationAction*) notificationAction {
    
}

- (void) onContentActionExecuted: (BRBeaconContentAction*) contentAction {
    
}

- (void) onTagActionExecuted: (BRBeaconTagAction*) tagAction {
    
}

Relution热图

要启用热力图报告，只需使用BeaconAdvertiser类开始广播发现消息。

// .m
#import <BlueRangeSDK/BRBeaconAdvertiser.h>
// ...
[[[BRBeaconAdvertiser alloc] init] startAdvertisingDiscoveryMessage];
// ...

Relution标签

如果您使用Relution标签进行邻近消息，请注册一个RelutionTagObserver以获取所有接收到的Relution标签的通知。如果您需要访问Relution标签的名称或描述，只需调用getTagInfoForTag

// .h
#import <BlueRangeSDK/BRRelutionIoTService.h>
@interface <YourClass> : NSObject<
    BRRelutionTagObserver>
@property BRRelutionIoTService* relutionIoTService;
@end

// .m
#import <BlueRangeSDK/BRRelutionIoTService.h>
#import <BlueRangeSDK/BRRelutionTagInfoRegistry.h>
#import <BlueRangeSDK/BRRelutionTagMessage.h>

- (void) registerRelutionTagObserver {
    [BRRelutionIoTService addRelutionTagObserver:self];
}

- (void) onTagReceived: (long) tag message: (BRRelutionTagMessage*) message {
    @try {
        [BRRelutionIoTService getTagInfoForTag:tag];
    } @catch(BRRelutionTagInfoRegistryNoInfoFound* exception) {
        // ...
    }
}

核心

如果您想构建独立于Relution的Beacon感知应用，请使用核心层。

扫描

启动扫描仪，如下所示。即使扫描仪正在运行，您也可以更改扫描仪的配置。

// .h
#import <BlueRangeSDK/BRBeaconMessageScanner.h>
#import <BlueRangeSDK/BRBeaconMessageScannerConfig.h>

@interface SystemTestsApplication : NSObject<BRBeaconMessageStreamNodeReceiver>
@property (strong) BRIBeaconMessageScanner* scanner;
@end

// .m
#import <BlueRangeSDK/BRBeaconMessageScanner.h>
#import <BlueRangeSDK/BRBeaconMessageScannerConfig.h>

- (void) startScanning {
    self->_scanner = [[BRBeaconMessageScanner alloc] initWithTracer:[BRTracer getInstance]];
    BRBeaconMessageScannerConfig *config = [self->_scanner config];
    [config scanIBeacon:@"b9407f30-f5f8-466e-aff9-25556b57fe6d" major:45 minor:1];
    [config scanIBeacon:@"c9407f30-f5f8-466e-aff9-25556b57fe6d" major:46 minor:2];
    [config scanRelutionTagsV1:[[NSArray alloc] initWithObjects:
                                [NSNumber numberWithLong:13], [NSNumber numberWithLong:2], nil]];
    [config scanJoinMeMessages];
    [self->_scanner addReceiver:self];
    [self->_scanner startScanning];
}

- (void) onMeshActive: (BRBeaconMessageStreamNode *) senderNode {
    // Do something
}

- (void) onReceivedMessage: (BRBeaconMessageStreamNode *) senderNode withMessage: (BRBeaconMessage*) message {
    // Do something
}

- (void) onMeshInactive: (BRBeaconMessageStreamNode *) senderNode {
    // Do something
}

日志记录

如果您想在稍后的时间处理Beacon消息，可能需要在设备上持久化地保存它们并在稍后读取。为此，您可以使用提供此目的便捷且线程安全的接口的BeaconMessageLogger。在大多数情况下，您会将扫描仪传递给日志记录器的构造函数。但是，如果您的消息处理流程更复杂，您可以传递任何实现BeaconMessageStreamNode接口的消息处理组件。接收到的消息将被传递给所有附加到日志记录器的接收者。因此，您可以将日志记录器用作静默消息持久化器

// .h
#import <BlueRangeSDK/BRBeaconMessageScanner.h>
#import <BlueRangeSDK/BRBeaconMessageScannerConfig.h>
#import <BlueRangeSDK/BRBeaconMessageLogger.h>

@interface SystemTestsApplication : NSObject<BRBeaconMessageStreamNodeReceiver>
@property (strong) BRIBeaconMessageScanner* scanner;
@property (strong) BRBeaconMessageLogger* logger;
@end

// .m
#import <BlueRangeSDK/BRBeaconMessageScanner.h>
#import <BlueRangeSDK/BRBeaconMessageScannerConfig.h>
#import <BlueRangeSDK/BRBeaconMessageLogger.h>

- (void) startLogging {
    // Configure Beacon scanner
    self->_scanner = [[BRBeaconMessageScanner alloc] initWithTracer:[BRTracer getInstance]];
    BRBeaconMessageScannerConfig *config = [self->_scanner config];
    [config scanIBeacon:@"b9407f30-f5f8-466e-aff9-25556b57fe6d" major:45 minor:1];
    [config scanIBeacon:@"c9407f30-f5f8-466e-aff9-25556b57fe6d" major:46 minor:2];
    [config scanRelutionTagsV1:[[NSArray alloc] initWithObjects:
                                [NSNumber numberWithLong:13], [NSNumber numberWithLong:2], nil]];
    [config scanJoinMeMessages];
    
    // Configure BeaconMessageLogger
    self->_logger = [[BRBeaconMessageLogger alloc] initWithSender:self->_scanner];
    
    [self->_logger addReceiver:self];
    [self->_scanner startScanning];
}

- (void) onMeshActive: (BRBeaconMessageStreamNode *) senderNode {
    // Do something
}

- (void) onReceivedMessage: (BRBeaconMessageStreamNode *) senderNode withMessage: (BRBeaconMessage*) message {
    // Do something
}

- (void) onMeshInactive: (BRBeaconMessageStreamNode *) senderNode {
    // Do something
}

如果您想一步内消耗日志中保存的所有消息，您可以使用readLog方法。但是，如果您的日志包含大量消息，最好使用日志迭代器或for each循环来减少内存消耗。迭代器将按它们被保存的顺序加载消息。正在针对线程安全和性能进行优化。

id<BRLogIterator>* logIterator = [self->_logger getLogIterator];
while ([logIterator hasNext]) {
    BRBeaconMessage* message = [logIterator next];
    // Do something
}

聚合

如果您想减少整体的消息吞吐量或平均接收到的信号强度（RSSI），则消息聚合可能很有用。BeaconMessageAggregator目前支持两种模式：数据包模式和滑动窗口模式。数据包模式结合接收了一个特定时间内的等效消息流，而滑动窗口模式则保持流中相同数量的消息同时使用移动平均滤波器平均RSSI

// .h
#import <BlueRangeSDK/BRBeaconMessageScanner.h>
#import <BlueRangeSDK/BRBeaconMessageScannerConfig.h>
#import <BlueRangeSDK/BRBeaconMessageAggregator.h>
#import <BlueRangeSDK/BRLinearWeightedMovingAverageFilter.h>

- (void) startAggregating {
    // Configure scanner
    self->_scanner = [[BRBeaconMessageScanner alloc] initWithTracer:[BRTracer getInstance]];
    BRBeaconMessageScannerConfig *config = [self->_scanner config];
    [config scanIBeacon:@"b9407f30-f5f8-466e-aff9-25556b57fe6d" major:45 minor:1];
    [config scanIBeacon:@"c9407f30-f5f8-466e-aff9-25556b57fe6d" major:46 minor:2];
    [config scanRelutionTagsV1:[[NSArray alloc] initWithObjects:
                                [NSNumber numberWithLong:13], [NSNumber numberWithLong:2], nil]];
    [config scanJoinMeMessages];

    // Configure aggregator
    BRBeaconMessageAggregator* aggregator = [[BRBeaconMessageAggregator alloc]
                                           initWithTracer:[BRTracer getInstance] andSender:self->_scanner];
    [aggregator setAggregationMode:AGGREGATION_MODE_SLIDING_WINDOW];
    [aggregator setAggregateDurationInMs:5*1000];
    [aggregator setAverageFilter:[[BRLinearWeightedMovingAverageFilter alloc] initWithC:0.3]];
}

广告

要定期发送广告消息，只需调用BeaconAdvertiser类的任一start方法。

// .m
#import <BlueRangeSDK/BRBeaconAdvertiser.h>

- (void) startAdvertising {
    self.beaconAdvertiser = [[BRBeaconAdvertiser alloc] init];
    [self.beaconAdvertiser startAdvertisingDiscoveryMessage];
}

许可证

* Copyright (c) 2017, M-Way Solutions GmbH
* All rights reserved.

* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
* 
*     https://apache.ac.cn/licenses/LICENSE-2.0
* 
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.