# ThingsEdge 4G DTU 接入 ThingsCloud 完全手册

# 介绍

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

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

# 功能特性

• 4G Cat.1 网络连接，支持国内移动、电信、联通物联网卡。
• 开箱即用，无需 PC 上位机软件配置，直连 ThingsCloud。
• 串口连接支持 RS485/RS232，可连接所有 Modbus 协议的传感器、执行器、控制器。
• 支持 ThingsCloud 设备自动注册协议，项目大规模设备接入无需预先创建设备。
• 支持 ThingsCloud 设备属性下发，自动转为 Modbus 指令，包括开关量和数值属性。
• 支持 Modbus 边缘轮询，自动同步 ThingsCloud 设备类型的 Modbus 寄存器配置，在边缘自动完成 Modbus 转 JSON。
• 支持多种边缘轮询上报模式，包括：周期轮询上报、周期轮询仅变化上报、实时上报。
• 支持 Modbus 控制器 IO 输入实时采集，不需要从云平台下发 Modbus 查询。
• 支持 Modbus 传感器数值上报变化量，节省通信流量和设备消息量。
• 支持设备重启后 Modbus 寄存器状态自动恢复，适合用于继电器通断状态和云平台保持同步。
• 支持云平台控制开关量延迟控制和延迟反转。
• 支持基站定位上报。

# 视频教程

• ThingsEdge DTU - 开机自动连接 ThingsCloud 🎦
• ThingsEdge DTU - 硬件连线指南 🎦
• ThingsEdge DTU - 开启基站定位上报 🎦
• ThingsEdge DTU - 新设备自动注册 🎦
• ThingsEdge DTU - IO 控制器 Modbus 透传接入 🎦
• ThingsEdge DTU - 温湿度传感器 Modbus 透传接入 🎦
• ThingsEdge DTU - App 控制 Modbus 继电器 🎦
• ThingsEdge DTU - 上报温湿度变化数据 🎦
• ThingsEdge DTU - 实时采集 Modbus 开关量输入 🎦
• ThingsEdge DTU - 控制继电器开关定时反转 🎦
• ThingsEdge DTU - 实现 Modbus 控制器智能联动 🎦

# 硬件说明

# 设备特性

# 引脚说明

# 硬件连线指南

# 常用场景

# DTU Modbus RTU 透传模式

# Modbus 云解析

# Modbus 云网关

# DTU 边缘解析模式

# DTU 直连模式

# DTU 网关子设备模式

# 下发控制

# 实时采集变化量

# DTU 操作指南

# 使用 ThingsCloud 控制台

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

# 关联 DTU 到项目

在进行以下操作之前，请先联系设备经销商，将 DTU 关联到您在 ThingsCloud 的指定项目中。

# 创建设备类型

我们先创建设备类型，选择产品类型，输入产品 ID 1871114718，直接使用标准产品库的模板，已包含 DTU 的功能定义。

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

# 创建设备

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

在设备外壳背面可以找到 15位的 IMEI 编号，作为设备的唯一标识。

# 开机自动连接

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

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

接下来可以给 DTU 上电开机。

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

# 远程重启设备

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

# 开启基站定位（可选）

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

# 自动创建设备（可选）

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

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

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

# 修改 RS485 波特率（可选）

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

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

{
    "baud_rate": "115200"
}

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 产品，可参考这些示例：

• 有人 4G DTU TCP 接入open in new window
• 塔石 4G DTU MQTT 接入open in new window

# DTU 边缘解析模式

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

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

# 边缘 Modbus 轮询温湿度

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

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

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

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

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

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

# 传感器数值仅变化上报

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

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

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

# 实时获取 IO 输入

另一个需要边缘 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;
}

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

# 边缘设备联动规则

除了在云平台实现设备联动规则，有时我们也许在边缘实现联动，它具有一些优势，例如：

• 对控制的实时性有严苛要求的场景，边缘设备的实时性可以确保就近处理控制规则。
• 在设备偶尔断网的情况下，边缘设备可以脱离部署在互联网上的云平台，直接对子设备就近完成联动控制。但这种控制仅限于边缘设备的子设备之间，存在一定的物理空间限制。

该功能正在内测中，即将支持。

# 启用 DTU 网关模式

ThingsEdge DTU 不仅可以通过直连方式接入云平台，还可以通过网关方式接入。

在使用网关方式接入时，除了像所有透传 DTU 一样支持 ThingsCloud 的 Modbus 云网关模式，还内置了对 ThingsCloud 网关 MQTT 协议的支持，这使得它同样支持子设备的边缘功能，使用方法和直连模式下基本相同。

该部分内容即将完善。

# 生成用户 App

最后，我们给这个示例生成一个用户 App，包括：

• 显示 DTU 的温湿度数据
• 显示其中两个 IO 输入实时状态
• 显示其中两个继电器状态

从设备类型中进入 App 编辑，如下图：

在 App 编辑器中，支持可视化零代码开发界面上的布局和组件。如下图：

然后创建用户 App 通用版，即可使用多平台的 App。

# 生成项目 SaaS

不同于 ThingsCloud 控制台，项目应用 SaaS 通用版是一个面向设备使用者的 Web 管理平台，我们来为本示例创建一个 SaaS 通用版。

创建项目应用，选择 SaaS 通用版。

创建成功后，会生成项目 SaaS 的专属登录地址，进入登录界面，如下图：

在设备列表中，可以看到控制台上创建的所有设备。

进入 DTU 设备，可以方便的查看数据和下发控制。