云端使用说明文档

注：为了方便描述，下文将蓝牙路由器称为AP。
蓝牙路由器以及蓝牙设备的管理软件称为AC。

正文

一、产品综述

1.1、产品介绍AP,AC是什么？

AP：
        1） 蓝牙路由器(AP):可以通过扫描和建连的方式对蓝牙设备进行控制和数据采集。一方面，蓝牙路由器可以大大地提高传统的蓝牙通信距离和连接 终端数量，另一方面，蓝牙路由器可以将蓝牙信号通过网络传递给远程的控 制端。
        2） 蓝牙路由器(AP):可以实现主设备到从设备的角色反转，作为模拟蓝牙设备向外发送广播包。

AC:
        1）AC是一套对AP以及蓝牙设备的管理软件。
针对企业的业务层提供 API 接口作为调用、数据转发、定位、漫游、 安全及策略管理等，可以跨越局域网实现对AP的远程控制。
        2）AC作为集中管理的网络节点，其形态可以有如下三种：
盒子：旁挂在用户网络的汇聚交换机或核心交换机上。
私有云：部署在刀片服务器上。
公有云：部署在IDC机房或阿里云、亚马逊上，为B端用户提供蓝 牙路由器托管服务。

1.2、AP，AC会给你带来什么？

AP：
        1)AP解决了手机与蓝牙设备之间只能一对一连接的问题。
        2)解决了手机与蓝牙设备之间只能连接10m的问题
        3)家庭方面：可躺在沙发通过手机，控制家中多个蓝牙设备
        4)养老方面：通过蓝牙技术将跌倒呼救器与智能终端或者蓝牙路由器相连接， 实现使用者的跌倒自动报警和一键主动求救。
        5)教育方面：管理学生进出校，考勤管理，反向通知等功能。
        6)工业方面：通过传感器，实时获取多个工业设备的运转状态及数据等。
        7)运动检测：通过手环，获取多人实时心率，步数，卡路里等数据
        8)AP提供了简单的api接口，供开发使用
AC：
         1) 快速批量配置网络信息、wifi等
        2) 连接保障、系统的稳定性
        3) 可视化查询ap的状态以及详细信息（如版本信息等）
        4) 定位功能
        5) 方便接入客户的软件系统
        6) 可以通过外网远程控制
        7) 对局域网的网络环境适应性强（二层、三层网络均可，可穿透内网防火墙）
        8) 可以根据ap的唯一标识（mac地址）来控制ap，防止出现ap的ip变化 的问题
        9) 安全问题，内网通过ip地址调试无任何安全机制，普通人可以简单地干扰 ap的使用，需要oAuth认证；ac支持https方式对数据进行加密

二、产品结构

2.1、网络结构图

        下图一是集中管理架构下，AC作为网络设备、私有云时的网络结构示意图：
         Alt text

图1： AC作为网络设备或私有云时的网络拓朴

        图二是集中管理架构下，AC作为公有云时的网络结构示意图：
        Alt text

图2： AC作为公有云部署时的网络拓朴

        有线上行和WiFi上行的AP均可由本地局域网连接到AC上；若采用3G、LTE上行时，AC需要在互联网上具备一个公网地址（或公网映射）,AP通过互联网可连入AC。
业务平台与AC之间通过局域网或Internet进行通信。

2.2、工作流程图

        Alt text
        Alt text

以下为我们健身房实例图：
        Alt text

2.3、连网方式

        3.1：以太网：通过以太网线直接连接到AP的网口，AP将会自动接入接入互联网，AP的IP地址默认通过DHCP方式获取。
        3.2：wifi：只支持2.4G网络，不支持portal认证方式
        3.3：3G,4G(暂不支持5G)：插入3G/4G无线网卡到USB插口，AP将会自动接入互联网， 目前大陆支持中兴MF823 Hilink版

优先级：以太网>wifi>3G4G（即：插上网线后，优先通过以太网方式进行dhcp分配地址）

三、对接流程 ，AP详细功能及BI使用说明

3.1 AP与AC对接设备调试的流程（必看）此流程可完成初步对接

        1) 将AP供电并插上网线，保证其可以进入到配置页面。(3.2)
        2) 进入到AP配置页面，对AP进行配置，填写Developer Key和 AC Address保证与AC端一致。(3.4)
        3) 进入到AC，在设置中填写Developer Key和Developer Secret。(4.6)
        4) AC添加或自动发现AP，等待约1分钟后，AP上线，可以进行调试及对接工作。(4.6)
        5) 通过蓝牙调试工具或其他方式进行设备的对接，获取数据。(5.2)
        6) 最后遵照蓝牙协议进行解析数据。(例子见6.12)
        选看(7) 在可以成功使用AC后可对AC中的BI进行使用，目前支持教育解决方案（详情看4.8）

