ESP32 Arduino Matter 温度传感器示例深度解析从配对入网到智能家居集成【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32本指南以 MatterTemperatureSensor 示例 为主线深入讲解如何基于 arduino-esp32 的 Matter 库将一块 ESP32 开发板打造成符合 Matter 协议标准的温度传感器配件Accessory。文章既覆盖从接线、配置、编译烧录到 Apple Home / Amazon Alexa / Google Home 配对入网的全流程实操也结合仓库源码剖析MatterTemperatureSensor端点内部如何以 1/100℃ 精度上报温度、如何通过 BOOT 键执行出厂重置decommission帮助读者真正理解并复用这套 Matter 设备开发范式。示例概述一个开箱即用的 Matter 温度传感器该示例通过 ESP32 SoC 创建一个 Matter 兼容的温度传感器设备完整展示了 Matter 设备的三大核心能力Commissioning配对入网通过 QR 码或手动配对码Manual Pairing Code将设备接入 Matter 生态传感器数据上报将温度读数持续上报给智能家居中枢Hub自动温度模拟内置模拟温度传感器无需外接硬件即可演示完整流程。从仓库结构看示例由三个文件组成MatterTemperatureSensor.ino主程序、README.md使用文档和 ci.ymlCI 构建配置。其中ci.yml明确了两条关键构建前提分区方案必须为PartitionSchemehuge_app且必须开启CONFIG_ESP_MATTER_ENABLE_DATA_MODELy这两点与下文编译与烧录章节一一对应。支持的目标芯片与配对方式SoCWi-FiThreadBLE 配对状态ESP32支持不支持不支持完全支持ESP32-S2支持不支持不支持完全支持ESP32-S3支持不支持支持完全支持ESP32-C3支持不支持支持完全支持ESP32-C5不支持支持支持支持仅 ThreadESP32-C6支持不支持支持完全支持ESP32-H2不支持支持支持支持仅 Thread配对方式的重要差异ESP32 与 ESP32-S2 不支持 BLE 配对必须直接在 sketch 中写入 Wi-Fi 凭据让设备手动连接网络ESP32-C6 虽支持 Thread但 arduino-esp32 的 Matter 库预编译版本仅启用 Wi-Fi。若需 Thread-only 运行必须将 Arduino 作为 ESP-IDF Component 构建并禁用 Matter 的 Wi-Fi Station 功能ESP32-C5 虽支持 Wi-Fi 2.4GHz/5GHz但预编译库仅启用 Thread。若需 Wi-Fi 运行同样需要以 ESP-IDF Component 方式构建关闭 Thread 网络仅保留 Wi-Fi Station。示例代码 MatterTemperatureSensor.ino 与上述规则严格对应当CONFIG_ENABLE_CHIPOBLE未启用即不支持 BLE 配对时才引入WiFi.h并声明ssid/password常量启用 CHIPoBLE 的芯片则完全不需要 Wi-Fi 代码节省 flash 空间。功能特性一览Matter 协议温度传感器设备实现同时支持 Wi-Fi 与 Thread(*) 连接以摄氏度为单位上报温度测量值自动模拟温度读数-10℃ ~ 10℃ 范围循环每 5 秒周期性更新传感器数据按键控制出厂重置decommission通过 QR 码或手动配对码完成 Matter 配对可集成 Apple HomeKit、Amazon Alexa、Google Home。 * 需以 Arduino 作为 IDF Component 方式编译硬件要求与引脚配置ESP32 系列开发板参考上表支持的芯片用于出厂重置的用户按键默认使用 BOOT 按键可选外接真实温度传感器DS18B20、DHT22、BMP280、BME280 等替换模拟函数即可。按键引脚默认使用BOOT_PIN。该宏在 cores/esp32/esp32-hal.h 中按芯片定义ESP32 / ESP32-S2 / ESP32-S3GPIO 0ESP32-C2 / C3 / C6 / C61 / H2GPIO 9ESP32-P4GPIO 35ESP32-C5GPIO 28。示例中通过const uint8_t buttonPin BOOT_PIN;引用可按需改为任意可用 GPIO。软件环境准备安装 Arduino IDE推荐 2.0 及以上版本安装带 Matter 支持的 ESP32 Arduino Core即本仓库确保以下 Arduino 库可用Matter本仓库 libraries/MatterWi-Fi仅 ESP32 与 ESP32-S2 需要。配置详解1. Wi-Fi 凭据不使用 BLE 配对时必需ESP32 / ESP32-S2 为强制const char *ssid your-ssid; // 修改为你的 Wi-Fi SSID const char *password your-password; // 修改为你的 Wi-Fi 密码注意这段代码位于#if !CONFIG_ENABLE_CHIPOBLE条件编译块内仅在不支持 BLE 配对的目标上生效。2. 按键引脚配置可选默认使用 BOOT 按键GPIO 0执行出厂重置可按需更换const uint8_t buttonPin BOOT_PIN; // 在这里设置你的按键引脚3. 真实传感器接入可选将getSimulatedTemperature()函数替换为你的传感器读取代码函数返回以摄氏度表示的 float 温度值。以 DS18B20 为例#include OneWire.h #include DallasTemperature.h OneWire oneWire(4); // 连接 DS18B20 的 GPIO 引脚 DallasTemperature sensors(oneWire); float getSimulatedTemperature() { sensors.requestTemperatures(); return sensors.getTempCByIndex(0); }或使用 DHT22#include DHT.h DHT dht(DHT_PIN, DHT22); float getSimulatedTemperature() { return dht.readTemperature(); }编译与烧录步骤在 Arduino IDE 中打开 MatterTemperatureSensor.ino在Tools Board菜单中选择你的 ESP32 开发板在Tools Partition Scheme菜单中选择Huge APP (3MB No OTA/1MB SPIFFS)。这一要求与仓库 CI 配置 ci.yml 中的fqbn_append: PartitionSchemehuge_app完全一致——Matter 协议栈体积较大必须使用大 APP 分区方案在Tools菜单中启用Erase All Flash Before Sketch Upload选项通过 USB 将开发板连接到电脑点击Upload按钮编译并烧录。预期串口输出解读烧录完成后打开串口监视器波特率设为115200。仅 ESP32 与 ESP32-S2 会打印 Wi-Fi 连接过程其余目标芯片会通过 Matter CHIPoBLE 自动建立 IP 网络。预期输出类似Connecting to your-wifi-ssid ....... Wi-Fi connected IP address: 192.168.1.100 Matter Node is not commissioned yet. Initiate the device discovery in your Matter environment. Commission it to your Matter hub with the manual pairing code or QR code Manual pairing code: 34970112332 QR code URL: 设备打印的 QR 码在线配对地址 Matter Node not commissioned yet. Waiting for commissioning. Matter Node not commissioned yet. Waiting for commissioning. ... Matter Node is commissioned and connected to the network. Ready for use. Current Temperature is -25.00C Current Temperature is -10.00C Current Temperature is -9.50C ... Current Temperature is 10.00C Current Temperature is -10.00C其中Manual pairing code与QR code URL由 Matter.h 声明的Matter.getManualPairingCode()与Matter.getOnboardingQRCodeUrl()在Matter.begin()之后生成见 MatterTemperatureSensor.ino是配对的必需信息。配对完成后串口会输出 Matter Node is commissioned and connected to the network. Ready for use.随后开始周期性打印温度值。代码结构深度解析全局对象与端点声明MatterTemperatureSensor SimulatedTemperatureSensor;该对象是 MatterEndpoints/MatterTemperatureSensor.h 中MatterTemperatureSensor类的实例继承自端点基类 MatterEndPoint代表 Matter 节点Node上的一个温度传感器端点。setup()硬件初始化与 Matter 启动主要完成四件事初始化按键pinMode(buttonPin, INPUT_PULLUP);将 BOOT 按键配置为内部上拉输入连接 Wi-Fi仅不支持 BLE 配对的芯片调用WiFi.begin(ssid, password)并循环等待WL_CONNECTED初始化温度端点SimulatedTemperatureSensor.begin(-25.00);设定初始温度 -25℃随后模拟值才进入 -10℃~10℃ 循环启动 Matter 栈调用Matter.begin()。查看 Matter.cpp 可知该方法会先校验是否已创建至少一个端点MatterLifecycle::NodeCreated再调用esp_matter::start(app_event_cb)正式启动协议栈。最后通过Matter.isDeviceCommissioned()检查配对状态未配对时打印手动配对码与二维码 URL并每 5 秒50 * 100ms输出一次等待提示直到Matter.isDeviceCommissioned()返回 true。loop()数据上报与按键轮询温度上报利用timeCounter % 10与delay(500)实现每 5 秒打印一次当前温度SimulatedTemperatureSensor.getTemperature()并调用SimulatedTemperatureSensor.setTemperature(getSimulatedTemperature())更新读数按键处理带软件消抖逻辑——记录按下时刻button_time_stamp millis()当按键持续按下超过decommissioningTimeout 50005 秒时调用Matter.decommission()执行出厂重置随后复位时间戳防止重复触发。getSimulatedTemperature()温度模拟与真实传感器接口float getSimulatedTemperature() { static float simulatedTempHWSensor -10.0; simulatedTempHWSensor simulatedTempHWSensor 0.5; if (simulatedTempHWSensor 10) { simulatedTempHWSensor -10; } return simulatedTempHWSensor; }模拟逻辑从 -10℃ 起每步 0.5℃到达 10℃ 后重置回 -10℃实现无限循环。这也是温度变化不明显类问题的排查关键——真实场景下应替换此函数。端点实现1/100℃ 精度背后的原理MatterEndpoints/MatterTemperatureSensor.h 与 MatterEndpoints/MatterTemperatureSensor.cpp 揭示了精度的实现机制Matter 协议内部将温度存储为int16_t1/100 摄氏度因此begin(double)内部执行static_castint16_t(temperature * 100.0f)setTemperature(double)同样乘以 100 后调用setRawTemperature()getTemperature()返回(double)rawTemperature / 100.0。setRawTemperature()的核心是更新TemperatureMeasurement集群的MeasuredValue属性先通过getAttributeVal()读取当前值仅在值变化时调用updateAttributeVal()写入新值避免无意义上报见 MatterTemperatureSensor.cpp。由于int16_t范围为 -32768 ~ 32767有效温度范围为 -273.15℃绝对零度到 327.67℃超出会溢出。此外该类还提供了便捷运算符mySensor 25.5;等价于setTemperature(25.5)double temp mySensor;等价于getTemperature()详见 ep_temperature_sensor.rst 的 API Reference。智能家居集成使用 Matter 兼容中枢如 Apple HomePod、Google Nest Hub 或 Amazon Echo即可完成配对。Apple Home在 iOS 设备上打开家庭App点击按钮 添加配件扫描串口监视器中显示的 QR 码或点击我没有或无法扫描代码后输入手动配对码按提示完成设置设备将以温度传感器形式出现在家庭 App 中可查看温度读数并基于温度阈值创建自动化如温度超标时开启空调。Amazon Alexa打开 Alexa App依次点击 更多 添加设备 Matter选择扫描 QR 码或手动输入代码完成设置后温度传感器会出现在 Alexa App 中可基于温度变化创建 Routine。Google Home打开 Google Home App点击 设置设备 新设备选择Matter 设备扫描 QR 码或输入手动配对码完成设置后可查看温度读数并基于温度变化创建自动化。故障排查配对时设备不可见确认 Wi-Fi 或 Thread 网络配置正确温度读数不更新检查模拟函数是否被正确调用使用真实传感器时核对接线与库初始化温度值超出范围Matter 协议内部以int16_t存储 1/100℃ 值合法范围为 -273.15℃~327.67℃请确保输入为摄氏度且未越界状态不变化模拟传感器每 5 秒增加 0.5℃使用真实传感器时请确认其连接与读数正常配对失败长按按键执行出厂重置或在 Arduino IDE 中通过Tools Erase All Flash Before Sketch Upload: Enabled擦除整个 flash也可用esptool.py --port PORT erase_flash直接擦除无串口输出检查波特率115200与 USB 连接。相关文档仓库内Matter 概述Matter 协议栈整体介绍与架构说明Matter 端点基类MatterEndPoint基类 API 与端点通用能力Matter 温度传感器端点 APIMatterTemperatureSensor类的完整 API 参考Matter 库源码端点实现、Matter 管理器与事件系统更多 Matter 示例libraries/Matter/examples。【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考