CC2541-QQ 物联接入 规格书 SDK 版本 V1.0 2016 年 4 月 26 日 版权所有
1.概述... 3 2.应用... 3 2.1 空气净化器... 3 3.QQ 物联接入步骤 参考自 QQ 物联平台上的相关文档... 4 3.1 开发前的准备工作... 4 3.1.1 申请开发者账号... 4 3.1.2 申请白名单... 5 3.1.3 进入配置平台... 5 3.1.4 添加新设备... 5 3.1.5 设置控制器... 10 3.1.6 提交审核... 10 3.2 配置蓝牙广播和服务... 11 3.3 下载硬件 SDK... 12 3.4 第一行代码... 13 3.5 配置初始化数据... 14 3.6 实现 fh_*中的函数... 17 3.7 调用 fd_engine.h 中的函数...20 4. 关于 QQ 物联设备量产的操作方法...23 4.1 用于调试的操作方法的局限性介绍... 23 4.2 量产时的操作方法介绍... 23 5.版本说明与修订记录... 24
概述 1.概述 概述 QQ 物联平台将 QQ 账号体系及关系链 QQ 消息通道能力等核心能力 提供给可穿戴设备 智能家居 智能车载 传统硬件等领域合作伙伴 实现用户与设备及设备与设备之间的互联 互通互动 充分利用和发挥腾讯 QQ 的亿万手机客户端及云服务的优势 更大范围帮助传统 行业实现互联网化 CC2541 是一款针对低能耗以及私有 2.4GHz 应用的功率优化的真正片载系统(SoC)解决方 案 CC2541 非常适合应用于需要超低能耗的系统 非常适合用来开发可穿戴设备 智能家 居 智能车载 传统硬件等 因此 CC2541+QQ 物联的开发方案就显得很有价值了 2.应用 QQ 物联平台可以将所有符合协议的蓝牙设备接入到平台上 同时 QQ 平台还支持为设备 定制控制界面 开发者只需要自己用 html5 制作好想要的控制界面 然后在 QQ 平台上将该 网址绑定到我们的设备上就可以使用该网页对我们的蓝牙设备进行控制或者接收设备的信 息了 2.1 空气净化器 我司现有支持 QQ 物联的设备是一款空气净化器 用户通过手机 QQ 扫描设备对应的二维 码后就可以绑定该设备 界面如图一所示 绑定之后进入设备 界面如图二所示 从图三中 我们可以看出 通过这个网页 APP 我们可以轻松的控制净化器的开启和关闭 同时还可以 为净化器设置定时开关 非常便捷 实用 图四是净化器工作时的效果图
图一 图二 图三 图四 3.QQ 物联接入步骤 参考自 QQ 物联平台上的相关文档 说明 本节内容所述的方法适用于开发调试时使用 量产时的操作方法有些许不同 关于 量产的介绍在第四节有详细说明 建议先看完本节的内容后再去看第四节 图A 接入流程图 3.1 开发前的准备工作 3.1.1 申请开发者账号 进入腾讯开放平台官网 用一个 QQ 号 申请 公司 身份的开发者帐号 最好是用司公 用的 QQ 号来申请 以防人事变动造成不必要的麻烦 如图 B 所示
图B 3.1.2 申请白名单 在 QQ 物联公测申请页中填写并提交相应的内容 来获得 QQ 物联的公测资格 如图 C 所示 图C 3.1.3 进入配置平台 白名单开启后 便可以登入 QQ 物联配置平台 进入平台后就可以添加 配置新的设备了 3.1.4 添加新设备 进入 配置平台 - 设备 之后 点击添加设备按钮 填写 设备名称 及选择 设备类 型 后即可开始快速注册一个新设备 完成后 我们已经获得了该产品的重要信息 pid 和 server key 这两个信息非常重要 会在后面的 Step3.5 中用到 在设备导航栏中 选择进入相应的设备 即可在头部看到 如 图 D 建议 可以把与设备相关的一些文件或者信息(包括这里的 pid 和 server key 和后面的 ec_key.pem public.pem 已及 SN 等)保存到一个文件夹里 方便后面的使用
图D 按照自己的需求补全设备的基本信息 如图 E 图 F 图E
图F 设备型号 可以自由填写 设备名称请尽量用中文并控制长度 因为这些字符会出现在手机 QQ 的界面里 是用户可以直接看到的 设备类型 必须填写准确 后期无法进行修改 这里我们选择设备类型为空气净化器 操作系统 这里我们选择 其它 连接方式 我们选择 蓝牙 初始化方式 决定了设备的入网方式以及跟手机 QQ 的绑定方式 所以这个选项很重要 这 里选择蓝牙, 这里只支持 4.0 以上 即低功耗蓝牙 不支持经典蓝牙 公钥上传 稍微复杂一点 因为需要下载一个工具来完成这个步骤 点击网页上的公钥& 证书工具下载 Win 7 Only 链接 如图 F 所示的 公钥上传 处即可下载 然后运行密 钥生成工具 点击下图 G 中的生成 KEY 按钮 会在指定的目录下生成一对非对称密钥文件 ec_key.pem 和 public.pem 之后点击上传按钮上传 public.pem 就可以了 如图 G 所示
图G 说明 以后的环节中会反复用到 ec_key.pem 所以一定要妥善保管这个文件 接下来还需要上传一个设备激活登记表 如图 H 所示 图H 可以点击图 H 中箭头所指的位置查看说明
这个登记表需要我们自己制作 制作方法如下 1 新建一个 excel 文件 2 在文件的第一行第一列位置输入 SN(serial number 序列号) 第一行第二列位置输 入设备的 MAC 地址 如图 I 所示 3 添加完成之后 将文件另存为 csv 格式 图I 说明 1 上面第二步中用到的 SN 需要用工具软件生成 如图 J 所示 使用的工具是前面下 载的公钥&证书工具 Win 7 Only 图J 只需按照图中的 1 2 3 步分别点击操作即可获得 SN
说明 2 不能直接将 excel 文件的后缀名改成 csv 而应该用另存为的方法 制作好登记表后就可以上传了 后面如果需要增加设备的数量 也是在这里把新的 MAC 地址和对应的 SN 进行登记 只有在这里登记了 我们的设备才允许接入 QQ 物联平台 上传之后记得点击页面下方的保存按钮 3.1.5 设置控制器 功能添加完成之后 切换到控制器设置页签 填写控制器相关的信息 可以采用 QQ 物联 开发的公用模版控制器或者自己设计的 Html 5 控制器 控制器为用户实际用来操控设备的 轻 APP 如图 K 所示 图K 3.1.6 提交审核 配置平台允许在不提交审核之前以及审核中拥有 100 个 DIN 用于测试 也就是说在批量生产 调试之前可以按需更改配置即时生效 从右上角的提示可以看到当前设备所在的状态 同时获知您现在所使用的 DIN 数量 如图 L 所示
图L 当确认功能调试完毕时 请查看审核须知 并在再三确认调试完毕后点提交审核.请注意提 交审核到审核通过期间将无法修改所有的功能及触发器信息 所以只有当确定调试完成后方 可重新提交审核 到 3.1.5 步为止 我们已经完成了一个新设备的新建 下面开始进行蓝牙设备的配置环节 3.2 配置蓝牙广播和服务 蓝牙设备在未被 App 连接到之前 需要一直发广播 广播中至少包含 ServiceUUID 和 manufature specific data 内容里的字节序采用小端序(Little Endian) QQ 物联的蓝牙广播和 Service 标准如下 名称 manufature specific data ServiceUUID Write Characteristics UUID Indicate Characteristics UUID Read Characteristics UUID 值 以 PID(4 字节) + MAC(6 字节)结尾 0xFEBA 0000fec7-feba-f1f1-99c0-7e0ce07d0c03 0000fec8-feba-f1f1-99c0-7e0ce07d0c03 0000fec9-feba-f1f1-99c0-7e0ce07d0c03 作用 Device 发广播时标识设备 标识 QQ 物联 App 向 Device 传输数据(需要 response) Device 向 App 传输数据(需要 confirm) Device 不发广播时标识设备 ServiceUUID 和 Characteristic 的值是固定的 按照格式填写即可 manufature specific data 的计算如下 比如某设备 PID=1000000358(0x3B9ACB66) MAC 地址=44:A6:E5:0E:B1:05 则 MSD 数据如下: 自定义数据 / 00 0D... /Company id\ \ 66 CB 9A 3B PID(小端序) 05 B1 0E E5 A6 44 MAC 地址(小端序) 广播数据结构示意图 Read Characteristics 里的内容跟广播 manufature specific data 的数据要求一致 注意 UUID 为 128bit 类型 数据传输为 Indicate 方式 以上面的空气净化器为例 用 LigthBlue 查看设备信息如图一所示
图一 3.3 下载硬件 SDK 硬件 SDK 的下载地址为 http://iot.open.qq.com/wiki/index.html#!sdk/ble.md 此文档是以 V1.0 的 SDK 为基础进行说明的 若后面 SDK 有更新 请以新的说明为准 压缩包中包含静态库文件以及相应的头文件 关于 SDK 压缩包的说明 文件名 ff_syshdr.h ff_inc.h fd_engine.h txble.lib/a 作用 系统头文件定义 它可以根据编译环境 配置是否使用某些基础库 通用数据结构及枚举值的定义 SDK 的接口定义 静态库文件 SDK 的具体实现
3.4 第一行代码 把刚下载的 SDK 加入到工程中 如图二所示 图二 在工程的初始化函数里调用 SDK 初始化函数 如图三所示 图三
关于 fh 和 fd 的说明 在 fd_engine.h 里定义了两类函数 一类是以 fd 开头 由 SDK 实现 被上层调用 一类是以 fh 开头 由开发者实现 供 SDK 调用 3.5 配置初始化数据 初始数据每个设备都不相同 宏定义于 fh_impl.h 文件中 如图四所示 图四 1) PID 与服务器公钥的获取 登录 QQ 物联平台 找到相应的设备即可得到 PID 与服务器公钥 如图五所示 图五 其中 服务器公钥需要下载到本地 只需点击图中蓝色字体位置即可下载 2) PUK 设备公钥 和 AUTH KEY 设备共享密钥 将上面下载的服务器公钥文件用文本的方式打开 复制其中的所有内容 打开我们前面下载 的工具 将刚才复制的服务器公钥文件里的内容粘贴到 生成共享密钥 栏,然后点击 生 成 按钮 如图六所示
图六 根据服务器公钥 每一个设备都可以生成一对设备密钥 注意 测试时同一类产品可以共用一对设备密钥 但量产时 需要为每一个设备生成一对 唯一的密钥 将 QQ 物联提供的 C++源代码 集成到自己的烧录工具中 可为每一个设备自 动生成一对密钥 并写入 flash 3) licence(认证签名) 使用图七所示的工具 首先指定上面生成的 ec_key.pem 文件所在目录 然后点击 导 入 csv 导入前面我们制作的 csv 文件 然后在其下的输入框中输入 CSV 文件中的 MAC 地 址 如有多组 MAC 地址 需用逗号分隔开 如图七所示
图七 说明 1 箭头 1 所指为 ec_key.pem 文件所在目录 说明 2 生成的 licence.csv 文件的内容是一串十六进制的数据 我们需要将这些数据处理 一下才能放到代码里 也就是在每个数据前加上 0x 在每个数据之间加上, 我们 可以借助一些具有列编辑功能的文档编辑工具如 UltraEdit 来进行这些操作 如图八所示 图八 首先复制 licence 文件里的内容 打开编辑工具 粘贴我们复制的内容 然后点击箭头 1 所指的列选项 在其下拉列表里选择 列模式 用鼠标选中数据的一列 输入需要的内 容即可 操作完了之后需要再次点击箭头 1 处 选择 列模式 表示退出列模式 之后就 可以复制我们的处理好的数据了
得到这些数据之后对应替换图四中的内容 在 SDK 中有专门的一个数据类型用于存储这些数 据 如下 typedef struct _QQ_SEC_INFO { uint8_t license[ft_max_license_len]; uint16_t licenselen; uint8_t din[din_len]; uint32_t pid; uint8_t authkey[auth_key_len]; uint8_t pukstr[puk_str_buffer_len]; }QQSecInfo; 3.6 实现 fh_*中的函数 fd_engine.h 中有部分函数是交给开发者实现的 这部分函数都是以 fh 开头 int8_t fh_send(uint8_t* datum,uint16_t length); 这个函数是 SDK 在发送数据时调用的 这个函数只是一个接口 功能就是发送数据 需 要开发者用自己的方式实现这个发送数据的功能 如图九 开发者在发送完一包数据后 需要调用 void fd_flush(struct fd_engine_s engine); 来告知 SDK 否则 SDK 不会继续发送数据如图十一 另外 SDK 会传入需要发送的全部数据 由开发者负责分帧 void fh_load_mac(uint8_t* zone); 返回设备的 mac 地址 比如我们这台设备(mac 地址 44:A6:E5:0E:B1:05 )返回的是 "44A6E50EB105" 注意顺序和大小写 fd_save_din/fd_load_din 需要用到 NVRAM 或 Flash 这个 bin 与设备的连接有关 如果没有处理好则会导致设备 在第一次绑定连接之后再次连接时无法连接 需重新扫描才能再次连接(正常的情况是在设 备正常工作的情况下 再次连接时只需在手机 QQ 上直接点击该设备图标) fh_data_load/fh_data_store 这两个函数主要用于存储于 QQ 物联有关的数据 如图十二所示 其它方法根据需要自行实现或留空
图九 图中的实现方法是将收到的数据存储到缓冲区中 然后置起专门的数据发送事件来发送 这些数据 INDECA_EVT 事件里主要处理的就是数据的分包和发送 如图十所示 图十 上图是整个任务处理函数的结构 关于 INDECA_EVT 事件的具体处理如图十一所示
图十一 上图中 Periphral_Indicate()函数是调用库函数实现的以 indicate 方式上传数据的函数 整个过程的处理就是先判断需要发送的数据包的长度 若长度超过 20 字节(蓝牙每次最多发 送 20 字节)则做分包处理 即本次数据以最大长度(20 字节)发送 发送之后将数据包的长 度减少 20 同时索引号增加 20 之后就给这个事件设置一个定时 也就是等待一段时间后 再次来这个事件里接着上次的位置继续发送数据 直至全部发送为止 图十二 上图的操作是直接把 qqsecurityinfo 存储到指定 flash 区域
3.7 调用 fd_engine.h 中的函数 实现了 fd_engine.h 中的函数后 工程就可以编译通过 但是要让 SDK 正常运行 还需 要按顺序调用下面方法 设备连接/断开时 调用 fd_connect/fd_disconnet 如图十二所示 在接收数据的地方 调用 int8_t fd_received(struct fd_engine_s* engine, uint8_t* datum,uint16_t length);将收到的数据传给 SDK 这里上层业务从 QQ 物联定义的 Write 特 征值里收到数据 立即调用此函数 不需要累积数据包 而由 SDK 组包 如图十三所示 图十三
图十四 至此 代码部分的修改已经完成 接下来还有一个很重要的内容 那就是生成设备的二维码 蓝牙设备目前只支持通过扫 描设备二维码的方式绑定 连接设备 二维码的生成步骤如下; 1) 去网上任意搜索一个二维码生成工具 比如 http://cli.im/text?5bfc12ac983fae4719e32ad7f440b58c 2) 在输入栏输入如下内容(是一个网址,直接复制 而不是打开这个网址): http://iot.qq.com/add?pid=<>&sn=<> 3) 将设备对应的 PID 和 SN 填写到相应的位置 如图十四
图十五 注意 替换的时候需要连同尖括号一起替换掉 生成二维码之后就可以下载到本地保存了 将前面修改好的程序烧写到我们的设备之后 用手机 QQ 扫描二维码即可绑定 连接我们 的设备 如图十五 图十六 图十六 图十七
注意 QQ 物联对手机 QQ 的版本也有要求 Android QQ 要求 5.5 版本以上 iphone QQ 要 求 5.7 版本以上 在扫描二维码之前请先检查手机 QQ 的版本是否符合要求 至此 一个可用于调试的 QQ 物联设备已经完成 接下来介绍关于 QQ 物联设备量产的内容 注意 以上的所有操作方法都是针对只用于调试的设备的 量产时 这些步骤又有所不同 具体的内容请参照下面的内容 4. 关于 QQ 物联设备量产的操作方法 4.1 用于调试的操作方法的局限性介绍 从 Step3 中我们了解到 每一个蓝牙设备 我们都需要为其生成对应的 FT_DEFAULT_PUK FT_DEFAULT_AUTH_KEY licence 二维码等 操作十分繁琐 效率非常低 不适用于量产 4.2 量产时的操作方法介绍 首先我们来列举一下我们需要得到的数据以及其来源 服务器公钥 同一类设备(比如空气净化器)共用一个服务器公钥 从 QQ 平台获取; PID : 同一类设备(比如空气净化器)共用一个 PID 从 QQ 平台获取; SN : 通过工具批量生成 设备公钥(PUK) : 服务器公钥 + 工具 量产时要求每一个设备的 PUK 不同 设备共享密钥(AUTH KEY): 服务器公钥 + 工具 量产时要求每一个设备的 AUTH KEY 不同 (同一个 服务器公钥 每次生成出来的 PUK 和 AUTH KEY 都不同) 设备登记表 SN + MAC Licence MAC + 设备登记表 + 工具 二维码 PID + SN + 工具 从上面的总结可以看出对于同一类设备来说 有些信息是固定的 而有些信息各不相同 可行的做法如下 1) 2) 3) 4) 在代码中把已知的数据填写进去 比如 PID 其他的留空 如 licence 等 在代码中制作一个数据接口 用于接收在第一步中留空的数据 使用工具批量生成 SN 使用工具批量生成二维码(PID + SN + 工具)
5) 将生成的二维码和我们的设备随机组合(物理上的组合 也就是放到一起) 6) 将第五步中组合好的设备一个一个通过我们的量产工具 7) 量产工具扫描设备得到 MAC 地址 扫描和设备组合的二维码 得到对应的 SN 8) 量产工具在得到 SN 和 MAC 后生成一个 csv 文件 9) 量产工具在生成 csv 文件后再生成该设备对应的 licence 10) 量产工具通过输入的服务器公钥生成 PUK 和 AUTH KEY 11) 量产工具将生成的 licence 通过第二步中预留的数据接口把 licence 写入到设备中 12) 量产工具将 PUK 和 AUTH KEY 通过第二步中预留的数据接口把数据写入到设备中 13) 量产工具处理完所有设备后 输出一个总的 csv 文件 用于 QQ 物联平台登记注册 也就是说 在编写底层代码的时候 我们可以先把那些确定的信息写入到代码里 那些 不确定的信息到后面的量产处理时再生成 写入 这样就避免了为每一个设备编写一版程序 的操作 也就是说如果用上面的方法 我们就可以编写出一套针对一类设备的通用代码了 上面流程中的一个关键点就是这个量产工具 这个工具需要自己开发 开发方法可以参 照 3.5.2 点的注意事项 QQ 物联平台有提供相关的开源包 开发者需要将该源码包集成到 量产工具里 源码包中包含了 licence 等数据的生成方法 说明 上面步骤中 设备在收到数据接口发过来的数据后就会将数据保存到非易失性存储 器(flash)里,成功收到数据后会有相应的回应 以供量产工具进行判断 5.版本说明与修订记录 Software Version: Hardware Version: IDE: Diver Version: BLE-STACK V4.0 HY-254101 V1 模组 (深圳昇润科技 www.tuner168.com) IAR 8.30.3 for 8051 V1.0 修订记录 日期 修订 版本 修订说明 2016/4/28 0 V1.0 首次发布