4. 云平台设备模型与物模型设计
在农业物联网云平台中，设备接入只是第一步。平台真正要理解的是：这台设备是什么、能上报哪些数据、数据代表什么含义、平台能否向它下发指令。解决这一问题的核心机制就是物模型（Thing Model）。可以把物模型理解为设备在云端的“数字化说明书”：它用统一的结构描述设备的属性、事件和服务，使平台不必为每一款硬件单独写解析逻辑，从而实现设备的标准化接入与统一管理。
物模型的三要素：属性、事件、服务
物模型通常由三类要素构成，它们分别对应设备“有什么状态”“发生了什么”“能做什么”。
- 属性（Property）：描述设备可被读取或设置的状态量，如土壤含水率、空气温度、阀门开关状态。属性一般具有数据类型、取值范围、单位、读写权限和采集频率等元数据。
- 事件（Event）：描述设备主动上报的、具有时间意义的通知，如“低电量告警”“传感器故障”“灌溉完成”。事件通常包含事件标识、级别和输出参数。
- 服务（Service）：描述平台可向设备调用的能力，如“开启灌溉”“校准传感器”“设置上报周期”。服务由输入参数、输出参数和调用方式组成。
三者的区别可以用一句话概括：属性是“状态快照”，事件是“时间点上的通知”，服务是“可被调用的动作”。在建模时若混淆三者，后续的数据解析和指令下发都会出现问题。例如把“灌溉完成”建成属性，平台就只能轮询状态而无法获得带时间戳的完成通知；把“设置上报周期”建成属性，则难以表达参数校验和调用结果。
农业设备物模型建模方法
建模的基本流程是：先梳理设备的物理量与应用需求，再为每个量选择正确的要素类型，最后补齐数据类型、单位、范围与标识符。下面以三类典型设备说明。
土壤墒情传感器通常包含多层土壤含水率、土壤温度、电导率等测量量。这些量适合建为只读属性，例如标识符 soil_moisture_20cm，数据类型为 float，单位 %，范围 0～100，读写权限为只读。设备电量、信号强度也建为属性。若设备支持远程校准，则建一个服务 calibrate，输入为校准点数量与标准值，输出为校准结果码。传感器探头断线属于异常，应建为事件 probe_fault，输出参数为探头编号。
气象站测量量更多，包括空气温度、湿度、风速、风向、降雨量、光照度、大气压等。建模时要注意单位统一，例如风速用 m/s、降雨量用 mm、光照度用 lux。风向是 0～360 度的角度量，需在描述中说明正北为 0 度、顺时针增加。气象站常带加热除霜功能，可建服务 set_heater，输入为开关布尔值。降雨量突增或风速超限可建为事件，便于平台触发告警。
灌溉控制器兼具状态与动作。阀门开关、当前灌溉模式、剩余灌溉时长建为属性，其中阀门开关可设为读写，允许平台远程置位。开启灌溉建为服务 start_irrigation，输入包括阀门编号、时长（分钟）、流量上限；停止灌溉建为服务 stop_irrigation。灌溉完成、管路压力异常建为事件。这里的关键是：动作必须建为服务而非属性，因为服务能携带参数并返回执行结果，而属性写入无法表达“执行了多久、是否成功”。
物模型与数据解析的映射关系
设备真实上报的往往是紧凑的二进制帧或自定义 JSON，物模型的价值在于建立“原始报文—标准属性”的映射。以常见的 Modbus 上报为例，设备上传寄存器值 0x0A8C（十进制 2700），物模型中定义 soil_moisture_20cm 的缩放系数为 0.01、单位 %，则解析结果为 27.00%。这一映射关系包含三层：字段定位（第几个寄存器/哪个 JSON 键）、数值转换（缩放、偏移、字节序）、语义绑定（对应哪个属性标识符及单位）。
事件与服务同样需要映射。事件映射把报文中的告警码转换为事件标识符和级别；服务映射则把平台下发的 JSON 参数转换为设备可识别的指令帧。下图展示了从设备原始数据到物模型要素、再到平台应用的完整映射链路。
实际配置时，解析规则通常以脚本或映射表形式存在。例如在平台的数据解析节点中填写：源字段 reg[2]、缩放 0.01、目标属性 soil_moisture_20cm。若设备更换型号，只需调整映射表而无需改动上层业务逻辑，这正是物模型解耦硬件与应用的工程价值。
建模中的常见问题与判断依据
第一，单位与量纲不统一。同一平台内温度有的用摄氏度、有的用开尔文，会导致告警阈值失效。应在物模型元数据中强制写明单位，并在解析层完成统一换算。第二，读写权限设置错误。把只读测量量设为可写，可能被误下发覆盖真实值。第三，事件与属性混用。判断依据是：该信息是否需要保留发生时刻并主动通知？是则建事件，否则建属性。第四，服务缺少结果返回。灌溉服务若只下发不返回执行结果，平台无法判断指令是否生效，应定义输出参数如 result_code 与 actual_duration。
验证物模型是否正确，可采用“三查”方法：查属性能否被完整解析且数值落在合理范围（如含水率 27% 而非 2700）；查事件能否在触发条件下按时上报并带正确级别；查服务下发后设备是否返回预期结果码。以灌溉为例，平台调用 start_irrigation 输入阀门 1、时长 10 分钟，若返回 result_code=0 且属性 valve_status 在数秒内变为开启，则说明服务映射与状态回传链路均正常。通过这样的闭环验证，物模型才真正成为设备与平台之间可靠的语言。