复合开关产品开发包

更新时间:2023-12-25 03:08:46下载pdf

本文描述一款基于 TuyaOS 平台开发的 Zigbee 复合场景开关 Demo。

概述

  • 支持开关功能。

    • 控制方式:
      • 设备按键本地控制。
      • App 面板远程控制。
    • 状态同步:设备状态(包括继电器、指示灯)和 App 面板状态保持同步。
    • 全开/全关:App 面板支持下发多路开关 DP,实现设备的全开、全关功能。
  • 支持指示灯状态设置。

    • 指示灯关闭:继电器指示灯关闭(常灭)。

    • 指示开/关状态:开关开、指示灯亮,开关关、指示灯灭,即开关和指示灯状态同步。

    • 指示设备位置:开关开、指示灯灭,开关关、指示灯亮,即开关和指示灯状态相反,用于在黑暗环境下提示设备所在位置。

    App 操作后,指示灯状态切换立即执行。

  • 支持继电器上电状态(总控)。

    • 断电:设备断电重新上电后,默认处于断电状态(继电器断开、负载灯灭)。
    • 通电:设备断电重新上电后,默认处于通电状态(继电器闭合、负载灯亮)。
    • 断电记忆:设备断电重新上电后,通/断电状态与断电前保持一致。
  • 支持分路继电器上电状态设置(分控)。

    上电状态设置(分控)适用于多路开关对应通道的继电器上电状态。每个开关通道均分以下 3 种状态:

    • 断电:设备断电重新上电后,默认处于断电状态(继电器断开、负载灯灭)。
    • 通电:设备断电重新上电后,默认处于通电状态(继电器闭合、负载灯亮)。
    • 断电记忆:设备断电重新上电后,通/断电状态与断电前保持一致。

    支持通过 App 面板自定义修改对应开关通道的上述 3 种上电状态。

    App 操作后,上电状态切换在下一次断电上电后执行。

  • 支持倒计时功能。

    设置一段时间,计时到点后,设备对当前设备开/关状态取反。即设备开时设置倒计时,计时到点后设备关。设备关时设置倒计时,计时到点后设备开。

    仅支持单次设置。多路开关时,每路开关可单独设置。

    当发生以下情况时,倒计时功能取消(清零):

    • 面板下发倒计时 DP 为 0。
    • 倒计时执行计时周期内,设备开/关状态发生改变,包括设备本地按键控制、App 面板远程控制、定时控制执行等。
    • 设备断电重新上电或者模组重启。

    设置倒计时开始执行后,设备每隔一段时间上报一次剩余时间,用于面板更新显示对应设备将在多久之后执行开启/关闭。

功能特点

  • 支持远程 on、off 和 toggle 命令控制开关,支持本地按键触发控制开关。
  • Zigbee 通信协议:使用 Zigbee 协议进行无线通信,确保可靠的数据传输和连接稳定性。
  • 按键功能:配备易于操作的按键,用于设备的配网和本地离网等功能。
  • 指示灯显示:配备指示灯,用于显示设备的连接状态和工作状态等。

操作及现象

  • 进行网络配对:

    • 长按设备上的配对按键 3 秒,设备将开启配网功能,网络指示灯开始快闪。

    • 此时可将传感器与网关进行配对,步骤参考 配网步骤

    • 配对成功时,设备网络指示灯熄灭,此时可在 App 页面看到此设备。

    • 配对失败时/超时后(时间默认 300 秒),设备网络指示灯停止闪烁,指示灯长亮。

  • 按键操作:

    • 短按时,按住按键,并在 2s 内释放,触发短按,对应继电器和指示灯会翻转。

    • 长按时,长按大于 2 秒并且短于 5 秒时,无反应。长按大于 5 秒,指示灯开始快闪并开启配网。

  • 网络指示灯显示:根据设备的状态和连接情况,指示灯会显示相应的指示信息。

    • 配网中,网络指示灯快闪。

    • 配网超时,网络指示灯熄灭。

    • 配网成功,网络指示灯长亮。

产品创建

关于产品创建流程,参考 产品创建

设备协议介绍

Zigbee 基本信息

