开关产品开发包

更新时间：2023-12-25 03:06:55下载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	0x0100

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`，即 `0x41` 为 `1.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	TS000x（零火开关）（接入涂鸦网关使用，`x` 用于指代路数，`TS0002` 代表 2 路零火开关）
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 common private cluster

Attributes

ID	Name	Data type	Range	Default
0xD003	点动开关（涂鸦私有属性）	array-0x48	/	/

Commands

ID	Name	Direction
0xFB	点动开关（涂鸦私有命令）	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
7	开关 1 倒计时	是	1
8	开关 2 倒计时	是	2
14	上电状态设置-总控	否	1
15	指示灯状态设置	否	1
19	点动开关	否	1
29	开关 1 上电状态设置-分控	否	1
30	开关 2 上电状态设置-分控	否	2

DP1 开关 1 ~ DP2 开关 2

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

命令方向	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

DP7 开关 1 倒计时 ~ DP8 开关 2 倒计时

命令方向	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

DP14 上电状态设置-总控

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

DP15 指示灯状态设置

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

DP19 点动开关

命令方向	Cluster ID	CMD / ATTR ID	VALUE
下发	`0xE000` (Tuya common private cluster)	`0xFB`：私有命令	Payload
上报	`0xE000` (Tuya common private cluster)	`0xD003`（涂鸦私有属性）	Payload

Payload 格式：3*n，n ≤ 6。从开关开始的部分为单个节点数据格式。

功能	长度	说明
通道号 + 通道使能位	1 byte	bit0：`0`：使能，`1`：不使能 bit7-bit1：通道号
点动延迟关闭时间	2 byte	00 3C – 0x003c = 60s

示例：

单路：01 00 3C，第一路使能，开启时间为 3C→60s 的延时关闭。

多路：00 00 3C 03 00 3C，第一路不使能，开启时间为 3C→60s 的延时关闭，第二路使能，开启时间为 3C→60s 的延时关闭。

DP29 开关 1 上电状态设置-分控 ~ DP30 开关 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`：掉电记忆

设备编译与烧录

固件编译

在 Visual Studio Code 软件页面上，打开产品开发包，展开左侧 software/TuyaOS/apps，可以看到本产品 Demo 的 project 文件夹。
右键产品文件夹，选择 Build Project，在跳出的文本框内输入编译固件的版本号（格式为 x.x.x）后，按回车键确认。
编译成功后，控制台打印内容如下：

编译产物可在工程路径下的 apps/*产品名称*/output 文件夹查看，其中 QIO 标识的是烧录固件，UG 标识的是 OTA 升级文件，具体如下：
清除编译内容，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 DELAY_CLOSE_ENABLE                      1     //0: disable 1: delay close relay 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

设备注册配置

在产品工程的 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_id 和 g_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_ON_OFF_LIGHT, ep)
#define DEV_DESCRIPTION_EXCEPT_EP1_DEF(ep)          DEV_SERVER_DESC_EXCEPT_EP1(ZG_DEVICE_ID_ON_OFF_LIGHT, 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_id 和 manufacture_name 属性，则必须使用第二种配置方式，并填写 capacity、product_type 和 product_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 \
    } \

#endif

支持与帮助

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

上一篇计量插座产品开发包

下一篇复合开关产品开发包