ThingsEdge 4G DTU 接入 ThingsCloud 完全手册

约 7326 字大约 24 分钟

ThingsEdge 4G DTU 接入 ThingsCloud 完全手册

介绍

ThingsEdge 系列 DTU 基于 ThingsCloud 开放平台接入协议，除了具备普通 DTU 的串口透传功能，还具备可配置的边缘能力，在一些依赖边缘控制和数据实时采集的物联网场景中应用广泛，例如：

农业大棚
燃气监测
能耗监测
市政交通
智能风机
污水处理
远程抄表
资产追踪

提示

ThingsCloud 广泛支持不同厂商的物联网设备接入，了解详细的设备接入方法，请浏览：

功能特性

4G全网通：采用 4G Cat.1 网络连接，支持国内移动、电信、联通物联网卡。随设备赠送物联网卡。
免连接配置：开箱即用，无需 PC 上位机软件配置，直连 ThingsCloud。了解详情
RS485/Modbus：可连接上千种 RS485/Modbus 协议的传感器、执行器、控制器。了解详情
Modbus 边缘解析：支持 Modbus 和 JSON 的互相转换，自动同步 ThingsCloud 上设备的寄存器配置。了解详情
设备自动注册：当大规模设备接入时，无需预先在平台创建设备。了解详情
数据变化上报：支持 Modbus 传感器数据变化时上报，节省通信流量和设备消息量。了解详情
开关量实时采集：支持 Modbus 控制器 IO 输入实时采集，不需要从云平台下发 Modbus 查询。了解详情
状态恢复：支持设备重启后 Modbus 寄存器状态自动恢复，适合用于继电器通断状态和云平台保持同步。
开关量延迟控制：支持云平台控制开关量延迟控制和延迟反转。了解详情
边缘联动：支持 DI-DO 的边缘联动规则。了解详情
基站位置：支持基站定位上报。了解详情
OTA升级：支持固件免费 OTA 升级。

视频教程

硬件说明

设备特性

名称	说明
供电范围	12 ~ 36V
工作电流	12V 供电，平均 30ma
工作温度	-35°C ~ 75°C
工作湿度	5% ~ 95%RH (无凝露)
防静电能力	接触放电 ±8KV，空气放电 ±15KV
支持频段	4G 国内全网通 LTE-FDD: B1/B3/B5/B8 LTE-TDD: B34/B38/B39/B40/B41
支持地区	中国/东南亚/印度
主机尺寸	高：69mm（不含底部端子）、76mm（含底部端子）宽：53mm（不含左右挂耳）、72mm（含左右挂耳）厚：19mm

标准套件

名称	数量	说明
ThingsEdge DTU 主机	1	不含DC电源
4G 天线	1	棒状天线/3DBI/90mm长度
物联网卡	1	随设备赠送物联网SIM卡

引脚说明

编号	引脚	功能	说明
1	VIN	电源正极	供电电源，支持 12~36V 直流电源，电源最少支持 10W 功率以保障稳定运行。
2	GND	电源负极	供电电源，支持 12~36V 直流电源，电源最少支持 10W 功率以保障稳定运行。
3	RX	RS232	RS232 端口
4	TX
5	CTS
6	RTS
7	GND	GND	当使用 RS232 端口时，用于和设备共地
8	A	RS485	RS485 端口，和设备的 A 和 B 请勿接反。
9	B	RS485	RS485 端口，和设备的 A 和 B 请勿接反。

DTU 连线指南

DTU 如何接入 ThingsCloud

这一小节介绍如何让 DTU 在 ThingsCloud 控制台中上线，只需要简单的几个步骤。

ThingsEdge DTU X1 采用 4G 连网方式，开机直连 ThingsCloud，无需使用 PC 上位机软件进行配置。

提示

ThingsEdge DTU 完全基于 ThingsCloud 开放标准协议，包括 MQTT 接入协议和自定义数据流，详情可浏览：

登录 ThingsCloud 控制台

如果您已经注册 ThingsCloud 控制台的账号，请直接登录控制台。

如果您还没有注册账号，可点击以上网址，免费注册账号后登录。

创建项目

如果您已经创建项目，请直接点击项目进入。

如果您还没有项目，请先创建免费版项目或购买付费版项目。请参考创建项目。

关联 DTU 到项目

请联系设备经销商，确保 DTU 已关联到您在 ThingsCloud 的指定项目中。

创建设备类型

