谷雨云透传平台接入指南

来自谷雨文档中心
Ghostyu讨论 | 贡献2019年2月12日 (二) 12:23的版本 附录1:常见问题
跳转至: 导航搜索

谷雨物联网的使命是让联网通信更简单,正因为这个使命,我们开发了【谷雨云透传平台】,面向广大开发者免费提供。

开发云透传还有一些重要原因:

  • 降低NB-IOT的学习门槛。电信NB有定向IP访问限制,要求设备必须接入电信平台。
  • 提供一款好用的免费的远程网络调试助手。并提供简单透传功能。


1 适用群体

谷雨云透传平台的定位是:极客的小创意、小产品的远程联网需求,网络连接测试。例如,使用NB-IOT技术,快速实现家庭烟雾报警的功能演示;或者远程温湿度监控等等。

因此我们的云透传平台的适用群体为:

  • 学生
  • 极客
  • 开发者(处于学习或者Demo调研演示阶段)

当前版本虽然未2.0,但定位仍然为测试,量产产品建议接入华为、电信或阿里云IOT等企业级云平台,更有安全性和稳定性的保障。

2 功能框图

NB-IOT终端接入谷雨云透传的功能框图如下图所示:

谷雨云透传:功能框图-NB终端.png

非NB-IOT终端设备接入谷雨云透传的功能框图下图所示:

谷雨云透传:功能框图-非终端.png

3 平台能力

谷雨云透传平台具有下面几大能力:

  • 支持本地UDP/TCP协议接入。设备直连谷雨云透传。
  • 支持电信/华为平台对接(LwM2M或CoAP协议)。设备直连华为/电信平台,消息路由到谷雨云透传。
  • 支持上述设备之间的数据透传能力。支持任意两个网络设备之间的数据透传。

4 平台接口

直连设备采用最简单、最原始的Socket连接(具有网络通信能力的设备采用UDP或者TCP协议,作为客户端的身份连接谷雨云透传)。

电信、华为平台设备采用LwM2M或CoAP协议。

类型 IP或域名 端口号
管理界面(Web登录) http://cloud.iotxx.com 80
直连设备(UDP协议) 115.29.240.46 6000
直连设备(TCP协议) 115.29.240.46 9000
电信平台设备(LwM2M或CoAP协议) 117.60.157.137 5683
Icon-info.png
注意,由于电信NB网络有定向IP访问限制,使用电信NB网络的用户需要使用电信平台对接的方式接入。对于没有访问限制的移动NB网络,或者其他网络,使用设备直连UDP/TCP协议接入。

5 注册包机制

平台为了鉴别接入设备的合法性,需要额外的一些信息或数据包来辅助判断。该信息或数据包,需要在平台上预先配置,因此设备接入平台之前,必须要在平台上先创建设备。

谷雨云透传:注册包机制.png

5.1 直连设备

Socket采用服务器/客户端的机制通信,客户端只要知道服务器的IP地址和端口号,就可以建立链接。

建立链接后,谷雨云透传为了识别客户端设备的合法性,使用了一种注册包机制,即客户端每次与平台建立链接后,首先需要发送一包数据,这包数据需要按照我们规定的格式来发送。平台通过该数据包的内容来识别设备。这个数据包,我们称之为注册包。

注册包格式为:ep=deviceId&pw=devicePw

deviceId(设备编号)和devicePw(设备密码)是两个变量。由云平台自动分配或客户自定义。

5.2 电信平台设备

电信平台采用验证模块IMEI码的方式,因此,创建电信平台设备时,设备编号必须使用NB模块的IMEI码,否则无法通信。

6 在线调试

在线调试是一项非常实用的功能,可以实现远程网络调试助手功能。

该功能给那些必须要固定IP才能通信的设备的用户带来了极大的方便,不再需要费时费力开发服务器端的网络程序。

谷雨云透传:在线调试.png

7 分组透传

上一节中的在线调试功能很实用,但设备数据只能在网页中收发,如果有一个功能,可以将这些数据再转发到开发者的电脑上或指定设备中,那再好不过。

基于这个需求,我们设计了分组透传的功能。

