门磁产品开发包

本文描述一款基于 TuyaOS 平台开发的 Zigbee 协议门磁传感器 Demo，支持门磁警报上报、防拆警报、按键、指示灯和电池电量上报等功能。

概述

功能特点

• 门磁警报上报：传感器可以监测门窗的开闭状态，并通过 Zigbee 协议将门磁警报信息上报给主控设备。当门窗状态发生变化时，传感器会向网关发送相应的事件通知，以便及时处理安全问题。
• Zigbee 通信协议：使用 Zigbee 协议进行无线通信，确保可靠的数据传输和连接稳定性。
• 防拆警报：传感器具备防拆功能，可以通过检测是否被拆卸来触发防拆警报。如果有人试图拆下传感器或者传感器遭受破坏，传感器会立即发送防拆警报信息给网关，以便保障安全性。
• 按键功能：配备易于操作的按键，用于设备的配网、唤醒及本地离网等功能。
• 指示灯显示：配备指示灯，用于显示设备的连接状态和工作状态等。
• 电池电量上报：定期上报设备的电池电量，及时为用户提供更换电池的参考。

操作及现象

• 进行网络配对：

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

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

  • 配对成功时，设备网络指示灯长亮三秒后熄灭，此时可在 App 页面看到此设备。

  • 配对超时（默认 30 秒）后，设备网络指示灯停止闪烁，设备进入休眠。

• 警报功能：

  • 门窗打开，状态指示灯快闪 1 下，如果在网内，就上报门磁开启给网关。

  • 门窗关闭，状态指示灯快闪 1 下，如果在网内，就上报门磁闭合给网关。

  • 防拆触发，状态指示灯快闪 1 下，如果在网内，就上报防拆触发给网关。

  • 防拆解除，状态指示灯无动作，如果在网内，就上报防拆解除给网关。

• 按键操作：

  • 短按时，按下网络指示灯亮，松开网络指示灯灭并上报电池电量。

  • 长按时，按下网络指示灯亮，长按短于 3 秒时，松开指示灯灭。长按大于 3 秒，指示灯开始快闪并开启配网。

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

  • 上电时，网络指示灯长亮 3 秒。

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

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

  • 配网成功，网络指示灯长亮 3 秒后熄灭。

• 电池电量上报：

  • 配网成功后 5 秒内上报 100% 电量。

  • 配网成功后 20 分钟上报真实电量。

  • 每 4 小时周期上报当前电量。

  • 电量低于 20% 时，以 1/4 周期上报时间（1 小时）周期上报电量。

产品创建

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

设备协议介绍

Zigbee 基本信息

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

Endpoint 描述

Endpoint	描述
1	当前门磁传感器使用的端口号

支持的 cluster

Input clusters （Server)	Output clusters （Client)
Basic（0x0000）	Over The Air Upgrade（0x0019）
Power Configuration（0x0001）	/
IAS Zone（0x0500）	/

支持的属性和命令

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	TY0203
0x0007	Power Source	enum8-0x30	0x00-0xff	0x03
0xFFFD	Cluster Revision	uint16-0x21	0x0000-0xffff	0x0001

Power configuration

Attributes

ID	Name	Data type	Range	Default
0x0000	MainsVoltage	uint16-0x21	0x0000-0xffff	0x03
0x0020	BatteryVoltage	uint8-0x20	24-30（2.4V-3.0V）	30
0x0021	BatteryPercentageRemaining	uint8-0x20	0-200（0-100%）	200
0xfffd	ClusterRevision	uint16-0x21	0x0000-0xffff	0x0001

IAS zone

Attributes

ID	Name	Data type	Range	Default
0x0000	Zone State	enum8-0x30	0x00-0xff	0x00
0x0001	Zone Type	enum16-0x31	0x0000-0xffff	0x0015
0x0002	Zone Status	bitmap16-0x19	0x0000-0xffff	0x0000
0x0010	IAS CIE Address	ieee address-0xF0	8 bytes	NULL
0x0011	Zone ID	uint8-0x20	0x00-0xff	0x0000
0xFFFD	Cluster Revision	uint16-0x21	0x0000-0xffff	0x0001

