单个添加物模型

使用限制

• MQTT型实例下不支持物模型功能，无法添加物模型。

• 物模型需要在模块中配置，每个产品中默认模块和自定义模块总个数不能超过200个。

• 如果产品已发布，不能编辑物模型。如需编辑物模型，需先撤销产品发布。

• 可以编辑物模型历史版本，生成新的版本。

• 同一物模型最多保存最近的10个版本，多余的历史版本将被覆盖。

• 物模型编辑后，需发布才会正式生效。

定义物模型的更多使用限制，请参见使用限制。

添加自定义模块

当您需要不同模块管理物模型功能时，可添加自定义模块管理不同业务场景的物模型功能。

1. 登录物联网平台控制台。

2. 在控制台左上方，选择物联网平台所在地域。

3. 在实例概览页签的全部环境下，找到对应的实例，单击实例卡片。

4. 在左侧导航栏，选择设备管理 > 产品。在产品列表中，单击产品对应操作列的查看。

5. 在产品详情页面，单击功能定义页签，然后单击前往编辑草稿。

6. 单击添加图标，完成参数配置，单击确认。

   参数	说明
   模块名称	支持中文、英文字母、日文、数字和下划线（_），长度限制为4～30个字符，一个中文、一个日文算1个字符。
   模块标识符	模块唯一标识符，也是模块ID，在产品中具有唯一性。支持英文大小写字母、数字和下划线（_），长度限制为30个字符。
   模块描述	输入文字，对模块进行说明或备注。长度限制为4096个字符。

   添加自定义模块后，如果没有添加物模型并发布上线，返回功能定义页签，左侧模块列表不会展示该自定义模块。

添加物模型功能

1. 在产品详情页面，单击功能定义页签，然后单击前往编辑草稿，单击默认模块或添加模块。

2. 可选：从历史版本下拉菜单选择要编辑的历史版本，再单击恢复此版本，在历史版本的基础上编辑草稿。

3. 添加标准功能。如果您创建产品时选择了标准品类，则物联网平台已为该品类预定义标准功能。

   标准功能分为必选和可选，使用如下：

   • 必选功能：已在物模型的默认模块中添加且不可删除。

   • 可选功能：单击添加标准功能，然后在弹出的双列表框左侧中，选择适用于该产品的标准功能。

     支持全选添加和全选删除。

     

   • 通用操作：您可单击功能对应操作列的编辑，修改标准功能定义。

     重要

     不支持修改标准功能的功能类型、标识符和数据类型。