开发者可以将需要数据透传的设备添加到透传分组中,这样同一个透传分组中的设备就可以实现相互透传。

对平台来说,透传分组中的所有设备,逻辑上都是对等的,也就是说,相互透传的设备可以是两个NB模块,也可以两个WiFi模块,当然也可以是NB模块与WiFi模块之间,或NB模块与电脑之间透传。

例如,在平台上创建两个设备,一个用于NB模块的接入,另外一个用于电脑上的Socket客服端程序(可以使用网络调试助手)接入。然后将两个设备添加同一个透传分组中,这样,NB模块和电脑上的Socket客户端程序即可相互收发数据。

我们支持以下三种分组透传策略:

  • 点对点,我们称作单聊模式,只有两个设备参与透传。
  • 点对多点,称作集散模式,多设备透传,且需要指定一个主设备,其他设备作为从设备。主设备发送的数据,每个从设备都能收到,而从设备发送的数据,只能被主设备收到。
  • 多点对多点,该模式类似一个聊天群组,群组内的所有设备均对等,所有设备都能接收到其他设备发送的消息。
谷雨云平台:分组透传.png

8 账号注册

谷雨云透传平台向广大学习者免费提供服务,使用前需注册账号。

浏览器中输入网址:https://cloud.iotxx.com/register ,注册谷雨云平台账号,如下图所示。

谷雨云透传:注册账号.png

注册成功后,访问网址:https://cloud.iotxx.com/dashboard ,进入控制台,控制台显示当前的设备概况,新闻通知等内容。

谷雨云透传:控制台概况.png

控制台左侧菜单有如下分类:

  • 谷雨直连,管理和创建直连谷雨云透传平台的设备,该菜单下的设备使用UDP或TCP协议接入。
  • 电信平台,管理和创建接入电信平台的设备,该菜单下的设备使用LwM2M或CoAP协议接入。
  • 透传分组,管理和创建透传分组。

无论是谷雨直连的设备,还是电信平台的设备,均可以通过透传分组来实现设备间的数据透传。

9 谷雨直连设备演示

谷雨直连是指设备采用Socket UDP/TCP协议直接接入谷雨云平台,不经过第三方云平台转发。

9.1 创建设备

在控制台左侧菜单中单击【谷雨直连】,然后打开【创建设备】页面,如下图所示。

谷雨云透传:创建直连设备.png
  • 设备编号:一组15~16位的随机字符串,可以使用平台自动生成的编号,也可以用户自定义。设备接入时需要上报包含此编号的注册包。
  • 通信密码:长度为6的数字字符串,作为设备通信密码。设备接入时需要上报包含此密码的注册包。
  • 设备名称:给设备起个可读的名字,方便区分不同设备。
  • 过期时间:已弃用,固定为0秒。
  • 设备描述:可选,可以给设备添加详细的描述。
  • 地理位置:可选,可以给设备添加一个地理位置。

9.2 设备接入

由于实体设备还未接入,此时的设备在线状态为离线。为了方便演示,我们在电脑上使用Socket网络调试助手来接入平台。

谷雨云透传:直连设备列表.png

9.2.1 创建Socket客户端

使用网络调试助手,创建udp或tcp协议客户端来连接谷雨云透传。

谷雨云透传:网络调试助手接入.png

根据以下表格的接入地址和端口填写。

类型 IP地址 端口号
直连设备(UDP协议) 115.29.240.46 6000
直连设备(TCP协议) 115.29.240.46 9000

点击确认,准备发送注册包,UDP协议不需要连接,可直接发送数据,而TCP协议需要先连接,然后才能发送数据。

9.2.2 发送注册包

设备连接平台后,首先需要上报注册包,用于身份识别,然后才能数据通信。注册包的格式为:ep=deviceId&pw=devicePw,将deviceId和devicePw替换成当前已创建的设备编号和密码。

大家可以进入在线调试页面,在线调试页面的右下角自动生成注册包,可直接复制。

谷雨云透传:发送注册包.png

9.3 在线调试

在设备列表中点击在线调试按钮(小齿轮图标),进入相应设备的在线数据调试页面,此时设备已上线,可以发送数据到网页端显示,网页上的数据也可以发送到电脑上显示。

