两路开关 Demo 开发包

本文介绍一款基于 TuyaOS 平台开发的 Zigbee 两路开关 Demo。

概述

• 支持配网功能。

  • 控制方式：网络按键长按 3 秒，进入配网状态。

• 支持开关功能（两路开关）。

  • 控制方式：

    • 设备按键本地控制：开关按键切换对应的开关状态。
    • App 面板远程控制。

  • 状态同步：设备状态（开关指示灯）和 App 面板状态保持同步。

• 支持指示灯状态设置。

  • 指示网络状态：上电或网络状态改变时，网络指示灯有相应的行为。

  • 指示开/关状态：本 Demo 使用两路开关，分别通过指示灯来指示开关状态。打开开关后，对应的指示灯亮。关闭开关后，对应的指示灯灭。

    在 App 面板打开/关闭开关，设备收到开/关命令后，设备上的开关状态立即切换，对应指示灯的亮灭状态也随之切换。

• 支持数据上报。

功能特点

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

操作与现象

进行配网

• 长按设备的网络按键 3 秒，设备将开启配网功能，网络指示灯开始快闪。此时可将设备与网关进行配网，步骤参考 配网步骤。
• 配网成功时，设备网络指示灯长亮 3 秒后熄灭，此时可在 App 页面看到此设备。
• 配网超时（默认 30 秒）后，设备网络指示灯停止闪烁。

按键操作

• 短按开关按键，切换对应开关指示灯的开关（亮灭）状态并上报。
• 长按网络按键 3 秒以上，网络指示灯开始快闪并开启配网。

指示灯显示

根据设备状态和连接情况，指示灯显示相应的指示信息。

• 上电时，网络指示灯长亮 3 秒。
• 配网中，网络指示灯快闪。
• 配网超时，网络指示灯熄灭。
• 配网成功，网络指示灯长亮 3 秒后熄灭。

开关状态上报

• 配网成功 15 秒后，上报开关状态。
• 短按开关按键后，切换对应开关并上报开关状态。

面板开关下发处理

配网成功后，操作面板按键，网关给设备发送携带开关状态的数据包。

设备接收到数据包后，根据数据包中的开关状态切换开关的开关状态。

产品创建

关于产品创建流程，参考 创建产品。

设备协议介绍

Zigbee 基本信息

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

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）	/

支持的属性和命令

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	恢复出厂设置

Identify cluster

Attributes

ID	Name	Data type	Range	Default
0x0000	identify time	uint16-0x21	0x0000-0xffff	0x0000

Group cluster

Attributes

ID	Name	Data type	Range	Default
0x0000	name support	bitmap8-0x18	0x00-0xff	0x00

Commands

ID	Name	Direction
0x00	Add group	C->S
0x03	Remove group	C->S

Scene cluster

Attributes

ID	Name	Data type	Range	Default
0x0000	Scene count	uint8-0x20	0x00-0xff	0x00
0x0001	Current scene	uint8-0x20	0x00-0xff	0x00
0x0002	Current group	uint16-0x21	0x0000-0xffff	0x0000
0x0003	Scene valid	bool-0x10	0x00-0xff	0x00
0x0004	Name support	bitmap8-0x18	0x00-0xff	0x00

Commands

ID	Name	Direction
0x04	Store Scene	C->S
0x05	Recall Scene	C->S

On/Off cluster

Attributes

ID	Name	Data type	Range	Default
0x0000	OnOff	bool-0x10	0：Off 1：On	0x00

Commands

ID	Name	Direction
0x00	Off	C->S
0x01	On	C->S

DP 与 Cluster 对应关系

DPID	DP 含义	是否为标准指令	对应 Endpoint
1	开关 1	是	1
2	开关 2	是	2

DP1 开关 1 ~ DP2 开关 2

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

指令方向	Cluster ID	CMD / ATTR ID	Value
下发	0x0006：on/off	0x00：off 0x01：on	/
上报	0x0006：on/off	0x0000：on/off	0：off 1：on

设备编译与烧录

固件编译

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

   

2. 右键产品文件夹，选择 Build Project，在弹出的文本框内，输入编译固件的版本号（格式为 x.x.x）后，按回车键确认。

   对于泰凌微芯片平台，建议在 Build Project 前先 Clean Project。

   

