谷雨云透传平台接入指南
谷雨物联网的使命是让联网通信更简单，正因为这个使命，我们开发了【谷雨云透传平台】，面向广大开发者免费提供。
开发云透传还有一些重要原因：
- 降低NB-IOT的学习门槛。电信NB有定向IP访问限制，要求设备必须接入电信平台。
- 提供一款好用的免费的远程网络调试助手。并提供简单透传功能。
目录
1 适用群体
谷雨云透传平台的定位是：测试设备的远程联网需求，网络测试。例如，使用NB-IOT技术，快速实现家庭烟雾报警的功能演示；或者远程温湿度监控等等。
因此我们的云透传平台的适用群体为：
- 学生
- 极客
- 开发者（处于学习或者Demo调研演示阶段）
当前版本虽然2.0，但定位仍然为测试，量产产品建议接入华为、电信或阿里云IOT等企业级云平台，更有安全性和稳定性的保障。
2 功能框图
NB-IOT终端接入谷雨云透传的功能框图如下图所示：
非NB-IOT终端设备接入谷雨云透传的功能框图下图所示：
3 平台能力
谷雨云透传平台具有下面几大能力：
- 支持本地UDP/TCP协议接入。设备直连谷雨云透传。
- 支持电信/华为平台对接（LwM2M或CoAP协议）。设备直连华为/电信平台，消息路由到谷雨云透传。
- 支持上述设备之间的数据透传能力。支持任意两个网络设备之间的数据透传。
- 在线Web可视化管理。
4 平台限制
使用UDP或者TCP直连设备时，上传的最大数据长度为512字节，超过此长度，消息将被丢弃。
5 设备接口
直连设备采用最简单、最原始的Socket连接（具有网络通信能力的设备采用UDP或者TCP协议，作为客户端的身份连接谷雨云透传）。
电信、华为平台设备采用LwM2M或CoAP协议。
| 类型 | 域名或IP地址 | 端口号 |
|---|---|---|
| 直连设备（UDP协议） | 115.29.240.46 | 6000 |
| 直连设备（TCP协议） | 115.29.240.46 | 9000 |
| 电信平台设备（LwM2M或CoAP协议） | 117.60.157.137 | 5683 |
 |