4. 添加自定义功能。

   选择添加自定义功能。您可以为产品自定义属性、服务和事件。

   • 自定义属性：在添加自定义功能对话框，选择功能类型为属性。设置参数完成后，单击确认。

     属性参数设置说明如下表。

     参数	描述
     功能名称	属性的名称，例如：用电量。同一产品下功能名称不能重复。 支持中文、英文字母、日文、数字、短划线（-）、下划线（_）、正斜线（/）和英文句号（.），且必须以中文、英文、日文或数字开头，不超过30个字符。 输入功能名称时，将从标准功能库中筛选匹配的标准功能供您选择，您可以参考标准功能进行配置。 说明 当接入网关协议为Modbus时，不支持标准属性，仅支持自定义属性。
     标识符	属性唯一标识符，在产品中具有唯一性。即Alink JSON格式中的identifier的值，作为设备上报该属性数据的Key，云端根据该标识符校验是否接收数据。支持英文、数字和下划线（_），不超过50个字符，例如：PowerConsumption。 说明 不能用以下系统保留参数作为标识符：set、get、post、property、event、time、value。
     数据类型	int32：32位整型。需定义取值范围、步长和单位符号。 float：单精度浮点型。需定义取值范围、步长和单位符号。 double：双精度浮点型。需定义取值范围、步长和单位符号。 enum：枚举型。定义枚举项的参数值和参数描述，例如：1表示加热模式、2表示制冷模式。 bool：布尔型。采用0或1来定义布尔值，例如：0表示关、1表示开。 text：字符串。需定义字符串的数据长度，最长支持10240字节。 date：时间戳。格式为String类型的UTC时间戳，单位：毫秒。 struct：JSON对象。定义一个JSON结构体，新增JSON参数项，例如：定义灯的颜色是由Red、Green、Blue三个参数组成的结构体。不支持结构体嵌套。 array：数组。需声明数组内的元素类型、数组元素个数。元素类型可选择int32、float、double、text或struct，需确保同一个数组元素类型相同。元素个数，限制1~512个。 说明 当设备协议为Modbus时，无需设置该参数。
     取值范围	数据类型为int32、float、double时，可设置属性值的取值范围。
     步长	属性值变化的最小粒度。数据类型为int32、float、double时，可根据您的业务需要设置步长。 例如：为温度计产品定义温度属性时，将数据类型设置为int32，步长为2，单位为℃，取值范围0~100。即温度每变化两度，设备上报温度值，例如：0℃、2℃、4℃、6℃、8℃等。
     单位	单位可选择为无，或根据实际情况选择。
     读写类型	读写：请求读写的方法支持GET（获取）和SET（设置）。 只读：请求只读的方法仅支持GET（获取）。 说明 当接入网关协议为Modbus时，无需设置该参数。
     描述	输入文字，对该功能进行说明或备注。长度限制为100个字符。
     扩展描述	扩展描述为设备通信协议到标准物模型的映射关系。对应物模型TSL中的物模型扩展配置。 仅节点类型为网关子设备且接入网关协议为自定义、OPC UA或Modbus的产品，添加物模型属性时，显示且需填写该参数。 接入网关协议为自定义时，填写JSON格式的自定义配置信息，长度限制为1024个字符。 接入网关协议为OPC UA时，设置节点名称。节点名称需保证属性维度下唯一。 接入网关协议为Modbus时，需设置以下参数： 操作类型： 离散量输入（只读，0x02） 线圈状态（只读，0x01） 线圈状态（读写，读取使用0x01，写入使用0x05） 线圈状态（读写，读取使用0x01，写入使用0x0F） 线圈状态（只写，0x05） 线圈状态（只写，0x0F） 保持寄存器（只读，0x03） 保持寄存器（读写，读取使用0x03，写入使用0x06） 保持寄存器（读写，读取使用0x03，写入使用0x10） 保持寄存器（只写，0x06） 保持寄存器（只写，0x10） 输入寄存器（只读，0x04） 寄存器地址：十六进制，必须以0x开头，且限制范围是0x0~0xFFFF，例如：0xFE。 原始数据类型：支持int16、uint16、int32、uint32、int64、uint64、float、double、string、bool、bits。 比特位置：原始数据类型选择bits时的参数。选择数据对应的位置。 取值范围：这是原始数据经过缩放因子处理之后的取值范围。不在该取值范围内的数据会被丢弃。物联网平台已为各操作类型设置了默认取值范围： 线圈状态类型：0~1 离散量输入类型：0~1 保持寄存器类型：-2147483648~2147483647 输入寄存器类型：-2147483648~2147483647 交换寄存器内高低字节：是否把寄存器内16位数据的前后8个bit互换（byte1byte2 -> byte2byte1）。 true：互换。 false：不互换。 交换寄存器顺序：是否把原始数据32位数据的前后16个bit互换（byte1byte2byte3byte4 -> byte3byte4byte1byte2）。 true：互换。 false：不互换。 缩放因子：整型或浮点型数字，默认值为1，不可以为0，不可以为负数。 数据上报方式：可选按时上报和变更上报。

   • 自定义服务：在添加自定义功能对话框，选择功能类型为服务。设置参数完成后，单击确认。

     说明

     接入网关的协议选择为Modbus时，不支持定义任何服务。

     服务参数设置说明如下表。

     参数	描述
     功能名称	服务名称。支持中文、英文字母、日文、数字、短划线（-）、下划线（_）、正斜线（/）和英文句号（.），且必须以中文、英文、日文或数字开头，不超过30个字符。 输入功能名称时，将从标准功能库中筛选匹配的标准功能供您选择，您可以参考标准功能进行配置。
     标识符	服务唯一标识符，在产品下具有唯一性。即Alink JSON格式中该服务的identifier的值。支持英文、数字和下划线（_），不超过50个字符。 说明 不能用以下系统保留参数作为标识符：set、get、post、property、event、time、value。
     调用方式	异步：服务为异步调用时，云端执行调用后直接返回结果，不会等待设备的回复消息。 同步：服务为同步调用时，云端会等待设备回复；若设备没有回复，则调用超时。
     输入参数	设置该服务的入参，可选。 单击增加参数，在弹窗对话框中添加服务入参。 当接入网关协议为OPC UA时，需设置参数索引，用于标记参数的顺序。 说明 不能用以下系统保留参数作为输入参数的标识符：set、get、post、property、event、time、value。 您可以使用某个属性作为入参，也可以自定义参数。例如：在定义自动喷灌服务功能时，将已定义的属性喷灌时间和喷灌量作为自动喷灌服务的入参，则调用该参数时传入这两个参数，喷灌设备将按照设定的喷灌时间和喷灌量自动进行精准灌溉。 一个服务最多支持定义20个入参。
     输出参数	设置该服务的出参，可选。 单击增加参数，在弹窗对话框中添加服务出参。 当接入网关协议为OPC UA时，需设置参数索引，用于标记参数的顺序。 说明 不能用以下系统保留参数作为输出参数的标识符：set、get、post、property、event、time、value。 您可以使用某个属性作为出参，也可以自定义参数，例如：将已定义的属性土壤湿度作为出参，则云端调用自动喷灌服务时，将返回当前土壤湿度的数据。 一个服务最多支持定义20个出参。
     扩展描述	扩展描述为设备通信协议到标准物模型的映射关系。对应物模型TSL中的物模型扩展配置。 仅节点类型为网关子设备且接入网关协议为自定义或OPC UA的产品，添加物模型时，显示且需增加扩展描述。 接入网关协议为自定义时，需传入JSON格式的自定义配置，长度不超过1024个字符。 接入网关协议为OPC UA时，设置节点名称。节点名称需保证服务维度下唯一。
     描述	输入文字，对该服务功能进行说明或备注。长度限制为100个字符。

   • 自定义事件：在添加自定义功能对话框，选择功能类型为事件。设置参数完成后，单击确认。

     说明

     接入网关的协议选择为Modbus时，不支持定义任何事件。

     事件参数设置说明如下。

     参数	描述
     功能名称	事件的名称。支持中文、英文字母、日文、数字、短划线（-）、下划线（_）、正斜线（/）和英文句号（.），且必须以中文、英文、日文或数字开头，不超过30个字符。 输入功能名称时，将从标准功能库中筛选匹配的标准功能供您选择，您可以参考标准功能进行配置。
     标识符	事件唯一标识符，在产品下具有唯一性。即Alink JSON格式中该事件的identifier的值，作为设备上报该事件数据的Key，例如：ErrorCode。 支持英文、数字和下划线（_），不超过50个字符。 说明 不能用以下系统保留参数作为标识符：set、get、post、property、event、time、value。
     事件类型	您可以针对不同的事件类型进行业务逻辑处理和统计分析。 信息：指设备上报的一般性通知，例如：完成某项任务。 告警：设备运行过程中主动上报的突发或异常情况，告警类信息，优先级高。 故障：设备运行过程中主动上报的突发或异常情况，故障类信息，优先级高。
     输出参数	该事件的出参。单击增加参数，在弹窗对话框中添加一个服务出参。您可以使用某个属性作为出参，也可以自定义参数。例如：将已定义的属性电压作为出参，则设备上报该故障事件时，将携带当前设备的电压值，用于进一步判断故障原因。 当接入网关协议为OPC UA时，需设置参数索引，用于标记参数的顺序。 说明 不能用以下系统保留参数作为输出参数的标识符：set、get、post、property、event、time、value。 一个事件最多支持定义50个出参。
     扩展描述	扩展描述为设备通信协议到标准物模型的映射关系。对应物模型TSL中的物模型扩展配置。 仅节点类型为网关子设备且接入网关协议为自定义或OPC UA的产品，添加物模型时，显示且需增加扩展描述。 接入网关协议为自定义时，需传入JSON格式的自定义配置，长度不超过1024个字符。 接入网关协议为OPC UA时，设置节点名称。节点名称需保证事件维度下唯一。
     描述	输入文字，对该事件功能进行说明或备注。长度限制为100个字符。

