企业官网建设流程全解析

Matter ASR 平台 Lighting 示例应用开发指南：构建、配网与集群控制实战

【免费下载链接】connectedhomeipMatter (formerly Project CHIP) creates more connections between more objects, simplifying development for manufacturers and increasing compatibility for consumers, guided by the Connectivity Standards Alliance.项目地址: https://gitcode.com/GitHub_Trending/co/connectedhomeip

导读

本文面向在 ASR 芯片平台上开发 Matter（原 Project CHIP）照明类产品的开发者，系统讲解 examples/lighting-app/asr 示例应用的完整使用流程：从环境准备与交叉编译，到使用chip-tool通过 OnOff、LevelControl、ColorControl 三大集群控制灯泡，再到三色 RGB LED 指示灯的硬件接线与软件实现原理。阅读本文后，你将能够在 ASR582X / ASR595X / ASR550X 任一受支持平台上独立构建、烧录、配网并控制一盏 Matter 智能灯，并能基于源码理解其状态指示机制。

一、示例应用概览：ASR 平台上的 Matter 智能灯

ASR Lighting 示例演示了 Matter Lighting 应用在 ASR 平台上的完整实现。ASR 平台是基于 ASR FreeRTOS SDK 的 Matter 平台（详见 docs/platforms/asr/asr_getting_started_guide.md），当前仓库中受支持的芯片型号包括：

• ASR582X（ARM 架构）
• ASR595X（RISC-V 架构，ASR RISC-V GNU 工具链）
• ASR550X（ARM 架构）

示例工程的完整源码位于 examples/lighting-app/asr，目录结构如下：

从 BUILD.gn 的sources列表可以看出，该示例由平台公共代码（examples/platform/asr 下的CHIPDeviceManager.cpp、LEDWidget.cpp、init_Matter.cpp、init_asrPlatform.cpp、shell/matter_shell.cpp）与应用专属代码（AppTask.cpp、DeviceCallbacks.cpp、main.cpp）共同编译链接，最终输出文件名为chip-asr-lighting-example.out。

二、构建与配网（Building and Commissioning）

2.1 环境准备

构建前需要完成两件事：搭建 Matter 构建环境、安装 ASR 平台工具链。详细步骤请参考 docs/platforms/asr/asr_getting_started_guide.md#building-the-example-application 与 docs/guides/BUILDING.md。

工具链选择（按芯片架构区分）：

• ASR582X 与 ASR550X使用 ARM 工具链gcc-arm-none-eabi-9-2019-q4-major，下载解压后导出环境变量：

  export ASR_TOOLCHAIN_PATH={abs-path-to-toolchain}/gcc-arm-none-eabi-9-2019-q4-major/bin/

• ASR595X使用 RISC-V 工具链（asr_riscv_gnu_toolchain_10.2），需从 ASR Tools 仓库获取并拼合分卷压缩包后解压：

  git clone --depth=1 https://github.com/asriot/Tools.git cd Tools/toolchain cat asr_riscv_gnu_toolchain_10.2_ubuntu-16.04.tar.bz2.part* > asr_riscv_gnu_toolchain_10.2_ubuntu-16.04.tar.bz2 mkdir -p asr_riscv_gnu_toolchain_10.2_ubuntu-16.04 tar -jxvf asr_riscv_gnu_toolchain_10.2_ubuntu-16.04.tar.bz2 -C asr_riscv_gnu_toolchain_10.2_ubuntu-16.04/ export ASR_TOOLCHAIN_PATH={abs-path-to-toolchain}/asr_riscv_gnu_toolchain_10.2_ubuntu-16.04/bin/

设置目标板型号（ASR_BOARD环境变量）：

export ASR_BOARD=asr582x # ASR582X export ASR_BOARD=asr595x # ASR595X export ASR_BOARD=asr550x # ASR550X

2.2 构建 Lighting 示例

使用仓库自带的build_examples.py脚本进行交叉编译：

./scripts/build/build_examples.py --target asr-$ASR_BOARD-lighting build

--target参数中的目标名决定了输出镜像文件的存放目录——镜像会生成在out目录下与--target参数同名的子目录中（例如out/asr-asr582x-lighting/），其中的chip-asr-lighting-example.out即为最终固件。

在build_examples.py脚本中，目标后缀还可扩展为多种功能组合，详见 docs/platforms/asr/asr_getting_started_guide.md：

例如：

./scripts/build/build_examples.py --target asr-$ASR_BOARD-lighting-shell build ./scripts/build/build_examples.py --target asr-$ASR_BOARD-lighting-ota build ./scripts/build/build_examples.py --target asr-$ASR_BOARD-lighting-factory build

2.3 烧录

构建完成后，使用DOGO 工具将固件烧录到开发板。DOGO 是 ASR 官方的下载工具，其使用方式参见 ASR DOGO Tool User Guide（在 docs/platforms/asr/asr_getting_started_guide.md 中有指引）。烧录后开发板上电即自动运行示例程序。

2.4 构建参数说明

cfg.gni 定义了三个可调构建参数，并会在 BUILD.gn 中转换为编译宏：