Commands

ID	Name	Direction	Description
0x00	Zone Status Change Notification	S->C	上报报警信息
0x01	Zone Enroll Request	S->C	向网关请求 Zone ID 信息
0x00	Zone Enroll Response	C->S	网关返回给设备的 Zone ID 请求响应

Over the air upgrade

Attributes

ID	Name	Data type	Range	Default
0x0000	UpgradeServerID	EUI64-0xF0	/	0xffffffffffffffff
0x0001	FileOffset	uint32-0x23	/	0x00000000
0x0002	CurrentFileVersion	uint32-0x23	/	0x00000040
0x0006	ImageUpgradeStatus	enum8-0x30	/	0x00
0x0007	Manufacturer ID	uint16-0x21	/	0x1002
0x0008	Image Type ID	uint16-0x21	/	0x1602
0x0009	MinimumBlockPeriod	uint16-0x21	/	0x0000
0xfffd	ClusterRevision	uint16-0x21	0x0000-0xffff	0x0001

Commands

ID	Name	Direction
0x00	Image Notify	S->C
0x01	Query Next Image Request	C->S
0x02	Query Next Image Response	S->C
0x03	Image Block Request	C->S
0x05	Image Block Response	S->C
0x06	Upgrade End Request	C->S
0x07	Upgrade End Response	S->C

常用 DP 与 cluster 对应关系

DPID	DP 含义	是否为标准指令
1	门磁	是
2	电池电量	是
4	防拆报警	是

DP1 门磁

指令方向	Cluster ID	ATTR ID	Value
上报	0x0500	0x0002 zonestatus	Bit0（alarm1） 0：not alarmed 1：alarmed

门打开上报 1，关闭上报 0。

DP2 电池电量

指令方向	Cluster ID	ATTR ID	Value
上报	0x0001	0x0020 battery voltage	0x00-0xff
上报	0x0001	0x0021 battery percentage remain	0x00-0xff

0x0020 上报数值 30，代表 3.0v 电压，0x0021 上报数值 180，代表 90% 剩余电量。

DP4 防拆报警

指令方向	Cluster ID	ATTR ID	Value
上报	0x0500	0x0002 zonestatus	Bit2（tamper） 0：not alarmed 1：alarmed

防拆类似按键，防拆触发时上报 alarmed，解除防拆报警后上报 not alarmed。

默认心跳（4h，上报电量）

请参考 DP2 电池电量。

设备编译与烧录

固件编译

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 文件夹的 sensor_app_config.h 文件，可配置本例程支持的功能。将所需的功能开关宏置 1，相关功能开启，反之则关闭。产品例程会默认开启产品所必须的功能及提供对应的组件。如需支持其他未开启的功能，请联系涂鸦产品经理。门磁默认开启的功能如下：

#define APP_KEY_SUPPORT                          1
#define APP_LED_SUPPORT                          1
#define APP_BATTERY_SUPPORT                      1
#define APP_GPIO_ALARM_SUPPORT                   1
#define APP_IAS_ZONE_SUPPORT                     1
#define APP_ILLUM_SUPPORT                        0
#define APP_PIR_SUPPORT                          0
#define APP_TEMPERATURE_HUMIDITY_SUPPORT         0

设备注册配置

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

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

// server cluster list
CONST TAL_CLUSTER_T app_server_cluster_list[] = {
    DEF_CLUSTER_IDENTIFY_CLUSTER_ID(identify_attr_list)
    DEF_CLUSTER_POWER_CLUSTER_ID(power_attr_list)
    DEF_CLUSTER_IAS_ZONE_CLUSTER_ID(ias_zone_attr_list)
    DEF_CLUSTER_TEMP_MEASUREMENT_CLUSTER_ID(temperature_attr_list)
    DEF_CLUSTER_RELATIVE_HUMIDITY_MEASUREMENT_CLUSTER_ID(humidity_attr_list)
    DEF_CLUSTER_ILLUM_MEASUREMENT_CLUSTER_ID(illum_measurement_attr_list)
    DEF_CLUSTER_TUYA_SENSOR_CLUSTER_ID(tuya_sensor_server_attr_list)
};

