计量插座产品开发包

更新时间：2024-08-06 07:57:59下载pdf

本文描述一款基于 TuyaOS 平台开发的 Zigbee 计量插座 Demo。

概述

支持开关功能。
- 控制方式：
  - 设备按键本地控制。
  - App 面板远程控制。
- 状态同步：设备状态（包括继电器、指示灯）和 App 面板状态保持同步。
- 全开/全关：App 面板支持下发多路开关 DP，实现设备的全开、全关功能。
计量检测功能。
- 可监测以下数据：
  - 电压
  - 电流
  - 功率
  - 用电量
  - 计量数据报警功能
  产测校准后，测量更精确，误差可控制在 3% 以内。
支持指示灯状态设置。
- 指示灯关闭：继电器指示灯关闭（常灭）。
- 指示开/关状态：开关开、指示灯亮，开关关、指示灯灭，即开关和指示灯状态同步。
- 指示设备位置：开关开、指示灯灭，开关关、指示灯亮，即开关和指示灯状态相反，用于在黑暗环境下提示设备所在位置。
  
  App 操作后，指示灯状态切换立即执行。
支持继电器上电状态（总控）。
- 断电：设备断电重新上电后，默认处于断电状态（继电器断开、负载灯灭）。
- 通电：设备断电重新上电后，默认处于通电状态（继电器闭合、负载灯亮）。
- 断电记忆：设备断电重新上电后，通/断电状态与断电前保持一致。
支持倒计时功能。

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

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

当发生以下情况时，倒计时功能取消（清零）：
- 面板下发倒计时 DP 为 0。
- 倒计时执行计时周期内，设备开/关状态发生改变，包括设备本地按键控制、App 面板远程控制、定时控制执行等。
- 设备断电重新上电或者模组重启。
设置倒计时开始执行后，设备每隔一段时间上报一次剩余时间，用于面板更新显示对应设备将在多久之后执行开启/关闭。

功能特点

支持远程 on、off 和 toggle 命令控制开关，支持本地按键触发控制开关。
计量数据报警并关闭继电器，保障用电安全。
Zigbee 通信协议：使用 Zigbee 协议进行无线通信，确保可靠的数据传输和连接稳定性。
按键功能：配备易于操作的按键，用于设备的配网和本地离网等功能。
指示灯显示：配备指示灯，用于显示设备的连接状态和工作状态等。

操作及现象

进行网络配对：
- 长按设备上的配对按键 3 秒，设备将开启配网功能，网络指示灯开始快闪。
- 此时可将插座与网关进行配对，步骤参考配网步骤。
- 配对成功时，设备网络指示灯熄灭，此时可在 App 页面看到此设备。
- 配对失败时/超时后（时间默认 300 秒），设备网络指示灯停止闪烁，指示灯长亮。
按键操作：
- 短按时，按住按键，并在 2s 内释放，触发短按，对应继电器和指示灯会翻转。
- 长按时，长按大于 2 秒并且短于 5 秒时，无反应。长按大于 5 秒，指示灯开始快闪并开启配网。
网络指示灯显示：根据设备的状态和连接情况，指示灯会显示相应的指示信息。
- 配网中，网络指示灯快闪。
- 配网超时，网络指示灯熄灭。
- 配网成功，网络指示灯长亮。

产品创建

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

设备协议介绍

Zigbee 基本信息

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

Endpoint 描述

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

支持的 cluster

Input clusters（Server）	Output clusters（Client）
Basic（0x0000）	Over The Air Upgrade（0x0019）
Identify（0x0003）	/
Group （0x0004）	/
Scene （0x0005）	/
OnOff （0x0006）	/
Simple Metering (0x0702)	/
Electrical Measurement (0x0B04)	/
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	TS011F（计量插座）。
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

Simple metering cluster

Attributes

ID	Name	Data type	Range	Default
0x0000	CurrentSummationDelivered	Uint48-0x25	/	/
0x0200	Status	bitmap8-0x18	/	0x00
0x0300	UintOfMeasure	enum8-0x30	/	0x00
0x0303	SummationFormatting	bitmap8-0x18	/	0x00
0x0306	MeteringDeviceType	bitmap8-0x18	/	0x00

Electrical measurement

Attributes

ID	Name	Data type	Range	Default
0x0505	RMSVoltage	uint16-0x21	0x0000–0xFFFF	0x0000
0x0508	RMSCurrent	uint16-0x21	0x0000–0xFFFF	0x0000
0x050B	ActivePower	int16-0x29	-32768–32767	0x0000

Tuya electrical private cluster

Attributes

ID	Name	Data type	Range	Default
0xD000	产测（校准）结果	uint8-0x20	/	0x00
0xD001	计量故障	bitmap32-0x1B	/	0x00000000
0xD002	电量校准系数	uint32-0x23	/	0x00000000
0xD003	电压校准系数	uint32-0x23	/	0x00000000
0xD004	电流校准系数	uint32-0x23	/	0x00000000
0xD005	功率校准系数	uint32-0x23	/	0x00000000

DP 与 cluster 对应关系