注意cfg.gni的默认值属于开发测试用途；量产时应替换为符合 Matter 规范的正式 PIN Code 与 Discriminator。此外 args.gni 将chip_stack_lock_tracking设为none，原因是该 FreeRTOS 配置未开启INCLUDE_xSemaphoreGetMutexHolder。

2.5 配网（Commissioning）

ASR 平台支持两种配网模式，流程均为：构建烧录 → 上电自动运行 → 使用recovery命令恢复出厂设置 → 用 chip-tool 配网。

BLE 模式（仅 ASR582X 与 ASR595X 支持）：

./chip-tool pairing ble-wifi <node_id> <ssid> <password> <pin_code> <discriminator>

IP 模式（on-network 模式，先用命令连接 AP 再配网）：

wifi_open sta [ssid] [password] # 在设备 shell 中连接 AP ./chip-tool pairing onnetwork-long <node_id> <pin_code> <discriminator>

两种模式下pin_code与discriminator需与构建参数setupPinCode、setupDiscriminator（或设备实际值）一致。配网成功即可通过 chip-tool 发送集群指令控制设备。

三、集群控制（Cluster Control）：用 chip-tool 操控灯泡

配网成功后，使用chip-tool（构建说明见 examples/chip-tool）即可控制开发板上的灯泡。chip-tool命令的通用形式为./chip-tool <cluster> <command> <attribute/参数> <NODE ID> <endpoint>，其中<NODE ID> 1中的1为 endpoint id。

3.1 OnOff 集群（开关控制）

./chip-tool onoff on <NODE ID> 1 ./chip-tool onoff off <NODE ID> 1 ./chip-tool onoff toggle <NODE ID> 1

对应三个 Matter 标准命令：打开、关闭、翻转（toggle）灯的开关状态。在 AppTask.cpp 中，IsLightOn()通过读取 endpoint 1 上 OnOff 集群的OnOff属性来判断当前灯是否点亮，返回值会直接驱动后续 LED 状态指示。

3.2 LevelControl 集群（亮度控制）

./chip-tool levelcontrol move-to-level 128 10 0 0 <NODE ID> 1

参数含义依次为：目标亮度128（LevelControl 的 0～254 范围）、移动时间10（单位 1/10 秒，即 1 秒）、选项掩码0、选项覆盖0。程序端通过 AppTask.cpp 的GetLightLevel()读取 endpoint 1 的CurrentLevel属性（app::DataModel::Nullable<uint8_t>类型，需判空），进而把亮度值映射到 LED 的 PWM 占空比。

3.3 ColorControl 集群（颜色控制）

./chip-tool colorcontrol move-to-hue-and-saturation 240 100 0 0 0 <NODE ID> 1

参数含义依次为：目标 Hue240、目标 Saturation100、移动时间0、选项掩码0、选项覆盖0。该命令通过 HSB 色彩模型设置灯的颜色，颜色最终由三色 RGB LED 呈现（具体映射逻辑见下文第四节）。

提示：以上示例命令需要将<NODE ID>替换为配网时指定的实际节点 ID；若 endpoint 编号不同，也应同步修改末尾的1。

四、灯泡状态指示：三色 RGB LED 的硬件接线与软件原理

4.1 硬件接线

默认情况下，示例使用一个三色 RGB LED 模组来实时指示灯泡状态（开关、亮度、颜色）。将模组按下表连接至开发板：

4.2 默认引脚与通道定义（源码级）

这些默认引脚定义于 examples/platform/asr/LEDWidget.h，对应宏如下：

#define LIGHT_RGB_RED PWM_OUTPUT_CH6 #define LIGHT_RGB_GREEN PWM_OUTPUT_CH4 #define LIGHT_RGB_BLUE PWM_OUTPUT_CH1 #define LIGHT_RGB_RED_PAD PAD7 #define LIGHT_RGB_GREEN_PAD PAD6 #define LIGHT_RGB_BLUE_PAD PAD10 #define LIGHT_LED GPIO6_INDEX // 单色模式下的灯泡 LED #define STATE_LED GPIO7_INDEX // 状态指示 LED

即红色对应 PWM 输出通道 CH6 / PAD7，绿色对应 CH4 / PAD6，蓝色对应 CH1 / PAD10。从 LEDWidget.cpp 的RGB_init()可以看出，RGB 模式会依次初始化三个 PWM 通道：