3. 编译成功后，控制台打印内容如下，以芯科平台为例：

   

   芯科平台的编译产物可在 software/TuyaOS/_output 文件夹查看，其中 QIO 标识的是烧录固件，UG 标识的是 OTA 升级文件，具体如下：

   
   • 芯科平台的编译产物在 software/TuyaOS/_output 文件夹内。
   • 泰凌微平台的编译产物在 项目工程路径 下的 output 文件夹内。
   • 奉加微平台的编译产物在 software/TuyaOS/_output 文件夹内。

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

   

固件烧录

• 芯科、泰凌微和奉加微平台可使用原厂烧录工具烧录。
• 涂鸦烧录授权工具烧录及芯科平台原厂工具烧录，可参考 涂鸦烧录授权及芯科原厂工具烧录说明 的 烧录授权章节。

例程开发说明

基础信息配置

设备注册配置

在产品工程的 src 文件夹中的 app_dev_register.c 文件，可修改注册的 Device ID、Cluster 和 Attribute 等设备信息。

可在文件的如下所示处，修改注册的 Server Cluster，您可根据需要进行删减：

// server cluster list
CONST TAL_CLUSTER_T onoff_1_ep_server_cluster_list[] = {
    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)
};
CONST TAL_CLUSTER_T onoff_2_ep_server_cluster_list[] = {

    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)
};

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

//Endpoint descriptor
TAL_ENDPOINT_T dev_endpoint_desc[] = {
    {ONOFF_1_ENDPOINT, ZHA_PROFILE_ID, ZG_DEVICE_ID_ON_OFF_LIGHT_SWITCH, ONOFF_1_EP_SERVER_CLUSTER_NUM, (TAL_CLUSTER_T *)&onoff_1_ep_server_cluster_list[0], 0, NULL},
    {ONOFF_2_ENDPOINT, ZHA_PROFILE_ID, ZG_DEVICE_ID_ON_OFF_LIGHT_SWITCH, ONOFF_2_EP_SERVER_CLUSTER_NUM, (TAL_CLUSTER_T *)&onoff_2_ep_server_cluster_list[0], 0, NULL},
};

固件信息修改

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

#######################################################################
# COMPATIBILITY of 【Tuya mode】
# For the use of tuya redefined attributes:
# [cluster:0x0000,attribute:0x0004] tuya manu 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: "TS0002"
  manufacture_name: "_TZ3000_qlizmo9x" # capacity+pid
  module_name: ""
  chip_id: "" # efr32mg21a020f1024im32/efr32mg21a020f768im32/TLSR8258F1KET

########################################################################
# COMPATIBILITY of 【zigbee standard mode】
# For the use of ZCL stardard 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

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

设备信息配置

例程开发需要开发者配置的设备信息及其配置方法如下：

设备信息配置

可在产品工程的 include 文件夹的 switch_app_config.h 文件，修改组件配置项，可配置项如下：

配置项	功能
ONOFF_1_ENDPOINT	开关 1 默认 Endpoint 序号，不建议修改
ONOFF_2_ENDPOINT	开关 2 默认 Endpoint 序号，不建议修改
APP_ZG_NODE_ROUTER	设备类型（router），不建议修改
ZIGBEE_JOIN_TIMEOUT_MS	配网超时时间，默认 30s
ZCL_ID_ONOFF	onoff 属性值上报时的 ZCL ID
PRESS_JOIN_TIME_MS	长按网络按键来开启配网时间，默认 3s

管脚配置

按键配置

可在产品工程的 include 文件夹的 switch_app_config.h 文件，修改组件配置项，可配置按键 I/O 口、有效电平和中断触发模式。可在文件如下所示处修改：

//key info
#if defined(PHY622X_EVB)
#define KEY_STA_1_PIN               TUYA_GPIO_NUM_32
#elif defined(MCU_CORE_8258)
#define KEY_STA_1_PIN               TUYA_GPIO_NUM_26
#else
#define KEY_STA_1_PIN               TUYA_GPIO_NUM_0
#endif
#define KEY_STA_1_ACTIVE_LEVEL      TUYA_GPIO_LEVEL_LOW
#define KEY_STA_1_IRQ_MODE          TUYA_GPIO_IRQ_RISE_FALL

#if defined(PHY622X_EVB)
#define KEY_STA_2_PIN               TUYA_GPIO_NUM_33
#elif defined(MCU_CORE_8258)
#define KEY_STA_2_PIN               TUYA_GPIO_NUM_12
#else
#define KEY_STA_2_PIN               TUYA_GPIO_NUM_3
#endif
#define KEY_STA_2_ACTIVE_LEVEL      TUYA_GPIO_LEVEL_LOW
#define KEY_STA_2_IRQ_MODE          TUYA_GPIO_IRQ_RISE_FALL