注意，由于电信NB网络有定向IP访问限制，使用电信NB网络的用户需要使用电信平台对接的方式接入。对于没有访问限制的移动NB网络，或者其他网络，可以使用设备直连UDP/TCP协议接入。 |
6 管理接口
管理接口使用Web可视化管理，开发者通过浏览器登录谷雨云透传，创建、测试等管理。
支持的浏览器有：谷歌Chrome，火狐FireFox，Safari。
不支持微软的IE浏览器或基于IE内核的其他浏览器。（创建设备后，若设备状态一直处于加载状态，则表示该浏览器不支持）
| 类型 | 域名或IP地址 | 端口号 |
|---|---|---|
| Web管理接口 | https://cloud.iotxx.com | 443 |
7 注册包机制
平台为了鉴别接入设备的合法性，需要额外的一些信息或数据包来辅助判断。该信息或数据包，需要在平台上预先配置，因此设备接入平台之前，必须要在平台上先创建设备。
7.1 直连设备
我们知道，Socket采用服务器/客户端的机制通信，客户端只要知道服务器的IP地址和端口号，就可以建立链接。
因此，在设备作为客户端的身份接入谷雨云透传，谷雨云透传为了识别客户端设备的合法性，使用了一种注册包机制，即每次建立链接后，首先需要发送一包数据，这包数据需要按照我们规定的格式来发送。平台通过该数据包的内容来识别设备，我们称之为注册包。
注册包格式为：ep=deviceId&pw=devicePw
deviceId（设备编号）和devicePw（设备密码）是两个变量。由云平台自动分配或客户自定义。
7.2 电信平台设备
电信平台采用验证模块IMEI码的方式，创建电信平台设备时，设备编号必须使用NB模块的IMEI码，否则无法通信。
8 在线调试
在线调试是一项非常实用的功能，可以实现远程网络调试助手功能。
该功能给那些必须要固定IP才能通信的设备的用户带来了极大的方便，不再需要费时费力开发服务器端的网络程序。
9 分组透传
上一节中的在线调试功能很实用，但设备数据只能在网页中收发，如果有一个功能，可以将这些数据再转发到开发者的电脑上或指定设备中，那再好不过。
基于这个需求，我们设计了分组透传的功能。
开发者可以将需要数据透传的设备添加到透传分组中，这样同一个透传分组中的设备就可以实现相互透传。
对平台来说，透传分组中的所有设备，逻辑上都是对等的，也就是说，相互透传的设备可以是两个NB模块，也可以两个WiFi模块，当然也可以是NB模块与WiFi模块之间，或NB模块与电脑之间透传。
例如，在平台上创建两个设备，一个用于NB模块的接入，另外一个用于电脑上的Socket客服端程序（可以使用网络调试助手）接入。然后将两个设备添加同一个透传分组中，这样，NB模块和电脑上的Socket客户端程序即可相互收发数据。
我们支持以下三种分组透传策略：
- 点对点，我们称作单聊模式，只有两个设备参与透传。
- 点对多点，称作集散模式，多设备透传，且需要指定一个主设备，其他设备作为从设备。主设备发送的数据，每个从设备都能收到，而从设备发送的数据，只能被主设备收到。
- 多点对多点，该模式类似一个聊天群组，群组内的所有设备均对等，所有设备都能接收到其他设备发送的消息。
10 账号注册
谷雨云透传平台向广大学习者免费提供服务，使用前需注册账号。
浏览器中输入网址：http://id.iotxx.com/register ,注册谷雨云平台账号，如下图所示。
注册成功后，访问网址：https://cloud.iotxx.com/dashboard ,进入控制台，控制台显示当前的设备概况，新闻通知等内容。
控制台左侧菜单有如下分类：
- 谷雨直连，管理和创建直连谷雨云透传平台的设备，该菜单下的设备使用UDP或TCP协议接入。
- 电信平台，管理和创建接入电信平台的设备，该菜单下的设备使用LwM2M或CoAP协议接入。
- 透传分组，管理和创建透传分组。
无论是谷雨直连的设备，还是电信平台的设备，均可以通过透传分组来实现设备间的数据透传。
11 谷雨直连设备演示
谷雨直连是指设备采用Socket UDP/TCP协议直接接入谷雨云平台，设备消息不经过第三方服务器转发。
11.1 创建设备
在控制台左侧菜单中单击【谷雨直连】，然后打开【创建设备】页面，如下图所示。
- 设备编号：一组15~16位的随机字符串，可以使用平台自动生成的编号，也可以用户自定义。设备接入时需要上报包含此编号的注册包。
- 通信密码：长度为6的数字字符串，作为设备通信密码。设备接入时需要上报包含此密码的注册包。
- 设备名称：给设备起个可读的名字，方便区分不同设备。
- 过期时间：已弃用，固定为0秒。
- 设备描述：可选，可以给设备添加详细的描述。
- 地理位置：可选，可以给设备添加一个地理位置。
由于真实设备还未接入，此时的设备在线状态为离线，如下图所示。
11.2 一般网络设备接入
为了方便演示，我们在电脑上使用Socket网络调试助手来接入平台。
11.2.1 创建Socket客户端
使用网络调试助手，创建udp或tcp协议客户端来连接谷雨云透传。
根据以下表格的接入地址和端口填写。
| 类型 | IP地址 | 端口号 |
|---|---|---|
| 直连设备（UDP协议） | 115.29.240.46 | 6000 |
| 直连设备（TCP协议） | 115.29.240.46 | 9000 |
点击确认，准备发送注册包，UDP协议不需要连接，可直接发送数据，而TCP协议需要先连接，然后才能发送数据。
11.2.2 发送注册包
设备连接平台后，首先需要上报注册包，用于身份识别，然后才能数据通信。注册包的格式为：ep=deviceId&pw=devicePw，将deviceId和devicePw替换成当前已创建的设备编号和密码。
大家可以进入在线调试页面，在线调试页面的右下角自动生成注册包，可直接复制。
11.3 NB设备接入
本节描述NB模块的接入步骤，注意事项如下：
- 先创建直连设备，建议选择自动生成的设备编码创建设备。
- 步骤中仅描述通信相关的指令，关于指令的详细用法，请阅读各模块的软件设计手册。
- 直连设备采用UDP协议接入。强烈建议使用我们提供的NBTool上位机软件连接NB模块完成设备接入测试，全程可视化图形操作。
- 由于NB卡默认均为PSM模式，20s未通信，平台将无法下发数据。另外使用电信NB卡的用户可能无法与我们的云透传通信（定向访问的白名单限制）。
- 若步骤执行错误，请先熟读各模块的软件设计手册和本手册，并且详细阅读本文附录中的常见问题。
11.3.1 BC95/BC28/BC35接入实例
直连设备使用UDP协议接入，BC28还支持TCP协议接入。
接入流程：
- 初始化NB模块并附着网络，等待网络附着成功。
- 创建UDP客户端，发送指令：
AT+NSOCR=DGRAM,17,3000,1，记录返回的socket Id。 - 向平台发送注册包，在谷雨云透传的设备数据调试页面右下角可以看到已经编码的注册包。发送指令：
AT+NSOST=id,115.29.240.46,6000,29,65703d5453585641334c34423643354e5247372670773d313233343536，注意：务必将指令中的id替换为步骤2中的socketId，以及最后data字段的注册包替换为实际创建的设备注册包。 - 此时，云透传平台上可以到设备已变为在线状态（可能有几秒的延时），可收发数据。
11.3.2 BC26/BC20接入实例
直连设备使用UDP协议接入，BC26和BC20还支持TCP协议接入。
接入流程：
- 初始化NB模块并附着网络，等待网络附着成功。
- 创建UDP客户端并指定平台地址和端口，发送指令：
AT+QIOPEN=1,0,"UDP","115.29.240.46",6000,3001,1，记录返回的conenct Id。 - 向平台发送注册包，在谷雨云透传的设备数据调试页面右下角可以看到注册包。发送指令：
AT+QISEND=id,29,"ep=TSXVA3L4B6C5NRG7&pw=123456"，注意：务必将指令中的id替换为步骤2中的connect Id，以及最后data字段的注册包替换为实际创建的设备注册包。 - 此时，云透传平台上可以到设备已变为在线状态（可能有几秒的延时），可收发数据。
11.4 在线调试
在设备列表中点击在线调试按钮（小齿轮图标），进入相应设备的在线数据调试页面，此时设备已上线，可以发送数据到网页端显示，网页上的数据也可以发送到电脑上显示。
12 电信平台设备演示
电信平台设备是指设备通过谷雨云透传接入电信平台。
电信NB-IOT云平台是面向企业商用的统一开发平台，具有NB-IOT设备接入及管理、数据采集管理以及分析、各种各种终端适配及扩展等功能。电信NB-IOT云平台提供两种接口。
- 南向接口：向下提供的接口，用来设备接入。
- 北向接口：向上提供接口，提供给企业管理设备，收发设备数据的接口。北向接口对应企业的应用服务器。企业的应用服务器向终端客户提供具体的商业逻辑。
此时，谷雨云透传的角色是电信云平台的北向应用：应用服务器，电信平云台类似桥梁的作用，连接设备与谷雨云透传。
对接电信平台的原因：
- 电信平台需要企业身份申请，初学者可通过我们的云透传快速体验电信平台的优点。
- 电信NB网络有定向IP限制，不允许直连私有服务器。
因此，建议走电信网络的NB-IOT设备，全部采用这种方式接入，避免直连私有服务器，包括我们的谷雨云透传。
12.1 创建设备
在控制台左侧菜单中单击【电信平台】，然后打开【创建设备】页面，如下图所示，与创建直连设备很相似。
- IMEI编号： IMEI编号是指NB模块的IMEI码，电信平台要求使用模块的IMEI码来创建设备。因此，必须如实填写模块的IMEI码，否则无法通信。
- 设备名称：给设备起个可读的名字，方便区分不同设备。
- 设备描述：可选，可以给设备添加详细的描述。
- 地理位置：可选，可以给设备添加一个地理位置。
已创建的设备，可以在设备列表中找到，如下图所示，界面与直连设备基本相同。
|
注意，创建设备使用IMEI码，IMEI是国际移动设备识别码International Mobile Equipment Identity的缩写，是以86（国内模块）开头的一组数字字符串。请勿和卡的IMSI码混淆，国内卡的IMSI码是以460开头的一组数字字符串。 |
12.2 NB设备接入
本节描述NB模块的接入步骤，注意事项如下：
- 务必先用NB模块的IMEI码创建电信平台设备。IMEI码是以86开头的一串数字。
- 步骤中仅描述通信相关的指令，关于指令的详细用法，请阅读各模块的软件设计手册。
- 电信平台接入采用CoAP或LwM2M协议，强烈建议使用我们提供的NBTool上位机软件连接NB模块完成设备接入测试，全程可视化图形操作。
- 若步骤执行错误，请先熟读各模块的软件设计手册和本手册，并且详细阅读本文附录中的常见问题。
12.2.1 BC95/BC28/BC35接入实例
BC95使用CoAP协议接入，与BC95用法相同的还有BC35和BC28。
接入流程：
- 初始化NB模块并附着网络。具体指令请参考各自模块的软件指令手册。
- 设置CDP服务器和端口，发送指令：
AT+NCDP=117.60.157.137,5683，117.60.157.137是电信平台（商用版）的南向接入地址，5683是协议端口。 - 第一次设置CDP参数后建议重启，发送指令：
AT+NRB。 - 重启后，模块再次附着到网络，会自动执行平台设备绑定，如果绑定成功，串口首先上报异步消息：
+QLWEVTIND:0，0：表示注册完成；然后随即再次上报状态：+QLWEVTIND:3，3：表示注册已更新。 - 此时，NB模块已成功接入，在我们的云透传上，可以看到在线状态已变为在线（可能会有几秒的延时）。假如第4步的现象没有出现，可以调用发送数据指令来完成设备绑定。发送指令：
AT+NMGS=3,313232，指令意思是发送3个字节的数据，数据内容是字符串：123 - 若模块返回：
+NSMI:SENT表示数据已发送，也意味着设备绑定成功。若返回513错误，请检查注册设备用的设备编号是否与模块IMEI码一致，发送指令：AT+CGSN=1来查询模块IMEI码。
12.2.2 BC26/BC20接入实例
BC26使用LwM2M协议接入，相对BC95的CoAP协议，设置的内容较多。下面是详细的流程。
接入流程：
- 初始化NB模块并附着网络。具体指令请参考各自模块的软件指令手册。
- 设置平台设备接入地址和端口，发送指令：
AT+QLWSERV="117.60.157.137",5683，117.60.157.137是电信平台（商用版）的南向接入地址，5683是协议端口。 - 设置EndPoint，先获取模块IMEI码，发送指令：
AT+CGSN=1，然后用返回的IMEI码来设置endPoint，发送指令：AT+QLWCONF="866971030245736"，注：根据实际情况替换IMEI码。 - 配置LwM2M Object，先发送指令：
AT+QLWADDOBJ=19,0,1,"0"，再发送指令：AT+QLWADDOBJ=19,1,1,"0" - 向平台发送注册请求和更新请求，先发送指令：
AT+QLWOPEN=0，再发送指令：AT+QLWUPDATE，此时NB模块已成功接入到平台，在谷雨云透传上，可以看到状态已变为在线。 - 设置数据收发格式，发送指令：
AT+QLWCFG="dataformat",1,1，意思是设置16进制格式的数据收发，与BC95一致。 - 发送任意数据，发送指令：
AT+QLWDATASEND=19,0,0,3,313233,0x0000，意思是向平台发送字符串123，此刻可以在平台上看到数据发送端数据。
12.2.3 SIM7020C接入
待更新。
12.3 在线调试
在电信平台菜单下的设备列表中点击在线调试按钮（小齿轮图标），进入在线数据调试页面，此时设备已上线，可以发送数据到网页端显示，网页上的数据也可以下发到模块中。
和直连设备的不同的是：平台下发增加了发送状态提示，例如SENT表示数据已发送，但尚未收到NB模块的ACK应答。DELIVERED表示数据已送达，收到模块的ACK应答。
13 分组透传
可以将需要数据透传的设备添加到透传分组中，这样同一个透传分组中的设备就可以实现相互透传。并且不受设备类型、设备协议的引用，都可以实现透传。
在控制台左侧菜单中单击【分组透传】，然后再点击【分组列表】页面中的【创建透传分组】，如下图所示，将刚刚创建的两个设备添加到一对一透传分组中。
- 分组名称： 给设备起个可读的名字，方便区分不同透传分组。
- 透传模式：设备数据的路由逻辑，可设置一对一透传（单聊模式，两个设备互相透传），一对多透传（集散模式，主设备与从设备之间的透传），多对多透传（群聊模式，每个设备都会收到其他设备发送的数据）。
- 已添加设备：从右侧的设备列表中，选择待添加的设备。注意，一对一透传只能添加两个设备。一对多透传必须要指定一个主设备，指定方法在在左侧【已添加设备】列表中单击选中一个即可。
点击提交，跳转到已创建的透传分组列表中，如下图所示。
设置结束了？是的，此时透传分组的两个设备即可相互透传，注意，直连设备首先需要上报注册包，平台设备需要先绑定。另外，如果长期未进行数据收发，导致其中一个设备接入信息老化，则数据将无法透传到此设备中，需要此设备主动上报注册包激活。
14 附录1：常见问题
Web管理（创建设备）过程中的常见问题如下表格：
| 描述 | 解释或解决办法 |
|---|---|
| 设备编号： 记录已存在 | 表示数据库列表中已存在该编号的设备，需要删除原有记录才能重新创建设备。请按下述排除：
|
| 平台消息：设备数量已达上限 | 表示已创建的设备数量已达到上限，谷雨云透传可以免费创建5个本地设备和5个电信平台设备。 |
设备接入过程中的常见问题如下表格：
| 描述 | 解释或解决办法 |
|---|---|
| 电信平台设备，发送数据，模块返回：
+CME ERROR: 513 |
意思是模块向CDP服务器发送注册信息，但服务器未响应或者返回错误代码。
请排除以下原因：
|
| 直连设备，发送注册包，平台返回：
[iotxx:ok] |
表示平台已收到设备发送的注册包，并且设备注册成功。可以进行数据通信。 |
| 直连设备，发送注册包，平台返回：
[iotxx:update] |
表示平台收到了设备发送的多条注册包，第一个注册包用来身份识别。
若有效期内（端口老化之前），设备再次发送注册包，可以理解是设备发来的心跳包。可以进行数据通信。 |
| 直连设备，发送注册包，平台返回：
[iotxx:pw-error] |
表示设备发送的注册包中的密码字段错误，通常是已发送的注册包中包含了不可见字符，例如回车换行等符号。 |
| 直连设备，发送注册包，平台返回：
[iotxx:not-allow-new-device] |
表示设备发送了注册包并且注册成功之后，在有效期内（端口老化之前）又发送了新设备编号的注册包。平台拒绝此操作。 |
| 直连设备，发送注册包，平台返回：
[iotxx:invalid-device] |
表示平台收到了设备发送的注册包，但该注册包中的设备编号对应的设备并未创建，或者设备编号错误。 |
| 直连设备，发送数据，平台返回：
[iotxx:send-reg-first] |
表示设备发送数据之前没有先发送注册包注册设备，若注册包已发送过，很可能是该设备原先的接入信息已失效，需要重新发送注册包。 |
15 附录2：更新记录
| 日期 | 更新记录 |
|---|---|
| 2017-11-15 | V0.1版本发布，支持UDP/CoAP协议接入以及，数据在线调试。 |
| 2017-12-01 | V1.0版本发布，实现透传分组功能，可实现任意设备之间的数据透传。 |
| 2018-01-01 | 增加TCP协议接入。 |
| 2018-09-01 | V2.0版本内部测试，完成电信平台对接工作。 内部测试中 |
| 2018-11-01 | 完成华为平台对接工作，内部测试中。 |
| 2019-01-29 | 顺利通过电信平台测试，V2.0版本即将上线。 |
| 2019-02-01 | V2.0版本正式发布，支持电信平台设备接入。并且支持电信平台设备与谷雨直连设备之间的数据透传。 |
| 2019-02-13 | 启用SSL安全链接，由http访问改为https，新版本入口为 https://cloud.iotxx.com |