void LEDWidget::RGB_init() { Init(LIGHT_RGB_RED); // red light of RGB Init(LIGHT_RGB_GREEN); // green light of RGB Init(LIGHT_RGB_BLUE); // blue light of RGB }

4.3 软件实现原理

AppTask.cpp 中的初始化与状态同步逻辑：

#ifdef LIGHT_SELECT_RGB lightLED.RGB_init(); // 初始化三通道 PWM #else lightLED.Init(LIGHT_LED); // 单色 GPIO 模式 #endif led_startup_status(); // 读取 OnOff/CurrentLevel 属性恢复 LED 状态

其中LIGHT_SELECT_RGB宏由 BUILD.gn 的defines注入（"LIGHT_SELECT_RGB"），因此默认编译即为 RGB 三色模式。led_startup_status()在启动时调用IsLightOn()与GetLightLevel()读取 Matter 属性并恢复 LED 的开关与亮度状态，保证设备重启后指示与属性一致。

PWM 驱动细节（见 LEDWidget.cpp）：

• PWM 频率固定为1000 Hz（PWM_LED_FREQ_HZ）；
• 亮度值 0～100 映射为 PWM 占空比，周期为 255μs（LED_PWM_PERIOD_US），即占空比 =val / 255；
• SetColor()内部先把 Matter 的 Hue（0～254）与 Saturation（0～254）归一化到色相角[0°, 360°]与饱和度[0, 100]（见 LEDWidget.cpp），再经HSB2rgb()完成 HSB→RGB 转换，最终由showRGB()分别写入红、绿、蓝三个 PWM 通道；
• 非 RGB 模式（LIGHT_SELECT_RGB未定义）时退化为单个 GPIO 推挽输出（duet_gpio_output_low/high），并因 LED 采用低电平有效接法，DoSet()中点亮对应输出低电平。

平台差异处理：LEDWidget.h通过CFG_PLF_RV32（RISC-V 芯片如 ASR595X）、CFG_PLF_DUET、默认lega_*三套宏分支，把 ASR SDK 的asr_pwm_*/asr_gpio_*、duet_*、lega_*接口统一映射为duet_pwm_*/duet_gpio_*内部接口，从而让同一份 LEDWidget 代码跨芯片平台复用；RISC-V 平台还会在 PWM 初始化前调用asr_pinmux_config(pad, PF_PWM)完成引脚复用配置（见 LEDWidget.cpp）。

五、配套调试手段：Shell、OTA 与 Factory Data

围绕 Lighting 示例，docs/platforms/asr/asr_getting_started_guide.md 还提供了三类配套能力：

5.1 Matter Shell 调试

使用-lighting-shell目标构建后，上电即可进入交互式 Shell。help命令列出的常用命令包括：

help List out all top level commands version Output the software version wifi Usage: wifi <subcommand> config Manage device configuration device Device management commands onboardingcodes Dump device onboarding codes dns Dns client commands OnOff OnOff commands. Usage: OnOff [on|off]

其中OnOff on|off可在无 chip-tool 的情况下直接验证灯的开关功能，onboardingcodes可打印设备的二维码与手动配对码（none|softap|ble|onnetwork四种渲染形式），config可读写如 discriminator 等设备配置。此外在 AppTask.cpp 中，启用 Shell 时还会通过RegisterLightCommands()注册额外的灯控命令。

5.2 OTA 升级

使用-lighting-ota目标构建即可启用 Matter OTA Requestor 功能，详细用法参见 examples/ota-requestor-app/asr/README.md。

5.3 Factory Data

使用-lighting-factory目标构建可启用 ASR Factory Data Provider，出厂数据（如证书、设备信息）的生成与写入方法参见 ASR Factory Tool 用户指南（入口在 docs/platforms/asr/asr_getting_started_guide.md）。启用后 BUILD.gn 会注入CONFIG_ENABLE_ASR_FACTORY_DATA_PROVIDER与CONFIG_ENABLE_ASR_FACTORY_DEVICE_INFO_PROVIDER两个宏。

六、快速排查与常见问题

• 构建失败：找不到工具链→ 确认ASR_TOOLCHAIN_PATH已按芯片架构导出正确路径，ASR595X 与 ASR582X/ASR550X 的编译器不同。
• 配网失败：PIN Code / Discriminator 不匹配→ 检查 chip-tool 命令中的<pin_code>、<discriminator>是否与构建参数setupPinCode（默认20202021）、setupDiscriminator（默认3840）一致。
• BLE 配网无效→ 仅 ASR582X 与 ASR595X 支持 BLE 模式，ASR550X 请改用 IP 模式（onnetwork-long）。
• LED 不亮或颜色异常→ 核对 RGB 接线是否对应 PAD7 / PAD6 / PAD10，并确认构建时LIGHT_SELECT_RGB宏生效；单色板可去掉该宏走 GPIO 模式。
• 重启后 LED 状态丢失→ 属正常现象之外请留意led_startup_status()是否在初始化流程中被执行（其依赖 Matter 属性读取成功）。

参考资料（仓库内）

• 平台入门指南：docs/platforms/asr/asr_getting_started_guide.md
• 示例应用主目录：examples/lighting-app/asr
• 核心实现：src/AppTask.cpp、src/main.cpp
• 构建脚本与参数：BUILD.gn、cfg.gni、args.gni
• LED 状态指示：LEDWidget.h、LEDWidget.cpp
• chip-tool 控制器：examples/chip-tool
• 平台公共代码：examples/platform/asr

【免费下载链接】connectedhomeipMatter (formerly Project CHIP) creates more connections between more objects, simplifying development for manufacturers and increasing compatibility for consumers, guided by the Connectivity Standards Alliance.项目地址: https://gitcode.com/GitHub_Trending/co/connectedhomeip