单个添加物模型,即单个添加属性、事件和服务。下面介绍如何在物联网平台控制台定义物模型。

背景信息

  • 如果产品已发布,不能编辑物模型。如需编辑物模型,需先撤销产品发布。
  • 可以编辑物模型历史版本,生成新的版本。
  • 同一物模型最多保存最近的10个版本,多余的历史版本将被覆盖。
  • 物模型编辑后,需发布才会正式生效。

操作步骤

  1. 登录物联网平台控制台
  2. 在左侧导航栏,选择设备管理 > 产品
  3. 产品页面产品列表中,单击产品对应的查看操作按钮。
  4. 产品详情页,单击功能定义页签,再单击编辑草稿
  5. (可选)从历史版本下拉菜单选择要编辑的历史版本,再单击恢复此版本,在历史版本的基础上编辑草稿。
  6. 添加标准功能。如果您创建产品时选择了标准品类,则物联网平台已为该品类预定义了标准功能。选择添加标准功能,然后在弹出的双列表框中,选择适用于该产品的标准功能。
    添加标准功能
  7. 添加自定义功能。

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

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

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

      参数 描述
      功能名称

      属性的名称,例如用电量。同一产品下功能名称不能重复。

      支持中文、大小写字母、数字、短划线和下划线,且必须以中文、英文或数字开头,不超过30个字符。

      输入功能名称时,将从标准功能库中筛选匹配的标准功能供您选择,您可以参考标准功能进行配置。

      说明 当接入网关协议为Modbus时,不支持标准属性,仅支持自定义属性。
      标识符 属性唯一标识符,在产品中具有唯一性。即Alink JSON格式中的identifier的值,作为设备上报该属性数据的Key,云端根据该标识符校验是否接收数据。可包含英文、数字、下划线,长度不超过50个字符,例如PowerComsuption。
      说明 不能用以下系统保留参数作为标识符:set、get、post、time、value。
      数据类型
      • int32:32位整型。需定义取值范围、步长和单位符号。
      • float:单精度浮点型。需定义取值范围、步长和单位符号。
      • double:双精度浮点型。需定义取值范围、步长和单位符号。
      • enum:枚举型。定义枚举项的参数值和参数描述,例如1-加热模式、2-制冷模式等。
      • bool:布尔型。采用0或1来定义布尔值,例如0-关;1-开。
      • text:字符串。需定义字符串的数据长度,最长支持2048字节。
      • date:时间戳。格式为String类型的UTC时间戳,单位:毫秒。
      • struct:JSON对象。定义一个JSON结构体,新增JSON参数项,例如定义灯的颜色是由Red、Green、Blue三个参数组成的结构体。不支持结构体嵌套。
      • array:数组。需声明数组内的元素类型、数组元素个数。元素类型可选择int32floatdoubletextstruct,需确保同一个数组元素类型相同。元素个数,限制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时,需设置以下参数:
        • 操作类型:
          • 线圈状态(只读,01)
          • 线圈状态(读写,读取使用01,写入使用05)
          • 线圈状态(读写,读取使用01,写入使用0F)
          • 离散量输入(只读,02)
          • 保持寄存器(只读,03)
          • 保持寄存器(读写,读取使用03,写入使用06)
          • 保持寄存器(读写,读取使用03,写入使用10)
          • 输入寄存器(只读,04)
        • 寄存器地址:十六进制,必须以0x开头,且限制范围是0x0~0xFFFF,例如0xFE
        • 原始数据类型:支持int16、uint16、int32、uint32、int64、uint64、float、double、string、bool多种数据类型。
        • 取值范围:这是原始数据经过缩放因子处理之后的取值范围。不在该取值范围内的数据会被丢弃。物联网平台已为各操作类型设置了默认取值范围:
          • 线圈状态类型:0~1
          • 离散量输入类型:0~1
          • 保持寄存器类型:-2147483648~2147483647
          • 输入寄存器类型:-2147483648~2147483647
        • 交换寄存器内高低字节:是否把寄存器内16位数据的前后8个bit互换(byte1byte2 -> byte2byte1)。
          • true:互换。
          • false:不互换。
        • 交换寄存器顺序:是否把原始数据32位数据的前后16个bit互换(byte1byte2byte3byte4 -> byte3byte4byte1byte2)。
          • true:互换。
          • false:不互换。
        • 缩放因子:不能为0,默认为1,可以为负数。
        • 数据上报方式:可选按时上报变更上报
    • 自定义服务:在添加自定义功能对话框,选择功能类型为服务。设置参数完成后,单击确认
      说明 接入网关的协议选择为Modbus时,不支持定义任何服务。
      物模型

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

      参数 描述
      功能名称

      服务名称。

      支持中文、大小写字母、数字、短划线和下划线,且必须以中文、英文或数字开头,不超过30个字符。

      输入功能名称时,将从标准功能库中筛选匹配的标准功能供您选择,您可以参考标准功能进行配置。

      标识符 服务唯一标识符,在产品下具有唯一性。即Alink JSON格式中该服务的identifier的值。可包含英文、数字、和下划线,长度不超过30个字符。
      说明 不能用以下系统保留参数作为标识符:set、get、post、time、value。
      调用方式
      • 异步:服务为异步调用时,云端执行调用后直接返回结果,不会等待设备的回复消息。
      • 同步:服务为同步调用时,云端会等待设备回复;若设备没有回复,则调用超时。
      输入参数 设置该服务的入参,可选。

      单击新增参数,在弹窗对话框中添加服务入参。

      当接入网关协议为OPC UA时,需设置参数索引,用于标记参数的顺序。

      说明
      • 不能用以下系统保留参数作为输入参数的标识符:set、get、post、time、value。
      • 您可以使用某个属性作为入参,也可以自定义参数。例如在定义自动喷灌服务功能时,将已定义的属性喷灌时间喷灌量作为自动喷灌服务的入参,则调用该参数时传入这两个参数,喷灌设备将按照设定的喷灌时间和喷灌量自动进行精准灌溉。
      • 一个服务最多支持定义 20 个入参。
      输出参数 设置该服务的出参,可选。

      单击新增参数,在弹窗对话框中添加服务出参。

      当接入网关协议为OPC UA时,需设置参数索引,用于标记参数的顺序。

      说明
      • 不能用以下系统保留参数作为输出参数的标识符:set、get、post、time、value。
      • 您可以使用某个属性作为出参,也可以自定义参数,例如将已定义的属性土壤湿度作为出参,则云端调用自动喷灌服务时,将返回当前土壤湿度的数据。
      • 一个服务最多支持定义20个出参。
      扩展描述

      扩展描述为设备通信协议到标准物模型的映射关系。对应物模型TSL中的物模型扩展配置。

      子设备接入网关协议为自定义协议或OPC UA时,需增加扩展描述。

      当接入网关协议为自定义时,需传入JSON格式的自定义配置,长度不超过1024字符。

      当接入网关协议为OPC UA时,设置节点名称。节点名称需保证服务维度下唯一。

      描述 输入文字,对该服务功能进行说明或备注。长度限制为100字。
    • 自定义事件:在添加自定义功能对话框,选择功能类型为事件。设置参数完成后,单击确认
      说明 接入网关的协议选择为Modbus时,不支持定义任何事件。
      物模型

      事件参数设置说明如下表。

      参数 描述
      功能名称

      事件的名称。

      支持中文、大小写字母、数字、短划线和下划线,且必须以中文、英文或数字开头,不超过30个字符。

      输入功能名称时,将从标准功能库中筛选匹配的标准功能供您选择,您可以参考标准功能进行配置。

      标识符 事件唯一标识符,在产品下具有唯一性。即Alink JSON格式中该事件的identifier的值,作为设备上报该事件数据的Key,例如 ErrorCode。
      说明 不能用以下系统保留参数作为标识符:set、get、post、time、value。
      事件类型 您可以针对不同的事件类型进行业务逻辑处理和统计分析。
      • 信息:指设备上报的一般性通知,例如完成某项任务等。
      • 告警:设备运行过程中主动上报的突发或异常情况,告警类信息,优先级高。
      • 故障:设备运行过程中主动上报的突发或异常情况,故障类信息,优先级高。
      输出参数 该事件的出参。单击增加参数,在弹窗对话框中添加一个服务出参。您可以使用某个属性作为出参,也可以自定义参数。例如将已定义的属性电压作为出参,则设备上报该故障事件时,将携带当前设备的电压值,用于进一步判断故障原因。

      当接入网关协议为OPC UA时,需设置参数索引,用于标记参数的顺序。

      说明
      • 不能用以下系统保留参数作为输出参数的标识符:set、get、post、time、value。
      • 一个事件最多支持定义50个出参。
      扩展描述

      扩展描述为设备通信协议到标准物模型的映射关系。对应物模型TSL中的物模型扩展配置。

      子设备接入网关协议为自定义协议或OPC UA时,需增加扩展描述。

      当接入网关协议为自定义时,需传入JSON格式的自定义配置,长度不超过1024字符。

      当接入网关协议为OPC UA时,设置节点名称。节点名称需保证事件维度下唯一。

      描述 输入文字,对该事件功能进行说明或备注。长度限制为100字。
  8. 发布物模型。
    1. 单击页面左下方的发布上线按钮。
    2. (可选)在发布物模型对话框中,单击添加发布备注,输入版本号和版本描述。
      参数 说明
      版本号 设置当前物模型版本号。后期可根据版本号管理物模型。

      版本号支持英文字母、数字和点号(.),长度限制 1~16 个字符。

      版本描述 描述当前版本物模型。支持中文汉字、英文字母、数字和特殊符号。长度限制为100个字符。一个中文汉字算一个字符。
    3. 如存在已上线的版本,则需要进行对比,确认新版本的修改点。单击对比结果,在弹窗中查看修改点。确认无误后,单击确认查阅,回到发布物模型对话框,自动勾选“确认已查看当前版本与线上版本的对比结果”。
    4. 单击确定,发布物模型。
      说明
      • 发布后,物模型才会正式生效。
      • 同一物模型最多保存最近的10个版本,多余的历史版本将被覆盖。

执行结果

物模型发布后,物联网平台为该产品生成正式版本的物模型。在产品详情 页的功能定义页签下,您可以:
  • 单击物模型TSL,查看JSON格式的物模型TSL。
  • 单击生成设备端代码,下载物联网平台根据您定义的功能生成的设备端代码,用于设备端物模型功能开发。
说明 仅华东2(上海)地域支持生成设备端代码。