我们先创建设备类型，选择从产品库快速导入，输入产品 ID 1871114718，直接从产品库导入设备类型，已包含 DTU 的初始功能定义。

提示

请注意，这里的产品 ID 不是设备背面的设备编号，而是输入以上的固定 ID，它代表 ThingsEdge DTU X1 这款产品。

设备类型的名称，您可以随意修改。

创建设备

接下来，为 DTU 创建设备，关联到刚创建的设备类型。

进入设备创建页面，填写以下几项：

设备名称：给设备起一个名字。
设备唯一标识：填写设备外壳背面的 15 位的设备编号。
设备类型：选择刚创建的设备类型。

其它选项可以不填写，提交创建设备。

进入创建的设备，可以看到初始属性来自设备类型中的功能定义。

设备出厂默认未开启基站定位功能，您可以根据需要来开启。

开机自动连接

接下来可以给 DTU 上电。

提示

上电前确保检查以下事项：

是否安装 4G 天线，否则影响网络稳定性。
是否插入物联网卡，插入的方向是否正确，外壳有示意图。

稍等片刻，DTU 设备显示已连接，会上报一些系统属性。

远程重启设备

如果需要重启设备，可以下发命令，如下：

开启基站定位（可选）

DTU 支持 4G 基站定位，开启基站定位后，需要重启 DTU，重新启动后会上报位置信息，由于基站定位误差较大，仅供参考。

自动创建设备（可选）

当我们正式在项目中部署大量设备时，可以开通设备自动注册功能。

首先在设备类型中找到自动创建设备配置，开启允许设备自动创建，然后复制 TypeKey，提供给 DTU 经销商。

配置生效后，我们测试一台新的 DTU，开机后自动创建。默认的设备名称会包含 DTU 的 IMEI 后四位数字。

修改 RS485 波特率（可选）

DTU 的 RS485 端口默认波特率是 9600，如需修改，可在控制台的设备概览中，为波特率属性选择需要的数值，下发后 DTU 立即生效。如下图：

若使用调试窗口或 API，可以直接向设备下发属性：

{
    "baud_rate": "115200"
}

DTU 每次重启后，会自动同步为最近一次设置的波特率。

串口透传说明

ThingsEdge DTU X1 连接到平台后，会自动开启 RS485 透传模式，将串口收到的数据转发到 ThingsCloud 平台上对应的设备，同时将平台设备下发的数据转发到串口。

DTU 设备使用平台的自定义数据流进行通信，自定义数据流标识符为 stream，请勿在平台的设备类型中修改该自定义数据流的设置，以免影响数据通信。

需要注意的是，若您为 DTU 启用了 Modbus RTU 边缘任务，由于边缘任务的优先级较高，会不同程度的影响透传模式的运行，可能会导致串口输入数据有时无法转发到平台。

DTU 支持多种连接场景

DTU Modbus RTU 透传模式

Modbus 云解析

Modbus 云网关

DTU 边缘解析模式

DTU 直连模式

DTU 网关子设备模式

下发控制

实时采集变化量

DTU Modbus RTU 透传模式

Modbus RTU 串口透传功能几乎是所有 DTU 产品的标配，我们在教程中也介绍了一些厂商的 DTU 接入示例。

ThingsEdge DTU 使用 Modbus 透传功能和其它 DTU 完全相同，这里列举一些常用方法。

使用 DTU 集成模式

ThingsCloud 对所有 DTU 的接入通常支持两种模式：

集成模式：也就是 DTU 以及它连接的所有传感器等设备，在 ThingsCloud 上体现为一台设备。这种方式适合 DTU 和子设备都比较少的情况。如果数量较多，不利于设备功能定义的复用性。
网关模式：将 DTU 和它的多个子设备，在 ThingsCloud 上对应独立的设备。这样便可以对子设备进行独立的功能定义，便于设备资产的组织和维护管理，非常清晰。

这一节我们先介绍集成模式。为了便于管理，我们用之前的方法新建一个设备类型，改个新的名称。

接线示例

在这个示例中，我们在 DTU 的 RS485 总线上连接了两个 Modbus 设备：

8进8出 IO 控制器，从机站号是 1，波特率 9600
温湿度传感器，从机站号是 2，波特率 9600

其中，在 IO 控制器的继电器端，我们连接了两个指示灯，在IO输入端，连接了两个行程开关。

添加 IO 控制器的属性定义

