开发指南
IoT物联网手册

设备管理

# 1. 设备分组

设备分组，由 IotDeviceGroupController 提供接口。通过分组可以对设备进行分类管理，一个设备可以属于多个分组。

# 1.1 表结构

省略 creator/create_time/updater/update_time/deleted/tenant_id 等通用字段

CREATE TABLE `iot_device_group` (
  `id` bigint unsigned NOT NULL AUTO_INCREMENT COMMENT '分组 ID',
  `name` varchar(100) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '分组名字',
  `status` tinyint NOT NULL DEFAULT '0' COMMENT '分组状态',
  `description` varchar(1000) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '分组描述',
  PRIMARY KEY (`id`) USING BTREE
) ENGINE=InnoDB AUTO_INCREMENT=18 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='IoT 设备分组表';

都是一些信息字段，仅仅用于展示，没有什么特殊逻辑。

# 1.2 管理后台

对应 [IoT 物联网 -> 设备接入 -> 设备分组] 菜单，对应前端项目的 @/views/iot/device/group 目录。

管理后台 - 设备分组

# 2. 设备信息

设备信息，由 IotDeviceController 提供接口。

# 2.1 表结构

省略 creator/create_time/updater/update_time/deleted/tenant_id 等通用字段

CREATE TABLE `iot_device` (
  `id` bigint unsigned NOT NULL AUTO_INCREMENT COMMENT '设备 ID，主键，自增',
  `nickname` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '设备备注名称，供用户自定义备注',
  `serial_number` varchar(100) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '设备序列号',
  `pic_url` varchar(512) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '设备图片',
    
  `product_id` bigint unsigned NOT NULL COMMENT '产品 ID',
  `product_key` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '产品 Key',
  `device_type` tinyint unsigned NOT NULL DEFAULT '0' COMMENT '设备类型，参见 IotProductDeviceTypeEnum 枚举',

  `device_name` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '设备名称，在产品内唯一，用于标识设备',
    
  `device_secret` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '设备密钥，用于设备认证，需安全存储',

  `gateway_id` bigint unsigned DEFAULT NULL COMMENT '网关设备 ID，子设备需要关联的网关设备 ID',

  `group_ids` varchar(512) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '设备分组编号集合',

  `state` tinyint unsigned NOT NULL DEFAULT '0' COMMENT '设备状态，参见 IotDeviceStateEnum 枚举',
  `online_time` datetime DEFAULT NULL COMMENT '最后上线时间',
  `offline_time` datetime DEFAULT NULL COMMENT '最后离线时间',
  `active_time` datetime DEFAULT NULL COMMENT '设备激活时间',

  `latitude` decimal(10,6) DEFAULT NULL COMMENT '设备位置的纬度',
  `longitude` decimal(10,6) DEFAULT NULL COMMENT '设备位置的经度',
  
  `firmware_id` bigint DEFAULT NULL COMMENT 'OTA 固件编号',
  
  `config` varchar(1024) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '设备配置，JSON 格式',
  PRIMARY KEY (`id`) USING BTREE,
  UNIQUE KEY `uniq_device_name_product_id` (`device_name`,`product_id`) USING BTREE,
  KEY `idx_product_id` (`product_id`) USING BTREE,
  KEY `idx_gateway_id` (`gateway_id`) USING BTREE
) ENGINE=InnoDB AUTO_INCREMENT=83 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='IoT 设备表';

① nickname、serial_number、pic_url 等字段为设备的基本信息，主要用于展示。

② product_id 为产品 ID，关联 iot_product 表的 id 字段。product_key、device_type 等字段冗余存储了产品相关信息，方便查询和展示。

③ device_name 为设备名称，需在同一产品内唯一。

④ device_secret 为设备密钥，创建设备时自动生成。设备通过 ProductKey + DeviceName + DeviceSecret 三元组进行身份认证。

具体可见 IotDeviceService 的 #authDevice(...) 方法。

⑤ gateway_id 为网关设备 ID，仅「网关子设备」需要设置，关联所属网关设备的 id 字段。

详见《设备网关与子设备》。

⑥ group_ids 为设备分组编号集合，存储设备所属分组的 ID 列表，一个设备可以属于多个分组。

⑦ state 为设备状态，参见 IotDeviceStateEnum 枚举。online_time、offline_time、active_time 分别为最后上线时间、最后离线时间、设备首次激活时间。

详见「3. 设备状态」小节。

⑧ latitude、longitude 为设备的地理位置坐标。支持两种方式记录：

手动设置：在管理后台，通过地图选点的方式设置设备位置
设备上报：PROPERTY_POST 属性上报消息包含 GeoLocation 结构体属性（含 Longitude、Latitude 等字段，参考阿里云标准）时，系统自动提取并更新。具体可见 IotDevicePropertyServiceImpl 的 #extractAndUpdateDeviceLocation(...) 方法。

⑨ firmware_id 为 OTA 固件编号，关联 iot_ota_firmware 表的 id 字段。OTA 升级任务完成后，系统会自动更新设备的 firmware_id 为新固件的 ID。

