谷雨云透传平台接入指南

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

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

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

1 适用群体

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

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

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

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

2 平台能力

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

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

3 平台接口

设备直连谷雨云透传采用最简单最原始的Socket连接，电信华为平台设备采用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协议接入。

4 注册包机制

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

4.1 直连设备

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

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

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

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

4.2 电信平台设备

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

5 在线调试

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

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

6 分组透传

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

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

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

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

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

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

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

7 账号注册

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

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

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

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

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

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

8 谷雨直连

8.1 创建本地设备

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

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

8.2 创建电信设备

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

• IMEI编号： IMEI编号是指NB模块的IMEI码，电信平台要求使用模块的IMEI码来创建设备。因此，必须如实填写模块的IMEI码，否则无法通信。
• 设备名称：给设备起个可读的名字，方便区分不同设备。
• 设备描述：可选，可以给设备添加一个地理位置。
• 地理位置：可选，可以给设备添加一个地理位置。