在文件如下所示处，修改设备注册的 endpoint 及其的 device ID 等信息。

//endpoint descriptor
TAL_ENDPOINT_T dev_endpoint_desc[] = {
    {1, ZHA_PROFILE_ID, ZG_DEVICE_ID_IAS_ZONE, SERVER_CLUSTER_NUM, (TAL_CLUSTER_T *)&app_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 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

名称	功能
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

组件配置

例程开发需要开发者配置的组件及其配置方法如下：

公共组件

公共组件 tbl_common 可在 tbl_common.h 文件修改组件配置项，可配置项如下：

配置项	功能
IAS_ZONE_ENDPOINT	IAS Zone 默认 Endpoint 序号，不建议修改
MANUFACTURER_CODE	手动组包发包用到的厂商号，不建议修改
IAS_ZONE_TYPE	IAS Zone Type，不建议修改
DEFAULT_TX_POWER	设备发射功率，可根据需求修改，受限制于硬件性能
BEACON_SEND_INTERVAL_200MS	扫网时 Beacon 发送间隔，一般不需要修改此项
ZIGBEE_RESET_TIME_MS	按键长按复位时间，默认 3s
ZIGBEE_JOIN_TIMEOUT_MS	配网超时时间，默认 30s

电池应用层组件

电池应用层组件 tbl_battery 可在 tbl_battery_config.h 文件修改组件功能配置，可配置项如下：

配置项	功能
TBL_BAT_INFO_FIRST_RPT_REAL_VAL_TIME	入网第一次上报真实值时间，单位：毫秒，默认 20 分钟
TBL_BAT_INFO_WAITTING_SILENCE_TIME	暂不支持，无需配置
TBL_BAT_INFO_MAX_PERIOD_TIME	周期采集电量时间，单位：毫秒，默认 1 小时
BATTTERY_HEARTBEAT_INTERVAL	周期上报时间（心跳周期），单位：毫秒，默认 4 小时

电池适配层组件

电池适配层组件 tdl_battery 可在 tdl_battery_config.h 文件修改组件功能配置，可配置项如下：

配置项	功能
TDL_BATTERY_DRIVER_TYPE	选择电池电量采集驱动类型，目前只支持 ADC 采样。
TDL_BAT_INFO_ADC_PIN	电压采集引脚，当选择内部采样时，此处可配 0。
TDL_BAT_INFO_ADC_CH_ID TDL_BAT_INFO_ADC_CH_LIST TDL_BAT_INFO_ADC_CH_NUM TDL_BAT_INFO_ADC_WIDTH TDL_BAT_INFO_ADC_FREQ TDL_BAT_INFO_ADC_MODE TDL_BAT_INFO_ADC_REF_VOL	ADC 参数配置项，目前这些配置暂不支持改动。
TDL_BAT_INFO_ADC_TYPE	配置电池采样类型。选择内部采样时，采集 VCC 供电电压。选择外部采样时，采集电压采集引脚电压。
TDL_BAT_INFO_MIN_VOLT TDL_BAT_INFO_MAX_VOLT	配置最大电压和最小电压值。涂鸦业务逻辑层（TBL）组件会据此计算电压电量转换表。当这两个宏均为 0 时，使用默认电压电量转换表。
BATTERY_DEFAULT_TABLE	默认电压电量转换表。

管脚配置

按键配置

在产品工程目录的 include 文件下的 sensor_app_config.h，可配置按键 IO 口，可在文件如下所示处，修改 IO 配置：

//key driver init info
#define KEY_PIN                                 TUYA_GPIO_NUM_17
#define KEY_IRQ_MODE                            TUYA_GPIO_LEVEL_LOW

指示灯配置

在产品工程目录的 include 文件下的 sensor_app_config.h，可配置指示灯 IO 口，可在文件如下所示处，修改 IO 配置：

#define LED_SUM                                  2

#define LED_STATUS_PIN                           (UINT32_T)TUYA_GPIO_NUM_1
#define LED_STATUS_LEVEL                         LED_HIGH_ACTIVE
#define LED_STATUS_STATRT_STATE                  LED_ST_OFF
#define LED_STATUS_COMPLETE_CB                   (NULL)      //Optional configuration

#define LED_NET_PIN                              (UINT32_T)TUYA_GPIO_NUM_0
#define LED_NET_LEVEL                            LED_HIGH_ACTIVE
#define LED_NET_STATRT_STATE                     LED_ST_OFF
#define LED_NET_COMPLETE_CB                      (NULL)

警报 IO 配置

在产品工程目录的 include 文件下的 sensor_app_config.h，可配置警报 IO 口。在文件如下所示处，修改门磁（gpio alarm）、防拆（tamper）的 IO 配置：

//GPIO alarm
#define GPIO_SENSOR_ALARM_1_ENABLE               TRUE
#define GPIO_SENSOR_ALARM_1_PIN                  TUYA_GPIO_NUM_18
#define GPIO_SENSOR_ALARM_1_LEVEL                TUYA_GPIO_LEVEL_HIGH

#define GPIO_SENSOR_TAMPER_ENABLE                TRUE
#define GPIO_SENSOR_TAMPER_PIN                   TUYA_GPIO_NUM_19
#define GPIO_SENSOR_TAMPER_LEVEL                 TUYA_GPIO_LEVEL_HIGH

#define GPIO_SENSOR_TROUBLE_ENABLE               FALSE
#define GPIO_SENSOR_TROUBLE_PIN                  TUYA_GPIO_NUM_14
#define GPIO_SENSOR_TROUBLE_LEVEL                TUYA_GPIO_LEVEL_HIGH

组件 IO 配置

参考 组件配置。

Telink 平台管脚对应关系

Telink 平台管脚对应关系如下，其中 TUYA_GPIO_NUM_0 对应的是 PA0，以此类推。

STATIC CONST UINT32_T tkl_gpio_list[] = {
    GPIO_PA0, GPIO_PA1, GPIO_PA2, GPIO_PA3, GPIO_PA4, GPIO_PA5, GPIO_PA6, GPIO_PA7, // 0 - 7 //
    GPIO_PB0, GPIO_PB1, GPIO_PB2, GPIO_PB3, GPIO_PB4, GPIO_PB5, GPIO_PB6, GPIO_PB7, // 8 - 15 //
    GPIO_PC0, GPIO_PC1, GPIO_PC2, GPIO_PC3, GPIO_PC4, GPIO_PC5, GPIO_PC6, GPIO_PC7, // 16 - 23 //
    GPIO_PD0, GPIO_PD1, GPIO_PD2, GPIO_PD3, GPIO_PD4, GPIO_PD5, GPIO_PD6, GPIO_PD7, // 24 - 31 //
    GPIO_PE0, GPIO_PE1, GPIO_PE2, GPIO_PE3, // 32 - 35//
};

芯科 MG21 管脚对应关系

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

#define GPIO_PA0    0
#define GPIO_PA1    1
#define GPIO_PA2    2
#define GPIO_PA3    3
#define GPIO_PA4    4
#define GPIO_PA5    5
#define GPIO_PA6    6
#define GPIO_PB0    7
#define GPIO_PB1    8
#define GPIO_PC0    9
#define GPIO_PC1    10
#define GPIO_PC2    11
#define GPIO_PC3    12
#define GPIO_PC4    13
#define GPIO_PC5    14
#define GPIO_PD0    15
#define GPIO_PD1    16
#define GPIO_PD2    17
#define GPIO_PD3    18
#define GPIO_PD4    19

支持与帮助

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