详见《OTA 固件升级》。

⑩ config 为设备自定义配置，JSON 格式。可通过管理后台设置，并支持通过 CONFIG_PUSH 下行消息下发给设备。设备收到后可据此调整自身行为。

# 2.2 管理后台（列表）

对应 [IoT 物联网 -> 设备接入 -> 设备管理] 菜单，对应前端项目的 @/views/iot/device/device 目录。

管理后台 - 设备列表

支持「卡片视图」和「列表视图」两种展示模式，可以通过右上角的切换按钮进行切换。

# 2.3 管理后台（创建/更新）

点击【新增】按钮，弹出新增设备对话框。如下图所示：

管理后台 - 设备新增

# 2.4 管理后台（详情）

点击设备名称，进入设备详情页。详情页采用多 Tab 页签设计，对应前端项目的 @/views/iot/device/device/detail 目录。

管理后台 - 设备详情

# 2.4.1 设备信息 Tab

展示设备的基本信息，包括设备名称、所属产品、设备状态、设备密钥、上线/离线时间等。

# 2.4.2 物模型数据 Tab

展示设备上报的属性实时值，以及属性的历史数据变化趋势。

管理后台 - 设备详情 - 物模型数据

① 设备属性（运行状态），由 IotDevicePropertyController 提供接口。

最新值：由 #getLatestDeviceProperties(...) 方法提供，使用 DevicePropertyRedisDAO 从 Redis 读取（Key 为 device_property:{deviceId}）。
历史值：由 #getHistoryDevicePropertyList(...) 方法提供，使用 IotDevicePropertyDAO 从 yudao.iot.storage.type 选中的时序库读取（详见《功能开启》）：
- TDengine：每个产品一张超级表 product_property_{productId}，每个设备一张子表 device_property_{deviceId}
- IoTDB：每个产品一张表 product_property_{productId}，所有设备共用，通过 device_id TAG 区分设备

② 设备事件上报：由 IotDeviceMessageController 的 #getDeviceMessagePairPage(...) 方法提供，通过 method = thing.event.post 过滤，将请求与响应通过 requestId 配对展示。数据使用 IotDeviceMessageDAO 从选中时序库的 device_message 表读取：

TDengine：device_message 为超级表，每个设备一张子表 device_message_{deviceId}
IoTDB：device_message 为一张表，按 device_id 查询。注意，同一设备、同一毫秒后写入的消息会覆盖先写入的，配对时请求或响应可能缺失，详见《功能开启》

③ 设备服务调用：由 IotDeviceMessageController 的 #getDeviceMessagePairPage(...) 方法提供，通过 method = thing.service.invoke 过滤，同样将请求与响应配对展示，也是从选中时序库的 device_message 表读取。

# 2.4.3 子设备管理 Tab

仅「网关设备」显示此 Tab，用于管理挂载在该网关下的子设备。

详细可见《设备网关与子设备》。

# 2.4.4 设备消息 Tab

查看设备与平台之间的通信消息记录，包括上行和下行消息。

管理后台 - 设备详情 - 设备消息

由 IotDeviceMessageController 的 #getDeviceMessagePage(...) 方法提供，也是使用 IotDeviceMessageDAO 从选中时序库的 device_message 表读取。

# 2.4.5 模拟设备 Tab

模拟设备行为，可以模拟设备上报属性、触发事件、响应服务调用等，方便调试。

管理后台 - 设备详情 - 模拟设备

通过 IotDeviceMessageController 的 #sendDeviceMessage(...) 方法发送模拟消息。根据 method 参数的不同，模拟不同的设备行为：

thing.property.post 模拟属性上报
thing.event.post 模拟事件触发
thing.service.invoke 模拟服务调用

消息发送后，走正常的消息处理流程（MQ → 消息处理 → 存储），与真实设备上报行为一致。

# 2.4.6 设备配置 Tab

展示和修改设备的自定义配置（JSON 格式），支持将配置下发给设备。

管理后台 - 设备详情 - 设备配置

# 2.4.7 Modbus 配置 Tab

仅 Modbus 协议的设备显示此 Tab，用于配置 Modbus 连接参数和点位映射，包括寄存器地址、数据类型、读写操作等。

详细可见《设备接入（Modbus Client 模式）》和《设备接入（Modbus Server 模式）》。

# 2.4.8 设备影子 Tab

用于对比设备的期望状态（desired）与上报状态（reported），并支持下发期望状态、切换影子开关、重置影子。

详细可见《设备影子》。

# 3. 设备状态

版本说明

本节按单体项目 ruoyi-vue-pro (opens new window) 已提交的实现说明。微服务项目 yudao-module-iot-server 的设备状态代码尚未同步：当前仍按旧逻辑直接更新状态和时间，没有重复、乱序保护；离线检测不区分连接型与活跃型设备；网关也不上报存活标记。同步完成前，以实际代码为准。