我们先在 DTU 的设备类型中，找到功能定义，通过添加标准功能，找到对应的设备模型，添加 8 个 IO 输入开关量属性，和 8 个继电器输出开关量属性。

创建好的属性定义如下：

配置 IO 控制器的 Modbus 寄存器

然后在 DTU 的设备类型中，找到Modbus 配置，将刚创建的属性加入 IO 寄存器。如下图：

然后配置正确的从机地址和寄存器地址，如下图：

最后，开启属性智能转换，并绑定自定义数据流。如下图：

下发 Modbus 开关量控制

现在我们回到设备的概览面板，可以直接下发继电器输出。

在设备的调试功能中，可以看到属性下发被自动转成了 Modbus 指令，通过自定义数据流下发到了 DTU，再被透传到 IO 控制器，然后接收到了 DTU 回传的 Modbus 回复消息。如下图：

到目前为止，我们已经可以通过 ThingsCloud 控制台远程控制继电器开关。

通过 Modbus 任务查询继电器状态

有时候继电器断电会归位，云平台可能不知道继电器的最新状态，所以我们来建立一个继电器状态查询的 Modbus 任务。如下图：

这里我们将任务的目标类型选为设备类型，而不是设备，这使得任务对该设备类型下的所有设备生效，未来有更多设备添加后不需要再单独创建同样的任务。

推送方式选择 MQTT，自定义数据流填写 stream，这是 DTU 内置连接 ThingsCloud 的默认自定义数据流标识符。

选择 Modbus RTU 下发 任务，用 01 功能码查询继电器状态，这里需要略懂 Modbus 指令，通常可以从设备手册中找到 Modbus 协议。

任务创建成功后，我们可以手动运行一次。如下图：

可以在设备调试中看到 3 条消息，分别是：

下发的 Modbus 查询指令
收到 Modbus 回复指令
解析后转换成属性上报消息

配置温湿度传感器 Modbus 寄存器

接下来我们再配置另一个连接到 DTU 的温湿度传感器，同样先添加功能定义，添加温度和湿度两个属性，如下图：

添加新的属性后，如下图：

接着在 Modbus 配置中，设置温度、湿度属性对应的传感器寄存器，如下图：

不同厂家的温湿度传感器，支持的 Modbus 寄存器略有不同，请您参考实际产品手册。

通过 Modbus 任务查询温湿度

普通的温湿度传感器，只有上报数据的功能，我们来建立一个 Modbus 任务，定时查询温湿度。如下图：

这里我们用到任务的定时功能，我们选 间隔时间重复，如下图：

保存任务后，任务自动启动运行，等待我们设置的间隔时间后，任务首次运行，温湿度数据成功获得。

其它透传 DTU 的支持

ThingsCloud 的 Modbus RTU 透传方式适用于所有厂商支持串口透传的 DTU 产品，可参考这些示例：

DTU 边缘功能

边缘功能是 ThingsEdge DTU 支持的特有功能，所有的边缘功能配置都在 ThingsCloud 云平台完成，达到云端边缘一体化的使用体验。

我们来列举几个常用的使用示例：

边缘 Modbus 轮询温湿度

边缘 Modbus 查询功能，是指在边缘设备上直接轮询 Modbus 子设备，并自动解析 Modbus 返回消息，生成 JSON 属性消息，通过 ThingsCloud 的标准 MQTT 接入协议，上报到云平台。

我们来创建一个边缘任务，选择 Modbus RTU 读取轮询，设置内容和从云端下发的 Modbus RTU 读取温湿度基本相同，不同的是，它支持三种轮询上报模式：

周期轮询上报：按固定间隔时间进行轮询，每次获取数据均上报。
周期轮询仅变化上报：按固定间隔时间进行轮询，仅当数据变化时上报。适用于需要节省设备消息量和网络流量和场景。
实时上报：不需要设置轮询间隔时间，边缘设备以尽可能短的间隔时间进行轮询，当数据变化时立即上报。适用于实时获取Modbus设备IO输入，或者需要实时采集数据波动的场景。

这里我们用第一种周期轮询上报，设置为 30 秒轮询上报一次。

这里我们先关闭云平台下发的温湿度查询任务，然后点击新创建的边缘任务的更新到边缘，将这个任务实时更新到 DTU。

接下来，就可以看到 DTU 直接上报的温湿度 JSON 数据。

传感器数值仅变化上报