DPID	DP 含义	是否为标准指令	对应 Endpoint
1	开关 1	是	1
2	开关 2	是	2
9	开关 1 倒计时	是	1
10	开关 2 倒计时	是	2
17	增加电量（总电量）	是	1
18	当前电流	是	1
19	当前功率	是	1
20	当前电压	是	1
21	产测结果	否	1
22	电压校准系数	否	1
23	电流校准系数	否	1
24	功率校准系数	否	1
25	电量校准系数	否	1
26	故障报警	否	1
27	上电状态设置-总控	否	1
28	指示灯状态设置	否	1

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

DP9 开关 1 倒计时 ~ DP10 开关 2 倒计时

命令方向	Cluster ID	CMD / ATTR ID	Value
下发	`0x0006`：on/off	`0x42`：On with timed off	Payload
上报	`0x0006`：on/off	`0x4001`：OnTime `0x4002`：OffWaitTime	0-43200

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

On/off Control：0x00
On time：0x003c
Off Wait Time：0x003c

DP17 增加电量（总电量）

命令方向	Cluster ID	CMD / ATTR ID	Value
上报	`0x0702`：Simple Metering	`0x0000`：CurrentSummationDelivered	/

DP18 当前电流

命令方向	Cluster ID	CMD / ATTR ID	Value
上报	`0x0B04`：Electrical Measurement	`0x0508`：RMSCurrent	/

DP19 当前功率

命令方向	Cluster ID	CMD / ATTR ID	Value
上报	`0x0B04`：Electrical Measurement	`0x050B`：ActivePower	/

DP20 当前电压

命令方向	Cluster ID	CMD / ATTR ID	Value
上报	`0x0B04`：Electrical Measurement	`0x0505`：RMSVoltage	/

DP21 产测结果

命令方向	Cluster ID	CMD / ATTR ID	Value
上报	`0xE001`：`TUYA_ELECTRICIAN_PRIVATE`	`0xD000`：私有属性	/

DP22 电压校准系数

命令方向	Cluster ID	CMD / ATTR ID	Value
上报	`0xE001`：`TUYA_ELECTRICIAN_PRIVATE`	`0xD002`：私有属性	/

DP23 电流校准系数

命令方向	Cluster ID	CMD / ATTR ID	Value
上报	`0xE001`：`TUYA_ELECTRICIAN_PRIVATE`	`0xD003`：私有属性	/

DP24 功率校准系数

命令方向	Cluster ID	CMD / ATTR ID	Value
上报	`0xE001`：`TUYA_ELECTRICIAN_PRIVATE`	`0xD004`：私有属性	/

DP25 电量校准系数

命令方向	Cluster ID	CMD / ATTR ID	Value
上报	`0xE001`：`TUYA_ELECTRICIAN_PRIVATE`	`0xD005`：私有属性	/

DP26 故障报警

命令方向	Cluster ID	CMD / ATTR ID	Value
上报	`0xE001`：`TUYA_ELECTRICIAN_PRIVATE`	`0xD001`：私有属性	Bit0：过流 Bit1：过压 Bit4：欠压

DP27 上电状态设置-总控

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

DP28 指示灯状态设置

命令方向	Cluster ID	CMD / ATTR ID	Value
下发	`0x0006`：on/off	`0x8001`（涂鸦私有属性）	`0`：off `1`：状态指示（继电器开则亮） `2`：位置指示（继电器关则亮）
上报	`0x0006`：on/off	`0x8001`（涂鸦私有属性）	`0`：off `1`：状态指示（继电器开则亮） `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，相关功能开启，反之则关闭。产品例程会默认开启产品所必须的功能及提供对应的组件。如需要产品非必须的功能，则需自行增加对应组件后，再开启功能开关。插座默认开启的功能如下：

#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

#define MEASURING_ENABLE                              1
#if MEASURING_ENABLE
#define MEASURING_KV_ID                            4
#define MEASURING_CHIP_TYPE                        OEM_CT_BL0942       // Metering Chip Type
#define RESISTOR                                1                   // Sampling resistor, unit milliohms
#define OVER_CUR                                0                   // Overcurrent value
#define OVER_VOL                                0                   // Overvoltage value
#define LOSE_VOL                                0                   // Losevoltage value
#define REPORT_TIME                             300
#if MEASURING_CHIP_TYPE == OEM_CT_BL0937 | | MEASURING_CHIP_TYPE == OEM_CT_HLW8012
#define GRID_PULSE_SEL_CFG                      APP_GPIO_PD3
#define PIN_CF_CFG                              APP_GPIO_PC0
#define PIN_CF1_CFG                             APP_GPIO_PC2

#endif
#endif

设备注册配置

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

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

// server cluster
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)
#if MEASURING_ENABLE
    DEF_CLUSTER_SIMPLE_METERING_CLUSTER_ID(sm_attr_list)
    DEF_CLUSTER_ELECTRICAL_MEASUREMENT_CLUSTER_ID(em_attr_list)
#endif
    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(0x010A, ep)
#define DEV_DESCRIPTION_EXCEPT_EP1_DEF(ep)          DEV_SERVER_DESC_EXCEPT_EP1(0x010A, 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 \
    } \

支持与帮助

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

上一篇插座产品开发包

下一篇开关产品开发包