参数 数值
Profile ID 0x0104
Device ID 0x0004

Endpoint 描述

Endpoint 描述
1 第一路开关端口号
2 第二路开关端口号

支持的 cluster

Input clusters(Server) Output clusters(Client)
Basic(0x0000) Over The Air Upgrade(0x0019)
Identify(0x0003) /
Group (0x0004) /
Scene (0x0005) /
OnOff (0x0006) /
TUYA common private cluster(0xE000) /
Tuya electrical private cluster(0xE001) /

支持的属性和命令

Basic cluster

Attributes

ID Name Data type Range Default
0x0000 ZCL Version uint8-0x20 0x00-0xff 0x03
0x0001 Application Version uint8 -0x20 0x00-0xff 例如,0b 01 00 0001 = 1.0.1,即 0x411.0.1。OTA 功能会用到该版本号,在 OTA 开始阶段,网关会读取 OTA 包的版本号推送给设备。在 OTA 成功重启后,网关会读取版本号来确定是否升级成功。只能往更高的版本升级。
0x0002 Stack Version uint8-0x20 0x00-0xff 0x02
0x0003 Hardware Version uint8-0x20 0x00-0xff 0x01
0x0004 Manufacturer Name string-0x42 0-32 bytes XXX…XXX(长度为 16 个字节,由 8 字节前缀和 8 字节的 PID 组成),0-7 bytes:_TZ3000_,8-16 bytes:PID(由产品经理在平台或者自助创建和提供)。该字段决定了手机 App 界面的 UI 和功能展现,如果对 PID 没有特殊要求,可采用默认 PID。
0x0005 Model Identifier string-0x42 0-32 bytes TS0726(接入涂鸦网关使用)
0x0007 Power Source enum8-0x30 0x00-0xff 0x01
0xFFFD Cluster Revision uint16-0x21 0x0000-0xffff 0x0001

Commands

ID Name Direction Description
0x00 Reset to Factory Defaults C->S 恢复出厂设置

On/Off cluster

Attributes

ID Name Data type Range Default
0x0000 OnOff bool-0x10
  • 0:Off
  • 1:On
0x00
0x4001 OnTime uint16-0x21 0-43200 0x0000
0x4002 OffWaitTime uint16-0x21 0-43200 0x0000
0x8002 上电状态设置-总控(涂鸦私有属性) enum8-0x30
  • 0:Off
  • 1:On
  • 2:掉电记忆
0x00
0x8001 指示灯状态设置(涂鸦私有属性) enum8-0x30
  • 0:Off
  • 1:状态指示(继电器开则亮)
  • 2:位置指示(继电器关则亮)
0x00

Commands

ID Name Direction
0x00 OFF C->S
0x01 ON C->S
0x00 Toggle C->S
0x03 On with timed off C->S

Tuya electrical private cluster

Attributes

ID Name Data type Range Default
0xD010 开关上电状态(分路) enum8-0x30
  • 0:Off
  • 1:On
  • 2:掉电记忆
0x00

DP 与 cluster 对应关系

DPID DP 含义 是否为标准指令 对应 Endpoint
1 场景 1 1
2 场景 2 2
17 场景 ID 组 ID 1
18 模式 1 1
24 开关 1 1
30 开关 1 倒计时 1
37 指示灯状态设置 1
38 上电状态设置-总控 1
39 开关 1 上电状态设置-分控 1

DP17 场景 ID/组 ID

命令方向 Cluster ID CMD / ATTR ID VALUE
下发 0xE000 (Tuya electrical common private cluster) 0xE1 Payload
上报 0xE000 (Tuya electrical common private cluster) 0xD004
  • 0:失败
  • 1:成功

Payload 格式:

网关下发 01 02 00 03,表示通道 1 的组 ID 是 0x0002,场景 ID 是 0x03

DP18 模式

命令方向 Cluster ID CMD/ATTR ID Value
下发 0xE000 (Tuya electrical common private cluster) 0xD020
  • 0:开关
  • 1:场景开关
上报 0xE000 (Tuya electrical common private cluster) 0xD020
  • 0:开关
  • 1:场景开关

DP24 开关 1