在一些场景中，我们不希望周期轮询后每次都上报重复的数据，比较浪费 4G 流量以及云平台的设备消息数，这些都增加了设备运营成本。

那么就可以使用另一种轮询上报模式：周期轮询仅变化上报。我们修改刚创建的边缘任务，如下图：

更新边缘任务后，陆续可以看到 DTU 上报的温湿度数据，只包含变化的属性。如下图：

实时采集开关量（DI）输入

另一个需要边缘 Modbus 轮询的重要场景，是实时获取 Modbus IO 控制器的输入变化。由于 Modbus 协议机制是基于主机查询后从机回复，所以必须以较短间隔时间来轮询 IO 输入寄存器，才可以实时采集变化。

这使得通过云平台下发 Modbus 查询是不适合的，而在边缘进行快速轮询是最佳方案。

在前边的透传功能示例中，我们没有实现 IO 控制器输入的状态查询，现在我们用边缘任务来实现它。

类似边缘查询温湿度，我们新创建一个边缘任务，用功能码 02 读取输入状态，轮询模式选择实时上报。如下图：

更新任务到 DTU 后，会立即收到首次上报，包括所有 IO 输入寄存器的状态。如下图：

接下来，当我们波动行程开关，改变 IO 输入状态时，云平台可以立即收到上报消息。如下图：

下发属性到边缘

边缘 Modbus 服务还可以直接接收云平台下发的 JSON 属性，自动转为 Modbus 指令，发给子设备。

为了让 DTU 可以收到云平台下发的开关量属性，我们先得禁用云平台自动将属性下发转成 Modbus，将 Modbus 配置 中的 属性智能转换 关闭。如下图：

然后，我们就可以直接在设备概览中点击继电器的开关，下发属性到 DTU。如下图：

在 DTU 上会自动转为 Modbus 并转发给 IO 控制器。

需要注意的是，当您更新 Modbus 配置后，并不会自动同步到 DTU。在确定配置修改无误后，您需要向 DTU 下发更新 Modbus 配置的命令，或者重启 DTU，使得 DTU 读取最新的 Modbus 配置。

下发开关量控制命令

ThingsEdge DTU 内置了 Modbus 开关量边缘控制功能，通过响应云平台下发的命令，可实现对一个或多个继电器，执行闭合或断开的动作，并支持延迟执行和延迟反转功能，例如：控制一个继电器在 10 秒后闭合，再过 10 秒后自动断开。

提示

如何通过向设备下发命令？请学习使用设备消息调试界面，向设备下发消息。

开关量控制命令的标识符为 switch_relay，命令参数支持多种形式，接下来学习几种常用的命令参数。

单路继电器闭合

例如：让继电器#1 马上闭合。

下发一个命令消息给 DTU，如下：

{
    "method": "switch_relay",
    "params": {
        "attribute": "relay1",
        "state": true,
    },
    "id": 1000
}

attribute 表示开关量属性名称，这里用了继电器#1
state 表示更新状态，true 表示闭合，false 表示断开

单路继电器闭合后延迟反转

例如：让继电器#1 马上闭合，10 秒后断开。

命令参数中增加一个新的参数，如下：

{
    "method": "switch_relay",
    "params": {
        "attribute": "relay1",
        "state": true,
        "delay_reverse": 10
    },
    "id": 1000
}

delay_reverse 代表延迟反转的时间，单位是秒

下发命令后，观察设备消息，DTU 收到命令后，闭合继电器并上报通知云平台，接着 10 秒后断开继电器并上报通知云平台。

单路继电器延迟闭合再延迟反转

这一次，让继电器#1 在 10 秒后闭合，再等 10 秒自动断开。

{
    "method": "switch_relay",
    "params": {
        "attribute": "relay1",
        "state": true,
        "delay": 10,
        "delay_reverse": 10
    },
    "id": 1000
}

delay 代表延迟执行的时间，单位是秒

多路继电器延迟闭合再延迟反转

这一次，让 8 个继电器同时在 10 秒后闭合，再等 10 秒自动断开。

{
    "method": "switch_relay",
    "params": {
        "attributes": ["relay1", "relay2", "relay3", "relay4", "relay5", "relay6", "relay7", "relay8"],
        "state": true,
        "delay": 10,
        "delay_reverse": 10
    },
    "id": 1000
}

attributes 表示开关量属性数组，支持多个属性标识符。