谷雨云透传:在线调试-网络调试助手.png

10 电信平台设备演示

电信平台设备是指设备通过谷雨云透传接入电信平台。

电信NB-IOT云平台是面向企业商用的统一开发平台,具有NB-IOT设备接入及管理、数据采集管理以及分析、各种各种终端适配及扩展等功能。电信NB-IOT云平台提供两种接口。

  • 南向接口:向下提供的接口,用来设备接入。
  • 北向接口:向上提供接口,提供给企业管理设备,收发设备数据的接口。北向接口对应企业的应用服务器。企业的应用服务器向终端客户提供具体的商业逻辑。

此时,谷雨云透传的角色是电信云平台的北向应用:应用服务器,电信平云台类似桥梁的作用,连接设备与谷雨云透传。

对接电信平台的原因:

  1. 电信平台需要企业身份申请,初学者可通过我们的云透传快速体验电信平台的优点。
  2. 电信NB网络有定向IP限制,不允许直连私有服务器。

因此,建议走电信网络的NB-IOT设备,全部采用这种方式接入,避免直连私有服务器,包括我们的谷雨云透传。

10.1 创建设备

在控制台左侧菜单中单击【电信平台】,然后打开【创建设备】页面,如下图所示,与创建直连设备很相似。

谷雨云透传:创建电信平台设备.png
  • IMEI编号: IMEI编号是指NB模块的IMEI码,电信平台要求使用模块的IMEI码来创建设备。因此,必须如实填写模块的IMEI码,否则无法通信。
  • 设备名称:给设备起个可读的名字,方便区分不同设备。
  • 设备描述:可选,可以给设备添加详细的描述。
  • 地理位置:可选,可以给设备添加一个地理位置。
Icon-info.png
注意,创建设备使用IMEI码,IMEI是国际移动设备识别码International Mobile Equipment Identity的缩写,是以86(国内模块)开头的一组数字字符串。请勿和卡的IMSI码混淆,国内卡的IMSI码是以460开头的一组数字字符串。

10.2 设备接入

已创建的设备,可以在设备列表中找到,如下图所示,界面与直连设备基本相同。

谷雨云透传:电信平台设备列表.png

10.2.1 BC95接入

BC95使用CoAP协议接入,与BC95用法相同的还有BC35和BC28。

下面描述NB模块的接入流程(仅介绍与通信相关的指令)

  1. 初始化NB模块并附着网络。具体指令请参考各自模块的软件指令手册。
  2. 设置CDP服务器和端口,发送指令: AT+NCDP=117.60.157.137,5683 ,117.60.157.137是电信平台(商用版)的南向接入地址,5683是协议端口。
  3. 设置CDP服务器后建议重启,发送指令: AT+NRB
  4. 重启后,模块再次附着到网络,会自动执行平台设备绑定,如果绑定成功,串口首先上报异步消息:+QLWEVTIND:0 ,0:表示注册完成;然后随即再次上报状态:+QLWEVTIND:3 ,3:表示注册已更新。
  5. 此时,NB模块已成功接入,在我们的云透传上,可以看到在线状态已变为在线。若第4步的现象没有出现,可以调用发送数据指令来完成设备绑定。发送指令:AT+NMGS=3,313232 ,指令意思是发送3个字节的数据,数据内容是字符串:123
  6. 若模块返回:+NSMI:SENT 表示数据已发送,也意味着设备绑定成功。若返回513错误,请检查注册设备用的设备编号是否与模块IMEI码一致,发送指令:AT+CGSN=1 来查询模块IMEI码。

10.2.2 BC26接入

BC26使用LwM2M协议接入,相对BC95的CoAP协议,设置的内容较多。下面是详细的流程。

  1. 初始化NB模块并附着网络。具体指令请参考各自模块的软件指令手册。
  2. 待更新

10.2.3 SIM7020C接入

待更新。

10.3 在线调试

在电信平台菜单下的设备列表中点击在线调试按钮(小齿轮图标),进入在线数据调试页面,此时设备已上线,可以发送数据到网页端显示,网页上的数据也可以下发到模块中。