数据下发时,直接下发开,关和反转命令即可,上报需使用标准开关属性进行上报。

命令方向 Cluster ID CMD / ATTR ID VALUE
下发 0x0006:on/off
  • 0x00:off
  • 0x01:on
  • 0x02:toggle
/
上报 0x0006:on/off 0x0000:on/off
  • 0:off
  • 1:on

DP30 开关 1 倒计时

命令方向 Cluster ID CMD / ATTR ID VALUE
下发 0x0006:on/off 0x42:On with timed off Payload

Payload 格式:On/off Control:0x00,On time 和 Off Wait Time 的时间必须一样。例如,下发 60s 的本地倒计时命令,payload 内容为:

  • On/off Control:0x00

  • On time:0x003c

  • Off Wait Time:0x003c

DP38 上电状态设置-总控

命令方向 Cluster ID CMD / ATTR ID VALUE
下发 0x0006:on/off 0x8002(涂鸦私有属性)
  • 0:Off
  • 1:On
  • 2:掉电记忆
上报 0x0006:on/off 0x8002(涂鸦私有属性)
  • 0:Off
  • 1:On
  • 2:掉电记忆

DP37 指示灯状态设置-总控

命令方向 Cluster ID CMD / ATTR ID VALUE
下发 0x0006:on/off 0x8001(涂鸦私有属性)
  • 0:off
  • 1:状态指示(继电器开则亮)
  • 2:状态指示(继电器开则灭)
上报 0x0006:on/off 0x8001(涂鸦私有属性)
  • 0:off
  • 1:状态指示(继电器开则亮)
  • 2:状态指示(继电器开则灭)

DP39 开关 1 上电状态设置-分控 ~ DP40 开关 2 上电状态设置-分控

命令方向 Cluster ID CMD / ATTR ID VALUE
下发 0xE001 (Tuya electrical private cluster) 0xD010(涂鸦私有属性)
  • 0:Off
  • 1:On
  • 2:掉电记忆
上报 0xE001 (Tuya electrical private cluster) 0xD010(涂鸦私有属性)
  • 0:Off
  • 1:On
  • 2:掉电记忆

设备编译与烧录

固件编译

  1. 在 Visual Studio Code 软件页面上,打开产品开发包,展开左侧 software/TuyaOS/apps,可以看到本产品 Demo 的 project 文件夹。

    复合开关产品开发包
  2. 右键产品文件夹,选择 Build Project,在跳出的文本框内输入编译固件的版本号(格式为 x.x.x)后,按回车键确认。

    复合开关产品开发包 复合开关产品开发包
  3. 编译成功后,控制台打印内容如下:

    复合开关产品开发包

    编译产物可在工程路径下的 apps/*产品名称*/output 文件夹查看,其中 QIO 标识的是烧录固件,UG 标识的是 OTA 升级文件,具体如下:

    复合开关产品开发包
  4. 清除编译内容,Telink 平台编译前建议先清除上次编译内容,可右键产品文件夹,选择 Clean Project,输入版本号,按回车键确认对产品编译内容进行清除。

    复合开关产品开发包 复合开关产品开发包

固件烧录

  • Telink 平台使用原厂烧录工具烧录,可在 TLSR8258_3.8.1\software\TuyaOS\docs\ 查看。
  • 涂鸦烧录授权工具烧录及芯科平台原厂工具烧录,可参考 涂鸦烧录授权及芯科原厂工具烧录说明烧录授权章节

例程开发说明

基础信息配置

产品功能配置

在产品工程的 include 文件夹的 app_configuration.h 文件,可配置本例程支持的功能。将所需的功能开关宏置 1,相关功能开启,反之则关闭。产品例程会默认开启产品所必须的功能及提供对应的组件。如需要产品非必须的功能,则需自行增加对应组件后,再开启功能开关。插座默认开启的功能如下:

//Component Feature Enable Configuration
#define BUTTON_ENABLE                            1    //0: disable 1: button enable
#define COUNTDOWN_ENABLE                         1    //0: disable 1: countdown enable
#define REPORT_STRATEGY_ENABLE                   1    //0: disable 1: report attribute strategy enable
#define ZERO_CROSSING_DETECT_ENABLE              1    //0: disable 1: Zero-crossing detection enable
#define LED_MODE_ENABLE                          1    //0: disable 1: LED mode enable
#define TOT_RELAY_STATUS_ENABLE                  1    //0: disable 1: relay status power on enable
#define SUB_RELAY_UNIT_ENABLE                    1    //0: disable 1: sub relay status power on enable
#define DEV_CHANNEL_MODE_ENABLE                  1    //0: disable 1: Channel mode can be switched between switches and scenes

设备注册配置

在产品工程的 src 文件夹中的 app_dev_register.c 文件,可修改注册的 device ID、cluster、attribute 等设备信息。

可在文件下图所示处,修改注册的 server cluster,您可根据需要进行删减:

// server cluster for the first endpoint
CONST TAL_CLUSTER_T g_server_cluster_id[] = {
    DEF_CLUSTER_IDENTIFY_CLUSTER_ID(identify_attr_list)
    DEF_CLUSTER_GROUPS_CLUSTER_ID(group_attr_list)
    DEF_CLUSTER_SCENES_CLUSTER_ID(scene_attr_list)
    DEF_CLUSTER_ON_OFF_CLUSTER_ID(onoff_attr_list)
    CLUSTER_TUYA_ELECTRICIAN_CLUSTER_ID_DEF
    CLUSTER_TUYA_COMMON_CLUSTER_ID_DEF
};
  • 如果新增的 cluster 和属性只有第一路的 endpoint 有,只需在 g_server_cluster_id 添加新增的 cluster 和属性。

  • 如果新增的 cluster 和属性是所有 endpoint 都有的,需要同时在 g_server_cluster_idg_server_cluster_id_except_ep1 添加新增的 cluster 和属性。

// server cluster except for the first endpoint
CONST TAL_CLUSTER_T g_server_cluster_id_except_ep1[] = {
    DEF_CLUSTER_IDENTIFY_CLUSTER_ID(identify_attr_list)
    DEF_CLUSTER_GROUPS_CLUSTER_ID(group_attr_list)
    DEF_CLUSTER_SCENES_CLUSTER_ID(scene_attr_list)
    DEF_CLUSTER_ON_OFF_CLUSTER_ID(onoff_attr_list_except_ep1)
    CLUSTER_TUYA_ELECTRICIAN_CLUSTER_ID_DEF_EXCEPT_EP1
};

在产品工程的 include 文件夹中的 app_dev_register.h 文件,可在文件下图所示处,修改设备注册的 endpoint 及其的 device ID 等信息。

#define EP_VALUE_TABLE              {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}      ///endpoint 值
#define DEV_DESCRIPTION_DEF(ep)                     DEV_SERVER_DESC(ZG_DEVICE_ID_SCENE_SELECTOR, ep)
#define DEV_DESCRIPTION_EXCEPT_EP1_DEF(ep)          DEV_SERVER_DESC_EXCEPT_EP1(ZG_DEVICE_ID_SCENE_SELECTOR, ep)

固件信息修改
在产品工程文件夹下的 app_config.yaml,可配置该产品的 PID、model ID、设备类型等信息。文件支持两种配置方式,您根据需求任选其一即可。文件内容及作用如下:

#######################################################################
# COMPATIBILITY of [Tuya mode]
# For the use of Tuya redefined attributes:
# [cluster:0x0000,attribute:0x0004] Tuya manufacturer name
# [cluster:0x0000,attribute:0x0005] Tuya model ID
########################################################################
Firmware_Information:
  description: "this is a demo project"
  device_role: "router"   # router/sleep_end_dev
  image_type: 0x1602
  manufacture_id: 0x1002
  model_id: "TS0505B"
  manufacture_name: "_TZ3210_hxyvqfuz" # capacity+pid
  module_name: "ZSU"
  chip_id: "efr32mg21a020f1024im32" # efr32mg21a020f1024im32/efr32mg21a020f768im32


