Matter 联发科 Genio MT793X 平台门锁应用实战：编译、烧录与配网控制完整指南

Matter 联发科 Genio MT793X 平台门锁应用实战：编译、烧录与配网控制完整指南

【免费下载链接】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

本篇技术指南以connectedhomeip（Matter / Project CHIP）仓库中的Genio（MediaTek MT793X）门锁（Lock）示例为核心，完整讲解如何准备构建环境、编译门锁应用、通过 Flash Tool 烧录到EK-AI7931LD KIT开发板，以及使用 CHIP Tool 完成 BLE 配网（Commissioning）并远程控制门锁的完整流程。读者读完本文后，将掌握基于 MT793X 芯片的 Matter 门锁产品的开发、构建与调试方法，并能结合仓库源码理解门锁状态机、用户/凭证管理与 ZCL 回调的实现原理。

示例概览：MT793X 上的 Matter 门锁控制设备

Genio（MT793X）门锁示例位于 examples/lock-app/genio，它是 Matter 官方仓库中基于 MediaTekGenioSDK 构建的门锁控制设备（Door Lock control device）基线演示。该设备具备以下核心特征：

• 控制方式：可通过 CHIP（Matter）控制器通过 Wi-Fi 网络进行远程控制；
• 配网方式：设备支持通过蓝牙低功耗（BLE）完成配网。配网过程中设备与控制器通过 Rendez-vous 流程交换安全信息，随后控制器将 Wi-Fi 网络凭证下发给设备，设备接入网络；
• 产品模板价值：该示例既是探索 Matter 工作原理的入口，也是基于 MediaTek 平台创建真实产品的模板（原文档将其与同平台的 lighting 示例并列说明，二者共享同一套平台工程）。

从 examples/lock-app/genio/BUILD.gn 可以看到，该示例依赖examples/lock-app/lock-common（门锁通用逻辑）、examples/common/QRCode（配网二维码生成）、examples/platform/mt793x（平台 Shell 与 LED 等）以及src/setup_payload等模块，最终产物名为chip-mt793x-lock-app-example.out。

构建环境与硬件支持

准备构建环境

构建前需按照仓库的 Linux 构建指南准备环境，即 docs/guides/BUILDING.md 中与 Linux 相关的部分（安装依赖、激活 Python 虚拟环境、初始化子模块等）。

需要特别注意的是，Genio 平台依赖third_party/mt793x_sdk（MediaTek MT793X SDK 子模块）与third_party/connectedhomeip（示例内嵌子模块）。直接使用 GN/Ninja 构建前，务必在示例目录内执行git submodule update --init，否则 Flash Tool、链接脚本（mt793x_xip.ld）与scatter.ini生成脚本等 SDK 资源不可用。

支持的硬件

Genio130A（MT7931）开发板：

• EK-AI7931LD KIT

该开发板集成了 Wi-Fi、BLE 与安全子系统的 MT793X 双核 SoC，是评估 Matter-over-Wi-Fi 门锁方案的官方开发套件。

编译 Matter 门锁应用

原文档提供了两种编译路径，本文一并保留并补充细节。

方式一：使用示例构建脚本

cd ~/connectedhomeip ./scripts/examples/gn_genio_example.sh ./examples/lock-app/genio ./out/lock-app

说明：原文档示例命令针对的是lighting-app目录，若需构建门锁示例，应将路径参数替换为./examples/lock-app/genio。仓库的自动化构建体系（scripts/build/builders/genio.py）目前登记的GenioApp枚举为LIGHT（lighting-app）与SHELL（shell）两类，门锁示例与二者共用同一套mt793x_executableGN 模板与 MT793X SDK，构建流程完全一致。

清理构建产物：

cd ~/connectedhomeip rm -rf ./out/

方式二：直接使用 GN/Ninja

cd ~/connectedhomeip/examples/lock-app/genio git submodule update --init source third_party/connectedhomeip/scripts/activate.sh gn gen out/debug ninja -C out/debug

清理：

cd ~/connectedhomeip/examples/lock-app/genio rm -rf out/

构建产物解析

mt793x_executable模板（见 third_party/mt793x_sdk/mt793x_executable.gni）在编译之外还会自动产出：

• 可执行文件与二进制镜像：chip-mt793x-lock-app-example.out及通过arm-none-eabi-objcopy转换得到的.bin镜像；
• scatter.ini分区描述文件：由scatter_file_generator.py根据mt7931an_bootloader-xip.sgn（Bootloader）、BT_RAM_CODE_MT7933_2_1_hdr.bin（蓝牙固件）、WIFI_RAM_CODE_MT7933_ALL.bin（Wi-Fi 固件）与应用镜像自动生成，输出到root_out_dir/scatter.ini，供 Flash Tool 烧录使用；
• Bootloader 与协处理器固件拷贝：copy_fileaction 会把上述 Bootloader、BLE/Wi-Fi 固件一并拷贝到输出目录，保证烧录目录自包含。