谷雨云透传:电信平台设备在线调试.png

和直连设备的不同的是:平台下发增加了发送状态提示,例如SENT表示数据已发送,但尚未收到NB模块的ACK应答。DELIVERED表示数据已送达,收到模块的ACK应答。

11 分组透传

可以将需要数据透传的设备添加到透传分组中,这样同一个透传分组中的设备就可以实现相互透传。并且不受设备类型、设备协议的引用,都可以实现透传。

在控制台左侧菜单中单击【分组透传】,然后再点击【分组列表】页面中的【创建透传分组】,如下图所示,将刚刚创建的两个设备添加到一对一透传分组中。

谷雨云透传:创建透传分组.png
  • 分组名称: 给设备起个可读的名字,方便区分不同透传分组。
  • 透传模式:设备数据的路由逻辑,可设置一对一透传(单聊模式,两个设备互相透传),一对多透传(集散模式,主设备与从设备之间的透传),多对多透传(群聊模式,每个设备都会收到其他设备发送的数据)。
  • 已添加设备:从右侧的设备列表中,选择待添加的设备。注意,一对一透传只能添加两个设备。一对多透传必须要指定一个主设备,指定方法在在左侧【已添加设备】列表中单击选中一个即可。

点击提交,跳转到已创建的透传分组列表中,如下图所示。

谷雨云透传:透传分组列表.png

设置结束了?是的,此时透传分组的两个设备即可相互透传,注意,直连设备首先需要上报注册包,平台设备需要先绑定。另外,如果长期未进行数据收发,导致其中一个设备接入信息老化,则数据将无法透传到此设备中,需要此设备主动上报注册包激活。


12 附录1:常见问题

Web管理(创建设备)过程中的常见问题如下表格:

描述 解释或解决办法
设备编号: 记录已存在 表示数据库列表中已存在该编号的设备,需要删除原有记录才能重新创建设备。请按下述排除:
  • 由于本地设备(直连),平台设备(电信或华为)共享同一数据库,请确认是否被自己占用。若占用,请自行删除。
  • 若本账号下没有同编号设备,请确认是否被同学或同事占用,请联系我们确认及删除

设备接入过程中的常见问题如下表格:

描述 解释或解决办法
电信平台设备,发送数据,模块返回:

+CME ERROR: 513

意思是模块向CDP服务器发送注册信息,但服务器未响应或者返回错误代码。

请排除以下原因:

  • 若模块刚刚修改CDP设置,建议重启模块后重试。
  • 确认使用该模块的IMEI码创建了电信平台设备,检查IMEI码是否正确。
直连设备,发送注册包,平台返回:

[iotxx:ok]

表示平台已收到设备发送的注册包,并且设备注册成功。可以进行数据通信。
直连设备,发送注册包,平台返回:

[iotxx:update]

表示平台收到了设备发送的多条注册包,第一个注册包用来身份识别。

若有效期内(端口老化之前),设备再次发送注册包,可以理解是设备发来的心跳包。可以进行数据通信。

直连设备,发送注册包,平台返回:

[iotxx:pw-error]

表示设备发送的注册包中的密码字段错误,通常是已发送的注册包中包含了不可见字符,例如回车换行等符号。
直连设备,发送注册包,平台返回:

[iotxx:not-allow-new-device]

表示设备发送了注册包并且注册成功之后,在有效期内(端口老化之前)又发送了新设备编号的注册包。平台拒绝此操作。
直连设备,发送注册包,平台返回:

[iotxx:invalid-device]

表示平台收到了设备发送的注册包,但该注册包中的设备编号对应的设备并未创建,或者设备编号错误。
直连设备,发送数据,平台返回:

[iotxx:send-reg-first]

表示设备发送数据之前没有先发送注册包注册设备,若注册包已发送过,很可能是该设备原先的接入信息已失效,需要重新发送注册包。

13 附录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版本正式发布,支持电信平台设备接入。并且支持电信平台设备与谷雨直连设备之间的数据透传。

本PDF由谷雨文档中心自动生成,点击下方链接阅读最新内容。

取自“http://doc.iotxx.com/index.php?title=谷雨云透传平台接入指南&oldid=1487