功能定义

更新时间:2024-06-20 04:35:32下载pdf

本文介绍如何为生态设备接入 (TuyaLink) 方式创建的产品进行功能定义。

概念说明

物模型

物模型是 涂鸦开发者平台 针对物理实体设备在云端建立的数据模型,主要用于描述产品的功能。物模型通过定义一款产品设备所应具备的功能属性、动作功能、事件来表示一个物理实体设备,在云端的数据展现。

功能类型 说明 适用场景
属性 定义设备具有持续性、可查询等特点的状态,它代表设备的某个或者某几个功能参数。 属性通过设置读写操作,来实现对设备功能参数的修改和查询。当设备本身的某项功能参数发生变更,设备也可以主动修改属性。例如灯的亮度、开关状态等。
动作 用于控制设备执行复杂的业务功能。动作不涉及设备属性变更的控制指令。 需要设备响应指令,从而对外提供一个可供用户调用的方法。例如人脸识别、照片下发等。
事件 是设备上报的瞬时通知消息,可以包含多个输出参数,需要被外部感知和处理。 事件通常搭配数据订阅服务,或者与规则引擎结合,对事件信息作出业务逻辑上的处理,以满足特定的功能。例如水温报警、故障报警等。

目前,物模型信息是按需获取机制,请在合适的时机检查物模型本地缓存,并在适当的时候获取并更新物模型缓存。

标准功能和自定义功能

  • 标准功能:指由涂鸦开发者平台开放的标准功能点模板库,开发者可快速选择完成产品功能定义。 模板库包含 1000+ 产品品类的常见功能定义。

  • 自定义功能:指开发者可以根据需求进行个性化功能定义,支持多种功能类型和数据类型的定义,满足各种产品开发定义场景。

前提条件

您已经拥有至少一个使用 TuyaLink 自定义方案创建的产品。

操作步骤

第一步:进入功能定义页面

  1. 进入 产品开发页面,选择指定产品并单击操作栏中的 继续开发 按钮。

  2. 在顶部页签中选择 功能定义

    功能定义

第二步:添加标准功能点

添加标准功能。您可以根据自身需求选择所需要的标准功能。

功能定义
功能定义

第三步:添加自定义功能

如果在上述标准功能点中,无法找到合适的功能点,可通过添加自定义功能的方式个性化创建产品。

自定义功能点支持创建功能类型为属性、事件、动作的功能点,您可以根据当前开发产品的特性,定义需要具备的功能。

单击自定义功能栏对应的 添加功能 按钮,进入添加页面。

功能定义

功能类型有以下可选项:属性、事件、动作。根据不同功能类型选择,功能定义需要填写的内容不同,基本介绍如下:

  • 添加属性功能点
    属性功能点常用于描述产品具备的状态,例如灯的开关、运行模式,因为可定义范围较多,因此提供了丰富的数据类型。

    • 功能名称:产品所具有的功能命名。

    • 标识符:可用于您的功能函数定义,产品下唯一。

    • 数据类型:根据不同属性的特性,选择对应类型,一共有9种数据类型方式:数值型、字符型、时间型、布尔型、枚举型、透传型、结构型、数组型、故障型。

      功能定义

      属性定义示例

      数据类型 示例
      数值型(value) 如温度值,范围 1℃~100℃,设备上报数据为 36.6℃,定义如下:
      • 数值类型:数值型
      • 数值范围:1~1000
      • 间距:1
      • 倍数:1
      • 单位:℃
        其中倍数实现的目标是将上报为 1 的数据转化为 0.1,从而实现小数的作用,应用时需由设备端函数实现对倍数字段的应用,此处仅定义参数
      字符型(String) 如图片地址,主要为 URL 地址,定义如下:
      • 数据类型:字符型
      • 最大长度:50 字节
      时间型(Date) 如产品更新时间,设备主要通过时间戳上报和解析,定义如下:
      • 数据类型选择为时间型
      • 更新时间:1638853568 转化为时间则为 2021-12-07 13:06:08
      布尔型(Bool) 如开关,常包含开和关两种形态,定义如下:
      • 数据类型:布尔型
      • true 表示开,false 表示关
      枚举型(Enum) 如运行模式,常有多种:运动模式、个人模式、团队模式等,定义如下:
      • 数据类型选择为:枚举型
      • 枚举值:Sport_modePersonal_modeTeam_mode
      透传型(Raw) 如二进制码内容,不便于明文传递,定义如下:
      • 数据类型:透传型
        一般为平台接收后不做任何处理,传递给设备
      结构型(Struct) 如地理位置,同时具备多个数据内容,定义如下:
      • 数据类型:结构型
      • 添加参数(根据不同情况,选择不同数据类型)
        • 经度-数值型
        • 纬度-数值型
        • 高度-数值型、坐标系统-枚举值
          通过一个结构体的定义,完成地理位置的描述
      数组型(Array) 如灯光颜色,通过不同值展示不同内容,定义如下:
      • 数据类型:数组型
      • 元素类型:根据需求,选择不同数据类型,如数值
      • 元素个数:3 个
        一般灯光可以由 RGB 组成,不同组合可以叠加不同的颜色结果
      故障型(Fault) 如报警提示,通过特定条件上报指定信息,定义如下:
      • 数据类型选择为故障型
      • 故障值:温度过高、温度过低、温度报警
  • 添加事件功能点
    事件功能点常用于设备故障和告警上报,可通过定义功能上报的输出参数(一个或多个),来向云端传递信息,例如水温告警、消防报警等。

    功能定义
  • 添加动作功能点
    动作功能点主要用于描述产品具备的复杂功能,该功能具备输入和输出的功能定义。典型特点是消息的发送具备一应一答特点,常用于对功能有响应的场景。例如定义为开门,则开门动作完成后,会接收到确认已开门的消息,进而实现完整功能追踪。

    功能定义

综上所述,通过结合三种类型的功能定义,可以完整描述一个产品所具备的功能内容,即完成产品在云端的设备模型建立,实现物理实体与云端模型的解耦。硬件开发者和应用开发者可根据设备模型规范,分别进行开发,加速产品开发进程。

后续操作

完成功能定义后,可进行下一步骤 设备开发