4. 实现Matter Dimmable Light

任务说明

本案例基于Matter官方Lighting Example工程，为其添加Level Control cluster支持，使设备具备亮度调节能力。完成后的设备可通过Matter控制器（如chip-tool）发送亮度百分比指令，实现0%~100%范围内的平滑调节。

实现方案

Matter Lighting Example默认已包含On/Off cluster，本案例需要在其基础上增加Level Control cluster。实现分为三步：修改ZAP配置文件声明cluster、生成对应代码、实现亮度回调函数。设备端通过PWM方式驱动LED，亮度值映射到PWM占空比。

代码实现

首先在examples/lighting-app/lighting-common/lighting-app.zap中，于endpoint 1的server clusters列表中添加Level Control cluster（cluster ID 0x0008），并启用MoveToLevel、Move、Step等核心命令。修改后的关键配置片段如下：

<cluster>
  <side>server</side>
  <code>8</code>
  <name>Level Control</name>
  <command id="0" source="client">MoveToLevel</command>
  <command id="1" source="client">Move</command>
  <command id="2" source="client">Step</command>
  <command id="3" source="client">Stop</command>
  <attribute side="server" code="0" type="int8u" writable="false" default="0">CurrentLevel</attribute>
  <attribute side="server" code="1" type="int8u" writable="false" default="0">MinLevel</attribute>
  <attribute side="server" code="2" type="int8u" writable="false" default="254">MaxLevel</attribute>
</cluster>

重新运行scripts/tools/zap/generate.py生成cluster处理代码。随后在examples/lighting-app/lighting-common/src/lighting_app.cpp中实现亮度控制回调：

#include "app/util/af-types.h"
#include "app/util/af.h"
#include "lighting_app.h"

// PWM占空比映射：Level 0~254 → 占空比 0~100%
static uint8_t sCurrentLevel = 0;

void MatterLevelControlClusterServerAttributeChangedCallback(
    const app::ConcreteAttributePath & attributePath, bool isA)
{
    if (attributePath.mAttributeId == ZCL_CURRENT_LEVEL_ATTRIBUTE_ID)
    {
        EmberAfStatus status = emberAfReadServerAttribute(
            attributePath.mEndpointId, ZCL_LEVEL_CONTROL_CLUSTER_ID,
            ZCL_CURRENT_LEVEL_ATTRIBUTE_ID, &sCurrentLevel, sizeof(sCurrentLevel));
        if (status == EMBER_ZCL_STATUS_SUCCESS)
        {
            // 将Level值(0~254)映射到PWM占空比(0~100)
            uint8_t dutyCycle = static_cast<uint8_t>(
                (sCurrentLevel * 100) / 254);
            SetLightDutyCycle(dutyCycle);  // 硬件PWM驱动函数
        }
    }
}

void SetLightDutyCycle(uint8_t percent)
{
    // 实际项目中调用硬件PWM接口，例如：
    // pwm_set_duty(PWM_LIGHT_CHANNEL, percent);
    // 此处为演示保留空实现
}

在lighting_app.h中声明上述函数，并在LightingMgr::Init()中注册回调：

void MatterLevelControlClusterServerAttributeChangedCallback(
    const app::ConcreteAttributePath & attributePath, bool isA);

void LightingMgr::Init()
{
    // 注册Level Control属性变更回调
    app::AttributeChangedCallback::Register(
        &MatterLevelControlClusterServerAttributeChangedCallback);
    // ... 原有初始化代码
}

SVG：Level Control亮度调节流程

构建与烧录

# 在Matter SDK根目录执行
source scripts/activate.sh
cd examples/lighting-app/linux
gn gen out/debug --args='chip_enable_pw_rpc=false'
ninja -C out/debug

将生成的chip-lighting-app可执行文件拷贝至目标设备（如树莓派或开发板），运行前确保设备已连接PWM LED电路。

验证方法

使用Matter控制器（chip-tool）执行以下命令验证亮度调节功能：

# 建立配对（假设设备已开启）
chip-tool pairing onnetwork 1 20202021 3840

# 发送亮度调节指令：将亮度设为50%
chip-tool levelcontrol move-to-level 127 0 1 1

# 查询当前亮度属性
chip-tool levelcontrol read current-level 1 1

判定标准：

1. 执行move-to-level命令后，LED亮度应发生肉眼可见的变化，且亮度与设置的Level值（0~254）成线性对应关系；
2. 读取current-level属性返回值应与设置值一致（允许±1误差）；
3. 连续发送不同Level值（如0、64、127、254），LED亮度应平滑变化，无闪烁或跳变。

若以上三条均满足，则说明Level Control cluster已正确集成，亮度调节功能实现成功。