以上就是常用的几种开关量控制命令，您也可以在任务中使用这些命令，来实现定时任务。

云端设备联动规则

通过 DTU 的边缘 Modbus 服务，大大简化了云平台和 Modbus 设备的通信，所有的 Modbus 转换细节都在 DTU 上完成。这使得我们在 ThingsCloud 消息规则中实现各种设备联动更加简单。

我们来实现一个非常典型的联动控制规则，当 IO 控制器连接的行程开关闭合时，例如关门、窗帘到位等行为触发，我们希望某个继电器闭合，反之亦然。

我们建立一个消息规则，规则类型使用属性上报，设备来源类型选设备或设备类型都可以，这取决于您希望这个规则对单个设备有效，还是对设备类型下所有设备有效。

当选择单个设备来源时，规则操作可以选择向指定设备下发属性。如下图：

选择 DTU 作为下发的设备，其实就是下发到同一个设备，当然也可以下发到其它任何设备，完全没有物理空间限制，例如上海的行程开关联动控制北京的继电器。

同时编写一段 JavaScript 云函数，如下：

这里要注意的是，一定要先判断上报属性对象 report_attributes 中是否存在 di1，如果存在，我们让下发的继电器 relay1 状态跟随变化。

module.exports = function (report_attributes) {
    /**
     * report_attributes:   上报的属性对象，作为函数参数传入
     * push_attributes:     构造下发的属性对象，作为函数返回值，下发到硬件
     */
    var push_attributes = {
        
    };
    if (report_attributes.di1 !== undefined) {
        push_attributes.relay1 = report_attributes.di1
    }
    return push_attributes;
}

规则建立后，我们试试波动行程开关，可以看到继电器立刻跟随变化。

边缘设备联动规则

ThingsCloud 云平台可以轻松实现设备联动规则，但在有些特定场景下，我们也希望在 DTU 边缘实现联动，它具有一些优势，例如：

对联动控制的实时性有严苛要求的场景，不用等待设备和云平台之间的来回通信，而直接在 DTU 设备上实现控制。
当 DTU 设备偶尔信号不佳或断网的情况时，可不依赖云平台上的规则，直接在边缘完成联动控制。

ThingsEdge DTU 支持在边缘实现 DI（开关量输入）和 DO（开关量输出）的联动规则。首先需要满足以下条件：

联动规则相关的 DI 和 DO 属性，都已在设备类型的属性定义中添加，并且有相应的 Modbus 寄存器配置。
DI 和 DO 属性都在 DTU 设备下。不支持对子设备的属性实现边缘联动规则。
通过边缘任务来读取 DI 输入。

为 DTU 配置边缘联动规则很简单，只需为设备下发 JSON 结构到 di_do_rule 属性，如下图：

JSON 结构的说明如下：

{
    "<DI属性标识符1>": {
        "<触发条件>": {
            "<DO属性标识符1>": 1|0,
            "<DO属性标识符2>": 1|0,
            ...
        }
    },
    "<DI属性标识符2>": {
        "<触发条件>": {
            "<DO属性标识符1>": 1|0,
            "<DO属性标识符2>": 1|0,
            ...
        }
    },
    ...
}

其中，<DI属性标识符> 和 <DO属性标识符> 可以替换为属性标识符。

<触发条件> 的取值如下：

change：表示 DI 输入变化时触发，包括 ON 或 OFF。
on：表示 DI 变为 ON 的时候触发。
off：表示 DI 变为 ON 的时候触发。

当同一个 DI 输入包含多个触发条件时，on 和 off 的优先级高于 change。

下面看一个边缘规则的配置 JSON 示例：

{
    "di1": {
        "change": {
            "relay1": 1
        },
    },
    "di2": {
        "change": {
            "relay2": 1,
            "relay3": 0
        },
    },
    "di3": {
        "on": {
            "relay4": 1
        }
    }
}

解释一下这个示例配置的目的：

di1 这部分，change 表示 di1 发生变化时执行规则，"relay1": 1 表示继电器 relay1 状态正向联动。也就是说，当 di1 变为 ON 时，relay1 也会变为 ON，反之亦然。
di2 这部分，同时联动了 relay2 和 relay3 两个继电器属性，其中 "relay3: 0" 表示状态反向联动。也就是说，当 di2 变为 ON 时，relay3 也变为 OFF，反之亦然。
di3 这部分，on 表示仅当 di3 变为 ON 时执行规则，后边的内容同理。