########################################################################
# COMPATIBILITY of [Zigbee standard mode]
# For the use of ZCL standard attributes:
# [cluster:0x0000,attribute:0x0004] ManufacturerName
# [cluster:0x0000,attribute:0x0005] ModelIdentifier
########################################################################
# Firmware_Information:
#   description: "this is a demo project"
#   device_role: "router"   # router/sleep_end_dev
#   image_type: 0x1602
#   manufacture_id: 0x1002
#   model_id: "custom"
#   manufacture_name: "custom"
#   product_id: "bhzkbugw"
#   capacity: "_TZ3210_"
#   product_type: "TS0502B"  
#   module_name: "ZSU"
#   chip_id: "efr32mg21a020f1024im32" # efr32mg21a020f1024im32/efr32mg21a020f768im32

如果您想要自定义 model_idmanufacture_name 属性,则必须使用第二种配置方式,并填写 capacityproduct_typeproduct_id 字段。

名称 功能
description 产品描述字段
device_role 设备角色类型,router代表正常功耗路由设备,sleep_end_dev 代表休眠低功耗设备,请谨慎更改
image_type 固件信息,用于 OTA 时验证使用
manufacture_id 厂商 ID,用于 OTA 时验证使用
model_id 设备型号,用于加入涂鸦网关后确定设备功能,请谨慎更改
manufacture_name 产品能力值和涂鸦 PID 拼接,用下划线(_)连接,例如 _TZ3210_hxyvqfuz
module_name 模组型号,指示产品使用的模组
chip_id 芯片型号,指示产品使用的芯片,请勿更改
capacity 涂鸦产品能力值,该字段请勿更改。如需更改,请咨询涂鸦产品经理
product_type 设备型号,用于加入涂鸦网关后确定设备功能,请谨慎更改
product_id 涂鸦产品 ID,此处填写的是默认 PID,烧录授权时会写入新 PID

管脚配置

在产品工程目录的 include 文件下的 app_configuration.h,可配置产品硬件外设 IO 口,可在文件如下图所示处,修改 IO 配置:

  • 按键配置:

    //Button GPIO config
    #define KEY_GPIO_CFG    \
        { \
            .pin_num = APP_GPIO_PD2, \
            .pin_active_level = TUYA_GPIO_LEVEL_LOW \
        }, \
        { \
            .pin_num = APP_GPIO_PB4, \
            .pin_active_level = TUYA_GPIO_LEVEL_LOW \
        } \
    
  • 指示灯配置:

    //LED GPIO config
    #define LED_GPIO_CFG     \
        { \
            .led_pin_num = APP_GPIO_PD7, \
            .led_active_level = LED_LOW_ACTIVE, \
            .led_init_st = LED_ST_OFF, \
            .led_blink_stop_callback = led_stop_blink_callback \
        }, \
        { \
            .led_pin_num = APP_GPIO_PD4, \
            .led_active_level = LED_LOW_ACTIVE, \
            .led_init_st = LED_ST_OFF, \
            .led_blink_stop_callback = led_stop_blink_callback \
        } \
    
  • 网络指示灯配置:

    //Network LED GPIO config
    #define NET_LED_GPIO_CFG     \
        { \
            .led_pin_num = APP_GPIO_PC3, \
            .led_active_level = LED_LOW_ACTIVE, \
            .led_init_st = LED_ST_OFF, \
            .led_blink_stop_callback = led_stop_blink_callback \
        } \
    
  • 继电器配置:

    //Relay GPIO config
    #define RELAY_GPIO_CFG     \
        { \
            .led_pin_num = APP_GPIO_PA0, \
            .led_active_level = LED_HIGH_ACTIVE, \
            .led_init_st = LED_ST_OFF \
        }, \
        { \
            .led_pin_num = APP_GPIO_PA1, \
            .led_active_level = LED_HIGH_ACTIVE, \
            .led_init_st = LED_ST_OFF \
        } \
    
  • 过零检测管脚配置:

    //Zero-crossing detection GPIO config
    #define ZERO_GPIO_CFG    \
        { \
            .pin_num = APP_GPIO_PB6, \
            .pin_active_level = TUYA_GPIO_LEVEL_HIGH \
        } \
    

支持与帮助

在开发过程遇到问题,您可以登录 TuyaOS 开发者论坛 子设备开发版块 进行沟通咨询。