Matter window-app 实战指南Window Covering 窗帘设备的多平台构建、烧录与控制【免费下载链接】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/connectedhomeipconnectedhomeipMatter仓库中的 window-app 示例实现了一个标准的 Window Covering窗帘/遮阳Matter 设备通过实体按键模拟升降Lift与倾斜Tilt动作用 LED/LCD 反馈状态并可通过 chip-tool 或手机 App 经 BLE 配网BLE Thread/Wi-Fi Rendezvous后远程控制。读完本文你将掌握该示例在 Silicon Labs EFR32、nRF Connect、Telink、Realtek 四大平台上的构建与烧录方法、配网与控制操作流程以及示例核心类 WindowApp 的升降/倾斜位置模拟算法与事件处理机制。仓库中的窗口示例文档入口位于 docs/examples/window.md它通过 Sphinx toctree 聚合了各平台的 READMESilicon Labs EFR32、nRF Connect、Telink、Realtek。跨平台共享的应用逻辑位于 examples/window-app/common。一、示例定位与设备模型window-app 是一个 Matter 从设备accessory核心职责有三实现 Window Covering 集群的客户端交互面接收go-to-lift-percentage、go-to-tilt-percentage等 ZCL 命令更新TargetPositionLiftPercent100ths/TargetPositionTiltPercent100ths属性用软件定时器模拟真实电机的分段移动每次移动 LIFT_DELTA / TILT_DELTA 百分比步进周期性地更新CurrentPosition*属性与OperationalStatus提供本地 UI按键、LED/LCD支持本地步进控制、升降/倾斜模式切换、窗帘类型切换与出厂重置。设备的数据模型由 window-app.zap 与 window-app.matter 定义代码生成产物进入构建目录的zzz_generated/app-common。从 WindowApp.h 的结构可以看出跨平台抽象思路WindowApp是一个基类平台侧只需实现CreateButton、CreateTimer、PostEvent、ProcessEvents、OnMainLoop等纯虚函数Cover内嵌结构体mCoverList[WINDOW_COVER_COUNT]见 WindowApp.h#L209管理两个端点WINDOW_COVER_ENDPOINT1/WINDOW_COVER_ENDPOINT2上的两扇“窗帘”每扇窗帘各持有一个 lift 定时器和一个 tilt 定时器。二、核心实现升降与倾斜的位置模拟算法2.1 初始化属性预设Cover::Init在 WindowApp.cpp#L406-L448 中为每个端点预设 Window Covering 属性安装限位InstalledOpenLimitLift/InstalledClosedLimitLift、InstalledOpenLimitTilt/InstalledClosedLimitTiltType初始为kTiltBlindLiftAndTilt同时支持 lift 与 tilttype 0x08默认值ConfigStatus置位kLiftEncoderControlled与kTiltEncoderControlledEndProductType设为kInteriorBlindMode默认开启kLedFeedback。当前位置Current Position通过 Zap 配置预设并经 NVM 跨重启保持无需代码初始化。2.2 移动循环LiftUpdate / TiltUpdate以 lift 为例Cover::LiftUpdate位于 WindowApp.cpp#L480-L522其状态机逻辑为在StackLock保护下读取集群实例取得target、current并用ComputeOperationalState(target, current)判定当前应有的运行方向MovingUpOrOpen / MovingDownOrClose / Stall若是“目标更新”触发newTarget true即控制器写入了新的 Target 属性则停止旧定时器、刷新mLiftOpState若运行状态未变尚未到达/越过目标调用LiftStepToward再走一步从CurrentPositionLiftPercent100ths出发按LIFT_DELTA计算新的Percent100ths若无当前值则回到中间位置kWcPercent100thsMiddle再经LiftSchedulePositionSet提交若已到达或越过目标则把 Current 直接置为 Target 精确收敛状态置Stall每次更新都调用LiftScheduleOperationalStateSet写OperationalStatus非 Stall 时重启 lift 定时器从而形成“定时步进”的模拟运动。LiftSchedulePositionSet/LiftScheduleOperationalStateSet并不直接改属性而是通过PlatformMgr().ScheduleWork把工作投递到 CHIP 事件循环CallbackPositionSet最终调用LiftPositionSet/OperationalStateSet见 WindowApp.cpp#L677-L722。这是 Matter 应用层的典型线程安全模式属性访问只能在 CHIP 任务中完成。2.3 属性变更回调驱动动作WindowApp::DispatchEventAttributeChangeWindowApp.cpp#L289-L347把数据模型层的属性变更翻译成“电机动作”属性响应TargetPositionLiftPercent100ths触发LiftGoToTarget()开始朝目标移动TargetPositionTiltPercent100ths触发TiltGoToTarget()OperationalStatus回读并打印只读属性Mode回读、打印并回写可写属性联动 ConfigStatusConfigStatus/SafetyStatus由窗口覆盖服务端维护应用侧仅打印Type/EndProductType/ 当前位置类属性忽略Type循环切换逻辑在Cover::CycleType中kRollerShade → kDrapery → kTiltBlindLiftAndTilt → kRollerShadeWindowApp.cpp#L632-L657。2.4 事件分发与长按语义WindowApp::DispatchEventWindowApp.cpp#L194-L287与HandleLongPressWindowApp.cpp#L365-L395实现了按键组合语义各平台的按钮命名可能不同但底层事件一致单击 Up目标位置向上步进UpdateTargetPosition(MovingUpOrOpen)单击 Down向下步进UpDown 同时短按切换 lift/tilt 工作模式发TiltModeChange事件并抑制本次单按的步进Up 长按首次进入“重置警告”ResetWarning再次长按执行chip::Server::GetInstance().ScheduleFactoryReset()Down 长按循环切换窗帘类型RollerShade / Drapery / TiltBlindLiftAndTiltUpDown 同时长按在两扇窗帘端点 1 与端点 2之间切换当前操作对象mCurrentCover循环发CoverChange事件。WindowApp::Run主循环WindowApp.cpp#L129-L181每轮ProcessEvents()后用TryLockChipStack()非阻塞查询 Thread/Wi-Fi 配网状态与 BLE 连接数状态翻转时派发ProvisionedStateChanged/BLEConnectionsChanged事件——各平台的 LED 闪烁逻辑即基于这两个事件。此外Identify集群的OnTriggerEffect回调WindowApp.cpp#L34-L72把 Identify 效果映射为WinkOn/WinkOff事件驱动 LED 的 5 秒提示。三、Silicon Labs EFR32 平台参考 examples/window-app/silabs/README.md。3.1 构建支持硬件MG24 系列开发板BRD2703A / SLWSTK6000B2.4 GHz 10 dBmBRD4186C / SLWSTK6006A2.4 GHz 10 dBmBRD4187C / SLWSTK6006A2.4 GHz 20 dBm基础构建命令在仓库根目录cd ~/connectedhomeip ./scripts/examples/gn_silabs_example.sh ./examples/window-app/silabs/ ./out/window-app BRD4187C也可直接使用 GN/Ninjacd ~/connectedhomeip/examples/window-app/silabs git submodule update --init source third_party/connectedhomeip/scripts/activate.sh export SILABS_BOARDBRD4187C gn gen out/debug ninja -C out/debugICD间歇连接设备构建./scripts/examples/gn_silabs_example.sh ./examples/window-app/silabs/ ./out/window-app_ICD BRD4187C --icd # 等价 GN 参数 gn gen out/debug --argsSILABS_BOARDBRD4187C enable_sleepy_devicetrue chip_openthread_ftdfalsePigweed RPC 构建./scripts/examples/gn_silabs_example.sh examples/window-app/silabs/ out/window_app_rpc BRD4187C import(//with_pw_rpc.gni)3.2 烧录cd ~/connectedhomeip/examples/window-app/silabs python3 out/debug/matter-silabs-window-example.flash.py所有 EFR32 板需要 bootloader可使用 Silicon Labs 提供的预编译 Matter bootloader 二进制或经 SEGGER Ozone 直接加载 .out 文件调试。3.3 日志查看SEGGER RTT需安装 J-Link 软件包Linux 下执行sudo usermod -a -G dialout ${USER}获得 /dev/ttyACMx 访问权限。连接命令JLinkExe -device EFR32MG24AXXXF1536 -if SWD -speed 4000 -autoconnect 1 # 终端 1 JLinkRTTClient # 终端 2串口控制台默认波特率 115200CTS/RTS 握手若以--verbose构建则需 921600可用commander vcom config --baudrate 921600 --handshake rtscts配置 VCOM。无 LCD 的板如 BRD4166A可从 RTT 日志中直接取到 QR 码 URLhttps://project-chip.github.io/...形式的复制粘贴 URL在浏览器打开即可获得配网二维码。3.4 用户界面LCD显示配网二维码Rendezvous 用及窗帘状态LED 0连接状态50 ms 亮/950 ms 灭 未配网待配100/100 ms 快闪 BLE 已连上配网应用950 ms 亮/50 ms 灭 已配网但 Thread 未全连通常亮 完全就绪LED 1窗帘状态常亮 全开灭 全关慢闪 半开快闪 自动运动进行中按键Button0 短按 开 10%按住 6 秒 出厂重置提前松开取消两颗 LED 同步闪烁提示已进入重置流程Button1 短按 关 10%按住 3 秒 循环切换窗帘类型两键同按短按 切换 lift/tilt 模式两键同按长按 切换窗帘 1/窗帘 2。3.5 构建选项选项说明示例日志开关chip_progress_logging/chip_detail_logging/chip_automation_logging./scripts/examples/gn_silabs_example.sh ./examples/window-app/silabs ./out/window-app BRD4164A chip_detail_loggingfalse chip_automation_loggingfalse chip_progress_loggingfalseDebug/Releaseis_debug... BRD4164A is_debugfalse关闭 LCD 二维码show_qr_code... BRD4164A show_qr_codefalseKVS 最大条目数kvs_max_entries默认 75阈值 30–255... BRD4164A kvs_max_entries503.6 运行完整示例前提已有一个运行中的 OpenThread 边界路由器BR。设备配网后RTT 日志出现Device Role: CHILD与 Thread 单播地址列表即表示入网成功。配网并控制示例chip-tool pairing ble-thread 1 hex:operationalDataset 20202021 3840 chip-tool onoff on 1 chip-tool windowcovering go-to-tilt-percentage 50 0 1 1 chip-tool windowcovering # 列出 Window Covering 集群支持的全部命令若路由器未提供原生 IPv6需在边界路由器与 PC 上分别添加静态 IPv6 地址并建立路由# On Border Router : sudo ip addr add dev Network interface 2002::2/64 # On PC (Linux) : sudo ip addr add dev Network interface 2002::1/64 sudo ip route add Thread global ipv6 prefix/64 via 2002::2四、nRF Connect 平台参考 examples/window-app/nrfconnect/README.md。该示例定位为 Matter nRF Connect SDK 的冒烟测试参考生产级应用建议以 Nordic 官方 nRF Connect SDK 中的 Matter 示例为准。4.1 环境准备支持的开发板与构建目标硬件构建目标nRF52840 DKnrf52840dk/nrf52840nRF5340 DKnrf5340dk/nrf5340/cpuappnRF54L15 DKnrf54l15dk/nrf54l15/cpuapp步骤摘要检出平台子模块python3 scripts/checkout_submodules.py --shallow --platform nrfconnect安装 nRF Command Line Tools并通过 nRF Connect for Desktop 的 Toolchain Manager 安装仓库推荐的 nRF Connect SDK 版本校验 SDK 版本与 Matter 兼容python3 scripts/setup/nrfconnect/update_ncs.py --update。4.2 构建与烧录cd examples/window-app/nrfconnect west build -b nrf52840dk/nrf52840 --sysbuild # 产物build/nrfconnect/zephyr/zephyr.hex west flash --erase west debug # 目标板调试Release 构建关闭日志/CLI 等诊断功能west build -b build-target --sysbuild -- -DFILE_SUFFIXrelease切换构建板型或修改配置后需删除build目录重新构建用west build -b build-target --sysbuild -t menuconfig打开 Kconfig 菜单配置配置文件的构建类型后缀约定为prj_type.conf如prj_release.conf。4.3 配网与用户界面设备通电后自动开启 BLE 广播用于配网广播可能超时需按Button 4nRF52840/nRF5340 DK或Button 3nRF54L15 DK重新开启同时启动 NFC 标签模拟nRF54L15 默认 15 分钟其余板默认 60 分钟配网信息setup payload以 QR 码形式打印到 UART 控制台并写入 NFC 模拟标签LED 亮度表示位置lift 与 tilt 各用一颗 LED亮度 0–2550 全开255 全关步进按钮nRF52840/5340 DK 用 Button2开/ Button3关nRF54L15 DK 用 Button1开/ Button2关各走一步约 200 ms/步全开/全关需 20 步位置与 LED 亮度持久化保存两键同按切换 lift/tilt 模式复位后默认 liftButton154L15 为 Button0按 6 秒执行出厂重置短按3 秒触发 OTA 升级流程默认关闭需先按 DFU 章节启用。4.4 OTA / DFU示例默认启用 Matter OTA 的 Device Firmware UpgradeDFU基于 MCUboot 引导加载器与外部 QSPI Flash启用 BLE 传输的 SMPSimple Management Protocol下载固件west build -b build-target --sysbuild -- -DCONFIG_CHIP_DFU_OVER_BT_SMPy修改 MCUboot 配置编辑sysbuild/mcuboot目录下的prj.conf引导镜像是独立应用配置须与应用侧保持一致修改 Flash 分区默认通过 Partition Manager 生成自定义编辑应用目录下的pm_static_build_target.yml如pm_static_nrf52840dk_nrf52840.yml单核板nRF52840 DK、nRF54L15 DK用单镜像 DFU双核 nRF5340 DK 用多镜像 DFU 同时升级应用核与网络核。五、Telink 平台参考 examples/window-app/telink/README.md。5.1 支持板型板/SoC构建目标B91 / TLSR9518ADK80Dtlsr9518adk80d、tlsr9518adk80d-mars、tlsr9518adk80d-usbB92 / TLSR9528Atlsr9528a、tlsr9528a_retentionW91 / TLSR9118BDK40Dtlsr9118bdk40d5.2 构建与烧录推荐在官方 Docker 构建容器中进行镜像版本见仓库 CI 配置examples-telink.yamlsource ./scripts/activate.sh -p all,telink west build -b build_target # 产物build/zephyr/zephyr.bin west build -b build_target -- -DFLASH_SIZE4m # 板载 Flash 非 2MB 时指定大小 west flash --erase5.3 用户界面UARTPB3RX、PB2TXJ34 连接器 17/16 脚波特率 115200按键tlsr9518adk80dButton1 连按 3 次 出厂重置Button2 单击 开一步双击 切换 Lift/Tilt 模式Button3 打开 BLE 配网窗口Button4 单击 关一步LED蓝色 LED 以 PWM0–254指示 Lift 位置tilt 状态可外接 LED 到 PE0红色 LED 指示 Thread 状态短脉冲 未配网/Thread 关闭频繁脉冲 正在 JOIN宽脉冲 已作为 CHILD 入网绿色 LED 执行 Identify 集群的识别效果Blink/Breathe/Okay/ChannelChange/Finish/Stop 各有对应闪烁模式映射自Clusters::Identify::EffectIdentifierEnum。5.4 chip-tool 控制配网./chip-tool pairing ble-thread ${NODE_ID} hex:${DATASET} ${PIN_CODE} ${DISCRIMINATOR}常用控制命令参数依次为 集群名、命令、端点号./chip-tool onoff on 1 # 打开 ./chip-tool onoff off 1 # 关闭 ./chip-tool onoff read on-off 1 # 读 on-off 属性 ./chip-tool levelcontrol move-to-level 32 0 0 0 1 # 设亮度32亮度值 0过渡时间 0option mask 0override ./chip-tool levelcontrol read current-level 15.5 OTALinux OTA ProviderTelink 示例默认仅在 ota-requestor-app 中启用 OTA为 window-app 启用需在对应prj.conf中设置CONFIG_CHIP_OTA_REQUESTORy。测试时构建两版固件matter.ota需更高的CONFIG_CHIP_DEVICE_SOFTWARE_VERSION流程# 1. 构建 Linux OTA Provider ./scripts/examples/gn_build_example.sh examples/ota-provider-app/linux out/ota-provider-app chip_config_network_layer_blefalse # 2. 启动 Provider 并加载镜像 ./chip-ota-provider-app -f matter.ota # 3. 配网 Provider ./chip-tool pairing onnetwork ${OTA_PROVIDER_NODE_ID} 20202021 # 4. 写入 Provider 端点 ACL允许请求端访问 ./chip-tool accesscontrol write acl [{fabricIndex: 1, privilege: 5, authMode: 2, subjects: [112233], targets: null}, {fabricIndex: 1, privilege: 3, authMode: 2, subjects: null, targets: null}] ${OTA_PROVIDER_NODE_ID} 0 # 5. 向设备公告 Provider启动 OTA ./chip-tool otasoftwareupdaterequestor announce-otaprovider ${OTA_PROVIDER_NODE_ID} 0 0 0 ${DEVICE_NODE_ID} 0传输完成后 Requestor 发送 ApplyUpdateRequest设备成功应用镜像后自动重启。此外Telink 示例还支持 Pigweed RPCwest build -b build_target -- -DOVERLAY_CONFIGrpc.overlay由 USB 连接的宿主机经 proto 服务控制应用功能。六、Realtek 平台参考 examples/window-app/realtek/common/README.md。支持 RTL8777G基于 RTL87x2G SDK 与 OT-REALTEK OpenThread 移植。构建流程建议 Linux 环境依赖清单见 BUILDING.md 的前置条件scripts/checkout_submodules.py --shallow --platform realtek --recursive git submodule update --init --recursive third_party/openthread/ot-realtek source ./scripts/activate.sh # 若环境过期则 source ./scripts/bootstrap.sh ./scripts/build/build_examples.py --target realtek-rtl8777g-window build # 产物out/realtek-rtl8777g-window/bin/matter-cli-mtd该示例为标准配网流程未入网设备上电即广播 BLE 广告通过ble-thread方式配对Thread 网络数据集经 BLE 安全会话下发配网信息passcode 与 discriminator通常编码在 QR 码中或打印到 UART 控制台。七、平台差异速查与延伸阅读维度EFR32 (silabs)nRF ConnectTelinkRealtek构建体系GN/Ninjagn_silabs_example.shwest sysbuildwestDockerbuild_examples.py配网方式BLEQR 码/LCD 或 RTT URLBLE NFC 模拟UART 打印 QRBLEButton3 打开配网窗口BLE 标准配网流程位置反馈LCD LED1LED 亮度lift/tilt 各一蓝色 LED PWMLED/按键参考应用特色ICD 构建、Pigweed RPC、构建选项开关MCUboot DFU/OTA、多核多镜像OTA Linux Provider、Pigweed RPC单命令构建进一步可深入的仓库路径跨平台核心逻辑WindowApp.h、WindowApp.cpp、ZclCallbacks.cpp数据模型定义window-app.zap、window-app.matter各平台工程与默认配置silabs、nrfconnect、telink、realtek构建总入口与前置条件BUILDING.md、configure 脚本。注意各平台 README 中部分构建命令依赖对应厂商 SDK 与工具链Simplicity Commander、J-Link、west/ncs、Realtek SDK 子模块实际执行前请以仓库 docs/guides/BUILDING.md 及厂商文档核对你所用板型与工具版本。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考