#if defined(PHY622X_EVB)
#define KEY_NWK_PIN                 TUYA_GPIO_NUM_34
#elif defined(MCU_CORE_8258)
#define KEY_NWK_PIN                 TUYA_GPIO_NUM_13
#else
#define KEY_NWK_PIN                 TUYA_GPIO_NUM_4
#endif
#define KEY_NWK_ACTIVE_LEVEL        TUYA_GPIO_LEVEL_LOW
#define KEY_NWK_IRQ_MODE            TUYA_GPIO_IRQ_RISE_FALL

指示灯配置

可在产品工程的 include 文件夹的 switch_app_config.h 文件，修改组件配置项，可配置指示灯 I/O 口、有效电平和初始化状态。可在文件如下所示处修改：

//led info
#if defined(PHY622X_EVB)
#define LED_STA_1_PIN               TUYA_GPIO_NUM_31
#elif defined(MCU_CORE_8258)
#define LED_STA_1_PIN               TUYA_GPIO_NUM_18
#else
#define LED_STA_1_PIN               TUYA_GPIO_NUM_7
#endif
#define LED_STA_1_ACTIVE_LEVEL      TUYA_GPIO_LEVEL_LOW
#define LED_STA_1_INIT_STATUS       LED_ST_OFF              //OFF

#if defined(PHY622X_EVB)
#define LED_STA_2_PIN               TUYA_GPIO_NUM_26
#elif defined(MCU_CORE_8258)
#define LED_STA_2_PIN               TUYA_GPIO_NUM_1
#else
#define LED_STA_2_PIN               TUYA_GPIO_NUM_8
#endif
#define LED_STA_2_ACTIVE_LEVEL      TUYA_GPIO_LEVEL_LOW
#define LED_STA_2_INIT_STATUS       LED_ST_OFF              //OFF

#if defined(PHY622X_EVB)
#define LED_NWK_PIN                 TUYA_GPIO_NUM_11
#elif defined(MCU_CORE_8258)
#define LED_NWK_PIN                 TUYA_GPIO_NUM_0
#else
#define LED_NWK_PIN                 TUYA_GPIO_NUM_19
#endif
#define LED_NWK_ACTIVE_LEVEL        TUYA_GPIO_LEVEL_LOW
#define LED_NWK_INIT_STATUS         LED_ST_OFF              //OFF

不同平台的管脚对应关系不一样。

• 对于芯科和泰凌微平台，可在 tkl_platform_types.h 文件中查看。
• 对于奉加微平台，可参考 ZPU 模组规格书。

以 芯科 MG21 为例，其管脚对应关系如下，其中 TUYA_GPIO_NUM_0 对应的是 PA0，以此类推。

//GPIO Index
#define APP_GPIO_PA0    TUYA_GPIO_NUM_0
#define APP_GPIO_PA1    TUYA_GPIO_NUM_1
#define APP_GPIO_PA2    TUYA_GPIO_NUM_2
#define APP_GPIO_PA3    TUYA_GPIO_NUM_3
#define APP_GPIO_PA4    TUYA_GPIO_NUM_4
#define APP_GPIO_PA5    TUYA_GPIO_NUM_5
#define APP_GPIO_PA6    TUYA_GPIO_NUM_6
#define APP_GPIO_PB0    TUYA_GPIO_NUM_7
#define APP_GPIO_PB1    TUYA_GPIO_NUM_8
#define APP_GPIO_PC0    TUYA_GPIO_NUM_9
#define APP_GPIO_PC1    TUYA_GPIO_NUM_10
#define APP_GPIO_PC2    TUYA_GPIO_NUM_11
#define APP_GPIO_PC3    TUYA_GPIO_NUM_12
#define APP_GPIO_PC4    TUYA_GPIO_NUM_13
#define APP_GPIO_PC5    TUYA_GPIO_NUM_14
#define APP_GPIO_PD0    TUYA_GPIO_NUM_15
#define APP_GPIO_PD1    TUYA_GPIO_NUM_16
#define APP_GPIO_PD2    TUYA_GPIO_NUM_17
#define APP_GPIO_PD3    TUYA_GPIO_NUM_18
#define APP_GPIO_PD4    TUYA_GPIO_NUM_19

支持与帮助

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