另外，examples/lock-app/genio/BUILD.gn 默认开启chip_print_memory_usage = true，链接时追加-Wl,--print-memory-usage与-fstack-usage，可在编译日志中直接看到各段内存占用与栈使用情况；若开启chip_enable_ota_requestor还会定义MT793X_OTA_ENABLED并加入OTAConfig.cpp支持 OTA。

构建参数与平台配置解析

BUILD.gn 中的配网参数

examples/lock-app/genio/BUILD.gn 中通过declare_args定义了门锁示例的测试配网参数，并通过宏注入到 SDK 目标：

declare_args() { # Dump memory usage at link time. chip_print_memory_usage = true # PIN code for PASE session establishment. setupPinCode = 20202021 setupDiscriminator = 3940 }

这两个参数分别对应CHIP_DEVICE_CONFIG_USE_TEST_SETUP_PIN_CODE=20202021与CHIP_DEVICE_CONFIG_USE_TEST_SETUP_DISCRIMINATOR=3940，是 BLE 配网阶段 PASE（Passcode-Authenticated Session Establishment）会话建立使用的配对 PIN 码与发现标识符。后面运行 CHIP Tool 配网命令时，命令行中的20202021与3840即与此对应（Discriminator 默认使用 3840，可在setupDiscriminator中调整）。

args.gni：BLE 与锁跟踪配置

examples/lock-app/genio/args.gni 定义了平台级 GN 参数：

chip_enable_ble = true declare_args() { chip_enable_ota_requestor = false # Disable lock tracking, since our FreeRTOS configuration does not set # INCLUDE_xSemaphoreGetMutexHolder chip_stack_lock_tracking = "none" chip_config_network_layer_ble = true }

• chip_enable_ble = true：启用 BLE 作为配网（Rendez-vous）通道，这是"BLE 配网 + Wi-Fi 入网"流程的前提；
• chip_config_network_layer_ble = true：允许 BLE 承载网络层数据；
• chip_stack_lock_tracking = "none"：因该平台 FreeRTOS 配置未开启INCLUDE_xSemaphoreGetMutexHolder，关闭 CHIP 栈锁跟踪避免编译/运行问题；
• chip_enable_ota_requestor = false：默认不启用 OTA 请求方。

Wi-Fi 构建参数

示例目录提供面向 Wi-Fi 场景的构建参数文件 build_for_wifi_args.gni 与 build_for_wifi_gnfile.gn。其中：

• chip_enable_thread = false：关闭 Thread 支持，仅保留 Wi-Fi 单协议栈；
• 导入src/platform/MT793X/wifi_args.gni获取 Wi-Fi 驱动相关参数；
• build_for_wifi_gnfile.gn指定target_cpu = "arm"、target_os = "freertos"、use_thread = false，可作为gn gen时的自定义构建文件入口（--file或-C指定）。

门锁资源参数（AppConfig.h）

门锁的用户/凭证容量在 examples/lock-app/genio/include/AppConfig.h 中定义：

// Maximum number of users supported by lock #define CONFIG_LOCK_NUM_USERS (5) // Maximum number of credentials per user supported by lock #define CONFIG_LOCK_NUM_CREDENTIALS_PER_USER (2)

即该示例默认支持5 个用户、每用户 2 条凭证。与之配套，examples/lock-app/genio/include/LockManager.h 中的ResourceRanges常量声明了每用户每周日/周年/假日日程上限各 10 条、单条凭证最大长度 8 字节，并明确"用户/凭证/日程索引均以 1 起始（1-indexed）"。ACTUATOR_MOVEMENT_PERIOS_MS (10)表示模拟电机动作持续 10ms，门锁状态机通过该时长模拟真实锁舌动作。

烧录应用（Flash Tool）

编译完成后需要把镜像烧录到EK-AI7931LD KIT。原文档给出了基于 Windows 图形化 Flash Tool 的烧录流程：

1. 拷贝 Flash Tool：将编译主机（Linux）上的 Flash Tool（FlashBurningTool_V2.83）拷贝到一台 Windows PC。原文档说明 Flash Tool 位于源码树third_party/mt793x_sdk/filogic/flash_tool目录下（该路径随mt793x_sdk子模块拉取，请确保子模块已初始化）；
2. 运行 Flash Tool：在 Windows PC 上启动 Flash Tool；
3. 选择 scatter 文件：在./out/lock-app（对应方式一输出目录）中选择编译生成的scatter.ini文件。该文件由构建系统根据 Bootloader、BLE/Wi-Fi 固件与应用镜像的分区布局自动生成（见 third_party/mt793x_sdk/mt793x_executable.gni）；
4. 切换下载模式：按照EK-AI7931LD KIT随附说明，将开发板切换到 Download（下载）模式；
5. 开始烧录：在 Flash Tool 中点击Download，等待烧录完成。

运行完整示例：配网与控制

使用 CHIP Tool 配网

烧录完成后，可以使用多种控制器对设备进行配网（Provision）与控制，包括 Python 控制器、CHIP Tool 独立工具、Android 或 iOS 应用。CHIP Tool 的完整使用说明见 docs/development_controllers/chip-tool/chip_tool_guide.md。

以 CHIP Tool 为例，配网命令如下：

chiptool pairing ble-wifi 1234 my-ap myapppassword 20202021 3840

参数说明：

参数	含义
1234	要分配给设备的 Node ID（在此示例中为 1234）
my-ap	Wi-Fi SSID（接入点名称）
myapppassword	Wi-Fi 密码
20202021	配对 PIN 码（PASE Setup PIN），对应setupPinCode
3840	Discriminator（发现标识符），用于 BLE 扫描阶段识别设备

配网成功后，设备会通过 BLE 与控制器完成安全握手、获取 Wi-Fi 凭证并加入网络，随后即可通过 Matter 网络层远程控制门锁。

门锁控制命令

原文档沿用了同仓库 lighting 示例的测试命令（onoff开关），此处保留以便对照：

chiptool onoff on 1 1 chiptool onoff off 1 1

而针对门锁示例，实际控制操作对应 Matter 的Door Lock 集群（Cluster Id 对应DoorLock::Id）。门锁的 Lock/Unlock 命令通过 examples/lock-app/genio/src/ZclCallbacks.cpp 中的emberAfPluginDoorLockOnDoorLockCommand/emberAfPluginDoorLockOnDoorUnlockCommand回调进入门锁应用逻辑，再转发给LockMgr()执行。可以使用 CHIP Tool 的 door-lock 集群命令（如chiptool lock lock <endpoint> <nodeid>、chiptool lock unlock <endpoint> <nodeid>）远程上锁/开锁。

板载 Shell 命令

若编译时启用了ENABLE_CHIP_SHELL，设备启动时会创建 Matter Shell 任务（见 examples/platform/mt793x/matter_shell.cpp：注册cmd_misc_init()、cmd_otcli_init()等基础命令），可通过串口交互式调试。原文档给出的light命令（含onoff、color、level子命令）是 lighting 示例的 Shell 界面；门锁示例的 Shell 通过main.cpp中chip::startShellTask()启动，可通过help查看当前固件实际注册的命令列表：

> help

源码实现纵深：门锁应用如何工作

启动流程与任务模型（main.cpp）

examples/lock-app/genio/src/main.cpp 展示了典型的 FreeRTOS + Matter 启动序列：

1. 设置mbedtls_platform_set_calloc_free，将 mbedTLS 内存分配切换到 CHIP 平台内存；
2. system_init()完成 MT793X SDK 底层初始化；
3. mt793xSwdPortConfig()配置 SWD 调试端口；
4. vTaskStartScheduler()启动 FreeRTOS 调度器；
5. 守护任务启动钩子中创建startTask（栈 1000 words），其内部依次完成：注册日志重定向（mt793xLogRedirectCallback）、注册 wpa_supplicant 日志回调、chip::Platform::MemoryInit()、PlatformMgr().InitChipStack()、启动 CHIP 事件循环任务、启动 AppTask、初始化 Filogic 按键回调。

设备的 Wi-Fi 名称在#define WIFI_DEV_NAME "MediaTek-Lock"中定义。若发生致命错误，appError()会打印错误码并portDISABLE_INTERRUPTS()挂死，便于调试。

门锁状态机（LockManager.cpp）

examples/lock-app/genio/src/LockManager.cpp 实现了核心门锁状态机，状态定义于 LockManager.h：

kState_LockInitiated -> kState_LockCompleted kState_UnlockInitiated -> kState_UnlockCompleted

• InitiateAction()仅在"上一个动作已完成"时才接受新动作：kState_LockCompleted时接受UNLOCK_ACTION，kState_UnlockCompleted时接受LOCK_ACTION；
• 动作启动后调用StartTimer(ACTUATOR_MOVEMENT_PERIOS_MS)（10ms 的 FreeRTOS 一次性软件定时器），定时器到期后ActuatorMovementTimerEventHandler将状态置为 Completed 并触发完成回调；
• Lock()/Unlock()最终调用setLockState()：先读取 Door Lock 集群的RequirePINforRemoteOperation属性判断远程操作是否需要 PIN；若配置了 PIN 校验，则遍历用户/凭证数据库匹配 PIN 码，未命中时返回OperationErrorEnum::kInvalidCredential。

用户、凭证与日程管理

LockManager完整实现了 Matter Door Lock 集群的用户（User）、凭证（Credential）、周/年/假日日程（Schedule）管理接口，包括GetUser/SetUser、GetCredential/SetCredential、三类Get/SetSchedule，并具备完整的索引与容量校验（IsValidUserIndex、IsValidCredentialIndex等）。所有数据均通过MT793XConfig::WriteConfigValueBin/ReadConfigValueBin持久化到 MT793X 平台的 NVM Flash（对应kConfigKey_LockUser、kConfigKey_Credential、kConfigKey_UserCredentials、kConfigKey_WeekDaySchedules、kConfigKey_YearDaySchedules、kConfigKey_HolidaySchedules等键），掉电不丢失。AppTask::AppTaskMain在启动后首次循环中调用LockMgr().ReadConfigValues()一次性从 Flash 恢复全部数据。

ZCL 回调与集群初始化（ZclCallbacks.cpp）

examples/lock-app/genio/src/ZclCallbacks.cpp 是数据模型与应用逻辑之间的桥梁：

• emberAfDoorLockClusterInitCallback：在 Door Lock 集群初始化时设置LockType = kDeadBolt（死锁/插芯锁）、NumberOfTotalUsersSupported = CONFIG_LOCK_NUM_USERS、NumberOfPINUsersSupported = CONFIG_LOCK_NUM_USERS、NumberOfRFIDUsersSupported = 0、NumberOfCredentialsSupportedPerUser = CONFIG_LOCK_NUM_CREDENTIALS_PER_USER，并将FeatureMap设为0x101（kUser | kPinCredential，即"用户 + PIN 凭证"能力位，注意当前逻辑不支持 PIN 与 RFID 同时启用）；
• emberAfPluginDoorLockOnDoorLockCommand/OnDoorUnlockCommand：收到 Lock/Unlock 命令后调用LockMgr().Lock()/Unlock()校验并执行，成功后通过InitiateAction驱动状态机；
• GetUser/SetUser/GetCredential/SetCredential/Get/SetSchedule系列回调：统一转发到LockMgr()的对应实现，使数据模型读写与 NVM 持久化解耦。

AppTask 交互与 LED 指示（AppTask.cpp）

examples/lock-app/genio/src/AppTask.cpp 中：

• AppTask::Init()完成 Wi-Fi 初始化等待、NetworkCommissioning实例注册（基于GenioWiFiDriver）、示例 DAC（Device Attestation Credentials）注入、CHIP Server 启动、门锁初始状态读取与LockMgr().Init()，最后打印 Onboarding Codes（默认使用kSoftAPRendezvous 标志）；
• 状态 LED 与锁 LED 由LEDWidget驱动：Wi-Fi 已配置但未连接时sStatusLED.Blink(950, 50)，未配置则Blink(50, 950)；
• 按键长按 3 秒触发恢复出厂设置流程（FACTORY_RESET_TRIGGER_TIMEOUT = 3000，期间松开可取消），短按则切换门锁状态并将结果同步回 Door Lock 集群属性（UpdateClusterState→DoorLockServer::Instance().SetLockState）。

注意事项

• IPv6 环境：Matter 运行在 IPv6 之上。如果路由器没有为设备（Border Router / PC）提供原生 IPv6 地址，需要在设备与 PC 上手动配置静态 IPv6 地址，并在 PC 上添加指向 Border Router 的 IPv6 路由，否则配网成功后设备可能无法与控制器正常通信；
• 子模块完整性：third_party/mt793x_sdk与示例内嵌的third_party/connectedhomeip为 Git 子模块，构建与烧录（尤其 Flash Tool 与scatter.ini生成）强依赖其内容，务必先执行git submodule update --init；
• 构建目录一致性：Flash Tool 需要选择与编译输出一致目录下的scatter.ini，请确保"方式一"的./out/lock-app或"方式二"的out/debug与烧录时选择的目录对应。

通过本文的编译、烧录、配网与源码解析，你可以在EK-AI7931LD KIT（MT7931）上完整跑通一个 Matter 门锁设备，并以此为基础按需调整用户/凭证容量、PIN 校验策略与日程能力，向真实产品化演进。

【免费下载链接】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