brightBeacon

来自于:智石立即使用

概述

brightBeacon是一个基于Web的API库,以便与iBeacon、brightBeacon设备互动。该SDK安装要求IOS6.0+iPhone4s以上、Android4.3及以上支持蓝牙低功耗(BLE)的设备。 brightBeacon是智石说(北京)科技有限公司提供给开发者使用的API库。

使用此模块 需要打开定位权限(IOS 7.0和Android 6.0及以后必要)、蓝牙权限

registerAppKey

注册并验证开发者appKey,申请地址:智石开放平台

registerAppKey({params},callback(ret, err))

params

key:

callback(ret, err)

ret:

  • 类型:JSON对象
  • 内部字段:
{
    status: true      //布尔型;true,验证成功
}

err:

  • 类型:JSON对象
  • 内部字段:
{
    error:无效的AppKey
            AppKey注册失败
}

示例代码

var bb;
apiready = function() {
        bb = api.require('brightBeacon');
    };
bb.registerAppKey({
            key: ""
        }, function(ret, err) {
            if (ret.status) {
                alert(JSON.stringify(ret))
            } else {
                alert(JSON.stringify(err))
            }
        });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

startRanging

扫描iBeacon或brightBeacon蓝牙设备

startRanging({params}, callback(ret, err))

params

uuids:

  • 类型:uuid数组,扫描的设备UUID(推荐传入),留空或不传扫描所有设备(iOS有差异)
  • 描述:注意Android使用蓝牙,IOS扫描iBeacon都需要请求蓝牙定位权限(非GPS);另IOS在留空或不传该参数时,无法获得扫描设备的UUID参数,但能获取电量等参数,并支持连接、配置设备(由于IOS对iBeacon扫描和蓝牙扫描的严格区分导致)
  • 常用取值:
    • E2C56DB5-DFFB-48D2-B060-D0F5A71096E0
    • FDA50693-A4E2-4FB1-AFCF-C6EB07647825
    • 任意标准UUID格式即可(如上)

callback(ret, err)