3.2 怎么进入到AP的配置页面？

        1）将进入到wifi路由器的配置页面
        2）找到AP的mac地址（在AP的底部）
        3）进入WiFi路由器控制面板，通过mac地址查找AP被分配的IP地址。
        4）在浏览器地址栏中输入AP的ip地址即可进到AP的配置页面

Alt text

3.3 获取AP的ip地址

        进入WiFi路由器控制面板，查看AP被分配的IP地址。
在这里找到AP的mac地址所对应的ip地址
        Alt text

3.4 AP配置页面的详情

Alt text

将AP登录到AC ，必须配置Developer和 AC Address（cassia提供）
Alt text

3.5 怎么连接到3G/4G网？

        插入3G/4G无线网卡到USB插口，AP将会自动接入互联网，目前大陆 支持中兴MF823 Hilink版。

3.6 怎么连接到以太网 ？怎样设置静态IP？

        通过以太网线直接连接到AP的网口，AP将会自动接入接入互联网，AP的IP地址默认通过DHCP方式获取。
        可以在AP配置页面将IP配置为static
        打开cmd，输入ipconfig

Alt text
Alt text

3.7怎么连接到WiFi？（及网络优先级问题）

        插上网线连接以太网。通过IP地址进入AP的配置页面(如图3)，在Wireless处配置WIfI 的名字和密码,配置完成后拔掉网线，AP会自动连接WiFi.
        设置WiFi静态IP，同上
        网络优先级：连网的优先级由高到低为：3G/4G > 以太网 > WiFi（优先级：当3G/4G、以太网、WIFI并存的情况下数据会从优先级高的通道走）

3.8连网成功有什么提示吗？

        AP上共有5个指示灯：WIFI、BT、SYS、PWR、ETH;
        当接通电源后，PWR的绿灯常亮；
        当系统正常工作时，SYS的绿灯会闪烁；
        当连接以太网成功后，ETH的绿灯会闪烁；
        当连接WIFI以后，WIFI的绿灯会闪烁。
        当有蓝牙设备与其连接上时，BT亮

3.9 AP登录到AC,需要配置哪些参数？

        让AP登录到AC，必须配置AC Address和Developer 。Developer 要跟AC中设置相同，配置成功后点击保存。然后进入AC中添加或自动发现AP

四、AC详细功能

4.1总览面板

Alt text

Alt text

4.2 ac历史统计

Alt text
Alt text
Alt text

4.3管理蓝牙路由器

Alt text

4.4查看已连接蓝牙设备

Alt text

4.5 地图管理

Alt text
Alt text

4.6 AP怎么连接到AC（设置详情）

Alt text

Alt text

Alt text

点击添加或自动发现，并写入AP的mac地址和名字(名字自定义)
添加：
Alt text

自动发现：
Alt text

点击确定后，等待约1分钟，AP上线，就可以进行简单的调试，对接工作了。

4.7升级更新与维护

Alt text

4.8BI的使用说明

4.8.1BI概述

        ①、BI是什么
BI（Business Intelligence）即商务智能软件，是一种根据预设定的程序自主处理用户的原始数据，并将原始数据转化成可读的用户数据的软件。在我们的产品中，BI是通用的面向大部分客户的蓝牙数据采集及蓝牙数据交互平台。
        ②、为什么要用BI
使用蓝牙路由器获取数据后，将原始数据进行解析，并发送到服务地址的过程，多是重复工作，这样的开发多为复杂，繁琐的工作。若使用相同的手环，解析数据是对于每个客户都相同步骤。为省去客户许多不必要的对接工作，我们创造了BI。

4.8.2、BI页面
Alt text

4.8.3、BI功能及使用

        AC进入BI的唯一通道：将AC地址中主机名后的第一个路由改为”bi”，即可进到BI中。
Alt text

        进到BI后，会有许多版本选择，在您想要的版本后点击install，即可下载成功。
Alt text

        点击setting，进到BI配置页面
BI目前整合了6项业务，数据采集业务、信息录入业务、定位业务、进出校业务、反向通知业务、校时业务。
        每项业务必须填写参数，保存后需重启BI，路由器会将获取到的数据发送到目标地址上。

Alt text

我们以定位业务为例：

Alt text

        当我们想要获取到手环的数据时，需将左侧AC的信息写入，地址为AP的所在AC地址（后面必须加入端口号+/api），账号及密码为AC中设置项的信息。右侧有4项填写的信息，url为目标服务器地址，数据将通过post请求方式向地址推送数据。选择设备为使用设备的名称。发送间隔为获取到的数据发送至目标服务器的发送间隔。数据类型有json和form两种类型。
        全部配置好后，点击保存，若提示保存失败，请完善上方配置信息，不符合标准的会有提示，确认信息填写正确后，点击保存，会提示”保存成功，重启BI生效”，返回到上一页面，重启BI。配置信息即可生效。

