为产品定义物模型
2025/10/12大约 3 分钟
为产品定义物模型
物联网平台支持为产品定义物模型,将实际产品抽象成由属性、服务、事件所组成的数据模型,便于物联网平台管理和数据交互。产品创建完成后,您可以为它定义物模型,产品下的设备将自动继承物模型内容。
前提条件
已完成产品创建。具体操作,请参见创建产品与设备。
物模型三要素
| 要素 | 说明 | 示例 |
|---|---|---|
| 属性 | 设备的状态或可设置的参数,支持读取与写入 | 温度 temperature、开关 Power |
| 事件 | 设备运行时主动上报的通告,多用于告警 | 过温告警 overTemp |
| 服务 | 平台可远程调用的设备能力 | 远程重启 reboot、设置功率 setPower |
操作步骤
- 在 物联网 > 产品管理 列表中,单击目标产品进入产品详情。
- 在物模型(TSL)编辑区域,分别添加属性、事件与服务。
添加属性
以温度属性为例:
| 字段 | 示例取值 | 说明 |
|---|---|---|
| 功能名称 | 温度 | 展示用 |
| 标识符 identifier | temperature | 设备上报数据时使用的键名,必须与报文中的 JSON 键完全一致 |
| 读写类型 | 读写 | 只读:仅设备上报;只写:仅平台下发;读写:均可 |
| 数据类型 | double | 决定平台对上报值的校验规则 |
| 取值范围 / 步长 / 单位 | -40 ~ 85,0.1,℃ | 可选,用于展示与校验 |
添加事件
以过温告警为例:标识符 overTemp,事件类型选择告警,添加输出参数 temperature(double)。
添加服务
以设置功率为例:标识符 setPower,调用方式选择同步或异步:
- 同步:平台下发后等待设备回复(10 秒超时),设备需把响应发布回收到消息的同一个 Topic。
- 异步:平台下发后不等待回复,设备执行结果通过属性上报或事件上报反馈。
添加输入参数 Power(enum:0-关、1-开)、输出参数 result(text)。
标识符命名规则
- 字母开头,仅包含字母、数字、下划线,后台表单最长 32 字符。
- 不能使用保留字:
set、get、post、property、event、time、value。 - 属性、事件、服务标识符在同一产品内唯一。
数据类型
| 类型 | 上报值要求 | 示例 |
|---|---|---|
| int32 | 整数 | 23 |
| float / double | 必须带小数点 | 23.5(传 23 会被拒绝) |
| enum | 枚举编号(整数) | 1 |
| bool | 布尔值 | true |
| text | 字符串 | "on" |
| date | 字符串 yyyy-MM-dd HH:mm:ss.SSS | "2026-10-25 10:00:00.000" |
| struct | JSON 对象 | {"lat": 30.5} |
| array | JSON 数组 | [1, 2, 3] |
geopoint 类型当前校验实现存在缺陷,上报会恒定失败,请改用 text 承载坐标,详见 MQTT设备接入已知限制。
自定义模块(可选)
一个产品可划分多个功能模块(block),便于管理大量功能。在产品详情的物模型模块中新建模块(如 MCU)后,该模块下的功能标识符在上报时写作 {block}:{identifier},例如 MCU:fwVersion;默认模块不带前缀。
下一步
物模型定义完成后,使用 MQTT 客户端模拟设备接入平台并上报数据,参见使用 MQTT.fx 接入平台。