ret:

  • 类型:JSON对象
  • 内部字段:
{
    status: true   //布尔型;true||false
    list: [{
            uuid:       //设备UUID,区域标识(IOS需此UUID包含在传入参数数组内)
               major:        //设备主值,范围[0,65535]
            minor:        //设备次值,范围[0,65535]
            rssi:        //信号强度,和发射功率有关,范围约-20 ~ -100
            accuracy:        //距离参考,由采样计算或rssi估算
            name:            //设备名(IOS不传uuids才解析)
            txPower:        //设备发射功率(IOS不传uuids才解析)
            txInterval:    //设备发射频率,越低RSSI越稳定,耗电(IOS不传uuids才解析)
            mPower:        //设备测量功率,1米处RSSI值,用于距离accuracy估算(IOS不传uuids才解析)
            battery:        //设备电量(IOS不传uuids才解析)
            temperature:    //设备温度(IOS不传uuids才解析)
            pMode:            //设备是否加密(IOS不传uuids才解析)
            version:        //设备硬件版本(IOS不传uuids才解析)
            firmware:        //设备软件版本(IOS不传uuids才解析)
            mac:            //设备蓝牙mac地址(IOS不传uuids才解析)
            broadcastMode://设备工作模式(0:仅iBeacon 2:实物网ID-取自uuid 3:实物网链接 4:0和2同时 5:0和3同时 6:2和3同时)(IOS不传uuids才解析)
            eddystoneUrl://设备谷歌实物网链接(IOS不传uuids才解析)
        },{
            ...
        }
}

err:

  • 类型:JSON对象
  • 内部字段:
{
    error: 扫描错误信息
}

示例代码

var param = {
            "uuids": ["FDA50693-A4E2-4FB1-AFCF-C6EB07647825"]
        };
        bb.startRanging(param, function(ret, err) {
                if (ret && ret.status) {
                    for (var i = 0; i < ret.list.length; i++) {
                        var beacon = ret.list[i];
                        //beacon.rssi 信号强度
                        //beacon.accuracy 距离参考
                        //beacon.major 主标识 
                        //beacon.minor 次标识
                        //beacon.uuid iBeacon的UUID(IOS需此uuid在传入列表能获取)
                        //beacon.mac 蓝牙设备mac地址(IOS在不传uuids能获取)
                        ...更多参考以上字段列表说明
                    }
                } else {
                    alert(err.error);
                }
            }

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

stopRanging

停止扫描iBeacon、brightBeacon

stopRanging()

示例代码

bb.stopRanging();

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

startMonitoring

设备区域后台监听,如需支持后台回调检测,请在apiReady之后立即初始化callback通道,保证启动后区域回调成功,{params}可留空

startMonitoring({params}, callback(ret, err))

params(可选)

uuid:

  • 类型:字符串
  • 描述:监听区域设备uuid

major:

  • 类型:字符串
  • 描述:(可选项)监听区域设备主值

minor:

  • 类型:字符串
  • 描述:(可选项)监听区域设备次值

identifier:

  • 类型:字符串
  • 描述:区域标识,识别、覆盖相同标识区域(留空选择有效的uuid_major_minor格式生成)

in:

  • 类型:字符串
  • 描述:是否监听进入区域(仅IOS支持)

out:

  • 类型:字符串
  • 描述:是否监听离开区域(仅IOS支持)

display:

  • 类型:字符串
  • 描述:是否锁屏时检测区域状态(仅IOS支持)

callback(ret, err)(可选)

开启监听区域成功不会立即返回callback, 开启监听区域失败、或监测到设备区域变化时才返回此callback, 如果需要支持后台监听区域,请在apiReady之后立即初始化callback通道。 ret:

  • 类型:JSON对象
  • 内部字段:
{
    status: true   //监听回调成功
    uuid:                //区域uuid
    major:            //区域主值(未监听为空)
    minor:            //区域次值(未监听为空)
    identifier:       //区域标识符(区域唯一标志)
    state: 1、进入区域 2、离开区域
}

err:

  • 类型:JSON对象
  • 内部字段:
{
    error:
            未设置监听区域uuid;
            major值不能超过65535!
            minor值不能超过65535!
            未设置监听区域状态!
               监听区域无效!
               该设备没有蓝牙功能,无法进行ibeacon的相关操作!
            此功能需要开启蓝牙
}

示例代码

var _param = {
            "uuid": _uuid,
            "major": _major,
            "minor": _minor,
            "in": isIn ? "1" : "0",
            "out": isOut ? "1" : "0",
            "display": isDisplay ? "1" : "0",
            "identifier": _identifier
        };
        bb.startMonitoring(_param, function(ret, err) {
            if (ret && ret.status) {
                if (ret.state) {
                    var param = {
                        "msg": (ret.state == 1 ? "进入区域通知" : "离开区域通知") + ret.uuid,
                        "action": "立即查看",
                        "userInfo": "自定义传输参数"
                    };
                    //此处发一个消息栏通知,实际或自定义动作
                    bb.sendLocalNotification(param, function(ret1, err1) {
                        if (ret1.status) {
                            alert(JSON.stringify(ret1));
                        } else {
                            alert(err1.error);
                        }
                    });
                }
            } else {
                api.alert({
                    title: '错误',
                    msg: err.error,
                }, function(ret, err) {

                });
            }
        });

补充说明

iOS

  • 如果需要程序退出后持续监听,需要提醒用户打开位置权限->始终;并需在apiReady时候初始化后台回调callback:{@link startRanging(callback(ret,err)):}

android

  • 通过服务保持后台,部分自定义系统、优化软件会严格限制程序后台服务运行时间。

    可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

stopMonitoring

停止监听

stopMonitoring()

params

uuid:

  • 类型:字符串
  • 描述:监听区域设备uuid

major:

  • 类型:字符串
  • 描述:(可选,选则需uuid同传)监听区域设备主值

minor:

  • 类型:字符串
  • 描述:(可选,选则需uuid和major同传)监听区域设备次值

identifier:

  • 类型:字符串
  • 描述:区域标识,识别、覆盖相同标识区域(留空选择有效的uuid_major_minor格式生成)

示例代码

  bb.stopMonitoring({
            uuid: uuid,
            major: major,
            minor: minor

        }, function(ret, err) {
            alert(JSON.stringify(ret));
            alert(JSON.stringify(err));
        });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

monitorRegions

获取当前监听中的区域

monitorRegions(callback(ret))

callback(ret)

ret.regions:

  • 类型:JSON对象
  • 内部字段:
{
    status: true   //布尔型;true
    uuid:
    major:
    minor:
    in:(限IOS有效)
    out: (限IOS有效)
    display:(限IOS有效)
}

示例代码

bb.monitorRegions(function(ret, err) {
                    if(ret && ret.status) {
                        var html = "";
                        for(var i = 0; i < ret.regions.length; i++) {
                            var region = ret.regions[i];
                            //region.uuid
                            //region.major
                            //region.minor
                            //region.in
                            //region.out
                            //region.display
                    }else {
                        alert(err.error);
                    }
                });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

isMonitorRegion

区域是否处于监听中,identifier和uuid_major_minor组合任选传入

isMonitorRegion({params}, callback(ret))

Params

uuid:

  • 类型:字符串
  • 描述:监听区域设备uuid

major:

  • 类型:字符串
  • 描述:(可选,选则需uuid同传)监听区域设备主值

minor:

  • 类型:字符串
  • 描述:(可选,选则需uuid和major同传)监听区域设备次值

identifier:

  • 类型:字符串
  • 描述:区域标识,识别、覆盖相同标识区域(留空选择有效的uuid_major_minor格式生成)

    示例代码

bb.isMonitorRegion({
            "uuid": uuid,
            "major": major,
            "minor": minor
        }, function(ret) {
            alert(JSON.stringify(ret));
        })
或者:
bb.isMonitorRegion({"identifier":xxx}, function(ret) {
            alert(JSON.stringify(ret));
        });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

sendLocalNotification

显示消息到通知栏

sendLocalNotification({params}, callback(ret, err))

params

msg:

  • 类型:字符串
  • 描述:通知栏消息内容

action:

  • 类型:字符串
  • 描述:通知栏操作字段

useInfo:

  • 类型:字符串
  • 描述:自定义传输参数

callback(ret, err)

ret:

  • 类型:JSON对象
  • 内部字段:
{
    status: true   //布尔型;true
}

示例代码

bb.sendLocalNotification(param, function(ret1, err1) {
                            if(ret1.status) {
                                alert(JSON.stringify(ret1));
                            } else {
                                alert(err1.error);
                            }
                        });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

startAdvertising

广播iBeacon,仅支持前台

startAdvertising({params}, callback(ret, err))

params

uuid:

  • 类型:字符串
  • 描述:广播设备uuid

major:

  • 类型:字符串
  • 描述:设备主值

minor:

  • 类型:字符串
  • 描述:设备次值

callback(ret, err)

ret:

  • 类型:JSON对象
  • 内部字段:
{
  status: true,       //布尔型;true||false
}

err:

  • 类型:JSON对象
  • 内部字段:
{
    error:uuid不能为空
            其他广播不支持或相关错误
}

示例代码

var param = {
            "uuid": _uuid,
            "major": _major,
            "minor": _minor
        };
        bb.startAdvertising(param, function(ret, err) {
            if (ret && ret.status) {
                alert("请使用其他设备开始iBeacon扫描,您将看到当前设备模拟的UUID,Major&Minor:" + _uuid + "," + _major + "," + _minor);
                obj.innerHTML = "停止模拟";
            } else {
                alert(err.error);
            }
        });

可用性

iOS 7及以上系统,Android 5.0及以上系统

可提供的1.0.0及更高版本

stopAdvertising

停止模拟设备信号

stopAdvertising()

示例代码

bb.stopAdvertising();

connectBeacon

连接设备,修改设备参数相关操作,需先执行本方法进行连接成功。

connectBeacon({mac:xx}, callback(ret, err))

params

mac:

  • 类型:字符串
  • 描述:设备mac地址。

callback(ret, err)

ret:

  • 类型:JSON对象
  • 内部字段:
{
  status: true,      //布尔型;true||false
  beacon: {
            uuid:       //设备UUID,区域标识
               major:        //设备主值,范围[0,65535]
            minor:        //设备次值,范围[0,65535]
            rssi:        //信号强度,和发射功率有关,范围约-20 ~ -100
            accuracy:        //距离参考,由采样计算或rssi估算
            name:            //设备名
            txPower:        //设备发射功率
            txInterval:    //设备发射频率
            mPower:        //设备测量功率,1米处RSSI值,用于距离accuracy估算
            battery:        //设备电量)
            temperature:    //设备温度
            pMode:            //设备是否加密
            version:        //设备硬件版本
            firmware:        //设备软件版本
            mac:            //设备蓝牙mac地址
            broadcastMode://设备工作模式(0:仅iBeacon 2:实物网ID-取自uuid 3:实物网链接 4:0和2同时 5:0和3同时 6:2和3同时)
            eddystoneUrl://设备谷歌实物网链接
  }
}

err:

  • 类型:JSON对象
  • 内部字段:
{
    error:连接相关失败
}

示例代码

bb.connectBeacon({
                    "mac": mac
                }, function(ret, err) {
                if(ret && ret.status) {
                //ret.beacon
                } else {
                    alert(JSON.stringify(err));
                }
            }

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

disconnectBeacon

断开连接设备

disconnectBeacon({mac:xx})

params

mac:

  • 类型:字符串
  • 描述:设备mac(可选),留空断开所有连接设备。

callback(ret, err)

ret:

  • 类型:JSON对象
  • 内部字段:
{
    status: true,      //布尔型;true||false
}

示例代码

    bb.disconnectBeacon({mac:'xx:xx:xx:xx:xx'});
    或
    bb.disconnectBeacon();

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

isBeaconConnected

设备是否处于连接中

isBeaconConnected({mac:xx}, callback(ret, err))

params

mac:

  • 类型:字符串
  • 描述:设备mac

callback(ret, err)

ret:

  • 类型:JSON对象
  • 内部字段:
{
    status: true,      //连接状态:true||false
}

err:无

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

writeBeaconValues

连接成功后可用,写入设备广播数据、方式、配置设备发射频率、功率等

writeBeaconValues({mac:xx,...}, callback(ret, err))

params

mac:

  • 类型:字符串
  • 描述:设备mac

uuid:

  • 类型:字符串
  • 描述:设备uuid

major:

  • 类型:字符串
  • 描述:设备major

minor:

  • 类型:字符串
  • 描述:设备minor

txInterval:

  • 类型:字符串
  • 描述:设备发射间隔,100毫秒~10秒

mPower:

  • 类型:字符串
  • 描述:设备测量功率,1米处rssi值,用于接收设备距离估算

pMode:

  • 类型:字符串
  • 描述:设备加密,需要APPKEY

txPower:

  • 类型:字符串
  • 描述:设备发射功率 -30 -20 -16 -12 -8 -4 0 4

batteryInterval:

  • 类型:字符串
  • 描述:设备电量检测间隔

temperatureInterval:

  • 类型:字符串
  • 描述:设备温度检测间隔

broadcastMode:

  • 类型:字符串
  • 描述:设备广播模式

eddystoneUrl:

  • 类型:字符串
  • 描述:谷歌实物网,国内无法使用

callback(ret, err)

ret:

  • 类型:JSON对象
  • 内部字段:
{
    status: true,      //布尔型;true||false
}

err:

  • 类型:JSON对象
  • 内部字段:
{
    error:参见错误描述
}

示例代码

        var param = {
                    "mac": _mac,
                    "uuid": _uuid,
                    "major": _major,
                    "minor": _minor,
                    "name": _name,
                    "txInterval": _txInterval,
                    "mPower": _mPower,
                    "pMode": _mode,
                    "txPower": _txPower,
                    "batteryInterval": _batteryInterval,
                    "temperatureInterval": _temperatureInterval,
                    "broadcastMode": _broadcastMode,
                    "eddystoneUrl": _eddystoneUrl
                };
                //发起连接
                bb.connectBeacon({mac:_mac},function(r,e){
                if(r && r.status) {
                //写入参数
                bb.writeBeaconValues(param, function(ret, err) {
                //断开连接
                    bb.disconnectBeacon(_mac);
                 if(ret && ret.status) {api.toast({
                                        msg: '保存成功',
                                        duration: 2000,
                                        location: 'middle'
                                        });
                    } else {
                        alert(err.error);
                    }
                });
                }
            }

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

sendBeaconValue

连接成功后可用,通过命令模式写入设备参数,基本参数修改效果同writeBeaconValues,并支持自定义扩展硬件的命令发送。
基本参数修改对应的消息ID:
0x00~0x3F:Beacon参数配置定义:
00重启 01版本 02温度电量 03写key 04读UUID 05写UUID 06读MM 07写MM 08读MPower 09写MPower
0A读功率 0B写功率 0C读模式 0D写模式 0E读名称 0F写名称 10读频率 11写频率 12读温度电量间隔 13写温电间隔 14读自定义广播
15写自定义广播 16读eddystoneUrl 17写eddystoneUrl 18开始/停止固件升级数据 19写入固件升级数据 20~3F内部扩展保留
0x40~0xFF:配合硬件SDK自定义传输使用

sendBeaconValue({mac:xx}, callback(ret, err))

params

mac:

  • 类型:字符串
  • 描述:设备mac

callback(ret, err)

ret:

  • 类型:JSON对象
  • 内部字段:
{
    status: true,      //布尔型;true||false
}

err:

  • 类型:JSON对象
  • 内部字段:
{
    error:参见错误描述
}

示例代码

//示例读取版本
                bb.sendBeaconValue({
                    "mac": _mac,
                    "value": "0102"
                }, function(ret, err) {
                    if(ret.status) alert("示例:发送命令0102获取版本数据:" + ret.data + "(命令/数据格式:1byte标识+1byte当前命令总byte数+数据(<=18byte))");
                });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

checkBeaconFirmwareUpdate

检测设备固件版本

checkBeaconFirmwareUpdate({mac:xx}, callback(ret, err))

params

mac:

  • 类型:字符串
  • 描述:设备mac

callback(ret, err)

ret:

  • 类型:JSON对象
  • 内部字段:
{
    status: true,      //布尔型;true||false
    update: true,        //布尔型;true有更新,false无更新
}

err:

  • 类型:JSON对象
  • 内部字段:
{
    error:参见错误描述
}

示例代码

var param = {
                    "mac": _mac
                };
                bb.checkBeaconFirmwareUpdate(param, function(ret, err) {
                    if(ret && ret.status && ret.update) {
                        bb.updateBeaconFirmwareWithProgress(param, function updateBack(ret, err){
                                if(ret.progress == '100'){
                                    //升级完成
                                }
                        });
                    } else {
                        //error;
                    }
                });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

updateBeaconFirmwareWithProgress

更新设备固件

updateBeaconFirmwareWithProgress({mac:xx}, callback(ret, err))

params

mac:

  • 类型:字符串
  • 描述:设备mac

callback(ret, err)

ret:

  • 类型:JSON对象
  • 内部字段:
{
    status: true,      //布尔型;true||false
    progress:进度 [0,100]
}

err:

  • 类型:JSON对象
  • 内部字段:
{
    error:参见错误描述
}

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

resetBeacon

重置设备参数,默认值:

参数名 默认值
UUID E2C56DB5-DFFB-48D2-B060-D0F5A71096E0
major mac后8位前4位
minor mac后8位后4位
名称name BrightBeacon
测量功率mPower -65
广播频率txInterval 760ms
广播功率tx 0dBm
设备加密pMode

resetBeacon({mac:xx}, callback(ret, err))

params

mac:

  • 类型:字符串
  • 描述:设备mac

callback(ret, err)

ret:

  • 类型:JSON对象
  • 内部字段:
{
    status: true,      //布尔型;true||false
}

err:

  • 类型:JSON对象
  • 内部字段:
{
    error:参见错误描述
}

可用性

iOS系统,Android系统 可提供的1.0.0及更高版本