物模型简介
物模型是腾讯云物联网开发平台为同一类设备即产品定义的一套数字模型，通过属性、事件、行为三种功能类型对产品进行数字化描述。
功能类型 | 功能描述 |
属性 | 指设备在运行过程中的各类参数、状态数据。如温湿度传感器采集的温度、湿度值；电器类设备的开关状态值、车载设备采集的当前速度、经纬度值。属性支持读写和只读两类，读写表示该属性即可从设备端上报到平台也可从平台发起控制，只读表示该属性只从设备向平台上报。 |
事件 | 指设备运行时由设备发起需要用户业务系统感知的数据，包括信息、告警、故障三种事件类型。例如设备运行出现故障，需要将故障信息及故障发生时的相关数据发送到平台。 |
行为 | 指设备为应用提供的调用方法，用于业务发起请求，需要设备端处理完成后返回处理结果，业务系统能同步或异步获取结果的场景。例如： 停车场用户在支付完停车费后，系统需要立刻打开道闸放行，业务系统需要获取道闸的最终状态同步操作是否成功。 云打印场景用户下发打印行为后，行为的入参包含订单 ID、打印单据内容等，出参包括打印结果编码。 |
物模型类别
产品的功能包括标准功能、自定义功能及高级功能。
功能分类 | 功能描述 |
标准功能 | 标准功能是指腾讯云物联网平台提供的一些常用设备品类的物模型。用户可以根据需要选择使用或不使用这些功能。 |
自定义功能 | 自定义功能指腾讯云物联网平台提供的让用户自由定义产品物模型的功能。用户可以根据设备的规格特性自由创建、删除和编辑物模型功能。 |
高级功能 | 高级功能指腾讯云物联网为用户提供的增值服务功能，如实时音视频服务可应用于可视对讲、云广播实时喊话、一对多紧急呼叫场景；高级功能一般会自动生成对应的标准功能。 |
操作步骤
添加标准功能物模型
标准功能腾讯云物联网预设品类默认的物模型定义以及高级功能对应的默认物模型。
1. 登录 物联网开发平台，进入实例列表页，选择已生成的公共实例。
2. 单击企业实例，进入实例内页，单击左侧菜单中的产品开发，进入产品列表，并选择某个“产品”，进入物模型定义。
3. 单击标准功能标签页的添加标准功能。
4. 其他产品品类为用户所选择品类的同一级品类的系统预设物模型，用户可以按需选择添加，确定后选择的物模型将会添加到“自定义功能”中。
自定义添加物模型属性
自定义功能允许用户根据设备规格自由定义物模型，赋予用户充分的自由权来进行定义。
1. 登录 物联网开发平台，进入实例列表页，选择已生成的公共实例。
2. 单击公共实例，进入实例内页，单击左侧菜单中的产品开发，进入产品列表，并选择某个“产品”，进入物模型定义。
3. 单击自定义功能标签页的添加自定义功能按钮。
4. 在弹出窗口中按需选择“功能类型”。例如照明类产品会有个属性开关，则功能名称输入“开关”、标识符必须在该产品下所有物模型中保持唯一，选择数据类型即可保存。
自定义添加物模型事件
1. 登录 物联网开发平台，进入实例列表页，选择已生成的公共实例。
2. 单击公共实例，进入实例内页，单击左侧菜单中的产品开发，进入产品列表，并选择某个“产品”，进入物模型定义。
3. 单击自定义功能标签页的添加自定义功能按钮。
4. 在弹出窗口中按需选择事件，再次选择“事件类型”为“信息”，用户可自由定义设备向物联网平台发生的事件信息。
自定义添加物模型行为
1. 登录 物联网开发平台，进入实例列表页，选择已生成的公共实例。
2. 单击公共实例，进入实例内页。单击左侧菜单中的产品开发，进入产品列表，并选择某个“产品”，进入物模型定义。
3. 单击自定义功能标签页的添加自定义功能按钮。
4. 在弹出窗口中按需选择行为。
在自助零售、共享支付或停车场景中，常需在支付完成后通过物联网平台让业务系统立即执行开门、开锁或开闸等操作。这要求业务系统能实时接收到设备端的处理结果。若未能及时响应，业务系统需对该交易进行取消处理，例如发起退款。
5. 在功能名称录入对应的行为名称及参数。请求参数需要由用户定义，返回参数是设备侧执行完之后上报到物联网平台的参数。
例如，功能名称为“开锁”，标识符为“Open”。请求参数自定义一个订单 ID 的字符串类型，这样业务系统可以跟踪到每笔订单在设备侧的处理情况；返回参数也可以添加订单 ID 以及设备最终开锁状态结果的字段 code，如果开锁成功，则返回 code 为0，失败则为1。当业务系统接收到 code 为1时，则要么在业务允许的情况下重试，若已支付完成重试多次失败后则发起退款操作。
添加高级功能物模型
查看物模型 JSON
1. 添加完标准功能、自定义功能后，用户可以单击查看物模型JSON，来查看物模型对应的 JSON 格式。
2. 如下图所示，用户可以复制或下载 JSON 物模型。可以通过“导入物模型”功能，将复制的 JSON 用于产品间物模型定义的复制。
导入物模型
1. 复制完某个产品的物模型 JSON 后，单击导入物模型，将复制的 JSON 粘贴到文本框中。
2. 然后单击导入，将覆盖原产品的物模型。注意，若是已量产的产品需要慎用物模型导入功能。
物模型格式参考
以下为智能灯的物模型 JSON 描述说明，包括各种数据类型和事件类型。示例 JSON 如下：
{"version": "1.0","profile": {"ProductId": "2300UMK31M","CategoryId": "3"},"properties": [{"id": "power_switch","name": "电灯开关","desc": "控制电灯开灭","required": true,"mode": "rw","define": {"type": "bool","mapping": {"0": "关","1": "开"}}},{"id": "color","name": "颜色","desc": "灯光颜色","mode": "rw","define": {"type": "enum","mapping": {"0": "Red","1": "Green","2": "Blue"}}},{"id": "brightness","name": "亮度","desc": "灯光亮度","mode": "rw","define": {"type": "int","unit": "%","step": "1","min": "0","max": "100","start": "1"}},{"id": "name","name": "灯位置名称","desc": "灯位置名称：书房、客厅等","mode": "rw","required": false,"define": {"type": "string","min": "0","max": "64"}}],"events": [{"id": "status_report","name": "DeviceStatus","desc": "Report the device status","type": "info","required": false,"params": [{"id": "status","name": "running_state","desc": "Report current device running state","define": {"type": "bool","mapping": {"0": "normal","1": "fault"}}},{"id": "message","name": "Message","desc": "Some extra message","define": {"type": "string","min": "0","max": "64"}}]},{"id": "low_voltage","name": "LowVoltage","desc": "Alert for device voltage is low","type": "alert","required": false,"params": [{"id": "voltage","name": "Voltage","desc": "Current voltage","define": {"type": "float","unit": "V","step": "1","min": "0.0","max": "24.0","start": "1"}}]},{"id": "hardware_fault","name": "Hardware_fault","desc": "Report hardware fault","type": "fault","required": false,"params": [{"id": "name","name": "Name","desc": "Name like: memory,tf card, censors ...","define": {"type": "string","min": "0","max": "64"}},{"id": "error_code","name": "Error_Code","desc": "Error code for fault","define": {"type": "int","unit": "","step": "1","min": "0","max": "2000","start": "1"}}]}],"actions": [{"id": "unlock","name": "开灯行为检测","desc": "用于描述开灯的动作","input": [{"id": "open","name": "开关","define": {"type": "bool","mapping": {"0": "关","1": "开"}}},{"id": "user","name": "用户","define": {"type": "string","min": "0","max": "2048"}}],"output": [{"id": "user","name": "用户","define": {"type": "string","min": "0","max": "2048"}},{"id": "time","name": "开灯时间","define": {"type": "timestamp"}},{"id": "state","name": "灯的状态","define": {"type": "bool","mapping": {"0": "关","1": "开"}}}],"required": false}]}
相关文档
了解物模型协议，请参考 物模型协议。
查看设备属性、事件、行为可参考 设备调试 内容。
