设备属性、事件和命令怎么区分？从一台水泵看懂功能定义

设备接入平台时，平台需要先知道一件事：这台设备能做什么？它能提供哪些数据、能执行哪些操作，都要先描述清楚，平台才能正确展示数据、保存记录和下发控制。

在 ThingsCloud 中，这个描述就是设备类型的功能定义，其中最常用的是属性、事件和命令三类功能。以一台水泵为例：接入平台后，你可能想知道出口压力是多少、水泵有没有运行、刚才为什么停机，也可能希望远程发起一次复位。

这些需求看起来都与设备有关，但表达方式有所不同。不用先记住复杂术语，我们从水泵的几个日常问题开始。

先用三个问题区分

属性、事件和命令，分别对应三类日常需求：

例如，“水泵当前处于故障状态”可以用属性展示；“水泵刚发生了一次过载”则可以用事件通知平台。两者可以配合使用，分别帮助人看清当前状态和发生过的事情。

属性：页面上经常看到的设备数据

温度、压力、水位、电量和开关状态，都可以是属性。对于水泵，你可以先关注出口压力、实际运行状态和故障状态。

ThingsCloud 会保存属性的当前值和历史值。当前值用来看“现在怎么样”，历史数据用来回看变化。比如发现供水压力偏低后，可以打开 设备属性时序图表，查看压力从什么时候开始下降。

有些属性来自设备，例如传感器测到的压力；有些属性可以由用户设置，例如希望设备保持的目标压力。在配置时，按真实用途选择哪些数据允许上报、哪些允许下发即可。详细区别可以在用到时查阅 属性类型文档。

一个值得记住的区别是：按下“启动”与水泵真正运行，是两件事。 页面上的运行状态应来自设备实际反馈。即使启动请求已经发出，也要等设备反馈后，才能确认水泵是否运行。

事件：告诉平台发生过一件事

假设水泵控制器检测到过载，可以向平台发出一次事件，同时带上故障原因、当时的电流等信息。以后排查时，这些放在一起的信息比一个简单的“有故障”更容易理解。

门被异常打开、设备完成自检，也适合用事件表达。事件强调的是某件事发生过；属性则方便持续展示当前状态。属性同样有历史记录，所以选择哪一种，主要看你希望怎样使用这条信息。

事件需要设备或控制器提供相应的上报能力。准备接入时，可以让开发或设备供应商参照 功能定义文档配置事件。

命令：让设备执行一次操作

远程复位、重启和开始自检，都属于“一次操作”，适合用命令表达。设备收到命令后，再由自己的程序完成对应处理。

命令与修改属性有什么区别？可以这样看：

• 设置目标压力：告诉设备以后按什么目标工作，适合修改属性。
• 执行一次复位：要求设备现在处理一件事，适合使用命令。

实际操作还要看设备是否支持。平台发出了复位命令，不代表设备一定允许复位，也不代表故障已经解除。需要由设备返回结果，或通过新的状态数据确认。

设备开发人员可以在 MQTT 接入文档中查到事件上报、命令接收和结果回应的消息格式。日常使用平台时，先理解这些操作各自做什么就足够了。

自定义数据流，什么时候会用到？

属性、事件和命令之外，接入设备时还可能遇到数据格式的问题。有些设备上传的数据不能直接作为平台属性使用。例如，一台工业仪表使用厂家规定的通信格式，平台需要先把它转换成能看懂的温度、压力等数据。

自定义数据流可以理解成传送这类原始数据的通道。配置好转换方法后，日常查看页面仍然使用温度、压力这些熟悉的属性，不需要每次都读原始数据。

例如，使用 Modbus RTU 协议的仪表，可以通过 DTU（一种连接仪表与云平台的通信设备）把数据送到平台，再按仪表手册配置转换。你可以将这个过程理解为：

仪表发来数据 → 平台按配置识别 → 显示为压力等属性 → 用于看板和告警

是否需要这一步，取决于设备的接入方式。如果设备已经按 ThingsCloud 的标准方式上报属性，就不必为了使用平台而额外创建自定义数据流。需要对接非标准消息时，再查阅 自定义数据流文档；使用工业仪表时，可继续看 Modbus 寄存器设置。

第一次配置，先把常用功能列出来

仍以水泵为例，第一版可以先整理这些内容：

先确认设备能提供哪些功能，再到 设备类型的功能定义中添加。填写时给数据起清楚的名称，选好单位和类型；具体选项可参考 数据类型文档。

最后用一台真实设备检查：读数是否正确、故障能否看见、操作后有没有真实反馈。没有用到的功能可以以后再加，不必第一次就把设备手册中的全部内容搬进平台。

把数据整理清楚，后面的应用就容易搭

当压力、运行状态和故障信息都有清楚的含义后，就可以把它们放到看板里，配置异常提醒，或在手机上查看。后续增加同款设备，也可以继续使用这套定义。

初次上手，可以先完成“看到一个读数、查看一段历史、识别一次异常”。等设备用顺之后，再扩展远程操作和更多功能。