再以比较复杂的校时业务为例：

校时业务分为自动校时，手动校时。
        自动校时：

Alt text

选择设备：为使用的终端设备
是否接收回复：为是否接收校时的结果
接受回复的地址：为接受结果的地址，BI将校时的结果通过post请求推送至目标地址
校时开始时间；为路由器开始进行校时的时间点，时间以AC服务器的时间为准。注：若校时开始时间为8:00则在8点前需将手环开启（路由器可以扫到），在8点过后再次扫描到手环才可进行校时。
校时时间：为进行校时的总时长，若接受回复，且在指定时间内没有全部校时成功，则校时时间结束时向服务器推送校时结果。若接受回复，且全部手环在时间范围内全部校时成功，则在全部校时成功后，将结果推送至服务器。

        手动校时：

Alt text

选择设备为使用的终端设备
是否接收回复为是否接收校时的结果
BI服务器地址为将进行手动校时的手环或其他蓝牙设备的MAC地址推送至BI的服务器中的地址。常为http://192.168.199.183:8081/bi/education/api/clockSync/后接自定义路由。（下面以postman为例，向BI服务器发送请求）注：推送的地址与BI页面中的地址必须统一。
接受回复的地址 Alt text

为接受结果的地址，BI将校时的结果通过post请求推送至目标地址。推送的数据格式请看业务的介绍文档

校时开始时间为路由器开始进行校时的时间点，时间以AC服务器的时间为准
校时时间为进行校时的总时长，若接受回复，且在校时时间内没有全部校时成功，则校时时间结束时向服务器教室结果数据。若接受回复，且全部手环在时间范围内全部校时成功，则在全部校时成功后，将结果推送至服务器。
黑白名单为是选用制定路由器执行，还是不选用指定路由器执行

我们拿postman举例，向BI服务器地址发送指定的校时手环。

        Headers中写入Content-        Type:application/json
        Body中数据格式为
         “type”: “clockSync”,
         “timeout”: 300,//与BI中的填写相同
         “requireRes”: “true”,
         “deviceMac”:[“D8:45:A3:B8:20:C2”,”D3:CB:56:6E:7C:82”,”E6:96:F1:52:D1:C2”]

五、配置完成后怎么调试？

5.1 可以用哪些工具进行调试？

        1）我们提供了一个蓝牙调试工具，实现了API中的大部分控制功能，在如何操作见5.2；
        2）其他支持HTTP请求的软件，比如Postman(不支持SSE)，如何操作间见5.3；
        3）浏览器(不支持POST请求)，在地址栏发送http请求，如何操作见5.4；

5.2 蓝牙调试工具怎么使用？（推荐）