设备状态由 IotDeviceStateEnum 枚举定义，对应 iot_device 表的 state 字段：

状态	值	说明
未激活	`0`	设备创建后的初始状态，从未上线过
在线	`1`	设备当前在线
离线	`2`	设备曾经上线过，当前离线

设备的上线、离线，统一通过 thing.state.update 状态消息处理，最终调用 IotDeviceService 的 #updateDeviceState(...) 方法更新。

# 3.1 上线与激活

设备在以下两种情况会上线：

① 连接型协议的设备，连接认证成功时，由网关发送上线消息；连接断开时，发送离线消息。其中，EMQX 协议依赖 EMQX Broker 的 client.connected、client.disconnected 连接事件。

② 设备处于「未激活」或「离线」时，平台收到它的任意一条有效业务上行（属性上报、事件上报等），会自动将其标记为在线，上线时间沿用这条消息的上报时间。具体可见 IotDeviceMessageSubscriber 的 #forceDeviceOnline(...) 方法。

注意，透传的原始报文在数据解析失败（脚本执行失败、超时、输出不合法等）被丢弃时，不会让设备上线。详见《消息透传与数据解析》。

active_time 激活时间，在设备第一次真正上线时写入，之后不再变化。管理后台创建、编辑设备，不会激活设备。

# 3.2 重复与乱序事件

设备断线重连、多网关节点、消息总线重投等场景下，状态消息可能重复或乱序到达。平台通过 online_time、offline_time 两个时间做保护，事件时间按秒比较和存储：

重复事件：已在线再收到上线、已离线再收到离线，状态不变，不会再次触发场景联动、数据流转。其中，网关连接的重复上线、较新的重复离线，会推进对应的最后上线或离线时间。
迟到事件：上线时间早于最后离线时间、或离线时间早于最后上线时间的事件，直接忽略。例如说，设备断线后很快重连，迟到的旧离线不会把设备重新标记为离线。
旧网关节点的离线：设备已经连接到其它网关节点时，原节点上旧连接的离线不生效。EMQX 协议除外，它的连接由 EMQX Broker 维护。

同一秒内的多个事件，按处理顺序决定先后。

# 3.3 离线检测

按照在线状态的判断方式，设备分为两类：

类型	协议	说明
连接型	MQTT、EMQX、TCP、WebSocket、Modbus Client、Modbus Server	在线状态由连接决定：连接即在线，断开即离线
活跃型	HTTP、CoAP、UDP，以及所有网关子设备	没有持久连接，有上行即在线，超过一定时间没有上行则离线

IotDeviceOfflineCheckJob 定时任务，负责检测超时的在线设备，并发送离线消息：

超时阈值 = keepAliveTime（默认 10 分钟）× keepAliveFactor（默认 1.5），即 15 分钟。定义在 YudaoIotProperties 类中，目前没有对应的 yaml 配置项，如需调整可修改它的默认值。
活跃型设备：最后一次上报距今超过阈值，即判为离线。
连接型设备：超过阈值后，还需要连接已经失效才判为离线，即所在网关的协议实例已停止（存活标记不存在）、或在设备上线后重启过。在网关存活标记正常续期的前提下，连接还在、只是长时间没有业务消息的设备，不会被判离线。存活标记的说明，可见《设备接入（概述）》。
EMQX 协议的设备不使用网关存活标记，以 EMQX Broker 的连接事件为准。
离线时间 = 最后一次上报时间 + 超时阈值。如果期间设备重新上线，这条离线不会生效。

注意：离线检测的定时任务，需要手动配置！！！

微服务项目中，该定时任务基于 XXL-Job 实现，JobHandler 为 deviceOfflineCheckJob，运行在 iot-server 服务中。需要先参考《定时任务》搭建 XXL-Job 调度中心、将 iot-server 添加为执行器，再在 XXL-Job 的 [任务管理] 菜单中新增该任务（例如说 CRON 0 * * * * ? 每分钟执行）并启动。

注意，application-local.yaml 默认 xxl.job.enabled: false 关闭了调度。未配置时，活跃型设备不会自动离线，连接型设备在网关宕机后也不会被标记为离线。

# 3.4 状态变化的处理

设备状态真正变化时，平台在同一个数据库事务中，更新设备状态，并执行场景联动、数据流转。其中规则匹配、配置读取等数据库、Redis 数据访问出现异常时，状态更新一起回滚，异常交给消息总线处理。

发往外部的 HTTP、MQ 等推送，失败时沿用原有的日志记录处理；已经发出的操作，也无法随数据库事务撤销。

网关设备离线时，网关的状态事务提交后，平台再为它下面仍在线的子设备逐个发送离线消息，离线时间沿用网关的离线时间。每个子设备独立处理，某个子设备处理失败时只记录日志，不影响已经生效的网关离线，也不影响其它子设备。详见《设备网关与子设备》。

具体可见单体项目 IotDeviceMessageServiceImpl 的 #processStateUpdateMessage(...) 方法。

← 产品管理物模型配置→