发布物模型

1. 单击功能定义的编辑草稿页面左下方的发布上线。控制台页面会弹出发布物模型上线？对话框。

2. 可选：单击添加发布备注，输入版本号和版本描述。

   参数	说明
   版本号	设置当前物模型版本号。后期可根据版本号管理物模型。 版本号支持英文字母、数字和英文句号（.），长度限制1～16个字符。
   版本描述	描述当前版本物模型。支持中文汉字、英文字母、日文、数字和特殊符号。长度限制为100个字符。一个中文汉字算一个字符；一个日文算一个字符。

3. 如果存在已上线的版本，则需要进行比对，确认新版本的修改点。

   单击比对结果，在比对结果对话框中查看修改点。确认无误后，单击确认查阅，回到发布物模型上线对话框，自动选中“确认已查看当前版本与线上版本的比对结果”前的复选框。

   如果不需要比对，您可直接手动选中“确认已查看当前版本与线上版本的比对结果”前的复选框。

4. 单击确定，完成物模型的发布。

   发布物模型成功后，会直接返回产品详情页面的功能定义页签，您可看到当前物模型的版本号和上线时间。

   

执行结果

物模型发布后，物联网平台为该产品生成正式版本的物模型。在产品详情页面的功能定义页签下，您可以：

• 单击物模型TSL，查看JSON格式的物模型TSL。

• 单击生成设备端代码，下载物联网平台根据您定义的功能生成的设备端代码，用于设备端物模型功能开发。

相关API

后续操作

产品下设备上报的物模型数据默认会自动写入热数据存储空间，您可根据实际业务需要，停止部分或全部物模型的热数据存储服务。具体内容，请参见关闭或开启物模型数据存储。

相关文档

• 修改或删除已添加的物模型模块或物模型属性、事件和服务，请参见修改和删除物模型。

• 批量导入物模型文件或直接复制其他产品物模型，请参见批量添加物模型。

• 通过物模型实现设备与物联网平台通信的使用说明，请参见设备使用物模型通信。