(http://www.bluetooth.tech/nativeHubControl/index.html)
        说明文档：点击下载蓝牙调试工具说明文档

5.3 Postman怎么调用API接口？(不支持sse)

        需要获取token，详细见6.4
Alt text

5.4 浏览器怎么调用调用API接口？(不可请求post)

        在浏览器地址栏中输入API接口
例:scan接口
Alt text

六、API接口的常见问题

API接口文档地址：https://cassiasdk.docs.apiary.io
找到APIs的章节，即为所有API的接口

6.1 什么是API接口？都有哪些接口？

        AP提供了简单的api接口，供开发使用

token

http://AC address/oauth2/token

Scan(sse)

http://AC address/gap/nodes/?event=1&mac=&chip=&filter_name=&filter_mac=&filter_uuid=&access_token=

Connect(post)

http://AC address/gap/nodes/<node>/connection?mac=&chip=&access_token=

       post请求的body:({
        "timeout": "1",//此字段可不写（默认5s），最小值为1
        "type" :"public" // `public` or `random`
      })
Disconnect(delete)

http://AC address/gap/nodes/<node>/connection?mac=&access_token

Connect_list(get)

http://AC address/gap/nodes/?connection_state=connected&mac=&access_token=

Discover services & characteristics & desciptors(get)

http://AC address/gatt/nodes/<node>/services/characteristics/descriptors?mac=&access_token=

Get device connection state(sse)

http://AC address/gap/nodes/?connection_state=connected&mac=&access_token=

Write by handle(get)

http://AC address/gatt/nodes/<node>/handle/<handle>/value/<value>/?mac=&access_token=

Notify(sse)

http://AC address/gatt/nodes/?event=1&mac=&access_token=

Pair(post)(此接口为新增)

http://192.168.199.218/management/nodes/<node>/pair?&access_token=

        post请求的data: ({
            "bond": 1,
            "legacy-oob":  0,
            "io-capability": 'KeyboardDisplay'
        })

**注：若此设备不支持配对，则http请求会返回失败

Pair-input(post)(此接口为新增)

http://192.168.199.218/management/nodes/<node>/pair-input?&access_token=

        post请求的data: ({
            "passkey": passkey //passkey为配对码
        })
Unpair(delete)(此接口为新增)

http://192.168.199.218/management/nodes/<node>/bond?&access_token=

        以上为常用API接口，供开发使用，有专门的的API接口文档，蓝牙调试工具所有功能都是通过API接口实现的。
以连接接口为例（js语言）：
Alt text

以扫描的sse接口为例（js语言）：
Alt text

以上云端使用调用接口时均需要加入token，进行验证

6.2 API支持哪些开发语言？

        任何基于HTTP通信协议的编程语言都支持（例如C＃，Node.js，Java，iOS等）。
对于C＃、Node.js、Java、iOS，我们提供了oAuth认证及sse的sampleCode。
https://github.com/CassiaNetworks/CassiaHubSDKSamples/tree/master/samples

6.3 SSE（Server-sent Events）是什么?该如何实现？API中有哪些接口使用SSE？

        server-sent events，简称：see。是一种http的长链接，请求需要手动关闭，否则理论上在不报错的情况下会一直进行，每条数据会以“data: ” 开头。在调试中可以直接将sse的url输入在浏览器中进行调用。但是在编程中使用一般的http请求无法请求到数据(一般的http请求都是在请求结束后返回所有的数据)，我们目前提供了iOS/java/nodejs/js/c#等的demo来实现sse的调用，如果在这方面遇到困难可以参考。另外，当调用sse时，最好对该长链接进行监控，以便在长链接出现错误或意外停止后进行重启，或者其他操作。
API中的SCAN、Get device connection state、Receive indication & notification 三个接口使用的是SSE

6.4 怎么通过API进行oAuth认证？

1）http的post请求进行oAuth认证(可在postman中进行)：

        例如你的用户名：tester 密码：10b83f9a2e823c47

①将 tester:10b83f9a2e823c47进行base64编码得到 dgvzdgvyojewyjgzzjlhmmu4mjnjndc= 使用下面的HTTP请求进行身份验证：
 POST  /oauth2/token  HTTP/1.1
   Host: AC地址 /oauth2/token
   Headers: 
   {
     Authorization:Basic dGVzdGVyOjEwYjgzZjlhMmU4MjNjNDc=,
     Content-Type:application/x-www-form-urlencoded
    }
 Body: {grant_type=client_credentials}
②如果没有错，你会得到这样的JSON响应:
    HTTP/1.1 200 OK
    Content-Type: application/json;charset=UTF-8,
    Cache-Control: no-store,
    Pragma: no-cache
    {
    token_type:’bearer’,    
    access_token:"2b6ced831413685ec33204abc2a9a476310a852f53a763b72c854fd7708499f1bc0b3626bfcfef2a2cfe0519356c9d7cb1b514243cb29f60e76b92d4a64ea8bd"
     expires_in: 3600
    }

现在你可以使用access_token访问其他API，添加access_token URL参数：
例：
Alt text
Alt text

6.5 拿到token后怎么使用？

        拿到access_token后访问其他API，例：scan接口
http://AC地址/gap/nodes/?event=1&mac=xxx&access_token=xxxx
        或者你可以在接口中添加Headers “Authorization:Bearer XXXX”

6.6 oAuth认证得到的token有效期是多长久?

        Token的有效期为1小时
        在上一个token有效期内再次申请token，这两个token都有效

6.7 token只与AC与开发者账号有关

        Token只与开发者账号有关，与AP的MAC无关，100个AP如果有相同的开发者账号，那只需要1个小时重新获取一次token

6.8 怎么调用API中的SSE接口？（以扫描为例）

        在浏览器地址栏中输入：
http://AC地址/gap/nodes/?event=1&mac=&access_token=xxx

6.9 API中url的参数是什么意思？该如何填写？

        mac=:当前AP的mac地址(例如：CC:1B:E0:E0:24:B4)
        node=:需要对接的设备的mac地址(例如：EF:F3:CF:F0:8B:81)
        handle=:对应操作的索引值(发现设备服务后，根据设备蓝牙协议中的UUID找到对应的handle)
        value=:想对应handle中写入的值(根据蓝牙协议，写入操作的对应命令)
在此，以开源蓝牙协议为例：

(Alt text)
Alt text